Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ae97891266 | ||
|
|
aea86746e7 | ||
|
|
c773503938 | ||
|
|
939e23ee88 | ||
|
|
687c168014 | ||
|
|
eac9b45263 | ||
|
|
74b298e80d | ||
|
|
fc7097bae4 | ||
|
|
b624084745 | ||
|
|
0bbe735c3c | ||
|
|
92de46aca4 | ||
|
|
8bbe017a5e | ||
|
|
1a13989230 | ||
|
|
5ad1a07f5c | ||
|
|
bcfc763ba4 | ||
|
|
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 |
No files matched your search
@@ -144,7 +144,7 @@ Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compli
|
||||
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
|
||||
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
|
||||
|
||||
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
Browser client programs: prefer nested `import:` with `browser: lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
@@ -186,7 +186,7 @@ When editing a file full of `json.set`:
|
||||
1. Turn static structures into GFM tables.
|
||||
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
|
||||
3. Leave at most sparse `table.put` for dynamic keys.
|
||||
4. Drop `import json:…` if unused.
|
||||
4. Drop unused `json:` (or other) entries under nested `import:`.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
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. Read collections with **`[key](map)`**, not footnote indexes for new code. **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.
|
||||
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.
|
||||
|
||||
@@ -49,21 +49,31 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `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`) |
|
||||
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | 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] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| GFM table after empty RHS bind | Collection; get with `access(coll, "key")` (legacy `` `m`[^key] `` remains available) |
|
||||
| `- [item](遍历 coll 为 item)` | Foreach |
|
||||
| `` ```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.1.0)
|
||||
|
||||
Occlusion is the default syntax. Shipped source declares `markup: occlusion` (or `标记: 遮蔽`) explicitly so imports stay deterministic. Legacy `[key](collection)` requires `markup: classic` or the one-cycle CLI flag `--legacy-markup`; `MARQDO_MARKUP` does not change parsing.
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `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 . --mark --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
@@ -125,13 +135,14 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
Imports use nested YAML `import:` (`导入:` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
import text:lib/text.mq.md
|
||||
import clock:lib/time.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
clock: lib/time.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -141,7 +141,8 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
|
||||
```markdown
|
||||
---
|
||||
import browser:lib/browser.mq.md
|
||||
import:
|
||||
browser: lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -168,7 +169,8 @@ Return and soft-error packs are **tables**, not `json.set` pipelines. Full style
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
@@ -217,7 +219,8 @@ Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains whe
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -230,8 +233,9 @@ import text:lib/text.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
import:
|
||||
re: lib/re.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -246,8 +250,9 @@ import enc:lib/encoding.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
import:
|
||||
log: lib/log.mq.md
|
||||
uuid: lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -278,7 +283,8 @@ After a blank line, code runs:
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -326,7 +332,8 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/agent.mq.md
|
||||
import:
|
||||
agent: ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -378,8 +385,9 @@ if x > 0:
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import web:ext/web/web.mq.md
|
||||
import db:db/index.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -416,7 +424,8 @@ import db:db/index.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -445,7 +454,8 @@ import quantum:ext/quantum/quantum.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -122,7 +122,8 @@ Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -141,7 +142,8 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
|
||||
|
||||
```markdown
|
||||
---
|
||||
import foreign:lib/foreign.mq.md
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -126,9 +126,14 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.1.0**:文件级 Occlusion 默认语义——全仓迁移 · `migrate labels --mark` · `access` / `遍历` · 可执行知识语义投影
|
||||
- **v2.1.0**: File-scoped Occlusion by default — corpus migration, `migrate labels --mark`, `access` / `for`, executable-knowledge projections
|
||||
- **v2.1.0 ext**:扩展包同步 2.1.0 / Ext pack 2.1.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.1 ext**:扩展包同步 1.5.1 / Ext pack 1.5.1
|
||||
- **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
|
||||
|
||||
+10
@@ -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/
|
||||
|
||||
+91
-1
@@ -1,13 +1,103 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
## 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 行构成。
|
||||
|
||||
## v2.1.0 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
|
||||
|
||||
### Added
|
||||
|
||||
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
|
||||
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
|
||||
|
||||
### Changed
|
||||
|
||||
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
## 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
|
||||
|
||||
Generated
+14
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.5.0"
|
||||
version = "2.1.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.5.0"
|
||||
version = "2.1.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",
|
||||
]
|
||||
|
||||
+4
-3
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.5.1"
|
||||
version = "2.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -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
|
||||
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -31,13 +31,94 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
|
||||
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
|
||||
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
|
||||
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
|
||||
|
||||
---
|
||||
|
||||
## 链接语法:链接即调用(v2.1 设计声明)
|
||||
|
||||
> **这是 v2.1 的可执行知识模型。**
|
||||
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
|
||||
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
|
||||
|
||||
### 两文档,一次类调用
|
||||
|
||||
知识文档 `libai.mq.md`:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- `# 李白` = 类;
|
||||
- `## 李白的出生年份` = 函数;
|
||||
- `*701*` = 返回值。
|
||||
|
||||
调用文档 `main.mq.md`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
|
||||
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`:
|
||||
|
||||
```markdown
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 四条语义
|
||||
|
||||
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
|
||||
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
|
||||
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
|
||||
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
|
||||
|
||||
### 现状与目标
|
||||
|
||||
| 能力 | v2.0.0 | v2.1 |
|
||||
|------|-------------|-----------|
|
||||
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
|
||||
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
|
||||
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
|
||||
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
|
||||
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
|
||||
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
|
||||
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
|
||||
| `links.lock` 可复现 | ❌ | ✅ 可选 |
|
||||
|
||||
### 知识分层:本体 → 知识个体 → 调用面
|
||||
|
||||
| 层 | 写法 | 语义 |
|
||||
|----|------|------|
|
||||
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
|
||||
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
|
||||
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
|
||||
|
||||
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
|
||||
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
|
||||
|
||||
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
|
||||
|
||||
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
|
||||
|
||||
---
|
||||
|
||||
## 愿景与期许
|
||||
|
||||
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
|
||||
@@ -45,7 +126,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
|
||||
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
|
||||
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
|
||||
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
@@ -64,24 +145,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.3)
|
||||
## 语法速览
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
|
||||
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
|
||||
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
|
||||
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
|
||||
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
|
||||
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
|
||||
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
|
||||
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
|
||||
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
@@ -116,6 +203,51 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 工程习惯:允许申报未完成,但不允许假装完成
|
||||
|
||||
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
|
||||
而欠账是可见、可数、可结算的(而不是假装完成):
|
||||
|
||||
```markdown
|
||||
## 检索资料
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
|
||||
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
|
||||
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
|
||||
|
||||
**四条约定**
|
||||
|
||||
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
|
||||
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
|
||||
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
|
||||
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
|
||||
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
|
||||
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels --count # 内置口径:还有多少未完成
|
||||
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
|
||||
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
|
||||
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
@@ -149,10 +281,11 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.5.1)
|
||||
## 现状(v2.1.0)
|
||||
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin · 扩展包同步 **1.5.1**
|
||||
- **外联 v2 / view 交互单元(v1.5.0)**:结构化 invoke · JSON call/call_many · 并行扇出 · Python/Node 持久内核 · 显式状态桥 · cell 单步/Run All/内核切换 · `foreign.session` 句柄 · 无 `会话` 时无状态 cells · 清除输出 API · 高对比浅深主题;扩展包同步 **1.5.0**
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock) · 扩展包同步 **2.1.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)
|
||||
@@ -186,7 +319,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.5.1)
|
||||
### 如何使用最新 Marqdo(v2.1.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -201,7 +334,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.5.1 # 或留在 main
|
||||
git checkout v2.1.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -240,7 +373,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.5.1
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.1.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.5.1"
|
||||
version = "2.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
|
||||
serde_json = "1"
|
||||
serde_json = "1"
|
||||
Vendored
+37
@@ -1,3 +1,40 @@
|
||||
marqdo (2.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
|
||||
standard/extension libraries and executable-knowledge projections.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
|
||||
|
||||
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,
|
||||
|
||||
@@ -13,6 +13,8 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
|
||||
@@ -105,6 +107,21 @@
|
||||
| [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**(规划) |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
|
||||
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [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 静默丢失 …) |
|
||||
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
|
||||
| [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 的所有验证结论。
|
||||
@@ -36,7 +36,8 @@ type: llm
|
||||
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
api_key: ${secret.OPENAI_API_KEY!}
|
||||
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
|
||||
import sys:lib/sys.mq.md
|
||||
import:
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -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. 循环的新写法你倾向哪一种:
|
||||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||||
- `- [篮子里的果子](篮子 → 果)`
|
||||
- 保留 `- [果](篮子)` 作短形
|
||||
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -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` 引擎),
|
||||
而不是继续在特性内部找"重复"——那已经找完了。
|
||||
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Draft · v2.1 语义重构** |
|
||||
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
|
||||
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
|
||||
|
||||
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
|
||||
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
|
||||
源位置、输入/输出、依赖和影响范围。
|
||||
|
||||
```text
|
||||
代码投影: eval([名称](载荷)) = eval(载荷)
|
||||
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
|
||||
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
|
||||
```
|
||||
|
||||
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
|
||||
三者同源,才是代码即文档、文档即知识、知识即可执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 统一节点:`Named<T>`
|
||||
|
||||
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
|
||||
|
||||
```text
|
||||
Named<T> { label, inner: T, span }
|
||||
```
|
||||
|
||||
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
|
||||
|
||||
| 既有位置 | `T` | 示例 | 知识角色 |
|
||||
|---|---|---|---|
|
||||
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
|
||||
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
|
||||
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
|
||||
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
|
||||
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
|
||||
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
|
||||
|
||||
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
|
||||
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
|
||||
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
|
||||
|
||||
### 1.1 每个节点都有角色,而不是两套语法
|
||||
|
||||
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
|
||||
|
||||
| role | 如何识别 | `check` 应问什么 |
|
||||
|---|---|---|
|
||||
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
|
||||
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
|
||||
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
|
||||
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
|
||||
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
|
||||
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
|
||||
|
||||
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
|
||||
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
|
||||
|
||||
---
|
||||
|
||||
## 2. 知识层不是目录隔离,而是同一图的不同投影
|
||||
|
||||
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
|
||||
同一份 `.mq.md` 可以同时有多层节点。
|
||||
|
||||
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|
||||
|---|---|---|---|
|
||||
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
|
||||
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
|
||||
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
|
||||
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
|
||||
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
|
||||
|
||||
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
|
||||
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
|
||||
这正是通用语法本身兼容知识体系的含义。
|
||||
|
||||
### 2.1 `#` / `##` 的位置
|
||||
|
||||
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
|
||||
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
|
||||
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
|
||||
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
|
||||
|
||||
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
|
||||
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
|
||||
`[]()` 是知识单元的内部结构。
|
||||
|
||||
---
|
||||
|
||||
## 3. 大项目的寻址:可读短名与稳定身份同时成立
|
||||
|
||||
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
|
||||
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
|
||||
|
||||
1. 文件的既有 frontmatter `id` 是稳定身份;
|
||||
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
|
||||
3. `#` / `##` 是人可读的路径段;
|
||||
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: knowledge.people.li-bai
|
||||
import:
|
||||
li_bai: knowledge/people/li-bai.mq.md
|
||||
---
|
||||
|
||||
# 回答
|
||||
|
||||
**year = [李白的出生年份](li_bai.李白.出生年份)**
|
||||
李白出生于[公元 701 年](李白.出生年份)。
|
||||
```
|
||||
|
||||
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
|
||||
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
|
||||
而是可读的查询,必须由 lock 固化。
|
||||
|
||||
---
|
||||
|
||||
## 4. 每个 `[]()` 产生统一的知识记录
|
||||
|
||||
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
|
||||
"inputs": ["订单.行"],
|
||||
"outputs": ["行"],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
此记录就是统一知识图节点:
|
||||
|
||||
- 本地取元有输入/类型边;
|
||||
- 纯计算有输入/输出/公式边;
|
||||
- 循环有集合、变量绑定和循环体边;
|
||||
- 调用有 `calls`/`uses` 边;
|
||||
- 有来源的事实再增加 `derived_from` 边;
|
||||
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
|
||||
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
|
||||
|
||||
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
|
||||
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
|
||||
|
||||
---
|
||||
|
||||
## 5. 闭环:写、跑、看、查、变
|
||||
|
||||
```text
|
||||
作者写 Named<T>
|
||||
│
|
||||
├─ run:擦除 label,按原语义执行
|
||||
├─ view:显示 label,可展开值、输入、步骤和来源
|
||||
└─ check:解析所有依赖,编译统一知识图
|
||||
│
|
||||
catalog / lock / context pack
|
||||
│
|
||||
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
|
||||
│
|
||||
作者或 agent 修复后重新 check/verify
|
||||
```
|
||||
|
||||
### 5.1 命令边界
|
||||
|
||||
| 操作 | 做什么 | 不做什么 |
|
||||
|---|---|---|
|
||||
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
|
||||
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
|
||||
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
|
||||
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
|
||||
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
|
||||
|
||||
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施顺序
|
||||
|
||||
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
|
||||
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
|
||||
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
|
||||
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
|
||||
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
|
||||
|
||||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|
||||
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
|
||||
|
||||
```markdown
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
import:
|
||||
plugin: lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -159,11 +159,12 @@ REPLACE
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import subtask:lib/subtask.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
subtask: lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 智能体:ext/ai/智能体.mq.md
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
导入 时间:lib/时间.mq.md
|
||||
导入:
|
||||
智能体: ext/ai/智能体.mq.md
|
||||
大模型: ext/ai/大模型.mq.md
|
||||
自写回: lib/自写回.mq.md
|
||||
时间: lib/时间.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
|
||||
@@ -197,7 +197,8 @@
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
@@ -201,8 +201,9 @@ $$
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -20,7 +20,8 @@ Import:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -101,7 +101,8 @@ marqdo ext add quantum
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
@@ -341,7 +342,8 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
@@ -62,8 +62,9 @@ route: /
|
||||
method: GET
|
||||
data_source: posts
|
||||
data_order: -created_at
|
||||
import web:ext/web/web.mq.md
|
||||
import data:ext/data/db.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
data: ext/data/db.mq.md
|
||||
---
|
||||
|
||||
# Marqdo
|
||||
@@ -106,7 +107,8 @@ path: /api/posts
|
||||
request: json
|
||||
response: json
|
||||
auth: member
|
||||
import data:ext/data/db.mq.md
|
||||
import:
|
||||
data: ext/data/db.mq.md
|
||||
---
|
||||
|
||||
**post = > data.db.insert …**
|
||||
|
||||
@@ -49,7 +49,8 @@
|
||||
英文:
|
||||
|
||||
```markdown
|
||||
import web:ext/web/web.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
|
||||
# main
|
||||
|
||||
|
||||
@@ -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 产物与解析
|
||||
|
||||
|
||||
+16
-14
@@ -128,13 +128,14 @@ myapp/
|
||||
---
|
||||
title: web-site
|
||||
description: Home = page table; main may be inline; class methods assemble.
|
||||
import web:ext/web/web.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
shell: styles/shell.mq.md
|
||||
nav: components/nav.mq.md
|
||||
side: components/side.mq.md
|
||||
foot: components/foot.mq.md
|
||||
articles: db/articles.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -171,13 +172,14 @@ Main content is not a reusable component, so it is authored here.
|
||||
```markdown
|
||||
---
|
||||
title: 站点
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
shell: styles/shell.mq.md
|
||||
nav: components/nav.mq.md
|
||||
side: components/side.mq.md
|
||||
foot: components/foot.mq.md
|
||||
articles: db/articles.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -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,443 @@
|
||||
# 知识分层:原始语料、可执行知识、调用面
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
|
||||
| 日期 | 2026-10-23 |
|
||||
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
|
||||
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
|
||||
| 示例 | [examples/knowledge-layers/](../../examples/knowledge-layers/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论先行
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
> **分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 `#`/`= >` 语法。**
|
||||
> 如果「实例化」指**知识个体**,用 `# 李白 = > 诗人` 编码即可,零新语法;
|
||||
> 如果「实例化」指**运行时对象**,就需要新的可寻址实例声明/注册表,语法成本明显更高。
|
||||
|
||||
### 0.2 三层 / 四层:推荐四层
|
||||
|
||||
| 层 | 名称 | 内容 | 语法载体 |
|
||||
|----|------|------|---------|
|
||||
| **L0** | 原始语料 | 原文、出处、引用、版本 | `.md` / `.mq.md` 叙述 + `来源` 表 |
|
||||
| **L1** | 本体 / 模式 | 类、字段、类型、约束 | `# 诗人` + 字段/类型表 |
|
||||
| **L2** | 可执行知识 | 知识个体、事实、返回值、出处 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` |
|
||||
| **L3** | 调用面 | 链接、类调用、view、LinkInfo、EKC、agent | `[出生年份](李白.出生年份)` |
|
||||
|
||||
三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把**本体**与**个体**分开,正好对应 EKC 的 schema/knowledge 分层。
|
||||
|
||||
### 0.3 核心判断
|
||||
|
||||
| 判断 | 结论 |
|
||||
|------|------|
|
||||
| 原始语料 → 可执行知识 → 调用面,逻辑成立 | ✅ |
|
||||
| 可执行知识能还原/验证回原始语料 | ✅ 需要出处/校验约定,语法上可行 |
|
||||
| `# 诗人` 是类 | ✅ 现有 `#` 语义 |
|
||||
| `# 李白 = > 诗人` 是「实例化」 | ⚠️ **语法上是继承/特化,不是运行时实例化** |
|
||||
| `李白.出生年份` 是类调用 | ✅ 需要类函数 + 项目类索引(v2.1 目标) |
|
||||
| `[]()` 是调用面,不新增语法 | ✅ `[描述](类.函数)` = 描述 + 已有调用 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 你的模型(精确复述)
|
||||
|
||||
1. 有一个**诗人**类(`# 诗人`),定义诗人应该有什么字段/函数;
|
||||
2. 用**李白的知识**把这个类「实例化」:
|
||||
- 李白是诗人;
|
||||
- 李白有姓名、出生年份等事实;
|
||||
3. 通过 `[]()` 链接语法调用这个知识:
|
||||
- `[出生年份](李白.出生年份)`;
|
||||
4. 整个体系分层:
|
||||
- 原始语料;
|
||||
- 改写/抽象后的可执行知识(可还原验证回原始知识);
|
||||
- 智能体回答/思考时的调用面。
|
||||
|
||||
这个模型在**知识架构**上没有问题;问题只在第 2 步的「实例化」如何落到语法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前语法事实
|
||||
|
||||
| 语法 | 当前语义 | 对模型的影响 |
|
||||
|------|---------|-------------|
|
||||
| `# 诗人` | 类/类型;正文是构造体 | ✅ 可做本体 |
|
||||
| `# 李白 = > 诗人` | **继承/子类**;不是实例 | ⚠️ 与「实例化」字面不符 |
|
||||
| `## 李白的出生年份` | 方法;可用 `self`/`自` | ⚠️ 当前是实例方法 |
|
||||
| `> 李白` | 构造实例(map + `_type`) | ✅ 运行时实例 |
|
||||
| `李白.李白的出生年份` | 当前被当变量/实例方法路径 | ❌ 类调用未实现 |
|
||||
| `[描述](...)` | 描述 + 表达式 | ✅ 调用面 |
|
||||
| `import` | 跨文档绑定 | ⚠️ 当前跨文档继承/调用需 import |
|
||||
|
||||
**实测**(`marqdo 2.0.0`):
|
||||
|
||||
- `# 李白 = > 诗人` 在**另一个文档**定义 `# 诗人` 时,未 import 会报 `unknown base type 诗人`;
|
||||
- import 后可以继承,但调用仍需 `> libai.李白` 构造实例,再 `` `li`.李白的出生年份() `` → `701`;
|
||||
- `李白.李白的出生年份` 直接调用报 `undefined variable`;
|
||||
- 跨文档类索引不存在。
|
||||
|
||||
所以「诗人类 → 李白实例 → 链接调用」在**目标模型**上成立,在**当前语法**上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 自洽性检查:逐层
|
||||
|
||||
### 3.1 L0 原始语料
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| 原始语料是否可执行? | 否;它是出处,不是程序 |
|
||||
| 能否被引用? | ✅ 现有 Markdown 相对链接/`来源` 表 |
|
||||
| 能否保留原文? | ✅ 叙述、引用块、表格 |
|
||||
| 语法负担 | 零:就是现有文档 |
|
||||
|
||||
**要点**:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要**物理/逻辑分离**(`corpus/` vs `knowledge/`)。
|
||||
|
||||
### 3.2 L1 本体 / 模式
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 姓名 | text | 诗人姓名 |
|
||||
| 出生年份 | number | 公元年份 |
|
||||
```
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
|
||||
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
|
||||
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
|
||||
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
|
||||
|
||||
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
|
||||
|
||||
### 3.3 L2 可执行知识:关键歧义
|
||||
|
||||
「用李白的知识实例化诗人」有两种落法:
|
||||
|
||||
#### A. 单体知识类(推荐)
|
||||
|
||||
```markdown
|
||||
# 李白 = > 诗人
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- 语法:`# 李白 = > 诗人` = 继承/特化;
|
||||
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
|
||||
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
|
||||
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
|
||||
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
|
||||
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
|
||||
|
||||
#### B. 运行时实例(不推荐作为 v2.1 语法)
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
## 李白
|
||||
|
||||
*> 诗人 姓名="李白" 出生年份=701*
|
||||
```
|
||||
|
||||
- 语法:`## 李白` 是函数,返回一个实例 map;
|
||||
- 调用:`李白().出生年份`(函数返回实例,再取方法);
|
||||
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
|
||||
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
|
||||
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
|
||||
|
||||
#### C. 显式个体声明(未来可选)
|
||||
|
||||
```markdown
|
||||
# 李白 : 诗人
|
||||
```
|
||||
|
||||
- `:` 明确「李白是诗人个体」;
|
||||
- 语法更贴近本体(instance-of),但**新增一个标记**;
|
||||
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
|
||||
- 不建议 v2.1 引入;可作为 v2.2 的候选。
|
||||
|
||||
### 3.4 L3 调用面
|
||||
|
||||
```markdown
|
||||
[出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
|
||||
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
|
||||
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
|
||||
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
|
||||
| 终端输出? | 代码链接 + `print` |
|
||||
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
|
||||
| view 能否显示调用点? | 需要新增(工具,不是语法) |
|
||||
|
||||
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 推荐模型:单体知识类
|
||||
|
||||
### 4.1 定义
|
||||
|
||||
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 姓名 | text | 诗人姓名 |
|
||||
| 出生年份 | number | 公元年份 |
|
||||
|
||||
# 李白 = > 诗人
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|------|------|------|
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
调用:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 4.2 为什么推荐 A
|
||||
|
||||
| 维度 | A 单体类 | B 运行时实例 |
|
||||
|------|---------|-------------|
|
||||
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
|
||||
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
|
||||
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
|
||||
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
|
||||
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
|
||||
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
|
||||
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
|
||||
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
|
||||
|
||||
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
|
||||
|
||||
### 4.3 术语约定
|
||||
|
||||
| 术语 | 含义 | 语法 |
|
||||
|------|------|------|
|
||||
| **类 / 本体** | 诗人的模式 | `# 诗人` |
|
||||
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
|
||||
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
|
||||
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
|
||||
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
|
||||
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
|
||||
|
||||
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
|
||||
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
|
||||
|
||||
### 4.4 多诗人怎么办
|
||||
|
||||
```markdown
|
||||
# 李白 = > 诗人
|
||||
# 杜甫 = > 诗人
|
||||
# 王维 = > 诗人
|
||||
```
|
||||
|
||||
- 每个个体是一个单体类;项目类索引登记它们;
|
||||
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
|
||||
- 这是「命名个体注册表」,不是运行时实例集合;
|
||||
- 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 EKC 的映射
|
||||
|
||||
| 层 | EKC 层 | 节点/边 |
|
||||
|----|--------|---------|
|
||||
| L0 原始语料 | Repository / sources | `documented_by` / `derived_from` |
|
||||
| L1 本体 | Capability / Schema | `# 诗人` class 节点 |
|
||||
| L2 知识个体 | Knowledge / Symbol | `# 李白` class 节点 + `##` fact 节点;`specializes` 边 → `诗人` |
|
||||
| L3 调用面 | Symbol / Capability | `[]()` 链接 → `calls` 边;LinkInfo |
|
||||
| L4 Agent | Agent / Context Pack | `find`/`reuse`/`link.resolve` |
|
||||
|
||||
**新增边(建议)**:
|
||||
|
||||
- `specializes`:`# 李白 = > 诗人`(语法上是继承;知识语义上是 is-a);
|
||||
- `derived_from`:fact → 原始语料;
|
||||
- `calls`:调用文档 → `李白.出生年份`;
|
||||
- `has_fact`:`# 李白` → `## 出生年份`。
|
||||
|
||||
EKC 现有 `depends_on`/`uses`/`implements`/`documented_by` 可以复用;`specializes` 建议新增。
|
||||
|
||||
---
|
||||
|
||||
## 6. 还原 / 验证(L2 → L0)
|
||||
|
||||
「可执行知识能还原验证回原始知识」需要三件事:
|
||||
|
||||
### 6.1 出处是数据,不是注释
|
||||
|
||||
```markdown
|
||||
## 李白的出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|------|------|------|
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- `来源` 列指向原始语料(路径 + 标题/锚点);
|
||||
- 也可以放 frontmatter `sources:`;
|
||||
- `check` 验证来源存在;`verify` 验证值/引文一致(能自动化的部分)。
|
||||
|
||||
### 6.2 可还原的渲染
|
||||
|
||||
- `view` 把 `# 李白` 渲染成「知识文档」:字段 + 值 + 来源;
|
||||
- `catalog` 生成 OKF `Fact` 页,`resource:` 指向 `.mq.md`;
|
||||
- 渲染结果与原始语料可人工/机器对照;
|
||||
- 这不是新语法,是 view/catalog 的输出。
|
||||
|
||||
### 6.3 漂移检查
|
||||
|
||||
| 诊断 | 触发 |
|
||||
|------|------|
|
||||
| `knowledge.source_missing` | 事实没有来源 |
|
||||
| `knowledge.source_dangling` | 来源路径/锚点不存在 |
|
||||
| `knowledge.value_mismatch` | 事实值与来源引文不一致(可自动判断时) |
|
||||
| `knowledge.schema_mismatch` | `# 李白` 字段与 `# 诗人` 不匹配 |
|
||||
| `knowledge.fact_drift` | 原始语料变了,知识未复核 |
|
||||
|
||||
这些是**工具诊断**,不是语法。
|
||||
|
||||
---
|
||||
|
||||
## 7. 调用面:智能体如何使用
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
- `view` 显示:`李白.李白的出生年份` → `701` → 来源 `corpus/libai.md#出生年份`;
|
||||
- `check --json` 返回 LinkInfo(class/function/value/source);
|
||||
- agent 通过 `link.resolve` / `find` 取到值 + 出处,回答时可引用来源;
|
||||
- `run` 加 `print` 才输出;正文链接不执行,保证叙述安全。
|
||||
|
||||
**这就是「调用面」**:不是自然语言猜,而是可解析、可验证、可引用的类调用。
|
||||
|
||||
---
|
||||
|
||||
## 8. 反例与边界
|
||||
|
||||
| 场景 | 用 A 单体类 | 说明 |
|
||||
|------|-----------|------|
|
||||
| 李白、杜甫、王维 | 三个单体类 | 类索引;命名个体 |
|
||||
| 同一诗人的多个版本 | 多个事实/来源,或子个体 | 版本是事实维度,不是实例 |
|
||||
| 需要运行时状态(可变对象) | `> 李白` 构造实例 | 运行时实例仍存在,但与知识个体分离 |
|
||||
| 上千个诗人 | 类索引/表驱动注册 | v2.2 优化;语法不变 |
|
||||
| 需要 `instanceof` | `# 李白 = > 诗人` 的 `specializes` 边 | 知识语义;不是运行时 `_type` |
|
||||
| 需要多继承 | 现有不支持 | 不在本设计范围 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决策建议
|
||||
|
||||
1. **v2.1 采用 A(单体知识类)**:`# 诗人` + `# 李白 = > 诗人` + `##` 事实 + `[]()` 类调用;零新语法。
|
||||
2. **术语冻结**:`# 李白 = > 诗人` 叫「知识个体/单体类」,不叫「实例」;`> 诗人` 才是运行时实例。
|
||||
3. **补类函数与类索引**:不使用 `self` 的 `##` 是类函数;项目类索引解析跨文档 `李白`。
|
||||
4. **补出处/验证**:`来源` 列或 `sources:`;`check`/`verify`;`view`/`catalog` 可还原。
|
||||
5. **EKC 边**:`specializes` / `derived_from` / `calls` / `has_fact`。
|
||||
6. **保留 B/C 作为未来**:如果真需要运行时实例/个体声明,再评估 `# 李白 : 诗人` 或实例注册表;不在 v2.1 引入。
|
||||
|
||||
### 9.1 备选:frontmatter 个体声明(零语法,但换元数据)
|
||||
|
||||
如果不想把 `= >` 的继承语义借给「个体」,可以用 frontmatter 标记:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: Individual
|
||||
class: 诗人
|
||||
id: libai
|
||||
---
|
||||
|
||||
# 李白
|
||||
|
||||
## 出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
| 维度 | 单体类 A | frontmatter 个体 |
|
||||
|------|----------|------------------|
|
||||
| 可见性 | `# 李白 = > 诗人` 一眼可见 | 类型在 frontmatter,正文只看到 `# 李白` |
|
||||
| 语法 | 现有 `= >` | 现有 frontmatter,无新标记 |
|
||||
| 语义纯度 | 继承/特化 | 明确 individual-of |
|
||||
| EKC | class + specializes | individual + instance_of |
|
||||
| 代价 | 术语「个体」不是「实例」 | 两套 is-a 表达(`= >` 与 `class:`)需要约定 |
|
||||
|
||||
**建议**:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter `type: Individual`,并规定「`= >` 只用于类-类,个体用 frontmatter」。
|
||||
|
||||
---
|
||||
|
||||
## 10. 结论
|
||||
|
||||
> **三层/四层模型自洽;「实例化」是唯一需要修正的词。**
|
||||
> 在 Marqdo 的语法里,`# 李白 = > 诗人` 是**继承/特化**,不是运行时实例;
|
||||
> 把它用作**单体知识类**,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、`李白.出生年份` 可调用」。
|
||||
> 这正是 EKC 的「文档即知识、知识可执行」:**类是本体的地址,单体类是知识个体的地址,`[]()` 是调用面。**
|
||||
|
||||
---
|
||||
|
||||
## 附录 A:一页对照
|
||||
|
||||
```markdown
|
||||
# L1 本体
|
||||
# 诗人
|
||||
| 字段 | 类型 | 说明 |
|
||||
| 姓名 | text | ... |
|
||||
| 出生年份 | number | ... |
|
||||
|
||||
# L2 知识个体(单体类)
|
||||
# 李白 = > 诗人
|
||||
## 李白的出生年份
|
||||
| 返回 | 类型 | 来源 |
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
*701*
|
||||
|
||||
# L3 调用面
|
||||
[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
| 层 | 语法 | 语义 |
|
||||
|----|------|------|
|
||||
| L0 | `.md` 原文 + 来源 | 不可执行 |
|
||||
| L1 | `# 诗人` + 字段表 | 类/模式 |
|
||||
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
|
||||
| L3 | `[描述](类.函数)` | 类调用/链接 |
|
||||
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
|
||||
|
||||
## 附录 B:与现有文档的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
|
||||
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
|
||||
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
|
||||
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
|
||||
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
|
||||
@@ -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,799 @@
|
||||
# 链接语法:命名载荷、类-函数调用与可执行知识
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
|
||||
| 日期 | 2026-10-23 |
|
||||
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
|
||||
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
|
||||
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
|
||||
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
|
||||
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 设计声明
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
> **`[]()` 本身不制作新语法。**
|
||||
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
|
||||
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
|
||||
|
||||
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
|
||||
|
||||
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
|
||||
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
|
||||
|
||||
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
|
||||
|
||||
它始终同时有三种投影:
|
||||
|
||||
| 投影 | 规则 | 目的 |
|
||||
|------|------|------|
|
||||
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
|
||||
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
|
||||
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
|
||||
|
||||
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
|
||||
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
|
||||
|
||||
例如:
|
||||
|
||||
```markdown
|
||||
**name = [订单收件人](at(订单, "收件人"))**
|
||||
**gross = [含税金额](金额 * (1 + 税率))**
|
||||
- [逐个订单行](遍历 订单.行 为 行)
|
||||
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
|
||||
```
|
||||
|
||||
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
|
||||
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
|
||||
不能要求每一次取元或循环都伪造来源表。
|
||||
|
||||
这才同时实现三件事:
|
||||
|
||||
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
|
||||
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
|
||||
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
|
||||
|
||||
完整的跨文件闭环、稳定寻址和层次投影见
|
||||
[executable-knowledge-system.md](executable-knowledge-system.md)。
|
||||
|
||||
### 0.2 三个「不新增」
|
||||
|
||||
| 不新增 | 说明 |
|
||||
|--------|------|
|
||||
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
|
||||
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
|
||||
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
|
||||
|
||||
**本文定义四件事**:
|
||||
|
||||
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
|
||||
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
|
||||
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
|
||||
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
|
||||
|
||||
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
|
||||
|
||||
### 0.3 原始意图
|
||||
|
||||
第一个可执行文档:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
李白出生于*某年*
|
||||
```
|
||||
|
||||
在 Marqdo 里:
|
||||
|
||||
- `# 李白` = **类**;
|
||||
- `## 李白的出生年份` = 该类下的**函数**;
|
||||
- `李白.李白的出生年份` = **类调用这个函数**。
|
||||
|
||||
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
|
||||
|
||||
第二个文档:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
|
||||
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
|
||||
|
||||
```markdown
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
这不是两套语法,而是同一套语法的两种呈现:
|
||||
|
||||
- `**year = 李白.李白的出生年份**` 是代码;
|
||||
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
|
||||
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
|
||||
|
||||
### 0.4 当前实现的偏差
|
||||
|
||||
v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
|
||||
| 设计意图 | 当前实现 | 后果 |
|
||||
|----------|---------|------|
|
||||
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
|
||||
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
|
||||
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
|
||||
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
|
||||
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
|
||||
|
||||
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
|
||||
|
||||
### 0.5 三个统一
|
||||
|
||||
| 统一 | 链接语法的作用 |
|
||||
|------|---------------|
|
||||
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
|
||||
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
|
||||
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
|
||||
|
||||
形式化:
|
||||
|
||||
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
|
||||
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
|
||||
|
||||
---
|
||||
|
||||
## 1. 术语
|
||||
|
||||
| 术语 | 定义 |
|
||||
|------|------|
|
||||
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
|
||||
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
|
||||
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
|
||||
| **类(class)** | `# 名称`;知识命名空间/类型 |
|
||||
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
|
||||
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
|
||||
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
|
||||
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
|
||||
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
|
||||
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
|
||||
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
|
||||
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
|
||||
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 语义
|
||||
|
||||
### 2.1 描述永不执行,载荷唯一执行
|
||||
|
||||
```text
|
||||
[label](expr) ≡ expr
|
||||
```
|
||||
|
||||
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
|
||||
- `()` 是唯一执行体;空 `()` 值为 `None`;
|
||||
- `label.missing` / `label.empty_payload` 仍是结构诊断;
|
||||
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
|
||||
|
||||
### 2.2 `#` 是类,`##` 是函数
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `# 名称` | 类/知识命名空间;正文是构造体 |
|
||||
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
|
||||
| `###` … | 更深层函数/子命名空间 |
|
||||
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
|
||||
|
||||
**函数与实例的关系**:
|
||||
|
||||
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
|
||||
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
|
||||
- 类函数不执行 `# 类` 的构造体,不产生实例;
|
||||
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
|
||||
|
||||
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
|
||||
|
||||
### 2.3 `类.函数` 是类调用
|
||||
|
||||
| 写法 | 语义 |
|
||||
|------|------|
|
||||
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
|
||||
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
|
||||
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
|
||||
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
|
||||
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
|
||||
|
||||
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
|
||||
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
|
||||
|
||||
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
|
||||
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
|
||||
|
||||
### 2.4 跨文档:模块身份优先,类索引只做发现
|
||||
|
||||
链接目标可以跨文档。可运行代码的解析顺序:
|
||||
|
||||
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
|
||||
2. **当前文档类/函数**:`# 类` / `## 函数`;
|
||||
3. **已 import 的模块**:现有 `import bind:target` 绑定;
|
||||
4. **内置/插件**。
|
||||
|
||||
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
|
||||
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
|
||||
按名加载机制:
|
||||
|
||||
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
|
||||
- 排除 `# main`;
|
||||
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
|
||||
- 索引只在项目根内(`--fs-root`),不访问网络;
|
||||
- 索引可缓存(按文件 mtime)。
|
||||
|
||||
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
|
||||
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
|
||||
|
||||
### 2.5 `()` 与 `**代码**` 同权
|
||||
|
||||
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|
||||
|------|-----------|----------------------|
|
||||
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
|
||||
| 变量/插值 | ✅ | ✅ |
|
||||
| 本地调用 `callee(args)` | ✅ | ✅ |
|
||||
| 类调用 `类.函数` | ✅ | ✅ |
|
||||
| 实例调用 `obj.函数` | ✅ | ✅ |
|
||||
| 表/列/映射 | ✅ | ✅ |
|
||||
| 返回值 | Value | Value(同类型系统) |
|
||||
| 副作用 | 可 | 可(受沙箱限制) |
|
||||
|
||||
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
|
||||
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
|
||||
|
||||
**代码链接 vs 正文链接**:
|
||||
|
||||
| 上下文 | `[]()` 行为 |
|
||||
|--------|-------------|
|
||||
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
|
||||
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
|
||||
| 标题 / frontmatter | 不执行;按普通文本处理 |
|
||||
|
||||
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`。
|
||||
|
||||
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
|
||||
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
|
||||
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
|
||||
|
||||
### 2.6 输出:值知识必须有值,过程知识必须声明效果
|
||||
|
||||
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
|
||||
|
||||
```markdown
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
|
||||
|
||||
- `run` 得到 `None`;
|
||||
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
|
||||
- view 显示「无返回值」;
|
||||
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
|
||||
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
|
||||
|
||||
### 2.7 view 显示调用信息
|
||||
|
||||
**代码链接**:
|
||||
|
||||
```text
|
||||
┌─ 链接 ─────────────────────────────┐
|
||||
│ `year` = [李白的出生年份] │
|
||||
│ → 李白.李白的出生年份 │
|
||||
│ class 李白 · function · () -> number │
|
||||
│ value 701 · ok │
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**正文链接**:
|
||||
|
||||
```text
|
||||
用户想要知道李白的出生年份,我们要告诉用户 701。
|
||||
↑
|
||||
悬浮:李白的出生年份 → 李白.李白的出生年份
|
||||
class 李白 · () -> number · value 701
|
||||
```
|
||||
|
||||
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
|
||||
- Execution 模式:显示值;
|
||||
- 点击目标:跳到目标文档/类/函数;
|
||||
- 错误:错误 chip + 诊断码 + 修复建议;
|
||||
- 无返回值:显示「无返回值」,不伪造值。
|
||||
|
||||
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
|
||||
|
||||
### 2.8 编译器返回 LinkInfo
|
||||
|
||||
每个 `[]()` 产出:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
|
||||
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
|
||||
"outputs": [{"name": "行", "type": "订单行"}],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"value": null,
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
|
||||
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
|
||||
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
|
||||
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
|
||||
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
|
||||
|
||||
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
|
||||
|
||||
`LinkInfo` 至少要区分三类状态:
|
||||
|
||||
| 层 | 要回答的问题 | 典型状态 |
|
||||
|------|-------------|----------|
|
||||
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
|
||||
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
|
||||
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
|
||||
|
||||
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
|
||||
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
|
||||
`link.unresolved` 或副作用越权。
|
||||
|
||||
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
|
||||
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
|
||||
|
||||
### 2.9 链接既是步骤节点,也是图边
|
||||
|
||||
```text
|
||||
定价.订单定价 --contains--> step#逐个订单行
|
||||
step#逐个订单行 --observes--> 订单.行
|
||||
step#逐个订单行 --calls--> 定价.订单定价.含税价
|
||||
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
|
||||
```
|
||||
|
||||
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
|
||||
`narrates` 等边的一种;
|
||||
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
|
||||
- `catalog` 模块页显示「链接到/被链接」;
|
||||
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
|
||||
都可精确找出受影响的代码步骤和句子;
|
||||
- view 的 Structure 面板显示上下游。
|
||||
|
||||
### 2.10 安全
|
||||
|
||||
| 风险 | 规则 |
|
||||
|------|------|
|
||||
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
|
||||
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
|
||||
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
|
||||
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
|
||||
| 循环 | 链接图检测环;运行时深度/步数上限 |
|
||||
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
|
||||
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
|
||||
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
|
||||
|
||||
### 2.11 可复现(可选,生成物)
|
||||
|
||||
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
|
||||
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
|
||||
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
|
||||
- 这是生成物/工具,不是新语法。
|
||||
|
||||
### 2.12 知识分层:类、知识个体、调用面
|
||||
|
||||
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
|
||||
|
||||
```markdown
|
||||
# 诗人 # L1 本体:类/模式
|
||||
| 字段 | 类型 | 说明 |
|
||||
| 姓名 | text | ... |
|
||||
| 出生年份 | number | ... |
|
||||
|
||||
# 李白 = > 诗人 # L2 知识个体:单体知识类
|
||||
## 李白的出生年份
|
||||
| 返回 | 类型 | 来源 |
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
*701*
|
||||
|
||||
# L3 调用面
|
||||
[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
**术语**:
|
||||
|
||||
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
|
||||
- `> 李白` 才是运行时实例(map + `_type`);
|
||||
- `李白.李白的出生年份` 是类调用;
|
||||
- `[]()` 是调用面,不新增语法。
|
||||
|
||||
**为什么不在 v2.1 引入运行时实例作为知识实体**:
|
||||
|
||||
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
|
||||
- EKC 的节点是文档/类/函数,不是运行时 map;
|
||||
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前实现 vs 目标
|
||||
|
||||
### 3.1 已具备(v2.0.0)
|
||||
|
||||
| 能力 | 状态 | 证据 |
|
||||
|------|------|------|
|
||||
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
|
||||
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
|
||||
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
|
||||
| view 本地链接卡 | ✅ | `render.rs:1227` |
|
||||
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
|
||||
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
|
||||
|
||||
### 3.2 缺失(v2.1 目标)
|
||||
|
||||
| 能力 | 状态 | 影响 |
|
||||
|------|------|------|
|
||||
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
|
||||
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
|
||||
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
|
||||
| LinkInfo | ❌ | 编译器不返回链接信息 |
|
||||
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
|
||||
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
|
||||
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
|
||||
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
|
||||
|
||||
### 3.3 为什么旧例子失败
|
||||
|
||||
| 层 | 旧例子 | 设计要求 |
|
||||
|----|--------|---------|
|
||||
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
|
||||
| 类索引 | 无 import | 项目类索引解析 `李白` |
|
||||
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
|
||||
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
|
||||
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
|
||||
| 静态检查 | 不解析 | `check` 报 `link.*` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 编译器 / view / CLI 表面
|
||||
|
||||
### 4.1 `check --json`
|
||||
|
||||
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
|
||||
- 不执行目标函数;
|
||||
- `link.ok` 可作 info,不阻断;
|
||||
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
|
||||
|
||||
### 4.2 MLSP
|
||||
|
||||
| method | 作用 |
|
||||
|--------|------|
|
||||
| `link.resolve` | 解析一个链接 → LinkInfo |
|
||||
| `links.list` | 列出文件/项目所有链接 |
|
||||
| `links.graph` | 返回链接图 |
|
||||
| `link.check` | 校验一个链接 |
|
||||
|
||||
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
|
||||
|
||||
### 4.3 `catalog` / EKC
|
||||
|
||||
- `catalog` 增加 `links:` 段与链接图;
|
||||
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
|
||||
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
|
||||
|
||||
### 4.4 `links` CLI(可选)
|
||||
|
||||
```bash
|
||||
marqdo links list [PATH] --json
|
||||
marqdo links resolve FILE:LINE:COL
|
||||
marqdo links graph [PATH] --json
|
||||
marqdo links lock [PATH] # 可选,生成指纹锁
|
||||
```
|
||||
|
||||
### 4.5 诊断
|
||||
|
||||
| code | 级别 | 触发 | 建议 |
|
||||
|------|------|------|------|
|
||||
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
|
||||
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
|
||||
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
|
||||
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
|
||||
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
|
||||
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
|
||||
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
|
||||
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
|
||||
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
|
||||
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
|
||||
| `label.missing` | error | 空描述 | 写一句人话 |
|
||||
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 开发指导
|
||||
|
||||
### 5.1 里程碑
|
||||
|
||||
| 阶段 | 目标 | 交付 |
|
||||
|------|------|------|
|
||||
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
|
||||
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
|
||||
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
|
||||
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
|
||||
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
|
||||
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
|
||||
|
||||
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
|
||||
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
|
||||
|
||||
### 5.2 文件级改动
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
|
||||
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
|
||||
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
|
||||
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
|
||||
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
|
||||
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
|
||||
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
|
||||
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
|
||||
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
|
||||
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
|
||||
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
|
||||
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
|
||||
| `src/catalog.rs` | links 段/图 |
|
||||
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
|
||||
| `src/main.rs` | `links` 子命令;check 选项 |
|
||||
| `README.md` | 链接语法章节(不新增语法) |
|
||||
| `doc/README.md` | 登记本文/示例 |
|
||||
| `examples/link-syntax/` | 用户原始示例 + compat |
|
||||
|
||||
### 5.3 关键实现点
|
||||
|
||||
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
|
||||
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
|
||||
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
|
||||
4. **`[]()` 分类**:
|
||||
- payload 是类/函数路径 → 知识链接;
|
||||
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
|
||||
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
|
||||
- 正文 `[]()` → 正文链接(view/check)。
|
||||
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
|
||||
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
|
||||
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
|
||||
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
|
||||
|
||||
**最小改动原则**(证明「不新增语法」):
|
||||
|
||||
| 层 | 现状 | v2.1 改动 |
|
||||
|----|------|-----------|
|
||||
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
|
||||
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
|
||||
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
|
||||
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
|
||||
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
|
||||
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
|
||||
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
|
||||
|
||||
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
|
||||
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
|
||||
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
|
||||
|
||||
### 5.4 测试
|
||||
|
||||
| 层 | 用例 |
|
||||
|----|------|
|
||||
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
|
||||
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
|
||||
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
|
||||
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
|
||||
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
|
||||
| 双后端 | tree + bytecode 一致 |
|
||||
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
|
||||
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
|
||||
|
||||
### 5.5 迁移
|
||||
|
||||
- `#`/`##` 的实例调用保持;
|
||||
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
|
||||
- `类.函数` 是新增解析,不改变旧调用;
|
||||
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
|
||||
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
|
||||
|
||||
---
|
||||
|
||||
## 6. 示例
|
||||
|
||||
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
|
||||
|
||||
### 6.1 用户原始示例(目标)
|
||||
|
||||
`libai.mq.md`:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
李白的出生年份是公元 701 年。
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
`main.mq.md`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
|
||||
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
|
||||
- `check --json`:LinkInfo(target/class/function/signature/status);
|
||||
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
|
||||
|
||||
### 6.2 加 print(终端输出)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 6.3 带参数
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**greeting = [问候](李白.问候("世界"))**
|
||||
> print text=`greeting`
|
||||
```
|
||||
|
||||
### 6.4 当前兼容写法(v2.0.0)
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
import:
|
||||
libai: libai.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**li = > libai.李白**
|
||||
**year = [李白的出生年份](li.李白的出生年份())**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收标准
|
||||
|
||||
| # | 验收 | 判定 |
|
||||
|---|------|------|
|
||||
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
|
||||
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
|
||||
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
|
||||
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
|
||||
| 5 | 同名类 → `link.ambiguous` | 反例 |
|
||||
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
|
||||
| 7 | 无返回值 → `link.no_value` | 反例 |
|
||||
| 8 | EKC 出现 `calls` 边 | graph.json |
|
||||
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
|
||||
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
|
||||
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
|
||||
|
||||
**一句话验收**:
|
||||
|
||||
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
|
||||
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与开放问题
|
||||
|
||||
| 风险 | 说明 | 缓解 |
|
||||
|------|------|------|
|
||||
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
|
||||
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
|
||||
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
|
||||
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
|
||||
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
|
||||
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
|
||||
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
|
||||
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
|
||||
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
|
||||
|
||||
**开放问题**:
|
||||
|
||||
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
|
||||
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
|
||||
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
|
||||
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
|
||||
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
|
||||
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
|
||||
|
||||
---
|
||||
|
||||
## 9. 结论
|
||||
|
||||
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
|
||||
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
|
||||
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
|
||||
|
||||
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
|
||||
v2.1 要补的是**语义**,不是语法:
|
||||
|
||||
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
|
||||
2. `类.函数` → 类调用;跨文档用项目类索引;
|
||||
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
|
||||
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
|
||||
|
||||
**一句话**:
|
||||
|
||||
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
|
||||
|
||||
---
|
||||
|
||||
## 附录 A:一页速查
|
||||
|
||||
```markdown
|
||||
# 类
|
||||
## 函数
|
||||
*701*
|
||||
|
||||
# 代码链接(求值)
|
||||
**year = [出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
|
||||
# 正文链接(view/check 解析,run 不执行)
|
||||
李白出生于 [李白的出生年份](李白.李白的出生年份)。
|
||||
|
||||
# 带参类调用
|
||||
**g = [问候](李白.问候("世界"))**
|
||||
```
|
||||
|
||||
| 写法 | 执行 | 用途 |
|
||||
|------|------|------|
|
||||
| `**类.函数**` | ✅ | 普通代码/调用 |
|
||||
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
|
||||
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
|
||||
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
|
||||
| `[描述](url)` | ❌ | 普通导航 |
|
||||
|
||||
## 附录 B:与旧文档的关系
|
||||
|
||||
| 旧文档 | 关系 |
|
||||
|--------|------|
|
||||
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
|
||||
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
|
||||
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
|
||||
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
|
||||
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
|
||||
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
|
||||
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
@@ -16,9 +16,9 @@
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
|
||||
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
|
||||
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,8 +29,8 @@
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
|
||||
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
|
||||
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import` / `导入`。
|
||||
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import:` / `导入:`。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
@@ -54,27 +54,38 @@
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
|
||||
|
||||
```yaml
|
||||
---
|
||||
import:
|
||||
utils: utils.mq.md
|
||||
json: lib/json.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
```
|
||||
|
||||
| 含义 | 英文 | 中文 |
|
||||
|------|------|------|
|
||||
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
|
||||
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
|
||||
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
|
||||
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
|
||||
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
|
||||
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
|
||||
|
||||
规则:
|
||||
|
||||
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
|
||||
- `:` 右侧 `target`:
|
||||
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
|
||||
- 映射值 `target`:
|
||||
- 以 `.mq.md` 结尾 → **文件导入**;
|
||||
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
|
||||
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
|
||||
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
|
||||
- 同一文件不得同时出现 `import:` 与 `导入:`。
|
||||
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
|
||||
|
||||
### 3.3 废除的旧规则
|
||||
|
||||
不再支持:
|
||||
|
||||
- 一行式 `import bind:target` / `导入 bind:target`;
|
||||
- 省略绑定名时用文件名茎作库名;
|
||||
- 导入侧 `as` / `作为`;
|
||||
- 独立关键字 `use` / `使用`。
|
||||
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -153,10 +166,11 @@ import fmt:time.format
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
|
||||
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
|
||||
| `import fmt`:time.format
|
||||
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
|
||||
| `import fmt:time.format` | `import:` → `fmt: time.format` |
|
||||
| 茎名默认库名 | 绑定名始终显式 |
|
||||
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
|
||||
|
||||
不提供旧 `>` 导入过渡开关。
|
||||
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
|
||||
|
||||
---
|
||||
|
||||
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
|
||||
|
||||
## 8. 实现要点
|
||||
|
||||
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
|
||||
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
|
||||
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
|
||||
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M1+M2 | 点号路径 + 短名 — 已落地 |
|
||||
| **Import 句法** | 统一 `import bind:target` — **本波次** |
|
||||
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决议摘要
|
||||
|
||||
1. 导入 = `import bind:target`(`导入` 等价)。
|
||||
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
|
||||
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
|
||||
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
|
||||
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
|
||||
@@ -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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
|
||||
|
||||
---
|
||||
|
||||
## 附:一句话总结
|
||||
|
||||
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
|
||||
> 它用链接的天然分工(人话 / 目标)实现这一点,
|
||||
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
|
||||
> 而 `>` 调用同样在负债之列。
|
||||
@@ -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 的标签保鲜都成立,
|
||||
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
|
||||
@@ -35,7 +35,8 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -44,7 +45,8 @@ import text:lib/text.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 文本:lib/文本.mq.md
|
||||
导入:
|
||||
文本: lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -17,7 +17,8 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
table: lib/table.mq.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——**第一天就不会有任何存量警告**。
|
||||
@@ -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 条警告。
|
||||
+26
-1
@@ -13,6 +13,8 @@
|
||||
|------|------|------|
|
||||
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
|
||||
| Git | 任意近期版本 | `git --version` |
|
||||
| GCC / Binutils | 原生依赖编译与链接 | `cc --version` / `ld --version` |
|
||||
| Go | ≥ 1.22(仅构建 `plugins/web` 与 web 扩展测试需要) | `go version` |
|
||||
|
||||
安装 Rust(若尚未安装):
|
||||
|
||||
@@ -21,7 +23,17 @@
|
||||
|
||||
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
|
||||
|
||||
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
|
||||
**不需要:** Flex、Bison、LLVM。Node/npm 只在开发 VS Code 扩展时需要;核心 Rust 开发不依赖它们。
|
||||
|
||||
本仓库提供了固定 Rust 版本:`rust-toolchain.toml` 使用 Rust 1.81.0,并启用
|
||||
`rustfmt` / `clippy`。在受限开发容器中,推荐先加载仓库环境脚本:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh
|
||||
```
|
||||
|
||||
脚本会优先使用 `target/toolchain/` 下的工具链,普通开发机则回退到 PATH 中已有的工具,
|
||||
并把 Cargo、Go 缓存和临时目录放在工作区内。
|
||||
|
||||
---
|
||||
|
||||
@@ -36,6 +48,12 @@ cargo test
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
```
|
||||
|
||||
构建 Go web 插件(完整扩展开发需要):
|
||||
|
||||
```bash
|
||||
bash scripts/build-web-plugin.sh
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
|
||||
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
|
||||
@@ -50,6 +68,13 @@ cargo fmt
|
||||
cargo clippy --all-targets
|
||||
```
|
||||
|
||||
只验证 Rust 核心时可运行 `cargo test --locked --lib`;包含全部扩展的 gold 测试需要 Go,
|
||||
并建议单线程运行以避免共享临时夹具互相影响:
|
||||
|
||||
```bash
|
||||
cargo test --locked --test gold -- --test-threads=1
|
||||
```
|
||||
|
||||
代理下拉 crate(可选,与 git 推送类似):
|
||||
|
||||
```bash
|
||||
|
||||
+453
@@ -0,0 +1,453 @@
|
||||
# Marqdo 的 `[]()`:从可读语法走向可验证的知识引用
|
||||
|
||||
我重新读取了仓库当前 `main` 分支(提交 `1a139892`)的 README、链接语法设计、知识分层设计,以及仓库中针对现有实现的复核报告。
|
||||
|
||||
这次我认为应当调整之前对 Marqdo 的评价:你提出的 `[]()` 不只是改善语法外观,它确实有机会成为 Marqdo 从“可执行文档”走向“可复用知识系统”的关键入口。
|
||||
|
||||
但当前设计有一个尚未解决的根本问题:
|
||||
|
||||
它已经尝试统一“可读描述”和“可执行表达式”,却还没有真正统一“知识的身份、知识的含义、知识的实现、知识的证据,以及知识的版本”。
|
||||
|
||||
仅仅让链接能解析到一个函数,并不能保证 AI 没有用错知识。仅仅让函数有一个确定的编译结果,也不能保证这个结果所表达的知识是真的。
|
||||
|
||||
这恰恰可能是你不断修改设计,却始终没有得到预期效果的原因。
|
||||
|
||||
## 一、先区分仓库已经实现了什么
|
||||
|
||||
当前 README 标明的是 v2.0.0,`doc/design/link-syntax.md` 将跨文档类函数调用列为 v2.1 目标。
|
||||
|
||||
| 能力 | 仓库当前状态 |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `[描述](表达式)` 本地遮蔽 | 已实现,主要通过 `markup: occlusion` |
|
||||
| `()` 中表达式求值 | 已实现 |
|
||||
| 用自然语言描述隐藏复杂代码 | 已实现基础能力 |
|
||||
| `类.函数` 直接调用 | 设计目标,尚未按文档实现 |
|
||||
| 跨文档自动解析知识目标 | 设计目标 |
|
||||
| 编译器生成 LinkInfo | 设计目标 |
|
||||
| 链接进入 EKC 知识图 | 设计目标 |
|
||||
| 版本指纹和链接锁定 | 设计目标 |
|
||||
|
||||
仓库还有一份很重要的复核报告:[occlusion-vs-executable-knowledge-2026-10.md](https://github.com/cflmy/marqdo/blob/main/doc/research/occlusion-vs-executable-knowledge-2026-10.md?utm_source=chatgpt.com)。
|
||||
|
||||
它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。
|
||||
|
||||
这份报告说明:问题不是 `[]()` 的形式不够优美,而是链接背后的知识语义基础尚未建成。
|
||||
|
||||
这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。
|
||||
|
||||
## 二、我建议保留你的两个目标,但增加第三个目标
|
||||
|
||||
目标一 · Presentation
|
||||
|
||||
自然语言呈现
|
||||
|
||||
用 `[]` 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。
|
||||
|
||||
目标二 · Executable Reference
|
||||
|
||||
确定性知识引用
|
||||
|
||||
让 `()` 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。
|
||||
|
||||
目标三 · Knowledge Integrity
|
||||
|
||||
知识一致性保障
|
||||
|
||||
当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。
|
||||
|
||||
第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。
|
||||
|
||||
我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。
|
||||
|
||||
## 三、关键转变:不要把“函数”直接等同于“知识”
|
||||
|
||||
目前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的核心设计是:
|
||||
|
||||
```
|
||||
[label](expr) ≡ expr
|
||||
```
|
||||
|
||||
它规定标签不改变计算语义,链接只为表达式增加人类描述和编译器元数据。
|
||||
|
||||
这个规则作为表达式语义是合理的,但作为完整知识模型还不够。
|
||||
|
||||
原因在于,至少有三种不同的东西可能进入 `()`:
|
||||
|
||||
| 内容 | 例子 | 实质 |
|
||||
| ---- | ---------------------------- | --------------- |
|
||||
| 表达式 | `[税额](amount * rate)` | 一次计算 |
|
||||
| 函数 | `[计算税额](Tax.calculate(100))` | 一种计算能力的调用 |
|
||||
| 知识事实 | `[适用税率](TaxPolicy.rate)` | 一项具有来源、范围、版本的知识 |
|
||||
|
||||
第三种不能只靠前两种来解释。
|
||||
|
||||
例如,编译器能确定 `TaxPolicy.rate` 返回 `0.10`,只能证明“目标被正确解析并返回该值”,不能证明“2026 年某个地区、某种业务适用的税率确实是 10%”。
|
||||
|
||||
确定性执行和知识真实性是两个独立维度。
|
||||
|
||||
我建议把 Marqdo 的知识模型扩展为以下结构:
|
||||
|
||||
Markdown 文档
|
||||
|
||||
自然语言叙述、表格、函数与知识定义
|
||||
|
||||
Semantic Artifact · 语义制品
|
||||
|
||||
稳定身份、类型、签名、实现、契约、依赖、证据
|
||||
|
||||
Verified Knowledge Reference
|
||||
|
||||
解析引用、检查约束、固定版本、判定可否复用
|
||||
|
||||
解释执行
|
||||
|
||||
知识检索
|
||||
|
||||
AI 复用
|
||||
|
||||
这里最重要的新概念不是链接,而是 Semantic Artifact(语义制品)。
|
||||
|
||||
它应当是 Marqdo 编译器第一次真正统一代码、文档与知识的中间产物。
|
||||
|
||||
### 一个语义制品应该包含什么?
|
||||
|
||||
建议最小模型如下。这里是我的架构提案,不是当前仓库已经实现的格式。
|
||||
|
||||
```
|
||||
{
|
||||
"id": "knowledge://project/TaxPolicy/rate",
|
||||
"kind": "fact",
|
||||
"signature": {
|
||||
"params": [],
|
||||
"returns": "number"
|
||||
},
|
||||
"implementation": {
|
||||
"ir": "compiled-reference",
|
||||
"digest": "sha256:..."
|
||||
},
|
||||
"contract": {
|
||||
"unit": "ratio",
|
||||
"scope": "example-policy",
|
||||
"effects": "pure"
|
||||
},
|
||||
"provenance": {
|
||||
"source": "policy.md#rate",
|
||||
"digest": "sha256:..."
|
||||
},
|
||||
"verification": {
|
||||
"status": "verified",
|
||||
"methods": ["source-check", "contract-test"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中 `id` 是符号身份,`implementation.digest` 是编译内容指纹,`provenance` 是来源证据,`verification` 是验证记录。
|
||||
|
||||
这样一来,AI 复用的对象就不再是“某个名字看起来正确的函数”,而是一个具有明确身份和约束的知识制品。
|
||||
|
||||
需要注意:这里的 `verified` 只能表示通过了所声明的验证方法,不能凭此宣称该知识在所有现实情境下都正确。
|
||||
|
||||
## 四、重新定义 `[]()`:统一写法,不强行统一所有行为
|
||||
|
||||
我建议继续保持你所追求的语法纯度:
|
||||
|
||||
```
|
||||
[人类可读的描述](机器可解析的目标)
|
||||
```
|
||||
|
||||
不引入额外的 `knowledge:`、`call:` 或 `ref:` 前缀,也不让 AI 记忆复杂的新标记。
|
||||
|
||||
但编译器必须区分目标的性质,而不是把一切都当作普通表达式立即求值。
|
||||
|
||||
A · 表达式遮蔽
|
||||
|
||||
计算
|
||||
|
||||
```
|
||||
**total = [应付总额](price * quantity + shipping)**
|
||||
```
|
||||
|
||||
对原有表达式的透明包装。编译后仍是普通表达式,描述不改变值。
|
||||
|
||||
B · 能力引用
|
||||
|
||||
复用
|
||||
|
||||
```
|
||||
**total = [计算应付总额](Pricing.total(订单))**
|
||||
```
|
||||
|
||||
解析到已编译函数,检查参数、类型、依赖、权限和版本,然后调用。
|
||||
|
||||
C · 知识事实引用
|
||||
|
||||
知识
|
||||
|
||||
```
|
||||
用户可以查阅[李白的出生年份](李白.出生年份)。
|
||||
```
|
||||
|
||||
解析到知识制品;view 展示事实、来源和验证状态。正文保持惰性,不自动产生副作用。
|
||||
|
||||
这种设计保留了 `[label](expr) ≡ expr` 的计算规则,但增加了一个重要条件:编译器首先要解析 `expr` 的目标类型,然后才能决定它应该怎样验证、绑定和使用。
|
||||
|
||||
这不会使语言多出三套语法,反而能够避免当前设计中“语法统一了,但知识语义仍然散落在工具中”的问题。
|
||||
|
||||
## 五、你的第二个目标,最关键的是“绑定”而不是“调用”
|
||||
|
||||
假设有这样一份知识文档:
|
||||
|
||||
```
|
||||
# 李白
|
||||
|
||||
## 出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|---|---|---|
|
||||
| 701 | number | corpus/libai.md#birth |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
另一个文档写:
|
||||
|
||||
```
|
||||
李白的[出生年份](李白.出生年份)是 701 年。
|
||||
```
|
||||
|
||||
理想情况下,编译器应该执行一条确定性的处理链:
|
||||
|
||||
Resolve — 查找 `李白.出生年份` 指向哪个知识单元
|
||||
|
||||
Bind — 绑定稳定 Symbol ID,而不是仅保存字符串
|
||||
|
||||
Validate — 检查返回类型、来源、契约与依赖
|
||||
|
||||
Pin — 根据需要固定知识版本和内容指纹
|
||||
|
||||
Evaluate — 仅在允许执行的上下文中求值
|
||||
|
||||
Trace — 将引用关系、验证结果与来源写入知识图
|
||||
|
||||
此时,编译器内部的引用不应该只是:
|
||||
|
||||
```
|
||||
"李白.出生年份"
|
||||
```
|
||||
|
||||
而应该更接近:
|
||||
|
||||
```
|
||||
KnowledgeRef {
|
||||
target_symbol_id,
|
||||
resolved_artifact_id,
|
||||
expected_signature,
|
||||
pinned_digest,
|
||||
verification_policy,
|
||||
source_span
|
||||
}
|
||||
```
|
||||
|
||||
其中的 `target_symbol_id` 解决“引用谁”,`pinned_digest` 解决“引用哪个版本”,`verification_policy` 解决“什么时候可以信任它”。
|
||||
|
||||
这才是让 AI 不必重新生成已有知识,而是能够确定性地调用已有知识的技术基础。
|
||||
|
||||
还有一个必须考虑的问题:如果编译器只记录函数源码哈希,而函数内部调用的其他知识已经发生变化,那么源码没有变,实际执行语义也可能已经变化。因此,至少要对调用依赖形成可追踪的版本关系;对需要严格复现的纯函数,还应生成包含传递依赖的制品指纹。对于网络请求、时间、随机数等外部效应,则必须记录环境和执行条件,不能简单承诺重放一定得到相同结果。
|
||||
|
||||
## 六、仓库当前设计里,我最想修改的三个地方
|
||||
|
||||
### 1. 不要继续把类当作所有知识的唯一载体
|
||||
|
||||
[knowledge-layers.md](https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md?utm_source=chatgpt.com) 提出用 `# 李白 = > 诗人` 表示知识个体,也就是“单体知识类”。
|
||||
|
||||
这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。
|
||||
|
||||
因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。
|
||||
|
||||
更理想的是:让编译器内部明确区分 `Type`、`Entity`、`Fact`、`Function`、`Capability` 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。
|
||||
|
||||
### 2. 不要让 `check` 与 EKC 各自维护一套知识理解
|
||||
|
||||
目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 [engineering-knowledge.md](https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md?utm_source=chatgpt.com)。
|
||||
|
||||
这里完全没有必要再为 `[]()` 平行开发另一套知识注册表。
|
||||
|
||||
我建议把架构整理成:
|
||||
|
||||
- 编译器负责产出统一 Semantic IR、符号信息和引用关系;
|
||||
- `check` 消费这些信息进行验证;
|
||||
- EKC 将它们投影成知识图和上下文包;
|
||||
- `view` 消费同一份信息展示可读知识;
|
||||
- Agent 使用同一份引用解析接口,而不是重新理解 `.mq.md` 文本。
|
||||
|
||||
如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。
|
||||
|
||||
### 3. 不要认为“描述过期”和“知识过期”是一回事
|
||||
|
||||
仓库中的 [occlusion-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/occlusion-syntax.md?utm_source=chatgpt.com) 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。
|
||||
|
||||
但是,三类变化必须区分:
|
||||
|
||||
| 变化 | 应该检查什么 |
|
||||
| ------------- | -------------- |
|
||||
| 实现变了,描述没变 | 描述是否仍与行为一致 |
|
||||
| 知识来源变了,函数没变 | 知识事实是否仍然有证据支持 |
|
||||
| 引用目标变了,代码还能运行 | 是否仍满足原始契约和版本要求 |
|
||||
|
||||
尤其是第三种:AI 幻觉可能表现为调用了一个真实存在、类型也正确、但是业务含义完全错误的函数。
|
||||
|
||||
纯粹的符号解析和类型检查抓不住这种错误。因此,需要让能力契约、适用范围和知识来源成为可检查的制品属性,而不是只依赖 `[]` 中的自然语言。
|
||||
|
||||
## 七、建议的实施顺序
|
||||
|
||||
不要一次性实现完整知识图谱、版本锁定、自动修复和复杂本体系统。我建议分成四个阶段,每一阶段都必须有独立的可执行验收。
|
||||
|
||||
| 阶段 | 核心交付 | 必须通过的测试 |
|
||||
| ------------ | ------------------------------------- | ---------------------------------- |
|
||||
| P0 · 统一引用语义 | `[]()` 的统一 AST、目标类型识别、正文/代码上下文区分 | 不再因 Classic/Occlusion 模式造成静默错义 |
|
||||
| P1 · 稳定寻址 | 项目符号索引、类函数解析、稳定 Symbol ID、静态 LinkInfo | 两文档李白示例无需实例化即可完成解析与引用 |
|
||||
| P2 · 可验证知识制品 | Semantic Artifact、契约、来源、指纹、统一诊断 | 删除目标、修改签名、改变来源,均得到准确诊断 |
|
||||
| P3 · 确定性复用 | 依赖图、制品锁定、EKC 集成、Agent 引用优先策略 | AI 不重新生成已存在的能力;错误、过期和不适用的知识被阻止直接复用 |
|
||||
|
||||
我特别建议设置一个不依赖 LLM 的核心验收实验:
|
||||
|
||||
准备 100 个知识单元,包含同名符号、跨文档引用、版本变更、类型不匹配、来源缺失、循环依赖和正常复用。由程序自动生成和验证预期结果。
|
||||
|
||||
先证明编译器能够正确识别、绑定和诊断这些情况,再引入 AI 测试上下文成本和幻觉率。否则很容易把模型能力、索引召回率与编译器的正确性混在一起。
|
||||
|
||||
## 八、重新评价 Marqdo 的研究主张
|
||||
|
||||
过去 Marqdo 的核心叙述是:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
我认为现在可以把它变得更加严格:
|
||||
|
||||
Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行、可复用的知识制品的语言与编译系统。
|
||||
|
||||
这个定位的价值不在于“Markdown 可以运行代码”,也不在于“Markdown 链接能调用函数”。这两点单独来看都不足以形成很强的研究贡献。
|
||||
|
||||
它真正值得探索的创新组合是:
|
||||
|
||||
一份自然语言与程序混合的源码,经过统一编译后,同时生成可执行程序、语义符号体系、验证证据、版本化知识引用和 AI 可消费的复用接口。
|
||||
|
||||
当然,这仍然是一个待证明的系统设计目标,而不是当前 v2.0.0 已经达到的状态。
|
||||
|
||||
## 最终判断
|
||||
|
||||
你的 `[]()` 方向值得保留,甚至值得作为下一轮 Marqdo 核心架构调整的切入点。但我不建议继续把主要精力投入到如何让 `[]()` 兼容更多语法、更多函数调用形式或更多 Markdown 场景。
|
||||
|
||||
你现在缺少的不是更漂亮的链接语法,而是一个由编译器负责维护的“知识身份与语义绑定层”。
|
||||
|
||||
这也是我认为应该优先修正当前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。
|
||||
|
||||
当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。
|
||||
|
||||
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
|
||||
|
||||
|
||||
是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。
|
||||
|
||||
实际上,这两者应当区分。
|
||||
|
||||
你最初提出的:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
并不只是一句理念性的口号,它本身已经包含了完整的目标链条:
|
||||
|
||||
1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。
|
||||
2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。
|
||||
3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。
|
||||
|
||||
其中,知识复用就是第三阶段最重要的结果之一。
|
||||
|
||||
因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。
|
||||
|
||||
## 真正需要解决的是:什么才算知识被复用?
|
||||
|
||||
我认为这里才是 Marqdo 当前设计最值得深入的地方。
|
||||
|
||||
假设 AI 需要计算一笔订单的最终价格。
|
||||
|
||||
传统方式可能是:
|
||||
|
||||
- 检索价格计算文档;
|
||||
- 阅读文档中的公式和约束;
|
||||
- AI 自己理解并重新编写计算逻辑;
|
||||
- 执行新生成的代码。
|
||||
|
||||
这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。
|
||||
|
||||
而你想实现的 Marqdo 应该是:
|
||||
|
||||
```
|
||||
订单最终价格为[计算后的价格](订单.最终价格(订单数据))。
|
||||
```
|
||||
|
||||
这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。
|
||||
|
||||
如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从:
|
||||
|
||||
“根据知识重新生成答案或程序”
|
||||
|
||||
转变成:
|
||||
|
||||
“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果”
|
||||
|
||||
这才是 Marqdo 的核心价值。
|
||||
|
||||
## 所以,`[]()` 应该承担什么角色?
|
||||
|
||||
我建议将整个体系理解成:
|
||||
|
||||
代码即文档
|
||||
|
||||
统一人类叙述与机器可执行内容
|
||||
|
||||
文档即知识库
|
||||
|
||||
知识具有结构、身份、关联与约束
|
||||
|
||||
知识即可执行
|
||||
|
||||
知识能够被确定性引用、调用和组合
|
||||
|
||||
知识真正复用
|
||||
|
||||
AI 优先使用既有知识,而非反复解释和重新生成
|
||||
|
||||
`[]()` 不需要独自完成这一切。
|
||||
|
||||
它应该成为整个体系中知识从文档进入使用场景的统一入口。
|
||||
|
||||
而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。
|
||||
|
||||
这里有一个很重要的区别:
|
||||
|
||||
- `[]()` 负责表达“我要使用这段知识”。
|
||||
- 编译器负责确定“究竟是哪段知识”。
|
||||
- 验证系统负责判断“这段知识是否满足当前使用条件”。
|
||||
- 运行时负责执行知识。
|
||||
|
||||
这些职责不应该全部压到 `[]()` 的语法设计上。
|
||||
|
||||
## 我现在更倾向于保留你的原始理念
|
||||
|
||||
甚至不建议用我之前那段冗长的定义替换它。
|
||||
|
||||
“代码即文档,文档即知识库,知识即可执行”已经足够准确。
|
||||
|
||||
真正值得补充的是它背后的一个技术原则:
|
||||
|
||||
> 知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。
|
||||
|
||||
这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。
|
||||
|
||||
不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。
|
||||
|
||||
我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题:
|
||||
|
||||
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
|
||||
|
||||
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
@@ -0,0 +1,295 @@
|
||||
# Marqdo 可执行知识体系:统一语义制品与知识引用设计规范
|
||||
|
||||
> 状态:设计提案(非当前版本的已实现功能)
|
||||
> 基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标
|
||||
> 宗旨:**代码即文档,文档即知识库,知识即可执行。**
|
||||
> 核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现?
|
||||
|
||||
## 1. 决策摘要
|
||||
|
||||
保持 `[描述](表达式或知识目标)` 的 Markdown 形态,不引入新的前缀或第二套表达式文法。`[]` 是面向读者的陈述,`()` 内的内容进入统一表达式解析器。语言内部建立稳定的 **Semantic Artifact(语义制品)** 和 **Verified Knowledge Reference(可验证知识引用)** 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 `.mq.md` 经语义分析得到的统一中间表示。
|
||||
|
||||
**三项不变式:**
|
||||
|
||||
1. **表达式透明性**:在求值上下文中 `[L](E)` 与 `E` 取得同一类型和值;`L` 不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。
|
||||
2. **文本安全性**:叙述中的知识链接在 `check/view` 中解析;`run` 不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。
|
||||
3. **知识可信边界**:`resolved`、`compiled`、`tested`、`source_verified`、`domain_validated` 是不同状态。能执行不等于事实真;有来源不等于来源仍然适用。没有证据时允许展示,但不得向 agent 宣称为已验证知识。
|
||||
|
||||
### 1.1 不是要做的事
|
||||
|
||||
- 不将 Markdown 转成一个独立于解释器的新运行语言。
|
||||
- 不把所有知识都强制构建为类,也不等同“知识 = 函数”。
|
||||
- 不把自然语言标签作为权限或事实正确性的证明。
|
||||
- 不把符号名的字符串匹配当成稳定知识复用。
|
||||
- 不要求所有调用都锁版本:本地临时表达式可无锁,跨文档公共知识/关键业务则可选或强制锁定。
|
||||
|
||||
## 2. 以真实仓库为准的兼容边界
|
||||
|
||||
| 语法或能力 | 当前已支持 | 目标设计/注意事项 |
|
||||
|---|---|---|
|
||||
| `.mq.md` 和 Markdown 叙述 | 是 | 原有叙述默认安全 |
|
||||
| `#` 对象/类型,`##` 函数/方法 | 是 | 目标:不依赖 `self` 的函数可通过类命名空间直接调用 |
|
||||
| `**表达式**`、`*返回*` | 是 | 复用现有表达式解析器,不另造链接表达式 |
|
||||
| `+ \`参数\``/叙述推断参数 | 是 | 签名必须能静态抽取并生成规范化形式 |
|
||||
| `1.` 条件分支、`-` 循环 | 是 | 新版链接循环形式须通过模式迁移;旧式依赖 Classic |
|
||||
| Markdown 表格→List/Map/列向表/行向记录 | 是 | 数据语义与契约表应从上下文区别 |
|
||||
| Frontmatter `import` | 是 | 可作为当前跨文档路径的兼容实现 |
|
||||
| `[描述](本地表达式)` | v2.0.0 已有,主要需 `markup: occlusion` | 统一后免模式开关;旧 `[键](集合)` 必须避免静默变义 |
|
||||
| `类.函数` 无实例直接调用 | 未按目标实现 | **新能力**:区分类函数/实例方法、隐式零参调用 |
|
||||
| 跨文档项目符号索引 | 尚缺 | **新能力**:可控作用域、同名消歧、增量索引 |
|
||||
| LinkInfo/知识引用图/links.lock | 目标设计 | **新能力**;与已有 EKC 统一,拒绝第二套知识图 |
|
||||
| 双执行后端(树遍历、字节码) | 是 | 引用语义必须在两个后端一致 |
|
||||
|
||||
项目示例分为:**V2-目标示例**(体现最终范式)与**V2.0-兼容示例**(现有调用方式)。所有目标示例是规范性设计,不宣称已在 v2.0.0 执行验证。
|
||||
|
||||
## 3. 知识不是代码字符串:规范化语义模型
|
||||
|
||||
### 3.1 Semantic Artifact
|
||||
|
||||
每个可引用实体编译为 `Artifact`,而非仅落入 AST 一个节点。
|
||||
|
||||
```text
|
||||
Artifact {
|
||||
symbol_id: StableSymbolId, // 跨增量构建稳定的身份(命名空间 + 显式/规范化路径)
|
||||
kind: Type | Entity | Fact | Function | Capability | Constraint | Policy | Dataset,
|
||||
visibility: Local | Module | Project | Exported,
|
||||
source_span: SourceSpan,
|
||||
signature: CanonicalSignature?, // 参数、返回值、默认值、单位与结构类型
|
||||
ir: CompiledIR?, // 运行逻辑或规范化常量;普通叙述可无
|
||||
effects: EffectSet, // pure / fs.read / fs.write / network / llm / time / random ...
|
||||
dependencies: [SymbolId],
|
||||
contract: [Predicate | Schema | Condition],
|
||||
provenance: [SourceRef],
|
||||
hashes: { interface, implementation, dependency_closure, evidence },
|
||||
verification: VerificationRecord
|
||||
}
|
||||
```
|
||||
|
||||
区分以下四个概念:
|
||||
|
||||
- **Identity(身份)**:目标属于哪一知识单元;名称调整可使用迁移映射,不允许悄悄重绑定到不同实体。
|
||||
- **Content(内容)**:符号当前定义和可执行 IR;代码变更指纹改变。
|
||||
- **Applicability(适用性)**:参数、业务前提、单位、时间/地区/场景等约束;匹配才可复用。
|
||||
- **Evidence(证据)**:来源、测试与验证结果。证据改变不等同于程序改变,但需要重新评估可信状态。
|
||||
|
||||
### 3.2 Knowledge Reference
|
||||
|
||||
```text
|
||||
KnowledgeRef {
|
||||
label: String,
|
||||
payload_ast: Expr,
|
||||
context: Narrative | Code | Return | Argument | Table | Heading,
|
||||
resolution: ResolvedSymbol | LocalExpression | NavigationURL | Unresolved,
|
||||
target_symbol_id: SymbolId?,
|
||||
target_digest: Digest?,
|
||||
expected_signature: Signature?,
|
||||
required_verification: VerificationPolicy,
|
||||
source_span: SourceSpan
|
||||
}
|
||||
```
|
||||
|
||||
`[描述](E)` 在运行语义上是透明的,但其静态解析必须构建 KnowledgeRef。在调用点将地址绑定到 `SymbolId`,不能每次由 AI 重新解释描述。
|
||||
|
||||
### 3.3 类型 / 知识实体 / 计算能力分别建模
|
||||
|
||||
- `# 诗人` 是 Type;`# 李白 = > 诗人` 在现有语法中仍是**继承/特化**。作为 v2.1 过渡方案可视为“单体知识类”,但不得默认为真正的 `instance_of`。
|
||||
- 事实可以由 `## 出生年份` + 返回值 + 来源表承载;编译器推导为 Fact Artifact。是否是事实要根据可检查的声明/契约,不应仅凭函数名字猜测。
|
||||
- 业务函数如 `## 计算应付` 是 Function/Capability;不应因为带中文说明就被误识别成事实。
|
||||
- 未来需要大规模实体库时,Entity/Fact 应支持表驱动注册,不为每个实体强制生成 Rust 或 Marqdo 类。
|
||||
|
||||
## 4. `[]()` 的确定语义
|
||||
|
||||
### 4.1 一个表面形式、三种解析结果
|
||||
|
||||
| 表面形式 | 静态解释 | `run` | `check` / `view` |
|
||||
|---|---|---|---|
|
||||
| `**总额=[应付](数量*单价)**` | 本地表达式遮蔽 | 求值 | 保存标签、表达式和诊断 |
|
||||
| `**总额=[计算总额](Pricing.计算总额(订单))**` | 知识能力调用 | 绑定后调用 | 检查签名、效应、依赖和版本 |
|
||||
| `文中参见[税率](Policy.税率)` | 叙述知识引用 | 不执行 | 解析、展示受信任/未验证状态,纯目标可选择显式求值 |
|
||||
| `[项目文档](./guide.md)` | 导航链接 | 不执行 | 保持 Markdown 导航 |
|
||||
|
||||
语法上的“同权”是 `()` 与 `**...**` 共用表达式文法;**不是正文和代码拥有相同的执行许可**。 `view` 对具外部效应的目标默认只展示元数据,必须明确授权才允许运行。
|
||||
|
||||
### 4.2 最小语义规则
|
||||
|
||||
```text
|
||||
parse_bracket(label, payload, context) -> KnowledgeRef
|
||||
|
||||
context ∈ executable_context:
|
||||
verify_resolved_target(); evaluate(payload_ast)
|
||||
context ∈ narrative_context:
|
||||
resolve_only(); never_schedule_effects()
|
||||
payload ∈ ordinary_navigation:
|
||||
preserve_as_markdown_link()
|
||||
```
|
||||
|
||||
### 4.3 唯一性与优先级
|
||||
|
||||
1. 当前词法作用域的变量/接收者;
|
||||
2. 当前文档的声明;
|
||||
3. 显式 `import` 命名空间;
|
||||
4. 项目导出索引(受 `--fs-root` 和导出策略约束);
|
||||
5. 内置/已安装扩展。
|
||||
|
||||
如果两个候选都满足同一级优先规则,报 `link.ambiguous`;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。
|
||||
|
||||
### 4.4 类函数 vs 实例方法
|
||||
|
||||
- 目标函数使用 `self/自` → 实例方法,必须有显式接收者。
|
||||
- 函数不使用接收者 → 可由 `类.函数` 调用;不运行类的构造体。
|
||||
- 路径解析到零参函数时可以省略 `()`,但**函数作为一等值的语义必须避免与隐式调用冲突**。建议只有被 `[]()` 用作知识目标、或显式值需求时才触发零参隐式调用;直接 `类.函数` 在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。
|
||||
|
||||
### 4.5 版本策略与效应
|
||||
|
||||
`interface_digest` 代表签名兼容性,`implementation_digest` 代表实现变化,`dependency_closure_digest` 代表传递依赖;`evidence_digest` 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。
|
||||
|
||||
纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。
|
||||
|
||||
## 5. 静态分析、来源与可信性
|
||||
|
||||
### 5.1 五层验证(必须分层报告)
|
||||
|
||||
1. **Parse**:Markdown 结构/语法可解析。
|
||||
2. **Resolve**:目标存在,歧义可消除。
|
||||
3. **Type/Contract**:签名、入参与结构类型、单位、前置条件匹配。
|
||||
4. **Execution/Test**:纯函数或受控沙箱完成运行与测试。
|
||||
5. **Evidence/Domain**:事实来源可访问,内容匹配,满足适用范围;复杂自然语言事实可能需要人工或 LLM 辅助复核,复核结果必须标识非确定性。
|
||||
|
||||
严禁将 `check OK` 展示成“现实知识已被证明正确”。
|
||||
|
||||
### 5.2 诊断码草案
|
||||
|
||||
| Code | 默认级别 | 含义 |
|
||||
|---|---|---|
|
||||
| `link.unresolved` | error | 找不到可绑定的目标 |
|
||||
| `link.ambiguous` | error | 目标符号不唯一 |
|
||||
| `link.kind_mismatch` | error | 把类型/实例/函数错当为可执行知识 |
|
||||
| `link.instance_only` | error | 类调用命中实例方法 |
|
||||
| `link.arg_mismatch` | error | 参数与签名不符 |
|
||||
| `link.effect_forbidden` | error | 当前位置不允许此类副作用 |
|
||||
| `link.target_changed` | warning/error | 被锁定或要求稳定的目标发生变更 |
|
||||
| `knowledge.source_missing` | warning/error | 来源缺失 |
|
||||
| `knowledge.source_changed` | warning | 来源指纹变化尚未复核 |
|
||||
| `knowledge.constraint_unmet` | error | 当前输入不满足适用条件 |
|
||||
| `knowledge.unverified` | info/warning | 可用但未得到所需级别的验证 |
|
||||
| `label.ref_dangling` | error | 标签中反引号引用无法解析(保留已有规则) |
|
||||
| `label.possibly_stale` | hint | 代码变更但描述未更新,需要人工检查 |
|
||||
|
||||
标签里提到的自然语言不能被静态类型系统完全证明。所有自动语义比对必须报告置信限制。
|
||||
|
||||
## 6. 编译器实施架构
|
||||
|
||||
```text
|
||||
Markdown Source
|
||||
│
|
||||
├─ CommonMark/GFM-aware parse + Marqdo lexical context
|
||||
▼
|
||||
Syntax AST (prose + code + table + heading + bracket)
|
||||
▼
|
||||
Symbol Index (module, class, function, fact, export)
|
||||
▼
|
||||
Resolution & Type / Contract / Effect Analysis
|
||||
▼
|
||||
Semantic Artifact IR + KnowledgeRef IR
|
||||
├──────────────┬──────────────────┬───────────────────────┐
|
||||
▼ ▼ ▼ ▼
|
||||
Tree Interpreter Bytecode VM View / Debug EKC/Catalog/MLSP
|
||||
│ │
|
||||
└──────────┬────────────┘
|
||||
▼
|
||||
Agent deterministic reuse
|
||||
```
|
||||
|
||||
**实现优先原则**:统一在语义分析层生成符号与引用元信息。不要在 view、EKC、Agent 中分别重新解析 `.mq.md` 来猜同一段代码代表什么。
|
||||
|
||||
### 6.1 Markdown 链接兼容性
|
||||
|
||||
`[描述](含空格或括号的表达式)` 不是任意标准 Markdown 渲染器都可识别的合法 URL 目标。Marqdo 必须定义其**源码级别的上下文语义和渲染行为**:先保留有意义的源码跨度,再由专属 view 转为原生可读的标签及悬浮信息;不能假设 GitHub Markdown 会在所有表达式上正确渲染。代码围栏、行内代码、转义以及普通 URL 链接不能被误识别成可执行引用。
|
||||
|
||||
### 6.2 旧语法迁移
|
||||
|
||||
Classic 的 `[键](集合)` 曾用于取元,`- [项](集合)` 曾用于循环。默认统一为遮蔽含义前,需要 AST 辅助迁移:
|
||||
|
||||
```text
|
||||
[key](table) → [可读描述](at(table, key))
|
||||
- [item](list) → - [逐项遍历](遍历 list 为 item)
|
||||
```
|
||||
|
||||
避免靠简单正则批量替换;不能把旧代码成功运行但产生不同值视为兼容。迁移应生成审计报告、变更 diff 与双后端对照测试。
|
||||
|
||||
## 7. EKC 与 Agent 复用协议
|
||||
|
||||
当前 EKC 已有 Symbol、Capability、Knowledge、Context Pack、REUSE→ADAPT→CREATE。将这些能力变为统一 Semantic Artifact 的**投影/索引**,不要再建第二套符号管理器。
|
||||
|
||||
Agent 必须按以下状态机处理:
|
||||
|
||||
```text
|
||||
TASK → DISCOVER → RESOLVE → CONTRACT_CHECK
|
||||
│ │
|
||||
│ ├─ verified + applicable → REUSE → EXECUTE → TRACE
|
||||
│ ├─ adaptable → ADAPT → VERIFY → PROMOTE
|
||||
│ └─ absent/unusable → CREATE → VERIFY → PROMOTE
|
||||
└─ ambiguous → REQUEST_DISAMBIGUATION / FAIL_CLOSED
|
||||
```
|
||||
|
||||
- **Discovery 是召回**,可以模糊检索,不等于可信复用。
|
||||
- **Resolve 必须精确**,让自然语言意图最终绑定到具体 `SymbolId`。
|
||||
- **Reuse 是编译器行为**:Agent 持有可验证引用,并使用明确的输入与契约,不复制代码段。
|
||||
- **Promote 是门槛**:新生成内容必须通过所需静态检查、测试与来源规则才可进入已验证知识索引。
|
||||
- **Trace 可审计**:保存“这次回答具体用了哪些符号、哪些版本和哪些输入”,不是仅存 LLM 的解释文本。
|
||||
|
||||
建议新增的 MLSP 读接口:`artifact.find`、`artifact.inspect`、`link.resolve`、`artifact.verify`、`artifact.impact`、`artifact.bind`;后者在编译器确定性解析后返回可调用句柄/引用描述,不应凭自然语言标签直接执行。
|
||||
|
||||
## 8. 里程碑与硬验收
|
||||
|
||||
### M0 语义冻结
|
||||
|
||||
明确新语义与 Classic 的区别,形成机器可读 gold cases,涵盖 URL、嵌套括号、空标签、取元、循环、代码围栏、换行、标题、叙述链接与作用域。所有未经标注的旧语义变化不得静默放行。
|
||||
|
||||
### M1 符号身份与项目索引
|
||||
|
||||
构建导出符号表、稳定 `SymbolId`、同名诊断。验收:同仓两个 `李白` 定义应报歧义;限定名可解析;改变目录扫描顺序不影响绑定结果。
|
||||
|
||||
### M2 统一 Bracket IR 与类函数调用
|
||||
|
||||
语法识别→表达式解析→目标绑定→双后端执行。验收:含 `self` 与不含 `self` 的函数正确分派,构造不产生意外副作用;正文不自动执行。
|
||||
|
||||
### M3 Semantic Artifact / 验证
|
||||
|
||||
签名、effect、contract、provenance、验证记录与指纹。验收:接口修改、依赖修改、证据变化、适用条件不匹配得到不同诊断。
|
||||
|
||||
### M4 EKC、view、agent 集成
|
||||
|
||||
整个工具链共享 SymbolId/LinkInfo,生成 links graph、可查看调用与来源、可追踪复用。验收:图边与实际编译的调用目标完全一致;Agent 命中已有能力时不得偷偷生成新实现。
|
||||
|
||||
### M5 基准实验(对照 Python/Notebook/普通 Markdown+检索)
|
||||
|
||||
同一模型、同一任务集、相当的工具与提示预算;分别统计可执行成功率、知识错误引用率、重复实现比例、文件改动数、调用/修复次数、总 tokens、端到端时延、可复核程度。公开任务、生成器、冻结环境、置信区间和失败样本;不要使用只在 Marqdo 方案可解的夹具,也不要把编译器固有优势等同整个 Agent 的领先。
|
||||
|
||||
## 9. 设计原则冻结
|
||||
|
||||
1. **源码可读,编译结果确定**。
|
||||
2. **知识是制品,不是文本片段**。
|
||||
3. **检索可以模糊,绑定必须确定**。
|
||||
4. **知识能够执行,但执行不等于真实**。
|
||||
5. **知识可以复用,但必须满足契约与适用条件**。
|
||||
6. **显示文字可自由,语义判断不依赖显示文字**。
|
||||
7. **默认保持叙述安全,副作用需要明确执行上下文**。
|
||||
8. **保持一种语法,一个语义解析器,一套符号索引**。
|
||||
9. **双后端与 view/EKC 使用同一份语义中间表示**。
|
||||
10. **失败必须可观察,不能因为链接看起来优雅而隐去错误**。
|
||||
|
||||
## 10. 来源依据
|
||||
|
||||
仓库:<https://github.com/cflmy/marqdo>。重点阅读:
|
||||
|
||||
- `README.md`(v2.0.0 现状与 v2.1 目标)
|
||||
- `doc/design/markdown-mapping-v0.3.md`(基本语法)
|
||||
- `doc/design/objects.md`(类、实例、自/self、继承)
|
||||
- `doc/design/link-syntax.md`(现有链接设计声明)
|
||||
- `doc/design/occlusion-syntax.md`(遮蔽与描述新鲜度)
|
||||
- `doc/design/knowledge-layers.md`(知识分层、过渡型单体类)
|
||||
- `doc/design/engineering-knowledge.md`(EKC 与复用流程)
|
||||
- `.cursor/skills/marqdo/reference.md` 与 `examples.md`(参考语法;其部分 Classic 旧写法必须经过迁移)
|
||||
|
||||
附录项目:`Marqdo_Executable_Knowledge_Example.md`。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,400 @@
|
||||
# Marqdo 可执行知识范式:多文件完整示例与对照
|
||||
|
||||
> **规范性目标示例**:用于描述 v2.1+ 期望语义;并非宣称 v2.0.0 已能运行所有代码。示例内价格、折扣、门槛均为虚构业务数据。
|
||||
> 展示:Markdown 叙述、frontmatter 导入、`#` 类型、`##` 函数、继承、表格集合、隐式形参、`**` 代码、`*` 返回、条件有序列表、循环无序列表、变量反引号、带描述的 `[]()`、对象、契约、来源、知识索引与 Agent 复用。
|
||||
|
||||
## 1. 实际业务场景
|
||||
|
||||
一家虚构的“云雀书店”需要将定价规则维护为**人类可阅读的运营文档**,由网站、客服机器人、后端结算、审计报告复用,而不是让四个 AI 分别根据文字重新写四次逻辑。业务规则:普通会员 100% 计价,银卡会员 95%,金卡会员 90%;订单满 100 元免 8 元运费;仅处理人民币订单,件数为正整数。所有规则均为示例,没有现实效力。
|
||||
|
||||
### 项目结构
|
||||
|
||||
```text
|
||||
bookshop/
|
||||
├─ corpus/
|
||||
│ └─ pricing-policy.md # 业务原始资料(不可执行)
|
||||
├─ knowledge/
|
||||
│ ├─ policy.mq.md # 已编译的政策知识
|
||||
│ ├─ order.mq.md # 数据类型及订单操作
|
||||
│ └─ pricing.mq.md # 定价能力
|
||||
├─ apps/
|
||||
│ ├─ checkout.mq.md # 业务执行入口
|
||||
│ ├─ assistant.mq.md # AI 问答呈现/知识引用
|
||||
│ └─ batch.mq.md # 列表与循环
|
||||
└─ .marqdo/ # 生成:catalog、symbols、graph、links.lock
|
||||
```
|
||||
|
||||
## 2. 原始资料 `corpus/pricing-policy.md`
|
||||
|
||||
```markdown
|
||||
# 云雀书店价格政策(演示)
|
||||
|
||||
生效范围:2026 年演示订单,人民币;不代表任何真实商店。
|
||||
|
||||
## 会员折扣
|
||||
|
||||
普通会员不优惠;银卡会员九五折;金卡会员九折。
|
||||
|
||||
## 运费
|
||||
|
||||
商品合计满 100 元免运费,否则运费为 8 元。
|
||||
|
||||
## 约束
|
||||
|
||||
商品单价不得为负;数量必须为正整数。会员等级仅允许普通、银卡、金卡。
|
||||
```
|
||||
|
||||
这是原始证据,并非运行时调用目标。它可被查看、引用和版本化,但不能因为被 AI 读到就自动获得 `verified` 状态。
|
||||
|
||||
## 3. 政策知识 `knowledge/policy.mq.md`
|
||||
|
||||
使用现有类/函数、返回值与契约表,将业务知识拆成稳定的、可发现的编译单元。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 云雀书店演示定价政策
|
||||
type: policy
|
||||
---
|
||||
|
||||
# 书店政策
|
||||
|
||||
这是云雀书店的演示业务政策,供结算、客服和审计引用。
|
||||
|
||||
规则只适用于人民币演示订单,来源为
|
||||
[价格政策原文](../corpus/pricing-policy.md)。
|
||||
|
||||
## 金卡折扣
|
||||
|
||||
| 返回 | 类型 | 单位 | 来源 |
|
||||
|---|---|---|---|
|
||||
| 0.90 | number | ratio | corpus/pricing-policy.md#会员折扣 |
|
||||
|
||||
*0.90*
|
||||
|
||||
## 银卡折扣
|
||||
|
||||
| 返回 | 类型 | 单位 | 来源 |
|
||||
|---|---|---|---|
|
||||
| 0.95 | number | ratio | corpus/pricing-policy.md#会员折扣 |
|
||||
|
||||
*0.95*
|
||||
|
||||
## 免运费门槛
|
||||
|
||||
| 返回 | 类型 | 单位 | 来源 |
|
||||
|---|---|---|---|
|
||||
| 100 | number | CNY | corpus/pricing-policy.md#运费 |
|
||||
|
||||
*100*
|
||||
|
||||
## 基础运费
|
||||
|
||||
| 返回 | 类型 | 单位 | 来源 |
|
||||
|---|---|---|---|
|
||||
| 8 | number | CNY | corpus/pricing-policy.md#运费 |
|
||||
|
||||
*8*
|
||||
|
||||
## 获取折扣
|
||||
|
||||
根据输入会员等级`等级`确定折扣比例。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 等级 | text | 普通、银卡、金卡 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 比例 | number | 0 到 1 之间的比例 |
|
||||
|
||||
1. `等级` == "金卡"
|
||||
*[金卡优惠比例](书店政策.金卡折扣)*
|
||||
2. `等级` == "银卡"
|
||||
*[银卡优惠比例](书店政策.银卡折扣)*
|
||||
3. *
|
||||
*1*
|
||||
```
|
||||
|
||||
**说明**:`书店政策.金卡折扣` 等类函数直接调用属于 v2.1 目标;现有 `#` 类型/`##` 方法和表格、分支是当前语言能力。严格策略下,非法会员等级应报 `knowledge.constraint_unmet` 而不是无条件走默认分支;此处末尾 `3. *` 只是语言分支结构示范,正式实现需要额外拒绝非法等级。
|
||||
|
||||
## 4. 订单类型与继承 `knowledge/order.mq.md`
|
||||
|
||||
```markdown
|
||||
# 订单
|
||||
|
||||
一个订单至少包含数量、单价和会员等级。
|
||||
|
||||
## 描述
|
||||
|
||||
本方法使用`自`读取对象字段,属于**实例方法**。
|
||||
|
||||
*自*
|
||||
|
||||
# 线上订单 = > 订单
|
||||
|
||||
线上订单是订单类型的一个特化。此处是实际继承语义,不把它误称为“知识实体实例化”。
|
||||
|
||||
## 渠道
|
||||
|
||||
*"online"*
|
||||
```
|
||||
|
||||
注意:`# 线上订单 = > 订单` 在 Marqdo 中的确代表子类型继承;`> 线上订单` 构造实例,实例方法需要实例接收者。在知识分层中,普通 Fact 不应强制视为类实例。
|
||||
|
||||
## 5. 核心能力 `knowledge/pricing.mq.md`
|
||||
|
||||
这是“知识直接被复用”的核心,而不是把文字重新交给 AI 算一遍。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 价格计算能力
|
||||
import policy:knowledge/policy.mq.md
|
||||
---
|
||||
|
||||
# 定价
|
||||
|
||||
下列函数实现演示书店的结算规则,适用于人民币演示订单。
|
||||
|
||||
## 计算商品小计
|
||||
|
||||
输入商品`单价`和`数量`。
|
||||
|
||||
| 参数 | 类型 | 约束 |
|
||||
|---|---|---|
|
||||
| 单价 | number | 大于等于 0;单位 CNY |
|
||||
| 数量 | number | 大于 0,且为整数 |
|
||||
|
||||
| 返回 | 类型 | 单位 |
|
||||
|---|---|---|
|
||||
| 小计 | number | CNY |
|
||||
|
||||
**小计 = [商品小计](单价 * 数量)**
|
||||
*小计*
|
||||
|
||||
## 计算运费
|
||||
|
||||
根据商品折扣后的金额`金额`决定是否免运费。
|
||||
|
||||
1. `金额` >= [免运费门槛](书店政策.免运费门槛)
|
||||
*0*
|
||||
2. *
|
||||
*[基础运费](书店政策.基础运费)*
|
||||
|
||||
## 计算应付金额
|
||||
|
||||
接受`单价`、`数量`、`等级`;输出应付总金额。
|
||||
|
||||
**小计 = [商品小计](定价.计算商品小计(单价, 数量))**
|
||||
**折扣 = [当前会员折扣](书店政策.获取折扣(等级))**
|
||||
**折后价 = [折扣后商品金额](小计 * 折扣)**
|
||||
**运费 = [应收运费](定价.计算运费(折后价))**
|
||||
**应付 = [最终应付人民币金额](折后价 + 运费)**
|
||||
*应付*
|
||||
```
|
||||
|
||||
**目标能力标记**:这一示例使用 `类.函数` 静态调用、跨文档自动类索引以及嵌入条件表达式中的知识引用,这些是计划实现的语义。当前实际版本中,一般需要显式 `import` 和实例句柄。其余 `**代码**`、`*返回*`、契约表、分支为现有基础。
|
||||
|
||||
这里看得最清楚:对读者,整段代码是一个有清晰描述的计算故事;对编译器,括号内是有类型、依赖、来源的调用图;对 AI,复用的不是价格公式的自然语言解释,而是绑定到已有符号的能力。
|
||||
|
||||
## 6. 结算入口 `apps/checkout.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 演示结算
|
||||
import pricing:knowledge/pricing.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
一位金卡用户购买两件单价 60 元的商品。
|
||||
|
||||
**单价 = 60**
|
||||
**数量 = 2**
|
||||
**等级 = "金卡"**
|
||||
|
||||
**应付 = [本次订单应付款](定价.计算应付金额(单价, 数量, 等级))**
|
||||
|
||||
> 打印 内容=`应付`
|
||||
```
|
||||
|
||||
预期:`60 × 2 × 0.90 = 108` 元,达到免运费门槛,输出 `108`。这是目标语义下的预期值,而非当前版本的实测输出。
|
||||
|
||||
**对照(相对现有版本更接近可执行)**:使用 `import`、构造实例,再调用实例方法。下面的最小兼容样例来自仓库 `examples/link-syntax/main.compat.mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
import libai:libai.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**li = > libai.李白**
|
||||
**year = [李白的出生年份](li.李白的出生年份())**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
此兼容片段是仓库实例,不能直接替代上面的定价案例:它用于说明当前版本与目标引用模型之间的差距。
|
||||
|
||||
## 7. 文档问答 `apps/assistant.mq.md`
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
# 云雀书店结算说明
|
||||
|
||||
普通会员原价结算;金卡会员使用[已登记的金卡折扣](书店政策.金卡折扣)。
|
||||
|
||||
当前免运费门槛为[已登记的门槛金额](书店政策.免运费门槛)。
|
||||
|
||||
关于政策出处,参见[原始价格政策](../corpus/pricing-policy.md)。
|
||||
```
|
||||
|
||||
这展示**知识链接与导航链接共存**:前两条必须由编译器解析知识目标,最后一条仍是传统 Markdown 导航。不应把全文正文都作为主动执行入口。UI 可以显示“来源文件/目标类型/验证状态/必要时的值”;若目标未验证,应明确标注。
|
||||
|
||||
## 8. 表格几何与循环 `apps/batch.mq.md`
|
||||
|
||||
演示一列 List、横表 Map、`@` 行向记录、无序列表循环和条件分支。根据 v2.0 新语义,旧 `[key](collection)` 取元改为 `at(collection,key)`。
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`会员等级` =
|
||||
|
||||
| 等级 |
|
||||
|---|
|
||||
| 普通 |
|
||||
| 银卡 |
|
||||
| 金卡 |
|
||||
|
||||
`折扣说明` =
|
||||
|
||||
| 普通 | 银卡 | 金卡 |
|
||||
|---|---|---|
|
||||
| 1 | 0.95 | 0.90 |
|
||||
|
||||
`演示订单` =
|
||||
|
||||
| @ | 客户 | 等级 | 单价 | 数量 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 甲 | 金卡 | 60 | 2 |
|
||||
| 2 | 乙 | 银卡 | 30 | 2 |
|
||||
|
||||
**银卡比例 = [银卡折扣值](at(折扣说明, "银卡"))**
|
||||
|
||||
- [逐个检查会员等级](遍历 会员等级 为 等级)
|
||||
1. `等级` == "金卡"
|
||||
> 打印 内容="识别到金卡会员"
|
||||
2. *
|
||||
> 打印 内容=`等级`
|
||||
```
|
||||
|
||||
表格语义:单列→List;两列以上一数据行→Map;首列 `@`→按行组成的 List of Map。此处只演示集合构造、访问与循环,避免假定尚未验证的嵌套函数语义。`遍历` 链接循环是新设计形式,必须通过现有版本的解析器验收后才能标记为已实现。
|
||||
|
||||
## 9. 编译后的产物应当长什么样
|
||||
|
||||
下列均是**建议输出示意**,不是现有 CLI 的真实输出:
|
||||
|
||||
```json
|
||||
{
|
||||
"symbol": "knowledge://bookshop/定价/计算应付金额",
|
||||
"kind": "capability",
|
||||
"signature": {
|
||||
"params": ["单价:number", "数量:number", "等级:text"],
|
||||
"returns": "number:CNY"
|
||||
},
|
||||
"dependencies": [
|
||||
"knowledge://bookshop/定价/计算商品小计",
|
||||
"knowledge://bookshop/书店政策/获取折扣",
|
||||
"knowledge://bookshop/定价/计算运费"
|
||||
],
|
||||
"effects": ["pure"],
|
||||
"verification": {"parse": "ok", "resolve": "ok", "contracts": "ok", "evidence": "pending"}
|
||||
}
|
||||
```
|
||||
|
||||
假设用户把政策金卡折扣由 0.90 改为 0.88,正确行为应该是:
|
||||
|
||||
1. `书店政策.金卡折扣` 的实现摘要变化;
|
||||
2. `书店政策.获取折扣` 与 `定价.计算应付金额` 的传递依赖指纹变化;
|
||||
3. 所有引用这些知识的文档都能由 `impact` 找到;
|
||||
4. 如果使用 lock,校验报告“知识目标变更”,而不是静默引用新版;
|
||||
5. 修改政策的原始来源还需要单独复核,不把源码更新等同于证据更新;
|
||||
6. Agent 必须先检查适用性和验证状态,不能拿一个未复核的版本装作确定事实。
|
||||
|
||||
## 10. AI 原生复用:有无语义制品的差别
|
||||
|
||||
**传统文档 + RAG**:
|
||||
|
||||
```text
|
||||
用户问“金卡买两件 60 元的商品多少钱?”
|
||||
→ 检索到价格政策.md
|
||||
→ LLM 阅读、复述并临时写计算步骤
|
||||
→ 得到 108(本次碰巧正确)
|
||||
→ 下次又重新解释规则,可能遗漏免运费条件
|
||||
```
|
||||
|
||||
**Marqdo 目标路径**:
|
||||
|
||||
```text
|
||||
用户请求
|
||||
→ EKC.find("计算应付金额") // 发现候选,不等于信任
|
||||
→ artifact.inspect(定价.计算应付金额) // 得到签名、适用范围、来源
|
||||
→ link.resolve(...) // 确定性绑定具体符号
|
||||
→ verify(contract, input) // 单价60、数量2、等级金卡
|
||||
→ execute(bound_symbol, input) // 执行编译制品,得到108
|
||||
→ trace(symbol+digest+input+result) // 可审计记录
|
||||
→ AI 用自然语言解释结果
|
||||
```
|
||||
|
||||
AI 不必记住“满百免运费”的公式,也不用每次生成新的结算代码。它需要做的是找准能力、验证条件并引用它。
|
||||
|
||||
## 11. 演示必须通过的负例
|
||||
|
||||
| 变更/攻击输入 | 期待结果 |
|
||||
|---|---|
|
||||
| 将 `书店政策.金卡折扣` 改名但未迁移引用 | `link.unresolved` |
|
||||
| 新增第二个同名 `书店政策` | `link.ambiguous` |
|
||||
| 对 `定价.计算应付金额` 漏传数量 | `link.arg_mismatch` |
|
||||
| 数量传入 0 | `knowledge.constraint_unmet` |
|
||||
| 来源 `pricing-policy.md` 删除 | `knowledge.source_missing` |
|
||||
| 来源内容变化但知识函数不变 | `knowledge.source_changed` |
|
||||
| 来源规则仍然正确但业务已过期 | 需要过期/适用期检查,不能自动声称 verified |
|
||||
| 尝试在正文链接里执行网络支付 | `link.effect_forbidden` 或只解析不执行 |
|
||||
| 标签写“免费”但表达式仍产生费用 | 结构检查可能通过;标签语义审查需报警或人工审核,不得保证静态证明 |
|
||||
| 类实例方法经 `类.方法` 直接调用 | `link.instance_only` |
|
||||
|
||||
## 12. 为什么这个范式更强
|
||||
|
||||
1. **人类维护规则**:读的是 Markdown 业务故事、表格与政策,不是必须遍历全仓源码。
|
||||
2. **编译器复用行为**:跨文档引用已绑定语义制品,避免重复造轮子。
|
||||
3. **错误能被提前拦截**:同名、失效、类型、契约、来源变化有各自诊断。
|
||||
4. **审计能回答“依据是什么”**:结果、符号、版本、输入和来源可追踪。
|
||||
5. **AI 只负责不确定环节**:意图匹配、适用性判断、结果解释;确定性的计算留给编译制品。
|
||||
6. **上下文可以缩短,但不是无条件保证**:目标是让 Agent 读取能力摘要而非每次粘贴全部实现;是否节省 tokens 需要客观实验。
|
||||
|
||||
**核心竞争力不是 Markdown 链接本身,而是“自然语言描述 → 精确符号绑定 → 可验证语义制品 → 执行与复用”的完整链条。**
|
||||
|
||||
## 13. 语法覆盖与非目标
|
||||
|
||||
本示例涵盖语法主干,但“全部语法”还包括外联代码围栏、公式 `$$`、浏览器/WASM、原生插件 ABI、量子与线性代数扩展、MCP/Agent、网络和文件 API 等。它们的具体运行依赖扩展与环境,不能当作知识引用所必需的语言核心;统一 IR 应允许这些能力以受效应约束的 Artifact 注册和复用,而不必将每种扩展硬塞入同一个教学案例。
|
||||
|
||||
建议另建生态回归套件:
|
||||
|
||||
- foreign/LLM/network 函数注册为 EffectSet 的非纯函数;
|
||||
- 数学公式与表格按返回类型编译为 Artifact;
|
||||
- 浏览器和 Web 插件导出的能力经符号索引显式引用;
|
||||
- Agent 的复用接口通过 MLSP 获得固定签名与效果说明。
|
||||
|
||||
## 14. 原仓库参考资料
|
||||
|
||||
- <https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md>
|
||||
- <https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md>
|
||||
- <https://github.com/cflmy/marqdo/blob/main/doc/design/objects.md>
|
||||
- <https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md>
|
||||
- <https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md>
|
||||
- <https://github.com/cflmy/marqdo/blob/main/examples/link-syntax/main.compat.mq.md>
|
||||
@@ -0,0 +1,83 @@
|
||||
# 可执行知识语法:仓库级测试与兼容性规程
|
||||
|
||||
本文是 `Marqdo_Executable_Knowledge_Development.md` 的验证规程。它约束稳定符号 URI、零参数知识路径、关联函数/实例方法区分及其 CLI 解析进入标准库、扩展库和发布流程后的测试方式。
|
||||
|
||||
## 覆盖目标
|
||||
|
||||
新写法只在需要值的位置把零参数路径解释为调用:
|
||||
|
||||
```marqdo
|
||||
**pi = math.pi**
|
||||
**year = facts.Person.birth_year**
|
||||
```
|
||||
|
||||
旧的 `**pi = > math.pi**` 和 `> math.pi` 继续兼容。对象子函数不读取 `self` / `自` 时是 `associated_function`;读取接收者时是 `instance_method`,不能由 `Type.method` 直接执行。
|
||||
|
||||
每项语法变更必须同时证明:新写法正确、旧写法未回归、Tree/Bytecode 一致、CLI 静态解析和运行时规则一致,并且标准库与扩展库仍能加载、运行。
|
||||
|
||||
## 自动化测试矩阵
|
||||
|
||||
| 层级 | 覆盖内容 | 命令 | 通过条件 |
|
||||
|---|---|---|---|
|
||||
| 解析 | 零参路径降级 Call;带参路径不能静默执行 | `cargo test --locked --lib parse::expr` | AST、参数数与诊断稳定 |
|
||||
| 语义 | ProjectRoot、ModuleId、SymbolId、关联/实例分类、歧义 | `cargo test --locked --lib sema::` | 扫描顺序不影响结果;分类不改变 SymbolId |
|
||||
| Tree | 标准库裸路径、关联函数、旧写法 | `cargo test --locked --test gold structure_new_path_stdlib structure_ns_associated_function` | stdout 金样一致 |
|
||||
| Bytecode | 同一正例的后端一致性 | `cargo test --locked --test gold bytecode_new_path_stdlib bytecode_ns_associated_function` | stdout、退出码一致 |
|
||||
| 负例 | 接收者依赖路径被拒绝 | `cargo test --locked --test gold error_ns_instance_method knowledge_resolve_rejects_instance_path` | 不构造对象、不执行方法 |
|
||||
| CLI | `inspect` / `resolve` JSON | `cargo test --locked --test gold knowledge_resolve_new_path` | 返回 URI、source、callable;resolve 不执行代码 |
|
||||
| 标准库 | 英文/中文零参知识 | `cargo test --locked --test gold lib_log_uuid_smoke lib_log_uuid_zh_smoke` | `uuid.v4` 等裸路径可用 |
|
||||
| 扩展库 | 改写后的扩展调用和插件加载 | `cargo test --locked --test gold ext_quantum_gates_smoke` | `math.pi` 新写法输出不变 |
|
||||
|
||||
## 每次语法改动的执行顺序
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh
|
||||
cargo check --locked
|
||||
cargo test --locked --lib
|
||||
cargo test --locked --test gold -- --test-threads=1
|
||||
cargo test --locked
|
||||
cargo build --locked
|
||||
```
|
||||
|
||||
发布前再做可观察的 CLI/双后端冒烟:
|
||||
|
||||
```bash
|
||||
target/debug/marqdo knowledge tests/structure/ns --json resolve \
|
||||
helpers.Box.birth_year --from tests/structure/ns/associated.mq.md
|
||||
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend tree
|
||||
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend bytecode
|
||||
```
|
||||
|
||||
完整 gold 会构建部分原生/Go 扩展,必须单线程执行。网络、真实 LLM 与 ignored 实验不属于离线语法门禁,不能以其失败掩盖核心回归。
|
||||
|
||||
## 标准库与扩展库改写准则
|
||||
|
||||
仅改写可机械证明等价的值表达式:
|
||||
|
||||
| 原写法 | 新写法 | 前提 |
|
||||
|---|---|---|
|
||||
| `**x = > math.pi**` | `**x = math.pi**` | 目标零参数、值位置 |
|
||||
| `**id = > uuid.v4**` | `**id = uuid.v4**` | 目标零参数、值位置 |
|
||||
| `**x = > Type.fact**` | `**x = Type.fact**` | 目标为关联函数 |
|
||||
|
||||
禁止自动改写副作用语句、带必填参数函数、实例方法、文本/围栏/URL/导航链接,以及不能同时通过 Tree/Bytecode 的变更。本轮用 `math.pi`(量子扩展夹具)、`数学.圆周率`(中文标准库夹具)和 `uuid.v4`(标准库夹具)作为真实金样。
|
||||
|
||||
## CLI 合约
|
||||
|
||||
```text
|
||||
marqdo knowledge PATH --json inspect SYMBOL
|
||||
marqdo knowledge PATH --json resolve REFERENCE --from CALLER.mq.md
|
||||
```
|
||||
|
||||
`resolve` 只绑定、不执行。它依据 `--from` 的 frontmatter import 解析第一个路径段,不会在项目中按名字猜测目标。关联函数返回 `resolution: "symbol"`;实例方法返回 `resolution: "instance_only"` 并以退出码 1 拒绝直接路径调用。
|
||||
|
||||
## 发布门槛
|
||||
|
||||
1. `git diff --check` 无错误;
|
||||
2. Rust 核心、gold、完整 `cargo test --locked` 通过;
|
||||
3. 每个新正例有 Tree、Bytecode 和 CLI(适用时)覆盖;
|
||||
4. 每个语义拒绝路径有稳定负例;
|
||||
5. 标准库/扩展库改写保留原 stdout 金样;
|
||||
6. 不提交 `.marqdo/`、插件构建物或本地凭据。
|
||||
|
||||
失败报告必须记录命令、后端、夹具、stdout/stderr、插件/网络依赖及与旧写法的差异。
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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` |
|
||||
@@ -79,7 +79,8 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
+16
-10
@@ -17,8 +17,9 @@ description: 描述文字
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import time:lib/time.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
time: lib/time.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
@@ -35,8 +36,9 @@ import time:lib/time.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -55,7 +57,8 @@ import json:lib/json.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import:
|
||||
agent: ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -71,8 +74,9 @@ import agent:ext/ai/agent.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -98,7 +102,8 @@ import fmt:time.format
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import:
|
||||
agent: ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -143,8 +148,9 @@ project/
|
||||
|
||||
```markdown
|
||||
---
|
||||
import 数学:lib/数学.mq.md
|
||||
import 问候:lib/问候.mq.md
|
||||
import:
|
||||
数学: lib/数学.mq.md
|
||||
问候: lib/问候.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
+10
-5
@@ -56,7 +56,8 @@ Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `li
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -85,7 +86,8 @@ import json:lib/json.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -101,7 +103,8 @@ import text:lib/text.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -114,7 +117,8 @@ import math:lib/math.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -145,7 +149,8 @@ marqdo ext add quantum
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/llm.mq.md
|
||||
import:
|
||||
llm: ext/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -29,7 +29,8 @@ marqdo ext add web
|
||||
|
||||
```markdown
|
||||
---
|
||||
import net:lib/net.mq.md
|
||||
import:
|
||||
net: lib/net.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -84,7 +85,8 @@ route: /
|
||||
method: GET
|
||||
data_source: posts
|
||||
data_order: -created_at
|
||||
import web:ext/web/web.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# 我的站点
|
||||
@@ -118,8 +120,9 @@ response: json
|
||||
|
||||
```markdown
|
||||
---
|
||||
import web:ext/web/web.mq.md
|
||||
import posts:db/posts.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
posts: db/posts.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -145,7 +148,8 @@ import posts:db/posts.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import data:ext/data/db.mq.md
|
||||
import:
|
||||
data: ext/data/db.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -162,7 +166,8 @@ HTTP 门禁与登录走 `ext/security`(`auth` / `rbac` / `oidc`),再用 `w
|
||||
|
||||
```markdown
|
||||
---
|
||||
import rbac:ext/security/rbac.mq.md
|
||||
import:
|
||||
rbac: ext/security/rbac.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -0,0 +1,418 @@
|
||||
# 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) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: agent-okf-flywheel (Wave B0)
|
||||
description: Promote solidified workbook; second plan is cache=hit — document as knowledge base (OKF).
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
fs: lib/fs.mq.md
|
||||
json: lib/json.mq.md
|
||||
plugin: lib/plugin.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: agent-pong (Wave B0)
|
||||
description: >-
|
||||
Constitution demo — call_site + source in step context; optional live CALL via .env.
|
||||
Code is documentation; tools are ## in this same file.
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import time:lib/time.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
plugin: lib/plugin.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
time: lib/time.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
markup: occlusion
|
||||
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
|
||||
import:
|
||||
agent: ext/ai/agent.mq.md
|
||||
fs: lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -19,8 +21,8 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
> 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)**
|
||||
**dry_ok = [ok](access(dry, "ok"))**
|
||||
**dry_committed = [committed](access(dry, "committed"))**
|
||||
1. `dry_ok`
|
||||
1. not `dry_committed`
|
||||
> print text=dry-ok
|
||||
@@ -36,8 +38,8 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
> 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)**
|
||||
**wet_ok = [ok](access(wet, "ok"))**
|
||||
**wet_committed = [committed](access(wet, "committed"))**
|
||||
1. `wet_ok`
|
||||
1. `wet_committed`
|
||||
> print text=wet-ok
|
||||
@@ -52,7 +54,7 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
2. *
|
||||
> print text=proof-missing
|
||||
|
||||
**pname = [name]([profile](wet))**
|
||||
**pname = [name](access([profile](access(wet, "profile")), "name"))**
|
||||
1. `pname` == "default"
|
||||
> print text=profile-default
|
||||
2. *
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/chrome
|
||||
description: 暗恋见君壳层 — head 资源表、导航 HTML、页脚 HTML(对齐 Django base / site_footer)。
|
||||
---
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/feed
|
||||
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
## 帖子列表HTML
|
||||
@@ -11,13 +13,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 +43,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 +81,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,3 +1,7 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 页脚
|
||||
|
||||
站点信息与站长链接(毛玻璃底由壳样式绘制)。
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/fragments
|
||||
description: AJAX 片段 — /post/ten、/news/five。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import db:../db/index.mq.md
|
||||
import feed:feed.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
db: ../db/index.mq.md
|
||||
feed: feed.mq.md
|
||||
---
|
||||
|
||||
## 帖子十
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 首页引言
|
||||
|
||||
英雄区 HTML(品牌标语 + CTA + 漂浮主图)。样式在 `styles/shell` 的 Hero / 动效表。
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/home_body
|
||||
description: 首页主体 HTML — hero + 公告 + 新闻时间线 + 论坛帖子(对齐 Django home.html,无外层导航)。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import feed:feed.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
feed: feed.mq.md
|
||||
---
|
||||
|
||||
## 装配
|
||||
@@ -19,9 +21,9 @@ import feed:feed.mq.md
|
||||
**帖子行 = > 库.查询 表="posts" 上限=10 排序="-created_at"**
|
||||
|
||||
**公告段 = None**
|
||||
- [告](公告行)
|
||||
**文 = [content](告)**
|
||||
**时 = [created_at](告)**
|
||||
- [告](遍历 公告行 为 告)
|
||||
**文 = [content](access(告, "content"))**
|
||||
**时 = [created_at](access(告, "created_at"))**
|
||||
**一项 = "<div class=\"notice-item\"><article class=\"notice-content\">" + 文 + "</article><p class=\"notice-create-time\">" + 时 + "</p></div>"**
|
||||
**公告段 = > table.append list=公告段 item=一项**
|
||||
1. 公告段
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 导航
|
||||
|
||||
顶栏:首页、帖子、新闻、搜索、聊天、发帖(登录后)、后台。
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/page
|
||||
description: 用原站 chrome 包一层完整 HTML 引言(bare 布局)。
|
||||
import text:lib/text.mq.md
|
||||
import chrome:chrome.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
chrome: chrome.mq.md
|
||||
---
|
||||
|
||||
## 包装
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: db/index
|
||||
description: 打开库、建全表、幂等种子、帖子全文索引。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import schema:schema.mq.md
|
||||
import seed:seed.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
schema: schema.mq.md
|
||||
seed: seed.mq.md
|
||||
---
|
||||
|
||||
## 打开
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## posts
|
||||
|
||||
帖子主表。`slug` 用于详情路径;`board` 为板块显示名,`board_id` 关联 `boards`。
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## boards
|
||||
|
||||
帖子板块:日常 / 开发 / 聊天。
|
||||
|
||||
@@ -1,15 +1,17 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 暗恋见君 · Marqdo
|
||||
description: 对齐 Django 暗恋见君:原站 CSS/DOM、首页四段、列表详情、发帖门禁、聊天室、专题、搜索、API 指南。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import chrome:components/chrome.mq.md
|
||||
import page:components/page.mq.md
|
||||
import home:components/home_body.mq.md
|
||||
import feed:components/feed.mq.md
|
||||
import fragments:components/fragments.mq.md
|
||||
import db:db/index.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
chrome: components/chrome.mq.md
|
||||
page: components/page.mq.md
|
||||
home: components/home_body.mq.md
|
||||
feed: components/feed.mq.md
|
||||
fragments: components/fragments.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -140,10 +142,10 @@ import db:db/index.mq.md
|
||||
|
||||
**房间行 = > store.查询 表="chat_rooms" 上限=50**
|
||||
**房间段 = None**
|
||||
- [房](房间行)
|
||||
**名 = [name](房)**
|
||||
**链 = [slug](房)**
|
||||
**摘 = [summary](房)**
|
||||
- [房](遍历 房间行 为 房)
|
||||
**名 = [name](access(房, "name"))**
|
||||
**链 = [slug](access(房, "slug"))**
|
||||
**摘 = [summary](access(房, "summary"))**
|
||||
**项 = "<article class=\"chat-room-card\"><h3><a href=\"/chat/" + 链 + "\">" + 名 + "</a></h3><p>" + 摘 + "</p></article>"**
|
||||
**房间段 = > table.append list=房间段 item=项**
|
||||
**房间内 = > text.str_join xs=房间段 sep=""**
|
||||
@@ -164,10 +166,10 @@ import db:db/index.mq.md
|
||||
|
||||
**专题行 = > store.查询 表="topics" 上限=50**
|
||||
**专题段 = None**
|
||||
- [题](专题行)
|
||||
**题名 = [title](题)**
|
||||
**链 = [slug](题)**
|
||||
**摘 = [summary](题)**
|
||||
- [题](遍历 专题行 为 题)
|
||||
**题名 = [title](access(题, "title"))**
|
||||
**链 = [slug](access(题, "slug"))**
|
||||
**摘 = [summary](access(题, "summary"))**
|
||||
**项 = "<article class=\"topic-card\"><h3>" + 题名 + "</h3><p>" + 摘 + "</p><p class=\"text-muted\">slug: " + 链 + "</p></article>"**
|
||||
**专题段 = > table.append list=专题段 item=项**
|
||||
**专题内 = > text.str_join xs=专题段 sep=""**
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: anlian-mq offline smoke
|
||||
description: 不 listen:装配库表/页面/门禁/WS 路由袋,验证可读路径可构造。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import db:db/index.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
shell: styles/shell.mq.md
|
||||
nav: components/nav.mq.md
|
||||
foot: components/foot.mq.md
|
||||
db: db/index.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -44,7 +46,7 @@ import sys:lib/sys.mq.md
|
||||
**应用 = > 应用.门禁 路径="/write" 角色="admin" 匹配="prefix" 拒绝="redirect"**
|
||||
**应用 = > 应用.路由实时 路径="/chat/ws" 模式="broadcast"**
|
||||
|
||||
**gates = [gates](应用)**
|
||||
**gates = [gates](access(应用, "gates"))**
|
||||
**n = > len value=`gates`**
|
||||
1. `n` >= 2
|
||||
> print text=gates-ok
|
||||
@@ -52,9 +54,9 @@ import sys:lib/sys.mq.md
|
||||
> print text=gates-fail
|
||||
> sys.exit code=1
|
||||
|
||||
**ws = [ws_routes](应用)**
|
||||
**room = [/chat/ws](ws)**
|
||||
**mode = [mode](room)**
|
||||
**ws = [ws_routes](access(应用, "ws_routes"))**
|
||||
**room = [/chat/ws](access(ws, "/chat/ws"))**
|
||||
**mode = [mode](access(room, "mode"))**
|
||||
1. `mode` == "broadcast"
|
||||
> print text=ws-ok
|
||||
2. *
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: styles/shell
|
||||
description: 暗恋见君壳样式——对照 Django 原站粉玻璃 + 动效,用表格声明。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import text:lib/text.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
对照原站 `config/static/front/css/{base,feed_common,footer,index/hero}.css`:
|
||||
|
||||
Loaded 100 of 773 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user