Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2e65c055b8 | ||
|
|
3da7b276d3 | ||
|
|
63e5be80ab | ||
|
|
92d88fe761 | ||
|
|
c4ffb9473f | ||
|
|
3a7e11c995 | ||
|
|
b0c777c480 | ||
|
|
b00b018056 | ||
|
|
b974f10c6e | ||
|
|
72777a8c74 | ||
|
|
e08cd839be | ||
|
|
5309848292 | ||
|
|
1271aafcdd | ||
|
|
54a507d906 | ||
|
|
ea17ae1074 | ||
|
|
fe9046cecf | ||
|
|
b5e9d15391 | ||
|
|
dcd0cdb8f7 | ||
|
|
a53ebb65ee | ||
|
|
a5d30c00b3 | ||
|
|
fd36b92224 | ||
|
|
30cd39fd8f | ||
|
|
31a4b69bbd |
No files matched your search
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: marqdo
|
||||
description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/*, running marqdo CLI, or when the user mentions Marqdo,
|
||||
mq.md, markup-as-syntax, or code-as-documentation.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
|
||||
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `> path.mq.md` | Import |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
*`y` = `x` + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
> print text=`xs`
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names (do not mix).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `**Hello**` to print | `> print text=Hello` |
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call `拆分` | Match file language |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
- [ ] File ends with `.mq.md`
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
@@ -0,0 +1,162 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = 2*
|
||||
*`b` = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## 6. Foreach loop
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
- [`果`](`篮子`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`parts` = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*`not_executed` = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
|
||||
> print text=this runs
|
||||
```
|
||||
|
||||
## 9. Frontmatter import only
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*`ws` = > agent *
|
||||
*`n` = > `ws`.ensure_layout *
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
+ `x` > 0
|
||||
|
||||
# GOOD — ordered list arms
|
||||
1. `x` > 0
|
||||
```
|
||||
@@ -0,0 +1,135 @@
|
||||
# Marqdo reference (AI)
|
||||
|
||||
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
|
||||
|
||||
## CLI
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run FILE.mq.md
|
||||
marqdo run FILE.mq.md --backend bytecode
|
||||
marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent
|
||||
marqdo ext remove llm|agent
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `> ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
| EN | ZH | Role |
|
||||
|----|----|------|
|
||||
| `print` | `打印` | stdout; arg `text` / `内容` |
|
||||
| `input` | `输入` | one line; arg `prompt` / `提示` |
|
||||
| `len` | `长度` | length; arg `value` / `值` |
|
||||
| `str` | `文本` | to text; arg `value` / `值` |
|
||||
| `int` | `整数` | to int; arg `value` / `值` |
|
||||
|
||||
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
## Standard library files
|
||||
|
||||
Import one file; use **that** file’s function names.
|
||||
|
||||
| EN import | ZH import | Typical APIs (EN / ZH) |
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | table/rows helpers |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
|
||||
## Foreign (Python example)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
```
|
||||
|
||||
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
|
||||
|
||||
## Function-end details
|
||||
|
||||
| Form | Effect |
|
||||
|------|--------|
|
||||
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
|
||||
| `****` or empty bold | Return `None` and end body |
|
||||
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
|
||||
|
||||
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
|
||||
|
||||
## Call arguments
|
||||
|
||||
- Named: `> greet who=World`
|
||||
- Positional: `> greet World`
|
||||
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
|
||||
- Inline call in statement: `` *`n` = > len value=`s`* ``
|
||||
|
||||
See `doc/design/call-arguments.md`.
|
||||
|
||||
## Identifiers
|
||||
|
||||
- Variables: `` `name` ``
|
||||
- Comparisons: `==` `>` `<` `>=` `<=`
|
||||
- Do not use keyword tokens as names
|
||||
|
||||
## Design docs (repo)
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
|
||||
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
|
||||
| `doc/design/ext-abi.md` | Native C ABI v1 |
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -28,7 +28,7 @@ jobs:
|
||||
- name: Build & export site
|
||||
run: |
|
||||
cargo build --release
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' -print0 \
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
|
||||
| xargs -0 -n1 ./target/release/marqdo run
|
||||
./target/release/marqdo view output public -o public
|
||||
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
# Build and attach release binaries when a version tag is pushed.
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
|
||||
- name: Build VSIX
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
Push-Location vscode-extension
|
||||
npm ci
|
||||
npm run compile
|
||||
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
|
||||
Pop-Location
|
||||
|
||||
- name: Package
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
$target = "x86_64-pc-windows-msvc"
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
$exe = "marqdo-$ver-$target.exe"
|
||||
$zip = "marqdo-$ver-$target.zip"
|
||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
||||
Copy-Item lib "$stageLib/lib" -Recurse
|
||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights
|
||||
- **Embedded stdlib** (v0.1.2+): `lib/*.mq.md` built into the binary
|
||||
- **writeback** + **subtask** stdlibs
|
||||
- **`marqdo version --check`**
|
||||
- VSIX built from branch **`vscode-extension`** (not tracked on `main`)
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
|
||||
Extension workflow: [doc/design/vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
|
||||
files: |
|
||||
dist/${{ env.EXE }}
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.VSIX }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
+21
@@ -1,15 +1,36 @@
|
||||
/target/
|
||||
/dist/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
/tests/lib/libdemo.so
|
||||
/tests/lib/libdemo.dylib
|
||||
/tests/ext/agent.dll
|
||||
/tests/ext/libagent.so
|
||||
/tests/ext/libagent.dylib
|
||||
/tests/ext/skel.mq.md
|
||||
/tests/ext/out-demo.mq.md
|
||||
/tests/ext/ticket.txt
|
||||
/tests/ext/ticket-stub.txt
|
||||
/tests/ext/agents/
|
||||
/tests/ext/runbooks/
|
||||
/tests/ext/templates/
|
||||
/tests/ext/reports/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
/public/pages/
|
||||
|
||||
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
|
||||
/vscode-extension/
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
spike/__pycache__/
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# Changelog
|
||||
|
||||
## v0.1.2 — 2026-08-07
|
||||
|
||||
### Added
|
||||
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
|
||||
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
|
||||
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
|
||||
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
|
||||
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
|
||||
|
||||
### Changed
|
||||
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
|
||||
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
|
||||
|
||||
## v0.1.1
|
||||
|
||||
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
|
||||
|
||||
## v0.1.0
|
||||
|
||||
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
|
||||
Generated
+721
-5
@@ -2,6 +2,12 @@
|
||||
# It is not intended for manual editing.
|
||||
version = 3
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
|
||||
|
||||
[[package]]
|
||||
name = "aho-corasick"
|
||||
version = "1.1.5"
|
||||
@@ -11,6 +17,15 @@ dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "android_system_properties"
|
||||
version = "0.1.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
|
||||
dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anstream"
|
||||
version = "0.6.21"
|
||||
@@ -47,7 +62,7 @@ version = "1.1.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
|
||||
dependencies = [
|
||||
"windows-sys",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -58,7 +73,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"once_cell_polyfill",
|
||||
"windows-sys",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -94,6 +109,18 @@ version = "1.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
|
||||
|
||||
[[package]]
|
||||
name = "base64"
|
||||
version = "0.22.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "2.13.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
|
||||
|
||||
[[package]]
|
||||
name = "bstr"
|
||||
version = "1.13.0"
|
||||
@@ -105,6 +132,39 @@ dependencies = [
|
||||
"serde_core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "bumpalo"
|
||||
version = "3.20.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
|
||||
|
||||
[[package]]
|
||||
name = "cc"
|
||||
version = "1.4.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
|
||||
dependencies = [
|
||||
"find-msvc-tools",
|
||||
"shlex",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
||||
|
||||
[[package]]
|
||||
name = "chrono"
|
||||
version = "0.4.45"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
|
||||
dependencies = [
|
||||
"iana-time-zone",
|
||||
"num-traits",
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chunked_transfer"
|
||||
version = "1.5.0"
|
||||
@@ -157,6 +217,21 @@ version = "1.0.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
|
||||
|
||||
[[package]]
|
||||
name = "core-foundation-sys"
|
||||
version = "0.8.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
|
||||
|
||||
[[package]]
|
||||
name = "crc32fast"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "difflib"
|
||||
version = "0.4.0"
|
||||
@@ -169,6 +244,22 @@ version = "0.3.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
|
||||
|
||||
[[package]]
|
||||
name = "find-msvc-tools"
|
||||
version = "0.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
|
||||
|
||||
[[package]]
|
||||
name = "flate2"
|
||||
version = "1.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
|
||||
dependencies = [
|
||||
"crc32fast",
|
||||
"miniz_oxide",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "float-cmp"
|
||||
version = "0.9.0"
|
||||
@@ -178,6 +269,59 @@ dependencies = [
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "form_urlencoded"
|
||||
version = "1.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
|
||||
dependencies = [
|
||||
"percent-encoding",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "futures-core"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
|
||||
|
||||
[[package]]
|
||||
name = "futures-task"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
|
||||
|
||||
[[package]]
|
||||
name = "futures-util"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
|
||||
dependencies = [
|
||||
"futures-core",
|
||||
"futures-task",
|
||||
"pin-project-lite",
|
||||
"slab",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "getopts"
|
||||
version = "0.2.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
|
||||
dependencies = [
|
||||
"unicode-width",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "getrandom"
|
||||
version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"libc",
|
||||
"wasi",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
@@ -190,18 +334,119 @@ version = "1.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
|
||||
|
||||
[[package]]
|
||||
name = "iana-time-zone"
|
||||
version = "0.1.65"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
|
||||
dependencies = [
|
||||
"android_system_properties",
|
||||
"core-foundation-sys",
|
||||
"iana-time-zone-haiku",
|
||||
"js-sys",
|
||||
"log",
|
||||
"wasm-bindgen",
|
||||
"windows-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "iana-time-zone-haiku"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
|
||||
dependencies = [
|
||||
"cc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"smallvec",
|
||||
"utf8_iter",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna_adapter"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "279259b0ac81c89d11c290495fdcfa96ea3643b7df311c138b6fe8ca5237f0f8"
|
||||
dependencies = [
|
||||
"idna_mapping",
|
||||
"unicode-bidi",
|
||||
"unicode-normalization",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna_mapping"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "11c13906586a4b339310541a274dd927aff6fcbb5b8e3af90634c4b31681c792"
|
||||
dependencies = [
|
||||
"unicode-joining-type",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "include_dir"
|
||||
version = "0.7.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
|
||||
dependencies = [
|
||||
"include_dir_macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "include_dir_macros"
|
||||
version = "0.7.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "js-sys"
|
||||
version = "0.3.103"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"futures-util",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "libc"
|
||||
version = "0.2.189"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
|
||||
|
||||
[[package]]
|
||||
name = "libloading"
|
||||
version = "0.8.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "fc2f4eb4bc735547cfed7c0a4922cbd04a4655978c09b54f1f7b228750664c34"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"windows-targets",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "log"
|
||||
version = "0.4.33"
|
||||
@@ -210,14 +455,36 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.0.3"
|
||||
version = "0.1.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"clap",
|
||||
"idna_adapter",
|
||||
"include_dir",
|
||||
"libloading",
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"serde_json",
|
||||
"thiserror",
|
||||
"tiny_http",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -226,6 +493,16 @@ version = "2.8.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
|
||||
|
||||
[[package]]
|
||||
name = "miniz_oxide"
|
||||
version = "0.8.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
|
||||
dependencies = [
|
||||
"adler2",
|
||||
"simd-adler32",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "normalize-line-endings"
|
||||
version = "0.3.0"
|
||||
@@ -241,12 +518,30 @@ dependencies = [
|
||||
"autocfg",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "once_cell"
|
||||
version = "1.21.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
|
||||
|
||||
[[package]]
|
||||
name = "once_cell_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "percent-encoding"
|
||||
version = "2.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
|
||||
|
||||
[[package]]
|
||||
name = "predicates"
|
||||
version = "3.1.0"
|
||||
@@ -286,6 +581,25 @@ dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pulldown-cmark"
|
||||
version = "0.12.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f86ba2052aebccc42cbbb3ed234b8b13ce76f75c3551a303cb2bcffcff12bb14"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"getopts",
|
||||
"memchr",
|
||||
"pulldown-cmark-escape",
|
||||
"unicase",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pulldown-cmark-escape"
|
||||
version = "0.11.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
|
||||
|
||||
[[package]]
|
||||
name = "quote"
|
||||
version = "1.0.47"
|
||||
@@ -309,9 +623,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "regex-automata"
|
||||
version = "0.4.16"
|
||||
version = "0.4.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
|
||||
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
|
||||
dependencies = [
|
||||
"aho-corasick",
|
||||
"memchr",
|
||||
@@ -324,6 +638,69 @@ version = "0.8.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
||||
|
||||
[[package]]
|
||||
name = "ring"
|
||||
version = "0.17.14"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
|
||||
dependencies = [
|
||||
"cc",
|
||||
"cfg-if",
|
||||
"getrandom",
|
||||
"libc",
|
||||
"untrusted",
|
||||
"windows-sys 0.52.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls"
|
||||
version = "0.22.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bf4ef73721ac7bcd79b2b315da7779d8fc09718c6b3d2d1b2d94850eb8c18432"
|
||||
dependencies = [
|
||||
"log",
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls-pki-types"
|
||||
version = "1.15.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
|
||||
dependencies = [
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls-webpki"
|
||||
version = "0.102.8"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "64ca1bc8749bd4cf37b5ce386cc146580777b4e8572c7b97baf22c83f444bee9"
|
||||
dependencies = [
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"untrusted",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustversion"
|
||||
version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
|
||||
|
||||
[[package]]
|
||||
name = "serde"
|
||||
version = "1.0.229"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
|
||||
dependencies = [
|
||||
"serde_core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_core"
|
||||
version = "1.0.229"
|
||||
@@ -344,12 +721,55 @@ dependencies = [
|
||||
"syn 3.0.3",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_json"
|
||||
version = "1.0.151"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"memchr",
|
||||
"serde",
|
||||
"serde_core",
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "shlex"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
|
||||
|
||||
[[package]]
|
||||
name = "simd-adler32"
|
||||
version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
|
||||
|
||||
[[package]]
|
||||
name = "slab"
|
||||
version = "0.4.12"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
|
||||
|
||||
[[package]]
|
||||
name = "smallvec"
|
||||
version = "1.15.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
|
||||
|
||||
[[package]]
|
||||
name = "strsim"
|
||||
version = "0.10.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
|
||||
|
||||
[[package]]
|
||||
name = "subtle"
|
||||
version = "2.6.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
|
||||
|
||||
[[package]]
|
||||
name = "syn"
|
||||
version = "2.0.119"
|
||||
@@ -410,12 +830,101 @@ dependencies = [
|
||||
"log",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tinyvec"
|
||||
version = "1.12.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
|
||||
dependencies = [
|
||||
"tinyvec_macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tinyvec_macros"
|
||||
version = "0.1.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
|
||||
|
||||
[[package]]
|
||||
name = "unicase"
|
||||
version = "2.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-bidi"
|
||||
version = "0.3.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-ident"
|
||||
version = "1.0.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-joining-type"
|
||||
version = "1.0.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d8d00a78170970967fdb83f9d49b92f959ab2bb829186b113e4f4604ad98e180"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-normalization"
|
||||
version = "0.1.25"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
|
||||
dependencies = [
|
||||
"tinyvec",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicode-width"
|
||||
version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
|
||||
|
||||
[[package]]
|
||||
name = "untrusted"
|
||||
version = "0.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
|
||||
|
||||
[[package]]
|
||||
name = "ureq"
|
||||
version = "2.9.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d11a831e3c0b56e438a28308e7c810799e3c118417f342d30ecec080105395cd"
|
||||
dependencies = [
|
||||
"base64",
|
||||
"flate2",
|
||||
"log",
|
||||
"once_cell",
|
||||
"rustls",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"url",
|
||||
"webpki-roots 0.26.11",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "url"
|
||||
version = "2.5.8"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
|
||||
dependencies = [
|
||||
"form_urlencoded",
|
||||
"idna",
|
||||
"percent-encoding",
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "utf8_iter"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
|
||||
|
||||
[[package]]
|
||||
name = "utf8parse"
|
||||
version = "0.2.2"
|
||||
@@ -431,12 +940,143 @@ dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasi"
|
||||
version = "0.11.1+wasi-snapshot-preview1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.126"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
"rustversion",
|
||||
"wasm-bindgen-macro",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.126"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.126"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.126"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "webpki-roots"
|
||||
version = "0.26.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
|
||||
dependencies = [
|
||||
"webpki-roots 1.0.9",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "webpki-roots"
|
||||
version = "1.0.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
|
||||
dependencies = [
|
||||
"rustls-pki-types",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-core"
|
||||
version = "0.62.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
|
||||
dependencies = [
|
||||
"windows-implement",
|
||||
"windows-interface",
|
||||
"windows-link",
|
||||
"windows-result",
|
||||
"windows-strings",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-implement"
|
||||
version = "0.60.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-interface"
|
||||
version = "0.59.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-link"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
|
||||
|
||||
[[package]]
|
||||
name = "windows-result"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-strings"
|
||||
version = "0.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.52.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
|
||||
dependencies = [
|
||||
"windows-targets",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.61.2"
|
||||
@@ -445,3 +1085,79 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-targets"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
|
||||
dependencies = [
|
||||
"windows_aarch64_gnullvm",
|
||||
"windows_aarch64_msvc",
|
||||
"windows_i686_gnu",
|
||||
"windows_i686_gnullvm",
|
||||
"windows_i686_msvc",
|
||||
"windows_x86_64_gnu",
|
||||
"windows_x86_64_gnullvm",
|
||||
"windows_x86_64_msvc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows_aarch64_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
|
||||
|
||||
[[package]]
|
||||
name = "windows_aarch64_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_gnu"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_gnu"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "zeroize"
|
||||
version = "1.8.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde"
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
|
||||
+14
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.0.3"
|
||||
version = "0.1.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -13,9 +13,22 @@ path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
include_dir = "0.7"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
|
||||
@@ -1,69 +1,130 @@
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即代码。**
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
|
||||
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 测试布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.1)
|
||||
## 为什么重要
|
||||
|
||||
| 痛点 | Marqdo 的答案 |
|
||||
|------|----------------|
|
||||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
||||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
||||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
||||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
||||
|
||||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.2)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 注释 |
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` / `##` | 函数与作用域 |
|
||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||||
| `-` | 循环(头下纯名则为形参) |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| `---` / `***` | 可选:框住分支/循环(不强制) |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
- n
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
|
||||
1. 叙述默认安全(无标记 = 注释)。
|
||||
2. 返回是架构;打印只是函数。
|
||||
3. 依赖清单由工具生成(OKF 风格),不是手填配置。
|
||||
4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
|
||||
---
|
||||
|
||||
## 现状
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
|
||||
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
|
||||
- **Phase I(树遍历)已通**:`tests/structure/` 与 `tests/keywords/` 金样例均可 `marqdo run`
|
||||
- **view**:`marqdo view public` 浏览用户文档;金样例用 `marqdo view tests`
|
||||
- **用户静态站**:可执行文稿在 `public/`(无 errors);`view output` 生成 HTML(ignore),CI 发布到 `gh-pages` — 见 [user-site.md](doc/design/user-site.md)
|
||||
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
marqdo catalog public -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.2)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- **官方扩展 `ext/`**(非 stdlib):[`ext/llm`](doc/design/ext-llm.md);[`ext/agent`](doc/design/ext-agent.md) 智能体开发框架。安装:`marqdo ext list` / `add llm|agent` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)
|
||||
- **原生插件 ABI v1**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);demo `plugins/demo`
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
|
||||
```bash
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- debug public --no-open
|
||||
cargo run -- catalog public -o .marqdo
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
cargo run -- catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
文档:用户站见 [public/](public/) 与 [user-site.md](doc/design/user-site.md);设计文稿见 [doc/](doc/);`view` 皮肤见 [view.md](doc/design/view.md);OKF 清单见 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
**发布包(GitHub Releases)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+17
-1
@@ -16,22 +16,38 @@
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置 `print` `input`** |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
||||
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
|
||||
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Marqdo AI Skill
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
|
||||
| `examples.md` | 按需:可复制样例 |
|
||||
|
||||
## 使用
|
||||
|
||||
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
|
||||
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
|
||||
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
|
||||
|
||||
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
|
||||
@@ -32,7 +32,10 @@ positional ::= value_token
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 内置 `print` 形参名为 `text`:`> print Hi` 与 `> print text=Hi` 等价。
|
||||
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
|
||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
||||
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -21,7 +21,8 @@
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -81,6 +81,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ tests/
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Native plugin ABI (v1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| Date | 2026-08-06 |
|
||||
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
|
||||
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
|
||||
## Goals
|
||||
|
||||
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
|
||||
- **Not** linked into the `marqdo` binary; load at runtime.
|
||||
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
|
||||
- Official / local paths only — **no** third-party package registry.
|
||||
|
||||
## Contract
|
||||
|
||||
`MARQDO_ABI_VERSION = 1`.
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | Must equal host’s supported version |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`.
|
||||
|
||||
### Wire format
|
||||
|
||||
Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
|
||||
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/json`).
|
||||
|
||||
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
|
||||
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load path=demo.dll
|
||||
|
||||
*`sum` = > demo_add a=1 b=2 *
|
||||
> print text=`sum`
|
||||
```
|
||||
|
||||
After `load`, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user `#`/`##` defs).
|
||||
|
||||
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected. Prefer a same-directory filename, or pass a path via a variable / env (see gold tests).
|
||||
|
||||
## Demo
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_demo
|
||||
# Windows: target/debug/demo.dll
|
||||
# Linux: target/debug/libdemo.so
|
||||
# macOS: target/debug/libdemo.dylib
|
||||
```
|
||||
|
||||
Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
|
||||
Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Embedding plugins in the release exe by default
|
||||
- Callbacks from plugin into arbitrary Marqdo evaluation
|
||||
- OS sandbox / seccomp
|
||||
- **Third-party** plugin / package registry
|
||||
|
||||
Official install of known extensions (`marqdo ext add …`) is **planned** — see [ext-cli.md](ext-cli.md). That is not a public marketplace.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Official agent development framework (`ext/ai/agent`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted · **thin agent loop locked** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) |
|
||||
|
||||
## What we are building
|
||||
|
||||
An **agent-development framework** — smallest runtime surface for agents on Marqdo.
|
||||
|
||||
**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext.
|
||||
|
||||
| In scope | Out of scope (your runbook / your code) |
|
||||
|----------|-------------------------------------------|
|
||||
| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … |
|
||||
| `## 执行` | Anything task-specific in `ext/` |
|
||||
| `## 清空历史` | |
|
||||
| Auto context: source, position, history, Marqdo skill | |
|
||||
|
||||
## Repo layout (`ext/`)
|
||||
|
||||
Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md`
|
||||
|
||||
## Layering
|
||||
|
||||
| Layer | Role |
|
||||
|-------|------|
|
||||
| **Your runbook** | Tables, loops, **your** tools & logic |
|
||||
| **`ext/ai/llm`** | Model I/O |
|
||||
| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` |
|
||||
| **`lib/*`** | Generic I/O |
|
||||
|
||||
```text
|
||||
> ext/ai/智能体.mq.md
|
||||
▼
|
||||
# 智能体 (大模型, 工具, 用户提示信息?)
|
||||
## 执行
|
||||
## 清空历史
|
||||
```
|
||||
|
||||
`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module.
|
||||
|
||||
Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
|
||||
|
||||
### Tools (v1)
|
||||
|
||||
Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table:
|
||||
|
||||
```markdown
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
| 分配任务 |
|
||||
```
|
||||
|
||||
- Single-column table → list of function **names** (text).
|
||||
- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`.
|
||||
- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:<name>`.
|
||||
- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls.
|
||||
|
||||
---
|
||||
|
||||
## Public API (v1)
|
||||
|
||||
| | Role |
|
||||
|--|------|
|
||||
| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** |
|
||||
| `## 执行` / `## run` | **额外信息**; context + LLM + history append |
|
||||
| `## 清空历史` / `## clear_history` | Wipe history on this handle |
|
||||
|
||||
Module-level `##` helpers (e.g. context assembly) are internal — not public contract.
|
||||
|
||||
### Auto context (each `执行`)
|
||||
|
||||
- `.mq.md` source
|
||||
- Call-site / position
|
||||
- Conversation history on this handle
|
||||
- Marqdo skill (`skills/marqdo/`)
|
||||
|
||||
### History (v1)
|
||||
|
||||
- Host-backed id per handle
|
||||
- Append after each successful `执行`
|
||||
- `清空历史` ships with `执行`
|
||||
|
||||
---
|
||||
|
||||
## Example runbook (application — not framework)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 *
|
||||
*`工具名` = | 技能匹配 | 分配任务 | … |
|
||||
*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… *
|
||||
|
||||
- [任务](任务队列)
|
||||
> `助手`.清空历史
|
||||
*`结果` = > `助手`.执行 额外信息=`任务` *
|
||||
```
|
||||
|
||||
Domain `##` functions live in **this file** or your lib — never in `ext/ai/`.
|
||||
|
||||
---
|
||||
|
||||
## Shipped / roadmap
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| `ext/ai/` + framework + context injection | in progress |
|
||||
| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped |
|
||||
| Tool-call loop in `执行` (`TOOL:<name>` → `call_fn`) | shipped |
|
||||
|
||||
### Non-goals
|
||||
|
||||
- Domain tools in official ext
|
||||
- Flat `ext/*.mq.md` at repo root
|
||||
- Second chat stack beside llm
|
||||
@@ -0,0 +1,61 @@
|
||||
# Official extension installer (`marqdo ext`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext`
|
||||
|
||||
Imports use paths like `> ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed into `ai/`.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md` |
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
@@ -0,0 +1,70 @@
|
||||
# Official extensions (`ext/`) — LLM
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods on the handle |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_env
|
||||
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing)
|
||||
- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
@@ -0,0 +1,137 @@
|
||||
# 内置关键字 / 函数:中英双名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(已实现)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **无需导入**;中英为**同一语义的别名**,不是语言模式开关 |
|
||||
| 相关 | [keywords.md](keywords.md) · [stdlib-i18n.md](stdlib-i18n.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区分语言**」(见 [stdlib-i18n.md](stdlib-i18n.md));对**不必导入**的一层——字面量关键字与极少内置函数——也要对等提供中文名。
|
||||
|
||||
正因为每增加一个内置名,就要同时维护中英(及日后更多语言)别名,所以:
|
||||
|
||||
> **关键字 / 内置必须少而精**——体积在「名字 × 语言」上放大,而不是在功能清单上堆满。
|
||||
|
||||
更多能力进可导入的 `lib/`,用中英**不同库文件、不同函数名**扩展,不膨胀解释器内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层(与标准库对齐)
|
||||
|
||||
| 层 | 是否导入 | 中英怎么区分 |
|
||||
|----|----------|--------------|
|
||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
||||
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
|
||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围:哪些要双名
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
中英文名均**不可作变量名**(同一保留集)。
|
||||
|
||||
### 3.2 内置函数(可调用、无需导入)
|
||||
|
||||
**仅**下列核心五项做中英双名(与「少而精」一致):
|
||||
|
||||
| 英文 | 中文(提案) | 作用 |
|
||||
|------|--------------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
形参名也提供中英别名(便于纯中文调用):
|
||||
|
||||
| 英文形参 | 中文形参 | 用于 |
|
||||
|----------|----------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及对应中文名 |
|
||||
|
||||
示例(等价):
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > len `s`*
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
### 3.3 明确不进 L0 双名表
|
||||
|
||||
下列若已在解释器中实现,视为**宿主原语 / 过渡 API**,**不**再批中文内核别名;应迁入或仅通过标准库暴露(中英分文件):
|
||||
|
||||
| 英文名 | 去向 |
|
||||
|--------|------|
|
||||
| `type` | L1 或维持实现细节,不进「关键字最少集」宣传 |
|
||||
| `trim` `split` `join` | L1:`lib/text.mq.md` / `lib/文本.mq.md` |
|
||||
| `at` | L1:`lib/table.mq.md` / `lib/表.mq.md` |
|
||||
|
||||
这样 L0 公开面 ≈ **6 个关键字词 ×2 + 5 个函数 ×2**,而不是「每个工具函数都 ×2」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语义规则
|
||||
|
||||
1. **别名等价**:中英文名绑定同一实现;诊断文案可用英文稳定串(金样例已有),用户文档中英均可举例。
|
||||
2. **可混用**:同一文件可同时出现 `print` 与 `打印`、`True` 与 `真`。
|
||||
3. **遮蔽**:用户 `# 打印` 与 `# print` 均会遮蔽对应内置名(实现阶段应警告)。
|
||||
4. **大小写**:英文关键字保持 Python 风格(`True`/`False`/`None`);中文无名感大小写问题。
|
||||
5. **扩语言**:日后日文等 → 再为 L0 增加第三个别名列;仍无「名字表」而非语言开关。标准库继续用**文件名**区分(见 i18n 草案)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与旧决议的关系
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档与金样例义务(实现时)
|
||||
|
||||
| 项 | 要求 |
|
||||
|----|------|
|
||||
| `keywords.md` | L0 表改为中英并列;砍掉对 `trim`/`split`/… 的「内核关键字」宣传 |
|
||||
| `public/` | 英 / 中文件同目录并列(拉丁名 vs 中文名) |
|
||||
| `tests/` | 中文关键字 / `打印`·`长度` 等金样例;与英文样例对等 |
|
||||
| 诊断 | 位置格式不变;message 可暂维持英文,或中英均可接受(另开小节) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现备忘(暂不开发)
|
||||
|
||||
1. 词法 / 解析:字面量与 `and`/`or`/`not` 识别中文别名。
|
||||
2. 调用解析:内置表按别名归一到同一 `BuiltinId`。
|
||||
3. 形参绑定:`text`≡`内容`,`prompt`≡`提示`,`value`≡`值`。
|
||||
4. **不要**加 `lang:` 或全局「中文模式」。
|
||||
5. 与 [stdlib-i18n.md](stdlib-i18n.md) 一并落地时:先收束 L0 公开面,再铺 `lib/text` ↔ `lib/文本`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**内核:中英别名、无需导入、必须少;标准库:中英分文件、靠导入路径选择——这样 Marqdo 才能中英文通用而不把解释器撑爆。**
|
||||
+51
-38
@@ -2,51 +2,65 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(前期够用) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **英文**;参考 [Python](https://realpython.com/python-keywords/) 但远更少;控制流仍靠 Markdown 标记,不引入 `if`/`while`/`def` |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) |
|
||||
| 状态 | 已定(中英双名) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **少而精**;控制流靠 Markdown;内核中英**别名等价**(见 [keywords-i18n.md](keywords-i18n.md)) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords-i18n.md](keywords-i18n.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **英文标识**:内置与字面量用英文,便于工具高亮与国际协作。
|
||||
3. **学 Python 的边界**:Python 3 里 [`print` / `input` 是内置函数,不是关键字](https://realpython.com/python-keywords/);布尔与空值是字面量关键字。Marqdo 同样区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:前期只列执行金样例所需;要加再进 ADR。
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键字(词法保留,不可作变量名)
|
||||
|
||||
| 关键字 | 含义 | 备注 |
|
||||
|--------|------|------|
|
||||
| `True` | 布尔真 | 对齐 Python 大小写 |
|
||||
| `False` | 布尔假 | |
|
||||
| `None` | 空值 | |
|
||||
| `and` | 逻辑与 | 表达式内 |
|
||||
| `or` | 逻辑或 | |
|
||||
| `not` | 逻辑非 | |
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**本期不引入:** `if` `else` `elif` `while` `for` `def` `class` `return` `import` `pass` `break` `continue` `in` `is` `lambda` …
|
||||
(`else` 分支臂仍用臂头单独的 `*` 标记,不是单词 `else`。)
|
||||
**不引入:** `if` `else` `while` `for` `def` `return` …(分支臂 `*` 不是单词 `else`。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 内置函数(可调用名,建议勿遮蔽)
|
||||
## 3. 内置函数(可调用,无需导入)
|
||||
|
||||
| 名称 | 作用 | 调用示例 |
|
||||
|------|------|----------|
|
||||
| `print` | 写到 stdout(副作用) | `> print text=Hello` 或 `> print Hello`(位置实参,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `input` | 从 stdin 读一行(返回文本) | `*`name` = > input prompt=Name: *` |
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行;capture / view 用 frontmatter `stdin:` / `输入:`、表单或 `--stdin-file` 预置 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
参数约定(v0):
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
- `print`:具名实参 `text`(必填);日后可扩展 `end` 等。
|
||||
- `input`:可选 `prompt`;返回用户输入字符串(不含换行)。
|
||||
形参别名:
|
||||
|
||||
旧文档中的中文 `print` **废弃**,统一为 `print`。
|
||||
| 英文 | 中文 | 用于 |
|
||||
|------|------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及其中文名 |
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
宿主原语 `type` / `trim` / `split` / `join` / `at` **无**内核中文别名;文本/表扩展走标准库文件(见 [stdlib-i18n.md](stdlib-i18n.md))。转换错误见 [stdlib.md](stdlib.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -55,30 +69,29 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
> 打印 内容=Hello World!
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
+ *
|
||||
> print text=other
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
- `>` 是**调用标记**(架构)。
|
||||
- `print` 是**被调名字**(内置库)。
|
||||
- 用户自定义 `# print` 会遮蔽内置(实现应警告)。
|
||||
- `>` 是调用标记;`print` / `打印` 是同一内置的别名。
|
||||
- 用户 `# print` 或 `# 打印` 会遮蔽对应名字。
|
||||
|
||||
---
|
||||
|
||||
## 5. 标识符规则(摘要)
|
||||
|
||||
- 变量:行内 `` `name` ``;`name` 不可为上表关键字。
|
||||
- 函数名:`#` 标题文本;建议 ASCII/英文,中文标题仍允许但内置名保持英文。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and` `or` `not`。
|
||||
- 变量:`` `name` ``;不可为上表任一中英文关键字。
|
||||
- 函数名:`#` 标题;中英文均可。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and`/`且`、`or`/`或`、`not`/`非`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续可增(未批准)
|
||||
|
||||
`len`、`str`、`int`、`float`、`range`;以及 `break`/`continue`(若循环需要)。增加前开短 ADR。
|
||||
`float`、`range`;以及 `break`/`continue`。增加前开短 ADR,并同步考虑是否值得占用双名配额。
|
||||
@@ -1,11 +1,11 @@
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
@@ -15,8 +15,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,38 +30,50 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.1)
|
||||
## 3. 映射总表(v0.2)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | 函数;层数 = 作用域 |
|
||||
| 函数头下 `-` 纯名 | 形参 |
|
||||
| 体内 `-` | 循环 |
|
||||
| 体内 `+` 或 `1.` | 分支 |
|
||||
| 分支臂头整行恰为 `*` | else |
|
||||
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||||
| GFM 表格 | 集合 |
|
||||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### `+` / `-` / `1.` 消歧
|
||||
|
||||
| 位置 | `+` | `1.` … | `-` |
|
||||
|------|-----|--------|-----|
|
||||
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
|
||||
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
|
||||
|
||||
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.1) |
|
||||
| 错误(旧) | 正确(v0.2) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
|
||||
| 输出与返回抢粗体 | 粗体只表示 **返回** |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
@@ -76,13 +89,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
*`y` = `x` + 2*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
# 加一
|
||||
- n
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
@@ -97,7 +110,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂**第一行整行只有一个** `*` → else。
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
@@ -110,9 +123,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
---
|
||||
|
||||
## 6. 函数、作用域、提升
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
规则同 v0。推荐:
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -120,48 +135,90 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
(需要打印时对返回值再 `> print`,或直接 `> print`。)
|
||||
可选形参:
|
||||
|
||||
形参 `- 名` → 体内 `` `名` ``。
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
```
|
||||
|
||||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定与比较
|
||||
## 7. 绑定、比较与字符串
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||||
|
||||
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
|
||||
### 双引号字符串(复杂文本)
|
||||
|
||||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||||
|
||||
```markdown
|
||||
> input prompt="你叫什么名字\n"
|
||||
*`msg` = "Hello, `name`!\n"*
|
||||
```
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
|
||||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
1. `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
2. `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
*`bool_value` = True*
|
||||
|
||||
1. `bool_value` == True
|
||||
> print text=True
|
||||
2. *
|
||||
> print text=False
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
`while`:
|
||||
|
||||
```markdown
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 集合(表格)
|
||||
@@ -175,21 +232,19 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
@@ -198,20 +253,16 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
||||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
||||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
||||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
||||
|
||||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 用 `*` 作无序列表符
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Objects(`#`)与函数(`##`+)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Accepted |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [ext-llm.md](ext-llm.md) |
|
||||
|
||||
## 1. 约定
|
||||
|
||||
| 标题层 | 含义 |
|
||||
|--------|------|
|
||||
| `#`(恰好一层) | **对象 / 类型**。正文 = 构造体;调用类型名 = 构造实例。 |
|
||||
| `##` 及更深 | **函数**(自由函数或方法)。层数差表示嵌套,与 v0.1 相同。 |
|
||||
|
||||
`# main` 是**入口对象**:运行文件 = 执行其构造体。若无 `main`,且文件恰好只有一个无参顶层 `#` 对象(如 `# Hello World`),则把它当作入口。
|
||||
|
||||
## 2. 实例句柄
|
||||
|
||||
构造返回值若为 `map`,运行时写入 `_type`(文本,值为类型名),形成句柄。
|
||||
方法调用通过 `_type` 找到定义对象,再解析其下的 `##` 方法。
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `自`(中文)
|
||||
- `self`(英文)
|
||||
|
||||
二者同一接收者。
|
||||
|
||||
## 3. 调用外形
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*`自` = …配置 map…*
|
||||
**`自`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
…使用 `自` …
|
||||
**`内容`**
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 模型名=gpt-4o-mini *
|
||||
*`回复` = > `模型`.运行 提示=你好 *
|
||||
> print text=`回复`
|
||||
```
|
||||
|
||||
- `> 大模型 …` — 构造
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名)
|
||||
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
|
||||
|
||||
## 4. 标准库
|
||||
|
||||
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
|
||||
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
|
||||
|
||||
## 5. 非目标(本波)
|
||||
|
||||
- 继承 / 接口 / 可见性
|
||||
- 无 `_type` 的「鸭子」方法分发
|
||||
- 用表格声明字段 schema(表格仍表示集合)
|
||||
|
||||
## 6. 迁移摘要
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 库顶层 `# http_get` | `## http_get` |
|
||||
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
|
||||
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
|
||||
@@ -27,15 +27,17 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | 进入/离开函数、绑定、分支臂选择、`print` 调用 |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(见 [bytecode.md](bytecode.md)) |
|
||||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||||
|
||||
格式约定:
|
||||
|
||||
- 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- 可选 `--dump-format=text|json`(json 后置,text 先做)
|
||||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- `--trace-eval`:每条事件一行 JSON,例如
|
||||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
||||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# 外联 / 胶水标准库
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则
|
||||
|
||||
**导入即用**:`lib/foreign` / `lib/外联`。解释器来自用户本机(PATH / `set_cmd` / `MARQDO_FOREIGN_*`)。live view 可点 Run;静态导出展示源码,Run 禁用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 绑定语法(与公式同构)
|
||||
|
||||
```markdown
|
||||
`hi` =
|
||||
```python
|
||||
print("hello")
|
||||
```
|
||||
|
||||
*`out` = > run code=`hi` *
|
||||
```
|
||||
|
||||
得到运行时类型 **`code`**(`lang` + `source`)。未绑定的 \`\`\` 围栏仍是叙述注释。
|
||||
|
||||
曾用的 \`\`\`python name=hi **已移除**。
|
||||
|
||||
---
|
||||
|
||||
## 3. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_cmd` | `设置命令` | `lang`, `cmd` | None |
|
||||
| `run` | `运行` | `code`(code 值) | 文本 stdout |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source` | 文本 |
|
||||
| `langs` | `语言表` | | 列表 |
|
||||
|
||||
live view:Structure 中 code 卡片带命令框 + Run → `POST /api/foreign-run`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 一句话
|
||||
|
||||
**`name` = + \`\`\`lang 围栏 → code 值;显式 run;本机解释器可配置。**
|
||||
@@ -0,0 +1,146 @@
|
||||
# 标准库多语言命名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **草案(先文档、后实现)** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要解决什么
|
||||
|
||||
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
|
||||
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
|
||||
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案(采用)
|
||||
|
||||
**导入哪个库文件,就用哪套函数名。**
|
||||
文件名本身表达语言;解释器只做路径解析,不做语言推断。
|
||||
|
||||
### 2.1 推荐:库名用目标语言书写
|
||||
|
||||
| 导入 | 库内函数名(示例) |
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `rows` · `row_at` |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > 拆分 s=a,b,c sep=,*
|
||||
```
|
||||
|
||||
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
|
||||
|
||||
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
|
||||
|
||||
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
|
||||
|
||||
| 导入 | 含义 |
|
||||
|------|------|
|
||||
| `> lib/text-en.mq.md` | 英文 API |
|
||||
| `> lib/text-zh.mq.md` | 中文 API |
|
||||
|
||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
||||
|
||||
### 2.3 明确不做
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
|
||||
| `> std/text` 再按语言展开 | 多一次魔法 |
|
||||
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
|
||||
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
|
||||
|
||||
---
|
||||
|
||||
## 2.4 特例:JSON
|
||||
|
||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
||||
|
||||
```text
|
||||
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
```
|
||||
|
||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与「少而精内置」的边界
|
||||
|
||||
| 层 | 内容 | 如何获得 |
|
||||
|----|------|----------|
|
||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
|
||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||||
|
||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录与扩展约定
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
||||
# 暂缓:math/数学 · foreign/外联
|
||||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
||||
```
|
||||
|
||||
扩展新语言时:
|
||||
|
||||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
||||
2. 库内函数名用该语言习惯。
|
||||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
||||
|
||||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档与示例义务
|
||||
|
||||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
||||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
||||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现备忘(暂不开发)
|
||||
|
||||
实现阶段仅需:
|
||||
|
||||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
||||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
||||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
||||
|
||||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|
||||
@@ -0,0 +1,231 @@
|
||||
# 数学标准库(方案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **公式类型**:解析 `$$…$$`(及行内 `$…$` 的可选支持),得到可绑定、可传递的 **`formula` 值**——语义上像「公式常量 / 公式变量」。
|
||||
2. **数学库对 `formula`(及文本表达式)做操作**:求值、化简、求导、求解、作图等。
|
||||
3. **数值 + 随机**:日常算术与可复现随机。
|
||||
4. **作图**:view / 静态页内嵌 SVG;CLI 写本地文件(可指定 `path`)。
|
||||
|
||||
**难度自觉:** 只覆盖高中知识面,自研小型表达式 AST + 规则即可,**不**追求 Mathematica / SymPy 完备性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心模型:`formula` 类型
|
||||
|
||||
### 2.1 运行时
|
||||
|
||||
| 类型 | `type` 标签 | 说明 |
|
||||
|------|-------------|------|
|
||||
| `Value::Num(f64)` | `num` | 浮点 |
|
||||
| `Value::Formula(…)` | `formula` | 已解析的表达式树(或等价内部表示) |
|
||||
|
||||
`print` / `str` 对 `formula`:输出规范 ASCII(如 `2*x + 1`)或保留源 LaTeX 的一种(实现时写死并文档化;建议 **ASCII 规范式** 便于测试)。
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
sin(x) + x
|
||||
$$
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> plot formula=`f` var=x min=-3 max=3 path=f.svg
|
||||
````
|
||||
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
| 英文 | 中文 | 说明 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | `text=` 解析为 `formula`(ASCII 或简单 LaTeX 子集) |
|
||||
|
||||
数学库函数形参统一接受:**`formula` 值**,或能解析的 **文本**(内部先 `formula` 化)。
|
||||
|
||||
### 2.4 与叙述面的关系
|
||||
|
||||
- `` `f` = `` + `$$…$$`:代码面赋值,得到 `formula` 值。
|
||||
- 成段注释里的 `$$`:仍是注释,不解析为公式。
|
||||
- view:公式赋值在 Structure 中显示为绑定,不是 comment。
|
||||
|
||||
(见 [markdown-mapping.md](markdown-mapping.md):空 RHS + `$$` → 公式赋值。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 知识范围(高中)
|
||||
|
||||
### 3.1 表达式与符号(S)
|
||||
|
||||
| 纳入 | 例子 |
|
||||
|------|------|
|
||||
| 多项式 | `x^2 - 3*x + 2` |
|
||||
| 初等函数 | `sin` `cos` `tan` `ln` `exp` `sqrt` `abs` |
|
||||
| 四则、幂 | `+ - * / ^` |
|
||||
| 化简 / 展开 | 合并同类项、基本三角恒等(小集合) |
|
||||
| 求导 | 单变元,初等函数求导法则 |
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
| 纳入 | 说明 |
|
||||
|------|------|
|
||||
| 显函数 `y=f(x)` | 采样折线 SVG |
|
||||
| 导数曲线 | 对 `formula` 先 `diff` 再画,或 `plot` 选项 `derivative=true` |
|
||||
| 圆锥曲线 | 标准形:圆、椭圆、双曲线、抛物线(参数方程或隐式采样) |
|
||||
| 点列 | `plot_points` |
|
||||
|
||||
**不做:** 三维、隐函数通用求解器、交互缩放(静态 SVG 足够)。
|
||||
|
||||
### 3.3 数值与随机(N)
|
||||
|
||||
常数、四则、三角、对数、取整、`num` 转换、`random` / `random_int` / `seed`(同前稿)。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 草图(对 `formula` 操作)
|
||||
|
||||
### 4.1 构造与数值
|
||||
|
||||
| 英文 | 中文 | 要点 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | 文本 → formula |
|
||||
| `pi` `e` | `圆周率` `自然底数` | → num |
|
||||
| `add`… / `sin`… | `加`… / `正弦`… | 对 num;若传入 formula 则返回 formula(符号)或报错——**v1 建议:算术函数只接 num;符号用 simplify/diff/subs** |
|
||||
| `eval` | `求值` | `formula` + 变量赋值 → num |
|
||||
| `random` / `random_int` / `seed` | `随机` / `随机整数` / `设种子` | 见前 |
|
||||
|
||||
### 4.2 符号
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `simplify` | `化简` | `formula` | formula |
|
||||
| `expand` | `展开` | `formula` | formula |
|
||||
| `diff` | `求导` | `formula`, `var` | formula |
|
||||
| `subs` | `代入` | `formula`, `var`, `value` | formula 或 num |
|
||||
| `solve` | `求解` | `formula`, `var`,可选区间 | list(num 或公式根) |
|
||||
|
||||
### 4.3 作图
|
||||
|
||||
| 英文 | 中文 | 形参 |
|
||||
|------|------|------|
|
||||
| `plot` | `绘图` | **`formula`**(或 `expr` 文本), `var`, `min`, `max`;可选 `steps`, `path`, `derivative`, **`grid`**(默认开;`False`/`假` 关) |
|
||||
| `plot_conic` | `绘圆锥` | `kind`(circle/ellipse/hyperbola/parabola)+ 系数;可选 `path`, `grid` |
|
||||
| `plot_points` | `绘点列` | `xs`, `ys`;可选 `path`, `grid` |
|
||||
|
||||
返回 **SVG 文本**;坐标轴带箭头与刻度,默认网格;写文件与 view 嵌入规则同前(§5)。
|
||||
|
||||
`diff` / `simplify` / `expand` / 未完全数值化的 `subs` 返回 **`formula`**,可继续链式调用。
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`svg` = > plot formula=`f` var=x min=-3 max=3 path=parabola.svg *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 作图:CLI / view / 静态(不变精神)
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 带 `path=` | 写 SVG 到该路径(沙箱内) |
|
||||
| CLI 无 path | 自动 `{stem}-plot-{n}.svg` + 一行 `plot: …` |
|
||||
| view / 导出无 path | 不强制写盘;加入 **plots 产物列表**,Execution 内嵌 |
|
||||
| view / 导出有 path | 写盘 + 内嵌 |
|
||||
|
||||
不把整段 SVG 默认灌进 CLI stdout。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分期
|
||||
|
||||
| 期 | 交付 |
|
||||
|----|------|
|
||||
| **M1** | `Num` + 数值/随机;`Formula` AST + `` `name` = `` + `$$…$$` 赋值绑定 |
|
||||
| **M2** | `simplify` / `diff` / `subs` / `eval` / 二次 `solve`(高中子集) |
|
||||
| **M3** | `plot` / `plot_points` / `plot_conic` + view 内嵌 + path 写盘 |
|
||||
| **M4** | 用户文档 `public/stdlib/math*` · 金样例 · mapping 文档补丁 |
|
||||
|
||||
M1–M3 可在同一发版列车上连续落地;验收以「公式赋值 → 求导 → 作图」一条龙为准。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现要点
|
||||
|
||||
```text
|
||||
src/formula/ # 词法/AST/化简/求导/求值(高中规则表)
|
||||
src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
||||
src/host/plot.rs # SVG
|
||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
||||
Value::Num / Value::Formula
|
||||
Interpreter.plots: Vec<String>
|
||||
lib/math.mq.md · lib/数学.mq.md
|
||||
```
|
||||
|
||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做
|
||||
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收
|
||||
|
||||
1. `` `f` = `` + `$$…$$` + `diff` / `solve` / `plot` 金样例(中英库)。
|
||||
2. 固定 `seed` 的随机金样例。
|
||||
3. `plot` + `path` 在 CLI 落盘;view HTML 含 `<svg`。
|
||||
4. `type` 对公式为 `formula`,对浮点为 `num`。
|
||||
5. view Structure 将公式赋值显示为绑定,而非 comment。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**`` `f` = `` + `$$…$$` 产出 `formula` 值;数学库对它做高中范围的符号运算、求解与作图——数值与随机并行,图在 view 内嵌、在 CLI 写文件。**
|
||||
@@ -0,0 +1,181 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层与实现分工
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
|
||||
|
||||
### 3.2 系统 — 已含 dotenv
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
|
||||
### 3.4 JSON — 已含 `quote`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `quote` | `text` | JSON 字符串字面量(含引号) |
|
||||
|
||||
### 3.5 网络 — HTTPS
|
||||
|
||||
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
|
||||
|
||||
### 3.6 插件 — `plugin` / `插件`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
|
||||
| `unload` | `卸载` | (无) | `None` |
|
||||
| `list` | `列出` | (无) | 已注册名列表 |
|
||||
|
||||
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
|
||||
|
||||
### 3.1–3.5 历史 API 草图
|
||||
|
||||
#### 文件 — `fs` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
| `read_text` | `读文本` | `path` / `路径` | 文本 |
|
||||
| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
|
||||
| `append_text` | `追加文本` | 同上 | `None` |
|
||||
| `exists` | `存在` | `path` / `路径` | 布尔 |
|
||||
| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
|
||||
| `now_ms` | `此刻毫秒` | (无) | 整数 |
|
||||
| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
fs.mq.md / 文件.mq.md
|
||||
sys.mq.md / 系统.mq.md
|
||||
time.mq.md / 时间.mq.md
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
math.mq.md / 数学.mq.md
|
||||
foreign.mq.md / 外联.mq.md
|
||||
plugin.mq.md / 插件.mq.md
|
||||
|
||||
ext/ # 非 stdlib
|
||||
llm.mq.md / 大模型.mq.md
|
||||
agent.mq.md / 智能体.mq.md
|
||||
```
|
||||
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
|
||||
@@ -0,0 +1,25 @@
|
||||
# 子任务标准库(subtask)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v2 |
|
||||
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `join` 返回值 |
|
||||
|------|----------|---------------|
|
||||
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
|
||||
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
|
||||
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
|
||||
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
|
||||
|
||||
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
|
||||
|
||||
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
|
||||
|
||||
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
|
||||
|
||||
Host:`host_subtask_*`(`src/host/subtask.rs`)。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 自写回标准库(writeback)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
|
||||
## 存储格式
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
<!-- marqdo-out
|
||||
42
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移)
|
||||
- 默认在**调用行下方**插入或替换紧邻块(中间可有空行)
|
||||
- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块)
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `record` | `写回` | `value=`,可选 `at_end=false` |
|
||||
| `get` | `取` | 可选 `at_end=false` |
|
||||
| `clear` | `清除` | 可选 `at_end=false` |
|
||||
| `list` | `列出` | 全文所有输出块(含推断锚点行) |
|
||||
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`)。
|
||||
@@ -0,0 +1,104 @@
|
||||
# 标准库(P2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置一览(S0 + S1)
|
||||
|
||||
| 名 | 形参 | 结果 |
|
||||
|----|------|------|
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
| `at` | `value`, `index` | 列表下标(越界 → `None`) |
|
||||
|
||||
表(单列表格)在运行时是 `list`:行数用 `len`,取行用 `at`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
1. 相对当前文件
|
||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
|
||||
|
||||
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
|
||||
|
||||
| 路径 | 导出 |
|
||||
|------|------|
|
||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
|
||||
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
|
||||
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
|
||||
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
|
||||
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
|
||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
||||
| `lib/table.mq.md` | `rows` `row_at` |
|
||||
| `lib/表.mq.md` | `行数` `取行` |
|
||||
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 转换错误约定(S3)
|
||||
|
||||
用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
内置转换相关文案(稳定子集,金样例断言):
|
||||
|
||||
| 情况 | message |
|
||||
|------|---------|
|
||||
| 非法整数文本 | `cannot convert to int: "…"` |
|
||||
| `int` 类型不对 | `int needs int, bool, or text` |
|
||||
| `len` 类型不对 | `len needs text or list` |
|
||||
| `trim` 非文本 | `trim needs text` |
|
||||
| `split`/`join` 参数类型 | `split needs text value` 等 |
|
||||
| 空分隔符 | `split sep must not be empty` |
|
||||
|
||||
不引入独立异常类型对象;一律走 `Diagnostic`。
|
||||
+11
-2
@@ -13,7 +13,7 @@
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
@@ -50,7 +50,16 @@ public/
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
## 4. 内容分层(用户站)
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
|
||||
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
|
||||
|
||||
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# View 调试(`marqdo debug`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
## Debug 布局(对齐常见调试器)
|
||||
|
||||
参考 VS Code / Chrome DevTools / Jupyter debugger:
|
||||
|
||||
```
|
||||
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
|
||||
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
|
||||
│ │ ├─ Breakpoints │
|
||||
│ │ └─ Call stack │
|
||||
├────────┴────────────────────────────────────┴────────────────┤
|
||||
│ Debug Console (session stdout) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 暂停粒度:语句起点(树遍历)。
|
||||
- 无断点时 Start 停在第一句。
|
||||
- Structure 为断点面(非 Source 行)。
|
||||
|
||||
## API
|
||||
|
||||
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
|
||||
|
||||
## View 大纲
|
||||
|
||||
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
|
||||
+9
-6
@@ -25,14 +25,14 @@
|
||||
| 规则 | 要求 |
|
||||
|------|------|
|
||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
||||
| 布局 | 壳层 `max-width ≈ 1400px` 居中;侧栏 ≈280px sticky;主内容 `max-width ≈ 58rem`(宽屏可读、不过窄);**≤800px 侧栏收起**,顶栏汉堡(checkbox,无 JS) |
|
||||
| 布局 | 壳层 `max-width ≈ 1680px`;侧栏 ≈280px;主内容 `max-width ≈ 76rem`;Structure 旁函数大纲;**≤800px 侧栏收起** |
|
||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
||||
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `40rem` 方案。
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -75,6 +75,7 @@ OUT_DIR/
|
||||
|
||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
|
||||
@@ -87,9 +88,10 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
---
|
||||
|
||||
## 4. 信息架构(不变)
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏索引 + 主区三节:结构(AST+注释插回)· 执行 · 源码。表达式为表面语法,非 Debug。
|
||||
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
||||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -107,7 +109,8 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 6. 验收
|
||||
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件。
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
@@ -0,0 +1,82 @@
|
||||
# VS Code 扩展 — 分支与提交约定
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
|
||||
| 扩展分支 | **`vscode-extension`** |
|
||||
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则(必读)
|
||||
|
||||
| 分支 | 是否跟踪 `vscode-extension/` |
|
||||
|------|-------------------------------|
|
||||
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
|
||||
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
|
||||
|
||||
**禁止**在 `main` 上:
|
||||
|
||||
- 删除 `.gitignore` 里的 `/vscode-extension/`
|
||||
- `git add vscode-extension/`
|
||||
- 把扩展目录「合并进 main」以便发版
|
||||
|
||||
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 日常开发(扩展)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile
|
||||
```
|
||||
|
||||
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
|
||||
|
||||
```bash
|
||||
git add vscode-extension/
|
||||
git commit -m "vscode-extension: <简要说明>"
|
||||
git push origin vscode-extension
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常开发(CLI / 语言)
|
||||
|
||||
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
|
||||
|
||||
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发版(CLI tag + VSIX)
|
||||
|
||||
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
|
||||
2. **VSIX**:Release 工作流在 tag 构建时执行:
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
|
||||
```
|
||||
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
|
||||
|
||||
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给 Agent / 协作者
|
||||
|
||||
执行「更新 VS Code 插件」类任务时:
|
||||
|
||||
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
|
||||
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
|
||||
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
|
||||
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
|
||||
@@ -0,0 +1,31 @@
|
||||
# VS Code 扩展(分支指针)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定分支模型** |
|
||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
||||
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
|
||||
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
|
||||
|
||||
---
|
||||
|
||||
## 分工(类比 `public` / `gh-pages`)
|
||||
|
||||
| 分支 | 内容 |
|
||||
|------|------|
|
||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
|
||||
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
|
||||
| `gh-pages` | 用户站生成 HTML |
|
||||
|
||||
```bash
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm install
|
||||
```
|
||||
|
||||
规范入口(在 **`vscode-extension` 分支**上阅读):
|
||||
|
||||
- `vscode-extension/README.md` — 目标与目录
|
||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
||||
|
||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -0,0 +1,220 @@
|
||||
# 下一阶段:从玩具到可用语言
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
|
||||
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/view-debug.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状快照(决策依据)
|
||||
|
||||
| 能力 | 现状 | 结论 |
|
||||
|------|------|------|
|
||||
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
|
||||
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
---
|
||||
|
||||
## 1. 轻重缓急(总序)
|
||||
|
||||
```text
|
||||
P0 诊断加固(短、撬动后续一切)
|
||||
P1 输入补完(先 CLI,再 view)
|
||||
P2 最小标准库(内置 + 可选 .mq.md 库)
|
||||
P3 view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
|
||||
```
|
||||
|
||||
| 优先级 | 主题 | 为何此刻 | 不做的代价 |
|
||||
|--------|------|----------|------------|
|
||||
| **P0** | 诊断完备度 | 便宜;给金样例、字节码、调试打地基 | 断点停错行;双后端错误体验分裂 |
|
||||
| **P1** | `input` | 「真语言」最低交互面;已有半截实现 | 只能写纯计算/打印 demo |
|
||||
| **P2** | 标准库 | 无库则用户无法写稍大程序 | 人人自造轮子、示例膨胀 |
|
||||
| **P3** | 前端调试 | 差异化(文档即调试);成本最高 | view 仍停留在「跑完看 stdout」 |
|
||||
|
||||
**原则:** 先让 **CLI 树遍历**成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。
|
||||
|
||||
---
|
||||
|
||||
## 2. P0 — 诊断与错误模型(约 3–7 天)
|
||||
|
||||
### 目标
|
||||
|
||||
所有用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
树遍历与字节码**同文案、同位置粒度(至少语句级)**;金样例断言位置而不只子串。
|
||||
|
||||
### 工作项
|
||||
|
||||
1. **统一出口**
|
||||
- 解析侧尽量只产 `Diagnostic`(减少裸 `bail!("7:1: …")`)。
|
||||
- 字节码编译/VM:错误携带 `Span`(或指令 → 源行映射)。
|
||||
2. **位置粒度**
|
||||
- 短期:保持「语句起点」亦可;中期:为 `Expr`/`CallExpr` 补 `span`,让「未定义名」落在标识符上。
|
||||
3. **金样例**
|
||||
- `tests/errors/*`:断言完整 `path:line:col` 前缀(或相对路径规范化后的形式)。
|
||||
- 补:类型错误、除零、循环条件、capture 下 `input` 等。
|
||||
4. **文档**
|
||||
- 更新 [pipeline-debug.md](../design/pipeline-debug.md):错误码/严重级别可列为 P0.5(可选 `E0001` 一类,不阻塞)。
|
||||
|
||||
### 完成定义
|
||||
|
||||
- `cargo test`:errors 金样例含位置。
|
||||
- 同一 `.mq.md` 在 `--backend tree|bytecode` 下诊断一致(允许实现细节差异写进豁免表)。
|
||||
- view 执行失败区仍可读,路径无 `\\?\`。
|
||||
|
||||
### 刻意不做
|
||||
|
||||
- IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。
|
||||
|
||||
---
|
||||
|
||||
## 3. P1 — 输入(约 1–2 周)
|
||||
|
||||
分两轨:**CLI 必须先绿**;**view 交互后做**。
|
||||
|
||||
### P1a — CLI 完备(高优先级)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 树遍历 | 已实现 stdin;补 `tests/keywords/input.mq.md`(用管道喂入) |
|
||||
| 字节码 | 增加 `Op::Input`(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API |
|
||||
| 文档/用户站 | `public/keywords/input.mq.md`;说明「view 默认无交互 stdin」 |
|
||||
|
||||
完成定义:`echo Alice | marqdo run …` 与字节码后端输出一致;金样例稳定。
|
||||
|
||||
### P1b — view / 静态站中的输入(中优先级,接在 P1a 后)
|
||||
|
||||
当前 `run_file_capture` **不能**接真实 stdin——这是设计,不是偶然 bug。
|
||||
|
||||
推荐路径(由易到难):
|
||||
|
||||
1. **脚本化注入(无 UI)**
|
||||
- `marqdo run --stdin-file answers.txt` 或 frontmatter/`---` 旁测数据。
|
||||
- view:执行前提供「预置输入行」文本框,一次性灌入队列。
|
||||
2. **实时交互(live view)**
|
||||
- 执行到 `input` → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
|
||||
- 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
|
||||
3. **静态 `view output`**
|
||||
- 无服务器则只支持预置输入或跳过并标明 `input skipped`。
|
||||
|
||||
完成定义:live `marqdo view` 下至少一个带 `input` 的示例可点按跑通;静态导出行为有文档。
|
||||
|
||||
---
|
||||
|
||||
## 4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)
|
||||
|
||||
### 分层
|
||||
|
||||
```text
|
||||
L0 内置函数(解释器内) len / str / int / float? / type?
|
||||
L1 标准库模块(.mq.md) 文本、表/集合小工具;官方路径如 lib/ 或 std/
|
||||
L2 生态约定 catalog 收录;用户站专章
|
||||
```
|
||||
|
||||
### 建议落地顺序
|
||||
|
||||
| 迭代 | 内容 | 依据 |
|
||||
|------|------|------|
|
||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
||||
|
||||
### 完成定义(S0)
|
||||
|
||||
- 金样例 + 双后端;`public/` 有对应介绍页。
|
||||
- 不引入 `if`/`while` 英文关键字(控制流仍归 Markdown 标记)。
|
||||
|
||||
### 刻意不做(本阶段)
|
||||
|
||||
- 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。
|
||||
|
||||
---
|
||||
|
||||
## 5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)
|
||||
|
||||
**不要从 DAP/VS Code 插件开干。** view 已有 Structure / Source / Execution,是天然宿主。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
|
||||
Pause --> Sess[调试会话 API]
|
||||
Sess --> UI[view 断点与单步 UI]
|
||||
UI --> DAP[可选 DAP 适配]
|
||||
```
|
||||
|
||||
| 里程碑 | 交付 | 依赖 |
|
||||
|--------|------|------|
|
||||
| **D0** | 语句级源映射(树优先;字节码指令→行) | P0 |
|
||||
| **D1** | 运行时钩子:进入语句前可 pause;`--trace-eval` 结构化事件(JSON 行) | D0 |
|
||||
| **D2** | 进程内调试会话:设/清断点、continue、step over(先树遍历) | D1 |
|
||||
| **D3** | **view debug 模式**:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 | D2 + 少量 JS 或服务端推进 |
|
||||
| **D4** | 与 P1b 合流:`input` 暂停复用同一会话 | P1b |
|
||||
| **D5**(可选) | DAP 薄适配,供外部 IDE | D2 稳定后 |
|
||||
|
||||
### 完成定义(D3 即「可用调试」)
|
||||
|
||||
- 用户能在 `marqdo view` 对某 `.mq.md` 设断点、单步、看变量。
|
||||
- 文档站默认模式不变(一次执行);debug 为显式开关。
|
||||
- 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。
|
||||
|
||||
### 风险与边界
|
||||
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
||||
- 字节码调试可晚于树遍历一个迭代。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐排期(可执行流程)
|
||||
|
||||
按「每段都可合并、可演示」切周,避免大爆炸:
|
||||
|
||||
| 周序 | 主题 | 可合并交付 |
|
||||
|------|------|------------|
|
||||
| **W1** | P0 诊断统一 + errors 金样例加固 | 双后端错误位置一致 |
|
||||
| **W2** | P1a `input` 字节码 + 管道金样例 + 用户文档 | CLI 交互闭环 |
|
||||
| **W3** | P2-S0 `len`/`str`/`int` + 样例 | 「有点像语言」的第一批库 |
|
||||
| **W4** | P1b 预置输入(view 文本框 / `--stdin-file`) | view 可跑含 input 的 demo |
|
||||
| **W5–W6** | P3-D0–D2 暂停与会话 | 无 UI 也能用 API/CLI 单步 |
|
||||
| **W7–W8** | P3-D3 view 断点 UI + D4 与 input 暂停 | **调试机构**第一版 |
|
||||
| **并行/随后** | P2-S1/S2 扩库;P3-D5 DAP | 按反馈加 |
|
||||
|
||||
若人力紧:**砍掉顺序为 D5 → S2 花活 → 字节码调试**;**不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收总表(「真正可用」最低线)
|
||||
|
||||
1. **I/O**:CLI 上 `print`/`input` 双后端一致;view 至少支持预置或交互输入之一。
|
||||
2. **错误**:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
|
||||
3. **库**:至少 `len`/`str`/`int` 可用并有文档。
|
||||
4. **调试**:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
|
||||
5. **不破坏**:现有 `tests/` 金样例与 `public/` 用户站回归绿。
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档与工程动作(开工时)
|
||||
|
||||
1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 `doc/design/` 子设计(`input-interactive.md`、`stdlib.md`、`view-debug.md`)。
|
||||
2. 每个里程碑:金样例 → 实现 → `public/` 更新 →(若行为用户可见)再发版 / 刷 `gh-pages`。
|
||||
3. 版本建议:P1a+P0 可打 `v0.0.4`;P2-S0 打 `v0.0.5`;P3-D3 打 `v0.1.0`(「可用调试」语义升级)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话路线
|
||||
|
||||
**先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。**
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: ext/ai/agent
|
||||
description: Thin agent framework — ctor, run, clear_history only.
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
## build_agent_context
|
||||
+ `agent`
|
||||
+ `extra`
|
||||
|
||||
Internal: assemble prompt (user prompt, extra, tool list, source, call site, history, Marqdo skill).
|
||||
|
||||
*`user_prompt` = > get value=`agent` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = None*
|
||||
|
||||
*`tools` = > get value=`agent` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`agent` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# agent
|
||||
+ `model`
|
||||
+ `tools`
|
||||
+ `user_prompt`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"agent"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`model` *
|
||||
*`h` = > map_set map=`h` key=tools value=`tools` *
|
||||
|
||||
1. `user_prompt`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`user_prompt` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## clear_history
|
||||
|
||||
*`id` = > get value=`self` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## run
|
||||
+ `extra`
|
||||
|
||||
*`ctx` = > build_agent_context agent=`self` extra=`extra` *
|
||||
*`id` = > get value=`self` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`extra` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`reply` = > `model`.complete prompt=`ctx` *
|
||||
*`tools` = > get value=`self` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > call_fn name=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.complete prompt=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: ext/ai/llm
|
||||
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
|
||||
> lib/sys.mq.md
|
||||
> lib/net.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## load_env
|
||||
|
||||
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# llm
|
||||
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`).
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > env_get name=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > env_get name=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
|
||||
> exit code=1
|
||||
|
||||
*`base_url` = > env_get name=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > env_get name=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > env_get name=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > env_get name=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
|
||||
Chat completion using `self` / `自` handle fields.
|
||||
|
||||
*`api_key` = > get value=`self` key=api_key *
|
||||
*`base_url` = > get value=`self` key=base_url *
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`suffix` = > get value=`self` key=suffix *
|
||||
*`bearer` = > get value=`self` key=bearer *
|
||||
*`p1` = > get value=`self` key=p1 *
|
||||
*`p2` = > get value=`self` key=p2 *
|
||||
*`p3` = > get value=`self` key=p3 *
|
||||
*`h1` = > get value=`self` key=h1 *
|
||||
*`h2` = > get value=`self` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`prompt` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=`status`
|
||||
> print text=`raw`
|
||||
> exit code=1
|
||||
|
||||
---
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
|
||||
Alias for `complete`.
|
||||
|
||||
**> `self`.complete prompt=`prompt`**
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: ext/ai/大模型
|
||||
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
|
||||
> lib/系统.mq.md
|
||||
> lib/网络.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 加载环境
|
||||
|
||||
从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# 大模型
|
||||
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > 取环境 名=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > 取环境 名=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
|
||||
> 退出 码=1
|
||||
|
||||
*`base_url` = > 取环境 名=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > 取环境 名=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > 取环境 名=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
使用 `自` / `self` 句柄字段做聊天补全。
|
||||
|
||||
*`api_key` = > get value=`自` key=api_key *
|
||||
*`base_url` = > get value=`自` key=base_url *
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`suffix` = > get value=`自` key=suffix *
|
||||
*`bearer` = > get value=`自` key=bearer *
|
||||
*`p1` = > get value=`自` key=p1 *
|
||||
*`p2` = > get value=`自` key=p2 *
|
||||
*`p3` = > get value=`自` key=p3 *
|
||||
*`h1` = > get value=`自` key=h1 *
|
||||
*`h2` = > get value=`自` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`提示` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=`status`
|
||||
> 打印 内容=`raw`
|
||||
> 退出 码=1
|
||||
|
||||
---
|
||||
|
||||
## 聊天
|
||||
+ `提示`
|
||||
|
||||
`运行` 的别名。
|
||||
|
||||
**> `自`.运行 提示=`提示`**
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: ext/ai/智能体
|
||||
description: 薄智能体框架 — 仅构造、执行、清空历史。
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
## 构建上下文
|
||||
+ `智能体`
|
||||
+ `额外信息`
|
||||
|
||||
内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。
|
||||
|
||||
*`user_prompt` = > get value=`智能体` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = 空*
|
||||
|
||||
*`tools` = > get value=`智能体` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`智能体` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# 智能体
|
||||
+ `大模型`
|
||||
+ `工具`
|
||||
+ `用户提示信息`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"智能体"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`大模型` *
|
||||
*`h` = > map_set map=`h` key=tools value=`工具` *
|
||||
|
||||
1. `用户提示信息`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## 清空历史
|
||||
|
||||
*`id` = > get value=`自` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 执行
|
||||
+ `额外信息`
|
||||
|
||||
*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` *
|
||||
*`id` = > get value=`自` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
*`tools` = > get value=`自` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > 调用 名=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -0,0 +1,43 @@
|
||||
/* Marqdo plugin ABI v1 — C contract (source of truth).
|
||||
*
|
||||
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
|
||||
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
|
||||
*/
|
||||
#ifndef MARQDO_ABI_H
|
||||
#define MARQDO_ABI_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define MARQDO_ABI_VERSION 1u
|
||||
|
||||
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
|
||||
* On success: return 0, set *out_json to a heap string (host frees via free).
|
||||
* On failure: return non-zero; optional *err_msg heap string (host frees).
|
||||
* out_json / err_msg may be left NULL.
|
||||
*/
|
||||
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
|
||||
|
||||
typedef struct MarqdoHostApi {
|
||||
void *userdata;
|
||||
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
|
||||
int (*register_fn)(void *userdata, const char *name, const char *params,
|
||||
MarqdoPluginFn fn);
|
||||
void *(*alloc)(size_t n);
|
||||
void (*free)(void *p);
|
||||
} MarqdoHostApi;
|
||||
|
||||
/* Required exports from every plugin shared library. */
|
||||
uint32_t marqdo_plugin_abi_version(void);
|
||||
int marqdo_plugin_init(const MarqdoHostApi *host);
|
||||
void marqdo_plugin_shutdown(void);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* MARQDO_ABI_H */
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
---
|
||||
|
||||
## set_cmd
|
||||
+ `lang`
|
||||
+ `cmd`
|
||||
|
||||
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
|
||||
|
||||
## run
|
||||
+ `code`
|
||||
|
||||
**> host_foreign_run code=`code`**
|
||||
|
||||
## run_lang
|
||||
+ `lang`
|
||||
+ `source`
|
||||
|
||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
||||
|
||||
## langs
|
||||
|
||||
**> host_foreign_langs**
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: lib/fs
|
||||
description: English filesystem wrappers
|
||||
---
|
||||
|
||||
## read_text
|
||||
+ `path`
|
||||
|
||||
**> host_read_text path=`path`**
|
||||
|
||||
## write_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_write_text path=`path` text=`text`**
|
||||
|
||||
## append_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_append_text path=`path` text=`text`**
|
||||
|
||||
## exists
|
||||
+ `path`
|
||||
|
||||
**> host_exists path=`path`**
|
||||
|
||||
## list_dir
|
||||
+ `path`
|
||||
|
||||
**> host_list_dir path=`path`**
|
||||
|
||||
## make_dir
|
||||
+ `path`
|
||||
|
||||
**> host_make_dir path=`path`**
|
||||
|
||||
## remove
|
||||
+ `path`
|
||||
|
||||
**> host_remove path=`path`**
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: lib/json
|
||||
description: JSON parse/stringify (shared EN/ZH import)
|
||||
---
|
||||
|
||||
## parse
|
||||
+ `text`
|
||||
|
||||
**> host_json_parse text=`text`**
|
||||
|
||||
## stringify
|
||||
+ `value`
|
||||
|
||||
**> host_json_stringify value=`value`**
|
||||
|
||||
## get
|
||||
+ `value`
|
||||
+ `key`
|
||||
|
||||
**> host_json_get value=`value` key=`key`**
|
||||
|
||||
## keys
|
||||
+ `value`
|
||||
|
||||
**> host_json_keys value=`value`**
|
||||
|
||||
## quote
|
||||
+ `text`
|
||||
|
||||
**> host_json_quote text=`text`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
+200
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: lib/math
|
||||
description: High-school math — num, random, formula, plot
|
||||
---
|
||||
|
||||
## pi
|
||||
|
||||
**> host_pi**
|
||||
|
||||
## e
|
||||
|
||||
**> host_e**
|
||||
|
||||
## num
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
## add
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
## sub
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
## mul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
## div
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
## pow
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
## neg
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
## sin
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
## cos
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
## tan
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
## asin
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
## acos
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
## atan
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
## sqrt
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
## abs
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
## ln
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
## exp
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
## floor
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
## ceil
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
## min
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
## max
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
## random
|
||||
|
||||
**> host_random**
|
||||
|
||||
## random_int
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
## seed
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
## formula
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
## simplify
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
## expand
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
## diff
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
## subs
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## eval
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## solve
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
## plot
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## plot_points
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
## plot_conic
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: lib/net
|
||||
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
|
||||
---
|
||||
|
||||
## http_get
|
||||
+ `url`
|
||||
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
|
||||
**> host_http_get url=`url`**
|
||||
|
||||
## http_post
|
||||
+ `url`
|
||||
+ `body`
|
||||
|
||||
Default content type is JSON. Optional `content_type=` / `headers=` (map).
|
||||
|
||||
**> host_http_post url=`url` body=`body`**
|
||||
|
||||
## http_request
|
||||
+ `method`
|
||||
+ `url`
|
||||
|
||||
Optional `body=` / `content_type=` / `headers=`.
|
||||
|
||||
**> host_http_request method=`method` url=`url`**
|
||||
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
**> host_url_encode text=`text`**
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: lib/plugin
|
||||
description: Load optional native ABI plugins (.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## load
|
||||
+ `path`
|
||||
|
||||
**> host_plugin_load path=`path`**
|
||||
|
||||
## unload
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## list
|
||||
|
||||
**> host_plugin_list**
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: lib/subtask
|
||||
description: Concurrent subtasks — file, function, or foreign code
|
||||
---
|
||||
|
||||
## spawn
|
||||
+ `path`=None
|
||||
+ `fn`=None
|
||||
+ `args`=None
|
||||
+ `code`=None
|
||||
+ `lang`=None
|
||||
+ `source`=None
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
|
||||
|
||||
## poll
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## wait
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## kill
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## wait_all
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: lib/sys
|
||||
description: English system wrappers (load_dotenv accepts optional path via host alias)
|
||||
---
|
||||
|
||||
## env_get
|
||||
+ `name`
|
||||
|
||||
**> host_env_get name=`name`**
|
||||
|
||||
## env_set
|
||||
+ `name`
|
||||
+ `value`
|
||||
|
||||
**> host_env_set name=`name` value=`value`**
|
||||
|
||||
## load_dotenv
|
||||
|
||||
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## args
|
||||
|
||||
**> host_args**
|
||||
|
||||
## cwd
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
## exit
|
||||
+ `code`
|
||||
|
||||
**> host_exit code=`code`**
|
||||
|
||||
## exec
|
||||
+ `cmd`
|
||||
|
||||
**> host_exec cmd=`cmd`**
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: lib/table
|
||||
description: English table helpers over len / at
|
||||
---
|
||||
|
||||
## rows
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## row_at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: lib/text
|
||||
description: English text helpers over trim / split / join
|
||||
---
|
||||
|
||||
## str_trim
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
## str_split
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
## str_join
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: lib/time
|
||||
description: English time wrappers
|
||||
---
|
||||
|
||||
## now_unix
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
## now_ms
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
## format
|
||||
+ `unix`
|
||||
+ `pattern`
|
||||
|
||||
**> host_format_time unix=`unix` pattern=`pattern`**
|
||||
|
||||
## sleep_ms
|
||||
+ `ms`
|
||||
|
||||
**> host_sleep_ms ms=`ms`**
|
||||
|
||||
## parse
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_parse_time text=`text` pattern=`pattern`**
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: lib/writeback
|
||||
description: Persist run output in .mq.md (Jupyter-style writeback)
|
||||
---
|
||||
|
||||
## record
|
||||
+ `value`
|
||||
+ `at_end`=False
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF.
|
||||
|
||||
**> host_writeback_record value=`value` at_end=`at_end`**
|
||||
|
||||
## get
|
||||
+ `at_end`=False
|
||||
|
||||
Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`.
|
||||
|
||||
**> host_writeback_get at_end=`at_end`**
|
||||
|
||||
## clear
|
||||
+ `at_end`=False
|
||||
|
||||
Remove the adjacent or EOF output block.
|
||||
|
||||
**> host_writeback_clear at_end=`at_end`**
|
||||
|
||||
## list
|
||||
|
||||
List all output blocks in the entry file.
|
||||
|
||||
**> host_writeback_list**
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: lib/外联
|
||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
---
|
||||
|
||||
## 设置命令
|
||||
+ `语言`
|
||||
+ `命令`
|
||||
|
||||
**> host_foreign_set_cmd lang=`语言` cmd=`命令`**
|
||||
|
||||
## 运行
|
||||
+ `代码`
|
||||
|
||||
**> host_foreign_run code=`代码`**
|
||||
|
||||
## 按语言运行
|
||||
+ `语言`
|
||||
+ `源码`
|
||||
|
||||
**> host_foreign_run_lang lang=`语言` source=`源码`**
|
||||
|
||||
## 语言表
|
||||
|
||||
**> host_foreign_langs**
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: lib/子任务
|
||||
description: 并发子任务 — 文件、函数或外联代码
|
||||
---
|
||||
|
||||
## 启动
|
||||
+ `路径`=None
|
||||
+ `函数`=None
|
||||
+ `参数`=None
|
||||
+ `代码`=None
|
||||
+ `语言`=None
|
||||
+ `源码`=None
|
||||
+ `输入`=None
|
||||
|
||||
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
|
||||
|
||||
## 探测
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## 等待
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## 终止
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## 等待全部
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: lib/插件
|
||||
description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## 加载
|
||||
+ `路径`
|
||||
|
||||
**> host_plugin_load path=`路径`**
|
||||
|
||||
## 卸载
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_plugin_list**
|
||||
+200
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: lib/数学
|
||||
description: 高中数学 — 数值、随机、公式、作图
|
||||
---
|
||||
|
||||
## 圆周率
|
||||
|
||||
**> host_pi**
|
||||
|
||||
## 自然底数
|
||||
|
||||
**> host_e**
|
||||
|
||||
## 数
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
## 加
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
## 减
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
## 乘
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
## 除
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
## 幂
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
## 负
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
## 正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
## 余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
## 正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
## 反正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
## 反余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
## 反正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
## 平方根
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
## 绝对值
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
## 对数
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
## 指数
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
## 向下取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
## 向上取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
## 最小
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
## 最大
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
## 随机
|
||||
|
||||
**> host_random**
|
||||
|
||||
## 随机整数
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
## 设种子
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
## 公式
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
## 化简
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
## 展开
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
## 求导
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
## 代入
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## 求值
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## 求解
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
## 绘图
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## 绘点列
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
## 绘圆锥
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: lib/文件
|
||||
description: 中文文件系统包装
|
||||
---
|
||||
|
||||
## 读文本
|
||||
+ `路径`
|
||||
|
||||
**> host_read_text path=`路径`**
|
||||
|
||||
## 写文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_write_text path=`路径` text=`内容`**
|
||||
|
||||
## 追加文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_append_text path=`路径` text=`内容`**
|
||||
|
||||
## 存在
|
||||
+ `路径`
|
||||
|
||||
**> host_exists path=`路径`**
|
||||
|
||||
## 列目录
|
||||
+ `路径`
|
||||
|
||||
**> host_list_dir path=`路径`**
|
||||
|
||||
## 建目录
|
||||
+ `路径`
|
||||
|
||||
**> host_make_dir path=`路径`**
|
||||
|
||||
## 删除
|
||||
+ `路径`
|
||||
|
||||
**> host_remove path=`路径`**
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: lib/文本
|
||||
description: 中文文本库:去空白 / 拆分 / 拼接
|
||||
---
|
||||
|
||||
## 去空白
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
## 拆分
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
## 拼接
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: lib/时间
|
||||
description: 中文时间包装
|
||||
---
|
||||
|
||||
## 此刻秒
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
## 此刻毫秒
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
## 格式化
|
||||
+ `秒`
|
||||
+ `格式`
|
||||
|
||||
**> host_format_time unix=`秒` pattern=`格式`**
|
||||
|
||||
## 睡眠毫秒
|
||||
+ `毫秒`
|
||||
|
||||
**> host_sleep_ms ms=`毫秒`**
|
||||
|
||||
## 解析时间
|
||||
+ `内容`
|
||||
+ `格式`
|
||||
|
||||
**> host_parse_time text=`内容` pattern=`格式`**
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: lib/系统
|
||||
description: 中文系统包装(加载环境 可选 路径=)
|
||||
---
|
||||
|
||||
## 取环境
|
||||
+ `名`
|
||||
|
||||
**> host_env_get name=`名`**
|
||||
|
||||
## 设环境
|
||||
+ `名`
|
||||
+ `值`
|
||||
|
||||
**> host_env_set name=`名` value=`值`**
|
||||
|
||||
## 加载环境
|
||||
|
||||
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## 参数表
|
||||
|
||||
**> host_args**
|
||||
|
||||
## 工作目录
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
## 退出
|
||||
+ `码`
|
||||
|
||||
**> host_exit code=`码`**
|
||||
|
||||
## 执行
|
||||
+ `命令`
|
||||
|
||||
**> host_exec cmd=`命令`**
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: lib/网络
|
||||
description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。
|
||||
---
|
||||
|
||||
## 获取
|
||||
+ `地址`
|
||||
|
||||
支持 HTTPS。可选具名实参 `headers=`(映射)。
|
||||
|
||||
**> host_http_get url=`地址`**
|
||||
|
||||
## 提交
|
||||
+ `地址`
|
||||
+ `内容`
|
||||
|
||||
默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_post url=`地址` body=`内容`**
|
||||
|
||||
## 请求
|
||||
+ `方法`
|
||||
+ `地址`
|
||||
|
||||
可选 `body=` / `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_request method=`方法` url=`地址`**
|
||||
|
||||
## 编码地址
|
||||
+ `内容`
|
||||
|
||||
**> host_url_encode text=`内容`**
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: lib/自写回
|
||||
description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
---
|
||||
|
||||
## 写回
|
||||
+ `值`
|
||||
+ `末尾`=False
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。
|
||||
|
||||
**> host_writeback_record value=`值` at_end=`末尾`**
|
||||
|
||||
## 取
|
||||
+ `末尾`=False
|
||||
|
||||
读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。
|
||||
|
||||
**> host_writeback_get at_end=`末尾`**
|
||||
|
||||
## 清除
|
||||
+ `末尾`=False
|
||||
|
||||
删除紧邻块或末尾块。
|
||||
|
||||
**> host_writeback_clear at_end=`末尾`**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_writeback_list**
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: lib/表
|
||||
description: 中文表库:行数 / 取行
|
||||
---
|
||||
|
||||
## 行数
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## 取行
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: 人工文档
|
||||
description: 这是人工写的文档,禁止机器修改
|
||||
---
|
||||
|
||||
对于marqdo这个项目,详细的语法定义为:
|
||||
---
|
||||
|
||||
#标识对象,#main不算特殊这是一个项目的传统入口可以视为是一个对象。
|
||||
---
|
||||
##、### 、####等标识函数,不同数目表示从属关系,例如###是##函数的子函数,作用域不超过
|
||||
这个函数,使用-表示函数的变量名
|
||||
**** 空返回(None),并结束本函数体
|
||||
---
|
||||
无标记行表示注释信息,对于无标记行应该这么约定不是说开头没有符合不然就会出现:
|
||||
|
||||
**强调信息**是什么什么
|
||||
|
||||
上面应该是一个注释
|
||||
---
|
||||
程序语言使用*程序*也就是斜体表示
|
||||
---
|
||||
`变量名`表示变量
|
||||
---
|
||||
> 表示引用函数
|
||||
---
|
||||
有序列表表示分支语句
|
||||
---
|
||||
无序列表表示循环语句
|
||||
---
|
||||
公式由数学库渲染
|
||||
---
|
||||
代码片段由外联库渲染
|
||||
---
|
||||
添加一个新的标准库,自写回标准库,自写回的内容必须使用<!---->包裹,这个不会被md识别,
|
||||
但是这个可以被marqdo识别,当作提示信息或生成结果的一律表示,markdo view要能渲染,以某种方式
|
||||
---
|
||||
添加一个新的标准库,子任务库,能够自由的运行子任务,现在的调用还是顺序化的,但是子任务允许多个
|
||||
进程式的调用,子任务库将成为marqdo的护城河项目,子任务要依赖于父任务,父任务结束子任务一定结束,防止出现问题
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这是人工构建的用于测试的样例
|
||||
|
||||
`测试目录` =
|
||||
|测试文件夹|
|
||||
|-----|
|
||||
|structure|
|
||||
|keyword|
|
||||
|lib|
|
||||
|
||||
|
||||
- [`测试文件夹`](`测试目录`)
|
||||
> 打印 `测试文件夹`
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
1. `a` and not `b`
|
||||
> print text=ok
|
||||
2. *
|
||||
> print text=fail
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输入
|
||||
|
||||
*`name`=> input "你叫什么名字\n"*
|
||||
|
||||
> print `name`
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输出
|
||||
|
||||
> print 欢迎你
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 + 2
|
||||
$$
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`ty` = > type `f` *
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> print text=`df`
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`y` = > eval formula=`f` var=x value=3 *
|
||||
|
||||
> print text=`y`
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试写回库
|
||||
|
||||
*`name`=>input "你叫什么名字?\n"*
|
||||
|
||||
> record `name`
|
||||
<!-- marqdo-out
|
||||
123132
|
||||
-->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试分支语句
|
||||
|
||||
* `bool_value` = True *
|
||||
|
||||
1. `bool_value` == True
|
||||
> print True
|
||||
2. *
|
||||
> print False
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试循环语句语句
|
||||
|
||||
*`n`=0*
|
||||
|
||||
- `n` < 42
|
||||
`n`=`n`+1
|
||||
|
||||
> print `n`
|
||||
@@ -0,0 +1,14 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo agent layout plugin (ABI v1 cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "agent"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,574 @@
|
||||
//! Agent layout plugin (C ABI v1): find_root, ensure_layout, probe, scaffold.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json";
|
||||
const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"];
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<serde_json::Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Err("null args".into());
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
|
||||
v.get(key)
|
||||
.and_then(|x| x.as_str())
|
||||
.ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
fn has_parent_escape(rel: &Path) -> bool {
|
||||
rel.components().any(|c| matches!(c, Component::ParentDir))
|
||||
}
|
||||
|
||||
fn find_root(start: &str, markers: &str) -> Result<PathBuf, String> {
|
||||
let markers: Vec<&str> = markers
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.collect();
|
||||
if markers.is_empty() {
|
||||
return Err("empty markers".into());
|
||||
}
|
||||
let mut cur = PathBuf::from(start);
|
||||
if cur.as_os_str().is_empty() {
|
||||
cur = std::env::current_dir().map_err(|e| e.to_string())?;
|
||||
}
|
||||
if !cur.exists() {
|
||||
return Err(format!("start path missing: {}", cur.display()));
|
||||
}
|
||||
let mut cur = std::fs::canonicalize(&cur).map_err(|e| e.to_string())?;
|
||||
loop {
|
||||
for m in &markers {
|
||||
let p = cur.join(m);
|
||||
let ok = if m.contains('.') {
|
||||
p.is_file()
|
||||
} else {
|
||||
p.is_dir()
|
||||
};
|
||||
if ok {
|
||||
return Ok(cur);
|
||||
}
|
||||
}
|
||||
if !cur.pop() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
Err("agent project root not found".into())
|
||||
}
|
||||
|
||||
fn ensure_layout(root: &Path) -> Result<i64, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut created = 0i64;
|
||||
for d in LAYOUT_DIRS {
|
||||
let p = root.join(d);
|
||||
if !p.exists() {
|
||||
std::fs::create_dir_all(&p).map_err(|e| e.to_string())?;
|
||||
created += 1;
|
||||
} else if !p.is_dir() {
|
||||
return Err(format!("{} exists and is not a directory", p.display()));
|
||||
}
|
||||
}
|
||||
Ok(created)
|
||||
}
|
||||
|
||||
fn probe(root: &Path) -> Result<serde_json::Value, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut map = serde_json::Map::new();
|
||||
map.insert(
|
||||
"root".into(),
|
||||
serde_json::Value::String(root.to_string_lossy().into_owned()),
|
||||
);
|
||||
for d in LAYOUT_DIRS {
|
||||
let key = format!("has_{d}");
|
||||
map.insert(key, serde_json::Value::Bool(root.join(d).is_dir()));
|
||||
}
|
||||
Ok(serde_json::Value::Object(map))
|
||||
}
|
||||
|
||||
fn scaffold(root: &Path, name: &str, template: &str, dest: &str) -> Result<String, String> {
|
||||
if name.is_empty() {
|
||||
return Err("name is empty".into());
|
||||
}
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let tmpl_rel = Path::new(template);
|
||||
let dest_rel = Path::new(dest);
|
||||
if has_parent_escape(tmpl_rel) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
if has_parent_escape(dest_rel) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
let tmpl_path = root.join(tmpl_rel);
|
||||
if !tmpl_path.is_file() {
|
||||
return Err(format!("template not found: {}", tmpl_path.display()));
|
||||
}
|
||||
let tmpl_can = std::fs::canonicalize(&tmpl_path).map_err(|e| e.to_string())?;
|
||||
if !tmpl_can.starts_with(&root) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
let dest_path = root.join(dest_rel);
|
||||
if let Some(parent) = dest_path.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
|
||||
let parent_can = std::fs::canonicalize(parent).map_err(|e| e.to_string())?;
|
||||
if !parent_can.starts_with(&root) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
}
|
||||
let body = std::fs::read_to_string(&tmpl_can).map_err(|e| e.to_string())?;
|
||||
let body = body.replace("{{name}}", name);
|
||||
std::fs::write(&dest_path, body).map_err(|e| e.to_string())?;
|
||||
Ok(dest_path.to_string_lossy().into_owned())
|
||||
}
|
||||
|
||||
fn map_get_str<'a>(m: &'a serde_json::Value, keys: &[&str]) -> Option<&'a str> {
|
||||
let obj = m.as_object()?;
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(s) = v.as_str() {
|
||||
return Some(s);
|
||||
}
|
||||
if let Some(n) = v.as_i64() {
|
||||
// allow numeric fields to be read as display later
|
||||
let _ = n;
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn map_get_i64(m: &serde_json::Value, keys: &[&str]) -> i64 {
|
||||
let Some(obj) = m.as_object() else {
|
||||
return i64::MAX;
|
||||
};
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(n) = v.as_i64() {
|
||||
return n;
|
||||
}
|
||||
if let Some(s) = v.as_str() {
|
||||
if let Ok(n) = s.parse::<i64>() {
|
||||
return n;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
i64::MAX
|
||||
}
|
||||
|
||||
fn skills_text(m: &serde_json::Value) -> String {
|
||||
map_get_str(m, &["技能", "skills", "skill"])
|
||||
.unwrap_or("")
|
||||
.to_string()
|
||||
}
|
||||
|
||||
fn match_skill(skill: &str, members: &serde_json::Value) -> Result<serde_json::Value, String> {
|
||||
let arr = members
|
||||
.as_array()
|
||||
.ok_or_else(|| "members must be a JSON array".to_string())?;
|
||||
let skill = skill.trim();
|
||||
if skill.is_empty() {
|
||||
return Err("skill is empty".into());
|
||||
}
|
||||
let mut best: Option<&serde_json::Value> = None;
|
||||
let mut best_load = i64::MAX;
|
||||
for m in arr {
|
||||
let sk = skills_text(m);
|
||||
if sk.split(',').any(|p| p.trim() == skill) || sk.contains(skill) {
|
||||
let load = map_get_i64(m, &["负载", "load"]);
|
||||
if load < best_load {
|
||||
best_load = load;
|
||||
best = Some(m);
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(best.cloned().unwrap_or(serde_json::Value::Null))
|
||||
}
|
||||
|
||||
fn bump_load(member: &serde_json::Value, delta: i64) -> Result<serde_json::Value, String> {
|
||||
let mut obj = member
|
||||
.as_object()
|
||||
.cloned()
|
||||
.ok_or_else(|| "member must be a JSON object".to_string())?;
|
||||
let key = if obj.contains_key("负载") {
|
||||
"负载"
|
||||
} else if obj.contains_key("load") {
|
||||
"load"
|
||||
} else {
|
||||
obj.insert("负载".into(), serde_json::Value::Number(0.into()));
|
||||
"负载"
|
||||
};
|
||||
let cur = match obj.get(key) {
|
||||
Some(serde_json::Value::Number(n)) => n.as_i64().unwrap_or(0),
|
||||
Some(serde_json::Value::String(s)) => s.parse().unwrap_or(0),
|
||||
_ => 0,
|
||||
};
|
||||
obj.insert(
|
||||
key.into(),
|
||||
serde_json::Value::Number((cur + delta).into()),
|
||||
);
|
||||
Ok(serde_json::Value::Object(obj))
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_find_root(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let start = match arg_str(&v, "start") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let markers = v
|
||||
.get("markers")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.unwrap_or(DEFAULT_MARKERS);
|
||||
match find_root(start, markers) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p.to_string_lossy().into_owned()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_ensure_layout(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match ensure_layout(Path::new(root)) {
|
||||
Ok(n) => {
|
||||
set_out(out_json, &n.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_probe(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match probe(Path::new(root)) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_scaffold(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let name = match arg_str(&v, "name") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let template = match arg_str(&v, "template") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let dest = match arg_str(&v, "dest") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match scaffold(Path::new(root), name, template, dest) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_match_skill(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let skill = match arg_str(&v, "skill") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let members = match v.get("members") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_match_skill: missing members");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
// members may be a JSON string (from Marqdo stringify) or already an array
|
||||
let members = if let Some(s) = members.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: members JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
members
|
||||
};
|
||||
match match_skill(skill, &members) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_bump_load(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = match v.get("member") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_bump_load: missing member");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = if let Some(s) = member.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: member JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
member
|
||||
};
|
||||
let delta = v.get("delta").and_then(|x| x.as_i64()).unwrap_or(1);
|
||||
match bump_load(&member, delta) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_ensure_layout", "root", agent_ensure_layout) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_probe", "root", agent_probe) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_scaffold",
|
||||
"root,name,template,dest",
|
||||
agent_scaffold,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_match_skill", "skill,members", agent_match_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 {
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Demo Marqdo ABI v1 plugin (cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "demo"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,170 @@
|
||||
//! Demo Marqdo plugin (C ABI v1). Registers `demo_add` and `demo_echo`.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_add(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_add: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_add: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_add: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let a = v.get("a").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
let b = v.get("b").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
set_out(out_json, &(a + b).to_string());
|
||||
0
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_echo(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_echo: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_echo: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_echo: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let text = v
|
||||
.get("text")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("");
|
||||
let out = serde_json::Value::String(text.to_string()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let name_add = CString::new("demo_add").unwrap();
|
||||
let params_add = CString::new("a,b").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_add.as_ptr(),
|
||||
params_add.as_ptr(),
|
||||
demo_add,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
let name_echo = CString::new("demo_echo").unwrap();
|
||||
let params_echo = CString::new("text").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_echo.as_ptr(),
|
||||
params_echo.as_ptr(),
|
||||
demo_echo,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
+39
-15
@@ -1,31 +1,55 @@
|
||||
---
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档
|
||||
title: Welcome to Marqdo
|
||||
description: User docs home — code is documentation (English)
|
||||
> lib/math.mq.md
|
||||
> lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是marqdo的开发者,很高兴你看到这个网站,marqdo是一个代码即文档的编程语言,作者想要做这个项目来源于一个小小的想法,AI输出的首选语言是markdown,为什么不能基于markdown创建一个新式的编程语言,不再区分文档和代码,代码写出来就是一份文档,文档也是代码(这个项目的野心实际更大些,项目立项之处就调研了谷歌OKF规范,计划自动生成YAML使得代码和文档能够自动的变成知识库,与此同时还有更多可能,例如规范化生成的PPT)。
|
||||
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where **code is documentation, and documentation is code**: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
所以marqdo产生了,为了确保我们的新语言能够百分百被markdown渲染,这门语言甚至采用了`.mq.md`的双层嵌套后缀,所以不需要有压力使用这门语言,就算出现了巨大的问题,就当让ai写文档好了,如果成功了,试想这样一种场景,你不再需要让ai生成代码的文档,ai写的代码能够便捷的被你读懂,至少能省点token,毕竟烧了太多,钱包容易饿瘦。
|
||||
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
|
||||
|
||||
这门语言还是起步阶段,目前计划是制作一个解释型的语言,现在的marqdo支持一些特定的语法结构和关键字,并且允许自由的输出调试信息,以及直接通过前端预览各个代码块,生成静态文件,是的,没错,这个网站就是marqdo制作的,至少我相信marqdo会成为一个博客工具。
|
||||
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
除了部分内置的关键字,marqdo并不限制必须使用英文编程,当然这并不意味着我要开发一个中文编程系统,事实上,这是由于文档即代码、代码即文档的结构决定的,如果只支持英文,那还有什么作用?还要掌握一门语言,这并不是让人愉悦的阅读体验,所以marqdo会长期支持多语言编程的可能。
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
欢迎各位加入开源库,共同建设和完成这个项目[marqdo的github仓库链接](https://github.com/cflmy/marqdo)
|
||||
A small function to say hello:
|
||||
|
||||
最后,引用所有程序员的开始欢迎各位:
|
||||
> greet who=marqdo
|
||||
|
||||
> 问候 marqdo
|
||||
Named args can include spaces:
|
||||
|
||||
如果你是一个敏锐的程序员应该会察觉到一个小问题,这个问题的解决方案是像下面这样的,我其实并不知道这样解决是否正确,但是我暂且放在这里,欢迎你,敏锐的程序元朋友。
|
||||
> greet who=marqdo user
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=欢迎,`谁`!
|
||||
> print text=Welcome, `who`!
|
||||
|
||||
---
|
||||
|
||||
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
|
||||
|
||||
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it:
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
|
||||
The foreign library lets you call external code, for example:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档(中文版)
|
||||
> lib/数学.mq.md
|
||||
> lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门**代码即文档,文档即代码**的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
|
||||
|
||||
用一个小函数打个招呼:
|
||||
|
||||
> 问候 谁=marqdo
|
||||
|
||||
具名实参可以带空格:
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
|
||||
---
|
||||
|
||||
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
|
||||
|
||||
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
之后让我们画个图像吧!
|
||||
|
||||
*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 *
|
||||
|
||||
外联库则允许你调用外部代码,例如:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
|
||||
文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验marqdo吧!
|
||||
+12
-10
@@ -1,26 +1,28 @@
|
||||
# 用户文档(可执行 · 可下载)
|
||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
|
||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
||||
|
||||
| 路径 | 内容 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) | 首页 |
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与内置 `print` |
|
||||
| [`features/`](features/) | 特性迭代说明 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`,避免用户站出现红色执行失败。
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
开发文档(语言设计等)在 [`doc/`](../doc/),与本目录分离。
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
|
||||
开发文档在 [`doc/`](../doc/)。
|
||||
|
||||
## 浏览与生成 HTML
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
生成的 `index.html` 与 `pages/` 默认被 ignore;CI 构建后推到 `gh-pages`。详见 [user-site.md](../doc/design/user-site.md)。
|
||||
详见 [user-site.md](../doc/design/user-site.md)。
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: Phase I — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
title: Phase I — tree-walk interpreter
|
||||
description: Lex · parse · check · tree-walk end to end
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:Phase I(树遍历)。
|
||||
Milestone: Phase I (tree-walk).
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
|
||||
|
||||
本页本身即可运行,证明「文档即程序」在解释器里已落地:
|
||||
This page runs as a program — documentation is executable:
|
||||
|
||||
> print text=Phase I:tree-walk interpreter is live.
|
||||
> print text=Phase I: tree-walk interpreter is live.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 第一阶段 — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:第一阶段(树遍历)。
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
|
||||
本页本身即可运行,证明「文档即程序」已落地:
|
||||
|
||||
> 打印 内容=第一阶段:树遍历解释器已就绪。
|
||||
@@ -1,18 +1,18 @@
|
||||
---
|
||||
title: 字节码后端
|
||||
description: --backend bytecode 与树遍历共用语义
|
||||
title: Bytecode backend
|
||||
description: `--backend bytecode` shares semantics with tree-walk
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:字节码原型。
|
||||
Milestone: bytecode prototype.
|
||||
|
||||
同一套 .mq.md 可用树遍历或字节码 VM 执行。命令示例:
|
||||
The same `.mq.md` runs on tree-walk or the bytecode VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
下面这段在两种后端下输出一致:
|
||||
Output matches on both backends:
|
||||
|
||||
> print text=Bytecode backend:same program, alternate engine.
|
||||
> print text=Bytecode backend: same program, alternate engine.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 字节码后端
|
||||
description: `--backend bytecode` 与树遍历共用语义
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:字节码原型。
|
||||
|
||||
同一套 `.mq.md` 可用树遍历或字节码 VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
两种后端输出一致:
|
||||
|
||||
> 打印 内容=字节码后端:同一程序,另一引擎。
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
title: view and the user docs site
|
||||
description: Local browse and static export from the interpreter
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:marqdo view 与 view output。
|
||||
Milestone: `marqdo view` and `view output`.
|
||||
|
||||
本地浏览:marqdo view public
|
||||
Local: `marqdo view public`
|
||||
|
||||
静态导出:marqdo view output public -o public
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
用户可执行文档就在 public/;生成的 HTML(index.html / pages/)供静态托管,CI 发布到 gh-pages。
|
||||
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
|
||||
|
||||
> print text=Docs site:generated by the Marqdo interpreter, not hand-written HTML.
|
||||
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:`marqdo view` 与 `view output`。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
|
||||
|
||||
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Objects and methods
|
||||
description: Sharp heading is a type; deeper headings are functions or methods
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
|
||||
|
||||
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
|
||||
|
||||
> print text=objects-ok
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: 对象与方法
|
||||
description: 一级标题是类型;更深标题是函数或方法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。
|
||||
|
||||
详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。
|
||||
|
||||
> 打印 内容=对象就绪
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Official extensions (ext/)
|
||||
description: Optional packages — not stdlib
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
ext/ holds official optional extensions. They are not part of lib/. Resolve via MARQDO_EXT, ./ext, or ext/ next to the binary.
|
||||
|
||||
- ext/llm — OpenAI-compatible chat object. Design: doc/design/ext-llm.md
|
||||
- ext/agent — agent development framework (layout helpers today; compose with ext/llm for model-backed orchestration). Design: doc/design/ext-agent.md
|
||||
- Installer: marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
- Native plugins: lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
> print text=ext-ok
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 官方扩展(ext/)
|
||||
description: 可选包 — 不是标准库
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:MARQDO_EXT、./ext、或可执行文件旁的 ext/。
|
||||
|
||||
- ext/llm(ext/大模型)— OpenAI 兼容聊天。设计:doc/design/ext-llm.md
|
||||
- ext/agent(ext/智能体)— 智能体开发框架(当前含布局助手;与大模型组合做编排见路线)。设计:doc/design/ext-agent.md
|
||||
- 安装器:marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
- 通用原生插件:lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
> 打印 内容=扩展就绪
|
||||
@@ -1,23 +1,23 @@
|
||||
---
|
||||
title: 布尔与逻辑
|
||||
description: True / False / None 与 and / or / not
|
||||
title: Booleans and logic
|
||||
description: True / False / None and and / or / not
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
关键字:`True`、`False`、`None`,以及 `and` / `or` / `not`。
|
||||
Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
+ `a` and not `b`
|
||||
1. `a` and not `b`
|
||||
> print text=ok
|
||||
+ *
|
||||
2. *
|
||||
> print text=fail
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
+ None
|
||||
1. None
|
||||
> print text=none-truthy
|
||||
+ *
|
||||
2. *
|
||||
> print text=none-falsy
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Built-in input
|
||||
description: Read one line from stdin; optional prompt. Demo via frontmatter stdin.
|
||||
stdin: Ada
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
The input builtin reads one line. For demos and marqdo view / static export, put sample lines in frontmatter (stdin:). CLI can also use a pipe or --stdin-file. Live view can override with the Preset input box.
|
||||
|
||||
*`name` = > input prompt=Name: *
|
||||
|
||||
> print text=Hello `name`!
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: 内置 print
|
||||
description: 具名与位置两种写法
|
||||
title: Built-in print
|
||||
description: Named and positional forms
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
内置 print 接受具名或位置实参:
|
||||
The `print` builtin accepts named or positional arguments:
|
||||
|
||||
> print text=named form
|
||||
|
||||
> print positional
|
||||
|
||||
这里的设计思路是具名实参允许空格的传入,位置实参则不允许。
|
||||
Named args may contain spaces; positional args may not.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Built-ins len / str / int / type / trim / split / join / at
|
||||
description: Host builtins for strings and tables
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Length and type:
|
||||
|
||||
*`s` = hello*
|
||||
|
||||
*`n` = > len `s`*
|
||||
|
||||
> print text=`n`
|
||||
|
||||
*`ty` = > type `s`*
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
Trim, split, join, and index:
|
||||
|
||||
*`t` = > trim value= hi *
|
||||
|
||||
*`parts` = > split value=a,b sep=,*
|
||||
|
||||
*`mid` = > at value=`parts` index=0*
|
||||
|
||||
*`j` = > join value=`parts` sep=-*
|
||||
|
||||
> print text=`t`
|
||||
|
||||
> print text=`mid`
|
||||
|
||||
> print text=`j`
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 中英内核双名
|
||||
description: 无需导入:打印、长度、文本、整数 与 print / len / …
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
内核中英别名等价,可混用:
|
||||
|
||||
*`s` = 你好*
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
|
||||
> 打印 内容=`n`
|
||||
|
||||
> print text=also-english
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 布尔与逻辑
|
||||
description: 真 / 假 / 空 与 且 / 或 / 非
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
关键字:`真`、`假`、`空`,以及 `且` / `或` / `非`。
|
||||
|
||||
*`a` = 真*
|
||||
*`b` = 假*
|
||||
|
||||
1. `a` 且 非 `b`
|
||||
> 打印 内容=通过
|
||||
2. *
|
||||
> 打印 内容=失败
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
1. 空
|
||||
> 打印 内容=空为真
|
||||
2. *
|
||||
> 打印 内容=空为假
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 内置 打印
|
||||
description: 具名与位置两种写法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
内置 `打印` 接受具名或位置实参:
|
||||
|
||||
> 打印 内容=具名写法
|
||||
|
||||
> 打印 位置写法
|
||||
|
||||
具名实参可以带空格;位置实参不可以。
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: 内置 长度 / 文本 / 整数 与 trim 等
|
||||
description: 主机内置;中文别名覆盖常用几个
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
长度与英文 `type`(类型无中文内核别名,见标准库文档):
|
||||
|
||||
*`s` = 你好*
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
|
||||
> 打印 内容=`n`
|
||||
|
||||
*`ty` = > type `s`*
|
||||
|
||||
> 打印 内容=`ty`
|
||||
|
||||
去空白、拆分、拼接、按下标(主机名仍为英文):
|
||||
|
||||
*`t` = > trim value= 嗨 *
|
||||
|
||||
*`parts` = > split value=甲,乙 sep=,*
|
||||
|
||||
*`mid` = > at value=`parts` index=0*
|
||||
|
||||
*`j` = > join value=`parts` sep=-*
|
||||
|
||||
> 打印 内容=`t`
|
||||
|
||||
> 打印 内容=`mid`
|
||||
|
||||
> 打印 内容=`j`
|
||||
Loaded 100 of 250 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user