Compare commits

..
Author SHA1 Message Date
cflmy 1c6fea84d4 vscode-extension: bump to 2.8.0 for release 2026-11-18 10:55:39 +08:00
cflmy 5c79902f70 vscode-extension: bump to 2.7.1 for release 2026-11-11 00:26:52 +08:00
cflmy 2e5308e044 vscode-extension: bump to 2.7.0 for release 2026-11-10 16:45:51 +08:00
cflmy 78b427b667 vscode-extension: bump to 2.6.0 for release 2026-11-08 23:36:03 +08:00
cflmy 7faaac2aea vscode-extension: bump to 2.5.1 for release 2026-11-07 13:07:07 +08:00
cflmy c7011cc32e vscode-extension: bump to 2.5.0 for release 2026-11-07 10:06:02 +08:00
cflmyandCursor 14a2470a12 vscode-extension: bump to 2.4.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-06 15:10:41 +08:00
cflmyandCursor 4c7f41151a vscode-extension: bump to 2.3.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 14:48:50 +08:00
cflmyandCursor 02e8c21118 vscode-extension: bump to 2.2.2 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 09:44:23 +08:00
cflmyandCursor b06a832472 vscode-extension: bump to 2.2.1 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 11:42:04 +08:00
cflmyandCursor 25f970db7e vscode-extension: bump to 2.2.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 09:08:55 +08:00
cflmyandCursor 44569ec26c vscode-extension: bump to 2.1.5 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 15:40:52 +08:00
cflmyandCursor 70de478857 vscode-extension: bump to 2.1.4 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 18:33:58 +08:00
cflmyandCursor a6987f8877 vscode-extension: bump to 2.1.3 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 23:13:49 +08:00
cflmyandCursor 2e9342b5fa vscode-extension: bump to 2.1.2 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-24 22:52:30 +08:00
cflmyandCursor 9e7c8aafbd vscode-extension: bump to 2.1.1 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:41:50 +08:00
cflmy 76213ccf0b vscode-extension: bump to 2.1.0 for release 2026-10-23 13:02:04 +00:00
cflmy dcedfdadff vscode-extension: bump to 2.0.0 for release 2026-10-22 16:28:46 +08:00
cflmy 7597184909 vscode-extension: bump to 1.5.2 for release 2026-10-18 14:57:45 +08:00
cflmy 3955ae8eca vscode-extension: bump to 1.5.1 for release 2026-10-18 14:05:52 +08:00
cflmy 8598edb535 vscode-extension: bump to 1.5.0 for release 2026-10-18 03:18:14 +08:00
cflmyandCursor 568fa4f2bf vscode-extension: bump to 1.4.6 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 23:59:25 +08:00
cflmyandCursor 95a6375558 vscode-extension: bump to 1.4.5 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 17:37:21 +08:00
cflmyandCursor 8fe8d51289 vscode-extension: bump to 1.4.4 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 14:38:41 +08:00
cflmyandCursor 86a9513e51 vscode-extension: bump to 1.4.2 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:52:02 +08:00
cflmyandCursor 9325cf327d vscode-extension: bump to 1.4.1 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:37:46 +08:00
cflmyandCursor e455235218 vscode-extension: bump to 1.4.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:55:07 +08:00
cflmyandCursor dd025016c3 vscode-extension: bump to 1.3.3 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:19:09 +08:00
cflmyandCursor 31da360274 vscode-extension: bump to 1.3.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 16:46:48 +08:00
cflmyandCursor 0ac3b2ab27 vscode-extension: bump to 1.2.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:39:46 +08:00
cflmyandCursor 82ef21e816 vscode-extension: bump to 1.1.1 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:34:49 +08:00
cflmyandCursor 00e25c1f69 vscode-extension: bump to 1.1.0 (sync with CLI)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:35:07 +08:00
cflmyandCursor f274a48f60 vscode-extension: bump to 1.0.7 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:44:38 +08:00
cflmyandCursor f75d34f64a vscode-extension: bump to 1.0.3 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:20:53 +08:00
cflmyandCursor 2e10987982 vscode-extension: bump to 1.0.2 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-16 21:06:23 +08:00
cflmyandCursor c96a2de94c vscode-extension: bump to 1.0.1 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 14:50:47 +08:00
cflmyandCursor fd2254b2a8 vscode-extension: bump to 1.0.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 16:06:48 +08:00
cflmyandCursor db300977c2 vscode-extension: bump to 0.4.0 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 15:10:21 +08:00
cflmy f583062b4b chore(ext): bump VS Code extension to 0.3.9 2026-09-09 15:26:27 +08:00
cflmyandCursor 84afb6bcb8 chore(ext): bump VS Code extension to 0.3.8
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 10:15:42 +08:00
cflmyandCursor e8e11cffce vscode-extension: bump to 0.3.7 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 22:23:02 +08:00
cflmyandCursor d180b949f4 vscode-extension: bump to 0.3.6 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:56:08 +08:00
cflmy 4a546d17bc vscode-extension: bump to 0.3.5 for release 2026-09-04 17:13:46 +08:00
cflmyandCursor 12569f0afd vscode-extension: bump to 0.3.4 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 14:28:19 +08:00
cflmyandCursor 155bed4ce9 vscode-extension: bump to 0.3.3 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 10:27:32 +08:00
cflmyandCursor 78af67d1e0 vscode-extension: bump to 0.3.2 for release
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:20:08 +08:00
cflmyandCursor 9361992d11 vscode-extension v0.0.6: v0.2 grammar, embedded stdlib detection, update check.
Min CLI 0.1.2. See main doc/design/vscode-extension-commit.md for branch workflow.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 09:38:17 +08:00
cflmyandCursor d1b75d88c5 Polish VS Code extension: three toolbar actions and CLI checks.
Add Run/View/Debug title icons, logo cover art, version/stdlib install prompts, and LiveServer for view + debug hosts.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 17:13:58 +08:00
cflmyandCursor 3887205ebb Add Marqdo VS Code run/debug, diagnostics, and CLI auto-install.
Ship TextMate highlighting, Run/Problems/debug entry, GitHub release CLI+stdlib bootstrap, and packaging metadata for the published .vsix.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:57:49 +08:00
cflmyandCursor f4f798a4d0 Bootstrap VS Code extension workspace and development norms.
Add Marqdo language registration, TextMate grammar stub, and docs for the vscode-extension branch workflow.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:26:33 +08:00
385 changed files with 7164 additions and 36792 deletions

No files matched your search

-170
View File
@@ -1,170 +0,0 @@
---
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` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are variables (strings need `"…"` / `'…'`; ticks still ok).
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. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`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` [`as` / `作为` name] | Import (binds library name) |
| Frontmatter `> use lib.member` [`as` name] / `使用` | Bind short name to a library path |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | 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 (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
| `` ```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
Imports bind a **library name** (default = file stem; optional `as` / `作为`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
> lib/text.mq.md
> lib/time.mq.md as clock
---
# main
*`xs` = > text.split value=a,b,c sep=,*
> print text=`xs`
*`t` = > clock.now_unix *
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- 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` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- 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 bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
## 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)
-234
View File
@@ -1,234 +0,0 @@
# 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=`果`
```
## 6b. Map table + footnote get
```markdown
# main
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
*`种` = 分类[^苹果] *
> print text=`种`
*`第一` = 篮子[^1] *
```
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
*`名` = `订单`[^1][^品名] *
```
## 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` / `自`.
## 10b. Object inheritance
```markdown
# Greeter
## hello
+ `who`
*`msg` = "Hello, `who`!" *
**`msg`**
# Loud = > Greeter
## hello
+ `who`
*`msg` = "HELLO, `who`!" *
**`msg`**
```
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
```markdown
# Child = > Parent
+ `name`
*`self` = > Parent name=`name` *
*`self` = > json.set map=`self` key=extra value=1 *
**`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
> print text=pos
2. *
> print text=other
# GOOD — another independent branch (restart at 1.)
1. `y` > 0
> print text=y-pos
2. *
> print text=y-other
```
-135
View File
@@ -1,135 +0,0 @@
# 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. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). 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` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
| `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 |
+5 -61
View File
@@ -14,34 +14,13 @@ jobs:
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")
New-Item -ItemType Directory -Force -Path dist | Out-Null
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: |
@@ -51,20 +30,7 @@ jobs:
$exe = "marqdo-$ver-$target.exe"
$zip = "marqdo-$ver-$target.zip"
$stdlib = "marqdo-$ver-stdlib.zip"
$source = "marqdo-$ver-source.zip"
$vsix = "marqdo-$ver.vsix"
$public = "marqdo-$ver-public.zip"
$extZip = "marqdo-$ver-ext.zip"
Copy-Item target/release/marqdo.exe "dist/$exe"
git archive --format=zip -o "dist/$source" HEAD
./target/release/marqdo view output public -o public
Compress-Archive -Path public/* -DestinationPath "dist/$public" -Force
$stageExt = "dist/stage-ext"
if (Test-Path $stageExt) { Remove-Item $stageExt -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stageExt | Out-Null
Copy-Item ext "$stageExt/ext" -Recurse
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
@@ -81,46 +47,24 @@ jobs:
echo "EXE=$exe" >> $env:GITHUB_ENV
echo "ZIP=$zip" >> $env:GITHUB_ENV
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
echo "VSIX=$vsix" >> $env:GITHUB_ENV
echo "SOURCE=$source" >> $env:GITHUB_ENV
echo "PUBLIC=$public" >> $env:GITHUB_ENV
echo "EXT=$extZip" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Marqdo ${{ github.ref_name }}
### Highlights — extension libraries
- Official **`ext/`** packages: `llm`, `agent`, `web`, `quantum` (not stdlib)
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/ext-cli.md)
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
### Downloads
## 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-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
| `marqdo-*.vsix` | VS Code / Cursor extension |
| `marqdo-*-public.zip` | Static user docs site |
| `marqdo-*-windows-msvc.exe` | **Executable only** — does **not** include the standard library |
| `marqdo-*-windows-msvc.zip` | **Recommended**: `marqdo.exe` + `lib/` (keep them together) |
| `marqdo-*-stdlib.zip` | Standard library only — unpack next to the exe, or set `MARQDO_LIB` |
Extension workflow: [vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
> The standalone `.exe` does **not** ship `lib/`. Use the bundle zip or stdlib zip for `lib/…` imports.
files: |
dist/${{ env.EXE }}
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
dist/${{ env.EXT }}
dist/${{ env.VSIX }}
dist/${{ env.SOURCE }}
dist/${{ env.PUBLIC }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+3 -32
View File
@@ -1,36 +1,17 @@
/target/
/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/
# Editor settings at repo root only (keep vscode-extension/.vscode for F5)
/.vscode/
*.pdb
.DS_Store
.marqdo/
**/.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/
@@ -38,13 +19,3 @@ spike/__pycache__/
spike/.pytest_cache/
**/__pycache__/
*.pyc
# Local sqlite / scratch
/data/
/tmp/
plugins/*/tmp/
# web smoke/example DBs (cwd-relative or fixture data dirs)
/web-fixtures/
/tests/ext/web-fixtures/data/
/examples/web-site/data/
/examples/web-site-zh/data/
-80
View File
@@ -1,80 +0,0 @@
# Changelog
## v0.2.0 — 2026-08-12
### Highlights — official extension libraries
This release centers on **`ext/`**: optional packages that are **not** part of the embedded stdlib. Install them with the CLI; native plugins (`.so` / `.dll`) ship beside L1 Markdown APIs.
**How to get extensions**
```bash
# List what the installer knows about
marqdo ext list
# Install from the repo's ./ext (or MARQDO_EXT_SOURCE), into ~/.marqdo/ext (or MARQDO_EXT)
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
# Chinese ids work the same (大模型 / 智能体 / 网页 / 量子)
marqdo ext add 量子
marqdo ext remove quantum
```
Native plugins (agent / web / quantum) must be built once, then `ext add` copies them into `MARQDO_EXT/native/`:
```bash
cargo build --release -p marqdo_plugin_agent
cargo build --release -p marqdo_plugin_web
cargo build --release -p marqdo_plugin_quantum
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
```
Runtime also resolves plugins from `CARGO_TARGET_DIR`, `target/`, next to the `marqdo` binary, or `MARQDO_*_PLUGIN` env vars. Design: [ext-cli.md](doc/design/ext-cli.md) · [ext-abi.md](doc/design/ext-abi.md).
| Package | What you get |
|---------|----------------|
| **llm** | OpenAI-compatible chat — [ext-llm.md](doc/design/ext-llm.md) |
| **agent** | Agent layout / orchestration helpers + native plugin — [ext-agent.md](doc/design/ext-agent.md) |
| **web** | HTTP + SQLite site helpers + native plugin — [ext-web.md](doc/design/ext-web.md) |
| **quantum** | State-vector circuits, draw, noise, formula `matrix=` custom gates — [ext-quantum.md](doc/design/ext-quantum.md) |
User-facing intro: [`public/features/05-extensions.mq.md`](public/features/05-extensions.mq.md) / [`05-扩展.mq.md`](public/features/05-扩展.mq.md).
### Added
- Full **ext CLI** catalog: `llm`, `agent`, `web`, `quantum` (EN/ZH ids).
- **Quantum (Q0–Q6)**: gates, `run`/`steps`, draw (circuit/probs/bloch), heatmaps, teaching noise incl. amplitude damping, **custom gates from `$$` / `matrix=`**.
- **Web** extension (listen / render / SQLite) with L1 EN/ZH.
- **Agent** native plugin path + installer copy into `native/`.
- View **Variables** panel: previews + click-to-open rich modal (matrices / KaTeX).
- Formula matrix parse (`pmatrix` / `[[…]]`) for executable gate matrices.
### Changed
- Release notes and docs emphasize extensions vs embedded stdlib.
- Highlight.js CDN path for view pages; Variables panel script escaping fixed.
## 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
+22 -912
View File
File diff suppressed because it is too large. Load diff
+1 -12
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.2.0"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,17 +19,6 @@ 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"
libc = "0.2"
[workspace]
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
resolver = "2"
[dev-dependencies]
assert_cmd = "=2.0.14"
+12 -19
View File
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
欢迎访问 [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)
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.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`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
---
@@ -23,7 +23,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.2)
## 语法速览(v0.1)
| 标记 | 含义 |
|------|------|
@@ -32,11 +32,9 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
| `#` / `##` | 函数与作用域 |
| `+` / `1.` | 分支(臂头单独 `*` = else) |
| `-` | 循环(头下纯名则为形参) |
| 表格 | 集合 |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
@@ -47,14 +45,14 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
> 问候 谁=World
## 问候
+ `谁`
- 谁
> print text=Hello `谁`!
---
## 加一
+ `n`
- n
**`n` + 1**
```
@@ -97,19 +95,14 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.2.0)
## 现状(v0.1.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
- **官方扩展库 `ext/`**(本版重点,**非** stdlib):`llm` · `agent` · `web` · `quantum`。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [ext-quantum](doc/design/ext-quantum.md)
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
- **用户静态站**:`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
@@ -122,7 +115,7 @@ cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
```
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add llm|agent|web|quantum` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。`marqdo version --check` 可查看是否有新版本。
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/`;请下载带 `lib/` 的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB`)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
+6 -24
View File
@@ -16,49 +16,31 @@
| 文档 | 摘要 |
|------|------|
| [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/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [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) | **英文最小关键字 / 内置函数** |
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `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`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** |
| [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 调试** |
| [roadmap/okf-near-match.md](roadmap/okf-near-match.md) | **规划:OKF 相近任务命中**(精确 sig 之外的可选软复用) |
| [roadmap/agent-streaming.md](roadmap/agent-streaming.md) | **流式输出**(SSE + `complete`/`step` stream;S0–S1 已落地) |
| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) |
| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) |
| [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) |
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
-29
View File
@@ -1,29 +0,0 @@
# 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 是面向模型的压缩操作手册。
+1 -2
View File
@@ -67,8 +67,7 @@
| `keywords/bool-logic` | ✅ | ✅ |
| `structure/nested-call` | ✅ | ✅ |
| `structure/positional-call` | ✅ | ✅ |
| `structure/import/*` | ✅ | ✅(导入模块树后编译) |
| `structure/ns/*` | ✅ | ✅ |
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
+3 -3
View File
@@ -3,8 +3,8 @@
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 日期 | 2026-08-07 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
| 日期 | 2026-08-04 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
---
@@ -50,4 +50,4 @@ positional ::= value_token
## 4. 金样例
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
+33 -32
View File
@@ -2,18 +2,18 @@
| | |
|---|---|
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
| 日期 | 2026-08-07 |
| 状态 | 已定(v0 命令落地) |
| 日期 | 2026-08-04 |
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
| 相关 | [okf.md](okf.md)(**实现规范总览**)· [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
---
## 1. 决策(重申)
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
本文件规定 **CLI 与 v0 落盘格式**。
---
@@ -28,31 +28,26 @@ marqdo sync [PATH] -o OUT_DIR
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
---
## 3. 生成物
## 3. 生成物(v0)
```
OUT_DIR/
catalog.yaml # 机器向总清单(OKF 风格字段)
index.md # 人可读总览:Modules + Agent knowledge
index.md # 人/Agent 可读总览(含 YAML frontmatter)
modules/
<stem>.md # 每个工程 .mq.md 一个 Module 页
concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3)
tasks/…
skills/…
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
```
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
`structure/import/main.mq.md` → `modules/structure__import__main.md`
`.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。
### 3.1 `catalog.yaml`(示意)
```yaml
@@ -60,11 +55,12 @@ OUT_DIR/
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/0.1.2
by: marqdo/0.0.1
# at: 可选 ISO8601;CI 比对时可忽略
modules:
- id: structure/hello
resource: structure/hello.mq.md
title: Hello World
title: Hello World # 来自源 frontmatter title,缺省用文件名
imports: []
exports:
- name: Hello World
@@ -76,28 +72,35 @@ modules:
exports:
- name: main
kind: fn
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
```
字段约定(v0 最小集):
| 字段 | 含义 |
|------|------|
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
| `modules[].resource` | 相对 `PATH` 的源路径 |
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
| `generated.by` | `marqdo/<crate version>` |
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
### 3.2 模块概念页
### 3.2 模块概念页 frontmatter
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
```yaml
---
type: Marqdo Module
title: …
resource: structure/hello.mq.md
depends: [] # imports 列表
exports: [Hello World]
generated:
by: marqdo/0.0.1
---
```
### 3.3 Agent knowledge
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
---
@@ -106,7 +109,7 @@ Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Depend
| 命令 | 产物 | 受众 |
|------|------|------|
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
二者都从同一源树生成,互不替代。发布用户文档时可同时:
@@ -119,9 +122,7 @@ marqdo catalog tests -o .marqdo
## 5. 验收
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
6. `marqdo sync` 与 `catalog` 行为一致。
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
4. `marqdo sync` 与 `catalog` 行为一致。
+1 -2
View File
@@ -21,8 +21,7 @@
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
---
-1
View File
@@ -81,7 +81,6 @@ 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`) |
#### 强烈建议
+3 -11
View File
@@ -3,7 +3,7 @@
| | |
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-07 |
| 日期 | 2026-08-04 |
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
---
@@ -26,17 +26,10 @@ tests/
import/
main.mq.md
utils.mq.md
ns/
helpers.mq.md
path3.mq.md
use.mq.md
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md
ext/
agent-run-live.mq.md
errors/ # 期望失败(诊断文案稳定后再加金样例)
ns-instance-method.mq.md
…
```
@@ -49,7 +42,7 @@ tests/
| 类别 | 测什么 | 不测什么 |
|------|--------|----------|
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
@@ -58,8 +51,7 @@ tests/
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
- **CLI**:默认 `index.mq.md`、退出码
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径)
- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`)
- **模块图**:循环导入拒绝
---
-105
View File
@@ -1,105 +0,0 @@
# Native plugin ABI (v2)
| | |
|---|---|
| Status | Accepted |
| Date | 2026-08-07 |
| 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.
- **v2**: allowlisted `host_query` so plugins can read entry source / call site / skill without baking agent logic into the core.
## Contract
`MARQDO_ABI_VERSION = 2` (host accepts plugins with version `1..=2`).
Every plugin exports:
| Symbol | Role |
|--------|------|
| `marqdo_plugin_abi_version` | `1` or `2` |
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
| `marqdo_plugin_shutdown` | Teardown |
Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`.
### 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`.
### `host_query` allowlist (v2)
| name | Result JSON | Notes |
|------|-------------|--------|
| `module_source` | string | Entry `.mq.md` text |
| `call_site` | `{path,function,line}` | Active call site |
| `marqdo_skill` | string | Skill pack text |
| `cwd` | string | Host `cwd` (entry file directory) for path resolution |
| `record_plot` | `{ok:true}` | Args `{svg}` + optional `path`; push SVG into host plots (view embed / CLI auto-write), same channel as math plots |
Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).
## Marqdo surface (`lib/plugin` / `lib/插件`)
| English | Chinese | Host |
|---------|---------|------|
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
| `## unload` | `## 卸载` | `host_plugin_unload` |
| `## list` | `## 列出` | `host_plugin_list` |
| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` |
```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 unless trusted (`MARQDO_EXT` / `MARQDO_AGENT_PLUGIN` / built `libagent.*`). Prefer `native_path name=agent` for the official agent plugin.
## Demo / agent
```bash
cargo build -p marqdo_plugin_demo
cargo build -p marqdo_plugin_agent
```
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
- Agent (ABI v2): … **OKF agent-kb** …
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
## Layering
| Layer | May call `host_*` |
|-------|-------------------|
| `lib/*` | Yes (only L1 wrappers of generic L0.5) |
| `ext/*` | **No** — compose `lib/*` or ABI plugin names via `lib/plugin` |
| Application `.mq.md` | Prefer same as ext; do not add agent/OKF originals to `src/host` |
**Hard rule:** agent / OKF domain primitives live in `plugins/agent`, never in `HostFn` / `src/host/kb.rs`.
## Non-goals
- Embedding plugins in the release exe by default
- Callbacks from plugin into arbitrary Marqdo evaluation
- Arbitrary HostFn passthrough via `host_query`
- **Third-party** plugin / package registry
-143
View File
@@ -1,143 +0,0 @@
# 父智能体 Plan-and-Move(`## plan` 行动面)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-08-11 |
| 父文档 | [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md) |
| 相关 | [stdlib-subtask.md](stdlib-subtask.md) · [okf.md](okf.md) · [ai-skill.md](ai-skill.md) |
---
## 1. 一句话
**父智能体 = Plan-and-Move 控制器**:观察工作簿与子任务结果 → 规划下一步 → 行动(读 / 调工具 / 补丁 / 再跑 / 停);Marqdo「文档即代码」让工具、记忆与程序都落在 `.mq.md` 上。
---
## 2. 为何需要强化
单靠 `DECISION: DONE|CONTINUE|RUN` 时,父侧几乎没有「手」:
| 缺口 | 后果 |
|------|------|
| 看不到子源码 / 报错 / stdout | 空想 FIND/REPLACE,输出又臭又长 |
| 标准库未进入行动表 | 无法在规划环内用 `fs` / `json` / `subtask` 等 |
| 不能用 Marqdo 造工具 | 无法把可复用步骤沉淀为 `##` |
| 提示词过长且互相打架 | 模型「继续帮忙」而不停机 |
业界对 agent 回环的共识:成功标准、停机动作、**确定性行动面**三者必须写清;停机最终靠代码护栏,不只靠 prompt。
---
## 3. Marqdo 赋予的特性(相对通用 Plan-and-Move)
| 特性 | 含义 |
|------|------|
| 工作簿即程序 | 子执行物是可 `spawn path=` 的 `.mq.md`,不是隐式任务图 |
| 固化即记忆 | `DECISION: DONE` → `agent_workbook_solidify` + OKF 晋升 |
| `lib/*` 即工具 | 标准库是父可调度能力;经父 helper 或写入工作簿/`tools/` 后调用 |
| 补丁即改代码 | `CONTINUE` + 精确 FIND/REPLACE;禁止整文件 LLM 重写 |
| 文档即提示 | 站立提示、Skill 摘要、观察切片都是可读 Markdown,而非黑盒 system blob |
---
## 4. 循环形状(锁定)
```text
┌──────────────┐
│ Plan (LLM) │
└──────┬───────┘
│ 协议回复
┌─────────────┼─────────────┐
▼ ▼ ▼
READ:/CALL: DECISION: (无效 → error)
│ DONE/RUN/
│ CONTINUE
▼ ▼
Act 工具 Move(固化/补丁/spawn)
│ │
└──────┬──────┘
▼
Observe(有界)
│
└──► 回到 Plan 或终止
```
优先级(解析父回复时):
1. **`CALL:<name>` / `调用:`** — 跑父侧工具,结果并入 observation,再 Plan
2. **`READ:<kind>` / `读取:`** — 加深某一观察切片,再 Plan
3. **`DECISION:`** — Move(含运行时 solidify / apply_patch / spawn)
---
## 5. 观察面(有界、可加深)
`inspect_workbook` / `await_workbook` 在磁盘上可持有全文;**注入父 prompt 的默认紧凑观察**必须可行动且短:
| 字段 | 默认 | `READ:` 加深 |
|------|------|----------------|
| `source_excerpt` | 去 `<!-- … -->` 后的结构摘录,硬顶 ~4KiB / ~80 行 | `READ:source` → 更大但仍有硬顶的摘录 |
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
---
## 6. 工具面
### 6.1 父侧内建 helper(`CALL:` 首批)
写在 `ext/ai/agent.mq.md`,由 plan 循环直接调度(**不用** OpenAI function calling):
| 名称 | 作用 |
|------|------|
| `workbook_read` | 按 depth 读工作簿摘录 |
| `workbook_excerpt` | 结构摘录(默认观察同源) |
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
### 6.2 标准库与造工具
- **标准库直调(白名单)**:`CALL:lib.fs.read_text`(及 `exists` / `list_dir` / `json.parse` / `json.stringify` / `sys.cwd`)+ 可选 `ARGS:{…}` JSON 行;拒绝 `net.*` / `sys.exec` / 写删类。
- **目录**:`lib_catalog` 列出可 CALL 的 dotted 名。
- **造工具**:优先 `CONTINUE` + 短 PATCH 在工作簿内新增 `##`;或 `CALL:scratch_tool_write` 沉淀独立工具文件。
- **流式**:父 CALL/READ 发 `tool_start` / `tool_end`(view Tool 卡)。
- **非目标**:全量 `lib/*` JSON schema 反射;OpenAI function calling。
---
## 7. 输出纪律(停机规则)
父回复**只允许**协议行 + 一行 `SUMMARY` + 短 PATCH(`<20` 行)。禁止长独白 / 行程散文 / 把 observation 粘进 REPLACE。
修订阶段硬规则(自上而下):
1. `exit_code==0` 且 `has_value` → **立刻** `DECISION: DONE`(运行时 solidify);`has_worker_step` **不是** CONTINUE 的理由。
2. 仅失败 / 无值 / 明确未达目标时才 `CONTINUE`。
3. 代码护栏:非 `improve` 时,子已返回值则 **跳过父 LLM**,直接 solidify + DONE。
---
## 8. 与 `## step` 的关系
| | `step`(子) | `plan`(父) |
|---|-------------|-------------|
| 协议 | `CALL:` 或最终答案 | `CALL:` / `READ:` / `DECISION:` |
| 工具来源 | 工作簿 / 调用方 allowlist | 父 helper + 写入的 Marqdo `##` |
| 成功出口 | 返回答案文本 | `DONE` + solidify / promote |
---
## 9. 实现落点
| 组件 | 路径 |
|------|------|
| 设计(本文) | `doc/design/ext-agent-parent.md` |
| 多步总设计增量 | `doc/design/ext-agent-plan.md` §4.1 / 协议 |
| 子任务 I/O | `src/host/subtask.rs`、`lib/subtask.mq.md` |
| 父循环 / 观察 / 提示 | `ext/ai/agent.mq.md` |
-356
View File
@@ -1,356 +0,0 @@
# 智能体多步(`## 多步` / `## plan`)
| | |
|---|---|
| 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** |
| 日期 | 2026-08-11 |
| 父文档 | [ext-agent.md](ext-agent.md) |
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) |
---
## 1. 动机
单步(`## 单步` / `## step`)适合原子任务。复杂目标需要:
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
2. **用子任务真正跑这份工作簿**,与主推理隔离。
3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。
4. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。
5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
---
## 2. 一句话
**多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 `lib/subtask` 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 `# 智能体` 只跑 `单步`,确定步骤固化为代码。**
---
## 3. 角色与产物
| 角色 | 职责 |
|------|------|
| **父智能体** | 持有目标;创建 / 改写工作簿;`spawn path=` 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
| **工作簿 `.mq.md`** | 任务实现的**详细步骤文档兼程序**:导入、工具、一个或多个子智能体、可固化的普通函数与 `# main` 编排 |
| **子智能体** | 工作簿内的 `# 智能体` / `# agent`;走 `单步`(默认);工具表白名单可收窄 |
| **子任务通道** | `lib/subtask`:`spawn path=<工作簿>` → `wait`;与工具 `spawn fn=` 同一套能力 |
| 产物 | 说明 |
|------|------|
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`result`(子 `# main` 返回值优先)、`summary` / `error`;可选 `observation` |
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
---
## 4. 调用流水线(锁定)
```text
父:`助手`.多步 目标=…
▼
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
▼
② 创建(或打开)工作簿 .mq.md
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
- **大模型配置与父智能体一致**(见 §5)
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
▼
③ 父模型「分解」(非 OKF 命中路径必跑):`phase=decompose`,尚未 spawn;可 `DECISION: RUN` / `CONTINUE`+补丁 / 固化后 `DONE`
▼
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
▼
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
▼
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
- 充分 → 汇总,写回父文档,返回
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
▼
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
```
要点:
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
- **父是智能体开发大师**:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
---
## 4.1 观察面与补丁(锁定)
父每次二次规划前必须拿到观察 map(`inspect_workbook` / `await_workbook`)。磁盘可持全文;**注入父 LLM 的默认观察为有界紧凑面**(摘录 + I/O 尾部)。完整语义与 `READ:` / `CALL:` 行动面见 [ext-agent-parent.md](ext-agent-parent.md)。
| 字段 | 含义 |
|------|------|
| `path` | 工作簿路径 |
| `source` | 最新全文(磁盘);prompt 默认用 `source_excerpt` |
| `exit_code` | 上一轮子任务退出码 |
| `value` | 子 `# main` 返回值(经 `await_workbook` / `wait.value`) |
| `stdout` / `stderr` | 子任务捕获(`quiet` 仅静音 TTY,不丢弃数据) |
| `slots` | 命名写回列表(`key` + `body`) |
| `last_ok` / `last_error` | 便捷字段 |
二次规划输出协议(机器可解析;**禁止**只输出整份 `.mq.md`;**禁止**长独白):
```text
CALL:<parent-tool>
READ:source|stderr|stdout|slots
DECISION: DONE
SUMMARY: <一行>
DECISION: RUN
DECISION: CONTINUE
PATCH:
<<<
FIND
<确切旧片段>
===
REPLACE
<新片段>
>>>
```
解析优先级:`CALL` → `READ` → `DECISION`。应用器对文件做**精确** FIND→REPLACE;找不到则报错。`DONE` 时运行时 `agent_workbook_solidify` 固化答案(不必靠长 REPLACE 粘贴子散文)。
---
## 4.2 多轮哲学:仅子智能体接力(模式 C)
复杂 / 多轮目标 = **多份可执行 `.mq.md` 接力**,经 OKF 索引与复用;父 `plan` 聚合各子 `wait.value` 为 `result`。
| 做 | 不做 |
|----|------|
| 每主题 / 子目标一份工作簿(`resources/` / `explore/`) | 单文件无限追加「对话日志」 |
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
| `# main` **返回**答案;`quiet` 只管 TTY | 依赖子 `print` 把答案刷到父终端 |
---
## 5. 大模型配置与父保持一致
工作簿内构造子智能体时:
| 从父继承 | 说明 |
|----------|------|
| `model` / `大模型` 句柄字段 | `api_key`、`base_url`、`model`、`suffix`、`bearer` 及拼装前缀等与父相同 |
| 默认站立提示基调 | 可追加「只负责本工作簿内子任务」等收窄句;不得更换供应商端点 |
实现约定(D2):
1. 父把当前 llm 句柄 **序列化进工作簿**(例如构造段直接写 `> llm.llm` 前先 `load_env`,或写入由父生成的配置表 / 环境约定)。
2. 优先:**工作簿与父共享同一套 `OPENAI_*` / `.env` 加载路径**,子文件内 `> llm.load_env` + `> llm.llm`(或中文面),避免把密钥明文写进工作簿。
3. 若父句柄来自非默认 env,父须在生成工作簿时写出等价构造(仍禁止把密钥写进 git 跟踪路径;工作簿目录应默认被 ignore)。
**禁止**:子工作簿默默改用另一 `base_url` / 另一模型名,除非调用方显式参数允许覆盖(v1 不提供覆盖;一律继承)。
---
## 6. 工作簿内容形态
### 6.1 推荐:多个子智能体
面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示:
```markdown
---
title: agent-run-…
> ext/ai/llm.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/writeback.mq.md
> lib/subtask.mq.md
---
# 总目标
(父写入的目标叙述)
## 工具甲
…
# main
> llm.load_env path=…
*`模型` = > llm.llm *
*`调研` = > agent.agent model=`模型` tools=`表甲` standing=… *
*`撰写` = > agent.agent model=`模型` tools=`表乙` standing=… *
*`a` = > `调研`.step task=… *
*`b` = > `撰写`.step task=… *
```
### 6.2 也可:一个智能体多次单步
适合线性流水线;每次 `step` 仍默认写回,便于中断续跑。
### 6.3 固化为代码(强烈推荐)
一旦某步输入输出稳定(例如「取今日日期」「解析固定 JSON」),父智能体应把该步 **改写成普通 `##` 函数 + 直接调用**,不再经子智能体推理:
| 不确定 | 已确定 |
|--------|--------|
| `` > `子`.step task=… `` | `` *`x` = > 本地函数 … `` |
| 宽工具表 + 长 standing | 窄函数、表驱动、分支 `1.` / `2.` |
**多步的价值之一就是把「试出来的正确步骤」沉淀成工作簿里的代码**,而不仅是 chat 痕迹。
### 6.4 持续更新的两类内容
| 更新 | 含义 |
|------|------|
| **代码更新** | 增删 `##`、改 `# main` 编排、改工具表、把 step 换成固化调用、修分支 |
| **写回注释更新** | `<!-- marqdo-out ok|error -->` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 writeback 实现约定) |
工作簿是活文档:子任务跑完后磁盘上的 `.mq.md` 应比创建时更「像最终报告」。
---
## 7. 单步自动写回(服务多步)
### 7.1 决议
| | |
|---|---|
| **默认** | `单步` / `step` **自动写回** 本步结果(命名槽) |
| **开关** | 参数 `写回` / `writeback`(布尔,默认 `真` / `True`) |
| **槽** | 成功 → `key=ok`;失败 → `key=error`;正文为结构化 map 的 JSON(或与现 live 样例一致的 stringify) |
| **锚点** | 本步调用行(与现 `writeback.record` 锚点规则一致) |
这样:
- 父 / 工作簿**不必**靠提示词强迫模型「请记得写回」。
- 编排方仍可 `写回=假` 拿到纯 map,自行 `writeback.record`(测试、嵌套去重时有用)。
### 7.2 与父写回的分工
| 层级 | 写什么 |
|------|--------|
| 子 `step`(默认开) | 该步 decision / tool / result 或 error |
| 父 `plan` | 工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
**推荐**:载荷以子 `# main` 返回值(`wait.value` → `plan.result`)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
### 7.3 返回值
`step` 仍返回结构化 map(与现 D1 一致)。自动写回是**附加副作用**,不取代返回值。
---
## 8. 父智能体上下文(每次修订 / 汇总前)
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
| 片段 | 来源 |
|------|------|
| 站立提示 | 父构造 |
| 总目标 | `多步` 实参 |
| **父文件源码** | `agent_module_source` |
| **调用位置** | `agent_call_site` |
| **Marqdo Skill** | `agent_marqdo_skill` |
| 工作簿全文 / 写回 / 子返回 | `inspect_workbook`(源码 + slots + 退出码 + `value`) |
| 子任务退出码 | `subtask.wait` |
| 对话 / 历史 | 父 session;真相以写回为准 |
父模型输出必须是 **DONE / CONTINUE+精确补丁** 协议(见 §4.1),禁止整文件重写。
---
## 9. 公开 API(D2 契约)
### 9.1 `## 多步` / `## plan`
| 参数 | 中 / 英 | 默认 | 说明 |
|------|---------|------|------|
| 目标 | `目标` / `goal` | 必填 | 复杂任务描述 |
| 工作簿目录 | `工作簿目录` / `workbook_dir` | `.marqdo/agent-runs` | 新建文件所在目录 |
| 工作簿 | `工作簿` / `workbook` | 空 | 若给路径则**续跑 / 修订**该文件,跳过空白创建 |
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
| 写回 | `写回` / `writeback` | `真` | 父侧汇总写回 |
| 骨架 | `骨架` / `skeleton` | `single` | `single` 单 worker;`dual` 为 research→writer 两子智能体 |
返回 map(字段名英文字段,中文面可读同一结构):
| 字段 | 含义 |
|------|------|
| `status` | `ok` / `error` / `pending`(待确认) |
| `goal` | 回显目标 |
| `workbook` | 工作簿路径 |
| `rounds` | 实际执行轮次 |
| `summary` | 成功时的汇总 |
| `error` | 失败信息 |
### 9.2 `## 单步` / `## step`(修订)
在 D1 参数上增加:
| 参数 | 默认 | 说明 |
|------|------|------|
| `写回` / `writeback` | `真` | 是否自动 `record` 到 ok/error 槽 |
### 9.3 内部辅助(非稳定对外)
工作簿模板渲染、从父句柄生成子文件 frontmatter、解析子写回摘要等——可随实现调整。
---
## 10. 安全与边界
| 风险 | 对策 |
|------|------|
| 无限修订 / 嵌套 | `最大轮次`、`最大深度`;叶任务禁止再 `plan` |
| 工作簿写爆仓库 | 默认目录 `.marqdo/agent-runs/` + gitignore;禁止默认写到 `lib/` / `ext/` |
| 密钥进工作簿 | 继承 env / load_dotenv,不写明文 key |
| 子文件乱改父仓 | 子任务 cwd / fs_root 落到工作簿目录;工具表白名单 |
| 写回空行膨胀 | 替换跨度含 `-->` 行尾换行(已实现) |
| 并发写同一工作簿 | writeback 全局锁;同一 plan 内串行 spawn 为 v1 默认 |
---
## 11. 与旧 §3.2 叙述的差异(显式)
| 旧粗述 | 本文锁定 |
|--------|----------|
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
| 缓存命中略写 | **以 OKF 任务知识包为准**([okf.md §7](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` |
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
---
## 12. 实现路线(D2)
| 项 | 内容 |
|----|------|
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** |
| D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** |
| D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) |
| D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) |
| D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) |
---
## 13. 决议摘要
1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。
2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。
3. **经 `lib/subtask` 启动该文件**;可多轮执行。
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
5. **工作簿持续更新**:代码 + `marqdo-out`。
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。
---
## 14. 一句话
**多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
-349
View File
@@ -1,349 +0,0 @@
# Official agent development framework (`ext/ai/agent`)
| | |
|---|---|
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
## 0. 为什么要改掉旧方案
旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、`TOOL:<name>` 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,**背离了 Marqdo 的初衷**。
Marqdo 的宪法是 **代码即文档、文档即知识库**:
| 旧方案的问题 | Marqdo 应有的形态 |
|--------------|-------------------|
| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 `.mq.md` 里,人与模型同读同写 |
| 执行过程是不透明的 chat transcript | 思考与行动写回文档;`view` / `debug` 可跟可审 |
| 复杂任务与简单任务同一套循环 | **单步**与**多步(工作簿)**两级模型 |
| 成功经验留在进程内存 | **自写回**做成果缓存与失败知识;同类任务可复用 |
本文件锁定新方向。仓库里现有的 `ext/ai/agent.mq.md` / `智能体.mq.md`(TOOL: 薄循环)视为 **待替换实现**,以本文为准。
---
## 1. 我们在建什么
一个 **文档驱动的智能体开发框架**:编排本身就是可读的 `.mq.md`;模型吃的是这份文档与调用位置;写回让思考过程可控、可调试、可沉淀。
**不是** 外挂任务队列、**不是** 官方捆绑领域工具、**不是** 第二套聊天栈(模型 I/O 仍用 `ext/ai/llm`)。
| 在范围内 | 在范围外(应用 / runbook) |
|----------|---------------------------|
| `# 智能体` / `# agent` 构造 | 领域工具:`## 查天气`、`## 分配任务` … |
| `## 单步` / `## step` | 业务表格、队列、工单流程 |
| `## 多步` / `## plan`(生成并驱动工作簿) | 具体分解策略模板库(可放用户仓) |
| 上下文:源码、调用位置、工作簿路径、Skill | 第二套 HTTP / 聊天协议 |
| 与 `lib/writeback`、**`lib/subtask`(工具执行通道)**、**`lib/plugin` + ABI v2 `plugins/agent`** 协作 | 把领域技能塞进官方 `ext/ai/`;在 `ext` 内直调 `host_*` |
---
## 2. 核心理念:编排可读,过程可写回
1. **提示词与代码不分离**
站立提示、工具表、任务叙述都写在 `.mq.md` 里。框架把**当前模块源码**与**调用位置**交给模型,而不是另起一套 system prompt 黑盒。
2. **把 Marqdo 源码交给智能体**
每次推理可注入:入口 / 工作簿 `.mq.md` 全文(或相关切片)、`host_call_site`(路径、函数、行)、`skills/marqdo`(写 / 读 `.mq.md` 的语法纪律)。模型输出应优先是 **可解释的决策** 与 **对文档的结构化改动意图**,而不是私有 JSON 协议。
3. **自写回 = 思考轨迹 + 成果缓存**
成功或失败都写回文档(见 [stdlib-writeback.md](stdlib-writeback.md))。成功块可被后续同类任务命中,避免重复失败;失败块成为可读的「避坑记录」。`marqdo view` 在语句下展示 output-card,调试面可对齐同一份真相。
4. **相对其他框架的优势**
无需外挂向量库 / 状态机才能「记住」某次子任务已成功:记忆就是仓库里的 Markdown。审计、合规、复盘 = `git log` + 打开工作簿。
---
## 3. 两级执行模型
### 3.1 模式 A — 单步(原子任务)
| | |
|---|---|
| **输入** | 小任务描述 + 必要上下文(工具表、站立提示、源码切片) |
| **过程** | 一次(或有限次)推理;可选调用 **runbook 内** 的工具函数;结果写回 |
| **输出** | 原子结果(文本 / 表 / 句柄字段) |
| **适用** | 问答、单一工具、确定性一步 |
公开方法(中 / 英):`## 单步` / `## step`。
示意(语法外形;实现以落地代码为准):
```markdown
---
> ext/ai/智能体.mq.md
> ext/ai/大模型.mq.md
> lib/自写回.mq.md
> lib/时间.mq.md
---
## 获取时间
*`u` = > 时间.此刻秒 *
**> 时间.格式化 秒=`u` 格式=%Y-%m-%d**
# main
*`模型` = > 大模型.大模型 *
`工具表` =
| 工具 |
|------|
| 获取时间 |
*`助手` = > 智能体 大模型=`模型` 工具=`工具表` 站立提示=你是可调试的 Marqdo 助手。 *
*`结果` = > `助手`.单步 任务=今天日期是什么?请在需要时调用工具。 *
> 打印 内容=`结果`
```
单步约定:
- 模型看到的上下文 **包含本文件源码与调用位置**,因此「有哪些 `##` 工具」对模型是可见的;行动约定写在提示里(人可读),例如单独一行 `CALL:<工具名>` / `调用:<工具名>`,最终答案则直接正文回复。
- 工具仍是 **runbook 里的 `##` 函数**(v1 以零参为主;可经 `args=` 扩展)。
- **调用工具走 [`lib/subtask`](stdlib-subtask.md)**:白名单校验通过后 `spawn fn=<名>`(中文面 `启动 函数=`)→ `wait` / `等待`,而不是进程内直接 `call_fn`。这样工具与主推理隔离在子任务语义下,并可与并行、超时、探测同一套主机能力对齐。
- 结束后用自写回记录:任务摘要、选用工具、结果或错误。
### 3.2 模式 B — 多步 / 复杂执行(工作簿)
> **完整锁定设计**见 [**ext-agent-plan.md**](ext-agent-plan.md)。以下为摘要。
| | |
|---|---|
| **输入** | 复杂目标 |
| **过程** | 父智能体**创建(或续跑)工作簿** →(非命中)**父先分解** → **`lib/subtask` spawn** 跑子文件 → 观察写回 → **父修订补丁后再执行**(有轮次上限) |
| **输出** | 汇总 map(含 `result`)+ 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
| **适用** | 需分解、多情形、可固化步骤、可复用子成果的任务 |
公开方法:`## 多步` / `## plan`。
流水线要点:
1. **创建工作簿** — 默认 `.marqdo/agent-runs/`;内容为任务的详细可执行步骤(导入、工具、`# main`、子智能体)。
2. **模型配置继承父智能体** — 共享 env / 等价 llm 句柄;v1 不静默换模。
3. **子任务执行整文件** — 不是父进程内嵌解释。
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为返回答案的普通代码**(多轮 = 多文件接力 + OKF,见 [ext-agent-plan.md §4.2](ext-agent-plan.md))。
5. **持续更新** — 代码修订 + 写回注释刷新(替换不累积空行)。
6. **`单步` 默认自动写回**(`写回=` / `writeback=` 可关),父侧再汇总写回。
7. **父上下文** — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
示意:
```markdown
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 *
> 打印 内容=`报告`
```
工作簿概念形状与修订循环细节 → [ext-agent-plan.md](ext-agent-plan.md)。
## 4. 分层与仓库布局
```text
ext/
ai/
llm.mq.md / 大模型.mq.md # 模型 I/O
agent.mq.md / 智能体.mq.md # 本框架(按本文重写)
```
| 层 | 职责 |
|----|------|
| **应用 runbook** | 领域 `##` 工具、任务表、是否人工确认分解 |
| **`ext/ai/agent`** | 单步 / 多步、工作簿生成、子智能体编排、写回约定 |
| **`ext/ai/llm`** | 补全 / 聊天 |
| **`lib/writeback`** | 持久化输出块 |
| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) |
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`> ext/ai/智能体.mq.md`。
**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找:
1. `MARQDO_AGENT_PLUGIN`(显式 `.so` / `.dylib` 路径)
2. `CARGO_TARGET_DIR/{debug,release}/libagent.so`(或 `.dylib`)
3. cwd `target/{debug,release}/`
4. 可执行文件旁 `libagent.*` 或 `target/debug/`
5. `MARQDO_EXT/native/libagent.*`(`marqdo ext add agent` 安装)
本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。
**分层纪律(硬规则,勿破)**:
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
---
## 5. 公开 API(目标契约)
| 中文 | 英文 | 角色 |
|------|------|------|
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
构造参数(v1):
| 参数 | 说明 |
|------|------|
| `大模型` / `model` | `ext/ai/llm` 句柄 |
| `工具` / `tools` | 工具名表(单列文本,或多列且含 `工具`/`tools`/`name`) |
| `站立提示` / `standing` | 写在文档里的常驻说明(可空) |
`## 单步` 参数:`任务` / `task`;可选 `写回` / `writeback`(默认真)、深度、是否强制不用缓存等。
`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`工作簿`(续跑路径)、`最大深度`、`最大轮次`、`确认分解` —— 详见 [ext-agent-plan.md §9](ext-agent-plan.md)。
模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)**不是**稳定对外契约,可随实现调整。
---
## 6. 工具表与子任务调用
工具 **不是** 框架内置能力。在 runbook 定义 `##`,再用表登记名称:
```markdown
`工具表` =
| 工具 |
|------|
| 获取时间 |
| 读取摘要 |
```
- 单列表 → 名称列表。
- 多列表 → 从列 `工具` / `tools` / `name` 取名。
- 名称须对应当前模块(或导入可见)的 `##`。
- **不要** 用 `parse text=["fn"]` 列工具(未加引号的标识符会被当成调用)。
### 6.1 调用路径(锁定)
```text
模型回复含 CALL:<名> / 调用:<名>
▼
host_tool_allowed(工具表白名单)
▼
lib/subtask:spawn fn=<名> → wait
▼
工具返回值写回上下文 / 自写回
```
| | |
|---|---|
| 英文面 | `> spawn fn=`名`` → `> wait id=`…`` |
| 中文面 | `> 启动 函数=`名`` → `> 等待 id=`…`` |
| 可选 | `args=` / `参数=` 传给带形参的工具;多工具并行时多次 `spawn` 再 `wait_all` / `等待全部` |
**非目标:** 以裸 `call_fn` 作为框架默认工具通道(应用仍可直接 `call_fn`,但官方智能体走子任务库)。
领域逻辑永远留在应用文件,不进官方 `ext/ai/`。
---
## 7. 上下文注入(每次单步 / 子步)
必须可注入(实现可切片,但不得默默丢掉「代码即文档」):
| 片段 | 来源 |
|------|------|
| 站立提示 | 构造参数 / 文档正文 |
| 任务 / 目标 | 方法实参 |
| 工具表(人可读) | 构造参数 |
| **当前 `.mq.md` 源码** | 插件 `agent_module_source`(经 ABI v2 `host_query`) |
| **调用位置** | 插件 `agent_call_site` |
| **Marqdo skill** | 插件 `agent_marqdo_skill` |
| Marqdo Skill | `skills/marqdo/`(`MARQDO_SKILL` 可覆盖) |
| 相关写回块 | `lib/writeback` 的 `get` / `list` |
禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。
---
## 8. 自写回与缓存语义
依赖 [stdlib-writeback.md](stdlib-writeback.md):`record` / `写回` → `<!-- marqdo-out … -->`。
### 8.1 单步返回值与默认写回
`单步` / `step` 返回结构化 map,并在 **`写回` / `writeback` 默认真** 时自动 `record` 到命名槽(成功 `ok` / 失败 `error`)。关闭写回则行为与早期「纯返回值」一致,由编排方自行 `writeback.record`。
| 字段 | 何时 | 含义 |
|------|------|------|
| `status` | 总是 | `ok` / `error` |
| `task` | 总是 | 本步任务 |
| `decision` | 总是 | 模型首轮输出(含 CALL 行等) |
| `tool` / `tool_result` | 成功且调了工具 | 工具名与子任务返回 |
| `result` | 成功 | 最终答复 |
| `error` | 失败 | 错误信息 |
```markdown
*`out` = > `助手`.step task=… *
*`回复` = > json.get value=`out` key=result *
# 默认已写回;若 writeback=False 则需自行 record:
# > writeback.record value=`body` key=ok
```
命名槽 `ok` / `error` 互不覆盖;锚点为调用行。多步工作簿内依赖此默认写回,避免靠提示词强制落盘 —— 见 [ext-agent-plan.md §7](ext-agent-plan.md)。
**命中规则(后续缓存)**:读 `key=ok` 且非占位时可复用。失败知识读 `key=error`。
用户可 `clear key=ok` / `clear key=error` 强制重跑。
复杂执行中,子结果写回优先落在 **工作簿** 文件;父 `多步` 维护汇总写回。
### 8.2 Live 金样例
[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step`(**默认写回** `ok`/`error`)+ 子任务工具。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**。需已构建 agent 原生库(见 §4)。
---
## 9. 安全与边界
| 风险 | 对策 |
|------|------|
| 无限多步递归 | `最大深度`(默认小,如 2);叶任务强制单步 |
| 工具越权 | 仅工具表白名单;子智能体可传更窄的表 |
| 工作簿爆炸 | 统一目录、命名含时间 / id;可选总超时 |
| 缓存过期 | 签名 + 时间戳;手动清块 |
| 模型乱改仓库 | 写回 API 约束写入形态;多步生成文件限于工作簿目录 |
---
## 10. 相对旧 API 的迁移
| 旧(废弃方向) | 新 |
|----------------|----|
| 唯一的 `## 执行` / `## run` + 隐藏 TOOL: 循环 | `## 单步` / `## 多步` |
| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 |
| 提示全在框架字符串 | 站立提示与任务在 `.mq.md`;源码注入 |
| `tests/ext/agent-smoke` 测 TOOL 上下文拼接 | 重写为单步离线 / 写回 / 工作簿骨架测试 |
兼容:可短期保留 `## 执行` 作为 `## 单步` 的别名,但文档与金样例迁到新名后删除别名。
---
## 11. 实现路线(文档锁定后)
| 阶段 | 内容 | 状态 |
|------|------|------|
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** |
| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** |
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(观察→精确补丁;禁止整文件重写);**D2a–D2f 主路径已落地** | **done** |
| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** |
| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | done(workbook 链到 `/file?path=`;写回槽 `ok`/`error`/`trace` 徽章 + `#wb-{line}`;plan 结果卡) |
| O2 | OKF 任务知识包:`plan` reuse/promote([okf.md §7](okf.md)) | **done** |
### 非目标
- 在官方 `ext/ai/` 捆绑领域工具或工单技能
- 在 `ext/` 根目录摊平 `.mq.md`
- 平行再造一套 LLM HTTP 栈
- 以不可读的私有二进制协议作为编排主界面
---
## 12. 一句话
**智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。**
单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 [ext-agent-plan.md](ext-agent-plan.md)。
流式:`## step` / `## plan` 支持 `stream=True` / `echo=True`(SSE 增量;返回 map 不变;`plan` 另附 `events`,可选 `trace` 写回)。非命中时先流式父分解再 spawn 子任务。见 [agent-streaming.md](../roadmap/agent-streaming.md)。
-72
View File
@@ -1,72 +0,0 @@
# Official extension installer (`marqdo ext`)
| | |
|---|---|
| Status | **Accepted (v0.1)** |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.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/web/`, `ext/quantum/`), 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`, **`native/libagent.so`** (or `.dylib`) |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
```bash
cargo build -p marqdo_plugin_agent
marqdo ext add agent
```
Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
## Tests
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
-85
View File
@@ -1,85 +0,0 @@
# 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) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
**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` |
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
| `# llm` | `# 大模型` | Object ctor → handle map |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
```markdown
---
> ext/ai/llm.mq.md
---
# main
> load_env
*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`
*`events` = > `model`.complete prompt=Say hi stream=True *
- [`ev`](`events`)
*`t` = > json.get value=`ev` key=type *
1. `t` == "delta"
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. *
*`_` = 1*
```
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`
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
-49
View File
@@ -1,49 +0,0 @@
# `ext/quantum` — 自定义酉门(公式矩阵 → 可施加)
| | |
|---|---|
| 状态 | **Accepted · 已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) |
---
## 1. 目标
作者用 `$$…$$`(或嵌套 list)写出酉矩阵 → `quantum.gate matrix=…` 得到可复用门句柄 → `` `qc`.apply gate=… qubits=… `` 施加到电路。
---
## 2. 公式矩阵
`$$` 围栏若含 `[[…]]` 或 `\begin{pmatrix}` / `\begin{bmatrix}`,在**解析期**求值为嵌套数值 list(非整棵 `Formula` 标量树)。
支持:
- ASCII:`[[1,0],[0,-1]]`、`(1/sqrt(2))*[[1,1],[1,-1]]`
- LaTeX 子集:`\frac{…}{…}`、`\sqrt{…}`、`pmatrix` / `bmatrix`(`&` / `\\`)
复数:list 路径仍可用 `{re,im}` 或 `[re,im]`;公式路径本切片以实矩阵为主。
---
## 3. API
```markdown
*`U` = > quantum.gate matrix=`H_matrix` name=U *
# 或构造参数 matrix=;name 可选(默认 U)
*`qc` = > `qc`.apply gate=`U` qubits=0 *
# qubits= 标量或 list;矩阵维数须为 2^k
```
中文:`量子.门 矩阵=` / `` `qc`.施加 门= 比特= ``。
具名门仍可用 `name=H`;`matrix` / `matches_matrix` / `draw` 对自定义门同样有效。
---
## 4. 验收
- 公式(或 list)定义的 H 与内置 `H` 概率一致
- EN/ZH 金样
-48
View File
@@ -1,48 +0,0 @@
# `ext/quantum` Q5.5 — 振幅阻尼(教学轨迹)
| | |
|---|---|
| 状态 | **Accepted · 已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q5.md](ext-quantum-q5.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
---
## 1. 目标
在 Q5 的 `bitflip` / `depolarizing` 之外,补一种**耗散**教学噪声:`amplitude_damping`(中文 `振幅阻尼`),仍只影响 `run` 轨迹;`simulate` / `probabilities` 忽略。
**刻意不做:** 完整 Kraus 表 API、任意算符噪声、密度矩阵引擎、相位阻尼完整 Lindblad。
---
## 2. 作者面
```markdown
*`qc` = > `qc`.noise kind=amplitude_damping p=0.1 *
# 中文
*`qc` = > `qc`.噪声 种类=振幅阻尼 概率=0.1 *
```
别名:`amp_damp` / `amplitude-damping`。
---
## 3. 模拟语义
与 Q5 相同:每个改态门后,对涉及比特独立掷骰。
对每个比特,以概率 `p` 施加**跳跃**算符 \(E_1 = |0\rangle\langle 1|\)(只作用该比特),再归一化:
- 若态在该比特上几乎全为 `|0⟩`(范数 ≈ 0),跳跃无效,态不变。
- 否则振幅从 `|…1…⟩` 搬到对应 `|…0…⟩` 并归一化。
金样:`X` 后 `amplitude_damping p=1` → 全部 shot 落在 `|0⟩`。
---
## 4. 验收
- `tests/ext/quantum-amp-damp-smoke.mq.md`(+ 中文对称)
- L1 EN/ZH 文档列出第三种 `kind`
-69
View File
@@ -1,69 +0,0 @@
# `ext/quantum` Q5 — 最小噪声(教学用)
| | |
|---|---|
| 状态 | **Accepted · 最小实现已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
---
## 1. 目标
在 **不** 引入完整开放系统 / 云后端的前提下,让教学文档能写「带噪声的采样」,金样可复现。
**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。振幅阻尼教学轨迹见 [ext-quantum-q5.5.md](ext-quantum-q5.5.md)。
---
## 2. 作者面
电路上可选噪声字段(方法链设置,返回新句柄):
```markdown
*`qc` = > `qc`.noise kind=bitflip p=0.05 *
# 或
*`qc` = > `qc`.noise kind=depolarizing p=0.02 *
```
| 参数 | 含义 |
|------|------|
| `kind` | `bitflip` \| `depolarizing`(中文:`比特翻转` / `退极化`) |
| `p` | 每比特、每个非 `barrier`/`measure` 门后的错误概率,`0…1` |
`simulate` / `probabilities`:**忽略噪声**(仍为理想酉演化),避免概率图被蒙特卡洛抖动。
`run shots= seed=`:**启用噪声**(若 `p>0`):按轨迹采样,结果可复现。
---
## 3. 模拟语义(轨迹)
每个 shot:
1. 从 `|0…0⟩` 施电路门(跳过 `BARRIER`;`MEASURE` 不改变酉演化)。
2. 每施一个会改态的门后,对**该门涉及的每个比特**独立:
- `bitflip`:以概率 `p` 施 `X`;
- `depolarizing`:以概率 `p` 均匀随机施 `X`/`Y`/`Z` 之一。
3. 若电路含 `MEASURE` 标记:只对标记比特做计算基采样;否则测全部比特。
RNG:与现有 `run seed=` 同一 SplitMix64 流(门后噪声与最终采样共用)。
---
## 4. 与作者面补齐的关系
| API | 行为 |
|-----|------|
| `barrier` | 仅可视化;模拟跳过 |
| `measure` | 可视化测量符号;决定 `run` 读出哪些比特 |
| `append` | 追加另一 `circuit` 的 `ops`(或单门) |
| `state` | 等价于当前理想 `simulate` 结果(`quantum_state`) |
---
## 5. 验收
- 金样:理想 Bell `run` 不变;`noise kind=bitflip p=1` 在已知电路上计数偏离理想(`seed=` 固定)。
- `barrier`/`measure` 出现在 `draw kind=circuit` SVG。
- 中英 L1 对称;仍无 `host_*` 于 `ext/**`。
-400
View File
@@ -1,400 +0,0 @@
# 官方扩展:`ext/quantum` 量子计算模拟
| | |
|---|---|
| 状态 | **Accepted · Q0–Q5.5 已落地**(教学噪声含振幅阻尼;完整开放系统另文) |
| 日期 | 2026-08-12 |
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
---
## 0. 一句话
`ext/quantum` 用 **GFM 表格 + 类方法 +(可选)`$$` 狄拉克/矩阵公式** 描述量子门与电路;**经典状态向量模拟**给出概率与采样。
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。
**不改 Marqdo 核心语法**;热路径只在 ABI 插件;**禁止**把量子核链进 `marqdo` 主二进制或在 `ext/**` 里调用 `host_*`。
---
## 1. 为何做量子扩展(与 math 的关系)
### 1.1 与 `lib/math` 的相似处
| math | quantum |
|------|---------|
| `` `f` = `` + `$$…$$` → `formula` | 门矩阵 / 态矢量可用 `$$` **展示与核对** |
| 库函数对公式求值、求导、作图 | 类方法对电路施门、模拟、画图 |
| view 内嵌 SVG;CLI 可 `path=` | view 内嵌**电路图 / 概率条 / 布洛赫**;CLI 可落盘 |
| 金样例失败 = 文档/公式错 | 金样例失败 = 门定义或电路叙述错 |
math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的可执行电路文档**。两者都是「写出公式 → 跑通 → 证明文档正确」。
### 1.2 与 math 的刻意分界
| 做 | 不做 |
|----|------|
| 量子在 **`ext/quantum`**,经 `plugin.load` | **不**并进 `lib/math`(避免 stdlib 膨胀) |
| 复数振幅用 `{re, im}` map(与现有 `Value` 兼容) | **不**为量子在核心新增 `Value::Complex`(可二期) |
| 角度可用 `math.pi` 等常量 | **不**在 quantum 插件内重写 CAS |
### 1.3 「代码即文档」在这里的作用
典型教学页:
```markdown
# 贝尔态 |Φ+⟩
对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。
# main
`steps` =
| 步 | 门 | 比特 |
|----|----|------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
```
- 叙述与表格是**给人看的电路说明**;
- 同一文件是**可执行程序**;
- gold / CI 断言概率 → **文档与物理约定同步**,无需另维护「幻灯片公式」。
---
## 2. 硬约束(评审锁定)
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
---
## 3. 布局与安装
```text
ext/quantum/
quantum.mq.md # 英文类 API
量子.mq.md # 中文类 API
plugins/quantum/
Cargo.toml
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
examples/quantum-bell/ # 规范示例(Q3)
tests/ext/quantum-*.mq.md
```
```bash
cargo build -p marqdo_plugin_quantum
marqdo ext add quantum
```
导入:
```markdown
---
> ext/quantum/quantum.mq.md
---
```
或中文:`> ext/quantum/量子.mq.md`。
---
## 4. 核心模型
### 4.1 运行时句柄(JSON map + `_type`)
| `_type`(英) | 中文类名 | 含义 |
|---------------|----------|------|
| `quantum_gate` | `量子门` | 具名门或自定义酉矩阵 |
| `quantum_circuit` | `量子电路` | n qubits + 有序门列表 |
| `quantum_state` | `量子态` | 状态向量(振幅列表) |
| `quantum_result` | `量子结果` | 概率 / 采样 / 可选坍缩态 |
| `quantum_svg` | (产物) | 带 `svg` 字段的可视化结果 |
插件返回 map;Marqdo 对象系统挂 `_type` 后可用方法链。
### 4.2 状态表示
- **纯态**状态向量:长度 `2^n`,每元 `{re, im}`(f64)。
- 默认初态:`|0…0⟩`(仅 index 0 振幅为 1)。
- 门作用后可选重归一化(阈值误差阈值,默认开)。
### 4.3 公式面(对齐 math 精神,不抢 math 实现)
允许用 `` `G` = `` + `$$…$$` 书写门矩阵(**可执行**,见 [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md)):
````markdown
`H_matrix` =
$$
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
$$
*`U` = > quantum.gate matrix=`H_matrix` *
*`qc` = > `qc`.apply gate=`U` qubits=0 *
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
````
- v1:**具名门**以插件内置酉矩阵为准;`matrix=` 可从嵌套 list / `$$` 矩阵围栏构造自定义门。
- `$$` 含 `[[…]]` 或 `\begin{pmatrix}` 时解析期求值为数值 list;标量公式仍为 `Formula`。
- `matches_matrix` 仍可用于核对。
---
## 5. 作者面 API(锁定草图)
### 5.1 英文 `ext/quantum/quantum.mq.md`
```markdown
# gate
+ `name`=None # H X Y Z S T I CX CZ SWAP …
+ `theta`=None # Rx/Ry/Rz
## matrix # → 振幅表 / 嵌套 list(文档与调试)
## draw # → quantum_svg(`kind=gate|matrix` 符号 / 热力图)
## matches_matrix
+ `matrix`
+ `tol`=1e-9
# circuit
+ `qubits`
+ `steps`=None # 可选:GFM 门序列表
## h / x / y / z / s / t
+ `qubit`
## rx / ry / rz
+ `qubit`
+ `theta`
## cx / cz
+ `control`
+ `target`
## swap
+ `a`
+ `b`
## barrier # 仅可视化分隔,不改变态
## measure # 标记测量(模拟时按计算基)
+ `qubits`=None # 默认全部
## append # 追加另一电路或门
+ `op`
## simulate # → quantum_state(不坍缩)
## probabilities # → map 基矢标签 → 概率
## run
+ `shots`=1024
+ `seed`=None # → quantum_result(计数直方图)
## draw
+ `path`=None # SVG;无 path 时仍可进 view 产物
## state # 当前缓存态(若已 simulate)
```
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
### 5.2 中文 `ext/quantum/量子.mq.md`
| 英文 | 中文 |
|------|------|
| `gate` | `门` |
| `circuit` | `电路` |
| `h` | `哈达玛` |
| `x` / `y` / `z` | `泡利X` / `泡利Y` / `泡利Z` |
| `cx` | `控非` |
| `cz` | `控相` |
| `rx`/`ry`/`rz` | `绕X`/`绕Y`/`绕Z` |
| `simulate` | `模拟` |
| `probabilities` | `概率` |
| `run` | `运行` |
| `draw` | `绘图` |
| `measure` | `测量` |
| `qubits` | `比特数` |
| `steps` | `步骤` |
| `shots` / `seed` | `次数` / `种子` |
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
### 5.3 电路表(文档优先写法)
```markdown
`steps` =
| 步 | 门 | 比特 | 参数 |
|----|----|------|------|
| 1 | H | 0 | |
| 2 | CX | 0,1 | |
| 3 | RZ | 1 | pi/4 |
```
列名中英兼容:`步|step`、`门|gate`、`比特|qubits|qubit`、`参数|theta|params`。
*`qc` = > quantum.circuit qubits=2 steps=`steps` *` 与方法链**等价**;表更适合「整页即电路说明书」。
### 5.4 返回值形态
| 方法 | 返回 |
|------|------|
| `simulate` | `{_type, qubits, dim, amplitudes:[{re,im},…]}` |
| `probabilities` | `{ "00": 0.5, "11": 0.5 }`(标签为小端比特串,文档写死) |
| `run` | `{ counts: {…}, shots, seed }` |
| `draw` | `{_type: quantum_svg, kind: circuit\|gate\|probs\|bloch, svg: "…" }` |
---
## 6. 模拟器语义
| 项 | 锁定 |
|----|------|
| 模型 | 封闭系统纯态;计算基测量 |
| 默认上限 | **12 qubits**;`MARQDO_QUANTUM_MAX_QUBITS` 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16) |
| 超限 | 错误信息含当前 n 与上限 |
| `simulate` / `probabilities` | **无 RNG**、确定性 |
| `run` | 多项式采样;`seed=` 可复现(金样必用) |
| 数值 | f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段 |
实现:插件内 Kronecker / 按比特作用稀疏更新;可用 `nalgebra` 或手写,**不**捆绑外部量子云。
---
## 7. view 模式支持(专项)
对齐 [view.md](view.md) 与 math 作图:**Structure / Execution / Source 共用渲染**;禁止第二套皮肤。
### 7.1 Structure(结构区)
| 源形态 | 展示 |
|--------|------|
| `` `qc` = `` + 电路表 | **circuit-card**:比特数、门序列时间线(文本/紧凑 SVG) |
| `` `G` = `` + `$$` 门矩阵 | 沿用 **formula-card**(KaTeX);徽章可标 `gate`(若绑定来自 quantum.gate) |
| 方法链语句 | 普通调用行;不强制每步展开 |
### 7.2 Execution(执行区)
| 产物 | 展示 |
|------|------|
| `quantum_svg` | 与 math `plots` 同级:**内嵌 SVG**(电路轨线图 / 概率直方图 / 单比特布洛赫) |
| `probabilities` / `counts` | 表格 + 可选自动条形 SVG |
| `quantum_state` | 默认折叠振幅表;小 n(≤3)可并排显示基矢 |
### 7.3 产物如何进入 view(实现锁定)
插件**不能**直接碰核心 `HostContext.plots`。采用其一(实现时二选一,优先 A):
| 方案 | 做法 |
|------|------|
| **A(推荐)** | ABI `host_query("record_plot")`:参数 JSON `{svg}`;写入与 math 相同的 plots 列表([ext-abi.md](ext-abi.md) allowlist 增补一条) |
| **B** | 仅返回 `quantum_svg`;view 在渲染执行值时识别 `_type`/`svg` 字段并内嵌(不扩 ABI) |
CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。
### 7.4 可视化内容(v1 必须 / 可后)
| 图 | v1 | 说明 |
|----|----|------|
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` |
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
---
## 8. 分期(开发计划)
```text
Q0 脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
Q1 态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
Q2 Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
Q3 电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-quantum-q5.md) ← **done(最小)**
```
| 阶段 | 交付物 | 验收 |
|------|--------|------|
| **Q0** | `marqdo_plugin_quantum` 注册 `quantum_ping`;L1 加载失败可读 | `ext add quantum` 路径通 |
| **Q1** | 贝尔态 `probabilities` ≈ 0.5/0.5 | `tests/ext/quantum-bell-smoke.mq.md` |
| **Q2** | 旋转门 + `run seed=` 计数稳定 | 中英双金样 |
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
| **Q4** | 概率图 + 布洛赫;`matches_matrix`;用户文档页 | `quantum-draw-smoke` / `quantum-gate-matrix-smoke`;`view output` 可浏览示例 |
| **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` |
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
---
## 9. 规范示例(目标作者体验)
```markdown
---
title: Bell state
> ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
*`svg` = > `qc`.draw *
> print text=`p`
```
中文面对称:`量子.电路`、`哈达玛`、`控非`、`概率`、`绘图`。
---
## 10. 刻意不做(本 Accepted 范围)
- 真机 / 云后端(IBM、Braket…)
- 开放系统、完整噪声模型(可 Q5+)
- 符号电路编译优化器
- 交互式电路编辑器
- 把量子并入 `lib/math` 或核心 opcode
- 无上限比特的「生产级」模拟
---
## 11. 开放点(已收敛 / 剩余)
| 议题 | 结论 |
|------|------|
| 对象面 vs 自由函数 | **主推对象/方法链**;自由函数不平行提供 |
| 电路表 | **v1 纳入**(Q3),与方法链等价 |
| 振幅过大 | v1 全进 Value;n≤12 可接受;超限已挡 |
| view 产物 | **优先** `host_query("record_plot")` |
| 与 web | **不依赖** web 做可视化;SVG 自绘 |
---
## 12. 评审清单
1. ABI-only + 中英分文件是否认可?
2. 默认 12 qubits 上限是否合适?
3. 电路表列设计(步/门/比特/参数)是否够用?
4. view:电路轨线 + 概率条为 v1 必须,是否同意?
5. `$$` 矩阵核对放 Q4,是否同意先表驱动?
评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。
---
## 13. 一句话
**表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。**
-600
View File
@@ -1,600 +0,0 @@
# 官方扩展:`ext/web` 动态网站
| | |
|---|---|
| 状态 | **Accepted · 完成**(SQLite 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / `app.static`;Postgres 等见 §9) |
| 日期 | 2026-08-11 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
---
## 0. 一句话
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
---
## 1. 为何要做网络扩展库
### 1.1 问题
若没有专用扩展,作者只能:
- 手写 JSON 袋、`json.set` 拼装组件/样式;或
- 要求改语言(让表格单元格求值、点号取值等)。
二者都破坏 Marqdo 的「代码即文档」。
### 1.2 答案
在 **`ext/web/web.mq.md`(英文)** 与 **`ext/web/网页.mq.md`(中文)** 中各提供一套 **`#` 类**:
- 作者只写**表** + **少量实例方法调用**;
- 表单元格保持**字面量**;
- **寻址字符串**由类方法解析;
- **导入英文文件 → 只用英文 API;导入中文文件 → 只用中文 API**(见 [stdlib-i18n.md](stdlib-i18n.md))。
### 1.3 硬约束(评审锁定)
| # | 约束 |
|---|------|
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
---
## 2. 作者心智与目录
```text
myapp/
index.mq.md # 入口 + 首页:页面表 +(可选)就地主体表 + 类方法 + listen
pages/ # 子页:同形的页面表(导出布局表或由入口再装配)
components/ # 可复用组件:导出与路径同名的 ##,体为 |属性|值|样式|
styles/ # 样式模块:每个样式一个 ##,体为 |属性|值|
db/ # 库:schema 表 +(可选)open/种子
data/ # sqlite 等运行时数据(gitignore)
```
| 表种 | 列 | 一句话 |
|------|-----|--------|
| **页面表** | `组件` \| `样式` | 本页用哪些组件、各套哪套样式 |
| **组件 / 主体表** | `属性` \| `值` \| `样式` | 前端属性 ↔ 取值(库字段或字面量)↔ 样式名 |
| **样式表** | `属性` \| `值` | CSS 声明 |
| **库结构表** | `字段` \| `类型` \| `可空` | schema |
---
## 3. 表内寻址约定(单元格仍是字符串)
单元格**不求值**。下列写法是 **web 扩展约定的路径文本**,由 `# 页面` / `# 样式` / `# 数据库` 的方法解析。
### 3.1 反引号与裸名
| 含义 | 写法 | 例 |
|------|------|-----|
| 要「去导入树 / 定义里解析」的名字 | 反引号 `` `名` `` | `` `nav` ``、`` `title` ``、`` `topnav` ``、`` `articles` ``(表名) |
| 字面量(文案、URL、CSS 属性名/值、SQL 类型、**列名**) | **裸**或 `"…"` | `首页`、`/about`、`font-size`、`integer`、`title`(作为列名时) |
### 3.2 路径形态(锁定)
| 场景 | 形态 | 例 | 方法内语义 |
|------|------|-----|------------|
| 引用导入模块的导出 | `模块.`导出`` | `nav.`nav``、`shell.`topnav`` | 在**站点入口模块**的 import 树上调用 `模块.导出`(零参 `##`),取回表 Value |
| 引用库字段 | `模块.`表`.列` | `articles.`articles`.title` | 模块名 = 命名空间(对应导入的 db 文件);`` `表` `` = 库表名;**列名裸写**(列不是变量)→ 运行时绑定 `表.列` |
| 前端属性名 | `` `title` `` | 组件表「属性」列 | 解析为字段名 `title` |
| 样式引用 | 同「模块.导出」或纯样式名 | `shell.`card-title`` | 取回 `|属性|值|` 表并编译为 CSS 类 |
**刻意不做的事:**
- 不把「组件变量名」魔法等同于「库表名」;
- 不要求作者写 `json.set` 才能把 `nav` 放进袋;
- 不把 `articles.`articles`.title` 做成语言级表达式。
### 3.3 与模块命名空间的关系
- 库名来自 frontmatter 导入(茎名或 `as`),**裸名**,见 [module-namespace.md](module-namespace.md)。
- `nav.`nav`` 中:前段 `nav` = 导入库名;`` `nav` `` = 该库上的 `## nav` 导出。
- 组件/样式文件应导出 **与路径第二段同名的 `##`**,直接返回表(不要 `## bag` / `## bind` 袋)。
---
## 4. 规范示例:`index.mq.md`(作者面唯一样板)
**语言与导入绑定(锁定,纠正手写混用):**
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|------|----------------|------------------|
| `> ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
| `> ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
禁止:`> ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
### 4.1 英文面(导入 `web.mq.md`)
```markdown
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
> ext/web/web.mq.md
> styles/shell.mq.md
> components/nav.mq.md
> components/side.mq.md
> components/foot.mq.md
> db/articles.mq.md
> db/index.mq.md as db
---
# main
`home` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
Main content is not a reusable component, so it is authored here.
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`store` = > db.open *
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1>" *
*`page` = > `page`.compose_components components=`home` *
*`page` = > `page`.compose_main main=`index` *
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
> `app`.listen
```
说明:表头列名可用中文(`组件`/`样式`/`属性`/`值`)——那是**表约定词汇**,不是库成员名;库成员必须与导入语言一致。
### 4.2 中文面(导入 `网页.mq.md`)
```markdown
---
title: 站点
> ext/web/网页.mq.md
> styles/shell.mq.md
> components/nav.mq.md
> components/side.mq.md
> components/foot.mq.md
> db/articles.mq.md
> db/index.mq.md as db
---
# main
`首页` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
主体不是可复用组件,因此就地撰写。
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`库` = > db.open *
*`页` = > 网页.页面 标题="站点" 引言="<h1>站点</h1>" *
*`页` = > `页`.组件装配 组件=`首页` *
*`页` = > `页`.主体装配 主体=`index` *
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
> `应用`.监听
```
**允许出现在 index 的非表内容:** frontmatter 导入、开库一行、构造页面/应用并装配、`listen` / `监听`。
**不允许:** `json.*` 袋、手写 `/_part` 注册、中英 API 混用。
---
## 5. 类 API(分文件 · 分语言)
依据 [stdlib-i18n.md](stdlib-i18n.md):**导入哪个文件,就用哪套名字。**
`ext/web/web.mq.md` = 全英文;`ext/web/网页.mq.md` = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但**对外导出的 `#` / `##` / 形参名必须是中文**。
### 5.1 页面 · `page` / `页面`
**英文(`web.mq.md`):**
```markdown
# page
+ `title`=…
+ `intro`=…
## compose_components
+ `components` # page table |组件|样式|
## compose_main
+ `main` # bind table |属性|值|样式|
```
**中文(`网页.mq.md`):**
```markdown
# 页面
+ `标题`=…
+ `引言`=…
## 组件装配
+ `组件`
## 主体装配
+ `主体`
```
| 行为 | 说明 |
|------|------|
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
### 5.2 样式 · `style` / `样式`
**英文:** `# style` · `## process` · `+ style=` / `name=` / `path=`
**中文:** `# 样式` · `## 样式处理` · `+ 样式=` / `名=` / `路径=`
页面装配可内部调用;作者一般不必在 index 显式调。
### 5.3 数据库 · `db` / `数据库`
完整**增删改查**;页面绑定、种子、`/admin`、表单提交共用。
**英文(`web.mq.md`):**
```markdown
# db
+ `url`=…
## init
+ `name`
+ `fields` # or table= schema
## insert
+ `table`
+ `rows`
## select
+ `table`
+ `where`=None # optional simple filters
+ `limit`=200
## get
+ `table`
+ `id`
## update
+ `table`
+ `id`
+ `row`
## delete
+ `table`
+ `id`
## exec
+ `sql`
+ `args`=None # escape hatch: raw SQL (not everyday authoring)
```
**中文(`网页.mq.md`):**
```markdown
# 数据库
+ `地址`=…
## 初始化
+ `数据库表` # 或 名= + 字段=
## 插入
+ `表`
+ `行` # 或 多行=
## 查询
+ `表`
+ `条件`=None
+ `上限`=200
## 获取
+ `表`
+ `id`
## 更新
+ `表`
+ `id`
+ `行`
## 删除
+ `表`
+ `id`
## 执行
+ `sql`
+ `参数`=None
```
| 中文 | 英文 | 职责 |
|------|------|------|
| 初始化 | `init` | 建表;登记表名 |
| 插入 | `insert` | 增 |
| 查询 | `select` | 查列表(可带简单条件 / limit) |
| 获取 | `get` | 按主键一行 |
| 更新 | `update` | 改 |
| 删除 | `delete` | 删 |
| 执行 | `exec` | 可选原始 SQL(进阶) |
`table=` / `表=` 接受表名或句柄;行数据优先 GFM 表。
**命名锁定:** 列表查询用 `select` / `查询`,**不用** `all`;原始 SQL 用 `exec` / `执行`,避免与 `select` 混淆。
### 5.4 应用 · `app` / `应用`
**英文:** `# app` · `## route` · `## static` · `## listen` · 形参 `page` `db` `admin` `host` `port`
**中文:** `# 应用` · `## 路由` · `## 静态` · `## 监听` · 形参 `页面` `数据库` `后台` `主机` `端口`
`listen` / `监听`:加载插件、注入 `db_url`、按页面 part 提供 `/_part/{id}`(首页)与 `{path}/_part/{id}`(`app.route` 页)、可选 `static` 目录挂载、启动 HTTP。作者不必手写 part 注册。
`static` / `静态`:`dir=`(或 `目录=`)+ 可选 `mount=`(默认 `/static`);`listen` 时用 `tower-http` 提供只读文件服务。
### 5.5 表单 · `form` / `表单`(规划锁定)
用户输入也走「表 + 类方法」,与页面/库同一心智;**提交最终调用 `# db` 的 insert/update**,不另开旁路。
**英文(`web.mq.md`):**
```markdown
# form
+ `table`=None # bound db table name (optional until submit)
+ `action`=insert # insert | update
+ `id`=None # required when action=update
## fields
+ `fields` # |字段|标签|类型|必填|默认|…
## validate
+ `rules`=None # |字段|规则|消息|… (optional extra rules)
+ `data` # submitted row / map
## render
# → HTML form (or form descriptor for page slot)
## submit
+ `data`
+ `db` # db handle
```
**中文(`网页.mq.md`):**
```markdown
# 表单
+ `表`=None
+ `动作`=插入 # 插入 | 更新
+ `id`=None
## 字段
+ `字段`
## 校验
+ `规则`=None
+ `数据`
## 渲染
## 提交
+ `数据`
+ `数据库`
```
#### 5.5.1 字段表(作者面)
```markdown
`文章表单` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | 标题 | text | true | |
| body | 正文 | textarea | false | |
```
| 列 | 含义 |
|----|------|
| `字段` | 对应库列名(裸名或 `` `列` ``,与 schema 对齐) |
| `标签` | 展示文案(字面量) |
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
| `必填` | 是否必填 |
| `默认` | 可选默认值 |
#### 5.5.2 校验表(作者面)
```markdown
`文章校验` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | 标题不能为空 |
| title | max:120 | 标题过长 |
| body | max:8000 | 正文过长 |
```
| 规则(初版) | 含义 |
|--------------|------|
| `required` | 非空 |
| `min:N` / `max:N` | 字符串长度或数值范围 |
| `email` / `url` | 格式 |
| `match:字段` | 与另一字段相等(如确认密码) |
| `in:a,b,c` | 枚举 |
schema 上的「可空 / 类型」在 **submit 时自动并入校验**(不必重复写 `required`,但校验表可覆盖消息)。
#### 5.5.3 行为流程
```text
render → 按字段表出 HTML(或嵌入 page 主区)
用户填写 → POST /_form/{id} 或同页提交
validate → 合并 schema + 校验表;失败则带回字段级错误、不写库
submit → action=insert → db.insert;action=update → db.update
→ 成功后刷新槽位或跳转(由 form 选项约定)
```
| 层 | 校验 |
|----|------|
| **服务端(必须)** | `validate` 在写库前执行;唯一可信边界 |
| **浏览器(可选增强)** | 同源规则可生成 `required`/`maxlength` 等 HTML 属性;**不能**替代服务端 |
`/admin` 的新建/编辑页 = 内置 form:字段来自 schema,校验来自类型/可空;与站点自定义 form **同一套** `validate` + `db.insert`/`update`。
#### 5.5.4 与页面的关系
- 表单可以是独立路由页,或页面表里的一个「组件」导出(仍用 `|属性|值|样式|` 描述展示,提交走 form 类)。
- **`page.compose_form id=… form=…`**:把 form 嵌入该页主区;`listen` 从首页与路由页收集表单并挂载 `/_form/{id}`(`app.mount_form` 仍可用)。校验失败时若表单有所属页,则带回该页壳重渲染。
### 5.6 文件职责
| 文件 | 内容 |
|------|------|
| `ext/web/web.mq.md` | 英文 `# page` `# style` `# db` `# form` `# app` |
| `ext/web/网页.mq.md` | 中文 `# 页面` `# 样式` `# 数据库` `# 表单` `# 应用`(可包装英文实现,**不得**把中文名写进 `web.mq.md`) |
---
## 6. 模块导出形状(配合寻址)
### 6.1 组件 `components/nav.mq.md`
```markdown
## nav
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | `nav`.`title` | |
| `href` | `nav`.`href` | |
**`nav`**
```
说明:组件**内部**绑定仍可用 `` `表`.`列` ``(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 `articles.`articles`.title` 分工:
- **跨文件、带导入命名空间** → `模块.`表`.列`;
- **组件文件内、表已明确** → `` `表`.`列` `` 即可。
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
### 6.2 样式 `styles/shell.mq.md`
每个样式一个 `##`,**禁止** `## bag` + `json.set`:
```markdown
## topnav
… |属性|值| …
**`topnav`**
## card-title
…
```
### 6.3 库 `db/articles.mq.md` / `db/index.mq.md`
- `articles`:`## schema`(或同名导出)返回结构表;
- `index`:`## open` → 确保插件、建库、init、幂等种子,返回 `# 数据库` 句柄。
---
## 7. 运行时职责划分
```text
作者 .mq.md 表(字面量单元格)
│
▼
ext/web 类方法(Marqdo)
│ 解析路径;需要时经 ABI host_query
│ 调用入口模块 import 树上的 lib.member
▼
plugins/web(HTTP / SQL / HTML 壳)
│
▼
浏览器:四区布局 + /_part 局部刷新 + /admin(可选)
```
| 层 | 做 | 不做 |
|----|----|------|
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
**实现要点(评审通过后再做):**
1. ABI `host_query("call_lib_path")`:在**站点入口模块**上执行 `lib.member`;
2. 插件函数由类方法调用(如 compose_components / compose_main);
3. `listen` 合并页面内 part,注入 `db_url`。
---
## 8. 全部废弃 · 从头开发(锁定)
**旧有网络扩展库内容一律作废**,包括但不限于:
| 范围 | 处理 |
|------|------|
| [`plugins/web/`](../../plugins/web/) | 评审通过后**删除或清空**,按本文重写 cdylib |
| [`ext/web/`](../../ext/web/)(`web.mq.md` / `网页.mq.md` / templates) | 同上,**不**在旧 L1 上打补丁 |
| 依赖旧 API 的示例(如当前 `examples/web-site`、`web-demo`、`man-write-site` 可跑胶水版) | 按 §4 规范重写或暂时移除 |
| 依赖旧 API 的 gold / 单测 | 删除后按新 API 重写 |
| 本文之前的袋式 / assemble / wire / `## bag` 等作者面 | 永久移出正典 |
**禁止**:在遗留代码上「修到能跑」再文档化。
**允许**:实现时参考旧代码中的 HTTP/SQLite 技术经验,但**新树另起**,不以 ABI 表面或作者面兼容为目标。
历史摸索中明确不再回归的作者面模式:
- `json.parse` / `json.set` 拼 components/styles 袋;
- 手写 `web.assemble` + 袋参数;
- 手写 part JSON + `` `app`.part ``;
- `|前端变量|后端数据库|` 填路由;
- 「变量名即表名」魔法默认表;
- 样式 `## bag`;掏空 index 只留 `wire.boot`。
---
## 9. 非本波次(可记入路线图)
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
- 复杂权限与多租户;
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
---
## 10. 评审清单
请确认或批注:
1. **§3 路径**:`模块.`导出`` 与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内 `` `表`.`列` `` 是否保留?
2. **§4 index**:开库是否允许单独一行 `` db.open ``,还是必须进一步藏进 `web.应用`?
3. **§5 分文件**:英文 `web.mq.md` / 中文 `网页.mq.md` 是否严格分语言、禁止混排?
4. **§5.3**:列表查询用 `select` / `查询`、原始 SQL 用 `exec` / `执行` 是否认可?
5. **§5.5 表单/校验**:字段表、校验表、服务端必校、admin 共用是否认可?
6. **§5 槽位**:仅由组件导出名推断,是否足够?
7. **§8 废弃**:是否确认**全部推倒重来**、不兼容旧实现?
评审通过后:冻结本文为 Accepted → **清空旧 web 扩展代码** → 按本文从零实现(骨架 → db CRUD/`select` → form/validate → 页面装配 → app listen → 规范示例 → gold)。
+2 -2
View File
@@ -4,9 +4,9 @@
|---|---|
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
---
## 决策
+2 -2
View File
@@ -36,7 +36,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
### 3.1 字面量 / 逻辑关键字(词法保留)
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
| 英文 | 中文(提案) | 备注 |
|------|--------------|------|
@@ -107,7 +107,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
---
+3 -5
View File
@@ -11,7 +11,7 @@
## 1. 设计原则
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
@@ -43,8 +43,6 @@
| `str` | `文本` | 转为显示文本 |
| `int` | `整数` | 转为整数 |
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
形参别名:
| 英文 | 中文 | 用于 |
@@ -73,9 +71,9 @@
*`n` = 1*
1. `n` > 0
+ `n` > 0
> print text=positive
2. *
+ *
> 打印 内容=other
```
+52 -182
View File
@@ -1,11 +1,11 @@
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 日期 | 2026-08-07 |
| 取代 | 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) · [module-namespace.md](module-namespace.md) |
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
| 日期 | 2026-08-04 |
| 取代 | v0 中「`**`=输出、`*`=返回」 |
| 相关 | [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,13 +15,8 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
1. `.mq.md`:打开即文档,运行即程序。
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
**豁免:**
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**;字符串须 `"…"` 或 `'…'`;`` `名` `` 仍合法。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
---
@@ -34,26 +29,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
---
## 3. 映射总表(v0.2)
## 3. 映射总表(v0.1)
| 标记 | 语义 |
|------|------|
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
| `#` … `######` | 函数;层数 = 作用域 |
| 函数头下 `-` 纯名 | 形参 |
| 体内 `-` | 循环 |
| 体内 `+` 或 `1.` | 分支 |
| 分支臂头整行恰为 `*` | else |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
| frontmatter `> path.mq.md` | 跨文件导入 |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
@@ -63,23 +55,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| ` ```lang ` | 外联异种代码 |
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
### `+` / `-` / `1.` 消歧
| 位置 | `+` | `1.` … | `-` |
|------|-----|--------|-----|
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
### 输出不是架构
| 错误(旧) | 正确(v0.2) |
| 错误(旧) | 正确(v0.1) |
|------------|--------------|
| `**Hello**` 表示打印 | `> print text=Hello` |
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
| `- 谁` 作形参 | `` + `谁` `` |
| `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` |
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
| 输出与返回抢粗体 | 粗体只表示 **返回** |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
@@ -90,27 +72,22 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
### 程序语句(斜体)
```markdown
*x = 1*
*y = x + 2*
*answer = ev[^message]*
*`亦可用` = 1*
*`x` = 1*
*`y` = `x` + 2*
```
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
## 加一
+ `n`
# 加一
- n
**n + 1**
**"ok"**
**`n` + 1**
```
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
### 输出(内置函数 `print`)
```markdown
@@ -121,7 +98,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
### else 与斜体消歧
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
- 分支臂**第一行整行只有一个** `*` → else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
@@ -129,18 +106,14 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
## 5. Frontmatter 与跨文件
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
---
## 6. 对象、函数、形参
## 6. 函数、作用域、提升
- `# Name`:对象(构造体);`# main` 为入口对象。
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
- `##` / `###` …:函数或方法;挂在对象下则为方法。
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
规则同 v0。推荐:
```markdown
# main
@@ -148,162 +121,53 @@ 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**(无转义,按字面量) |
### 双引号字符串(复杂文本)
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
```markdown
> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
```
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | `\` |
| `\"` | `"` |
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
---
## 8. 分支与循环
分支(**有序列表** `1.` `2.` …),循环(`-`):
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
```markdown
*`x` = 0*
1. `x` > 0
+ `x` > 0
> print text=正数
2. `x` < 0
+ `x` < 0
> print text=负数
3. *
+ *
> print text=零
```
```markdown
*`bool_value` = True*
1. `bool_value` == True
> print text=True
2. *
> print text=False
```
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
```markdown
1. `a`
> print text=A
2. *
> print text=not-A
1. `b`
> print text=B
2. *
> print text=not-B
```
上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。
```markdown
- [果](篮子)
> print text=今天吃`果`
```
反引号形式等价:`` - [`果`](`篮子`) ``。两侧可混用。
`while`:
```markdown
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
```
---
## 9. 集合(表格)
`` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)):
| 形状 | 值 |
|------|-----|
| **1 列**(竖表) | `List`(表头 = foreach 元素名,不进入元素) |
| **≥2 列 + 1 行数据**(横表) | `Map`:键 = 表头,值 = 该列标量 |
| **≥2 列 + ≥2 行数据** | `Map`:键 = 表头,值 = 该列 `List`(列向) |
| **≥2 列 + 0 行数据** | `Map`:键存在,值为空列表 |
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
| 重复表头 | 诊断错误 |
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
```markdown
*`k` = secret *
`cfg` =
| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |
```
行向示例:
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
*`名` = `订单`[^1][^品名] *
```
**脚注取元**(表达式级;可链式):
```markdown
*`第一` = 篮子[^1] * # 基名可省略反引号(`[^` 已标明取元)
*`种` = 分类[^苹果] *
*`第一种苹果` = 货架[^苹果][^1] *
*`亦可用` = `分类`[^苹果] * # 反引号形式并存
```
- **List**:标签须为纯数字(1-based);`[^0]` / 越界 → 报错。
- **Map**:标签为键文本(含 `"00"` 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 `[^1]` 当成「第 1 个条目」。
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
同 v0。`` `篮子` = `` 后接 GFM 表。
---
@@ -312,19 +176,21 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
1. 加载 `index.mq.md` + 导入。
2. Pass1 收集定义。
3. Pass2 执行 `# main`。
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
---
## 11. 函数体结束(`---` / `***` / 空返回)
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
- 谁
> print text=Hello `谁`!
@@ -333,16 +199,20 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| 约定 | 说明 |
|------|------|
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
---
## 12. v0.2 非目标
## 12. v0.1 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- `+` 作分支、`+`/`-` 作形参(**不保留**)
- 用 `*` 作无序列表符
---
-266
View File
@@ -1,266 +0,0 @@
# 模块命名空间(import / 点号寻址)
| | |
|---|---|
| 状态 | **Accepted;M1+M2 已落地** |
| 日期 | 2026-08-07 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
---
## 1. 动机
今日加载器把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**(`merge_top_level`)。
后果:
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存;import 顺序决定谁赢,错误表现为「缺 `pattern`」这类误导信息。
- `lib/writeback` 的 `get` 盖住 `lib/json` 的 `get`。
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
**结论**:Marqdo 必须支持**模块命名空间**与**点号寻址**。扁平静默覆盖不是可保留的「兼容糖」,而是会**掩盖冲突**的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。
---
## 2. 目标与非目标
### 2.1 目标
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
2. **点号寻址调用**:`库.成员`、并预留 `库.对象.成员` 等多段路径;`.` 表示在定义树上的寻址,不是字段运算。
3. **库名不是变量**:寻址段为**裸标识符**,**不加**反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
4. **模块内名字默认不进全局**;需要本地短名时必须**显式** `use`,且冲突**报错**。
5. **中英对等**:路径中英分文件;`as` / `作为` 与默认库名规则双语一致。
### 2.2 非目标
- 第三方包管理 / 版本求解。
- 在兼容期内继续支持扁平合并旧语义。
- 「裸名仍可从最后一次导入解析」——**明确拒绝**。
- 把库名写成 `` `time`.parse ``——**明确拒绝**(会把库名误当成变量)。
---
## 3. 核心语义
### 3.1 模块 / 库
每个可导入的 `.mq.md` 文件是一个**库模块**:
| 内容 | 归属 |
|------|------|
| 顶层 `##` 自由函数 | 库根下的**函数** |
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
| 类型下的 `##` 方法 | 该对象节点下的**成员函数**(可被路径寻址;实例调用见 §4.4) |
| 被导入文件的 `# main` | **不**作为入口执行 |
### 3.2 导入句法(frontmatter)
| 英文 | 中文 | 含义 |
|------|------|------|
| `> lib/time.mq.md` | `> lib/时间.mq.md` | 导入;默认库名见 §3.3 |
| `> lib/time.mq.md as time` | `> lib/时间.mq.md 作为 时间` | 导入并以给定库名绑定 |
规则:
- `as` / `作为` 后为**裸库名**(不加反引号)。
- 同一文件内两个导入不得绑定同一库名 → 硬错误。
- 禁止「只写路径、成员洒进全局」的旧语义。
### 3.3 默认库名
省略 `as` / `作为` 时,库名 = **文件名茎**(去掉 `.mq.md`):
| 路径 | 默认库名 |
|------|----------|
| `lib/time.mq.md` | `time` |
| `lib/时间.mq.md` | `时间` |
| `ext/ai/agent.mq.md` | `agent` |
| `ext/ai/智能体.mq.md` | `智能体` |
### 3.4 调用解析顺序
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
2. **当前文件**顶层 `#` / `##`(无点号的短名)。
3. **L0 内置**。
4. **插件注册名**(`lib/plugin` 加载后的全局表)。
5. 否则 → 未知 callee。
---
## 4. 点号寻址(核心外形)
### 4.1 文法
```text
path_callee ::= ident ('.' ident)+
```
- 每一段都是**裸标识符**(库名、类型名、函数名)。
- **整条路径都不使用反引号**。
- `.` 只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。
### 4.2 二段:`库.成员`
```markdown
---
> lib/time.mq.md
> lib/json.mq.md
---
# main
*`t` = > time.now_unix *
*`s` = > time.format unix=`t` pattern=%Y-%m-%d *
*`obj` = > json.parse text={"a":1} *
*`a` = > json.get value=`obj` key=a *
> print text=`s`
```
| 路径 | 解析 |
|------|------|
| `time.now_unix` | 库 `time` → 函数 `now_unix` |
| `json.parse` | 库 `json` → 函数 `parse` |
| `agent.agent` | 库 `agent` → **类型** `agent`(构造) |
库根下的函数调用**不**注入 `self` / `自`。
### 4.3 三段及以上:`库.对象.成员`(预留并锁定语义)
后续常见形态:
```markdown
> agent.agent # 库 → 类型:构造
> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员
```
解析规则(锁定):
1. 第一段必须是**已导入库名**。
2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。
3. 若最终落在**函数**上则发起调用;若落在**类型**上则发起构造。
4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。
实例方法若需要接收者,仍走 §4.4;`库.对象.方法` 表示定义树上的该成员(无接收者时:仅当该成员可作为无 `self` 的关联函数调用,否则报错「需要实例」)。这样 `.` 始终是**定义寻址**,逻辑一致。
中文库同理:`时间.格式化`、`智能体.智能体`、`智能体.智能体.单步`(若对类型成员做路径调用)。
### 4.4 变量 / 实例 vs 库路径(反引号分界)
| 写法 | 左侧重 | 是否反引号 |
|------|--------|------------|
| `time.parse` | 库名(绑定) | 路径段皆**裸名** |
| `agent.agent` | 库名.类型名 | 裸名 |
| `` > `助手`.step `` | **变量**(实例句柄) | 接收者**必须**反引号 |
| `` > `out`.… `` | 变量 | 反引号 |
原则:
- **名在定义/导入空间里** → 点号路径,无 `` ` ` ``。
- **名在值环境里**(绑定结果、形参、`self`)→ 反引号标识符;方法调用保持现有 `` > `obj`.method ``。
禁止混写 `` > `time`.parse ``(把库当成变量)。
### 4.5 应用侧完整示例
```markdown
---
> lib/time.mq.md
> lib/writeback.mq.md
> ext/ai/agent.mq.md
---
# main
*`助手` = > agent.agent model=… tools=… *
*`out` = > `助手`.step task=… *
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
```
(上例假定 `json` 已导入;`stringify` 为该库成员。)
---
## 5. 导出面
默认:库内顶层 `#` / `##` 均可被路径访问。
类型下的 `##` 挂在该类型节点下,供 `库.类型.成员` 寻址;实例调用仍用 `` `变量`.成员 ``。
本版不引入 `private`。
---
## 6. 显式 `use`(可选短名,非静默兼容)
| 英文 | 中文 |
|------|------|
| `> use time.format` | `> 使用 时间.格式化` |
| `> use time.format as fmt` | `> 使用 时间.格式化 作为 fmt` |
- `use` 右侧为**点号路径**(裸名寻址)。
- 引入后本地短名可见;与导入库名或当前文件顶层同名 → **硬错误**。
- **禁止** `use time.*`(无通配 `use`)。
---
## 7. 与旧行为的关系(破坏性变更)
| 旧 | 新 |
|----|----|
| 导入 = 合并进全局 | 导入 = 绑定库名 |
| 同名后写覆盖 | 无跨库扁平同名 |
| `> parse` 来源不明 | 必须 `json.parse` 或显式 `use` |
| (若曾设想)`` `time`.parse `` | **否**;库路径不加反引号 |
不提供扁平合并过渡开关。
---
## 8. 对分层与 ext 的影响
| 层 | 影响 |
|----|------|
| L0 内置 | 仍为全局短名 |
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,**不得**塞进 `HostFn` |
**硬规则**:不得为「方便」把 `ext/ai` 领域能力写进 `src/host/dispatch.rs` / `src/host/*.rs`。标准库可走 `lib/*` → 薄 `host_*`;智能体专属走 `plugins/agent` 注册名(见 [ext-agent.md](ext-agent.md) §4)。
---
## 9. 实现要点
1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 `merge_top_level` 泼洒。
2. 调用方解析 `path_callee`:按 `.` 分段,自导入表下行。
3. 区分路径 callee 与 `` `变量`.方法 ``(词法:首段是否反引号 / 是否含裸点号路径)。
4. 金样例与 stdlib 文档改为 `time.parse` 形态。
| 阶段 | 内容 |
|------|------|
| M0 | 本文 Accepted(含本修订) |
| M1 | 二段路径 `库.成员` + 破坏旧扁平 — **已落地**(tree + bytecode;`as`/`作为`;stdlib/ext/tests 已迁) |
| M2 | 三段 `库.对象.成员`;`use` / `使用` — **已落地**(实例方法路径调用报错,须 `` `var`.method ``) |
| M3 | 诊断工具(可选) |
**双后端**:tree 与 bytecode 均支持点号路径调用与 `use` / `使用`(与 M1/M2 同语义)。
**金样例**:
| 路径 | 测什么 |
|------|--------|
| `tests/structure/ns/` | 二段/三段路径、`use`、导入 `as` |
| `tests/errors/ns-instance-method.mq.md` | `库.类型.方法` 无接收者 → 硬错误(须 `` `var`.method ``) |
**L1 薄包装**:命名空间下 `net.http_post` 等解析到 **`lib/*.mq.md` 的 `##` 包装**,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:`headers` 未传到 `host_http_post`)。规则见 [stdlib-modules.md](stdlib-modules.md) §2.1。
---
## 10. 决议摘要
1. 导入绑定**库名**;成员不进全局。
2. 调用以**裸名点号路径**寻址:`库.成员`,并支持 `库.对象.成员`;`.` = 定义树寻址。
3. **库名 / 路径段不加反引号**;反引号只用于值变量与实例接收者。
4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 `use`。
5. M1/M2 已实现;M3 另开。
-104
View File
@@ -1,104 +0,0 @@
# 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. 继承(`# 子类 = > 父类`)
```markdown
# Greeter
## hello
+ `who`
*`msg` = "Hello, `who`!" *
**`msg`**
# Loud = > Greeter
## hello
+ `who`
*`msg` = "HELLO, `who`!" *
**`msg`**
```
| 规则 | 说明 |
|------|------|
| 语法 | `# Child = > Parent`(右侧必须是 `>` + 简单类型名;无路径) |
| `_type` | 构造后仍为**最具体子类名** |
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
| 构造 | **不**隐式调用父构造(无 auto-super)。需要父字段时在子类正文首行显式 `` `self` = > Parent … ``,再改字段并 `**`self`**`;返回 map 的 `_type` 仍为子类名 |
| 多继承 | 不支持 |
| 诊断 | 未知基类、循环继承、非法 RHS(如 `# Foo = 1`) |
详见 [object-inheritance.md](../roadmap/object-inheritance.md)。
## 6. 非目标(本波)
- 接口 / 可见性 / 多继承
- 无 `_type` 的「鸭子」方法分发
- 用表格声明字段 schema(表格仍表示数据集合;见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md))
## 7. 迁移摘要
| 旧 | 新 |
|----|----|
| 库顶层 `# http_get` | `## http_get` |
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
-482
View File
@@ -1,482 +0,0 @@
# Marqdo 的 OKF 实现
| | |
|---|---|
| 状态 | **Accepted(规范);实现分层见 §10** |
| 日期 | 2026-08-07 |
| 调研 | [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
| 命令现状 | [catalog-cli.md](catalog-cli.md)(v0 已落地) |
| 生成式清单方向 | [generated-yaml-manifest.md](generated-yaml-manifest.md) |
| 智能体消费面 | [ext-agent.md](ext-agent.md) · [ext-agent-plan.md](ext-agent-plan.md) · 任务知识包见本文 §7 |
| 外部规范 | [OKF SPEC v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
本文是 **Marqdo 语言侧 OKF 实现的详细设计**:界定我们借鉴什么、已经实现什么、下一阶段必须补什么。
**不把 Google OKF 整本照搬进语言语义**;Marqdo 的可执行真相永远是 `.mq.md` 源。
---
## 1. 定位
### 1.1 OKF 是什么(对我们)
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) 用 **目录中的 Markdown + YAML frontmatter** 表示可交换知识:概念一页一文、路径即 ID、链接成图、最小强制面(几乎只强制 `type`),并在 v0.2 加入信任信号。
Marqdo 对齐的判断是:
> 人类可读的 Markdown 可以成为人与 Agent 的一等交换面;**程序本身也应能投影成同一形态的知识包**。
### 1.2 Marqdo 多走的一步
| | OKF(通用知识) | Marqdo |
|--|-----------------|--------|
| 正文 | 自由散文 | **可执行语法**(`.mq.md`) |
| 成功标准 | 互通、可策展、可信任 | 能跑 + 能读 + 可被 Agent 索引 |
| 清单角色 | 知识本身 | **从源派生的投影**(非第二套权威配置) |
一句话:
**OKF 形、Marqdo 义 — 形态对齐 OKF;词汇与生命周期服务模块、依赖、任务技能与信任,而不是 BigQuery 业务概念表。**
### 1.3 三层文档(勿混)
| 层 | 谁写 | 是什么 |
|----|------|--------|
| **源** | 人 / 编码 Agent | `.mq.md`:唯一语义权威,打开即读、即可跑 |
| **工程目录包** | `marqdo catalog` | 模块依赖/导出总览(`Marqdo Module`) |
| **任务知识包** | `plan` 晋升等 | 任务↔技能↔可执行资源(`Marqdo Task` / `Marqdo Agent Skill`) |
`marqdo view output` 出 HTML 站点,与 OKF 包**分工**:人读程序站 vs Agent/工具读知识包。见 [view.md](view.md)、[catalog-cli.md](catalog-cli.md) §4。
---
## 2. 设计原则(锁定)
1. **源为唯一权威** — 依赖、导出、可执行行为以 `.mq.md` 为准;知识包是提取或晋升结果。
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一工程目录包(时间戳字段可规范化忽略)。
3. **勿手改生成物** — 文件头 / `generated` 标明 GENERATED;手改不被承认为权威。
4. **最小强制面** — 互通只要求:合法 frontmatter、`type` 字段、可解析的 `resource` / 链接;未知 `type` **必须优雅降级**(仍可读正文与已知字段)。
5. **格式而非平台** — 包可 `cat` / `git clone`;不绑定某一云或某一模型。
6. **清单可删可再生** — 无 catalog 时解释器仍能直接从源工作;catalog **不是**语言语义的一部分。
7. **可执行资源显式** — 凡声称「可跑」的概念必须有 `resource:` 指向 `.mq.md`(或等价路径),禁止只靠散文描述冒充程序。
---
## 3. 概念模型
### 3.1 Bundle(知识包)
一个 OKF 风格 bundle 是目录树:
```text
<bundle-root>/
index.md # 可选:人/Agent 总览
log.md # 可选:变更史(策展用)
catalog.yaml # 可选:机器向总清单
concepts/… # 或 modules/…:概念页(frontmatter + Markdown)
resources/… # 可选:被引用的可执行 .mq.md(任务包常用)
```
**Concept ID** = 相对 bundle 根、去掉扩展名的路径(OKF 惯例)。
例:`concepts/tasks/a1b2c3d4e5f6.md` → ID `concepts/tasks/a1b2c3d4e5f6`。
**联系** = frontmatter 中的路径字段 + 正文中的 Markdown 链接,形成可遍历图。
### 3.2 Marqdo 使用的两类 bundle
| Bundle | 默认根 | 生产者 | 消费者 |
|--------|--------|--------|--------|
| **工程目录包** | `.marqdo/`(`-o` 可改) | `marqdo catalog` / `sync` | 人、CI、未来编译加速、通用 Agent |
| **任务知识包** | `.marqdo/agent-kb/` | `ext/ai` 的 `plan` 晋升等 | 父智能体快路径、策展、复用 |
二者词汇共享(`type` / `generated` / `verified` / `status`),目录职责分离:
**不要**把探索用的 `agent-runs/` 时间戳文件当成稳定概念 ID。
---
## 4. Frontmatter 词汇表
### 4.1 所有概念页的公共字段
| 字段 | 必填 | 含义 |
|------|------|------|
| `type` | **是** | 概念类型字符串(见 §5) |
| `title` | 推荐 | 短标题 |
| `description` | 可选 | 一句话说明 |
| `tags` | 可选 | 字符串列表 |
| `resource` | 视类型 | 指向权威源或可执行 `.mq.md` 的相对路径 |
| `status` | 推荐 | `draft` \| `stable` \| `deprecated` |
| `generated` | 生成物必有 | `{ by, at? }` — 谁生成 |
| `verified` | 可选 | `{ by, at? }` — 谁核验(非 LLM 口述) |
| `sources` | 可选 | 出处列表(OKF v0.2) |
| `stale_after` | 可选 | 绝对日期,过期后消费者应降级信任 |
| 未知字段 | — | **保留、不拒绝** |
信任档位(推导,不必单独存字段):
| 条件 | 档位 |
|------|------|
| 无 `verified` | 未验证(机器生成草稿) |
| 有 `verified.by` 为确定性工具(如 `marqdo-agent/spawn`) | 机器确认 |
| 有人工审核约定(未来) | 人工审核 |
### 4.2 工程模块页额外字段(v0 已用)
| 字段 | 含义 |
|------|------|
| `depends` | 导入列表(从源 frontmatter `> path` 提取) |
| `exports` | 顶层 `#` 导出名列表 |
### 4.3 任务 / 技能页额外字段(目标词汇)
| 字段 | 所在 type | 含义 |
|------|-----------|------|
| `skill` | `Marqdo Task` | 指向 Skill 概念页的相对路径 |
| `goal` 或正文中的规范化 goal | `Marqdo Task` | 匹配材料(规范化规则见 §7.3) |
| `llm_free` | `Marqdo Agent Skill` | 资源是否仍含 `agent.step` / LLM 调用(机器启发) |
| `quality` | `Marqdo Agent Skill` | 整数启发分(长度、llm_free 等),**非**模型打分 |
---
## 5. `type` 注册表(Marqdo 义)
未知 type **不得**导致解析失败;工具可跳过专用逻辑,仍展示 title/正文/链接。
| `type` | 状态 | 含义 | 主要生产者 |
|--------|------|------|------------|
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
| 其他 | 开放 | 第三方/未来扩展 | — |
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
---
## 6. 工程目录包(v0 — 已实现)
### 6.1 CLI
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # 别名
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或单文件;目录则递归 `*.mq.md` |
| `-o` | `.marqdo` | 输出根;写入前创建,**覆盖**同名生成文件 |
实现:[`src/catalog.rs`](../../src/catalog.rs)。金样:`tests/gold.rs` → `catalog_writes_yaml`、`catalog_includes_agent_kb_concepts`。
### 6.2 生成物布局
```text
OUT_DIR/
catalog.yaml
index.md
modules/
<path-with-__>.md
concepts/ # O3:从 **/.marqdo/agent-kb/concepts/ 复制
tasks/…
skills/…
```
路径拍扁:`structure/import/main.mq.md` → `modules/structure__import__main.md`。
`agent-kb` 下的可执行 `.mq.md` **不**进 Module 表(避免与概念/资源重复);Task/Skill 概念页进 `concepts/` 与 `catalog.yaml` 的 `concepts:`。
### 6.3 `catalog.yaml`(现行字段)
```yaml
# GENERATED by marqdo — do not edit by hand
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/<crate-version>
modules:
- id: structure/hello # resource 去掉 .mq.md
resource: structure/hello.mq.md
title: … # 源 frontmatter title,否则用路径
imports: [] # 或 ["lib/x.mq.md as x", …]
exports:
- name: Hello World
kind: fn
# 可选(源 frontmatter 有则透传):
# verified: { by: … }
# sources: […]
concepts: [] # 或 Task/Skill 条目(O3)
# - id: concepts/tasks/<sig>
# type: Marqdo Task
# title: …
# status: …
# page: concepts/tasks/<sig>.md
# resource: …
# skill: …
```
提取规则:
- **imports**:源文件 YAML frontmatter 中以 `>` 开头的导入行(经 `parse_import_spec`)。
- **exports**:解析成功则用 AST 顶层函数名;否则回退扫描 `# ` 标题行。
- **verified / sources**:源 frontmatter 有则写入 module/concept 条目(O3)。
- **concepts**:扫描 `**/.marqdo/agent-kb/concepts/**/*.md`,复制到 `OUT_DIR/concepts/`。
- **不**提取正文 `>` 动态调用图、不写锁哈希、不写跨仓 URL。
### 6.4 模块概念页(现行)
```yaml
---
type: Marqdo Module
title: …
resource: path/to/file.mq.md
depends: […]
exports: […]
generated:
by: marqdo/<version>
# verified / sources:源有则透传
---
```
正文含「勿手改」、**可点击依赖链接**(解析到同包其它 Module 页)、导出表。`index.md` 含 Modules 表与 **Agent knowledge** 节(链到 `concepts/`)。
### 6.5 仍相对完整 OKF 愿景的缺口
| 缺口 | 说明 |
|------|------|
| 无通用 Concept ID 遍历 API | catalog 为生成物;无独立查询命令 |
| 无 `stale_after` / Attested 再现 | 信任信号仅可选 `verified`/`sources` |
| 无 `log.md` | 无策展历史(O4) |
| 运行时不读 catalog | 解释器不依赖生成物(有意为之) |
O2/O3 已补:Task/Skill 知识包、catalog 扫入 agent-kb、模块页可点依赖、可选信任字段。
---
## 7. 任务知识包(规范 — 实现路线 O2)
服务「父智能体优化过的工作簿,同任务应直接执行」:把子 Marqdo / 技能登记为 OKF 概念,用 ID 与链接匹配,而不是私有 `index.json`。
### 7.1 布局(锁定)
```text
.marqdo/
agent-runs/workbook-<slug>-<ts>.mq.md # 仅当显式 workbook_dir= 时(可 gc)
agent-kb/ # 任务知识包 bundle(默认首次 plan 就写这里)
index.md
log.md # 可选
catalog.yaml # 可选;可由 promote 或 catalog 刷新
concepts/
tasks/<slug>.md # type: Marqdo Task;sig 在 frontmatter
skills/<slug>.md # type: Marqdo Agent Skill
resources/
<slug>.mq.md # 默认可执行工作簿(探索与晋升同一路径)
```
默认根可通过 `plan` 参数 `kb_dir` / `知识库目录` 覆盖。`.gitignore` 已忽略 `**/.marqdo/`。
路径用可读 **slug**(由 goal 派生:拉丁小写、CJK 保留、其它变 `-`,最长约 48 字符)。**`sig` 仅写在 frontmatter**,用于精确匹配。同 slug 异 sig 时用 `slug-<sig前4位>`。旧包若仍以 `<sig>` 为文件名,lookup 会回退识别。
### 7.2 概念页模板
**Task**(匹配入口):
```yaml
---
type: Marqdo Task
title: <短摘要>
description: <规范化 goal>
sig: <12hex>
status: stable
tags: [agent-task]
skill: ../skills/<slug>.md
generated:
by: marqdo-agent/plan
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Task
See [skill](../skills/<slug>.md).
```
**Skill**(可执行绑定):
```yaml
---
type: Marqdo Agent Skill
title: <短名>
sig: <12hex>
resource: ../../resources/<slug>.mq.md
status: stable | candidate
llm_free: true | false
quality: <int>
hits: <int>
generated:
by: marqdo-agent/plan
at: <ISO8601>
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Skill
Prefer spawning `resource` over re-planning.
```
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
### 7.3 任务签名 → Concept 路径
材料:
1. `goal`:Unicode NFC → trim → 连续空白折叠为单空格。
2. 若调用方工具表非空:工具名排序后追加进材料。
3. **不**把父 `standing` 计入签名(易变导致永不命中)。
输出:稳定短哈希 `sig`(`agent_goal_sig`)+ 可读 `slug`(`agent_goal_slug`)。路径:
- `concepts/tasks/<slug>.md`
- `concepts/skills/<slug>.md`
- `resources/<slug>.mq.md`
匹配顺序:
1. **精确**:slug 试探 + frontmatter `sig` → 扫目录 `sig:` → 旧 hex 文件名。
2. **别名(Accepted)**:精确 miss 后,扫 Task FM `aliases:`(YAML 列表或 `[a, b]`);`normalize_goal(query)` 与某条 alias **精确相等**则命中同一 Skill/resource。lookup 返回 `match: exact|alias`;`plan` 对 alias 写 `cache=soft-hit`。
3. **规范句(Accepted)**:仍 miss 时对 goal 做轻量 `agent_kb_canonicalize`(剥站立前缀、去尾标点),再精确/别名各试一次;命中返回 `match: canonical`,`cache=soft-hit`。
4. **近义(Accepted,默认开)**:仍 miss 且 `near_match=True` 时,对 Task `title|description|aliases` 做本地**字符 bigram 词袋 + 余弦**;`best.score >= near_threshold`(默认 `0.78`)则 `match: near` 并带 `score`,`cache=soft-hit`,并可 `agent_kb_add_alias`。这是稀疏词法近邻,**不是** embedding 模型。
5. **父裁决 soft_match(Accepted,默认关)**:仍 miss 且 `plan soft_match=True` 时,把 `agent_kb_near_match` 排序候选(含 score;空则退回 `list_tasks`)交给父模型:`DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`;REUSE 后可 `agent_kb_add_alias`。
6. **不做**默认 dense embedding / 远程向量库。远期 dense 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E。
`agent_kb_promote` 可选 `aliases=`(字符串或列表)写入 Task;再晋升时合并既有 aliases。
### 7.4 与 `## plan` 的契约
| 参数 | 默认 | 含义 |
|------|------|------|
| `reuse` / `复用` | `True` | 允许知识包快路径 |
| `optimize` / `优化` | `False` | 跳过知识包,强制再规划 |
| `force` / `强制` | `False` | 忽略知识包 |
| `soft_match` / `软命中` | `False` | miss 后父裁决 REUSE/NEW(须显式打开;候选为 near 排序列表) |
| `near_match` / `近义命中` | `True` | lookup 第四趟本地 n-gram;`False` 关闭 |
| `near_threshold` / `近义阈值` | `0.78` | near 自动命中最低余弦分 |
| `promote` / `晋升` | `True` | DONE 后固化并写入/更新概念与 resource |
| `kb_dir` / `知识库目录` | `.marqdo/agent-kb` | bundle 根 |
| `workbook_dir` / `工作簿目录` | `None` | 默认直接写 `kb_dir/resources/<slug>.mq.md`;显式传入则用该目录下的临时 `workbook-<slug>-<ts>.mq.md` |
| `improve_every` / `改进周期` | `3` | candidate 每 N 次命中触发 ≤1 轮改进 |
| `explore_n` / `探索次数` | `3` | 同任务已有文件数 `< N` 且非 `llm_free` 时,强制新建 `explore/<slug>/<k>.mq.md` 尝试不同路径(第 2 次默认 dual 骨架) |
调用示例(路径可直接写在参数里,无需 `json.parse`):
```markdown
> `助手`.plan goal=… max_rounds=3
> `助手`.plan goal=… workbook_dir=".marqdo/agent-runs"
> `助手`.plan goal=… explore_n=3
```
快路径:
1. lookup 命中且 resource **llm_free**(含现场检测已固化源)→ spawn → `cache=hit`,**父 LLM 不调用**。
2. 否则若任务相关文件数 `< explore_n` → 写入新的 explore 变体,父 LLM 被提示尝试不同路径;成功则固化并晋升。
3. 否则走 candidate 命中 / `improve_every` 改进逻辑。
`DECISION: DONE` 时先 `agent_workbook_solidify`(把仍含 `worker.step` 的簿固化为 `# main` **返回**答案,而非仅 `print`),再晋升并写 `verified`。
显式 `workbook=` 续跑优先于知识包查找。
质量启发(覆盖 skill 时,不调模型):`llm_free` 优先;源更短优先;同质取较新。更差 `quality` 不覆盖现 skill。
### 7.5 自我成长如何落在 OKF 上
| 能力 | 机制 |
|------|------|
| 优化 | 规划循环固化代码 → 更优 `resources/<slug>.mq.md` |
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
---
## 8. 运行时与工具职责
| 组件 | 读 OKF? | 写 OKF? | 备注 |
|------|----------|----------|------|
| 解释器 / 字节码 VM | 否(语义) | 否 | 只跑 `.mq.md` |
| `marqdo catalog` | — | 工程目录包 | v0 |
| `plugins/agent`(`agent_kb_*`)+ `ext/ai` `plan` | 任务包 | 晋升时写任务包 | O2;**不**进核心 `src/host` |
| `lib/fs` | 通用文件 | 通用文件 | L1 包装 |
| `marqdo view` | 否 | 否 | HTML 另一轨 |
| 未来 `marqdo kb query` | 是 | 否 | 可选:按 type/tag/链接查询 |
agent-kb 运行时实现归属 **agent 插件**(`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / `agent_kb_record_hit` / `agent_workbook_solidify` / `agent_kb_task_files`),由 `ext/ai/agent` 调用;禁止把这些原语加回 `HostFn`。
解释器**不得**因缺少 catalog 而拒绝运行源文件。
---
## 9. 安全与边界
| 风险 | 对策 |
|------|------|
| 把生成物当配置手改 | 文档 + GENERATED 头;CI 可选校验 |
| 错误技能被复用 | 快路径必 spawn+inspect;失败标 `draft` 并重规划 |
| 签名过宽 | tools 指纹;文档强调 exact goal |
| 密钥进入知识包 | 继承 env;禁止把 key 写入 resource/概念正文 |
| 包膨胀 | runs 与 kb 分离;仅 DONE 晋升 |
| 与语言语义耦合 | catalog/kb 失败不影响 `marqdo run` 源文件 |
---
## 10. 实现路线
| 阶段 | 内容 | 状态 |
|------|------|------|
| **O0** | 调研 + 生成式清单方向 + `.mq.md` 后缀 | **done** |
| **O1** | `marqdo catalog` / `sync`:Module + Catalog YAML | **done**(v0) |
| **O2** | 本文锁定的任务知识包:`Marqdo Task` / `Agent Skill`;`plan` reuse/promote | **done**(host kb_* + plan 快路径) |
| **O3** | catalog 增强:`verified`/`sources` 可选;模块页可点击依赖;扫入 `agent-kb` 概念供人浏览 | **done** |
| **O4** | `log.md` 策展、可选 `kb query`、Attested-style「再现跑通」收据(非 BigQuery) | 远期 |
| **O5** | 相近任务软命中:aliases + canonicalize + 本地 n-gram `near` + `soft_match` 父裁决已落地;dense embedding 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E | **A/B/C/D-near done** |
O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。
---
## 11. 非目标
- 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。
- 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。
- 强制用户提交 `.marqdo/` 进 git。
- **默认**语义相似检索 / 向量库(可选软命中见 O5 / [okf-near-match.md](../roadmap/okf-near-match.md);不进内核)。
- 跨仓技能市场(可后续在概念图上扩展)。
- 照搬 OKF `Attested Computation` 的 BigQuery executor 模型。
---
## 12. 与既有文档的关系
| 文档 | 关系 |
|------|------|
| [okf-and-marqdo.md](../research/okf-and-marqdo.md) | 调研;产业背景与借鉴边界 |
| [generated-yaml-manifest.md](generated-yaml-manifest.md) | 早期「生成式清单」方向;**词汇与原则并入本文,命令细节见 catalog-cli** |
| [catalog-cli.md](catalog-cli.md) | O1 CLI 与 v0 落盘的操作说明 |
| [ext-agent-plan.md](ext-agent-plan.md) | 多步执行;缓存/复用应引用本文 §7 |
| [ext-agent.md](ext-agent.md) | 框架总览;自写回 ≠ 跨调用 OKF 知识包 |
---
## 13. 决议摘要
1. Marqdo 的 OKF 实现 = **形态对齐 + Marqdo 类型词汇 + 生成/晋升管道**,不是语言换皮。
2. **O1–O3 已落地**(工程目录包、任务知识包、catalog 扫入 agent-kb + 人读链接图);**O4** 策展/查询为远期。
3. 可执行真相是 `.mq.md`;概念页负责**寻址、信任与联系**——人与 Agent 都是闭环里的一环。
4. 父智能体复用优化结果,应走 **Task → Skill → resource → spawn**,而不是私有 JSON 缓存主路径。
5. 未知 `type` 降级;无清单亦可运行源码。
---
## 14. 一句话
**Marqdo 用 OKF 风格的知识包索引程序与任务技能:源负责跑,概念负责找与信,catalog 与 agent-kb 分管工程目录与自我成长。**
+2 -2
View File
@@ -2,8 +2,8 @@
| | |
|---|---|
| 状态 | **已落地(v1)** |
| 日期 | 2026-08-06 |
| 状态 | **已定(v1)** |
| 日期 | 2026-08-05 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
---
+1 -1
View File
@@ -28,7 +28,7 @@
|------|-------------------|
| `> lib/text.mq.md` | `trim` · `split` · `join` |
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
| `> lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
| `> lib/table.mq.md` | `rows` · `row_at` |
| `> lib/表.mq.md` | `行数` · `取行` |
示例:
+133 -100
View File
@@ -1,36 +1,32 @@
# 标准库 L1 模块
# 标准库下一波(L1 扩展模块)
| | |
|---|---|
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
| 日期 | 2026-08-07 |
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
| 日期 | 2026-08-05 |
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
| 下一波 | **外联**(本机解释器 / 具名围栏) |
| 暂缓 | — |
| 原则 | 全部经 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) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
---
## 1. 目标
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
| 模块族 | 英文库 | 中文库 | 状态 |
| 模块族 | 英文库 | 中文库 | 本波 |
|--------|--------|--------|------|
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.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)。
| 文本(已有) | `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` | **做** |
| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
---
@@ -38,73 +34,35 @@
```text
用户 .mq.md
│ > lib/fs.mq.md / > ext/llm.mq.md
│ > lib/fs.mq.md
▼
L1 官方库 / 官方 ext(.mq.md)
L1 官方库(.mq.md)
│
▼
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
L0.5 宿主原语(Rust,英文蛇形)
│
▼
OS / HTTP / 时钟 / 共享库 …
OS / HTTP / 时钟 / …
```
| 层 | 谁实现 | 用户是否直接调用 |
|----|--------|------------------|
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 |
| **L1 官方库** | `lib/*.mq.md` | **是** |
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`);**禁止** `host_*`,经 `lib/*` 或插件注册名 |
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
> **已变更(M1+M2)**:[module-namespace.md](module-namespace.md) — 取消跨文件扁平合并;L1/ext 经**裸名点号路径**调用(`time.parse`、`agent.agent`;M2:`库.对象.成员` + `use`),库名不加反引号;实例方法须 `` `var`.method ``;不再靠 import 顺序覆盖同名。
规则:
### 2.1 L1 薄包装 → 宿主(命名空间后必读)
点号路径 `net.http_post` / `json.stringify` 等解析到 **`lib/*.mq.md` 的 `##` 函数**,再转发 `host_*`。未在包装形参表声明的可选实参会被**静默丢弃**(曾导致 live agent 401:`Authorization` 等 `headers` 从未到达宿主)。
| 规则 | 说明 |
|------|------|
| 每个 `host_*` 包装 | 须在 `+` 形参表声明**全部**宿主可选参数,默认 `None`,并在 `**> host_…**` 中**原样转发** |
| `http_post` / `提交` | `content_type=None` 时宿主按默认 JSON charset 处理 |
| 已对齐(2026-08-07) | `net`/`网络`(headers、content_type、body)、`sys`/`系统`(load_dotenv、exec)、`ext/ai/llm`(load_env / 加载环境 path)、`json.stringify` indent、`foreign`/`外联` stdin、`math`/`数学` plot*/solve 可选项 |
**无**扁平合并回退;**无**裸名双轨兼容。
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
2. **不设 `lang:`**。
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
---
## 3. 核心模块 API(摘要)
## 3. 核心模块 API 草图(L1)
文件 / 系统 / 时间 / 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` / `文件`
### 3.1 文件 — `fs` / `文件`
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|------|------|-----------------|------|
@@ -116,19 +74,22 @@ OS / HTTP / 时钟 / 共享库 …
| `make_dir` | `建目录` | `path` / `路径` | `None` |
| `remove` | `删除` | `path` / `路径` | `None` |
#### 系统 — `sys` / `系统`
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
### 3.2 系统 — `sys` / `系统`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
| `args` | `参数表` | (无) | 文本列表 |
| `cwd` | `工作目录` | (无) | 文本 |
| `exit` | `退出` | `code` / `码` | 不返回 |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
#### 时间 — `time` / `时间`
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
### 3.3 时间 — `time` / `时间`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
@@ -138,58 +99,130 @@ OS / HTTP / 时钟 / 共享库 …
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
#### JSON — `json`
view 中 `sleep_ms` 设上限(如 5s)。
### 3.4 JSON — `json`(**中英同库特例**)
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
| 项 | 约定 |
|----|------|
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
| 形参 | 英文:`text` / `value` / `key` / `indent` |
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
| 函数 | 形参 | 结果 |
|------|------|------|
| `parse` | `text` | 值 |
| `parse` | `text` | 值(见下) |
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
| `get` | `value`, `key` | 值或 `None` |
| `keys` | `value` | 文本列表 |
| `quote` | `text` | JSON 字符串字面量 |
#### 网络 — `net` / `网络`
**类型映射(草案)**:
| JSON | Marqdo Value |
|------|----------------|
| `null` | `None` |
| bool | bool |
| number(整数可表) | int |
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
| string | text |
| array | list |
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
### 3.5 网络(简)— `net` / `网络`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
---
## 4. 中英路径总表
## 4. 中英路径总表(本波)
```text
lib/
text.mq.md / 文本.mq.md
table.mq.md / 表.mq.md
fs.mq.md / 文件.mq.md
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 # 中英共用
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
# 暂缓:math / 数学 · foreign / 外联
```
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
别名:`std/…` ≡ `lib/…`。
---
## 5. 安全与 view / 静态导出
## 5. 落地分期(本波 = M1–M5)
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
| 期 | 内容 | 完成定义 |
|----|------|----------|
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
---
## 6. 一句话
## 6. 安全与 view / 静态导出
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
### 6.1 行为一致
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
差异仅在 **软退出**:
| | CLI `run` | view / capture / 静态导出 |
|--|-----------|---------------------------|
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
### 6.2 静态部署
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
---
## 7. 与现有库的关系
- `text` / `table` 继续纯包装、无 IO。
- JSON `stringify` ≠ `str`(显示)。
---
## 8. 刻意不做(本波)
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
- 数据库、异步事件循环、WebSocket、原始 TCP。
- float/复数进 L0。
- `lang:` 或按 locale 自动选库。
- 为 JSON 强造中文库名或中文 API 双份。
---
## 9. 一句话
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
-29
View File
@@ -1,29 +0,0 @@
# 子任务标准库(subtask)
| | |
|---|---|
| 状态 | v2 |
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
## 定位
**并发**执行单元。`spawn` 四选一:
| 参数 | 执行方式 | `join` / `wait` 返回值 |
|------|----------|------------------------|
| `path=` | `marqdo run <file> --emit-result <tmp>` 子进程 | map `{ code, value, stdout?, stderr? }`(`# main` 返回值;quiet 时 piped 捕获 I/O 尾部,不 inherit TTY) |
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
`quiet=` / `静默=`(默认 `True`):仅影响 **文件** 子任务的 **TTY**。默认 **piped 捕获** stdout/stderr(父终端不被污染,`wait` map 带截断后的 `stdout`/`stderr` 供父智能体观察);`False` 时继承父进程 stdout/stderr(map 中 I/O 字段为空)。**答案载荷仍以 `# main` 返回值为主**(经 `--emit-result` 旁路)。外联子任务仍经管道收集 stdout 供 `join` 返回,不受此参数影响。
**事件转发(文件子任务)**:spawn 时设置 `MARQDO_EVENT_FORWARD=<临时 ndjson>`;子进程内 `EventBus.publish` 追加写入该文件;父在 `wait` 阻塞期间 tail 并 republish(加 `source=child`)。这样子 LLM `stream=True` 的 token 能进 `marqdo view` SSE,而不破坏 quiet TTY 契约。函数子任务在同进程内,本来就共享 EventBus。
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
Host:`host_subtask_*`(`src/host/subtask.rs`)。
-82
View File
@@ -1,82 +0,0 @@
# `lib/table` / `lib/表` — 列表与字典
| | |
|---|---|
| 状态 | **已落地**(可用级集合 API) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [table-cell-expressions.md](table-cell-expressions.md) · [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) |
---
## 1. 读写对
| 读 | 写 |
|----|----|
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
```markdown
---
> lib/table.mq.md
---
# main
*`h` = > table.put in=None at=Authorization value=Bearer-x*
`xs` =
| v |
|---|
| a |
| b |
*`xs` = > table.put in=`xs` at=1 value=A*
```
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
---
## 2. 索引约定
| API | 基数 |
|-----|------|
| `put` / `改` 路径中的整数;脚注 `[^n]` | **1-based** |
| `at` / `row_at` / `set_at` / `insert` / `remove_at` / `slice` / `index_of` | **0-based** |
---
## 3. API 摘要(EN ↔ ZH)
| EN | ZH | 说明 |
|----|----|------|
| `put` | `改` | 按路径改一元(首选写入) |
| `len` / `rows` | `长度` / `行数` | 长度 |
| `at` / `row_at` | `取` / `取行` | 0-based 取元 |
| `append` / `prepend` / `concat` | `追加` / `前插` / `拼接` | 列表 |
| `insert` / `set_at` / `remove_at` / `pop` | `插入` / `改位` / `删位` / `弹出` | 列表位操作 |
| `first` / `last` / `slice` | `首` / `末` / `切片` | |
| `contains` / `index_of` / `reverse` | `含有` / `下标` / `反转` | |
| `clear` | `清空` | 列表或字典 |
| `get` / `set` / `delete` / `has` | `取键` / `设` / `删键` / `有键` | 浅层字典 |
| `keys` / `values` / `items` / `merge` / `size` | `键表` / `值表` / `项表` / `合并` / `键数` | |
| `empty_list` / `empty_map` | `空表` / `空字典` | |
嵌套改写优先 `put`/`改`;`set`/`set_at` 仅浅层。
---
## 4. 与 `lib/json`
| 用途 | 用 |
|------|----|
| 解析 / 序列化 / `quote` | `json.parse` · `json.stringify` · `json.quote` |
| 集合读写 | **`table.*` / `表.*`** |
| 兼容 | `json.set` / `json.append` / `json.get` / `json.keys` 仍为别名,新代码勿依赖 |
---
## 5. 宿主
`host_collection_put` + list/map 原语(见 `src/host/collection.rs`)。作者面经 `lib/table` / `lib/表` 调用,不直接写 `host_*`。
-59
View File
@@ -1,59 +0,0 @@
# 自写回标准库(writeback)
| | |
|---|---|
| 状态 | v1 已落地 |
| 日期 | 2026-08-07 |
| 库 | `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
-->
```
命名槽(智能体成功/失败互不覆盖):
```markdown
<!-- marqdo-out ok
status=ok result=…
-->
<!-- marqdo-out error
pending
-->
```
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
- 默认在**调用行下方**插入或替换紧邻**无键**块
- `at_end=true`:替换文件末尾的**无键**块
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
### 替换跨度与空行
替换 `<!-- marqdo-out … -->` 时,被替换跨度**包含**注释块结束 `-->` 后的**单个**换行符(不把该换行留在文件里)。这样多次 `record` **不会**在块下方累积多余空行。
命名槽仍锚在调用行(如 `step` / `写回`)下方;整簇结束后保留**一条**有意空行即可,且应稳定。
## API
| EN | ZH | 说明 |
|----|-----|------|
| `record` | `写回` | `value=`;可选 `at_end`、`key`、`line` |
| `get` | `取` | 可选 `at_end`、`key`、`line` |
| `clear` | `清除` | 可选 `at_end`、`key`、`line` |
| `ensure` | `确保` | `key=` + 可选 `placeholder=`、`line=`;槽已存在则不动 |
| `list` | `列出` | 全文所有输出块(命名槽含 `key` 字段) |
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。
**与 `ext/ai/agent`:** `## step` / `## 单步` 在 D2 起 **默认自动** `record` 到 `ok`/`error` 槽(参数 `writeback=` / `写回=` 可关)。多步工作簿依赖此默认,见 [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md)。
+17 -27
View File
@@ -2,13 +2,12 @@
| | |
|---|---|
| 状态 | **S0–S3 + L1 全模块落地** |
| 日期 | 2026-08-07 |
| 相关 | [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) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
| 状态 | **S0–S3 落地** |
| 日期 | 2026-08-04 |
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.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)。
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
---
@@ -16,9 +15,8 @@
| 层 | 内容 |
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
| **L2** | catalog / 用户站收录(随发版) |
---
@@ -30,7 +28,7 @@
| `len` | `value` | 文本标量数或列表长度 |
| `str` | `value` | 显示文本 |
| `int` | `value` | 整数(失败 → 诊断) |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
| `trim` | `value` | 去首尾空白 |
| `split` | `value`, `sep` | 文本列表 |
| `join` | `value`, `sep` | 拼接文本 |
@@ -42,7 +40,7 @@
## 3. 官方库导入(S2)
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
Frontmatter:
```markdown
---
@@ -51,36 +49,28 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
---
```
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `> use time.format`(冲突 → 硬错误)。
`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/` 时自动使用)
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
当前模块(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/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
| `lib/table.mq.md` | `put` 为首选写入;`rows`/`row_at` 及完整 list/map API — 见 [stdlib-table.md](stdlib-table.md) |
| `lib/表.mq.md` | `改` 为首选写入;`行数`/`取行` 及完整 list/map API |
| `lib/table.mq.md` | `rows` `row_at` |
| `lib/表.mq.md` | `行数` `取行` |
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
---
-138
View File
@@ -1,138 +0,0 @@
---
title: table cell expressions
status: Accepted
date: 2026-08-12
related: markdown-mapping.md · roadmap/tables-maps-footnotes.md · call-arguments.md
---
# 表单元格表达式(T5)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-08-12 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [call-arguments.md](call-arguments.md) |
---
## 1. 问题
v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结果虽是 `Map` / `List`,却不能写:
```markdown
`h` =
| api_key | model |
|---------|-------|
| `api_key` | `model` |
```
作者只好用 `json.set` 链或 JSON 字符串拼接——这是**实现缺口**,不是「字典只能装字面量」的语义必然。
---
## 2. 锁定规则
### 2.1 数据单元格 = 与调用实参相同的值语法
每个**数据**单元格(非表头、非分隔行)按 [`parse_call_arg_value`](../../src/parse/expr.rs) 解析,再在绑定求值时执行:
| 单元格写法 | 含义 |
|------------|------|
| `苹果` / `Alpha` | 裸词 → 文本字面量(与今日竖表兼容) |
| `42` | 整数 |
| `` `api_key` `` | 变量引用 |
| `` `a` + `b` `` | 普通表达式 |
| `True` / `假` / `None` | 布尔 / 空 |
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
| 空单元格 | 空文本 `""` |
### 2.2 表头仍是键名文本
表头单元格**不**求值:键 = trim 后的表头字符串(与今日一致)。不允许 `` | `k` | `` 当动态键(v1 非目标;需要时另文)。
### 2.3 几何语义不变
竖表 / 横表单行 Map / 多行列向 Map / `@`·`行`·`row` 行向记录——**形状规则不变**;只把「单元格 → `Expr::Literal`」换成「单元格 → 完整 `Expr`」。
求值已由解释器对 `Expr::List` / `Expr::Map` 递归完成,字节码后端已发射列表/字典,**无需新 AST 节点**。
### 2.4 求值时机
表出现在 `` `名` = `` 右侧时,在**该绑定语句**求值:单元格内变量读**当时**环境。构造函数体里的表与语句表规则相同。
### 2.5 错误
- 单元格表达式非法 → 与别处表达式相同的 `path:line:col` 诊断(行号取该表行)。
- 变量未定义 → 求值期报错。
- 不引入「单元格静默当字面量」的回退(除 §2.1 已列的路径/连字符折叠,与调用实参对齐)。
---
## 3. 作者示例(目标体验)
```markdown
*`api_key` = > sys.env_get name=OPENAI_API_KEY *
*`model` = "gpt-4o-mini" *
`handle` =
| api_key | base_url | model | suffix |
|---------|----------|-------|--------|
| `api_key` | https://api.openai.com/v1 | `model` | /chat/completions |
```
`handle` 为含运行时 `api_key` / `model` 的字典;静态 URL 与 suffix 仍可裸写(路径折叠)。
嵌套:
```markdown
*`prompt` = hello *
`msg` =
| role | content |
|------|---------|
| user | `prompt` |
*`messages` = > json.append list=None item=`msg` *
```
(列表字面量表仍可用竖表;需要「单行记录」时用横表或 `@` 行向表。)
---
## 4. 兼容性
| 旧写法 | 行为 |
|--------|------|
| 纯中文/英文词、整数 | **不变** |
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
---
## 5. 非目标(本阶段)
- 表头动态键
- 单元格内 `>` 调用(可用表外算完再引用)
- 单元格内多语句 / 分支
- 把叙述区(注释段)里的 GFM 表当成可执行(仍为注释)
---
## 6. 验收
| 项 | 标准 |
|----|------|
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
实现跟踪见 [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) **T5**。
+2 -11
View File
@@ -13,7 +13,7 @@
| 路径 | 是否入库 | 职责 |
|------|----------|------|
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
@@ -50,16 +50,7 @@ public/
---
## 4. 内容分层(用户站)
| 目录 | 内容 |
|------|------|
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
## 5. 验收
## 4. 验收
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
+4 -49
View File
@@ -90,16 +90,8 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
## 4. 信息架构
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
| 区块 | 内容 |
|------|------|
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
---
@@ -110,44 +102,8 @@ view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
| `GET` | `/file?path=…` | 单文件页 |
| `GET` | `/api/tree` | JSON 树(可选) |
| `GET` | `/api/events?path=…` | 可选长订 EventBus(调试);**Stream 面板默认不用**(避免页载常连导致标签页一直转圈) |
| `POST` | `/api/run` | JSON `{path, stdin?}` → **直接返回** `text/event-stream`(本次 run 的事件);结束后关流 |
| `POST` | `/api/foreign-run` | 外联代码块试跑 |
根目录锁死;拒绝 `..` 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
### 5.1 Stream 面板(对齐主流 LLM 呈现)
**仅当**当前文件 frontmatter 导入了 `ext/ai/llm` / `大模型` 或 `ext/ai/agent` / `智能体`(及等价路径)时,在 live Execution 区显示;普通脚本页不出现该组件。
参考常见助手产品(思考折叠 + 正文流式、工具/子步骤独立卡片):**不要**把所有 SSE 事件打成一条混色终端日志。
| 区块 | 事件 | 呈现 |
|------|------|------|
| **Thinking** | `reasoning` | 可折叠;流式追加到同一块;默认展开直至本轮 `delta`/`done` 开始,之后可收起 |
| **Answer** | `delta` | **主文**;token 连续拼进同一段落(禁止每 token 换行);主色正文 |
| **Decision** | `decision` | 时间线条目标记(`RUN` / `CONTINUE` / `DONE` / `REUSE` / `NEW` + 可选 summary) |
| **Tool** | `tool_start` / `tool_end` | 父 Plan-and-Move 的 CALL/READ:名称 + kind;`tool_end` 可带截断 `result` |
| **Phase** | `decompose` | 父 pre-run 分解开始(workbook 链);填补「决策后到首 token」空隙 |
| **Child / Workbook** | `await` → `round` | `await`:Child **running…** 占位卡(quiet 子任务等待中);`round`:升级为完成卡(退出码 + 可选 `result`) |
| **Status** | `run_start` / `done` / `error` | 顶栏状态 + 错误行;嵌套 LLM `done`(无 `run_id`)只冲刷 drip,不改顶栏;终态 `done.result` 仅在无 Answer 时作摘要 |
**传输与流畅度(对齐 ChatGPT 类产品):**
1. **Run = 一次 `fetch` POST**,用 `ReadableStream` 读响应体里的 SSE 帧;**不要**页载常驻 `EventSource`。
2. **「Run with input」拦截表单**:`preventDefault` 后走同一 Stream `/api/run`,**禁止整页重载**;带 `?stdin=` 进入时 live 页也不再阻塞跑完,改为自动开 Stream。
3. **只改 Stream 对话框 DOM**;token **按动画帧合批一次写入**(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
4. **Stick-to-bottom**:仅在用户仍贴底时跟随;程序化 `scrollTop` 产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。
5. **Stop**:`AbortController` 中止 fetch。
6. **子任务并发进度**:`spawn` 立即返回;`wait` 阻塞父循环期间,子进程经 `MARQDO_EVENT_FORWARD` 把 EventBus 帧实时转发到父 SSE;view 把 `source=child` 的 delta 画进 Child 卡。quiet 仍不污染父 TTY。
视觉约束(与 §2 一致):
- 浅色内容面,不用深色「伪终端」底;Thinking 用次要字色 / 浅底。
- 一屏只突出 Answer;Thinking 与 Child 是附属。
- plan 多轮:每一轮 Child 一张卡;父侧 Thinking/Answer 按 decision 分轮,不清空历史。
事件字段约定(与 [agent-streaming.md](../roadmap/agent-streaming.md) 一致):`round` 可带 `result`(子 `# main` 返回值摘要);`reasoning`/`delta` 的 `text` 为增量。
根目录锁死;拒绝 `..` 逃逸。
---
@@ -157,5 +113,4 @@ view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
4. 冷启动无明显外网依赖。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
-82
View File
@@ -1,82 +0,0 @@
# 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` 只保留本约定与设计指针。
+5 -5
View File
@@ -3,9 +3,9 @@
| | |
|---|---|
| 状态 | **已定分支模型** |
| 日期 | 2026-08-05 |
| 代码分支 | **`vscode-extension`**(同仓库) |
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
| 目录 | 工作区 `vscode-extension/`(仅在该分支跟踪;**`main` 忽略**) |
---
@@ -13,8 +13,8 @@
| 分支 | 内容 |
|------|------|
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
| `main` | Marqdo 语言 / CLI / `public/*.mq.md` 源;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、开发规范、TextMate 语法 |
| `gh-pages` | 用户站生成 HTML |
```bash
@@ -22,7 +22,7 @@ git checkout vscode-extension
cd vscode-extension && npm install
```
规范入口(在 **`vscode-extension` 分支**上阅读):
规范入口(在该分支上阅读):
- `vscode-extension/README.md` — 目标与目录
- `vscode-extension/DEVELOPMENT.md` — 日常流程
+3 -3
View File
@@ -54,8 +54,8 @@ cargo clippy --all-targets
```bash
# Windows PowerShell 示例
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
cargo build
```
@@ -63,7 +63,7 @@ cargo build
```toml
[http]
proxy = "http://127.0.0.1:7890"
proxy = "http://127.0.0.1:7897"
```
---
+1 -1
View File
@@ -192,7 +192,7 @@ OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳;**实现规范见 [okf.md](../design/okf.md)**,命令见 [catalog-cli.md](../design/catalog-cli.md))。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
-181
View File
@@ -1,181 +0,0 @@
# 智能体流式输出(未来规划)
| | |
|---|---|
| 状态 | **S0–S3 已落地**(view SSE) |
| 日期 | 2026-08-10 |
| 相关 | [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md)(父 Plan-and-Move / CALL·READ) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [view.md](../design/view.md) |
| 痛点 | `complete` / `step` / `plan` 均为整段返回;用户看不到思考与中间输出 |
---
## 1. 问题
当前体验:
| 路径 | 行为 | 体验问题 |
|------|------|----------|
| `` `model`.complete `` | 等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 |
| `` `助手`.step `` | 拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 |
| `` `助手`.plan `` | 多轮 spawn + 父 LLM;子任务默认 `quiet` | 父侧只有最终 `result` map;过程静默 |
这与「文档驱动、过程可审计」并不矛盾——**落盘真相**仍可以是工作簿与写回;缺的是**运行时的渐进呈现**(TTY / view / 调用方回调)。
约束回顾(不得破坏):
1. 文件子任务默认静默:答案走 `# main` **返回值**([stdlib-subtask.md](../design/stdlib-subtask.md))。
2. `ext/**` 不直调 `host_*`;流式原语进 `ext/ai/llm` + 必要时薄 host/net。
3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。
---
## 2. 目标
1. **可选**流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
2. 默认保持今日语义:未开流式 = 整段 `complete` / 整包 `result`。
3. 流式是**呈现与旁路**,不替代 `**返回**` / `plan.result` / 写回。
4. CLI、`marqdo view`、嵌入调用方可共用同一事件模型。
非目标(本规划):
- 把 Marqdo 做成聊天产品 UI 框架。
- 强制所有 `print` 改流式 API。
- 在 quiet 子进程里把子 `print` 默认真传父 TTY(与返回优先冲突)。
---
## 3. 分层设计
```text
LLM 供应商 SSE / chunked
↓
ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel
↓
ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」
↓
呈现面:TTY | view EventSource | 调用方 foreach 事件表
```
### 3.1 事件模型(锁定方向)
统一为可 JSON 化的小 map(便于写回与 view):
| `type` | 含义 | 主要字段 |
|--------|------|----------|
| `reasoning` | 模型思考增量(如 DeepSeek `reasoning_content`) | `text` |
| `delta` | 模型答案增量文本 | `text` |
| `tool_start` / `tool_end` | 工具轮(父 plan CALL/READ 已发;view Tool 卡) | `name`, `kind?`, `result?` |
| `round` | plan 轮次边界(子工作簿跑完) | `round`, `workbook`, `exit_code?`, `result?`(子返回值摘要) |
| `decision` | DONE / CONTINUE / RUN | `decision`, `summary?` |
| `done` | 本调用结束 | `result`(答案正文;不含 thinking) |
| `error` | 失败 | `message` |
中英键名可在 L1 包装层镜像;插件/wire 先用英文 `type`。
### 3.2 `llm`:流式完成
```markdown
*`model` = > llm *
*`stream` = > `model`.complete prompt=… stream=True *
- [`ev`](`stream`)
*`t` = > json.get value=`ev` key=type *
1. `t` == delta
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. `t` == done
*`answer` = > json.get value=`ev` key=result *
```
或回调形(若日后支持函数值作实参):`on_delta=` —— v1 优先 **事件列表 / 可迭代句柄**,少发明回调语法。
实现要点:
- `lib/net` 或 llm 插件支持 **读 SSE / chunked body**(今日 `http_post` 偏整包)。
- `stream=False`(默认)路径零行为变化。
- 金样:mock SSE fixture,不强制打真网。
### 3.3 `agent.step` / `plan`:过程透传
| 开关(草案) | 默认 | 行为 |
|--------------|------|------|
| `stream=False` | ✓ | 与今日相同 |
| `stream=True` | | 向**当前进程**呈现面推送事件;返回值仍是最终 map |
| `trace=True` | 可选 | 把事件追加写入调用行写回槽 `trace`(审计);与 TTY 流式可分立 |
plan 特有:
- `await_workbook` **前**发 `await`(view Child running 占位);结束后发 `round`。
- 父 pre-run 分解发 `decompose`。
- 父 LLM 的 `complete` 若 `stream=True`,`delta` 冒泡到 plan 的 stream。
- **子文件 quiet 不变(TTY)**;默认骨架 `step stream=True`,子 EventBus 经 `MARQDO_EVENT_FORWARD` **实时转发**到父 SSE(`source=child`)。答案仍以 `# main` 返回为准。
### 3.4 呈现面
| 面 | 做法 |
|----|------|
| CLI | `delta` 直接写 stdout(无额外 JSON 包装);结构化事件可 `--trace-events` 走 stderr / 旁路文件 |
| `marqdo view` | Execution 区 Stream 面板订阅 SSE(见 [view.md](../design/view.md) §5.1):Thinking / Answer / Child 分栏,非混色日志 |
| 库调用方 | foreach 事件集合,自行决定 UI |
**view Stream 锁定(S3 UI):**
1. `reasoning` → 可折叠 Thinking;`delta` → 主文 Answer(连续拼接)。
2. `round` → 独立 Child/Workbook 卡(路径链 + 可选 `result`);不与父 Answer 混排。
3. `decision` → 时间线条目标记。
4. 视觉跟 view HIG 浅色壳,不用深色终端底。
5. **传输**:`POST /api/run` 直接 SSE;前端 `fetch`+`ReadableStream`(非页载 EventSource);rAF 合批;stick-to-bottom。
---
## 4. 与「返回优先」的关系
| 通道 | 职责 |
|------|------|
| stream / trace | **过程**(体验、调试、审计) |
| `# main` `**…**` / `plan.result` | **结果**(编排、OKF、调用方消费) |
| writeback `ok`/`error` | **落盘摘要**(默认可关) |
禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。
---
## 5. 推荐落地顺序
```text
S0 net/llm:SSE 读 + complete stream=True + 事件 foreach ✅
S1 step stream=True(echo 增量;返回 map 不变) ✅
S2 plan stream=True:round + 父 delta;trace 写回可选 ✅
S3 view 订阅(EventBus + GET /api/events + POST /api/run) ✅
```
### 开放点决议(S0)
1. **Eager 事件列表**(非惰性句柄):`complete stream=True` 返回 `List` of maps,可用今日 foreach。
2. **默认不自动 print**:`echo=False`;需要边读边打时传 `echo=True` / `打印增量=真`。
3. 中文:`## 运行` 用 `流式=` / `打印增量=`。
### 开放点决议(S2)
1. `plan` / `多步` 增加 `stream` / `echo` / `trace`(中文 `流式` / `打印增量` / `轨迹`)。
2. 事件挂在返回 map 的 `events`;父 `complete` 只冒泡 `delta`/`error`(嵌套 `done` 不进列表)。
3. `trace=True` → 写回槽 `trace`(与 TTY `echo` 可分立)。
4. **体验(父先子后)**:非命中路径先 `decompose`(SSE + 可选 TTY `plan:decompose`),再 `await`(SSE 占位 + 可选 TTY `plan:await`),子 quiet。修订轮仍是观察后父决策。SSE 本身用 `tests/ext/llm-stream-live.mq.md`。
验收:
1. 未传 `stream` 的金样零 diff。
2. `stream=True` 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。
3. 最终 `result` 与非流式路径一致(同 prompt fixture)。
4. quiet 子任务仍不污染父 TTY。
---
## 6. 开放点
1. ~~Eager vs 惰性~~ → S0 选 eager;惰性句柄可后补。
2. ~~delta 默认 print~~ → 默认关;`echo=True` 可选。
3. ~~中文面~~ → `流式=` / `打印增量=`。
4. ~~S2~~ → `plan stream=True`:`round` / 父 delta / `decision` / `done`;可选 `trace`。
5. ~~**S3**~~ → `marqdo view`:进程内 EventBus;`GET /api/events`(SSE);`POST /api/run` 后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。
S0 可与 [okf-near-match.md](okf-near-match.md) 并行,互不阻塞。
-56
View File
@@ -1,56 +0,0 @@
# 官方扩展:`ext/quantum` 实现路线图
| | |
|---|---|
| 状态 | **Q0–Q6 已落地**(含公式自定义门;更大 n / 完整开放系统另文) |
| 日期 | 2026-08-12 |
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
---
## 1. 目标回顾(一句)
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | **done** |
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | **done** |
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | **done** |
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | **done** |
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | **done** |
| **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** |
| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** |
| **Q6** | 公式/`matrix=` 自定义门 + `apply` — [ext-quantum-custom-gate.md](../design/ext-quantum-custom-gate.md) | **done** |
验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、`quantum-amp-damp-smoke.mq.md`、`quantum-custom-gate-smoke.mq.md`、中文对称样例。
---
## 3. 已收敛的原开放点
| 原疑问 | 锁定结论(见设计文) |
|--------|----------------------|
| 并进 math? | **否**,独立 `ext/quantum` |
| 电路表 | **要做**(Q3),与方法链等价 |
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
| 自由函数面 | **不**与对象面并行 |
---
## 4. 与其它文档
| 文档 | 关系 |
|------|------|
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |
-53
View File
@@ -1,53 +0,0 @@
# 官方扩展:`ext/web` 实现路线图
| | |
|---|---|
| 状态 | **W0–W3 骨架已落地;W4 待** |
| 日期 | 2026-08-11 |
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
| 安装 | `marqdo ext add web`(`web` / `网页`) |
本文只跟踪**实现阶段**。类模型、赋值绑定、后台、`.env`、异步边界、ABI 名等以设计文为准。
---
## 1. 目标回顾(一句)
**表格完成动态站**:页面表拼组件、组件表绑库与样式、样式表定外观;热路径进 ABI 插件;可选 S3 / Redis。人写目标见设计 §0.1 与 `examples/man-write-site/`。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done**(登录鉴权仍简) |
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
| **W4** | Postgres;Redis / S3 驱动 | pending |
验收金样:`tests/ext/web-smoke.mq.md`、`ext_cli_add_web`。
---
## 3. 已收敛的原开放点
| 原疑问 | 锁定结论(见设计文) |
|--------|----------------------|
| listen 阻塞 vs 后台任务 | `# main` 内 `listen` **同步阻塞**;插件内部异步 |
| handler 形态 | **不主推**手写 REST;表 href + bind + 自动后台 |
| `marqdo web` 子命令 | scaffold 经 `web.scaffold`;`marqdo web new` 可后续补 |
| Windows + SQLite | 路径用 `DATABASE_URL` |
---
## 4. 与其它文档
| 文档 | 关系 |
|------|------|
| [design/ext-web.md](../design/ext-web.md) | **真理** |
| [user-site.md](../design/user-site.md) | 静态站互补 |
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
+1 -1
View File
@@ -62,7 +62,7 @@ index.mq.md (+ 导入的 .mq.md)
└─────────┬─────────┘
▼
┌───────────────────┐
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
│ │ 作用域链、形参、未定义名诊断
└─────────┬─────────┘
▼
+1 -1
View File
@@ -19,7 +19,7 @@
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
-167
View File
@@ -1,167 +0,0 @@
# 对象继承语法(未来规划)
| | |
|---|---|
| 状态 | **I0–I3 已落地**(显式父构造约定;**不做**隐式 auto-super) |
| 日期 | 2026-08-10 |
| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) |
| 提案语法 | `# 子类 = > 父类` |
---
## 1. 动机
今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。
实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少:
- 复用父构造 / 父方法而不复制 `.mq.md`
- 子类型在 `_type` 链上解析方法
- 与 Markdown 标题体系一致的、可读的继承声明
需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。
---
## 2. 锁定语法(提案)
```markdown
# 子类 = > 父类
```
| 片段 | 既有含义 | 组合后含义 |
|------|----------|------------|
| `# 子类` | 定义对象 / 类型 | 子类型名 |
| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 |
| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) |
可选带参基类(若基类本身是泛化构造,v1 可暂不支持):
```markdown
# 特化智能体 = > 智能体
```
中英对称:
```markdown
# Child = > Parent
# 子类 = > 父类
```
### 2.1 为何不冲突
1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。
2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。
3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。
4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。
反例(仍是今日语义,不变):
```markdown
# main
*`a` = > 父类 *
```
---
## 3. 运行时语义(草案)
### 3.1 方法解析
实例 map 仍有 `_type` = 构造时的类型名(子类名)。
查找 `` `obj`.方法 ``:
1. 在 `_type` 对应对象上找 `## 方法`
2. 未找到 → 沿 **基类链** 查找
3. 仍无 → 报错(带类型链)
构造:
1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。
2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。
### 3.2 子类正文
```markdown
# 工蜂 = > 智能体
## 采蜜
+ `花`
*`out` = > `self`.step task=`花` *
**`out`**
```
- 子类可定义新 `##`
- 可覆盖同名 `##`(子类优先)
- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字
### 3.3 多继承
**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。
---
## 4. 解析与 AST
标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl:
| 字段 | 值 |
|------|-----|
| `name` | 子类 |
| `base` | 父类(标识符) |
| `body` | 与今日 object body 相同 |
歧义处理:
- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`)
- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式)
- 基类尚未定义 → Pass1 收集后解析;循环继承报错
---
## 5. 与标准库 / 扩展
| 用途 | 例子 |
|------|------|
| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` |
| 扩展 llm 句柄 | 一般不必要;优先组合 |
| 用户域模型 | `# 订单服务 = > 服务基类` |
官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。
---
## 6. 推荐落地顺序
```text
I0 语法 + AST + 金样(解析/循环继承错误) ✅
I1 方法解析沿基类链;构造 _type=子类 ✅
I2 覆盖方法;文档更新 objects.md ✅
I3 显式父构造约定(**不做**隐式 auto-super) ✅
```
验收:
1. 无继承文件行为不变。
2. 子类实例能调父类 `##`;覆盖后只走子类。
3. `` # A = > B `` / `` # B = > A `` 诊断清晰。
4. Skill / 金样:`tests/structure/inherit-*.mq.md`(含显式 `` `self` = > Parent ``)。
---
## 7. 开放点
1. ~~**隐式 super**~~ → **不做**:子类构造体不自动跑父构造。需要父初始化时正文写 `` `self` = > 父类 … `` 再改字段后 `**`self`**`;构造完成时 `_type` 仍为最具体子类名。
2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。
3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。
---
## 8. 非目标
- 接口 / 抽象方法 / 可见性(`public`)
- 多继承、mixin 关键字
- 用继承替代 `plan` 工作簿接力
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
-108
View File
@@ -1,108 +0,0 @@
# OKF 相近任务命中
| | |
|---|---|
| 状态 | **A 规范句 + B aliases + C 父裁决(soft_match)+ D 本地 n-gram `near` 已落地**;E dense embedding 仍非目标 |
| 日期 | 2026-08-11 |
| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) |
| 触发观察 | `man-test`:相近 goal 生成两份独立 resource |
---
## 1. 问题
v1 agent-kb **精确命中仍是默认快路径**:
1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。
2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。
3. `agent_kb_lookup`:精确 → aliases → canonicalize → **本地 n-gram `near`(默认开)**;仍 miss 且 `plan soft_match=True` 时父裁决 REUSE/NEW(候选为排序 near 列表)。
历史痛点(已由 A/B/C/D 缓解):
| goal(调用方输入) | 旧行为 |
|--------------------|--------|
| `你是一个智能体,帮我规划明天的行程` | 独立 slug,与下方不命中 |
| `帮我规划明天的行程` | 另一份 resource |
| `帮我规划明天行程` | 又一份(近句碎片) |
调用方直觉:「这不是同一件事吗?」——现可用 canonicalize、默认 `near_match`,或显式 `soft_match` 父裁决。
---
## 2. 为何精确指纹仍优先
| 理由 | 说明 |
|------|------|
| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟 |
| 可审计 | `sig` 可复算;`near` 留下 `match`/`score` |
| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 |
**结论:** 精确命中长期保留为**默认快路径**;`near` 是可关闭的第四趟(`near_match=False`)。
---
## 3. 已落地层
### A. 规范化后再精确命中 — **已落地**
`agent_kb_canonicalize`:剥站立前缀、去尾标点;`match: canonical`。
### B. 别名 / 标签表 — **已落地**
Task FM `aliases:`;`match: alias`。
### C. 父智能体软裁决 — **已落地(默认关)**
`plan soft_match=True`:`agent_kb_near_match` 排序候选(含 `score`;空则退回 `list_tasks`)→ 父 `DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`。
### D. 本地字符 bigram + 余弦 — **已落地(默认开)**
| | |
|--|--|
| 做法 | 稀疏词法向量化(**不是** embedding 模型):canonicalize 后对 goal 与 Task `title\|description\|aliases` 建字符 bigram 词袋,算余弦 |
| API | `agent_kb_near_match`;`agent_kb_lookup` 第四趟 |
| 参数 | `near_match`/`近义命中` 默认 `True`;`near_threshold`/`近义阈值` 默认 `0.78` |
| 痕迹 | `match: near` + `score`;`cache=soft-hit`;可写 alias |
术语:这是 **sparse lexical near-match**,勿宣传为向量库 / embedding 检索。
### E. Dense embedding(可选远期)
远程 / 本地 dense 向量与 ANN **仍非本仓默认目标**;仅当 D 在真实包体量下证据不足时再评估。
---
## 4. 演进顺序
```text
精确 sig(永不删除)
→ A 规范句 + B aliases(已落地)
→ C soft_match 父裁决(已落地,默认关)
→ D 本地 n-gram near(已落地,默认开)
→ E dense embedding(仅有证据再开)
```
验收原则:
1. `near_match=False` 时与无 near 行为一致;`force`/`optimize` 仍跳过 reuse。
2. 软/近义命中留下 `cache=soft-hit` / `match` / 可选 `score`。
3. 假阳性可被 `force=True` / 显式 `workbook=` / 调高 `near_threshold` 覆盖。
4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。
---
## 5. 调用方建议
- 固定规范 goal;站立语可由 canonicalize 剥掉。
- 近句碎片依赖默认 `near_match`;字面差更大时开 `soft_match=True`。
- 策展:合并重复 task,次要措辞写入 `aliases`(O4)。
---
## 6. 与现有路线图的关系
| 条目 | 关系 |
|------|------|
| [okf.md](../design/okf.md) O2 / O5 | 精确 reuse + A/B/C/D;E dense 仍待 |
| [okf.md](../design/okf.md) O4 | `kb query` / 策展可继续扩 aliases |
| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」 |
-303
View File
@@ -1,303 +0,0 @@
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
| | |
|---|---|
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
| 日期 | 2026-08-12 |
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
---
## 1. 问题
### 1.1 今日表格 =「竖表 → 列表」
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
### 1.2 缺字典外形与嵌套
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
### 1.3 不能按下标 / 键直接取元
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
---
## 2. 目标
1. **竖表**继续表示列表(兼容现有金样)。
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
非目标:
- 完整电子表格公式引擎
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
- 破坏现有单列竖表金样
---
## 3. 表格几何 → 值(锁定提案)
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
### 3.1 竖表 → 列表(现状,保留)
**形状:** 恰好 **1** 列。
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
| 结果 | 说明 |
|------|------|
| 值 | `List`:`["苹果","梨","桃"]` |
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
### 3.2 横表单数据行 → 字典
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
```markdown
`分类` =
| 苹果 | 黄瓜 | 鼠标 |
|------|------|------|
| 水果 | 蔬菜 | 数码用品 |
```
| 结果 | 说明 |
|------|------|
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
| 键 | 表头单元格文本(规范化空白后) |
| 值 | 唯一数据行对应列 |
### 3.3 横表多数据行 → 字典套列表(默认)
**形状:** ≥2 列,且 **≥2 行数据**。
```markdown
`货架` =
| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |
```
**默认语义(锁定):列向聚合**
```text
{
"苹果": ["红富士", "嘎啦"],
"黄瓜": ["青瓜", "黄瓜条"]
}
```
即:**键 = 表头,值 = 该列数据行组成的列表**。
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
**备选语义(不默认):行向记录列表**
```text
[
{"苹果":"红富士","黄瓜":"青瓜"},
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
]
```
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
### 3.4 单列多行 vs 多列
| 列数 | 数据行 | 值类型 |
|------|--------|--------|
| 1 | ≥0 | `List` |
| ≥2 | 1 | `Map`(标量值) |
| ≥2 | ≥2 | `Map`(值均为 `List`) |
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
### 3.5 显式形态标记(行向记录)— **已落地**
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
| 标记 | 说明 |
|------|------|
| `@` | ASCII 短标记 |
| `行` | 中文 |
| `row` | 英文 |
规则:
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
2. 其余列 → 每行一个 `Map`;整体为 `List`。
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
```
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
---
## 4. 脚注取元(提案)
### 4.1 为何用脚注外形
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
### 4.2 列表:按下标
```markdown
*`第一` = `篮子`[^1] *
> print text=`第一`
```
| 约定 | 选择(提案) |
|------|----------------|
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
| 越界 | 清晰诊断 `path:line:col` |
### 4.3 字典:按键
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
```markdown
*`种` = `分类`[^苹果] *
*`p00` = `概率`[^00] *
> print text=`种`
```
| 规则 | 说明 |
|------|------|
| `[^苹果]` | 键文本 `苹果` |
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
### 4.4 嵌套取元
列向字典套列表:
```markdown
*`货架` = …多行横表… *
*`第一种苹果` = `货架`[^苹果][^1] *
```
从左到右:先键、再下标。
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
### 4.5 与 GFM「定义脚注」正文
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
规则:
- **表达式位置**的 `` `名`[^…] `` → 取元。
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
### 4.6 与 `lib/table` 关系
| 层 | 职责 |
|----|------|
| 语言脚注取元 | 一等、短、金样覆盖 |
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
---
## 5. foreach 与字典
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
扩展草案:
| 集合 | 遍历 |
|------|------|
| List | 不变,项为元素 |
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
---
## 6. 推荐落地顺序
```text
T0 横表单行 → Map;金样;竖表回归 ✅
T1 横表多行 → Map of List(列向);嵌套金样 ✅
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
T4 行向记录表:首列 `@` / `行` / `row` ✅
T5 数据单元格 = 表达式(同调用实参值语法) ✅
```
验收:
1. `tests/structure/collection.mq.md` 行为不变。
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
3. 错误下标 / 缺键带 `line:col`。
4. 双后端(tree / bytecode)一致。
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
---
## 7. 教学对照(写入 Skill 的素材)
| 几何 | 含义 | 取元 |
|------|------|------|
| 单列竖表 | 列表 | `` `a`[^1] `` |
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
---
## 8. 开放点
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
---
## 9. 与其它规划的关系
| 文档 | 关系 |
|------|------|
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
| [okf-near-match.md](okf-near-match.md) | 正交 |
-10
View File
@@ -1,10 +0,0 @@
# quantum-bell
Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw.
```bash
cargo build -p marqdo_plugin_quantum
marqdo run examples/quantum-bell/index.mq.md
```
Writes `bell.svg` next to the program (sandbox cwd).
-27
View File
@@ -1,27 +0,0 @@
---
title: Bell state
description: H then CX; probabilities ≈ 1/2; circuit SVG.
> ext/quantum/quantum.mq.md
> lib/math.mq.md
> lib/json.mq.md
---
# Bell |Φ+⟩
H on qubit 0, then CNOT(0→1). Ideal measurement: |00⟩ and |11⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
*`_` = > `qc`.draw path=bell.svg *
*`_` = > `qc`.draw kind=probs path=bell-probs.svg *
> print text=`p`
-28
View File
@@ -1,28 +0,0 @@
---
title: GHZ state
description: 3-qubit GHZ; |000⟩/|111⟩ ≈ 1/2; probs + H matrix heatmap.
> ext/quantum/quantum.mq.md
---
# GHZ
H on qubit 0, CX(0→1), CX(0→2). Ideal: |000⟩ and |111⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
| 3 | CX | 0,2 |
*`qc` = > quantum.circuit qubits=3 steps=`steps` *
*`p` = > `qc`.probabilities *
*`_` = > `qc`.draw path=ghz.svg *
*`_` = > `qc`.draw kind=probs path=ghz-probs.svg *
*`H` = > quantum.gate name=H *
*`_` = > `H`.draw kind=matrix path=ghz-h-matrix.svg *
> print text=`p`
-10
View File
@@ -1,10 +0,0 @@
# examples/web-site-zh
中文作者面示例:只导入 `ext/web/网页.mq.md`(不用英文 `web.mq.md`)。
```bash
cargo build -p marqdo_plugin_web
cargo run -- examples/web-site-zh/index.mq.md
```
打开 http://127.0.0.1:18082/ — `/about`、`/new`、`/admin`、`/static/site.css`。
@@ -1,9 +0,0 @@
## foot
`foot` =
| 属性 | 值 | 样式 |
|------|-----|------|
| Marqdo | https://github.com | |
**`foot`**
-12
View File
@@ -1,12 +0,0 @@
## nav
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| 首页 | / | |
| 关于 | /about | |
| 写文章 | /new | |
| 后台 | /admin | |
**`nav`**
@@ -1,10 +0,0 @@
## side
`side` =
| 属性 | 值 | 样式 |
|------|-----|------|
| 笔记 | / | |
| 文档 | https://github.com | |
**`side`**
-22
View File
@@ -1,22 +0,0 @@
## schema
`fields` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| title | text | false |
| body | text | true |
**`fields`**
## seed
`rows` =
| id | title | body |
|----|-------|------|
| 1 | 你好 Marqdo | 第一篇来自 GFM 表格。 |
| 2 | 代码即文档 | 页面表就是程序。 |
**`rows`**
-19
View File
@@ -1,19 +0,0 @@
---
title: db/index
description: 打开 sqlite、建表、幂等种子。
> ext/web/网页.mq.md
> articles.mq.md as articles
---
## open
*`store` = > 网页.数据库 地址="sqlite:data/site-zh.db" *
*`fields` = > articles.schema *
> `store`.初始化 名=articles 字段=`fields`
*`rows` = > `store`.查询 表=articles 上限=1 *
1. `rows`
**`store`**
2. *
*`seed` = > articles.seed *
> `store`.插入 表=articles 行=`seed`
**`store`**
-65
View File
@@ -1,65 +0,0 @@
---
title: 中文站点示例
description: Home + /about + /new(表单嵌入)+ 后台;只用 ext/web/网页.mq.md。
> ext/web/网页.mq.md
> styles/shell.mq.md
> components/nav.mq.md
> components/side.mq.md
> components/foot.mq.md
> db/articles.mq.md
> db/index.mq.md as db
---
# main
`home` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side_panel` |
| foot.`foot` | |
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card_title` |
| `body` | articles.`articles`.body | shell.`card_body` |
`article_fields` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | 标题 | text | true | |
| body | 正文 | textarea | false | |
`article_rules` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | 标题不能为空 |
| title | max:120 | 标题太长 |
| body | max:8000 | 正文太长 |
*`store` = > db.open *
*`page` = > 网页.页面 标题="Marqdo 中文站" 引言="<h1>中文站</h1><p>表格 + 类方法。</p>" *
*`page` = > `page`.组件装配 组件=`home` *
*`page` = > `page`.主体装配 主体=`index` *
*`about` = > 网页.页面 标题="关于" 引言="<h1>关于</h1><p>导入网页.mq.md 即用中文 API。</p>" *
*`about` = > `about`.组件装配 组件=`home` *
*`article_form` = > 网页.表单 表=articles 动作=插入 *
*`article_form` = > `article_form`.字段 字段=`article_fields` *
*`article_form` = > `article_form`.规则 规则=`article_rules` *
*`new` = > 网页.页面 标题="写文章" 引言="<h1>写文章</h1><p>表单嵌在主区。</p>" *
*`new` = > `new`.组件装配 组件=`home` *
*`new` = > `new`.表单装配 id=article 表单=`article_form` *
*`app` = > 网页.应用 页面=`page` 数据库=`store` 后台=True 主机=127.0.0.1 端口=18082 *
*`app` = > `app`.路由 路径=/about 页面=`about` *
*`app` = > `app`.路由 路径=/new 页面=`new` *
*`app` = > `app`.静态 目录=public 挂载=/static *
> `app`.监听
-5
View File
@@ -1,5 +0,0 @@
/* 可选站点样式 — /static/site.css */
body.site-hint::before {
content: "static ok";
display: none;
}
-42
View File
@@ -1,42 +0,0 @@
## topnav
`topnav` =
| 属性 | 值 |
|------|-----|
| background | #ffffff |
| border-bottom | 1px solid #e7e5e4 |
**`topnav`**
## side_panel
`side_panel` =
| 属性 | 值 |
|------|-----|
| background | #f5f5f4 |
**`side_panel`**
## card_title
`card_title` =
| 属性 | 值 |
|------|-----|
| font-size | 1.15rem |
| margin | 0 0 0.35rem |
**`card_title`**
## card_body
`card_body` =
| 属性 | 值 |
|------|-----|
| color | #57534e |
| margin | 0 |
**`card_body`**
-10
View File
@@ -1,10 +0,0 @@
# examples/web-site
Canonical English sample for `ext/web` (design §4).
```bash
cargo build -p marqdo_plugin_web
cargo run -- examples/web-site/index.mq.md
```
Then open http://127.0.0.1:18081/ — `/about`, `/new` (form in page slot), `/admin`, `/static/site.css`.
-9
View File
@@ -1,9 +0,0 @@
## foot
`foot` =
| 属性 | 值 | 样式 |
|------|-----|------|
| Marqdo | https://github.com | |
**`foot`**
-14
View File
@@ -1,14 +0,0 @@
## nav
Static top links for the shell.
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| Home | / | |
| About | /about | |
| New | /new | |
| Admin | /admin | |
**`nav`**
-10
View File
@@ -1,10 +0,0 @@
## side
`side` =
| 属性 | 值 | 样式 |
|------|-----|------|
| Notes | / | |
| Docs | https://github.com | |
**`side`**
-22
View File
@@ -1,22 +0,0 @@
## schema
`fields` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| title | text | false |
| body | text | true |
**`fields`**
## seed
`rows` =
| id | title | body |
|----|-------|------|
| 1 | Hello Marqdo | First article from a GFM table. |
| 2 | Code as docs | The page table is the program. |
**`rows`**
-20
View File
@@ -1,20 +0,0 @@
---
title: db/index
description: Open sqlite, init articles, seed once.
> ext/web/web.mq.md
> articles.mq.md as articles
> lib/fs.mq.md
---
## open
*`store` = > web.db url="sqlite:data/site.db" *
*`fields` = > articles.schema *
> `store`.init name=articles fields=`fields`
*`rows` = > `store`.select table=articles limit=1 *
1. `rows`
**`store`**
2. *
*`seed` = > articles.seed *
> `store`.insert table=articles rows=`seed`
**`store`**
-73
View File
@@ -1,73 +0,0 @@
---
title: web-site
description: Home + /about + /new (form in page slot) + admin.
> ext/web/web.mq.md
> styles/shell.mq.md
> components/nav.mq.md
> components/side.mq.md
> components/foot.mq.md
> db/articles.mq.md
> db/index.mq.md as db
---
# main
`home` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side_panel` |
| foot.`foot` | |
Main content is not a reusable component, so it is authored here.
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card_title` |
| `body` | articles.`articles`.body | shell.`card_body` |
Article create form (design §5.5): field table + rules table.
`article_fields` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | Title | text | true | |
| body | Body | textarea | false | |
`article_rules` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | Title is required |
| title | max:120 | Title is too long |
| body | max:8000 | Body is too long |
*`store` = > db.open *
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1><p>Tables + class methods.</p>" *
*`page` = > `page`.compose_components components=`home` *
*`page` = > `page`.compose_main main=`index` *
About page: same shell, different intro (no main bind).
*`about` = > web.page title="About" intro="<h1>About</h1><p>Marqdo web = tables + class methods.</p>" *
*`about` = > `about`.compose_components components=`home` *
*`article_form` = > web.form table=articles action=insert *
*`article_form` = > `article_form`.fields fields=`article_fields` *
*`article_form` = > `article_form`.rules rules=`article_rules` *
New article: form embedded in the page main slot (design §5.5.4).
*`new` = > web.page title="New article" intro="<h1>New article</h1><p>Form lives in the main slot.</p>" *
*`new` = > `new`.compose_components components=`home` *
*`new` = > `new`.compose_form id=article form=`article_form` *
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
*`app` = > `app`.route path=/about page=`about` *
*`app` = > `app`.route path=/new page=`new` *
*`app` = > `app`.static dir=public mount=/static *
> `app`.listen
-5
View File
@@ -1,5 +0,0 @@
/* Optional site stylesheet — served at /static/site.css */
body.site-hint::before {
content: "static ok";
display: none;
}
-42
View File
@@ -1,42 +0,0 @@
## topnav
`topnav` =
| 属性 | 值 |
|------|-----|
| background | #ffffff |
| border-bottom | 1px solid #e7e5e4 |
**`topnav`**
## side_panel
`side_panel` =
| 属性 | 值 |
|------|-----|
| background | #f5f5f4 |
**`side_panel`**
## card_title
`card_title` =
| 属性 | 值 |
|------|-----|
| font-size | 1.15rem |
| margin | 0 0 0.35rem |
**`card_title`**
## card_body
`card_body` =
| 属性 | 值 |
|------|-----|
| color | #57534e |
| margin | 0 |
**`card_body`**
-1859
View File
File diff suppressed because it is too large. Load diff
-126
View File
@@ -1,126 +0,0 @@
---
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
> lib/table.mq.md
---
## load_env
+ `path`=None
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
**> sys.load_dotenv path=`path`**
## stream_result
+ `events`
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown event types abort.
*answer = ""*
- [ev](events)
*t = ev[^type]*
1. `t` == "done"
*answer = ev[^result]*
2. `t` == "error"
*answer = ev[^message]*
3. `t` == "delta"
4. *
> print text=ext/ai/llm: unexpected SSE event type
> print text=`t`
> sys.exit code=1
**answer**
# llm
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*`.
*api_key = > sys.env_get name=OPENAI_API_KEY*
1. not `api_key`
*api_key = > sys.env_get name=MARQDO_LLM_API_KEY*
1. not `api_key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
> sys.exit code=1
*base_url = > sys.env_get name=OPENAI_BASE_URL*
1. not `base_url`
*base_url = > sys.env_get name=MARQDO_LLM_BASE_URL*
1. not `base_url`
*base_url = "https://api.openai.com/v1"*
*model = > sys.env_get name=OPENAI_MODEL*
1. not `model`
*model = > sys.env_get name=MARQDO_LLM_MODEL*
1. not `model`
*model = "gpt-4o-mini"*
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
**h**
## complete
+ `prompt`
+ `stream`=False
+ `echo`=False
Chat completion using `self` handle fields.
Wire body is `{model, messages:[{role,content}], stream?}`. Messages are an `@` row table; headers and optional `stream` use `table.put`. `json` is only for stringify/parse.
*url = self[^base_url] + self[^suffix]*
*auth = self[^bearer] + self[^api_key]*
*headers = > table.put in=None at=Authorization value=`auth`*
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `prompt` |
`req` =
| model | messages |
|-------|----------|
| self[^model] | `messages` |
1. `stream`
*req = > table.put in=`req` at=stream value=True*
*body = > json.stringify value=`req`*
*resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`*
1. resp[^status] == 200
**resp[^events]**
2. *
> print text=ext/ai/llm: HTTP error (stream)
> print text=resp[^status]
> sys.exit code=1
2. *
*body = > json.stringify value=`req`*
*resp = > net.http_post url=`url` body=`body` headers=`headers`*
1. resp[^status] == 200
*data = > json.parse text=resp[^body]*
**data[^choices][^1][^message][^content]**
2. *
> print text=ext/ai/llm: HTTP error
> print text=resp[^status]
> print text=resp[^body]
> sys.exit code=1
---
## chat
+ `prompt`
+ `stream`=False
+ `echo`=False
Alias for `complete`.
**> `self`.complete prompt=`prompt` stream=`stream` echo=`echo`**
-126
View File
@@ -1,126 +0,0 @@
---
title: ext/ai/大模型
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
> lib/系统.mq.md
> lib/网络.mq.md
> lib/json.mq.md
> lib/表.mq.md
---
## 加载环境
+ `路径`=None
从工作目录加载 `.env`(可选命名实参 `路径=`)。不覆盖已有变量。
**> 系统.加载环境 路径=`路径`**
## 流式结果
+ `事件`
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知事件类型直接失败。
*answer = ""*
- [ev](事件)
*t = ev[^type]*
1. `t` == "done"
*answer = ev[^result]*
2. `t` == "error"
*answer = ev[^message]*
3. `t` == "delta"
4. *
> 打印 内容=ext/ai/大模型: 未预期的 SSE 事件类型
> 打印 内容=`t`
> 系统.退出 码=1
**answer**
# 大模型
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄。
*api_key = > 系统.取环境 名=OPENAI_API_KEY*
1. 非 `api_key`
*api_key = > 系统.取环境 名=MARQDO_LLM_API_KEY*
1. 非 `api_key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
> 系统.退出 码=1
*base_url = > 系统.取环境 名=OPENAI_BASE_URL*
1. 非 `base_url`
*base_url = > 系统.取环境 名=MARQDO_LLM_BASE_URL*
1. 非 `base_url`
*base_url = "https://api.openai.com/v1"*
*model = > 系统.取环境 名=OPENAI_MODEL*
1. 非 `model`
*model = > 系统.取环境 名=MARQDO_LLM_MODEL*
1. 非 `model`
*model = "gpt-4o-mini"*
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
**h**
## 运行
+ `提示`
+ `流式`=False
+ `打印增量`=False
使用 `自` 句柄字段做聊天补全。
线上 body 为 `{model, messages:[{role,content}], stream?}`。消息用 `@` 行向表;headers 与可选 `stream` 用 `表.改`。`json` 只做 stringify/parse。
*url = 自[^base_url] + 自[^suffix]*
*auth = 自[^bearer] + 自[^api_key]*
*headers = > 表.改 入=None 于=Authorization 值=`auth`*
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `提示` |
`req` =
| model | messages |
|-------|----------|
| 自[^model] | `messages` |
1. `流式`
*req = > 表.改 入=`req` 于=stream 值=True*
*body = > json.stringify value=`req`*
*resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`*
1. resp[^status] == 200
**resp[^events]**
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误(流式)
> 打印 内容=resp[^status]
> 系统.退出 码=1
2. *
*body = > json.stringify value=`req`*
*resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`*
1. resp[^status] == 200
*data = > json.parse text=resp[^body]*
**data[^choices][^1][^message][^content]**
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误
> 打印 内容=resp[^status]
> 打印 内容=resp[^body]
> 系统.退出 码=1
---
## 聊天
+ `提示`
+ `流式`=False
+ `打印增量`=False
运行 的别名。
**> `自`.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`**
-235
View File
@@ -1,235 +0,0 @@
---
title: ext/ai/智能体
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
> ext/ai/大模型.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/系统.mq.md
> lib/自写回.mq.md
> lib/子任务.mq.md
> lib/插件.mq.md
---
## 构建单步上下文
+ `智能体`
+ `任务`
组装可读提示:站立提示、任务、工具、调用位置、源码、Skill,以及人可见的行动约定。
*`standing` = > json.get value=`智能体` key=standing *
1. `standing`
*`up` = `standing`*
2. *
*`up` = 空*
*`tools` = > json.get value=`智能体` key=tools *
*`tools_s` = > agent_format_tools tools=`tools` *
*`src` = > agent_module_source *
*`site` = > agent_call_site *
*`site_s` = > json.stringify value=`site` *
*`skill` = > agent_marqdo_skill *
*`task_s` = > json.stringify value=`任务` *
*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"} *
*`a` = > json.get value=`esc` key=a *
*`b` = > json.get value=`esc` key=b *
*`c` = > json.get value=`esc` key=c *
*`d` = > json.get value=`esc` key=d *
*`e` = > json.get value=`esc` key=e *
*`f` = > json.get value=`esc` key=f *
*`g` = > json.get value=`esc` key=g *
*`p` = "You are a Marqdo agent. The runbook source is your ground truth — code is documentation." *
*`p` = `p` + `a` + `up` + `b` + `task_s` + `c` + `tools_s` + `g` + `d` + `site_s` + `e` + `src` + `f` + `skill` *
**`p`**
---
## 提取工具名
+ `回复`
解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。
*`esc` = > json.parse text={"nl":"\n"} *
*`nl` = > json.get value=`esc` key=nl *
*`text` = > trim value=`回复` *
*`lines` = > split value=`text` sep=`nl` *
*`found` = 空*
- [`line`](`lines`)
*`t` = > trim value=`line` *
*`parts` = > split value=`t` sep=: *
*`n` = > len value=`parts` *
1. `n` > 1
*`head` = > at value=`parts` index=0 *
*`head` = > trim value=`head` *
*`rest` = > at value=`parts` index=1 *
*`rest` = > trim value=`rest` *
1. `head` == CALL
*`found` = `rest`*
2. `head` == 调用
*`found` = `rest`*
3. *
*`_` = 1*
2. *
*`_` = 1*
**`found`**
---
## 运行工具
+ `工具`
+ `名`
白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。
*`allowed` = > agent_tool_allowed tools=`工具` name=`名` *
1. `allowed`
*`id` = > 子任务.启动 函数=`名` *
**> 子任务.等待 id=`id`**
2. *
*`msg` = "Tool not allowed:" *
**`msg` + `名`**
# 智能体
+ `大模型`
+ `工具`
+ `站立提示`
加载 ABI v2 agent 插件(会话袋 + 上下文查询)。
*`p` = > 插件.原生路径 名=agent *
1. `p`
> 插件.加载 路径=`p`
2. *
> 打印 内容=ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent)
> 系统.退出 码=1
*`id` = > agent_alloc *
*`h` = > json.parse text={"_type":"智能体"} *
*`h` = > json.set map=`h` key=id value=`id` *
*`h` = > json.set map=`h` key=model value=`大模型` *
*`h` = > json.set map=`h` key=tools value=`工具` *
1. `站立提示`
*`h` = > json.set map=`h` key=standing value=`站立提示` *
2. *
*`_` = 1*
**`h`**
## 清空历史
清空本智能体 id 的插件会话袋。
*`id` = > json.get value=`自` key=id *
> agent_history_clear id=`id`
****
## 单步
+ `任务`
+ `写回`=真
+ `流式`=假
+ `打印增量`=假
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
*`ctx` = > 构建单步上下文 智能体=`自` 任务=`任务` *
*`id` = > json.get value=`自` key=id *
*`model` = > json.get value=`自` key=model *
*`tools` = > json.get value=`自` key=tools *
*`user_turn` = > json.parse text={"role":"user"} *
*`user_turn` = > json.set map=`user_turn` key=content value=`任务` *
> agent_history_append id=`id` item=`user_turn`
1. `流式`
*`evs` = > `model`.运行 提示=`ctx` 流式=真 打印增量=`打印增量` *
*`reply` = > 大模型.流式结果 事件=`evs` *
2. *
*`reply` = > `model`.运行 提示=`ctx` *
*`reply` = > trim value=`reply` *
*`decision` = `reply`*
*`tool_name` = > 提取工具名 回复=`reply` *
*`out` = > json.parse text={"status":"ok"} *
*`out` = > json.set map=`out` key=task value=`任务` *
*`out` = > json.set map=`out` key=decision value=`decision` *
1. `tool_name`
*`tool_out` = > 运行工具 工具=`tools` 名=`tool_name` *
*`tool_s` = > json.stringify value=`tool_out` *
*`deny` = > split value=`tool_s` sep=Tool not allowed *
*`deny_n` = > len value=`deny` *
1. `deny_n` > 1
*`out` = > json.set map=`out` key=status value=error *
*`out` = > json.set map=`out` key=error value=`tool_s` *
*`reply` = `tool_s`*
2. *
*`task_s` = > json.stringify value=`任务` *
*`fp` = "The user asked:" *
*`fp` = `fp` + `task_s` *
*`fp` = `fp` + ". Tool" *
*`fp` = `fp` + `tool_name` *
*`fp` = `fp` + "ran via subtask and returned:" *
*`fp` = `fp` + `tool_s` *
*`fp` = `fp` + ". Reply to the user briefly." *
1. `流式`
*`evs2` = > `model`.运行 提示=`fp` 流式=真 打印增量=`打印增量` *
*`reply` = > 大模型.流式结果 事件=`evs2` *
2. *
*`reply` = > `model`.运行 提示=`fp` *
*`out` = > json.set map=`out` key=tool value=`tool_name` *
*`out` = > json.set map=`out` key=tool_result value=`tool_s` *
*`out` = > json.set map=`out` key=result value=`reply` *
2. *
*`out` = > json.set map=`out` key=result value=`reply` *
*`as_turn` = > json.parse text={"role":"assistant"} *
*`as_turn` = > json.set map=`as_turn` key=content value=`reply` *
> agent_history_append id=`id` item=`as_turn`
1. `写回`
*`body` = > json.stringify value=`out` *
*`st` = > json.get value=`out` key=status *
1. `st` == ok
> 自写回.写回 值=`body` 键=ok
2. *
> 自写回.写回 值=`body` 键=error
2. *
*`_` = 1*
**`out`**
## 多步
+ `目标`
+ `工作簿目录`=None
+ `工作簿`=None
+ `最大轮次`=4
+ `确认分解`=False
+ `写回`=True
+ `骨架`=single
+ `复用`=True
+ `优化`=False
+ `强制`=False
+ `软命中`=False
+ `近义命中`=True
+ `近义阈值`=0.78
+ `晋升`=True
+ `知识库目录`=.marqdo/agent-kb
+ `改进周期`=3
+ `探索次数`=3
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。
*`model` = > json.get value=`self` key=model *
*`tools` = > json.get value=`self` key=tools *
*`standing` = > json.get value=`self` key=standing *
*`en` = > agent.agent model=`model` tools=`tools` standing=`standing` *
**> `en`.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`**
-201
View File
@@ -1,201 +0,0 @@
---
title: ext/quantum/quantum
description: Official quantum circuit simulator (English). Gates + circuits; ABI plugin.
> lib/plugin.mq.md
> lib/sys.mq.md
> lib/json.mq.md
---
## ensure_plugin
Load the ABI v2 `quantum` plugin once.
*`p` = > plugin.native_path name=quantum *
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/quantum: native quantum plugin not found (build marqdo_plugin_quantum or marqdo ext add quantum)
> sys.exit code=1
****
# circuit
+ `qubits`=1
+ `steps`=None
State-vector circuit (default |0…0⟩). Optional `steps=` gate table (column or row records). Methods append gates and return an updated handle.
> ensure_plugin
**> quantum_circuit_new qubits=`qubits` steps=`steps`**
## h
+ `qubit`=0
**> quantum_h circuit=`self` qubit=`qubit`**
## x
+ `qubit`=0
**> quantum_x circuit=`self` qubit=`qubit`**
## y
+ `qubit`=0
**> quantum_y circuit=`self` qubit=`qubit`**
## z
+ `qubit`=0
**> quantum_z circuit=`self` qubit=`qubit`**
## s
+ `qubit`=0
**> quantum_s circuit=`self` qubit=`qubit`**
## t
+ `qubit`=0
**> quantum_t circuit=`self` qubit=`qubit`**
## i
+ `qubit`=0
**> quantum_i circuit=`self` qubit=`qubit`**
## rx
+ `qubit`=0
+ `theta`
**> quantum_rx circuit=`self` qubit=`qubit` theta=`theta`**
## ry
+ `qubit`=0
+ `theta`
**> quantum_ry circuit=`self` qubit=`qubit` theta=`theta`**
## rz
+ `qubit`=0
+ `theta`
**> quantum_rz circuit=`self` qubit=`qubit` theta=`theta`**
## cx
+ `control`=0
+ `target`=1
**> quantum_cx circuit=`self` control=`control` target=`target`**
## cz
+ `control`=0
+ `target`=1
**> quantum_cz circuit=`self` control=`control` target=`target`**
## swap
+ `a`=0
+ `b`=1
**> quantum_swap circuit=`self` a=`a` b=`b`**
## barrier
Visual separator only (no state change).
**> quantum_barrier circuit=`self`**
## measure
+ `qubits`=None
Mark computational-basis readout (`None` / empty = all qubits). Affects which bits `run` reports.
**> quantum_measure circuit=`self` qubits=`qubits`**
## append
+ `op`
Append another circuit's ops or a `{gate,qubits}` op map.
**> quantum_append circuit=`self` op=`op`**
## apply
+ `gate`
+ `qubits`=0
Apply a gate handle (named or custom `matrix=`) on `qubits` (int or list).
**> quantum_apply circuit=`self` gate=`gate` qubits=`qubits`**
## noise
+ `kind`
+ `p`
Teaching noise for `run` trajectories (`bitflip` / `depolarizing` / `amplitude_damping`). Ignored by `simulate` / `probabilities`.
**> quantum_noise circuit=`self` kind=`kind` p=`p`**
## simulate
Return state vector amplitudes `{re,im}` (ideal; no noise).
**> quantum_simulate circuit=`self`**
## state
Ideal state vector (same amplitudes as `simulate`).
**> quantum_state circuit=`self`**
## probabilities
Return map of basis label → probability (qubit 0 = rightmost bit). Ideal; ignores noise.
**> quantum_probabilities circuit=`self`**
## run
+ `shots`=1024
+ `seed`=1
Sample computational-basis shots (deterministic with `seed=`). Applies circuit `noise` if set.
**> quantum_run circuit=`self` shots=`shots` seed=`seed`**
## draw
+ `path`=None
+ `kind`=circuit
+ `qubit`=0
Circuit rail / probability bars / Bloch sphere SVG (`kind=circuit|probs|bloch`). Records into view/CLI plots via host `record_plot`.
**> quantum_draw_circuit circuit=`self` path=`path` kind=`kind` qubit=`qubit`**
# gate
+ `name`=None
+ `theta`=None
+ `matrix`=None
Named built-in gate (`name=H`) or custom unitary from `matrix=` (nested list / `$$` matrix fence). Optional `name=` label for custom gates (default `U`).
> ensure_plugin
1. `matrix`
**> quantum_gate_from_matrix matrix=`matrix` name=`name`**
2. *
**> quantum_gate_new name=`name` theta=`theta`**
## matrix
**> quantum_gate_matrix gate=`self`**
## matches_matrix
+ `matrix`
+ `tol`=0.000000001
**> quantum_gate_matches_matrix gate=`self` matrix=`matrix` tol=`tol`**
## draw
+ `path`=None
+ `kind`=gate
Gate glyph or complex-matrix heatmap (`kind=gate|matrix`). Records via host `record_plot`.
**> quantum_gate_draw gate=`self` path=`path` kind=`kind`**
-201
View File
@@ -1,201 +0,0 @@
---
title: ext/quantum/量子
description: 官方量子电路模拟(中文)。门 + 电路;ABI 插件。
> lib/plugin.mq.md
> lib/sys.mq.md
> lib/json.mq.md
---
## 确保插件
加载 ABI v2 `quantum` 插件。
*`p` = > plugin.native_path name=quantum *
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/quantum: 未找到原生 quantum 插件(请 build marqdo_plugin_quantum 或 marqdo ext add quantum)
> sys.exit code=1
****
# 电路
+ `比特数`=1
+ `步骤`=None
状态向量电路(默认 |0…0⟩)。可选 `步骤=` 门序列表。方法追加门并返回更新后的句柄。
> 确保插件
**> quantum_circuit_new qubits=`比特数` steps=`步骤`**
## 哈达玛
+ `比特`=0
**> quantum_h circuit=`self` qubit=`比特`**
## 泡利X
+ `比特`=0
**> quantum_x circuit=`self` qubit=`比特`**
## 泡利Y
+ `比特`=0
**> quantum_y circuit=`self` qubit=`比特`**
## 泡利Z
+ `比特`=0
**> quantum_z circuit=`self` qubit=`比特`**
## 相位S
+ `比特`=0
**> quantum_s circuit=`self` qubit=`比特`**
## 相位T
+ `比特`=0
**> quantum_t circuit=`self` qubit=`比特`**
## 单位
+ `比特`=0
**> quantum_i circuit=`self` qubit=`比特`**
## 绕X
+ `比特`=0
+ `参数`
**> quantum_rx circuit=`self` qubit=`比特` theta=`参数`**
## 绕Y
+ `比特`=0
+ `参数`
**> quantum_ry circuit=`self` qubit=`比特` theta=`参数`**
## 绕Z
+ `比特`=0
+ `参数`
**> quantum_rz circuit=`self` qubit=`比特` theta=`参数`**
## 控非
+ `控制`=0
+ `目标`=1
**> quantum_cx circuit=`self` control=`控制` target=`目标`**
## 控相
+ `控制`=0
+ `目标`=1
**> quantum_cz circuit=`self` control=`控制` target=`目标`**
## 交换
+ `比特甲`=0
+ `比特乙`=1
**> quantum_swap circuit=`self` a=`比特甲` b=`比特乙`**
## 屏障
仅可视化分隔(不改态)。
**> quantum_barrier circuit=`self`**
## 测量
+ `比特`=None
标记计算基读出(空 = 全部比特)。影响 `运行` 报告哪些位。
**> quantum_measure circuit=`self` qubits=`比特`**
## 追加
+ `操作`
追加另一电路的 ops,或 `{gate,qubits}` 操作表。
**> quantum_append circuit=`self` op=`操作`**
## 施加
+ `门`
+ `比特`=0
将门句柄(具名或 `矩阵=` 自定义)施加到 `比特`(整数或列表)。
**> quantum_apply circuit=`self` gate=`门` qubits=`比特`**
## 噪声
+ `种类`
+ `概率`
教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` / `amplitude_damping`,或中文:比特翻转 / 退极化 / 振幅阻尼)。`模拟` / `概率` 忽略。
**> quantum_noise circuit=`self` kind=`种类` p=`概率`**
## 模拟
返回态矢量振幅 `{re,im}`(理想;无噪声)。
**> quantum_simulate circuit=`self`**
## 态
理想态矢量(与 `模拟` 相同振幅)。
**> quantum_state circuit=`self`**
## 概率
基矢标签 → 概率(qubit 0 为最右侧比特)。理想;忽略噪声。
**> quantum_probabilities circuit=`self`**
## 运行
+ `次数`=1024
+ `种子`=1
计算基采样(`种子=` 可复现)。若设置了电路噪声则启用。
**> quantum_run circuit=`self` shots=`次数` seed=`种子`**
## 绘图
+ `路径`=None
+ `种类`=circuit
+ `比特`=0
电路轨线 / 概率条 / 布洛赫球(种类 circuit、probs 或 bloch)。经 record_plot 进入 view/CLI plots。
**> quantum_draw_circuit circuit=`self` path=`路径` kind=`种类` qubit=`比特`**
# 门
+ `名`=None
+ `参数`=None
+ `矩阵`=None
具名内置门(`名=H`)或由 `矩阵=`(嵌套 list / `$$` 矩阵围栏)定义的自定义酉门。自定义门可选 `名=`(默认 `U`)。
> 确保插件
1. `矩阵`
**> quantum_gate_from_matrix matrix=`矩阵` name=`名`**
2. *
**> quantum_gate_new name=`名` theta=`参数`**
## 矩阵
**> quantum_gate_matrix gate=`self`**
## 匹配矩阵
+ `矩阵`
+ `容差`=0.000000001
**> quantum_gate_matches_matrix gate=`self` matrix=`矩阵` tol=`容差`**
## 绘图
+ `路径`=None
+ `种类`=gate
门符号或复矩阵热力图(`种类=gate|matrix`)。经 `record_plot` 记录。
**> quantum_gate_draw gate=`self` path=`路径` kind=`种类`**
-31
View File
@@ -1,31 +0,0 @@
# ext/web
Official dynamic website extension: **GFM tables + class methods**.
Design: [`doc/design/ext-web.md`](../../doc/design/ext-web.md).
| Surface | Import | Classes |
|---------|--------|---------|
| English | `> ext/web/web.mq.md` | `page` · `db` · `app` · `form` · `style` |
| Chinese | `> ext/web/网页.mq.md` | `页面` · `数据库` · `应用` · `表单` · `样式` |
```bash
cargo build -p marqdo_plugin_web
# optional install into ~/.marqdo/ext
marqdo ext add web
```
Canonical sample (design §4): [`examples/web-site/`](../../examples/web-site/).
```bash
cargo run -- run examples/web-site/index.mq.md
# http://127.0.0.1:18081/
# /_form/article · /admin · /admin/articles/new
```
Offline smokes: `tests/ext/web-smoke.mq.md`, `web-form-smoke.mq.md`, `web-admin-smoke.mq.md`.
| Feature | Notes |
|---------|--------|
| Form §5.5 | field/rules tables · `validate` · `submit` · `mount_form` → `GET\|POST /_form/{id}` |
| Admin CRUD | `admin=True` · schema → same form path · new/edit/delete under `/admin/{table}` |
| Route | `` `app`.route path=/about page=`about` `` → `GET /about` |
-213
View File
@@ -1,213 +0,0 @@
---
title: ext/web/web
description: Official web site classes (English). Tables + methods; no bag glue.
> lib/plugin.mq.md
> lib/sys.mq.md
> lib/json.mq.md
---
## ensure_plugin
Load the ABI v2 `web` plugin once.
*`p` = > plugin.native_path name=web *
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/web: native web plugin not found (build marqdo_plugin_web or marqdo ext add web)
> sys.exit code=1
****
# page
+ `title`="Marqdo Web"
+ `intro`=""
> ensure_plugin
**> web_page_new title=`title` intro=`intro`**
## compose_components
+ `components`
Assemble nav / sidebar / footer from a page table (`|组件|样式|` or `|src|style|`).
**> web_compose_components page=`self` components=`components`**
## compose_main
+ `main`
Assemble main from a bind table (`|属性|值|样式|` or `|front|back|css|`).
**> web_compose_main page=`self` main=`main`**
## compose_form
+ `form`
+ `id`
Embed a form into the page main slot. `listen` auto-registers `GET|POST /_form/{id}` from page/route forms (optional `app.mount_form`).
**> web_compose_form page=`self` form=`form` id=`id`**
## render
+ `db`=None
Offline HTML for tests / previews.
1. `db`
*`url` = > json.get value=`db` key=url *
**> web_render page=`self` url=`url`**
2. *
**> web_render page=`self`**
# style
+ `name`=""
Style tables live as `##` exports in site style modules; compose resolves them by path.
**`self`**
## process
+ `style`=None
+ `name`=None
+ `path`=None
**`self`**
# db
+ `url`="sqlite:site.db"
> ensure_plugin
**> web_db_new url=`url`**
## init
+ `name`
+ `fields`
*`url` = > json.get value=`self` key=url *
**> web_db_init url=`url` name=`name` fields=`fields`**
## insert
+ `table`
+ `rows`
*`url` = > json.get value=`self` key=url *
**> web_db_insert url=`url` table=`table` rows=`rows`**
## select
+ `table`
+ `where`=None
+ `limit`=200
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like`).
*`url` = > json.get value=`self` key=url *
*`r` = > web_db_select url=`url` table=`table` where=`where` limit=`limit` *
**> json.get value=`r` key=rows**
## get
+ `table`
+ `id`
*`url` = > json.get value=`self` key=url *
**> web_db_get url=`url` table=`table` id=`id`**
## update
+ `table`
+ `id`
+ `row`
*`url` = > json.get value=`self` key=url *
**> web_db_update url=`url` table=`table` id=`id` row=`row`**
## delete
+ `table`
+ `id`
*`url` = > json.get value=`self` key=url *
**> web_db_delete url=`url` table=`table` id=`id`**
## exec
+ `sql`
+ `args`=None
*`url` = > json.get value=`self` key=url *
**> web_db_exec url=`url` sql=`sql` args=`args`**
# form
+ `table`=None
+ `action`=insert
+ `id`=None
Field table + rules table; submit writes through `# db`.
> ensure_plugin
**> web_form_new table=`table` action=`action` id=`id`**
## fields
+ `fields`
**> web_form_fields form=`self` fields=`fields`**
## rules
+ `rules`
**> web_form_rules form=`self` rules=`rules`**
## validate
+ `rules`=None
+ `data`
**> web_form_validate form=`self` rules=`rules` data=`data`**
## render
+ `id`=form
+ `data`=None
+ `errors`=None
**> web_form_render form=`self` id=`id` data=`data` errors=`errors`**
## submit
+ `data`
+ `db`
*`url` = > json.get value=`db` key=url *
**> web_form_submit form=`self` data=`data` url=`url`**
# app
+ `page`
+ `db`=None
+ `admin`=False
+ `host`=127.0.0.1
+ `port`=18081
> ensure_plugin
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port`**
## route
+ `path`
+ `page`
Mount an assembled page at `path` (e.g. `/about`). `/` is the home `page=`.
**> web_app_route app=`self` path=`path` page=`page`**
## mount_form
+ `id`
+ `form`
Register `GET|POST /_form/{id}` for listen when the form is not already embedded via `page.compose_form`.
**> web_app_mount_form app=`self` id=`id` form=`form`**
## static
+ `dir`
+ `mount`=/static
Serve files from `dir` under `mount` (default `/static`). Path is resolved from the process working directory at listen time.
**> web_app_static app=`self` dir=`dir` mount=`mount`**
## listen
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), and optional `/admin`.
**> web_listen app=`self`**
-203
View File
@@ -1,203 +0,0 @@
---
title: ext/web/网页
description: 官方网站类(中文)。表格 + 方法;不写袋式胶水。
> lib/plugin.mq.md
> lib/sys.mq.md
> lib/json.mq.md
---
## 确保插件
加载 ABI v2 `web` 插件。
*`p` = > plugin.native_path name=web *
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/web: 未找到原生 web 插件(请 build marqdo_plugin_web 或 marqdo ext add web)
> sys.exit code=1
****
# 页面
+ `标题`="站点"
+ `引言`=""
> 确保插件
**> web_page_new title=`标题` intro=`引言`**
## 组件装配
+ `组件`
**> web_compose_components page=`self` components=`组件`**
## 主体装配
+ `主体`
**> web_compose_main page=`self` main=`主体`**
## 表单装配
+ `表单`
+ `id`
将表单嵌入页面主区。`listen` 会从页面/路由上的表单自动挂载 `GET|POST /_form/{id}`(可选再 `挂载表单`)。
**> web_compose_form page=`self` form=`表单` id=`id`**
## 渲染
+ `数据库`=None
1. `数据库`
*`url` = > json.get value=`数据库` key=url *
**> web_render page=`self` url=`url`**
2. *
**> web_render page=`self`**
# 样式
+ `名`=""
**`self`**
## 样式处理
+ `样式`=None
+ `名`=None
+ `路径`=None
**`self`**
# 数据库
+ `地址`="sqlite:site.db"
> 确保插件
**> web_db_new url=`地址`**
## 初始化
+ `名`
+ `字段`
*`url` = > json.get value=`self` key=url *
**> web_db_init url=`url` name=`名` fields=`字段`**
## 插入
+ `表`
+ `行`
*`url` = > json.get value=`self` key=url *
**> web_db_insert url=`url` table=`表` rows=`行`**
## 查询
+ `表`
+ `条件`=None
+ `上限`=200
简单条件:单行列→值映射(AND `=`),或 `|字段|操作|值|` 表(`=` `!=` `>` `>=` `<` `<=` `like`)。
*`url` = > json.get value=`self` key=url *
*`r` = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` *
**> json.get value=`r` key=rows**
## 获取
+ `表`
+ `id`
*`url` = > json.get value=`self` key=url *
**> web_db_get url=`url` table=`表` id=`id`**
## 更新
+ `表`
+ `id`
+ `行`
*`url` = > json.get value=`self` key=url *
**> web_db_update url=`url` table=`表` id=`id` row=`行`**
## 删除
+ `表`
+ `id`
*`url` = > json.get value=`self` key=url *
**> web_db_delete url=`url` table=`表` id=`id`**
## 执行
+ `sql`
+ `参数`=None
*`url` = > json.get value=`self` key=url *
**> web_db_exec url=`url` sql=`sql` args=`参数`**
# 表单
+ `表`=None
+ `动作`=插入
+ `id`=None
字段表 + 校验表;提交经 `# 数据库` 写入。
> 确保插件
**> web_form_new table=`表` action=`动作` id=`id`**
## 字段
+ `字段`
**> web_form_fields form=`self` fields=`字段`**
## 规则
+ `规则`
**> web_form_rules form=`self` rules=`规则`**
## 校验
+ `规则`=None
+ `数据`
**> web_form_validate form=`self` rules=`规则` data=`数据`**
## 渲染
+ `id`=form
+ `数据`=None
+ `错误`=None
**> web_form_render form=`self` id=`id` data=`数据` errors=`错误`**
## 提交
+ `数据`
+ `数据库`
*`url` = > json.get value=`数据库` key=url *
**> web_form_submit form=`self` data=`数据` url=`url`**
# 应用
+ `页面`
+ `数据库`=None
+ `后台`=False
+ `主机`=127.0.0.1
+ `端口`=18081
> 确保插件
**> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口`**
## 路由
+ `路径`
+ `页面`
将已装配页面挂到 `路径`(如 `/about`)。`/` 由首页 `页面=` 提供。
**> web_app_route app=`self` path=`路径` page=`页面`**
## 挂载表单
+ `id`
+ `表单`
**> web_app_mount_form app=`self` id=`id` form=`表单`**
## 静态
+ `目录`
+ `挂载`=/static
将 `目录` 下的文件挂到 `挂载`(默认 `/static`)。路径在 `监听` 时相对进程工作目录解析。
**> web_app_static app=`self` dir=`目录` mount=`挂载`**
## 监听
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录,以及可选 `/admin`。
**> web_listen app=`self`**
-55
View File
@@ -1,55 +0,0 @@
/* Marqdo plugin ABI v2 — 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.
*
* v1: register_fn, alloc, free
* v2: + host_query (allowlisted host introspection for plugins)
*/
#ifndef MARQDO_ABI_H
#define MARQDO_ABI_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define MARQDO_ABI_VERSION 2u
#define MARQDO_ABI_VERSION_MIN 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);
/* Host → plugin query (v2). `name` is an allowlisted query id.
* Same success/failure convention as MarqdoPluginFn.
*/
typedef int (*MarqdoHostQueryFn)(void *userdata, const char *name, 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);
/* v2: NULL for hosts that only speak v1; required when plugin abi >= 2 */
MarqdoHostQueryFn host_query;
} 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 */
+11 -13
View File
@@ -3,25 +3,23 @@ title: lib/foreign
description: Run bound code fences and inline sources via local interpreters
---
## set_cmd
+ `lang`
+ `cmd`
# set_cmd
- lang
- cmd
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
## run
+ `code`
+ `stdin`=None
# run
- code
**> host_foreign_run code=`code` stdin=`stdin`**
**> host_foreign_run code=`code`**
## run_lang
+ `lang`
+ `source`
+ `stdin`=None
# run_lang
- lang
- source
**> host_foreign_run_lang lang=`lang` source=`source` stdin=`stdin`**
**> host_foreign_run_lang lang=`lang` source=`source`**
## langs
# langs
**> host_foreign_langs**
+16 -33
View File
@@ -3,56 +3,39 @@ title: lib/fs
description: English filesystem wrappers
---
## read_text
+ `path`
# read_text
- path
**> host_read_text path=`path`**
## write_text
+ `path`
+ `text`
# write_text
- path
- text
**> host_write_text path=`path` text=`text`**
## append_text
+ `path`
+ `text`
# append_text
- path
- text
**> host_append_text path=`path` text=`text`**
## exists
+ `path`
# exists
- path
**> host_exists path=`path`**
## list_dir
+ `path`
# list_dir
- path
**> host_list_dir path=`path`**
## make_dir
+ `path`
# make_dir
- path
**> host_make_dir path=`path`**
## remove
+ `path`
# remove
- path
**> host_remove path=`path`**
## text_patch
+ `path`
+ `find`
+ `replace`
Exact FIND→REPLACE once in a UTF-8 text file. `find` must match exactly once.
**> host_text_patch path=`path` find=`find` replace=`replace`**
## apply_patch_blocks
+ `path`
+ `text`
Apply plan-style `<<<` / FIND / === / REPLACE / `>>>` blocks from `text` to `path`.
**> host_apply_patch_blocks path=`path` text=`text`**
+10 -29
View File
@@ -3,42 +3,23 @@ title: lib/json
description: JSON parse/stringify (shared EN/ZH import)
---
## parse
+ `text`
# parse
- text
**> host_json_parse text=`text`**
## stringify
+ `value`
+ `indent`=None
# stringify
- value
**> host_json_stringify value=`value` indent=`indent`**
**> host_json_stringify value=`value`**
## get
+ `value`
+ `key`
# get
- value
- key
**> host_json_get value=`value` key=`key`**
## keys
+ `value`
# 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`**
+92 -105
View File
@@ -3,211 +3,198 @@ title: lib/math
description: High-school math — num, random, formula, plot
---
## pi
# pi
**> host_pi**
## e
# e
**> host_e**
## num
+ `value`
# num
- value
**> host_num value=`value`**
## add
+ `a`
+ `b`
# add
- a
- b
**> host_math_add a=`a` b=`b`**
## sub
+ `a`
+ `b`
# sub
- a
- b
**> host_math_sub a=`a` b=`b`**
## mul
+ `a`
+ `b`
# mul
- a
- b
**> host_math_mul a=`a` b=`b`**
## div
+ `a`
+ `b`
# div
- a
- b
**> host_math_div a=`a` b=`b`**
## pow
+ `a`
+ `b`
# pow
- a
- b
**> host_math_pow a=`a` b=`b`**
## neg
+ `value`
# neg
- value
**> host_math_neg value=`value`**
## sin
+ `value`
# sin
- value
**> host_math_sin value=`value`**
## cos
+ `value`
# cos
- value
**> host_math_cos value=`value`**
## tan
+ `value`
# tan
- value
**> host_math_tan value=`value`**
## asin
+ `value`
# asin
- value
**> host_math_asin value=`value`**
## acos
+ `value`
# acos
- value
**> host_math_acos value=`value`**
## atan
+ `value`
# atan
- value
**> host_math_atan value=`value`**
## sqrt
+ `value`
# sqrt
- value
**> host_math_sqrt value=`value`**
## abs
+ `value`
# abs
- value
**> host_math_abs value=`value`**
## ln
+ `value`
# ln
- value
**> host_math_ln value=`value`**
## exp
+ `value`
# exp
- value
**> host_math_exp value=`value`**
## floor
+ `value`
# floor
- value
**> host_math_floor value=`value`**
## ceil
+ `value`
# ceil
- value
**> host_math_ceil value=`value`**
## min
+ `a`
+ `b`
# min
- a
- b
**> host_math_min a=`a` b=`b`**
## max
+ `a`
+ `b`
# max
- a
- b
**> host_math_max a=`a` b=`b`**
## random
# random
**> host_random**
## random_int
+ `min`
+ `max`
# random_int
- min
- max
**> host_random_int min=`min` max=`max`**
## seed
+ `value`
# seed
- value
**> host_seed value=`value`**
## formula
+ `text`
# formula
- text
**> host_formula value=`text`**
## simplify
+ `formula`
# simplify
- formula
**> host_simplify value=`formula`**
## expand
+ `formula`
# expand
- formula
**> host_expand value=`formula`**
## diff
+ `formula`
+ `var`
# diff
- formula
- var
**> host_diff formula=`formula` var=`var`**
## subs
+ `formula`
+ `var`
+ `value`
# subs
- formula
- var
- value
**> host_subs formula=`formula` var=`var` value=`value`**
## eval
+ `formula`
+ `var`
+ `value`
# eval
- formula
- var
- value
**> host_eval formula=`formula` var=`var` value=`value`**
## solve
+ `formula`
+ `var`
+ `min`=None
+ `max`=None
# solve
- formula
- var
**> host_solve formula=`formula` var=`var` min=`min` max=`max`**
**> host_solve formula=`formula` var=`var`**
## plot
+ `formula`
+ `var`
+ `min`
+ `max`
+ `steps`=None
+ `path`=None
+ `derivative`=None
+ `grid`=None
# plot
- formula
- var
- min
- max
**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`**
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
## plot_points
+ `xs`
+ `ys`
+ `path`=None
+ `grid`=None
# plot_points
- xs
- ys
**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`**
**> host_plot_points xs=`xs` ys=`ys`**
## plot_conic
+ `kind`
+ `a`
+ `b`=None
+ `h`=None
+ `k`=None
+ `path`=None
+ `grid`=None
# plot_conic
- kind
- a
**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`**
**> host_plot_conic kind=`kind` a=`a`**
+10 -47
View File
@@ -1,57 +1,20 @@
---
title: lib/net
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
description: English minimal HTTP wrappers
---
## http_get
+ `url`
+ `headers`=None
# http_get
- url
HTTPS supported. Optional named arg `headers=` (map).
**> host_http_get url=`url`**
**> host_http_get url=`url` headers=`headers`**
# http_post
- url
- body
## http_post
+ `url`
+ `body`
+ `content_type`=None
+ `headers`=None
**> host_http_post url=`url` body=`body`**
Default content type is JSON. Optional `content_type=` / `headers=` (map).
**> host_http_post url=`url` body=`body` content_type=`content_type` headers=`headers`**
## http_post_sse
+ `url`
+ `body`
+ `content_type`=None
+ `headers`=None
+ `echo`=False
POST and consume OpenAI-compatible SSE. Returns `{status, events}` where `events` is a list of `{type, …}` maps (`delta` / `done` / `error`). Optional `echo=True` prints delta text to stdout as chunks arrive.
**> host_http_post_sse url=`url` body=`body` content_type=`content_type` headers=`headers` echo=`echo`**
## openai_sse_parse
+ `text`
+ `echo`=False
Offline: parse an OpenAI chat SSE body into the same event list (no network).
**> host_openai_sse_parse text=`text` echo=`echo`**
## http_request
+ `method`
+ `url`
+ `body`=None
+ `content_type`=None
+ `headers`=None
Optional `body=` / `content_type=` / `headers=`.
**> host_http_request method=`method` url=`url` body=`body` content_type=`content_type` headers=`headers`**
## url_encode
+ `text`
# url_encode
- text
**> host_url_encode text=`text`**
-24
View File
@@ -1,24 +0,0 @@
---
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**
## native_path
+ `name`
Resolve installed / local native plugin path (e.g. `agent`).
**> host_ext_native_path name=`name`**
-40
View File
@@ -1,40 +0,0 @@
---
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
+ `quiet`=True
File children are silent by default (`quiet=True`: piped capture, no TTY noise).
Set `quiet=False` to inherit parent stdout/stderr.
File `wait` returns `{code, value}` plus optional `stdout`/`stderr` tails when quiet-captured.
`value` is the child's `# main` return (not stdout).
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin` quiet=`quiet`**
## 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**
+13 -28
View File
@@ -1,48 +1,33 @@
---
title: lib/sys
description: English system wrappers (load_dotenv accepts optional path via host alias)
description: English system wrappers
---
## env_get
+ `name`
# env_get
- name
**> host_env_get name=`name`**
## env_set
+ `name`
+ `value`
# env_set
- name
- value
**> host_env_set name=`name` value=`value`**
## load_dotenv
+ `path`=None
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
**> host_dotenv_load path=`path`**
## args
# args
**> host_args**
## cwd
# cwd
**> host_cwd**
## exit
+ `code`
# exit
- code
**> host_exit code=`code`**
## exec
+ `cmd`
+ `args`=None
# exec
- cmd
**> host_exec cmd=`cmd` args=`args`**
## stream_publish
+ `event`
Publish a stream event map onto the process EventBus (`marqdo view` SSE). No-op when nothing is subscribed.
**> host_stream_publish event=`event`**
**> host_exec cmd=`cmd`**
+6 -195
View File
@@ -1,204 +1,15 @@
---
title: lib/table
description: >-
List and map helpers. Prefer put (1-based path, same as footnotes); at/set_at/slice
are 0-based. json is for parse/stringify.
description: English table helpers over len / at
---
## put
+ `in`
+ `at`
+ `value`
Directly update one element. `at=` is a text key, a **1-based** list index, or a list path of keys/indices (same nesting as footnotes).
**> host_collection_put in=`in` at=`at` value=`value`**
## len
+ `xs`
# rows
- xs
**> len `xs`**
## rows
+ `xs`
**> len `xs`**
## at
+ `xs`
+ `i`
Index is zero-based (same as builtin `at`). Out of range → `None`.
# row_at
- xs
- i
**> at value=`xs` index=`i`**
## row_at
+ `xs`
+ `i`
**> at value=`xs` index=`i`**
## append
+ `list`
+ `item`
**> host_list_append list=`list` item=`item`**
## prepend
+ `list`
+ `item`
**> host_list_prepend list=`list` item=`item`**
## concat
+ `a`
+ `b`
**> host_list_concat a=`a` b=`b`**
## insert
+ `list`
+ `index`
+ `item`
Index is zero-based (may insert at `len` to append).
**> host_list_insert list=`list` index=`index` item=`item`**
## set_at
+ `list`
+ `index`
+ `item`
Zero-based replace. Prefer `put` with 1-based index for author-facing edits.
**> host_list_set_at list=`list` index=`index` item=`item`**
## remove_at
+ `list`
+ `index`
**> host_list_remove_at list=`list` index=`index`**
## pop
+ `list`
Drop the last item (errors if empty). Use `last` first when you need the removed value.
*`n` = > len `list`*
1. `n` > 0
**> host_list_remove_at list=`list` index=`n` - 1**
2. *
**> host_list_remove_at list=`list` index=0**
## first
+ `list`
**> host_list_first list=`list`**
## last
+ `list`
**> host_list_last list=`list`**
## slice
+ `list`
+ `start`
+ `end`=None
Zero-based half-open range from `start` to `end`.
**> host_list_slice list=`list` start=`start` end=`end`**
## contains
+ `list`
+ `item`
**> host_list_contains list=`list` item=`item`**
## index_of
+ `list`
+ `item`
Zero-based index or `None`.
**> host_list_index_of list=`list` item=`item`**
## reverse
+ `list`
**> host_list_reverse list=`list`**
## clear
+ `value`
Empty list or empty map (by type).
**> host_collection_clear value=`value`**
## get
+ `map`
+ `key`
Missing key → `None`.
**> host_map_get map=`map` key=`key`**
## set
+ `map`
+ `key`
+ `value`
Shallow map update. Prefer `put` for nested paths.
**> host_map_set map=`map` key=`key` value=`value`**
## delete
+ `map`
+ `key`
**> host_map_delete map=`map` key=`key`**
## has
+ `map`
+ `key`
**> host_map_has map=`map` key=`key`**
## keys
+ `map`
**> host_map_keys map=`map`**
## values
+ `map`
**> host_map_values map=`map`**
## items
+ `map`
Rows shaped as key/value maps.
**> host_map_items map=`map`**
## merge
+ `a`
+ `b`
Right-hand keys win.
**> host_map_merge a=`a` b=`b`**
## size
+ `map`
**> host_map_size map=`map`**
## empty_list
**> host_list_concat a=None b=None**
## empty_map
**> host_map_merge a=None b=None**
+8 -8
View File
@@ -3,19 +3,19 @@ title: lib/text
description: English text helpers over trim / split / join
---
## str_trim
+ `s`
# str_trim
- s
**> trim `s`**
## str_split
+ `s`
+ `sep`
# str_split
- s
- sep
**> split value=`s` sep=`sep`**
## str_join
+ `xs`
+ `sep`
# str_join
- xs
- sep
**> join value=`xs` sep=`sep`**
+10 -10
View File
@@ -3,27 +3,27 @@ title: lib/time
description: English time wrappers
---
## now_unix
# now_unix
**> host_now_unix**
## now_ms
# now_ms
**> host_now_ms**
## format
+ `unix`
+ `pattern`
# format
- unix
- pattern
**> host_format_time unix=`unix` pattern=`pattern`**
## sleep_ms
+ `ms`
# sleep_ms
- ms
**> host_sleep_ms ms=`ms`**
## parse
+ `text`
+ `pattern`
# parse
- text
- pattern
**> host_parse_time text=`text` pattern=`pattern`**
-54
View File
@@ -1,54 +0,0 @@
---
title: lib/writeback
description: Persist run output in .mq.md (Jupyter-style writeback)
---
## record
+ `value`
+ `at_end`=False
+ `key`=None
+ `line`=None
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that **named** slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
**> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`**
## get
+ `at_end`=False
+ `key`=None
+ `line`=None
Read persisted output for the current call site (adjacent unkeyed block), the unkeyed EOF block when `at_end=true`, or a named slot when `key=` is set.
**> host_writeback_get at_end=`at_end` key=`key` line=`line`**
## clear
+ `at_end`=False
+ `key`=None
+ `line`=None
Remove the adjacent, EOF, or named output block.
**> host_writeback_clear at_end=`at_end` key=`key` line=`line`**
## ensure
+ `key`
+ `placeholder`=pending
+ `line`=None
Create a named slot with `placeholder` if missing. Never overwrites an existing slot body.
**> host_writeback_ensure key=`key` placeholder=`placeholder` line=`line`**
## list
List all output blocks in the entry file (includes `key` when named).
**> host_writeback_list**
## scan_path
+ `path`
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
**> host_writeback_scan_path path=`path`**
Loaded 100 of 385 files, more files were not shown because too many files have changed in this diff. Show more