Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bf76e069ee | ||
|
|
9015de26e5 | ||
|
|
8c24d96626 | ||
|
|
4a2f5bf226 | ||
|
|
86e921e959 | ||
|
|
b196a44685 | ||
|
|
c8ed5bffb7 | ||
|
|
fb135ae2f8 | ||
|
|
69fcdd6227 | ||
|
|
deac53d0f5 | ||
|
|
932403237a | ||
|
|
a14a6e221d | ||
|
|
8b0ea9ed7a | ||
|
|
6ae0d39e5a | ||
|
|
307c8efa81 | ||
|
|
34b0911218 | ||
|
|
4488a3cb70 | ||
|
|
9dbcc728b6 | ||
|
|
0405a60d68 | ||
|
|
409b8df2cb | ||
|
|
6bba0be6d2 | ||
|
|
1c90312c02 | ||
|
|
fd0cfcb566 | ||
|
|
6dd0ce47b1 | ||
|
|
1a94cc8490 | ||
|
|
11417c42e0 | ||
|
|
13012cac0e | ||
|
|
5a0f4ed747 | ||
|
|
05b8edc186 | ||
|
|
8926f7bed6 | ||
|
|
18b0c655f7 | ||
|
|
924885969f | ||
|
|
619271b8eb | ||
|
|
719b7a8d82 | ||
|
|
dfe99a10b4 | ||
|
|
fac68e85ea | ||
|
|
639b0ebcd1 | ||
|
|
2c4dac005c | ||
|
|
0ac661eef2 | ||
|
|
1dd74578b5 | ||
|
|
14114993c4 | ||
|
|
e80c944c40 | ||
|
|
30cd5a0833 | ||
|
|
e2068c2051 | ||
|
|
9cda80ee7d | ||
|
|
eae4815fc7 | ||
|
|
3260494e5c | ||
|
|
3330a0fc66 | ||
|
|
42a1a46383 | ||
|
|
b6629e5450 | ||
|
|
ecd7d5e433 | ||
|
|
aeb5a2a43d | ||
|
|
f2d651e063 | ||
|
|
b020b9d218 | ||
|
|
33a14d272c | ||
|
|
6ed70fd8b8 | ||
|
|
115d1f6c0b | ||
|
|
7dc5e56850 | ||
|
|
514caa55ae | ||
|
|
74908ebf04 | ||
|
|
0f852593bc | ||
|
|
34e2fb4f74 | ||
|
|
0e407b2bd3 | ||
|
|
e5e532d83f | ||
|
|
064522a338 | ||
|
|
c85f1a2829 | ||
|
|
a7266185b2 | ||
|
|
4d7c0bea1b | ||
|
|
53758ebd1c | ||
|
|
dff0b700ae | ||
|
|
4da07c1b26 | ||
|
|
78922102e4 | ||
|
|
064bae2c65 | ||
|
|
92b91ffc81 | ||
|
|
ab6648ae0e | ||
|
|
5acf026e0c | ||
|
|
8dcd69412f | ||
|
|
2a13e52981 | ||
|
|
9b269f6447 | ||
|
|
15362cb048 | ||
|
|
05d48f68a4 | ||
|
|
e4387259ba | ||
|
|
518f8e386b | ||
|
|
9da12c9093 | ||
|
|
e0d34669e0 | ||
|
|
0ba4d3d2d7 | ||
|
|
ad3ebf243a | ||
|
|
142d30ce08 | ||
|
|
4757b82edd | ||
|
|
bff2f53e52 | ||
|
|
fb28eee62f | ||
|
|
01468ad976 | ||
|
|
f3791d11b4 | ||
|
|
7fef690167 | ||
|
|
024cdee82a | ||
|
|
f666eaaf40 | ||
|
|
e6f05c7748 | ||
|
|
81f9ea0072 | ||
|
|
dbf3f3a14b | ||
|
|
654e89d98c | ||
|
|
be20629496 | ||
|
|
3223295841 | ||
|
|
beb5bdbe8c | ||
|
|
b8cb022018 | ||
|
|
b9e331cb31 | ||
|
|
476c2b607b | ||
|
|
d99b275336 | ||
|
|
1415aee08f | ||
|
|
0f2c12b636 | ||
|
|
9873df7099 | ||
|
|
3001ed7ba5 | ||
|
|
050d71927f | ||
|
|
7859170aec | ||
|
|
e32ff8f6b3 | ||
|
|
c21a28c3bc | ||
|
|
1e61dca9d8 | ||
|
|
ba675a4767 | ||
|
|
bfd468d5e3 | ||
|
|
8353ba38fe | ||
|
|
b43a08b2e2 | ||
|
|
1908bf1a53 | ||
|
|
c44ea38ae2 | ||
|
|
d489f7c088 | ||
|
|
a993cfd76a | ||
|
|
d5f826a8c8 | ||
|
|
0f72173d08 | ||
|
|
a707758d47 | ||
|
|
63bcb882a6 | ||
|
|
1bb16dd6db | ||
|
|
58ec2172d6 |
No files matched your search
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
|
||||
|
||||
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
|
||||
|
||||
### 2. Good patterns
|
||||
### 2. Good patterns (copy these — not `json.set`)
|
||||
|
||||
**Wire / steps / commands** — `@` record table:
|
||||
|
||||
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
|
||||
| `wire` | `set_text` |
|
||||
```
|
||||
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task | result | llm_calls | tokens |
|
||||
|--------|------|--------|-----------|--------|
|
||||
| ok | `task` | `reply` | `llm_calls` | `tokens` |
|
||||
|
||||
*out*
|
||||
```
|
||||
|
||||
**Soft error pack** (transport / gate failure) — still a table humans can skim:
|
||||
|
||||
```markdown
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task |
|
||||
|--------|------|
|
||||
| error | `task` |
|
||||
|
||||
1. `err`
|
||||
**out = > table.put in=`out` at="error" value=`err`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
```
|
||||
|
||||
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
|
||||
|
||||
```markdown
|
||||
**empty_tc = > table.empty_list**
|
||||
**empty_map = > table.empty_map**
|
||||
```
|
||||
|
||||
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
**`set_text` = table.put in=None at="#log" value=msg**
|
||||
@@ -73,14 +119,20 @@ Better still — call a named helper:
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
|
||||
|
||||
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
|
||||
|
||||
```markdown
|
||||
**`ret` = json.set map=None key="set_text" value=…**
|
||||
**`ret` = json.set map=ret key="canvas" value=…**
|
||||
**`cmds` = json.append list=cmds item=c0**
|
||||
**`out` = json.parse text={"status":"ok"}**
|
||||
**`out` = json.set map=out key="task" value=task**
|
||||
```
|
||||
|
||||
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
|
||||
|
||||
## Writing application `.mq.md`
|
||||
|
||||
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
|
||||
|
||||
+69
-160
@@ -4,95 +4,40 @@ 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/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
---
|
||||
|
||||
# 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): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
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).
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
|
||||
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
|
||||
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
|
||||
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
|
||||
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
|
||||
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
|
||||
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** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
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 / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
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.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
|
||||
## 记不住语法细节?查 MLSP(AI 必读)
|
||||
|
||||
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
| method | 何时用 |
|
||||
|--------|--------|
|
||||
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
|
||||
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
|
||||
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
|
||||
| `schema` | 查单元契约(形参/返回/字段) |
|
||||
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
|
||||
|
||||
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
|
||||
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
|
||||
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
|
||||
|
||||
### 渐进式契约(可选标注;schema 就长在文档表里)
|
||||
|
||||
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
|
||||
|
||||
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|
||||
|--------------------------|----------|------|
|
||||
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
|
||||
|
||||
````text
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,期望是数字。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 加一结果 |
|
||||
|
||||
*n+1*
|
||||
````
|
||||
|
||||
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
|
||||
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
|
||||
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
|
||||
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
|
||||
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
|
||||
|
||||
## Markup → meaning (v0.3)
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
@@ -103,25 +48,33 @@ printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
|
||||
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`); bind with `` `name` = `` then fence |
|
||||
| `$$` + `% marqdo: var=name` | Block formula bind (TeX comment; prefer over empty RHS) |
|
||||
| `- [item](coll)` | Foreach (**preferred**, nestable). Sugar: `- 对`coll`的每一项`item`` / `- for each `item` in `coll`` |
|
||||
| `` | Image writeback form (validated stem.ext / URL); text writeback stays HTML comment |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| `` ```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`.
|
||||
|
||||
## Occlusion syntax (v2.0.0)
|
||||
|
||||
A file with frontmatter `markup: occlusion` (or `标记: 遮蔽`) reads `[x](y)` as **occlusion**, not index — in that file only (`MARQDO_MARKUP=occlusion` sets the process default; classic files are unchanged).
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
@@ -140,19 +93,20 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
Prefer **body-inferred params** and **prose-unified** wording (v0.3). `` + `name` `` still works, but teach the inferred form first:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**greet who="Marqdo"**
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
When we meet`who`, we **print text="Hello, `who`!"** and close with*None*.
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
```
|
||||
|
||||
- Call: `**fn key="text"**` (bold; quote text literals) or `> fn key=text` (standalone `>`; bare words are text).
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
|
||||
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
|
||||
@@ -160,16 +114,17 @@ When we meet`who`, we **print text="Hello, `who`!"** and close with*None*.
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
For input`n`, do **n = n + 1** and return*n*.
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
**n = 0**
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -192,16 +147,16 @@ import clock:lib/time.mq.md
|
||||
|
||||
# main
|
||||
|
||||
**xs = > text.str_split s="a,b,c" sep=","**
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
> print text=`xs`
|
||||
**t = > clock.now_unix**
|
||||
*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|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). **`ext/llm`** — intelligence primitive (`ask` / `stream` / `collect`; `complete` is compat); **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
|
||||
- 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`/`非`.
|
||||
@@ -216,61 +171,24 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only. **Engineering Knowledge(EKC)**:`marqdo knowledge|find|reuse|…` + `agent.preflight`(REUSE→ADAPT→CREATE)——见 [engineering-knowledge.md](../../doc/design/engineering-knowledge.md)。
|
||||
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
|
||||
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
|
||||
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`.
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
|
||||
|
||||
**Constitution (ADR 0007 — do not degrade):**
|
||||
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
|
||||
|
||||
1. **Document / Endpoint / Resource** — `.mq.md` with `type: web|endpoint` (ZH `类型: 网页|端点`) is the site surface; not a Flask-style class pile.
|
||||
2. **Code is documentation** — the file is docs + route + handler.
|
||||
3. **Table = data** — View schema only `|type|slot|value|attrs|style|`. No `compose_*` dialects, no `json.set` glue.
|
||||
4. **Facade only** — `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect`. DB → `ext/data`; auth → `ext/security`; ws/http → `ext/net`.
|
||||
5. **No author `ensure_plugin` / `host_*`**; import web = capability (plugin auto-load).
|
||||
6. **Declared vs system routes**; `web.inspect` lists both. No silent user routes.
|
||||
|
||||
Import **one language** per file:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md` (+ `import data:ext/data/db.mq.md` as needed)
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: web
|
||||
route: /
|
||||
title: Hello
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
Executable document as a page.
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: endpoint
|
||||
method: POST
|
||||
path: /api/ping
|
||||
response: json
|
||||
---
|
||||
|
||||
*{"ok": true}*
|
||||
```
|
||||
|
||||
Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS.
|
||||
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · ADR [0007](../../doc/adr/0007-web-document-endpoint.md) · rule: `.cursor/rules/web-artifact-no-degrade.mdc` · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) · API index: [reference.md](reference.md).
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
## Official extension: `ext/quantum` (circuits + Q7/Q8)
|
||||
|
||||
@@ -296,29 +214,23 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
## Foreign kernels (v1.5.0)
|
||||
|
||||
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
|
||||
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
|
||||
|
||||
- EN: `import la:ext/linalg/linalg.mq.md`
|
||||
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
|
||||
|
||||
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
|
||||
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
|
||||
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
|
||||
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
|
||||
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
|
||||
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
|
||||
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
|
||||
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
|
||||
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
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)
|
||||
|
||||
@@ -339,8 +251,7 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
|
||||
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
@@ -357,5 +268,3 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
- [ ] Browser client: `lib/browser` + tables when returning effects
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
|
||||
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
|
||||
@@ -162,6 +162,56 @@ import browser:lib/browser.mq.md
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -126,6 +126,25 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.0.0**:遮蔽语法——`[描述](实现)` 描述不执行 · `()` 内调用 · `access` 取元 · 遮蔽循环 · `labels` / `migrate labels` · view 桩徽章
|
||||
- **v2.0.0**: Occlusion syntax — `[label](payload)` inert prose, paren calls, `access`, occlusion loops, `labels` / `migrate labels`, view stub badges
|
||||
- **v2.0.0 ext**:扩展包同步 2.0.0 / Ext pack 2.0.0
|
||||
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
|
||||
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
|
||||
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
|
||||
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
|
||||
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
|
||||
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
|
||||
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
|
||||
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
@@ -134,12 +153,8 @@ jobs:
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
|
||||
- **v1.1.1**: AI stack — llm ask/stream/collect, Metadata Binding, Skill Compilation + Adaptive Routing, MCP client + resume, optional plugins/llm
|
||||
- **v1.0.7**:WS/网络边界加固;`url_encode` `%20`
|
||||
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com)
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
|
||||
+16
@@ -71,6 +71,16 @@ plugins/*/tmp/
|
||||
/examples/linalg-*/**/*.svg
|
||||
/examples/linalg-*/*.svg
|
||||
/examples/linalg-*.svg
|
||||
# oa2026 showcase: SVGs beside the examples ARE tracked; root-level ones are
|
||||
# run artifacts (draw/plot write to cwd when the example is run from root)
|
||||
/bell-*.svg
|
||||
/calculus-*.svg
|
||||
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# PLDI / thesis harness scratch must never land in this tree
|
||||
.lx*-tmp/
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
@@ -87,3 +97,9 @@ tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
+297
@@ -1,5 +1,46 @@
|
||||
# Changelog
|
||||
|
||||
## v2.0.0 — 2026-10-22
|
||||
|
||||
### Highlights
|
||||
|
||||
**遮蔽语法(Occlusion)落地**:`[描述](实现)` —— 方括号是给人读的描述(**永不执行**),圆括号是**唯一执行体**。配套 `()` 内调用、`access` 取元、`遍历` 遮蔽循环、`labels` 两级检索与债务棘轮、`migrate labels` 迁移;`view` 把描述渲染为正文、实现渲染为代码片、空载荷给「桩」徽章。全仓 **80 个语料文件 / 256 处取元 / 23 处循环** 已迁移(M7),语义零漂移。
|
||||
|
||||
```bash
|
||||
git checkout v2.0.0 && cargo build --release
|
||||
marqdo ext add web # CDN → 2.0.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)—— 遮蔽是既有 `[键](集合)` 与 `- [项](集合)` 形状在 `markup: occlusion` 文件中的**第二种读法**,默认 `classic` 语义不变;`access` 是宿主函数(id 212),不是新标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **M2 遮蔽语法**:`[描述](实现)`;`[]` 为自由文本、永不执行,`()` 为唯一执行体;支持嵌套;空载荷 `()` 值为 `None`(桩)。frontmatter `markup: occlusion` 按文件启用,`MARQDO_MARKUP=occlusion` 可作进程默认。
|
||||
- **M1 `()` 内调用**:`加(1)` / `加(1, 2)` / `加(加(1 2), 10)` / `加一 号(31)`(callee 可含空格,解决 D8)/ `txt.str_trim(" x ")`;`)` 是参数终止符,逗号可选,支持嵌套;括号形参数按表达式解析,空格形(`> f k=v`)仍按文本。
|
||||
- **M3 `access` 与遮蔽循环**:新增宿主函数 `access(集合, 键)`(别名 `取` / `取值`),与旧取元逐字等价;`- [描述](遍历 集合 为 变量)` 遮蔽循环,接受 `遍历`/`for` 与 `为`/`as`/`in`。
|
||||
- **M2.5 / M4 遮蔽诊断**:`label.missing`(空描述,error)、`label.empty_payload`(空载荷,warning)、`label.ref_dangling`(描述里的反引号实体不可解析,error);由 `marqdo check` 一并输出。
|
||||
- **M5 隐式遮蔽**:`marqdo check --implicit-labels` 把 `>` 调用上方的叙述当作描述(默认关闭,不改变既有输出)。
|
||||
- **M6 T1 会话内陈旧检测**:MLSP `repair_apply` 前后对照 payload 并返回变更的遮蔽点;新增 `session.summary` 会话末一次性汇总。
|
||||
- **M7 迁移与版本门**:frontmatter `markup:` 按文件切换解析模式(同进程可混载 classic / occlusion,imports 亦然);`marqdo migrate labels`(多路径、`--write`、`--json`)把 `[键](集合)` 改写为 `[键](access(集合, "键"))`、`- [项](集合)` 改写为遍历形。
|
||||
- **M8 债务棘轮与呈现**:`marqdo labels --baseline FILE` 记欠据、`--fail-on-increase` 只许降不许升;`view` 浏览 / 卡片 / 静态导出一致呈现遮蔽:描述为正文、实现为代码片、空载荷「桩」徽章。
|
||||
- **M9 两级词表检索**:`marqdo labels`(默认 `pending` 口径 / `--grep` 自定义词 / `--group` / `--also-builtin` / `--count` / `--json`,支持多路径);MLSP `labels.search`;兼容文档写法 `labels pending` / `labels search`。
|
||||
- **M10 工程化落点**:`ext/ai` 提示词加入「接不了就申报」;README「工程习惯」;空载荷一律 warning。
|
||||
- **示例与教程**:`examples/syntax-tour` 一页跑通全部现行语法;`examples/oa2026-showcase`;`doc/tutorial/15-常见陷阱.md`(D1–D10 实测)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **D9 未闭合引号**:不再静默吞掉后续行——分类层与解析层双层修复,直接报错并给出原始行。
|
||||
- **`加(31)`**:曾被解析成 `unknown function 加(31`(末个位置实参吞掉 `)`)。
|
||||
- **view 解析模式回归**:带 `markup: occlusion` 的文档在 `view` 结构区报 `expected ')' after link-index collection`;新增 `load::parse_source_auto` 统一五处解析点。
|
||||
|
||||
### Changed
|
||||
|
||||
- **HostFn 单表**:五张分派表合一为 `HOST_FN_TABLE`(`src/host/dispatch.rs` **−404 行**),203 项逐字节一致,行为零变化。
|
||||
- **插件 ABI 共享 crate**:新增 `marqdo-plugin-sdk`,5 个原生插件共用同一份 ABI 前言;**ABI 不变**(`include/marqdo_abi.h` / 符号与布局不变)。
|
||||
- **精简**:删除归档的 Rust web 插件 `plugins/web-rust-archive/`(14,235 行,非 workspace 成员,已由 Go `libweb` 取代);删除无调用点死代码,收拢 `as_text` 18 处重复、catalog 助手与 view 路由 34 臂,AST 遍历器合流。
|
||||
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
|
||||
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
@@ -8,6 +49,262 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.5.2 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.2 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
|
||||
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
|
||||
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
|
||||
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
|
||||
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`session_list` arity**:保持空 arity。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
|
||||
|
||||
## v1.5.1 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.1 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
|
||||
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
|
||||
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
|
||||
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
|
||||
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
|
||||
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
|
||||
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
|
||||
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
|
||||
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
|
||||
- **写回表标签**:写回表标签保持为行内代码。
|
||||
|
||||
### Changed
|
||||
|
||||
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
|
||||
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
|
||||
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
|
||||
|
||||
## v1.5.0 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**外联 v2 / 文档原生 Notebook**:`lib/foreign` 从“运行一段代码”升级为完整外联内核:结构化 `invoke` 记录、JSON 进出的 `call` / `call_many`、并行扇出、Python/Node 持久内核、显式状态桥,以及用绑定表声明的 Notebook 单元。`view` 增加 cell 单步、Run All、内核切换、journal、状态面板、浅/深主题与可调高度代码区;高对比度 token 修复了代码和 STRUCTURE 文字与背景区分度不足的问题。CLI · wasm · ext **1.5.0**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.0 && cargo build --release
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v2 只扩展 `lib/foreign` 的库 API;Notebook 的 `内核表` / `会话表` 是既有绑定表;没有新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
|
||||
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
|
||||
- **Notebook D1/D2**:`内核表` / `会话表` 文档原生语法;`DocumentSession`(cell index / 命名内核 / journal / value store);view Notebook 工具栏(Run All / Restart & Run All / Step / State / Journal / Reload)、状态徽标、内核下拉、Push/Pull 状态表单;`POST /api/session/*`。
|
||||
- **Notebook D3**:`reload` 重新解析并保留内核,源码变更的 cell 标为 `dirty`;Journal/Reload/Debug 按钮;Debug 打开同一 view 服务的语句级单步页(`/debug` + `/api/debug/*`);状态桥 Push/Pull。
|
||||
- **安全与健壮性**:所有外联入口检查 `exec` 能力;有界 stdout/stderr 读取与截断标记;stdin 写线程;Unix 进程组 / Windows `taskkill /T` 超时清理;shell-like argv 切分。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **view 文档表面与标注 chip**:把旧 view 的 `--ink` / `--fill` / `--line` 等 token 映射到当前主题,修复 STRUCTURE 中 `main`、`内核表 =`、函数名和 annot-chip 深色文字/白色卡片与暗色背景不一致的问题。
|
||||
- **view 代码对比度**:移除会互相覆盖的 highlight.js 深/浅两套外链样式,改用内置高对比 token 变量;深色代码正文 `#f0f0f0` on `#1e1e1e`(14.6:1),浅色 `#24292f` on `#f6f8fa`(13.8:1);关键词/字符串/注释均使用可读的对比色。
|
||||
- **view 反向代理兼容**:Notebook / Debug 的 API 与 Debug URL 改为相对路径,可在 `/marqdo-view/...` 路径前缀下工作,便于 Docker 内通过 DSH 同源预览。
|
||||
- **分支内共同局部变量**:if/else 各臂都赋值的局部变量不再被误提升为必选形参;修复 `# llm` 构造器无端要求 `key`,恢复 agent/llm/ext 全量测试。新增 `branch_else_common_local_is_not_a_param` 回归测试。
|
||||
- **外联临时脚本路径**:入口目录为相对路径时,脚本参数现在使用绝对路径,避免 `tests/lib/tests/lib/...` 双拼接。
|
||||
- **外联失败可观测**:解释器不存在时进入 `invoke` 记录,`run` 仍报错;view 显示 stderr / exit / ms。
|
||||
|
||||
### Changed
|
||||
|
||||
- **Notebook view 视觉重做**:采用 VS Code Dark 的扁平色板与 Jupyter 的 cell 组织:单一深色底、明确 surface/border 层级、`In [n]` / `Out [ ]` 提示、顶部 cell 工具栏、无渐变/无重阴影、暗色代码区与一致的字号/间距;保留并统一原始左侧文件导航、右侧 Functions/Variables 栏与 Execution/Source 区块;支持深色/浅色主题切换(localStorage 记忆)与代码区、输出区纵向拖拽调整高度。
|
||||
- **`langs`** 现在返回「预设 ∪ 注册 ∪ 配置」的已知语言(原集合是子集)。
|
||||
- 大输出从 `Err` 改为「截断 + `truncated=true`」;`subtask` 外联输出同步采用该语义。
|
||||
|
||||
## v1.4.6 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**裸自增升参**:粗体首次赋值的左值按设计 §8.2 视为声明。`**n = n + 1**` 在没有反引号提及时也会把 `n` 升成必选形参;缺参报 `missing argument for parameter`,不再是函数体内的 `undefined variable`。纯局部赋值(`**score = 1**`)与循环变量不升参。CLI · wasm **1.4.6**(扩展包仍为 **1.4.5**)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.6 && cargo build --release
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——升参与 §8.2 对齐(赋值左值声明);不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **升参**:`merge_inferred_params` 纳入首次粗体赋值左值。右值在绑定前读取同名(`n = n + 1`)时,该名成为必选推断形参。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm SemVer **1.4.6**。扩展包保持 **1.4.5**。
|
||||
|
||||
## v1.4.5 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Streamable HTTP MCP + web `/v1` 鉴权硬化**:`agent_mcp_serve` 支持 `transport=http`(MCP Streamable HTTP 2025-03-26);web invoke 注入 `Authorization` / `X-Api-Key`,`ok=false`+`unauthorized` → HTTP 401;`ext/ai` openai/agent 字段访问改 `json.get`,消除 footnote 硬崩。CLI · Ext · wasm **1.4.5**。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.5 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
# HTTP MCP:
|
||||
# QDAGENT_MCP_TRANSPORT=http marqdo run cli/求道-mcp.mq.md
|
||||
marqdo ext add agent # CDN → 1.4.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**新增** MCP Streamable HTTP 传输(`transport=http|streamable-http`);web invoke 契约扩展(header 注入 · 401);**无** MQ 关键词 / 表几何变更。
|
||||
|
||||
### Added
|
||||
|
||||
- **`agent_mcp_serve` Streamable HTTP**:`transport=http` · `host`/`port`/`path`;POST JSON-RPC + 可选 GET SSE;`Mcp-Session-Id`。facade:`ext/ai/agent` `## serve`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **web invoke**:`Authorization` / `X-Api-Key` 注入 payload;`jsonWrapInvokeValue` 对 `unauthorized` 返回 401;`{sse}` 自动 event-stream。
|
||||
- **`ext/ai/llm/openai` · `agent` · `llm`**:字段访问改 `json.get` / `at`,避免 `[field](x)` 在非 map 上硬崩。
|
||||
- **explore workbook**:子任务 `stream=False`(网关 SSE 524 更稳)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / Ext / wasm SemVer **1.4.5**。
|
||||
- 设计:[doc/design/ext-web-artifact.md](doc/design/ext-web-artifact.md)(sse / bearer)。
|
||||
|
||||
## v1.4.4 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.4 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_llm
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
marqdo ext add agent # CDN → 1.4.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
|
||||
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
|
||||
- CLI / Ext / wasm SemVer **1.4.4**。
|
||||
|
||||
## Ext pack v1.4.3 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
|
||||
|
||||
```bash
|
||||
marqdo ext add agent # CDN latest → 1.4.3
|
||||
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
|
||||
|
||||
### Fixed
|
||||
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
|
||||
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
|
||||
|
||||
## v1.4.2 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.2 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
marqdo run tests/ext/agent-sandbox-optin.mq.md
|
||||
marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add agent # CDN latest → 1.4.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
|
||||
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
|
||||
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
|
||||
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
|
||||
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
|
||||
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
|
||||
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
|
||||
|
||||
## v1.4.1 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.1 && cargo build --release
|
||||
marqdo view public/00-welcome.mq.md --no-open
|
||||
marqdo view output public -o /tmp/mq-public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
|
||||
|
||||
### Fixed
|
||||
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
|
||||
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
|
||||
|
||||
## v1.4.0 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+14
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.4.0"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -601,9 +601,16 @@ dependencies = [
|
||||
"zip",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.4.0"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -614,6 +621,7 @@ name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -621,6 +629,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -628,6 +637,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
@@ -637,6 +647,7 @@ name = "marqdo_plugin_llm"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
@@ -646,6 +657,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
+5
-4
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.4.0"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -19,7 +19,7 @@ cli = ["dep:clap"]
|
||||
view = ["dep:tiny_http"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
|
||||
plugin-host = ["dep:libloading"]
|
||||
exec-host = []
|
||||
exec-host = ["dep:libc"]
|
||||
fs-host = []
|
||||
tty = ["dep:libc"]
|
||||
wasm-core = []
|
||||
@@ -62,9 +62,10 @@ members = [
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
"crates/marqdo-plugin-sdk",
|
||||
]
|
||||
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
|
||||
# `plugins/web-rust-archive/` for reference (not a workspace member).
|
||||
# Official web plugin is Go (`plugins/web/`). The legacy Rust web plugin was
|
||||
# deleted from the tree (see CHANGELOG); git history keeps it if ever needed.
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Marqdo
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
@@ -116,6 +116,50 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 工程习惯:允许申报未完成,但不允许假装完成
|
||||
|
||||
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
|
||||
而欠账是可见、可数、可结算的(而不是假装完成):
|
||||
|
||||
```markdown
|
||||
## 检索资料
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**实现**(唯一执行)。这条语法叫**遮蔽**:
|
||||
把不可读或未完成的实现藏到括号里,人读描述、机器读代码。
|
||||
|
||||
**四条约定**
|
||||
|
||||
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
|
||||
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
|
||||
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
|
||||
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
|
||||
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
|
||||
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels pending # 内置口径:还有多少未完成
|
||||
marqdo labels search --grep "接口未联调,联调中" # 用你自己的说法
|
||||
marqdo labels search --grep 联调 --also-builtin # 自定义 + 内置一起数
|
||||
marqdo labels pending --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
@@ -149,8 +193,17 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.4.0)
|
||||
## 现状(v2.0.0)
|
||||
|
||||
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0**
|
||||
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
|
||||
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
|
||||
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
|
||||
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
|
||||
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
|
||||
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
@@ -169,7 +222,7 @@ marqdo catalog public -o .marqdo
|
||||
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client stdio** + Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **Streamable HTTP**)+ Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
|
||||
@@ -178,7 +231,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v1.4.0)
|
||||
### 如何使用最新 Marqdo(v2.0.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -193,7 +246,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.4.0 # 或留在 main
|
||||
git checkout v2.0.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -232,7 +285,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.4.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.0.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,195 @@
|
||||
//! Shared ABI plumbing for Marqdo native plugins (`<TAB>` slimming).
|
||||
//!
|
||||
//! Every plugin used to copy the same `MarqdoHostApi` struct, the alloc/free
|
||||
//! statics, `host_strdup`, `set_out`/`set_err`, `parse_args` and `reply`
|
||||
//! (about 140 lines each × 5 crates). This crate holds the single copy; the
|
||||
//! `marqdo_plugin!` macro emits the `#[no_mangle]` exports each `.so` needs.
|
||||
//!
|
||||
//! The ABI itself is unchanged: `include/marqdo_abi.h` and the host loader
|
||||
//! (`src/host/plugin.rs`) still see exactly the same symbols and layout.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
pub use serde_json::{json, Value};
|
||||
|
||||
/// Highest ABI version this SDK speaks.
|
||||
pub const ABI_VERSION: u32 = 2;
|
||||
|
||||
pub type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
pub type HostQueryFn = unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
pub host_query: Option<HostQueryFn>,
|
||||
}
|
||||
|
||||
pub static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
pub static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
pub static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
pub static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
/// Duplicate `s` into host-allocated memory (the host frees it).
|
||||
pub unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
pub fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse the JSON args object handed to a plugin entry point.
|
||||
pub fn parse_args(args_json: *const c_char) -> Result<Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
if s.trim().is_empty() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Write a plugin result (or error) back through the ABI pointers.
|
||||
pub fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
|
||||
match r {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin with no arguments (`host_query`).
|
||||
pub fn host_query_json(name: &str) -> Result<Value, String> {
|
||||
host_query_json_with(name, &json!({}))
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin, passing `args` as its argument object.
|
||||
pub fn host_query_json_with(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let q = unsafe { HOST_QUERY }.ok_or("host_query unavailable")?;
|
||||
let n = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let a = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out: *mut c_char = ptr::null_mut();
|
||||
let mut err: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe { q(HOST_USERDATA, n.as_ptr(), a.as_ptr(), &mut out, &mut err) };
|
||||
if rc != 0 {
|
||||
return Err(take_host_string(err).unwrap_or_else(|| "host_query failed".into()));
|
||||
}
|
||||
let text = take_host_string(out).ok_or("host_query returned nothing")?;
|
||||
serde_json::from_str(&text).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Copy a host-allocated C string into a Rust `String` and free the original.
|
||||
pub fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_string_lossy()
|
||||
.into_owned();
|
||||
if let Some(free) = unsafe { HOST_FREE } {
|
||||
unsafe { free(p as *mut c_void) };
|
||||
}
|
||||
Some(s)
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, f: PluginFn) -> c_int {
|
||||
let Some(reg) = host.register_fn else {
|
||||
return 1;
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { reg(host.userdata, n.as_ptr(), p.as_ptr(), f) }
|
||||
}
|
||||
|
||||
/// Store the host callbacks and register every entry point.
|
||||
pub unsafe fn init_plugin(host: *const MarqdoHostApi, regs: &[(&str, &str, PluginFn)]) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, *f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
/// Emit the four `#[no_mangle]` exports every plugin `.so` must provide,
|
||||
/// wiring `marqdo_plugin_init` to the given registration table.
|
||||
#[macro_export]
|
||||
macro_rules! marqdo_plugin {
|
||||
($version:expr, [ $( ($name:expr, $params:expr, $f:expr) ),* $(,)? ]) => {
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
$version
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(
|
||||
host: *const $crate::MarqdoHostApi,
|
||||
) -> i32 {
|
||||
$crate::init_plugin(host, &[ $( ($name, $params, $f as $crate::PluginFn) ),* ])
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.4.0"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+78
@@ -1,3 +1,81 @@
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
bracketed label is inert prose and the parenthesized payload is the
|
||||
only executed part. Adds paren-call arguments, access() element
|
||||
access, occlusion loops, marqdo labels (two-tier search + debt
|
||||
ratchet), marqdo migrate labels, and label.missing / empty_payload /
|
||||
ref_dangling diagnostics; view renders labels as prose, payloads as
|
||||
code, stubs with a badge. 80 corpus files migrated.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
|
||||
|
||||
marqdo (1.5.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
|
||||
interrupt, plan generation/add/remove/value API, snapshot
|
||||
export/import/replay, view capture for static export, explicit Persist
|
||||
button, nested plan boundary.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
|
||||
|
||||
marqdo (1.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.1: View static/live execution path unified; foreign value
|
||||
passing into multi-kernel sessions; cell stdin for live/static/persistent
|
||||
kernels; build-time execution with stdout injection in static exports;
|
||||
runnable foreign writeback example; writeback block grouping.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
|
||||
|
||||
marqdo (1.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
|
||||
parallel fan-out, persistent Python/Node kernels, explicit state
|
||||
bridge) and document-native notebooks in view; high-contrast
|
||||
light/dark view themes, resizable code/output panes, OKF/EKC and
|
||||
Python examples on the user site. Fixes branch-local variables
|
||||
leaking into required constructor parameters.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
|
||||
|
||||
marqdo (1.4.6-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
|
||||
The first bold assignment LHS is a declaration (design §8.2); a missing
|
||||
argument reports missing argument for parameter, not undefined variable.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
|
||||
|
||||
marqdo (1.4.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
|
||||
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
|
||||
field access via json.get (no footnote hard-fail).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
|
||||
|
||||
marqdo (1.4.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
|
||||
ext/ai table-first refactor (no json.set glue).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
|
||||
|
||||
marqdo (1.4.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
|
||||
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
|
||||
|
||||
marqdo (1.4.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
|
||||
to chip top-center), unify frame chip ids, L-to-R chip density.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
|
||||
|
||||
marqdo (1.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
|
||||
|
||||
+23
-2
@@ -48,7 +48,13 @@
|
||||
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
|
||||
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
|
||||
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
|
||||
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
|
||||
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
|
||||
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
|
||||
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
|
||||
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
|
||||
| [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 循环)** |
|
||||
@@ -90,10 +96,25 @@
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
|
||||
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
|
||||
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
|
||||
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
|
||||
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
|
||||
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
|
||||
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,250 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「让函数参数从上下文推断,`对**n=31**执行**加一函数**` 这种写法可能吗」 |
|
||||
| 方法 | 运行时实测 8 组 + 全仓库语料扫描(1322 个函数)+ 源码比对 |
|
||||
| 相邻 | [call-syntax-from-marks.md](call-syntax-from-marks.md)(**接替本文 §3 的设计**)· [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
> **后续更正**:本文 §3 提出的 L0「叙述式调用」用**未标记的词**(`执行`)触发调用,
|
||||
> 这会破坏「叙述默认安全、只有标记才执行」的底层原则,已被否决。
|
||||
> 在「只执行标记」约束下重新设计的调用语法见
|
||||
> [call-syntax-from-marks.md](call-syntax-from-marks.md)
|
||||
> (含树遍历 vs 字节码 3.8× 实测、叙述顺序导致位置绑定翻转的实验)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论:你的示例其实**不需要**隐式推断
|
||||
|
||||
先把一个关键事实摆出来:**你的例子里 `n=31` 明明写在那儿**。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
对**n=31**执行**加一函数**
|
||||
```
|
||||
|
||||
`n` 的绑定**就写在句子里**,这不是「从上下文推断」,这是**具名实参换了语序**。
|
||||
所以这个写法需要的是**新的叙述式调用语法**,不是新的作用域语义。
|
||||
|
||||
它今天跑出来的结果很能说明问题:**无输出、无报错、退出码 0**。
|
||||
不是参数推断失败,而是 `执行**加一函数**` 里的裸名字**只是被求值然后丢弃**,
|
||||
从来没被当成一次调用。
|
||||
|
||||
三层拆解:
|
||||
|
||||
| 层 | 写法 | 需要什么 | 裁决 |
|
||||
|----|------|---------|------|
|
||||
| **L0 叙述式调用** | `对**n=31**执行**加一函数**` | 只要语法糖(绑定仍在句中) | ✅ **可做,且安全** |
|
||||
| **L1 就近绑定** | 上一行 `**n=31**`,下一行 `执行**加一函数**` | 段落级隐式作用域 | ⚠️ 能做但危险,不建议 |
|
||||
| **L2 真隐式** | 只写 `执行**加一函数**`,n 全靠上下文 | 动态作用域 | ❌ **不建议**,见 §4 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 实测:今天到底发生了什么
|
||||
|
||||
| # | 用例 | 实测 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 1 | 你的示例原样 | **无输出、无报错、exit 0** | 静默 no-op |
|
||||
| 2 | 同样写法 + `> print text=`n`` | `main里的n=31` | **散文行里的 `**n=31**` 真的执行了** |
|
||||
| 3 | 只写 `对`加一函数`执行` | `done`,无报错 | 裸名字只被求值丢弃,**未调用** |
|
||||
| 4 | `**n = 31**` + `> 加一函数`(不传参) | `missing argument for parameter n` | **函数看不见调用者的 `n`** |
|
||||
| 5 | `> 加一函数 n=31` | `32` | 显式写法今天就能做 |
|
||||
| 6 | `# main` 读 frontmatter `税率` | `0.1` ✅ | 入口可见 |
|
||||
| 7 | `## 函数` 读同一个 `税率` | `undefined variable` ❌ | 函数不可见 |
|
||||
| 8 | 浏览器 WASM 入口调用函数 | metadata + `entry_bindings` **都会传** | 见 §5,**与 CLI 不一致** |
|
||||
|
||||
**第 2 与第 3 条合起来是关键**:散文行里的粗体确实会执行,但一个裸函数名在粗体里
|
||||
只是一个**表达式语句**(值算了就丢),不会变成调用。所以「看起来该调用」的句子,
|
||||
实际什么也没做——又是一次静默失败(与 D9 同一类)。
|
||||
|
||||
**第 4 条是语义基石**:Marqdo 现在的作用域是**严格分离**的,
|
||||
函数只能看到自己的形参与局部变量。你想要的 L2,就要拆掉这块基石。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你自己的担心是对的:数据在这里
|
||||
|
||||
你提到「大项目变量名会难以使用」。我把仓库里 `lib/ ext/ examples/ tests/` 全扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 扫描函数数 | **1322** |
|
||||
| 不同形参名 | 819 |
|
||||
| **被 ≥5 个函数共用的形参名** | **130 个** |
|
||||
|
||||
撞车最严重的一批:
|
||||
|
||||
| 形参名 | 用它的函数数 |
|
||||
|--------|-------------|
|
||||
| `path` | **70** |
|
||||
| `value` | 59 |
|
||||
| `text` | 53 |
|
||||
| `id` | 47 |
|
||||
| `list` | 38 |
|
||||
| `内容` | 38 |
|
||||
| `路径` | 35 |
|
||||
| `a` / `b` | 各 32 |
|
||||
|
||||
结论很直接:**如果参数靠上下文推断,那么每次调用一个读 `text` 的函数,
|
||||
它都会去捡当前作用域里的 `text` 是什么**。53 个函数在等这个值——
|
||||
撞车是常态,不是例外。这不是「大项目才有」的问题,中型项目就已经不可控。
|
||||
|
||||
---
|
||||
|
||||
## 3. L0:叙述式调用(推荐做)
|
||||
|
||||
### 3.1 目标写法
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对`n`我们让**n=n+1**之后返回*n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 对 n=31 执行 加一函数**
|
||||
> print text=`结果` # → 32
|
||||
```
|
||||
|
||||
### 3.2 语义映射(零模型改动)
|
||||
|
||||
```
|
||||
对 <绑定子句> 执行 <函数名> ≡ Call { callee: <函数名>, args: [<绑定子句>…] }
|
||||
```
|
||||
|
||||
也就是**纯粹换语序**的语法糖。它与今天的
|
||||
|
||||
```markdown
|
||||
**结果 = > 加一函数 n=31**
|
||||
```
|
||||
|
||||
产出**同一个 `CallExpr`**。因此:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约校验(T2.1/T2.2) | **不变**(实参照常绑定与校验) |
|
||||
| EKC 指纹 `collect_calls` | **不变**(callee 仍是静态名) |
|
||||
| 字节码 `Op::Call(fid, argc)` | **不变** |
|
||||
| 序列化 / 沙箱 | **不变** |
|
||||
| `view` 渲染 | 需决定回显哪一种语序 |
|
||||
|
||||
这正是它与「一等函数」「动态作用域」的本质区别:**只改写法,不改调用模型。**
|
||||
|
||||
### 3.3 设计细节要定的三件事
|
||||
|
||||
1. **动词**:`执行` 目前**不是**关键字;而 `调用` **已经是**关键字(`src/aliases.rs:39`
|
||||
把 `调用` 映射到内建 `call_fn`)。两个近义词并存会混乱,需要二选一或明确分工。
|
||||
2. **绑定子句的边界**:`对 n=31 执行 …` 里 `n=31` 到 `执行` 之间是参数区;
|
||||
多参数写 `对 n=31 m=2 执行 …`。
|
||||
3. **与散文的冲突**:`对` 起头的行今天是叙述(CJK 开头 = 注释)。
|
||||
要让这行变成代码,得给「叙述里出现 `执行 <函数名>`」一个可判定的规则,
|
||||
否则又是一处「看起来是代码、实际是注释」的静默陷阱。
|
||||
|
||||
---
|
||||
|
||||
## 4. L2:真隐式参数(不建议)
|
||||
|
||||
### 4.1 它到底是什么
|
||||
|
||||
L2 = **动态作用域**(dynamic scoping):被调函数在**调用者的环境**里查找自由变量。
|
||||
历史上被反复试过、也反复放弃:早期 Lisp 改成词法作用域、Shell 的动态作用域被视为坑。
|
||||
|
||||
### 4.2 七条硬伤(每条都是具体后果,不是理论洁癖)
|
||||
|
||||
| # | 问题 | 具体后果 |
|
||||
|---|------|---------|
|
||||
| 1 | **同名捕获** | `加一函数` 调 `记录日志`,两者都读 `text` → 日志函数静默拿到加一的局部值,输出错内容而不报错 |
|
||||
| 2 | **递归自毁** | `n=n+1` 后调自身:内层看到的是**已被改过的** n(还是副本?)——必须新增一套遮蔽规则,而规则本身又会成为新的坑 |
|
||||
| 3 | **无法复用** | 同一函数两次不同入参,只能反复改外部变量并祈祷调用顺序,等于把「参数」退化成全局可变状态 |
|
||||
| 4 | **契约报废** | `call_arg_diag` 在**调用边界**校验实参类型;如果不传实参,就没有校验点。T2.1/T2.2 契约体系直接失效 |
|
||||
| 5 | **指纹/arity 失真** | `collect_calls` 记录被调名,arity 由形参推断;隐式调用在 AST 上看起来是零参调用 → 复用预检、`plan` 能力匹配、查重全都失真 |
|
||||
| 6 | **沙箱与序列化** | `sandbox.run` 以隔离方式执行文档;隐式依赖外部作用域会破坏隔离语义;环境也必须可序列化 |
|
||||
| 7 | **不可审计** | 函数行为依赖看不见的上下文——这就是「全局可变状态」的经典问题,与「文档即程序、可被人读懂」直接冲突 |
|
||||
|
||||
再叠加 §2 的数据(130 个名字被 ≥5 函数共用),第 1 条不是边角情况,而是默认情况。
|
||||
|
||||
### 4.3 但有一个**受限版**值得考虑
|
||||
|
||||
如果你真正想要的是「短脚本读起来顺」,那么下面这个版本是安全的:
|
||||
|
||||
> **常量默认值**:允许函数在**未传入**某形参时,从**文件级常量**取值。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 报价
|
||||
税率: 0.1
|
||||
---
|
||||
|
||||
## 含税
|
||||
+ `金额`
|
||||
|
||||
*`金额` * (`税率`)* # 税率 未传入 → 取 frontmatter 常量
|
||||
|
||||
# main
|
||||
|
||||
**a = > 含税 金额=100** # 10
|
||||
**b = > 含税 金额=100 税率=0.06** # 6,显式覆盖
|
||||
```
|
||||
|
||||
为什么它安全而 L2 不安全:
|
||||
|
||||
| 维度 | L2 动态作用域 | 常量默认值 |
|
||||
|------|--------------|-----------|
|
||||
| 取值来源 | 调用者的**任意**变量 | 文件顶部**写一次**的常量 |
|
||||
| 静态可判定 | ❌ 取决于运行路径 | ✅ 打开文件就能看到 |
|
||||
| 随调用者变化 | ✅ 会变(最危险) | ❌ 不会 |
|
||||
| 契约 | 失效 | 仍可校验(实参照常声明) |
|
||||
| 序列化/沙箱 | 破坏隔离 | 可序列化(常量是数据) |
|
||||
| 复用 | 破坏 | 不受影响 |
|
||||
|
||||
**关键差别**:常量是**文档的一部分**(frontmatter 就在文件开头,人读得到),
|
||||
而动态作用域的值是**运行路径的一部分**(人读不到)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带发现的真问题:CLI 与 Web 的环境不一致
|
||||
|
||||
实测 §1 第 6/7/8 条时发现:
|
||||
|
||||
| 路径 | 函数可见环境 | 源码 |
|
||||
|------|-------------|------|
|
||||
| `# main`(CLI 运行) | frontmatter metadata ✅ | `src/interp.rs:473` `Env::with_metadata` |
|
||||
| **普通函数调用** | 只有实参 ❌ | `eval_call` 用 `Env::new()` |
|
||||
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
|
||||
|
||||
也就是说:**同一份文档,在浏览器里函数能读到 frontmatter 常量、还能读到 `# main`
|
||||
的绑定;在 CLI 里读不到。** 行为随运行面不同而不同。
|
||||
|
||||
这是一个**真实缺陷**,已记入 [D11](../research/qdagent-refactor-defects-2026-10.md):
|
||||
|
||||
- 对使用者:同一文件在 Web 能跑、在 CLI 报 `undefined variable`,极难排查
|
||||
- 对设计:说明「受控环境通道」其实已经存在(只是没在 CLI 打开),
|
||||
这既是 L2 受限版的现成基础,也是必须先统一的地方
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
| 优先级 | 事项 | 性质 |
|
||||
|--------|------|------|
|
||||
| 1 | **先统一 CLI/Web 的函数环境**(D11) | 修缺陷,消除行为分裂 |
|
||||
| 2 | **做 L0 叙述式调用**(`对 X 执行 F`) | 纯语法糖,零模型改动,554 回归可守 |
|
||||
| 3 | 若要「少写参数」,做**常量默认值**(§4.3) | 受控隐式,静态可判定 |
|
||||
| 4 | **不做 L2 动态作用域** | 七条硬伤 + 130 个撞车名 |
|
||||
|
||||
关于「代码即文档」的取向,我的理解是:
|
||||
|
||||
> 文档化的是**写法**(句子怎么读),不是**语义**(值从哪来)。
|
||||
> 让句子更像人话是值得的;让值从看不见的地方来,是把可读性换成不可预测性。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **L0 是否采纳?** 若采纳,动词用 `执行` 还是复用已有的 `调用`?
|
||||
2. **`对…执行…` 的行如何与散文区分**(§3.3 第 3 点)?这决定它会不会变成新的静默陷阱。
|
||||
3. **常量默认值**(§4.3)要不要做?
|
||||
4. **D11(CLI/Web 环境不一致)** 是否现在就修?我建议先修它,因为它会影响 L0/L2 的所有验证结论。
|
||||
@@ -0,0 +1,300 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 |
|
||||
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
|
||||
| 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) |
|
||||
|
||||
> **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`;
|
||||
> 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。
|
||||
> 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)**
|
||||
> 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 先把提案精确化
|
||||
|
||||
你的话可以解析出三种读法,差别很大,必须先分清:
|
||||
|
||||
| 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 |
|
||||
|------|------------|------------|-----------|
|
||||
| **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** |
|
||||
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
|
||||
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
|
||||
|
||||
你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**:
|
||||
**`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么我们会下意识觉得这个写法"美"
|
||||
|
||||
你的直觉不是审美偏好,它对应三个**真实存在**的设计同构:
|
||||
|
||||
### 1.1 超链接:可见文本 ↔ 目标
|
||||
|
||||
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
|
||||
这是人类最早、最成功的"双面文本"。
|
||||
|
||||
### 1.2 文学编程的 chunk 名(Knuth)
|
||||
|
||||
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
|
||||
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
|
||||
|
||||
### 1.3 Marqdo 自己已经有这个形态
|
||||
|
||||
```markdown
|
||||

|
||||
```
|
||||
|
||||
- `[]` 里是**指令/说明**(`marqdo-out`、可带 key)
|
||||
- `()` 里是**负载**(图片 URL / data URI)
|
||||
|
||||
**语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。
|
||||
|
||||
### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看"
|
||||
|
||||
| 用法 | 数量 | 谁读 |
|
||||
|------|------|------|
|
||||
| `[键](集合)` 取元 | 506 | 机器 |
|
||||
| `- [项](集合)` 循环 | 44 | 机器 |
|
||||
| `[函数] 参数` 调用 | **0(可执行)** | — |
|
||||
| `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** |
|
||||
|
||||
**可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。
|
||||
这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强)
|
||||
|
||||
### 2.1 收益一:两条规则变一条 —— 这是最大的价值
|
||||
|
||||
现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结:
|
||||
|
||||
> `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。
|
||||
|
||||
你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句",
|
||||
那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。
|
||||
|
||||
> 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。**
|
||||
> 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。
|
||||
|
||||
### 2.2 收益二:嵌套取元终于可读
|
||||
|
||||
现在是:
|
||||
|
||||
```markdown
|
||||
**第一 = [1]([苹果](货架))**
|
||||
```
|
||||
|
||||
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
|
||||
|
||||
改成标签后:
|
||||
|
||||
```markdown
|
||||
**第一 = [货架里苹果的第一项](…机器语句…)**
|
||||
```
|
||||
|
||||
**人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。
|
||||
|
||||
### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围
|
||||
|
||||
你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。
|
||||
|
||||
**这一点需要精确化,因为它决定这块值不值得改**:
|
||||
|
||||
| 阅读场合 | `- [果](篮子)` 的表现 |
|
||||
|---------|---------------------|
|
||||
| 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 |
|
||||
| **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 |
|
||||
|
||||
而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。
|
||||
|
||||
**结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合
|
||||
(`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事:
|
||||
|
||||
> **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。**
|
||||
> 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。
|
||||
|
||||
这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。
|
||||
|
||||
### 2.4 附带收益:标签是天然的锚点
|
||||
|
||||
你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小:
|
||||
|
||||
- `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位"
|
||||
- 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118`
|
||||
- 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多
|
||||
|
||||
---
|
||||
|
||||
## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元
|
||||
|
||||
这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。
|
||||
|
||||
若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法:
|
||||
|
||||
| 方案 | 形态 | 问题 |
|
||||
|------|------|------|
|
||||
| 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 |
|
||||
| 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 |
|
||||
| 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 |
|
||||
| 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 |
|
||||
|
||||
**这就是核心张力**:
|
||||
|
||||
> 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性;
|
||||
> 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则),
|
||||
> 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。
|
||||
|
||||
换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。**
|
||||
这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」,
|
||||
**用一条新规则换掉一条旧规则,不必然是净简化**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 描述漂移:我认为不能轻描淡写
|
||||
|
||||
你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条:
|
||||
|
||||
### 4.1 它是"注释"的回归
|
||||
|
||||
Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。
|
||||
而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。
|
||||
Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。
|
||||
|
||||
### 4.2 一旦标签成为锚点,漂移就有操作后果
|
||||
|
||||
你在 §2.4 里期望标签用于跳转与定位。那么:
|
||||
|
||||
- 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎**
|
||||
- agent 用标签定位 bug → 被标签误导
|
||||
- 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌
|
||||
|
||||
**标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。
|
||||
|
||||
### 4.3 安全面:标签是 agent 可读的攻击面
|
||||
|
||||
Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。
|
||||
「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。
|
||||
|
||||
**所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**:
|
||||
|
||||
| 缓释手段 | 说明 | 成本 |
|
||||
|---------|------|------|
|
||||
| ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 |
|
||||
| ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 |
|
||||
| ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 |
|
||||
| ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 |
|
||||
|
||||
其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B),
|
||||
而对"标签写得更细"这种正常情况不误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 采用风险:可能重演 v0.3 废除的"仪式感"
|
||||
|
||||
v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。
|
||||
|
||||
强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化:
|
||||
|
||||
1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有
|
||||
2. **噪音**:标签越写越长,正文被切碎,扫描性下降
|
||||
|
||||
这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。
|
||||
所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。
|
||||
|
||||
**这个矛盾必须在设计里正面解决,不能靠自觉。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移面(实测)
|
||||
|
||||
| 受影响的写法 | 数量 | 文件 |
|
||||
|------------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 个文件 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 个文件 |
|
||||
| `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
|
||||
**危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单),
|
||||
而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
|
||||
|
||||
所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报
|
||||
「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。
|
||||
另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 两条落地路线
|
||||
|
||||
### 路线一:双层(推荐,兼容)
|
||||
|
||||
> **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。**
|
||||
|
||||
- **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环
|
||||
- **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写**
|
||||
- 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
|
||||
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
|
||||
| 嵌套可读、循环可写清来源 | |
|
||||
| 标签可以逐步引入,不强迫 | |
|
||||
|
||||
### 路线二:纯度(一条规则到底)
|
||||
|
||||
> `()` 只装机器语句,取元必须搬进 `()`。
|
||||
|
||||
必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
|
||||
| `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 |
|
||||
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 我的评定
|
||||
|
||||
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
|
||||
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|------|------|
|
||||
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
|
||||
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
|
||||
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
|
||||
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
|
||||
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
|
||||
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
|
||||
|
||||
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
|
||||
让短形成为"读得懂但不必写"的兼容层。这样:
|
||||
|
||||
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
|
||||
- 506 处零迁移
|
||||
- 调用终于有家,且成本为零
|
||||
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
|
||||
|
||||
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
|
||||
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
|
||||
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **路线一(双层)还是路线二(纯度)?**
|
||||
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
|
||||
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
|
||||
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
|
||||
5. 循环的新写法你倾向哪一种:
|
||||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||||
- `- [篮子里的果子](篮子 → 果)`
|
||||
- 保留 `- [果](篮子)` 作短形
|
||||
@@ -0,0 +1,287 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 前置纠正 | 用户否决上一轮的「叙述式动词」方案:**未标记词承载语义 = 破坏「叙述默认安全」** |
|
||||
| 方法 | 实测 6 组(含双后端性能对比、叙述顺序实验)+ 源码比对 |
|
||||
| 相邻 | [ambient-parameters-evaluation.md](ambient-parameters-evaluation.md) · [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 先接受纠正:错在哪
|
||||
|
||||
我上一轮提的 `对**n=31**执行**加一函数**`,靠**未标记的词「执行」**来触发调用。这确实违背底层原则:
|
||||
|
||||
> **叙述(未标记)= 默认安全,不执行;标记 = 才进编译器。**
|
||||
|
||||
一旦「执行」这种词能改变语义,那么:
|
||||
|
||||
- 作者改一句措辞("执行" → "运行" / "调用" / 换个说法)就可能改变程序行为;
|
||||
- 读者无法只看标记判断哪句是代码——必须逐字读叙述;
|
||||
- 与 D9 同类的静默风险:语义藏在叙述里。
|
||||
|
||||
**所以本文的设计约束是硬的**:
|
||||
|
||||
> **调用的每一个语义成分(被调者、每个实参、绑定关系)必须落在标记内;
|
||||
> 叙述词只能起连接与解释作用,永不改变语义。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 先盘清「标记字母表」
|
||||
|
||||
要设计调用,先得知道手上只有哪些字。
|
||||
|
||||
| 标记 | 现行语义 | 可否参与构成调用 |
|
||||
|------|---------|-----------------|
|
||||
| `**…**` | 执行段(赋值 / 调用 / 表达式) | ✅ 主载体 |
|
||||
| `*…*` | 返回 | ✅ 终止 |
|
||||
| `` `x` `` | 变量引用;首次出现即声明 | ✅ 槽名 |
|
||||
| `` `x` = `` | 叙述中的绑定 | ✅ 槽赋值 |
|
||||
| `**x = …**` | 赋值 | ✅ |
|
||||
| `> …`(行首) | 调用语句 | ✅ 已是调用标记 |
|
||||
| `[callee] args` | 方括号调用(消歧 / 前置修饰) | ✅ 已是调用标记 |
|
||||
| `[k](coll)` | 取元 | ⚠️ 与调用抢外形(已否) |
|
||||
| `- [x](coll)` | 遍历 | — |
|
||||
| `#` / `##` | 对象 / 函数声明 | — |
|
||||
| 表格 | 数据 / 契约 | — |
|
||||
| ```lang | 外联代码 | — |
|
||||
|
||||
**关键观察**:调用载体其实只有三种标记:`> 行`、`**…**`、`[callee]`。
|
||||
而 `[k](coll)` 这个外形已被取元独占(前几轮结论),不能用。
|
||||
|
||||
所以问题收敛为:
|
||||
|
||||
> **在 `**…**` 或 `> …` 内部,用哪些标记把「函数名」和「槽赋值」连起来?**
|
||||
|
||||
---
|
||||
|
||||
## 2. 可读性从哪来(这是设计的核心)
|
||||
|
||||
Marqdo 的叙述与代码是**两层**:叙述解释「为什么」,标记表达「做什么」。
|
||||
所以可读性不是靠把叙述词变成语法,而是靠:
|
||||
|
||||
1. **标记本身足够像自然记号**(`=`, `(`, `)`, `→` 都是跨语言的);
|
||||
2. **叙述与标记紧邻**,人一句一码地读;
|
||||
3. **同一件事只写一遍**(叙述不要复述代码)。
|
||||
|
||||
一句话:
|
||||
|
||||
> **叙述负责「说人话」,标记负责「说准话」;两者相邻即高可读,混在一起即两败。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 三个候选设计
|
||||
|
||||
### 设计 A — 括注具名调用:`**加一函数(n=31)**`
|
||||
|
||||
**读法**:`加一函数(n=31)` —— 与数学/几乎所有语言的函数调用同构。
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ 整段在 `**…**` 内 |
|
||||
| 无歧义 | ✅ 圆括号紧跟名字 = 调用;取元需方括号,不冲突 |
|
||||
| 与叙述结合 | ✅「把 n 设为 31 后**加一函数(n=31)**」 |
|
||||
| 多参数 | ✅ `f(a=1 b=2)` |
|
||||
| 编译器 | ✅ 具名 → 编译期映射到槽下标(见 §4) |
|
||||
| 实现成本 | ⚠️ 需改参数分词器:`)` 作终止符、逗号、嵌套(原型已验 554/0,但 `f(1 2)` 的末参数会吞 `)`) |
|
||||
|
||||
### 设计 B — 箭头槽赋值:`**n=31 → 加一函数**`
|
||||
|
||||
**读法**:「n 设为 31,交给加一函数」——最贴合汉语「先条件、后动作」语序。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n=31 → 加一函数**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ `→` 是符号标记,不是词 |
|
||||
| 可读性 | ✅✅ 流水线极顺:`**订单 → 计税 → 汇总**` |
|
||||
| 无歧义 | ⚠️ 需定义优先级;`**x = a=1 → f**` 有歧义,得靠括号 |
|
||||
| 求值结果 | ⚠️ 箭头式天然是语句式;要拿返回值还得包一层 |
|
||||
| 实现成本 | 中:新增运算符 + 优先级 + 与 `=`/`*…*` 的交互 |
|
||||
|
||||
### 设计 C — 现成空格式:`**加一函数 n=31**`(今天就可用)
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ |
|
||||
| 实现成本 | **零**(实测 `**r = 加 1 2**` 已可跑) |
|
||||
| 可读性 | ⚠️ 参数边界靠空格;函数名含空格时不可用(D8) |
|
||||
| 编译器 | ✅ 具名同样可映射槽位 |
|
||||
|
||||
### 三者的取舍
|
||||
|
||||
| | A 括注 | B 箭头 | C 空格 |
|
||||
|---|---|---|---|
|
||||
| 像通用函数调用 | ✅✅ | ⚠️ | ✅ |
|
||||
| 中文语序自然 | ⚠️ | ✅✅ | ✅ |
|
||||
| 参数边界清晰 | ✅✅ | ✅ | ❌(空格切分) |
|
||||
| 链式组合 | ⚠️ | ✅✅ | ❌ |
|
||||
| 改动成本 | 中 | 中高 | **零** |
|
||||
| 与取元冲突 | 无 | 无 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「不分实参形参」:编译器视角的真实收益
|
||||
|
||||
你问的是:不再区分实参/形参,是否意味着变量总在某个固定位置、能否减少 IO。
|
||||
这一节用实测回答,结论会有点意外。
|
||||
|
||||
### 4.1 现状:两条执行路径,差异 3.8 倍
|
||||
|
||||
| 路径 | 参数如何绑定 | 200k 次调用(1 个 int 实参) | 2000 次调用(500 元素列表) |
|
||||
|------|-------------|------------------------------|------------------------------|
|
||||
| **树遍历**(默认 `Backend::Tree`) | `Env { HashMap<String, Value> }`,每个实参 `k.clone()` + `v.clone()`(**深拷贝**) | 167 ms | 66 ms |
|
||||
| **字节码**(`--backend bytecode`) | `slots: Vec<Value>`,`pop` 后**按位置移动**入槽(**无克隆、无哈希**) | **44 ms** | **23 ms** |
|
||||
|
||||
源码依据:
|
||||
|
||||
```rust
|
||||
// src/bytecode/vm.rs Op::Call(fid, argc)
|
||||
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
|
||||
for i in (0..argc).rev() {
|
||||
slots[i] = pop(&mut stack)?; // 移动,不克隆
|
||||
}
|
||||
frames.push(Frame { fn_idx: fid, ip: 0, slots, .. });
|
||||
```
|
||||
|
||||
### 4.2 三个结论
|
||||
|
||||
**结论一:「变量始终在某个位置」已经是字节码的现实。**
|
||||
形参按下标落槽,实参按位置移动入槽。这正是你说的模型——它已经存在。
|
||||
|
||||
**结论二:收益是真的,3.8×。**
|
||||
每次调用 0.83µs → 0.22µs;大实参 33µs → 11.5µs(省掉了深拷贝)。
|
||||
|
||||
**结论三(关键):这与「不分实参形参」的语法无关。**
|
||||
槽位化只需要「编译期知道形参顺序」,而形参顺序今天就有(v0.3 体推断给出确定顺序)。
|
||||
真正的瓶颈是**树遍历解释器用名字哈希 + 深拷贝**,以及**默认后端是 Tree**。
|
||||
|
||||
> **所以:不要用性能去论证语义变更。**
|
||||
> 想省 IO,把默认后端切到字节码、或把树遍历解释器槽位化即可——
|
||||
> 这是一条与语法正交的工程路径,收益确定、风险可控。
|
||||
> 而改语义(动态作用域)换来的性能,等于用正确性买速度。
|
||||
|
||||
### 4.3 但有一个真实的语法—性能耦合点:具名 vs 位置
|
||||
|
||||
这是本节最有价值的发现。**在「形参由体推断」的世界里,形参顺序 = 叙述里首次声明的顺序**
|
||||
(v0.3 §8.2:顺序按升参名字的首次声明事件出现序)。而叙述是可以自由改写的。
|
||||
|
||||
我用两个只差一句话序的文件做了实验:
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`a`和`b`。 ← 叙述顺序 a, b
|
||||
*`a` - `b`*
|
||||
```
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`b`和`a`。 ← 只把叙述顺序改成 b, a
|
||||
*`b` - `a`*
|
||||
```
|
||||
|
||||
| 调用写法 | 叙述 a 在前 | 叙述 b 在前 |
|
||||
|---------|------------|------------|
|
||||
| 具名 `a=10 b=3` | 7 | -7(语义随函数体改变,符合预期) |
|
||||
| **位置 `10 3`** | 7(a=10,b=3) | **7(b=10,a=3)** ← **绑定翻转了** |
|
||||
|
||||
**同一行调用代码 `> 减 10 3`,只因为作者改了前面的叙述语序,实际绑定就变了,而且不报错。**
|
||||
|
||||
这在「实参形参不分」的模型下是致命的:既然只有槽、槽序来自叙述,
|
||||
那么**位置传参等于把程序语义挂在叙述的可改写顺序上**。
|
||||
|
||||
**推论**:调用应当**以具名为准**,位置实参在体推断世界里是脆弱语法。
|
||||
这一点与编译器优化正好同向——具名调用让编译期把 `n` 静态映射到 `slots[0]`,
|
||||
既稳又快(不需要运行期哈希,也不需要猜顺序)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 我的设计建议
|
||||
|
||||
### 5.1 主形态:括注具名调用
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
理由:
|
||||
|
||||
1. **全部语义在标记内**(满足你的核心原则);
|
||||
2. 与通用函数调用同构,零学习成本;
|
||||
3. 具名 → 编译期静态映射槽位(对接字节码已有的 `slots[]`);
|
||||
4. 不碰取元 `[k](coll)`,不碰遍历 `- [x](c)`;
|
||||
5. 参数边界显式,顺带解决函数名含空格的调用难题(D8)。
|
||||
|
||||
### 5.2 位置实参:降级而非禁止
|
||||
|
||||
| 情形 | 建议 |
|
||||
|------|------|
|
||||
| 单参数 | 允许 `f(31)`(无歧义、写法自然) |
|
||||
| 多参数 | **要求具名**;位置仅保留给 `> f 1 2` 这种旧写法,并在 `check` 里 **warn** |
|
||||
| 理由 | §4.3:顺序来自叙述,可被改写而不报错 |
|
||||
|
||||
### 5.3 箭头(设计 B)作为可选补充
|
||||
|
||||
如果后续确实需要「流水线可读性」,再引入 `→`,定位为**语句式组合子**:
|
||||
|
||||
```markdown
|
||||
**订单 → 计税 → 汇总**
|
||||
```
|
||||
|
||||
但它是增量特性,不是本设计的前提。优势是链式,代价是优先级与返回值语义。
|
||||
|
||||
### 5.4 明确不做
|
||||
|
||||
| 方案 | 理由 |
|
||||
|------|------|
|
||||
| 未标记动词触发调用(上轮 L0) | 违背「叙述默认安全」 |
|
||||
| `[f](args)` | 与取元同形,已实测 2 个真实冲突文件 |
|
||||
| 动态作用域(参数从上下文推断) | 七条硬伤 + 130 个撞车形参名 |
|
||||
| 位置实参作为主流 | §4.3 叙述顺序会静默改变绑定 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 优劣总表
|
||||
|
||||
| 设计 | 标记完备 | 可读性 | 无歧义 | 编译器友好 | 改动 | 结论 |
|
||||
|------|---------|--------|--------|-----------|------|------|
|
||||
| **A 括注具名 `f(n=31)`** | ✅ | 高 | ✅ | ✅ 静态槽映射 | 中 | **推荐主形态** |
|
||||
| C 空格式 `f n=31` | ✅ | 中 | ✅ | ✅ | 零 | 今天可用,作兼容 |
|
||||
| B 箭头 `n=31 → f` | ✅ | 最高(流水线) | ⚠️ 优先级 | ✅ | 中高 | 可选增量 |
|
||||
| `[f](args)` | ✅ | 高 | ❌ 撞取元 | — | — | 不做 |
|
||||
| 未标记动词 | ❌ | 高 | ❌ | — | — | 不做 |
|
||||
| 动态作用域 | ✅ | 最高 | ❌ | ❌ 契约/指纹失效 | 高 | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **主形态选 A(括注具名)吗?** 若选,我按 B 档实现:`f(k=v)` 必通、`f(x)` 单参、多参数求具名。
|
||||
2. **位置实参**:多参时"要求具名 + 旧写法 warn"(§5.2),还是保持现状不动?
|
||||
3. **箭头**现在做还是留作后续?
|
||||
4. **顺带**:默认后端要不要切字节码(实测 3.8×,但需先验证 554 用例在 `--backend bytecode` 下全绿)?这条与语法无关,但可能是最划算的性能改进。
|
||||
|
||||
> 若你同意 A,我下一步会:改分词器(`)` 终止、逗号、嵌套)→ 补金样例 →
|
||||
> 跑双后端 554 回归 → 写变更文档。
|
||||
@@ -0,0 +1,231 @@
|
||||
# 变更记录:D9 未闭合引号不再静默吞行
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(待合入) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 |
|
||||
| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` |
|
||||
| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
$ echo $?
|
||||
0 # 没有输出、没有报错,s 这一行凭空消失
|
||||
```
|
||||
|
||||
**修复后**:解析期报错,退出码非 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
error: u.mq.md: 7:1: unterminated string: this line starts bold code but
|
||||
contains an odd number of `"` -- close the string and the trailing `**`
|
||||
(line: **s = "abc)
|
||||
$ echo $?
|
||||
1
|
||||
```
|
||||
|
||||
(实测记录:报错回显中 `unterminated` 前的空格与行号格式由
|
||||
`Diagnostic` 的 span 渲染决定,与其它语法错一致。)
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
问题**不在**解析器——`parse_quoted_string` 里的
|
||||
`bail!("unterminated {quote} string")` 一直都在,措辞也对。
|
||||
问题是这一行**根本到不了解析器**:
|
||||
|
||||
```
|
||||
"**s = \"abc"
|
||||
↓ classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
matching_bold_close() 扫描时遇到 '"' → in_str = true
|
||||
之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过
|
||||
→ 找不到收尾 '**' → 返回 None
|
||||
↓ is_marqdo_star_line = false
|
||||
↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 成为「叙述」,解析器看不到
|
||||
```
|
||||
|
||||
**这是分类层的静默降级,不是解析层的缺陷。**
|
||||
|
||||
它比一般的解析错误更危险,因为:
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** |
|
||||
| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 怎么改的
|
||||
|
||||
两层,缺一不可。
|
||||
|
||||
### 3.1 分类层:把畸形行留在 Code 类
|
||||
|
||||
`src/lex/mod.rs`
|
||||
|
||||
```rust
|
||||
if trimmed.starts_with("**") {
|
||||
if trimmed.trim() == "** **" {
|
||||
return true;
|
||||
}
|
||||
if matching_bold_close(trimmed).is_some() {
|
||||
return true;
|
||||
}
|
||||
// D9: 粗体起始但引号永不闭合 → 找不到收尾 `**`
|
||||
// 判为 Comment 会静默丢行;判为 Code 让解析器报错
|
||||
return has_unterminated_string(trimmed);
|
||||
}
|
||||
```
|
||||
|
||||
新增辅助函数:
|
||||
|
||||
```rust
|
||||
pub fn has_unterminated_string(line: &str) -> bool {
|
||||
// 统计未被 \ 转义的双引号个数,奇数即「开了没收」
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析层:给出精确报错
|
||||
|
||||
`src/parse/mod.rs`,紧跟既有粗体分支之后:
|
||||
|
||||
```rust
|
||||
// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`,
|
||||
// 通用 "unrecognized statement" 会掩盖真正原因。
|
||||
if trimmed.starts_with("**") && has_unterminated_string(trimmed) {
|
||||
bail!("{span}: unterminated string: ... (line: {trimmed})");
|
||||
}
|
||||
```
|
||||
|
||||
没有这一层,用户会看到 `unrecognized statement: **s = "abc`——
|
||||
能定位到行,但不知道是引号没闭合。
|
||||
|
||||
---
|
||||
|
||||
## 4. 影响面(改前量化过)
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
### 5.1 新增单元测试(`src/lex/mod.rs`,4 个)
|
||||
|
||||
| 测试 | 断言 |
|
||||
|------|------|
|
||||
| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) |
|
||||
| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` |
|
||||
| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` |
|
||||
| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` |
|
||||
|
||||
**先写测试确认失败**(TDD):
|
||||
|
||||
```
|
||||
---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment
|
||||
panicked: expected Code (so parser reports the error),
|
||||
got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }]
|
||||
```
|
||||
|
||||
修复后 14/14 通过。
|
||||
|
||||
### 5.2 回归
|
||||
|
||||
| 范围 | 结果 |
|
||||
|------|------|
|
||||
| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) |
|
||||
| `cargo test --release --test gold` | 276 passed, 8 failed |
|
||||
| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed |
|
||||
| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知边界
|
||||
|
||||
| 情形 | 行为 | 说明 |
|
||||
|------|------|------|
|
||||
| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 |
|
||||
| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 |
|
||||
| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 |
|
||||
|
||||
> 单引号的情况建议后续按同样思路处理,但需要单独评估
|
||||
> (单引号也用于英文撇号,误判风险高于双引号)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 |
|
||||
| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 |
|
||||
| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) |
|
||||
| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) |
|
||||
| `doc/design/change-d9-unterminated-string.md` | 本文件 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附:本机测试环境(2026-10-22 装好)
|
||||
|
||||
修复过程中发现本机缺两样东西,导致基线本来就有失败。补环境后全量测试 **554 passed / 0 failed**。
|
||||
|
||||
### 8.1 两个非直觉约束
|
||||
|
||||
| 约束 | 表现 | 解法 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `error: AccessDenied`(全局缓存无处可写) | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 显式指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接报 `running gcc failed: signal: aborted`;zig 链接报 `AccessDenied` | `TMPDIR` 指向可写**且可执行**目录 |
|
||||
|
||||
第二条最隐蔽:`/tmp` 挂载为 `rw,nosuid,nodev,noexec`,构建工具会把产物写到那里再执行,
|
||||
于是「文件能写、却执行不了」。错误信息完全指向不了这一点。
|
||||
|
||||
### 8.2 Go 插件(`libweb.so`)
|
||||
|
||||
`gold` 测试里 8 个 `ext_web_*` 失败全因缺 `libweb.so`:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # 提供 go 1.25 + gcc shim(zig) + TMPDIR
|
||||
./scripts/build-web-plugin.sh # 产出 plugins/web/build/libweb.so
|
||||
cp plugins/web/build/libweb.so target/release/ target/debug/
|
||||
```
|
||||
|
||||
Go 的 cgo 要 `gcc`,本机没有,用 zig cc 充当:
|
||||
`/workspace/qdagent/.tools/zigcc/bin/gcc`(会过滤 Go 传入的 `-Qunused-arguments`,
|
||||
该参数会让 zig 驱动 abort)。
|
||||
|
||||
### 8.3 一键复用
|
||||
|
||||
新增 `scripts/dev-env.sh`,`source` 后即具备完整工具链:
|
||||
|
||||
```
|
||||
marqdo dev-env: rust=1.81.0 go=go1.25.0 python=3.12.15 cc=zig-glibc2.36
|
||||
```
|
||||
|
||||
### 8.4 环境修复前后的测试对比
|
||||
|
||||
| 阶段 | lib 测试 | gold 测试 |
|
||||
|------|----------|-----------|
|
||||
| 无 python3 | 231 / 2 failed | — |
|
||||
| 加 python3 | 233 / 0 failed | 276 / 8 failed |
|
||||
| 加 go + libweb | — | **284 / 0 failed** |
|
||||
| **全量** | | **554 passed / 0 failed** |
|
||||
@@ -0,0 +1,99 @@
|
||||
# 变更记录:HostFn 五张表合一(`HOST_FN_TABLE` 单一来源)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 4 项 |
|
||||
| 改动 | `src/host/dispatch.rs`:**−404 行**(639 删 / 235 增) |
|
||||
| 行为 | **零变化**(203 项逐字节一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原来有五张并行表
|
||||
|
||||
202 个宿主函数的元数据分散在五个手写 match 里:
|
||||
|
||||
| 表 | 行数 | 作用 |
|
||||
|----|------|------|
|
||||
| `from_u16` | ~215 | id → 变体 |
|
||||
| `from_name` | ~215 | 名字/别名 → 变体(**保留**,见 §4) |
|
||||
| `name` | ~210 | 变体 → 规范名 |
|
||||
| `required_params` | ~145 | 变体 → 必填参数 |
|
||||
| `optional_params` | ~90 | 变体 → 可选参数 |
|
||||
|
||||
五张表必须同步维护,而 [code-volume-audit.md](code-volume-audit.md) 记录过
|
||||
`from_name` 接受 `http_get` 而 `name()` 只输出 `host_http_get` 的一类漂移。
|
||||
|
||||
## 2. 现在只有一张
|
||||
|
||||
```rust
|
||||
pub struct HostFnDef {
|
||||
pub id: u16,
|
||||
pub f: HostFn,
|
||||
pub name: &'static str,
|
||||
pub required: &'static [&'static str],
|
||||
pub optional: &'static [&'static str],
|
||||
}
|
||||
|
||||
pub const HOST_FN_TABLE: &[HostFnDef] = &[
|
||||
HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
|
||||
required: &["path"], optional: &[] },
|
||||
…
|
||||
];
|
||||
```
|
||||
|
||||
四个函数改为查表(`from_u16` 按 id 查,其余按判别值查);
|
||||
`call_host` 保留它那 202 个一行臂——**分派逻辑不动**,只把元数据集中。
|
||||
|
||||
## 3. 怎么保证没改坏
|
||||
|
||||
迁移采用**快照比对**:
|
||||
|
||||
1. 先在旧实现上导出全部 203 项的 `(id, name, required, optional)` 到 TSV
|
||||
2. 合并成表后,用同一段代码再导出一份
|
||||
3. `diff` 两份文件 → **完全一致**
|
||||
|
||||
```
|
||||
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
|
||||
IDENTICAL
|
||||
```
|
||||
|
||||
快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `every_assigned_id_round_trips` | 每个已分配 id → `as_u16()` 往返(id 空间稀疏是**退役 id**,不复用) |
|
||||
| `every_id_has_a_name_that_round_trips` | `name()` → `from_name()` 回到同一变体 |
|
||||
| `names_are_unique` | 规范名唯一 |
|
||||
| `required_and_optional_params_are_disjoint` | 必填/可选不重叠、`all_params` 无重复 |
|
||||
|
||||
## 4. 为什么 `from_name` 没有并进表
|
||||
|
||||
它是**别名注册表**(`http_get`、`get`、中文别名…),语义与"规范名"不同;
|
||||
并进表会让 `name()` 与 `from_name` 又变成一对映射。
|
||||
现在它保留原样,由上面的往返测试保证不与表漂移。
|
||||
|
||||
## 5. 收益
|
||||
|
||||
| 指标 | 前 | 后 |
|
||||
|------|----|----|
|
||||
| `dispatch.rs` | 2,052 行 | **1,648 行** |
|
||||
| `src/` 合计 | 53,040 | **52,668** |
|
||||
| 需同步维护的表 | 5 | **1** |
|
||||
|
||||
## 6. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release` | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 快照 diff | 203 项逐字节一致 |
|
||||
| 四个不变量测试 | 全绿 |
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/host/dispatch.rs` | 新增 `HostFnDef` / `HOST_FN_TABLE`(203 项);`from_u16` / `name` / `required_params` / `optional_params` 改为查表;删除对应四个 match |
|
||||
| `doc/design/change-hostfn-table.md` | 本文件 |
|
||||
@@ -0,0 +1,134 @@
|
||||
# 变更记录:M1 `()` 内调用语法(`)` 终止 / 逗号 / 嵌套 / 空格 callee)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M1([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/parse/expr.rs` |
|
||||
| 影响面 | **共享参数分词器**(所有调用都会经过) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
四件事,一句概括:**`(…)` 现在是一等调用外形**。
|
||||
|
||||
| # | 前 | 后 |
|
||||
|---|----|----|
|
||||
| 1 | `加(31)` 报 `unknown function 加(31` | ✅ 调用,返回 32 |
|
||||
| 2 | 末个位置实参会吞掉 `)` | `)` 是**参数终止符** |
|
||||
| 3 | 只支持空白分隔 | 支持 `,` / `,` 可选分隔 |
|
||||
| 4 | 嵌套 `加(加(1 2), 3)` 不可用 | ✅ 递归解析 |
|
||||
| 5 | `加一 号(31)` 不可用(D8) | ✅ **callee 可含空格** |
|
||||
|
||||
实测(1.5.2 本地构建,tree 与 bytecode 双后端结果一致):
|
||||
|
||||
```
|
||||
空格参=3 加(1 2)
|
||||
逗号=3 加(1, 2)
|
||||
嵌套=13 加(加(1 2), 10)
|
||||
带空格callee=32 加一 号(31) ← 缺陷 D8 的结构性解法
|
||||
库函数=x txt.str_trim(" x ")
|
||||
具名=3 加(a=1, b=2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现要点
|
||||
|
||||
### 2.1 参数扫描:深度感知 + `)` 终止
|
||||
|
||||
`split_first_token` 与 `find_next_arg_boundary` 改为**通用扫描器**:
|
||||
|
||||
- 跟踪 `()` `[]` `{}` 嵌套、`"…"` 字符串、`` `…` `` 反引号
|
||||
- **顶层** `)` / 空白(以及括号形里的 `,`)终止当前 token,且**不吞掉终止符**
|
||||
- 字符串内的逗号不受影响(`拼接("a,b", "c")` 仍是 2 个参数)
|
||||
|
||||
### 2.2 `try_paren_call`:callee = 第一个 `(` 之前的全部文本
|
||||
|
||||
```rust
|
||||
let Some(open) = s.find('(') else { return Ok(None) };
|
||||
let callee_tok = s[..open].trim(); // 允许空格
|
||||
```
|
||||
|
||||
**安全护栏**(否则会误判):
|
||||
|
||||
| callee 里出现 | 判定 |
|
||||
|--------------|------|
|
||||
| `=` | 不是括号调用(那是 `text=a(b)` 具名实参) |
|
||||
| `[` `]` `(` `)` `"` `'` | 不是括号调用(那是 `trim [stdout](…)` 方括号实参) |
|
||||
| 以 `[` `]` `"` `'` 开头 | 不是括号调用 |
|
||||
| 反引号 | **允许**(保留 `` `obj`.方法(…) `` 接收者写法) |
|
||||
|
||||
### 2.3 表达式级 postfix 调用
|
||||
|
||||
`parse_primary` 的裸词分支:**紧跟** `(` 时按调用解析。
|
||||
|
||||
```rust
|
||||
if self.allow_paren_call && self.rest().starts_with('(') { … }
|
||||
```
|
||||
|
||||
要求"紧跟"(不隔空格),使 `加 (1)` 仍是原来的"文本 + 括号"行为。
|
||||
|
||||
### 2.4 方括号形也允许空格 callee
|
||||
|
||||
`is_bracket_callee_inner` 不再拒绝空白:`[加一 号] 31` 可用。
|
||||
(仓库内可执行的方括号调用用量为 0,风险极低。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键设计决策:括号形 vs 空格形的参数**值**语义不同
|
||||
|
||||
这是本里程碑唯一有争议的点,必须写清。
|
||||
|
||||
| 形态 | 参数值 | 例子 |
|
||||
|------|--------|------|
|
||||
| **括号形** `f(…)` | 表达式(**允许** `name(args)` 调用) | `加(加(1 2), 3)` |
|
||||
| **空格形** `> f k=v` | 文本(**不允许**裸 `name(args)` 变成调用) | `source=print(2+2)` 仍是文本 |
|
||||
|
||||
**为什么必须区分**:`source=print(2+2)` 在 Marqdo 里历来是**文本**(未加引号的实参按文本处理)。
|
||||
若不区分,它会变成对 `print` 的调用,`foreign.run_lang` 直接报 `source must be text`
|
||||
—— 这正是本次回归测试抓到的 3 个失败。
|
||||
|
||||
实现:`Parser` 增加 `allow_paren_call` 字段;`parse_call_arg_value_mode(input, prefer_var, allow_call)`
|
||||
统一两种值解析(`allow_call=false` 即旧行为)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元 | 新增 11 个(单参/多参/逗号/具名/空格 callee/零参/库路径/嵌套/引号内逗号/旧写法不回归/方括号形) | ✅ |
|
||||
| 全量 | `cargo test --release` | **565 passed / 0 failed**(基线 554 + 11) |
|
||||
| 双后端 | tree 与 `--backend bytecode` 跑同一文档 | 输出一致 |
|
||||
| 端到端 | `marqdo run` 六个用例 | 输出符合预期 |
|
||||
|
||||
**TDD 过程**:先写 11 个测试 → 10 个失败(红灯确认)→ 实现 → 全绿。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带移除的死代码
|
||||
|
||||
`end_of_quoted_string`:新扫描器取代其唯一用途后变成 `never used`,删除(编译器警告清零)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界(本里程碑不做)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 逗号仅在括号形生效 | 空格形 `text=a,b` 的逗号仍是文本(兼容) |
|
||||
| `加 (1)`(空格后跟括号) | 不视为调用,保持旧行为 |
|
||||
| 遮蔽语法 `[描述](…)` | M2 才引入,本里程碑不解析 |
|
||||
| 位置实参顺序脆弱性 | 与叙述顺序绑定,M7/M8 再处理(诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/parse/expr.rs` | 参数扫描器重写(`)`/逗号/嵌套);新增 `try_paren_call` + `split_callee` 抽取;表达式级 postfix 调用;`Parser.allow_paren_call`;`parse_call_arg_value_mode` 统一两种值语义;方括号 callee 允许空格;删除 `end_of_quoted_string` |
|
||||
| `doc/design/change-m1-paren-call.md` | 本文件 |
|
||||
@@ -0,0 +1,73 @@
|
||||
# 变更记录:M10 工程化落点(README + agent 提示词)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M10([occlusion-description-and-search.md](occlusion-description-and-search.md) §5) |
|
||||
| 改动文件 | `ext/ai/agent.mq.md`(README 一节已在文档阶段落地) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 改了什么
|
||||
|
||||
把「接不了就申报,别假装完成」写进 **agent 的默认提示词**,两处:
|
||||
|
||||
### 1.1 `how-to-act` 协议段(每轮都会带)
|
||||
|
||||
```
|
||||
Call ONLY names listed under --- tools --- (whitelist). …
|
||||
If a capability cannot truly be wired, do NOT fake it silently and never claim it works:
|
||||
write an occlusion with an explicit status, e.g. [按关键词检索,接口未接,待开发](None).
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.search.
|
||||
Tools run via Marqdo subtask (spawn fn / wait).
|
||||
```
|
||||
|
||||
### 1.2 默认 standing(`p`)
|
||||
|
||||
```
|
||||
You are a Marqdo agent. Code is documentation: … not a hidden system prompt.
|
||||
When you cannot wire a capability, declare it in the description (待开发 / 模拟)
|
||||
instead of faking success.
|
||||
```
|
||||
|
||||
**为什么这两处**:standing 定基调(每次对话开头),how-to-act 定动作(每轮)。
|
||||
只写 standing 容易被长上下文冲淡;只写 how-to-act 又缺"为什么要申报"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计要点
|
||||
|
||||
| 要点 | 说明 |
|
||||
|------|------|
|
||||
| 给**范式**而不是规则 | 直接给出可抄的 `[按关键词检索,接口未接,待开发](None)`,模型不必发明措辞 |
|
||||
| 给**返回值**要求 | "必须写清返回什么(None 也行)"——对应 `label.empty_payload` 的 warning |
|
||||
| 给**自查**动作 | `labels.search` 让模型收尾时能自己盘点,而不是靠人提醒 |
|
||||
| 用**英文**写 | 与既有 standing / 协议段语言一致(模型对英文指令更稳) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `marqdo check ext/ai/agent.mq.md`(occlusion 模式) | `contract check OK` |
|
||||
| 提示词文本落入模块 | `grep` 命中 2 处(standing 与 how-to-act 各 1) |
|
||||
| 全量回归 | 587 passed / 0 failed(与 M9 相同,本改动不动逻辑) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
- 提示词是**建议**,不是门禁;违反不会被拒绝,但会在描述/诊断里暴露。
|
||||
- `labels.search` 需要 M7 翻转默认后对 classic 文档才有意义;提示词先就位。
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `ext/ai/agent.mq.md` | how-to-act 协议段与默认 standing 各追加申报约定 |
|
||||
| `doc/design/change-m10-engineering-habits.md` | 本文件 |
|
||||
@@ -0,0 +1,126 @@
|
||||
# 变更记录:M2 遮蔽语法 `[描述](实现)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(模式开关默认仍是 classic) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增语法
|
||||
|
||||
```markdown
|
||||
[描述](实现)
|
||||
```
|
||||
|
||||
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
|
||||
- `()` = **实现**(唯一执行体)
|
||||
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
|
||||
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
|
||||
|
||||
实测(`MARQDO_MARKUP=occlusion`):
|
||||
|
||||
```
|
||||
a=2 [加一之后的值](1 + 1)
|
||||
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
|
||||
c=True [某某功能开发中]() ← 空载荷 → None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**模式开关,暂不切换语义**
|
||||
|
||||
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
|
||||
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
|
||||
|
||||
因此 M2 只**实现能力**,不动默认:
|
||||
|
||||
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|
||||
|------|-----------------|-----------------|
|
||||
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
|
||||
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
|
||||
|
||||
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
|
||||
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现要点
|
||||
|
||||
### 3.1 AST
|
||||
|
||||
```rust
|
||||
Occluded {
|
||||
label: String,
|
||||
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析
|
||||
|
||||
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
|
||||
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
|
||||
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
|
||||
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
|
||||
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
|
||||
|
||||
### 3.3 求值(两个后端一致)
|
||||
|
||||
| 位置 | 处理 |
|
||||
|------|------|
|
||||
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
|
||||
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
|
||||
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
|
||||
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
|
||||
|
||||
**描述永不参与求值**——守住铁律 1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
|
||||
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
|
||||
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
|
||||
| 双后端 | tree 与 `--backend bytecode` | 一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带重构
|
||||
|
||||
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
|
||||
(全局只由 CLI 入口设置一次)。
|
||||
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述不参与作用域/类型 | 写什么都不影响执行 |
|
||||
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
|
||||
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
|
||||
| 跨行描述 | 不支持(v1) |
|
||||
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
|
||||
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
|
||||
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
|
||||
| `src/interp.rs` | 求值 + 读引用收集 |
|
||||
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
|
||||
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
|
||||
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
|
||||
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
|
||||
| `doc/design/change-m2-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,91 @@
|
||||
# 变更记录:M2.5 遮蔽标签诊断(`label.missing` / `label.empty_payload`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2.5([occlusion-syntax.md](occlusion-syntax.md) §13,诊断规范 §10) |
|
||||
| 改动文件 | **新增 `src/label.rs`** · `src/check.rs` · `src/lib.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check`(新增两类诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两条诊断
|
||||
|
||||
| code | 级别 | 触发 | 文案要点 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | **error** | `[](实现)` 描述为空 | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.empty_payload` | **warning** | `[描述]()` 载荷为空 | 「这里没有可执行内容」,建议写 `(None)` 或补实现 |
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
|
||||
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
|
||||
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
|
||||
contract check: 1 条诊断(0 error) # exit 0(warning 不影响退出码)
|
||||
```
|
||||
|
||||
JSON 出口(自动继承既有 schema,含 `doc_quote`):
|
||||
|
||||
```json
|
||||
{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
|
||||
"doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现
|
||||
|
||||
### 2.1 新增 `src/label.rs`
|
||||
|
||||
- `OcclusionSite { label, has_payload, line, unit }`
|
||||
- `collect(module)`:遍历函数体与嵌套语句/表达式,收集所有遮蔽点
|
||||
(描述只读,**不产生任何读引用**)
|
||||
- `check(module, path)`:产出上面两条诊断
|
||||
|
||||
### 2.2 接入 `check_module`
|
||||
|
||||
```rust
|
||||
walk(module, &module.functions, path, &known, &mut out);
|
||||
out.extend(crate::label::check(module, path)); // M2.5
|
||||
```
|
||||
|
||||
设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加,
|
||||
`check` 只做一行汇总。
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3 新) | 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **578 passed / 0 failed**(M2 后 575 + 3) |
|
||||
|
||||
反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述内容不校验 | 写什么都可以;M4 才校验反引号引用 |
|
||||
| 空载荷仅在 occlusion 模式可能出现 | classic 模式下 `()` 空是语法错 |
|
||||
| warning 不影响退出码 | 与既有 `Severity` 语义一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | **新增**:遮蔽点收集 + 两类诊断 |
|
||||
| `src/lib.rs` | `pub mod label;` |
|
||||
| `src/check.rs` | `check_module` 追加 label 诊断 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{empty-label,empty-payload,clean}.mq.md` | 新增 3 个集成测试与样例 |
|
||||
| `doc/design/change-m25-label-diagnostics.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M3 `access` 与遮蔽循环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) |
|
||||
| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 |
|
||||
|
||||
---
|
||||
|
||||
## 1. `access(集合, 键)`
|
||||
|
||||
旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。
|
||||
纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式:
|
||||
|
||||
```markdown
|
||||
**a = [取表项](access(`表`, "键"))**
|
||||
**b = [取列表第二项](access(`列`, 2))**
|
||||
```
|
||||
|
||||
- 别名:`取` / `取值` / `access`
|
||||
- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None)
|
||||
- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移
|
||||
|
||||
实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`,
|
||||
**不新增平行实现**(避免两套索引语义)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 遮蔽循环
|
||||
|
||||
```markdown
|
||||
- [篮子里的每个果子](遍历 `列` 为 `果`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach)
|
||||
- 接受 `遍历`/`for` 与 `为`/`as`/`in`
|
||||
- 描述存入 `Stmt::ForEach.label`(`Option<String>`),供 M8 渲染/诊断使用
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
a=值
|
||||
b=二
|
||||
果子=一
|
||||
果子=二
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么先做 M3 再做 M7
|
||||
|
||||
迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。
|
||||
先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ |
|
||||
| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 |
|
||||
| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 |
|
||||
| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) |
|
||||
| `src/ast.rs` | `Stmt::ForEach.label: Option<String>` |
|
||||
| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 |
|
||||
| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m3-access-and-loop.md` | 本文件 |
|
||||
@@ -0,0 +1,84 @@
|
||||
# 变更记录:M4 L1 引用一致性(`label.ref_dangling`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) |
|
||||
| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` |
|
||||
| 影响面 | `marqdo check`(新增一条 error) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> 描述里用反引号写出的名字 = **断言**:它必须能解析
|
||||
> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。
|
||||
|
||||
```markdown
|
||||
**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬)
|
||||
**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到
|
||||
**c = [取长度](len("abc"))** # ✅ 内置函数
|
||||
**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么只认反引号(可证伪原则)
|
||||
|
||||
| 写法 | 是否检查 | 原因 |
|
||||
|------|---------|------|
|
||||
| `` `税率` `` | ✅ | 显式引用,可证伪 |
|
||||
| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 |
|
||||
|
||||
代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**,
|
||||
同时反向抑制"为凑数写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现
|
||||
|
||||
| 环节 | 做法 |
|
||||
|------|------|
|
||||
| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 |
|
||||
| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` |
|
||||
| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 |
|
||||
|
||||
`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ |
|
||||
| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界与后续
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 |
|
||||
| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 |
|
||||
| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m4-label-refs.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) |
|
||||
| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到
|
||||
> (或能解析到模块/内置)。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额: ← 描述
|
||||
|
||||
> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率`
|
||||
```
|
||||
|
||||
```
|
||||
impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它
|
||||
```
|
||||
|
||||
段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、
|
||||
标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**默认关闭**
|
||||
|
||||
这不是洁癖,是实测结论:
|
||||
|
||||
| 阶段 | lib + ext/ai 上的警告数 |
|
||||
|------|------------------------|
|
||||
| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) |
|
||||
| 加"实体名形状"过滤 | 2 条 |
|
||||
| **再加默认关闭** | **0 条** |
|
||||
|
||||
理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多;
|
||||
机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。
|
||||
所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实体名过滤(降低误报)
|
||||
|
||||
反引号内容必须**像实体名**才算断言:
|
||||
|
||||
```rust
|
||||
首字符:字母 / `_` / 非 ASCII(不能是数字)
|
||||
其余:字母数字 / `_` / `.` / 非 ASCII 且非空白
|
||||
```
|
||||
|
||||
于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用法
|
||||
|
||||
```bash
|
||||
marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音)
|
||||
marqdo check 文件.mq.md --implicit-labels # 开启
|
||||
```
|
||||
|
||||
MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ |
|
||||
| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) |
|
||||
|
||||
**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent`
|
||||
两条都在证明"不乱响"。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 |
|
||||
| 只认反引号 + 实体形状 | 普通散文永远不参与 |
|
||||
| 不查 payload 语义 | 只查"提到的实体是否被用到" |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` |
|
||||
| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) |
|
||||
| `src/main.rs` | `check --implicit-labels` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 |
|
||||
| `doc/design/change-m5-implicit-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,109 @@
|
||||
# 变更记录:M6 T1 会话内陈旧检测 + 会话末汇总
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M6([t1-session-staleness.md](t1-session-staleness.md) · [staleness-providers.md](staleness-providers.md) T1) |
|
||||
| 改动文件 | `src/label.rs` · `src/mlsp.rs` · `src/view/mod.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | MLSP `repair_apply` 新增可选字段;新增 `session.summary` 方法 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制
|
||||
|
||||
`repair_apply` 内部同一作用域里同时有 `source`(改前)与 `new_source`(改后),
|
||||
所以「描述是否还成立」可以**纯内存**判定:
|
||||
|
||||
```
|
||||
stale ⟺ 标签文本未变 ∧ payload 指纹变了
|
||||
```
|
||||
|
||||
配对按 `(标签文本, 出现序号)`,因此**移动代码不会误报**。
|
||||
|
||||
请求:
|
||||
|
||||
```json
|
||||
{"method":"repair_apply","params":{
|
||||
"source":"…","ranges":[[3,3]],
|
||||
"edits":[{"op":"replace","line":3,"text":"**a = [按税率算总价](100 * 0.2)**"}],
|
||||
"check_labels":true}}
|
||||
```
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"result":{
|
||||
"source":"…","edits_applied":1,
|
||||
"labels":{"newly_seen":1,"stale":[
|
||||
{"label":"按税率算总价","line":3,
|
||||
"code_past":"100 * 0.1","code_now":"100 * 0.2"}]}}}
|
||||
```
|
||||
|
||||
**同一份 `source` / `new_source` 就是"前一状态"**——不需要 git、不需要台账、
|
||||
不需要沙箱里的 exec 权限。这是"agent 回路不需要 VCS"的落地。
|
||||
|
||||
---
|
||||
|
||||
## 2. 会话末汇总(你要求做)
|
||||
|
||||
`session.summary` 返回并**重置**计数:
|
||||
|
||||
```json
|
||||
{"ok":true,"labels_stale_seen":1,"labels_fixed":0,
|
||||
"labels_outstanding":1,"items":["按税率算总价"]}
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `labels_stale_seen` | 本次会话累计发现过多少条(去重按标签) |
|
||||
| `labels_fixed` | 曾经 outstanding、现在不再 stale 的条数 |
|
||||
| `labels_outstanding` | 仍未处理 |
|
||||
| `items` | 未处理的标签文本(只给文本,不重复诊断细节) |
|
||||
|
||||
设计:客户端在收尾时调用一次即可闭合;**不主动打屏**,不污染协议。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键取舍
|
||||
|
||||
| 取舍 | 理由 |
|
||||
|------|------|
|
||||
| `check_labels` 默认 **false** | 零开销、零噪音;agent 框架在修复回路里显式打开 |
|
||||
| 标签变了 → **不报** | 作者改描述本身就是"已复核"的信号 |
|
||||
| 新标签 → 不报 | 无历史可比 |
|
||||
| 指纹用 `Debug` | **只需进程内一致**;跨版本稳定指纹是 T2/T3 的事 |
|
||||
| payload 渲染用 `view::expr_display` | 让 `code_past/code_now` 是人能读的表面语法,而非 AST 调试串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 只改 payload → `stale` 含 `code_past`/`code_now`;同时改标签 → `stale: []`;`session.summary` 计数正确 | ✅ |
|
||||
| 全量 | `cargo test --release` | **590 passed / 0 failed**(M10 后 587 + 3) |
|
||||
|
||||
**反向验证**:`t1_silent_when_label_also_changes` 证明"改描述即复核"不会误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只看本次编辑 | 跨会话漂移是 T2/T3 的职责(可选 provider) |
|
||||
| 解析失败则跳过 | 修复后的源码可能语法错误,此时不评测标签,交给 `validate` |
|
||||
| 会话状态是进程级 | 一条 MLSP 连接(一个进程)即一个会话;`session.summary` 后清零 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `StaleItem` · `payload_fingerprint` · `compare` · `SessionSummary`(含 `record`)· `OcclusionSite.payload_fp/payload_src` |
|
||||
| `src/mlsp.rs` | `repair_apply` 的 `check_labels`;`session.summary`;进程级 `SESSION` |
|
||||
| `src/view/mod.rs` | `pub use render::expr_display`(供诊断渲染 payload) |
|
||||
| `tests/occlusion.rs` | 3 个 T1 集成测试 |
|
||||
| `doc/design/change-m6-t1-session.md` | 本文件 |
|
||||
@@ -0,0 +1,127 @@
|
||||
# 变更记录:M7 迁移与版本门(per-file 标记 + `migrate labels` + 全仓迁移)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M7([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | **新增 `src/migrate.rs`** · `src/load.rs` · `src/parse/mod.rs`(expr) · `src/host/dispatch.rs` · **80 个语料文件** · 测试 |
|
||||
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原计划的问题:同形换义
|
||||
|
||||
原设计想"翻转默认 + 对旧形硬报错"。但 `[键](集合)` 与 `[描述](实现)` **外形完全相同**:
|
||||
|
||||
- 翻转默认 → 506 处取元**静默变成**"遮蔽整个集合",正是文档点名的最坏变更
|
||||
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
|
||||
|
||||
**结论:模式不能全局翻转,必须按文件声明。**
|
||||
|
||||
## 2. 新方案:per-file `markup:`
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
```
|
||||
|
||||
| 文件 | 解析模式 | `[a](b)` 的含义 |
|
||||
|------|---------|----------------|
|
||||
| 无 `markup:` | classic(进程默认) | 取元 |
|
||||
| `markup: occlusion` | 纯度 | 遮蔽 |
|
||||
|
||||
实现:`load.rs` 先读 frontmatter 取出模式,用 `parse::expr::with_markup(m, …)`
|
||||
(线程局部覆盖,压栈/出栈)包住解析。**同一进程里可以同时加载两种模式的文件**
|
||||
(imports!),且 `MARQDO_MARKUP=occlusion` 仍可作为进程默认。
|
||||
|
||||
好处:迁移是**逐文件、可增量、可回滚**的;不存在"半迁移的静默错义"。
|
||||
|
||||
## 3. 迁移工具 `marqdo migrate labels`
|
||||
|
||||
```bash
|
||||
marqdo migrate labels . # 干跑:列出将改什么
|
||||
marqdo migrate labels . --write # 实际写入
|
||||
marqdo migrate labels . --json # 机器可读
|
||||
```
|
||||
|
||||
### 3.1 改写规则
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `[键](集合)` | `[键](access(集合, "键"))` |
|
||||
| `` [`名`](集合) `` | `` [名](access(集合, `名`)) `` |
|
||||
| `- [项](集合)` | `- [项](遍历 集合 为 项)` |
|
||||
|
||||
`access` 是新增宿主函数(`host_access`,id 212),语义与旧取元**逐字一致**
|
||||
(Map 按键 / List 1-based / 缺键 `missing map key`)。它进 `HostFn` 是有意的:
|
||||
**两个后端共用同一实现**,不再有特例分支。
|
||||
|
||||
### 3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
|
||||
|
||||
1. 原文件按 classic 解析,得到 AST-A
|
||||
2. 文本改写后,按 occlusion 解析,得到 AST-B
|
||||
3. **反归一化** B:把"标签与键同名 + payload 为 `access(x, k)`"的遮蔽还原成 `Index`
|
||||
4. 比较 `Debug(A)` 与 `Debug(反归一化(B))`(抹掉行号,因为插入了 marker 行)
|
||||
5. 只有相等才写入;否则**原文件一字不动**并报告 `equivalence check failed`
|
||||
|
||||
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
|
||||
链式索引、`[问候] (…)` 与遮蔽混淆),每一类都是**先被拦下、再修工具**,没有污染文件。
|
||||
|
||||
### 3.3 只改代码行
|
||||
|
||||
用词法层的 `LineKind::Code` 限定范围;表格行只改 `**…**` 单元格
|
||||
(散文里的 markdown 链接 `[docs](https://…)` 必须原样保留)。
|
||||
|
||||
### 3.4 由内向外
|
||||
|
||||
链式索引 `[content]([1]([messages](req)))` 必须**最内层先改**,
|
||||
否则外层改写会让内层的位置失效;已迁移的 `[k](access(…))` 有守卫,不会二次改写。
|
||||
|
||||
## 4. 全仓迁移结果
|
||||
|
||||
```
|
||||
migrate labels: 256 index, 23 loop, 80 file written
|
||||
```
|
||||
|
||||
- 覆盖 `lib/ ext/ examples/ public/ cli/ tests/`
|
||||
- **0 文件被等价性检查拒绝**
|
||||
- 迁移后 `cargo test --release` → **604 passed / 0 failed**
|
||||
- 再跑一次迁移 → **幂等**(只剩刻意保留的 classic 测试样例)
|
||||
|
||||
## 5. 顺带修的两处真实语义缺陷
|
||||
|
||||
| 缺陷 | 现象 | 修法 |
|
||||
|------|------|------|
|
||||
| payload 继承外层"文本模式" | `f text=[k](access(c,k))` 里 `access(...)` 不被当调用 → 退化成插值文本 | `()` 内**永远**允许 `callee(args)`(`parse_occluded` 临时置位) |
|
||||
| 遮蔽形状判定过宽 | `[问候] ([格式化] "Bo")` 被误判为遮蔽 | 要求 `]` 后**紧跟** `(`;否则落回方括号调用 |
|
||||
|
||||
## 6. 版本门
|
||||
|
||||
- 旧写法**不再**被硬报错——因为无法与遮蔽区分;真正的门是 **per-file 声明**:
|
||||
没写 `markup: occlusion` 的文件按 classic 解析,行为不变。
|
||||
- 需要"禁止新写旧形"的仓库可用 `migrate labels` 干跑做 CI 门禁(有改动即失败)。
|
||||
|
||||
## 7. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
|
||||
| 集成(3) | 干跑不写盘;写入后**运行输出不变**且幂等;等价失败则文件不动 | ✅ |
|
||||
| 全量 | `cargo test --release` | **604 passed / 0 failed**(M3 后 595 + 9) |
|
||||
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
|
||||
|
||||
## 8. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/migrate.rs` | **新增**:改写器、等价性证明、`migrate_file` / `migrate_path` |
|
||||
| `src/load.rs` | `frontmatter_markup` + `with_markup` 包裹两处 `parse_source` |
|
||||
| `src/parse/expr.rs` | `with_markup` 线程局部覆盖;`()` 内强制允许调用;`occlusion_shape_ahead` 严格判定 |
|
||||
| `src/host/dispatch.rs` | `HostFn::Access`(enum / from_u16 212 / from_name / name / required_params / call_host) |
|
||||
| `src/main.rs` | `migrate labels` 子命令 |
|
||||
| `src/interp.rs` | 移除 access 特例(改用 HostFn,单一实现) |
|
||||
| 80 个语料文件 | 索引与循环迁移 + `markup: occlusion` 标记 |
|
||||
| `tests/migrate.rs` + `src/migrate.rs` 单测 | 9 个测试 |
|
||||
| `doc/design/change-m7-migration.md` | 本文件 |
|
||||
@@ -0,0 +1,81 @@
|
||||
# 变更记录:M8 债务棘轮与呈现
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M8([warning-fatigue-control.md](warning-fatigue-control.md) §4 棘轮 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/main.rs` · `tests/ratchet.rs` |
|
||||
| 影响面 | `labels` 新增 `--baseline` / `--fail-on-increase` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 棘轮规则
|
||||
|
||||
```bash
|
||||
# CI:未完成项只许减少,不许增加
|
||||
marqdo labels . --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
| 情形 | 行为 | 退出码 |
|
||||
|------|------|--------|
|
||||
| 台账不存在 | **建立**(写入当前计数),提示 `已建立 N` | 0 |
|
||||
| 当前 > 台账 | 失败,提示 `未完成项增加了 K` | **1** |
|
||||
| 当前 ≤ 台账 | 通过;若减少则**收紧**台账(`N → M`) | 0 |
|
||||
|
||||
**为什么"减少即收紧"**:否则债务可以先降后升,棘轮形同虚设。
|
||||
收紧后台账记住新的低水位,回退到旧数量同样会失败(测试第 4 步验证)。
|
||||
|
||||
台账格式:
|
||||
|
||||
```json
|
||||
{"count": 1, "words": ["待开发", "未开发", "…"]}
|
||||
```
|
||||
|
||||
记录词集是为了让"口径变了"可被审计——换词集时会看到 `words` 变化。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么用棘轮而不是硬门禁
|
||||
|
||||
| 方案 | 老债 | 新债 | 结论 |
|
||||
|------|------|------|------|
|
||||
| 硬门禁(必须为 0) | 阻塞一切 | 拦住 | 存量债立刻红一片,逼人关检查 |
|
||||
| **棘轮(只拦增量)** | 不阻塞 | 拦住 | ✅ 债务可见且不恶化 |
|
||||
| 无门禁 | 不阻塞 | 不拦 | 债务无声增长 |
|
||||
|
||||
这与 [warning-fatigue-control.md](warning-fatigue-control.md) 的结论一致:
|
||||
**老账不追、新账必拦**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 呈现(已具备)
|
||||
|
||||
| 面 | 表现 |
|
||||
|----|------|
|
||||
| `expr_display` / `view` | 遮蔽渲染为 `[描述](实现)`,桩渲染为 `[描述]()`,实测 `view output` 页面含 `access(` |
|
||||
| `labels` | 人类行 `文件:行 [函数] 描述 ← 命中词`;`--json` 一个数组 |
|
||||
| `check` | `label.*` 三类诊断(missing / empty_payload / ref_dangling) |
|
||||
| MLSP | `labels.search` · `session.summary` |
|
||||
|
||||
**没有做桩徽章**:桩已经是 `[描述]()` 这个显眼形状,再加装饰是噪音;
|
||||
需要计数时用 `labels --count`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(1 个四步用例) | 建账 → 增加失败 → 减少收紧 → 回退再次失败 | ✅ |
|
||||
| 全量 | `cargo test --release` | **605 passed / 0 failed**(M7 后 604 + 1) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/main.rs` | `labels --baseline` / `--fail-on-increase`;建账/收紧/违约逻辑 |
|
||||
| `tests/ratchet.rs` | 四步棘轮用例 |
|
||||
| `doc/design/change-m8-ratchet.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 |
|
||||
| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` |
|
||||
| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 先修回归:view 用错解析模式
|
||||
|
||||
`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件,
|
||||
而 per-file `markup:` 是在 `load` 层生效的(M7)。结果:
|
||||
|
||||
```
|
||||
<div class="structure"><div class="err">parse/load error: expected ')' after link-index collection</div></div>
|
||||
```
|
||||
|
||||
任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。
|
||||
用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。
|
||||
|
||||
**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`,
|
||||
用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。
|
||||
|
||||
## 2. 遮蔽呈现
|
||||
|
||||
### 2.1 浏览视图(`document.rs`,`/file`)
|
||||
|
||||
```html
|
||||
<div class="doc-line doc-occl" data-line="81">
|
||||
<span class="occl-pre">留存 =</span> <!-- 变量名:灰、等宽 -->
|
||||
<span class="occl-label">客户留存率,模拟数据</span> <!-- 描述:正文 -->
|
||||
<code class="occl-code">0.42</code> <!-- 实现:代码片 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
- 空载荷 → `<span class="occl-stub">桩</span>`(琥珀色徽章,title 说明"未接通或待补返回值")
|
||||
- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致)
|
||||
- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画
|
||||
|
||||
### 2.2 卡片视图(`render.rs`,`/debug`)
|
||||
|
||||
按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句),
|
||||
渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。
|
||||
|
||||
### 2.3 样式(`html.rs`)
|
||||
|
||||
```css
|
||||
.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; }
|
||||
.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); }
|
||||
.occl-label { color:var(--ink); }
|
||||
.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line);
|
||||
border-radius:6px; padding:.02rem .38rem; }
|
||||
.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; }
|
||||
```
|
||||
|
||||
刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) |
|
||||
| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 |
|
||||
| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` |
|
||||
| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 |
|
||||
| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) |
|
||||
|
||||
## 4. 未能做到的:截图
|
||||
|
||||
本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在),
|
||||
`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com`
|
||||
TLS 断连,两次重试均失败)。所以无法自动截图比对,改为:
|
||||
DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) |
|
||||
| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` |
|
||||
| `src/view/debug_page.rs` | 1 处同上 |
|
||||
| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 |
|
||||
| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 |
|
||||
| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 |
|
||||
| `doc/design/change-m8-view-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 变更记录:M9 两级词表检索(`labels` CLI + MLSP `labels.search`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M9([occlusion-description-and-search.md](occlusion-description-and-search.md) §3 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/label.rs` · `src/main.rs` · `src/mlsp.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增 CLI 子命令与 MLSP 方法(**不改语法**) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两级词表
|
||||
|
||||
| 级 | 在哪 | 作用 |
|
||||
|----|------|------|
|
||||
| **第一级:内置** | `label::BUILTIN_GROUPS`(数据常量) | 默认查询 + LLM 范例 + 跨项目可比 |
|
||||
| **第二级:参数** | `--grep` / `grep` | 替换或并集,项目自己的说法照样能搜 |
|
||||
|
||||
内置六组:`未完成`(待开发/未开发/开发中/未实现/待实现/未接/接口未接/TODO)、
|
||||
`假数据`(模拟/假数据/桩/占位/stub/mock)、`示例`、`实验`、`废弃`、`待校验`。
|
||||
`pending` = `未完成 ∪ 假数据`。
|
||||
|
||||
**词表是数据不是语法**:扩充它不改任何解析规则。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo labels . # 默认:pending 口径(内置两组)
|
||||
marqdo labels . --grep "联调" # 替换为自定义词
|
||||
marqdo labels . --grep "联调" --also-builtin # 自定义 ∪ 内置
|
||||
marqdo labels . --group 示例,实验 # 选内置组
|
||||
marqdo labels . --count # 只给数字(CI/棘轮用)
|
||||
marqdo labels . --json # 一个 JSON 数组
|
||||
```
|
||||
|
||||
输出(人类):
|
||||
|
||||
```
|
||||
a.mq.md:3 [main] 按关键词检索,接口未接,待开发 ← 待开发,未接,接口未接
|
||||
a.mq.md:4 [main] 客户留存率,模拟 ← 模拟
|
||||
label search: 2 命中(1 文件,词=[…])
|
||||
```
|
||||
|
||||
`--json`:
|
||||
|
||||
```json
|
||||
[{"file":"a.mq.md","line":3,"unit":"main","label":"…","words":["待开发"],"has_payload":true}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. MLSP
|
||||
|
||||
```json
|
||||
{"id":1,"method":"labels.search",
|
||||
"params":{"source":"…"|"path":"…","grep":["联调"],"also_builtin":true}}
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```json
|
||||
{"ok":true,"words":[…],"count":2,"hits":[{"line":3,"unit":"main","label":"…",
|
||||
"words":["待开发"],"has_payload":true}]}
|
||||
```
|
||||
|
||||
语义与 CLI 完全一致(同一份 `label::search`)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 检索语义(v1)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 匹配 | **子串**(CJK 无词边界,子串最稳) |
|
||||
| 多词 | OR |
|
||||
| 大小写 | 英文不敏感(`TODO`/`todo` 等价) |
|
||||
| 误判 | 必然存在(`[不属于待开发范围]` 会命中)——只影响计数,输出带描述原文可人工判断 |
|
||||
|
||||
不做否定语法;留作 v1.1 可选项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(4) | pending 计数=2;`--grep` 替换=1;`--also-builtin` 并集=3;MLSP `labels.search` 返回 hits | ✅ |
|
||||
| 全量 | `cargo test --release` | **587 passed / 0 failed**(M4 后 583 + 4) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只在 occlusion 模式产生命中 | classic 模式下没有 `Expr::Occluded`;M7 翻转默认后自然可用 |
|
||||
| 解析失败的文件跳过 | 那是 `check` 的职责,检索不应因一个坏文件整体失败 |
|
||||
| 不做棘轮 | `--baseline` / `--fail-on-increase` 留给 M8(门禁) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `WordGroup` / `BUILTIN_GROUPS` / `PENDING_GROUPS` / `group_words` / `parse_words` / `matched_words` / `Hit` / `search` |
|
||||
| `src/main.rs` | `labels` 子命令 + `collect_mq_files` 递归扫描 |
|
||||
| `src/mlsp.rs` | `labels.search` 方法 + 分发 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/labels.mq.md` | 4 个集成测试 |
|
||||
| `doc/design/change-m9-label-search.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
|
||||
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
|
||||
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
|
||||
|
||||
| 复制的内容 | 说明 |
|
||||
|-----------|------|
|
||||
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
|
||||
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
|
||||
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
|
||||
| `register` + `#[no_mangle]` 四导出 | 样板 |
|
||||
|
||||
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
|
||||
|
||||
## 2. 方案
|
||||
|
||||
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
|
||||
|
||||
```rust
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
|
||||
]);
|
||||
```
|
||||
|
||||
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
|
||||
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
|
||||
|
||||
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
|
||||
|
||||
## 3. 安全措施:注册项逐一核对
|
||||
|
||||
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
|
||||
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
|
||||
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
|
||||
|
||||
补救:正则允许 `::`,并把新旧两张表逐项比对:
|
||||
|
||||
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|
||||
|------|------------|--------|------|
|
||||
| agent | 63 | 63 | **0** |
|
||||
| quantum | 41 | 41 | 0 |
|
||||
| linalg | 31 | 31 | 0 |
|
||||
| llm | 2 | 2 | 0 |
|
||||
| demo | 2 | 2 | 0 |
|
||||
|
||||
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
|
||||
|
||||
另外两次由"编译通过但语义已变"暴露的问题:
|
||||
|
||||
| 问题 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
|
||||
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
|
||||
|
||||
## 4. 收益
|
||||
|
||||
| 插件 | 迁移前 | 迁移后 | 变化 |
|
||||
|------|--------|--------|------|
|
||||
| agent | 1,237 | 929 | −308 |
|
||||
| quantum | 1,045 | 835 | −210 |
|
||||
| linalg | 688 | 524 | −164 |
|
||||
| llm | 405 | 278 | −127 |
|
||||
| demo | 170 | 73 | −97 |
|
||||
| 新增 SDK | — | 232 | +232 |
|
||||
|
||||
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release`(含 5 个插件) | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
|
||||
| 注册项三元组比对 | 5 个插件全部 0 差异 |
|
||||
|
||||
## 6. 边界
|
||||
|
||||
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
|
||||
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
|
||||
- 后续新增插件只需依赖 SDK + 一行宏调用。
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
|
||||
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
|
||||
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
|
||||
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
|
||||
| `doc/design/change-plugin-sdk.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 代码体量审计:53k 行里哪些是特性、哪些是冗余
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **实施记录**(精简依据与进度) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 结论 | 冗余已清 ~14.5k 行;**剩余体量主要是特性面**,不是废弃物 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前账目
|
||||
|
||||
| 部分 | 行数 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/` | **52,668** | 其中约 **5,200** 是内联测试(`#[cfg(test)]`) |
|
||||
| `plugins/` + `crates/` | **14,700** | 5 个 ABI 插件(含共享 SDK)+ wasm crate |
|
||||
| 合计 Rust | **67,368** | |
|
||||
|
||||
最大的 10 个文件:
|
||||
|
||||
| 行数 | 文件 | 性质 |
|
||||
|------|------|------|
|
||||
| 4,451 | `src/view/html.rs` | 3,861 行是 CSS/HTML 字符串(页面皮肤) |
|
||||
| 2,691 | `src/parse/mod.rs` | 解析器主体 + 412 行内联测试 |
|
||||
| 2,194 | `src/parse/expr.rs` | 表达式解析 + 465 行内联测试 |
|
||||
| 2,063 | `src/host/foreign_doc.rs` | 外部语言内核(python/node 文档执行) |
|
||||
| 1,648 | `src/host/dispatch.rs` | 202 个宿主函数的元数据表(已合一) |
|
||||
| 1,968 | `src/host/foreign.rs` | 外部进程/会话管理 |
|
||||
| 1,925 | `src/interp.rs` | 树遍历求值器 |
|
||||
| 1,913 | `src/view/render.rs` | 渲染 |
|
||||
| 1,309 | `src/formula/mod.rs` | `$$…$$` 公式求值 |
|
||||
| 1,168 | `src/view/annot.rs` | 注解/映射 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 已清除的冗余(14.5k 行)
|
||||
|
||||
| # | 项 | 行数 | 提交 |
|
||||
|---|----|------|------|
|
||||
| 1 | `plugins/web-rust-archive/`(31 文件,非 workspace 成员、默认不构建、被 Go `libweb` 取代) | **14,235** | `13012ca` |
|
||||
| 2 | `as_text` × 18 份复制(两种措辞)→ 一个 `host::as_text` | ~100 | `8b0ea9e` |
|
||||
| 3 | `catalog.rs` 的 4 个助手(与 `knowledge::util` 逐字相同) | ~70 | `8b0ea9e` |
|
||||
| 4 | `view` 路由 34 臂 → 2 张表(`handle` / `handle_debug`) | 99 | `8b0ea9e` |
|
||||
| 5 | 无调用点死代码 ×5(`parse_italic_assign` 等) | ~50 | `a14a6e2` |
|
||||
| 6 | 转义重复:URL 编码器 2 份、`escape_js_string` 2 份(debug 副本漏 U+2028/2029) | ~40 | `9324032` |
|
||||
| 7 | AST 遍历器 3 份 → `ast::walk_stmts` / `ast::stmt_line` | ~50 | `deac53d` |
|
||||
|
||||
**顺带修出的真实缺陷**(不是行数问题,是正确性问题):
|
||||
|
||||
| 缺陷 | 发现方式 |
|
||||
|------|---------|
|
||||
| `Access` 变体只有隐式判别值(重排即错位) | 新加的一致性测试 |
|
||||
| HOST id 空间稀疏——不是 bug,但此前无测试守护 | 同上(测试先报"不连续",核实后改成"稀疏但可还原") |
|
||||
| `escape_js_string` 的 debug 副本漏转义 U+2028/2029(JS 里是换行符) | 对比两份实现 |
|
||||
| `view` 路由分布在两个 handler,只改一个会让 debug 路由全 405 | 改完实测 HTTP |
|
||||
|
||||
---
|
||||
|
||||
## 3. 剩余体量为什么不是"冗余"
|
||||
|
||||
逐项核过,剩下的都是**功能**,删掉就是砍特性:
|
||||
|
||||
| 区域 | 行数 | 为什么保留 |
|
||||
|------|------|-----------|
|
||||
| `view/` 合计 | ~12,000 | live server + notebook UI:路由、渲染、注解、调试面板、执行报告;审计确认是 feature-gated 的一等 CLI 面 |
|
||||
| `host/foreign*` | ~5,100 | 外部语言内核(python/node 持久会话、快照、中断);qdagent 的沙箱执行依赖 |
|
||||
| `parse/` | ~4,900 | 词法/语法主体 + 内联测试 |
|
||||
| `bytecode/` | 1,921 | 第二后端;72 处测试引用(含双后端一致性) |
|
||||
| `knowledge/` | ~4,000 | catalog / EKC / 指纹;`marqdo catalog` 的输出有 golden 测试 |
|
||||
| `formula/` | 1,741 | `$$…$$` 公式;与 `ast::Expr` 是**不同类型**的两套求值器(不可合并) |
|
||||
| `host/dispatch.rs` | 2,052 | 202 个宿主函数的元数据 + 分派;`call_host` 是 202 个一行臂 |
|
||||
| `view/html.rs` | 4,451 | 其中 3,861 是页面皮肤字符串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 剩余可精简项(已定位,未做)
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| ~~插件 ABI 前言共享 crate~~ | **已完成**:[change-plugin-sdk.md](change-plugin-sdk.md),净减 674 行,注册项 0 差异 |
|
||||
| ~~HostFn 五表合一~~ | **已完成**:[change-hostfn-table.md](change-hostfn-table.md),−404 行,203 项逐字节一致 |
|
||||
| `view/html.rs` 皮肤"重复声明基础 CSS" | **审计判断不成立**:实测基础样式 312 条规则、notebook 128 条,**选择器零重叠**,无重复可删 |
|
||||
| `debug_page.rs` "复刻 shell" | **判断基本不成立**:只在 head/favicon 上有约 10 行相似;它没有 nav/topbar,是独立极简页 |
|
||||
| 内联测试迁到 `tests/` | 不减总量,只让 `src` 变薄;不做 |
|
||||
|
||||
**结论(修正后)**:可机械消除的重复**已经清完**。剩余体量全是特性实现,
|
||||
要再压只能砍功能(例如 `view` 调试面板、`formula` 引擎),不是"找重复"。
|
||||
|
||||
**判断**:这些加起来约 1.3k 行(总量的 2%),收益边际递减;其中插件 SDK 最值得做(消除 5 份漂移),
|
||||
其余属于"可以但不必"。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与设计的关系
|
||||
|
||||
精简的目的不是数字好看,而是**不让冗余掩盖设计**:
|
||||
|
||||
- 已消除的都是**重复实现**(同一逻辑多份 → 必然漂移)
|
||||
- 保留的都是**单一实现的特性能耐**
|
||||
- 每一条删改都跑全量测试:`605 → 609 passed / 0 failed`,编译零警告
|
||||
|
||||
如果后续还要压体量,正确的方向是**砍特性**(例如 `view` 的调试面板、`formula` 引擎),
|
||||
而不是继续在特性内部找"重复"——那已经找完了。
|
||||
@@ -0,0 +1,142 @@
|
||||
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · O1–O5 locked** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
|
||||
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 方案立场
|
||||
|
||||
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
|
||||
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
|
||||
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
|
||||
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构愿景(闭环)
|
||||
|
||||
```text
|
||||
目标 / 任务
|
||||
│
|
||||
▼
|
||||
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
|
||||
│ miss
|
||||
▼
|
||||
small-llm 路由 / 父分解
|
||||
│
|
||||
▼
|
||||
生成或修补 .mq.md(代码即文档风格)
|
||||
│
|
||||
▼
|
||||
sandbox.open → sandbox.run(caps)→ diff
|
||||
│
|
||||
├─ 失败 → writeback error / 隔离,不 promote
|
||||
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
|
||||
│
|
||||
▼
|
||||
下次 REUSE(降本)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 可行方向全集
|
||||
|
||||
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
|
||||
|
||||
### A. 沙盒 × Agent 闭环
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
|
||||
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
|
||||
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
|
||||
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
|
||||
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
|
||||
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
|
||||
|
||||
### B. OKF / EKC / 技能层
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
|
||||
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
|
||||
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
|
||||
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
|
||||
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
|
||||
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
|
||||
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
|
||||
|
||||
### C. 大模型 / 路由 / 成本
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
|
||||
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
|
||||
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
|
||||
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
|
||||
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
|
||||
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
|
||||
|
||||
### D. 代码即文档(产出质量)
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
|
||||
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
|
||||
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
|
||||
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
|
||||
|
||||
### E. 评测与产品化
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
|
||||
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
|
||||
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
|
||||
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
|
||||
|
||||
### F. 明确不优先 / 需单独论证
|
||||
|
||||
| ID | 方向 | 理由 |
|
||||
|----|------|------|
|
||||
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
|
||||
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
|
||||
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
|
||||
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
|
||||
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
|
||||
|
||||
---
|
||||
|
||||
## 3. 执行顺序(O1→O5 locked)
|
||||
|
||||
| 波次 | 方向组合 | 为何先做 |
|
||||
|------|----------|----------|
|
||||
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
|
||||
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
|
||||
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
|
||||
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
|
||||
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
|
||||
| **O∞** | C4 / A6 | 研究项,单独立项 |
|
||||
|
||||
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收原则(任一波次)
|
||||
|
||||
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
|
||||
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
|
||||
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
|
||||
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地
|
||||
|
||||
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Official AI sandbox (`ext/ai/sandbox`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted · implementing** |
|
||||
| Date | 2026-10-16 |
|
||||
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. One-liner
|
||||
|
||||
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals / non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| # | Goal |
|
||||
|---|------|
|
||||
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
|
||||
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
|
||||
| G3 | `diff` / `discard` / `inspect` for review gates |
|
||||
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
|
||||
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
|
||||
|
||||
### Non-goals (this wave)
|
||||
|
||||
| # | Non-goal |
|
||||
|---|----------|
|
||||
| N1 | Embed wasmtime in CLI |
|
||||
| N2 | True Wasm ABI plugins (linalg/quantum) |
|
||||
| N3 | bwrap / microVM |
|
||||
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
|
||||
| N5 | Symlink-forest workspace isolation |
|
||||
| N6 | Default host-proxy of all native ABI plugins |
|
||||
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Layering
|
||||
|
||||
```text
|
||||
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
|
||||
↓ host_query
|
||||
HostContext + CowSession
|
||||
(fs / writeback see upper)
|
||||
```
|
||||
|
||||
| Layer | May call `host_*` | Role |
|
||||
|-------|-------------------|------|
|
||||
| `ext/ai/sandbox` | **No** | Author facade |
|
||||
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
|
||||
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Author API
|
||||
|
||||
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
|
||||
|
||||
| Method | Params | Result |
|
||||
|--------|--------|--------|
|
||||
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
|
||||
| `write` | `id=`, `path=`, `text=` | none |
|
||||
| `read` | `id=`, `path=` | text |
|
||||
| `remove` | `id=`, `path=` | none (whiteout) |
|
||||
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
|
||||
| `commit` | `id=` | `{ ok, applied }` |
|
||||
| `discard` | `id=` | `{ ok }` |
|
||||
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
|
||||
| `inspect` | `id=` | caps, root, change count, notes |
|
||||
|
||||
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. CoW semantics
|
||||
|
||||
- **lower** = real workspace root (read-through).
|
||||
- **upper** = session map path → bytes.
|
||||
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
|
||||
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
|
||||
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
|
||||
|
||||
---
|
||||
|
||||
## 5. Hard bans
|
||||
|
||||
1. No public `lib/sandbox`.
|
||||
2. No symlink forest as the isolation story.
|
||||
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
|
||||
4. `ext/**` must not call `host_*`.
|
||||
5. Do not treat empty `# main` as sandbox completeness.
|
||||
|
||||
---
|
||||
|
||||
## 6. ABI / host_query
|
||||
|
||||
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
|
||||
|
||||
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
|
||||
@@ -120,8 +120,8 @@ import data:ext/data/db.mq.md
|
||||
| `path` | `路径` | URL |
|
||||
| `method` | `方法` | GET/POST/… |
|
||||
| `request` | `请求` | `json` / `form` / `none` |
|
||||
| `response` | `响应` | `json` / `text` / `html` |
|
||||
| `auth` | `鉴权` | 角色名或 `none` |
|
||||
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
|
||||
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
|
||||
|
||||
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
|
||||
|
||||
|
||||
@@ -347,7 +347,8 @@ plugins/web/ # Go module(替换原 Rust crate)
|
||||
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
```
|
||||
|
||||
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
|
||||
原 Rust 源码:曾置于 `plugins/web-rust-archive/`(已移出 Cargo workspace,参考用);
|
||||
该目录已于 v1.6 精简时从工作树移除,历史保留在 git 中。
|
||||
|
||||
### 9.2 产物与解析
|
||||
|
||||
|
||||
@@ -0,0 +1,449 @@
|
||||
# 外联内核(Foreign Kernel)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **F0–F3.5 已实现** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) |
|
||||
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> 外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 `marqdo run` 里的显式调用使用,也能被 view 的 notebook 会话使用。
|
||||
|
||||
---
|
||||
|
||||
## 1. 定位与边界
|
||||
|
||||
### 1.1 负责
|
||||
|
||||
- 解释器发现、注册、配置、探测。
|
||||
- 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
|
||||
- 持久内核:启动、求值、状态、关闭、列表。
|
||||
- 状态桥:`session_set` / `session_get` / `session_names`。
|
||||
- JSON 值桥:Marqdo `Value` ↔ JSON。
|
||||
- 结构化记录:`ok/code/stdout/stderr/ms/timed_out/truncated/result/error`。
|
||||
- 安全:`exec` 门禁、`cwd` 沙箱、进程组、并发/输出上限。
|
||||
- 视图诊断:代码卡片 Run 的完整结果。
|
||||
|
||||
### 1.2 不负责
|
||||
|
||||
- 文档语法(`内核表` / `会话表`)→ [notebook-syntax.md](notebook-syntax.md)。
|
||||
- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。
|
||||
- Foreign → Marqdo 函数回调(v2 不做)。
|
||||
- 依赖安装(pip/npm)。
|
||||
- 远程 / 容器执行。
|
||||
|
||||
### 1.3 与相邻模块的区别
|
||||
|
||||
| 模块 | 生命周期 | 用途 |
|
||||
|---|---|---|
|
||||
| `foreign` | 一次性或持久 | 调外部语言;状态可选 |
|
||||
| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 |
|
||||
| `plugin` | 进程内 | 原生 C ABI 扩展 |
|
||||
| `writeback` | 文档级 | 把输出写回 `.mq.md` |
|
||||
|
||||
`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。
|
||||
|
||||
---
|
||||
|
||||
## 1.4 实施状态(2026-10-17)
|
||||
|
||||
| 阶段 | 状态 | 关键文件 |
|
||||
|---|---|---|
|
||||
| F0 安全执行 / `invoke` 记录 | ✅ | `src/host/foreign.rs` |
|
||||
| F1 预设 / probe / register / config | ✅ | `src/foreign/registry.rs` · `src/host/foreign.rs` |
|
||||
| F2 JSON 桥 / run_many / call_many | ✅ | `src/host/foreign.rs` |
|
||||
| F3 Python/Node 持久内核 | ✅ | `src/host/foreign_session.rs` |
|
||||
| F3.5 session_set/get/names | ✅ | 同上 |
|
||||
| F4 history / view 打磨 / 发布 | 部分 | — |
|
||||
|
||||
测试:`cargo test --lib foreign`(11+)、`cargo test --test gold lib_foreign`(12,python 条件跳过)、`tests/notebook/shared.mq.md` 手工 view 验证。
|
||||
|
||||
---
|
||||
|
||||
## 2. 语言与内核模型
|
||||
|
||||
### 2.1 语言预设
|
||||
|
||||
| lang | 别名 | 默认命令 | 扩展名 | 版本探测 | 会话 |
|
||||
|---|---|---|---|---|---|
|
||||
| `python` | `python3`, `py` | `python3`(Windows `python`) | `.py` | `--version` | ✅ |
|
||||
| `node` | `javascript`, `js` | `node` | `.js` | `-v` | ✅ |
|
||||
| `deno` | — | `deno run` | `.ts` | `--version` | ❌ |
|
||||
| `bun` | — | `bun` | `.js` | `--version` | ❌ |
|
||||
| `ruby` | — | `ruby` | `.rb` | `--version` | ❌ |
|
||||
| `perl` | — | `perl` | `.pl` | `--version` | ❌ |
|
||||
| `php` | — | `php -r {inline}` | `.php` | `--version` | ❌ |
|
||||
| `lua` | — | `lua` | `.lua` | `-v` | ❌ |
|
||||
| `r` | `rscript` | `Rscript` | `.R` | `--version` | ❌ |
|
||||
| `julia` | — | `julia` | `.jl` | `--version` | ❌ |
|
||||
| `go` | — | `go run {file}` | `.go` | `version` | ❌ |
|
||||
| `bash` | `sh`, `shell` | `bash` | `.sh` | `--version` | ❌ |
|
||||
| `powershell` | `pwsh`, `ps1` | `pwsh`(Windows `powershell`) | `.ps1` | `--version` | ❌ |
|
||||
| `sqlite` | `sqlite3` | `sqlite3` | `.sql` | `--version` | ❌ |
|
||||
| `tsx` | `typescript` | `tsx` | `.ts` | `--version` | ❌ |
|
||||
|
||||
说明:
|
||||
|
||||
- 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
|
||||
- 会话能力首批只有 Python / Node;其它语言一次性执行。
|
||||
- `php` 用 `{inline}`,围栏里直接写 PHP,不需要 `<?php`。
|
||||
- `deno` 默认不给权限;需要时通过配置追加 `--allow-*`。
|
||||
|
||||
### 2.2 解析优先级
|
||||
|
||||
从高到低:
|
||||
|
||||
1. 调用级 `cmd`(整行 argv,shell-like 切分)+ `args`(追加)。
|
||||
2. 进程内注册:`register` / `set_cmd`。
|
||||
3. 环境变量 `MARQDO_FOREIGN_<LANG>`(整行或 JSON 数组)。
|
||||
4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。
|
||||
5. 内置预设。
|
||||
6. 都没有 → 带修复建议的诊断。
|
||||
|
||||
Python 额外发现顺序(在预设层内):
|
||||
|
||||
1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`);
|
||||
2. `<cwd>/.venv` / `venv` / `env`;
|
||||
3. 入口目录与 `fs_root` 向上查找;
|
||||
4. PATH 的 `python3` / `python`。
|
||||
|
||||
`MARQDO_FOREIGN_NO_VENV=1` 关闭 venv 探测;显式 `cmd` / `set_cmd` / `MARQDO_FOREIGN_PYTHON` 优先。
|
||||
|
||||
相对路径:配置里的 `cmd` 相对配置目录;注册 / `set_cmd` / 环境变量里的 `cmd` 相对 `cwd`。
|
||||
|
||||
### 2.3 注册与模板
|
||||
|
||||
`register(lang, cmd?, args?, template?, ext?, env?, version_args?)`。
|
||||
|
||||
模板占位符:
|
||||
|
||||
| 占位符 | 展开 |
|
||||
|---|---|
|
||||
| `{file}` | 临时脚本绝对路径 |
|
||||
| `{dir}` | 临时目录 |
|
||||
| `{base}` | 脚本文件名 |
|
||||
| `{inline}` | 源码作为一个 argv;不写临时文件 |
|
||||
| `{lang}` | 语言 id |
|
||||
| `{cwd}` | 实际工作目录 |
|
||||
|
||||
规则:
|
||||
|
||||
- `cmd` 与 `template` 至少一个;都给 → 报错。
|
||||
- `{file}` 与 `{inline}` 不能同时出现。
|
||||
- 都没有时自动追加 `{file}`。
|
||||
- `{inline}` 超过 60 KiB → 报错并建议 `{file}`。
|
||||
- 模板不做 shell 转义;需要 shell 时显式写 `bash -c`,路径由引擎生成(安全字符)。
|
||||
|
||||
配置示例:
|
||||
|
||||
```toml
|
||||
[python]
|
||||
cmd = ".venv/bin/python"
|
||||
args = ["-u"]
|
||||
|
||||
[go]
|
||||
template = ["go", "run", "{file}"]
|
||||
|
||||
[rust]
|
||||
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]
|
||||
|
||||
[php]
|
||||
template = ["php", "-r", "{inline}"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 一次性执行
|
||||
|
||||
### 3.1 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|---|---|---|---|
|
||||
| `run` | `运行` | `code`, 可选 `stdin` `env` `cwd` `timeout` `args` `max_output` | stdout 文本(v1 兼容) |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source`, 可选同上 | stdout 文本 |
|
||||
| `invoke` | `执行` | 可选 `code` / `lang`+`source` / `stdin` / `input` / `env` / `cwd` / `timeout` / `args` / `output` / `max_output` / `cmd` / `keep` / `cache` | 记录 map |
|
||||
| `call` | `调用` | 可选 `code` / `lang`+`source` / `input` / `stdin` / `env` / `cwd` / `timeout` / `args` | 解析后的 JSON 值 |
|
||||
| `run_many` | `批量运行` | `runs`, 可选 `concurrency` | 记录列表 |
|
||||
| `call_many` | `批量调用` | `inputs`, 可选 `code` / `lang`+`source` / `cmd` / `env` / `cwd` / `timeout` / `args` / `max_output` / `concurrency` | 结果值列表 |
|
||||
|
||||
### 3.2 记录结构
|
||||
|
||||
`invoke` / `run_many` / `session_eval` 共用:
|
||||
|
||||
| 键 | 类型 | 含义 |
|
||||
|---|---|---|
|
||||
| `ok` | Bool | exit=0 且未超时 |
|
||||
| `code` | Int | 退出码;未启动 / kill → -1 |
|
||||
| `stdout` | Text | 原始 stdout(可能截断) |
|
||||
| `stderr` | Text | 原始 stderr(可能截断) |
|
||||
| `ms` | Int | 墙钟毫秒 |
|
||||
| `lang` | Text | 实际语言 |
|
||||
| `cmd` | Text | 实际 argv |
|
||||
| `timed_out` | Bool | 是否超时 |
|
||||
| `truncated` | Bool | stdout/stderr 是否截断 |
|
||||
| `result` | 任意 / None | 按 `output` 解析 |
|
||||
| `result_error` | Text | json 解析失败原因 |
|
||||
| `error` | Text | 启动 / 超时 / 策略原因 |
|
||||
| `script` | Text | `keep=True` 的脚本路径 |
|
||||
| `cached` | Bool | 缓存命中(P4) |
|
||||
|
||||
`session_eval` 额外:`id`、`alive`。
|
||||
|
||||
### 3.3 输出模式
|
||||
|
||||
| `output=` | `result` |
|
||||
|---|---|
|
||||
| `auto`(默认) | 尝试 JSON;失败 → None |
|
||||
| `text` | None |
|
||||
| `json` | 解析;失败 → `result_error` |
|
||||
| `lines` | 行列表 |
|
||||
| `bytes` | stdout 原始字节的 base64 |
|
||||
|
||||
`call` 固定 JSON:空 stdout → None;非空非法 JSON → 错误。
|
||||
|
||||
### 3.4 失败语义
|
||||
|
||||
- `run` / `call`:执行失败 → `Err`;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
|
||||
- `invoke` / `run_many`:执行失败 → 记录;只有参数非法 / 策略拒绝 → `Err`。
|
||||
- 输出过大:截断 + `truncated=true`,不再 OOM / 报错。
|
||||
|
||||
---
|
||||
|
||||
## 4. JSON 状态桥
|
||||
|
||||
### 4.1 值映射
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number |
|
||||
| Num | number(NaN/Inf → null) |
|
||||
| Text | string |
|
||||
| List | array |
|
||||
| Map | object |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
### 4.2 输入
|
||||
|
||||
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
|
||||
- `stdin=` 文本与 `input=` 互斥。
|
||||
- 都不给 → stdin EOF。
|
||||
- 大输入走文件,避免环境变量大小限制。
|
||||
|
||||
### 4.3 输出
|
||||
|
||||
- `result` 按 `output` 解析。
|
||||
- 原始 stdout/stderr 始终保留(截断到上限)。
|
||||
- `call` 返回解析值;`invoke` 返回记录。
|
||||
|
||||
### 4.4 类型限制
|
||||
|
||||
v2 是**值拷贝**,不是对象引用:
|
||||
|
||||
- Python DataFrame / NumPy / Node 对象 → 需要先 `to_dict` / `to_json` / `JSON.stringify`。
|
||||
- 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
|
||||
- Secret 不默认进入 JSON;需要 env 显式交付。
|
||||
|
||||
---
|
||||
|
||||
## 5. 持久内核与会话
|
||||
|
||||
### 5.1 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|---|---|---|---|
|
||||
| `session_open` | `会话开启` | `lang`, 可选 `cmd` `env` `cwd` `timeout` | 会话 id(Text) |
|
||||
| `session_eval` | `会话求值` | `id`, 可选 `code` / `source` / `input` / `timeout` | 记录(含 id/alive) |
|
||||
| `session_set` | `会话设值` | `id`, `name`, `value` | None |
|
||||
| `session_get` | `会话取值` | `id`, `name` | JSON 值 / None |
|
||||
| `session_names` | `会话变量` | `id` | 名称列表 |
|
||||
| `session_close` | `会话关闭` | `id` | Bool |
|
||||
| `session_list` | `会话表` | — | map 列表 |
|
||||
|
||||
### 5.2 支持语言
|
||||
|
||||
| 语言 | 方式 |
|
||||
|---|---|
|
||||
| python | `python3 -u -c <bootstrap>` |
|
||||
| node | `node -e <bootstrap>` |
|
||||
| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` |
|
||||
|
||||
### 5.3 线路协议
|
||||
|
||||
stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:
|
||||
|
||||
```json
|
||||
{"id":1,"code":"x = 41","input":null}
|
||||
{"id":2,"code":"x + 1","input":null}
|
||||
```
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
|
||||
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
|
||||
```
|
||||
|
||||
- 同一会话严格串行:等到匹配响应后才发下一条。
|
||||
- 响应单行;JSON 转义换行。
|
||||
- 崩溃 / EOF → `alive=false`,会话移除。
|
||||
- 超时 → kill 会话(状态不可信)。
|
||||
|
||||
### 5.4 Python bootstrap
|
||||
|
||||
- 保留原始 `sys.stdout` 写协议;用户输出用 `redirect_stdout/stderr` 捕获。
|
||||
- `ast.parse`:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
|
||||
- 异常 → `traceback.format_exc(limit=8)`,`ok=false`;会话继续。
|
||||
- `input` → 全局 `marqdo_input`。
|
||||
- 不可序列化 → `default=str`。
|
||||
|
||||
### 5.5 Node bootstrap
|
||||
|
||||
- 保存原始 `process.stdout.write` 写协议。
|
||||
- eval 期间替换 `console.*` 与 `process.stdout/stderr.write`;结束后恢复。
|
||||
- `vm.runInThisContext` 保留全局状态;`require` 挂到 `globalThis`。
|
||||
- Promise → await;顶层 await 需用户包 `(async()=>{…})()`。
|
||||
- 序列化失败 → `String(result)`。
|
||||
|
||||
### 5.6 状态桥
|
||||
|
||||
- `session_set`:值 → JSON → 请求 `{"set": name, "value": ...}` 或执行一段赋值。
|
||||
- `session_get`:请求 `{"get": name}` → JSON → Marqdo Value。
|
||||
- `session_names`:请求变量名列表。
|
||||
- 与 `session_eval` 同一线路协议;严格串行。
|
||||
- 名称必须是合法标识符;保留名(`marqdo_input` 等)另行文档。
|
||||
|
||||
### 5.7 生命周期
|
||||
|
||||
- id 为 `s1`、`s2`…。
|
||||
- 每会话独立进程、cwd、env。
|
||||
- `HostContext` drop → 全部 kill + wait。
|
||||
- `subtask` 不继承会话。
|
||||
- 不跨文档共享。
|
||||
|
||||
---
|
||||
|
||||
## 6. 环境契约
|
||||
|
||||
| 变量 | 值 |
|
||||
|---|---|
|
||||
| `MARQDO_FOREIGN` | `1` |
|
||||
| `MARQDO_FOREIGN_LANG` | 语言 id |
|
||||
| `MARQDO_FOREIGN_SCRIPT` | 脚本路径(文件模式) |
|
||||
| `MARQDO_FOREIGN_DIR` | 脚本目录 |
|
||||
| `MARQDO_FOREIGN_CWD` | 实际 cwd |
|
||||
| `MARQDO_ENTRY` | 入口 `.mq.md` 路径 |
|
||||
| `MARQDO_ENTRY_DIR` | 入口目录 |
|
||||
| `MARQDO_INPUT` | input JSON(≤8 KiB) |
|
||||
| `MARQDO_INPUT_FILE` | input JSON 文件(任意大小) |
|
||||
|
||||
语言默认:
|
||||
|
||||
- Python:`PYTHONUNBUFFERED=1`、`PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`;`PYTHONPATH` 前插 cwd。
|
||||
- Node:`NODE_PATH` 前插 cwd(可选)。
|
||||
|
||||
`env` 是 map;值 `as_display()`;Secret 取真实值(显式交付)。不主动清空父环境。
|
||||
|
||||
---
|
||||
|
||||
## 7. 临时文件与 cwd
|
||||
|
||||
- 默认 `<cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/`;不可写 → 系统临时目录。
|
||||
- `MARQDO_FOREIGN_TMPDIR` 覆盖。
|
||||
- 脚本 `main.<ext>`;Python 加 utf-8 声明。
|
||||
- 默认 cwd = 入口目录;调用级 cwd 经 `resolve_path` + `fs_root` 校验。
|
||||
- 成功/失败/超时都清理;`keep=True` 保留并回填 `script`。
|
||||
- Node 相对 `require('./x')` 相对脚本目录;需要项目相对路径时用 `MARQDO_FOREIGN_CWD` 或 `{inline}` 模板。
|
||||
|
||||
---
|
||||
|
||||
## 8. 超时、IO、进程组
|
||||
|
||||
- `timeout`:秒,可小数;默认 10s;上限 3600s;`<=0` 报错。
|
||||
- 超时 kill 进程组:
|
||||
- Unix:`process_group(0)` + `kill(-pid, SIGKILL)`;
|
||||
- Windows:`taskkill /PID <pid> /T /F`。
|
||||
- `max_output`:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;`truncated=true`。
|
||||
- stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
|
||||
- stdout/stderr 两个读线程;UTF-8 lossy。
|
||||
- 记录原始字节(至上限)以支持 `bytes` 输出。
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全
|
||||
|
||||
| 项 | 策略 |
|
||||
|---|---|
|
||||
| 能力门禁 | `run` / `invoke` / `probe` / `session_*` 全部检查 `allow_exec()`;沙箱 → 拒绝 |
|
||||
| shell | 默认不经 shell;模板显式 `bash -c` 才走 |
|
||||
| cwd | `resolve_path` + `fs_root`;越界拒绝 |
|
||||
| 输出 | 有界读取 + 丢弃式排空 |
|
||||
| 时间 | 上限 + 进程组 kill |
|
||||
| 并发 | 默认 4,上限 32 |
|
||||
| 会话 | 每文档独立;关闭/drop 清理;超时即杀 |
|
||||
| Secret | JSON 不默认暴露;env 显式;面板打码 |
|
||||
| wasm | `exec-host` 关闭时全部返回清晰错误;`langs` 返回 [] |
|
||||
|
||||
---
|
||||
|
||||
## 10. 兼容性
|
||||
|
||||
- `run` / `run_lang` / `set_cmd` / `langs` 既有调用可用。
|
||||
- `run` 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
|
||||
- `set_cmd` 增加可选 `args`。
|
||||
- `langs` 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
|
||||
- `subtask` 的 `spawn code=` / `lang=` 仍返回 stdout 文本。
|
||||
- HostFn id 只追加;字节码参数 < 255。
|
||||
- 无核心表面 Δ。
|
||||
|
||||
---
|
||||
|
||||
## 11. 测试矩阵
|
||||
|
||||
| 测试 | 依赖 | 断言 |
|
||||
|---|---|---|
|
||||
| 既有 `foreign-python` / `run-lang` / `外联-python` | python | 兼容 |
|
||||
| `foreign-invoke` | node | ok/code/stdout/stderr/ms |
|
||||
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
|
||||
| `foreign-timeout` | node | timed_out, 无遗留进程 |
|
||||
| `foreign-call-json` | node | 嵌套 list/map 往返 |
|
||||
| `foreign-call-many` / `run-many` | node | 顺序/隔离/并发 |
|
||||
| `foreign-session` | node(python 可选) | 跨 eval 状态、异常不杀 |
|
||||
| `foreign-session-set-get` | node | 变量推拉 |
|
||||
| `foreign-session-timeout` | node | alive=false |
|
||||
| `foreign-probe` | node | path/version/ok |
|
||||
| `foreign-register` | node | 模板 `{inline}` |
|
||||
| `foreign-config` | node | `MARQDO_FOREIGN_CONFIG` |
|
||||
| `foreign-caps` | 无 | exec=false 拒绝 |
|
||||
| 单元测试 | 无 | shell 切分/模板/别名/JSON |
|
||||
|
||||
当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 `python_available()` / `bash_available()` 守卫。
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现落点
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `src/foreign/registry.rs` | 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑) |
|
||||
| `src/host/foreign.rs` | Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config |
|
||||
| `src/host/foreign_session.rs` | Python/Node bootstrap;会话生命周期;set/get/names |
|
||||
| `src/host/dispatch.rs` | HostFn 追加 |
|
||||
| `src/aliases.rs` | 参数别名 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | L1 API + 文档 |
|
||||
| `src/view/mod.rs` / `html.rs` / `debug_page.rs` | Run 诊断;后续接文档会话 |
|
||||
| `tests/gold.rs` / `tests/lib/foreign-*.mq.md` | 测试 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 明确不做
|
||||
|
||||
- Foreign line-level step。
|
||||
- Foreign → Marqdo 函数 callback。
|
||||
- 自动镜像变量。
|
||||
- 跨语言共享对象引用。
|
||||
- 全进程快照。
|
||||
- 自动安装依赖。
|
||||
- 浏览器 wasm 外联。
|
||||
@@ -0,0 +1,654 @@
|
||||
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed;尚未实现** |
|
||||
| 日期 | 2026-10-18 |
|
||||
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
|
||||
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
|
||||
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
|
||||
|
||||
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计约束
|
||||
|
||||
v3 必须继续满足以下约束,否则不进入实现:
|
||||
|
||||
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
|
||||
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
|
||||
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
|
||||
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
|
||||
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
|
||||
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
|
||||
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
|
||||
|
||||
---
|
||||
|
||||
## 2. 基线:现在已经有什么
|
||||
|
||||
| 能力 | 状态 |
|
||||
|---|---|
|
||||
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
|
||||
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
|
||||
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
|
||||
| `foreign.session kernels= cells= values=` | 已实现 |
|
||||
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
|
||||
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
|
||||
| 无 `会话` 时无状态 cells | 已实现 |
|
||||
| view 每 cell 内核选择 / Clean / Run | 已实现 |
|
||||
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
|
||||
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
|
||||
| 显式 `writeback.record` | 已实现(库能力) |
|
||||
| 静态页按钮的“不可执行”提示 | 已实现 |
|
||||
|
||||
---
|
||||
|
||||
## 2.1 实施状态(2026-10-18)
|
||||
|
||||
| ID | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
|
||||
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
|
||||
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
|
||||
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
|
||||
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
|
||||
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
|
||||
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
|
||||
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
|
||||
|
||||
## 3. 缺口清单
|
||||
|
||||
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|
||||
|---|---|---|---|---|
|
||||
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
|
||||
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
|
||||
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
|
||||
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
|
||||
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
|
||||
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
|
||||
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
|
||||
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
|
||||
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
|
||||
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
|
||||
|
||||
---
|
||||
|
||||
## 4. 统一模型
|
||||
|
||||
### 4.1 会话句柄
|
||||
|
||||
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
|
||||
|
||||
```text
|
||||
{
|
||||
kind: "foreign-session",
|
||||
id: "<session-id>",
|
||||
document: "<entry-source-hash>",
|
||||
status: "created | ready | running | interrupted | dirty | closed",
|
||||
kernels: [...],
|
||||
cells: [...],
|
||||
inputs: [...],
|
||||
values: [...],
|
||||
generation: 1
|
||||
}
|
||||
```
|
||||
|
||||
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
|
||||
|
||||
### 4.2 三种输入
|
||||
|
||||
必须严格区分:
|
||||
|
||||
| 输入 | 目标 | 形态 | 当前 |
|
||||
|---|---|---|---|
|
||||
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
|
||||
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
|
||||
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
|
||||
|
||||
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
|
||||
|
||||
### 4.3 每 cell 输入表
|
||||
|
||||
不新增标记,仍然使用普通表:
|
||||
|
||||
```mq.md
|
||||
`单元输入` =
|
||||
| 单元 | stdin | input |
|
||||
|------|-------|-------|
|
||||
| 计算 | hello | {rate: 0.08} |
|
||||
| 复核 | | {check: true} |
|
||||
```
|
||||
|
||||
`foreign.session` 增加可选参数:
|
||||
|
||||
```text
|
||||
foreign.session kernels=... cells=... values=... inputs=`单元输入`
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- `stdin` 只给该 cell 的程序 stdin;
|
||||
- `input` 只给该 cell 的 `marqdo_input`;
|
||||
- 空值表示不提供;
|
||||
- 输入大小有上限,超限显式报错;
|
||||
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
|
||||
|
||||
### 4.4 执行流水线
|
||||
|
||||
```text
|
||||
evaluate 会话 handle
|
||||
→ open kernels
|
||||
→ apply values
|
||||
→ apply cell inputs
|
||||
→ run cell
|
||||
→ record {stdout, stderr, input_echo, result}
|
||||
→ next cell
|
||||
```
|
||||
|
||||
失败不终止整个 Run All;错误写入 cell record,journal 保留。
|
||||
|
||||
---
|
||||
|
||||
## 5. G1/G2:持久内核 stdin 与每 cell 输入
|
||||
|
||||
### 5.1 问题
|
||||
|
||||
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
|
||||
|
||||
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
|
||||
|
||||
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
|
||||
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
|
||||
- worker 协议升级为 `protocol: 2`:
|
||||
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
|
||||
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
|
||||
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
|
||||
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
|
||||
- 超时/中断关闭该次 stdin,不污染下一次 eval。
|
||||
|
||||
### 5.3 方案 B(降级):只支持 `input`
|
||||
|
||||
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
|
||||
|
||||
```text
|
||||
persistent kernel stdin is unavailable; use input= or stateless cells
|
||||
```
|
||||
|
||||
不能静默把 stdin 变成 `marqdo_input`。
|
||||
|
||||
### 5.4 方案 C:stdin cell 降级为一次性
|
||||
|
||||
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
|
||||
|
||||
### 5.5 UI 与静态
|
||||
|
||||
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
|
||||
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
|
||||
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
|
||||
|
||||
### 5.6 验收
|
||||
|
||||
- Python 与 Node 持久内核都能读取真实 stdin;
|
||||
- 同一个 cell 连续 eval 不串输入;
|
||||
- 超时/中断后下一次 eval 仍可读 stdin;
|
||||
- 无状态 cell 行为不变;
|
||||
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
|
||||
|
||||
---
|
||||
|
||||
## 6. G3:动态 plan 的边界
|
||||
|
||||
### 6.1 问题
|
||||
|
||||
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
|
||||
|
||||
### 6.2 设计决定(建议)
|
||||
|
||||
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
|
||||
|
||||
- plan 是文档的声明,不是程序运行时的副作用;
|
||||
- view 不应为了找 plan 而执行 `# main`;
|
||||
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
|
||||
|
||||
允许的动态形式:
|
||||
|
||||
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
|
||||
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
|
||||
- 运行时变化通过 G4 的显式 session API 完成。
|
||||
|
||||
**不支持**:
|
||||
|
||||
- `##` 函数内部的 plan;
|
||||
- `if`/`while` 分支里的 plan;
|
||||
- 依赖 `# main` 副作用才能得到的 plan。
|
||||
|
||||
### 6.3 诊断
|
||||
|
||||
如果源码中出现非顶层 `foreign.session`,给出:
|
||||
|
||||
```text
|
||||
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
|
||||
```
|
||||
|
||||
而不是静默降级为无状态。
|
||||
|
||||
---
|
||||
|
||||
## 7. G4:运行时更新 plan
|
||||
|
||||
### 7.1 目标
|
||||
|
||||
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
|
||||
|
||||
### 7.2 API
|
||||
|
||||
```text
|
||||
foreign.session_assign session=<handle> cell="计算" kernel="复核"
|
||||
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
|
||||
foreign.session_remove_cell session=<handle> cell="旧单元"
|
||||
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
|
||||
```
|
||||
|
||||
所有操作:
|
||||
|
||||
- 校验 cell/kernel 语言;
|
||||
- 递增 `generation`;
|
||||
- 写入 journal(kind=plan_change / value_change);
|
||||
- 标记受影响 cell 为 `dirty`;
|
||||
- 失败不改变 handle。
|
||||
|
||||
### 7.3 View
|
||||
|
||||
- 内核下拉复用 `session_assign`;
|
||||
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
|
||||
- UI 显示 generation / dirty 状态。
|
||||
|
||||
### 7.4 静态
|
||||
|
||||
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
|
||||
|
||||
---
|
||||
|
||||
## 8. G5:kernel interrupt
|
||||
|
||||
### 8.1 API
|
||||
|
||||
```text
|
||||
foreign.session_interrupt id=<session-id>
|
||||
```
|
||||
|
||||
### 8.2 行为
|
||||
|
||||
- 控制通道发送 `interrupt`;
|
||||
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
|
||||
- 保留已完成的值和 journal;
|
||||
- 状态从 `running` → `interrupted`;
|
||||
- 下一次 eval 可以继续使用内核(除非进程已损坏);
|
||||
- 超时继续作为最后一道防线。
|
||||
|
||||
### 8.3 View
|
||||
|
||||
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
|
||||
- 不自动重跑;
|
||||
- 静态导出没有 interrupt(快照不执行)。
|
||||
|
||||
### 8.4 跨平台
|
||||
|
||||
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
|
||||
|
||||
---
|
||||
|
||||
## 9. G6:状态持久化与 replay
|
||||
|
||||
### 9.1 不做的事
|
||||
|
||||
- 不做 Python pickle / Node 堆快照;
|
||||
- 不做任意对象反序列化;
|
||||
- 不把内核内存默认写进 `.mq.md`。
|
||||
|
||||
### 9.2 显式快照
|
||||
|
||||
```text
|
||||
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
|
||||
foreign.session_import path=".marqdo/sessions/doc-1.json"
|
||||
```
|
||||
|
||||
快照只包含:
|
||||
|
||||
```text
|
||||
{
|
||||
version: 1,
|
||||
document_hash: "...",
|
||||
plan_hash: "...",
|
||||
kernels: [{name, lang, cmd, values: {...}}],
|
||||
cells: [{name, kernel, status, last_ok, last_error}],
|
||||
journal: [...],
|
||||
inputs: [...]
|
||||
}
|
||||
```
|
||||
|
||||
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
|
||||
|
||||
### 9.3 replay
|
||||
|
||||
```text
|
||||
foreign.session_replay path="..." verify=True
|
||||
```
|
||||
|
||||
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
|
||||
|
||||
### 9.4 存储
|
||||
|
||||
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
|
||||
- 用户可通过 path 放到受控目录;
|
||||
- 不默认提交,不默认写源码。
|
||||
|
||||
---
|
||||
|
||||
## 10. G7:跨文档内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
|
||||
|
||||
### 10.1 原则
|
||||
|
||||
- 默认每文档独立;
|
||||
- 跨文档必须显式 `scope=` / `space=`;
|
||||
- 不自动按变量名或路径共享。
|
||||
|
||||
### 10.2 API
|
||||
|
||||
```text
|
||||
foreign.session_open lang="python" scope="shared:analytics"
|
||||
foreign.session_list scope="shared:analytics"
|
||||
foreign.session_close id=... scope=...
|
||||
```
|
||||
|
||||
- scope 注册表由 foreign runtime 管理;
|
||||
- 同名冲突报错,不覆盖;
|
||||
- view 只能打开当前文档声明允许的 scope;
|
||||
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
|
||||
|
||||
### 10.3 安全
|
||||
|
||||
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
|
||||
- journal 标记 scope;
|
||||
- 静态导出默认不打开跨文档 scope。
|
||||
|
||||
---
|
||||
|
||||
## 11. G8:非 Python/Node 持久内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
|
||||
|
||||
### 11.1 模型
|
||||
|
||||
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
|
||||
|
||||
```text
|
||||
session: none | protocol_v2
|
||||
```
|
||||
|
||||
- `none`:只能 `run` / `invoke` 一次性;
|
||||
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
|
||||
|
||||
### 11.2 适配器
|
||||
|
||||
Go 等语言通过一个薄 worker 实现:
|
||||
|
||||
```text
|
||||
control frame: eval {code, stdin, input}
|
||||
result frame: {ok, stdout, stderr, result, error}
|
||||
```
|
||||
|
||||
不允许“看起来像持久内核、实际每次重启”的假实现。
|
||||
|
||||
### 11.3 失败语义
|
||||
|
||||
- `session_open` 对 `session: none` 的语言明确报错;
|
||||
- `foreign.session` 的 plan 只能使用支持 session 的语言;
|
||||
- 静态/无状态仍可使用一次性执行。
|
||||
|
||||
---
|
||||
|
||||
## 12. G9:live → static 输入捕获
|
||||
|
||||
### 12.1 问题
|
||||
|
||||
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
|
||||
|
||||
### 12.2 设计
|
||||
|
||||
增加显式的“捕获快照”:
|
||||
|
||||
```text
|
||||
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
|
||||
```
|
||||
|
||||
快照内容:
|
||||
|
||||
- document source hash;
|
||||
- session plan(kernels/cells/values);
|
||||
- 每 cell 的 stdin/input;
|
||||
- 每 cell 的 stdout/stderr/status;
|
||||
- journal 摘要、语言/解释器版本;
|
||||
- 捕获时间。
|
||||
|
||||
静态导出:
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
|
||||
```
|
||||
|
||||
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
|
||||
|
||||
### 12.3 安全/隐私
|
||||
|
||||
- 快照可能包含 secrets;默认不提交、不发布;
|
||||
- 提供 `redact` 字段/正则;
|
||||
- 静态页面只发布脱敏后的快照。
|
||||
|
||||
### 12.4 验收
|
||||
|
||||
- live 中成功的结果可以在静态页面原样显示;
|
||||
- 不捕获内核内存,只捕获输入/输出/状态;
|
||||
- 没有快照时回退到构建时执行,行为明确。
|
||||
|
||||
---
|
||||
|
||||
## 13. G10:自动 writeback
|
||||
|
||||
### 13.1 原则
|
||||
|
||||
**“自动”必须是用户显式选择的策略,不是默认副作用。**
|
||||
|
||||
### 13.2 API
|
||||
|
||||
```text
|
||||
foreign.session persist=`写回策略`
|
||||
```
|
||||
|
||||
策略表:
|
||||
|
||||
```mq.md
|
||||
`写回策略` =
|
||||
| 单元 | key |
|
||||
|------|-----|
|
||||
| 计算 | total |
|
||||
| 复核 | check |
|
||||
```
|
||||
|
||||
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
|
||||
|
||||
### 13.3 语义
|
||||
|
||||
- 默认不写源码;
|
||||
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
|
||||
- 静态构建默认不写回;`--writeback` 必须显式;
|
||||
- writeback 只支持 JSON 可表达值;
|
||||
- 写入位置/格式仍由 `writeback` 库决定。
|
||||
|
||||
### 13.4 与静态快照的关系
|
||||
|
||||
- 静态快照是只读发布;
|
||||
- writeback 是源码内的活结果;
|
||||
- 两者可以共存,但不能互相隐式触发。
|
||||
|
||||
---
|
||||
|
||||
## 14. API / 端点汇总
|
||||
|
||||
### 14.1 新增 foreign 函数
|
||||
|
||||
```text
|
||||
foreign.session inputs=
|
||||
foreign.session_assign
|
||||
foreign.session_add_cell
|
||||
foreign.session_remove_cell
|
||||
foreign.session_set_value
|
||||
foreign.session_interrupt
|
||||
foreign.session_export
|
||||
foreign.session_import
|
||||
foreign.session_replay
|
||||
foreign.session_open scope=
|
||||
foreign.session_list scope=
|
||||
```
|
||||
|
||||
### 14.2 View API
|
||||
|
||||
```text
|
||||
POST /api/session/cell/run { cell, stdin }
|
||||
POST /api/session/run_all { restart, inputs? }
|
||||
POST /api/session/cell/clear
|
||||
POST /api/session/plan/assign
|
||||
POST /api/session/plan/add
|
||||
POST /api/session/plan/remove
|
||||
POST /api/session/plan/value
|
||||
POST /api/session/interrupt
|
||||
POST /api/session/snapshot/capture
|
||||
```
|
||||
|
||||
所有端点只操作 foreign 句柄;view 不直接读写内核。
|
||||
|
||||
### 14.3 CLI
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot FILE
|
||||
marqdo view output --execute
|
||||
marqdo view output --no-exec
|
||||
marqdo run --writeback
|
||||
```
|
||||
|
||||
不新增 `marqdo notebook`。
|
||||
|
||||
---
|
||||
|
||||
## 15. 语义矩阵
|
||||
|
||||
| 能力 | run | view | static |
|
||||
|---|---|---|---|
|
||||
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
|
||||
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
|
||||
| interrupt | 无 UI | 可调用 | 不可用 |
|
||||
| state export | 可调用 | 可显式导出 | 不导出或快照 |
|
||||
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
|
||||
| writeback | `--writeback` | 显式按钮 | 默认不写 |
|
||||
|
||||
---
|
||||
|
||||
## 16. 实施顺序
|
||||
|
||||
### P0(先做,直接影响真实使用)
|
||||
|
||||
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
|
||||
2. **G5 interrupt**:避免只能等超时。
|
||||
3. **G9 snapshot capture**:解决 live/static 不一致。
|
||||
|
||||
### P1
|
||||
|
||||
4. **G4 runtime plan updates**。
|
||||
5. **G6 export/replay**。
|
||||
|
||||
### P2
|
||||
|
||||
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
|
||||
7. **G10 explicit writeback policy**。
|
||||
|
||||
### Deferred(不在当前目标)
|
||||
|
||||
- **G7 cross-document scope**:设计保留,后续版本再开发。
|
||||
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
|
||||
|
||||
---
|
||||
|
||||
## 17. 测试设计
|
||||
|
||||
### 单元
|
||||
|
||||
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
|
||||
- 每 cell 输入隔离;
|
||||
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
|
||||
- 表格不产生 call chip(已修复);
|
||||
- plan top-level 诊断;
|
||||
- session generation / dirty;
|
||||
- export/import/replay 校验。
|
||||
|
||||
### 集成
|
||||
|
||||
- Python 持久内核读 `sys.stdin`;
|
||||
- Node 持久内核读 `process.stdin`;
|
||||
- view Run All 使用每 cell 输入;
|
||||
- interrupt 后下一次 eval 正常;
|
||||
- static snapshot 与 live 结果一致;
|
||||
- snapshot hash 不匹配显式失败;
|
||||
- cross-doc scope 冲突/清理;
|
||||
- Go 一次性 vs 持久能力诊断;
|
||||
- writeback 只显式写入。
|
||||
|
||||
### 静态
|
||||
|
||||
- 输出无 traceback;
|
||||
- 没有输入时显示说明而非伪造;
|
||||
- 多内核 controls 显示;
|
||||
- writeback slot 单块、暗色主题;
|
||||
- 静态按钮提示。
|
||||
|
||||
---
|
||||
|
||||
## 18. 兼容与迁移
|
||||
|
||||
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
|
||||
- 新 `inputs=` 可选;
|
||||
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
|
||||
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
|
||||
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
|
||||
|
||||
---
|
||||
|
||||
## 19. 需要拍板的决策
|
||||
|
||||
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
|
||||
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
|
||||
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
|
||||
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
|
||||
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
|
||||
|
||||
---
|
||||
|
||||
## 20. 当前目标范围
|
||||
|
||||
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
|
||||
|
||||
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
|
||||
|
||||
## 21. 非目标
|
||||
|
||||
- 不新增 Markdown 标记;
|
||||
- 不新增 notebook CLI/模式;
|
||||
- 不把任意内核内存序列化;
|
||||
- 不默认修改 `.mq.md`;
|
||||
- 不自动镜像变量;
|
||||
- 不把 view 变成第二套解释器;
|
||||
- 不把“未实现”伪装成支持。
|
||||
|
||||
@@ -0,0 +1,304 @@
|
||||
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 命题来源 | 用户:「函数是复用、是对高度凝练内容的提炼加工;正常人不会说『计算 37 的两倍需要抽象一个函数』,而是直接说乘二」 |
|
||||
| 定位 | 本文只谈**语义表示**与**自然语言映射**,不谈编译器与语法糖 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 把你的观察写成三条命题
|
||||
|
||||
**命题一(现象)**:函数是一种**预先抽象**装置——必须在使用之前先把内容提炼并命名,还要声明它需要哪些输入。
|
||||
|
||||
**命题二(对照)**:自然语言是**即席描述**——先把事说清楚,只有在内容确实要反复出现时,才顺手给它一个名字("以上做法,我们称为…"),而且命名之后它可以像普通名词/动词一样被使用。
|
||||
|
||||
**命题三(结论)**:因此「函数」这套仪式与「代码即文档」错位。要解决的不是调用写法,而是**用什么语义表示来承担"复用"这件事**。
|
||||
|
||||
本文的答案先给出来:
|
||||
|
||||
> **Marqdo 需要的不是更好的"函数",而是把「函数」还原成「命名」,把「调用」还原成「代入」。**
|
||||
> 函数 = **一段被命名的正文**;参数 = **那段正文里尚未确定的量**;调用 = **把这些量代入后重述一遍**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 语料给出的证据:Marqdo 的 `##` 其实不是"过程"
|
||||
|
||||
统计 `lib/ ext/ examples/ tests/` 全部 1322 个 `##`:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 函数总数 | 1322 |
|
||||
| **纯返回式**(零可执行语句,只有一个返回表达式) | **765(57.9%)** |
|
||||
| 一行式(可执行行 ≤1 且返回 ≤1) | 935(70.7%) |
|
||||
| 极短(可执行行 ≤2) | 1162(87.9%) |
|
||||
| 较长(可执行行 ≥10) | 62(4.7%) |
|
||||
| 可执行语句数**中位数** | **0** |
|
||||
| 平均 | 2.2 |
|
||||
|
||||
典型代表:`## str_trim`、`## contains`、`## to_upper`——**一个名字包一个表达式**。
|
||||
|
||||
这说明:**人们用 `##` 在做"命名",语法却要求他们按"过程抽象"的仪式来做。**
|
||||
签名(`+ n`)、祈使式调用(`> f 1 2`)、返回值约定(`*…*`)全是过程语言的行头,
|
||||
而实际内容是"给这个式子起个名字"。
|
||||
|
||||
**水土不服不是感受,是可以量化的形式错配。**
|
||||
|
||||
### 1.1 按「语义功能」再分一次类
|
||||
|
||||
把 1322 个函数按内容形态归类(同一函数可能重叠,故按主特征优先):
|
||||
|
||||
| 形态 | 判据 | 数量 | 占比 | 自然语言对应 |
|
||||
|------|------|------|------|-------------|
|
||||
| **纯命名式** | 零语句、零副作用、零分支、零循环,只有一个返回式 | **754** | **57.0%** | 「所谓 X,是指…」 |
|
||||
| **条款式** | 有分支、无副作用 | 103 | 7.8% | 「凡…则…」 |
|
||||
| **遍历式** | 有循环、无副作用 | 26 | 2.0% | 「对每一项…」 |
|
||||
| **命令式** | 含 `print` 等副作用 | **83** | **6.3%** | 「打印…」祈使句 |
|
||||
| 线性计算(其余) | 有语句但无控制流/副作用 | 356 | 26.9% | 「先…再…」 |
|
||||
|
||||
两个结论:
|
||||
|
||||
1. **命名 + 条款 = 64.8%** —— 三分之二的 `##` 落在"定义"与"条款"两种自然语言形态里,
|
||||
而这两种恰好不需要"过程"语义(§4 立场甲、乙)。
|
||||
2. **真正的副作用只有 6.3%** —— 也就是说"命令/祈使"语义只是少数派,
|
||||
完全可以隔离成一小块(§8.1),不必让它污染整体读法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么"抽象"在文档里格外别扭:复用经济学
|
||||
|
||||
抽象不是免费的。它有三项成本:
|
||||
|
||||
| 成本 | 内容 |
|
||||
|------|------|
|
||||
| **定义成本** | 要写一次定义(名字、输入、边界) |
|
||||
| **跳转成本** | 读者看到名字,必须回到定义处才能理解(文档尤其致命:要翻页/滚动) |
|
||||
| **维护成本** | 定义改了,所有使用处语义随之变化 |
|
||||
|
||||
收益只有一项:**同一内容被复用 N 次时省下的重复**。
|
||||
|
||||
于是有:
|
||||
|
||||
> **抽象值得做 ⟺ 复用次数 × 内容复杂度 > 定义成本 + N × 跳转成本**
|
||||
|
||||
在**代码**里,N 往往很大、跳转成本低(IDE 跳转、同屏),所以抽象划算。
|
||||
在**文档**里,N 常常是 **1**,跳转成本高(读者在阅读流里被打断),于是:
|
||||
|
||||
> **文档中大量"函数"是负收益的**——它们只被用一次,却强迫读者回头查定义。
|
||||
|
||||
这解释了为什么你会有"正常人不会这么说话"的直觉:**说话的默认假设是对方不知道你的定义**,
|
||||
所以人话倾向于**就地展开**;而函数默认假设读者愿意跳转。
|
||||
|
||||
---
|
||||
|
||||
## 3. 自然语言里「复用」到底有几种形态
|
||||
|
||||
程序语言只承认其中一种(命名+参数化),这是错配的第二层。
|
||||
|
||||
| 形态 | 自然语言的样子 | 对应的程序装置 | Marqdo 现状 |
|
||||
|------|---------------|---------------|------------|
|
||||
| **重复** | 再说一遍 | 复制粘贴 | ✅ 允许 |
|
||||
| **指称** | 如上所述 / 同前 / 该金额 | 变量、引用 | ✅ `` `名` `` |
|
||||
| **命名** | 所谓 X,是指…;以下称 X | 定义 / 函数 | ✅ `## X` |
|
||||
| **条款** | 凡…则…;若…应… | 条件分支、规则 | ✅ `1. 2. 3.` |
|
||||
| **范例** | 以 37 为例 | 样例/测试 | ⚠️ 仅测试目录 |
|
||||
| **表格/清单** | 见下表;用料如下 | 数据、查表 | ✅ 表格 |
|
||||
|
||||
**关键发现**:命名只是六分之一,但程序语言把它变成了**唯一的复用入口**。
|
||||
而文档写作里,**指称("该金额")与条款("凡…则…")比命名更常用**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 三种候选语义表示(哲学立场)
|
||||
|
||||
要"代替水土不服",必须给出**语义模型**,而不只是换个写法。三个候选:
|
||||
|
||||
### 立场甲:定义—代入(Definition & Substitution)
|
||||
|
||||
**语义**:一段正文被命名 → 成为一个**定义**。使用它 = 把定义里的自由量按**角色**代入,再重述。
|
||||
|
||||
```markdown
|
||||
## 加倍
|
||||
|
||||
把 `x` 乘以二,得 *y*
|
||||
```
|
||||
|
||||
使用(语义读法):**按「加倍」代入 x=37,得 74。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力 |
|
||||
| 与 Marqdo 契合 | ✅ `##`/`#` 本来就是标题(文档结构),天然是"定义"的载体 |
|
||||
| 参数观 | ✅ 角色(具名),不是位置占位符 |
|
||||
| 复用单位 | ✅ **文本段落本身**(文档即单位,符合"代码即文档") |
|
||||
| 71% 的现有一行式函数 | ✅ 直接就是"命名的表达式",无需过程仪式 |
|
||||
| 缺点 | 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5) |
|
||||
|
||||
### 立场乙:条款—援引(Clause & Citation)
|
||||
|
||||
**语义**:条件 → 结论。使用 = 援引条款并给出适用的事实。
|
||||
|
||||
```markdown
|
||||
## 计费规则
|
||||
|
||||
若 `里程` 超过 100 公里,则 `费用` 按 8 折计。
|
||||
```
|
||||
使用(语义读法):**本单里程 120 公里,依「计费规则」,费用按 8 折。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅✅ 「凡…则…」是中文说明文/法条/规章的骨架 |
|
||||
| 与 Marqdo 契合 | ✅ `1. 2. 3.` 分支已经就是条款形式 |
|
||||
| 缺点 | 数值计算写成条款别扭("把 37 乘以二"不是条款) |
|
||||
|
||||
### 立场丙:配方—配料(Recipe & Ingredients)
|
||||
|
||||
**语义**:一张用料表 + 一段做法。参数 = 配料表中的行。
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 菜谱、工艺卡、表单 |
|
||||
| 与 Marqdo 契合 | ✅✅ 表格优先正是 Marqdo 的特色;契约表已是雏形 |
|
||||
| 缺点 | 表达力弱;无法递归、无法组合;"给值"变成填表 |
|
||||
|
||||
### 取舍
|
||||
|
||||
| | 甲 代入 | 乙 条款 | 丙 配料 |
|
||||
|---|---|---|---|
|
||||
| 覆盖"命名表达式"(58% 的现状) | ✅✅ | ⚠️ | ❌ |
|
||||
| 覆盖"条件规则" | ⚠️ | ✅✅ | ❌ |
|
||||
| 覆盖"数值流程" | ✅ | ❌ | ⚠️ |
|
||||
| 可读性 | 高 | 最高 | 最高(但最弱) |
|
||||
| 与 `##` 结构一致 | ✅ | ✅ | ⚠️ 表为主 |
|
||||
|
||||
**推荐:以甲为主,乙作为甲内部的一种段落形态。** 理由见 §6。
|
||||
|
||||
---
|
||||
|
||||
## 5. 「代入」为什么比「调用」更贴自然语言
|
||||
|
||||
这不是文字游戏,三处实质差异:
|
||||
|
||||
| 维度 | 调用(invocation) | 代入(substitution) |
|
||||
|------|-------------------|---------------------|
|
||||
| 读者的心理动作 | "跳过去,看它做什么,再回来" | "把这个式子代进去" |
|
||||
| 输入的意义 | 实参 → 形参(两套名字) | 角色 → 定义里的同一个名字(**一套名字**) |
|
||||
| 结果的意义 | 函数返回了一个值 | 式子变成了具体结果 |
|
||||
| 出现位置 | 必须是独立语句或表达式 | 可以**嵌在叙述里**("加倍后为 74 件") |
|
||||
| 一次性使用 | 仍要付出定义+跳转成本 | 可以**不定义,直接展开**(§5.1) |
|
||||
|
||||
### 5.1 关键:抽象要能被"取消"
|
||||
|
||||
自然语言的强大在于**可省略**:能一句话说清就不起名字。
|
||||
所以语义模型必须允许同一件事有**两种粒度**,并可以随时在两者之间移动:
|
||||
|
||||
| 粒度 | 写法(示意) | 何时用 |
|
||||
|------|-------------|--------|
|
||||
| **就地描述** | 把 37 乘以二,得 74 | 只用一次 |
|
||||
| **命名后代入** | 按「加倍」代入 x=37,得 74 | 复用多次 |
|
||||
|
||||
而且**提升与展开都是作者的编辑动作,不是必须的入口**。
|
||||
这正是"抽象可选"——今天的函数是"必须先抽象",这是错配的第三层。
|
||||
|
||||
### 5.2 与 58% 纯表达式函数的对应
|
||||
|
||||
`## to_upper` 这类函数,用"代入"读就是:
|
||||
|
||||
> 「to_upper 的定义是:把 `s` 变成全大写。」使用:`to_upper` 代入 s="abc" 得 "ABC"。
|
||||
|
||||
它读起来是一个**定义 + 一次代入**,而不是"调用一个过程"。这与它的实际内容(一个表达式)一致。
|
||||
|
||||
---
|
||||
|
||||
## 6. 这套语义如何落到 Marqdo 已有的东西上
|
||||
|
||||
| 自然语言的成分 | Marqdo 已有载体 | 需不需要新东西 |
|
||||
|---------------|----------------|---------------|
|
||||
| 命名(给出定义) | `#` / `##` 标题 | ❌ 已有 |
|
||||
| 正文(定义的内容) | 叙述 + 标记代码 | ❌ 已有 |
|
||||
| 未确定的量(角色) | 体推断出来的形参(v0.3 已有) | ❌ 已有 |
|
||||
| 角色的**具名给值** | (缺失) | ✅ **这是唯一真正缺的一环** |
|
||||
| 结论(得…) | `*…*` 返回 | ❌ 已有 |
|
||||
| 条款(凡…则…) | `1. 2. 3.` 分支 | ❌ 已有 |
|
||||
| 配料表 | GFM 表格 + 契约表 | ❌ 已有 |
|
||||
| 引用(依…) | (缺失) | ⚠️ 与"具名给值"是同一件事 |
|
||||
|
||||
**结论:缺的只有一件事——「具名给值」的形式。**
|
||||
|
||||
也就是说:语义模型(代入)几乎不用改,语法只缺一个"把角色填上"的最小约定。
|
||||
这把问题从"要不要重新设计函数"缩小到"这一个小约定怎么长得最不刺眼"。
|
||||
|
||||
---
|
||||
|
||||
## 7. 不可回避的哲学难题:自然性 vs 可判定性
|
||||
|
||||
自然语言判断"哪些量要代入"靠**语境**(前文、常识、指代)。
|
||||
编译器不能。所以必须有一条**显式约定**,无法省掉。
|
||||
|
||||
三种可能的约定形态(只列哲学性质,不列语法细节):
|
||||
|
||||
| 形态 | 自然的程度 | 可判定的程度 | 风险 |
|
||||
|------|-----------|-------------|------|
|
||||
| **角色必须具名给出** | 中(像"按定义,其中 x=37") | ✅ 完全可判定 | 略啰嗦 |
|
||||
| **靠语序(位置)** | 高 | ✅ 可判定 | ❌ 已实测:叙述顺序一变,绑定就翻转(见 call-syntax-from-marks.md §4.3) |
|
||||
| **靠语境(隐式)** | 最高 | ❌ 不可判定 | ❌ 130 个形参名撞车 |
|
||||
|
||||
**这是整件事的硬边界**:越像人话,越难判定。Marqdo 必须选"具名"这一档——
|
||||
它是**唯一同时可读且可判定**的点。
|
||||
|
||||
而这也解释了为什么"叙述式动词"(`执行`)不可取:它把判定交给了一个**未标记的词**,
|
||||
既没有自然的程度优势,又破坏了"叙述安全"。
|
||||
|
||||
---
|
||||
|
||||
## 8. 三个尚未解决的哲学问题
|
||||
|
||||
这些是真问题,需要后续立场,不宜草率定:
|
||||
|
||||
1. **副作用怎么办?**
|
||||
"把 37 乘以二"是纯代入;"打印 74"呢?打印**改变世界**,不是代入。
|
||||
→ 副作用可能必须停留在"命令"语义(今天的 `> print`),
|
||||
而这会让文档里同时存在"代入"与"命令"两套读法。这是否可接受?
|
||||
|
||||
2. **递归与自引用怎么办?**
|
||||
代入是有限展开;递归是无限展开。若坚持代入选义,递归就不可表达。
|
||||
→ 是否接受"Marqdo 不支持递归"?还是给递归单独一套"过程"语义?
|
||||
|
||||
3. **定义的时序怎么办?**
|
||||
自然语言允许先使用后定义("如上,我们称之为…")。代入语义要求定义先存在。
|
||||
→ 是否允许前向引用(读者先看到 `加倍`,后面才看到定义)?
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话总结与建议
|
||||
|
||||
> **Marqdo 的问题不是"函数不好用",而是"函数是过程语言留给文档的遗产"。**
|
||||
> 文档需要的不是过程,是**命名**;不是**调用**,是**代入**。
|
||||
|
||||
建议的语义立场(待你裁决):
|
||||
|
||||
| 项 | 建议 |
|
||||
|----|------|
|
||||
| 复用单位 | **一段被命名的正文**(而非过程) |
|
||||
| 参数观 | **正文中未确定的量**(角色,具名) |
|
||||
| 调用观 | **代入**(可读作"按…代入…") |
|
||||
| 抽象时机 | **可选提升**:默认就地展开,需要复用时才命名 |
|
||||
| 唯一新增约定 | **具名给值**(形态待定,但必须具名,理由见 §7) |
|
||||
| 保留"命令"语义 | 仅用于副作用(`print` 等),与"代入"分层 |
|
||||
| 条款 | 作为定义的一种段落形态(`凡…则…`),不另设机制 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你裁决
|
||||
|
||||
1. **是否接受"函数→命名 / 调用→代入"这个总重构?**
|
||||
若接受,后续所有语法讨论都在这条轴上做取舍。
|
||||
2. **§8 的三个难题**你的倾向是什么(尤其"是否接受不支持递归")?
|
||||
3. **"具名给值"的最小形态**:你更接受哪一种读感?
|
||||
- `**加倍(x=37)**`(像函数调用)
|
||||
- `按**加倍**,`x`=37`(像句子,但需要判定规则)
|
||||
- 表格给出角色(像配料表)
|
||||
4. 是否需要我把这份哲学立场,反向校验一遍**现有 1322 个函数**——
|
||||
看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?
|
||||
@@ -0,0 +1,335 @@
|
||||
# 语义探析:代码函数能否解释为一张 GFM 表
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`## 函数名` + `+ 参数` + 函数体,从某种角度能否解释成 GFM 表」 |
|
||||
| 方法 | 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古 |
|
||||
| 相邻 | [functions-as-values-evaluation.md](functions-as-values-evaluation.md) · [link-style-call-evaluation.md](link-style-call-evaluation.md) |
|
||||
| 关键前置 | [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话答案
|
||||
|
||||
**你的命题在 Marqdo 里已经实现了——但它实现的是「关于函数的表」,不是「函数本身」。**
|
||||
|
||||
```
|
||||
## 加一
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
*n+1*
|
||||
```
|
||||
|
||||
这张表**今天就能跑**,是既有特性(契约表,`tests/contracts/ok_contract.mq.md`)。
|
||||
它证明了:函数参数**确实可以**是一张 GFM 表。
|
||||
|
||||
但它只能**描述**参数,不能**声明**参数;它不含函数体,不决定 arity,也不能被调用。
|
||||
一句话划界:
|
||||
|
||||
> **表能描述外延(输入→结果)与签名(元数据),不能描述内涵(怎么算)。**
|
||||
> 而「调用」恰恰是内涵操作。
|
||||
> `[k](集合)` 是**投影已有数据**,`f(x)` 是**计算新数据**——
|
||||
> 只有 f 本身已经是「预先枚举好的表函数」时,两者才重合。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先固定事实:Marqdo 的表格几何(实测)
|
||||
|
||||
讨论前必须先把「表」的语义钉死,否则会建在错觉上。
|
||||
|
||||
| 形状 | 绑定结果 | 实验 |
|
||||
|------|---------|------|
|
||||
| 1 列 N 行 | `List`(列值) | 文档锁定 + 实测 |
|
||||
| ≥2 列 **1 行** | `Map`(表头→标量,即「记录」) | `{"档位":[1,2]}` 反例 → 单行才是记录 |
|
||||
| ≥2 列 **N 行** | `Map`(表头→**列列表**,列向聚合) | 实测 `{"档位":[1,2],"税率":[0.03,0.1]}` |
|
||||
| 首列标头为 `行` / `@` / `row` | `List[Map]`(**行向记录**,显式开启) | [tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 |
|
||||
|
||||
**关键点**:Marqdo 的默认是**列向**。多行多列表不是「一组记录」,
|
||||
而是「一列一个列表」。行向记录是**显式标记**才能开的形态,
|
||||
文档原话:「**不得**与默认列向字典静默混用」。
|
||||
|
||||
这一条直接决定了「行 = 参数」在 Marqdo 里**不是自然形态**:
|
||||
按默认几何,`| 参数 | 类型 |` 两行参数会变成
|
||||
`{"参数":["a","b"], "类型":["number","number"]}` —— 列向。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你的命题已经存在:契约表
|
||||
|
||||
`src/contract.rs:308` 的注释写得很清楚:
|
||||
|
||||
```
|
||||
/// 未绑定文档表(`Expr::Map`)→ 契约块。
|
||||
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
|
||||
/// - `Some(Err)`:契约形状但畸形 —— 必产诊断。
|
||||
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
|
||||
```
|
||||
|
||||
三条规则(`src/contract.rs:260-334`):
|
||||
|
||||
| 规则 | 实现 |
|
||||
|------|------|
|
||||
| 表头含 `参数`/`形参`/`param`/`arg` → 形参契约 | `PARAM_HEADERS` |
|
||||
| 表头含 `返回`/`return`/`result` → 返回契约 | `RETURN_HEADERS` |
|
||||
| **必须含 `类型` 列**,否则视为普通说明表 | `TYPE_HEADERS` 缺失 → `return None` |
|
||||
|
||||
也就是说:**「函数参数表」不仅可能,而且已经是正式语法**。
|
||||
第一列标头(`参数` / `返回` / `字段`)扮演的正是
|
||||
[tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 里
|
||||
`行`/`@`/`row` 那种**形态标记**的角色:显式声明「这张表是干什么用的」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 但它是「关于参数的表」,不是「参数本身」
|
||||
|
||||
11 组实验里最关键的 6 组(全部实跑):
|
||||
|
||||
| # | 写法 | 实测结果 | 说明 |
|
||||
|---|------|---------|------|
|
||||
| E1 | 参数表列 `n`,函数体不读 `n` | `> f` 无参调用**成功**,`n` 不是形参 | 表不能声明形参 |
|
||||
| E3 | 叙述声明 `n` + 参数表 + 传 `"七"` | `参数 n 期望 number,实际 text(契约校验)` | **表能校验** |
|
||||
| E4 | 叙述声明 `n`,**无表** + 传 `"七"` | `七1` | 无表则不校验 |
|
||||
| E5 | `+ \`n\`` 旧式形参行 + 参数表 + 传 `"七"` | 同 E3,报契约错 | **你的草图形态可用** |
|
||||
| E6 | 表写 2 行(`a`,`b`),体只读 `a` | `too many positional arguments` | **表 ≠ arity** |
|
||||
| E7 | 单列参数表 `\| 参数 \|` + `\| n \|` | `七1`,**契约静默失效** | 1 列 = List,不成契约 |
|
||||
| E8 | 表里重复两行 `n` | 取**首行**类型,无诊断 | 表内重复静默 |
|
||||
| E9 | 表里有 `ghost`(体里没有) | 静默忽略 | 幽灵行静默 |
|
||||
| E10 | 同一张表加 `` `tc` = `` 绑定 | `七1`,契约**消失** | 绑定 → 变数据 |
|
||||
|
||||
**E10 揭示了一条隐含且优雅的规则**:
|
||||
|
||||
> **未绑定的表 = 声明/元数据(契约);绑定的表 = 数据。**
|
||||
|
||||
这正是语言对「表可以是声明吗」给出的既有答案:可以,**但前提是它不是一个值**。
|
||||
一旦你给它起名字(`` `tc` = ``),它就从「关于函数的声明」降级为「一个普通数据值」。
|
||||
|
||||
E6 + E7 + E8 + E9 合起来说明:**表与真实签名之间今天就可能漂移,而且是静默的**
|
||||
(`marqdo check e7.mq.md` 输出「无契约问题」)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若让表成为「定义」,运行时会发生什么
|
||||
|
||||
把上面的静默漂移从「少个校验」升级成「少个参数」,风险等级完全不同。
|
||||
|
||||
| 风险 | 今天(表=注解) | 若表=定义 |
|
||||
|------|----------------|-----------|
|
||||
| 漏写 `类型` 列 | 契约静默失效(E7) | **参数静默消失**,调用直接错 arity |
|
||||
| 表行数 ≠ 体读取数 | 表多余行被忽略(E6/E9) | **接口由表决定**,体重构后表未改 → 运行期崩 |
|
||||
| 重复行 | 取首行(E8) | **参数重复定义**,行为取决于解析器取舍 |
|
||||
| 表行重排 | 无影响(顺序由声明序决定) | **改变位置参数绑定顺序** → `> f 1 2` 含义变了 |
|
||||
| 加名字绑定 | 变数据(E10) | 语义分叉:什么时候是函数、什么时候是数据? |
|
||||
|
||||
最后一条最致命。**表是「可自由编辑的文档」**:调整行序、增删说明列、
|
||||
甚至把两张表合并,都是正常的写作行为。一旦表的行序决定位置参数绑定,
|
||||
「把 `b` 那行移到 `a` 上面」这个无害的编辑动作就**改变了程序行为**。
|
||||
|
||||
而 Marqdo 的核心承诺是「**文档即程序,且文档可被人阅读与维护**」。
|
||||
让排版顺序携带语义,等于给每张表埋一颗静默的雷。
|
||||
|
||||
对比一下:`[键](集合)` 之所以安全,是因为**键是显式的**,
|
||||
取元不依赖顺序。而位置参数天然依赖顺序——所以**签名不该用表承载顺序**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 为什么链接式调用 `[f](args)` 走不通(第三次论证,这次有史料)
|
||||
|
||||
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1:
|
||||
|
||||
> 心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
|
||||
```
|
||||
|
||||
§4「非目标」明确排除:点号 map 访问、`在`、箭头取元、`(键)[集合]`。
|
||||
[call-arguments.md](call-arguments.md) §2 同样锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` **不是「还没决定的语法」,而是已被明确分配给取元**。
|
||||
让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。
|
||||
|
||||
而且这与 §4 的表问题**同源**:都是「同一个外形要承载两种语义」,
|
||||
只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史:这条路走过,而且是被**反向**走过的
|
||||
|
||||
这是本轮考古最有价值的发现。四条史料:
|
||||
|
||||
### 6.1 v0.2 要求手写形参表 → v0.3 明确废除
|
||||
|
||||
[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §1 把 v0.2 的做法列为**代价**:
|
||||
|
||||
| v0.2 | 代价 |
|
||||
|------|------|
|
||||
| 形参必须 `` + `名` `` | **仪式感强;函数头像「另一套签名语言」,与正文脱节** |
|
||||
|
||||
§2 P4 直接给出新方针:
|
||||
|
||||
> **P4 — 形参由体推断(Body-inferred params)**
|
||||
> **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容)
|
||||
|
||||
§5 对照表把 `+ 名` 标为「**过渡兼容**:显式形参;**新代码不推荐**」。
|
||||
|
||||
**结论**:Marqdo 的发展方向是**离「声明式签名」越来越远**,转向「叙述即签名」。
|
||||
把参数改写成表,是在这条已经走反了的路上再走一遍。
|
||||
|
||||
### 6.2 「用表声明 schema」是明文非目标
|
||||
|
||||
[objects.md](objects.md) §6 非目标:
|
||||
|
||||
> - 用表格声明字段 schema(**表格仍表示数据集合**;见 tables-maps-footnotes.md)
|
||||
|
||||
路线图里同样列为非目标:
|
||||
|
||||
> 用表声明对象字段 schema(仍见 objects 非目标;**与数据集合分开**)
|
||||
|
||||
**结论**:语言已明确决定「表管数据,不管声明」。契约表是这一原则的**受控例外**——
|
||||
它只提供注解与校验,不提供绑定。
|
||||
|
||||
### 6.3 行向记录必须显式标记,且「不得静默混用」
|
||||
|
||||
[tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) §3.3:
|
||||
|
||||
> **备选语义(不默认):行向记录列表** …… 若未来需要,用显式标记区分,
|
||||
> **不得**与默认列向字典静默混用。
|
||||
|
||||
§3.5 落地了 `行`/`@`/`row` 标记。
|
||||
|
||||
**结论**:凡是「形态会改变语义」的地方,Marqdo 一律要求**显式标记**。
|
||||
「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式——
|
||||
而契约表的 `参数`/`返回` 头,正是这个显式标记的现成形态。
|
||||
|
||||
### 6.4 取元曾被反复挑选,最后选定链接形
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §3 记录了迁移史:
|
||||
脚注形 `` 集合[^键] ``(左键右基)→ 链接形 `[键](集合)`(左键右基,更好读)。
|
||||
|
||||
**结论**:`[…](…)` 这块语法是被**反复权衡后定下来的**,不是随手占用。
|
||||
|
||||
---
|
||||
|
||||
## 7. 诚实的收益清单
|
||||
|
||||
不能只讲风险。这条路确实有真收益:
|
||||
|
||||
| 收益 | 现状 | 潜力 |
|
||||
|------|------|------|
|
||||
| **人读** | 契约表已能带类型+说明,比 `+ 名` 可读得多 | 正是 v0.3 批评 `+` 行「仪式感」的解药 |
|
||||
| **调用边界校验** | 已实现(E3) | 可扩展到更多类型(枚举、范围) |
|
||||
| **机器读:tool schema** | ⚠️ 半成品:`tools` 已能写成记录行(`tool_names` 接受含 `name`/`工具` 字段的对象),但 `agent_format_tools` **只渲染名字**(`- name`),说明与参数被丢弃 | 若函数暴露签名,工具可带 schema 与说明,实参可校验 |
|
||||
| **机器读:CLI/表单** | ❌ 无 | 签名即表 → 直接生成命令行参数解析、Web 表单 |
|
||||
| **文档一致性** | ❌ 表与体可静默漂移(E6/E9) | 可做成「漂移即报错」 |
|
||||
|
||||
最后三行是**最有价值的**。最典型的是 tool schema:`tools` 的数据形态**已经允许**每行带说明,
|
||||
但渲染器只取名字——也就是说**能力已经在那儿,只差把签名接上去**。
|
||||
这不需要把表变成定义,只需要让签名**可被投影成表**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议:表做声明,不做定义(并补三件事)
|
||||
|
||||
### 8.1 结论
|
||||
|
||||
| 主张 | 裁决 |
|
||||
|------|------|
|
||||
| 函数参数可以用 GFM 表**描述** | ✅ **已经是特性**,继续用 |
|
||||
| 函数参数可以由 GFM 表**声明**(表即真相) | ❌ 不建议:顺序携带语义、静默漂移、与 v0.3 方向相反 |
|
||||
| 函数**本身**(含函数体)= 表 | ❌ 不可行:体是代码不是数据(见 functions-as-values §4.2) |
|
||||
| `[f](args)` 链接式调用 | ❌ 已被明确分配给取元 |
|
||||
|
||||
**保持现有分工**:
|
||||
|
||||
> 未绑定的表 = 声明(契约);绑定的表 = 数据;**函数体与 arity 是唯一真相**。
|
||||
|
||||
### 8.2 该补的三件事(都低成本,且都是「消灭静默」)
|
||||
|
||||
**① 让漂移显式化(最高价值)**
|
||||
|
||||
现状:表写 2 行、体只读 1 个 → 静默忽略(E6/E9);1 列 → 静默失效(E7)。
|
||||
建议 `marqdo check` 增加诊断:
|
||||
|
||||
| 情形 | 现在 | 应改为 |
|
||||
|------|------|--------|
|
||||
| 契约表缺 `类型` 列 | 静默视为普通表 | 若表头含 `参数`/`返回` 则 **warn**:缺 `类型` 列,已按说明表忽略 |
|
||||
| 契约表列数不齐 | 有诊断(`Some(Err)`) | 保持 |
|
||||
| 表里的参数名不在真实 arity 内 | 静默忽略 | **warn**:`ghost` 不是本函数的形参 |
|
||||
| 表头重复参数名 | 取首行 | **warn**:重复声明 |
|
||||
|
||||
这与本轮 D9「未闭合引号静默吞行」是同一类问题——**静默类缺陷**优先修。
|
||||
|
||||
**② 反向生成:签名 → 表(满足「语法很美」)**
|
||||
|
||||
既然表是好的**呈现**,就让工具来生成它,而不是让人手写:
|
||||
|
||||
```
|
||||
marqdo view --signature 文件.mq.md # 从体推断的签名生成契约表草案
|
||||
```
|
||||
|
||||
单一真相仍是函数体,表是**投影**。这样既拿到「签名即表」的可读性,
|
||||
又不引入第二真相。人也可以手写表,`check` 负责校验它与体一致(即 ①)。
|
||||
|
||||
**③ 让签名可供机器消费**
|
||||
|
||||
把 `Function` 的签名(名、参数、类型契约)暴露成结构化数据(如
|
||||
`marqdo knowledge` 的能力条目里带上参数 schema),
|
||||
`ext/ai` 的工具即可从「只渲染名字」升级为「带 schema 与说明的工具」。
|
||||
这是 §7 里最实的收益,且**零语法改动**。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一个可以试的新写法(示例,供你评判)
|
||||
|
||||
如果你想保留「表 + 函数体」的书写快感,最安全的形态是**双写 + 一致性校验**:
|
||||
|
||||
```markdown
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 档位 | number | 1/2/3 档 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 适用税率 |
|
||||
|
||||
- [行](`税率表`)
|
||||
**hit = [档位](`行`)**
|
||||
1. `hit`
|
||||
...
|
||||
*[税率](`行`)*
|
||||
```
|
||||
|
||||
| 优点 | 缺点 |
|
||||
|------|------|
|
||||
| 人读极好(表 + 正文) | 与真实签名可能漂移(需 ① 的校验兜住) |
|
||||
| 已经是**今天可跑**的语法(E5 验证) | `+ 行` 是 v0.3 标注「新代码不推荐」的旧形态 |
|
||||
| 类型校验已生效(E3) | 表不能替代体推断,参数仍要声明 |
|
||||
|
||||
**要点**:这张表**不是**函数的定义,而是它的**仪表盘**。
|
||||
真正的接口由 `+ 档位`(或叙述声明)决定,表负责类型与说明。
|
||||
只要两者不一致就报错,这套写法就既美又安全。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **裁决**:是否接受「表做声明、不做定义」(§8.1)?
|
||||
2. **优先级**:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费)
|
||||
先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
|
||||
3. **是否要我把 `+ 行` 加契约表的组合**写成教程样例(§9),
|
||||
并明确标注「`+` 是兼容形态、新代码优先叙述声明」?
|
||||
4. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
|
||||
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
|
||||
在小范围金样里验证是否可控。要我做吗?
|
||||
@@ -0,0 +1,469 @@
|
||||
# 方案评估:函数能否作为变量的一种(函数即表)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「函数本身可以理解为 `` `函数名` = `` + 参数/函数体表;此时和表格取元有极大相似性」 |
|
||||
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [spaced-function-names-d8.md](spaced-function-names-d8.md) · [function-as-table-semantics.md](function-as-table-semantics.md)(后续:函数与表格的语义考古,11 组实验) |
|
||||
| 影响面 | 值模型 / 调用语义 / 契约 / EKC 指纹 / 字节码 / 序列化 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**你的直觉在数学上是对的,但在语言上要拆成三种强弱不同的主张**:
|
||||
|
||||
| 主张 | 是否已成立 | 代价 |
|
||||
|------|-----------|------|
|
||||
| 弱:函数**名**可当数据传递 | ✅ **今天就能做**(字符串 + `call_fn`),但零参、不可静态检查 | 无 |
|
||||
| 中:函数是**一等值**(可存、可传、可返回) | ❌ 需要新值类型 + 动态 callee | 中高:契约、指纹、字节码、序列化全都要动 |
|
||||
| 强:函数**就是表**(结构性、可遍历、可序列化) | ❌ 需要把代码降格为数据 | **高**:与「代码即文档」的静态可索引性冲突 |
|
||||
|
||||
**建议**:把你草图里真正有价值的那部分(**有限域决策表**)作为一等公民支持——它今天就成立、
|
||||
且极其契合 Marqdo 的表格优先哲学;而「函数即表」的强主张不建议采纳,理由见 §4、§6。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先把「函数是变量」拆开
|
||||
|
||||
这四个概念经常被混为一谈,必须分开,否则讨论会滑。
|
||||
|
||||
### 1.1 外延观(extensional)——函数是「图」
|
||||
|
||||
数学上函数就是一组有序对 $f = \{(a,1),(b,2)\}$,即它的**图像**。
|
||||
按这个观点,函数**确实是一张表**,调用就是**查表**。
|
||||
|
||||
**但这里有一个必须先说清的实测事实**(我最初也想当然写错了):
|
||||
|
||||
GFM **两列表绑定成「列映射」,不是「按首列键控的映射」**:
|
||||
|
||||
```markdown
|
||||
`税率` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
```
|
||||
|
||||
```json
|
||||
{"档位":[1,2],"税率":[0.03,0.1]}
|
||||
```
|
||||
|
||||
所以 `[2](`税率`)` **不是**取税率,而是:
|
||||
|
||||
```
|
||||
error: missing map key `2`
|
||||
```
|
||||
|
||||
真正能「键 → 值」查表的形态是 **Map**(来自 JSON 或库函数),实测两条可用配方:
|
||||
|
||||
**配方 A(推荐,最简)**
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}**
|
||||
**t = [2](`税率`)** # → 0.1
|
||||
```
|
||||
|
||||
**配方 B(保留 GFM 表格可读性,但需显式索引)**
|
||||
|
||||
```markdown
|
||||
**ks = [档位](`税率`)** # [1, 2]
|
||||
**vs = [税率](`税率`)** # [0.03, 0.1]
|
||||
**i = > table.index_of list=`ks` item=2** # 1
|
||||
**r = > table.at xs=`vs` i=`i`** # 0.1
|
||||
```
|
||||
|
||||
两条都在 1.5.2 上跑通了。**结论**:外延观的「函数=表」在 Marqdo 里不是
|
||||
`[k](表)` 一句话就能实现,而是「**取到键值对**」这件事本身需要配方。
|
||||
这恰好是一个可补的库缺口(见 §8.1)。
|
||||
|
||||
### 1.2 内涵观(intensional)——函数是「规则」
|
||||
|
||||
`f(x) = x² + 1` 无法写成有限表(定义域无穷)。此时函数是**代码**,调用是**执行**。
|
||||
|
||||
### 1.3 闭包观——函数是「代码 + 环境」
|
||||
|
||||
参数之外还要捕获外部变量。这需要运行时的环境快照。
|
||||
|
||||
### 1.4 名字观——函数是「命名空间里的一条」
|
||||
|
||||
今天 Marqdo 就是这一种:函数存在于 `Module.functions`,按名字解析。
|
||||
|
||||
**你的草图 `|参数|函数体|` 属于哪一种?** 它是**混合体**:行是参数声明(§1.4 的味道),
|
||||
单元格放函数体(§1.2 的味道)。而「和表格取元相似」的直觉来自 §1.1。
|
||||
**三种东西被一句话连起来了**——这正是评估要解开的结。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状实测(全部在 1.5.2 上跑过)
|
||||
|
||||
### 2.1 值模型里没有函数
|
||||
|
||||
`src/value.rs:15` 的 `Value` 枚举:`None / Bool / Int / Num / Text / List / Map / Formula / Code / Secret`。
|
||||
**没有 `Func`。** 函数是 AST 节点(`src/ast.rs:58 Function`),挂在 `Module.functions`(`src/ast.rs:27`)。
|
||||
|
||||
`src/contract.rs:104` 的 `type_of` 同样是十种,穷举无函数。
|
||||
|
||||
### 2.2 调用的 callee 是静态名字,不是表达式
|
||||
|
||||
`src/ast.rs:130 CallExpr { callee: String, path, receiver, args }` ——
|
||||
`callee` 是 **`String`**,不是 `Expr`。所以**语法上无法写出「对计算出来的值发起调用」**。
|
||||
|
||||
运行期 `src/interp.rs:1119 eval_call` 最终走到 `lookup_function`(`src/interp.rs:1774`),
|
||||
按名字在 AST 树里查找。
|
||||
|
||||
### 2.3 对象已经是「表」
|
||||
|
||||
`src/interp.rs:1509 instance_type_name` 要求 method receiver 是**带 `_type` 键的 Map**:
|
||||
|
||||
```
|
||||
error: method receiver needs a map with `_type`
|
||||
```
|
||||
|
||||
也就是说 **Marqdo 里「用户定义的结构」本来就是普通 map + 一个标签**。
|
||||
对象与表之间没有鸿沟——**这与你的直觉一致,而且已经是既成事实**。
|
||||
|
||||
但函数不是。对象是值,函数不是。这个不对称值得注意。
|
||||
|
||||
### 2.4 已存在按名字间接调用:`call_fn`
|
||||
|
||||
`src/interp.rs:1295`:
|
||||
|
||||
```rust
|
||||
"call_fn" => {
|
||||
// name 必须是 text
|
||||
let target = lookup_function(module, fun, name)...;
|
||||
if !target.params.is_empty() {
|
||||
return Err("call_fn: `{name}` must have no parameters");
|
||||
}
|
||||
self.run_function(module, target, Env::new(), &[], false)
|
||||
}
|
||||
```
|
||||
|
||||
这是**今天最接近「函数可传递」的机制**,但有三道硬限制:零参、限当前模块、只在运行期校验。
|
||||
|
||||
### 2.5 六组实验
|
||||
|
||||
| # | 写法 | 结果 | 结论 |
|
||||
|---|------|------|------|
|
||||
| 1 | `**f = > greet**` | `missing argument for parameter who` | `> 名字` 是**调用**语法,**无法引用函数本身** |
|
||||
| 2 | `> call_fn name="hello"`(无参函数) | `world` | 按名字调用可行 |
|
||||
| 3 | `> call_fn name="add"`(有参) | `call_fn: `add` must have no parameters` | 不能传参 |
|
||||
| 4 | 表里存函数名 + `[h](reg)` 取名 + `call_fn` | `dispatch=world` | **动态派发今天就能做**(名字即数据) |
|
||||
| 5 | `> call_fn name="txt.str_trim"` | `unknown function` | **不能跨模块** |
|
||||
| 6 | `> call_fn name="no_such_fn"` | `unknown function` | 拼错只能在**运行期**发现 |
|
||||
|
||||
**实验 4 是关键**:它已经是「函数作为表成员」的可用原型,只是把函数表示成**名字字符串**而不是函数值。
|
||||
|
||||
---
|
||||
|
||||
## 3. 你的类比中成立的部分
|
||||
|
||||
必须明确肯定,否则会低估这个想法。
|
||||
|
||||
### 3.1 「有限域函数 = 表」是完全成立的范式
|
||||
|
||||
这类函数在工程里非常常见,而且用它表达比写代码更清楚:
|
||||
|
||||
| 场景 | 适合表格 | 为什么 |
|
||||
|------|---------|--------|
|
||||
| 税率 / 费率档位 | ✅ | 有限、离散、常改动 |
|
||||
| 状态机转移表 | ✅ | 二维查表一目了然 |
|
||||
| 错误码 → 处理动作 | ✅ | 业务方直接维护 |
|
||||
| 路由分发 | ✅ | 键即路径 |
|
||||
| 配置映射 | ✅ | 本来就是数据 |
|
||||
|
||||
而且 Marqdo 的 `[键](集合)` 取元**在语义上就是函数应用** ——
|
||||
前提是这个集合是 **Map**(键→值):
|
||||
|
||||
```markdown
|
||||
**rate = [2](`税率`)** # 读作:税率(2)
|
||||
```
|
||||
|
||||
只要 `税率` 是 Map,这行**无需任何语言改动**就是一个查表函数。你已经拥有它了。
|
||||
|
||||
唯一的坑是**数据形态要对**:GFM 两列表绑定的是**列映射**(§1.1 实测),
|
||||
`[2](两列表)` 会报 `missing map key`。所以「表 = 函数」成立,
|
||||
但**哪种表**有讲究——这正是 §8.1 要补 `table.by_column` / `table.lookup` 的原因。
|
||||
|
||||
### 3.2 表格对「参数边界」天然友好
|
||||
|
||||
上一轮讨论 `[函数名](参数)` 时,痛点是参数边界(空格切词)。表格完全绕开这个问题:
|
||||
键是**显式**的,不需要切词。
|
||||
|
||||
### 3.3 对象已证明「结构即表」不会损害语言
|
||||
|
||||
§2.3 说明对象本来就是 map。既然对象能这样,把**数据的**函数化交给表格是自洽的。
|
||||
|
||||
---
|
||||
|
||||
## 4. 类比的断裂点
|
||||
|
||||
三个,每一个都是硬约束。
|
||||
|
||||
### 4.1 断裂点一:表格是有限的,函数通常是无限的
|
||||
|
||||
外延观只对**有限定义域**成立。`f(x)=x²+1` 写成表需要无限行。
|
||||
所以「函数即表」只能覆盖**查表能解决的那部分**,不能作为函数的通用表示。
|
||||
|
||||
一旦你承认这一点,「函数即表」就从「函数的定义方式」降级为「一种特殊函数(图表函数)」。
|
||||
这仍然有用,**但不是语言的核心函数机制**。
|
||||
|
||||
### 4.2 断裂点二:函数体是**代码**,不是数据
|
||||
|
||||
你的草图把「函数体」放进单元格。但函数体在 Marqdo 里是 `Vec<Stmt>`(AST),不是 `Value`。
|
||||
要让函数体成为单元格内容,必须先让「代码」成为值——即 `Value::Code` 那种东西。
|
||||
|
||||
而 `Value::Code` 目前**只表示外联语言源码**(```lang 围栏),是交给外部执行器跑的,
|
||||
不是 Marqdo 自己的代码。让 Marqdo 代码变成值 = 引入 `eval`,这会带来:
|
||||
|
||||
- 静态检查失效(代码在运行期才成形,`marqdo check` 看不见)
|
||||
- EKC 指纹失效(§6.2)
|
||||
- 契约失效(§6.1)
|
||||
|
||||
### 4.3 断裂点三:调用不是取元——`[k](x)` 会被语义重载
|
||||
|
||||
这是最要命的一条,**与上一轮 `[函数名](参数)` 的冲突同源**。
|
||||
|
||||
若「函数是表」且「调用 = `[参数](函数表)`」,那么:
|
||||
|
||||
```markdown
|
||||
[a](m) # m 是普通 Map → 取成员 a
|
||||
[参数](f) # f 是「函数表」→ 执行?还是取成员「参数」?
|
||||
```
|
||||
|
||||
**形状完全一致,含义取决于值的类型**。这正是上一轮我们判定「不可靠消歧」的同一类问题,
|
||||
只不过从「语法层歧义」升级成了「类型层重载」。
|
||||
|
||||
Marqdo 的 `[k](coll)` 目前是**唯一且清晰**的取元语义。让它兼职「调用」,
|
||||
会让最常用的读表操作变得需要思考「这个表是不是函数」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 五条设计路径
|
||||
|
||||
### 路径 A — `Value::Func` 闭包(一等函数)
|
||||
|
||||
```rust
|
||||
Value::Func(Rc<FuncVal>) // params + body + captured Env
|
||||
```
|
||||
|
||||
调用点需支持「对表达式求值后再调用」,即 `CallExpr.callee` 从 `String` 变成 `Callee::Name(String) | Callee::Expr(Expr)`。
|
||||
|
||||
**代价**:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约(T2.1/T2.2) | `call_arg_diag(c, &target.name, …)` 依赖静态 `target: &Function`;动态调用**拿不到**,契约检查只能退化为运行期 |
|
||||
| 字节码 | `Op::Call(fid, argc)` 用**编译期函数 id**(`src/bytecode/compile.rs:709`),动态 callee 需要新指令或回退树遍历 |
|
||||
| EKC 指纹 | `collect_calls` 读 `c.callee`(`src/knowledge/fingerprint.rs:76`),动态调用只剩字面 `call_fn`,**复用/查重能力下降** |
|
||||
| 序列化 | `value_to_json`(`src/host/json.rs:98`)对 `Value` 穷举,函数值必须定义 JSON 语义(丢弃?报错?) |
|
||||
| 沙箱 | 函数值无法跨沙箱边界,`sandbox.run` 的接口要加限制 |
|
||||
| 闭包捕获 | 需要环境快照与生命周期管理;`Env` 目前是每次调用新建(`Env::new()`) |
|
||||
|
||||
**适用于**:确有高阶需求(回调、map/filter、事件处理)。属于**新语言特性**,应走 ADR。
|
||||
|
||||
### 路径 B — 函数即表(你的草图,强主张)
|
||||
|
||||
**代价**:A 的全部,**外加** §4.3 的语义重载,以及:
|
||||
|
||||
- 表可以 `table.put` 被修改 → 函数可变?还是只读?
|
||||
- 表可以遍历 → 遍历函数会看到什么?参数名?函数体 AST?
|
||||
- 表可以 `json.stringify` → 函数体以什么形式序列化?
|
||||
- 宏展开式的能力(代码即数据)会引入**自修改程序**,与「可静态审计」直接冲突
|
||||
|
||||
**结论**:**不建议**。它把 Marqdo 从「可静态索引的文档程序」推向「运行期构造的代码」,
|
||||
是在削弱自己最强的差异点(§6)。
|
||||
|
||||
### 路径 C — 对象可调用(复用 `_type` + 约定方法)
|
||||
|
||||
让 `# 类名` 实例在 `_type` 之外带一个约定的 `## 应用` 方法,`f(x)` 时若 `f` 是 map 且 `_type` 有该方
|
||||
法则走方法调用。
|
||||
|
||||
**优点**:不新增 `Value` 变体;复用既有 method 机制。
|
||||
**缺点**:仍需要「`f(x)` 里 f 是表达式」这一语法能力(同 A 的调用点改造);
|
||||
且引入「有的 map 可调用」的隐式规则,可读性下降。
|
||||
|
||||
### 路径 D — 名字即函数(扩展现有 `call_fn`)
|
||||
|
||||
不引入函数值,而是把**名字**这条路径做完整:
|
||||
|
||||
```markdown
|
||||
> call_fn name="add" args=[1, 2] # 支持传参
|
||||
> call_fn name="txt.str_trim" args=[…] # 跨模块路径
|
||||
> invoke table=`注册表` key="h" args=[…] # 从表里按名派发
|
||||
```
|
||||
|
||||
**优点**:
|
||||
- 零值模型改动 → 契约、字节码、指纹、序列化**全部不动**
|
||||
- 保持「函数永远有名字」→ EKC 能索引,代码可审计
|
||||
- 与实验 4 的现有用法完全兼容(只是补齐能力)
|
||||
|
||||
**缺点**:不是真正的一等函数(不能返回闭包);名字拼错仍要运行期发现
|
||||
(但**可以**加静态检查:`call_fn name="字面量"` 时校验目标存在——见 §8.2)。
|
||||
|
||||
### 路径 E — 决策表作为一等公民(**推荐方向**)
|
||||
|
||||
不叫它「函数即表」,而明确它是什么:**有限域查表函数**。
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}** # Map:键 → 值
|
||||
**t = [2](`税率`)** # 今天就能跑 → 0.1
|
||||
```
|
||||
|
||||
**优点**:**零语言改动**,只需文档与库函数支持(例如 `table.lookup` 带默认值,
|
||||
把 §1.1 配方 B 的「列取 + 索引」四步压成一步)。
|
||||
**定位诚实**:它是数据,不是代码;能被 EKC 索引、能序列化、能进沙箱、能被非程序员维护。
|
||||
|
||||
---
|
||||
|
||||
## 6. 对 Marqdo 特有机制的冲击面
|
||||
|
||||
这一节是决策的关键:Marqdo 不是通用语言,它的价值在**可静态索引的工程知识**。
|
||||
|
||||
### 6.1 契约系统(T2.1 / T2.2)
|
||||
|
||||
现有实现把契约挂在 `Function` 上(`src/ast.rs:71`),并在调用点用**静态 target**校验:
|
||||
|
||||
```rust
|
||||
if let Some(c) = &target.contract {
|
||||
if let Some(d) = contract::call_arg_diag(c, &target.name, &bound, …) { … }
|
||||
}
|
||||
```
|
||||
|
||||
动态 callee 拿不到静态 `target`,**契约检查必然退化到运行期**——而契约是 Marqdo
|
||||
「渐进式契约」卖点的核心。
|
||||
|
||||
### 6.2 EKC 指纹与复用
|
||||
|
||||
`collect_calls` 把调用目标名字写进指纹(`src/knowledge/fingerprint.rs:76`)。
|
||||
指纹用于**查重、复用预检、相似任务召回**。动态调用使指纹丢失真实目标,
|
||||
`marqdo duplicate` / `preflight` 的准确率会下降——这直接影响智能体复用飞轮。
|
||||
|
||||
### 6.3 「函数必须有名字」是特性,不是限制
|
||||
|
||||
EKC 按符号名索引(`marqdo knowledge` 输出 `59 modules, 346 symbols`)。
|
||||
匿名函数/表构造的函数**无法被索引**,也就无法被复用、被审计、被智能体发现。
|
||||
|
||||
> 对 Marqdo 而言,**函数有名字**不是妥协,而是「代码即文档」的必然:
|
||||
> 文档里的每一段代码都得有一个可被引用的标题。
|
||||
|
||||
### 6.4 序列化与沙箱
|
||||
|
||||
`value_to_json` 穷举所有 `Value`。函数值需要 JSON 语义;
|
||||
沙箱(CoW + 禁 exec/net/plugin)跨边界传值时,函数**无法表示**。
|
||||
一旦函数成为值,`sandbox.run` 的入参约束必须收紧。
|
||||
|
||||
### 6.5 确定性与可审计
|
||||
|
||||
表格是**静态可读**的:非程序员能改税率表。代码构造的函数则要求读者在脑中执行程序。
|
||||
Marqdo 面向的是「文档作者也能维护」的场景,这一点权重很高。
|
||||
|
||||
---
|
||||
|
||||
## 7. 方案对比
|
||||
|
||||
| 维度 | A 闭包 | B 函数即表 | C 可调用对象 | D 扩展 call_fn | E 决策表 |
|
||||
|------|--------|-----------|-------------|---------------|----------|
|
||||
| 值模型改动 | **需新变体** | 需新变体+代码即值 | 无 | **无** | **无** |
|
||||
| 保持静态可索引 | 部分(匿名不可) | ❌ | ✅ | ✅ | ✅ |
|
||||
| 契约检查 | **退化** | 退化 | 保持 | 保持 | 保持 |
|
||||
| EKC 指纹 | 退化 | 退化 | 保持 | 保持 | 保持 |
|
||||
| 序列化/沙箱 | 需特殊处理 | 需特殊处理 | 保持 | 保持 | 保持 |
|
||||
| 解决参数边界 | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| 支持无限定义域 | ✅ | ❌ | ✅ | ✅ | ❌(本质限制) |
|
||||
| 实现成本 | 高 | 很高 | 中 | **低** | **零** |
|
||||
| 风险 | 中高 | **高** | 中 | 低 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议(分阶段)
|
||||
|
||||
### 8.1 立即可做:决策表(路径 E)
|
||||
|
||||
零语言改动。补三件事即可让它好用:
|
||||
|
||||
1. **补库缺口**:新增 `table.lookup map=`key=`default=`(键→值,缺键返回 default)与
|
||||
`table.by_column rows=`key_col=`value_col=`key=`(把 §1.1 配方 B 的四步压成一步)。
|
||||
**这是当前最实的缺口**——GFM 两列表无法直接键查表,用户会反复手写索引逻辑。
|
||||
2. **文档**:在教程里明确「有限域映射怎么表达」,并给出三种形态的取舍:
|
||||
- 键→值查表 → `json.parse` 的 Map + `[键](map)`
|
||||
- 需要保留表格可读性 → 两列表 + `table.by_column`
|
||||
- 缺键行为 → 用 `table.get` / `default=`,避免缺陷 D5 的 `missing map key` 硬崩
|
||||
3. **命名**:明确它叫「决策表 / 查表」而不是「函数」——避免与 §1.2 的内涵观混淆。
|
||||
|
||||
**价值**:把用户已有的直觉固化成推荐用法,不付任何架构代价。
|
||||
|
||||
### 8.2 短期可做:扩展 `call_fn`(路径 D)
|
||||
|
||||
补齐三件事,都不触及值模型:
|
||||
|
||||
| 补充 | 说明 |
|
||||
|------|------|
|
||||
| `args=` | 允许传参,按目标签名绑定 |
|
||||
| 跨模块路径 | `name="lib.fn"` 走 import 解析 |
|
||||
| 字面量静态校验 | `call_fn name="字面量"` 在 `check` 期就校验目标存在(消灭实验 6 的类错误) |
|
||||
|
||||
**收益**:动态派发能力完整,且完全保留契约/指纹/序列化。
|
||||
|
||||
### 8.3 中期评估:一等函数(路径 A)
|
||||
|
||||
只有当出现**确实无法用名字表达**的需求时才做(例如回调、策略模式、事件处理器)。
|
||||
届时必须写 ADR,并明确回答:
|
||||
|
||||
- 匿名函数如何进入 EKC 索引?(可能需要要求「赋给变量的函数字面量必须有名字」)
|
||||
- 契约在动态调用下如何降级?
|
||||
- 字节码是否引入 `Op::CallValue`?
|
||||
- 函数值的 JSON 语义是什么?
|
||||
|
||||
### 8.4 不建议:路径 B(函数即表,强主张)
|
||||
|
||||
理由汇总:§4.3 语义重载 + §6 全面削弱静态可索引性 + §5 自修改程序风险。
|
||||
|
||||
---
|
||||
|
||||
## 9. 如果你想保留「函数即表」的形态,有一个折中
|
||||
|
||||
把「表」用于**参数与分发**,而不用于函数体:
|
||||
|
||||
```markdown
|
||||
`税率表` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
**ks = [档位](`税率表`)**
|
||||
**vs = [税率](`税率表`)**
|
||||
**i = > table.index_of list=`ks` item=`档位`**
|
||||
**r = > table.at xs=`vs` i=`i`**
|
||||
*r*
|
||||
```
|
||||
|
||||
(若 §8.1 的 `table.by_column` 落地,函数体可缩成一行:
|
||||
`**r = > table.by_column rows=`税率表` key_col="档位" value_col="税率" key=`档位`**`。)
|
||||
|
||||
这里:
|
||||
|
||||
- **数据**在表里(可被非程序员维护、可序列化、可进沙箱、可被 EKC 索引)
|
||||
- **逻辑**在命名函数里(可契约、可指纹、可审计)
|
||||
- 调用仍是一等清晰的 `> 税率 档位=2`
|
||||
|
||||
这其实是**最好的分工**:表格承担「知识」,函数承担「行为」。
|
||||
它同时满足你的类比直觉(表驱动)和 Marqdo 的静态可索引性。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **方向**:选 E(决策表,零改动)、D(扩展 call_fn)、还是 A(一等函数,需 ADR)?
|
||||
2. 若倾向 D:`args=` 的参数形式用 `[1, 2]`(列表)还是 `a=1 b=2`(具名)?
|
||||
3. 是否要我把 §9 的「数据在表、逻辑在函数」写成教程规范?
|
||||
4. 是否存在**具体用例**驱动一等函数?(例如某个 ext 需要回调)
|
||||
若有真实用例,评估会完全不同——请给我场景,我按场景重新评估。
|
||||
@@ -0,0 +1,414 @@
|
||||
# 纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(含语法落地、诊断 schema、分阶段计划) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 决策来源 | 用户:取**纯度**;标签**可省略但编译器须报错**;循环写法不重要;**重点:标签过期与 agent 误导** |
|
||||
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) |
|
||||
| 依托设施 | `src/diagnostics.rs`(`doc_anchor`/`doc_quote`/`contract_ref`)· `src/mlsp.rs`(`validate`/`repair_targets`/`repair_apply`)· `src/repair.rs`(有界修复)· `src/knowledge/fingerprint.rs` · `src/knowledge/lifecycle.rs`(已有 `find_stale`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 决策记录与一个推论
|
||||
|
||||
**已定**:
|
||||
|
||||
1. **纯度**:`()` 只装机器语句,`[]` 只装人话;取元搬进 `()`。
|
||||
2. **标签可省略,但编译器报错**:写空方括号是可能的,但那是一个**错误**。
|
||||
3. **循环写法从简**:`[]` 已是描述,`()` 内部只要自洽即可。
|
||||
|
||||
**由此得到一个必须先说清的推论**:
|
||||
|
||||
> **纯度强制两件东西同时存在**:
|
||||
> ① 一个**不带标签**的普通表达式写法(否则每个访问都被迫配一段人话 = 仪式感复辟);
|
||||
> ② 带标签的形式作为一个**可选包装**。
|
||||
|
||||
也就是说 `[标签](表达式)` 不是"唯一的表达式语法",而是"**当你想做断言时才用的包装**"。
|
||||
这一条同时解决了我在上一份文档里担心的"标签凑数"退化:
|
||||
**不想断言,就别用这个形式**——而不是"必须写标签但可以写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 1. 纯度路线下的语法落地
|
||||
|
||||
### 1.1 形式
|
||||
|
||||
```
|
||||
带标签表达式 ::= '[' 人话 ']' '(' 表达式 ')'
|
||||
```
|
||||
|
||||
- `表达式` = **现有 Marqdo 表达式文法**(不新增语言)
|
||||
- `人话` = 任意自然语言,必须是**关于这个值的断言**(§2)
|
||||
- 出现位置:表达式位置、语句位置、循环位置
|
||||
|
||||
### 1.2 关键缺口:普通取元怎么写
|
||||
|
||||
纯度之后 `[键](集合)` 不再是取元,所以必须给出**不带标签的取元写法**。四个候选:
|
||||
|
||||
| 方案 | 写法 | 优 | 劣 |
|
||||
|------|------|----|----|
|
||||
| **A 现有内建** | `[第一项](at value=篮子 index=1)` | 零新语法,今天就能实现 | 啰嗦;`value=`/`index=` 是机器腔 |
|
||||
| **B 后置方括号** | `[第一项](篮子[1])` | 最像通用语言;`篮子[拿铁]` 读起来自然 | `[]` 出现两种角色(前置=人话,后置=索引),视觉易混 |
|
||||
| **C 函数式 + 逗号参数** | `[第一项](at(篮子, 1))` | 与 `加一函数(31)` 统一;顺带解决前几轮想要的 `f(args)` | 需支持逗号分隔实参(要改参数分词器) |
|
||||
| D 点号 | `[拿铁价格](菜单.拿铁)` | 短 | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形 |
|
||||
|
||||
**我的建议**:**C**。
|
||||
|
||||
理由:你前面想要 `f(args)` 这种"人读友好"的调用,而 C 与它**同一个改动**——
|
||||
一次性把 `()` 内的表达式升级为「可带括号实参」的形式,
|
||||
`at(篮子, 1)`、`加一函数(31)`、`get(菜单, 拿铁)` 全部成立,且不新增第二种方括号角色。
|
||||
代价是参数分词器要支持 `)` 终止与逗号(前几轮原型已验证方向可行,全量 554/0 回归)。
|
||||
|
||||
若你希望**零实现风险**,选 A:今天就能用,只是啰嗦,后续可再收窄成 C。
|
||||
|
||||
### 1.3 空标签 = 硬错误
|
||||
|
||||
```markdown
|
||||
[](at(篮子, 1)) # ❌ label.missing
|
||||
```
|
||||
|
||||
诊断:`code: "label.missing"`,`severity: error`,`doc_quote: "[]"`,建议:
|
||||
「给这段语句写一句人话描述,或改用不带标签的普通表达式」。
|
||||
|
||||
**这一条是整套设计的门槛**:它把"标签"从可选装饰变成"用了就得负责"的承诺。
|
||||
也正好落实你说的「可以省略,但编译器应当报错」。
|
||||
|
||||
### 1.4 循环
|
||||
|
||||
你说不重要,那我给最省事、且与纯度一致的一条:
|
||||
|
||||
```markdown
|
||||
- [从篮子取出的每个果子](foreach 篮子 为 果)
|
||||
```
|
||||
|
||||
- `[]` 是描述(人读)
|
||||
- `()` 是机器语句:遍历什么、绑定给谁
|
||||
- 循环变量名从 `[]` **搬进 `()`**——因为 `[]` 不再承担绑定职责
|
||||
|
||||
若嫌 `foreach 篮子 为 果` 太新,可就近用现有词:
|
||||
`- [从篮子取出的每个果子](遍历 篮子 绑定 果)`。
|
||||
**关键是别再让 `[]` 兼任变量名**——否则"描述"与"标识符"又会打架。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标签是什么:**可校验断言的载体**
|
||||
|
||||
标签不是注释。三者区别:
|
||||
|
||||
| | 注释 | 标签 |
|
||||
|---|------|------|
|
||||
| 位置 | 游离于代码之外 | **锚定在 AST 节点上**(有 span,可定位) |
|
||||
| 可核验 | 不能 | **能**(§3) |
|
||||
| 可进修复协议 | 不能 | **能**(随诊断导出给 LLM) |
|
||||
| 变更感知 | 无 | **能**(代码变了会撞上旧断言) |
|
||||
|
||||
一句话:**标签 = 贴在可执行片段上、可被机器复核的断言。**
|
||||
这正是 Marqdo 相对传统"文档 + 注释"的核心增量。
|
||||
|
||||
---
|
||||
|
||||
## 3. 过期检测:三层机制
|
||||
|
||||
你问的核心是:**`()` 改了,怎么让 `[]` 的旧描述"叫起来"。**
|
||||
这需要三种能力,缺一不可,且分属不同层。
|
||||
|
||||
### 3.1 L1 引用一致性(无状态、确定性、零成本)
|
||||
|
||||
**规则**:标签内用反引号写出的名字 = **实体断言**。
|
||||
|
||||
```markdown
|
||||
[按 `税率` 计算总价](...)
|
||||
```
|
||||
|
||||
可核验的断言:
|
||||
|
||||
1. `` `税率` `` 必须**可解析**(在当前作用域/模块里存在)
|
||||
2. 它必须**出现在 `()` 的实际内容中**(或经调用链可达)
|
||||
|
||||
任一条不成立 → `label.stale`(引用已腐烂)。
|
||||
|
||||
**为什么低假阳性**:只有**显式反引号**才算断言,普通汉字不参与判定。
|
||||
这复用了 Marqdo 已有的 `` `名` `` = 实体 的约定,**没有新增记号**。
|
||||
|
||||
**局限(必须承认)**:它只查"引用",查不出"语义"。
|
||||
`税率` 还在,但操作从"乘"改成"除",L1 看不见。
|
||||
|
||||
### 3.2 L2 指纹台账(有状态、能查语义腐烂)
|
||||
|
||||
**做法**:把「标签写下时,它描述的那段代码」记一份指纹。
|
||||
|
||||
`.marqdo/labels.json`(与 EKC 产物同目录,视为**缓存**):
|
||||
|
||||
```json
|
||||
{
|
||||
"按税率计算总价#1": {
|
||||
"code_fingerprint": "9f2a…",
|
||||
"code_quote": "at(税率表, 档位) * 金额",
|
||||
"confirmed_at": "2026-10-22T09:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `code_fingerprint`:复用 `src/knowledge/fingerprint.rs`(已有 `collect_calls` / `ops_hint` / `fingerprint_hash`)
|
||||
→ **调用与运算变了,指纹就变**
|
||||
- `code_quote`:**旧代码的文本快照**——这就是你说的"保留内容用于校验"的对称物:
|
||||
`doc_quote` 保留 `[]`,`code_quote` 保留 `()`,两者一起导出给 LLM 对比
|
||||
- 键 = `规范化标签文本 + 同文本序号`(按标签键而不是按行号,**移动代码不会误报**)
|
||||
|
||||
**命中规则**:
|
||||
|
||||
| 变化 | 判定 |
|
||||
|------|------|
|
||||
| `()` 指纹变 | **stale**:标签描述的代码已变,需复核 |
|
||||
| 标签文本变 | **新断言**:无历史,首次确认即可 |
|
||||
| 两者都没变 | 通过 |
|
||||
|
||||
**局限**:需要状态文件;合并冲突要处理(§8.2)。
|
||||
|
||||
### 3.3 L3 LLM 复核(修复协议闭环)
|
||||
|
||||
诊断被导出时同时携带三方信息:
|
||||
|
||||
- `doc_quote`:`[]` 里的原话
|
||||
- `code_past`:`()` 当时的文本(来自台账)
|
||||
- `code_now`:`()` 现在的文本
|
||||
|
||||
模型据此判定三选一:
|
||||
|
||||
1. **改标签**(代码意图是对的,描述过期了)
|
||||
2. **改代码**(描述是对的,实现跑偏了)
|
||||
3. **确认无害**(改动不影响断言,写回台账 `confirmed`)
|
||||
|
||||
这正好接进**已有的修复回路**(`src/repair.rs`):`validate` → `repair_targets` → 模型行编辑 →
|
||||
`repair_apply`(越界必拒)→ 复验。
|
||||
|
||||
### 3.4 为什么三层都要
|
||||
|
||||
| 层 | 查什么 | 能否查"乘改除" | 需要状态 | 假阳性 |
|
||||
|----|--------|--------------|---------|--------|
|
||||
| L1 | 引用腐烂(改名/删除) | ❌ | 无 | 极低 |
|
||||
| L2 | 语义腐烂(同引用、不同操作) | ✅ | 需台账 | 中(无害改动也报) |
|
||||
| L3 | 谁错了(标签 or 代码) | ✅ | 复用 L2 | 由模型判 |
|
||||
|
||||
**L1 是地基**(确定性、零成本、可先上),**L2 是覆盖**(能查语义),**L3 是裁决**(谁改)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与现有设施的对接(这决定了落地成本)
|
||||
|
||||
### 4.1 诊断字段:**已经齐备,不需要新造**
|
||||
|
||||
`src/diagnostics.rs` 的 `to_json` 已输出:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "…", "severity": "…", "message": "…",
|
||||
"span": {"file":…, "line":…, "col":…},
|
||||
"doc_anchor": …, ← 标签位置
|
||||
"doc_quote": …, ← 标签原文
|
||||
"contract_ref": {"unit":…, "kind":…, "name":…, "declared":…},
|
||||
"suggestion": …
|
||||
}
|
||||
```
|
||||
|
||||
**`contract_ref.declared` 就是"声明"这一侧的先例**:
|
||||
契约诊断说的是「**declared** number,actual text」,
|
||||
标签诊断说的是「**declared(标签里的人话)**,actual(`()` 现在的代码)」——
|
||||
**同一个模式,只是从类型层下沉到散文层。**
|
||||
|
||||
> 这也回答了你的问题:"导出时能否保留 `[]` 的内容用于校验"——
|
||||
> **能,而且字段已经在协议里了**:`doc_quote` 就是它。
|
||||
|
||||
### 4.2 契约诊断是现成的范式
|
||||
|
||||
`src/contract.rs:203` 的 `Contract::diagnostic(...)` 一次性装配
|
||||
`code + severity + suggestion + doc_anchor + doc_quote + contract_ref`。
|
||||
标签诊断可以照抄这套装配,只是 `kind` 从 `"contract"` 换成 `"label"`。
|
||||
|
||||
### 4.3 修复范围:允许"标签行 ∪ 代码行"
|
||||
|
||||
现在 `repair_apply` 的形状是 `ranges: [[起, 止], …]`,**天然支持多个区间**。
|
||||
`label.stale` 只需把两段都放进 ranges:
|
||||
|
||||
| 允许范围 | 原因 |
|
||||
|---------|------|
|
||||
| 标签所在行 | 修法 1:改描述 |
|
||||
| `()` 所在行 | 修法 2:改实现 |
|
||||
|
||||
护栏不变:**越界改动一律拒绝(abstain)**——这正是 `src/repair.rs` 已经强制的语义。
|
||||
|
||||
### 4.4 知识层:`stale` 概念已经存在
|
||||
|
||||
`src/knowledge/lifecycle.rs` 已有 `find_stale` / `stale_json` / `verify`。
|
||||
标签过期可以走**同一条 stale 通道**,进入 EKC/OKF 的
|
||||
`marqdo verify` / `marqdo stale` 报告,成为知识库的健康指标。
|
||||
|
||||
> 这一点很重要:**标签过期 = 知识腐烂**,而 Marqdo 已经有"知识会腐烂"的机制,
|
||||
> 标签只是给它增加了一种新的腐烂类型(文档断言 vs 实现)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 诊断 schema 草案
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "label.stale",
|
||||
"severity": "warning",
|
||||
"message": "标签可能过期:标签提到 `税率`,但当前语句已不再引用它",
|
||||
"span": { "file": "报价.mq.md", "line": 42, "col": 12 },
|
||||
"doc_anchor": { "file": "报价.mq.md", "line": 42, "quote": "按 `税率` 计算总价" },
|
||||
"doc_quote": "按 `税率` 计算总价",
|
||||
"label_ref": {
|
||||
"kind": "label",
|
||||
"text": "按 `税率` 计算总价",
|
||||
"refs": ["税率"],
|
||||
"missing_refs": ["税率"],
|
||||
"code_past": "at(税率表, 档位) * 金额",
|
||||
"code_now": "at(税率表, 档位) / 金额",
|
||||
"fingerprint_past": "9f2a…",
|
||||
"fingerprint_now": "3c71…",
|
||||
"layer": "L2"
|
||||
},
|
||||
"suggestion": "若意图是乘,请还原 `*`;若意图改为除,请把标签改成「按档位折算比例」",
|
||||
"ranges": [[42, 42]]
|
||||
}
|
||||
```
|
||||
|
||||
要点:
|
||||
- 复用 `doc_anchor` / `doc_quote`,**不新造字段名**
|
||||
- `label_ref` 仿 `contract_ref`(`kind: "label"`)
|
||||
- `code_past` / `code_now` 并置 → 模型一眼看出差异
|
||||
- `layer` 标明是 L1 还是 L2 检出(便于分级治理)
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作流
|
||||
|
||||
```
|
||||
作者 / agent 改代码
|
||||
↓
|
||||
marqdo check 或 MLSP validate
|
||||
↓
|
||||
label.stale / label.missing 诊断(带 doc_quote + code_past + code_now)
|
||||
↓
|
||||
MLSP repair_targets(ranges = 标签行 ∪ 代码行)
|
||||
↓
|
||||
LLM 三选一:改标签 / 改代码 / 确认无害
|
||||
↓
|
||||
repair_apply(越界必拒)
|
||||
↓
|
||||
复验 → 通过后写回 .marqdo/labels.json(confirmed_fingerprint 更新)
|
||||
```
|
||||
|
||||
**CI 用法**:
|
||||
- 普通项目:`label.stale` 默认 **warning**(不阻塞)
|
||||
- 知识库项目(OKF/EKC 仓):可配置为 **error**,把"断言必须新鲜"作为门禁
|
||||
|
||||
---
|
||||
|
||||
## 7. 反幻觉:这一步到底解决了什么
|
||||
|
||||
必须把话说准,否则容易过度承诺。
|
||||
|
||||
### 7.1 它解决的**具体一类**
|
||||
|
||||
> **文档断言与实现不一致**(doc–code drift at the claim level)。
|
||||
|
||||
传统文档的失败模式:
|
||||
|
||||
| 失败模式 | 传统文档 | Marqdo(本设计) |
|
||||
|---------|---------|-----------------|
|
||||
| 注释过期 | 无声腐烂 | L1/L2 检出 |
|
||||
| 签名漂移 | 靠类型检查(有) | 契约已有 |
|
||||
| **散文描述与实现不符** | **完全无解** | **本设计**(新能力) |
|
||||
| 知识库引用失效 | 靠人工审阅 | 可机械化 |
|
||||
|
||||
### 7.2 它**不解决**什么
|
||||
|
||||
- 模型凭空编造(幻觉的另一种)
|
||||
- 代码本身写错
|
||||
- 标签写得含糊但"不算错"(L1 查不到,L2 只能报"变了")
|
||||
|
||||
**所以正确的表述是**:
|
||||
> 它把"**文档可信度**"从"靠人自觉"提升到"**可被机械复核 + 可被 LLM 裁决**"。
|
||||
|
||||
### 7.3 为什么这对"可执行知识体系"是决定性的
|
||||
|
||||
一个知识库的价值 = **断言的密度 × 断言的可信度**。
|
||||
传统知识库只能提高密度(多写),无法保证可信度(写完就腐)。
|
||||
Marqdo 若能把"断言→复核"闭环,就第一次让**知识库有了保鲜机制**——
|
||||
这也正好接上 EKC 已有的 `stale` / `verify` 体系。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与反对意见(诚实清单)
|
||||
|
||||
### 8.1 误报疲劳(最危险)
|
||||
|
||||
如果 `label.stale` 天天响,用户会在三天内学会忽略它。
|
||||
**对策**:
|
||||
- L1 **只在能证明冲突时报**(引用了不存在的实体 / 引用的实体不在语句里)
|
||||
- L2 **默认只报 warning**,且同一标签同一指纹只报一次(台账记录"已复核")
|
||||
- 诊断里必须给**可执行建议**(改哪一行、改成什么),否则就是噪音
|
||||
|
||||
### 8.2 台账的腐烂与合并冲突
|
||||
|
||||
`.marqdo/labels.json` 是缓存,不是真相。对策:
|
||||
- 语义上**可丢弃**:删掉后重建,最多一次全量确认
|
||||
- 合并冲突策略:**重算优先**(以代码指纹为准,冲突时保留 `confirmed_at` 较新者)
|
||||
- 不放进版本库时(`.gitignore`),退化为"本地提示";放进版本库时,成为团队级门禁
|
||||
|
||||
### 8.3 语义鸿沟
|
||||
|
||||
L1 只能查引用;标签写"算总价"而代码改成了"算单价",若两者都引用 `税率`,L1 沉默。
|
||||
**这是 L2 存在的理由**,也是必须承认的能力边界。
|
||||
|
||||
### 8.4 LLM 修标签可能引入新幻觉
|
||||
|
||||
"用幻觉修幻觉"是真风险。对策:
|
||||
- 护栏:**只允许改标签行或代码行**(`repair_apply` 已强制)
|
||||
- 修改必须**双向可逆**:诊断里给出"过去/现在"两侧,让模型做**判定**而不是**创作**
|
||||
- 知识库仓建议:L2 级修改需人工确认(`--confirm`)
|
||||
|
||||
### 8.5 标签不得参与安全判定
|
||||
|
||||
这是我在上一份文档里提的、也是你关心的"agent 误导"的另一面:
|
||||
**如果沙箱/权限判定读标签,那标签就成了攻击面。**
|
||||
硬约束:**策略、沙箱、工具白名单只读 `()` 的语义,永不读 `[]`。**
|
||||
标签只服务于"人读"与"AI 复核",不服务于"机器授权"。
|
||||
|
||||
### 8.6 成本
|
||||
|
||||
每标签一次指纹计算与比对。可增量:只对**本次变更的文件**做 L2 校验
|
||||
(与 EKC 的增量编译一致)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 分阶段落地
|
||||
|
||||
| 阶段 | 内容 | 依赖 | 风险 |
|
||||
|------|------|------|------|
|
||||
| **P0** | 纯度语法:`[标签](表达式)` + `label.missing` + 普通取元(A 或 C) | 解析器 | 中(506 处迁移) |
|
||||
| **P1** | L1 引用一致性 + `label.stale` 诊断(无状态) | 诊断字段已有 | 低 |
|
||||
| **P2** | 诊断 schema + MLSP ranges 并集 + 修复回路 | `mlsp.rs` / `repair.rs` | 低 |
|
||||
| **P3** | L2 指纹台账 + 增量校验 | `fingerprint.rs` | 中 |
|
||||
| **P4** | L3 LLM 复核 + `confirmed` 写回 + CI 门禁 | P2+P3 | 中 |
|
||||
|
||||
**建议先做 P1**:它零状态、确定性、能立刻抓住"引用了不存在的东西"这类最硬的腐烂,
|
||||
且不依赖纯度迁移——可以在旧语法上先验证"标签断言"这个概念是否好用。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **普通取元选 A(`at value=… index=…`,零新语法)还是 C(`at(篮子, 1)`,需逗号参数)?**
|
||||
2. **L1 的断言规则**:只认标签内的反引号 `` `名` ``,还是也认"与代码标识符同名"的中文词?
|
||||
(只认反引号更准;认中文词更聪明但假阳性高)
|
||||
3. **台账位置**:`.marqdo/labels.json`(默认忽略)还是纳入版本库(团队门禁)?
|
||||
4. **`label.stale` 默认级别**:warning(推荐)还是 error?
|
||||
5. **是否先只做 P1**(在旧语法上验证"标签断言"概念),再决定纯度迁移?
|
||||
|
||||
> 我的建议顺序:**P1 → P2 → P0 → P3 → P4**。
|
||||
> 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度),
|
||||
> 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。
|
||||
@@ -0,0 +1,218 @@
|
||||
# 方案评估:Markdown 链接式调用 `[函数名](参数…)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 已被 [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) 取代** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「markdown 的链接语义似乎很适合做这种操作」 |
|
||||
| 相邻 | [spaced-function-names-d8.md](spaced-function-names-d8.md)(方括号调用 + 空格) |
|
||||
| 影响面 | **核心解析**:`[key](coll)` 链接索引与调用语法冲突 |
|
||||
|
||||
> **后续更正**:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。
|
||||
> 用户问的是**调用写法**本身。最新评估(含原型实测 554/0 回归)见
|
||||
> [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md):
|
||||
> 方括号确实不可行(2 个真实冲突文件),但**去掉方括号的 `f(args)` 是空闲语法且可行**。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**语法本身很优雅,但它与既有特性「链接索引 `[key](map)`」正面冲突。**
|
||||
冲突不是「难实现」,而是「同一个写法要表示两种语义」。
|
||||
建议**不要**把它做成调用的主形式;若要引入,只能作为**受限变体**(见 §4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状事实(实测)
|
||||
|
||||
### 1.1 `[…](…)` 目前是链接索引
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"a":1}**
|
||||
**v = [a](m)** # 取 map 的 a 成员
|
||||
> print text=`v` # → 1
|
||||
```
|
||||
|
||||
这是 v0.3 的**正式特性**,文档里写作「集合取元优先 `[键](集合)`」。
|
||||
实现有专门入口 `parse_link_index`,并由 `link_index_shape_ahead` 判定:
|
||||
|
||||
> `[` … `]` 后面紧跟 `(` → **链接索引**
|
||||
|
||||
### 1.2 提议的写法今天会怎样
|
||||
|
||||
```markdown
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
*"hi " + `who`*
|
||||
|
||||
# main
|
||||
|
||||
**r = [greet](alice)**
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
error: l2.mq.md:12:1: undefined variable `alice`
|
||||
```
|
||||
|
||||
因为它被当作链接索引 `[greet](alice)`:拿 `alice` **当变量名**去查,
|
||||
查不到就报错。也就是说**链接索引已经把这块语法占满了**。
|
||||
|
||||
### 1.3 歧义判定只有一行
|
||||
|
||||
```rust
|
||||
fn link_index_shape_ahead(s: &str) -> bool {
|
||||
// '[' … ']' 后紧跟 '(' → 链接索引
|
||||
}
|
||||
```
|
||||
|
||||
任何 `[X](Y)` 都会走链接索引,没有例外。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么这个提议有吸引力
|
||||
|
||||
先说我认可的部分,避免低估它:
|
||||
|
||||
1. **视觉语义准确**。Markdown 里 `[文本](目标)` 的直觉是「链接一个东西到另一个」。
|
||||
调用 `[greet](alice)` 读作「调用 greet,指向 alice」,对非程序员也直观。
|
||||
2. **参数在括号里,边界清晰**。相比 `> greet alice`(空格切词),
|
||||
`(alice bob)` 的边界是**显式**的 —— 这恰好是 D8「带空格函数名」痛点的天然解药。
|
||||
3. **与 Markdown 完全兼容**。`[a](b)` 是合法链接写法,编辑器不会标红。
|
||||
|
||||
**但**:这些优点必须在「不破坏链接索引」的前提下才能兑现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 冲突分析
|
||||
|
||||
### 3.1 根本矛盾
|
||||
|
||||
| 写法 | 链接索引语义 | 调用语义 | 能否并存 |
|
||||
|------|-------------|---------|---------|
|
||||
| `[a](m)` | 取 `m` 的成员 `a` | 用参数 `m` 调用 `a` | **看内容才知道** |
|
||||
| `[greet](alice)` | 取 `alice` 的成员 `greet` | 用 `alice` 调用 `greet` | 同上 |
|
||||
|
||||
**两者形状完全一致**,区别只在「`greet` 是函数还是键名」「`alice` 是集合还是实参」——
|
||||
这需要**符号表信息**,而语法判定发生在解析期(此时未必知道有哪些函数)。
|
||||
|
||||
### 3.2 用「函数表已知」来消歧能行吗
|
||||
|
||||
理论上:若 `greet` 是已定义函数 → 调用;否则 → 链接索引。
|
||||
|
||||
**问题**:
|
||||
1. **跨模块不可知**:`[lib.greet](x)` 需要 import 结果,词法/语法期拿不到。
|
||||
2. **名字冲突**:如果既有 `greet` 函数,又有 map 里叫 `greet` 的键,语义就靠猜。
|
||||
3. **错误信息会变差**:本意是链接索引但键不存在时,会被误判成调用,
|
||||
报 `unknown function` 而不是 `missing map key` —— 把清晰错误变成误导错误。
|
||||
4. **修改即破坏**:今天所有 `[键](集合)` 写法都要进符号表做一次判定,
|
||||
这是**全量语义变更**,不是增量特性。
|
||||
|
||||
### 3.3 冲突的严重度
|
||||
|
||||
链接索引是 v0.3 **明确推广**的写法(「集合取元优先 `[键](集合)`」),
|
||||
仓库里大量使用。让调用去抢这块语法,等于**用新特性侵蚀既有特性**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 可选的受限方案
|
||||
|
||||
### 方案 L1 — 参数列表必须「非单个标识符」(不可靠,不推荐)
|
||||
|
||||
仅在 `(…)` 内含**分隔符**时判为调用,如 `[greet](alice, bob)`。
|
||||
|
||||
- 优点:`[a](m)` 单参数时保留链接索引语义
|
||||
- **致命缺陷**:`[greet](alice)` 这种最常见的单参数调用无法表达;
|
||||
而 `[greet](a, b)` 又和「链接索引 + 逗号」冲突。**语义随参数个数漂移**,最坏的一类设计。
|
||||
|
||||
### 方案 L2 — 独立标记前缀(可行,但失去「链接感」)
|
||||
|
||||
```markdown
|
||||
> [call]greet(alice) # 或 @greet(alice)
|
||||
```
|
||||
|
||||
- 优点:零歧义
|
||||
- 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力
|
||||
|
||||
### 方案 L3 — 方括号调用 + 括号参数(**推荐**)
|
||||
|
||||
保留既有的方括号调用形式,但允许**参数写在括号里**:
|
||||
|
||||
```markdown
|
||||
> [加一 号](n=1) # 具名参数
|
||||
> [加一 号](1) # 位置参数
|
||||
> [greet](alice bob) # 多参数
|
||||
```
|
||||
|
||||
关键:**`]` 后面跟 `(` 时仍优先判为链接索引**——
|
||||
除非方括号内是「已知的函数名形状」且**调用上下文**成立。
|
||||
|
||||
等等,这与 §3 的矛盾相同。**所以 L3 的真正形态是**:
|
||||
|
||||
```markdown
|
||||
> [加一 号] (n=1) # 方括号与括号之间有空格 → 调用+参数组,不是链接
|
||||
```
|
||||
|
||||
用「`]` 与 `(` 之间是否有空格」消歧:
|
||||
- `[key](coll)`(紧贴)→ 链接索引(**既有语义完全不变**)
|
||||
- `[callee] (args)`(有空格)→ 调用,参数为一组
|
||||
|
||||
- 优点:**零歧义**、**零回归**(紧贴形式完全不动)、保留了「括号包参数」的可读性、
|
||||
顺带解决 D8 的空格函数名
|
||||
- 缺点:视觉上 `] (` 有个空格,略不自然;但 Markdown 渲染不受影响
|
||||
|
||||
### 方案 L4 — 不在语法层做,在文档层说明(保守)
|
||||
|
||||
明确「链接索引是取元,不是调用」,调用一律用 `> callee args` 或 `> [callee] args`。
|
||||
`[函数名](参数)` 留作**不做**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 方案对比
|
||||
|
||||
| 方案 | 歧义 | 回归风险 | 保留「链接感」 | 解决 D8 | 推荐 |
|
||||
|------|------|---------|--------------|---------|------|
|
||||
| L1 参数需含分隔符 | **高**(随参数个数漂移) | 中 | 部分 | 否 | ❌ |
|
||||
| L2 独立前缀 | 无 | 无 | **否** | 是 | 备选 |
|
||||
| **L3 空格消歧** | **无** | **无** | 大部分 | **是** | ✅ |
|
||||
| L4 不做 | 无 | 无 | 否 | 否 | 退路 |
|
||||
| 直接抢 `[x](y)` | **不可解** | **高** | 是 | 是 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 6. 我的建议
|
||||
|
||||
1. **不要**把 `[函数名](参数)` 直接定为调用——它和链接索引形状相同,无法可靠消歧。
|
||||
2. 采纳 **L3**:`[callee] (args)`(中间有空格)作为「带括号参数组的调用」,
|
||||
紧贴的 `[key](coll)` 语义**一字不动**。
|
||||
3. 这样同时满足:
|
||||
- 「完全兼容 Markdown」(`[x](y)` 仍是链接语义)
|
||||
- 参数边界显式(括号括起来)
|
||||
- D8 的空格函数名(方括号内允许空格)
|
||||
4. 若你觉得 `] (` 的空格不好看,退一步选 **L2**(`> callee(args)` 这种函数式写法),
|
||||
牺牲链接感换取零歧义。
|
||||
|
||||
---
|
||||
|
||||
## 7. 若采纳 L3 的验证计划
|
||||
|
||||
| 编号 | 用例 | 期望 |
|
||||
|------|------|------|
|
||||
| L3-1 | `[a](m)` 紧贴 | 链接索引,取成员(**不变**) |
|
||||
| L3-2 | `[greet] (alice)` 有空格 | 调用,`alice` 作为位置参数 |
|
||||
| L3-3 | `[加一 号] (n=1)` | 调用带空格名函数,返回 2 |
|
||||
| L3-4 | `[greet] (a b)` | 两个位置参数 |
|
||||
| L3-5 | `[a](m)` 中 `a` 恰好也是函数名 | **仍走链接索引**(紧贴优先) |
|
||||
| L3-6 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不受影响 |
|
||||
| L3-7 | 全量 `cargo test` | 554 全绿 |
|
||||
| L3-8 | 全仓库 `.mq.md` 回归 | 无变化(紧贴形式未动) |
|
||||
|
||||
---
|
||||
|
||||
## 8. 待你决策
|
||||
|
||||
1. **选 L3、L2、还是 L4?**
|
||||
2. 若选 L3:`] (` 的空格你能接受吗?(渲染上无差别,源码里能看见)
|
||||
3. 是否同时支持全角 `【函数名】(参数)`?与 D2 全角冒号问题一致考虑。
|
||||
@@ -0,0 +1,531 @@
|
||||
# 文档会话(View Cells)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / 交互单元) |
|
||||
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无(读取既有 AST 与表格) |
|
||||
|
||||
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
|
||||
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
|
||||
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
|
||||
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
|
||||
5. **多语言**:命名内核 + 显式状态桥。
|
||||
6. **可复现**:Run All / journal / dirty / stale / replay。
|
||||
|
||||
---
|
||||
|
||||
## 1.1 实施状态(2026-10-18)
|
||||
|
||||
| 能力 | 状态 | 位置 |
|
||||
|---|---|---|
|
||||
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
|
||||
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
|
||||
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
|
||||
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
|
||||
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
|
||||
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
|
||||
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
|
||||
| `kernel/interrupt` | 待做 | — |
|
||||
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
|
||||
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
|
||||
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
|
||||
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
|
||||
| cell step | ✅ | 同上 |
|
||||
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
|
||||
| writeback 集成 | 待做 | `writeback` |
|
||||
| replay / 持久化 | 待做 | — |
|
||||
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
|
||||
| Node 会话 | ✅ | 同上 |
|
||||
|
||||
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两个执行面(不是两个 CLI 模式)
|
||||
|
||||
### 2.1 Program execution(规范)
|
||||
|
||||
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
|
||||
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
|
||||
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
|
||||
- 结果:可复现;是文档的“真理”。
|
||||
|
||||
### 2.2 View cells(交互)
|
||||
|
||||
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
|
||||
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
|
||||
- 状态:内核持久;可切换、重启、单步。
|
||||
- 结果:默认临时显示;可显式 writeback。
|
||||
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
|
||||
|
||||
### 2.3 两者关系
|
||||
|
||||
```text
|
||||
.mq.md
|
||||
/ \
|
||||
Program run View cells
|
||||
(canonical) (interactive)
|
||||
\ /
|
||||
Document Session
|
||||
├── cell index
|
||||
├── kernel registry
|
||||
├── journal
|
||||
└── state panel
|
||||
```
|
||||
|
||||
- 共享 cell index 与 kernel registry。
|
||||
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
|
||||
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
|
||||
|
||||
---
|
||||
|
||||
## 3. 文档会话模型
|
||||
|
||||
```text
|
||||
DocumentSession
|
||||
├── doc_path / doc_hash
|
||||
├── cells: Vec<Cell>
|
||||
│ ├── id (name / anon@line)
|
||||
│ ├── name (binding)
|
||||
│ ├── lang
|
||||
│ ├── line_start / line_end
|
||||
│ ├── source_hash
|
||||
│ ├── kernel (resolved)
|
||||
│ └── status: never | clean | dirty | stale | error | running
|
||||
├── kernels: KernelRegistry
|
||||
│ ├── name → ForeignSession
|
||||
│ └── default per language
|
||||
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
|
||||
├── journal: Vec<ExecutionRecord>
|
||||
├── created_ms / last_active_ms
|
||||
└── surface: program | view
|
||||
```
|
||||
|
||||
### 3.1 Cell
|
||||
|
||||
- 只有**绑定名**的代码围栏才是 cell:
|
||||
```markdown
|
||||
`加载` =
|
||||
```python
|
||||
...
|
||||
```
|
||||
```
|
||||
- 未绑定围栏仍是叙述,不是 cell。
|
||||
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
|
||||
- 同名 cell 重复 → 诊断;会话表按名字引用。
|
||||
- `source_hash` 用于 dirty 判断。
|
||||
- `line_start/line_end` 用于定位;编辑后重建索引。
|
||||
|
||||
### 3.2 Cell index 构建
|
||||
|
||||
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
|
||||
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
|
||||
3. 记录 name、lang、source、span、source hash。
|
||||
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
|
||||
6. 生成执行顺序:
|
||||
- 有会话表 → 行顺序;
|
||||
- 无 → 文档顺序。
|
||||
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
|
||||
|
||||
### 3.3 Kernel registry
|
||||
|
||||
- key:`<document_id>:<kernel_name>`。
|
||||
- 默认:`default:python`、`default:node`,按需启动。
|
||||
- 命名:来自 `内核表`,首次执行时启动。
|
||||
- 状态:`idle | starting | ready | busy | dead`。
|
||||
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
|
||||
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
|
||||
- 关闭:kill + 移除。
|
||||
|
||||
### 3.4 Value store(Marqdo 侧会话值)
|
||||
|
||||
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
|
||||
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
|
||||
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
|
||||
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
|
||||
- 用途:
|
||||
- 状态面板显示;
|
||||
- Push 到内核;
|
||||
- 作为 `session_set` 的值来源;
|
||||
- journal 记录。
|
||||
|
||||
### 3.5 Journal
|
||||
|
||||
每次执行追加一条:
|
||||
|
||||
```json
|
||||
{
|
||||
"seq": 3,
|
||||
"cell": "汇总",
|
||||
"kernel": "分析",
|
||||
"lang": "python",
|
||||
"ok": true,
|
||||
"code": 0,
|
||||
"ms": 42,
|
||||
"source_hash": "…",
|
||||
"stdout_hash": "…",
|
||||
"result_hash": "…",
|
||||
"started_ms": 1760000000000,
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
用途:
|
||||
|
||||
- 执行序号 / 顺序;
|
||||
- dirty/stale 判断;
|
||||
- replay;
|
||||
- 视图显示;
|
||||
- 调试(“为什么这个 cell 有值”)。
|
||||
|
||||
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 执行语义
|
||||
|
||||
### 4.1 操作
|
||||
|
||||
| 操作 | 语义 |
|
||||
|---|---|
|
||||
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
|
||||
| **Run above** | 按会话顺序执行到选中 cell(含) |
|
||||
| **Run all** | 按会话顺序执行全部;可选 `restart` |
|
||||
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
|
||||
| **Step next statement** | Marqdo 语句级单步(DebugController) |
|
||||
| **Restart kernel** | kill + 重建;cell 状态 `never` |
|
||||
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
|
||||
| **Reset session** | 关闭所有 kernel,清 journal / value store |
|
||||
|
||||
### 4.2 执行一个 cell
|
||||
|
||||
```text
|
||||
resolve cell -> resolve kernel
|
||||
-> ensure kernel ready
|
||||
-> [送入?] 显式 bridge 由文档代码/UI 负责
|
||||
-> foreign.session_eval(kernel, source, input?)
|
||||
-> record -> update cell status
|
||||
-> [取回?] 由文档代码/UI 负责
|
||||
-> journal append
|
||||
-> view update
|
||||
```
|
||||
|
||||
- 默认 cwd = 文档目录;env = kernel env。
|
||||
- 输出:stdout / stderr / result / ms / truncated。
|
||||
- 失败:cell 状态 `error`;journal 记录;不自动重试。
|
||||
- 同一 kernel 串行;UI 禁用并发 Run。
|
||||
|
||||
### 4.3 Step 语义
|
||||
|
||||
| 类型 | 行为 |
|
||||
|---|---|
|
||||
| **Cell step** | 执行下一个会话 cell;状态保留 |
|
||||
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
|
||||
| **Foreign line step** | 不做;未来 DAP |
|
||||
|
||||
- Cell step 是 view cells 的主单步。
|
||||
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
|
||||
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
|
||||
|
||||
### 4.4 中断
|
||||
|
||||
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
|
||||
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
|
||||
- 不允许“中断后继续用同一 kernel”除非确认状态。
|
||||
|
||||
### 4.5 并发
|
||||
|
||||
- 同一 kernel:一次一个 cell。
|
||||
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
|
||||
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
|
||||
- 并发上限沿用 foreign(32)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 状态桥(会话层)
|
||||
|
||||
### 5.1 显式 API
|
||||
|
||||
文档代码:
|
||||
|
||||
```markdown
|
||||
把 `数值表` 送进 `分析` 内核:
|
||||
**> foreign.session_set id="分析" name="xs" value=`数值表`**
|
||||
|
||||
从 `分析` 内核取回 `mean`:
|
||||
**`均值` = > foreign.session_get id="分析" name="mean"**
|
||||
```
|
||||
|
||||
### 5.2 状态面板
|
||||
|
||||
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
|
||||
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
|
||||
- 操作:
|
||||
- Push:选 Marqdo 值 → kernel 变量;
|
||||
- Pull:选 kernel 变量 → value store / 显示;
|
||||
- Refresh;
|
||||
- 复制名称/值。
|
||||
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
|
||||
|
||||
### 5.3 自动镜像
|
||||
|
||||
- v2 不做。
|
||||
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
|
||||
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
|
||||
|
||||
### 5.4 类型
|
||||
|
||||
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
|
||||
- 大对象:v2 显示摘要;传输用文件/DB。
|
||||
- 未来:Arrow / Parquet / 共享文件句柄。
|
||||
|
||||
---
|
||||
|
||||
## 6. Dirty / Stale / Run All
|
||||
|
||||
### 6.1 定义
|
||||
|
||||
| 状态 | 条件 |
|
||||
|---|---|
|
||||
| `never` | 未执行 |
|
||||
| `clean` | 上次执行成功后源码未变 |
|
||||
| `dirty` | 源码 hash 变了 |
|
||||
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
|
||||
| `error` | 上次执行失败 |
|
||||
| `running` | 正在执行 |
|
||||
| `unlisted` | 不在会话表 |
|
||||
|
||||
### 6.2 依赖
|
||||
|
||||
- v2:会话表行顺序 + 简单规则:
|
||||
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
|
||||
- 若 kernel 重启,全部 `never`。
|
||||
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
|
||||
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
|
||||
|
||||
### 6.3 Run All
|
||||
|
||||
- 默认:按会话顺序执行;可选 `restart=true`。
|
||||
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
|
||||
- 未重启时:显示“当前 kernel 有历史状态”警告。
|
||||
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
|
||||
|
||||
### 6.4 Replay
|
||||
|
||||
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
|
||||
- 比较 stdout/result hash;
|
||||
- 输出 divergence 报告。
|
||||
- v2 可选;至少保留 journal 以便未来实现。
|
||||
|
||||
---
|
||||
|
||||
## 7. 输出与文档
|
||||
|
||||
### 7.1 默认
|
||||
|
||||
- View cells 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
|
||||
- 不写 execution_count 到文档。
|
||||
|
||||
### 7.2 显式 writeback
|
||||
|
||||
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
|
||||
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
|
||||
- 可选:
|
||||
- 单 cell 写回;
|
||||
- 全部写回;
|
||||
- 只写回文本/数值,不写复杂对象。
|
||||
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
|
||||
|
||||
### 7.3 不写回
|
||||
|
||||
- 避免 Jupyter 的 `.ipynb` 输出噪声。
|
||||
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
|
||||
|
||||
---
|
||||
|
||||
## 8. View 交互
|
||||
|
||||
### 8.1 工具栏
|
||||
|
||||
```text
|
||||
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
|
||||
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
[State] [Journal] [Writeback ▾]
|
||||
```
|
||||
|
||||
### 8.2 每个 code card
|
||||
|
||||
```text
|
||||
`加载` python · kernel 分析 · run #3 · 42ms · clean
|
||||
[Run] [Step] [Kernel ▾] [State] [Copy output]
|
||||
```
|
||||
|
||||
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
|
||||
- 输出区:stdout / stderr / result / 截断提示。
|
||||
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
|
||||
- `Step` = 执行此 cell(cell step)。
|
||||
|
||||
### 8.3 状态面板
|
||||
|
||||
- Marqdo / kernel 分栏。
|
||||
- Push/Pull。
|
||||
- Secret 打码。
|
||||
- 大对象摘要 + 复制 JSON。
|
||||
|
||||
### 8.4 Journal 面板
|
||||
|
||||
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
|
||||
- 点击跳转 cell。
|
||||
- 导出 JSON。
|
||||
|
||||
### 8.5 键盘
|
||||
|
||||
- `Ctrl/Cmd + Enter`:Run cell。
|
||||
- `Shift + Enter`:Run cell + 下一个。
|
||||
- `Alt + Enter`:Run cell + 插入?不做。
|
||||
- `F10`:Step statement(与 debug 一致)。
|
||||
- `F5`:Run All。
|
||||
|
||||
---
|
||||
|
||||
## 9. 服务端 API
|
||||
|
||||
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|---|---|---|
|
||||
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
|
||||
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
|
||||
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
|
||||
| POST | `/api/session/cell/run` | 执行指定 cell |
|
||||
| POST | `/api/session/cell/step` | 执行下一个 cell |
|
||||
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
|
||||
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
|
||||
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
|
||||
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
|
||||
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
|
||||
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
|
||||
| POST | `/api/session/state/pull` | kernel 变量 → value store |
|
||||
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
|
||||
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
|
||||
| POST | `/api/session/journal` | 执行日志 |
|
||||
| GET | `/api/session` | 当前会话摘要 |
|
||||
|
||||
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 生命周期与持久化
|
||||
|
||||
- Session key:`<root>/<doc_rel>`;每个文档一个。
|
||||
- 打开:解析、建 cell index、按需启动 kernel。
|
||||
- 空闲超时:默认 30 分钟关闭(可配置)。
|
||||
- 文档关闭 / 服务退出:kill 所有 kernel。
|
||||
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
|
||||
- 持久化(可选):
|
||||
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
|
||||
- 默认 git 忽略;
|
||||
- 不持久化进程状态 / 大对象。
|
||||
- 不把 session 状态写进 `.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 11. 安全
|
||||
|
||||
| 项 | 策略 |
|
||||
|---|---|
|
||||
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
|
||||
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
|
||||
| cwd | 文档目录 / `fs_root`;越界拒绝 |
|
||||
| 输出 | 有界;截断标记 |
|
||||
| 超时 | cell 级;进程组 kill |
|
||||
| 中断 | 杀进程组;kernel 标记 dead |
|
||||
| Secret | 状态面板打码;JSON 不默认暴露 |
|
||||
| 未信任文档 | 不自动打开会话;必须显式 Run |
|
||||
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
|
||||
| writeback | 显式;路径沙箱;不自动改文档 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 测试
|
||||
|
||||
### 12.1 服务端
|
||||
|
||||
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
|
||||
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
|
||||
- 会话:open/close/reload;kernel 启动/重启/中断。
|
||||
- cell run:状态机 never→running→clean/error;dirty/stale。
|
||||
- step:cell step 顺序;statement step 与 debug 联动。
|
||||
- state:push/pull/list;Secret 打码;大对象摘要。
|
||||
- journal:顺序、hash、失败。
|
||||
- 并发:同 kernel 串行;不同 kernel 并行。
|
||||
- 安全:exec=false 拒绝;cwd 越界;超时。
|
||||
|
||||
### 12.2 金样例
|
||||
|
||||
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
|
||||
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
|
||||
- `tests/notebook/step.mq.md`:cell step 顺序。
|
||||
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
|
||||
- `tests/notebook/invalid-*.mq.md`:诊断。
|
||||
- 依赖:node 为主,python 条件跳过。
|
||||
|
||||
### 12.3 UI
|
||||
|
||||
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
|
||||
- 不引入前端测试框架;用服务端 API + 静态检查。
|
||||
|
||||
---
|
||||
|
||||
## 13. 与 Jupyter 对照
|
||||
|
||||
| 维度 | Jupyter | Document Session |
|
||||
|---|---|---|
|
||||
| 源 | `.ipynb` | `.mq.md` |
|
||||
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
|
||||
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
|
||||
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 单步 | cell | cell + statement |
|
||||
| 复现 | 手动 | Restart & Run All + journal + replay |
|
||||
| Git | 输出/计数噪声 | 源码干净;输出显式 |
|
||||
| 知识 | 无 | OKF / catalog |
|
||||
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 实现顺序(D 层)
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|---|---|
|
||||
| D0 | 设计/语法/决策文档(本文件) |
|
||||
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
|
||||
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
|
||||
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
|
||||
| D4 | statement step 接入;dirty/stale;writeback |
|
||||
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
|
||||
|
||||
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
|
||||
|
||||
---
|
||||
|
||||
## 15. 明确不做(v2)
|
||||
|
||||
- Foreign line-level step。
|
||||
- 自动镜像变量。
|
||||
- 跨文档共享 kernel。
|
||||
- 全进程快照。
|
||||
- 自动执行 cell。
|
||||
- 把 session 状态写进 `.mq.md`。
|
||||
- 前端 SPA 框架重写;沿用现有 HTML/JS。
|
||||
@@ -0,0 +1,305 @@
|
||||
# 文档原生 view cells 语法
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Decided;D1 解析已实现** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Document(读取约定) + Runtime(校验) |
|
||||
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) |
|
||||
| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 |
|
||||
|
||||
> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么不用围栏元数据
|
||||
|
||||
Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**:
|
||||
|
||||
- 读者看到的是一行属性,不是一段知识;
|
||||
- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图;
|
||||
- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行;
|
||||
- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。
|
||||
|
||||
Marqdo 的选择:
|
||||
|
||||
> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。**
|
||||
|
||||
这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两个约定数据表
|
||||
|
||||
它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 读取与清洗数据 |
|
||||
| 绘图 | python | | 独立环境 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 加载 | 分析 | 读取原始数据 |
|
||||
| 清洗 | 分析 | 处理缺失值 |
|
||||
| 汇总 | 分析 | 按城市聚合 |
|
||||
| 绘图 | 绘图 | 输出 SVG |
|
||||
```
|
||||
|
||||
为什么是“绑定的表”,不是 `# 外联内核` 对象:
|
||||
|
||||
- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。
|
||||
- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。
|
||||
- View / 文档会话读取 AST 中的绑定值,不需要执行文档。
|
||||
- 解析器零改动。
|
||||
|
||||
### 2.1 `内核表` / `kernels`
|
||||
|
||||
| 列 | 必填 | 含义 |
|
||||
|---|---|---|
|
||||
| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) |
|
||||
| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … |
|
||||
| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 |
|
||||
| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 |
|
||||
|
||||
规则:
|
||||
|
||||
- 名称在文件内唯一;重复 → 诊断。
|
||||
- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。
|
||||
- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。
|
||||
- 没有 `内核表`:每种语言自动一个 `default` 内核。
|
||||
- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。
|
||||
|
||||
### 2.2 `会话表` / `session`
|
||||
|
||||
| 列 | 必填 | 含义 |
|
||||
|---|---|---|
|
||||
| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** |
|
||||
| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 |
|
||||
| `说明` / `Notes` | 可选 | 给人读的一句话 |
|
||||
|
||||
规则:
|
||||
|
||||
- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。
|
||||
- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。
|
||||
- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。
|
||||
- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。
|
||||
- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。
|
||||
- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。
|
||||
- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。
|
||||
- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。
|
||||
|
||||
### 2.3 为什么放在 `# main` 体内
|
||||
|
||||
- `# main` 是入口;cell 绑定与元数据表同一作用域。
|
||||
- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。
|
||||
- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。
|
||||
- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 完整示例
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
|
||||
一个绘图单元在隔离的 `绘图` 内核里运行。
|
||||
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 数据读取与聚合 |
|
||||
| 绘图 | python | | 独立绘图环境 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 加载 | 分析 | 读取原始数据 |
|
||||
| 清洗 | 分析 | 处理缺失值 |
|
||||
| 汇总 | 分析 | 按城市聚合 |
|
||||
| 绘图 | 绘图 | 输出 SVG |
|
||||
|
||||
`加载` =
|
||||
```python
|
||||
import json
|
||||
|
||||
rows = [
|
||||
{"city": "上海", "value": 3},
|
||||
{"city": "北京", "value": 5},
|
||||
]
|
||||
print(json.dumps(rows, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`清洗` =
|
||||
```python
|
||||
rows = [r for r in rows if r["value"] > 0]
|
||||
```
|
||||
|
||||
`汇总` =
|
||||
```python
|
||||
from collections import Counter
|
||||
|
||||
counts = Counter(r["city"] for r in rows)
|
||||
print(dict(counts))
|
||||
```
|
||||
|
||||
`绘图` =
|
||||
```python
|
||||
print("plot-ready")
|
||||
```
|
||||
|
||||
`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。
|
||||
需要共享时,用 Marqdo 显式把值送过去:
|
||||
|
||||
**> foreign.session_set id="绘图" name="rows" value=`rows`**
|
||||
````
|
||||
|
||||
读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 自动模式(没有表)
|
||||
|
||||
### 4.1 没有任何约定表
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`分析` =
|
||||
```python
|
||||
x = 41
|
||||
```
|
||||
|
||||
`结论` =
|
||||
```python
|
||||
print(x + 1)
|
||||
```
|
||||
````
|
||||
|
||||
解释:
|
||||
|
||||
- 两个 cell 都是 `python`;
|
||||
- 自动使用 `default:python` 内核(一个);
|
||||
- 按文档顺序执行;
|
||||
- 共享 `x`。
|
||||
|
||||
现有文档不需要改一行就能在 view 里 cell-by-cell 运行。
|
||||
|
||||
### 4.2 只有内核表
|
||||
|
||||
- 所有 cell 按文档顺序;
|
||||
- 每种语言解析到该语言的 `default` 内核;
|
||||
- 命名内核只有被 `会话表` 引用时才使用。
|
||||
|
||||
### 4.3 只有会话表
|
||||
|
||||
- `内核` 列只能写语言 id;
|
||||
- 每个语言 id 解析到该语言默认内核;
|
||||
- 未列出的 cell 不入会话。
|
||||
|
||||
---
|
||||
|
||||
## 5. 可读性规则(语法评审标准)
|
||||
|
||||
新增/修改任何 cell 表约定,必须满足:
|
||||
|
||||
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
|
||||
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
|
||||
3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。
|
||||
4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。
|
||||
5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。
|
||||
6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。
|
||||
7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。
|
||||
8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
|
||||
9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。
|
||||
10. **无表也能跑**:约定表是增强,不是前置条件。
|
||||
|
||||
---
|
||||
|
||||
## 6. 诊断规范
|
||||
|
||||
| 情况 | 诊断(中文示例) | 修复建议 |
|
||||
|---|---|---|
|
||||
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
|
||||
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
|
||||
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
|
||||
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
|
||||
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
|
||||
| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 |
|
||||
| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 |
|
||||
| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 |
|
||||
|
||||
原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 program execution 的关系
|
||||
|
||||
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
|
||||
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
|
||||
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
|
||||
- 两者可以并存:
|
||||
- 文档用表描述“交互时怎么跑”;
|
||||
- `# main` 用显式调用描述“CI 时怎么跑”。
|
||||
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
|
||||
|
||||
这样避免把“执行计划”变成第二套程序语义。
|
||||
|
||||
---
|
||||
|
||||
## 8. 状态桥的语法边界
|
||||
|
||||
v2 **不**为状态交换新增表格/注释。原因:
|
||||
|
||||
- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
|
||||
- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
|
||||
- v2 先用显式 API,把时序讲清楚:
|
||||
```markdown
|
||||
把 `数值表` 送进 `分析` 内核:
|
||||
**> foreign.session_set id="分析" name="xs" value=`数值表`**
|
||||
|
||||
从 `分析` 内核取回 `mean`:
|
||||
**`均值` = > foreign.session_get id="分析" name="mean"**
|
||||
```
|
||||
- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要;
|
||||
- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。
|
||||
|
||||
这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。
|
||||
|
||||
---
|
||||
|
||||
## 9. 未来扩展(不承诺进 v2)
|
||||
|
||||
1. `共享表`:
|
||||
`| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。
|
||||
2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。
|
||||
3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。
|
||||
4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。
|
||||
5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
|
||||
|
||||
任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。
|
||||
|
||||
---
|
||||
|
||||
## 10. 实现落点
|
||||
|
||||
| 逻辑 | 位置 |
|
||||
|---|---|
|
||||
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
|
||||
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
|
||||
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
|
||||
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
|
||||
| 只读展示 | view Structure:表渲染成普通表格 + 徽标 |
|
||||
| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) |
|
||||
|
||||
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
|
||||
@@ -0,0 +1,426 @@
|
||||
# 遮蔽描述与两级检索:内置词表做范例,参数做扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 实施中**(与 [occlusion-syntax.md](occlusion-syntax.md) 同步) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 关键决策 | ①`[]` 是自由描述,不执行 ②**两级词表**:内置=范例/默认,参数=扩展 ③空载荷**一律 warning** ④工程化写进 README,提示词同步更新 |
|
||||
| 前置 | [occlusion-syntax.md](occlusion-syntax.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 五条定调
|
||||
|
||||
1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** 编译器**不解析**,只做**检索**。
|
||||
2. **两级词表**:
|
||||
- **内置词表 = 范例 + 默认检索集**(零配置可用;给 LLM 一个稳定范式)
|
||||
- **参数 = 扩展/覆盖**(`--grep 任意词`,项目自己的说法照样能搜)
|
||||
3. **空载荷一律 warning**:`()` 为空说明"这段遮蔽里没有可执行内容",写 `None` 即消除。
|
||||
4. **强力推荐 LLM 申报**:写不了真接口就"申报",别"假装"。提示词同步更新。
|
||||
5. **工程化实践写进 README**,不另造文档。
|
||||
|
||||
一句话:
|
||||
|
||||
> **描述给人读;内置词给个范式;参数给自由;空着不写会被提醒。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么要允许「假接通」
|
||||
|
||||
模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。
|
||||
|
||||
| 处理方式 | 结果 | 问题 |
|
||||
|---------|------|------|
|
||||
| **A 禁止**("不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 |
|
||||
| **B 放任** | 静默假功能 | 文档撒谎,没人知道欠了多少 |
|
||||
| **C 申报**(本方案) | 允许,但写进描述 | 代码照跑;欠据可数、可查 |
|
||||
|
||||
C 的关键:**不改道德要求,改激励**——申报比伪造省力,且申报后代码照样跑。
|
||||
|
||||
---
|
||||
|
||||
## 2. `()` 内部语法定稿
|
||||
|
||||
### 2.1 取元
|
||||
|
||||
| 语义 | 写法 |
|
||||
|------|------|
|
||||
| Map 取成员 | `at(表, 键)` |
|
||||
| List 第 n 项(1-based) | `at(列表, 1)` |
|
||||
| 缺键取默认(不崩) | `get(表, 键, 默认值)` |
|
||||
|
||||
### 2.2 调用
|
||||
|
||||
| 形态 | 写法 |
|
||||
|------|------|
|
||||
| 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) |
|
||||
| 具名实参 | `计税(档位=2, 金额=100)` |
|
||||
| **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 |
|
||||
| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` |
|
||||
|
||||
实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。
|
||||
**`(` 是明确分隔符**——这是缺陷 D8 的结构性解法。
|
||||
|
||||
### 2.3 循环
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
```
|
||||
|
||||
### 2.4 空载荷:**一律 warning**
|
||||
|
||||
| 写法 | 结果 |
|
||||
|------|------|
|
||||
| `[功能,开发中]()` | ⚠️ `label.empty_payload` |
|
||||
| `[功能,开发中](None)` | ✅ 无警告 |
|
||||
| `[功能,开发中](json.parse text="[]")` | ✅ 无警告 |
|
||||
|
||||
**为什么一律报**:空 `()` 就是"什么都没写"。哪怕桩也该说明返回什么——
|
||||
`None` 也是答案,下游能据此判断。
|
||||
**为什么不会造成存量噪音**:遮蔽语法是新形式,**今天仓库里一处都没有**。
|
||||
|
||||
> 可调旋钮(**非默认**):若实际使用中觉得"已申报的桩也报警"太吵,
|
||||
> 可开启「命中内置词表则降为 hint」。默认关闭——遵守"空载荷必须被看见"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 两级词表
|
||||
|
||||
### 3.1 第一级:内置词表(范式 + 默认检索集)
|
||||
|
||||
**它是什么**:编译器内置的一张**小词表**,用途三个——
|
||||
|
||||
| 用途 | 说明 |
|
||||
|------|------|
|
||||
| **范式** | 给 LLM 一个稳定写法:不知道怎么写状态,就照这个词表写 |
|
||||
| **默认检索集** | `marqdo labels pending` 零配置即可用;跨项目可比 |
|
||||
| **默认豁免集** | 命中这些词的遮蔽默认跳过 stale(见 §6.1) |
|
||||
|
||||
**它不是什么**:**不是语法**。写不写、怎么写都不影响解析与执行。
|
||||
|
||||
### 3.2 内置词表(v1)
|
||||
|
||||
| 组 | 关键词(子串任一命中即算) | 计入 |
|
||||
|----|--------------------------|------|
|
||||
| **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | pending |
|
||||
| **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | pending |
|
||||
| **演示** | `示例` `样例` `demo` | demo |
|
||||
| **不稳** | `实验` `试验` `experimental` | experimental |
|
||||
| **将删** | `废弃` `弃用` `deprecated` | deprecated |
|
||||
| **待核** | `待校验` `未验证` `待确认` | unverified |
|
||||
|
||||
- 组间**独立计数**,不合并
|
||||
- `pending` = 未完成 ∪ 假数据(默认口径,最常用)
|
||||
- 词表版本随编译器走;扩词表**不动语法**
|
||||
|
||||
### 3.3 第二级:参数(扩展与覆盖)
|
||||
|
||||
```bash
|
||||
# 默认:内置 pending 集
|
||||
marqdo labels pending
|
||||
|
||||
# 覆盖:只用我给的词
|
||||
marqdo labels search --grep "接口未联调,联调中"
|
||||
|
||||
# 合并:我给的 + 内置
|
||||
marqdo labels search --grep "联调中" --also-builtin
|
||||
```
|
||||
|
||||
| 参数 | 语义 |
|
||||
|------|------|
|
||||
| `--grep A,B` | **替换**为 A、B(子串、OR、英文大小写不敏感) |
|
||||
| `--also-builtin` | 与内置词表**取并集** |
|
||||
| `--group pending,demo` | 用内置的某几组(不带 `--grep` 时) |
|
||||
|
||||
MLSP 对应:
|
||||
|
||||
```json
|
||||
{ "method": "labels.search",
|
||||
"params": { "grep": ["联调中"], "also_builtin": true, "json": true } }
|
||||
```
|
||||
|
||||
### 3.4 为什么保留内置词表
|
||||
|
||||
| 理由 | 说明 |
|
||||
|------|------|
|
||||
| **LLM 有范本** | 模型不必发明措辞,照着写即可,稳定性显著提高 |
|
||||
| **跨项目可比** | 大家用同一套词,"还有多少没做"才有统一含义 |
|
||||
| **零配置可用** | CI 不必先写一份词表才能统计 |
|
||||
| **失败模式可控** | 词不全时用参数补,而不是每个项目各自发明一套 |
|
||||
|
||||
**代价**:内置词表是一种"语义偏见"。缓解方式是**两级**——
|
||||
内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。
|
||||
|
||||
### 3.5 识别规则:纯子串,无位置/分隔符要求
|
||||
|
||||
```rust
|
||||
// 语义示意
|
||||
for (group, words) in TABLE(words_from_params_or_builtin) {
|
||||
if words.iter().any(|w| label_text.contains(w)) { hits.insert(group) }
|
||||
}
|
||||
```
|
||||
|
||||
| 写法 | 命中 |
|
||||
|------|------|
|
||||
| `[某某功能开发中]` | ✅ 无分隔符 |
|
||||
| `[搜索接入,待开发]` | ✅ 逗号 |
|
||||
| `[搜索接入-待开发]` | ✅ 连字符 |
|
||||
| `[【待开发】搜索接入]` | ✅ 括号 |
|
||||
| `[这段还没写完]` | ❌ 无词(合法,不计数) |
|
||||
|
||||
- **识别不到不报错、不提示**——描述自由
|
||||
- **误判必然存在**(`[不属于待开发范围]` 会命中):只影响计数,不影响执行;
|
||||
输出带描述原文,人可判断;否定词窗口留 v1.1 可选
|
||||
|
||||
---
|
||||
|
||||
## 4. 桩的语义
|
||||
|
||||
### 4.1 三条规则
|
||||
|
||||
| # | 规则 | 原因 |
|
||||
|---|------|------|
|
||||
| 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 |
|
||||
| 2 | **桩必须写明返回什么** | 空载荷 → warning;写 `None` 也行,但不能什么都不写 |
|
||||
| 3 | **桩不得被当成已完成** | 描述里申报;检索能查到;`view` 有徽章 |
|
||||
|
||||
### 4.2 桩返回什么
|
||||
|
||||
| 手段 | 写法 |
|
||||
|------|------|
|
||||
| 显式空值 | `[某某功能开发中](None)` |
|
||||
| 常量占位 | `[税率预报,模拟](0.1)` |
|
||||
| 假数据 | `[搜索结果,模拟](json.parse text="[]")` |
|
||||
| **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" |
|
||||
|
||||
```markdown
|
||||
## 搜索
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,模拟](json.parse text="[]")
|
||||
```
|
||||
|
||||
### 4.3 惯例(不强制):桩返回值带 `stub: true`
|
||||
|
||||
```markdown
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 工程化:写进 README,提示词同步更新
|
||||
|
||||
### 5.1 README 增补(`README.md` 新节)
|
||||
|
||||
> **工程习惯:允许申报未完成,但不允许假装完成**
|
||||
>
|
||||
> ```markdown
|
||||
> [按关键词检索,接口未接,待开发](None)
|
||||
> ```
|
||||
>
|
||||
> - 桩必须能跑,并写清返回值(写 `None` 也比空着好)
|
||||
> - 描述是自由文本;内置词表只是推荐用词与默认检索集
|
||||
> - 盘点:`marqdo labels pending`;自定义:`--grep 你的词 --also-builtin`
|
||||
> - 门禁:`--baseline` + `--fail-on-increase`(棘轮:只拦新增,不追旧账)
|
||||
> - LLM:接不了就申报;提示词见 `ext/ai/agent.mq.md`
|
||||
|
||||
### 5.2 提示词更新(`ext/ai/agent.mq.md`)
|
||||
|
||||
| 位置 | 现状 | 增补 |
|
||||
|------|------|------|
|
||||
| `:48` 默认 standing(`You are a Marqdo agent…`) | 只讲"源码是真相" | 追加一句申报约定 |
|
||||
| `:39` how-to-act 协议段 | 只讲 CALL/READ | 追加"未完成必须申报" |
|
||||
|
||||
**建议追加文本**(英文,与现有 standing 一致):
|
||||
|
||||
```text
|
||||
When you cannot truly wire a capability, do not fake it silently and never claim it works.
|
||||
Write it as an occlusion with an explicit status instead:
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.pending.
|
||||
```
|
||||
|
||||
**为什么这条对 LLM 有效**:把"编造"变成"填表"——模型不必判断算不算伪造,
|
||||
只需写出状态词并给一个返回值。
|
||||
|
||||
### 5.3 工具面
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `labels pending` | 内置词表口径的未完成清单 |
|
||||
| `labels search --grep … [--json/--count/--also-builtin]` | 任意词盘点 |
|
||||
| `labels search … --changed` | 只看本次变更涉及的 |
|
||||
| MLSP `labels.search` | 协议内同上 |
|
||||
|
||||
### 5.4 指标
|
||||
|
||||
| 指标 | 算法 |
|
||||
|------|------|
|
||||
| `pending_count` | `labels pending --count` |
|
||||
| `unlabeled_empty` | `label.empty_payload` warning 数 |
|
||||
| `stub_ratio` | pending / 遮蔽总数 |
|
||||
| `stub_age` | 需 VCS(可选,不进默认路径) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 生命周期
|
||||
|
||||
```
|
||||
① 写桩 [按关键词检索,接口未接,待开发](None)
|
||||
↓
|
||||
② 盘点 labels pending → 列出它
|
||||
↓
|
||||
③ 开发 换成真实 HTTP 调用
|
||||
↓
|
||||
④ 复核 去掉"待开发"字样、改写描述
|
||||
↓
|
||||
⑤ 数字-1 检索结果自动减少
|
||||
```
|
||||
|
||||
### 6.1 stale 豁免(默认用内置集)
|
||||
|
||||
| 情形 | stale 行为 |
|
||||
|------|-----------|
|
||||
| 描述命中**内置 pending 组**(未完成/假数据) | **豁免** |
|
||||
| 命中 `将删`(废弃) | **豁免** |
|
||||
| 命中 `示例` / `实验` / `待核` | 正常报 |
|
||||
| 空载荷 | **豁免**(它就是桩) |
|
||||
| 无命中、有实现 | 正常报 |
|
||||
| `check --stub-words "A,B"` | **覆盖**内置集,用 A,B 判定豁免 |
|
||||
|
||||
理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale,
|
||||
12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。
|
||||
|
||||
### 6.2 防"做完了忘去掉申报"
|
||||
|
||||
- `labels search --grep … --changed`:本次变更中被改过的桩
|
||||
- 会话末汇总带一行 `pending_touched: 2`(只给数字,不逐条)
|
||||
|
||||
---
|
||||
|
||||
## 7. 与防疲劳机制的协同
|
||||
|
||||
| 机制 | 作用 |
|
||||
|------|------|
|
||||
| 桩豁免 stale(默认内置集) | 12 个桩不会变成 12 条常驻警告 |
|
||||
| 债务用**棘轮**(`--baseline` + `--fail-on-increase`) | 老债不阻塞、新债立刻拦 |
|
||||
| 检索是**按需命令**,不进 `check` 人类输出 | 零噪音 |
|
||||
| 搜不到**不报错** | 描述自由,机器不纠正用词 |
|
||||
| 空载荷 warning 仅作用于新语法 | 不可能产生历史债 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 编译器实现点
|
||||
|
||||
| 位置 | 要做的事 |
|
||||
|------|---------|
|
||||
| `src/parse` | 解析 `[描述](实现)`,**原样保存描述**(不解析、不分类) |
|
||||
| `src/ast.rs` | `Expr::Occluded { label: String, inner: Option<Box<Expr>> }` |
|
||||
| `src/label.rs`(新增) | **内置词表常量** + 描述索引/检索(子串、OR、大小写不敏感)+ L1 引用一致性 + T1 前后对比 |
|
||||
| `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、`label.empty_payload`(**warning,一律**) |
|
||||
| `src/interp.rs` | 描述**不影响求值**;空载荷 → `None` |
|
||||
| `src/main.rs` | `labels pending/search --grep … [--also-builtin/--json/--count/--changed]`;`check --stub-words …` |
|
||||
| `src/mlsp.rs` | `labels.search`(含 `also_builtin`)、`validate.stub_words`、会话汇总 `pending_touched` |
|
||||
| `src/view/render.rs` | 遮蔽渲染:描述为正文、实现可折叠;桩徽章 |
|
||||
| `README.md` | 新增「工程习惯」一节(§5.1) |
|
||||
| `ext/ai/agent.mq.md` | `:48` standing 与 `:39` 协议段追加申报约定(§5.2) |
|
||||
|
||||
**分层**:内置词表是**数据**(常量表),检索是**纯函数**,语法**零依赖**——
|
||||
扩词表不改语法,改语法不动词表。
|
||||
|
||||
---
|
||||
|
||||
## 9. 示例
|
||||
|
||||
### 9.1 无分隔符申报
|
||||
|
||||
```markdown
|
||||
[某某功能开发中](None)
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels pending # 命中(内置「开发中」)
|
||||
```
|
||||
|
||||
### 9.2 假算指标
|
||||
|
||||
```markdown
|
||||
本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。
|
||||
```
|
||||
|
||||
### 9.3 假接通外部系统
|
||||
|
||||
```markdown
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
### 9.4 该报 warning 的空载荷
|
||||
|
||||
```markdown
|
||||
[应纳税额]() # ⚠️ label.empty_payload
|
||||
```
|
||||
|
||||
### 9.5 项目自己的说法(参数层)
|
||||
|
||||
```markdown
|
||||
[接口还在联调,先返回空](json.parse text="[]")
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels search --grep "联调" --also-builtin # 内置 + 自定义一起数
|
||||
```
|
||||
|
||||
### 9.6 任意措辞(合法、不被自动分类,但可被搜)
|
||||
|
||||
```markdown
|
||||
[这段还没写完](0)
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels search --grep 还没写完 # LLM 自己挑的词,照样搜到
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与取舍
|
||||
|
||||
| 风险 | 说明 | 缓解 |
|
||||
|------|------|------|
|
||||
| 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数;输出带原文;否定词窗口留 v1.1 |
|
||||
| 内置词表是语义偏见 | 规定了"什么算未完成" | **两级**:内置只做默认,参数可覆盖/扩展 |
|
||||
| 空载荷 warning 偏多 | 作者爱留空 | 修法极简(写 `None`);仅影响新语法;可留降级旋钮 |
|
||||
| 桩腐化 | 忘去掉申报 | `--changed` + 会话汇总,不做常驻警告 |
|
||||
| 假功能上生产 | 最坏情况 | `view` 显著标记;CI 可 `--count` 门禁 |
|
||||
| LLM 滥用申报逃避检查 | 把真实现标成待开发 | 申报只增加可见性、不减少检查;豁免 stale 的代价是计入债务 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 已定 vs 待定
|
||||
|
||||
**已定(本文即规范)**
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| 描述性质 | 自由文本,不执行,不参与类型/作用域 |
|
||||
| 词表 | **两级**:内置范例/默认 + 参数扩展 |
|
||||
| 空载荷 | **一律 warning**(写 `None` 消除) |
|
||||
| 检索语义 | 子串 + OR + 英文大小写不敏感 |
|
||||
| stale 豁免 | 默认内置 pending/将删组;`--stub-words` 覆盖 |
|
||||
| 棘轮 | `--baseline` + `--fail-on-increase` |
|
||||
| 工程化落点 | README 一节 + `ext/ai` 提示词两处 |
|
||||
|
||||
**待你点头**
|
||||
|
||||
| # | 问题 | 建议 |
|
||||
|---|------|------|
|
||||
| 1 | 内置词表就 §3.2 这六组 | 是 |
|
||||
| 2 | `pending` = 未完成 ∪ 假数据 | 是 |
|
||||
| 3 | `--grep` 替换、`--also-builtin` 合并 | 是 |
|
||||
| 4 | 空载荷"降级旋钮"先不做 | 是(先按一律 warning 跑一段看噪音) |
|
||||
| 5 | 提示词追加文本按 §5.2 写 | 是 |
|
||||
|
||||
> 点头后即按 M1 → M2 → M4 → M9 → M6 开工;首批金样用 §9 的六个例子。
|
||||
@@ -0,0 +1,624 @@
|
||||
# 遮蔽语法(Occlusion Syntax):`[描述](实现)` 设计与实施总纲
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 实施中**(M0 起,本文档为实施依据) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 决策 | 纯度;标签可省略书写但**编译器报错**;新鲜度校验**不依赖 git**;**会话末做一次性汇总** |
|
||||
| 定位 | 本文把 `[]()` 从「若干语法的集合」重新定义为**一种语法、一个目的:遮蔽** |
|
||||
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) · [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) · [staleness-providers.md](staleness-providers.md) · [t1-session-staleness.md](t1-session-staleness.md) |
|
||||
| 增补 | [occlusion-description-and-search.md](occlusion-description-and-search.md) — **两级词表(内置=范例/默认;参数=扩展)**;空载荷一律 warning;桩语义;工程化落点(README + `ext/ai` 提示词);**`()` 内部语法定稿见该文 §2** |
|
||||
|
||||
---
|
||||
|
||||
## 0. 术语(后文一律按此使用)
|
||||
|
||||
| 术语 | 含义 |
|
||||
|------|------|
|
||||
| **遮蔽(occlusion)** | 用一段人话盖住一段实现:读者看人话,机器看实现 |
|
||||
| **描述(label)** | `[]` 里的文本。**不可执行**,只给人读,是可被机器核验的断言 |
|
||||
| **实现(payload)** | `()` 里的表达式。**唯一执行**的部分 |
|
||||
| **显式遮蔽** | `[描述](实现)` —— 描述与实现写在同一处 |
|
||||
| **隐式遮蔽** | 叙述段落 + 紧接的 `>` 调用 —— 描述是上方那段散文 |
|
||||
| **新鲜(fresh)** | 描述与实现仍然相符 |
|
||||
| **过期(stale)** | 实现变了、描述没变 —— 描述可能已不再成立 |
|
||||
|
||||
## 0.1 开发环境前置(实施前必须就绪)
|
||||
|
||||
本机(glibc 2.36、无系统 gcc/go/python3)已验证过的完整环境:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # rust 1.81 + go 1.25 + python 3.12 + zig(gcc shim, glibc 2.36)
|
||||
./scripts/build-web-plugin.sh # 产出 libweb.so,否则 gold 测试会失败
|
||||
```
|
||||
|
||||
两个非直觉约束(踩过的坑,写进文档免得后人重踩):
|
||||
|
||||
| 约束 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `AccessDenied` | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接 `signal: aborted`、zig `AccessDenied` | `TMPDIR` 指向可写且**可执行**目录 |
|
||||
|
||||
基线(改动前必须先跑通):`cargo test --release` → **554 passed / 0 failed**;
|
||||
`marqdo check` 对 `lib/` + `ext/ai/`(59 文件)→ **0 warning / 0 error**。
|
||||
任何里程碑都不得让这两个数字变差。
|
||||
|
||||
---
|
||||
|
||||
# Part I · 示例先行
|
||||
|
||||
## 1. 六个示例
|
||||
|
||||
### 1.1 嵌套取值:不可读 → 可读
|
||||
|
||||
**今天**(读者要在三层括号间来回跳):
|
||||
|
||||
```markdown
|
||||
**单价 = [1]([苹果]([水果类](货架)))**
|
||||
```
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
**单价 = [水果类里苹果的第 1 项价格](at(at(at(货架, 水果类), 苹果), 1))**
|
||||
```
|
||||
|
||||
人读方括号,机器读圆括号。**嵌套再深,读者也只看一句人话。**
|
||||
|
||||
### 1.2 长表达式打断叙述
|
||||
|
||||
**今天**:
|
||||
|
||||
```markdown
|
||||
本季度应缴税额为 **金额 * 税率 * (1 - 减免比例) + 附加费**,请注意申报期限。
|
||||
```
|
||||
|
||||
一句话被一串符号劈成两半。
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
本季度应缴税额为 **[应缴税额](金额 * 税率 * (1 - 减免比例) + 附加费)**,请注意申报期限。
|
||||
```
|
||||
|
||||
叙述仍然是句子;复杂算式被折进 `()`。
|
||||
|
||||
### 1.3 抽象层次混杂:把实现藏到读者不需要看的地方
|
||||
|
||||
**今天**(读者被迫读实现细节):
|
||||
|
||||
```markdown
|
||||
价格随会员等级浮动,具体为 **基础价 * 会员折扣[等级](折扣表) * (1 + 旺季系数)**。
|
||||
```
|
||||
|
||||
**遮蔽之后**(论证留在叙述里,算法藏起来):
|
||||
|
||||
```markdown
|
||||
价格随会员等级浮动:**[会员最终价](基础价 * at(折扣表, 等级) * (1 + 旺季系数))**。
|
||||
```
|
||||
|
||||
### 1.4 循环:来源从此可见
|
||||
|
||||
**今天**(渲染成「名为果的链接指向篮子」,看不出是遍历):
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
**总重 = 总重 + [重量](果)**
|
||||
```
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
**总重 = 总重 + [重量](at(果, 重量))**
|
||||
```
|
||||
|
||||
「从哪来」写进了人话——**不再依赖读者是否用了 `marqdo view` 才能看懂。**
|
||||
|
||||
### 1.5 带空格的函数名(**已实测验证**)
|
||||
|
||||
**今天**(`>` 调用无法表达,这是缺陷 D8):
|
||||
|
||||
```markdown
|
||||
> 加一 号 31 # ❌ unknown function `加一` —— 空格把名字切断了
|
||||
```
|
||||
|
||||
**遮蔽之后**(`(` 成为明确分隔符,空格不再是切词依据):
|
||||
|
||||
```markdown
|
||||
**结果 = [加一之后的值](加一 号(31))**
|
||||
```
|
||||
|
||||
**实测证据**(1.5.2 原型):
|
||||
|
||||
| 写法 | 结果 |
|
||||
|------|------|
|
||||
| `> 加一 号 31` | ❌ `unknown function 加一` |
|
||||
| `加一 号(31 )`(括号调用) | ✅ **32** |
|
||||
| `问候("世界")` | ✅ `你好 世界` |
|
||||
|
||||
> **因为 `()` 里的 callee 取「第一个 `(` 之前的全部文本」,空格不再有任何歧义。**
|
||||
> 这正是你说的「`()` 内部对带空格的函数名处理方式很多样」——而且它不只是"很多样",
|
||||
> 它是**结构上唯一正确**的处理:用括号做边界,而不是用空白。
|
||||
|
||||
### 1.6 反例:什么时候**不该**遮蔽
|
||||
|
||||
```markdown
|
||||
# 反例:为遮蔽而遮蔽
|
||||
|
||||
**总计 = [总计](a + b)** # ❌ 描述等于代码,白加一层
|
||||
**[价格](price)** # ❌ 描述等于变量名,无信息增量
|
||||
```
|
||||
|
||||
**判据**:如果描述不能比实现**多提供信息**(意图、来源、单位、why),就不要遮蔽。
|
||||
遮蔽的收益是"读者不用读实现",若描述只是把实现读了一遍,收益为零、成本照付。
|
||||
|
||||
---
|
||||
|
||||
## 2. 定义:遮蔽语法
|
||||
|
||||
```markdown
|
||||
[ 描述 ] ( 实现 )
|
||||
└─ 人读 ─┘ └─ 机读 ─┘
|
||||
```
|
||||
|
||||
### 2.1 三条铁律
|
||||
|
||||
| # | 铁律 | 理由 |
|
||||
|---|------|------|
|
||||
| 1 | `[]` **永不执行** | 与「叙述默认安全」一致:只说人话的东西不改变程序行为 |
|
||||
| 2 | `()` **是唯一执行体** | 语义只有一处,读者不必猜两层 |
|
||||
| 3 | **遮蔽必须可校验** | 见 §2.2 |
|
||||
|
||||
### 2.2 核心定理:遮蔽创造信任负债
|
||||
|
||||
> **你把实现藏起来,读者就必须相信描述。**
|
||||
> 所以:**遮蔽 ⇔ 描述成为承重结构 ⇔ 必须可被机器核验。**
|
||||
|
||||
这条定理把「新鲜度校验」从"附加功能"变成"遮蔽的**代价与前提**":
|
||||
|
||||
- 不遮蔽 → 读者能自己核对代码 → 描述过期无伤大雅(顶多是注释旧了)
|
||||
- 遮蔽 → 读者看不见代码 → **描述一旦过期,文档就变成了假的**
|
||||
|
||||
所以平台必须提供:**实现一变,描述立刻被质疑**。
|
||||
这不是锦上添花,是这套语法的**合法性来源**。
|
||||
|
||||
### 2.3 为什么必须是「链接外形」
|
||||
|
||||
| 性质 | 链接(`[]()`) | 其它候选 |
|
||||
|------|--------------|---------|
|
||||
| 文本不可执行、目标可执行 | ✅ 天生分离 | 括号内联(`(...)`)做不到"只读文本" |
|
||||
| 与 Markdown 渲染一致 | ✅ 渲染成超链接,读者熟悉 | 箭头 `→` 是自造符号 |
|
||||
| 可承载任意长文本 | ✅ | 下标 `x[y]` 放不下长描述 |
|
||||
| 可被工具定位/跳转 | ✅ 天然锚点 | 注释块不行 |
|
||||
|
||||
**一句话**:链接是唯一"人类文本与机器目标天然分工"的 Markdown 结构,
|
||||
而 Marqdo 正好需要这个分工。
|
||||
|
||||
---
|
||||
|
||||
# Part II · 应用场景(按**动机**分类,不按语法分类)
|
||||
|
||||
**重要**:遮蔽语法**不是**"循环语法""取元语法""调用语法"。
|
||||
它没有专属用途——它是**一种处理不可读性的手段**。任何表达式都可被遮蔽。
|
||||
|
||||
## 3. 五类遮蔽动机
|
||||
|
||||
| 动机 | 症状 | 遮蔽后得到什么 |
|
||||
|------|------|---------------|
|
||||
| **A 不可读** | 嵌套过深、括号堆叠 | 读者只看一句人话 |
|
||||
| **B 打断叙述** | 长算式把句子劈成两半 | 句子完整,算式退居括号 |
|
||||
| **C 层次混杂** | 论证与实现细节混排 | 论证在上,实现可折叠 |
|
||||
| **D 来源不明** | 看不出数据从哪来(如 `- [果](篮子)`) | 来源写进人话 |
|
||||
| **E 名称受限** | 函数名含空格写不出调用(D8) | `(` 做分隔符,名字自由 |
|
||||
|
||||
> 注意 D 与 E:它们是**遮蔽顺带解决的问题**,不是遮蔽的目的。
|
||||
> 若把它们写成"循环语法 / 调用语法",就会限制这套语法的适用面;
|
||||
> 按动机写,它才能覆盖未来尚未想到的不可读情形。
|
||||
|
||||
## 4. 什么时候不该遮蔽
|
||||
|
||||
| 情形 | 说明 |
|
||||
|------|------|
|
||||
| 描述 = 实现(§1.6) | 无信息增量 |
|
||||
| 只用一次且已足够可读 | 遮蔽会**增加**读者的跳转成本 |
|
||||
| 描述无法具体化 | 笼统的描述不可校验,等于把信任成本转嫁给读者 |
|
||||
| 性能敏感的热路径 | 遮蔽本身不贵,但过度嵌套的表达式不利于后续优化 |
|
||||
|
||||
---
|
||||
|
||||
# Part III · 语法规范
|
||||
|
||||
## 5. 文法
|
||||
|
||||
```
|
||||
遮蔽 ::= '[' 描述 ']' '(' 表达式? ')'
|
||||
描述 ::= 非空自由文本(可含 `实体`、空格、关键词;v1 不跨行)
|
||||
表达式 ::= 现有表达式文法(含 §6 的调用形);**可空** → 值为 None
|
||||
|
||||
带括号的调用 ::= callee '(' 实参列表? ')'
|
||||
callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2)
|
||||
实参列表 ::= 实参 (分隔 实参)*
|
||||
实参 ::= 名 '=' 值 | 值
|
||||
分隔 ::= 空白 | ',' # 逗号可选、容错
|
||||
```
|
||||
|
||||
出现位置:**表达式位置 / 语句位置 / 循环项位置**(三处形态一致)。
|
||||
|
||||
> **空载荷 `()`**:合法(值 `None`),但**一律**报 `label.empty_payload`(warning)——
|
||||
> 修法是显式写 `None` 或一个真实返回值。描述是自由文本,检索由**调用方传词**(子串匹配,无分隔符要求),
|
||||
> 详见 [occlusion-description-and-search.md](occlusion-description-and-search.md) §3–§4。
|
||||
|
||||
## 6. `()` 之内
|
||||
|
||||
### 6.1 表达式文法不变
|
||||
|
||||
`()` 里就是今天 Marqdo 的表达式:算术、比较、调用、变量(`` `名` ``)、字面量。
|
||||
**不引入第二套表达式语言。**
|
||||
|
||||
### 6.2 callee 可以含空格(解决 D8)
|
||||
|
||||
规则:**callee = 第一个 `(` 之前的全部文本**(去首尾空白)。
|
||||
|
||||
```markdown
|
||||
[加一之后的值](加一 号(31)) # callee = "加一 号"
|
||||
[会员最终价](会员价(等级=2 )) # 具名实参
|
||||
```
|
||||
|
||||
依据实测:`加一 号(31 )` → `32`。
|
||||
(当前实现的参数分词器会把 `)` 吞进末个实参,需要 M1 修掉;带尾随空格即可绕过。)
|
||||
|
||||
### 6.3 取元怎么写(纯度要求)
|
||||
|
||||
`[键](集合)` **不再是取元**(见 §9 迁移)。取元改为函数形:
|
||||
|
||||
| 语义 | 写法 |
|
||||
|------|------|
|
||||
| 取 Map 成员 | `at(表, 键)` 或 `get(表, 键)` |
|
||||
| 取 List 第 n 项(1-based) | `at(列表, 1)` |
|
||||
| 缺键不崩 | `get(表, 键, 默认值)` |
|
||||
|
||||
**理由**:与调用同一外形,读者不必区分"这是取元还是调用"——
|
||||
而这正是遮蔽语法要消灭的那种"两套读法"。
|
||||
|
||||
### 6.4 循环
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
```
|
||||
|
||||
- `[]` = 人读描述(来源、单位都可写)
|
||||
- `()` = `遍历 <集合> 为 <变量>`
|
||||
- **变量名从 `[]` 搬进 `()`**:`[]` 不再兼任标识符(否则"描述"与"名字"又打架)
|
||||
|
||||
## 7. 标签规则
|
||||
|
||||
| 规则 | 行为 |
|
||||
|------|------|
|
||||
| 空标签 `[](…)` | **error `label.missing`**(你说的"可省略书写但编译器报错") |
|
||||
| 标签内 `` `实体` `` | 视为**断言**:该实体必须可解析且出现在 `()` 中(§10.1) |
|
||||
| 标签含空格、中文、标点 | 允许 |
|
||||
| 标签含 `]` | 不允许(转义规则见 §11.3) |
|
||||
| 标签跨行 | v1 不支持(跨行标签会让定位困难) |
|
||||
|
||||
## 8. 与既有语法的关系
|
||||
|
||||
| 现有 | 归位 |
|
||||
|------|------|
|
||||
| `> 调用` | **保留**,作为"短形调用";同时纳入隐式遮蔽检查(§10.2) |
|
||||
| `[callee] args` | **保留**为消歧/前置修饰形;仓库实测可执行使用量为 **0**(189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
| `[键](集合)` | **废止**(改为 `at/get`;复用 `[]()` 外形)→ 需版本门 |
|
||||
| `- [项](集合)` | **废止**(改为 `- [描述](遍历 …)`)→ 需版本门 |
|
||||
| `*…*` 返回 | 不变 |
|
||||
|
||||
## 9. 迁移(实测规模)
|
||||
|
||||
| 受影响 | 数量 | 文件 |
|
||||
|--------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 |
|
||||
| 可执行方括号调用 | **0** | — |
|
||||
| `Caller:` 说明行(不执行,无需迁移) | 189 | — |
|
||||
|
||||
**危险点:同形换义。** 迁移后 `[键](集合)` 会变成"遮蔽整个集合",语义静默改变。
|
||||
因此必须:
|
||||
|
||||
1. **硬报错**:purity 模式下遇到旧形 → `syntax.legacy_index`,附迁移示例
|
||||
2. **机械迁移工具**:`marqdo migrate labels --write`
|
||||
3. **临时标签**:工具生成的标签 = 原键名,并标记为 `label.provisional`(**hint**,不报 error)
|
||||
—— 不能让 506 处都变成红错,否则没人能开工
|
||||
|
||||
## 10. 错误信息规范
|
||||
|
||||
| code | 级别 | 触发 | 建议文案 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | error | `[](…)` | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.ref_dangling` | error | 标签引用的实体不存在 | 「`X` 已不存在;改成 `Y` 或删掉该引用」 |
|
||||
| `label.stale` | hint/warning | 实现变了、标签没变 | 「标签说 A,实现现在是 B;二者之一需改」 |
|
||||
| `label.provisional` | hint | 标签 = 原键名 | 「建议把键名改写成读者能懂的一句话」 |
|
||||
| `syntax.legacy_index` | error | 旧 `[键](集合)` | 「取元请写 `at(集合, 键)`;遮蔽请写 `[描述](at(集合, 键))`」 |
|
||||
|
||||
---
|
||||
|
||||
# Part IV · 新鲜度校验
|
||||
|
||||
## 11. 两种遮蔽关系
|
||||
|
||||
| 类型 | 形态 | 描述在哪 |
|
||||
|------|------|---------|
|
||||
| **显式遮蔽** | `[描述](实现)` | `[]` 里 |
|
||||
| **隐式遮蔽** | 叙述段落 + 紧接 `> 调用` | 上方那一段散文 |
|
||||
|
||||
**两者都要查**——这是你明确要求的:"`>` 这种函数调用其实也应该被检查是否存在过期现象"。
|
||||
|
||||
### 11.1 L1:引用一致性(零依赖、确定性)
|
||||
|
||||
**规则**:断言 = 标签内的 `` `实体` ``。
|
||||
|
||||
1. 实体必须可解析(当前作用域/模块存在)
|
||||
2. 实体必须出现在 `()` 的实际内容中(或经调用链可达)
|
||||
|
||||
不满足 → `label.ref_dangling`(error)。
|
||||
|
||||
**为什么低假阳性**:只有**显式反引号**才算断言;纯口语不参与判定。
|
||||
**为什么能落地**:复用 Marqdo 已有的 `` `名` `` = 实体约定,**零新记号**。
|
||||
|
||||
### 11.2 隐式遮蔽:`>` 调用的描述从哪来
|
||||
|
||||
**规则**:取 `>` 行**上方紧邻的叙述段落**(连续非空行,遇空行/标题/代码行即止)作为描述。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额:
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
```
|
||||
|
||||
检查:
|
||||
- 段落里 `` `税率` ``、`` `档位` `` 必须**出现在调用实参或 callee 中**,或可解析
|
||||
- 若无叙述段 / 叙述里无反引号 → **不检查**(沉默,零噪音)
|
||||
|
||||
**这条规则的价值**:让**存量代码**(今天所有 `>` 调用)**无需改写**就获得新鲜度保护
|
||||
——只要作者在调用上方写了一句带反引号的说明。
|
||||
|
||||
### 11.3 转义
|
||||
|
||||
| 需求 | 写法 |
|
||||
|------|------|
|
||||
| 标签里要写 `]` | `\]` |
|
||||
| 标签里要写 `` ` ``(字面) | `` \` `` |
|
||||
| 实现里要写 `)` | 由括号配对规则处理(字符串内 `)` 不算) |
|
||||
|
||||
### 11.4 T1:会话内检测(不依赖 git)
|
||||
|
||||
**机制**:`repair_apply` 内部同时持有 before(`source`)与 after(`new_source`),
|
||||
解析两版,比较每个标签的 `()` 指纹:
|
||||
|
||||
> `stale ⟺ 标签文本未变 ∧ () 指纹变了`
|
||||
|
||||
- 按**标签文本**配对(不按行号)→ 移动代码不误报
|
||||
- 标签文本变了 → 视为作者在更新描述,**不报**
|
||||
- 新增/删除标签 → 不报
|
||||
- 指纹只需**进程内一致**(`Expr` 现为 `Debug`,可用 `format!("{:?}")`;或补 `derive(PartialEq)`)
|
||||
|
||||
**为什么这能消灭疲劳**:作用域 = 模型自己的 diff;投递 = 一次;自包含(下轮不重复)。
|
||||
|
||||
### 11.5 会话末一次性汇总(**你要求要做**)
|
||||
|
||||
T1 刻意"不重复",因此需要**闭合**:
|
||||
|
||||
- **会话**定义:MLSP 一条连接的生命周期;CLI 为一次 `marqdo check` 运行
|
||||
- 会话结束时输出**一次**:
|
||||
|
||||
```json
|
||||
{ "session": { "labels_stale_seen": 3, "labels_fixed": 1, "labels_outstanding": 2,
|
||||
"items": ["按 `税率` 计算总价", "篮子里的果子"] } }
|
||||
```
|
||||
|
||||
- 只报**数字 + 标签文本**,不重复诊断详情(详情已在各轮给过)
|
||||
- 若 `outstanding > 0`,可用 `"block"` 模式让客户端不得直接结束任务
|
||||
|
||||
### 11.6 能力自述与降级
|
||||
|
||||
| 环境 | 可用层 | 行为 |
|
||||
|------|--------|------|
|
||||
| CLI + VCS | L1 + T1 + T2 | 可跨会话 |
|
||||
| CLI 无 VCS | L1 + T1 | 仅会话内 |
|
||||
| agent 沙箱(`exec=false`) | L1 + T1 | **不调 git** |
|
||||
| 浏览器 WASM | L1 + T1 | 无持久状态 |
|
||||
| 单文件 / zip | L1 + T1 | — |
|
||||
|
||||
**`labels status` 必须显示当前启用了哪几层**,避免"没报 = 没问题"的误判。
|
||||
|
||||
---
|
||||
|
||||
# Part V · 实施计划
|
||||
|
||||
## 12. 里程碑总览
|
||||
|
||||
| M | 名称 | 产出 | 依赖 | 风险 |
|
||||
|---|------|------|------|------|
|
||||
## 13.1 实施进度
|
||||
|
||||
**全部完成**:M0 · M1 · M2 · M2.5 · M3 · M4 · M5 · M6 · M7 · M8 · M9 · M10
|
||||
(每步含变更文档与测试;全量 605 passed / 0 failed;0 编译警告)。
|
||||
|
||||
| 里程碑 | 变更文档 |
|
||||
|--------|---------|
|
||||
| M1 | [change-m1-paren-call.md](change-m1-paren-call.md) |
|
||||
| M2 | [change-m2-occlusion.md](change-m2-occlusion.md) |
|
||||
| M2.5 | [change-m25-label-diagnostics.md](change-m25-label-diagnostics.md) |
|
||||
| M3 | [change-m3-access-and-loop.md](change-m3-access-and-loop.md) |
|
||||
| M4 | [change-m4-label-refs.md](change-m4-label-refs.md) |
|
||||
| M5 | [change-m5-implicit-occlusion.md](change-m5-implicit-occlusion.md) |
|
||||
| M6 | [change-m6-t1-session.md](change-m6-t1-session.md) |
|
||||
| M7 | [change-m7-migration.md](change-m7-migration.md) |
|
||||
| M8 | [change-m8-ratchet.md](change-m8-ratchet.md) |
|
||||
| M9 | [change-m9-label-search.md](change-m9-label-search.md) |
|
||||
| M10 | [change-m10-engineering-habits.md](change-m10-engineering-habits.md) |
|
||||
|
||||
| **M0** | 语义冻结 | 本文档 Accepted + 术语表进 `doc/design/` | — | 无 |
|
||||
| **M1** | `()` 内调用增强 | `callee(args)`:`)` 终止、逗号、嵌套、**空格 callee** | M0 | 中(分词器共享) |
|
||||
| **M2** | 遮蔽语法 | `[描述](表达式)` + 标签节点 + `label.missing` | M1 | 中 |
|
||||
| **M3** | 普通取元与循环 | `at/get` 落地;`- [描述](遍历 …)` | M2 | 中 |
|
||||
| **M4** | L1 引用一致性 | `label.ref_dangling`(error) | M2 | 低 |
|
||||
| **M5** | 隐式遮蔽检查 | `>` 上方叙述 vs 实参 | M4 | 低 |
|
||||
| **M6** | T1 + 会话汇总 | `repair_apply.check_labels` + 汇总 | M2 | 低 |
|
||||
| **M7** | 迁移与版本门 | `marqdo migrate labels`、`syntax.legacy_index` | M3 | **高** |
|
||||
| **M8** | 呈现与门禁 | `view` 徽章、`labels status/review`、CI | M4–M6 | 低 |
|
||||
| **M9** | 描述检索与桩 | **两级词表**:`labels pending`(内置集)+ `labels search --grep … [--also-builtin]`、MLSP `labels.search`、空载荷 warning | M2 | 低 |
|
||||
| **M10** | 工程化落点 | `README.md` 工程习惯一节 + `ext/ai/agent.mq.md` 提示词(standing 与 how-to-act)追加申报约定 | M9 | 低 |
|
||||
|
||||
**顺序建议**:M0 → M1 → M2 → (M2.5 空载荷/描述) → M4 → **M9** → **M10** → M6 → M5 → M3 → M7 → M8
|
||||
|
||||
理由:**先把"断言 + 复核 + 修复回路"跑通(M2/M4/M6),再动 506 处迁移(M7)**。
|
||||
迁移一旦开始,中间态很痛;而 L1/T1 在旧语法上就能验证。
|
||||
|
||||
---
|
||||
|
||||
## 13. 每个里程碑的详细步骤
|
||||
|
||||
### M0 · 语义冻结
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 改动 | 本文档标记 `Accepted`;`doc/README.md` 登记 |
|
||||
| 要点 | 术语表(§0)作为唯一用词标准;`[]()` 一律称"遮蔽",不称"循环/取元/调用语法" |
|
||||
| 验收 | 团队评审通过;后续文档一律引用本文术语 |
|
||||
|
||||
### M1 · `()` 内调用增强
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `callee(args)` 可用:`)` 作实参终止、可选逗号、嵌套调用、**callee 允许空格** |
|
||||
| 改动文件 | `src/parse/expr.rs`(`parse_call_args` / `split_first_token` / `find_next_arg_boundary` / 新增 `try_paren_call`)、`src/parse/mod.rs`(`looks_like_paren_call` 接入两处调用判定) |
|
||||
| 关键点 | ① `)` 必须是实参终止符(今天会吞进末个实参)② 逗号可容错剥离 ③ 嵌套 `f(g(1))` 需括号深度 ④ `callee = 第一个 '(' 前全部文本`(空格合法) |
|
||||
| 测试 | 新增金样 `tests/structure/paren-call.mq.md`:单参/多参/具名/字符串/嵌套/空格名/库路径/方法 |
|
||||
| 验收 | 上述金样全绿;`cargo test --release` **554 全绿不减**;**双后端**(tree + `--backend bytecode`)均通过 |
|
||||
| 回滚 | 独立提交,可单独 revert(不改既有语义,风险低) |
|
||||
|
||||
### M2 · 遮蔽语法
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `[描述](表达式)` 解析为 `Expr::Occluded { label, inner }` |
|
||||
| 改动文件 | `src/ast.rs`(新增节点 + `PartialEq`)、`src/parse/mod.rs`(表达式/语句/循环三处入口)、`src/interp.rs`(求值时透明传递 inner)、`src/bytecode/compile.rs`+`vm.rs`(编译为 inner,label 只留在调试信息) |
|
||||
| 关键点 | ① 遮蔽对语义**完全透明**(`[d](e)` 的值 = `e` 的值)② label 必须存进 AST(供 L1/T1/诊断定位)③ 空 label → `label.missing` |
|
||||
| 测试 | 金样:三处位置各一例;label 含中文/空格/标点;`label.missing` 反例 |
|
||||
| 验收 | 双后端一致;554 全绿;`marqdo check` 对空标签报 error |
|
||||
| 回滚 | 独立提交;新语法是增量的 |
|
||||
|
||||
### M3 · 普通取元与循环
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `at(表, 键)` / `get(表, 键, 默认)` 可用;`- [描述](遍历 集合 为 变量)` 可用 |
|
||||
| 改动文件 | `src/interp.rs`(`at`/`get` 内建或库函数)、`src/parse/mod.rs`(循环新形)、`lib/table.mq.md`(`get` 带默认值) |
|
||||
| 关键点 | 1-based 与现有 `at value= index=` 保持一致;`get` 缺键返回默认而非崩(修 D5 的痛点) |
|
||||
| 测试 | 金样:Map 取元、List 下标、缺键默认、循环 |
|
||||
| 验收 | 双后端一致;554 全绿 |
|
||||
|
||||
### M4 · L1 引用一致性
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | 标签内 `` `实体` `` 校验:可解析 + 出现在 `()` |
|
||||
| 改动文件 | **新增 `src/label.rs`**(标签模型、引用抽取、校验)、`src/check.rs`(接入)、`src/diagnostics.rs`(复用 `doc_anchor`/`doc_quote`,新增 `label_ref`) |
|
||||
| 关键点 | ① 只认反引号(不猜中文词)→ 低假阳性 ② `doc_anchor` = 标签 span,`doc_quote` = 标签原文 ③ `code` 字段用 `label.ref_dangling` |
|
||||
| 测试 | 单元:抽取/解析/缺失;金样:悬空引用的 error、正常引用的通过 |
|
||||
| 验收 | 554 全绿;对现有仓库跑 `check` 仍为 **0 error**(除非真有悬空) |
|
||||
|
||||
### M5 · 隐式遮蔽(`>` 上方叙述)
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `>` 调用的描述 = 上方紧邻叙述段;其反引号实体须出现在实参/callee |
|
||||
| 改动文件 | `src/label.rs`(段落归属规则)、`src/check.rs` |
|
||||
| 关键点 | ① 段落边界:空行/标题/代码行即止 ② 无反引号则跳过(零噪音) ③ 默认级别 **hint** |
|
||||
| 测试 | 金样:三种(有实体且匹配 / 有实体不匹配 / 无叙述) |
|
||||
| 验收 | 554 全绿;现有仓库不因该规则新增 error |
|
||||
|
||||
### M6 · T1 + 会话汇总
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `repair_apply` 支持 `check_labels`;会话末输出一次性汇总 |
|
||||
| 改动文件 | `src/mlsp.rs`(`repair_apply` 内比 before/after;新增 `session.summary` 方法或响应字段)、`src/label.rs`(标签配对与指纹) |
|
||||
| 关键点 | ① 按标签文本配对 ② 标签变则不报 ③ 指纹进程内一致即可 ④ 会话状态按**连接**保存 |
|
||||
| 测试 | 集成:`repair_apply` 改 `()` 不改 `[]` → 返回 stale;改 `[]` → 不返回;会话末汇总数字正确 |
|
||||
| 验收 | 双后端;554 全绿;**无 VCS 环境下同样工作**(CI 里用临时目录验证) |
|
||||
|
||||
### M7 · 迁移与版本门
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `[键](集合)` / `- [项](集合)` 在 purity 模式下**硬报错**;提供机械迁移 |
|
||||
| 改动文件 | `src/parse/expr.rs`(`link_index_shape_ahead` 改为报 `syntax.legacy_index`)、**新增 `src/migrate.rs`** + `src/main.rs` 子命令 `marqdo migrate labels` |
|
||||
| 关键点 | ① 报错文案必须给"改成什么" ② 迁移生成 `[键](at(集合, 键))`,标 `label.provisional` ③ 一次性完成 506+44 处,避免中间态 ④ 迁移后必须跑全量回归 + 逐文件抽样 `run` |
|
||||
| 测试 | 迁移前快照→迁移→回归对比;抽样 20 个文件 `run` 输出一致 |
|
||||
| 验收 | 554 全绿;`marqdo check` 全仓 0 error;抽样输出无变化 |
|
||||
| 回滚 | **必须整批回滚**(中间态不可用),建议单独分支 |
|
||||
|
||||
### M8 · 呈现与门禁
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `view` 显示遮蔽徽章与新鲜度;`labels status/review/confirm`;CI 可 gate |
|
||||
| 改动文件 | `src/view/render.rs`(遮蔽渲染:显示 label,折叠 payload)、`src/main.rs`(`labels` 子命令)、`scripts/ci-*.sh` |
|
||||
| 关键点 | ① `view` 里 label 是正文、payload 可折叠(这正是遮蔽的呈现价值) ② `labels status` 报能力层级与债务数字 |
|
||||
| 验收 | 渲染截图人工评审;`labels status` 在无 VCS 环境正确降级 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 测试计划(贯穿全部里程碑)
|
||||
|
||||
| 层 | 内容 | 门禁 |
|
||||
|----|------|------|
|
||||
| 单元 | 解析/求值/标签抽取/指纹比较 | `cargo test --lib` 全绿 |
|
||||
| 金样 | 新增 `tests/structure/occlusion*.mq.md`、`paren-call*.mq.md` | `tests/gold.rs` 全绿 |
|
||||
| 回归 | 全量 `554`(现基线) | 不得减少 |
|
||||
| 双后端 | tree 与 `--backend bytecode` 各跑一遍 | 结论一致 |
|
||||
| 差异 | 迁移前后同文件 `run` 输出逐字节相同 | 抽样 ≥20 文件 |
|
||||
| 反向 | 故意破坏断言/标签,确认能报 | 每条规则至少一个反例 |
|
||||
| 环境 | 无 git / 沙箱(`exec=false`)/ WASM 构建 | 不崩、不报依赖错 |
|
||||
| 性能 | 1000 标签文件的 `check` 耗时 | 不劣化 >10% |
|
||||
|
||||
**反向验证是硬要求**:每个新检查必须证明"它真的会响",
|
||||
否则就是在写永不触发的代码(本项目已多次遇到"静默通过"的缺陷)。
|
||||
|
||||
---
|
||||
|
||||
## 15. 风险登记
|
||||
|
||||
| 风险 | 概率 | 影响 | 缓解 |
|
||||
|------|------|------|------|
|
||||
| M1 分词器改动波及所有调用 | 中 | 高 | 独立提交 + 554 回归 + 双后端 |
|
||||
| M7 迁移中间态不可用 | 高 | 高 | 整批迁移、单独分支、可整批回滚 |
|
||||
| 遮蔽被滥用(描述=实现) | 高 | 中 | `label.provisional` hint + §1.6 反例进教程 |
|
||||
| 标签自然语言无法核验 | 必然 | 中 | 只认反引号断言(可证伪才检查) |
|
||||
| 误报疲劳 | 中 | **高** | T1 变更驱动 + hint 默认 + 会话末汇总 |
|
||||
| 旧语法语义静默改变 | 中 | **高** | `syntax.legacy_index` 硬报错 |
|
||||
| `Expr` 无 `PartialEq` | 确定 | 低 | 先用 `Debug`;或补 derive |
|
||||
|
||||
---
|
||||
|
||||
# Part VI · 待决策
|
||||
|
||||
| # | 问题 | 建议 |
|
||||
|---|------|------|
|
||||
| 1 | 取元函数名用 `at` 还是 `get`(两者都留?) | 都留:`at` 严格、`get` 带默认 |
|
||||
| 2 | 实参分隔用逗号还是空白 | 两者都接受(逗号可选、容错) |
|
||||
| 3 | 循环新形用 `遍历 集合 为 变量` 还是别的 | 先用它,后续可加别名 |
|
||||
| 4 | `label.stale` 默认级别 | **hint**(会话末汇总再提) |
|
||||
| 5 | M7 迁移是否在本文档同批做 | **否**:M2/M4/M6 先上线并验证,再动迁移 |
|
||||
| 6 | 临时标签(`label.provisional`)是否接受 | **接受**,否则 506 处无法开工 |
|
||||
| 7 | 标签是否允许跨行 | v1 不允许 |
|
||||
| 8 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
|
||||
|
||||
---
|
||||
|
||||
## 附:一句话总结
|
||||
|
||||
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
|
||||
> 它用链接的天然分工(人话 / 目标)实现这一点,
|
||||
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
|
||||
> 而 `>` 调用同样在负债之列。
|
||||
+18
-2
@@ -314,10 +314,15 @@ type: Marqdo Agent Skill
|
||||
title: <短名>
|
||||
sig: <12hex>
|
||||
resource: ../../resources/<slug>.mq.md
|
||||
status: stable | candidate
|
||||
status: stable | candidate | quarantine
|
||||
llm_free: true | false
|
||||
quality: <int>
|
||||
hits: <int>
|
||||
# O2 optional metadata (from workbook frontmatter; see §7.5):
|
||||
applies_when: <text condition or tag>
|
||||
fixtures: <relative .mq.md proof path>
|
||||
sandbox_profile: default | readonly | <name>
|
||||
proof: <relative .mq.md> # alias of fixtures for sandbox gate
|
||||
generated:
|
||||
by: marqdo-agent/plan
|
||||
at: <ISO8601>
|
||||
@@ -331,7 +336,7 @@ verified:
|
||||
Prefer spawning `resource` over re-planning.
|
||||
```
|
||||
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
|
||||
|
||||
### 7.3 任务签名 → Concept 路径
|
||||
|
||||
@@ -401,6 +406,17 @@ Prefer spawning `resource` over re-planning.
|
||||
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
|
||||
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
|
||||
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
|
||||
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
|
||||
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
|
||||
|
||||
### 7.5a 技能 frontmatter 约定(O2 B1)
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
|
||||
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
|
||||
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
|
||||
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,229 @@
|
||||
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`[函数名](参数1 参数2)` 这种写法有没有可能成立;调用能否更符合人读习惯」 |
|
||||
| 更正 | 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法) |
|
||||
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [function-as-table-semantics.md](function-as-table-semantics.md) · [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| `[函数名](参数1 参数2)` 能否成立 | **技术上能,但代价在方括号**:它撞的是取元 `[键](集合)`,而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义 |
|
||||
| 更人读的调用能否成立 | **能,而且更干净**:`函数名(参数1 参数2)`(**不带方括号**)目前是**完全空闲的语法**,原型实测全量 **554 passed / 0 failed**,零回归 |
|
||||
|
||||
一句话:**想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。**
|
||||
|
||||
```markdown
|
||||
**税率 = 查询税率(档位=2)** # 具名,读起来像函数调用
|
||||
**合计 = 加(1 2)** # 位置,读起来像数学
|
||||
**名 = txt.str_trim(" x ")** # 库函数同样适用(原型已验证)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状:今天的调用写法盘点(全部实测)
|
||||
|
||||
| 写法 | 位置 | 实测 |
|
||||
|------|------|------|
|
||||
| `> 加 1 2` | 语句 | ✅ 位置参数 |
|
||||
| `> 加 a=1 b=2` | 语句 | ✅ 具名参数 |
|
||||
| `[加] 1 2` | 语句 | ✅ 方括号标记 + 位置参数(用于消歧/前置修饰) |
|
||||
| `**r = > [加] 1 2**` | 粗体赋值 | ✅ 返回 3(方括号调用**已支持空格参数**) |
|
||||
| `**r = 加 1 2**` | 粗体赋值 | ✅ **不带 `>` 也能调用,已可用**(打印 3) |
|
||||
| `**r = > 加 a=1**` | 粗体赋值 | ✅ 显式 `>` 形态 |
|
||||
| `**r = 加(1)**` | 粗体赋值 | ❌ `trailing input in expression: "(1)"` |
|
||||
| `**r = [加](1 2)**` | 粗体赋值 | ❌ `unknown function `[加](1`` |
|
||||
| `> [加](1 2)` | 语句 | ❌ `unknown function `[加](1`` |
|
||||
|
||||
也就是说:**「参数放在括号里」这件事今天完全不存在**。
|
||||
|
||||
---
|
||||
|
||||
## 2. `[函数名](参数)` 为什么碰壁
|
||||
|
||||
### 2.1 方括号 + 圆括号 = 取元,这是**已定的语义**
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1 写的是心智模型:
|
||||
|
||||
> **方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 从菜单里取出「拿铁」
|
||||
```
|
||||
|
||||
[call-arguments.md](call-arguments.md) §2 进一步锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` 不是「还没被用的语法」,而是**已经被取元占用**。
|
||||
|
||||
### 2.2 靠「名字是函数还是键」消歧,会真的打断现有代码
|
||||
|
||||
这是本轮新增的硬证据。我把全仓库扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件 | 851 |
|
||||
| `##` 级函数名 | 2367 |
|
||||
| `[键](…)` 出现次数 | 983 |
|
||||
| **键名与同文件函数名相同的冲突** | **5(去重后 2 个真实文件)** |
|
||||
|
||||
两个真实冲突(不是构造出来的):
|
||||
|
||||
```
|
||||
ext/data/db.mq.md:122 *[count](r)* # 函数名 ## count,同时 r 里有 count 列
|
||||
examples/code-as-docs/index.mq.md:79 价=[单价](行) # 函数名 ## 单价,同时 行 里有 单价 字段
|
||||
```
|
||||
|
||||
**这说明任何「函数名优先」的规则都会改变这两处的行为**:它们本意是取元,却会被解释成调用。
|
||||
反过来「数据优先」则永远无法用 `[f](1)` 调用。**两条路都走不通**——这不是实现难度问题,
|
||||
而是同一外形承载两种语义的固有代价。
|
||||
|
||||
### 2.3 但有一个「无歧义子集」确实存在
|
||||
|
||||
`[f](1 2)` 与 `[f](a=1)` 里的括号内容**不是合法表达式**(实测 `x=1` 报
|
||||
`unknown function`、`1 2` 报 `unknown function`),所以理论上可判为参数列表:
|
||||
|
||||
| 括号内容 | 能否是取元 | 可否判为调用 |
|
||||
|---------|-----------|-------------|
|
||||
| `(1 2)` 多 token | 否(非单一表达式) | ✅ 无歧义 |
|
||||
| `(a=1)` 具名 | 否 | ✅ 无歧义 |
|
||||
| `(1)` 单 token | **能** | ❌ 与 `[1](篮子)` 冲突 |
|
||||
| `(m)` 单变量 | **能** | ❌ 与 `[a](m)` 冲突 |
|
||||
|
||||
于是 `[f](1)`(最常见的单参调用)**永远无法**与取元区分。
|
||||
一个「多参数能用、单参数不能用」的语法,对使用者是最难记的一类。
|
||||
|
||||
---
|
||||
|
||||
## 3. `函数名(参数)`:空闲语法,原型验证通过
|
||||
|
||||
### 3.1 它是空闲的
|
||||
|
||||
实测 `**r = 加(1)**`(原型前)报 `trailing input in expression: "(1)"` ——
|
||||
说明 `名字(` 今天既不表示取元,也不表示任何别的含义。**没有既有语义要保护。**
|
||||
|
||||
### 3.2 原型做了什么
|
||||
|
||||
改了两处(**已回退,仅作验证**):
|
||||
|
||||
1. `src/parse/expr.rs`:新增 `try_paren_call` —— 紧随其后的 `(` 视为参数列表;
|
||||
在 `parse_call_tail` 里优先尝试。
|
||||
2. `src/parse/mod.rs`:粗体赋值与 `>` 两条路径的「像调用」判定加上
|
||||
`looks_like_paren_call`(让单 token 的 `加(1)` 也能进入调用分支)。
|
||||
|
||||
### 3.3 原型实测结果
|
||||
|
||||
| 用例 | 结果 |
|
||||
|------|------|
|
||||
| `加(1)` | ✅ 返回 2(单参) |
|
||||
| `加(1 2 )` | ✅ 返回 3(多参) |
|
||||
| `加("1" "2")` | ✅ 返回 `12`(字符串参数) |
|
||||
| `加(1 2)` | ❌ 末参数把 `)` 吞了 |
|
||||
| `加(a=1 b=2)` | ❌ 具名参数值把 `)` 吞了 |
|
||||
| `加(1, 2)` | ❌ 逗号不是分隔符 |
|
||||
| `加(加(1 2) 3)` | ❌ 嵌套未支持 |
|
||||
| `txt.str_trim(" x ")` | ✅ 返回 `x`(**库函数路径可用**) |
|
||||
| **全量测试** | ✅ **554 passed / 0 failed** |
|
||||
|
||||
**两条关键结论**:
|
||||
|
||||
1. **零回归**:新语法是纯增量,没有破坏任何既有用例(含 4 个 `[k](c)` 取元金样)。
|
||||
2. **真正的落点在参数分词器,不在语法**:`加(1 2)` 失败、`加(1 2 )` 成功,
|
||||
差别只是 `)` 前多一个空格——说明 `parse_call_args` 的分词把 `)` 当成了 token 的一部分。
|
||||
要修就得动 `parse_call_args` / `split_first_token` / `find_next_arg_boundary`,
|
||||
而这个分词器是**所有调用**(含今天在用的 `> f a=1`)共享的。
|
||||
|
||||
这解释了为什么这件事「看起来 10 行、实际一次核心改动」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 人读性对比
|
||||
|
||||
同一个意思,五种写法:
|
||||
|
||||
| 写法 | 读起来 | 现状 |
|
||||
|------|--------|------|
|
||||
| `> 加 1 2` | 「调用加,1 和 2」 | ✅ |
|
||||
| `**合计 = 加 1 2**` | 同上,无 `>` | ✅ |
|
||||
| `**合计 = 加(1 2)**` | 「加(1, 2)」,**像数学/函数调用** | 原型通过 |
|
||||
| `**合计 = 加(a=1 b=2)**` | 「加,a=1、b=2」,自解释 | 原型通过 |
|
||||
| `**[加](1 2)**` | 像链接,但与取元同形 | ❌ 不建议 |
|
||||
|
||||
我的判断:**`f(args)` 是这几种里最符合人读习惯的**,理由有三:
|
||||
|
||||
1. **与数学记号同构**:`税率(2)`、`sin(x)` 是跨语言、跨学科的通用写法,不需要学。
|
||||
2. **参数边界显式**:括号天然划定起止,解决了 `> f a b` 里「参数到哪结束」的模糊
|
||||
(这也是 D8「函数名含空格」难题的天然解药)。
|
||||
3. **不占用 Markdown 的链接语义**:渲染出来是普通文本 `f(1)`,
|
||||
不会像 `[f](1)` 那样在预览里变成超链接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 要走完这条路,需要做什么(评估工作量)
|
||||
|
||||
原型只验证了「方向可行」,要合入还缺这些:
|
||||
|
||||
| # | 事项 | 位置 | 风险 |
|
||||
|---|------|------|------|
|
||||
| 1 | `)` 作为参数终止符 | `parse_call_args` / `split_first_token` / `find_next_arg_boundary` | **中高**:所有调用共享 |
|
||||
| 2 | 逗号分隔 `f(1, 2)` | 同上 | 中:逗号在文本参数里合法(`"a,b"` 已加引号则无碍) |
|
||||
| 3 | 嵌套 `f(g(1) 2)` | `parse_call_args` 递归 | 中:需要括号深度跟踪 |
|
||||
| 4 | 方法 `obj.m(1)` / 库 `lib.fn(1)` | `try_paren_call` 已有基础(库路径实测通过) | 低 |
|
||||
| 5 | 位置/具名混用规则 | 复用 [call-arguments.md](call-arguments.md) §3 | 低 |
|
||||
| 6 | 空参 `f()` | 需定义语义(零参调用) | 低 |
|
||||
| 7 | EKC 指纹 | `collect_calls` 已读 `c.callee`,`CallExpr` 不变 → 自动兼容 | 无 |
|
||||
| 8 | `view` 渲染 | `[callee]` 已有 `bracket_marked` 标记,需决定是否回显括号形式 | 低 |
|
||||
| 9 | `marqdo check` | 需新增「`名字(` 但不是函数」的诊断 | 低 |
|
||||
|
||||
**注意第 7 条**:因为 `f(args)` 最终仍产出 `CallExpr { callee, args }`,
|
||||
EKC 指纹、契约、字节码 `Op::Call(fid, argc)` **全部自动兼容**——
|
||||
这正是它与「一等函数」方案([functions-as-values-evaluation.md](functions-as-values-evaluation.md) §5 路径 A)的本质区别:
|
||||
**它只是换了一种写法,没有改变调用模型。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
### 6.1 推荐路线
|
||||
|
||||
1. **不做 `[f](args)`**:与取元同形,且已证明按名消歧会打断 2 个真实文件;
|
||||
而「多参能用、单参不能用」的规则不可教。
|
||||
2. **做 `f(args)`**:空闲语法、零回归、人读性好、不动调用模型。
|
||||
3. 先落**具名**形态 `f(k=v)`(最无争议、自解释),再补位置 `f(1 2)`,最后考虑逗号与嵌套。
|
||||
|
||||
### 6.2 若你想保留方括号的「链接感」
|
||||
|
||||
有一个不碰取元的位置:**语句位置**。
|
||||
|
||||
```markdown
|
||||
> [加](1 2) # 今天报 unknown function;语句位置的 [k](c) 无实际用途
|
||||
```
|
||||
|
||||
`[k](c)` 作为**独立语句**今天只会算出值然后丢弃。全仓库扫描(851 文件):
|
||||
以 `[` 起行且形如 `[k](c)` 的独立行只有 **2 处**,且都是样式示例文件里的
|
||||
普通 Markdown 链接文本(`[海上花开](https://…)`),并非取元代码。
|
||||
所以在**语句调用**里允许 `[f](args)` 几乎无成本,表达式里则不允许。
|
||||
代价是「同一写法在两种位置含义不同」,可教性差;我倾向不做。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **是否采纳 `f(args)`**(不带方括号)作为新调用写法?
|
||||
2. 若采纳,**先做哪一档**:
|
||||
- A 只做具名 `f(k=v)`(最小、最稳)
|
||||
- B 具名 + 位置 `f(1 2)`(需改分词器,价值最大)
|
||||
- C 再加逗号与嵌套(一次做全)
|
||||
3. **`[f](args)` 是否彻底放弃**(我建议放弃,理由 §2.2);
|
||||
还是只允许在语句位置(§6.2)?
|
||||
4. 是否需要我按 B 档做一次完整实现(含分词器改造 + 金样例 + 变更文档),
|
||||
做完再走 554 回归?
|
||||
|
||||
原型代码已全部回退,工作区干净。等你定档我再动手。
|
||||
@@ -0,0 +1,208 @@
|
||||
# 设计:解析器诊断缺陷修复(D8 / D9)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 / D9 |
|
||||
| 影响面 | **核心解析**(`src/lex/mod.rs` 行分类 + `src/parse/expr.rs` 函数调用) |
|
||||
| 关联 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-vs-comment.md](code-vs-comment.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么这两条要先做调研
|
||||
|
||||
D8 与 D9 都落在**行分类**这一层:它决定一行是「叙述」还是「代码」。
|
||||
改错的代价是**整类文档解析结果变化**,而不是某个函数行为变化。
|
||||
所以本文先量化影响面、列出候选方案并逐条否决,再动手。
|
||||
|
||||
一句话结论:
|
||||
|
||||
- **D9** 的根因是分类层把「引号未闭合的粗体行」降级为叙述,
|
||||
导致解析层精心准备的 `unterminated " string` 报错**永远走不到**。
|
||||
修法是在分类层补一条「粗体起始但闭合搜索失败」的判定,让它进入解析层报错。
|
||||
语料实测 620 个文件 0 处受影响,风险可控。
|
||||
- **D8** 的根因是函数名解析按空格切词,与定义侧不对称。
|
||||
修法是在**定义期**拒绝含空格的函数名(fail fast),
|
||||
而不是在调用期做贪婪匹配(那会改变所有多词行的语义)。
|
||||
|
||||
---
|
||||
|
||||
## 1. D9 — 未闭合引号静默吞行
|
||||
|
||||
### 1.1 现状链路
|
||||
|
||||
```
|
||||
源码行 "**s = \"abc"
|
||||
↓ classify_source → classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
trimmed.starts_with("**") → matching_bold_close(trimmed)
|
||||
→ matching_bold_close_opts(require_eol=true)
|
||||
扫描时遇 '"' → in_str = true
|
||||
之后没有任何 '"' 关闭它 → 后续 '*' 全部被当作字符串内容跳过
|
||||
返回 None(找不到收尾 **)
|
||||
→ is_marqdo_star_line = false
|
||||
↓ classify_line 落到 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 该行成为**叙述**,parser 根本看不到它
|
||||
↓ parse_quoted_string 里 `bail!("unterminated {quote} string")` 不可达
|
||||
```
|
||||
|
||||
**结论**:这不是解析器的 bug,是**分类器的静默降级**。
|
||||
解析层已经把错误信息写好了,却没有人把这一行送到它面前。
|
||||
|
||||
### 1.2 影响(为什么算高严重度)
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失;变量未定义 → 在别处报 `undefined variable`,方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`marqdo check` 通过,**文档看起来完整却缺节** |
|
||||
| CI/门禁 | 门禁试跑通过 → 错误文档被沉淀入库 |
|
||||
|
||||
对「文档即程序」而言,这属于最危险的一类:**静默产出错误结果**。
|
||||
|
||||
### 1.3 候选方案与评判
|
||||
|
||||
#### 方案 A:分类层补判定(采纳)
|
||||
|
||||
在 `is_marqdo_star_line` 中,当 `trimmed.starts_with("**")` 且
|
||||
`matching_bold_close` 返回 `None` 时,再判断「这一行是否**像**粗体代码」:
|
||||
|
||||
- 行内含有 `=`(赋值)或 `>` 前导(调用)等强代码信号
|
||||
- 且引号计数为奇数
|
||||
|
||||
满足则**仍判为 Code**,让解析层去报 `unterminated " string`。
|
||||
|
||||
**优点**
|
||||
- 改动局限在分类层,不动解析语义
|
||||
- 复用解析层已有的、措辞准确的报错
|
||||
- 对「正常叙述中含 `**` 强调」零影响(那些行引号是配对的)
|
||||
|
||||
**风险**:叙述里恰好出现 `**…"…` 这种畸形组合会被判成代码 → 报错。
|
||||
但实测语料 0 例,且这种组合本身就是写法错误,报错是**期望行为**。
|
||||
|
||||
#### 方案 B:解析层预扫描(否决)
|
||||
|
||||
在 `parse_classified` 前加一遍全文引号配对检查。
|
||||
|
||||
**否决理由**:引号可以合法地出现在叙述、围栏代码块、行内代码里。
|
||||
全文扫描无法区分上下文,会制造大量假阳性(例如叙述里写「他说 "你好」)。
|
||||
逐行判断需要的是**分类**信息,而这正是方案 A 在做的事。
|
||||
|
||||
#### 方案 C:放宽 `matching_bold_close`,引号未闭合时也认 `**` 收尾(否决)
|
||||
|
||||
**否决理由**:会改变「粗体闭合」的语义。`**s = "a ** b"` 这类行
|
||||
会提前在中间 `**` 处闭合,把字符串拆断,产生更难理解的错误。
|
||||
这是把静默错误换成**更混乱的错误**,不是改进。
|
||||
|
||||
### 1.4 影响面实测
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
扫描时正确跳过了 `\` 转义(`\"` 不算引号开合)。
|
||||
结论:修复不会改变任何现有文件的解析结果。
|
||||
|
||||
### 1.5 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| `**s = "abc`(未闭合) | 报 `unterminated " string`,退出码非 0 |
|
||||
| `**s = "abc"`(闭合) | 正常运行 |
|
||||
| 跨行 `**s = "a` + `b"**` | 报错(不跨行拼接,符合现状) |
|
||||
| 叙述 `他说 "你好"` | 仍是叙述,不受影响 |
|
||||
| 全量 `cargo test` | 233 全绿 |
|
||||
| 全仓库重跑 `marqdo check` | 无新增错误 |
|
||||
|
||||
---
|
||||
|
||||
## 2. D8 — 函数名含空格:定义成功、调用必崩
|
||||
|
||||
> **⚠️ 本节方案已作废。** 原主张「定义期拒绝空格」违背了「完全兼容 Markdown」:
|
||||
> `## 用户 登录流程` 是合法标题,不该为了可调用而改写。
|
||||
> 现行评估见 [spaced-function-names-d8.md](spaced-function-names-d8.md)(Proposed · 待审阅)。
|
||||
> 本文其余部分(D9)仍然有效。
|
||||
|
||||
### 2.1 现状链路
|
||||
|
||||
```
|
||||
定义侧:## 加一 号 → 标题整体作为函数名 "加一 号"(允许空格)
|
||||
|
||||
调用侧:> 加一 号 n=1
|
||||
↓ 按空白切词
|
||||
token[0] = "加一" → 当作函数名
|
||||
token[1..] = ["号", "n=1"]
|
||||
↓ "号" 无 `=` → 按位置参数/变量插值处理
|
||||
↓ 变量 "号" 不存在 → undefined variable `号`
|
||||
```
|
||||
|
||||
两侧不对称:定义时把整串当名字,调用时只取第一个词。
|
||||
|
||||
### 2.2 候选方案与评判
|
||||
|
||||
#### 方案 A:定义期拒绝空格(**已否决**)
|
||||
|
||||
解析 `## 函数名` 时,若函数名含空白则报错:
|
||||
|
||||
```
|
||||
error: 文件:行: function name may not contain spaces: `加一 号`
|
||||
(write `加一_号`, or quote the call as `> "加一 号"`)
|
||||
```
|
||||
|
||||
**优点**
|
||||
- fail fast:错误在定义处暴露,与调用处报 `undefined variable` 相比指向明确
|
||||
- 不改变任何合法程序的语义
|
||||
- 与「标识符不含空格」的通行约定一致
|
||||
|
||||
**风险**:可能已有文件用了空格函数名且**只定义不调用**(今天能跑)。
|
||||
需先扫描语料确认。
|
||||
|
||||
#### 方案 B:调用侧贪婪匹配已知函数名(否决)
|
||||
|
||||
按「已知函数名的最长前缀」匹配。
|
||||
|
||||
**否决理由**:
|
||||
1. 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
|
||||
2. `> print text=hello world` 里 `hello world` 会被尝试拼成函数名,语义歧义
|
||||
3. 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
|
||||
|
||||
#### 方案 C:只警告不报错(否决)
|
||||
|
||||
**否决理由**:D8 的危害正是「check 通过、运行崩」。继续给警告等于维持现状。
|
||||
|
||||
### 2.3 影响面实测
|
||||
|
||||
统计仓库内**定义侧含空格**的 `##`/`###` 标题(仅可调用的层级):
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 含空格的二级及以下标题 | 4 |
|
||||
| 其中位于源码(非运行时目录)的 | **0** |
|
||||
| 分布 | 全部在 `.marqdo/agent/contexts/*.mq.md` 运行时生成物,且是叙述性标题("Existing Capabilities"),从未被调用 |
|
||||
|
||||
结论:源码中不存在含空格的函数名,加定义期校验不会破坏任何现有模块。
|
||||
运行时生成的 context 文件不受影响——它们不被 import。
|
||||
|
||||
### 2.4 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| `## 加一 号` | 报 `function name may not contain spaces` |
|
||||
| `## 加一_号` + 调用 | 正常 |
|
||||
| `## 断言干净`(中文连写) | 正常 |
|
||||
| 方法 `### 名字 带空格` | 同样拒绝 |
|
||||
| 全量测试 | 233 全绿 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 实施顺序
|
||||
|
||||
1. D9(分类层,影响面已量化)→ 测试 → 文档
|
||||
2. D8(定义期校验)→ 测试 → 文档
|
||||
3. 两条都做完后跑全仓库回归(`cargo test` + 抽样 `marqdo run`)
|
||||
|
||||
每一步独立提交,便于回滚。
|
||||
@@ -0,0 +1,216 @@
|
||||
# 方案评估:函数名含空格的调用(D8)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待审阅**(未实施任何代码改动) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 |
|
||||
| 前置 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md)(该文方案 A「禁止空格」**已被否决**,见 §0) |
|
||||
| 影响面 | 核心解析:`src/parse/expr.rs` 调用切词 / `src/lex` 行分类 / 名称解析 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么原方案被否决
|
||||
|
||||
原方案 A 主张「定义期拒绝含空格的函数名」。这是**错的**,理由是我此前忽略的一句话:
|
||||
|
||||
> Marqdo 的立身之本就是**完全兼容 Markdown**。
|
||||
|
||||
`## 用户 登录` 是一个**完全合法的 Markdown 二级标题**。真实文档里这类标题极多:
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程
|
||||
## 第三阶段 数据校验
|
||||
## Appendix A Results
|
||||
```
|
||||
|
||||
如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞——
|
||||
这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是**他自己想写的标题**。
|
||||
|
||||
**结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 事实基础(全部实测,1.5.2)
|
||||
|
||||
先固定真实行为,避免方案讨论建立在猜测上。
|
||||
|
||||
### 1.1 定义侧
|
||||
|
||||
| 输入 | 结果 |
|
||||
|------|------|
|
||||
| `## 加一 号` | ✅ 定义成功,函数名**原样**为 `加一 号`(`parse_object_decl` 走 `Ok((raw.to_string(), None))`) |
|
||||
| `## 用户 登录流程` | ✅ 同上 |
|
||||
|
||||
**定义侧完全支持空格**,不需要任何改动。
|
||||
|
||||
### 1.2 调用侧
|
||||
|
||||
| 输入 | 结果 | 原因 |
|
||||
|------|------|------|
|
||||
| `> 加一 号 n=1` | ❌ `undefined variable 号` | `parse_call_tail` 用 `split_whitespace().next()` 只取首词 |
|
||||
| `> [加一_号] n=1` | ✅ 正常(返回 2) | 方括号标记调用**已存在**且工作 |
|
||||
| `> [加一 号] n=1` | ❌ `unknown function [加一` | `is_bracket_callee_inner` 第 1248 行**显式拒绝含空白** |
|
||||
| `` `加一 号` `` 作为表达式 | ❌ `undefined variable 加一 号` | 反引号名走变量解析,找不到函数 |
|
||||
|
||||
### 1.3 关键发现
|
||||
|
||||
> **方括号标记调用(`[callee]`)已经存在且实现完整**,
|
||||
> 挡住带空格名字的是 `is_bracket_callee_inner` 里的**两处**校验,
|
||||
> 而不是一处(首轮评估低估了)。
|
||||
|
||||
这是本次评估最重要的发现:**不需要发明新语法**,只需要让既有机制接受空格。
|
||||
|
||||
### 1.4 可行性实测(已做,未保留改动)
|
||||
|
||||
为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验:
|
||||
临时放开两处校验 → 编译 → 跑用例 → **立即回退**(`src/parse/expr.rs` 已恢复原样)。
|
||||
|
||||
| 关卡 | 位置 | 原逻辑 | 放开后 |
|
||||
|------|------|--------|--------|
|
||||
| 1 | `is_bracket_callee_inner` | `t.chars().any(is_whitespace)` → 拒绝 | 删除该检查 |
|
||||
| 2 | 同函数末尾 bare-name 白名单 | `is_alphanumeric() \| '_' \| '.' \| !is_ascii()` | 追加 `\| c == ' '` |
|
||||
|
||||
**实验结果**
|
||||
|
||||
| 用例 | 结果 |
|
||||
|------|------|
|
||||
| `## 加一 号` + `> [加一 号] n=1` | ✅ **返回 `2`**(运行时函数表正确命中含空格名) |
|
||||
| `## 加一_号` + `> [加一_号] n=1`(对照) | ✅ 仍返回 `2`,既有行为不变 |
|
||||
| 全量 `cargo test --lib` | ✅ **237 passed, 0 failed** |
|
||||
|
||||
**结论**:方案 1 技术上完全成立,且**不破坏既有测试**。
|
||||
(237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)
|
||||
|
||||
> 注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例,
|
||||
> 特别是 V3–V7 的歧义排除,再决定是否合入。
|
||||
|
||||
---
|
||||
|
||||
## 2. 候选方案
|
||||
|
||||
### 方案 1 — 放开方括号内的空格(推荐)
|
||||
|
||||
**做法**:把 `is_bracket_callee_inner` 的「含空白即拒绝」改为「允许空白,
|
||||
但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。
|
||||
|
||||
**用法**:
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程
|
||||
+ `账号`
|
||||
|
||||
*"已登录 " + `账号`*
|
||||
|
||||
# main
|
||||
|
||||
> [用户 登录流程] 账号=alice
|
||||
*""
|
||||
```
|
||||
|
||||
**优点**
|
||||
- 不新增语法:`[…]` 标记调用是**既有**的正式特性,只是被一行校验挡住
|
||||
- 向后兼容:所有现有调用(含 `[加一_号]`)行为不变
|
||||
- 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
|
||||
- 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
|
||||
- 可推广:方法调用 `[obj.方法 名]`、库函数 `[lib.函数 名]` 一并受益
|
||||
|
||||
**风险与缓解**
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| `[…]` 也被用于链接索引 `[key](map)` | 已有守卫:`]` 后紧跟 `(` 则不是 callee(第 981 行),保持 |
|
||||
| JSON 数组 `[1, 2]` 被误认为 callee | 既有守卫:含 `,` `:` `{` `}` `[` `]` 一律拒绝,保持 |
|
||||
| `print text=(礼貌 [问候] x)` 类内嵌方括号 | 既有守卫:前缀含 `=` `(` `"` `'` `:` 则不当 callee,保持 |
|
||||
| 运行时按下标查函数表,`加一 号` 能否命中 | **需实测验证**(见 §4 验证计划 V1) |
|
||||
|
||||
**工作量**:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。**最小可验证改动**。
|
||||
|
||||
---
|
||||
|
||||
### 方案 2 — 调用侧最长前缀匹配(否决)
|
||||
|
||||
**做法**:拿到 `加一 号 n=1` 后,尝试用「已知函数名」做最长前缀匹配。
|
||||
|
||||
**否决理由**
|
||||
1. **上下文不可达**:调用发生在表达式解析阶段,此时只有本模块符号表;
|
||||
跨模块 `lib.函数 名` 需要 import 解析结果,不可在词法期判定。
|
||||
2. **歧义爆炸**:`> print text=hello world` 中,若存在名为 `print text` 的函数,
|
||||
本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。
|
||||
3. 属于**核心语义变更**,收益(省掉方括号)远小于风险。
|
||||
|
||||
---
|
||||
|
||||
### 方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)
|
||||
|
||||
**做法**:明确官方立场——带空格的名字**不自称可调用**,需要调用就请写
|
||||
一个无空格的 `## 别名` 转发,或直接把标题写成无空格形式。
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程 ← 给人读的标题,不被调用
|
||||
|
||||
## 用户登录流程 ← 真正被调用的函数
|
||||
+ `账号`
|
||||
...
|
||||
```
|
||||
|
||||
**优点**:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。
|
||||
|
||||
**缺点**:与「完全兼容 Markdown」仍有张力——作者得写两遍。
|
||||
|
||||
**适用**:如果审计认为方括号放开会牵连过多,可作为**保守退路**。
|
||||
|
||||
---
|
||||
|
||||
### 方案 4 — 反引号名解析到函数(否决)
|
||||
|
||||
允许 `` `加一 号` `` 在**调用位**解析成函数引用(`> `加一 号` n=1`)。
|
||||
|
||||
**否决理由**:反引号在 Marqdo 中统一表示**变量**引用。让它有时指变量、有时指函数,
|
||||
会让「反引号=变量」这条最基础的约定失效,错误更难排查。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案对比
|
||||
|
||||
| 维度 | 方案 1 放开方括号 | 方案 2 前缀匹配 | 方案 3 文档立场 | 方案 4 反引号 |
|
||||
|------|------------------|----------------|----------------|--------------|
|
||||
| 兼容 Markdown | ✅ 完全 | ✅ | ⚠️ 需写两遍 | ✅ |
|
||||
| 新增语法 | 无(复用既有) | 无 | 无 | 有歧义 |
|
||||
| 改动范围 | 1 处校验 + 测试 | 核心语义 | 0 代码 | 核心语义 |
|
||||
| 回归风险 | 低 | **高** | 无 | **高** |
|
||||
| 可验证性 | 高(可枚举用例) | 低 | — | 低 |
|
||||
| 推荐 | **首选** | 否决 | 备选 | 否决 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 若采纳方案 1:验证计划
|
||||
|
||||
必须全部通过才可合入。
|
||||
|
||||
| 编号 | 用例 | 期望 |
|
||||
|------|------|------|
|
||||
| V1 ✅| `## 加一 号` + `> [加一 号] n=1` | 返回 `2`(**已实测通过**,见 §1.4) |
|
||||
| V2 | `## 加一_号` + `> [加一_号] n=1` | 返回 `2`(**既有行为不变**) |
|
||||
| V3 | 链接索引 `[k](m)` | 仍解析为索引,不被当 callee |
|
||||
| V4 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不被当 callee |
|
||||
| V5 | 方括号内 JSON `[1, 2]` / `["a"]` | 仍被拒绝为 callee |
|
||||
| V6 | 跨模块 `[lib.函数 名]` | 正确解析到库函数 |
|
||||
| V7 | 方法 `[obj.方法 名]` | 正确解析 receiver |
|
||||
| V8 | 全量 `cargo test` | 233 全绿(+ 新增用例) |
|
||||
| V9 | 全仓库 `.mq.md` 回归 | 无新增解析错误 |
|
||||
|
||||
**V1 是决定性的**:如果运行时函数表以 `加一 号` 为键能正常查到,
|
||||
方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。
|
||||
|
||||
---
|
||||
|
||||
## 5. 待你决策的问题
|
||||
|
||||
1. **选哪个方案?** 我倾向 **方案 1**(放开方括号空格):不新增语法、
|
||||
完全兼容 Markdown、改动可控、可验证性强。
|
||||
2. **若选方案 1,调用书写是否需要中文别名?** 例如同时接受 `【加一 号】`(全角方括号),
|
||||
与全角冒号问题(D2)一致。
|
||||
3. **是否要保留方案 3 的文档立场作为补充说明?** 即「标题可自由书写;
|
||||
需要调用时用 `[完整名]` 引用」——这句话本身就很适合写进教程。
|
||||
|
||||
在你确认前,我不会改动 D8 相关代码。
|
||||
@@ -0,0 +1,223 @@
|
||||
# 修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 修订**(取代 [warning-fatigue-control.md](warning-fatigue-control.md) §2 的 M5a) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 触发 | 用户:不是所有开发都用 git,依赖 git 是否是好设计 |
|
||||
| 结论 | **不是好设计**。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖 |
|
||||
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 直接回答:不该依赖 git
|
||||
|
||||
三条理由,一条比一条硬:
|
||||
|
||||
### 0.1 环境覆盖不到
|
||||
|
||||
| 环境 | 能调 git 吗 | 依据 |
|
||||
|------|------------|------|
|
||||
| 浏览器 WASM | ❌ | `marqdo-wasm`(wasm32-unknown-unknown),无进程能力 |
|
||||
| **沙箱内执行** | ❌ | `src/host/sandbox_fs.rs`:`allow_exec: false` |
|
||||
| 单文件分发 / zip 工件 | ❌ | 没有 `.git` |
|
||||
| CI 容器(浅克隆/无 VCS) | ⚠️ 常常没有 | 取决于流水线 |
|
||||
| 非 git 用户(hg / svn / fossil / 无) | ❌ 或需另写适配 | — |
|
||||
|
||||
### 0.2 语言不该绑定某个 VCS
|
||||
|
||||
Marqdo 是**语言与运行时**。把"断言是否过期"的判定建立在"某个工具的目录是否存在"上,
|
||||
等于把语言的语义正确性外包给环境。今天 git 是主流,明天不是;语言不能跟着换。
|
||||
|
||||
### 0.3 最要命的:最重要的消费者恰在不能调 git 的地方
|
||||
|
||||
标签过期检测的**最高价值场景**是 agent 修复回路——
|
||||
模型改了代码,Marqdo 提醒它"你改的这处描述可能不成立了"。
|
||||
|
||||
而这个回路:
|
||||
- 常在沙箱里跑(`exec=false`,**调不了 git**)
|
||||
- 编辑目标是内存中的文本(`repair_apply` 的 `source`),不一定落在 git 工作区
|
||||
|
||||
**如果核心机制依赖 git,那它恰好在最需要它的地方失灵。** 这是设计错误的铁证。
|
||||
|
||||
---
|
||||
|
||||
## 1. 但 M5 的原则要保住
|
||||
|
||||
上一份文档的 M5 有两个部分,必须分开看:
|
||||
|
||||
| 部分 | 判定 |
|
||||
|------|------|
|
||||
| **原则**:stale 是"变更报告",不是"扫描报告"(没有新信息就不说话) | ✅ **保留**,这是防疲劳的根 |
|
||||
| **实现**:用 `git diff` 提供"前一状态" | ❌ **降级为可选 provider** |
|
||||
|
||||
也就是说:
|
||||
|
||||
> **判定逻辑只有一份:`stale ⟺ fingerprint(()) 变了 ∧ label 没变`。
|
||||
> 变的只是「前一个 `()` 从哪来」。**
|
||||
|
||||
这一步抽象之后,git 只是**四种来源之一**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 四层能力(provider 分层)
|
||||
|
||||
### T0 — 引用一致性(零依赖,永远可用)
|
||||
|
||||
纯文档分析:标签里的 `` `实体` `` 必须可解析、且出现在 `()` 中。
|
||||
|
||||
- 需要:只读当前文件(甚至只需文本)
|
||||
- 能力:查**引用腐烂**(改名、删除、错引)
|
||||
- 查不了:语义腐烂(`*` 改 `/`)
|
||||
|
||||
### T1 — 会话内前后对照(零依赖,最高性价比)
|
||||
|
||||
**任何"编辑前 + 编辑后"都在手的场合**都能算 stale:
|
||||
|
||||
| 场合 | 前一状态从哪来 |
|
||||
|------|---------------|
|
||||
| `MLSP repair_apply` | 调用方传入的 `source` + `edits` → 前/后两版都在内存里 |
|
||||
| `view`(保存后检查) | 保存前的模块 AST |
|
||||
| 编辑器保存钩子 | 编辑器持有的旧缓冲 |
|
||||
| agent 的 diff | 它自己的编辑集 |
|
||||
|
||||
**关键**:只看「本次会话改了哪些标签的 `()` 且没改 `[]`」。
|
||||
天然变更驱动、天然零台账、天然带 before/after——**而且不需要 git**。
|
||||
|
||||
### T2 — 外部历史源(可选,自动探测)
|
||||
|
||||
`git` / `hg` / `svn` / 任意"能取到上一版文件内容"的适配器。
|
||||
|
||||
- 检测:工作区存在 `.git` / `.hg` 且二进制可用
|
||||
- 用途:**跨会话**漂移(昨天改了代码,今天才检查)
|
||||
- 缺失时:**静默关闭**,不报错、不提示、不产生噪音
|
||||
|
||||
### T3 — 台账(可选,无 VCS 时的持久化)
|
||||
|
||||
`.marqdo/labels.json`:`{标签键 → {code_fingerprint, code_quote, confirmed_at}}`
|
||||
|
||||
- 用途:没有 VCS 的环境(沙箱长期任务、编辑器插件)+ 严格模式的"确认"状态
|
||||
- 语义:**可丢弃缓存**(删了重建,最多一次全量确认)
|
||||
- 已知代价:合并冲突、需要 bootstrap(因此作为 opt-in,不做默认)
|
||||
|
||||
---
|
||||
|
||||
## 3. 环境能力矩阵
|
||||
|
||||
| 环境 | T0 引用 | T1 会话内 | T2 历史源 | T3 台账 |
|
||||
|------|--------|----------|----------|--------|
|
||||
| CLI + git 仓库 | ✅ | ✅ | ✅ | ✅ |
|
||||
| CLI + hg/svn(有适配) | ✅ | ✅ | ✅ | ✅ |
|
||||
| CLI 无 VCS | ✅ | ✅ | ❌ | ✅ |
|
||||
| **agent 沙箱(exec=false)** | ✅ | ✅ | ❌ | ⚠️ CoW 内可写但不持久 |
|
||||
| **浏览器 WASM** | ✅ | ✅ | ❌ | ❌ 无持久 fs |
|
||||
| 单文件 / zip 工件 | ✅ | ✅ | ❌ | ❌ |
|
||||
| 数据库/对象存储里的 `.mq.md` | ✅ | ✅ | ❌ | 由宿主提供 |
|
||||
|
||||
**读法**:矩阵里**没有一行全 ❌**。T0+T1 在所有环境都成立——
|
||||
这两层就足以支撑"agent 改动即时提醒"这个最高价值场景。
|
||||
|
||||
---
|
||||
|
||||
## 4. 各层的能力边界(必须诚实)
|
||||
|
||||
| 层 | 能查 | 查不了 |
|
||||
|----|------|--------|
|
||||
| T0 | 引用了不存在的实体;引用的实体不在语句里 | 语义腐烂(乘改除) |
|
||||
| T1 | **本次会话内**的 `()` 变化 | 跨天/跨机器的漂移 |
|
||||
| T2 | 跨会话、跨机器的漂移(若 VCS 有历史) | 未提交历史之外的变化;跨仓库移动 |
|
||||
| T3 | 持久化的漂移(若台账被维护) | 台账未覆盖的标签;合并后需重算 |
|
||||
|
||||
**组合起来的语义**:
|
||||
- 有 T2 → 严格(能查历史)
|
||||
- 只有 T0+T1 → **会话级严格**(够 agent 用)
|
||||
- 什么都没有(WASM 首次打开) → 只查引用(T0),且**明确告知能力级别**
|
||||
|
||||
---
|
||||
|
||||
## 5. 最关键的一条:agent 回路不需要任何 VCS
|
||||
|
||||
`MLSP repair_apply` 的参数里**已经同时有前后两版**:
|
||||
|
||||
```rust
|
||||
// src/mlsp.rs:repair_apply 收到 source + ranges + edits
|
||||
let source = source_text(params)?;
|
||||
// → 应用 edits 得到 after
|
||||
```
|
||||
|
||||
所以只要给协议补一个字段 `base_code`(或让 `repair_apply` 自己在内部保留 before),
|
||||
Marqdo 就能在**同一次调用内**算出:
|
||||
|
||||
> 哪些标签的 `()` 指纹变了、而 `[]` 没变 → 输出 stale 提示。
|
||||
|
||||
**零外部状态、零依赖、零 git。** 而这正是"模型改了代码别忘了改描述"的场景。
|
||||
|
||||
**具体协议建议**(只需一个可选字段):
|
||||
|
||||
```json
|
||||
{ "method": "repair_apply",
|
||||
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
|
||||
"check_labels": true } }
|
||||
```
|
||||
|
||||
返回里附:
|
||||
|
||||
```json
|
||||
{ "labels": [{ "stale": 1, "items": [{ "text": "按 `税率` 计算总价",
|
||||
"code_past": "…* 金额", "code_now": "…/ 金额", "span": {...} }] }] }
|
||||
```
|
||||
|
||||
这样 agent 每轮只看到**自己刚弄脏的那几条**,且带前后对照。
|
||||
|
||||
---
|
||||
|
||||
## 6. provider 契约(五条硬规则)
|
||||
|
||||
1. **核心不依赖**:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。
|
||||
2. **缺失即降级**:provider 不可用 → 静默关闭该层能力,**绝不报错、绝不提示**。
|
||||
3. **能力必须自述**:`labels status` 必须显示"当前启用 T0/T1/T2/T3 中的哪些"。
|
||||
——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。
|
||||
4. **判定单一定义**:`stale` 的定义只有一处实现;provider 只提供 `prev`,不参与判定。
|
||||
——否则不同环境会给出不同结论,语言就没有统一语义了。
|
||||
5. **不写进文档**:provider 的状态、指纹、抑制**一律不进 `.mq.md`**。
|
||||
文档里只允许有人的语言与代码。
|
||||
|
||||
> 第 3 条是我这次最想强调的:**宁可少报,也不能假装"检查过了"。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 被否决的方案
|
||||
|
||||
| 方案 | 否决理由 |
|
||||
|------|---------|
|
||||
| **强制 git 作为核心** | 环境覆盖不到(§0.1);语言绑定 VCS(§0.2);最关键场景失灵(§0.3) |
|
||||
| 文档内嵌指纹 | 污染文档;作者一改就失效;与"文档即散文"冲突 |
|
||||
| 零宽字符隐藏指纹 | 不可见 = 不可审计;复制粘贴即损坏;工具链噩梦 |
|
||||
| mtime 启发式 | 不可靠(checkout、touch、云同步都会变) |
|
||||
| `# noqa` 抑制 | 已否(污染 + 不可审计 + 会永久化) |
|
||||
| 只做全量扫描 + 静音清单 | 静音清单就是台账,且首次即爆炸 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 对上一份文档的修订
|
||||
|
||||
| 原条目 | 修订后 |
|
||||
|--------|--------|
|
||||
| M5a「git 结构化 diff」为核心机制 | 降级为 **T2 的一个适配器**;核心改为 **T0 + T1** |
|
||||
| 严格模式依赖台账 | 严格模式 = 任意 T2 **或** T3 可用即可;无 provider 时按 T0/T1 运行 |
|
||||
| 验收指标「无变更时输出 = 0」 | 保留,且补一条:**provider 缺失时也必须为 0,并在 `labels status` 里说明** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **接受「T0+T1 为核心,T2/T3 可选」这个分层吗?**
|
||||
2. **T1 是否足够**作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景)
|
||||
3. **能力自述**要不要做成 `labels status` 的固定输出
|
||||
(含"本次无法检测历史漂移"这类明确提示)?
|
||||
4. **T2 的适配范围**:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现?
|
||||
5. **T3 台账**是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实)
|
||||
|
||||
> 我的建议:**先只做 T0 + T1**,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。
|
||||
> 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立,
|
||||
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
# T1 会话内陈旧检测:为什么模型不会收到重复警告
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 机制说明**(M6 落地) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 回答 | 「在不改变的情况下,能让模型免于多次警告疲劳吗?」——**能,而且几乎不用改什么** |
|
||||
| 前置 | [staleness-providers.md](staleness-providers.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **警告的作用域 = 模型自己刚改的那几行;投递次数 = 一次;附着在造成它的那次编辑的返回里。**
|
||||
|
||||
不是"我们让它少报",而是**同一件事在结构上不可能被报第二次**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制为什么成立:前后两版本来就在手里
|
||||
|
||||
看现有 `repair_apply`(`src/mlsp.rs:233`)的实现:
|
||||
|
||||
```rust
|
||||
let source = source_text(params)?; // ← 改动前(before)
|
||||
...
|
||||
match crate::repair::apply_edits(&source, &ranges, &edits) {
|
||||
Ok(new_source) => { // ← 改动后(after)
|
||||
Ok(json!({"source": new_source, "edits_applied": edits.len()}))
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**`source` 和 `new_source` 在同一个函数作用域里同时存在。**
|
||||
所以"比较改动前后"不需要任何外部东西:
|
||||
|
||||
| 需要的东西 | 从哪来 |
|
||||
|-----------|--------|
|
||||
| 改动前的 AST | `parse(source)` |
|
||||
| 改动后的 AST | `parse(new_source)` |
|
||||
| 标签配对 | 两份 AST 里的标签节点(按标签文本 + 序号) |
|
||||
| `()` 是否变了 | 比较两边的 AST 指纹 |
|
||||
| `[]` 是否变了 | 比较标签文本 |
|
||||
|
||||
**零 git、零台账、零缓存文件、零环境依赖。** 这就是"agent 回路根本不需要 VCS"的含义。
|
||||
|
||||
### 1.1 指纹怎么做(T1 只需要「进程内一致」)
|
||||
|
||||
这一点让实现变得很轻:
|
||||
|
||||
- `Expr` 目前 `#[derive(Debug, Clone)]`,**没有 `PartialEq`**(`src/ast.rs:184`)。
|
||||
- 但 T1 只在**同一个进程内**比较前后两版,**不需要跨版本、跨机器稳定的指纹格式**。
|
||||
于是最简做法是:把 `()` 的比较键取为 `format!("{:?}", expr)`——同一次运行内确定即可。
|
||||
- 若想更严谨,可给 `Expr` 及其成员补 `#[derive(PartialEq)]`(纯机械改动;`Literal` 含 `f64`,
|
||||
只可 `PartialEq` 不可 `Eq`),然后直接结构比较,不产生字符串。
|
||||
- 反过来,**T2/T3 才需要稳定指纹**(跨会话要能对上),那时才动用
|
||||
`knowledge/fingerprint.rs` 那套。
|
||||
|
||||
> 也就是说:T1 的实现成本 ≈ "解析两次 + 比较两棵子树",没有版本化指纹的负担。
|
||||
|
||||
---
|
||||
|
||||
## 2. 一次修复轮次的完整时序
|
||||
|
||||
```
|
||||
第 N 轮
|
||||
┌─ validate → 语法/契约诊断(不含标签扫描)
|
||||
├─ repair_targets → 靶点 + 允许范围
|
||||
├─ 模型产出 edits (例如:把 `* 金额` 改成 `/ 金额`)
|
||||
└─ repair_apply(source, ranges, edits)
|
||||
│
|
||||
├─ before = source
|
||||
├─ after = apply_edits(...)
|
||||
├─ 解析两版 → 比较每个标签的 () 指纹
|
||||
└─ 返回:
|
||||
{ "source": after,
|
||||
"edits_applied": 1,
|
||||
"labels": { "stale": [ {标签, code_past, code_now, span} ] } }
|
||||
```
|
||||
|
||||
模型在自己这次编辑的**响应里**看到:
|
||||
|
||||
```json
|
||||
{
|
||||
"labels": {
|
||||
"stale": [{
|
||||
"text": "按 `税率` 计算总价",
|
||||
"code_past": "at(税率表, 档位) * 金额",
|
||||
"code_now": "at(税率表, 档位) / 金额",
|
||||
"span": {"line": 42, "col": 12}
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
它只需要回答一个问题:**"你刚才动了这段实现,描述还成立吗?"**
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么「重复」在结构上消失了
|
||||
|
||||
三个性质,缺一不可:
|
||||
|
||||
| 性质 | 内容 | 效果 |
|
||||
|------|------|------|
|
||||
| **作用域 = 自己的 diff** | 只看这次 `apply` 触及的标签 | 全仓库/全文件的旧债永远不进模型的上下文 |
|
||||
| **投递 = 一次** | 只在造成它的那次响应里出现 | 不会在后续 `validate` 里重复出现 |
|
||||
| **自包含** | 下一轮的 diff 是新的 | 模型不改那处 → 那条标签不再出现 |
|
||||
|
||||
**注意第三条的含义(也是代价)**:模型若忽略了提示,它**不会**在下一轮被再提醒——
|
||||
因为它没碰那处。这是刻意的取舍:**宁可漏一次,也不反复骚扰**。
|
||||
|
||||
> 对比扫描式:一个 20 处标签的文件,5 轮修复里模型可能累计看到上百条重复提示;
|
||||
> T1 下最多看到 **自己这几行涉及的 0–2 条**,且每条只出现一次。
|
||||
|
||||
---
|
||||
|
||||
## 4. 关键重构:它在性质上**不是 warning,而是编辑期诊断**
|
||||
|
||||
这是我认为最重要的一点。
|
||||
|
||||
| | Lint 警告 | 编译器错误 | **T1 stale** |
|
||||
|---|---|---|---|
|
||||
| 出现时机 | 常在后台/每次保存 | 你按下构建那一刻 | **你改完那一刻** |
|
||||
| 数量 | 与存量成正比 | 与你这次写的错成正比 | **与你这次改的成正比** |
|
||||
| 是否重复 | 反复出现 | 不重复(改了就消失) | **不重复** |
|
||||
| 用户态度 | 容易忽略 | 必须处理 | **天然要处理** |
|
||||
|
||||
没有人抱怨"编译器又报语法错了"——因为它是**一次性的、可归因的、改动驱动的**。
|
||||
T1 的 stale 正好落在这个类别里。
|
||||
|
||||
**所以疲劳问题不是靠压制解决的,是靠把 stale 从"lint 类别"搬到"编译错误类别"解决的。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 「不改变」到什么程度
|
||||
|
||||
你的问法是"在不改变的情况下"。精确回答:
|
||||
|
||||
| 项 | 要不要变 |
|
||||
|----|---------|
|
||||
| `.mq.md` 文档内容 | **不变**(不嵌指纹、不加 `noqa`、不加标记) |
|
||||
| 写代码 / 读代码的工作流 | **不变**(还是 validate → repair_targets → 编辑 → repair_apply) |
|
||||
| 项目状态文件 | **不新增**(无台账、无基线、无 `.marqdo/labels.json`) |
|
||||
| 对 VCS 的依赖 | **无**(沙箱 `exec=false`、WASM 无进程,照样可用) |
|
||||
| 环境要求 | **无**(纯内存计算) |
|
||||
| **MLSP 协议** | **加一个可选参数 + 一个响应字段**(这是唯一的改动) |
|
||||
|
||||
唯一的协议改动小到可以忽略:
|
||||
|
||||
```json
|
||||
{ "method": "repair_apply",
|
||||
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
|
||||
"check_labels": true } }
|
||||
```
|
||||
|
||||
- `check_labels` 缺省 = 不做(**默认零开销、零噪音**)
|
||||
- 客户端(agent 框架)在修复回路里打开它
|
||||
- 返回里多一个 `labels` 字段;无 stale 时为空数组
|
||||
|
||||
---
|
||||
|
||||
## 6. 配对规则(哪些算"同一条标签")
|
||||
|
||||
比较两份 AST 时:
|
||||
|
||||
| 情形 | 判定 |
|
||||
|------|------|
|
||||
| 标签文本未变、`()` 指纹变 | ✅ **stale**(核心场景) |
|
||||
| 标签文本变了 | 不报——作者在更新描述,这就是"确认" |
|
||||
| `()` 与标签都没变 | 不报 |
|
||||
| 新插入的标签 | 不报——新断言无历史 |
|
||||
| 被删掉的标签 | 不报——没有东西可比 |
|
||||
| 标签移动位置(同文件) | 不报——按标签文本配,不按行号 |
|
||||
|
||||
**"按标签文本配对"很关键**:它让"把这段代码挪个位置"不会误报,
|
||||
而"把这段代码的计算改了"一定报警。
|
||||
|
||||
---
|
||||
|
||||
## 7. 模型会不会漏掉?三种兜底
|
||||
|
||||
T1 的代价是"不重复",所以要设计"漏了怎么办":
|
||||
|
||||
| 兜底 | 做法 | 代价 |
|
||||
|------|------|------|
|
||||
| **循环预算** | `labels.stale` 非空时,客户端允许下一轮(现有 `max_attempts: 2` 直接可用) | 无 |
|
||||
| **可选阻塞** | `check_labels: "block"`:apply 成功但返回 `needs_attention: true`,客户端不得结束任务 | 小 |
|
||||
| **会话末汇总** | 最后一轮给一次总数(只一次,不逐条) | 小 |
|
||||
|
||||
**建议默认**:`check_labels: true` + 循环预算。也就是"提示一次,允许一轮修,不强制"。
|
||||
知识库仓可以用 `"block"`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 边界(必须说清)
|
||||
|
||||
| 问题 | T1 能不能 |
|
||||
|------|----------|
|
||||
| 模型刚改完,描述还成立吗 | ✅ 能(核心场景) |
|
||||
| 昨天有人改了代码,今天打开才发现描述过期 | ❌ 不能(`diff` 里没有,那是 T2 的活) |
|
||||
| 从别处复制粘贴一段代码带来的旧标签 | ❌ 不能(无历史) |
|
||||
| 描述写得笼统、无法证伪 | ❌ 不能(L1 也不查) |
|
||||
|
||||
**T1 的定位**:保证"**改动者当场被问一次**"。
|
||||
它不保证"整个仓库始终新鲜"——后者需要 T2/T3,是可选增强,不进默认路径。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与你担心的「疲劳」对照
|
||||
|
||||
| 场景 | 扫描式(每轮全量) | **T1(本机制)** |
|
||||
|------|------------------|-----------------|
|
||||
| 模型一轮看到几条 | 全仓库 N 条 | **0–2 条** |
|
||||
| 5 轮累计 | N × 5 | **≤ 2** |
|
||||
| 同一标签重复 | 每轮重复 | **一次** |
|
||||
| 未修复的旧债 | 每轮都提 | 不再提(等它被改到时再说) |
|
||||
| 模型需要记住"我之前看过" | 需要 | **不需要**(自包含) |
|
||||
| 需要 VCS / 台账 | 常需要 | **不需要** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你确认
|
||||
|
||||
1. **接受"T1 = 编辑期诊断,不是 lint 警告"这个定位吗?**(这是整个防疲劳论证的支点)
|
||||
2. `check_labels` 默认值:`false`(零开销)还是 `true`(修复回路默认开)?
|
||||
3. 漏掉的兜底:用**循环预算**(不强制)还是**可选阻塞**(`"block"`)为默认?
|
||||
4. 会话末汇总要不要做?(一次性总数,不逐条)
|
||||
|
||||
> 若你确认,P1 的第一步就很小:给 `repair_apply` 加 `check_labels`,
|
||||
> 在 `apply_edits` 之后解析两版、比较标签指纹,把结果挂在响应里。
|
||||
> 文档零改动、状态零新增、不依赖 git——**第一天就不会有任何存量警告**。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,145 @@
|
||||
# View:叙述面标注缺口(prose annot gaps)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
|
||||
|
||||
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何「改了却几乎没变化」
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
|
||||
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
|
||||
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
|
||||
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标视觉语法(既有,不新造)
|
||||
|
||||
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注 chip
|
||||
```
|
||||
|
||||
- underline:`mark.mq-anchor.mq-{decl|code|return}`
|
||||
- band:段落下方 `.annot-band` → leaders + chips
|
||||
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
|
||||
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
|
||||
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
|
||||
|
||||
---
|
||||
|
||||
## 3. 管线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CLI["marqdo view / view output"] --> build["build_file_view"]
|
||||
build --> cap["run_file_capture"]
|
||||
cap --> annot["build_view_annots"]
|
||||
annot --> doc["document::render_module_document"]
|
||||
doc --> page["html.rs page_file"]
|
||||
page --> js["initAnnotLeaders + initCallPickers"]
|
||||
```
|
||||
|
||||
| 步骤 | 位置 |
|
||||
|------|------|
|
||||
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
|
||||
| Capture + Call 事件 | `src/interp.rs` |
|
||||
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
|
||||
| 文档面 HTML | `src/view/document.rs` |
|
||||
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
|
||||
| CSS / leader JS | `src/view/html.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 四条用户问题 → 根因 → 验收
|
||||
|
||||
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
|
||||
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
|
||||
|
||||
### P1 — 叙述与代码同段时信息不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | underline 在,chip / 连线弱或无 |
|
||||
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
|
||||
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
|
||||
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
|
||||
|
||||
### P2 — 函数内变量不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
|
||||
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
|
||||
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
|
||||
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
|
||||
|
||||
### P3 — ` ```text ` 渲染不一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
|
||||
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
|
||||
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
|
||||
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
|
||||
|
||||
### P4 — 函数引用 / 代码卡未渲染
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
|
||||
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
|
||||
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
|
||||
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
|
||||
|
||||
### call_id 语义(写死)
|
||||
|
||||
| 位置 | call_id |
|
||||
|------|---------|
|
||||
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
|
||||
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修复约定(实现红线)
|
||||
|
||||
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
|
||||
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
|
||||
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
|
||||
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
|
||||
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收命令
|
||||
|
||||
```bash
|
||||
cargo build -q
|
||||
./target/debug/marqdo version # 须为当前工作树版本
|
||||
./target/debug/marqdo view public/00-welcome.mq.md --no-open
|
||||
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
cargo test -q --lib view::
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
|
||||
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
|
||||
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
|
||||
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
|
||||
@@ -0,0 +1,261 @@
|
||||
# 防警告疲劳:标签校验必须自带的「静默机制」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(机制基线:stale 是变更报告) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 触发 | 用户:`[]()` 每次报 warning 会导致烦躁与忽略,必须先有机制再开工 |
|
||||
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) |
|
||||
| 结论 | stale **不是"扫描报告",而是"变更报告"**;默认零噪音,严格模式 opt-in |
|
||||
|
||||
> **§2 的 M5 已修订**:原文以 `git diff` 作为核心机制是错的——沙箱 `exec=false` 调不了 git、
|
||||
> 浏览器 WASM 无进程能力、非 git 用户无从使用,而**最需要它的 agent 修复回路恰在这些环境里**。
|
||||
> 现改为 **「前一状态」provider 分层**:`T0 引用一致性 + T1 会话内前后对照` 为核心(零依赖),
|
||||
> `T2 外部历史源(git 等)` 与 `T3 台账` 为可选适配器。
|
||||
> 见 [staleness-providers.md](staleness-providers.md)。本文其余结论(分级、聚合、去重、
|
||||
> 可证伪、节流、三道闸、验收指标)不受影响。
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么标签检查比一般 lint 更容易被忽视
|
||||
|
||||
三个结构性原因:
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| **高频** | 纯度之后标签密度会接近"每个取值/调用一处"(现有索引 506 处 + 循环 44 处是下限) |
|
||||
| **主观** | 标签是自然语言,机器只能近似判断;报告天然带"可能"二字,说服力弱 |
|
||||
| **持续** | 代码天天改,断言天天可能过期 → 报告是**常驻背景音**,不是一次性事件 |
|
||||
|
||||
**而当前基线是零噪音**:实测 `lib/` + `ext/ai/` 共 **59 个文件**跑 `marqdo check`,
|
||||
**warning = 0、error = 0**
|
||||
(契约检查只在真错时报 error)。也就是说:
|
||||
|
||||
> 标签校验会成为这个项目**第一个持续的警告源**。
|
||||
> 第一次引入就必须做对——一旦用户学会忽略,再想收回就晚了。
|
||||
|
||||
---
|
||||
|
||||
## 1. 疲劳的真正根因
|
||||
|
||||
不是"报得多",也不是"偶尔报错",而是:
|
||||
|
||||
> **同一件已知的事,被反复告知。**
|
||||
|
||||
心理学上这叫 habituation:信号无新信息 → 大脑过滤 → 真警报也被过滤。
|
||||
|
||||
所以设计目标不是"少报",而是三条更硬的:
|
||||
|
||||
1. **没有新信息就不说话**(变化驱动,而非扫描驱动)
|
||||
2. **说了就必须能做点什么**(可执行、有定位、有建议)
|
||||
3. **说过的就不再重复**(确认即静默)
|
||||
|
||||
---
|
||||
|
||||
## 2. 六个候选机制与评估
|
||||
|
||||
### M1 分级(hint / warning / error)
|
||||
|
||||
按**证据强度**分级,而不是按"我觉得重要":
|
||||
|
||||
| 级别 | 判据 | 人类可见 | 影响退出码 |
|
||||
|------|------|---------|-----------|
|
||||
| **error** | 能证明断裂:引用了不存在的实体、空标签 `label.missing` | ✅ | ✅ |
|
||||
| **warning** | 能证明变化,但无法判断谁错(L2 指纹漂移) | ✅(默认聚合) | ❌ |
|
||||
| **hint** | 弱信号:标签提到的实体仍在,但不在当前语句 | ❌(仅 JSON / view / labels) | ❌ |
|
||||
|
||||
**关键**:默认级别取 **hint**,只有项目显式升档才进人类可见输出。
|
||||
这让"默认安静"成为语言行为,而不是团队纪律。
|
||||
|
||||
### M2 聚合(一条汇总,细节下沉)
|
||||
|
||||
`check` 的人类输出**最多一行**:
|
||||
|
||||
```
|
||||
contract check OK(另有 3 条标签提示,见 marqdo labels status --json)
|
||||
```
|
||||
|
||||
细节走 `--json`(机器)、`view`(徽章)、`labels`(逐条复核)。
|
||||
理由:`check` 是 CI 工具,人很少逐条读;真正的阅读界面是 `view` 与编辑器。
|
||||
|
||||
### M3 基线(bootstrap 静默吸收)
|
||||
|
||||
全量扫描第一次跑时**只写台账、不报告**,把存量债务吸收掉。
|
||||
适用:从旧语法迁移到纯度之后的第一次。
|
||||
|
||||
### M4 确认即静默(ack)
|
||||
|
||||
对某个「标签 + `()` 指纹」组合确认后,记录 `confirmed` → 同样的组合不再报。
|
||||
这是最直接的对症药:**说过的就不再说**。
|
||||
|
||||
### M5 结构化 diff(**已修订:降级为可选 provider T2**,见 [staleness-providers.md](staleness-providers.md))
|
||||
|
||||
> **stale 只在"`()` 变了、`[]` 没变"时报,且只针对本次变更集。**
|
||||
|
||||
三种实现层次:
|
||||
|
||||
| 层次 | 做法 | 状态 | 噪音 |
|
||||
|------|------|------|------|
|
||||
| M5a | 工作区 vs `HEAD`:解析两版本文本,比较同一标签的 `()` AST 指纹 | **零状态** | 无变更即零 |
|
||||
| M5b | 工作区 vs 「标签文本最后一次被修改的提交」(`git blame` 定位) | 零状态 | 更精确,但依赖 blame 语义 |
|
||||
| M5c | 台账比对(上一份文档的 L2) | 需台账 | 中(首次需 bootstrap) |
|
||||
|
||||
**M5a 的性质非常关键**:
|
||||
|
||||
- **零台账**:git 就是台账,不需要新文件、不会合并冲突
|
||||
- **零基线**:不需要 bootstrap,第一次跑就安静(因为没变更)
|
||||
- **零重复**:提交之后 diff 清空 → 报告自动消失(除非再次改到同一处)
|
||||
- **天生带 before/after**:报告直接给旧代码与新代码,正好是 LLM 复核需要的输入
|
||||
- **格式化免疫**:比较的是 AST 指纹,不是文本
|
||||
|
||||
**边界**:不在 git 仓库 / 无 git 时,M5 自动降级为「只做 L1 引用一致性」(仍然确定性、零噪音)。
|
||||
|
||||
### M6 文档内抑制(`[描述](…) # noqa`)—— **否决**
|
||||
|
||||
理由:
|
||||
1. **污染文档**:`noqa` 是机器垃圾,与"文档即散文"直接冲突
|
||||
2. **不可审计**:抑制理由丢失,后来者不知道当初为什么不查
|
||||
3. **永久化**:抑制会累积,最终整个文件静音
|
||||
|
||||
**替代**:抑制放**台账/配置**(可审计、可过期、可统计),不进文档。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐组合:默认零噪音 + 严格模式 opt-in
|
||||
|
||||
### 3.1 默认(所有项目)
|
||||
|
||||
| 规则 | 效果 |
|
||||
|------|------|
|
||||
| stale 只在 M5a(结构化 diff)时报 | 无变更 → 完全静默 |
|
||||
| 默认级别 hint | 不进 `check` 人类输出;仅 JSON / view |
|
||||
| `check` 最多一行聚合 | CI 日志干净 |
|
||||
| 每条提示必须带:定位、`doc_quote`、`code_past`/`code_now`、一句可执行建议 | 可行动 |
|
||||
| 同一标签在未处理前只报一次(按变更集去重) | 不重复 |
|
||||
| 非 git 环境降级为 L1 | 仍然安静 |
|
||||
|
||||
### 3.2 严格模式(知识库仓,opt-in)
|
||||
|
||||
在默认之上加:
|
||||
|
||||
| 规则 | 效果 |
|
||||
|------|------|
|
||||
| stale 升为 **warning** 或 **error** | 可作 CI gate |
|
||||
| 启用 M3 基线 + M4 确认台账 | 存量债务可管理 |
|
||||
| **棘轮(ratchet)**:允许债务存在,但**禁止增加** | 只拦新增,不清旧账 |
|
||||
| `labels status` 进 CI 报告 | 债务可见 |
|
||||
|
||||
**棘轮**是我认为最值得抄的机制:`baseline.json` 记 `{"stale": 12}`,
|
||||
`labels check` 只在 **数量增加** 时失败。这样:
|
||||
- 老债不阻塞任何人
|
||||
- 新债立刻被拦
|
||||
- 债务数字可下降,团队有正反馈
|
||||
|
||||
---
|
||||
|
||||
## 4. 「确认」的三种语义
|
||||
|
||||
M4 需要一个"确认"动作,三种可选:
|
||||
|
||||
| 语义 | 操作 | 优 | 劣 |
|
||||
|------|------|----|----|
|
||||
| **改标签** | 编辑 `[]` 文本 | 留下真实痕迹,最诚实 | 有时标签确实无需改 |
|
||||
| **改代码** | 恢复 `()` 的行为 | 守住原意图 | 有时代码才是对的 |
|
||||
| **显式确认** | `marqdo labels confirm <标签>`,台账记新指纹 | 最省事 | 易被当成"消除警告按钮" |
|
||||
|
||||
**设计建议**:三者都提供,但**显式确认要留痕**——
|
||||
台账记录 `confirmed_at` 与 `confirmed_by`(人或模型),
|
||||
`labels status` 能显示"这条被确认过几次"。
|
||||
**被反复确认的标签,本身就是坏味道**(说明描述与实现长期脱节),值得在状态里暴露。
|
||||
|
||||
---
|
||||
|
||||
## 5. 可证伪原则:写得越具体,越接受检查
|
||||
|
||||
这条是从根上减少噪音的机制:
|
||||
|
||||
> **只有能被证伪的断言才被检查。**
|
||||
|
||||
- 标签含 `` `实体` `` 反引号 → 可证伪 → 参与 L1
|
||||
- 标签是纯口语("按档位折算")→ 不可证伪 → **L1 完全不检查**
|
||||
|
||||
于是**检查成本由作者的书写具体程度决定**:
|
||||
写具体的作者获得更强的保鲜保证,也接受更多检查;
|
||||
写笼统的作者不被检查(但也得不到保护)。
|
||||
|
||||
这不是漏洞,而是诚实的对齐:**机器只能校验它看得懂的断言。**
|
||||
同时它反向抑制了"为凑数而写废话"——废话没人查,也就没有价值。
|
||||
|
||||
---
|
||||
|
||||
## 6. agent 侧节流:只问它自己刚改的
|
||||
|
||||
智能体是主要编辑者,最容易被警告淹没。规则:
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 一次 `repair_apply` 改了 `()` | 只对**它改到的**那些标签做 stale 检查,最多 N 条(如 5) |
|
||||
| 未触碰的标签 | 一条都不报 |
|
||||
| 同一修复轮内 | 只报一次,不随每次编辑重报 |
|
||||
| 超过 N 条 | 只报前 N 条 + 汇总("另有 K 条") |
|
||||
|
||||
这样模型每轮的输入里最多几条相关提示,且都带 before/after——
|
||||
**它看到的是"你刚改的这处,描述可能不再成立",而不是"全仓库有 200 处过期"**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 防"用忽视解决"的三道闸
|
||||
|
||||
即使有静默机制,用户仍可能整体忽略。三道闸让它**不可能"无声地"忽略**:
|
||||
|
||||
1. **债务可见**:`labels status` 输出「12 条待复核 / 共 412 条标签」。
|
||||
数字不报警,但每次问就给——忽略变成**有意识的选择**而非无意识。
|
||||
2. **可 gate**:知识库仓把 stale 设为 error,CI 红。
|
||||
3. **可审计的抑制**:抑制只存在于台账,`labels audit` 能列出所有抑制及其年龄。
|
||||
超过 N 天未复核的抑制 → 提示"这条抑制过期了"。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与现有设施的对接
|
||||
|
||||
| 现有 | 复用方式 |
|
||||
|------|---------|
|
||||
| `marqdo check` | 增加**一行**聚合;细节不给 |
|
||||
| `--json` 诊断输出 | hint 走这里,机器可读 |
|
||||
| MLSP `validate` | 默认不含 hint,可传 `labels: "strict"` 打开 |
|
||||
| MLSP `repair_targets` / `repair_apply` | ranges = 标签行 ∪ 代码行(已有能力) |
|
||||
| `marqdo view` | 标签徽章(新鲜 / 待复核);点击跳到标签与代码 |
|
||||
| `marqdo verify` / `stale` | 复用已有的知识 stale 通道,进健康报告 |
|
||||
| 新增 `marqdo labels` | `status` / `review` / `confirm` / `audit` 四个子命令 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收指标(可量化,写进文档以免日后走样)
|
||||
|
||||
上线前必须满足:
|
||||
|
||||
| 指标 | 目标 |
|
||||
|------|------|
|
||||
| **默认静默率** | 无代码变更时,`check` 输出中标签相关行 = **0** |
|
||||
| **报告密度** | 单次变更集中标签提示 ≤ **3 条**,或 ≤ 变更涉及标签数的 **20%** |
|
||||
| **重复率** | 同一标签在未修改前重复提示 = **0** |
|
||||
| **可行动率** | 每条提示带定位 + before/after + 建议 = **100%** |
|
||||
| **误报率** | 人工抽检 50 条,误报 ≤ **10%** |
|
||||
| **默认可见性** | `check` 人类输出最多 **1 行**;逐条只在 JSON / view / labels |
|
||||
| **退出码** | hint / warning **不影响**退出码 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **核心机制选 M5a(结构化 diff,零状态)吗?**
|
||||
我强烈建议选它——它把"疲劳"从设计问题降级为几乎不存在,且不需要台账。
|
||||
2. **默认级别**:hint(我建议)还是 warning?
|
||||
3. **严格模式的棘轮**(禁止新增、允许存量)要不要一并做?我建议要,成本很低。
|
||||
4. **显式确认要不要留痕**(`confirmed_by` / 次数)?我建议要——反复确认的标签本身就是坏味道。
|
||||
5. **`check` 的聚合行**要不要固定出现("标签 0 待复核"也算信息)?
|
||||
我建议**不出现**:零噪音优先,`labels status` 才回答这个问题。
|
||||
|
||||
> 定了这五条,我就可以按 P1(L1 + 诊断 + MLSP 往返)开工——
|
||||
> 因为 P1 只做"能证明断裂"的 error 与 hint,且天然走 M5 的变更口径,
|
||||
> 不会在第一天就制造出 506 条警告。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 缺陷记录:LLM 传输失败硬中断 Agent Runtime
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(接通 `agent.run` live 路径时) |
|
||||
| 影响面 | `host/net` · `plugins/llm` · `ext/ai/llm` · `ext/ai/llm/openai` · `ext/ai/agent` |
|
||||
| 相关 | [agent-run-efi-resolve-bugs-2026-10.md](agent-run-efi-resolve-bugs-2026-10.md) · [ext-agent.md](../design/ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
上游 LLM **连接拒绝 / 超时 / 非 200** 时,Runtime 曾以 **硬错误** 终止整个 `marqdo run`;产品(qdagent ASK/BUILD)无法落到结构化 `status=error`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现
|
||||
|
||||
```bash
|
||||
OPENAI_API_KEY=offline OPENAI_BASE_URL=http://127.0.0.1:9 \
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
# 修复前:exit≠0,error: http POST …
|
||||
# 修复后:exit 0,ask/step/run 均带 finish|status=error + error 文本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
| 层 | 行为 |
|
||||
|----|------|
|
||||
| `host_http_post` / SSE | 传输失败 `Err(...)` → VM abort |
|
||||
| `plugins/llm` `llm_chat_completions` | 同上 `Err` |
|
||||
| `ext/ai/llm/openai` | HTTP≠200 → `sys.exit 1` |
|
||||
| `agent.model_turn` / `step` / `plan` | 无软失败臂 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | 传输失败 → `{status:0, body}` / SSE error event | `src/host/net.rs` |
|
||||
| 2 | 插件返回 `{finish:error, error, …}` 而非 `Err` | `plugins/llm/src/lib.rs` |
|
||||
| 3 | openai 非 200 → 结构化 pack,禁止 `sys.exit` | `ext/ai/llm/openai.mq.md` |
|
||||
| 4 | `llm.ask` 透传 `error` / `finish` | `ext/ai/llm.mq.md` |
|
||||
| 5 | `model_turn` / `step` / `plan` 收成 `status=error` | `ext/ai/agent.mq.md` |
|
||||
| 6 | 金样 | `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
|
||||
**契约**:Agent Runtime 对 LLM 传输失败必须可捕获;`status=error` + `error` 字符串;进程退出码 0(程序正常返回错误图)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent
|
||||
|
||||
`ensure_llm` 有 key 但上游不可达时,`ask`/`build` 可走既有 `mode=error` 臂写 workbook,不再整 CLI 崩。
|
||||
@@ -0,0 +1,117 @@
|
||||
# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 |
|
||||
| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` |
|
||||
| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。
|
||||
这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现(qdagent)
|
||||
|
||||
环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用:
|
||||
|
||||
```text
|
||||
助手 = > agent.agent …
|
||||
`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve
|
||||
```
|
||||
|
||||
本仓几乎没有 `.marqdo/agent-kb` 编译 skill。
|
||||
|
||||
### Bug A — `efi=True` → `unknown function preflight`
|
||||
|
||||
**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run`
|
||||
|
||||
```markdown
|
||||
1. `efi`
|
||||
**efi_pf = preflight task=`task`**
|
||||
```
|
||||
|
||||
同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。
|
||||
裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。
|
||||
|
||||
**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。
|
||||
|
||||
### Bug B — miss resolve → `missing map key llm_free`
|
||||
|
||||
**位置**:
|
||||
|
||||
1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task`
|
||||
当 `kb_lookup` 返回 null:
|
||||
|
||||
```rust
|
||||
Ok(json!({
|
||||
"mode": "unknown",
|
||||
"skill": null,
|
||||
"resource": null,
|
||||
"confidence": 0.0,
|
||||
// 缺 llm_free
|
||||
}))
|
||||
```
|
||||
|
||||
2. Facade:`## run` 在 resolve 之后:
|
||||
|
||||
```markdown
|
||||
**llm_free = [llm_free](resolved)**
|
||||
```
|
||||
|
||||
脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。
|
||||
|
||||
**期望**:
|
||||
|
||||
- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐)
|
||||
- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何金样没拦住
|
||||
|
||||
| 金样 | 为何漏网 |
|
||||
|------|----------|
|
||||
| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** |
|
||||
| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` |
|
||||
| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss |
|
||||
|
||||
qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单(本轮)
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` |
|
||||
| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` |
|
||||
| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent 的含义
|
||||
|
||||
修复后 qdagent 可恢复:
|
||||
|
||||
```text
|
||||
product preflight → latch → agent.run (efi=True|False) / plan
|
||||
```
|
||||
|
||||
而不必长期绕开 `agent.run`。
|
||||
在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不改 EKC / `agent_eng_preflight` 语义
|
||||
- 不引入第二套 Agent loop
|
||||
- 不把向量检索升为权威真相
|
||||
@@ -0,0 +1,136 @@
|
||||
# 调研:代码即文档 × OKF × 沙盒 下的智能体 / 大模型优化(2026-10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研 + 问题分析 · 供方案 [ext-ai-optimize.md](../design/ext-ai-optimize.md) 参考** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [agent-framework-2026-09.md](agent-framework-2026-09.md) · [ai-agent-sandbox.md](ai-agent-sandbox.md) · [okf-and-marqdo.md](okf-and-marqdo.md) |
|
||||
| 本仓能力 | [ext-agent.md](../design/ext-agent.md) · [okf.md](../design/okf.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
|
||||
| 外部抽样 | Anthropic Agent Skills · SoK Agentic Skills (arXiv 2602.20867) · ForgeAgent · ACES / Skill Lift · Switchcraft 路由 · DSPy/GEPA ·「工作流编译进权重」· MalSkillBench |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
业界正把 Agent 优化从「更好的 chat loop」转向 **可验证、可复用、可隔离执行的技能层**;Marqdo 已具备 **可执行 Markdown(代码即文档)+ OKF/EKC 复用 + CoW 沙盒** 三件套,优化目标应是把这三件套焊成闭环:**试跑 → 证据 → 晋升 → 零/少 LLM 复用**,而不是追平 LangChain 功能清单。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 扫业界技能层 | Anthropic Skills(渐进披露 `SKILL.md`);SoK Agentic Skills 生命周期;ForgeAgent「能力铸造」;ACES Skill Lift |
|
||||
| 扫成本/路由 | Switchcraft 工具调用路由;DSPy+GEPA 提示优化;工作流编译进小模型权重 |
|
||||
| 扫安全 | MalSkillBench 运行时验证恶意技能;沙盒粒度讨论(per-skill / per-session) |
|
||||
| 对照本仓 | A0–A4 / Wave B 已落地;沙盒 S0–S4 已落地;OKF + EKC + adaptive routing 现状 |
|
||||
|
||||
**不修改** `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界态势(与 Marqdo 相关的收敛点)
|
||||
|
||||
### 2.1 技能层取代「纯工具调用叙事」
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Anthropic Agent Skills | 目录 + `SKILL.md`;元数据预载、正文按需;脚本可执行 | 形态近 OKF 任务包,但 Marqdo 技能 **本身可跑** |
|
||||
| SoK Agentic Skills | 发现→练习→蒸馏→存储→组合→评测→更新;代码技能需沙盒 | 生命周期与 OKF promote / sandbox.run 对齐 |
|
||||
| ForgeAgent | 生成能力 → 沙盒证明 → 信任复用;失败进回归隔离 | **验证后晋升** 正是 solidify / `llm_free` 缺的硬闸 |
|
||||
| ACES | 有/无技能配对试验 → Skill Lift | 可作 Marqdo 评测 harness 指标 |
|
||||
|
||||
### 2.2 成本:路由 + 编译 + 小模型
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Switchcraft | 工具调用场景路由到最便宜仍正确的模型;报道大幅降本 | 已有 `marqdo \| small-llm \| llm \| auto`;可加 **工具步/试跑步** 细分 |
|
||||
| DSPy / GEPA | 用反馈改写指令,小模型追上大模型 | 优化对象应是 **`.mq.md` 提示文档 / standing / 路由策略文件**,不是黑盒字符串 |
|
||||
| 工作流编译进权重 | 程序化流程进小模型权重,上下文常数级 | 长期对应「高频 OKF 技能 → 专用小模型」;短期优先 **llm_free 源码路径** |
|
||||
|
||||
### 2.3 安全:技能不可信 + 沙盒必验
|
||||
|
||||
恶意技能基准与 SoK 均强调:**技能说明与代码默认不可信**,须运行时隔离。Marqdo 新沙盒(默认拒 plugin/net/exec)正好是技能晋升前的证明场。
|
||||
|
||||
---
|
||||
|
||||
## 3. Marqdo 已有资产(优化起点)
|
||||
|
||||
| 资产 | 现状 | 优化杠杆 |
|
||||
|------|------|----------|
|
||||
| 代码即文档 | `.mq.md` = 程序 = 提示工作面;GFM 表 / 链接取元 | 减少 json 胶水;让模型「看见」结构 |
|
||||
| 写回 | `marqdo-out` 槽;step 默认写回 | 晋升证据、失败避坑 |
|
||||
| OKF / agent-kb | 命中 / near / promote / solidify / `llm_free` | 复用率、降本主轴 |
|
||||
| EKC / EFI | L0–L4 catalog;preflight REUSE/ADAPT/CREATE | 生成前先查工程知识 |
|
||||
| Adaptive routing | marqdo / small-llm / llm / auto + policy 文件 | 再细分 sandbox 试跑 vs 开放推理 |
|
||||
| Sandbox | CoW + capped `run`;`ext/ai/sandbox` | **试跑闸门**;未 commit 不污染仓库 |
|
||||
| MCP / corpus | 证据工具,`authority=workbook` | 保持不升权威 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题分析(差距,不是功能羡慕)
|
||||
|
||||
### P1 — 试跑与晋升未焊死
|
||||
|
||||
沙盒已能 CoW 试跑,但 **`agent.step` / `plan` 默认仍可直接改真实树**;OKF `llm_free` 晋升不强制「沙盒金样绿」。
|
||||
→ 风险:未验证技能进入复用池(业界 ForgeAgent / MalSkillBench 已证明此问题)。
|
||||
|
||||
### P2 — 技能形态双轨
|
||||
|
||||
Anthropic Skills = 文件夹 + 渐进披露;Marqdo = 可执行 `.mq.md` + OKF 类型。
|
||||
→ 机会:用 **OKF frontmatter + 可执行体** 统一,不必引入第二套 SKILL.md 权威;缺的是 **披露层级与验证元数据**(适用条件、fixture、sandbox profile)。
|
||||
|
||||
### P3 — 路由粒度偏粗
|
||||
|
||||
现有路由偏「整任务后端」;未区分:查 OKF / 写补丁 / 沙盒 `run` / 对外 HTTP。
|
||||
→ Switchcraft 启示:按 **步骤类型** 选模型,且「便宜模型推理 token 爆炸」要计入总成本。
|
||||
|
||||
### P4 — 评测未锁差异化
|
||||
|
||||
Wave B1 仍 Active:缺稳定 **Skill Lift / 沙盒证明率 / llm_free 命中率 / 文档可读性** 指标。
|
||||
→ 没有指标,优化会滑回「多调几次模型」。
|
||||
|
||||
### P5 — 代码即文档在 Agent 产出侧仍易腐化
|
||||
|
||||
模型仍可能吐 `json.set` 链、混用 EN/ZH API、跳过表结构。
|
||||
→ 沙盒可跑通语法,但 **风格门禁**(lint / preflight)未默认卡在 commit 前。
|
||||
|
||||
### P6 — 上下文与 EKC 未默认进每步
|
||||
|
||||
EFI / catalog 能力在,但 step 默认上下文仍可能偏源码切片,缺少「先 REUSE」硬门槛。
|
||||
|
||||
### P7 — LLM 表面与 Agent 成本账未统一
|
||||
|
||||
`llm.ask` / `stream` / usage 已有;Agent 侧缺 **按会话/技能的成本仪表盘** 写回文档(可 git 审)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 优化目标函数(建议)
|
||||
|
||||
在固定任务集上最大化:
|
||||
|
||||
\[
|
||||
\begin{align*}
|
||||
& \text{ReuseRate}(\text{OKF hit} + \text{llm\_free}) \\
|
||||
&+ \text{SandboxProofRate}(\text{试跑绿再 commit/promote}) \\
|
||||
&- \lambda_1 \cdot \text{TokenCost} - \lambda_2 \cdot \text{HostMutationsWithoutCommit}
|
||||
\end{align*}
|
||||
\]
|
||||
|
||||
约束:权威真相仍是 `.mq.md`;不引入隐藏 TOOL 主循环;不改 `doc/next/*`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 链接 |
|
||||
|------|------|
|
||||
| Skills | [Anthropic engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Claude Code skills](https://code.claude.com/docs/en/skills) · [agentskills / anthropics/skills](https://github.com/anthropics/skills) |
|
||||
| 论文 | [SoK: Agentic Skills](https://arxiv.org/html/2602.20867) · [Skill Issue (repo SKILL 优化)](https://arxiv.org/html/2609.12742v1) · [ACES Skill Lift](https://arxiv.org/html/2608.20614) · [MalSkillBench](https://arxiv.org/html/2606.07131v3) · [Compiling workflows into weights](https://arxiv.org/html/2605.22502) |
|
||||
| 开源/产品 | [ForgeAgent](https://github.com/Yashasm18/ForgeAgent) · [DSPy GEPA](https://dspy.ai/current/getting-started/gepa-optimization/) · [Switchcraft](https://www.microsoft.com/en-us/research/publication/switchcraft-ai-model-router-for-agentic-tool-calling/) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 结语
|
||||
|
||||
Marqdo 不缺「再一个 Agent SDK」;缺的是把 **文档真相、知识晋升、沙盒证明、模型路由** 收成可度量闭环。下一篇方案文档按问题编号给出可选方向与推荐波次,**不预设唯一银弹**。
|
||||
@@ -0,0 +1,392 @@
|
||||
# 调研:AI 扩展库沙盒设计(执行隔离 × 工作区暂存 × 写回)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 供 `ext/ai/*` 沙盒设计锁定参考**(**2026-10-16 修订**:纳入「AI 只生成 Marqdo」产品约束) |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 |
|
||||
| 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) |
|
||||
| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) · [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**在「Agent 只生成 / 只执行 Marqdo(`.mq.md`)」这一产品约束下,Marqdo AI 沙盒应以 Wasm 为主沙盒——且必须是「内核 + `lib/*` + `ext/*`」可运行的完整运行时沙盒,而不是只跑光秃解释器。**
|
||||
|
||||
锁定方向:
|
||||
|
||||
1. **执行隔离 = Marqdo Wasm 运行时(与 ADR 0002 同构)** — deny-by-default 能力导入;**默认不授予** shell / 外联 / `dlopen` 原生插件。AI 产出面收窄到 Markdown 程序后,不必为通用 coding Agent 的「任意二进制」付沙盒税。
|
||||
2. **库完备性是验收线,不是加分项** — 沙盒内须能 `import lib/…` 与受支持的 `ext/…`;缺能力时 **显式失败**,禁止静默空成功(对齐 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5)。
|
||||
3. **工作区突变 = CoW / whiteout / 显式 commit**(应用层 VFS,必要时 overlay)— 「修改短暂不生效 → 确认写回」保留;**禁止以符号链接森林作为隔离边界**。
|
||||
4. **OS 沙盒 / microVM** — 降为 **逃逸舱 / 托管 Profile**:仅当显式启用 foreign、`subtask` 真子进程、或未来多租户托管时使用;**不是** Marqdo-only Agent 的默认主路径。
|
||||
|
||||
初稿曾按「通用 coding Agent 还需 shell」把 Wasm 与 bwrap 并列;在 Marqdo-only 约束下,主结论改为 **Wasm-first + 库完备 + CoW 写回**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法与边界
|
||||
|
||||
### 1.1 做了什么
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 厂商/产品文档 | Anthropic Claude Code sandbox / `@anthropic-ai/sandbox-runtime`;VS Code Copilot agent sandboxing;Docker AI Sandboxes;Turso AgentFS CoW overlay;OpenSandbox isolation sessions;WASI / jco preview2-shim;VS Code for the Web WASM webshell |
|
||||
| 工程对比文 | Northflank / Cosmonic 2026 agent sandbox 指南;gVisor vs Firecracker vs Docker 对比;ContainAI security comparison |
|
||||
| 学术与标准 | USENIX SEC'22 *Provably-Safe Multilingual Software Sandboxing using WebAssembly*;KTH 论文 *Intra-process Fault Isolation Using WebAssembly*(SFI 通信开销);ACM TOSEM *Research on WebAssembly Runtimes: A Survey*(2025);WASI Design Principles(capability / 无 ambient authority) |
|
||||
| 安全案例 | brig 项目挂载 symlink 逃逸(CVSS 8.2);Anthropic sandbox-runtime 对 bwrap bind 跟随 symlink 的修复;Docker Sandbox「direct mount vs clone」威胁说明 |
|
||||
| 对照本仓 | `ext/ai/{llm,agent}`、`lib/writeback`、`lib/subtask`、ADR 0002 浏览器 WASM、`RunOptions.allow_fs_write` 默认关 |
|
||||
|
||||
### 1.2 不做的
|
||||
|
||||
- 不把「发版用的容器镜像」与「Agent 工具沙盒」混为一谈。
|
||||
- 不宣称某一云厂商托管沙盒(E2B / Modal / Daytona)为 Marqdo 默认依赖。
|
||||
- 不修改 `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
### 1.3 产品约束(修订要点):AI 只生成 Marqdo
|
||||
|
||||
这是相对通用 coding Agent(Claude Code / Codex)的 **结构性好消息**:
|
||||
|
||||
| 通用 Agent | Marqdo AI Agent(本调研采纳) |
|
||||
|------------|------------------------------|
|
||||
| 模型可产出 shell / Python / 任意仓库补丁 | 模型产出面收束为 **`.mq.md`(文档即程序)** |
|
||||
| 沙盒必须兼容「整台开发机能力」 | 沙盒只需跑 **同构 Marqdo 运行时** |
|
||||
| Wasm 往往只能罩住工具子集 | Wasm **可以**成为主执行边界 |
|
||||
| 标准库 = 语言运行时 + OS 工具链 | 标准库 / 扩展 = **`lib/*.mq.md` + `ext/**`(+ 受控宿主能力)** |
|
||||
|
||||
硬规则建议(后续 design 应写死):
|
||||
|
||||
1. Agent 工具表 **不提供** 通用 `bash` / 任意语言 `exec`(除非显式 opt-in 逃逸舱,且另套 OS 沙盒)。
|
||||
2. Agent 改仓库的权威动作是 **写 / 修订 `.mq.md`(含写回块)**,经 CoW 会话再 `commit`。
|
||||
3. 运行 Agent 生成的程序 = 在沙盒里 `run` 该 `.mq.md`,且其 `import` 的 **lib 与 ext 必须可用或显式报不可用**。
|
||||
|
||||
### 1.4 威胁模型(在 Marqdo-only 下收窄)
|
||||
|
||||
| 威胁 | 典型路径 | Marqdo-only 下的权重 |
|
||||
|------|----------|----------------------|
|
||||
| T1 提示注入 | 诱导读密钥、外泄、破坏 `.mq.md` | 仍高 — 靠能力拒绝 + CoW |
|
||||
| T2 工具侧信道 | `subtask`/`foreign` 子进程 | **默认关闭**;opt-in 才升权 |
|
||||
| T3 工作区即时破坏 | 直接写穿源树 | 靠 CoW;commit 闸门 |
|
||||
| T4 挂载逃逸 | symlink / bind 打穿 | 仍相关 — **勿用 symlink 作 W 层** |
|
||||
| T5 网络外泄 | `lib/net` / llm 出站 | 能力开关 + 域名策略 |
|
||||
| T6 Wasm 宿主桥过宽 | `host_fs_*` / 插件桥过宽 | **主威胁** — 桥 = 权限表 |
|
||||
| T7 库残缺假安全 | 沙盒能跑 `# main` 但 `import lib/fs` 怪崩或静默空 | **产品验收威胁** |
|
||||
|
||||
**成功标准:** 失败域止于会话 upper + 已授予能力;真实工作区默认只读直至 commit;**代表性 `lib/*` 与 `ext/*` 金样在沙盒内可跑或得到明确 `unavailable in sandbox` 诊断**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 先拆三个「沙盒放哪里」(Marqdo-only 版)
|
||||
|
||||
业界「Harness / Workspace / Execution」三分法仍成立,但 **Execution 的内容变了**:
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Pattern H — Harness(编排环) │
|
||||
│ ext/ai/agent · parent Plan-and-Move ·(可选)MCP client │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern W — Workspace mutation(.mq.md 真相如何变) │
|
||||
│ CoW upper / whiteout / diff / commit → writeback │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern X — 执行 Agent 产出的 Marqdo 程序 │
|
||||
│ Wasm Marqdo runtime + embedded/packaged lib + sandboxed │
|
||||
│ ext 能力面(非「任意 shell」) │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Pattern | Marqdo 落点 | 沙盒要解决什么 |
|
||||
|---------|-------------|----------------|
|
||||
| H | `ext/ai/agent` | 编排是否持有过宽宿主权限;模型 I/O 与执行隔离 |
|
||||
| W | `lib/writeback` · 工作簿 | 编辑是否立刻污染仓库;人审/父裁决后落盘 |
|
||||
| X | **Wasm 内 `run` `.mq.md`** | 计算隔离;**lib/ext 能力是否完备且受控** |
|
||||
|
||||
用户提案在 Marqdo-only 下:**Wasm 作 X 主底层是正确方向**;仍须改掉 symlink,并补上 **库完备性** 这一环。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案谱系(横向对比)
|
||||
|
||||
> **读法(修订后):** 下表仍保留通用 Agent 对照。对 **Marqdo-only** 产品,请以 §0 / §5 / §6 的 Wasm-first 结论为准;本节 A/B 升权,F/G/H 降为逃逸舱或托管。
|
||||
|
||||
评分:● 强 / ◐ 中 / ○ 弱 / — 不适用。维度按「隔离强度」等客观属性;**产品适配**见 §5。
|
||||
|
||||
| 方案 | 隔离强度 | 启动成本 | 任意二进制 | 工作区暂存语义 | 与 Marqdo 契合 | 主要风险 |
|
||||
|------|----------|----------|------------|----------------|----------------|----------|
|
||||
| **A. 浏览器 WASM + 虚拟 FS** | ●(计算)◐(经桥的 FS) | ● | ○ | ◐(需自建 overlay) | ●(已有 ADR 0002) | 宿主桥过宽;无原生 toolchain |
|
||||
| **B. WASI / Component Model(非浏览器亦可)** | ● | ● | ○(仅 WASI 目标) | ●(preopens + 自建 VFS) | ● | 工具链不全则需降级 |
|
||||
| **C. 符号链接映射工作区 + 延迟写回** | ○ | ● | —(本身不是执行沙盒) | ◐(似是而非) | ○ | **symlink 逃逸是已知高危类** |
|
||||
| **D. 应用层 CoW VFS(upper/lower/whiteout)** | ◐(逻辑) | ● | — | ● | ●● | 必须配合 X 层 OS 隔离 |
|
||||
| **E. OS overlayfs / FUSE / AgentFS 式 CoW** | ●(配合命名空间) | ◐ | ●(在沙盒内) | ●● | ● | Linux/macOS 实现分叉;运维 |
|
||||
| **F. bubblewrap / Seatbelt(Anthropic SRT 类)** | ● | ● | ● | ○(默认可写 cwd) | ● | 需另加 CoW 才有「暂不生效」 |
|
||||
| **G. Docker / 硬化容器 / gVisor** | ◐→● | ◐ | ● | ◐(volume 策略) | ◐ | 共享内核或兼容性;重 |
|
||||
| **H. microVM(Firecracker / Kata)** | ●● | ◐ | ● | ◐ | ○(本地 CLI 过重) | KVM/运维;适合多租户托管 |
|
||||
| **I. 纯语言沙盒(RestrictedPython 等)** | ○ | ● | ○ | — | ○ | 对 Agent 工具链几乎无用 |
|
||||
|
||||
### 3.1 A — 浏览器 WASM + 虚拟 FS
|
||||
|
||||
**机制:** Wasm 线性内存 + 校验 + 仅经 import 碰宿主;FS 多为内存树 / OPFS / 经 JS bridge 的映射。Marqdo 已锁定「解释器进 WASM」(ADR 0002),默认 `allow_fs_write=false`。
|
||||
|
||||
**文献支撑:** Wasm 作为 SFI 窄腰(Bosamiya et al., USENIX SEC'22);进程内沙盒跨边界通信可比 IPC 快数量级(KTH Wasm-SFI 论文);WASI 明确 **capability / 无 ambient authority**。
|
||||
|
||||
**优点:** 与「代码即文档」浏览器运行同构;deny-by-default;适合跑 `.mq.md`、公式库、受控插件。
|
||||
**缺点:** 不能原生跑 `cargo test` / `npm` / 任意 shell;安全上限取决于 **bridge 授予了什么**;浏览器场景下「符号链接用户工作区」通常要落到 File System Access API 或服务端中继,**不是** POSIX symlink 语义。
|
||||
|
||||
**判定:** 在 **Marqdo-only** 约束下,作为 **Pattern X 主沙盒** 与浏览器内 Marqdo 的正解;完备性取决于 **lib 嵌入 + ext 能力桥**(§4.1),不取决于 shell。通用「任意二进制 Agent」场景下仍不够——但那不是本产品默认。
|
||||
|
||||
### 3.2 B — WASI / Component Model(CLI 宿主)
|
||||
|
||||
**机制:** preopens 显式挂载;`WASIShim({ sandbox: { preopens, enableNetwork: false } })`(Bytecode Alliance jco);Component imports = 权限表。
|
||||
|
||||
**优点:** 与 Wasm 同族,可在 Node/Wasmtime 跑,不绑浏览器;能力模型清晰。
|
||||
**缺点:** 同 A,任意 Linux 工具链需「宿主机再包一层」或改编译目标。
|
||||
|
||||
**判定:** Marqdo **官方扩展 / 插件中可 Wasm 化的部分**应走这条;与 ADR 0002 一条能力谱。
|
||||
|
||||
### 3.3 C — 符号链接映射工作区(用户设想的核心)
|
||||
|
||||
**设想:** 沙盒根下用 symlink 指向用户文件;写改暂存别处;确认后写回;删除 = 删 symlink。
|
||||
|
||||
**表面吸引力:** 零拷贝读、实现「像」有暂存。
|
||||
|
||||
**为何行业不把它当隔离原语:**
|
||||
|
||||
1. **Bind/mount 跟随 symlink 是经典逃逸。** Anthropic `sandbox-runtime` 明确修复:`allowWrite` 若为指向界外的 symlink,bwrap `--bind` 会把真实目标变成可写(PR #138 类修复)。
|
||||
2. **项目挂载未解析 symlink 可致高危。** Endor Labs 披露 brig「project mount symlink traversal」(CVSS 8.2):Agent 在可写项目内把子目录换成指向 `/etc` 的 symlink,下一轮宿主机按字符串挂载即打穿。
|
||||
3. **「删除 = 删 symlink」语义错误。** 删链接只去掉别名,**不等于**对 lower 层文件的 whiteout;若链接指向真实文件且曾被打开写穿,删除链接也救不回。
|
||||
4. **写穿风险。** 若某路径被解析成真实 inode 且可写,暂存承诺立刻破产。
|
||||
5. **跨平台。** Windows junction/reparse、浏览器虚拟 FS、容器 bind,行为不一致。
|
||||
|
||||
**判定:** **否决作为 Marqdo 默认工作区隔离方案。** 允许在 **只读、已解析、拒绝可写路径上的 symlink 组件** 的前提下作实现细节,但不得当作安全边界叙事。
|
||||
|
||||
### 3.4 D — 应用层 CoW VFS(推荐作 W 层默认)
|
||||
|
||||
**机制:**
|
||||
|
||||
```text
|
||||
lower = 真实工作区(只读打开 / 只读能力)
|
||||
upper = 会话 delta(内存 map / 目录树 / SQLite blob)
|
||||
whiteout = 逻辑删除集合
|
||||
view(path) = upper ?? (!whiteout && lower)
|
||||
commit() = 把 upper/whiteout 应用到 lower(可经人审)
|
||||
discard() = 丢弃会话
|
||||
diff() = 可审变更集
|
||||
```
|
||||
|
||||
与 Turso AgentFS、OpenSandbox `workspace.mode: overlay` 的 **语义同构**,但不强制 FUSE。
|
||||
|
||||
**与 Marqdo 对齐点:**
|
||||
|
||||
| VFS 操作 | Marqdo 真相 |
|
||||
|----------|-------------|
|
||||
| `diff()` | 父 Agent / 人审材料;可进 view |
|
||||
| `commit()` 文本结果 | `writeback.record` / 工作簿补丁 |
|
||||
| `discard()` | 失败回合不污染仓库 |
|
||||
| 只读 lower | 防止 T3 即时破坏 |
|
||||
|
||||
**优点:** 纯用户态、可测、可嵌入 `plugins/agent`;不依赖 root/FUSE;金样可锁。
|
||||
**缺点:** 对 **沙盒内原生工具**(它们走真实 POSIX)不可见,除非再挂 E 或把工具 I/O 也改走 VFS API。
|
||||
|
||||
**判定:** **Pattern W 的默认实现。**
|
||||
|
||||
### 3.5 E — OS CoW overlay(AgentFS / overlayfs / OpenSandbox)
|
||||
|
||||
**机制(AgentFS 公开设计):** lower=宿主只读;upper=SQLite delta;删除=whiteout;Linux 用 FUSE+user/mount ns;macOS 用 NFS+`sandbox-exec`。OpenSandbox 默认 `overlay`,会话结束可丢 upper。
|
||||
|
||||
**优点:** 对 **任意 shell 工具**透明;「改了但宿主机 `git status` 仍干净」体验业界已验证。
|
||||
**缺点:** 平台依赖;FUSE 权限;与应用层 D 双实现成本。
|
||||
|
||||
**判定:** **当 Pattern X 需要真实 shell 且要求暂存对工具透明时**启用(Linux 优先);作为 D 的「native 加速后端」,不是替代 Wasm。
|
||||
|
||||
### 3.6 F — OS 进程沙盒(bwrap / Seatbelt / VS Code Copilot)
|
||||
|
||||
**机制:** Anthropic:文件系统隔离 + **网络隔离(缺一不可)**;Linux bubblewrap + 代理;macOS Seatbelt。VS Code Copilot:同类依赖;路径分 readwrite / readonly / denied;明确「不是 VM,削弱授权即削弱边界」。
|
||||
|
||||
**优点:** 本地编码 Agent 的事实标准;覆盖子进程;启动轻。
|
||||
**缺点:** 默认可写 cwd → **没有**「暂不生效」;必须与 D/E 组合。Symlink 配置路径需解析与拒绝。
|
||||
|
||||
**判定:** **Pattern X(shell/外联/MCP)本地默认。**
|
||||
|
||||
### 3.7 G / H — 容器与 microVM
|
||||
|
||||
**共识:** 裸 Docker 共享内核,不适合作唯一边界应对不可信代码;gVisor 加强 syscall 拦截;Firecracker/Kata 适合多租户与高威胁(~125ms 级启动)。Docker AI Sandboxes 区分 **direct mount(即时写穿)** vs **clone(只读源 + 私有副本)**——后者才接近「确认后写回」。
|
||||
|
||||
**判定:** Marqdo **本地 CLI 默认不强制 microVM**;若未来 `ext` 提供托管执行 / 多租户,再把 H 定为服务端 Profile。G 可作为打包/CI Profile。
|
||||
|
||||
### 3.8 I — 语言级沙盒
|
||||
|
||||
对「Agent 会跑 shell」场景基本无效;仅作极窄解释器内嵌参考。
|
||||
|
||||
---
|
||||
|
||||
## 4. 专门评估:用户提案(修订)
|
||||
|
||||
> 浏览器 WASM 作沙盒底层 + 符号链接用户工作区 + 修改短暂不生效 + 确认后写回 + 删除变删 symlink。
|
||||
> **补充约束:** AI 只生成 Marqdo;沙盒须能用标准库与扩展库。
|
||||
|
||||
| 子命题 | 评价 | 说明 |
|
||||
|--------|------|------|
|
||||
| Wasm 作主执行隔离 | **在 Marqdo-only 下正确** | 与 ADR 0002 同构;不必为 shell 全集付税 |
|
||||
| 沙盒须含 lib + ext | **正确且关键** | 「能跑 `# main`」≠ 好沙盒;见 §4.1 |
|
||||
| 「短暂不生效」 | **正确** | CoW / staging(方案 D,必要时 E) |
|
||||
| 「确认后写回」 | **正确且极契合 Marqdo** | 与 writeback、父裁决、workbook 同一哲学 |
|
||||
| 「symlink 映射工作区」 | **仍错误** | 与是否只用 Marqdo 无关;换 CoW/whiteout |
|
||||
| 「删除 = 删 symlink」 | **仍错误** | 应为 whiteout;commit 时再对 lower 删除 |
|
||||
| 「性能最好且安全性最高」 | **Wasm 主路径下接近成立** | 前提是桥最小权限 + CoW;symlink 仍拉低安全 |
|
||||
|
||||
**修订后的正确表述:**
|
||||
|
||||
> **以 Wasm Marqdo 运行时为主沙盒,打包/嵌入 `lib/*`,经能力桥提供受支持的 `ext/*`;工作区用 lower 只读 + upper/whiteout;人审/父裁决后 commit。符号链接不作隔离原语。shell/外联/原生 dlopen 默认关闭,仅作显式逃逸舱。**
|
||||
|
||||
### 4.1 库完备性:什么叫「标准库和扩展库也能用」
|
||||
|
||||
沙盒若只能跑内置算术、却不能 `import lib/json` 或跑 `ext/ai/llm` 的离线金样,对 Agent 开发几乎无用——模型生成的 `.mq.md` **本来就会依赖 lib/ext**。
|
||||
|
||||
三类库进沙盒的路径不同:
|
||||
|
||||
| 类别 | 今日形态 | 沙盒策略 |
|
||||
|------|----------|----------|
|
||||
| **纯 `.mq.md` 库**(多数 `lib/*`、部分 `ext` 门面) | 源码 import | **嵌入或会话导入图**(已有 `embedded_lib` / import map)— 必须默认可用 |
|
||||
| **需宿主能力的 lib**(`fs` / `net` / `writeback` / `subtask` / `datetime.now`…) | `host_*` | **经能力表桥接**到会话 VFS / 受控 clock / 受控 fetch;默认最小集 |
|
||||
| **原生 ABI 扩展**(`plugins/web`、`plugins/agent`、quantum 等 `.so`) | `plugin.load` + dlopen | 浏览器/Wasm **无 dlopen**(ADR 0002 N2)。沙盒内应:**纯 mq 门面 + Wasm 插件**、或 **宿主代执行且权限计入会话**、或 **显式 `unavailable`** — 禁止假装成功 |
|
||||
|
||||
与 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5 对齐并扩展为 **Agent 沙盒能力矩阵(草案)**:
|
||||
|
||||
| 能力 | 沙盒默认 | 备注 |
|
||||
|------|----------|------|
|
||||
| builtins / 表 / 控制流 / 对象 | ✓ | 内核 |
|
||||
| `lib/math` `json` `table` `text` `collection`… | ✓ | embedded |
|
||||
| `lib/fs` | ✓(仅会话 VFS) | 写进 upper;禁越出 root |
|
||||
| `lib/writeback` | ✓(写会话内 `.mq.md`) | commit 后才进真实树 |
|
||||
| `lib/net` / llm HTTP | 默认关 / 域名白名单 | 与 T5 |
|
||||
| `lib/subtask` `fn=` | ✓(同 Wasm 会话) | |
|
||||
| `lib/subtask` `path=`/`code=`/`lang=` | **默认拒** | 逃逸舱 + OS 沙盒 |
|
||||
| `lib/plugin` + 原生 `.so` | **默认拒** | 改 Wasm 插件或宿主代执行 |
|
||||
| `ext/ai/llm` · `ext/ai/agent`(mq 门面) | ✓(能力允许时) | 网络/密钥另授 |
|
||||
| `ext/web` 服务端 listen/DB | **默认拒或只读 stub** | 完整 axum 不进沙盒;可测「装配/渲染」子集 |
|
||||
| `ext/quantum` / `ext/linalg` | 目标 ✓ | 优先纯逻辑 / Wasm 插件,避免强依赖宿主机 .so |
|
||||
|
||||
**验收金样建议(S 阶段):**
|
||||
一套「沙盒烟囱」:`import` 常用 lib → 写会话文件 → writeback → `diff` → `commit`;再各挑一个 **纯逻辑 ext** 与一个 **需网络的 ext**(后者验证拒绝/白名单)。缺能力必须诊断含 `unavailable in sandbox`(或同等措辞)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 综合评分(面向 Marqdo-only 产品)
|
||||
|
||||
加权(修订):执行隔离契合 Marqdo-only 30%、**lib/ext 完备** 25%、与 writeback 真相 20%、实现成本 15%、跨端(CLI↔浏览器)10%。
|
||||
(「任意 shell 工具完备」不再作为主权重。)
|
||||
|
||||
| 候选架构 | 分(相对) | 备注 |
|
||||
|----------|------------|------|
|
||||
| **A/B Wasm-first + D CoW + 库完备能力表** | **100(推荐)** | 主路径 |
|
||||
| 同上 + 逃逸舱 F(opt-in shell) | 95 | 兼容少数 foreign 需求 |
|
||||
| D + E + F(通用 coding 向) | 75 | 过重;非 Marqdo-only 默认 |
|
||||
| 仅 F(可写 cwd) | 55 | 缺 CoW;且鼓励非 mq 工具 |
|
||||
| 仅 A 但无 CoW、无 lib 嵌入 | 40 | 「半沙盒」 |
|
||||
| 仅 C(symlink) | 20 | 否决 |
|
||||
| 仅 H(人人 microVM) | 50 | 托管可选;本地默认过重 |
|
||||
|
||||
**绝对「最硬」单点**仍可以是 microVM(托管 Profile)。
|
||||
**Marqdo「最合适」:** **Wasm 完整运行时沙盒(内核+lib+受控 ext)+ CoW 工作区 + commit 闸门**。
|
||||
|
||||
---
|
||||
|
||||
## 6. Marqdo 应采用的沙盒设计(推荐锁定草案 · 修订)
|
||||
|
||||
### 6.1 产品形态
|
||||
|
||||
| Profile | 场景 | 执行(X) | 工作区(W) |
|
||||
|---------|------|-----------|------------|
|
||||
| **`mq-sandbox`(默认)** | Agent 生成并试跑 `.mq.md` | **Wasm Marqdo** + embedded `lib/*` + 能力桥 `ext` | 应用层 CoW;commit→真实树 / writeback |
|
||||
| **`browser`** | 页内同构运行 | 同左(ADR 0002) | 内存/OPFS;无 POSIX symlink |
|
||||
| **`escape`(显式)** | foreign / 真子进程 | OS 沙盒包一层 | 仍建议 CoW 可见 |
|
||||
| **`hosted`(可选)** | 多租户 | Wasm 或 microVM | 会话隔离;凭证外置 |
|
||||
|
||||
### 6.2 推荐架构图
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────┐
|
||||
│ ext/ai/agent (Harness) │
|
||||
│ 只产出 / 编排 .mq.md · 人审闸门 │
|
||||
└──────────────────┬───────────────────┘
|
||||
│
|
||||
┌─────────────────────┼─────────────────────┐
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌────────────────────┐
|
||||
│ Workspace CoW (W) │ │ Marqdo Wasm (X) │
|
||||
│ lower = RO 工作区 │◄── fs/writeback ───│ 同构解释器/VM │
|
||||
│ upper / whiteout │ 能力导入 │ + embedded lib/* │
|
||||
│ diff·commit·discard│ │ + ext 能力面 │
|
||||
└─────────┬──────────┘ │ 默认: 无 shell/so │
|
||||
│ └────────────────────┘
|
||||
▼
|
||||
真实工作区 / <!-- marqdo-out -->
|
||||
(代码即文档真相源)
|
||||
|
||||
(可选)escape: subtask path|code|lang → OS sandbox
|
||||
```
|
||||
|
||||
### 6.3 API 面建议(设计级,非立即实现)
|
||||
|
||||
落点倾向:宿主能力进 `plugins/agent` / Wasm HostContext;作者面经 `ext/ai` 或 `lib`(**禁止** `ext/**` 直调 `host_*`)。
|
||||
|
||||
| 概念 | 语义 |
|
||||
|------|------|
|
||||
| `sandbox.open(root, mode=cow)` | 打开会话;lower 只读 |
|
||||
| `sandbox.read/write/list/remove` | 经 view;remove → whiteout |
|
||||
| `sandbox.diff` / `stat` | 供父 Agent / view |
|
||||
| `sandbox.commit` / `discard` | 闸门;可要求 HITL |
|
||||
| `sandbox.run(source\|path, caps=…)` | **Wasm 跑 Marqdo**;caps 声明 fs/net/llm/… |
|
||||
| `sandbox.caps` / `inspect` | 列出已授能力与 lib/ext 可用性(对齐 `web.inspect` 哲学) |
|
||||
| `sandbox.exec(...)` | **仅 escape Profile**;默认不存在于作者工具表 |
|
||||
|
||||
与现有衔接:
|
||||
|
||||
- `lib/*`:优先 embedded;FS/时间/网络走会话 caps。
|
||||
- `ext/*`:mq 门面可加载;原生插件默认不可用并诊断;长期可 Wasm 化的(linalg/quantum 逻辑)优先进 Wasm。
|
||||
- `lib/writeback`:写入会话内文件;`commit` 时进入真实树。
|
||||
- `lib/subtask`:默认仅 `fn=`;`path`/`code`/`lang` 要 escape。
|
||||
|
||||
### 6.4 硬禁(写入后续 design 时应保留)
|
||||
|
||||
1. **不以 symlink 森林作为隔离或暂存原语。**
|
||||
2. **不以「能跑空 `# main`」宣称沙盒完成** — 必须过 lib/ext 完备金样或显式 unavailable。
|
||||
3. **默认工具表不提供通用 shell / 任意语言 exec。**
|
||||
4. **不默认可写 bind 真实工作区。**
|
||||
5. **宿主桥 = 权限表**:未授能力不得 ambient 成功。
|
||||
6. **不静默降级**:缺 Wasm/能力时不得假装已隔离。
|
||||
7. **`ext/**` 不调 `host_*`**(既有宪法)。
|
||||
|
||||
### 6.5 分阶段落地(建议,非 `doc/next`)
|
||||
|
||||
| 阶段 | 交付 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| S0 | 威胁模型 + 本调研(含 Marqdo-only) | 本文 |
|
||||
| S1 | Wasm `run` + embedded 核心 `lib/*` + 会话 VFS 读 | 常用 lib 金样在沙盒绿 |
|
||||
| S2 | CoW upper/whiteout + diff/commit/discard | 未 commit 时宿主机 `git status` 干净 |
|
||||
| S3 | writeback / 工作簿在会话内可写;commit 对齐 | agent step 金样 |
|
||||
| S4 | caps:net/llm 白名单;`subtask` 非 fn 默认拒 | 诊断字符串稳定 |
|
||||
| S5 | 代表性 ext(纯逻辑 + 需网)沙盒金样 | 完备性验收 |
|
||||
| S6 | (可选)escape OS 沙盒;hosted microVM | 文档标明非默认 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 引用 |
|
||||
|------|------|
|
||||
| 产品 | [Anthropic: Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) · [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) · [VS Code agent sandboxing](https://code.visualstudio.com/docs/agents/run/agent-sandboxing) · [Docker AI Sandboxes security](https://docs.docker.com/ai/sandboxes/security/) · [Turso AgentFS overlay](https://turso.tech/blog/agentfs-overlay) · [OpenSandbox isolation sessions](https://open-sandbox.ai/guides/isolation-sessions) |
|
||||
| 标准 | [WASI Design Principles](https://github.com/WebAssembly/WASI/blob/main/docs/DesignPrinciples.md) · [jco preview2-shim sandbox](https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/README.md) |
|
||||
| 论文 | Bosamiya et al., *Provably-Safe Multilingual Software Sandboxing using WebAssembly*, USENIX Security 2022 · *Intra-process Fault Isolation Using WebAssembly* (KTH) · *Research on WebAssembly Runtimes: A Survey*, ACM TOSEM 2025 |
|
||||
| 综述 | [Cosmonic: Choosing an AI agent sandbox (2026)](https://cosmonic.com/ai-sandbox/choosing-an-agent-sandbox/) · [Northflank: MicroVMs, gVisor & isolation](https://northflank.com/blog/how-to-sandbox-ai-agents) |
|
||||
| 安全案例 | [brig symlink traversal / Endor Labs](https://www.endorlabs.com/learn/project-mount-symlink-traversal-in-brig-how-a-sandbox-reaches-host-directories-it-was-never-given) · Anthropic sandbox-runtime symlink bind 修复 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 结语
|
||||
|
||||
- **产品好消息:** Agent 只生成 Marqdo → **Wasm 主沙盒设计成立**,不必默认扛通用 shell Agent 的复杂度。
|
||||
- **好沙盒的定义:** 不只跑内核,还要 **`lib/*` 可用、`ext/*` 在能力表内可用或显式不可用**;再加 **CoW + commit** 保护仓库真相。
|
||||
- **仍要改掉的:** 符号链接当暂存/隔离;默认开放 foreign/dlopen;「空 main 能跑」就算完工。
|
||||
- **降级为非默认的:** bwrap/microVM — 留给 escape / hosted,而不是 Marqdo-only 主路径。
|
||||
|
||||
不急着实现。下一步若继续收敛,再开 `doc/design/ext-ai-sandbox.md` 把 **能力矩阵 + 库完备金样清单** 锁死即可;**仍不要改 `doc/next/*`**。
|
||||
@@ -0,0 +1,290 @@
|
||||
# 外联内核 · 文档会话 · 决策记录
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Decided(由用户授权代为拍板)** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 范围 | 外联库(`lib/foreign`)· 外联内核 · 文档会话 · view notebook 交互 |
|
||||
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [notebook-session.md](../roadmap/notebook-session.md) |
|
||||
| 核心表面 Δ | **无**——不新增 Markdown 标记;只使用既有 `#` / `##` / 表格 / 反引号 |
|
||||
|
||||
> 本文件记录「为什么这样设计」。实现细节分别落在设计文档与路线图中;本文件不重复 API 表。
|
||||
|
||||
---
|
||||
|
||||
## 0. 背景与授权
|
||||
|
||||
用户的核心诉求:
|
||||
|
||||
1. Marqdo 的本质是 **代码即文档、文档即知识库**;`.mq.md` 天生兼容 Markdown / OKF 知识库。
|
||||
2. 外联库的初衷是**对标 Jupyter**:让文档与代码并行有用;但 Jupyter 有 Git 难跟踪、隐藏状态、execution_count 噪声等问题,Marqdo 要解决并超越。
|
||||
3. `view` 模式天然适合这种交互(已有执行按钮、结构视图、writeback、trace)。
|
||||
4. 之前外联库功能太单一;接下来必须支持:
|
||||
- 多个代码块共享外联状态;
|
||||
- 单步执行;
|
||||
- 切换哪些外联内核共享状态;
|
||||
- Marqdo 的状态/变量被外联使用;
|
||||
- 外联的状态/变量被 Marqdo 使用。
|
||||
5. 用户要求:**安全第一、效果最好、功能最强悍、不降级**;充分测试;每份讨论落成详细文档;文档提交并推送后再开发。
|
||||
6. 用户强调:**设计语法不要用代码思维**,语法要天然可读。
|
||||
|
||||
本文档 = 对该授权的决策记录。后续实现若与本文冲突,先改本文并说明理由。
|
||||
|
||||
---
|
||||
|
||||
## 1. 关键结论
|
||||
|
||||
### 结论 A:外联库不是“跑 Python 的函数”,而是多语言内核运行时
|
||||
|
||||
`lib/foreign` 的定位升级为:
|
||||
|
||||
> **文档运行时与外部语言运行时之间的内核/会话层**:启动内核、执行代码单元、持久化状态、双向类型桥、生命周期与安全。
|
||||
|
||||
它不等同于 `subtask`(一次性并发任务),也不等同于 `writeback`(输出持久化)。
|
||||
|
||||
### 结论 B:Jupyter 级体验需要两层,不是一层
|
||||
|
||||
| 层 | 名称 | 责任 |
|
||||
|---|---|---|
|
||||
| **F** | Foreign Kernel Runtime | 内核进程、语言发现/注册、JSON 桥、会话、安全、记录 |
|
||||
| **D** | Document Session | 文档会话、cell index、kernel 分配、单步、状态面板、执行日志、view 交互 |
|
||||
|
||||
上一版 `foreign-v2` 只覆盖 F。共享状态 / 单步 / 切换内核属于 D。两层分开设计、分开验收。
|
||||
|
||||
### 结论 C:Hybrid 执行模型
|
||||
|
||||
- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。
|
||||
- **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。
|
||||
|
||||
理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。
|
||||
|
||||
### 结论 D:命名内核;同内核共享,跨内核/跨语言显式传值
|
||||
|
||||
- 一个文档可以有多个命名内核:`py:分析`、`py:绘图`、`js:前端`。
|
||||
- 同一内核的 cell 共享全局状态。
|
||||
- 不同内核(即使同语言)默认隔离。
|
||||
- 不同语言不共享进程内存;只能通过 JSON / 文件 / DB 显式交换。
|
||||
- 默认每个文档、每种语言一个 `default` 内核;命名内核按需开启。
|
||||
- 跨文档默认隔离;全局内核以后再做。
|
||||
|
||||
### 结论 E:三种单步,分阶段实现
|
||||
|
||||
| 单步 | 含义 | 版本 |
|
||||
|---|---|---|
|
||||
| **Cell step** | 执行下一个代码单元,状态保留 | v2 必做 |
|
||||
| **Marqdo statement step** | 逐条执行 Marqdo 语句,查看变量 | v2 复用现有 debugger |
|
||||
| **Foreign line step** | 进入 Python/Node 逐行 | v2 不做;后续接 DAP/pdb/debugpy |
|
||||
|
||||
- 外联 cell 在 statement step 中是原子操作。
|
||||
- “Step into foreign” 是独立项目,不能混入首版。
|
||||
|
||||
### 结论 F:显式状态桥优先,不做隐式自动镜像
|
||||
|
||||
- 默认通过 `session_set` / `session_get` / `call input` / `call result` 交换,JSON 拷贝。
|
||||
- 不默认把 Marqdo 变量自动注入 Python,也不默认把 Python 变量自动写回 Marqdo。
|
||||
- 原因:命名冲突、Secret 泄漏、类型丢失、隐式状态、不可复现、大对象拷贝。
|
||||
- 后续可选 `mirror=True`:只同步 `mq_` 前缀、白名单类型、按值拷贝,且默认关闭。
|
||||
|
||||
### 结论 G:不新增围栏元数据;用文档原生的“内核表 / 会话表”
|
||||
|
||||
- 拒绝 ` ```python kernel=分析 `、`name=`、YAML kernel 配置、魔法注释。
|
||||
- 使用既有绑定表 + GFM 表格(放在 `# main` 体内,与 cell 同作用域):
|
||||
- `内核表` / `kernels`
|
||||
- `会话表` / `session`
|
||||
- 表格是**声明**,不是自动执行;只有 Run / Step 触发。
|
||||
- 解析器不变,核心表面零增长;view/session 读取这两个约定绑定。
|
||||
|
||||
理由:`kernel=` 是 IDE 配置思维,破坏“代码即文档”;绑定表是文档目录/执行计划,人可读、机器可解析,且不把文档拆成多个对象作用域。
|
||||
|
||||
### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md`
|
||||
|
||||
- View cells 的输出默认只在 view 中显示,不修改文档。
|
||||
- 需要持久化时显式 writeback(沿用 `<!-- marqdo-out … -->`),可 Git 跟踪、可忽略。
|
||||
- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。
|
||||
- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。
|
||||
|
||||
### 结论 I:首批会话语言 Python + Node
|
||||
|
||||
- Python:Jupyter 的主场景,优先支持。
|
||||
- Node:v1 已有基础,且当前开发环境可用。
|
||||
- 15 个语言预设继续用于**一次性执行**;R / Julia / Ruby 等的持久会话通过自定义 bootstrap 逐步加入,不阻塞首版。
|
||||
|
||||
### 结论 J:v2 不做“外联回调 Marqdo 函数”
|
||||
|
||||
- 状态/值双向:✅
|
||||
- Marqdo 代码作为源码文本传给外联:✅(外联按自己的语言执行)
|
||||
- 外联代码调用 Marqdo `##` 函数:❌ v2;后续做 callback RPC(控制通道 + 重入 + 死锁处理)。
|
||||
- 原因:重入解释器、线程安全、死锁、安全面都远超首版范围;先把数据/状态桥做稳。
|
||||
|
||||
### 结论 K:安全与测试是一等公民
|
||||
|
||||
- 所有 spawn / probe / session 入口检查 `allow_exec`。
|
||||
- 进程组超时清理;有界 IO;stdin 写线程;输出上限;并发上限。
|
||||
- 每文档生命周期,关闭即 kill;跨文档不共享。
|
||||
- 测试:node + bash 为最小环境主路径;python 条件覆盖;单元测试覆盖切分/模板/JSON;金样例覆盖记录/超时/会话/并行/状态桥。
|
||||
|
||||
---
|
||||
|
||||
## 2. 逐问逐答(保留原始讨论颗粒度)
|
||||
|
||||
### Q1:外联库是做什么的?
|
||||
|
||||
**答**:它是文档的多语言执行总线,负责:
|
||||
|
||||
1. 内核生命周期(启动/重启/中断/关闭/切换);
|
||||
2. cell 执行(源码 → kernel → stdout/stderr/result);
|
||||
3. 状态持久化(同一 kernel 的 cell 共享命名空间);
|
||||
4. 类型桥(Marqdo Value ↔ JSON ↔ 语言对象);
|
||||
5. 环境发现与配置(probe/register/venv/config);
|
||||
6. 记录与安全(耗时、退出码、截断、cap、清理)。
|
||||
|
||||
它不负责:文档语法(Language)、UI 布局(Document)、知识目录(Catalog)。这些由相邻层提供。
|
||||
|
||||
### Q2:是否支持外联库共享状态?
|
||||
|
||||
**答**:支持,但严格分层:
|
||||
|
||||
- 同一 kernel:共享全局变量。
|
||||
- 同一语言不同 kernel:隔离。
|
||||
- 不同语言:不共享内存,只能显式传值。
|
||||
- Marqdo ↔ kernel:显式桥。
|
||||
- 跨文档:默认隔离。
|
||||
|
||||
### Q3:能否单步执行?
|
||||
|
||||
**答**:能,但要定义清楚:
|
||||
|
||||
- cell step:v2 做。
|
||||
- Marqdo statement step:现有 debugger 已有,v2 接入 view。
|
||||
- foreign line step:v2 不做;后续 DAP。
|
||||
|
||||
### Q4:能否切换哪几个外联库共享状态?
|
||||
|
||||
**答**:能,用命名内核:
|
||||
|
||||
- `py:分析` 下所有 cell 共享;
|
||||
- `py:绘图` 隔离;
|
||||
- 每个 cell 有 kernel 归属;
|
||||
- 切换归属不迁移状态,需要重跑;
|
||||
- 跨语言用显式桥。
|
||||
|
||||
### Q5:Marqdo 的代码/状态能否被外联使用?外联的状态/变量能否被 Marqdo 使用?
|
||||
|
||||
**答**:
|
||||
|
||||
- Marqdo 值 → 外联:`session_set` / `call input` / `session_eval input`;JSON 拷贝。
|
||||
- 外联值 → Marqdo:`session_get` / `call` 返回值;赋值。
|
||||
- Marqdo 代码 → 外联:作为源码文本传递;外联按自己的语言执行,不是 Marqdo 语义。
|
||||
- 外联代码 → Marqdo 函数:v2 不做,后续 callback RPC。
|
||||
- 自动镜像:v2 不做,后续可选。
|
||||
|
||||
### Q6:如何超越 Jupyter?
|
||||
|
||||
**答**:不是“功能更多”,而是把 Jupyter 的隐藏面变成显式面:
|
||||
|
||||
| Jupyter | Marqdo |
|
||||
|---|---|
|
||||
| `.ipynb` JSON 混入输出/execution_count | `.mq.md` 源码干净;输出可选 writeback |
|
||||
| 隐藏 kernel 状态 | 内核 + 文档会话 + 状态面板 + journal |
|
||||
| 一个 notebook 一个 kernel | 命名内核 + 每 cell 归属 + 显式桥 |
|
||||
| 只有 cell step | cell step + statement step |
|
||||
| 手动 Run All | restart & run all + dirty/stale + replay |
|
||||
| 无知识目录 | OKF / catalog;cell 是可发现知识单元 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 被拒绝的方案
|
||||
|
||||
| 方案 | 为什么拒绝 |
|
||||
|---|---|
|
||||
| 围栏元数据 ` ```python kernel=分析 ` | Language 层变更;需 ADR;把文档语法变成 IDE 配置;破坏可读性 |
|
||||
| YAML `kernels:` 配置 | 代码思维;与“文档即知识”冲突;表格已能表达 |
|
||||
| 魔法 HTML 注释 `<!-- kernel: 分析 -->` | 不可见、易漂移、读者不可见;违背可读性 |
|
||||
| 自然语言 prose 解析(“把 xs 送给分析内核”) | 非确定性;误触发;违背“叙述默认安全” |
|
||||
| 隐式自动镜像变量 | 命名冲突、Secret 泄漏、类型丢失、不可复现 |
|
||||
| 一个文档一个 kernel | 无法做多语言/隔离实验,正是 Jupyter 的局限 |
|
||||
| 把状态/输出写进 `.mq.md` | Git 噪声;正是要解决的 Jupyter 问题 |
|
||||
| cell 自动执行 | 违背“未标记即叙述/未调用即数据”;破坏安全默认 |
|
||||
| v2 做 foreign→Marqdo callback | 重入/死锁/安全复杂;应先稳定数据桥 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 已锁定的实现边界
|
||||
|
||||
### v2 必做
|
||||
|
||||
- F0 安全执行内核 + `invoke` 记录 + `exec` 门禁 + 有界 IO + 进程组超时。
|
||||
- F1 语言注册/发现:15 预设、`probe`、`register`、`unset`、配置、venv。
|
||||
- F2 JSON 桥:`call` / `run_many` / `output` / `result`。
|
||||
- F3 持久内核:Python / Node `session_open/eval/close/list`。
|
||||
- F3.5 状态桥:`session_set/get/names`。
|
||||
- D1 文档会话服务端:cell index、kernel registry、journal、open/close。
|
||||
- D2 view notebook:内核选择、Run/Step/Run All/Restart、状态面板、dirty/stale。
|
||||
- D3 Marqdo statement step 接入 view。
|
||||
- D4 语法:`内核表` / `会话表` 解析与校验。
|
||||
- D5 测试、文档、catalog、CHANGELOG。
|
||||
|
||||
### v2 不做(明确记录,避免“降级”误解)
|
||||
|
||||
- Foreign line-level step(接 DAP 是后续项目)。
|
||||
- Foreign → Marqdo 函数 callback。
|
||||
- 跨语言共享对象引用 / 共享内存。
|
||||
- 全进程快照(只做变量级 JSON 快照)。
|
||||
- 跨文档全局内核。
|
||||
- 自动安装依赖。
|
||||
- 浏览器 wasm 外联。
|
||||
|
||||
这些不是“砍掉”,而是**独立阶段**;v2 先把内核/会话/桥做稳。
|
||||
|
||||
---
|
||||
|
||||
## 5. 风险与对策
|
||||
|
||||
| 风险 | 对策 |
|
||||
|---|---|
|
||||
| 会话协议脆弱(原生 fd 输出、缓冲) | bootstrap 用原始 stdout;Python `-u`;Node 保存原始 write;超时 kill;文档标注限制 |
|
||||
| 状态桥隐式化导致不可复现 | 默认显式;`mirror` 后续且默认关 |
|
||||
| 多内核进程泄漏 | 每文档生命周期;Drop kill;进程组;session_close;测试 |
|
||||
| 大对象 JSON 拷贝慢 | v2 明确拷贝语义;后续 Arrow/Parquet/文件句柄 |
|
||||
| `内核表` / `会话表` 名称冲突 | 文档声明为保留绑定名;后续可用 frontmatter 指针重命名 |
|
||||
| 表格行/单元不一致 | 明确诊断:未声明内核、重复单元、语言不匹配、未入会话 |
|
||||
| 交互执行顺序混乱 | journal + dirty/stale + Run All canonical + 执行序号 |
|
||||
| 安全(Secret/环境) | Secret 不进 JSON;env 显式交付;状态面板打码;exec cap |
|
||||
| 测试环境无 Python | node/bash 主路径;python 条件测试;协议单测 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 术语表(统一中英文)
|
||||
|
||||
| 中文 | English | 含义 |
|
||||
|---|---|---|
|
||||
| 外联内核 | foreign kernel | 外部语言进程 |
|
||||
| 外联会话 | foreign session | 内核实例 + 命名空间 |
|
||||
| 文档会话 | document session | Marqdo 状态 + 内核注册表 + journal |
|
||||
| 代码单元 | cell | 绑定名的代码围栏 |
|
||||
| 内核归属 | kernel assignment | cell → kernel |
|
||||
| 状态桥 | state bridge | Marqdo 值 ↔ 内核变量 |
|
||||
| 执行日志 | execution journal | 执行顺序/耗时/结果/hash |
|
||||
| 新鲜 | clean | 源码未变且已成功执行 |
|
||||
| 过期 | dirty | 源码变了,结果可能过期 |
|
||||
| 失效 | stale | 上游依赖变了,需要重跑 |
|
||||
| 规范执行 | canonical run | 重启后按会话表顺序 Run All |
|
||||
|
||||
---
|
||||
|
||||
## 7. 决策时间线
|
||||
|
||||
1. 用户提出外联库对标 Jupyter、共享状态、单步、切换、双向使用。
|
||||
2. Agent 阅读 `src/host/foreign.rs`、`src/view`、`src/debug`、`src/host/subtask.rs`、`lib/foreign`、设计文档。
|
||||
3. Agent 回答:需要 F + D 两层;单步分三种;共享分三层;显式桥。
|
||||
4. 用户授权 Agent 拍板:安全、最强、不降级、充分测试、文档先行、提交推送后开发。
|
||||
5. Agent 锁定本文件 §1 的 A–K 结论,进入文档编写与实现。
|
||||
|
||||
---
|
||||
|
||||
## 8. 后续变更流程
|
||||
|
||||
- 任何与本文冲突的实现,先改本文并写明「变更理由 / 影响 / 迁移」。
|
||||
- 新增核心语法(任何新标记)必须走 `doc/adr/` + `core-surface.md`;本文所有语法均为既有标记的组合。
|
||||
- 新增会话语言、跨语言数据平面、callback RPC,各自开独立设计文档,不塞进本文件。
|
||||
@@ -0,0 +1,489 @@
|
||||
# 缺陷实录:qdagent 重构期间发现的 Marqdo 运行时问题
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Open**(D1 待决策 · D2/D3 待修复 · D4–D6 已记录) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 报告者 | qdagent 重构(`/workspace/qdagent`) |
|
||||
| 运行时 | `marqdo 1.5.2`(本机自建 release,zig cc / glibc 2.36)· Ext pack 1.5.2 |
|
||||
| 来源 | `execution/docgate.mq.md` 文档门禁开发 · `agent/qdagent.mq.md` 输出契约收紧 |
|
||||
| 关联 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) · [ext-agent.md](../design/ext-agent.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 摘要
|
||||
|
||||
qdagent 重构把「智能体输出与沉淀笔记必须是可运行 `.mq.md`」设为硬契约,并为此实现了
|
||||
机械门禁(提取 → 结构检查 → 沙箱试跑)。该过程把 Marqdo 的一批**行为与文档不一致**、
|
||||
**诊断信息不可用**、**静默降级**问题暴露出来。逐条如下。
|
||||
|
||||
| ID | 主题 | 严重度 | 状态 |
|
||||
|----|------|--------|------|
|
||||
| D1 | `sandbox.profile` 仅回显,不改变实际能力 | **高** | Open(安全语义) |
|
||||
| D2 | `CALL:`/`调用:` 全角冒号无法解析,但提示文案推荐它 | **高** | Open(协议契约) |
|
||||
| D3 | 行首数字 / `+` 使叙述行被当语句,中文文档解析失败 | 中 | Open(可用性) |
|
||||
| D4 | `sandbox.run source=` 的报错丢失文件上下文 | 中 | Open(诊断) |
|
||||
| D5 | 成员式取元 `[key](map)` 在键缺失时硬崩 | 中 | Open(健壮性) |
|
||||
| D6 | 未绑定 GFM 表不可迭代,但报错不指向根因 | 低 | Open(诊断) |
|
||||
| D7 | 沙箱内 `subtask spawn path=` 静默不可用(设计如此,需文档明示) | 低 | Documented |
|
||||
| D8 | 函数名含空格:定义成功、调用必崩 | **高** | Open(不对称) |
|
||||
| D9 | 未闭合引号静默吞行,退出码 0 | **高** | Open(静默) |
|
||||
| D10 | `table.put` 非原地修改,累积状态静默失效 | 中 | Open(文档) |
|
||||
| D11 | 函数可见环境随运行面不同(CLI 无 metadata,Web 有 + 共享 entry_bindings) | **高** | Open(行为分裂) |
|
||||
|
||||
---
|
||||
|
||||
## D1 — `sandbox.profile` 仅回显,不改变实际能力
|
||||
|
||||
### 现象
|
||||
|
||||
`profile="readonly"` 打开沙箱后,`sandbox.inspect` 返回的能力仍是 default 行:
|
||||
|
||||
```json
|
||||
{"caps_default":{"exec":false,"fs_write":true,"net":false,"plugin":false},
|
||||
"profile":{"exec":"false","fs_write":"true","name":"default","net":"false","plugin":"false"}}
|
||||
```
|
||||
|
||||
即 `fs_write` 仍为 `true`,`profile.name` 回显为 `default` 而非 `readonly`。
|
||||
沙箱内的写操作(CoW upper)照常可用。
|
||||
|
||||
### 根因
|
||||
|
||||
- `ext/ai/sandbox.mq.md` 的 `## profile` 是一张**文档用**的能力表,`open root= profile=`
|
||||
把 `profile` 透传但原生层不接收(`plugins/agent/src/sandbox.rs` 只转 `root`)。
|
||||
- 原生 `sandbox_run` 的 `RunOptions` 中四项能力**硬编码**:
|
||||
|
||||
```rust
|
||||
// src/host/sandbox_fs.rs
|
||||
allow_fs_write: true,
|
||||
allow_exec: false,
|
||||
allow_net: false,
|
||||
allow_plugin: false,
|
||||
```
|
||||
|
||||
### 影响
|
||||
|
||||
调用方看到 `profile: readonly` 会合理地认为「沙箱内不能写」,从而把
|
||||
「用户数据落在 CoW upper 也不会污染宿主」当成安全保证;
|
||||
但 `readonly` 与 `default` 实际等价,安全语义**静默失效**。
|
||||
qcagent 的门禁依赖「失败绝不落盘」,一旦有人把门禁写成「先写进沙箱再看 profile」,
|
||||
就会得到错误结论。
|
||||
|
||||
### 建议
|
||||
|
||||
二选一,但必须明确:
|
||||
|
||||
1. **实现**:`RunOptions` 接受 profile,`readonly` 置 `allow_fs_write=false`;
|
||||
`sandbox.write` 在 readonly 下报 `fs_write denied (profile=readonly)`。
|
||||
2. **降级为文档事实并改名**:把 `## profile` 标注为「仅回显 · 不执行」,
|
||||
并从 `open root= profile=` 的公开签名里移除该参数,避免误用。
|
||||
|
||||
倾向方案 1:`readonly` 的价值正是「验证型试跑不产生任何 CoW upper」,
|
||||
这与「门禁只读校验」的语义完全吻合。
|
||||
|
||||
---
|
||||
|
||||
## D2 — 全角冒号 `调用:` 无法解析,而提示文案推荐它
|
||||
|
||||
### 现象
|
||||
|
||||
`ext/ai/agent.mq.md` 的 `## extract_tool_name` 用半角 `:` 切分:
|
||||
|
||||
```marqdo
|
||||
**parts = > split value=`t` sep=":"**
|
||||
```
|
||||
|
||||
因此只有 `CALL:x` / `调用:x`(半角)能被识别。
|
||||
但同一文件给模型的提示文案写的是全角:
|
||||
|
||||
```
|
||||
When calling an allowed tool, reply with exactly one line: CALL:<name>
|
||||
(Chinese ok: 调用:<name>)
|
||||
```
|
||||
|
||||
模型按提示输出 `调用:tool_find`(全角)时,`split sep=":"` 不切分,
|
||||
`head` 变成整行 `调用:tool_find`,匹配失败 → **静默忽略该 CALL**,
|
||||
模型以为调用已发出,实际没有工具结果,最终答案缺少证据。
|
||||
|
||||
### 影响
|
||||
|
||||
这是**协议层**的静默失败:不报错、不提示,只表现为「工具没被调用」。
|
||||
对中文模型(尤其国内模型)全角标点是默认习惯,命中率不低。
|
||||
|
||||
### 建议
|
||||
|
||||
解析器同时接受全角与半角:
|
||||
|
||||
```marqdo
|
||||
**t2 = > replace text=`t` old=":" new=":" count=None**
|
||||
**parts = > split value=`t2` sep=":"**
|
||||
```
|
||||
|
||||
同类问题应在 `READ:` / `DECISION:` / `SUMMARY:` / `SLUG:` 一并检查——
|
||||
调研显示这些解析器已经支持全半角,唯独 `extract_tool_name` 与 `extract_call_args` 不一致
|
||||
(`READ` §900-942 支持全角,`CALL` §130-159 只支持半角)。
|
||||
|
||||
---
|
||||
|
||||
## D3 — 行首数字 / `+` 导致中文文档解析失败
|
||||
|
||||
### 现象
|
||||
|
||||
按 v0.3 语法,非标记行是叙述(注释)。但某些行首字符会让该行被当成语句。
|
||||
|
||||
**实测修正(1.5.2,逐条跑过)**——不是所有标记都出问题:
|
||||
|
||||
| 行首 | 叙述区实测 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `9 号是数字。` | ❌ `unrecognized statement` | 数字字面量是真语句 |
|
||||
| `42` / `2026 年发布。` | ❌ `unrecognized statement` | 同上 |
|
||||
| `+ 加号` | ❌ `unrecognized statement` | `+` 是前导符语法 |
|
||||
| `- 列表项` | ✅ 安全 | 不构成有效 foreach → 跳过 |
|
||||
| `> 引用` | ✅ 安全 | 无对应函数时不当调用 |
|
||||
| `\| a \| b \|` | ✅ 安全 | 未绑定表不算语句 |
|
||||
| `[{"a":1}]` | ✅ 安全 | 无归属的链接索引 → 跳过 |
|
||||
|
||||
判据是**该行能否被解析成一条完整语句**:能则执行,不能则当叙述跳过。
|
||||
所以在函数体内上下文成立时,`- [`x`](`xs`)` 仍是真循环。
|
||||
|
||||
实测(qdagent 门禁):
|
||||
|
||||
```
|
||||
gate.门禁 text="...\n# 结论\n\n9 号是数字。\n\n# main\n..."
|
||||
→ {"ok":false,"stage":"structure",
|
||||
"violations":[{"line":6,"rule":"narration_marker","text":"9 号是数字。"}]}
|
||||
```
|
||||
|
||||
### 影响
|
||||
|
||||
对**人类作者**这是设计取舍(执行标记优先于叙述,符合「标记即语法」)。
|
||||
但对**LLM 生成的中文文档**是高频陷阱:中文写「2026 年」「42 条」「3 个要点」
|
||||
都是默认表达习惯,一旦出现在叙述区,整篇文档解析失败。
|
||||
|
||||
这是「文档即可运行」与「文档可读」之间的真实张力。
|
||||
qdagent 的应对是**在提示词里逐条禁止**并**门禁机械校验**(见
|
||||
`doc/design/09-document-contract-and-docgate.md`),但根源在语言层面。
|
||||
|
||||
补充(实测发现的更隐蔽问题):**未闭合引号会静默吞行**,不报错,
|
||||
只在别处表现为 `undefined variable`。见使用手册
|
||||
[`tutorial/15-常见陷阱.md`](../tutorial/15-常见陷阱.md) §1.4。
|
||||
|
||||
### 建议
|
||||
|
||||
不改语义(执行标记优先是 v0.3 的基石),但增强可诊断性:
|
||||
|
||||
1. `unrecognized statement` 报错附一句提示:
|
||||
「若此行为叙述,请以文字开头,或用行内代码/围栏包裹」。
|
||||
2. `marqdo check` 增加 `narration-marker` 规则,一次性列出全部风险行。
|
||||
3. 文档(`markdown-mapping-v0.3.md`)显著位置增加「中文叙述常见陷阱」小节。
|
||||
|
||||
---
|
||||
|
||||
## D4 — `sandbox.run source=` 的报错丢失文件上下文
|
||||
|
||||
### 现象
|
||||
|
||||
```marqdo
|
||||
**r = > sb.run id=`id` source="> print text=hello"**
|
||||
→ {"error":"<memory>: 1:1: expected heading (`#` object or `##` function), got: > print text=hello",
|
||||
"ok":false,"stdout":"","value":null}
|
||||
```
|
||||
|
||||
报错用 `<memory>` 作文件名,且**没有指出**「源文本必须含 `# main`」。
|
||||
对 `path=` 运行报错带真实路径,对 `source=` 只有 `<memory>`,两者诊断质量不一致。
|
||||
|
||||
### 影响
|
||||
|
||||
门禁类工具需要用 `source=` 直接跑生成的文本(避免先写盘)——
|
||||
这正是 qdagent 的用法。诊断不可用时会显著拉长修复轮次。
|
||||
|
||||
### 建议
|
||||
|
||||
`source=` 运行使用伪文件名 `sandbox-source.mq.md`(或调用方可传 `name=`),
|
||||
并在缺少 `# main` 时返回明确错误:
|
||||
`no # main object in source; add "# main" before statements`。
|
||||
|
||||
---
|
||||
|
||||
## D5 — 成员式取元 `[key](map)` 在键缺失时硬崩
|
||||
|
||||
### 现象
|
||||
|
||||
```marqdo
|
||||
**err = [error](r)** # r 来自 sandbox.run
|
||||
→ error: missing map key 'error'
|
||||
```
|
||||
|
||||
`sandbox.run` **成功**时返回 `{ok, stdout, value}`,**没有** `error` 键;
|
||||
失败时才有 `error`。于是「成功分支里读 error」会直接崩掉整个文档。
|
||||
|
||||
### 影响
|
||||
|
||||
同一函数的返回形状随成败变化(成功缺 `error`、失败缺 `value` 之外的键),
|
||||
按「防御式读取」写的代码极易在成功路径崩溃——而成功路径往往测试覆盖更少。
|
||||
|
||||
### 建议
|
||||
|
||||
二选一:
|
||||
|
||||
1. **统一形状**:`sandbox.run` 始终返回 `{ok, value, stdout, error}`(成功时 `error: ""`),
|
||||
与 `llm` 的软失败风格一致。
|
||||
2. 或在 `markdown-mapping-v0.3.md` 明确 `[key](map)` 是**断言式**取值(缺键即错),
|
||||
并提供 `get`/`has` 作为防御式写法(已有 `table.get` / `table.has`)。
|
||||
|
||||
qdagent 的修法是改用 `table.get map= key=` 取可选键,但这是每个调用方都要踩一次的坑。
|
||||
|
||||
---
|
||||
|
||||
## D6 — 未绑定 GFM 表不可迭代,但报错不指向根因
|
||||
|
||||
### 现象
|
||||
|
||||
```marqdo
|
||||
`pres` = # 注意:没有 name =,未绑定
|
||||
|
||||
| 前缀 |
|
||||
|------|
|
||||
| "9" |
|
||||
|
||||
- [p](pres) # 迭代未绑定表
|
||||
→ error: foreach needs a list or map
|
||||
```
|
||||
|
||||
未绑定表不会进入绑定图,因此不可迭代;但报错只说「需要一个 list 或 map」,
|
||||
不提示「这张表没有被绑定到变量」。
|
||||
|
||||
### 建议
|
||||
|
||||
报错附上下文:「`foreach` 目标未绑定;请写作 `` `name` = `` 绑定 GFM 表」。
|
||||
|
||||
---
|
||||
|
||||
## D7 — 沙箱内 `subtask spawn path=` 静默不可用(设计如此)
|
||||
|
||||
`src/host/subtask.rs` 在沙箱内拒绝 `path=` / `code=` / `lang=` 的 spawn
|
||||
(`subtask spawn disabled (exec capability off)`),只保留 `fn=` 进程内调用。
|
||||
这是**能力硬顶的合理结果**,但:
|
||||
|
||||
- 该限制不出现在 `ext/ai/sandbox.mq.md` 的 `## profile` 说明里;
|
||||
- 工具框架(`run_tool` → `subtask.spawn fn=`)恰好只用 `fn=`,因此**表面上一切正常**,
|
||||
直到有人写了基于 `path=` 的工具才发现。
|
||||
|
||||
建议在 `ext/ai/sandbox.mq.md` 顶部「能力硬顶」清单中补一条,与 exec/net/plugin 并列。
|
||||
|
||||
---
|
||||
|
||||
## D8 — 函数名含空格:定义成功,调用必崩
|
||||
|
||||
### 现象
|
||||
|
||||
```markdown
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 加一 号 n=1**
|
||||
```
|
||||
|
||||
```
|
||||
error: t8.mq.md:13:1: undefined variable `号`
|
||||
```
|
||||
|
||||
英文同理:`## my func` 调用时报 `undefined variable func`。
|
||||
|
||||
### 根因
|
||||
|
||||
定义侧(`##` 标题)接受空格;调用侧按空格切词,
|
||||
第一个词当函数名,其余当位置参数或**变量插值**。两侧不对称。
|
||||
|
||||
### 影响
|
||||
|
||||
这是**静默不对称**:`marqdo check` 通过(`无契约问题`),
|
||||
只有真跑才崩,且报错指向「未定义变量」而非「函数名非法」,
|
||||
排查方向被引偏。中文标识符天然爱加空格(`断言无 main`、`加一 号`),
|
||||
LLM 生成代码时尤其容易命中。
|
||||
|
||||
### 建议
|
||||
|
||||
二选一:
|
||||
|
||||
1. **定义侧拒绝空格**——`##` 名字含空格时报
|
||||
`function name may not contain spaces`,定义期即失败。
|
||||
2. **调用侧贪婪匹配**——按已知函数名最长前缀匹配,允许空格名(改动大,不推荐)。
|
||||
|
||||
倾向方案 1:与「标识符不含空格」的通行约定一致,成本最低。
|
||||
|
||||
---
|
||||
|
||||
## D9 — 未闭合双引号静默吞行,无任何报错
|
||||
|
||||
### 现象
|
||||
|
||||
```markdown
|
||||
**s = "abc
|
||||
> print text=hi
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `hi`,退出码 0,**没有报错**,`s` 那一行凭空消失。
|
||||
|
||||
### 根因
|
||||
|
||||
未闭合引号使该行无法解析为语句,于是被当作**叙述**跳过。
|
||||
叙述与「解析失败的语句」没有区分。
|
||||
|
||||
### 影响
|
||||
|
||||
- 变量「莫名未定义」,后续在别处报 `undefined variable`,根因被掩盖。
|
||||
- 生成的文档会少一节内容却不报错——对「文档即程序」而言这是**最危险**的一类:
|
||||
文档看起来完整、能跑、退出码 0,但少了一段。
|
||||
|
||||
### 建议
|
||||
|
||||
未闭合引号应在解析期报错:
|
||||
`unterminated string literal at line N`。
|
||||
若担心破坏「叙述自由」,至少让 `marqdo check` 检出
|
||||
「以 `**` 开头但不以 `**` 结尾」的行并 warn。
|
||||
|
||||
---
|
||||
|
||||
## D10 — 取元 `[key](map)` 与非原地 `table.put` 的认知负担
|
||||
|
||||
已在 [D5](#d5--成员式取元-keymap-在键缺失时硬崩) 记录取元硬崩。
|
||||
补充**协同陷阱**:`table.put` **不原地修改**,返回新 map:
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"n":0}**
|
||||
**r = > table.put in=`m` at="n" value=1**
|
||||
```
|
||||
|
||||
`m` 仍是 `{"n":0}`,`r` 才是 `{"n":1}`。
|
||||
于是「靠 `> table.put in=`state` ...` 累积计数」**不生效且无报错**——
|
||||
计数器永远是 0,自检看起来「全部通过」。
|
||||
|
||||
建议:在 `lib/table` 的 `put` 文档里用一句话强调「返回新表」,
|
||||
并考虑提供 `put!` 或 `set!` 的就地版本以匹配直觉。
|
||||
|
||||
---
|
||||
|
||||
## D11 — 函数可见环境随运行面不同(CLI vs Web)
|
||||
|
||||
### 现象
|
||||
|
||||
同一份文档,`# main` 与普通函数看到的变量环境不一致:
|
||||
|
||||
| 路径 | 函数能看到的变量 | 源码 |
|
||||
|------|-----------------|------|
|
||||
| `# main`(CLI) | frontmatter metadata ✅ | `src/interp.rs:473` `run(..., Env::with_metadata(module), ...)` |
|
||||
| **普通函数调用(CLI)** | **只有实参** | `eval_call` 内 `let mut call_env = Env::new();` |
|
||||
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
|
||||
|
||||
复现(1.5.2 实测):
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: m1
|
||||
税率: 0.1
|
||||
---
|
||||
|
||||
## 按税率
|
||||
+ `金额`
|
||||
|
||||
*`金额` * `税率`*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 按税率 金额=100**
|
||||
```
|
||||
|
||||
```
|
||||
error: m1.mq.md:9:1: undefined variable `税率`
|
||||
```
|
||||
|
||||
但同样在 `# main` 里直接读:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text="main里读到税率=" + `税率` # → 0.1
|
||||
```
|
||||
|
||||
**能读到。**
|
||||
|
||||
### 根因
|
||||
|
||||
- `Env::with_metadata(module)` 把 frontmatter metadata 注入 env(`src/interp.rs:62`),
|
||||
但只在三处使用:`# main` 运行(473/485)、`invoke_in_entry`(365)、以及
|
||||
入口依赖解析(411)。
|
||||
- 普通用户函数调用走 `eval_call`,用 `Env::new()` 新建空环境,只写入绑定好的实参。
|
||||
|
||||
于是「文件级常量」这个概念**只对入口可见**,函数不可见。
|
||||
|
||||
### 影响
|
||||
|
||||
1. **行为随运行面变化**:同一 `.mq.md`,在浏览器里函数能读到 frontmatter 常量、
|
||||
还能读到 `# main` 的绑定(`entry_bindings`);在 CLI 里报 `undefined variable`。
|
||||
这类差异极难排查——代码看着一样,结果不同。
|
||||
2. **阻断合法用法**:把配置写在 frontmatter、供多个函数共享,是文档化的自然写法,
|
||||
但今天在 CLI 下不可用,只能靠每个调用点重复传参。
|
||||
3. **掩盖真实能力**:读者会以为「函数能读文件级常量」(因为 Web 能),
|
||||
在 CLI 复现时才发现不能。
|
||||
|
||||
### 建议
|
||||
|
||||
二选一并写进文档:
|
||||
|
||||
1. **统一为「函数可见 metadata」**:`eval_call` 改用 `Env::with_metadata(module)`
|
||||
再写入实参(实参优先覆盖同名 metadata)。这样 frontmatter 成为**受控的只读环境**:
|
||||
写一次、文档开头可见、可序列化,且不随调用者变化。
|
||||
2. **统一为「函数不可见 metadata」**:把 `invoke_in_entry` 也改成 `Env::new()`,
|
||||
只保留 `# main` 可见,并在文档中明确「frontmatter 只供入口使用」。
|
||||
|
||||
倾向方案 1:它把已存在的机制补成一致的、静态可判定的「常量默认值」通道,
|
||||
对文档化使用场景价值明显,且不引入动态作用域的风险(见
|
||||
[ambient-parameters-evaluation.md](../design/ambient-parameters-evaluation.md) §4.3)。
|
||||
|
||||
---
|
||||
|
||||
## 附录:本次开发中确认正常的项
|
||||
|
||||
避免误报,以下行为经实测**符合文档**,不在缺陷之列:
|
||||
|
||||
| 项 | 实测 |
|
||||
|----|------|
|
||||
| 沙箱 CoW 隔离 | 宿主目录在 `commit` 前不变,`diff` 正确列出 write/remove |
|
||||
| 沙箱能力默认值 | `exec:false` / `net:false` / `plugin:false` / `fs_write:true (CoW only)` |
|
||||
| `sandbox.run` 成功形状 | `{ok:true, value, stdout}` |
|
||||
| `agent.run efi=` | EKC preflight 拦截 CREATE,返回 `{status:"error", error:"efi_create_denied"}` |
|
||||
| `agent.run sandbox=` | CREATE 阶段走 CoW trial,ok 才 commit |
|
||||
| LLM 软失败 | transport 失败返回 `status:"error"` 而非中断 VM |
|
||||
| `marqdo check` 契约检查 | 对 qdagent 全部改动文件返回「无契约问题」 |
|
||||
|
||||
---
|
||||
|
||||
## 复现清单
|
||||
|
||||
| ID | 复现 | 观察点 |
|
||||
|----|------|--------|
|
||||
| D1 | `sb.open root="." profile="readonly"` + `sb.inspect` | `profile.name` 回显 `default`,`fs_write:true` |
|
||||
| D2 | 模型输出 `调用:tool_find`(全角) | 无工具结果、无报错 |
|
||||
| D3 | 文档叙述区写 `9 号是数字。` 或 `+ 加号` | `unrecognized statement` / 门禁 `narration_marker` |
|
||||
| D4 | `sb.run id= source="> print text=x"` | `error` 以 `<memory>` 开头,未提示缺 `# main` |
|
||||
| D5 | `[error](r)`,`r` 为成功返回 | `missing map key 'error'` |
|
||||
| D6 | 未绑定 GFM 表后 `- [x](表)` | `foreach needs a list or map` |
|
||||
| D8 | `## my func` + `> my func n=1` | `undefined variable func`(check 却通过) |
|
||||
| D9 | `**s = "abc` 不闭合 | 静默吞行,退出码 0 |
|
||||
| D10 | `> table.put in=`m` at=…` 后读 `m` | 原表未变;计数永远是 0 |
|
||||
| D11 | frontmatter 写 `税率: 0.1`,函数体读 `` `税率` `` | CLI 报 `undefined variable`;`# main` 里却能读到 |
|
||||
|
||||
---
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-10-22 | 首次记录 D1–D7(qdagent 文档门禁开发期) |
|
||||
| 2026-10-22 | 补 D8–D10;D3 按逐条实测收敛(`-` / `>` / `\|` / `[` 实为安全,只数字与 `+` 报错);配套使用手册 `tutorial/15-常见陷阱.md` |
|
||||
@@ -18,6 +18,7 @@
|
||||
|----|------|------|
|
||||
| **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` |
|
||||
| **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` |
|
||||
| **Sandbox (trial)** | CoW workspace + capped `run` | `ext/ai/sandbox` · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) |
|
||||
| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 |
|
||||
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.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) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
| 后续 | 优化波次 O1–O5 见 [ext-ai-optimize.md](ext-ai-optimize.md)(沙盒证明 · Skill Lift · 路由/成本 · lint · 隔离) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Roadmap: Agent/LLM 优化波次 O1–O5
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
| Research | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| Prior | [ext-agent-optimize.md](ext-agent-optimize.md) (A0–A4 / Wave B) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
|
||||
## Principles
|
||||
|
||||
1. Executable `.mq.md` remains authority; OKF reuses; sandbox proves; LLM explores.
|
||||
2. No hidden TOOL: loop; no vector-store memory authority; no default shell Agent.
|
||||
3. Do not edit `doc/next/*`.
|
||||
|
||||
## Waves
|
||||
|
||||
| Wave | Scope | Gold / deliverable | Status |
|
||||
|------|-------|--------------------|--------|
|
||||
| **O1** | A1 opt-in `sandbox=` · A3 profile table · D1 skill · D4 example | `agent-sandbox-optin` · `examples/agent-sandbox-okf` | **done** |
|
||||
| **O2** | A2 promote proof · B1 OKF meta · B3/E1 harness Skill Lift | `agent-sandbox-promote` · harness subset | **done** |
|
||||
| **O3** | C1 step route · C2 cost · B6 EFI default | `agent-step-route` · run usage/efi | **done** |
|
||||
| **O4** | A4/D2 lint · A5 diff review report | `scripts/mq-style-lint.sh` · `sandbox.report` | **done** |
|
||||
| **O5** | B4 quarantine · C3 offline policy rewrite | `agent-sandbox-quarantine` · `optimize-standing-policy.sh` | **done** |
|
||||
|
||||
## Non-goals
|
||||
|
||||
F1–F5 · wasmtime CLI embed · default `sandbox=True` without ADR · edit `doc/next/*`
|
||||
@@ -0,0 +1,28 @@
|
||||
# Roadmap: `ext/ai/sandbox` (AI CoW trial runtime)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| Research | [ai-agent-sandbox.md](../research/ai-agent-sandbox.md) |
|
||||
|
||||
## Milestones
|
||||
|
||||
| ID | Deliverable | Done when |
|
||||
|----|-------------|-----------|
|
||||
| S0 | Design + this roadmap + research cross-links | **done** |
|
||||
| S1 | CoW open/write/read/remove/diff/commit/discard | **done** (`sandbox-cow`) |
|
||||
| S2 | `run` + default caps + core lib inside run | **done** (`sandbox-run-lib`) |
|
||||
| S3 | `inspect` + deny plugin.load | **done** (`sandbox-deny`) |
|
||||
| S4 | Polish: ai-stack + CHANGELOG | **done** |
|
||||
|
||||
## Gold samples (target)
|
||||
|
||||
- `tests/ext/sandbox-cow.mq.md`
|
||||
- `tests/ext/sandbox-run-lib.mq.md`
|
||||
- `tests/ext/sandbox-deny.mq.md`
|
||||
|
||||
## Out of scope this wave
|
||||
|
||||
wasmtime CLI embed · Wasm ABI plugins · bwrap/microVM · full web in sandbox · auto-wire agent.step · edit `doc/next/*`
|
||||
@@ -0,0 +1,226 @@
|
||||
# 外联内核 v2 路线图(F0–F4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **F0–F3.5 已落地;F4 进行中** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime |
|
||||
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [stdlib-foreign.md](../design/stdlib-foreign.md) · [notebook-session.md](notebook-session.md)(D 层路线) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> 本路线图只覆盖 **F:外联内核运行时**。共享状态 / 单步 / 切换内核的文档侧在 [notebook-session.md](notebook-session.md)(D 层)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状与目标
|
||||
|
||||
v1:`set_cmd` / `run` / `run_lang` / `langs`;临时文件 + 子进程 + stdout 文本;无状态、无结构化结果、无 exec 门禁、无有界 IO、无进程组清理。
|
||||
|
||||
v2 目标:安全、可发现、结构化、可持久、可并行,并成为 D 层文档会话的可靠底座。
|
||||
|
||||
---
|
||||
|
||||
## 1. 阶段总览
|
||||
|
||||
| 阶段 | 内容 | 估算 | 可独立发版 |
|
||||
|---|---|---|---|
|
||||
| **F0** | 执行内核与安全:Job/Execution、`exec` 门禁、有界 IO、进程组、`invoke` 记录、view 诊断 | 2–3 天 | 是 |
|
||||
| **F1** | 语言注册与发现:registry、15 预设、probe、register/unset、配置、venv | 2–3 天 | 是 |
|
||||
| **F2** | JSON 桥与并行:call/call_many、run_many、output/result | 2–3 天 | 是 |
|
||||
| **F3** | 持久内核:Python/Node session_open/eval/close/list | 3–4 天 | 是 |
|
||||
| **F3.5** | 状态桥:session_set/get/names | 1–2 天 | 是 |
|
||||
| **F4** | 打磨、文档、catalog、CHANGELOG、1.5.0 | 1–2 天 | 1.5.0 |
|
||||
|
||||
D 层(文档会话)从 F3.5 完成后开始;不要把 D 层塞进 F 层。
|
||||
|
||||
---
|
||||
|
||||
## 2. F0 — 执行内核与安全
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/host/foreign.rs` 重构:
|
||||
- `Job`:lang/source/stdin/input/env/cwd/timeout/args/output/max_output/cmd/keep。
|
||||
- `Execution`:stdout/stderr/raw bytes/exit/ms/timed_out/truncated/error。
|
||||
- `ForeignEnv`:cwd/fs_root/specs/caps 快照(供并行)。
|
||||
- `exec` 门禁:`run` / `invoke` / `run_many` / `probe` / `session_*` 统一检查。
|
||||
- 有界 IO:读线程保留前 N 字节、继续排空;`truncated`。
|
||||
- stdin 写线程;EPIPE 忽略。
|
||||
- 超时:进程组 kill(Unix `process_group(0)` + `kill(-pid)`;Windows `taskkill /T /F`)。
|
||||
- shell-like argv 切分(引号/转义)。
|
||||
- `invoke` + 稳定记录。
|
||||
- `run` / `run_lang` 增加 `env` / `cwd` / `timeout` / `args` / `max_output`。
|
||||
- view `/api/foreign-run` 返回完整记录;JS 显示 stderr / exit / ms。
|
||||
- `set_cmd` L1 补 `args`。
|
||||
|
||||
### 验收
|
||||
|
||||
- 既有 `lib_foreign_*` / `lib_subtask_foreign` 绿(python 可用时)。
|
||||
- 新增 node/bash 金样例:非 0 退出、stderr、超时、env/cwd、截断。
|
||||
- `exec=false` 拒绝。
|
||||
- `cargo test` 绿;release build;wasm check。
|
||||
|
||||
### 主要文件
|
||||
|
||||
`src/host/foreign.rs` · `src/host/mod.rs` · `src/host/subtask.rs` · `src/view/mod.rs` · `src/view/html.rs` · `src/view/debug_page.rs` · `Cargo.toml` · `tests/gold.rs` · `tests/lib/foreign-*.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. F1 — 语言注册与发现
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/foreign/registry.rs`(纯逻辑):
|
||||
- 15 预设、别名、扩展名、版本参数、会话能力。
|
||||
- 模板占位符 `{file}` / `{dir}` / `{base}` / `{inline}` / `{lang}` / `{cwd}`。
|
||||
- venv 探测、PATH 查找、shell-like 切分、配置解析。
|
||||
- `HostContext`:
|
||||
- `foreign_specs`、`foreign_config_loaded`。
|
||||
- `probe` 缓存(可选)。
|
||||
- API:`probe` / `langs` / `register` / `unset` / `load_config`。
|
||||
- 配置:`.marqdo/foreign.toml` + `MARQDO_FOREIGN_CONFIG`;优先级见设计。
|
||||
- `MARQDO_FOREIGN_<LANG>` 支持 JSON 数组与引号。
|
||||
- `subtask` 继承注册/配置。
|
||||
|
||||
### 验收
|
||||
|
||||
- `probe` 对 node / bash 给出 path + version;缺失语言 `ok=false` 不 panic。
|
||||
- 配置可把 `python` 指向 venv;模板可跑 `go run`(若本机有 go)。
|
||||
- `langs` 含预设;`unset` 回退预设。
|
||||
- 单元测试:切分、模板、别名、扩展名。
|
||||
|
||||
---
|
||||
|
||||
## 4. F2 — JSON 桥与并行
|
||||
|
||||
### 内容
|
||||
|
||||
- `call` / `call_many`;`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- `Value ↔ JSON` 复用 `host::json`;`bytes` base64。
|
||||
- `run_many` 并行引擎:`ForeignEnv` 快照、线程上限 32、结果同序、单项 panic 隔离。
|
||||
- `call_many` 全跑完再报错(清理所有子进程)。
|
||||
- 文档:Python / Node JSON 样板。
|
||||
|
||||
### 验收
|
||||
|
||||
- `call` 单列表 → map,mean 为 Num;嵌套 list/map 往返。
|
||||
- `run_many` 顺序稳定;单项失败不影响其它项。
|
||||
- 大输入(>8 KiB)走 `MARQDO_INPUT_FILE`。
|
||||
- 并发上限与超时生效。
|
||||
|
||||
---
|
||||
|
||||
## 5. F3 — 持久内核
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/host/foreign_session.rs`:
|
||||
- Python / Node bootstrap(嵌入式常量)。
|
||||
- 启动、reader/writer、严格串行、超时、崩溃、drop 清理。
|
||||
- `session_open` / `session_eval` / `session_close` / `session_list`。
|
||||
- 会话记录:与 invoke 同形 + `id` / `alive`。
|
||||
- 会话环境:cwd / env / cmd;`MARQDO_*`。
|
||||
- `HostContext` 字段(cfg exec-host)+ Drop。
|
||||
|
||||
### 验收
|
||||
|
||||
- Node:`let x=41` → `x+1` → 42;`console.log` 捕获;异常不杀会话。
|
||||
- Python:同(有 python 时)。
|
||||
- 超时 → kill + `alive=false`;close/drop 无遗留进程。
|
||||
- 会话与 `subtask` 边界:不继承。
|
||||
|
||||
---
|
||||
|
||||
## 6. F3.5 — 状态桥
|
||||
|
||||
### 内容
|
||||
|
||||
- `session_set` / `session_get` / `session_names`。
|
||||
- 值:Marqdo → JSON → kernel;kernel → JSON → Marqdo。
|
||||
- 名称校验;Secret 规则;错误可读。
|
||||
- 与 `session_eval` 同一线路,严格串行。
|
||||
- L1 文档 + 金样例。
|
||||
|
||||
### 验收
|
||||
|
||||
- Node:`session_set xs=[1,2,3]`,`session_eval sum(xs)` → 6;`session_get` 取回。
|
||||
- 复杂嵌套 map/list 往返。
|
||||
- 不存在变量 → None + 可读诊断。
|
||||
- 非 JSON 可序列化 → 错误说明。
|
||||
|
||||
---
|
||||
|
||||
## 7. F4 — 打磨与发布
|
||||
|
||||
- `history`(可选)/ `cache`(可选,默认关)。
|
||||
- view 命令记忆 / Ctrl+Enter / 错误分块。
|
||||
- `lib/foreign.mq.md` / `lib/外联.mq.md` 全量。
|
||||
- `public/stdlib/*` 示例。
|
||||
- catalog 重新生成;CHANGELOG;版本 1.5.0。
|
||||
- 性能:空跑、100 次调用、会话 vs 一次性。
|
||||
|
||||
### 验收
|
||||
|
||||
- 新函数全部有中文/英文文档与示例。
|
||||
- `marqdo catalog`、`public/` 构建通过。
|
||||
- 手工 view Run 一个 node 卡片,显示 stdout/stderr/exit/ms。
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试矩阵
|
||||
|
||||
> 当前环境:node / bash / sh / perl 可用,python3 不可用。新金样例以 node + bash 为主;python 用 `python_available()` 条件跳过。
|
||||
|
||||
| 测试 | 依赖 | 断言 |
|
||||
|---|---|---|
|
||||
| 既有 3 个 foreign 用例 | python | 兼容 |
|
||||
| `foreign-invoke` | node | 记录字段 |
|
||||
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
|
||||
| `foreign-timeout` | node | timed_out |
|
||||
| `foreign-call-json` | node | 类型往返 |
|
||||
| `foreign-call-many` / `run-many` | node | 顺序/隔离 |
|
||||
| `foreign-session` | node | 跨 eval |
|
||||
| `foreign-session-set-get` | node | 状态桥 |
|
||||
| `foreign-session-timeout` | node | alive=false |
|
||||
| `foreign-probe` | node | path/version |
|
||||
| `foreign-register` | node | 模板 |
|
||||
| `foreign-config` | node | 配置 |
|
||||
| `foreign-stdout-stderr` | bash | 成功也有 stderr |
|
||||
| `foreign-caps` | 无 | 拒绝 |
|
||||
| 单元测试 | 无 | 切分/模板/别名/JSON |
|
||||
|
||||
Windows:`python_available` / `bash_available` 守卫;进程组 `taskkill` 分支编译通过。
|
||||
|
||||
---
|
||||
|
||||
## 9. 兼容性
|
||||
|
||||
- `run` / `run_lang` / `set_cmd` / `langs` 兼容;只增可选参数。
|
||||
- `run` 成功仍返回 stdout;非 0 仍报错。
|
||||
- 大输出从“报错”改为“截断 + truncated”(更安全;CHANGELOG 写明)。
|
||||
- `langs` 扩展为预设 ∪ 注册 ∪ 配置。
|
||||
- HostFn id 末尾追加(196+)。
|
||||
- 无核心表面 Δ。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|---|---|
|
||||
| 会话协议脆弱 | 原始 stdout;`-u`;超时 kill;测试;文档限制 |
|
||||
| 并行进程过多 | 默认 4 / 上限 32;超时;输出上限 |
|
||||
| 配置优先级难记 | 设计文档固定表;`probe` 显示实际 path |
|
||||
| 模板 shell 注入 | 默认不 shell;路径引擎生成;文档警示 |
|
||||
| 大输出截断改变 v1 行为 | CHANGELOG;`truncated` 可检测 |
|
||||
| wasm 编译 | 新字段 cfg 隔离;registry 纯逻辑 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 完成定义
|
||||
|
||||
- F0–F3.5 全部验收。
|
||||
- `cargo test` 绿;release build;wasm check。
|
||||
- 文档/CHANGELOG/catalog 更新。
|
||||
- 提交并推送。
|
||||
- 进入 D 层([notebook-session.md](notebook-session.md))。
|
||||
@@ -0,0 +1,177 @@
|
||||
# 文档会话路线图(D0–D5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 已落地(首版);D4–D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / 前端) |
|
||||
| 相关 | [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-kernel.md](../design/foreign-kernel.md) · [foreign-v2.md](foreign-v2.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> F 层让“外部语言能持久运行”;D 层让“文档里的多个 cell 像 notebook 一样共享状态、单步、切换内核”。两层分开验收。
|
||||
|
||||
---
|
||||
|
||||
## 0. 依赖
|
||||
|
||||
- **F3**:Python / Node 持久内核。
|
||||
- **F3.5**:`session_set/get/names`。
|
||||
- 现有 `DebugController`(Marqdo 语句单步)。
|
||||
- 现有 `writeback` / `annot` / view 结构。
|
||||
|
||||
没有 F3/F3.5,D2 只能做一次性 Run,不是共享状态。
|
||||
|
||||
---
|
||||
|
||||
## 1. 阶段总览
|
||||
|
||||
| 阶段 | 内容 | 估算 |
|
||||
|---|---|---|
|
||||
| **D0** | 设计/语法/决策文档 | 已完成 |
|
||||
| **D1** | `src/notebook/`:cell index、表解析、session 结构、诊断 | 2–3 天 |
|
||||
| **D2** | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | 3–4 天 |
|
||||
| **D3** | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | 3–4 天 |
|
||||
| **D4** | statement step、dirty/stale、writeback | 2–3 天 |
|
||||
| **D5** | replay、持久化、并发优化、测试补全、发布 | 2–3 天 |
|
||||
|
||||
---
|
||||
|
||||
## 2. D1 — Cell index 与表解析
|
||||
|
||||
### 内容
|
||||
|
||||
- 新模块 `src/notebook/`:
|
||||
- `cell.rs`:从 AST 提取绑定名代码围栏;id/name/lang/line/source hash。
|
||||
- `syntax.rs`:读取 `内核表` / `会话表`;中英列名。
|
||||
- `session.rs`:`DocumentSession` 结构、kernel registry、value store、journal。
|
||||
- `diag.rs`:重复/未知/语言不匹配/未入会话诊断。
|
||||
- 自动模式:无表 → 文档顺序 + 默认内核。
|
||||
- 解析器不改;只遍历 `Module.functions` + `Stmt::Assign { value: Expr::Code }`。
|
||||
- 测试:单元 + `tests/notebook/*.mq.md`。
|
||||
|
||||
### 验收
|
||||
|
||||
- 两个 Python cell + 一个会话表 → cells 顺序、kernel 归属正确。
|
||||
- 无表 → 自动顺序。
|
||||
- 未知内核/未知单元/重复/语言不匹配 → 可读诊断。
|
||||
- 未绑定围栏不进入 cell index。
|
||||
|
||||
---
|
||||
|
||||
## 3. D2 — 服务端 API
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/view/notebook_api.rs`(或 `view/session_api.rs`):
|
||||
- open / close / reload
|
||||
- cell run / step / run_all
|
||||
- kernel restart / interrupt / assign
|
||||
- state list / push / pull
|
||||
- journal
|
||||
- Session 存储:`OnceLock<Mutex<HashMap<String, Arc<DocumentSession>>>>`(类似 debug sessions)。
|
||||
- 每个文档一个 session;key = 相对路径。
|
||||
- 执行线程:cell 执行不阻塞 HTTP;响应返回记录;SSE/EventBus 可选。
|
||||
- 错误统一 JSON。
|
||||
|
||||
### 验收
|
||||
|
||||
- open 返回 cells/kernels/journal。
|
||||
- cell run:never→running→clean/error;状态更新。
|
||||
- step:按会话顺序执行下一个。
|
||||
- run_all:按顺序;restart 选项。
|
||||
- 同 kernel 串行;不同 kernel 可并行。
|
||||
- close/drop kill 所有 kernel。
|
||||
- API 单测/集成测试。
|
||||
|
||||
---
|
||||
|
||||
## 4. D3 — View UI
|
||||
|
||||
### 内容
|
||||
|
||||
- 工具栏:Run All / Restart & Run All / Step Cell / Step Statement / Kernel 状态 / Restart / Interrupt / State / Journal。
|
||||
- Code card:
|
||||
- 状态徽标(never/clean/dirty/stale/error/running/unlisted)
|
||||
- kernel 下拉
|
||||
- Run / Step
|
||||
- 输出区(stdout/stderr/result/truncated)
|
||||
- 执行序号 / 耗时
|
||||
- 状态面板:
|
||||
- Marqdo 值 / kernel 变量分栏
|
||||
- Push / Pull / Refresh
|
||||
- Secret 打码、大对象摘要
|
||||
- Journal 面板:表格 + 跳转 + 导出。
|
||||
- 键盘:Ctrl/Cmd+Enter、Shift+Enter、F5、F10。
|
||||
- 静态导出的 Run 仍隐藏。
|
||||
|
||||
### 验收
|
||||
|
||||
- 手工冒烟:两个 Python cell 共享 `x`;切换 kernel 后隔离;Restart 清状态。
|
||||
- 状态面板 Push/Pull。
|
||||
- 错误 cell 红色徽标 + stderr。
|
||||
- 页面刷新后 session 仍在(服务端内存)。
|
||||
|
||||
---
|
||||
|
||||
## 5. D4 — Statement step / dirty / writeback
|
||||
|
||||
### 内容
|
||||
|
||||
- Statement step:复用 `DebugController`,与 DocumentSession 关联;暂停点显示变量。
|
||||
- dirty:reload 后 source hash 变化。
|
||||
- stale:按会话顺序,上游变更 → 下游 stale(v2 近似)。
|
||||
- writeback:单 cell / 全部;`<!-- marqdo-out -->`;不自动。
|
||||
- 运行历史 / 执行序号。
|
||||
|
||||
### 验收
|
||||
|
||||
- Statement step 在 view 中可用;外联调用原子完成。
|
||||
- 编辑 cell → dirty;Run All 后 clean。
|
||||
- 上游变更 → 下游 stale。
|
||||
- 显式 writeback 写入文档;不自动改文件。
|
||||
|
||||
---
|
||||
|
||||
## 6. D5 — Replay / 持久化 / 发布
|
||||
|
||||
### 内容
|
||||
|
||||
- Journal replay:新 kernel,按 journal 顺序/输入 hash 重放;比较 stdout/result hash;divergence 报告。
|
||||
- 可选持久化 `.marqdo/sessions/<doc-hash>.json`(kernel/cell 归属/journal/value store 摘要;默认 git 忽略)。
|
||||
- 并发优化:不同 kernel 并行;同 kernel 串行。
|
||||
- 测试补全;文档;catalog;CHANGELOG。
|
||||
- 版本:D 层随 1.5.x。
|
||||
|
||||
### 验收
|
||||
|
||||
- Replay 能复现 clean 会话;dirty 输入给出 divergence。
|
||||
- 关闭/重启服务无进程泄漏。
|
||||
- 文档完整;金样例绿。
|
||||
|
||||
---
|
||||
|
||||
## 7. 测试矩阵
|
||||
|
||||
| 测试 | 断言 |
|
||||
|---|---|
|
||||
| `notebook/kernels.mq.md` | 内核表/会话表解析 |
|
||||
| `notebook/auto-session.mq.md` | 无表自动顺序 |
|
||||
| `notebook/shared-state.mq.md` | 同 kernel 共享变量 |
|
||||
| `notebook/isolated-kernels.mq.md` | 不同 kernel 隔离 |
|
||||
| `notebook/step.mq.md` | cell step 顺序 |
|
||||
| `notebook/state-bridge.mq.md` | Marqdo ↔ kernel 推拉 |
|
||||
| `notebook/dirty.mq.md` | 编辑 → dirty/stale |
|
||||
| `notebook/invalid-*.mq.md` | 诊断 |
|
||||
| API 集成 | open/run/step/run_all/restart/interrupt/close |
|
||||
| 安全 | exec=false、cwd 越界、超时、Secret 打码 |
|
||||
|
||||
依赖 node 为主;python 条件跳过。
|
||||
|
||||
---
|
||||
|
||||
## 8. 完成定义
|
||||
|
||||
- D1–D4 验收;D5 可选(replay/持久化)。
|
||||
- 文档会话与 F 层联调通过。
|
||||
- 手工 view 冒烟:共享状态 / 单步 / 切换 / 状态面板 / journal。
|
||||
- 测试绿;文档更新;提交推送。
|
||||
@@ -0,0 +1,416 @@
|
||||
# Marqdo 常见陷阱手册
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 使用向**(全部条目在 `marqdo 1.5.2` 上实测) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | qdagent 重构期间(文档门禁 + 输出契约)逐条踩坑复现 |
|
||||
| 关联 | [02-基本语法.md](02-基本语法.md) · [06-函数.md](06-函数.md) · [11-模块与导入.md](11-模块与导入.md) · [design/markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
|
||||
| 缺陷来源 | [research/qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 怎么用这份文档
|
||||
|
||||
不是语言教程,而是**避坑清单**。每条都给出:
|
||||
|
||||
- **现象**:你会看到什么(报错原文)
|
||||
- **原因**:为什么这样
|
||||
- **改法**:可直接抄的写法
|
||||
|
||||
全部结论来自实测,不是推测。文中「✅ 安全」表示实测通过,不要靠猜。
|
||||
|
||||
---
|
||||
|
||||
## 1. 写文档(最常见的一类)
|
||||
|
||||
Marqdo 是「文档即程序」,所以**文档写得像正常中文**恰恰是最容易出错的地方。
|
||||
门禁类工具(如 qdagent 的 `execution/docgate`)主要就是在防这些。
|
||||
|
||||
### 1.1 行首数字 → 一定报错 ⚠️ 最高频
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: a.mq.md:7:1: unrecognized statement: 2026 年发布。
|
||||
error: b.mq.md:7:1: unrecognized statement: 42
|
||||
error: c.mq.md:7:1: unrecognized statement: 9 号是数字。
|
||||
```
|
||||
|
||||
**原因**
|
||||
|
||||
行首是数字时,该行被当成**语句**去解析(数字是字面量表达式),而非叙述。
|
||||
|
||||
**改法**
|
||||
|
||||
以文字开头即可。中文里「2026 年」「42 个」「3 个要点」「1. 第一步」这类写法极常见,
|
||||
凡是整行以数字起头都会被拦:
|
||||
|
||||
```markdown
|
||||
# 结论
|
||||
|
||||
发布年份是 2026 年。 ← 把数字后移
|
||||
共收录 42 条。 ← 不要以 42 起行
|
||||
有三个要点需要说明。 ← 不要写 "3 个要点…" 起行
|
||||
```
|
||||
|
||||
确需保留行首数字时,包进行内代码或围栏:
|
||||
|
||||
```markdown
|
||||
`2026` 是发布年份。
|
||||
|
||||
````markdown
|
||||
42
|
||||
````
|
||||
|
||||
### 1.2 行首 `+` → 报错
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: tmm.mq.md:7:1: unrecognized statement: + 加号
|
||||
```
|
||||
|
||||
**原因**:`+` 是形参声明与列表语法的前导符。
|
||||
|
||||
**改法**:叙述区不要用 `+ ` 起行做列表;需要列表用 `- `(见下条)。
|
||||
|
||||
### 1.3 `-` / `>` / `|` / `[` 起行:**多数情况安全**
|
||||
|
||||
这一条要纠正一个常见误解。实测:
|
||||
|
||||
| 行首 | 叙述区 | 说明 |
|
||||
|------|--------|------|
|
||||
| `- 列表项` | ✅ 安全 | 不构成有效 foreach → 跳过 |
|
||||
| `> 引用` | ✅ 安全 | 无对应函数时不当调用 |
|
||||
| `\| a \| b \|` | ✅ 安全 | 未绑定表不算语句 |
|
||||
| `[{"a":1}]` | ✅ 安全 | 无归属的链接索引 → 跳过 |
|
||||
| `9 号是数字。` | ❌ 报错 | 数字字面量是真语句 |
|
||||
| `+ 加号` | ❌ 报错 | 前导符是真语法 |
|
||||
|
||||
但**在函数体内且上下文成立时**它们会真的执行(例如 `- [`x`](`xs`)` 是真循环)。
|
||||
判断标准:**能不能被解析成一条完整语句**。能,就执行;不能,就当叙述跳过。
|
||||
|
||||
### 1.4 未闭合引号 → 静默吞行 ⚠️ 危险
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**s = "abc
|
||||
> print text=hi
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `hi`,**没有报错**,`s` 那一行凭空消失。
|
||||
|
||||
**原因**:未闭合的双引号让该行被当作叙述而不是语句。
|
||||
|
||||
**影响**:这类错误不会中断程序,只会让变量「不存在」,随后在别处报
|
||||
`undefined variable`,把排查方向引偏。
|
||||
|
||||
**改法**:写完立即 `marqdo check`,或注意「变量莫名未定义」时先看引号是否配对。
|
||||
|
||||
---
|
||||
|
||||
## 2. 变量作用域
|
||||
|
||||
### 2.1 模块级变量在函数之间**不可见**
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show
|
||||
*""
|
||||
|
||||
## show
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
```
|
||||
|
||||
```
|
||||
error: t1.mq.md:13:1: undefined variable `g`
|
||||
```
|
||||
|
||||
兄弟函数之间同样不可见:
|
||||
|
||||
```markdown
|
||||
## a
|
||||
|
||||
**x = 1**
|
||||
> b
|
||||
*None*
|
||||
|
||||
## b
|
||||
|
||||
> print text=`x` ← undefined variable `x`
|
||||
*None*
|
||||
```
|
||||
|
||||
**原因**:每个 `##` 是独立作用域;`# main` 与各函数之间**不共享变量**,只共享参数与返回值。
|
||||
|
||||
**改法**:一切跨函数数据走**参数与返回值**。
|
||||
|
||||
```markdown
|
||||
## show
|
||||
+ `g`
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show g=`g`
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.2 顶层不许有裸语句
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: e.mq.md: 5:1: expected heading (`#` object or `##` function), got: **x = 1**
|
||||
```
|
||||
|
||||
**原因**:文件顶层只能是 frontmatter、叙述、`#` 对象、`##` 函数。
|
||||
语句必须放进 `# main` 或某个 `##` 里。
|
||||
|
||||
**改法**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: e
|
||||
---
|
||||
|
||||
**x = 1** ← 挪走
|
||||
|
||||
# main
|
||||
|
||||
**x = 1**
|
||||
> print text=ok
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.3 `table.put` **不**原地修改
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"n":0}**
|
||||
**r = > table.put in=`m` at="n" value=1**
|
||||
```
|
||||
|
||||
之后 `m` 仍是 `{"n":0}`,`r` 才是 `{"n":1}`。
|
||||
|
||||
**影响**:想靠 `> table.put in=`state` ...` 累积状态**不会生效**,
|
||||
计数永远是 0,且不报错。
|
||||
|
||||
**改法**:接住返回值。
|
||||
|
||||
```markdown
|
||||
**state = > table.put in=`state` at="ok_n" value=`n2`**
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 函数
|
||||
|
||||
### 3.1 函数名含空格 → 定义成功,**调用必崩** ⚠️ 缺陷
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 加一 号 n=1**
|
||||
```
|
||||
|
||||
```
|
||||
error: t8.mq.md:13:1: undefined variable `号`
|
||||
```
|
||||
|
||||
英文同样:
|
||||
|
||||
```markdown
|
||||
## my func
|
||||
```
|
||||
调用 → `undefined variable func`。
|
||||
|
||||
**原因**:调用处按空格切分,第一个词当函数名,其余词当位置参数或变量插值。
|
||||
定义侧允许空格,**两侧不对称**。
|
||||
|
||||
**改法**:函数名**不要含空格**。用连字符、下划线或去掉空格:
|
||||
|
||||
```markdown
|
||||
## 加一_号
|
||||
## assert-no-main
|
||||
## my_func
|
||||
```
|
||||
|
||||
命名建议:中文标识符直接连写(`断言干净`、`门禁沉淀`),英文用下划线。
|
||||
|
||||
### 3.2 函数内变量名别和叙述里的裸词撞车
|
||||
|
||||
叙述里的裸词一般是安全的(实测 `大约 head 的位置。` 不报错)。
|
||||
但**在函数名或调用参数位置**出现未定义标识符会立刻报 `undefined variable`。
|
||||
判断标准同上:会被当成语句/表达式的上下文才插值。
|
||||
|
||||
---
|
||||
|
||||
## 4. 字符串与拼接
|
||||
|
||||
### 4.1 引号内 `**`、`|`、`#` 多数安全,不必恐慌
|
||||
|
||||
实测以下全部 ✅:
|
||||
|
||||
```markdown
|
||||
**s = "a ** b"**
|
||||
**s = "a | col | b"**
|
||||
**s = "abc # main def"**
|
||||
**s = "sum: total items"**
|
||||
```
|
||||
|
||||
只有**引号不配对**才会出问题(回到 §1.4)。
|
||||
|
||||
### 4.2 拼装文档正文时,`"`、`*`、`|` 仍建议转义
|
||||
|
||||
当你用字符串拼接**生成一份 `.mq.md`**(而不是自己写)时,字面量容易提前闭合标记。
|
||||
稳妥写法是用 Unicode 转义:
|
||||
|
||||
```markdown
|
||||
**qt = "\u{22}"**
|
||||
**star = "\u{2a}"**
|
||||
**pipe = "\u{7c}"**
|
||||
**nl = "\n"**
|
||||
|
||||
**doc = "---" + `nl` + "title: x" + `nl` + "---" + `nl` + `nl` + "# main" + `nl` + `nl`**
|
||||
**doc = `doc` + "> print text=" + `qt` + "hi" + `qt` + `nl` + `star` + "None" + `star` + `nl`**
|
||||
```
|
||||
|
||||
### 4.3 heredoc 写含 `\n` 的 `.mq.md` 会自毁
|
||||
|
||||
用 `cat <<'EOF'` 写文件时,若内容本身包含反斜杠转义序列,shell 虽不展开,
|
||||
但若中间出现 `EOF` 相邻的变体或内容被后续 `sed`/脚本改写,极易截断。
|
||||
**建议**:生成 .mq.md 用脚本(Python/Node)或编辑器,别用长 heredoc。
|
||||
|
||||
---
|
||||
|
||||
## 5. 导入
|
||||
|
||||
### 5.1 相对路径以**当前文件**为基准
|
||||
|
||||
`execution/a.mq.md` 里导入同目录的 `b.mq.md`,写 `import b:b.mq.md`。
|
||||
写 `import b:execution/b.mq.md` 或 `../execution/b.mq.md` 都可能失败:
|
||||
|
||||
```
|
||||
error: cannot resolve import `../execution/docgate.mq.md` from
|
||||
```
|
||||
|
||||
**跨目录**才用 `..`:
|
||||
|
||||
```markdown
|
||||
import ctx:../knowledge/context.mq.md
|
||||
```
|
||||
|
||||
### 5.2 库名必须导入,不能用裸名
|
||||
|
||||
```
|
||||
error: unknown library `json` (import it in frontmatter)
|
||||
```
|
||||
|
||||
```markdown
|
||||
import json:lib/json.mq.md
|
||||
```
|
||||
|
||||
标准库函数要**带库名前缀**:`json.parse`、`txt.contains`、`table.put`。
|
||||
裸 `str_split`、`contains` 会报 `unknown function`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见函数签名(易记错)
|
||||
|
||||
| 函数 | 参数名 | 备注 |
|
||||
|------|--------|------|
|
||||
| `txt.contains` | `text`, `sub` | 是 `sub` 不是 `part` |
|
||||
| `table.put` | `in`, `at`, `value` | 返回新表,见 §2.3 |
|
||||
| `table.get` | `map`, `key` | 取可选键,键缺失不崩 |
|
||||
| `json.get` | `value`, `key` | 同上 |
|
||||
| `split` | `value`, `sep` | 内置,无库名前缀 |
|
||||
| `sys.env_get` | `name` | |
|
||||
|
||||
**取元 `[key](map)` 是断言式**:键缺失直接 `missing map key 'error'`。
|
||||
取「可能不存在」的键一律用 `table.get` / `json.get`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结构
|
||||
|
||||
### 7.1 `# main` 的体不会被 `##` 截断
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=first
|
||||
|
||||
## helper
|
||||
|
||||
*1*
|
||||
|
||||
> print text=last ← 仍属于 main,会执行
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `first` `last`。**但可读性差**,建议 `# main` 只做编排,函数都放前面。
|
||||
|
||||
### 7.2 `1.` `2.` `3.` 是一条 if/elif/else 链
|
||||
|
||||
```markdown
|
||||
1. `a` > 10
|
||||
...
|
||||
2. `a` > 5
|
||||
...
|
||||
3. *
|
||||
...
|
||||
```
|
||||
|
||||
两段独立的 `1.` 是**两个** if,不是链。嵌套靠缩进。
|
||||
`2. *` 是 else 分支。
|
||||
|
||||
---
|
||||
|
||||
## 8. 自查清单
|
||||
|
||||
提交前跑一遍:
|
||||
|
||||
```bash
|
||||
marqdo check 你的文件.mq.md # 契约/语法检查
|
||||
marqdo run 你的文件.mq.md # 真跑,退出码 0 才算过
|
||||
```
|
||||
|
||||
逐项确认:
|
||||
|
||||
- [ ] 叙述区没有以**数字**或 `+` 起头的行
|
||||
- [ ] 所有双引号成对
|
||||
- [ ] 函数名不含空格
|
||||
- [ ] 没有依赖「函数间共享变量」
|
||||
- [ ] `table.put` 的返回值都接住了
|
||||
- [ ] import 路径以当前文件为基准
|
||||
- [ ] 可选键用 `table.get` / `json.get`,不用 `[key](map)`
|
||||
- [ ] 文件有 `# main`,且 `# main` 无副作用
|
||||
|
||||
---
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-10-22 | 首次发布;全部条目在 1.5.2 实测 |
|
||||
@@ -51,6 +51,7 @@
|
||||
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
|
||||
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
|
||||
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
|
||||
| [第 15 章:常见陷阱](./15-常见陷阱.md) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# agent-sandbox-okf(O1)
|
||||
|
||||
演示 **opt-in 沙盒试跑 + 表风格**(少 json 胶水):`agent.trial` 写入先落 upper,`commit=False` 时宿主不变,成功后再 `commit=True`。
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent
|
||||
export MARQDO_EXT="$PWD/ext"
|
||||
./target/release/marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
```
|
||||
|
||||
期望:`dry-ok` · `host-clean` · `wet-ok` · `proof-visible` · `profile-default`。
|
||||
|
||||
见 [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md) · 金样 [agent-sandbox-optin.mq.md](../../tests/ext/agent-sandbox-optin.mq.md)。
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: agent-sandbox-okf — trial then commit
|
||||
description: >
|
||||
O1 example: opt-in sandbox trial with GFM-table returns and link-index reads.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
|
||||
**had = fs.exists path="_example_sbx"**
|
||||
1. `had`
|
||||
> fs.remove path="_example_sbx"
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
> fs.make_dir path="_example_sbx"
|
||||
|
||||
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
|
||||
**dry_ok = [ok](dry)**
|
||||
**dry_committed = [committed](dry)**
|
||||
1. `dry_ok`
|
||||
1. not `dry_committed`
|
||||
> print text=dry-ok
|
||||
2. *
|
||||
> print text=dry-bad-commit
|
||||
2. *
|
||||
> print text=dry-fail
|
||||
|
||||
**leaked = fs.exists path="_example_sbx/note.txt"**
|
||||
1. `leaked`
|
||||
> print text=host-leaked
|
||||
2. *
|
||||
> print text=host-clean
|
||||
|
||||
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
|
||||
**wet_ok = [ok](wet)**
|
||||
**wet_committed = [committed](wet)**
|
||||
1. `wet_ok`
|
||||
1. `wet_committed`
|
||||
> print text=wet-ok
|
||||
2. *
|
||||
> print text=wet-no-commit
|
||||
2. *
|
||||
> print text=wet-fail
|
||||
|
||||
**body = fs.read_text path="_example_sbx/note.txt"**
|
||||
1. `body` == "sandbox-okf"
|
||||
> print text=proof-visible
|
||||
2. *
|
||||
> print text=proof-missing
|
||||
|
||||
**pname = [name]([profile](wet))**
|
||||
1. `pname` == "default"
|
||||
> print text=profile-default
|
||||
2. *
|
||||
> print text=profile-other
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/feed
|
||||
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
|
||||
import table:lib/table.mq.md
|
||||
@@ -11,13 +12,13 @@ import text:lib/text.mq.md
|
||||
给定帖子行记录列表,输出 `ul.home-posts-list` 标记(首页与列表页共用)。
|
||||
|
||||
**段 = None**
|
||||
- [帖](行)
|
||||
**板 = [board](帖)**
|
||||
**题 = [title](帖)**
|
||||
**链 = [slug](帖)**
|
||||
**作 = [author](帖)**
|
||||
**评 = [comments_count](帖)**
|
||||
**时 = [created_at](帖)**
|
||||
- [帖](遍历 行 为 帖)
|
||||
**板 = [board](access(帖, "board"))**
|
||||
**题 = [title](access(帖, "title"))**
|
||||
**链 = [slug](access(帖, "slug"))**
|
||||
**作 = [author](access(帖, "author"))**
|
||||
**评 = [comments_count](access(帖, "comments_count"))**
|
||||
**时 = [created_at](access(帖, "created_at"))**
|
||||
1. not 作
|
||||
**作 = "匿名"**
|
||||
2. *
|
||||
@@ -41,11 +42,11 @@ import text:lib/text.mq.md
|
||||
给定新闻行记录列表,输出 `.news-timeline` 标记。
|
||||
|
||||
**段 = None**
|
||||
- [讯](行)
|
||||
**题 = [title](讯)**
|
||||
**链 = [slug](讯)**
|
||||
**板 = [board](讯)**
|
||||
**时 = [created_at](讯)**
|
||||
- [讯](遍历 行 为 讯)
|
||||
**题 = [title](access(讯, "title"))**
|
||||
**链 = [slug](access(讯, "slug"))**
|
||||
**板 = [board](access(讯, "board"))**
|
||||
**时 = [created_at](access(讯, "created_at"))**
|
||||
1. not 板
|
||||
**板 = ""**
|
||||
2. *
|
||||
@@ -79,9 +80,9 @@ import text:lib/text.mq.md
|
||||
**全链 = 前缀 + "?" + 查询键 + "=0"**
|
||||
**全项 = "<a href=\"" + 全链 + "\" class=\"" + 全部类 + " active\" " + 数据属 + "=\"0\">" + 全标签 + "</a>"**
|
||||
**段 = > table.append list=段 item=全项**
|
||||
- [板](板块)
|
||||
**名 = [name](板)**
|
||||
**号 = [id](板)**
|
||||
- [板](遍历 板块 为 板)
|
||||
**名 = [name](access(板, "name"))**
|
||||
**号 = [id](access(板, "id"))**
|
||||
**链 = 前缀 + "?" + 查询键 + "=" + 号**
|
||||
**项 = "<a href=\"" + 链 + "\" class=\"" + 全部类 + "\" " + 数据属 + "=\"" + 号 + "\">" + 名 + "</a>"**
|
||||
**段 = > table.append list=段 item=项**
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: browser-app (route E+)
|
||||
description: list CRUD, storage, navigate, interval, fetch_all, ws — GFM + lib/browser
|
||||
import browser:lib/browser.mq.md
|
||||
@@ -64,7 +65,7 @@ import text:lib/text.mq.md
|
||||
**`bag` = bag + "\n" + value**
|
||||
**`parts` = > text.str_split s=bag sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"**
|
||||
**`ret` = > browser.set_html sel="#items" html=html**
|
||||
@@ -81,7 +82,7 @@ import text:lib/text.mq.md
|
||||
1. `data_id` != ""
|
||||
**`parts` = > text.str_split s=bag sep="\n"**
|
||||
**`next` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
1. `item` != `data_id`
|
||||
1. `next` == ""
|
||||
@@ -91,7 +92,7 @@ import text:lib/text.mq.md
|
||||
**`bag` = next**
|
||||
**`parts2` = > text.str_split s=bag sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts2)
|
||||
- [item](遍历 parts2 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"**
|
||||
**`ret` = > browser.set_html sel="#items" html=html**
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 代码即文档 · 周末咖啡手账
|
||||
description: >-
|
||||
一份可读可跑的周末手账:菜单是表,计价写在段落里,结账读起来像日记。
|
||||
@@ -55,13 +56,13 @@ description: >-
|
||||
上午来了位会员,点两杯拿铁。品名写进`名`,价钱从菜单里取:
|
||||
|
||||
**名 = "拿铁"**
|
||||
**价 = [`名`](菜单)**
|
||||
**价 = [名](access(菜单, `名`))**
|
||||
**摘要 = [结账摘要] 品名=`名` 价=`价` 杯数=2 会员=True**
|
||||
**打印 内容=`摘要`**
|
||||
|
||||
旁桌只要一杯普通美式,对照一下原价:
|
||||
|
||||
**对照 = [结账摘要] 品名="美式" 价=[美式](菜单)**
|
||||
**对照 = [结账摘要] 品名="美式" 价=[美式](access(菜单, "美式"))**
|
||||
**打印 内容=`对照`**
|
||||
|
||||
---
|
||||
@@ -75,8 +76,8 @@ description: >-
|
||||
| 1 | 燕麦拿铁 | 32 | 1 | True |
|
||||
| 2 | 美式 | 18 | 2 | False |
|
||||
|
||||
- [行](今日订单)
|
||||
**一行 = 结账摘要 品名=[品名](行) 价=[单价](行) 杯数=[杯数](行) 会员=[会员](行)**
|
||||
- [行](遍历 今日订单 为 行)
|
||||
**一行 = 结账摘要 品名=[品名](access(行, "品名")) 价=[单价](access(行, "单价")) 杯数=[杯数](access(行, "杯数")) 会员=[会员](access(行, "会员"))**
|
||||
**打印 内容=`一行`**
|
||||
|
||||
打烊前给积分卡盖一个章:
|
||||
|
||||
@@ -24,7 +24,7 @@ import data:ext/data/db.mq.md
|
||||
|
||||
| title | slug | summary | content | tag | created_at |
|
||||
|-------|------|---------|---------|-----|------------|
|
||||
| Hello Marqdo | hello | Welcome | # Hello\n\nExecutable documents. | intro | 2026-09-01 |
|
||||
| Hello Marqdo | hello | Welcome | Hello — executable documents. | intro | 2026-09-01 |
|
||||
| Artifact Web | artifact-web | Document first | Pages are mq.md files. | design | 2026-09-28 |
|
||||
|
||||
*rows*
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# oa2026-showcase
|
||||
|
||||
用于 2026 开源项目大赛作品介绍文档的可运行示例。
|
||||
|
||||
| 文件 | 展示的能力 | 运行 |
|
||||
|------|------------|------|
|
||||
| `add.mq.md` | 叙述统一、粗体即代码、斜体即返回 | `marqdo run examples/oa2026-showcase/add.mq.md` |
|
||||
| `invoice.mq.md` | 表格即数据、循环、分支、断言 | `marqdo run examples/oa2026-showcase/invoice.mq.md` |
|
||||
| `calculus.mq.md` | 公式即变量、求导、求根、绘图 | `marqdo run examples/oa2026-showcase/calculus.mq.md` |
|
||||
| `bell.mq.md` | 量子电路、概率、断言、SVG 派生物 | `marqdo run examples/oa2026-showcase/bell.mq.md` |
|
||||
| `foreign-node.mq.md` | 外联一次性执行、持久会话、显式传值 | `marqdo run examples/oa2026-showcase/foreign-node.mq.md` |
|
||||
|
||||
## 预期输出
|
||||
|
||||
```text
|
||||
$ marqdo run examples/oa2026-showcase/add.mq.md
|
||||
42
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/invoice.mq.md
|
||||
960
|
||||
912
|
||||
966
|
||||
within-cap
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/calculus.mq.md
|
||||
3*x^2 - 3
|
||||
9
|
||||
[-1.7320508076, 0, 1.7320508076]
|
||||
plot-ok
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/foreign-node.mq.md
|
||||
{华东: 420, 华北: 220, 华南: 230}
|
||||
华东: 420
|
||||
华南: 230
|
||||
华北: 220
|
||||
|
||||
华东: 420
|
||||
华北: 300
|
||||
华南: 230
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/bell.mq.md
|
||||
{00: 0.5, 11: 0.5}
|
||||
0.5
|
||||
0.5
|
||||
bell-00-ok
|
||||
bell-11-ok
|
||||
bell-draw-ok
|
||||
```
|
||||
|
||||
`bell.mq.md` 运行后会生成 `bell-circuit.svg` 与 `bell-probs.svg`;
|
||||
`calculus.mq.md` 运行后会生成 `calculus-plot.svg`。
|
||||
@@ -0,0 +1,10 @@
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,我们执行 **`n` = `n` + 1**,然后把更新后的值作为结果返回 *`n`*。
|
||||
|
||||
# main
|
||||
|
||||
从 41 出发调用「加一」,把结果存进`r`并打印。
|
||||
|
||||
**`r` = > 加一 n=41**
|
||||
> print text=`r`
|
||||
@@ -0,0 +1,24 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="320" height="136" viewBox="0 0 320.0 136.0" data-theme="light" role="img" aria-label="quantum circuit"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#eef3f9"/>
|
||||
<stop offset="55%" stop-color="#ffffff"/>
|
||||
<stop offset="100%" stop-color="#eef3f9"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#3d5afe" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="320.0" height="136.0" rx="14" fill="url(#mq-bg)"/>
|
||||
<rect x="1.5" y="1.5" width="317.0" height="133.0" rx="12.5" fill="none" stroke="#e2eaf3" stroke-width="1" opacity="0.55"/><line x1="96" y1="36" x2="296" y2="36" stroke="#4a5a6a" stroke-width="3.2" stroke-linecap="round" opacity="0.28"/>
|
||||
<line x1="96" y1="36" x2="296" y2="36" stroke="#4a5a6a" stroke-width="1.8" stroke-linecap="round"/><rect x="51" y="25" width="38" height="22" rx="7" fill="#ffffff" stroke="#e2eaf3" stroke-width="1"/>
|
||||
<text x="70" y="36" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="13" font-weight="700" letter-spacing="0.02em" fill="#15202b">q0</text><line x1="96" y1="100" x2="296" y2="100" stroke="#4a5a6a" stroke-width="3.2" stroke-linecap="round" opacity="0.28"/>
|
||||
<line x1="96" y1="100" x2="296" y2="100" stroke="#4a5a6a" stroke-width="1.8" stroke-linecap="round"/><rect x="51" y="89" width="38" height="22" rx="7" fill="#ffffff" stroke="#e2eaf3" stroke-width="1"/>
|
||||
<text x="70" y="100" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="13" font-weight="700" letter-spacing="0.02em" fill="#15202b">q1</text><rect x="116" y="16" width="40" height="40" rx="8" fill="#3d5afe" stroke="#ffffff" stroke-width="1.1" data-gate-family="clifford" filter="url(#mq-soft)" opacity="0.98"/>
|
||||
<text x="136" y="36" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="14" font-weight="700" fill="#ffffff">H</text><line x1="216" y1="36" x2="216" y2="100" stroke="#1a237e" stroke-width="2.25" data-gate-family="clifford"/>
|
||||
<circle cx="216" cy="36" r="5.2" fill="#1a237e" filter="url(#mq-glow)"/>
|
||||
<circle cx="216" cy="100" r="13" fill="#3d5afe" stroke="#1a237e" stroke-width="1.6" filter="url(#mq-soft)" opacity="0.96"/>
|
||||
<line x1="216" y1="87" x2="216" y2="113" stroke="#1a237e" stroke-width="2"/>
|
||||
<line x1="203" y1="100" x2="229" y2="100" stroke="#1a237e" stroke-width="2"/></svg>
|
||||
|
After Width: | Height: | Size: 2.7 KiB |
@@ -0,0 +1,14 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="light" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#eef3f9"/>
|
||||
<stop offset="55%" stop-color="#ffffff"/>
|
||||
<stop offset="100%" stop-color="#eef3f9"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#3d5afe" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#4a5560" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#4a5560" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#15202b">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#15202b">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#3d5afe" stroke="#1a237e" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#15202b">00</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#5a6a7a">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#3d5afe" stroke="#1a237e" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#15202b">11</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#5a6a7a">0.50</text></svg>
|
||||
|
After Width: | Height: | Size: 2.0 KiB |
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 贝尔态:两个量子比特如何一起回答
|
||||
description: 从一条假设开始,搭电路、看概率、画图,并用断言验收。
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
贝尔态:一次可读的量子实验。
|
||||
|
||||
我们先做一个假设:如果对第一个量子比特施加 Hadamard 门,再用它控制第二个量子比特翻转,
|
||||
那么测量结果不会出现「一个 0、一个 1」,只会出现「00」或「11」。
|
||||
|
||||
下面的表不是配置,而是实验步骤本身。读者先读实验设计,再读执行结果。
|
||||
|
||||
`步骤` =
|
||||
|
||||
| 步骤 | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
**`电路` = > quantum.circuit qubits=2 steps=`步骤`**
|
||||
**`概率` = > `电路`.probabilities**
|
||||
|
||||
> print text=`概率`
|
||||
|
||||
---
|
||||
|
||||
我们期待什么?如果假设成立,`概率`应该只在「00」与「11」上有值,而且各占一半。
|
||||
先把两个关键概率取出来,读者不必在长映射里找:
|
||||
|
||||
**`p00` = [00](概率)**
|
||||
**`p11` = [11](概率)**
|
||||
|
||||
> print text=`p00`
|
||||
> print text=`p11`
|
||||
|
||||
下面的断言不是装饰:如果电路写错,或者门接错,运行会直接失败。
|
||||
|
||||
1. `p00` > 0.49
|
||||
> print text=bell-00-ok
|
||||
2. *
|
||||
> print text=bell-00-fail
|
||||
|
||||
1. `p11` > 0.49
|
||||
> print text=bell-11-ok
|
||||
2. *
|
||||
> print text=bell-11-fail
|
||||
|
||||
---
|
||||
|
||||
图不是截图,而是这份文档运行后生成的派生物。电路图和概率图都来自同一个`电路`。
|
||||
|
||||
**`_` = > `电路`.draw path="bell-circuit.svg" theme="light"**
|
||||
**`_` = > `电路`.draw kind="probs" path="bell-probs.svg" theme="light"**
|
||||
|
||||
> print text=bell-draw-ok
|
||||
@@ -0,0 +1,17 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="289.09" x2="484" y2="289.09" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="216.36" x2="484" y2="216.36" class="grid"/><line x1="36" y1="180.00" x2="484" y2="180.00" class="grid"/><line x1="36" y1="143.64" x2="484" y2="143.64" class="grid"/><line x1="36" y1="107.27" x2="484" y2="107.27" class="grid"/><line x1="36" y1="70.91" x2="484" y2="70.91" class="grid"/><line x1="36" y1="180.00" x2="484" y2="180.00" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="184.00" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="176.00" x2="36.00" y2="184.00" class="tick"/><text x="36.00" y="194.00" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="176.00" x2="110.67" y2="184.00" class="tick"/><text x="110.67" y="194.00" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="176.00" x2="185.33" y2="184.00" class="tick"/><text x="185.33" y="194.00" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="176.00" x2="334.67" y2="184.00" class="tick"/><text x="334.67" y="194.00" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="176.00" x2="409.33" y2="184.00" class="tick"/><text x="409.33" y="194.00" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="176.00" x2="484.00" y2="184.00" class="tick"/><text x="484.00" y="194.00" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="289.09" x2="264.00" y2="289.09" class="tick"/><text x="252.00" y="289.09" text-anchor="end" dominant-baseline="middle" class="tick-label">-15</text><line x1="256.00" y1="252.73" x2="264.00" y2="252.73" class="tick"/><text x="252.00" y="252.73" text-anchor="end" dominant-baseline="middle" class="tick-label">-10</text><line x1="256.00" y1="216.36" x2="264.00" y2="216.36" class="tick"/><text x="252.00" y="216.36" text-anchor="end" dominant-baseline="middle" class="tick-label">-5</text><line x1="256.00" y1="143.64" x2="264.00" y2="143.64" class="tick"/><text x="252.00" y="143.64" text-anchor="end" dominant-baseline="middle" class="tick-label">5</text><line x1="256.00" y1="107.27" x2="264.00" y2="107.27" class="tick"/><text x="252.00" y="107.27" text-anchor="end" dominant-baseline="middle" class="tick-label">10</text><line x1="256.00" y1="70.91" x2="264.00" y2="70.91" class="tick"/><text x="252.00" y="70.91" text-anchor="end" dominant-baseline="middle" class="tick-label">15</text><text x="252.00" y="194.00" class="tick-label">0</text><path d="M 36.00 310.91 L 38.24 305.73 L 40.48 300.67 L 42.72 295.72 L 44.96 290.89 L 47.20 286.18 L 49.44 281.57 L 51.68 277.07 L 53.92 272.69 L 56.16 268.41 L 58.40 264.24 L 60.64 260.18 L 62.88 256.22 L 65.12 252.36 L 67.36 248.61 L 69.60 244.96 L 71.84 241.40 L 74.08 237.95 L 76.32 234.60 L 78.56 231.34 L 80.80 228.17 L 83.04 225.11 L 85.28 222.13 L 87.52 219.25 L 89.76 216.45 L 92.00 213.75 L 94.24 211.13 L 96.48 208.61 L 98.72 206.17 L 100.96 203.81 L 103.20 201.53 L 105.44 199.34 L 107.68 197.23 L 109.92 195.20 L 112.16 193.25 L 114.40 191.38 L 116.64 189.58 L 118.88 187.86 L 121.12 186.22 L 123.36 184.64 L 125.60 183.14 L 127.84 181.71 L 130.08 180.35 L 132.32 179.06 L 134.56 177.83 L 136.80 176.67 L 139.04 175.57 L 141.28 174.54 L 143.52 173.57 L 145.76 172.67 L 148.00 171.82 L 150.24 171.03 L 152.48 170.30 L 154.72 169.62 L 156.96 169.00 L 159.20 168.44 L 161.44 167.93 L 163.68 167.47 L 165.92 167.06 L 168.16 166.70 L 170.40 166.39 L 172.64 166.12 L 174.88 165.90 L 177.12 165.73 L 179.36 165.60 L 181.60 165.51 L 183.84 165.46 L 186.08 165.46 L 188.32 165.49 L 190.56 165.56 L 192.80 165.67 L 195.04 165.81 L 197.28 165.98 L 199.52 166.19 L 201.76 166.43 L 204.00 166.70 L 206.24 167.01 L 208.48 167.33 L 210.72 167.69 L 212.96 168.07 L 215.20 168.48 L 217.44 168.91 L 219.68 169.36 L 221.92 169.84 L 224.16 170.33 L 226.40 170.84 L 228.64 171.38 L 230.88 171.92 L 233.12 172.48 L 235.36 173.06 L 237.60 173.65 L 239.84 174.25 L 242.08 174.86 L 244.32 175.49 L 246.56 176.12 L 248.80 176.75 L 251.04 177.39 L 253.28 178.04 L 255.52 178.69 L 257.76 179.35 L 260.00 180.00 L 262.24 180.65 L 264.48 181.31 L 266.72 181.96 L 268.96 182.61 L 271.20 183.25 L 273.44 183.88 L 275.68 184.51 L 277.92 185.14 L 280.16 185.75 L 282.40 186.35 L 284.64 186.94 L 286.88 187.52 L 289.12 188.08 L 291.36 188.62 L 293.60 189.16 L 295.84 189.67 L 298.08 190.16 L 300.32 190.64 L 302.56 191.09 L 304.80 191.52 L 307.04 191.93 L 309Line truncated
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 6.8 KiB |
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: 一份可执行的求导讲义
|
||||
description: 公式、求导、求根、求值与绘图,在同一条叙述里完成。
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
我们从一条曲线开始。下面这个公式既是排版出来的数学对象,
|
||||
也是运行时可以直接求导、求根与绘图的`f`。
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^3 - 3*x
|
||||
$$
|
||||
|
||||
对它求导,得到`df`;再让`df`在 x = 2 处取值,得到切线斜率。
|
||||
|
||||
**`df` = [math.diff] formula=`f` var="x"**
|
||||
**`slope` = [math.eval] formula=`df` var="x" value=2**
|
||||
> print text=`df`
|
||||
> print text=`slope`
|
||||
|
||||
曲线与 x 轴的交点同样可以被机器找出来。这里不需要另写一段脚本。
|
||||
|
||||
**`roots` = [math.solve] formula=`f` var="x" min=-3 max=3**
|
||||
> print text=`roots`
|
||||
|
||||
最后把公式画成图。图不是截图,而是本文档运行产生的派生物。
|
||||
|
||||
**`_svg` = [math.plot] formula=`f` var="x" min=-3 max=3 path="calculus-plot.svg"**
|
||||
> print text=plot-ok
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 外联:把 Node 当作文档里的计算车间
|
||||
description: 一次性执行、持久会话、显式传值,以及可读的结果。
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这份文档要回答一个很具体的问题:同一批订单,按区域汇总之后,总金额分别是多少?
|
||||
数据已经写在文档里,计算交给 Node,结果回到文档里继续被阅读与断言。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
|
||||
先做一次性执行。`foreign.call` 把`订单`编码成 JSON 放到 stdin,
|
||||
Node 读完、汇总、打印 JSON;外联再把 stdout 解析成 Marqdo 的值。
|
||||
没有 shell,也没有隐式的 stdin 约定——传什么、读什么,都写在代码里。
|
||||
|
||||
`汇总代码` =
|
||||
```javascript
|
||||
const incoming = JSON.parse(require('fs').readFileSync(0, 'utf8'));
|
||||
|
||||
const byRegion = {};
|
||||
for (const row of incoming) {
|
||||
byRegion[row["区域"]] = (byRegion[row["区域"]] || 0) + Number(row["金额"]);
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(byRegion));
|
||||
```
|
||||
|
||||
**`汇总` = > foreign.call code=`汇总代码` input=`订单`**
|
||||
> print text=`汇总`
|
||||
|
||||
---
|
||||
|
||||
一次性执行适合「算完就走」。如果想让同一个 Node 内核保留变量,
|
||||
就显式开启会话、显式设值、显式求值、显式关闭——状态不会藏在某个看不见的 cell 里。
|
||||
|
||||
**`会话` = > foreign.session_open lang="node"**
|
||||
**> foreign.session_set id=`会话` name="orders" value=`订单`**
|
||||
|
||||
`排序代码` =
|
||||
```javascript
|
||||
const ranked = Object.entries(
|
||||
orders.reduce((acc, row) => {
|
||||
acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
|
||||
return acc;
|
||||
}, {})
|
||||
).sort((a, b) => b[1] - a[1]);
|
||||
|
||||
console.log(ranked.map(([region, total]) => `${region}: ${total}`).join("\n"));
|
||||
```
|
||||
|
||||
**`第一次` = > foreign.session_eval id=`会话` code=`排序代码`**
|
||||
> print text=[stdout](access(`第一次`, "stdout"))
|
||||
|
||||
内核状态是持续的。下面这段代码在同一个`orders`上追加一条华北订单,
|
||||
再重新排序;不需要重新传一遍整张表。
|
||||
|
||||
`追加代码` =
|
||||
```javascript
|
||||
orders.push({ 区域: "华北", 金额: 80 });
|
||||
|
||||
const rankedAgain = Object.entries(
|
||||
orders.reduce((acc, row) => {
|
||||
acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
|
||||
return acc;
|
||||
}, {})
|
||||
).sort((a, b) => b[1] - a[1]);
|
||||
|
||||
console.log(rankedAgain.map(([region, total]) => `${region}: ${total}`).join("\n"));
|
||||
```
|
||||
|
||||
**`第二次` = > foreign.session_eval id=`会话` code=`追加代码`**
|
||||
> print text=[stdout](access(`第二次`, "stdout"))
|
||||
|
||||
**> foreign.session_close id=`会话`**
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 一张订单,一份可执行的业务说明
|
||||
description: 叙述、数据、计算与断言共享同一个 .mq.md 源文件。
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这份文档不是代码旁边的说明,也不是说明里贴的代码。下表既是给人读的订单,
|
||||
也是运行时直接使用的记录集合;下面的句子既解释业务规则,也参与计算。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 客户 | 单价 | 数量 | 提前天数 |
|
||||
|---|------|------|------|----------|
|
||||
| 1 | 青山实验室 | 120 | 3 | 10 |
|
||||
| 2 | 远望中心 | 80 | 5 | 4 |
|
||||
| 3 | 星尘工坊 | 200 | 1 | 14 |
|
||||
|
||||
逐行把「单价 × 数量」累加进`小计`。读者看到的是清单,机器执行的是同一张表。
|
||||
|
||||
**`小计` = 0**
|
||||
- [行](遍历 订单 为 行)
|
||||
**`小计` = `小计` + [单价](access(行, "单价")) * [数量](access(行, "数量"))**
|
||||
|
||||
业务约定写在叙述里:提前不少于七天,整单按九五折;否则原价。
|
||||
本单最早提前 14 天。
|
||||
|
||||
**`最早提前` = 14**
|
||||
1. `最早提前` >= 7
|
||||
**`折后` = `小计` * 95 / 100**
|
||||
2. *
|
||||
**`折后` = `小计`**
|
||||
|
||||
把结果、依据和判断一起写进文档。下面的断言如果跑不通,文档本身就是错的。
|
||||
|
||||
**`含税` = `折后` * 106 / 100**
|
||||
> print text=`小计`
|
||||
> print text=`折后`
|
||||
> print text=`含税`
|
||||
|
||||
1. `含税` < 10000
|
||||
> print text=within-cap
|
||||
2. *
|
||||
> print text=over-cap
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
markup: occlusion
|
||||
import table:lib/table.mq.md
|
||||
title: Marqdo 语法全景(v1.6 现状)
|
||||
description: 一页看完全部现行语法:遮蔽、调用、取值、循环、分支、表格、契约
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
—— 1. 变量与插值 ——
|
||||
|
||||
**π = 3.14159**
|
||||
**名 = "Marqdo"**
|
||||
**开 = True**
|
||||
|
||||
> print text=名字是`名`,π 约等于 `π`
|
||||
|
||||
反引号取值,正文里的反引号是插值:
|
||||
|
||||
`长度` = [名字长度](len(`名`))
|
||||
|
||||
> print text=`名` 的长度是 `长度`
|
||||
|
||||
—— 2. 函数:参数、返回、契约 ——
|
||||
|
||||
税率函数接收档位与金额,返回应缴税额。
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
|
||||
`税率表` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.1 |
|
||||
| 3 | 0.2 |
|
||||
|
||||
—— 3. 调用的四种形态 ——
|
||||
|
||||
> print text="形态一:> 前缀 + 具名实参"
|
||||
|
||||
**甲 = 加(1 2)**
|
||||
**乙 = 加(1, 2)**
|
||||
**丙 = 加(加(1 2), 10)**
|
||||
**丁 = 加一 号(31)**
|
||||
|
||||
> print text=形态二 括号位置实参:`甲`
|
||||
> print text=形态三 括号逗号:`乙`
|
||||
> print text=形态四 嵌套:`丙`
|
||||
> print text=形态五 带空格的函数名:`丁`
|
||||
|
||||
—— 4. 取值:access / at / get ——
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
|
||||
`饮品价` =
|
||||
|
||||
| 拿铁 | 美式 |
|
||||
|------|------|
|
||||
| 28 | 18 |
|
||||
|
||||
`取第一` = [第一颗](access(`篮子`, "1"))
|
||||
`取配置` = [拿铁多少钱](access(`饮品价`, "拿铁"))
|
||||
`个数` = [篮子有几颗](table.len(`篮子`))
|
||||
`表取` = [用 table.get 读同一个键](table.get(`饮品价`, "美式"))
|
||||
|
||||
> print text=access 取列表第 1 项:`取第一`
|
||||
> print text=access 取 Map 的键:`取配置`
|
||||
> print text=table.len 数个数:`个数`
|
||||
> print text=table.get 读键:`表取`
|
||||
|
||||
—— 5. 遮蔽:把实现藏进括号 ——
|
||||
|
||||
描述给人读,`()` 里才是机器执行的部分。
|
||||
|
||||
写法用 `` `名` = [描述](实现) ``(裸赋值),而不是 `**名 = [描述](实现)**`:
|
||||
粗体会把描述也包成"代码味",读者一眼看到的是强调而不是人话。
|
||||
|
||||
`留存` = [客户留存率,模拟数据](0.42)
|
||||
|
||||
> print text=遮蔽的值:`留存`
|
||||
|
||||
未接通的功能用空载荷申报(会得到一条 warning,提醒写清返回值):
|
||||
|
||||
`待接` = [搜索接入,接口未接,待开发]()
|
||||
|
||||
> print text=空载荷桩的值:`待接`
|
||||
|
||||
—— 6. 循环 ——
|
||||
|
||||
- [篮子里的每个果子](遍历 `篮子` 为 `果`)
|
||||
> print text=果子:`果`
|
||||
|
||||
`n` = 3
|
||||
|
||||
- `n` > 0
|
||||
> print text=倒数 `n`
|
||||
**n = n - 1**
|
||||
|
||||
—— 7. 分支 ——
|
||||
|
||||
**分数 = 86**
|
||||
|
||||
1. `分数` >= 90
|
||||
> print text=等级 A
|
||||
2. `分数` >= 60
|
||||
> print text=等级 B
|
||||
3. *
|
||||
> print text=等级 C
|
||||
|
||||
—— 8. 表格的三态 ——
|
||||
|
||||
竖表(单列)→ List:
|
||||
|
||||
`城市` =
|
||||
|
||||
| 城 |
|
||||
|----|
|
||||
| 北京 |
|
||||
| 上海 |
|
||||
|
||||
横表(1 行)→ Map:
|
||||
|
||||
`配置` =
|
||||
|
||||
| 超时 | 重试 |
|
||||
|------|------|
|
||||
| 30 | 2 |
|
||||
|
||||
行向(首列 `行`)→ List of Map:
|
||||
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
|
||||
- [每条订单](遍历 `订单` 为 `单`)
|
||||
> print text=订单:`单`
|
||||
|
||||
> print text=配置超时是 `配置`
|
||||
|
||||
—— 9. 值类型 ——
|
||||
|
||||
**整数 = 42**
|
||||
**小数 = 1.5**
|
||||
**真值 = True**
|
||||
**空值 = None**
|
||||
**串 = "引号里的文本"**
|
||||
|
||||
> print text=整数 `整数` 小数 `小数` 真值 `真值` 空值 `空值`
|
||||
> print text=`串`
|
||||
|
||||
—— 10. 收尾 ——
|
||||
|
||||
> print text="以上全部可执行;描述只是描述,机器只跑括号里的东西。"
|
||||
|
||||
## 计税
|
||||
+ `档位`
|
||||
+ `金额`
|
||||
|
||||
**率 = 0.1**
|
||||
|
||||
1. `档位` == 1
|
||||
**率 = 0.03**
|
||||
2. `档位` == 3
|
||||
**率 = 0.2**
|
||||
3. *
|
||||
**率 = 0.1**
|
||||
|
||||
*`金额` * `率`*
|
||||
|
||||
## 加
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
*`a` + `b`*
|
||||
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: spa client
|
||||
description: routes table + memory store; list / detail / edit
|
||||
import browser:lib/browser.mq.md
|
||||
@@ -87,7 +88,7 @@ Routes (documentation + titles). Runtime switches panels by `path`.
|
||||
1. `cur_id` != ""
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`next` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
1. `item` == `cur_id`
|
||||
1. `next` == ""
|
||||
@@ -145,7 +146,7 @@ Routes (documentation + titles). Runtime switches panels by `path`.
|
||||
**`body` = ""**
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li data-id=\"" + item + "\">" + item + "</li>"**
|
||||
`persist` =
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.4.0
|
||||
2.0.0
|
||||
+643
-338
File diff suppressed because it is too large.
Load diff
+42
-15
@@ -5,6 +5,7 @@ description: >-
|
||||
OpenAI-compatible and Ollama HTTP stay behind the semantic surface.
|
||||
import sys:lib/sys.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import openai:ext/ai/llm/openai.mq.md
|
||||
@@ -25,14 +26,14 @@ Collapse a stream event list to final answer text (`done.result` or `error.messa
|
||||
**answer = ""**
|
||||
|
||||
- [ev](events)
|
||||
**t = [type](ev)**
|
||||
**t = > json.get value=`ev` key="type"**
|
||||
1. `t` == "done"
|
||||
**answer = [result](ev)**
|
||||
**answer = > json.get value=`ev` key="result"**
|
||||
2. `t` == "error"
|
||||
**answer = [message](ev)**
|
||||
**answer = > json.get value=`ev` key="message"**
|
||||
3. `t` == "delta"
|
||||
4. `t` == "text"
|
||||
**chunk = [text](ev)**
|
||||
**chunk = > json.get value=`ev` key="text"**
|
||||
1. `chunk`
|
||||
**answer = answer + chunk**
|
||||
2. *
|
||||
@@ -167,7 +168,8 @@ Module convenience: create a default handle and return **answer text**. Pass `pa
|
||||
|
||||
**m = > create model=`model` base_url=`base_url` api_key=`api_key`**
|
||||
**r = > m.ask prompt=`p`**
|
||||
*[text](r)*
|
||||
**_ret = > json.get value=`r` key="text"**
|
||||
*_ret*
|
||||
|
||||
# llm
|
||||
+ `model`=None
|
||||
@@ -283,9 +285,21 @@ Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `
|
||||
**text = > json.get value=`pack` key="text"**
|
||||
**usage = > json.get value=`pack` key="usage"**
|
||||
**finish = > json.get value=`pack` key="finish"**
|
||||
**err = > json.get value=`pack` key="error"**
|
||||
**tc = > json.get value=`pack` key="tool_calls"**
|
||||
1. not `tc`
|
||||
**tc = > json.parse text=[]**
|
||||
**tc = > table.empty_list**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `text`
|
||||
**text = ""**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `finish`
|
||||
1. `err`
|
||||
**finish = "error"**
|
||||
2. *
|
||||
**finish = "stop"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
@@ -293,16 +307,27 @@ Hoist receiver fields before the result table — table cells can shadow `self`
|
||||
column names (`model`, `usage`), so `[model](self)` / `[total_tokens](usage)`
|
||||
inside the table is unsafe.
|
||||
|
||||
**mdl = [model](self)**
|
||||
**b = [backend](self)**
|
||||
**nm = [name](self)**
|
||||
**tt = [total_tokens](usage)**
|
||||
**mdl = > json.get value=`self` key="model"**
|
||||
**b = > json.get value=`self` key="backend"**
|
||||
**nm = > json.get value=`self` key="name"**
|
||||
1. `usage`
|
||||
**tt = > json.get value=`usage` key="total_tokens"**
|
||||
2. *
|
||||
**tt = 0**
|
||||
1. not `tt`
|
||||
**tt = 0**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. `err`
|
||||
**calls = 0**
|
||||
2. *
|
||||
**calls = 1**
|
||||
|
||||
`result` =
|
||||
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` |
|
||||
|
||||
*result*
|
||||
|
||||
@@ -345,10 +370,12 @@ Internal / compatibility primitive. Prefer `ask` / `stream` in new code.
|
||||
|
||||
1. `stream`
|
||||
**pack = > self.complete_result prompt=`prompt` stream=True echo=`echo`**
|
||||
*[events](pack)*
|
||||
**_ret = > json.get value=`pack` key="events"**
|
||||
*_ret*
|
||||
2. *
|
||||
**pack = > self.complete_result prompt=`prompt` stream=False echo=`echo`**
|
||||
*[text](pack)*
|
||||
**_ret = > json.get value=`pack` key="text"**
|
||||
*_ret*
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
|
||||
+67
-27
@@ -1,9 +1,11 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/ai/llm/openai
|
||||
description: >-
|
||||
OpenAI-compatible chat completions transport (HTTP + SSE).
|
||||
Prefers optional plugins/llm ABI when present; falls back to lib/net.
|
||||
Used by ext/ai/llm; authors should prefer llm.ask / llm.stream.
|
||||
Result packs are GFM tables / table.put (code-as-documentation).
|
||||
import net:lib/net.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import table:lib/table.mq.md
|
||||
@@ -53,21 +55,18 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
|
||||
**choices = > json.get value=`data` key="choices"**
|
||||
1. not `choices`
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
2. *
|
||||
**c0 = [1](choices)**
|
||||
**c0 = [1](access(choices, "1"))**
|
||||
**msg = > json.get value=`c0` key="message"**
|
||||
1. not `msg`
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
2. *
|
||||
**tc = > json.get value=`msg` key="tool_calls"**
|
||||
1. `tc`
|
||||
*tc*
|
||||
2. *
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
|
||||
## chat_completions
|
||||
+ `base_url`
|
||||
@@ -79,7 +78,7 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
+ `suffix`=/chat/completions
|
||||
+ `bearer`="Bearer "
|
||||
|
||||
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`.
|
||||
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`. Soft transport / HTTP failures return `finish=error` packs (never abort the VM).
|
||||
|
||||
**p = > plugin.native_path name="llm"**
|
||||
1. `p`
|
||||
@@ -106,40 +105,81 @@ POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_c
|
||||
**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. [status](resp) == 200
|
||||
**pack = > json.parse text={"finish":"stop"}**
|
||||
**pack = > json.set map=`pack` key="events" value=[events](resp)**
|
||||
**st = > json.get value=`resp` key="status"**
|
||||
1. `st` == 200
|
||||
**evs = > json.get value=`resp` key="events"**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | events |
|
||||
|--------|--------|
|
||||
| stop | `evs` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
> print text=ext/ai/llm/openai: HTTP error (stream)
|
||||
> print text=[status](resp)
|
||||
> sys.exit code=1
|
||||
Soft transport / HTTP failure — structured pack, never abort the VM.
|
||||
**msg = "HTTP " + `st`**
|
||||
**evs = > json.get value=`resp` key="events"**
|
||||
1. `evs`
|
||||
**e0 = > at value=`evs` index=0**
|
||||
**m2 = > json.get value=`e0` key="message"**
|
||||
1. `m2`
|
||||
**msg = `m2`**
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | events |
|
||||
|--------|------|-------|--------|
|
||||
| error | "" | `msg` | `evs` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
**body = > json.stringify value=`req`**
|
||||
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
|
||||
1. [status](resp) == 200
|
||||
**data = > json.parse text=[body](resp)**
|
||||
**msg = [message]([1]([choices](data)))**
|
||||
**st = > json.get value=`resp` key="status"**
|
||||
1. `st` == 200
|
||||
**raw = > json.get value=`resp` key="body"**
|
||||
**data = > json.parse text=`raw`**
|
||||
**choices = > json.get value=`data` key="choices"**
|
||||
**choice0 = > at value=`choices` index=0**
|
||||
**msg = > json.get value=`choice0` key="message"**
|
||||
**text = > json.get value=`msg` key="content"**
|
||||
1. not `text`
|
||||
**text = ""**
|
||||
2. *
|
||||
**_ = 1**
|
||||
**usage = > usage_from data=`data`**
|
||||
**fr = > json.get value=[1]([choices](data)) key="finish_reason"**
|
||||
**fr = > json.get value=`choice0` key="finish_reason"**
|
||||
1. not `fr`
|
||||
**fr = "stop"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
**tc = > tool_calls_from data=`data`**
|
||||
**pack = > json.parse text={"finish":"stop"}**
|
||||
**pack = > json.set map=`pack` key="text" value=`text`**
|
||||
**pack = > json.set map=`pack` key="usage" value=`usage`**
|
||||
**pack = > json.set map=`pack` key="finish" value=`fr`**
|
||||
**pack = > json.set map=`pack` key="tool_calls" value=`tc`**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | usage | tool_calls |
|
||||
|--------|------|-------|------------|
|
||||
| `fr` | `text` | `usage` | `tc` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
> print text=ext/ai/llm/openai: HTTP error
|
||||
> print text=[status](resp)
|
||||
> print text=[body](resp)
|
||||
> sys.exit code=1
|
||||
Soft transport / HTTP failure — structured pack, never abort the VM.
|
||||
**raw = > json.get value=`resp` key="body"**
|
||||
**msg = "HTTP " + `st`**
|
||||
1. `raw`
|
||||
**msg = `msg` + ": " + `raw`**
|
||||
`usage0` =
|
||||
|
||||
| prompt_tokens | completion_tokens | total_tokens |
|
||||
|---------------|-------------------|--------------|
|
||||
| 0 | 0 | 0 |
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: step-route policy (O3)
|
||||
description: >
|
||||
Table-driven map from step class → Adaptive Routing backend.
|
||||
Readable authority for agent.step_route; do not invent a second dialect.
|
||||
---
|
||||
|
||||
# Step class → backend
|
||||
|
||||
Authors and `agent.step_route` read this table. Backends match Adaptive Routing:
|
||||
`marqdo` | `small-llm` | `llm` | `auto`.
|
||||
|
||||
**routes = **
|
||||
|
||||
| kind | backend | note |
|
||||
|------|---------|------|
|
||||
| lookup | marqdo | OKF / kb skill hit — no parent LLM |
|
||||
| patch | small-llm | Local patch / soft match |
|
||||
| sandbox_run | marqdo | CoW trial of `.mq.md` |
|
||||
| net | llm | Needs network / toolful turn |
|
||||
| default | auto | Cascade policy → kb → small-llm |
|
||||
|
||||
# main
|
||||
|
||||
*routes*
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/ai/sandbox
|
||||
description: >-
|
||||
CoW trial workspace for AI-generated Marqdo: open / run / diff / commit.
|
||||
Native work lives in plugins/agent (`sandbox_*` → host_query).
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
Load the agent plugin once per call (same pattern as other `ext/ai` helpers).
|
||||
|
||||
Capability profiles are GFM tables under `## profile` (readable authority; `open` / `inspect` echo them). Do not invent a second table dialect.
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
**p = plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
|
||||
> sys.exit code=1
|
||||
|
||||
## profile
|
||||
+ `name`=default
|
||||
|
||||
Named caps row as a map table (`name`, `fs_write`, `exec`, `net`, `plugin`). Unknown names → `default`.
|
||||
|
||||
Catalog (documentation + authority):
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| default | true | false | false | false |
|
||||
| readonly | false | false | false | false |
|
||||
|
||||
1. `name` == "readonly"
|
||||
**row = **
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| readonly | false | false | false | false |
|
||||
|
||||
2. *
|
||||
**row = **
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| default | true | false | false | false |
|
||||
|
||||
*row*
|
||||
|
||||
## open_native
|
||||
+ `root`=None
|
||||
|
||||
Native CoW open (plugin ABI italic return). Prefer `## open` for the profile-aware facade.
|
||||
|
||||
> ensure_plugin
|
||||
|
||||
1. `root`
|
||||
*> sandbox_open root=`root`*
|
||||
2. *
|
||||
*> sandbox_open*
|
||||
|
||||
## open
|
||||
+ `root`=None
|
||||
+ `profile`=default
|
||||
|
||||
Open a CoW session. Optional `root=` (directory). Default: entry file directory.
|
||||
`profile=` selects the caps row from `## profile` (echoed by `inspect`).
|
||||
|
||||
**sess = open_native root=`root`**
|
||||
**prof = profile name=`profile`**
|
||||
**sess = table.put in=`sess` at="profile" value=`prof`**
|
||||
*sess*
|
||||
|
||||
## write
|
||||
+ `id`
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
Write text into the session upper layer (host tree unchanged until `commit`).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_write id=`id` path=`path` text=`text`*
|
||||
|
||||
## read
|
||||
+ `id`
|
||||
+ `path`
|
||||
|
||||
Read through CoW (upper, else lower; whiteout misses).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_read id=`id` path=`path`*
|
||||
|
||||
## remove
|
||||
+ `id`
|
||||
+ `path`
|
||||
|
||||
Logical delete (whiteout).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_remove id=`id` path=`path`*
|
||||
|
||||
## diff
|
||||
+ `id`
|
||||
|
||||
List of `{ path, kind }` pending changes (`write` | `remove`).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_diff id=`id`*
|
||||
|
||||
## commit
|
||||
+ `id`
|
||||
|
||||
Apply upper / whiteout to the real workspace root.
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_commit id=`id`*
|
||||
|
||||
## discard
|
||||
+ `id`
|
||||
|
||||
Drop the session without writing the host tree.
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_discard id=`id`*
|
||||
|
||||
## run
|
||||
+ `id`
|
||||
+ `source`=None
|
||||
+ `path`=None
|
||||
|
||||
Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW).
|
||||
Pass `source=` or `path=` (relative to session root).
|
||||
|
||||
> ensure_plugin
|
||||
|
||||
1. `source`
|
||||
*> sandbox_run id=`id` source=`source`*
|
||||
2. `path`
|
||||
*> sandbox_run id=`id` path=`path`*
|
||||
3. *
|
||||
> print text=ext/ai/sandbox.run: need source= or path=
|
||||
> sys.exit code=1
|
||||
|
||||
## inspect_native
|
||||
+ `id`
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_inspect id=`id`*
|
||||
|
||||
## inspect
|
||||
+ `id`
|
||||
+ `profile`=default
|
||||
|
||||
Native caps / change counts, plus the GFM `## profile` row under key `profile`.
|
||||
|
||||
**raw = inspect_native id=`id`**
|
||||
**prof = profile name=`profile`**
|
||||
**out = table.put in=`raw` at="profile" value=`prof`**
|
||||
*out*
|
||||
|
||||
## report
|
||||
+ `id`
|
||||
+ `path`=sandbox-diff.md
|
||||
|
||||
O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report file, not a UI rewrite).
|
||||
|
||||
**pending = diff id=`id`**
|
||||
**n = len value=`pending`**
|
||||
**body = "# Sandbox diff report\n\nPending changes: "**
|
||||
**body = body + n**
|
||||
**body = body + "\n\n| path | kind |\n|------|------|\n"**
|
||||
- [row](遍历 pending 为 row)
|
||||
**p = [path](access(row, "path"))**
|
||||
**k = [kind](access(row, "kind"))**
|
||||
**body = body + "| "**
|
||||
**body = body + p**
|
||||
**body = body + " | "**
|
||||
**body = body + k**
|
||||
**body = body + " |\n"**
|
||||
> fs.write_text path=`path` text=`body`
|
||||
|
||||
**out = **
|
||||
|
||||
| path | count |
|
||||
|------|-------|
|
||||
| `path` | `n` |
|
||||
|
||||
*out*
|
||||
+57
-21
@@ -3,6 +3,8 @@ title: ext/ai/智能体
|
||||
description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编译经 ABI v2 agent 插件(情景 → 学习 → llm_free)。
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import json:lib/json.mq.md
|
||||
导入 系统:lib/系统.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
@@ -86,13 +88,14 @@ import json:lib/json.mq.md
|
||||
> 系统.退出 码=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=`工具`**
|
||||
`h` =
|
||||
|
||||
| _type | id | model | tools |
|
||||
|-------|-----|-------|-------|
|
||||
| 智能体 | `id` | `大模型` | `工具` |
|
||||
|
||||
1. `站立提示`
|
||||
**h = > json.set map=`h` key="standing" value=`站立提示`**
|
||||
**h = table.put in=`h` at="standing" value=`站立提示`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
@@ -106,23 +109,42 @@ import json:lib/json.mq.md
|
||||
> agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 试跑
|
||||
+ `路径`=None
|
||||
+ `源码`=None
|
||||
+ `根目录`=None
|
||||
+ `写入路径`=None
|
||||
+ `文本`=None
|
||||
+ `提交`=真
|
||||
+ `配置`=default
|
||||
|
||||
O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成功 `提交` 前不变)。
|
||||
|
||||
*> agent.trial path=`路径` source=`源码` root=`根目录` write_path=`写入路径` text=`文本` commit=`提交` profile=`配置`*
|
||||
|
||||
## 单步
|
||||
+ `任务`
|
||||
+ `写回`=真
|
||||
+ `流式`=假
|
||||
+ `打印增量`=假
|
||||
+ `沙盒`=假
|
||||
+ `沙盒配置`=default
|
||||
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 *map*(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
|
||||
|
||||
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
|
||||
流式=真 时走 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=`任务`**
|
||||
`user_turn` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| user | `任务` |
|
||||
|
||||
> agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
1. `流式`
|
||||
@@ -134,9 +156,11 @@ import json:lib/json.mq.md
|
||||
**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`**
|
||||
`out` =
|
||||
|
||||
| status | task | decision |
|
||||
|--------|------|----------|
|
||||
| ok | `任务` | `decision` |
|
||||
|
||||
1. `tool_name`
|
||||
**tool_out = > 运行工具 工具=`tools` 名=`tool_name`**
|
||||
@@ -144,8 +168,8 @@ import json:lib/json.mq.md
|
||||
**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`**
|
||||
**out = table.put in=`out` at="status" value="error"**
|
||||
**out = table.put in=`out` at="error" value=`tool_s`**
|
||||
**reply = tool_s**
|
||||
2. *
|
||||
**task_s = > json.stringify value=`任务`**
|
||||
@@ -161,16 +185,25 @@ import json:lib/json.mq.md
|
||||
**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`**
|
||||
**out = table.put in=`out` at="tool" value=`tool_name`**
|
||||
**out = table.put in=`out` at="tool_result" value=`tool_s`**
|
||||
**out = table.put in=`out` at="result" value=`reply`**
|
||||
2. *
|
||||
**out = > json.set map=`out` key="result" value=`reply`**
|
||||
**out = table.put in=`out` at="result" value=`reply`**
|
||||
|
||||
**as_turn = > json.parse text={"role":"assistant"}**
|
||||
**as_turn = > json.set map=`as_turn` key="content" value=`reply`**
|
||||
`as_turn` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| assistant | `reply` |
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `沙盒`
|
||||
**配置行 = sandbox.profile name=`沙盒配置`**
|
||||
**out = table.put in=`out` at="sandbox_profile" value=`配置行`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
1. `写回`
|
||||
**body = > json.stringify value=`out`**
|
||||
**st = > json.get value=`out` key="status"**
|
||||
@@ -296,14 +329,17 @@ Engineering First Information 门闩。转发 `agent.preflight`。
|
||||
+ `强制`=False
|
||||
+ `路由`=auto
|
||||
+ `路由模型`=None
|
||||
+ `沙盒`=False
|
||||
+ `沙盒配置`=default
|
||||
+ `工程预检`=True
|
||||
|
||||
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。
|
||||
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。`沙盒=真` 走 CoW 试跑;`工程预检` 对应 `efi`。
|
||||
|
||||
**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.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型`*
|
||||
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型` sandbox=`沙盒` sandbox_profile=`沙盒配置` efi=`工程预检`*
|
||||
|
||||
## 路由
|
||||
+ `任务`
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: ext/ai/沙盒
|
||||
description: >-
|
||||
AI 试跑 CoW 工作区:打开 / 运行 / 差异 / 提交(中文面,委托英文 sandbox 模块)。
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
---
|
||||
|
||||
## 打开
|
||||
+ `根`=None
|
||||
|
||||
*> sandbox.open root=`根`*
|
||||
|
||||
## 写入
|
||||
+ `id`
|
||||
+ `路径`
|
||||
+ `文本`
|
||||
|
||||
*> sandbox.write id=`id` path=`路径` text=`文本`*
|
||||
|
||||
## 读取
|
||||
+ `id`
|
||||
+ `路径`
|
||||
|
||||
*> sandbox.read id=`id` path=`路径`*
|
||||
|
||||
## 删除
|
||||
+ `id`
|
||||
+ `路径`
|
||||
|
||||
*> sandbox.remove id=`id` path=`路径`*
|
||||
|
||||
## 差异
|
||||
+ `id`
|
||||
|
||||
*> sandbox.diff id=`id`*
|
||||
|
||||
## 提交
|
||||
+ `id`
|
||||
|
||||
*> sandbox.commit id=`id`*
|
||||
|
||||
## 丢弃
|
||||
+ `id`
|
||||
|
||||
*> sandbox.discard id=`id`*
|
||||
|
||||
## 运行
|
||||
+ `id`
|
||||
+ `源码`=None
|
||||
+ `路径`=None
|
||||
|
||||
1. `源码`
|
||||
*> sandbox.run id=`id` source=`源码`*
|
||||
2. `路径`
|
||||
*> sandbox.run id=`id` path=`路径`*
|
||||
3. *
|
||||
> print text=沙盒.运行: 需要 源码= 或 路径=
|
||||
> sys.exit code=1
|
||||
|
||||
## 检查
|
||||
+ `id`
|
||||
|
||||
*> sandbox.inspect id=`id`*
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/cache
|
||||
description: Cache Resource (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -27,7 +28,7 @@ Key–value cache. Use `memory:` for in-process (tests / single process) or `red
|
||||
## get
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_get url=`url` key=`key`*
|
||||
|
||||
## set
|
||||
@@ -37,24 +38,24 @@ Key–value cache. Use `memory:` for in-process (tests / single process) or `red
|
||||
|
||||
Optional `ttl` is seconds until expiry.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`*
|
||||
|
||||
## del
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_del url=`url` key=`key`*
|
||||
|
||||
## exists
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_exists url=`url` key=`key`*
|
||||
|
||||
## ttl
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_ttl url=`url` key=`key`*
|
||||
|
||||
+32
-31
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/db
|
||||
description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -30,7 +31,7 @@ Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` /
|
||||
|
||||
Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_init url=`url` name=`name` fields=`fields`*
|
||||
|
||||
## insert
|
||||
@@ -38,7 +39,7 @@ Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引
|
||||
+ `rows`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
|
||||
|
||||
## select
|
||||
@@ -50,9 +51,9 @@ Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引
|
||||
|
||||
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
||||
*[rows](r)*
|
||||
*[rows](access(r, "rows"))*
|
||||
|
||||
## paginate
|
||||
+ `table`
|
||||
@@ -64,7 +65,7 @@ Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作
|
||||
|
||||
Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10).
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`*
|
||||
|
||||
## get
|
||||
@@ -72,7 +73,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `id`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## update
|
||||
@@ -81,7 +82,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `row`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
||||
|
||||
## delete
|
||||
@@ -89,7 +90,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `id`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## exec
|
||||
@@ -97,7 +98,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `args`=None
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## query
|
||||
@@ -107,7 +108,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
|
||||
Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## count
|
||||
@@ -117,16 +118,16 @@ Run bare SQL and return the result set — count / join / group / subqueries. Re
|
||||
|
||||
Count rows matching a `where` filter (same syntax as `select`). Returns a number.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`**
|
||||
*[count](r)*
|
||||
*[count](access(r, "count"))*
|
||||
|
||||
## migrate
|
||||
+ `steps`
|
||||
|
||||
Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_migrate url=`url` steps=`steps`*
|
||||
|
||||
## fts
|
||||
@@ -136,7 +137,7 @@ Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` ta
|
||||
|
||||
Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`*
|
||||
|
||||
## search
|
||||
@@ -147,7 +148,7 @@ Create an FTS5 index on `table` for the listed content columns (CSV string or li
|
||||
|
||||
Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`*
|
||||
|
||||
## 事务
|
||||
@@ -156,7 +157,7 @@ Begin a transaction: borrows the pooled connection exclusively and returns a
|
||||
`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back).
|
||||
Every statement runs on the same connection, so a batch is atomic.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_begin url=`url`*
|
||||
|
||||
# txn
|
||||
@@ -172,8 +173,8 @@ connection; finish with `提交` or `回滚`.
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
|
||||
|
||||
## select
|
||||
@@ -184,17 +185,17 @@ connection; finish with `提交` or `回滚`.
|
||||
|
||||
Same filters as `db.select`; runs inside the transaction.
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
||||
*[rows](r)*
|
||||
*[rows](access(r, "rows"))*
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## update
|
||||
@@ -202,37 +203,37 @@ Same filters as `db.select`; runs inside the transaction.
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## 提交
|
||||
|
||||
Commit the transaction and return its connection to the pool.
|
||||
|
||||
**txn = [txn](self)**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_commit txn=`txn`*
|
||||
|
||||
## 回滚
|
||||
|
||||
Roll the transaction back (undo every write) and return its connection.
|
||||
|
||||
**txn = [txn](self)**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_rollback txn=`txn`*
|
||||
|
||||
+2
-1
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/form
|
||||
description: Form Resource — fields, validate, submit (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -62,6 +63,6 @@ Localized submit / cancel copy for rendered forms.
|
||||
+ `data`
|
||||
+ `db`
|
||||
|
||||
**url = [url](db)**
|
||||
**url = [url](access(db, "url"))**
|
||||
*> web_form_submit form=`self` data=`data` url=`url`*
|
||||
|
||||
Loaded 100 of 312 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user