Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bf76e069ee | ||
|
|
9015de26e5 | ||
|
|
8c24d96626 | ||
|
|
4a2f5bf226 | ||
|
|
86e921e959 | ||
|
|
b196a44685 | ||
|
|
c8ed5bffb7 | ||
|
|
fb135ae2f8 | ||
|
|
69fcdd6227 | ||
|
|
deac53d0f5 | ||
|
|
932403237a | ||
|
|
a14a6e221d | ||
|
|
8b0ea9ed7a | ||
|
|
6ae0d39e5a | ||
|
|
307c8efa81 | ||
|
|
34b0911218 | ||
|
|
4488a3cb70 | ||
|
|
9dbcc728b6 | ||
|
|
0405a60d68 | ||
|
|
409b8df2cb | ||
|
|
6bba0be6d2 | ||
|
|
1c90312c02 | ||
|
|
fd0cfcb566 | ||
|
|
6dd0ce47b1 | ||
|
|
1a94cc8490 | ||
|
|
11417c42e0 | ||
|
|
13012cac0e | ||
|
|
5a0f4ed747 | ||
|
|
05b8edc186 | ||
|
|
8926f7bed6 | ||
|
|
18b0c655f7 | ||
|
|
924885969f | ||
|
|
619271b8eb | ||
|
|
719b7a8d82 | ||
|
|
dfe99a10b4 | ||
|
|
fac68e85ea | ||
|
|
639b0ebcd1 | ||
|
|
2c4dac005c | ||
|
|
0ac661eef2 | ||
|
|
1dd74578b5 | ||
|
|
14114993c4 | ||
|
|
e80c944c40 | ||
|
|
30cd5a0833 | ||
|
|
e2068c2051 | ||
|
|
9cda80ee7d | ||
|
|
eae4815fc7 | ||
|
|
3260494e5c | ||
|
|
3330a0fc66 | ||
|
|
42a1a46383 | ||
|
|
b6629e5450 | ||
|
|
ecd7d5e433 | ||
|
|
aeb5a2a43d | ||
|
|
f2d651e063 | ||
|
|
b020b9d218 | ||
|
|
33a14d272c | ||
|
|
6ed70fd8b8 | ||
|
|
115d1f6c0b | ||
|
|
7dc5e56850 | ||
|
|
514caa55ae | ||
|
|
74908ebf04 | ||
|
|
0f852593bc | ||
|
|
34e2fb4f74 | ||
|
|
0e407b2bd3 | ||
|
|
e5e532d83f | ||
|
|
064522a338 | ||
|
|
c85f1a2829 | ||
|
|
a7266185b2 | ||
|
|
4d7c0bea1b | ||
|
|
53758ebd1c | ||
|
|
dff0b700ae | ||
|
|
4da07c1b26 | ||
|
|
78922102e4 | ||
|
|
064bae2c65 | ||
|
|
92b91ffc81 | ||
|
|
ab6648ae0e | ||
|
|
5acf026e0c | ||
|
|
8dcd69412f | ||
|
|
2a13e52981 | ||
|
|
9b269f6447 | ||
|
|
15362cb048 | ||
|
|
05d48f68a4 | ||
|
|
e4387259ba | ||
|
|
518f8e386b | ||
|
|
9da12c9093 | ||
|
|
e0d34669e0 | ||
|
|
0ba4d3d2d7 | ||
|
|
ad3ebf243a | ||
|
|
142d30ce08 | ||
|
|
4757b82edd | ||
|
|
bff2f53e52 | ||
|
|
fb28eee62f | ||
|
|
01468ad976 | ||
|
|
f3791d11b4 | ||
|
|
7fef690167 | ||
|
|
024cdee82a |
No files matched your search
@@ -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.
|
||||
|
||||
@@ -64,6 +64,17 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Occlusion syntax (v2.0.0)
|
||||
|
||||
A file with frontmatter `markup: occlusion` (or `标记: 遮蔽`) reads `[x](y)` as **occlusion**, not index — in that file only (`MARQDO_MARKUP=occlusion` sets the process default; classic files are unchanged).
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
@@ -210,7 +221,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
|
||||
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
|
||||
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
|
||||
- A notebook is still a document: bind `内核表` and `会话表` as ordinary tables inside `# main`. A `view` session adds cell stepping, Run All, kernel switching, journal and reload. No new Markdown marker exists.
|
||||
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
|
||||
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
@@ -126,6 +126,14 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.0.0**:遮蔽语法——`[描述](实现)` 描述不执行 · `()` 内调用 · `access` 取元 · 遮蔽循环 · `labels` / `migrate labels` · view 桩徽章
|
||||
- **v2.0.0**: Occlusion syntax — `[label](payload)` inert prose, paren calls, `access`, occlusion loops, `labels` / `migrate labels`, view stub badges
|
||||
- **v2.0.0 ext**:扩展包同步 2.0.0 / Ext pack 2.0.0
|
||||
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
|
||||
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
|
||||
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
|
||||
+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/
|
||||
|
||||
+108
-1
@@ -1,5 +1,46 @@
|
||||
# Changelog
|
||||
|
||||
## v2.0.0 — 2026-10-22
|
||||
|
||||
### Highlights
|
||||
|
||||
**遮蔽语法(Occlusion)落地**:`[描述](实现)` —— 方括号是给人读的描述(**永不执行**),圆括号是**唯一执行体**。配套 `()` 内调用、`access` 取元、`遍历` 遮蔽循环、`labels` 两级检索与债务棘轮、`migrate labels` 迁移;`view` 把描述渲染为正文、实现渲染为代码片、空载荷给「桩」徽章。全仓 **80 个语料文件 / 256 处取元 / 23 处循环** 已迁移(M7),语义零漂移。
|
||||
|
||||
```bash
|
||||
git checkout v2.0.0 && cargo build --release
|
||||
marqdo ext add web # CDN → 2.0.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)—— 遮蔽是既有 `[键](集合)` 与 `- [项](集合)` 形状在 `markup: occlusion` 文件中的**第二种读法**,默认 `classic` 语义不变;`access` 是宿主函数(id 212),不是新标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **M2 遮蔽语法**:`[描述](实现)`;`[]` 为自由文本、永不执行,`()` 为唯一执行体;支持嵌套;空载荷 `()` 值为 `None`(桩)。frontmatter `markup: occlusion` 按文件启用,`MARQDO_MARKUP=occlusion` 可作进程默认。
|
||||
- **M1 `()` 内调用**:`加(1)` / `加(1, 2)` / `加(加(1 2), 10)` / `加一 号(31)`(callee 可含空格,解决 D8)/ `txt.str_trim(" x ")`;`)` 是参数终止符,逗号可选,支持嵌套;括号形参数按表达式解析,空格形(`> f k=v`)仍按文本。
|
||||
- **M3 `access` 与遮蔽循环**:新增宿主函数 `access(集合, 键)`(别名 `取` / `取值`),与旧取元逐字等价;`- [描述](遍历 集合 为 变量)` 遮蔽循环,接受 `遍历`/`for` 与 `为`/`as`/`in`。
|
||||
- **M2.5 / M4 遮蔽诊断**:`label.missing`(空描述,error)、`label.empty_payload`(空载荷,warning)、`label.ref_dangling`(描述里的反引号实体不可解析,error);由 `marqdo check` 一并输出。
|
||||
- **M5 隐式遮蔽**:`marqdo check --implicit-labels` 把 `>` 调用上方的叙述当作描述(默认关闭,不改变既有输出)。
|
||||
- **M6 T1 会话内陈旧检测**:MLSP `repair_apply` 前后对照 payload 并返回变更的遮蔽点;新增 `session.summary` 会话末一次性汇总。
|
||||
- **M7 迁移与版本门**:frontmatter `markup:` 按文件切换解析模式(同进程可混载 classic / occlusion,imports 亦然);`marqdo migrate labels`(多路径、`--write`、`--json`)把 `[键](集合)` 改写为 `[键](access(集合, "键"))`、`- [项](集合)` 改写为遍历形。
|
||||
- **M8 债务棘轮与呈现**:`marqdo labels --baseline FILE` 记欠据、`--fail-on-increase` 只许降不许升;`view` 浏览 / 卡片 / 静态导出一致呈现遮蔽:描述为正文、实现为代码片、空载荷「桩」徽章。
|
||||
- **M9 两级词表检索**:`marqdo labels`(默认 `pending` 口径 / `--grep` 自定义词 / `--group` / `--also-builtin` / `--count` / `--json`,支持多路径);MLSP `labels.search`;兼容文档写法 `labels pending` / `labels search`。
|
||||
- **M10 工程化落点**:`ext/ai` 提示词加入「接不了就申报」;README「工程习惯」;空载荷一律 warning。
|
||||
- **示例与教程**:`examples/syntax-tour` 一页跑通全部现行语法;`examples/oa2026-showcase`;`doc/tutorial/15-常见陷阱.md`(D1–D10 实测)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **D9 未闭合引号**:不再静默吞掉后续行——分类层与解析层双层修复,直接报错并给出原始行。
|
||||
- **`加(31)`**:曾被解析成 `unknown function 加(31`(末个位置实参吞掉 `)`)。
|
||||
- **view 解析模式回归**:带 `markup: occlusion` 的文档在 `view` 结构区报 `expected ')' after link-index collection`;新增 `load::parse_source_auto` 统一五处解析点。
|
||||
|
||||
### Changed
|
||||
|
||||
- **HostFn 单表**:五张分派表合一为 `HOST_FN_TABLE`(`src/host/dispatch.rs` **−404 行**),203 项逐字节一致,行为零变化。
|
||||
- **插件 ABI 共享 crate**:新增 `marqdo-plugin-sdk`,5 个原生插件共用同一份 ABI 前言;**ABI 不变**(`include/marqdo_abi.h` / 符号与布局不变)。
|
||||
- **精简**:删除归档的 Rust web 插件 `plugins/web-rust-archive/`(14,235 行,非 workspace 成员,已由 Go `libweb` 取代);删除无调用点死代码,收拢 `as_text` 18 处重复、catalog 助手与 view 路由 34 臂,AST 遍历器合流。
|
||||
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
|
||||
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
@@ -8,6 +49,72 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.5.2 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.2 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
|
||||
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
|
||||
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
|
||||
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
|
||||
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`session_list` arity**:保持空 arity。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
|
||||
|
||||
## v1.5.1 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.1 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
|
||||
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
|
||||
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
|
||||
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
|
||||
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
|
||||
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
|
||||
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
|
||||
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
|
||||
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
|
||||
- **写回表标签**:写回表标签保持为行内代码。
|
||||
|
||||
### Changed
|
||||
|
||||
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
|
||||
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
|
||||
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
|
||||
|
||||
## v1.5.0 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
@@ -22,7 +129,7 @@ git checkout v1.5.0 && cargo build --release
|
||||
|
||||
### Added
|
||||
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-notebook` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
|
||||
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
|
||||
|
||||
Generated
+14
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.5.0"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -601,9 +601,16 @@ dependencies = [
|
||||
"zip",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.5.0"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -614,6 +621,7 @@ name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -621,6 +629,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -628,6 +637,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
@@ -637,6 +647,7 @@ name = "marqdo_plugin_llm"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
@@ -646,6 +657,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
+4
-3
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.5.0"
|
||||
version = "2.0.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
|
||||
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
@@ -116,6 +116,50 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 工程习惯:允许申报未完成,但不允许假装完成
|
||||
|
||||
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
|
||||
而欠账是可见、可数、可结算的(而不是假装完成):
|
||||
|
||||
```markdown
|
||||
## 检索资料
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**实现**(唯一执行)。这条语法叫**遮蔽**:
|
||||
把不可读或未完成的实现藏到括号里,人读描述、机器读代码。
|
||||
|
||||
**四条约定**
|
||||
|
||||
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
|
||||
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
|
||||
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
|
||||
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
|
||||
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
|
||||
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels pending # 内置口径:还有多少未完成
|
||||
marqdo labels search --grep "接口未联调,联调中" # 用你自己的说法
|
||||
marqdo labels search --grep 联调 --also-builtin # 自定义 + 内置一起数
|
||||
marqdo labels pending --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
@@ -149,9 +193,11 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.5.0)
|
||||
## 现状(v2.0.0)
|
||||
|
||||
- **外联 v2 / 文档原生 Notebook(v1.5.0)**:结构化 invoke · JSON call/call_many · 并行扇出 · Python/Node 持久内核 · 显式状态桥 · cell 单步/Run All/内核切换 · 高对比浅深主题;扩展包同步 **1.5.0**
|
||||
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0**
|
||||
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
@@ -185,7 +231,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v1.5.0)
|
||||
### 如何使用最新 Marqdo(v2.0.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -200,7 +246,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.5.0 # 或留在 main
|
||||
git checkout v2.0.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -239,7 +285,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.5.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.0.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,195 @@
|
||||
//! Shared ABI plumbing for Marqdo native plugins (`<TAB>` slimming).
|
||||
//!
|
||||
//! Every plugin used to copy the same `MarqdoHostApi` struct, the alloc/free
|
||||
//! statics, `host_strdup`, `set_out`/`set_err`, `parse_args` and `reply`
|
||||
//! (about 140 lines each × 5 crates). This crate holds the single copy; the
|
||||
//! `marqdo_plugin!` macro emits the `#[no_mangle]` exports each `.so` needs.
|
||||
//!
|
||||
//! The ABI itself is unchanged: `include/marqdo_abi.h` and the host loader
|
||||
//! (`src/host/plugin.rs`) still see exactly the same symbols and layout.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
pub use serde_json::{json, Value};
|
||||
|
||||
/// Highest ABI version this SDK speaks.
|
||||
pub const ABI_VERSION: u32 = 2;
|
||||
|
||||
pub type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
pub type HostQueryFn = unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
pub host_query: Option<HostQueryFn>,
|
||||
}
|
||||
|
||||
pub static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
pub static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
pub static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
pub static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
/// Duplicate `s` into host-allocated memory (the host frees it).
|
||||
pub unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
pub fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse the JSON args object handed to a plugin entry point.
|
||||
pub fn parse_args(args_json: *const c_char) -> Result<Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
if s.trim().is_empty() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Write a plugin result (or error) back through the ABI pointers.
|
||||
pub fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
|
||||
match r {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin with no arguments (`host_query`).
|
||||
pub fn host_query_json(name: &str) -> Result<Value, String> {
|
||||
host_query_json_with(name, &json!({}))
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin, passing `args` as its argument object.
|
||||
pub fn host_query_json_with(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let q = unsafe { HOST_QUERY }.ok_or("host_query unavailable")?;
|
||||
let n = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let a = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out: *mut c_char = ptr::null_mut();
|
||||
let mut err: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe { q(HOST_USERDATA, n.as_ptr(), a.as_ptr(), &mut out, &mut err) };
|
||||
if rc != 0 {
|
||||
return Err(take_host_string(err).unwrap_or_else(|| "host_query failed".into()));
|
||||
}
|
||||
let text = take_host_string(out).ok_or("host_query returned nothing")?;
|
||||
serde_json::from_str(&text).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Copy a host-allocated C string into a Rust `String` and free the original.
|
||||
pub fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_string_lossy()
|
||||
.into_owned();
|
||||
if let Some(free) = unsafe { HOST_FREE } {
|
||||
unsafe { free(p as *mut c_void) };
|
||||
}
|
||||
Some(s)
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, f: PluginFn) -> c_int {
|
||||
let Some(reg) = host.register_fn else {
|
||||
return 1;
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { reg(host.userdata, n.as_ptr(), p.as_ptr(), f) }
|
||||
}
|
||||
|
||||
/// Store the host callbacks and register every entry point.
|
||||
pub unsafe fn init_plugin(host: *const MarqdoHostApi, regs: &[(&str, &str, PluginFn)]) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, *f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
/// Emit the four `#[no_mangle]` exports every plugin `.so` must provide,
|
||||
/// wiring `marqdo_plugin_init` to the given registration table.
|
||||
#[macro_export]
|
||||
macro_rules! marqdo_plugin {
|
||||
($version:expr, [ $( ($name:expr, $params:expr, $f:expr) ),* $(,)? ]) => {
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
$version
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(
|
||||
host: *const $crate::MarqdoHostApi,
|
||||
) -> i32 {
|
||||
$crate::init_plugin(host, &[ $( ($name, $params, $f as $crate::PluginFn) ),* ])
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.5.0"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+41
@@ -1,3 +1,44 @@
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
bracketed label is inert prose and the parenthesized payload is the
|
||||
only executed part. Adds paren-call arguments, access() element
|
||||
access, occlusion loops, marqdo labels (two-tier search + debt
|
||||
ratchet), marqdo migrate labels, and label.missing / empty_payload /
|
||||
ref_dangling diagnostics; view renders labels as prose, payloads as
|
||||
code, stubs with a badge. 80 corpus files migrated.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
|
||||
|
||||
marqdo (1.5.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
|
||||
interrupt, plan generation/add/remove/value API, snapshot
|
||||
export/import/replay, view capture for static export, explicit Persist
|
||||
button, nested plan boundary.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
|
||||
|
||||
marqdo (1.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.1: View static/live execution path unified; foreign value
|
||||
passing into multi-kernel sessions; cell stdin for live/static/persistent
|
||||
kernels; build-time execution with stdout injection in static exports;
|
||||
runnable foreign writeback example; writeback block grouping.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
|
||||
|
||||
marqdo (1.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
|
||||
parallel fan-out, persistent Python/Node kernels, explicit state
|
||||
bridge) and document-native notebooks in view; high-contrast
|
||||
light/dark view themes, resizable code/output panes, OKF/EKC and
|
||||
Python examples on the user site. Fixes branch-local variables
|
||||
leaking into required constructor parameters.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
|
||||
|
||||
marqdo (1.4.6-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
|
||||
|
||||
@@ -105,6 +105,15 @@
|
||||
| [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/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
|
||||
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -0,0 +1,250 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「让函数参数从上下文推断,`对**n=31**执行**加一函数**` 这种写法可能吗」 |
|
||||
| 方法 | 运行时实测 8 组 + 全仓库语料扫描(1322 个函数)+ 源码比对 |
|
||||
| 相邻 | [call-syntax-from-marks.md](call-syntax-from-marks.md)(**接替本文 §3 的设计**)· [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
> **后续更正**:本文 §3 提出的 L0「叙述式调用」用**未标记的词**(`执行`)触发调用,
|
||||
> 这会破坏「叙述默认安全、只有标记才执行」的底层原则,已被否决。
|
||||
> 在「只执行标记」约束下重新设计的调用语法见
|
||||
> [call-syntax-from-marks.md](call-syntax-from-marks.md)
|
||||
> (含树遍历 vs 字节码 3.8× 实测、叙述顺序导致位置绑定翻转的实验)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论:你的示例其实**不需要**隐式推断
|
||||
|
||||
先把一个关键事实摆出来:**你的例子里 `n=31` 明明写在那儿**。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
对**n=31**执行**加一函数**
|
||||
```
|
||||
|
||||
`n` 的绑定**就写在句子里**,这不是「从上下文推断」,这是**具名实参换了语序**。
|
||||
所以这个写法需要的是**新的叙述式调用语法**,不是新的作用域语义。
|
||||
|
||||
它今天跑出来的结果很能说明问题:**无输出、无报错、退出码 0**。
|
||||
不是参数推断失败,而是 `执行**加一函数**` 里的裸名字**只是被求值然后丢弃**,
|
||||
从来没被当成一次调用。
|
||||
|
||||
三层拆解:
|
||||
|
||||
| 层 | 写法 | 需要什么 | 裁决 |
|
||||
|----|------|---------|------|
|
||||
| **L0 叙述式调用** | `对**n=31**执行**加一函数**` | 只要语法糖(绑定仍在句中) | ✅ **可做,且安全** |
|
||||
| **L1 就近绑定** | 上一行 `**n=31**`,下一行 `执行**加一函数**` | 段落级隐式作用域 | ⚠️ 能做但危险,不建议 |
|
||||
| **L2 真隐式** | 只写 `执行**加一函数**`,n 全靠上下文 | 动态作用域 | ❌ **不建议**,见 §4 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 实测:今天到底发生了什么
|
||||
|
||||
| # | 用例 | 实测 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 1 | 你的示例原样 | **无输出、无报错、exit 0** | 静默 no-op |
|
||||
| 2 | 同样写法 + `> print text=`n`` | `main里的n=31` | **散文行里的 `**n=31**` 真的执行了** |
|
||||
| 3 | 只写 `对`加一函数`执行` | `done`,无报错 | 裸名字只被求值丢弃,**未调用** |
|
||||
| 4 | `**n = 31**` + `> 加一函数`(不传参) | `missing argument for parameter n` | **函数看不见调用者的 `n`** |
|
||||
| 5 | `> 加一函数 n=31` | `32` | 显式写法今天就能做 |
|
||||
| 6 | `# main` 读 frontmatter `税率` | `0.1` ✅ | 入口可见 |
|
||||
| 7 | `## 函数` 读同一个 `税率` | `undefined variable` ❌ | 函数不可见 |
|
||||
| 8 | 浏览器 WASM 入口调用函数 | metadata + `entry_bindings` **都会传** | 见 §5,**与 CLI 不一致** |
|
||||
|
||||
**第 2 与第 3 条合起来是关键**:散文行里的粗体确实会执行,但一个裸函数名在粗体里
|
||||
只是一个**表达式语句**(值算了就丢),不会变成调用。所以「看起来该调用」的句子,
|
||||
实际什么也没做——又是一次静默失败(与 D9 同一类)。
|
||||
|
||||
**第 4 条是语义基石**:Marqdo 现在的作用域是**严格分离**的,
|
||||
函数只能看到自己的形参与局部变量。你想要的 L2,就要拆掉这块基石。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你自己的担心是对的:数据在这里
|
||||
|
||||
你提到「大项目变量名会难以使用」。我把仓库里 `lib/ ext/ examples/ tests/` 全扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 扫描函数数 | **1322** |
|
||||
| 不同形参名 | 819 |
|
||||
| **被 ≥5 个函数共用的形参名** | **130 个** |
|
||||
|
||||
撞车最严重的一批:
|
||||
|
||||
| 形参名 | 用它的函数数 |
|
||||
|--------|-------------|
|
||||
| `path` | **70** |
|
||||
| `value` | 59 |
|
||||
| `text` | 53 |
|
||||
| `id` | 47 |
|
||||
| `list` | 38 |
|
||||
| `内容` | 38 |
|
||||
| `路径` | 35 |
|
||||
| `a` / `b` | 各 32 |
|
||||
|
||||
结论很直接:**如果参数靠上下文推断,那么每次调用一个读 `text` 的函数,
|
||||
它都会去捡当前作用域里的 `text` 是什么**。53 个函数在等这个值——
|
||||
撞车是常态,不是例外。这不是「大项目才有」的问题,中型项目就已经不可控。
|
||||
|
||||
---
|
||||
|
||||
## 3. L0:叙述式调用(推荐做)
|
||||
|
||||
### 3.1 目标写法
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对`n`我们让**n=n+1**之后返回*n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 对 n=31 执行 加一函数**
|
||||
> print text=`结果` # → 32
|
||||
```
|
||||
|
||||
### 3.2 语义映射(零模型改动)
|
||||
|
||||
```
|
||||
对 <绑定子句> 执行 <函数名> ≡ Call { callee: <函数名>, args: [<绑定子句>…] }
|
||||
```
|
||||
|
||||
也就是**纯粹换语序**的语法糖。它与今天的
|
||||
|
||||
```markdown
|
||||
**结果 = > 加一函数 n=31**
|
||||
```
|
||||
|
||||
产出**同一个 `CallExpr`**。因此:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约校验(T2.1/T2.2) | **不变**(实参照常绑定与校验) |
|
||||
| EKC 指纹 `collect_calls` | **不变**(callee 仍是静态名) |
|
||||
| 字节码 `Op::Call(fid, argc)` | **不变** |
|
||||
| 序列化 / 沙箱 | **不变** |
|
||||
| `view` 渲染 | 需决定回显哪一种语序 |
|
||||
|
||||
这正是它与「一等函数」「动态作用域」的本质区别:**只改写法,不改调用模型。**
|
||||
|
||||
### 3.3 设计细节要定的三件事
|
||||
|
||||
1. **动词**:`执行` 目前**不是**关键字;而 `调用` **已经是**关键字(`src/aliases.rs:39`
|
||||
把 `调用` 映射到内建 `call_fn`)。两个近义词并存会混乱,需要二选一或明确分工。
|
||||
2. **绑定子句的边界**:`对 n=31 执行 …` 里 `n=31` 到 `执行` 之间是参数区;
|
||||
多参数写 `对 n=31 m=2 执行 …`。
|
||||
3. **与散文的冲突**:`对` 起头的行今天是叙述(CJK 开头 = 注释)。
|
||||
要让这行变成代码,得给「叙述里出现 `执行 <函数名>`」一个可判定的规则,
|
||||
否则又是一处「看起来是代码、实际是注释」的静默陷阱。
|
||||
|
||||
---
|
||||
|
||||
## 4. L2:真隐式参数(不建议)
|
||||
|
||||
### 4.1 它到底是什么
|
||||
|
||||
L2 = **动态作用域**(dynamic scoping):被调函数在**调用者的环境**里查找自由变量。
|
||||
历史上被反复试过、也反复放弃:早期 Lisp 改成词法作用域、Shell 的动态作用域被视为坑。
|
||||
|
||||
### 4.2 七条硬伤(每条都是具体后果,不是理论洁癖)
|
||||
|
||||
| # | 问题 | 具体后果 |
|
||||
|---|------|---------|
|
||||
| 1 | **同名捕获** | `加一函数` 调 `记录日志`,两者都读 `text` → 日志函数静默拿到加一的局部值,输出错内容而不报错 |
|
||||
| 2 | **递归自毁** | `n=n+1` 后调自身:内层看到的是**已被改过的** n(还是副本?)——必须新增一套遮蔽规则,而规则本身又会成为新的坑 |
|
||||
| 3 | **无法复用** | 同一函数两次不同入参,只能反复改外部变量并祈祷调用顺序,等于把「参数」退化成全局可变状态 |
|
||||
| 4 | **契约报废** | `call_arg_diag` 在**调用边界**校验实参类型;如果不传实参,就没有校验点。T2.1/T2.2 契约体系直接失效 |
|
||||
| 5 | **指纹/arity 失真** | `collect_calls` 记录被调名,arity 由形参推断;隐式调用在 AST 上看起来是零参调用 → 复用预检、`plan` 能力匹配、查重全都失真 |
|
||||
| 6 | **沙箱与序列化** | `sandbox.run` 以隔离方式执行文档;隐式依赖外部作用域会破坏隔离语义;环境也必须可序列化 |
|
||||
| 7 | **不可审计** | 函数行为依赖看不见的上下文——这就是「全局可变状态」的经典问题,与「文档即程序、可被人读懂」直接冲突 |
|
||||
|
||||
再叠加 §2 的数据(130 个名字被 ≥5 函数共用),第 1 条不是边角情况,而是默认情况。
|
||||
|
||||
### 4.3 但有一个**受限版**值得考虑
|
||||
|
||||
如果你真正想要的是「短脚本读起来顺」,那么下面这个版本是安全的:
|
||||
|
||||
> **常量默认值**:允许函数在**未传入**某形参时,从**文件级常量**取值。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 报价
|
||||
税率: 0.1
|
||||
---
|
||||
|
||||
## 含税
|
||||
+ `金额`
|
||||
|
||||
*`金额` * (`税率`)* # 税率 未传入 → 取 frontmatter 常量
|
||||
|
||||
# main
|
||||
|
||||
**a = > 含税 金额=100** # 10
|
||||
**b = > 含税 金额=100 税率=0.06** # 6,显式覆盖
|
||||
```
|
||||
|
||||
为什么它安全而 L2 不安全:
|
||||
|
||||
| 维度 | L2 动态作用域 | 常量默认值 |
|
||||
|------|--------------|-----------|
|
||||
| 取值来源 | 调用者的**任意**变量 | 文件顶部**写一次**的常量 |
|
||||
| 静态可判定 | ❌ 取决于运行路径 | ✅ 打开文件就能看到 |
|
||||
| 随调用者变化 | ✅ 会变(最危险) | ❌ 不会 |
|
||||
| 契约 | 失效 | 仍可校验(实参照常声明) |
|
||||
| 序列化/沙箱 | 破坏隔离 | 可序列化(常量是数据) |
|
||||
| 复用 | 破坏 | 不受影响 |
|
||||
|
||||
**关键差别**:常量是**文档的一部分**(frontmatter 就在文件开头,人读得到),
|
||||
而动态作用域的值是**运行路径的一部分**(人读不到)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带发现的真问题:CLI 与 Web 的环境不一致
|
||||
|
||||
实测 §1 第 6/7/8 条时发现:
|
||||
|
||||
| 路径 | 函数可见环境 | 源码 |
|
||||
|------|-------------|------|
|
||||
| `# main`(CLI 运行) | frontmatter metadata ✅ | `src/interp.rs:473` `Env::with_metadata` |
|
||||
| **普通函数调用** | 只有实参 ❌ | `eval_call` 用 `Env::new()` |
|
||||
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
|
||||
|
||||
也就是说:**同一份文档,在浏览器里函数能读到 frontmatter 常量、还能读到 `# main`
|
||||
的绑定;在 CLI 里读不到。** 行为随运行面不同而不同。
|
||||
|
||||
这是一个**真实缺陷**,已记入 [D11](../research/qdagent-refactor-defects-2026-10.md):
|
||||
|
||||
- 对使用者:同一文件在 Web 能跑、在 CLI 报 `undefined variable`,极难排查
|
||||
- 对设计:说明「受控环境通道」其实已经存在(只是没在 CLI 打开),
|
||||
这既是 L2 受限版的现成基础,也是必须先统一的地方
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
| 优先级 | 事项 | 性质 |
|
||||
|--------|------|------|
|
||||
| 1 | **先统一 CLI/Web 的函数环境**(D11) | 修缺陷,消除行为分裂 |
|
||||
| 2 | **做 L0 叙述式调用**(`对 X 执行 F`) | 纯语法糖,零模型改动,554 回归可守 |
|
||||
| 3 | 若要「少写参数」,做**常量默认值**(§4.3) | 受控隐式,静态可判定 |
|
||||
| 4 | **不做 L2 动态作用域** | 七条硬伤 + 130 个撞车名 |
|
||||
|
||||
关于「代码即文档」的取向,我的理解是:
|
||||
|
||||
> 文档化的是**写法**(句子怎么读),不是**语义**(值从哪来)。
|
||||
> 让句子更像人话是值得的;让值从看不见的地方来,是把可读性换成不可预测性。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **L0 是否采纳?** 若采纳,动词用 `执行` 还是复用已有的 `调用`?
|
||||
2. **`对…执行…` 的行如何与散文区分**(§3.3 第 3 点)?这决定它会不会变成新的静默陷阱。
|
||||
3. **常量默认值**(§4.3)要不要做?
|
||||
4. **D11(CLI/Web 环境不一致)** 是否现在就修?我建议先修它,因为它会影响 L0/L2 的所有验证结论。
|
||||
@@ -0,0 +1,300 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 |
|
||||
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
|
||||
| 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) |
|
||||
|
||||
> **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`;
|
||||
> 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。
|
||||
> 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)**
|
||||
> 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 先把提案精确化
|
||||
|
||||
你的话可以解析出三种读法,差别很大,必须先分清:
|
||||
|
||||
| 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 |
|
||||
|------|------------|------------|-----------|
|
||||
| **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** |
|
||||
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
|
||||
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
|
||||
|
||||
你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**:
|
||||
**`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么我们会下意识觉得这个写法"美"
|
||||
|
||||
你的直觉不是审美偏好,它对应三个**真实存在**的设计同构:
|
||||
|
||||
### 1.1 超链接:可见文本 ↔ 目标
|
||||
|
||||
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
|
||||
这是人类最早、最成功的"双面文本"。
|
||||
|
||||
### 1.2 文学编程的 chunk 名(Knuth)
|
||||
|
||||
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
|
||||
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
|
||||
|
||||
### 1.3 Marqdo 自己已经有这个形态
|
||||
|
||||
```markdown
|
||||

|
||||
```
|
||||
|
||||
- `[]` 里是**指令/说明**(`marqdo-out`、可带 key)
|
||||
- `()` 里是**负载**(图片 URL / data URI)
|
||||
|
||||
**语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。
|
||||
|
||||
### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看"
|
||||
|
||||
| 用法 | 数量 | 谁读 |
|
||||
|------|------|------|
|
||||
| `[键](集合)` 取元 | 506 | 机器 |
|
||||
| `- [项](集合)` 循环 | 44 | 机器 |
|
||||
| `[函数] 参数` 调用 | **0(可执行)** | — |
|
||||
| `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** |
|
||||
|
||||
**可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。
|
||||
这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强)
|
||||
|
||||
### 2.1 收益一:两条规则变一条 —— 这是最大的价值
|
||||
|
||||
现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结:
|
||||
|
||||
> `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。
|
||||
|
||||
你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句",
|
||||
那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。
|
||||
|
||||
> 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。**
|
||||
> 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。
|
||||
|
||||
### 2.2 收益二:嵌套取元终于可读
|
||||
|
||||
现在是:
|
||||
|
||||
```markdown
|
||||
**第一 = [1]([苹果](货架))**
|
||||
```
|
||||
|
||||
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
|
||||
|
||||
改成标签后:
|
||||
|
||||
```markdown
|
||||
**第一 = [货架里苹果的第一项](…机器语句…)**
|
||||
```
|
||||
|
||||
**人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。
|
||||
|
||||
### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围
|
||||
|
||||
你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。
|
||||
|
||||
**这一点需要精确化,因为它决定这块值不值得改**:
|
||||
|
||||
| 阅读场合 | `- [果](篮子)` 的表现 |
|
||||
|---------|---------------------|
|
||||
| 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 |
|
||||
| **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 |
|
||||
|
||||
而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。
|
||||
|
||||
**结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合
|
||||
(`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事:
|
||||
|
||||
> **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。**
|
||||
> 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。
|
||||
|
||||
这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。
|
||||
|
||||
### 2.4 附带收益:标签是天然的锚点
|
||||
|
||||
你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小:
|
||||
|
||||
- `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位"
|
||||
- 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118`
|
||||
- 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多
|
||||
|
||||
---
|
||||
|
||||
## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元
|
||||
|
||||
这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。
|
||||
|
||||
若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法:
|
||||
|
||||
| 方案 | 形态 | 问题 |
|
||||
|------|------|------|
|
||||
| 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 |
|
||||
| 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 |
|
||||
| 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 |
|
||||
| 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 |
|
||||
|
||||
**这就是核心张力**:
|
||||
|
||||
> 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性;
|
||||
> 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则),
|
||||
> 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。
|
||||
|
||||
换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。**
|
||||
这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」,
|
||||
**用一条新规则换掉一条旧规则,不必然是净简化**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 描述漂移:我认为不能轻描淡写
|
||||
|
||||
你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条:
|
||||
|
||||
### 4.1 它是"注释"的回归
|
||||
|
||||
Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。
|
||||
而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。
|
||||
Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。
|
||||
|
||||
### 4.2 一旦标签成为锚点,漂移就有操作后果
|
||||
|
||||
你在 §2.4 里期望标签用于跳转与定位。那么:
|
||||
|
||||
- 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎**
|
||||
- agent 用标签定位 bug → 被标签误导
|
||||
- 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌
|
||||
|
||||
**标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。
|
||||
|
||||
### 4.3 安全面:标签是 agent 可读的攻击面
|
||||
|
||||
Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。
|
||||
「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。
|
||||
|
||||
**所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**:
|
||||
|
||||
| 缓释手段 | 说明 | 成本 |
|
||||
|---------|------|------|
|
||||
| ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 |
|
||||
| ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 |
|
||||
| ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 |
|
||||
| ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 |
|
||||
|
||||
其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B),
|
||||
而对"标签写得更细"这种正常情况不误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 采用风险:可能重演 v0.3 废除的"仪式感"
|
||||
|
||||
v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。
|
||||
|
||||
强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化:
|
||||
|
||||
1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有
|
||||
2. **噪音**:标签越写越长,正文被切碎,扫描性下降
|
||||
|
||||
这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。
|
||||
所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。
|
||||
|
||||
**这个矛盾必须在设计里正面解决,不能靠自觉。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移面(实测)
|
||||
|
||||
| 受影响的写法 | 数量 | 文件 |
|
||||
|------------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 个文件 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 个文件 |
|
||||
| `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
|
||||
**危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单),
|
||||
而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
|
||||
|
||||
所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报
|
||||
「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。
|
||||
另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 两条落地路线
|
||||
|
||||
### 路线一:双层(推荐,兼容)
|
||||
|
||||
> **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。**
|
||||
|
||||
- **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环
|
||||
- **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写**
|
||||
- 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
|
||||
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
|
||||
| 嵌套可读、循环可写清来源 | |
|
||||
| 标签可以逐步引入,不强迫 | |
|
||||
|
||||
### 路线二:纯度(一条规则到底)
|
||||
|
||||
> `()` 只装机器语句,取元必须搬进 `()`。
|
||||
|
||||
必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
|
||||
| `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 |
|
||||
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 我的评定
|
||||
|
||||
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
|
||||
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|------|------|
|
||||
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
|
||||
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
|
||||
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
|
||||
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
|
||||
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
|
||||
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
|
||||
|
||||
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
|
||||
让短形成为"读得懂但不必写"的兼容层。这样:
|
||||
|
||||
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
|
||||
- 506 处零迁移
|
||||
- 调用终于有家,且成本为零
|
||||
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
|
||||
|
||||
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
|
||||
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
|
||||
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **路线一(双层)还是路线二(纯度)?**
|
||||
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
|
||||
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
|
||||
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
|
||||
5. 循环的新写法你倾向哪一种:
|
||||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||||
- `- [篮子里的果子](篮子 → 果)`
|
||||
- 保留 `- [果](篮子)` 作短形
|
||||
@@ -0,0 +1,287 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 前置纠正 | 用户否决上一轮的「叙述式动词」方案:**未标记词承载语义 = 破坏「叙述默认安全」** |
|
||||
| 方法 | 实测 6 组(含双后端性能对比、叙述顺序实验)+ 源码比对 |
|
||||
| 相邻 | [ambient-parameters-evaluation.md](ambient-parameters-evaluation.md) · [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 先接受纠正:错在哪
|
||||
|
||||
我上一轮提的 `对**n=31**执行**加一函数**`,靠**未标记的词「执行」**来触发调用。这确实违背底层原则:
|
||||
|
||||
> **叙述(未标记)= 默认安全,不执行;标记 = 才进编译器。**
|
||||
|
||||
一旦「执行」这种词能改变语义,那么:
|
||||
|
||||
- 作者改一句措辞("执行" → "运行" / "调用" / 换个说法)就可能改变程序行为;
|
||||
- 读者无法只看标记判断哪句是代码——必须逐字读叙述;
|
||||
- 与 D9 同类的静默风险:语义藏在叙述里。
|
||||
|
||||
**所以本文的设计约束是硬的**:
|
||||
|
||||
> **调用的每一个语义成分(被调者、每个实参、绑定关系)必须落在标记内;
|
||||
> 叙述词只能起连接与解释作用,永不改变语义。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 先盘清「标记字母表」
|
||||
|
||||
要设计调用,先得知道手上只有哪些字。
|
||||
|
||||
| 标记 | 现行语义 | 可否参与构成调用 |
|
||||
|------|---------|-----------------|
|
||||
| `**…**` | 执行段(赋值 / 调用 / 表达式) | ✅ 主载体 |
|
||||
| `*…*` | 返回 | ✅ 终止 |
|
||||
| `` `x` `` | 变量引用;首次出现即声明 | ✅ 槽名 |
|
||||
| `` `x` = `` | 叙述中的绑定 | ✅ 槽赋值 |
|
||||
| `**x = …**` | 赋值 | ✅ |
|
||||
| `> …`(行首) | 调用语句 | ✅ 已是调用标记 |
|
||||
| `[callee] args` | 方括号调用(消歧 / 前置修饰) | ✅ 已是调用标记 |
|
||||
| `[k](coll)` | 取元 | ⚠️ 与调用抢外形(已否) |
|
||||
| `- [x](coll)` | 遍历 | — |
|
||||
| `#` / `##` | 对象 / 函数声明 | — |
|
||||
| 表格 | 数据 / 契约 | — |
|
||||
| ```lang | 外联代码 | — |
|
||||
|
||||
**关键观察**:调用载体其实只有三种标记:`> 行`、`**…**`、`[callee]`。
|
||||
而 `[k](coll)` 这个外形已被取元独占(前几轮结论),不能用。
|
||||
|
||||
所以问题收敛为:
|
||||
|
||||
> **在 `**…**` 或 `> …` 内部,用哪些标记把「函数名」和「槽赋值」连起来?**
|
||||
|
||||
---
|
||||
|
||||
## 2. 可读性从哪来(这是设计的核心)
|
||||
|
||||
Marqdo 的叙述与代码是**两层**:叙述解释「为什么」,标记表达「做什么」。
|
||||
所以可读性不是靠把叙述词变成语法,而是靠:
|
||||
|
||||
1. **标记本身足够像自然记号**(`=`, `(`, `)`, `→` 都是跨语言的);
|
||||
2. **叙述与标记紧邻**,人一句一码地读;
|
||||
3. **同一件事只写一遍**(叙述不要复述代码)。
|
||||
|
||||
一句话:
|
||||
|
||||
> **叙述负责「说人话」,标记负责「说准话」;两者相邻即高可读,混在一起即两败。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 三个候选设计
|
||||
|
||||
### 设计 A — 括注具名调用:`**加一函数(n=31)**`
|
||||
|
||||
**读法**:`加一函数(n=31)` —— 与数学/几乎所有语言的函数调用同构。
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ 整段在 `**…**` 内 |
|
||||
| 无歧义 | ✅ 圆括号紧跟名字 = 调用;取元需方括号,不冲突 |
|
||||
| 与叙述结合 | ✅「把 n 设为 31 后**加一函数(n=31)**」 |
|
||||
| 多参数 | ✅ `f(a=1 b=2)` |
|
||||
| 编译器 | ✅ 具名 → 编译期映射到槽下标(见 §4) |
|
||||
| 实现成本 | ⚠️ 需改参数分词器:`)` 作终止符、逗号、嵌套(原型已验 554/0,但 `f(1 2)` 的末参数会吞 `)`) |
|
||||
|
||||
### 设计 B — 箭头槽赋值:`**n=31 → 加一函数**`
|
||||
|
||||
**读法**:「n 设为 31,交给加一函数」——最贴合汉语「先条件、后动作」语序。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n=31 → 加一函数**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ `→` 是符号标记,不是词 |
|
||||
| 可读性 | ✅✅ 流水线极顺:`**订单 → 计税 → 汇总**` |
|
||||
| 无歧义 | ⚠️ 需定义优先级;`**x = a=1 → f**` 有歧义,得靠括号 |
|
||||
| 求值结果 | ⚠️ 箭头式天然是语句式;要拿返回值还得包一层 |
|
||||
| 实现成本 | 中:新增运算符 + 优先级 + 与 `=`/`*…*` 的交互 |
|
||||
|
||||
### 设计 C — 现成空格式:`**加一函数 n=31**`(今天就可用)
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ |
|
||||
| 实现成本 | **零**(实测 `**r = 加 1 2**` 已可跑) |
|
||||
| 可读性 | ⚠️ 参数边界靠空格;函数名含空格时不可用(D8) |
|
||||
| 编译器 | ✅ 具名同样可映射槽位 |
|
||||
|
||||
### 三者的取舍
|
||||
|
||||
| | A 括注 | B 箭头 | C 空格 |
|
||||
|---|---|---|---|
|
||||
| 像通用函数调用 | ✅✅ | ⚠️ | ✅ |
|
||||
| 中文语序自然 | ⚠️ | ✅✅ | ✅ |
|
||||
| 参数边界清晰 | ✅✅ | ✅ | ❌(空格切分) |
|
||||
| 链式组合 | ⚠️ | ✅✅ | ❌ |
|
||||
| 改动成本 | 中 | 中高 | **零** |
|
||||
| 与取元冲突 | 无 | 无 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「不分实参形参」:编译器视角的真实收益
|
||||
|
||||
你问的是:不再区分实参/形参,是否意味着变量总在某个固定位置、能否减少 IO。
|
||||
这一节用实测回答,结论会有点意外。
|
||||
|
||||
### 4.1 现状:两条执行路径,差异 3.8 倍
|
||||
|
||||
| 路径 | 参数如何绑定 | 200k 次调用(1 个 int 实参) | 2000 次调用(500 元素列表) |
|
||||
|------|-------------|------------------------------|------------------------------|
|
||||
| **树遍历**(默认 `Backend::Tree`) | `Env { HashMap<String, Value> }`,每个实参 `k.clone()` + `v.clone()`(**深拷贝**) | 167 ms | 66 ms |
|
||||
| **字节码**(`--backend bytecode`) | `slots: Vec<Value>`,`pop` 后**按位置移动**入槽(**无克隆、无哈希**) | **44 ms** | **23 ms** |
|
||||
|
||||
源码依据:
|
||||
|
||||
```rust
|
||||
// src/bytecode/vm.rs Op::Call(fid, argc)
|
||||
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
|
||||
for i in (0..argc).rev() {
|
||||
slots[i] = pop(&mut stack)?; // 移动,不克隆
|
||||
}
|
||||
frames.push(Frame { fn_idx: fid, ip: 0, slots, .. });
|
||||
```
|
||||
|
||||
### 4.2 三个结论
|
||||
|
||||
**结论一:「变量始终在某个位置」已经是字节码的现实。**
|
||||
形参按下标落槽,实参按位置移动入槽。这正是你说的模型——它已经存在。
|
||||
|
||||
**结论二:收益是真的,3.8×。**
|
||||
每次调用 0.83µs → 0.22µs;大实参 33µs → 11.5µs(省掉了深拷贝)。
|
||||
|
||||
**结论三(关键):这与「不分实参形参」的语法无关。**
|
||||
槽位化只需要「编译期知道形参顺序」,而形参顺序今天就有(v0.3 体推断给出确定顺序)。
|
||||
真正的瓶颈是**树遍历解释器用名字哈希 + 深拷贝**,以及**默认后端是 Tree**。
|
||||
|
||||
> **所以:不要用性能去论证语义变更。**
|
||||
> 想省 IO,把默认后端切到字节码、或把树遍历解释器槽位化即可——
|
||||
> 这是一条与语法正交的工程路径,收益确定、风险可控。
|
||||
> 而改语义(动态作用域)换来的性能,等于用正确性买速度。
|
||||
|
||||
### 4.3 但有一个真实的语法—性能耦合点:具名 vs 位置
|
||||
|
||||
这是本节最有价值的发现。**在「形参由体推断」的世界里,形参顺序 = 叙述里首次声明的顺序**
|
||||
(v0.3 §8.2:顺序按升参名字的首次声明事件出现序)。而叙述是可以自由改写的。
|
||||
|
||||
我用两个只差一句话序的文件做了实验:
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`a`和`b`。 ← 叙述顺序 a, b
|
||||
*`a` - `b`*
|
||||
```
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`b`和`a`。 ← 只把叙述顺序改成 b, a
|
||||
*`b` - `a`*
|
||||
```
|
||||
|
||||
| 调用写法 | 叙述 a 在前 | 叙述 b 在前 |
|
||||
|---------|------------|------------|
|
||||
| 具名 `a=10 b=3` | 7 | -7(语义随函数体改变,符合预期) |
|
||||
| **位置 `10 3`** | 7(a=10,b=3) | **7(b=10,a=3)** ← **绑定翻转了** |
|
||||
|
||||
**同一行调用代码 `> 减 10 3`,只因为作者改了前面的叙述语序,实际绑定就变了,而且不报错。**
|
||||
|
||||
这在「实参形参不分」的模型下是致命的:既然只有槽、槽序来自叙述,
|
||||
那么**位置传参等于把程序语义挂在叙述的可改写顺序上**。
|
||||
|
||||
**推论**:调用应当**以具名为准**,位置实参在体推断世界里是脆弱语法。
|
||||
这一点与编译器优化正好同向——具名调用让编译期把 `n` 静态映射到 `slots[0]`,
|
||||
既稳又快(不需要运行期哈希,也不需要猜顺序)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 我的设计建议
|
||||
|
||||
### 5.1 主形态:括注具名调用
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
理由:
|
||||
|
||||
1. **全部语义在标记内**(满足你的核心原则);
|
||||
2. 与通用函数调用同构,零学习成本;
|
||||
3. 具名 → 编译期静态映射槽位(对接字节码已有的 `slots[]`);
|
||||
4. 不碰取元 `[k](coll)`,不碰遍历 `- [x](c)`;
|
||||
5. 参数边界显式,顺带解决函数名含空格的调用难题(D8)。
|
||||
|
||||
### 5.2 位置实参:降级而非禁止
|
||||
|
||||
| 情形 | 建议 |
|
||||
|------|------|
|
||||
| 单参数 | 允许 `f(31)`(无歧义、写法自然) |
|
||||
| 多参数 | **要求具名**;位置仅保留给 `> f 1 2` 这种旧写法,并在 `check` 里 **warn** |
|
||||
| 理由 | §4.3:顺序来自叙述,可被改写而不报错 |
|
||||
|
||||
### 5.3 箭头(设计 B)作为可选补充
|
||||
|
||||
如果后续确实需要「流水线可读性」,再引入 `→`,定位为**语句式组合子**:
|
||||
|
||||
```markdown
|
||||
**订单 → 计税 → 汇总**
|
||||
```
|
||||
|
||||
但它是增量特性,不是本设计的前提。优势是链式,代价是优先级与返回值语义。
|
||||
|
||||
### 5.4 明确不做
|
||||
|
||||
| 方案 | 理由 |
|
||||
|------|------|
|
||||
| 未标记动词触发调用(上轮 L0) | 违背「叙述默认安全」 |
|
||||
| `[f](args)` | 与取元同形,已实测 2 个真实冲突文件 |
|
||||
| 动态作用域(参数从上下文推断) | 七条硬伤 + 130 个撞车形参名 |
|
||||
| 位置实参作为主流 | §4.3 叙述顺序会静默改变绑定 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 优劣总表
|
||||
|
||||
| 设计 | 标记完备 | 可读性 | 无歧义 | 编译器友好 | 改动 | 结论 |
|
||||
|------|---------|--------|--------|-----------|------|------|
|
||||
| **A 括注具名 `f(n=31)`** | ✅ | 高 | ✅ | ✅ 静态槽映射 | 中 | **推荐主形态** |
|
||||
| C 空格式 `f n=31` | ✅ | 中 | ✅ | ✅ | 零 | 今天可用,作兼容 |
|
||||
| B 箭头 `n=31 → f` | ✅ | 最高(流水线) | ⚠️ 优先级 | ✅ | 中高 | 可选增量 |
|
||||
| `[f](args)` | ✅ | 高 | ❌ 撞取元 | — | — | 不做 |
|
||||
| 未标记动词 | ❌ | 高 | ❌ | — | — | 不做 |
|
||||
| 动态作用域 | ✅ | 最高 | ❌ | ❌ 契约/指纹失效 | 高 | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **主形态选 A(括注具名)吗?** 若选,我按 B 档实现:`f(k=v)` 必通、`f(x)` 单参、多参数求具名。
|
||||
2. **位置实参**:多参时"要求具名 + 旧写法 warn"(§5.2),还是保持现状不动?
|
||||
3. **箭头**现在做还是留作后续?
|
||||
4. **顺带**:默认后端要不要切字节码(实测 3.8×,但需先验证 554 用例在 `--backend bytecode` 下全绿)?这条与语法无关,但可能是最划算的性能改进。
|
||||
|
||||
> 若你同意 A,我下一步会:改分词器(`)` 终止、逗号、嵌套)→ 补金样例 →
|
||||
> 跑双后端 554 回归 → 写变更文档。
|
||||
@@ -0,0 +1,231 @@
|
||||
# 变更记录:D9 未闭合引号不再静默吞行
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(待合入) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 |
|
||||
| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` |
|
||||
| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
$ echo $?
|
||||
0 # 没有输出、没有报错,s 这一行凭空消失
|
||||
```
|
||||
|
||||
**修复后**:解析期报错,退出码非 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
error: u.mq.md: 7:1: unterminated string: this line starts bold code but
|
||||
contains an odd number of `"` -- close the string and the trailing `**`
|
||||
(line: **s = "abc)
|
||||
$ echo $?
|
||||
1
|
||||
```
|
||||
|
||||
(实测记录:报错回显中 `unterminated` 前的空格与行号格式由
|
||||
`Diagnostic` 的 span 渲染决定,与其它语法错一致。)
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
问题**不在**解析器——`parse_quoted_string` 里的
|
||||
`bail!("unterminated {quote} string")` 一直都在,措辞也对。
|
||||
问题是这一行**根本到不了解析器**:
|
||||
|
||||
```
|
||||
"**s = \"abc"
|
||||
↓ classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
matching_bold_close() 扫描时遇到 '"' → in_str = true
|
||||
之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过
|
||||
→ 找不到收尾 '**' → 返回 None
|
||||
↓ is_marqdo_star_line = false
|
||||
↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 成为「叙述」,解析器看不到
|
||||
```
|
||||
|
||||
**这是分类层的静默降级,不是解析层的缺陷。**
|
||||
|
||||
它比一般的解析错误更危险,因为:
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** |
|
||||
| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 怎么改的
|
||||
|
||||
两层,缺一不可。
|
||||
|
||||
### 3.1 分类层:把畸形行留在 Code 类
|
||||
|
||||
`src/lex/mod.rs`
|
||||
|
||||
```rust
|
||||
if trimmed.starts_with("**") {
|
||||
if trimmed.trim() == "** **" {
|
||||
return true;
|
||||
}
|
||||
if matching_bold_close(trimmed).is_some() {
|
||||
return true;
|
||||
}
|
||||
// D9: 粗体起始但引号永不闭合 → 找不到收尾 `**`
|
||||
// 判为 Comment 会静默丢行;判为 Code 让解析器报错
|
||||
return has_unterminated_string(trimmed);
|
||||
}
|
||||
```
|
||||
|
||||
新增辅助函数:
|
||||
|
||||
```rust
|
||||
pub fn has_unterminated_string(line: &str) -> bool {
|
||||
// 统计未被 \ 转义的双引号个数,奇数即「开了没收」
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析层:给出精确报错
|
||||
|
||||
`src/parse/mod.rs`,紧跟既有粗体分支之后:
|
||||
|
||||
```rust
|
||||
// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`,
|
||||
// 通用 "unrecognized statement" 会掩盖真正原因。
|
||||
if trimmed.starts_with("**") && has_unterminated_string(trimmed) {
|
||||
bail!("{span}: unterminated string: ... (line: {trimmed})");
|
||||
}
|
||||
```
|
||||
|
||||
没有这一层,用户会看到 `unrecognized statement: **s = "abc`——
|
||||
能定位到行,但不知道是引号没闭合。
|
||||
|
||||
---
|
||||
|
||||
## 4. 影响面(改前量化过)
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
### 5.1 新增单元测试(`src/lex/mod.rs`,4 个)
|
||||
|
||||
| 测试 | 断言 |
|
||||
|------|------|
|
||||
| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) |
|
||||
| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` |
|
||||
| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` |
|
||||
| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` |
|
||||
|
||||
**先写测试确认失败**(TDD):
|
||||
|
||||
```
|
||||
---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment
|
||||
panicked: expected Code (so parser reports the error),
|
||||
got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }]
|
||||
```
|
||||
|
||||
修复后 14/14 通过。
|
||||
|
||||
### 5.2 回归
|
||||
|
||||
| 范围 | 结果 |
|
||||
|------|------|
|
||||
| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) |
|
||||
| `cargo test --release --test gold` | 276 passed, 8 failed |
|
||||
| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed |
|
||||
| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知边界
|
||||
|
||||
| 情形 | 行为 | 说明 |
|
||||
|------|------|------|
|
||||
| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 |
|
||||
| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 |
|
||||
| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 |
|
||||
|
||||
> 单引号的情况建议后续按同样思路处理,但需要单独评估
|
||||
> (单引号也用于英文撇号,误判风险高于双引号)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 |
|
||||
| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 |
|
||||
| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) |
|
||||
| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) |
|
||||
| `doc/design/change-d9-unterminated-string.md` | 本文件 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附:本机测试环境(2026-10-22 装好)
|
||||
|
||||
修复过程中发现本机缺两样东西,导致基线本来就有失败。补环境后全量测试 **554 passed / 0 failed**。
|
||||
|
||||
### 8.1 两个非直觉约束
|
||||
|
||||
| 约束 | 表现 | 解法 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `error: AccessDenied`(全局缓存无处可写) | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 显式指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接报 `running gcc failed: signal: aborted`;zig 链接报 `AccessDenied` | `TMPDIR` 指向可写**且可执行**目录 |
|
||||
|
||||
第二条最隐蔽:`/tmp` 挂载为 `rw,nosuid,nodev,noexec`,构建工具会把产物写到那里再执行,
|
||||
于是「文件能写、却执行不了」。错误信息完全指向不了这一点。
|
||||
|
||||
### 8.2 Go 插件(`libweb.so`)
|
||||
|
||||
`gold` 测试里 8 个 `ext_web_*` 失败全因缺 `libweb.so`:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # 提供 go 1.25 + gcc shim(zig) + TMPDIR
|
||||
./scripts/build-web-plugin.sh # 产出 plugins/web/build/libweb.so
|
||||
cp plugins/web/build/libweb.so target/release/ target/debug/
|
||||
```
|
||||
|
||||
Go 的 cgo 要 `gcc`,本机没有,用 zig cc 充当:
|
||||
`/workspace/qdagent/.tools/zigcc/bin/gcc`(会过滤 Go 传入的 `-Qunused-arguments`,
|
||||
该参数会让 zig 驱动 abort)。
|
||||
|
||||
### 8.3 一键复用
|
||||
|
||||
新增 `scripts/dev-env.sh`,`source` 后即具备完整工具链:
|
||||
|
||||
```
|
||||
marqdo dev-env: rust=1.81.0 go=go1.25.0 python=3.12.15 cc=zig-glibc2.36
|
||||
```
|
||||
|
||||
### 8.4 环境修复前后的测试对比
|
||||
|
||||
| 阶段 | lib 测试 | gold 测试 |
|
||||
|------|----------|-----------|
|
||||
| 无 python3 | 231 / 2 failed | — |
|
||||
| 加 python3 | 233 / 0 failed | 276 / 8 failed |
|
||||
| 加 go + libweb | — | **284 / 0 failed** |
|
||||
| **全量** | | **554 passed / 0 failed** |
|
||||
@@ -0,0 +1,99 @@
|
||||
# 变更记录:HostFn 五张表合一(`HOST_FN_TABLE` 单一来源)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 4 项 |
|
||||
| 改动 | `src/host/dispatch.rs`:**−404 行**(639 删 / 235 增) |
|
||||
| 行为 | **零变化**(203 项逐字节一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原来有五张并行表
|
||||
|
||||
202 个宿主函数的元数据分散在五个手写 match 里:
|
||||
|
||||
| 表 | 行数 | 作用 |
|
||||
|----|------|------|
|
||||
| `from_u16` | ~215 | id → 变体 |
|
||||
| `from_name` | ~215 | 名字/别名 → 变体(**保留**,见 §4) |
|
||||
| `name` | ~210 | 变体 → 规范名 |
|
||||
| `required_params` | ~145 | 变体 → 必填参数 |
|
||||
| `optional_params` | ~90 | 变体 → 可选参数 |
|
||||
|
||||
五张表必须同步维护,而 [code-volume-audit.md](code-volume-audit.md) 记录过
|
||||
`from_name` 接受 `http_get` 而 `name()` 只输出 `host_http_get` 的一类漂移。
|
||||
|
||||
## 2. 现在只有一张
|
||||
|
||||
```rust
|
||||
pub struct HostFnDef {
|
||||
pub id: u16,
|
||||
pub f: HostFn,
|
||||
pub name: &'static str,
|
||||
pub required: &'static [&'static str],
|
||||
pub optional: &'static [&'static str],
|
||||
}
|
||||
|
||||
pub const HOST_FN_TABLE: &[HostFnDef] = &[
|
||||
HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
|
||||
required: &["path"], optional: &[] },
|
||||
…
|
||||
];
|
||||
```
|
||||
|
||||
四个函数改为查表(`from_u16` 按 id 查,其余按判别值查);
|
||||
`call_host` 保留它那 202 个一行臂——**分派逻辑不动**,只把元数据集中。
|
||||
|
||||
## 3. 怎么保证没改坏
|
||||
|
||||
迁移采用**快照比对**:
|
||||
|
||||
1. 先在旧实现上导出全部 203 项的 `(id, name, required, optional)` 到 TSV
|
||||
2. 合并成表后,用同一段代码再导出一份
|
||||
3. `diff` 两份文件 → **完全一致**
|
||||
|
||||
```
|
||||
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
|
||||
IDENTICAL
|
||||
```
|
||||
|
||||
快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `every_assigned_id_round_trips` | 每个已分配 id → `as_u16()` 往返(id 空间稀疏是**退役 id**,不复用) |
|
||||
| `every_id_has_a_name_that_round_trips` | `name()` → `from_name()` 回到同一变体 |
|
||||
| `names_are_unique` | 规范名唯一 |
|
||||
| `required_and_optional_params_are_disjoint` | 必填/可选不重叠、`all_params` 无重复 |
|
||||
|
||||
## 4. 为什么 `from_name` 没有并进表
|
||||
|
||||
它是**别名注册表**(`http_get`、`get`、中文别名…),语义与"规范名"不同;
|
||||
并进表会让 `name()` 与 `from_name` 又变成一对映射。
|
||||
现在它保留原样,由上面的往返测试保证不与表漂移。
|
||||
|
||||
## 5. 收益
|
||||
|
||||
| 指标 | 前 | 后 |
|
||||
|------|----|----|
|
||||
| `dispatch.rs` | 2,052 行 | **1,648 行** |
|
||||
| `src/` 合计 | 53,040 | **52,668** |
|
||||
| 需同步维护的表 | 5 | **1** |
|
||||
|
||||
## 6. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release` | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 快照 diff | 203 项逐字节一致 |
|
||||
| 四个不变量测试 | 全绿 |
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/host/dispatch.rs` | 新增 `HostFnDef` / `HOST_FN_TABLE`(203 项);`from_u16` / `name` / `required_params` / `optional_params` 改为查表;删除对应四个 match |
|
||||
| `doc/design/change-hostfn-table.md` | 本文件 |
|
||||
@@ -0,0 +1,134 @@
|
||||
# 变更记录:M1 `()` 内调用语法(`)` 终止 / 逗号 / 嵌套 / 空格 callee)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M1([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/parse/expr.rs` |
|
||||
| 影响面 | **共享参数分词器**(所有调用都会经过) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
四件事,一句概括:**`(…)` 现在是一等调用外形**。
|
||||
|
||||
| # | 前 | 后 |
|
||||
|---|----|----|
|
||||
| 1 | `加(31)` 报 `unknown function 加(31` | ✅ 调用,返回 32 |
|
||||
| 2 | 末个位置实参会吞掉 `)` | `)` 是**参数终止符** |
|
||||
| 3 | 只支持空白分隔 | 支持 `,` / `,` 可选分隔 |
|
||||
| 4 | 嵌套 `加(加(1 2), 3)` 不可用 | ✅ 递归解析 |
|
||||
| 5 | `加一 号(31)` 不可用(D8) | ✅ **callee 可含空格** |
|
||||
|
||||
实测(1.5.2 本地构建,tree 与 bytecode 双后端结果一致):
|
||||
|
||||
```
|
||||
空格参=3 加(1 2)
|
||||
逗号=3 加(1, 2)
|
||||
嵌套=13 加(加(1 2), 10)
|
||||
带空格callee=32 加一 号(31) ← 缺陷 D8 的结构性解法
|
||||
库函数=x txt.str_trim(" x ")
|
||||
具名=3 加(a=1, b=2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现要点
|
||||
|
||||
### 2.1 参数扫描:深度感知 + `)` 终止
|
||||
|
||||
`split_first_token` 与 `find_next_arg_boundary` 改为**通用扫描器**:
|
||||
|
||||
- 跟踪 `()` `[]` `{}` 嵌套、`"…"` 字符串、`` `…` `` 反引号
|
||||
- **顶层** `)` / 空白(以及括号形里的 `,`)终止当前 token,且**不吞掉终止符**
|
||||
- 字符串内的逗号不受影响(`拼接("a,b", "c")` 仍是 2 个参数)
|
||||
|
||||
### 2.2 `try_paren_call`:callee = 第一个 `(` 之前的全部文本
|
||||
|
||||
```rust
|
||||
let Some(open) = s.find('(') else { return Ok(None) };
|
||||
let callee_tok = s[..open].trim(); // 允许空格
|
||||
```
|
||||
|
||||
**安全护栏**(否则会误判):
|
||||
|
||||
| callee 里出现 | 判定 |
|
||||
|--------------|------|
|
||||
| `=` | 不是括号调用(那是 `text=a(b)` 具名实参) |
|
||||
| `[` `]` `(` `)` `"` `'` | 不是括号调用(那是 `trim [stdout](…)` 方括号实参) |
|
||||
| 以 `[` `]` `"` `'` 开头 | 不是括号调用 |
|
||||
| 反引号 | **允许**(保留 `` `obj`.方法(…) `` 接收者写法) |
|
||||
|
||||
### 2.3 表达式级 postfix 调用
|
||||
|
||||
`parse_primary` 的裸词分支:**紧跟** `(` 时按调用解析。
|
||||
|
||||
```rust
|
||||
if self.allow_paren_call && self.rest().starts_with('(') { … }
|
||||
```
|
||||
|
||||
要求"紧跟"(不隔空格),使 `加 (1)` 仍是原来的"文本 + 括号"行为。
|
||||
|
||||
### 2.4 方括号形也允许空格 callee
|
||||
|
||||
`is_bracket_callee_inner` 不再拒绝空白:`[加一 号] 31` 可用。
|
||||
(仓库内可执行的方括号调用用量为 0,风险极低。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键设计决策:括号形 vs 空格形的参数**值**语义不同
|
||||
|
||||
这是本里程碑唯一有争议的点,必须写清。
|
||||
|
||||
| 形态 | 参数值 | 例子 |
|
||||
|------|--------|------|
|
||||
| **括号形** `f(…)` | 表达式(**允许** `name(args)` 调用) | `加(加(1 2), 3)` |
|
||||
| **空格形** `> f k=v` | 文本(**不允许**裸 `name(args)` 变成调用) | `source=print(2+2)` 仍是文本 |
|
||||
|
||||
**为什么必须区分**:`source=print(2+2)` 在 Marqdo 里历来是**文本**(未加引号的实参按文本处理)。
|
||||
若不区分,它会变成对 `print` 的调用,`foreign.run_lang` 直接报 `source must be text`
|
||||
—— 这正是本次回归测试抓到的 3 个失败。
|
||||
|
||||
实现:`Parser` 增加 `allow_paren_call` 字段;`parse_call_arg_value_mode(input, prefer_var, allow_call)`
|
||||
统一两种值解析(`allow_call=false` 即旧行为)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元 | 新增 11 个(单参/多参/逗号/具名/空格 callee/零参/库路径/嵌套/引号内逗号/旧写法不回归/方括号形) | ✅ |
|
||||
| 全量 | `cargo test --release` | **565 passed / 0 failed**(基线 554 + 11) |
|
||||
| 双后端 | tree 与 `--backend bytecode` 跑同一文档 | 输出一致 |
|
||||
| 端到端 | `marqdo run` 六个用例 | 输出符合预期 |
|
||||
|
||||
**TDD 过程**:先写 11 个测试 → 10 个失败(红灯确认)→ 实现 → 全绿。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带移除的死代码
|
||||
|
||||
`end_of_quoted_string`:新扫描器取代其唯一用途后变成 `never used`,删除(编译器警告清零)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界(本里程碑不做)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 逗号仅在括号形生效 | 空格形 `text=a,b` 的逗号仍是文本(兼容) |
|
||||
| `加 (1)`(空格后跟括号) | 不视为调用,保持旧行为 |
|
||||
| 遮蔽语法 `[描述](…)` | M2 才引入,本里程碑不解析 |
|
||||
| 位置实参顺序脆弱性 | 与叙述顺序绑定,M7/M8 再处理(诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/parse/expr.rs` | 参数扫描器重写(`)`/逗号/嵌套);新增 `try_paren_call` + `split_callee` 抽取;表达式级 postfix 调用;`Parser.allow_paren_call`;`parse_call_arg_value_mode` 统一两种值语义;方括号 callee 允许空格;删除 `end_of_quoted_string` |
|
||||
| `doc/design/change-m1-paren-call.md` | 本文件 |
|
||||
@@ -0,0 +1,73 @@
|
||||
# 变更记录:M10 工程化落点(README + agent 提示词)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M10([occlusion-description-and-search.md](occlusion-description-and-search.md) §5) |
|
||||
| 改动文件 | `ext/ai/agent.mq.md`(README 一节已在文档阶段落地) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 改了什么
|
||||
|
||||
把「接不了就申报,别假装完成」写进 **agent 的默认提示词**,两处:
|
||||
|
||||
### 1.1 `how-to-act` 协议段(每轮都会带)
|
||||
|
||||
```
|
||||
Call ONLY names listed under --- tools --- (whitelist). …
|
||||
If a capability cannot truly be wired, do NOT fake it silently and never claim it works:
|
||||
write an occlusion with an explicit status, e.g. [按关键词检索,接口未接,待开发](None).
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.search.
|
||||
Tools run via Marqdo subtask (spawn fn / wait).
|
||||
```
|
||||
|
||||
### 1.2 默认 standing(`p`)
|
||||
|
||||
```
|
||||
You are a Marqdo agent. Code is documentation: … not a hidden system prompt.
|
||||
When you cannot wire a capability, declare it in the description (待开发 / 模拟)
|
||||
instead of faking success.
|
||||
```
|
||||
|
||||
**为什么这两处**:standing 定基调(每次对话开头),how-to-act 定动作(每轮)。
|
||||
只写 standing 容易被长上下文冲淡;只写 how-to-act 又缺"为什么要申报"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计要点
|
||||
|
||||
| 要点 | 说明 |
|
||||
|------|------|
|
||||
| 给**范式**而不是规则 | 直接给出可抄的 `[按关键词检索,接口未接,待开发](None)`,模型不必发明措辞 |
|
||||
| 给**返回值**要求 | "必须写清返回什么(None 也行)"——对应 `label.empty_payload` 的 warning |
|
||||
| 给**自查**动作 | `labels.search` 让模型收尾时能自己盘点,而不是靠人提醒 |
|
||||
| 用**英文**写 | 与既有 standing / 协议段语言一致(模型对英文指令更稳) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `marqdo check ext/ai/agent.mq.md`(occlusion 模式) | `contract check OK` |
|
||||
| 提示词文本落入模块 | `grep` 命中 2 处(standing 与 how-to-act 各 1) |
|
||||
| 全量回归 | 587 passed / 0 failed(与 M9 相同,本改动不动逻辑) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
- 提示词是**建议**,不是门禁;违反不会被拒绝,但会在描述/诊断里暴露。
|
||||
- `labels.search` 需要 M7 翻转默认后对 classic 文档才有意义;提示词先就位。
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `ext/ai/agent.mq.md` | how-to-act 协议段与默认 standing 各追加申报约定 |
|
||||
| `doc/design/change-m10-engineering-habits.md` | 本文件 |
|
||||
@@ -0,0 +1,126 @@
|
||||
# 变更记录:M2 遮蔽语法 `[描述](实现)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(模式开关默认仍是 classic) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增语法
|
||||
|
||||
```markdown
|
||||
[描述](实现)
|
||||
```
|
||||
|
||||
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
|
||||
- `()` = **实现**(唯一执行体)
|
||||
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
|
||||
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
|
||||
|
||||
实测(`MARQDO_MARKUP=occlusion`):
|
||||
|
||||
```
|
||||
a=2 [加一之后的值](1 + 1)
|
||||
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
|
||||
c=True [某某功能开发中]() ← 空载荷 → None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**模式开关,暂不切换语义**
|
||||
|
||||
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
|
||||
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
|
||||
|
||||
因此 M2 只**实现能力**,不动默认:
|
||||
|
||||
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|
||||
|------|-----------------|-----------------|
|
||||
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
|
||||
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
|
||||
|
||||
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
|
||||
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现要点
|
||||
|
||||
### 3.1 AST
|
||||
|
||||
```rust
|
||||
Occluded {
|
||||
label: String,
|
||||
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析
|
||||
|
||||
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
|
||||
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
|
||||
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
|
||||
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
|
||||
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
|
||||
|
||||
### 3.3 求值(两个后端一致)
|
||||
|
||||
| 位置 | 处理 |
|
||||
|------|------|
|
||||
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
|
||||
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
|
||||
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
|
||||
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
|
||||
|
||||
**描述永不参与求值**——守住铁律 1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
|
||||
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
|
||||
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
|
||||
| 双后端 | tree 与 `--backend bytecode` | 一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带重构
|
||||
|
||||
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
|
||||
(全局只由 CLI 入口设置一次)。
|
||||
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述不参与作用域/类型 | 写什么都不影响执行 |
|
||||
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
|
||||
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
|
||||
| 跨行描述 | 不支持(v1) |
|
||||
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
|
||||
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
|
||||
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
|
||||
| `src/interp.rs` | 求值 + 读引用收集 |
|
||||
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
|
||||
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
|
||||
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
|
||||
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
|
||||
| `doc/design/change-m2-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,91 @@
|
||||
# 变更记录:M2.5 遮蔽标签诊断(`label.missing` / `label.empty_payload`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2.5([occlusion-syntax.md](occlusion-syntax.md) §13,诊断规范 §10) |
|
||||
| 改动文件 | **新增 `src/label.rs`** · `src/check.rs` · `src/lib.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check`(新增两类诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两条诊断
|
||||
|
||||
| code | 级别 | 触发 | 文案要点 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | **error** | `[](实现)` 描述为空 | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.empty_payload` | **warning** | `[描述]()` 载荷为空 | 「这里没有可执行内容」,建议写 `(None)` 或补实现 |
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
|
||||
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
|
||||
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
|
||||
contract check: 1 条诊断(0 error) # exit 0(warning 不影响退出码)
|
||||
```
|
||||
|
||||
JSON 出口(自动继承既有 schema,含 `doc_quote`):
|
||||
|
||||
```json
|
||||
{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
|
||||
"doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现
|
||||
|
||||
### 2.1 新增 `src/label.rs`
|
||||
|
||||
- `OcclusionSite { label, has_payload, line, unit }`
|
||||
- `collect(module)`:遍历函数体与嵌套语句/表达式,收集所有遮蔽点
|
||||
(描述只读,**不产生任何读引用**)
|
||||
- `check(module, path)`:产出上面两条诊断
|
||||
|
||||
### 2.2 接入 `check_module`
|
||||
|
||||
```rust
|
||||
walk(module, &module.functions, path, &known, &mut out);
|
||||
out.extend(crate::label::check(module, path)); // M2.5
|
||||
```
|
||||
|
||||
设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加,
|
||||
`check` 只做一行汇总。
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3 新) | 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **578 passed / 0 failed**(M2 后 575 + 3) |
|
||||
|
||||
反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述内容不校验 | 写什么都可以;M4 才校验反引号引用 |
|
||||
| 空载荷仅在 occlusion 模式可能出现 | classic 模式下 `()` 空是语法错 |
|
||||
| warning 不影响退出码 | 与既有 `Severity` 语义一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | **新增**:遮蔽点收集 + 两类诊断 |
|
||||
| `src/lib.rs` | `pub mod label;` |
|
||||
| `src/check.rs` | `check_module` 追加 label 诊断 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{empty-label,empty-payload,clean}.mq.md` | 新增 3 个集成测试与样例 |
|
||||
| `doc/design/change-m25-label-diagnostics.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M3 `access` 与遮蔽循环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) |
|
||||
| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 |
|
||||
|
||||
---
|
||||
|
||||
## 1. `access(集合, 键)`
|
||||
|
||||
旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。
|
||||
纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式:
|
||||
|
||||
```markdown
|
||||
**a = [取表项](access(`表`, "键"))**
|
||||
**b = [取列表第二项](access(`列`, 2))**
|
||||
```
|
||||
|
||||
- 别名:`取` / `取值` / `access`
|
||||
- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None)
|
||||
- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移
|
||||
|
||||
实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`,
|
||||
**不新增平行实现**(避免两套索引语义)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 遮蔽循环
|
||||
|
||||
```markdown
|
||||
- [篮子里的每个果子](遍历 `列` 为 `果`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach)
|
||||
- 接受 `遍历`/`for` 与 `为`/`as`/`in`
|
||||
- 描述存入 `Stmt::ForEach.label`(`Option<String>`),供 M8 渲染/诊断使用
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
a=值
|
||||
b=二
|
||||
果子=一
|
||||
果子=二
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么先做 M3 再做 M7
|
||||
|
||||
迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。
|
||||
先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ |
|
||||
| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 |
|
||||
| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 |
|
||||
| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) |
|
||||
| `src/ast.rs` | `Stmt::ForEach.label: Option<String>` |
|
||||
| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 |
|
||||
| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m3-access-and-loop.md` | 本文件 |
|
||||
@@ -0,0 +1,84 @@
|
||||
# 变更记录:M4 L1 引用一致性(`label.ref_dangling`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) |
|
||||
| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` |
|
||||
| 影响面 | `marqdo check`(新增一条 error) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> 描述里用反引号写出的名字 = **断言**:它必须能解析
|
||||
> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。
|
||||
|
||||
```markdown
|
||||
**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬)
|
||||
**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到
|
||||
**c = [取长度](len("abc"))** # ✅ 内置函数
|
||||
**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么只认反引号(可证伪原则)
|
||||
|
||||
| 写法 | 是否检查 | 原因 |
|
||||
|------|---------|------|
|
||||
| `` `税率` `` | ✅ | 显式引用,可证伪 |
|
||||
| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 |
|
||||
|
||||
代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**,
|
||||
同时反向抑制"为凑数写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现
|
||||
|
||||
| 环节 | 做法 |
|
||||
|------|------|
|
||||
| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 |
|
||||
| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` |
|
||||
| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 |
|
||||
|
||||
`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ |
|
||||
| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界与后续
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 |
|
||||
| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 |
|
||||
| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m4-label-refs.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) |
|
||||
| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到
|
||||
> (或能解析到模块/内置)。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额: ← 描述
|
||||
|
||||
> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率`
|
||||
```
|
||||
|
||||
```
|
||||
impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它
|
||||
```
|
||||
|
||||
段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、
|
||||
标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**默认关闭**
|
||||
|
||||
这不是洁癖,是实测结论:
|
||||
|
||||
| 阶段 | lib + ext/ai 上的警告数 |
|
||||
|------|------------------------|
|
||||
| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) |
|
||||
| 加"实体名形状"过滤 | 2 条 |
|
||||
| **再加默认关闭** | **0 条** |
|
||||
|
||||
理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多;
|
||||
机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。
|
||||
所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实体名过滤(降低误报)
|
||||
|
||||
反引号内容必须**像实体名**才算断言:
|
||||
|
||||
```rust
|
||||
首字符:字母 / `_` / 非 ASCII(不能是数字)
|
||||
其余:字母数字 / `_` / `.` / 非 ASCII 且非空白
|
||||
```
|
||||
|
||||
于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用法
|
||||
|
||||
```bash
|
||||
marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音)
|
||||
marqdo check 文件.mq.md --implicit-labels # 开启
|
||||
```
|
||||
|
||||
MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ |
|
||||
| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) |
|
||||
|
||||
**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent`
|
||||
两条都在证明"不乱响"。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 |
|
||||
| 只认反引号 + 实体形状 | 普通散文永远不参与 |
|
||||
| 不查 payload 语义 | 只查"提到的实体是否被用到" |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` |
|
||||
| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) |
|
||||
| `src/main.rs` | `check --implicit-labels` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 |
|
||||
| `doc/design/change-m5-implicit-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,109 @@
|
||||
# 变更记录:M6 T1 会话内陈旧检测 + 会话末汇总
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M6([t1-session-staleness.md](t1-session-staleness.md) · [staleness-providers.md](staleness-providers.md) T1) |
|
||||
| 改动文件 | `src/label.rs` · `src/mlsp.rs` · `src/view/mod.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | MLSP `repair_apply` 新增可选字段;新增 `session.summary` 方法 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制
|
||||
|
||||
`repair_apply` 内部同一作用域里同时有 `source`(改前)与 `new_source`(改后),
|
||||
所以「描述是否还成立」可以**纯内存**判定:
|
||||
|
||||
```
|
||||
stale ⟺ 标签文本未变 ∧ payload 指纹变了
|
||||
```
|
||||
|
||||
配对按 `(标签文本, 出现序号)`,因此**移动代码不会误报**。
|
||||
|
||||
请求:
|
||||
|
||||
```json
|
||||
{"method":"repair_apply","params":{
|
||||
"source":"…","ranges":[[3,3]],
|
||||
"edits":[{"op":"replace","line":3,"text":"**a = [按税率算总价](100 * 0.2)**"}],
|
||||
"check_labels":true}}
|
||||
```
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"result":{
|
||||
"source":"…","edits_applied":1,
|
||||
"labels":{"newly_seen":1,"stale":[
|
||||
{"label":"按税率算总价","line":3,
|
||||
"code_past":"100 * 0.1","code_now":"100 * 0.2"}]}}}
|
||||
```
|
||||
|
||||
**同一份 `source` / `new_source` 就是"前一状态"**——不需要 git、不需要台账、
|
||||
不需要沙箱里的 exec 权限。这是"agent 回路不需要 VCS"的落地。
|
||||
|
||||
---
|
||||
|
||||
## 2. 会话末汇总(你要求做)
|
||||
|
||||
`session.summary` 返回并**重置**计数:
|
||||
|
||||
```json
|
||||
{"ok":true,"labels_stale_seen":1,"labels_fixed":0,
|
||||
"labels_outstanding":1,"items":["按税率算总价"]}
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `labels_stale_seen` | 本次会话累计发现过多少条(去重按标签) |
|
||||
| `labels_fixed` | 曾经 outstanding、现在不再 stale 的条数 |
|
||||
| `labels_outstanding` | 仍未处理 |
|
||||
| `items` | 未处理的标签文本(只给文本,不重复诊断细节) |
|
||||
|
||||
设计:客户端在收尾时调用一次即可闭合;**不主动打屏**,不污染协议。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键取舍
|
||||
|
||||
| 取舍 | 理由 |
|
||||
|------|------|
|
||||
| `check_labels` 默认 **false** | 零开销、零噪音;agent 框架在修复回路里显式打开 |
|
||||
| 标签变了 → **不报** | 作者改描述本身就是"已复核"的信号 |
|
||||
| 新标签 → 不报 | 无历史可比 |
|
||||
| 指纹用 `Debug` | **只需进程内一致**;跨版本稳定指纹是 T2/T3 的事 |
|
||||
| payload 渲染用 `view::expr_display` | 让 `code_past/code_now` 是人能读的表面语法,而非 AST 调试串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 只改 payload → `stale` 含 `code_past`/`code_now`;同时改标签 → `stale: []`;`session.summary` 计数正确 | ✅ |
|
||||
| 全量 | `cargo test --release` | **590 passed / 0 failed**(M10 后 587 + 3) |
|
||||
|
||||
**反向验证**:`t1_silent_when_label_also_changes` 证明"改描述即复核"不会误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只看本次编辑 | 跨会话漂移是 T2/T3 的职责(可选 provider) |
|
||||
| 解析失败则跳过 | 修复后的源码可能语法错误,此时不评测标签,交给 `validate` |
|
||||
| 会话状态是进程级 | 一条 MLSP 连接(一个进程)即一个会话;`session.summary` 后清零 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `StaleItem` · `payload_fingerprint` · `compare` · `SessionSummary`(含 `record`)· `OcclusionSite.payload_fp/payload_src` |
|
||||
| `src/mlsp.rs` | `repair_apply` 的 `check_labels`;`session.summary`;进程级 `SESSION` |
|
||||
| `src/view/mod.rs` | `pub use render::expr_display`(供诊断渲染 payload) |
|
||||
| `tests/occlusion.rs` | 3 个 T1 集成测试 |
|
||||
| `doc/design/change-m6-t1-session.md` | 本文件 |
|
||||
@@ -0,0 +1,127 @@
|
||||
# 变更记录:M7 迁移与版本门(per-file 标记 + `migrate labels` + 全仓迁移)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M7([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | **新增 `src/migrate.rs`** · `src/load.rs` · `src/parse/mod.rs`(expr) · `src/host/dispatch.rs` · **80 个语料文件** · 测试 |
|
||||
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原计划的问题:同形换义
|
||||
|
||||
原设计想"翻转默认 + 对旧形硬报错"。但 `[键](集合)` 与 `[描述](实现)` **外形完全相同**:
|
||||
|
||||
- 翻转默认 → 506 处取元**静默变成**"遮蔽整个集合",正是文档点名的最坏变更
|
||||
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
|
||||
|
||||
**结论:模式不能全局翻转,必须按文件声明。**
|
||||
|
||||
## 2. 新方案:per-file `markup:`
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
```
|
||||
|
||||
| 文件 | 解析模式 | `[a](b)` 的含义 |
|
||||
|------|---------|----------------|
|
||||
| 无 `markup:` | classic(进程默认) | 取元 |
|
||||
| `markup: occlusion` | 纯度 | 遮蔽 |
|
||||
|
||||
实现:`load.rs` 先读 frontmatter 取出模式,用 `parse::expr::with_markup(m, …)`
|
||||
(线程局部覆盖,压栈/出栈)包住解析。**同一进程里可以同时加载两种模式的文件**
|
||||
(imports!),且 `MARQDO_MARKUP=occlusion` 仍可作为进程默认。
|
||||
|
||||
好处:迁移是**逐文件、可增量、可回滚**的;不存在"半迁移的静默错义"。
|
||||
|
||||
## 3. 迁移工具 `marqdo migrate labels`
|
||||
|
||||
```bash
|
||||
marqdo migrate labels . # 干跑:列出将改什么
|
||||
marqdo migrate labels . --write # 实际写入
|
||||
marqdo migrate labels . --json # 机器可读
|
||||
```
|
||||
|
||||
### 3.1 改写规则
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `[键](集合)` | `[键](access(集合, "键"))` |
|
||||
| `` [`名`](集合) `` | `` [名](access(集合, `名`)) `` |
|
||||
| `- [项](集合)` | `- [项](遍历 集合 为 项)` |
|
||||
|
||||
`access` 是新增宿主函数(`host_access`,id 212),语义与旧取元**逐字一致**
|
||||
(Map 按键 / List 1-based / 缺键 `missing map key`)。它进 `HostFn` 是有意的:
|
||||
**两个后端共用同一实现**,不再有特例分支。
|
||||
|
||||
### 3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
|
||||
|
||||
1. 原文件按 classic 解析,得到 AST-A
|
||||
2. 文本改写后,按 occlusion 解析,得到 AST-B
|
||||
3. **反归一化** B:把"标签与键同名 + payload 为 `access(x, k)`"的遮蔽还原成 `Index`
|
||||
4. 比较 `Debug(A)` 与 `Debug(反归一化(B))`(抹掉行号,因为插入了 marker 行)
|
||||
5. 只有相等才写入;否则**原文件一字不动**并报告 `equivalence check failed`
|
||||
|
||||
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
|
||||
链式索引、`[问候] (…)` 与遮蔽混淆),每一类都是**先被拦下、再修工具**,没有污染文件。
|
||||
|
||||
### 3.3 只改代码行
|
||||
|
||||
用词法层的 `LineKind::Code` 限定范围;表格行只改 `**…**` 单元格
|
||||
(散文里的 markdown 链接 `[docs](https://…)` 必须原样保留)。
|
||||
|
||||
### 3.4 由内向外
|
||||
|
||||
链式索引 `[content]([1]([messages](req)))` 必须**最内层先改**,
|
||||
否则外层改写会让内层的位置失效;已迁移的 `[k](access(…))` 有守卫,不会二次改写。
|
||||
|
||||
## 4. 全仓迁移结果
|
||||
|
||||
```
|
||||
migrate labels: 256 index, 23 loop, 80 file written
|
||||
```
|
||||
|
||||
- 覆盖 `lib/ ext/ examples/ public/ cli/ tests/`
|
||||
- **0 文件被等价性检查拒绝**
|
||||
- 迁移后 `cargo test --release` → **604 passed / 0 failed**
|
||||
- 再跑一次迁移 → **幂等**(只剩刻意保留的 classic 测试样例)
|
||||
|
||||
## 5. 顺带修的两处真实语义缺陷
|
||||
|
||||
| 缺陷 | 现象 | 修法 |
|
||||
|------|------|------|
|
||||
| payload 继承外层"文本模式" | `f text=[k](access(c,k))` 里 `access(...)` 不被当调用 → 退化成插值文本 | `()` 内**永远**允许 `callee(args)`(`parse_occluded` 临时置位) |
|
||||
| 遮蔽形状判定过宽 | `[问候] ([格式化] "Bo")` 被误判为遮蔽 | 要求 `]` 后**紧跟** `(`;否则落回方括号调用 |
|
||||
|
||||
## 6. 版本门
|
||||
|
||||
- 旧写法**不再**被硬报错——因为无法与遮蔽区分;真正的门是 **per-file 声明**:
|
||||
没写 `markup: occlusion` 的文件按 classic 解析,行为不变。
|
||||
- 需要"禁止新写旧形"的仓库可用 `migrate labels` 干跑做 CI 门禁(有改动即失败)。
|
||||
|
||||
## 7. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
|
||||
| 集成(3) | 干跑不写盘;写入后**运行输出不变**且幂等;等价失败则文件不动 | ✅ |
|
||||
| 全量 | `cargo test --release` | **604 passed / 0 failed**(M3 后 595 + 9) |
|
||||
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
|
||||
|
||||
## 8. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/migrate.rs` | **新增**:改写器、等价性证明、`migrate_file` / `migrate_path` |
|
||||
| `src/load.rs` | `frontmatter_markup` + `with_markup` 包裹两处 `parse_source` |
|
||||
| `src/parse/expr.rs` | `with_markup` 线程局部覆盖;`()` 内强制允许调用;`occlusion_shape_ahead` 严格判定 |
|
||||
| `src/host/dispatch.rs` | `HostFn::Access`(enum / from_u16 212 / from_name / name / required_params / call_host) |
|
||||
| `src/main.rs` | `migrate labels` 子命令 |
|
||||
| `src/interp.rs` | 移除 access 特例(改用 HostFn,单一实现) |
|
||||
| 80 个语料文件 | 索引与循环迁移 + `markup: occlusion` 标记 |
|
||||
| `tests/migrate.rs` + `src/migrate.rs` 单测 | 9 个测试 |
|
||||
| `doc/design/change-m7-migration.md` | 本文件 |
|
||||
@@ -0,0 +1,81 @@
|
||||
# 变更记录:M8 债务棘轮与呈现
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M8([warning-fatigue-control.md](warning-fatigue-control.md) §4 棘轮 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/main.rs` · `tests/ratchet.rs` |
|
||||
| 影响面 | `labels` 新增 `--baseline` / `--fail-on-increase` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 棘轮规则
|
||||
|
||||
```bash
|
||||
# CI:未完成项只许减少,不许增加
|
||||
marqdo labels . --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
| 情形 | 行为 | 退出码 |
|
||||
|------|------|--------|
|
||||
| 台账不存在 | **建立**(写入当前计数),提示 `已建立 N` | 0 |
|
||||
| 当前 > 台账 | 失败,提示 `未完成项增加了 K` | **1** |
|
||||
| 当前 ≤ 台账 | 通过;若减少则**收紧**台账(`N → M`) | 0 |
|
||||
|
||||
**为什么"减少即收紧"**:否则债务可以先降后升,棘轮形同虚设。
|
||||
收紧后台账记住新的低水位,回退到旧数量同样会失败(测试第 4 步验证)。
|
||||
|
||||
台账格式:
|
||||
|
||||
```json
|
||||
{"count": 1, "words": ["待开发", "未开发", "…"]}
|
||||
```
|
||||
|
||||
记录词集是为了让"口径变了"可被审计——换词集时会看到 `words` 变化。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么用棘轮而不是硬门禁
|
||||
|
||||
| 方案 | 老债 | 新债 | 结论 |
|
||||
|------|------|------|------|
|
||||
| 硬门禁(必须为 0) | 阻塞一切 | 拦住 | 存量债立刻红一片,逼人关检查 |
|
||||
| **棘轮(只拦增量)** | 不阻塞 | 拦住 | ✅ 债务可见且不恶化 |
|
||||
| 无门禁 | 不阻塞 | 不拦 | 债务无声增长 |
|
||||
|
||||
这与 [warning-fatigue-control.md](warning-fatigue-control.md) 的结论一致:
|
||||
**老账不追、新账必拦**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 呈现(已具备)
|
||||
|
||||
| 面 | 表现 |
|
||||
|----|------|
|
||||
| `expr_display` / `view` | 遮蔽渲染为 `[描述](实现)`,桩渲染为 `[描述]()`,实测 `view output` 页面含 `access(` |
|
||||
| `labels` | 人类行 `文件:行 [函数] 描述 ← 命中词`;`--json` 一个数组 |
|
||||
| `check` | `label.*` 三类诊断(missing / empty_payload / ref_dangling) |
|
||||
| MLSP | `labels.search` · `session.summary` |
|
||||
|
||||
**没有做桩徽章**:桩已经是 `[描述]()` 这个显眼形状,再加装饰是噪音;
|
||||
需要计数时用 `labels --count`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(1 个四步用例) | 建账 → 增加失败 → 减少收紧 → 回退再次失败 | ✅ |
|
||||
| 全量 | `cargo test --release` | **605 passed / 0 failed**(M7 后 604 + 1) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/main.rs` | `labels --baseline` / `--fail-on-increase`;建账/收紧/违约逻辑 |
|
||||
| `tests/ratchet.rs` | 四步棘轮用例 |
|
||||
| `doc/design/change-m8-ratchet.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 |
|
||||
| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` |
|
||||
| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 先修回归:view 用错解析模式
|
||||
|
||||
`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件,
|
||||
而 per-file `markup:` 是在 `load` 层生效的(M7)。结果:
|
||||
|
||||
```
|
||||
<div class="structure"><div class="err">parse/load error: expected ')' after link-index collection</div></div>
|
||||
```
|
||||
|
||||
任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。
|
||||
用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。
|
||||
|
||||
**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`,
|
||||
用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。
|
||||
|
||||
## 2. 遮蔽呈现
|
||||
|
||||
### 2.1 浏览视图(`document.rs`,`/file`)
|
||||
|
||||
```html
|
||||
<div class="doc-line doc-occl" data-line="81">
|
||||
<span class="occl-pre">留存 =</span> <!-- 变量名:灰、等宽 -->
|
||||
<span class="occl-label">客户留存率,模拟数据</span> <!-- 描述:正文 -->
|
||||
<code class="occl-code">0.42</code> <!-- 实现:代码片 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
- 空载荷 → `<span class="occl-stub">桩</span>`(琥珀色徽章,title 说明"未接通或待补返回值")
|
||||
- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致)
|
||||
- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画
|
||||
|
||||
### 2.2 卡片视图(`render.rs`,`/debug`)
|
||||
|
||||
按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句),
|
||||
渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。
|
||||
|
||||
### 2.3 样式(`html.rs`)
|
||||
|
||||
```css
|
||||
.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; }
|
||||
.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); }
|
||||
.occl-label { color:var(--ink); }
|
||||
.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line);
|
||||
border-radius:6px; padding:.02rem .38rem; }
|
||||
.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; }
|
||||
```
|
||||
|
||||
刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) |
|
||||
| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 |
|
||||
| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` |
|
||||
| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 |
|
||||
| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) |
|
||||
|
||||
## 4. 未能做到的:截图
|
||||
|
||||
本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在),
|
||||
`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com`
|
||||
TLS 断连,两次重试均失败)。所以无法自动截图比对,改为:
|
||||
DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) |
|
||||
| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` |
|
||||
| `src/view/debug_page.rs` | 1 处同上 |
|
||||
| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 |
|
||||
| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 |
|
||||
| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 |
|
||||
| `doc/design/change-m8-view-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 变更记录:M9 两级词表检索(`labels` CLI + MLSP `labels.search`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M9([occlusion-description-and-search.md](occlusion-description-and-search.md) §3 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/label.rs` · `src/main.rs` · `src/mlsp.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增 CLI 子命令与 MLSP 方法(**不改语法**) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两级词表
|
||||
|
||||
| 级 | 在哪 | 作用 |
|
||||
|----|------|------|
|
||||
| **第一级:内置** | `label::BUILTIN_GROUPS`(数据常量) | 默认查询 + LLM 范例 + 跨项目可比 |
|
||||
| **第二级:参数** | `--grep` / `grep` | 替换或并集,项目自己的说法照样能搜 |
|
||||
|
||||
内置六组:`未完成`(待开发/未开发/开发中/未实现/待实现/未接/接口未接/TODO)、
|
||||
`假数据`(模拟/假数据/桩/占位/stub/mock)、`示例`、`实验`、`废弃`、`待校验`。
|
||||
`pending` = `未完成 ∪ 假数据`。
|
||||
|
||||
**词表是数据不是语法**:扩充它不改任何解析规则。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo labels . # 默认:pending 口径(内置两组)
|
||||
marqdo labels . --grep "联调" # 替换为自定义词
|
||||
marqdo labels . --grep "联调" --also-builtin # 自定义 ∪ 内置
|
||||
marqdo labels . --group 示例,实验 # 选内置组
|
||||
marqdo labels . --count # 只给数字(CI/棘轮用)
|
||||
marqdo labels . --json # 一个 JSON 数组
|
||||
```
|
||||
|
||||
输出(人类):
|
||||
|
||||
```
|
||||
a.mq.md:3 [main] 按关键词检索,接口未接,待开发 ← 待开发,未接,接口未接
|
||||
a.mq.md:4 [main] 客户留存率,模拟 ← 模拟
|
||||
label search: 2 命中(1 文件,词=[…])
|
||||
```
|
||||
|
||||
`--json`:
|
||||
|
||||
```json
|
||||
[{"file":"a.mq.md","line":3,"unit":"main","label":"…","words":["待开发"],"has_payload":true}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. MLSP
|
||||
|
||||
```json
|
||||
{"id":1,"method":"labels.search",
|
||||
"params":{"source":"…"|"path":"…","grep":["联调"],"also_builtin":true}}
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```json
|
||||
{"ok":true,"words":[…],"count":2,"hits":[{"line":3,"unit":"main","label":"…",
|
||||
"words":["待开发"],"has_payload":true}]}
|
||||
```
|
||||
|
||||
语义与 CLI 完全一致(同一份 `label::search`)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 检索语义(v1)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 匹配 | **子串**(CJK 无词边界,子串最稳) |
|
||||
| 多词 | OR |
|
||||
| 大小写 | 英文不敏感(`TODO`/`todo` 等价) |
|
||||
| 误判 | 必然存在(`[不属于待开发范围]` 会命中)——只影响计数,输出带描述原文可人工判断 |
|
||||
|
||||
不做否定语法;留作 v1.1 可选项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(4) | pending 计数=2;`--grep` 替换=1;`--also-builtin` 并集=3;MLSP `labels.search` 返回 hits | ✅ |
|
||||
| 全量 | `cargo test --release` | **587 passed / 0 failed**(M4 后 583 + 4) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只在 occlusion 模式产生命中 | classic 模式下没有 `Expr::Occluded`;M7 翻转默认后自然可用 |
|
||||
| 解析失败的文件跳过 | 那是 `check` 的职责,检索不应因一个坏文件整体失败 |
|
||||
| 不做棘轮 | `--baseline` / `--fail-on-increase` 留给 M8(门禁) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `WordGroup` / `BUILTIN_GROUPS` / `PENDING_GROUPS` / `group_words` / `parse_words` / `matched_words` / `Hit` / `search` |
|
||||
| `src/main.rs` | `labels` 子命令 + `collect_mq_files` 递归扫描 |
|
||||
| `src/mlsp.rs` | `labels.search` 方法 + 分发 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/labels.mq.md` | 4 个集成测试 |
|
||||
| `doc/design/change-m9-label-search.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
|
||||
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
|
||||
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
|
||||
|
||||
| 复制的内容 | 说明 |
|
||||
|-----------|------|
|
||||
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
|
||||
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
|
||||
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
|
||||
| `register` + `#[no_mangle]` 四导出 | 样板 |
|
||||
|
||||
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
|
||||
|
||||
## 2. 方案
|
||||
|
||||
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
|
||||
|
||||
```rust
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
|
||||
]);
|
||||
```
|
||||
|
||||
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
|
||||
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
|
||||
|
||||
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
|
||||
|
||||
## 3. 安全措施:注册项逐一核对
|
||||
|
||||
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
|
||||
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
|
||||
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
|
||||
|
||||
补救:正则允许 `::`,并把新旧两张表逐项比对:
|
||||
|
||||
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|
||||
|------|------------|--------|------|
|
||||
| agent | 63 | 63 | **0** |
|
||||
| quantum | 41 | 41 | 0 |
|
||||
| linalg | 31 | 31 | 0 |
|
||||
| llm | 2 | 2 | 0 |
|
||||
| demo | 2 | 2 | 0 |
|
||||
|
||||
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
|
||||
|
||||
另外两次由"编译通过但语义已变"暴露的问题:
|
||||
|
||||
| 问题 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
|
||||
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
|
||||
|
||||
## 4. 收益
|
||||
|
||||
| 插件 | 迁移前 | 迁移后 | 变化 |
|
||||
|------|--------|--------|------|
|
||||
| agent | 1,237 | 929 | −308 |
|
||||
| quantum | 1,045 | 835 | −210 |
|
||||
| linalg | 688 | 524 | −164 |
|
||||
| llm | 405 | 278 | −127 |
|
||||
| demo | 170 | 73 | −97 |
|
||||
| 新增 SDK | — | 232 | +232 |
|
||||
|
||||
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release`(含 5 个插件) | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
|
||||
| 注册项三元组比对 | 5 个插件全部 0 差异 |
|
||||
|
||||
## 6. 边界
|
||||
|
||||
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
|
||||
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
|
||||
- 后续新增插件只需依赖 SDK + 一行宏调用。
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
|
||||
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
|
||||
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
|
||||
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
|
||||
| `doc/design/change-plugin-sdk.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 代码体量审计:53k 行里哪些是特性、哪些是冗余
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **实施记录**(精简依据与进度) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 结论 | 冗余已清 ~14.5k 行;**剩余体量主要是特性面**,不是废弃物 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前账目
|
||||
|
||||
| 部分 | 行数 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/` | **52,668** | 其中约 **5,200** 是内联测试(`#[cfg(test)]`) |
|
||||
| `plugins/` + `crates/` | **14,700** | 5 个 ABI 插件(含共享 SDK)+ wasm crate |
|
||||
| 合计 Rust | **67,368** | |
|
||||
|
||||
最大的 10 个文件:
|
||||
|
||||
| 行数 | 文件 | 性质 |
|
||||
|------|------|------|
|
||||
| 4,451 | `src/view/html.rs` | 3,861 行是 CSS/HTML 字符串(页面皮肤) |
|
||||
| 2,691 | `src/parse/mod.rs` | 解析器主体 + 412 行内联测试 |
|
||||
| 2,194 | `src/parse/expr.rs` | 表达式解析 + 465 行内联测试 |
|
||||
| 2,063 | `src/host/foreign_doc.rs` | 外部语言内核(python/node 文档执行) |
|
||||
| 1,648 | `src/host/dispatch.rs` | 202 个宿主函数的元数据表(已合一) |
|
||||
| 1,968 | `src/host/foreign.rs` | 外部进程/会话管理 |
|
||||
| 1,925 | `src/interp.rs` | 树遍历求值器 |
|
||||
| 1,913 | `src/view/render.rs` | 渲染 |
|
||||
| 1,309 | `src/formula/mod.rs` | `$$…$$` 公式求值 |
|
||||
| 1,168 | `src/view/annot.rs` | 注解/映射 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 已清除的冗余(14.5k 行)
|
||||
|
||||
| # | 项 | 行数 | 提交 |
|
||||
|---|----|------|------|
|
||||
| 1 | `plugins/web-rust-archive/`(31 文件,非 workspace 成员、默认不构建、被 Go `libweb` 取代) | **14,235** | `13012ca` |
|
||||
| 2 | `as_text` × 18 份复制(两种措辞)→ 一个 `host::as_text` | ~100 | `8b0ea9e` |
|
||||
| 3 | `catalog.rs` 的 4 个助手(与 `knowledge::util` 逐字相同) | ~70 | `8b0ea9e` |
|
||||
| 4 | `view` 路由 34 臂 → 2 张表(`handle` / `handle_debug`) | 99 | `8b0ea9e` |
|
||||
| 5 | 无调用点死代码 ×5(`parse_italic_assign` 等) | ~50 | `a14a6e2` |
|
||||
| 6 | 转义重复:URL 编码器 2 份、`escape_js_string` 2 份(debug 副本漏 U+2028/2029) | ~40 | `9324032` |
|
||||
| 7 | AST 遍历器 3 份 → `ast::walk_stmts` / `ast::stmt_line` | ~50 | `deac53d` |
|
||||
|
||||
**顺带修出的真实缺陷**(不是行数问题,是正确性问题):
|
||||
|
||||
| 缺陷 | 发现方式 |
|
||||
|------|---------|
|
||||
| `Access` 变体只有隐式判别值(重排即错位) | 新加的一致性测试 |
|
||||
| HOST id 空间稀疏——不是 bug,但此前无测试守护 | 同上(测试先报"不连续",核实后改成"稀疏但可还原") |
|
||||
| `escape_js_string` 的 debug 副本漏转义 U+2028/2029(JS 里是换行符) | 对比两份实现 |
|
||||
| `view` 路由分布在两个 handler,只改一个会让 debug 路由全 405 | 改完实测 HTTP |
|
||||
|
||||
---
|
||||
|
||||
## 3. 剩余体量为什么不是"冗余"
|
||||
|
||||
逐项核过,剩下的都是**功能**,删掉就是砍特性:
|
||||
|
||||
| 区域 | 行数 | 为什么保留 |
|
||||
|------|------|-----------|
|
||||
| `view/` 合计 | ~12,000 | live server + notebook UI:路由、渲染、注解、调试面板、执行报告;审计确认是 feature-gated 的一等 CLI 面 |
|
||||
| `host/foreign*` | ~5,100 | 外部语言内核(python/node 持久会话、快照、中断);qdagent 的沙箱执行依赖 |
|
||||
| `parse/` | ~4,900 | 词法/语法主体 + 内联测试 |
|
||||
| `bytecode/` | 1,921 | 第二后端;72 处测试引用(含双后端一致性) |
|
||||
| `knowledge/` | ~4,000 | catalog / EKC / 指纹;`marqdo catalog` 的输出有 golden 测试 |
|
||||
| `formula/` | 1,741 | `$$…$$` 公式;与 `ast::Expr` 是**不同类型**的两套求值器(不可合并) |
|
||||
| `host/dispatch.rs` | 2,052 | 202 个宿主函数的元数据 + 分派;`call_host` 是 202 个一行臂 |
|
||||
| `view/html.rs` | 4,451 | 其中 3,861 是页面皮肤字符串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 剩余可精简项(已定位,未做)
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| ~~插件 ABI 前言共享 crate~~ | **已完成**:[change-plugin-sdk.md](change-plugin-sdk.md),净减 674 行,注册项 0 差异 |
|
||||
| ~~HostFn 五表合一~~ | **已完成**:[change-hostfn-table.md](change-hostfn-table.md),−404 行,203 项逐字节一致 |
|
||||
| `view/html.rs` 皮肤"重复声明基础 CSS" | **审计判断不成立**:实测基础样式 312 条规则、notebook 128 条,**选择器零重叠**,无重复可删 |
|
||||
| `debug_page.rs` "复刻 shell" | **判断基本不成立**:只在 head/favicon 上有约 10 行相似;它没有 nav/topbar,是独立极简页 |
|
||||
| 内联测试迁到 `tests/` | 不减总量,只让 `src` 变薄;不做 |
|
||||
|
||||
**结论(修正后)**:可机械消除的重复**已经清完**。剩余体量全是特性实现,
|
||||
要再压只能砍功能(例如 `view` 调试面板、`formula` 引擎),不是"找重复"。
|
||||
|
||||
**判断**:这些加起来约 1.3k 行(总量的 2%),收益边际递减;其中插件 SDK 最值得做(消除 5 份漂移),
|
||||
其余属于"可以但不必"。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与设计的关系
|
||||
|
||||
精简的目的不是数字好看,而是**不让冗余掩盖设计**:
|
||||
|
||||
- 已消除的都是**重复实现**(同一逻辑多份 → 必然漂移)
|
||||
- 保留的都是**单一实现的特性能耐**
|
||||
- 每一条删改都跑全量测试:`605 → 609 passed / 0 failed`,编译零警告
|
||||
|
||||
如果后续还要压体量,正确的方向是**砍特性**(例如 `view` 的调试面板、`formula` 引擎),
|
||||
而不是继续在特性内部找"重复"——那已经找完了。
|
||||
@@ -347,7 +347,8 @@ plugins/web/ # Go module(替换原 Rust crate)
|
||||
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
```
|
||||
|
||||
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
|
||||
原 Rust 源码:曾置于 `plugins/web-rust-archive/`(已移出 Cargo workspace,参考用);
|
||||
该目录已于 v1.6 精简时从工作树移除,历史保留在 git 中。
|
||||
|
||||
### 9.2 产物与解析
|
||||
|
||||
|
||||
@@ -0,0 +1,654 @@
|
||||
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed;尚未实现** |
|
||||
| 日期 | 2026-10-18 |
|
||||
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
|
||||
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
|
||||
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
|
||||
|
||||
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计约束
|
||||
|
||||
v3 必须继续满足以下约束,否则不进入实现:
|
||||
|
||||
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
|
||||
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
|
||||
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
|
||||
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
|
||||
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
|
||||
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
|
||||
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
|
||||
|
||||
---
|
||||
|
||||
## 2. 基线:现在已经有什么
|
||||
|
||||
| 能力 | 状态 |
|
||||
|---|---|
|
||||
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
|
||||
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
|
||||
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
|
||||
| `foreign.session kernels= cells= values=` | 已实现 |
|
||||
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
|
||||
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
|
||||
| 无 `会话` 时无状态 cells | 已实现 |
|
||||
| view 每 cell 内核选择 / Clean / Run | 已实现 |
|
||||
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
|
||||
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
|
||||
| 显式 `writeback.record` | 已实现(库能力) |
|
||||
| 静态页按钮的“不可执行”提示 | 已实现 |
|
||||
|
||||
---
|
||||
|
||||
## 2.1 实施状态(2026-10-18)
|
||||
|
||||
| ID | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
|
||||
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
|
||||
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
|
||||
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
|
||||
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
|
||||
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
|
||||
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
|
||||
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
|
||||
|
||||
## 3. 缺口清单
|
||||
|
||||
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|
||||
|---|---|---|---|---|
|
||||
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
|
||||
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
|
||||
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
|
||||
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
|
||||
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
|
||||
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
|
||||
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
|
||||
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
|
||||
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
|
||||
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
|
||||
|
||||
---
|
||||
|
||||
## 4. 统一模型
|
||||
|
||||
### 4.1 会话句柄
|
||||
|
||||
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
|
||||
|
||||
```text
|
||||
{
|
||||
kind: "foreign-session",
|
||||
id: "<session-id>",
|
||||
document: "<entry-source-hash>",
|
||||
status: "created | ready | running | interrupted | dirty | closed",
|
||||
kernels: [...],
|
||||
cells: [...],
|
||||
inputs: [...],
|
||||
values: [...],
|
||||
generation: 1
|
||||
}
|
||||
```
|
||||
|
||||
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
|
||||
|
||||
### 4.2 三种输入
|
||||
|
||||
必须严格区分:
|
||||
|
||||
| 输入 | 目标 | 形态 | 当前 |
|
||||
|---|---|---|---|
|
||||
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
|
||||
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
|
||||
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
|
||||
|
||||
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
|
||||
|
||||
### 4.3 每 cell 输入表
|
||||
|
||||
不新增标记,仍然使用普通表:
|
||||
|
||||
```mq.md
|
||||
`单元输入` =
|
||||
| 单元 | stdin | input |
|
||||
|------|-------|-------|
|
||||
| 计算 | hello | {rate: 0.08} |
|
||||
| 复核 | | {check: true} |
|
||||
```
|
||||
|
||||
`foreign.session` 增加可选参数:
|
||||
|
||||
```text
|
||||
foreign.session kernels=... cells=... values=... inputs=`单元输入`
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- `stdin` 只给该 cell 的程序 stdin;
|
||||
- `input` 只给该 cell 的 `marqdo_input`;
|
||||
- 空值表示不提供;
|
||||
- 输入大小有上限,超限显式报错;
|
||||
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
|
||||
|
||||
### 4.4 执行流水线
|
||||
|
||||
```text
|
||||
evaluate 会话 handle
|
||||
→ open kernels
|
||||
→ apply values
|
||||
→ apply cell inputs
|
||||
→ run cell
|
||||
→ record {stdout, stderr, input_echo, result}
|
||||
→ next cell
|
||||
```
|
||||
|
||||
失败不终止整个 Run All;错误写入 cell record,journal 保留。
|
||||
|
||||
---
|
||||
|
||||
## 5. G1/G2:持久内核 stdin 与每 cell 输入
|
||||
|
||||
### 5.1 问题
|
||||
|
||||
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
|
||||
|
||||
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
|
||||
|
||||
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
|
||||
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
|
||||
- worker 协议升级为 `protocol: 2`:
|
||||
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
|
||||
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
|
||||
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
|
||||
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
|
||||
- 超时/中断关闭该次 stdin,不污染下一次 eval。
|
||||
|
||||
### 5.3 方案 B(降级):只支持 `input`
|
||||
|
||||
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
|
||||
|
||||
```text
|
||||
persistent kernel stdin is unavailable; use input= or stateless cells
|
||||
```
|
||||
|
||||
不能静默把 stdin 变成 `marqdo_input`。
|
||||
|
||||
### 5.4 方案 C:stdin cell 降级为一次性
|
||||
|
||||
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
|
||||
|
||||
### 5.5 UI 与静态
|
||||
|
||||
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
|
||||
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
|
||||
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
|
||||
|
||||
### 5.6 验收
|
||||
|
||||
- Python 与 Node 持久内核都能读取真实 stdin;
|
||||
- 同一个 cell 连续 eval 不串输入;
|
||||
- 超时/中断后下一次 eval 仍可读 stdin;
|
||||
- 无状态 cell 行为不变;
|
||||
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
|
||||
|
||||
---
|
||||
|
||||
## 6. G3:动态 plan 的边界
|
||||
|
||||
### 6.1 问题
|
||||
|
||||
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
|
||||
|
||||
### 6.2 设计决定(建议)
|
||||
|
||||
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
|
||||
|
||||
- plan 是文档的声明,不是程序运行时的副作用;
|
||||
- view 不应为了找 plan 而执行 `# main`;
|
||||
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
|
||||
|
||||
允许的动态形式:
|
||||
|
||||
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
|
||||
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
|
||||
- 运行时变化通过 G4 的显式 session API 完成。
|
||||
|
||||
**不支持**:
|
||||
|
||||
- `##` 函数内部的 plan;
|
||||
- `if`/`while` 分支里的 plan;
|
||||
- 依赖 `# main` 副作用才能得到的 plan。
|
||||
|
||||
### 6.3 诊断
|
||||
|
||||
如果源码中出现非顶层 `foreign.session`,给出:
|
||||
|
||||
```text
|
||||
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
|
||||
```
|
||||
|
||||
而不是静默降级为无状态。
|
||||
|
||||
---
|
||||
|
||||
## 7. G4:运行时更新 plan
|
||||
|
||||
### 7.1 目标
|
||||
|
||||
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
|
||||
|
||||
### 7.2 API
|
||||
|
||||
```text
|
||||
foreign.session_assign session=<handle> cell="计算" kernel="复核"
|
||||
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
|
||||
foreign.session_remove_cell session=<handle> cell="旧单元"
|
||||
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
|
||||
```
|
||||
|
||||
所有操作:
|
||||
|
||||
- 校验 cell/kernel 语言;
|
||||
- 递增 `generation`;
|
||||
- 写入 journal(kind=plan_change / value_change);
|
||||
- 标记受影响 cell 为 `dirty`;
|
||||
- 失败不改变 handle。
|
||||
|
||||
### 7.3 View
|
||||
|
||||
- 内核下拉复用 `session_assign`;
|
||||
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
|
||||
- UI 显示 generation / dirty 状态。
|
||||
|
||||
### 7.4 静态
|
||||
|
||||
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
|
||||
|
||||
---
|
||||
|
||||
## 8. G5:kernel interrupt
|
||||
|
||||
### 8.1 API
|
||||
|
||||
```text
|
||||
foreign.session_interrupt id=<session-id>
|
||||
```
|
||||
|
||||
### 8.2 行为
|
||||
|
||||
- 控制通道发送 `interrupt`;
|
||||
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
|
||||
- 保留已完成的值和 journal;
|
||||
- 状态从 `running` → `interrupted`;
|
||||
- 下一次 eval 可以继续使用内核(除非进程已损坏);
|
||||
- 超时继续作为最后一道防线。
|
||||
|
||||
### 8.3 View
|
||||
|
||||
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
|
||||
- 不自动重跑;
|
||||
- 静态导出没有 interrupt(快照不执行)。
|
||||
|
||||
### 8.4 跨平台
|
||||
|
||||
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
|
||||
|
||||
---
|
||||
|
||||
## 9. G6:状态持久化与 replay
|
||||
|
||||
### 9.1 不做的事
|
||||
|
||||
- 不做 Python pickle / Node 堆快照;
|
||||
- 不做任意对象反序列化;
|
||||
- 不把内核内存默认写进 `.mq.md`。
|
||||
|
||||
### 9.2 显式快照
|
||||
|
||||
```text
|
||||
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
|
||||
foreign.session_import path=".marqdo/sessions/doc-1.json"
|
||||
```
|
||||
|
||||
快照只包含:
|
||||
|
||||
```text
|
||||
{
|
||||
version: 1,
|
||||
document_hash: "...",
|
||||
plan_hash: "...",
|
||||
kernels: [{name, lang, cmd, values: {...}}],
|
||||
cells: [{name, kernel, status, last_ok, last_error}],
|
||||
journal: [...],
|
||||
inputs: [...]
|
||||
}
|
||||
```
|
||||
|
||||
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
|
||||
|
||||
### 9.3 replay
|
||||
|
||||
```text
|
||||
foreign.session_replay path="..." verify=True
|
||||
```
|
||||
|
||||
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
|
||||
|
||||
### 9.4 存储
|
||||
|
||||
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
|
||||
- 用户可通过 path 放到受控目录;
|
||||
- 不默认提交,不默认写源码。
|
||||
|
||||
---
|
||||
|
||||
## 10. G7:跨文档内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
|
||||
|
||||
### 10.1 原则
|
||||
|
||||
- 默认每文档独立;
|
||||
- 跨文档必须显式 `scope=` / `space=`;
|
||||
- 不自动按变量名或路径共享。
|
||||
|
||||
### 10.2 API
|
||||
|
||||
```text
|
||||
foreign.session_open lang="python" scope="shared:analytics"
|
||||
foreign.session_list scope="shared:analytics"
|
||||
foreign.session_close id=... scope=...
|
||||
```
|
||||
|
||||
- scope 注册表由 foreign runtime 管理;
|
||||
- 同名冲突报错,不覆盖;
|
||||
- view 只能打开当前文档声明允许的 scope;
|
||||
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
|
||||
|
||||
### 10.3 安全
|
||||
|
||||
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
|
||||
- journal 标记 scope;
|
||||
- 静态导出默认不打开跨文档 scope。
|
||||
|
||||
---
|
||||
|
||||
## 11. G8:非 Python/Node 持久内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
|
||||
|
||||
### 11.1 模型
|
||||
|
||||
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
|
||||
|
||||
```text
|
||||
session: none | protocol_v2
|
||||
```
|
||||
|
||||
- `none`:只能 `run` / `invoke` 一次性;
|
||||
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
|
||||
|
||||
### 11.2 适配器
|
||||
|
||||
Go 等语言通过一个薄 worker 实现:
|
||||
|
||||
```text
|
||||
control frame: eval {code, stdin, input}
|
||||
result frame: {ok, stdout, stderr, result, error}
|
||||
```
|
||||
|
||||
不允许“看起来像持久内核、实际每次重启”的假实现。
|
||||
|
||||
### 11.3 失败语义
|
||||
|
||||
- `session_open` 对 `session: none` 的语言明确报错;
|
||||
- `foreign.session` 的 plan 只能使用支持 session 的语言;
|
||||
- 静态/无状态仍可使用一次性执行。
|
||||
|
||||
---
|
||||
|
||||
## 12. G9:live → static 输入捕获
|
||||
|
||||
### 12.1 问题
|
||||
|
||||
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
|
||||
|
||||
### 12.2 设计
|
||||
|
||||
增加显式的“捕获快照”:
|
||||
|
||||
```text
|
||||
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
|
||||
```
|
||||
|
||||
快照内容:
|
||||
|
||||
- document source hash;
|
||||
- session plan(kernels/cells/values);
|
||||
- 每 cell 的 stdin/input;
|
||||
- 每 cell 的 stdout/stderr/status;
|
||||
- journal 摘要、语言/解释器版本;
|
||||
- 捕获时间。
|
||||
|
||||
静态导出:
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
|
||||
```
|
||||
|
||||
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
|
||||
|
||||
### 12.3 安全/隐私
|
||||
|
||||
- 快照可能包含 secrets;默认不提交、不发布;
|
||||
- 提供 `redact` 字段/正则;
|
||||
- 静态页面只发布脱敏后的快照。
|
||||
|
||||
### 12.4 验收
|
||||
|
||||
- live 中成功的结果可以在静态页面原样显示;
|
||||
- 不捕获内核内存,只捕获输入/输出/状态;
|
||||
- 没有快照时回退到构建时执行,行为明确。
|
||||
|
||||
---
|
||||
|
||||
## 13. G10:自动 writeback
|
||||
|
||||
### 13.1 原则
|
||||
|
||||
**“自动”必须是用户显式选择的策略,不是默认副作用。**
|
||||
|
||||
### 13.2 API
|
||||
|
||||
```text
|
||||
foreign.session persist=`写回策略`
|
||||
```
|
||||
|
||||
策略表:
|
||||
|
||||
```mq.md
|
||||
`写回策略` =
|
||||
| 单元 | key |
|
||||
|------|-----|
|
||||
| 计算 | total |
|
||||
| 复核 | check |
|
||||
```
|
||||
|
||||
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
|
||||
|
||||
### 13.3 语义
|
||||
|
||||
- 默认不写源码;
|
||||
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
|
||||
- 静态构建默认不写回;`--writeback` 必须显式;
|
||||
- writeback 只支持 JSON 可表达值;
|
||||
- 写入位置/格式仍由 `writeback` 库决定。
|
||||
|
||||
### 13.4 与静态快照的关系
|
||||
|
||||
- 静态快照是只读发布;
|
||||
- writeback 是源码内的活结果;
|
||||
- 两者可以共存,但不能互相隐式触发。
|
||||
|
||||
---
|
||||
|
||||
## 14. API / 端点汇总
|
||||
|
||||
### 14.1 新增 foreign 函数
|
||||
|
||||
```text
|
||||
foreign.session inputs=
|
||||
foreign.session_assign
|
||||
foreign.session_add_cell
|
||||
foreign.session_remove_cell
|
||||
foreign.session_set_value
|
||||
foreign.session_interrupt
|
||||
foreign.session_export
|
||||
foreign.session_import
|
||||
foreign.session_replay
|
||||
foreign.session_open scope=
|
||||
foreign.session_list scope=
|
||||
```
|
||||
|
||||
### 14.2 View API
|
||||
|
||||
```text
|
||||
POST /api/session/cell/run { cell, stdin }
|
||||
POST /api/session/run_all { restart, inputs? }
|
||||
POST /api/session/cell/clear
|
||||
POST /api/session/plan/assign
|
||||
POST /api/session/plan/add
|
||||
POST /api/session/plan/remove
|
||||
POST /api/session/plan/value
|
||||
POST /api/session/interrupt
|
||||
POST /api/session/snapshot/capture
|
||||
```
|
||||
|
||||
所有端点只操作 foreign 句柄;view 不直接读写内核。
|
||||
|
||||
### 14.3 CLI
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot FILE
|
||||
marqdo view output --execute
|
||||
marqdo view output --no-exec
|
||||
marqdo run --writeback
|
||||
```
|
||||
|
||||
不新增 `marqdo notebook`。
|
||||
|
||||
---
|
||||
|
||||
## 15. 语义矩阵
|
||||
|
||||
| 能力 | run | view | static |
|
||||
|---|---|---|---|
|
||||
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
|
||||
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
|
||||
| interrupt | 无 UI | 可调用 | 不可用 |
|
||||
| state export | 可调用 | 可显式导出 | 不导出或快照 |
|
||||
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
|
||||
| writeback | `--writeback` | 显式按钮 | 默认不写 |
|
||||
|
||||
---
|
||||
|
||||
## 16. 实施顺序
|
||||
|
||||
### P0(先做,直接影响真实使用)
|
||||
|
||||
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
|
||||
2. **G5 interrupt**:避免只能等超时。
|
||||
3. **G9 snapshot capture**:解决 live/static 不一致。
|
||||
|
||||
### P1
|
||||
|
||||
4. **G4 runtime plan updates**。
|
||||
5. **G6 export/replay**。
|
||||
|
||||
### P2
|
||||
|
||||
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
|
||||
7. **G10 explicit writeback policy**。
|
||||
|
||||
### Deferred(不在当前目标)
|
||||
|
||||
- **G7 cross-document scope**:设计保留,后续版本再开发。
|
||||
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
|
||||
|
||||
---
|
||||
|
||||
## 17. 测试设计
|
||||
|
||||
### 单元
|
||||
|
||||
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
|
||||
- 每 cell 输入隔离;
|
||||
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
|
||||
- 表格不产生 call chip(已修复);
|
||||
- plan top-level 诊断;
|
||||
- session generation / dirty;
|
||||
- export/import/replay 校验。
|
||||
|
||||
### 集成
|
||||
|
||||
- Python 持久内核读 `sys.stdin`;
|
||||
- Node 持久内核读 `process.stdin`;
|
||||
- view Run All 使用每 cell 输入;
|
||||
- interrupt 后下一次 eval 正常;
|
||||
- static snapshot 与 live 结果一致;
|
||||
- snapshot hash 不匹配显式失败;
|
||||
- cross-doc scope 冲突/清理;
|
||||
- Go 一次性 vs 持久能力诊断;
|
||||
- writeback 只显式写入。
|
||||
|
||||
### 静态
|
||||
|
||||
- 输出无 traceback;
|
||||
- 没有输入时显示说明而非伪造;
|
||||
- 多内核 controls 显示;
|
||||
- writeback slot 单块、暗色主题;
|
||||
- 静态按钮提示。
|
||||
|
||||
---
|
||||
|
||||
## 18. 兼容与迁移
|
||||
|
||||
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
|
||||
- 新 `inputs=` 可选;
|
||||
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
|
||||
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
|
||||
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
|
||||
|
||||
---
|
||||
|
||||
## 19. 需要拍板的决策
|
||||
|
||||
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
|
||||
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
|
||||
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
|
||||
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
|
||||
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
|
||||
|
||||
---
|
||||
|
||||
## 20. 当前目标范围
|
||||
|
||||
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
|
||||
|
||||
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
|
||||
|
||||
## 21. 非目标
|
||||
|
||||
- 不新增 Markdown 标记;
|
||||
- 不新增 notebook CLI/模式;
|
||||
- 不把任意内核内存序列化;
|
||||
- 不默认修改 `.mq.md`;
|
||||
- 不自动镜像变量;
|
||||
- 不把 view 变成第二套解释器;
|
||||
- 不把“未实现”伪装成支持。
|
||||
|
||||
@@ -0,0 +1,304 @@
|
||||
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 命题来源 | 用户:「函数是复用、是对高度凝练内容的提炼加工;正常人不会说『计算 37 的两倍需要抽象一个函数』,而是直接说乘二」 |
|
||||
| 定位 | 本文只谈**语义表示**与**自然语言映射**,不谈编译器与语法糖 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 把你的观察写成三条命题
|
||||
|
||||
**命题一(现象)**:函数是一种**预先抽象**装置——必须在使用之前先把内容提炼并命名,还要声明它需要哪些输入。
|
||||
|
||||
**命题二(对照)**:自然语言是**即席描述**——先把事说清楚,只有在内容确实要反复出现时,才顺手给它一个名字("以上做法,我们称为…"),而且命名之后它可以像普通名词/动词一样被使用。
|
||||
|
||||
**命题三(结论)**:因此「函数」这套仪式与「代码即文档」错位。要解决的不是调用写法,而是**用什么语义表示来承担"复用"这件事**。
|
||||
|
||||
本文的答案先给出来:
|
||||
|
||||
> **Marqdo 需要的不是更好的"函数",而是把「函数」还原成「命名」,把「调用」还原成「代入」。**
|
||||
> 函数 = **一段被命名的正文**;参数 = **那段正文里尚未确定的量**;调用 = **把这些量代入后重述一遍**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 语料给出的证据:Marqdo 的 `##` 其实不是"过程"
|
||||
|
||||
统计 `lib/ ext/ examples/ tests/` 全部 1322 个 `##`:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 函数总数 | 1322 |
|
||||
| **纯返回式**(零可执行语句,只有一个返回表达式) | **765(57.9%)** |
|
||||
| 一行式(可执行行 ≤1 且返回 ≤1) | 935(70.7%) |
|
||||
| 极短(可执行行 ≤2) | 1162(87.9%) |
|
||||
| 较长(可执行行 ≥10) | 62(4.7%) |
|
||||
| 可执行语句数**中位数** | **0** |
|
||||
| 平均 | 2.2 |
|
||||
|
||||
典型代表:`## str_trim`、`## contains`、`## to_upper`——**一个名字包一个表达式**。
|
||||
|
||||
这说明:**人们用 `##` 在做"命名",语法却要求他们按"过程抽象"的仪式来做。**
|
||||
签名(`+ n`)、祈使式调用(`> f 1 2`)、返回值约定(`*…*`)全是过程语言的行头,
|
||||
而实际内容是"给这个式子起个名字"。
|
||||
|
||||
**水土不服不是感受,是可以量化的形式错配。**
|
||||
|
||||
### 1.1 按「语义功能」再分一次类
|
||||
|
||||
把 1322 个函数按内容形态归类(同一函数可能重叠,故按主特征优先):
|
||||
|
||||
| 形态 | 判据 | 数量 | 占比 | 自然语言对应 |
|
||||
|------|------|------|------|-------------|
|
||||
| **纯命名式** | 零语句、零副作用、零分支、零循环,只有一个返回式 | **754** | **57.0%** | 「所谓 X,是指…」 |
|
||||
| **条款式** | 有分支、无副作用 | 103 | 7.8% | 「凡…则…」 |
|
||||
| **遍历式** | 有循环、无副作用 | 26 | 2.0% | 「对每一项…」 |
|
||||
| **命令式** | 含 `print` 等副作用 | **83** | **6.3%** | 「打印…」祈使句 |
|
||||
| 线性计算(其余) | 有语句但无控制流/副作用 | 356 | 26.9% | 「先…再…」 |
|
||||
|
||||
两个结论:
|
||||
|
||||
1. **命名 + 条款 = 64.8%** —— 三分之二的 `##` 落在"定义"与"条款"两种自然语言形态里,
|
||||
而这两种恰好不需要"过程"语义(§4 立场甲、乙)。
|
||||
2. **真正的副作用只有 6.3%** —— 也就是说"命令/祈使"语义只是少数派,
|
||||
完全可以隔离成一小块(§8.1),不必让它污染整体读法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么"抽象"在文档里格外别扭:复用经济学
|
||||
|
||||
抽象不是免费的。它有三项成本:
|
||||
|
||||
| 成本 | 内容 |
|
||||
|------|------|
|
||||
| **定义成本** | 要写一次定义(名字、输入、边界) |
|
||||
| **跳转成本** | 读者看到名字,必须回到定义处才能理解(文档尤其致命:要翻页/滚动) |
|
||||
| **维护成本** | 定义改了,所有使用处语义随之变化 |
|
||||
|
||||
收益只有一项:**同一内容被复用 N 次时省下的重复**。
|
||||
|
||||
于是有:
|
||||
|
||||
> **抽象值得做 ⟺ 复用次数 × 内容复杂度 > 定义成本 + N × 跳转成本**
|
||||
|
||||
在**代码**里,N 往往很大、跳转成本低(IDE 跳转、同屏),所以抽象划算。
|
||||
在**文档**里,N 常常是 **1**,跳转成本高(读者在阅读流里被打断),于是:
|
||||
|
||||
> **文档中大量"函数"是负收益的**——它们只被用一次,却强迫读者回头查定义。
|
||||
|
||||
这解释了为什么你会有"正常人不会这么说话"的直觉:**说话的默认假设是对方不知道你的定义**,
|
||||
所以人话倾向于**就地展开**;而函数默认假设读者愿意跳转。
|
||||
|
||||
---
|
||||
|
||||
## 3. 自然语言里「复用」到底有几种形态
|
||||
|
||||
程序语言只承认其中一种(命名+参数化),这是错配的第二层。
|
||||
|
||||
| 形态 | 自然语言的样子 | 对应的程序装置 | Marqdo 现状 |
|
||||
|------|---------------|---------------|------------|
|
||||
| **重复** | 再说一遍 | 复制粘贴 | ✅ 允许 |
|
||||
| **指称** | 如上所述 / 同前 / 该金额 | 变量、引用 | ✅ `` `名` `` |
|
||||
| **命名** | 所谓 X,是指…;以下称 X | 定义 / 函数 | ✅ `## X` |
|
||||
| **条款** | 凡…则…;若…应… | 条件分支、规则 | ✅ `1. 2. 3.` |
|
||||
| **范例** | 以 37 为例 | 样例/测试 | ⚠️ 仅测试目录 |
|
||||
| **表格/清单** | 见下表;用料如下 | 数据、查表 | ✅ 表格 |
|
||||
|
||||
**关键发现**:命名只是六分之一,但程序语言把它变成了**唯一的复用入口**。
|
||||
而文档写作里,**指称("该金额")与条款("凡…则…")比命名更常用**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 三种候选语义表示(哲学立场)
|
||||
|
||||
要"代替水土不服",必须给出**语义模型**,而不只是换个写法。三个候选:
|
||||
|
||||
### 立场甲:定义—代入(Definition & Substitution)
|
||||
|
||||
**语义**:一段正文被命名 → 成为一个**定义**。使用它 = 把定义里的自由量按**角色**代入,再重述。
|
||||
|
||||
```markdown
|
||||
## 加倍
|
||||
|
||||
把 `x` 乘以二,得 *y*
|
||||
```
|
||||
|
||||
使用(语义读法):**按「加倍」代入 x=37,得 74。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力 |
|
||||
| 与 Marqdo 契合 | ✅ `##`/`#` 本来就是标题(文档结构),天然是"定义"的载体 |
|
||||
| 参数观 | ✅ 角色(具名),不是位置占位符 |
|
||||
| 复用单位 | ✅ **文本段落本身**(文档即单位,符合"代码即文档") |
|
||||
| 71% 的现有一行式函数 | ✅ 直接就是"命名的表达式",无需过程仪式 |
|
||||
| 缺点 | 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5) |
|
||||
|
||||
### 立场乙:条款—援引(Clause & Citation)
|
||||
|
||||
**语义**:条件 → 结论。使用 = 援引条款并给出适用的事实。
|
||||
|
||||
```markdown
|
||||
## 计费规则
|
||||
|
||||
若 `里程` 超过 100 公里,则 `费用` 按 8 折计。
|
||||
```
|
||||
使用(语义读法):**本单里程 120 公里,依「计费规则」,费用按 8 折。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅✅ 「凡…则…」是中文说明文/法条/规章的骨架 |
|
||||
| 与 Marqdo 契合 | ✅ `1. 2. 3.` 分支已经就是条款形式 |
|
||||
| 缺点 | 数值计算写成条款别扭("把 37 乘以二"不是条款) |
|
||||
|
||||
### 立场丙:配方—配料(Recipe & Ingredients)
|
||||
|
||||
**语义**:一张用料表 + 一段做法。参数 = 配料表中的行。
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 菜谱、工艺卡、表单 |
|
||||
| 与 Marqdo 契合 | ✅✅ 表格优先正是 Marqdo 的特色;契约表已是雏形 |
|
||||
| 缺点 | 表达力弱;无法递归、无法组合;"给值"变成填表 |
|
||||
|
||||
### 取舍
|
||||
|
||||
| | 甲 代入 | 乙 条款 | 丙 配料 |
|
||||
|---|---|---|---|
|
||||
| 覆盖"命名表达式"(58% 的现状) | ✅✅ | ⚠️ | ❌ |
|
||||
| 覆盖"条件规则" | ⚠️ | ✅✅ | ❌ |
|
||||
| 覆盖"数值流程" | ✅ | ❌ | ⚠️ |
|
||||
| 可读性 | 高 | 最高 | 最高(但最弱) |
|
||||
| 与 `##` 结构一致 | ✅ | ✅ | ⚠️ 表为主 |
|
||||
|
||||
**推荐:以甲为主,乙作为甲内部的一种段落形态。** 理由见 §6。
|
||||
|
||||
---
|
||||
|
||||
## 5. 「代入」为什么比「调用」更贴自然语言
|
||||
|
||||
这不是文字游戏,三处实质差异:
|
||||
|
||||
| 维度 | 调用(invocation) | 代入(substitution) |
|
||||
|------|-------------------|---------------------|
|
||||
| 读者的心理动作 | "跳过去,看它做什么,再回来" | "把这个式子代进去" |
|
||||
| 输入的意义 | 实参 → 形参(两套名字) | 角色 → 定义里的同一个名字(**一套名字**) |
|
||||
| 结果的意义 | 函数返回了一个值 | 式子变成了具体结果 |
|
||||
| 出现位置 | 必须是独立语句或表达式 | 可以**嵌在叙述里**("加倍后为 74 件") |
|
||||
| 一次性使用 | 仍要付出定义+跳转成本 | 可以**不定义,直接展开**(§5.1) |
|
||||
|
||||
### 5.1 关键:抽象要能被"取消"
|
||||
|
||||
自然语言的强大在于**可省略**:能一句话说清就不起名字。
|
||||
所以语义模型必须允许同一件事有**两种粒度**,并可以随时在两者之间移动:
|
||||
|
||||
| 粒度 | 写法(示意) | 何时用 |
|
||||
|------|-------------|--------|
|
||||
| **就地描述** | 把 37 乘以二,得 74 | 只用一次 |
|
||||
| **命名后代入** | 按「加倍」代入 x=37,得 74 | 复用多次 |
|
||||
|
||||
而且**提升与展开都是作者的编辑动作,不是必须的入口**。
|
||||
这正是"抽象可选"——今天的函数是"必须先抽象",这是错配的第三层。
|
||||
|
||||
### 5.2 与 58% 纯表达式函数的对应
|
||||
|
||||
`## to_upper` 这类函数,用"代入"读就是:
|
||||
|
||||
> 「to_upper 的定义是:把 `s` 变成全大写。」使用:`to_upper` 代入 s="abc" 得 "ABC"。
|
||||
|
||||
它读起来是一个**定义 + 一次代入**,而不是"调用一个过程"。这与它的实际内容(一个表达式)一致。
|
||||
|
||||
---
|
||||
|
||||
## 6. 这套语义如何落到 Marqdo 已有的东西上
|
||||
|
||||
| 自然语言的成分 | Marqdo 已有载体 | 需不需要新东西 |
|
||||
|---------------|----------------|---------------|
|
||||
| 命名(给出定义) | `#` / `##` 标题 | ❌ 已有 |
|
||||
| 正文(定义的内容) | 叙述 + 标记代码 | ❌ 已有 |
|
||||
| 未确定的量(角色) | 体推断出来的形参(v0.3 已有) | ❌ 已有 |
|
||||
| 角色的**具名给值** | (缺失) | ✅ **这是唯一真正缺的一环** |
|
||||
| 结论(得…) | `*…*` 返回 | ❌ 已有 |
|
||||
| 条款(凡…则…) | `1. 2. 3.` 分支 | ❌ 已有 |
|
||||
| 配料表 | GFM 表格 + 契约表 | ❌ 已有 |
|
||||
| 引用(依…) | (缺失) | ⚠️ 与"具名给值"是同一件事 |
|
||||
|
||||
**结论:缺的只有一件事——「具名给值」的形式。**
|
||||
|
||||
也就是说:语义模型(代入)几乎不用改,语法只缺一个"把角色填上"的最小约定。
|
||||
这把问题从"要不要重新设计函数"缩小到"这一个小约定怎么长得最不刺眼"。
|
||||
|
||||
---
|
||||
|
||||
## 7. 不可回避的哲学难题:自然性 vs 可判定性
|
||||
|
||||
自然语言判断"哪些量要代入"靠**语境**(前文、常识、指代)。
|
||||
编译器不能。所以必须有一条**显式约定**,无法省掉。
|
||||
|
||||
三种可能的约定形态(只列哲学性质,不列语法细节):
|
||||
|
||||
| 形态 | 自然的程度 | 可判定的程度 | 风险 |
|
||||
|------|-----------|-------------|------|
|
||||
| **角色必须具名给出** | 中(像"按定义,其中 x=37") | ✅ 完全可判定 | 略啰嗦 |
|
||||
| **靠语序(位置)** | 高 | ✅ 可判定 | ❌ 已实测:叙述顺序一变,绑定就翻转(见 call-syntax-from-marks.md §4.3) |
|
||||
| **靠语境(隐式)** | 最高 | ❌ 不可判定 | ❌ 130 个形参名撞车 |
|
||||
|
||||
**这是整件事的硬边界**:越像人话,越难判定。Marqdo 必须选"具名"这一档——
|
||||
它是**唯一同时可读且可判定**的点。
|
||||
|
||||
而这也解释了为什么"叙述式动词"(`执行`)不可取:它把判定交给了一个**未标记的词**,
|
||||
既没有自然的程度优势,又破坏了"叙述安全"。
|
||||
|
||||
---
|
||||
|
||||
## 8. 三个尚未解决的哲学问题
|
||||
|
||||
这些是真问题,需要后续立场,不宜草率定:
|
||||
|
||||
1. **副作用怎么办?**
|
||||
"把 37 乘以二"是纯代入;"打印 74"呢?打印**改变世界**,不是代入。
|
||||
→ 副作用可能必须停留在"命令"语义(今天的 `> print`),
|
||||
而这会让文档里同时存在"代入"与"命令"两套读法。这是否可接受?
|
||||
|
||||
2. **递归与自引用怎么办?**
|
||||
代入是有限展开;递归是无限展开。若坚持代入选义,递归就不可表达。
|
||||
→ 是否接受"Marqdo 不支持递归"?还是给递归单独一套"过程"语义?
|
||||
|
||||
3. **定义的时序怎么办?**
|
||||
自然语言允许先使用后定义("如上,我们称之为…")。代入语义要求定义先存在。
|
||||
→ 是否允许前向引用(读者先看到 `加倍`,后面才看到定义)?
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话总结与建议
|
||||
|
||||
> **Marqdo 的问题不是"函数不好用",而是"函数是过程语言留给文档的遗产"。**
|
||||
> 文档需要的不是过程,是**命名**;不是**调用**,是**代入**。
|
||||
|
||||
建议的语义立场(待你裁决):
|
||||
|
||||
| 项 | 建议 |
|
||||
|----|------|
|
||||
| 复用单位 | **一段被命名的正文**(而非过程) |
|
||||
| 参数观 | **正文中未确定的量**(角色,具名) |
|
||||
| 调用观 | **代入**(可读作"按…代入…") |
|
||||
| 抽象时机 | **可选提升**:默认就地展开,需要复用时才命名 |
|
||||
| 唯一新增约定 | **具名给值**(形态待定,但必须具名,理由见 §7) |
|
||||
| 保留"命令"语义 | 仅用于副作用(`print` 等),与"代入"分层 |
|
||||
| 条款 | 作为定义的一种段落形态(`凡…则…`),不另设机制 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你裁决
|
||||
|
||||
1. **是否接受"函数→命名 / 调用→代入"这个总重构?**
|
||||
若接受,后续所有语法讨论都在这条轴上做取舍。
|
||||
2. **§8 的三个难题**你的倾向是什么(尤其"是否接受不支持递归")?
|
||||
3. **"具名给值"的最小形态**:你更接受哪一种读感?
|
||||
- `**加倍(x=37)**`(像函数调用)
|
||||
- `按**加倍**,`x`=37`(像句子,但需要判定规则)
|
||||
- 表格给出角色(像配料表)
|
||||
4. 是否需要我把这份哲学立场,反向校验一遍**现有 1322 个函数**——
|
||||
看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?
|
||||
@@ -0,0 +1,335 @@
|
||||
# 语义探析:代码函数能否解释为一张 GFM 表
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`## 函数名` + `+ 参数` + 函数体,从某种角度能否解释成 GFM 表」 |
|
||||
| 方法 | 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古 |
|
||||
| 相邻 | [functions-as-values-evaluation.md](functions-as-values-evaluation.md) · [link-style-call-evaluation.md](link-style-call-evaluation.md) |
|
||||
| 关键前置 | [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话答案
|
||||
|
||||
**你的命题在 Marqdo 里已经实现了——但它实现的是「关于函数的表」,不是「函数本身」。**
|
||||
|
||||
```
|
||||
## 加一
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
*n+1*
|
||||
```
|
||||
|
||||
这张表**今天就能跑**,是既有特性(契约表,`tests/contracts/ok_contract.mq.md`)。
|
||||
它证明了:函数参数**确实可以**是一张 GFM 表。
|
||||
|
||||
但它只能**描述**参数,不能**声明**参数;它不含函数体,不决定 arity,也不能被调用。
|
||||
一句话划界:
|
||||
|
||||
> **表能描述外延(输入→结果)与签名(元数据),不能描述内涵(怎么算)。**
|
||||
> 而「调用」恰恰是内涵操作。
|
||||
> `[k](集合)` 是**投影已有数据**,`f(x)` 是**计算新数据**——
|
||||
> 只有 f 本身已经是「预先枚举好的表函数」时,两者才重合。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先固定事实:Marqdo 的表格几何(实测)
|
||||
|
||||
讨论前必须先把「表」的语义钉死,否则会建在错觉上。
|
||||
|
||||
| 形状 | 绑定结果 | 实验 |
|
||||
|------|---------|------|
|
||||
| 1 列 N 行 | `List`(列值) | 文档锁定 + 实测 |
|
||||
| ≥2 列 **1 行** | `Map`(表头→标量,即「记录」) | `{"档位":[1,2]}` 反例 → 单行才是记录 |
|
||||
| ≥2 列 **N 行** | `Map`(表头→**列列表**,列向聚合) | 实测 `{"档位":[1,2],"税率":[0.03,0.1]}` |
|
||||
| 首列标头为 `行` / `@` / `row` | `List[Map]`(**行向记录**,显式开启) | [tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 |
|
||||
|
||||
**关键点**:Marqdo 的默认是**列向**。多行多列表不是「一组记录」,
|
||||
而是「一列一个列表」。行向记录是**显式标记**才能开的形态,
|
||||
文档原话:「**不得**与默认列向字典静默混用」。
|
||||
|
||||
这一条直接决定了「行 = 参数」在 Marqdo 里**不是自然形态**:
|
||||
按默认几何,`| 参数 | 类型 |` 两行参数会变成
|
||||
`{"参数":["a","b"], "类型":["number","number"]}` —— 列向。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你的命题已经存在:契约表
|
||||
|
||||
`src/contract.rs:308` 的注释写得很清楚:
|
||||
|
||||
```
|
||||
/// 未绑定文档表(`Expr::Map`)→ 契约块。
|
||||
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
|
||||
/// - `Some(Err)`:契约形状但畸形 —— 必产诊断。
|
||||
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
|
||||
```
|
||||
|
||||
三条规则(`src/contract.rs:260-334`):
|
||||
|
||||
| 规则 | 实现 |
|
||||
|------|------|
|
||||
| 表头含 `参数`/`形参`/`param`/`arg` → 形参契约 | `PARAM_HEADERS` |
|
||||
| 表头含 `返回`/`return`/`result` → 返回契约 | `RETURN_HEADERS` |
|
||||
| **必须含 `类型` 列**,否则视为普通说明表 | `TYPE_HEADERS` 缺失 → `return None` |
|
||||
|
||||
也就是说:**「函数参数表」不仅可能,而且已经是正式语法**。
|
||||
第一列标头(`参数` / `返回` / `字段`)扮演的正是
|
||||
[tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 里
|
||||
`行`/`@`/`row` 那种**形态标记**的角色:显式声明「这张表是干什么用的」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 但它是「关于参数的表」,不是「参数本身」
|
||||
|
||||
11 组实验里最关键的 6 组(全部实跑):
|
||||
|
||||
| # | 写法 | 实测结果 | 说明 |
|
||||
|---|------|---------|------|
|
||||
| E1 | 参数表列 `n`,函数体不读 `n` | `> f` 无参调用**成功**,`n` 不是形参 | 表不能声明形参 |
|
||||
| E3 | 叙述声明 `n` + 参数表 + 传 `"七"` | `参数 n 期望 number,实际 text(契约校验)` | **表能校验** |
|
||||
| E4 | 叙述声明 `n`,**无表** + 传 `"七"` | `七1` | 无表则不校验 |
|
||||
| E5 | `+ \`n\`` 旧式形参行 + 参数表 + 传 `"七"` | 同 E3,报契约错 | **你的草图形态可用** |
|
||||
| E6 | 表写 2 行(`a`,`b`),体只读 `a` | `too many positional arguments` | **表 ≠ arity** |
|
||||
| E7 | 单列参数表 `\| 参数 \|` + `\| n \|` | `七1`,**契约静默失效** | 1 列 = List,不成契约 |
|
||||
| E8 | 表里重复两行 `n` | 取**首行**类型,无诊断 | 表内重复静默 |
|
||||
| E9 | 表里有 `ghost`(体里没有) | 静默忽略 | 幽灵行静默 |
|
||||
| E10 | 同一张表加 `` `tc` = `` 绑定 | `七1`,契约**消失** | 绑定 → 变数据 |
|
||||
|
||||
**E10 揭示了一条隐含且优雅的规则**:
|
||||
|
||||
> **未绑定的表 = 声明/元数据(契约);绑定的表 = 数据。**
|
||||
|
||||
这正是语言对「表可以是声明吗」给出的既有答案:可以,**但前提是它不是一个值**。
|
||||
一旦你给它起名字(`` `tc` = ``),它就从「关于函数的声明」降级为「一个普通数据值」。
|
||||
|
||||
E6 + E7 + E8 + E9 合起来说明:**表与真实签名之间今天就可能漂移,而且是静默的**
|
||||
(`marqdo check e7.mq.md` 输出「无契约问题」)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若让表成为「定义」,运行时会发生什么
|
||||
|
||||
把上面的静默漂移从「少个校验」升级成「少个参数」,风险等级完全不同。
|
||||
|
||||
| 风险 | 今天(表=注解) | 若表=定义 |
|
||||
|------|----------------|-----------|
|
||||
| 漏写 `类型` 列 | 契约静默失效(E7) | **参数静默消失**,调用直接错 arity |
|
||||
| 表行数 ≠ 体读取数 | 表多余行被忽略(E6/E9) | **接口由表决定**,体重构后表未改 → 运行期崩 |
|
||||
| 重复行 | 取首行(E8) | **参数重复定义**,行为取决于解析器取舍 |
|
||||
| 表行重排 | 无影响(顺序由声明序决定) | **改变位置参数绑定顺序** → `> f 1 2` 含义变了 |
|
||||
| 加名字绑定 | 变数据(E10) | 语义分叉:什么时候是函数、什么时候是数据? |
|
||||
|
||||
最后一条最致命。**表是「可自由编辑的文档」**:调整行序、增删说明列、
|
||||
甚至把两张表合并,都是正常的写作行为。一旦表的行序决定位置参数绑定,
|
||||
「把 `b` 那行移到 `a` 上面」这个无害的编辑动作就**改变了程序行为**。
|
||||
|
||||
而 Marqdo 的核心承诺是「**文档即程序,且文档可被人阅读与维护**」。
|
||||
让排版顺序携带语义,等于给每张表埋一颗静默的雷。
|
||||
|
||||
对比一下:`[键](集合)` 之所以安全,是因为**键是显式的**,
|
||||
取元不依赖顺序。而位置参数天然依赖顺序——所以**签名不该用表承载顺序**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 为什么链接式调用 `[f](args)` 走不通(第三次论证,这次有史料)
|
||||
|
||||
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1:
|
||||
|
||||
> 心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
|
||||
```
|
||||
|
||||
§4「非目标」明确排除:点号 map 访问、`在`、箭头取元、`(键)[集合]`。
|
||||
[call-arguments.md](call-arguments.md) §2 同样锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` **不是「还没决定的语法」,而是已被明确分配给取元**。
|
||||
让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。
|
||||
|
||||
而且这与 §4 的表问题**同源**:都是「同一个外形要承载两种语义」,
|
||||
只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史:这条路走过,而且是被**反向**走过的
|
||||
|
||||
这是本轮考古最有价值的发现。四条史料:
|
||||
|
||||
### 6.1 v0.2 要求手写形参表 → v0.3 明确废除
|
||||
|
||||
[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §1 把 v0.2 的做法列为**代价**:
|
||||
|
||||
| v0.2 | 代价 |
|
||||
|------|------|
|
||||
| 形参必须 `` + `名` `` | **仪式感强;函数头像「另一套签名语言」,与正文脱节** |
|
||||
|
||||
§2 P4 直接给出新方针:
|
||||
|
||||
> **P4 — 形参由体推断(Body-inferred params)**
|
||||
> **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容)
|
||||
|
||||
§5 对照表把 `+ 名` 标为「**过渡兼容**:显式形参;**新代码不推荐**」。
|
||||
|
||||
**结论**:Marqdo 的发展方向是**离「声明式签名」越来越远**,转向「叙述即签名」。
|
||||
把参数改写成表,是在这条已经走反了的路上再走一遍。
|
||||
|
||||
### 6.2 「用表声明 schema」是明文非目标
|
||||
|
||||
[objects.md](objects.md) §6 非目标:
|
||||
|
||||
> - 用表格声明字段 schema(**表格仍表示数据集合**;见 tables-maps-footnotes.md)
|
||||
|
||||
路线图里同样列为非目标:
|
||||
|
||||
> 用表声明对象字段 schema(仍见 objects 非目标;**与数据集合分开**)
|
||||
|
||||
**结论**:语言已明确决定「表管数据,不管声明」。契约表是这一原则的**受控例外**——
|
||||
它只提供注解与校验,不提供绑定。
|
||||
|
||||
### 6.3 行向记录必须显式标记,且「不得静默混用」
|
||||
|
||||
[tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) §3.3:
|
||||
|
||||
> **备选语义(不默认):行向记录列表** …… 若未来需要,用显式标记区分,
|
||||
> **不得**与默认列向字典静默混用。
|
||||
|
||||
§3.5 落地了 `行`/`@`/`row` 标记。
|
||||
|
||||
**结论**:凡是「形态会改变语义」的地方,Marqdo 一律要求**显式标记**。
|
||||
「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式——
|
||||
而契约表的 `参数`/`返回` 头,正是这个显式标记的现成形态。
|
||||
|
||||
### 6.4 取元曾被反复挑选,最后选定链接形
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §3 记录了迁移史:
|
||||
脚注形 `` 集合[^键] ``(左键右基)→ 链接形 `[键](集合)`(左键右基,更好读)。
|
||||
|
||||
**结论**:`[…](…)` 这块语法是被**反复权衡后定下来的**,不是随手占用。
|
||||
|
||||
---
|
||||
|
||||
## 7. 诚实的收益清单
|
||||
|
||||
不能只讲风险。这条路确实有真收益:
|
||||
|
||||
| 收益 | 现状 | 潜力 |
|
||||
|------|------|------|
|
||||
| **人读** | 契约表已能带类型+说明,比 `+ 名` 可读得多 | 正是 v0.3 批评 `+` 行「仪式感」的解药 |
|
||||
| **调用边界校验** | 已实现(E3) | 可扩展到更多类型(枚举、范围) |
|
||||
| **机器读:tool schema** | ⚠️ 半成品:`tools` 已能写成记录行(`tool_names` 接受含 `name`/`工具` 字段的对象),但 `agent_format_tools` **只渲染名字**(`- name`),说明与参数被丢弃 | 若函数暴露签名,工具可带 schema 与说明,实参可校验 |
|
||||
| **机器读:CLI/表单** | ❌ 无 | 签名即表 → 直接生成命令行参数解析、Web 表单 |
|
||||
| **文档一致性** | ❌ 表与体可静默漂移(E6/E9) | 可做成「漂移即报错」 |
|
||||
|
||||
最后三行是**最有价值的**。最典型的是 tool schema:`tools` 的数据形态**已经允许**每行带说明,
|
||||
但渲染器只取名字——也就是说**能力已经在那儿,只差把签名接上去**。
|
||||
这不需要把表变成定义,只需要让签名**可被投影成表**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议:表做声明,不做定义(并补三件事)
|
||||
|
||||
### 8.1 结论
|
||||
|
||||
| 主张 | 裁决 |
|
||||
|------|------|
|
||||
| 函数参数可以用 GFM 表**描述** | ✅ **已经是特性**,继续用 |
|
||||
| 函数参数可以由 GFM 表**声明**(表即真相) | ❌ 不建议:顺序携带语义、静默漂移、与 v0.3 方向相反 |
|
||||
| 函数**本身**(含函数体)= 表 | ❌ 不可行:体是代码不是数据(见 functions-as-values §4.2) |
|
||||
| `[f](args)` 链接式调用 | ❌ 已被明确分配给取元 |
|
||||
|
||||
**保持现有分工**:
|
||||
|
||||
> 未绑定的表 = 声明(契约);绑定的表 = 数据;**函数体与 arity 是唯一真相**。
|
||||
|
||||
### 8.2 该补的三件事(都低成本,且都是「消灭静默」)
|
||||
|
||||
**① 让漂移显式化(最高价值)**
|
||||
|
||||
现状:表写 2 行、体只读 1 个 → 静默忽略(E6/E9);1 列 → 静默失效(E7)。
|
||||
建议 `marqdo check` 增加诊断:
|
||||
|
||||
| 情形 | 现在 | 应改为 |
|
||||
|------|------|--------|
|
||||
| 契约表缺 `类型` 列 | 静默视为普通表 | 若表头含 `参数`/`返回` 则 **warn**:缺 `类型` 列,已按说明表忽略 |
|
||||
| 契约表列数不齐 | 有诊断(`Some(Err)`) | 保持 |
|
||||
| 表里的参数名不在真实 arity 内 | 静默忽略 | **warn**:`ghost` 不是本函数的形参 |
|
||||
| 表头重复参数名 | 取首行 | **warn**:重复声明 |
|
||||
|
||||
这与本轮 D9「未闭合引号静默吞行」是同一类问题——**静默类缺陷**优先修。
|
||||
|
||||
**② 反向生成:签名 → 表(满足「语法很美」)**
|
||||
|
||||
既然表是好的**呈现**,就让工具来生成它,而不是让人手写:
|
||||
|
||||
```
|
||||
marqdo view --signature 文件.mq.md # 从体推断的签名生成契约表草案
|
||||
```
|
||||
|
||||
单一真相仍是函数体,表是**投影**。这样既拿到「签名即表」的可读性,
|
||||
又不引入第二真相。人也可以手写表,`check` 负责校验它与体一致(即 ①)。
|
||||
|
||||
**③ 让签名可供机器消费**
|
||||
|
||||
把 `Function` 的签名(名、参数、类型契约)暴露成结构化数据(如
|
||||
`marqdo knowledge` 的能力条目里带上参数 schema),
|
||||
`ext/ai` 的工具即可从「只渲染名字」升级为「带 schema 与说明的工具」。
|
||||
这是 §7 里最实的收益,且**零语法改动**。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一个可以试的新写法(示例,供你评判)
|
||||
|
||||
如果你想保留「表 + 函数体」的书写快感,最安全的形态是**双写 + 一致性校验**:
|
||||
|
||||
```markdown
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 档位 | number | 1/2/3 档 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 适用税率 |
|
||||
|
||||
- [行](`税率表`)
|
||||
**hit = [档位](`行`)**
|
||||
1. `hit`
|
||||
...
|
||||
*[税率](`行`)*
|
||||
```
|
||||
|
||||
| 优点 | 缺点 |
|
||||
|------|------|
|
||||
| 人读极好(表 + 正文) | 与真实签名可能漂移(需 ① 的校验兜住) |
|
||||
| 已经是**今天可跑**的语法(E5 验证) | `+ 行` 是 v0.3 标注「新代码不推荐」的旧形态 |
|
||||
| 类型校验已生效(E3) | 表不能替代体推断,参数仍要声明 |
|
||||
|
||||
**要点**:这张表**不是**函数的定义,而是它的**仪表盘**。
|
||||
真正的接口由 `+ 档位`(或叙述声明)决定,表负责类型与说明。
|
||||
只要两者不一致就报错,这套写法就既美又安全。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **裁决**:是否接受「表做声明、不做定义」(§8.1)?
|
||||
2. **优先级**:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费)
|
||||
先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
|
||||
3. **是否要我把 `+ 行` 加契约表的组合**写成教程样例(§9),
|
||||
并明确标注「`+` 是兼容形态、新代码优先叙述声明」?
|
||||
4. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
|
||||
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
|
||||
在小范围金样里验证是否可控。要我做吗?
|
||||
@@ -0,0 +1,469 @@
|
||||
# 方案评估:函数能否作为变量的一种(函数即表)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「函数本身可以理解为 `` `函数名` = `` + 参数/函数体表;此时和表格取元有极大相似性」 |
|
||||
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [spaced-function-names-d8.md](spaced-function-names-d8.md) · [function-as-table-semantics.md](function-as-table-semantics.md)(后续:函数与表格的语义考古,11 组实验) |
|
||||
| 影响面 | 值模型 / 调用语义 / 契约 / EKC 指纹 / 字节码 / 序列化 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**你的直觉在数学上是对的,但在语言上要拆成三种强弱不同的主张**:
|
||||
|
||||
| 主张 | 是否已成立 | 代价 |
|
||||
|------|-----------|------|
|
||||
| 弱:函数**名**可当数据传递 | ✅ **今天就能做**(字符串 + `call_fn`),但零参、不可静态检查 | 无 |
|
||||
| 中:函数是**一等值**(可存、可传、可返回) | ❌ 需要新值类型 + 动态 callee | 中高:契约、指纹、字节码、序列化全都要动 |
|
||||
| 强:函数**就是表**(结构性、可遍历、可序列化) | ❌ 需要把代码降格为数据 | **高**:与「代码即文档」的静态可索引性冲突 |
|
||||
|
||||
**建议**:把你草图里真正有价值的那部分(**有限域决策表**)作为一等公民支持——它今天就成立、
|
||||
且极其契合 Marqdo 的表格优先哲学;而「函数即表」的强主张不建议采纳,理由见 §4、§6。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先把「函数是变量」拆开
|
||||
|
||||
这四个概念经常被混为一谈,必须分开,否则讨论会滑。
|
||||
|
||||
### 1.1 外延观(extensional)——函数是「图」
|
||||
|
||||
数学上函数就是一组有序对 $f = \{(a,1),(b,2)\}$,即它的**图像**。
|
||||
按这个观点,函数**确实是一张表**,调用就是**查表**。
|
||||
|
||||
**但这里有一个必须先说清的实测事实**(我最初也想当然写错了):
|
||||
|
||||
GFM **两列表绑定成「列映射」,不是「按首列键控的映射」**:
|
||||
|
||||
```markdown
|
||||
`税率` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
```
|
||||
|
||||
```json
|
||||
{"档位":[1,2],"税率":[0.03,0.1]}
|
||||
```
|
||||
|
||||
所以 `[2](`税率`)` **不是**取税率,而是:
|
||||
|
||||
```
|
||||
error: missing map key `2`
|
||||
```
|
||||
|
||||
真正能「键 → 值」查表的形态是 **Map**(来自 JSON 或库函数),实测两条可用配方:
|
||||
|
||||
**配方 A(推荐,最简)**
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}**
|
||||
**t = [2](`税率`)** # → 0.1
|
||||
```
|
||||
|
||||
**配方 B(保留 GFM 表格可读性,但需显式索引)**
|
||||
|
||||
```markdown
|
||||
**ks = [档位](`税率`)** # [1, 2]
|
||||
**vs = [税率](`税率`)** # [0.03, 0.1]
|
||||
**i = > table.index_of list=`ks` item=2** # 1
|
||||
**r = > table.at xs=`vs` i=`i`** # 0.1
|
||||
```
|
||||
|
||||
两条都在 1.5.2 上跑通了。**结论**:外延观的「函数=表」在 Marqdo 里不是
|
||||
`[k](表)` 一句话就能实现,而是「**取到键值对**」这件事本身需要配方。
|
||||
这恰好是一个可补的库缺口(见 §8.1)。
|
||||
|
||||
### 1.2 内涵观(intensional)——函数是「规则」
|
||||
|
||||
`f(x) = x² + 1` 无法写成有限表(定义域无穷)。此时函数是**代码**,调用是**执行**。
|
||||
|
||||
### 1.3 闭包观——函数是「代码 + 环境」
|
||||
|
||||
参数之外还要捕获外部变量。这需要运行时的环境快照。
|
||||
|
||||
### 1.4 名字观——函数是「命名空间里的一条」
|
||||
|
||||
今天 Marqdo 就是这一种:函数存在于 `Module.functions`,按名字解析。
|
||||
|
||||
**你的草图 `|参数|函数体|` 属于哪一种?** 它是**混合体**:行是参数声明(§1.4 的味道),
|
||||
单元格放函数体(§1.2 的味道)。而「和表格取元相似」的直觉来自 §1.1。
|
||||
**三种东西被一句话连起来了**——这正是评估要解开的结。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状实测(全部在 1.5.2 上跑过)
|
||||
|
||||
### 2.1 值模型里没有函数
|
||||
|
||||
`src/value.rs:15` 的 `Value` 枚举:`None / Bool / Int / Num / Text / List / Map / Formula / Code / Secret`。
|
||||
**没有 `Func`。** 函数是 AST 节点(`src/ast.rs:58 Function`),挂在 `Module.functions`(`src/ast.rs:27`)。
|
||||
|
||||
`src/contract.rs:104` 的 `type_of` 同样是十种,穷举无函数。
|
||||
|
||||
### 2.2 调用的 callee 是静态名字,不是表达式
|
||||
|
||||
`src/ast.rs:130 CallExpr { callee: String, path, receiver, args }` ——
|
||||
`callee` 是 **`String`**,不是 `Expr`。所以**语法上无法写出「对计算出来的值发起调用」**。
|
||||
|
||||
运行期 `src/interp.rs:1119 eval_call` 最终走到 `lookup_function`(`src/interp.rs:1774`),
|
||||
按名字在 AST 树里查找。
|
||||
|
||||
### 2.3 对象已经是「表」
|
||||
|
||||
`src/interp.rs:1509 instance_type_name` 要求 method receiver 是**带 `_type` 键的 Map**:
|
||||
|
||||
```
|
||||
error: method receiver needs a map with `_type`
|
||||
```
|
||||
|
||||
也就是说 **Marqdo 里「用户定义的结构」本来就是普通 map + 一个标签**。
|
||||
对象与表之间没有鸿沟——**这与你的直觉一致,而且已经是既成事实**。
|
||||
|
||||
但函数不是。对象是值,函数不是。这个不对称值得注意。
|
||||
|
||||
### 2.4 已存在按名字间接调用:`call_fn`
|
||||
|
||||
`src/interp.rs:1295`:
|
||||
|
||||
```rust
|
||||
"call_fn" => {
|
||||
// name 必须是 text
|
||||
let target = lookup_function(module, fun, name)...;
|
||||
if !target.params.is_empty() {
|
||||
return Err("call_fn: `{name}` must have no parameters");
|
||||
}
|
||||
self.run_function(module, target, Env::new(), &[], false)
|
||||
}
|
||||
```
|
||||
|
||||
这是**今天最接近「函数可传递」的机制**,但有三道硬限制:零参、限当前模块、只在运行期校验。
|
||||
|
||||
### 2.5 六组实验
|
||||
|
||||
| # | 写法 | 结果 | 结论 |
|
||||
|---|------|------|------|
|
||||
| 1 | `**f = > greet**` | `missing argument for parameter who` | `> 名字` 是**调用**语法,**无法引用函数本身** |
|
||||
| 2 | `> call_fn name="hello"`(无参函数) | `world` | 按名字调用可行 |
|
||||
| 3 | `> call_fn name="add"`(有参) | `call_fn: `add` must have no parameters` | 不能传参 |
|
||||
| 4 | 表里存函数名 + `[h](reg)` 取名 + `call_fn` | `dispatch=world` | **动态派发今天就能做**(名字即数据) |
|
||||
| 5 | `> call_fn name="txt.str_trim"` | `unknown function` | **不能跨模块** |
|
||||
| 6 | `> call_fn name="no_such_fn"` | `unknown function` | 拼错只能在**运行期**发现 |
|
||||
|
||||
**实验 4 是关键**:它已经是「函数作为表成员」的可用原型,只是把函数表示成**名字字符串**而不是函数值。
|
||||
|
||||
---
|
||||
|
||||
## 3. 你的类比中成立的部分
|
||||
|
||||
必须明确肯定,否则会低估这个想法。
|
||||
|
||||
### 3.1 「有限域函数 = 表」是完全成立的范式
|
||||
|
||||
这类函数在工程里非常常见,而且用它表达比写代码更清楚:
|
||||
|
||||
| 场景 | 适合表格 | 为什么 |
|
||||
|------|---------|--------|
|
||||
| 税率 / 费率档位 | ✅ | 有限、离散、常改动 |
|
||||
| 状态机转移表 | ✅ | 二维查表一目了然 |
|
||||
| 错误码 → 处理动作 | ✅ | 业务方直接维护 |
|
||||
| 路由分发 | ✅ | 键即路径 |
|
||||
| 配置映射 | ✅ | 本来就是数据 |
|
||||
|
||||
而且 Marqdo 的 `[键](集合)` 取元**在语义上就是函数应用** ——
|
||||
前提是这个集合是 **Map**(键→值):
|
||||
|
||||
```markdown
|
||||
**rate = [2](`税率`)** # 读作:税率(2)
|
||||
```
|
||||
|
||||
只要 `税率` 是 Map,这行**无需任何语言改动**就是一个查表函数。你已经拥有它了。
|
||||
|
||||
唯一的坑是**数据形态要对**:GFM 两列表绑定的是**列映射**(§1.1 实测),
|
||||
`[2](两列表)` 会报 `missing map key`。所以「表 = 函数」成立,
|
||||
但**哪种表**有讲究——这正是 §8.1 要补 `table.by_column` / `table.lookup` 的原因。
|
||||
|
||||
### 3.2 表格对「参数边界」天然友好
|
||||
|
||||
上一轮讨论 `[函数名](参数)` 时,痛点是参数边界(空格切词)。表格完全绕开这个问题:
|
||||
键是**显式**的,不需要切词。
|
||||
|
||||
### 3.3 对象已证明「结构即表」不会损害语言
|
||||
|
||||
§2.3 说明对象本来就是 map。既然对象能这样,把**数据的**函数化交给表格是自洽的。
|
||||
|
||||
---
|
||||
|
||||
## 4. 类比的断裂点
|
||||
|
||||
三个,每一个都是硬约束。
|
||||
|
||||
### 4.1 断裂点一:表格是有限的,函数通常是无限的
|
||||
|
||||
外延观只对**有限定义域**成立。`f(x)=x²+1` 写成表需要无限行。
|
||||
所以「函数即表」只能覆盖**查表能解决的那部分**,不能作为函数的通用表示。
|
||||
|
||||
一旦你承认这一点,「函数即表」就从「函数的定义方式」降级为「一种特殊函数(图表函数)」。
|
||||
这仍然有用,**但不是语言的核心函数机制**。
|
||||
|
||||
### 4.2 断裂点二:函数体是**代码**,不是数据
|
||||
|
||||
你的草图把「函数体」放进单元格。但函数体在 Marqdo 里是 `Vec<Stmt>`(AST),不是 `Value`。
|
||||
要让函数体成为单元格内容,必须先让「代码」成为值——即 `Value::Code` 那种东西。
|
||||
|
||||
而 `Value::Code` 目前**只表示外联语言源码**(```lang 围栏),是交给外部执行器跑的,
|
||||
不是 Marqdo 自己的代码。让 Marqdo 代码变成值 = 引入 `eval`,这会带来:
|
||||
|
||||
- 静态检查失效(代码在运行期才成形,`marqdo check` 看不见)
|
||||
- EKC 指纹失效(§6.2)
|
||||
- 契约失效(§6.1)
|
||||
|
||||
### 4.3 断裂点三:调用不是取元——`[k](x)` 会被语义重载
|
||||
|
||||
这是最要命的一条,**与上一轮 `[函数名](参数)` 的冲突同源**。
|
||||
|
||||
若「函数是表」且「调用 = `[参数](函数表)`」,那么:
|
||||
|
||||
```markdown
|
||||
[a](m) # m 是普通 Map → 取成员 a
|
||||
[参数](f) # f 是「函数表」→ 执行?还是取成员「参数」?
|
||||
```
|
||||
|
||||
**形状完全一致,含义取决于值的类型**。这正是上一轮我们判定「不可靠消歧」的同一类问题,
|
||||
只不过从「语法层歧义」升级成了「类型层重载」。
|
||||
|
||||
Marqdo 的 `[k](coll)` 目前是**唯一且清晰**的取元语义。让它兼职「调用」,
|
||||
会让最常用的读表操作变得需要思考「这个表是不是函数」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 五条设计路径
|
||||
|
||||
### 路径 A — `Value::Func` 闭包(一等函数)
|
||||
|
||||
```rust
|
||||
Value::Func(Rc<FuncVal>) // params + body + captured Env
|
||||
```
|
||||
|
||||
调用点需支持「对表达式求值后再调用」,即 `CallExpr.callee` 从 `String` 变成 `Callee::Name(String) | Callee::Expr(Expr)`。
|
||||
|
||||
**代价**:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约(T2.1/T2.2) | `call_arg_diag(c, &target.name, …)` 依赖静态 `target: &Function`;动态调用**拿不到**,契约检查只能退化为运行期 |
|
||||
| 字节码 | `Op::Call(fid, argc)` 用**编译期函数 id**(`src/bytecode/compile.rs:709`),动态 callee 需要新指令或回退树遍历 |
|
||||
| EKC 指纹 | `collect_calls` 读 `c.callee`(`src/knowledge/fingerprint.rs:76`),动态调用只剩字面 `call_fn`,**复用/查重能力下降** |
|
||||
| 序列化 | `value_to_json`(`src/host/json.rs:98`)对 `Value` 穷举,函数值必须定义 JSON 语义(丢弃?报错?) |
|
||||
| 沙箱 | 函数值无法跨沙箱边界,`sandbox.run` 的接口要加限制 |
|
||||
| 闭包捕获 | 需要环境快照与生命周期管理;`Env` 目前是每次调用新建(`Env::new()`) |
|
||||
|
||||
**适用于**:确有高阶需求(回调、map/filter、事件处理)。属于**新语言特性**,应走 ADR。
|
||||
|
||||
### 路径 B — 函数即表(你的草图,强主张)
|
||||
|
||||
**代价**:A 的全部,**外加** §4.3 的语义重载,以及:
|
||||
|
||||
- 表可以 `table.put` 被修改 → 函数可变?还是只读?
|
||||
- 表可以遍历 → 遍历函数会看到什么?参数名?函数体 AST?
|
||||
- 表可以 `json.stringify` → 函数体以什么形式序列化?
|
||||
- 宏展开式的能力(代码即数据)会引入**自修改程序**,与「可静态审计」直接冲突
|
||||
|
||||
**结论**:**不建议**。它把 Marqdo 从「可静态索引的文档程序」推向「运行期构造的代码」,
|
||||
是在削弱自己最强的差异点(§6)。
|
||||
|
||||
### 路径 C — 对象可调用(复用 `_type` + 约定方法)
|
||||
|
||||
让 `# 类名` 实例在 `_type` 之外带一个约定的 `## 应用` 方法,`f(x)` 时若 `f` 是 map 且 `_type` 有该方
|
||||
法则走方法调用。
|
||||
|
||||
**优点**:不新增 `Value` 变体;复用既有 method 机制。
|
||||
**缺点**:仍需要「`f(x)` 里 f 是表达式」这一语法能力(同 A 的调用点改造);
|
||||
且引入「有的 map 可调用」的隐式规则,可读性下降。
|
||||
|
||||
### 路径 D — 名字即函数(扩展现有 `call_fn`)
|
||||
|
||||
不引入函数值,而是把**名字**这条路径做完整:
|
||||
|
||||
```markdown
|
||||
> call_fn name="add" args=[1, 2] # 支持传参
|
||||
> call_fn name="txt.str_trim" args=[…] # 跨模块路径
|
||||
> invoke table=`注册表` key="h" args=[…] # 从表里按名派发
|
||||
```
|
||||
|
||||
**优点**:
|
||||
- 零值模型改动 → 契约、字节码、指纹、序列化**全部不动**
|
||||
- 保持「函数永远有名字」→ EKC 能索引,代码可审计
|
||||
- 与实验 4 的现有用法完全兼容(只是补齐能力)
|
||||
|
||||
**缺点**:不是真正的一等函数(不能返回闭包);名字拼错仍要运行期发现
|
||||
(但**可以**加静态检查:`call_fn name="字面量"` 时校验目标存在——见 §8.2)。
|
||||
|
||||
### 路径 E — 决策表作为一等公民(**推荐方向**)
|
||||
|
||||
不叫它「函数即表」,而明确它是什么:**有限域查表函数**。
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}** # Map:键 → 值
|
||||
**t = [2](`税率`)** # 今天就能跑 → 0.1
|
||||
```
|
||||
|
||||
**优点**:**零语言改动**,只需文档与库函数支持(例如 `table.lookup` 带默认值,
|
||||
把 §1.1 配方 B 的「列取 + 索引」四步压成一步)。
|
||||
**定位诚实**:它是数据,不是代码;能被 EKC 索引、能序列化、能进沙箱、能被非程序员维护。
|
||||
|
||||
---
|
||||
|
||||
## 6. 对 Marqdo 特有机制的冲击面
|
||||
|
||||
这一节是决策的关键:Marqdo 不是通用语言,它的价值在**可静态索引的工程知识**。
|
||||
|
||||
### 6.1 契约系统(T2.1 / T2.2)
|
||||
|
||||
现有实现把契约挂在 `Function` 上(`src/ast.rs:71`),并在调用点用**静态 target**校验:
|
||||
|
||||
```rust
|
||||
if let Some(c) = &target.contract {
|
||||
if let Some(d) = contract::call_arg_diag(c, &target.name, &bound, …) { … }
|
||||
}
|
||||
```
|
||||
|
||||
动态 callee 拿不到静态 `target`,**契约检查必然退化到运行期**——而契约是 Marqdo
|
||||
「渐进式契约」卖点的核心。
|
||||
|
||||
### 6.2 EKC 指纹与复用
|
||||
|
||||
`collect_calls` 把调用目标名字写进指纹(`src/knowledge/fingerprint.rs:76`)。
|
||||
指纹用于**查重、复用预检、相似任务召回**。动态调用使指纹丢失真实目标,
|
||||
`marqdo duplicate` / `preflight` 的准确率会下降——这直接影响智能体复用飞轮。
|
||||
|
||||
### 6.3 「函数必须有名字」是特性,不是限制
|
||||
|
||||
EKC 按符号名索引(`marqdo knowledge` 输出 `59 modules, 346 symbols`)。
|
||||
匿名函数/表构造的函数**无法被索引**,也就无法被复用、被审计、被智能体发现。
|
||||
|
||||
> 对 Marqdo 而言,**函数有名字**不是妥协,而是「代码即文档」的必然:
|
||||
> 文档里的每一段代码都得有一个可被引用的标题。
|
||||
|
||||
### 6.4 序列化与沙箱
|
||||
|
||||
`value_to_json` 穷举所有 `Value`。函数值需要 JSON 语义;
|
||||
沙箱(CoW + 禁 exec/net/plugin)跨边界传值时,函数**无法表示**。
|
||||
一旦函数成为值,`sandbox.run` 的入参约束必须收紧。
|
||||
|
||||
### 6.5 确定性与可审计
|
||||
|
||||
表格是**静态可读**的:非程序员能改税率表。代码构造的函数则要求读者在脑中执行程序。
|
||||
Marqdo 面向的是「文档作者也能维护」的场景,这一点权重很高。
|
||||
|
||||
---
|
||||
|
||||
## 7. 方案对比
|
||||
|
||||
| 维度 | A 闭包 | B 函数即表 | C 可调用对象 | D 扩展 call_fn | E 决策表 |
|
||||
|------|--------|-----------|-------------|---------------|----------|
|
||||
| 值模型改动 | **需新变体** | 需新变体+代码即值 | 无 | **无** | **无** |
|
||||
| 保持静态可索引 | 部分(匿名不可) | ❌ | ✅ | ✅ | ✅ |
|
||||
| 契约检查 | **退化** | 退化 | 保持 | 保持 | 保持 |
|
||||
| EKC 指纹 | 退化 | 退化 | 保持 | 保持 | 保持 |
|
||||
| 序列化/沙箱 | 需特殊处理 | 需特殊处理 | 保持 | 保持 | 保持 |
|
||||
| 解决参数边界 | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| 支持无限定义域 | ✅ | ❌ | ✅ | ✅ | ❌(本质限制) |
|
||||
| 实现成本 | 高 | 很高 | 中 | **低** | **零** |
|
||||
| 风险 | 中高 | **高** | 中 | 低 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议(分阶段)
|
||||
|
||||
### 8.1 立即可做:决策表(路径 E)
|
||||
|
||||
零语言改动。补三件事即可让它好用:
|
||||
|
||||
1. **补库缺口**:新增 `table.lookup map=`key=`default=`(键→值,缺键返回 default)与
|
||||
`table.by_column rows=`key_col=`value_col=`key=`(把 §1.1 配方 B 的四步压成一步)。
|
||||
**这是当前最实的缺口**——GFM 两列表无法直接键查表,用户会反复手写索引逻辑。
|
||||
2. **文档**:在教程里明确「有限域映射怎么表达」,并给出三种形态的取舍:
|
||||
- 键→值查表 → `json.parse` 的 Map + `[键](map)`
|
||||
- 需要保留表格可读性 → 两列表 + `table.by_column`
|
||||
- 缺键行为 → 用 `table.get` / `default=`,避免缺陷 D5 的 `missing map key` 硬崩
|
||||
3. **命名**:明确它叫「决策表 / 查表」而不是「函数」——避免与 §1.2 的内涵观混淆。
|
||||
|
||||
**价值**:把用户已有的直觉固化成推荐用法,不付任何架构代价。
|
||||
|
||||
### 8.2 短期可做:扩展 `call_fn`(路径 D)
|
||||
|
||||
补齐三件事,都不触及值模型:
|
||||
|
||||
| 补充 | 说明 |
|
||||
|------|------|
|
||||
| `args=` | 允许传参,按目标签名绑定 |
|
||||
| 跨模块路径 | `name="lib.fn"` 走 import 解析 |
|
||||
| 字面量静态校验 | `call_fn name="字面量"` 在 `check` 期就校验目标存在(消灭实验 6 的类错误) |
|
||||
|
||||
**收益**:动态派发能力完整,且完全保留契约/指纹/序列化。
|
||||
|
||||
### 8.3 中期评估:一等函数(路径 A)
|
||||
|
||||
只有当出现**确实无法用名字表达**的需求时才做(例如回调、策略模式、事件处理器)。
|
||||
届时必须写 ADR,并明确回答:
|
||||
|
||||
- 匿名函数如何进入 EKC 索引?(可能需要要求「赋给变量的函数字面量必须有名字」)
|
||||
- 契约在动态调用下如何降级?
|
||||
- 字节码是否引入 `Op::CallValue`?
|
||||
- 函数值的 JSON 语义是什么?
|
||||
|
||||
### 8.4 不建议:路径 B(函数即表,强主张)
|
||||
|
||||
理由汇总:§4.3 语义重载 + §6 全面削弱静态可索引性 + §5 自修改程序风险。
|
||||
|
||||
---
|
||||
|
||||
## 9. 如果你想保留「函数即表」的形态,有一个折中
|
||||
|
||||
把「表」用于**参数与分发**,而不用于函数体:
|
||||
|
||||
```markdown
|
||||
`税率表` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
**ks = [档位](`税率表`)**
|
||||
**vs = [税率](`税率表`)**
|
||||
**i = > table.index_of list=`ks` item=`档位`**
|
||||
**r = > table.at xs=`vs` i=`i`**
|
||||
*r*
|
||||
```
|
||||
|
||||
(若 §8.1 的 `table.by_column` 落地,函数体可缩成一行:
|
||||
`**r = > table.by_column rows=`税率表` key_col="档位" value_col="税率" key=`档位`**`。)
|
||||
|
||||
这里:
|
||||
|
||||
- **数据**在表里(可被非程序员维护、可序列化、可进沙箱、可被 EKC 索引)
|
||||
- **逻辑**在命名函数里(可契约、可指纹、可审计)
|
||||
- 调用仍是一等清晰的 `> 税率 档位=2`
|
||||
|
||||
这其实是**最好的分工**:表格承担「知识」,函数承担「行为」。
|
||||
它同时满足你的类比直觉(表驱动)和 Marqdo 的静态可索引性。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **方向**:选 E(决策表,零改动)、D(扩展 call_fn)、还是 A(一等函数,需 ADR)?
|
||||
2. 若倾向 D:`args=` 的参数形式用 `[1, 2]`(列表)还是 `a=1 b=2`(具名)?
|
||||
3. 是否要我把 §9 的「数据在表、逻辑在函数」写成教程规范?
|
||||
4. 是否存在**具体用例**驱动一等函数?(例如某个 ext 需要回调)
|
||||
若有真实用例,评估会完全不同——请给我场景,我按场景重新评估。
|
||||
@@ -0,0 +1,414 @@
|
||||
# 纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(含语法落地、诊断 schema、分阶段计划) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 决策来源 | 用户:取**纯度**;标签**可省略但编译器须报错**;循环写法不重要;**重点:标签过期与 agent 误导** |
|
||||
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) |
|
||||
| 依托设施 | `src/diagnostics.rs`(`doc_anchor`/`doc_quote`/`contract_ref`)· `src/mlsp.rs`(`validate`/`repair_targets`/`repair_apply`)· `src/repair.rs`(有界修复)· `src/knowledge/fingerprint.rs` · `src/knowledge/lifecycle.rs`(已有 `find_stale`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 决策记录与一个推论
|
||||
|
||||
**已定**:
|
||||
|
||||
1. **纯度**:`()` 只装机器语句,`[]` 只装人话;取元搬进 `()`。
|
||||
2. **标签可省略,但编译器报错**:写空方括号是可能的,但那是一个**错误**。
|
||||
3. **循环写法从简**:`[]` 已是描述,`()` 内部只要自洽即可。
|
||||
|
||||
**由此得到一个必须先说清的推论**:
|
||||
|
||||
> **纯度强制两件东西同时存在**:
|
||||
> ① 一个**不带标签**的普通表达式写法(否则每个访问都被迫配一段人话 = 仪式感复辟);
|
||||
> ② 带标签的形式作为一个**可选包装**。
|
||||
|
||||
也就是说 `[标签](表达式)` 不是"唯一的表达式语法",而是"**当你想做断言时才用的包装**"。
|
||||
这一条同时解决了我在上一份文档里担心的"标签凑数"退化:
|
||||
**不想断言,就别用这个形式**——而不是"必须写标签但可以写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 1. 纯度路线下的语法落地
|
||||
|
||||
### 1.1 形式
|
||||
|
||||
```
|
||||
带标签表达式 ::= '[' 人话 ']' '(' 表达式 ')'
|
||||
```
|
||||
|
||||
- `表达式` = **现有 Marqdo 表达式文法**(不新增语言)
|
||||
- `人话` = 任意自然语言,必须是**关于这个值的断言**(§2)
|
||||
- 出现位置:表达式位置、语句位置、循环位置
|
||||
|
||||
### 1.2 关键缺口:普通取元怎么写
|
||||
|
||||
纯度之后 `[键](集合)` 不再是取元,所以必须给出**不带标签的取元写法**。四个候选:
|
||||
|
||||
| 方案 | 写法 | 优 | 劣 |
|
||||
|------|------|----|----|
|
||||
| **A 现有内建** | `[第一项](at value=篮子 index=1)` | 零新语法,今天就能实现 | 啰嗦;`value=`/`index=` 是机器腔 |
|
||||
| **B 后置方括号** | `[第一项](篮子[1])` | 最像通用语言;`篮子[拿铁]` 读起来自然 | `[]` 出现两种角色(前置=人话,后置=索引),视觉易混 |
|
||||
| **C 函数式 + 逗号参数** | `[第一项](at(篮子, 1))` | 与 `加一函数(31)` 统一;顺带解决前几轮想要的 `f(args)` | 需支持逗号分隔实参(要改参数分词器) |
|
||||
| D 点号 | `[拿铁价格](菜单.拿铁)` | 短 | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形 |
|
||||
|
||||
**我的建议**:**C**。
|
||||
|
||||
理由:你前面想要 `f(args)` 这种"人读友好"的调用,而 C 与它**同一个改动**——
|
||||
一次性把 `()` 内的表达式升级为「可带括号实参」的形式,
|
||||
`at(篮子, 1)`、`加一函数(31)`、`get(菜单, 拿铁)` 全部成立,且不新增第二种方括号角色。
|
||||
代价是参数分词器要支持 `)` 终止与逗号(前几轮原型已验证方向可行,全量 554/0 回归)。
|
||||
|
||||
若你希望**零实现风险**,选 A:今天就能用,只是啰嗦,后续可再收窄成 C。
|
||||
|
||||
### 1.3 空标签 = 硬错误
|
||||
|
||||
```markdown
|
||||
[](at(篮子, 1)) # ❌ label.missing
|
||||
```
|
||||
|
||||
诊断:`code: "label.missing"`,`severity: error`,`doc_quote: "[]"`,建议:
|
||||
「给这段语句写一句人话描述,或改用不带标签的普通表达式」。
|
||||
|
||||
**这一条是整套设计的门槛**:它把"标签"从可选装饰变成"用了就得负责"的承诺。
|
||||
也正好落实你说的「可以省略,但编译器应当报错」。
|
||||
|
||||
### 1.4 循环
|
||||
|
||||
你说不重要,那我给最省事、且与纯度一致的一条:
|
||||
|
||||
```markdown
|
||||
- [从篮子取出的每个果子](foreach 篮子 为 果)
|
||||
```
|
||||
|
||||
- `[]` 是描述(人读)
|
||||
- `()` 是机器语句:遍历什么、绑定给谁
|
||||
- 循环变量名从 `[]` **搬进 `()`**——因为 `[]` 不再承担绑定职责
|
||||
|
||||
若嫌 `foreach 篮子 为 果` 太新,可就近用现有词:
|
||||
`- [从篮子取出的每个果子](遍历 篮子 绑定 果)`。
|
||||
**关键是别再让 `[]` 兼任变量名**——否则"描述"与"标识符"又会打架。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标签是什么:**可校验断言的载体**
|
||||
|
||||
标签不是注释。三者区别:
|
||||
|
||||
| | 注释 | 标签 |
|
||||
|---|------|------|
|
||||
| 位置 | 游离于代码之外 | **锚定在 AST 节点上**(有 span,可定位) |
|
||||
| 可核验 | 不能 | **能**(§3) |
|
||||
| 可进修复协议 | 不能 | **能**(随诊断导出给 LLM) |
|
||||
| 变更感知 | 无 | **能**(代码变了会撞上旧断言) |
|
||||
|
||||
一句话:**标签 = 贴在可执行片段上、可被机器复核的断言。**
|
||||
这正是 Marqdo 相对传统"文档 + 注释"的核心增量。
|
||||
|
||||
---
|
||||
|
||||
## 3. 过期检测:三层机制
|
||||
|
||||
你问的核心是:**`()` 改了,怎么让 `[]` 的旧描述"叫起来"。**
|
||||
这需要三种能力,缺一不可,且分属不同层。
|
||||
|
||||
### 3.1 L1 引用一致性(无状态、确定性、零成本)
|
||||
|
||||
**规则**:标签内用反引号写出的名字 = **实体断言**。
|
||||
|
||||
```markdown
|
||||
[按 `税率` 计算总价](...)
|
||||
```
|
||||
|
||||
可核验的断言:
|
||||
|
||||
1. `` `税率` `` 必须**可解析**(在当前作用域/模块里存在)
|
||||
2. 它必须**出现在 `()` 的实际内容中**(或经调用链可达)
|
||||
|
||||
任一条不成立 → `label.stale`(引用已腐烂)。
|
||||
|
||||
**为什么低假阳性**:只有**显式反引号**才算断言,普通汉字不参与判定。
|
||||
这复用了 Marqdo 已有的 `` `名` `` = 实体 的约定,**没有新增记号**。
|
||||
|
||||
**局限(必须承认)**:它只查"引用",查不出"语义"。
|
||||
`税率` 还在,但操作从"乘"改成"除",L1 看不见。
|
||||
|
||||
### 3.2 L2 指纹台账(有状态、能查语义腐烂)
|
||||
|
||||
**做法**:把「标签写下时,它描述的那段代码」记一份指纹。
|
||||
|
||||
`.marqdo/labels.json`(与 EKC 产物同目录,视为**缓存**):
|
||||
|
||||
```json
|
||||
{
|
||||
"按税率计算总价#1": {
|
||||
"code_fingerprint": "9f2a…",
|
||||
"code_quote": "at(税率表, 档位) * 金额",
|
||||
"confirmed_at": "2026-10-22T09:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `code_fingerprint`:复用 `src/knowledge/fingerprint.rs`(已有 `collect_calls` / `ops_hint` / `fingerprint_hash`)
|
||||
→ **调用与运算变了,指纹就变**
|
||||
- `code_quote`:**旧代码的文本快照**——这就是你说的"保留内容用于校验"的对称物:
|
||||
`doc_quote` 保留 `[]`,`code_quote` 保留 `()`,两者一起导出给 LLM 对比
|
||||
- 键 = `规范化标签文本 + 同文本序号`(按标签键而不是按行号,**移动代码不会误报**)
|
||||
|
||||
**命中规则**:
|
||||
|
||||
| 变化 | 判定 |
|
||||
|------|------|
|
||||
| `()` 指纹变 | **stale**:标签描述的代码已变,需复核 |
|
||||
| 标签文本变 | **新断言**:无历史,首次确认即可 |
|
||||
| 两者都没变 | 通过 |
|
||||
|
||||
**局限**:需要状态文件;合并冲突要处理(§8.2)。
|
||||
|
||||
### 3.3 L3 LLM 复核(修复协议闭环)
|
||||
|
||||
诊断被导出时同时携带三方信息:
|
||||
|
||||
- `doc_quote`:`[]` 里的原话
|
||||
- `code_past`:`()` 当时的文本(来自台账)
|
||||
- `code_now`:`()` 现在的文本
|
||||
|
||||
模型据此判定三选一:
|
||||
|
||||
1. **改标签**(代码意图是对的,描述过期了)
|
||||
2. **改代码**(描述是对的,实现跑偏了)
|
||||
3. **确认无害**(改动不影响断言,写回台账 `confirmed`)
|
||||
|
||||
这正好接进**已有的修复回路**(`src/repair.rs`):`validate` → `repair_targets` → 模型行编辑 →
|
||||
`repair_apply`(越界必拒)→ 复验。
|
||||
|
||||
### 3.4 为什么三层都要
|
||||
|
||||
| 层 | 查什么 | 能否查"乘改除" | 需要状态 | 假阳性 |
|
||||
|----|--------|--------------|---------|--------|
|
||||
| L1 | 引用腐烂(改名/删除) | ❌ | 无 | 极低 |
|
||||
| L2 | 语义腐烂(同引用、不同操作) | ✅ | 需台账 | 中(无害改动也报) |
|
||||
| L3 | 谁错了(标签 or 代码) | ✅ | 复用 L2 | 由模型判 |
|
||||
|
||||
**L1 是地基**(确定性、零成本、可先上),**L2 是覆盖**(能查语义),**L3 是裁决**(谁改)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与现有设施的对接(这决定了落地成本)
|
||||
|
||||
### 4.1 诊断字段:**已经齐备,不需要新造**
|
||||
|
||||
`src/diagnostics.rs` 的 `to_json` 已输出:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "…", "severity": "…", "message": "…",
|
||||
"span": {"file":…, "line":…, "col":…},
|
||||
"doc_anchor": …, ← 标签位置
|
||||
"doc_quote": …, ← 标签原文
|
||||
"contract_ref": {"unit":…, "kind":…, "name":…, "declared":…},
|
||||
"suggestion": …
|
||||
}
|
||||
```
|
||||
|
||||
**`contract_ref.declared` 就是"声明"这一侧的先例**:
|
||||
契约诊断说的是「**declared** number,actual text」,
|
||||
标签诊断说的是「**declared(标签里的人话)**,actual(`()` 现在的代码)」——
|
||||
**同一个模式,只是从类型层下沉到散文层。**
|
||||
|
||||
> 这也回答了你的问题:"导出时能否保留 `[]` 的内容用于校验"——
|
||||
> **能,而且字段已经在协议里了**:`doc_quote` 就是它。
|
||||
|
||||
### 4.2 契约诊断是现成的范式
|
||||
|
||||
`src/contract.rs:203` 的 `Contract::diagnostic(...)` 一次性装配
|
||||
`code + severity + suggestion + doc_anchor + doc_quote + contract_ref`。
|
||||
标签诊断可以照抄这套装配,只是 `kind` 从 `"contract"` 换成 `"label"`。
|
||||
|
||||
### 4.3 修复范围:允许"标签行 ∪ 代码行"
|
||||
|
||||
现在 `repair_apply` 的形状是 `ranges: [[起, 止], …]`,**天然支持多个区间**。
|
||||
`label.stale` 只需把两段都放进 ranges:
|
||||
|
||||
| 允许范围 | 原因 |
|
||||
|---------|------|
|
||||
| 标签所在行 | 修法 1:改描述 |
|
||||
| `()` 所在行 | 修法 2:改实现 |
|
||||
|
||||
护栏不变:**越界改动一律拒绝(abstain)**——这正是 `src/repair.rs` 已经强制的语义。
|
||||
|
||||
### 4.4 知识层:`stale` 概念已经存在
|
||||
|
||||
`src/knowledge/lifecycle.rs` 已有 `find_stale` / `stale_json` / `verify`。
|
||||
标签过期可以走**同一条 stale 通道**,进入 EKC/OKF 的
|
||||
`marqdo verify` / `marqdo stale` 报告,成为知识库的健康指标。
|
||||
|
||||
> 这一点很重要:**标签过期 = 知识腐烂**,而 Marqdo 已经有"知识会腐烂"的机制,
|
||||
> 标签只是给它增加了一种新的腐烂类型(文档断言 vs 实现)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 诊断 schema 草案
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "label.stale",
|
||||
"severity": "warning",
|
||||
"message": "标签可能过期:标签提到 `税率`,但当前语句已不再引用它",
|
||||
"span": { "file": "报价.mq.md", "line": 42, "col": 12 },
|
||||
"doc_anchor": { "file": "报价.mq.md", "line": 42, "quote": "按 `税率` 计算总价" },
|
||||
"doc_quote": "按 `税率` 计算总价",
|
||||
"label_ref": {
|
||||
"kind": "label",
|
||||
"text": "按 `税率` 计算总价",
|
||||
"refs": ["税率"],
|
||||
"missing_refs": ["税率"],
|
||||
"code_past": "at(税率表, 档位) * 金额",
|
||||
"code_now": "at(税率表, 档位) / 金额",
|
||||
"fingerprint_past": "9f2a…",
|
||||
"fingerprint_now": "3c71…",
|
||||
"layer": "L2"
|
||||
},
|
||||
"suggestion": "若意图是乘,请还原 `*`;若意图改为除,请把标签改成「按档位折算比例」",
|
||||
"ranges": [[42, 42]]
|
||||
}
|
||||
```
|
||||
|
||||
要点:
|
||||
- 复用 `doc_anchor` / `doc_quote`,**不新造字段名**
|
||||
- `label_ref` 仿 `contract_ref`(`kind: "label"`)
|
||||
- `code_past` / `code_now` 并置 → 模型一眼看出差异
|
||||
- `layer` 标明是 L1 还是 L2 检出(便于分级治理)
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作流
|
||||
|
||||
```
|
||||
作者 / agent 改代码
|
||||
↓
|
||||
marqdo check 或 MLSP validate
|
||||
↓
|
||||
label.stale / label.missing 诊断(带 doc_quote + code_past + code_now)
|
||||
↓
|
||||
MLSP repair_targets(ranges = 标签行 ∪ 代码行)
|
||||
↓
|
||||
LLM 三选一:改标签 / 改代码 / 确认无害
|
||||
↓
|
||||
repair_apply(越界必拒)
|
||||
↓
|
||||
复验 → 通过后写回 .marqdo/labels.json(confirmed_fingerprint 更新)
|
||||
```
|
||||
|
||||
**CI 用法**:
|
||||
- 普通项目:`label.stale` 默认 **warning**(不阻塞)
|
||||
- 知识库项目(OKF/EKC 仓):可配置为 **error**,把"断言必须新鲜"作为门禁
|
||||
|
||||
---
|
||||
|
||||
## 7. 反幻觉:这一步到底解决了什么
|
||||
|
||||
必须把话说准,否则容易过度承诺。
|
||||
|
||||
### 7.1 它解决的**具体一类**
|
||||
|
||||
> **文档断言与实现不一致**(doc–code drift at the claim level)。
|
||||
|
||||
传统文档的失败模式:
|
||||
|
||||
| 失败模式 | 传统文档 | Marqdo(本设计) |
|
||||
|---------|---------|-----------------|
|
||||
| 注释过期 | 无声腐烂 | L1/L2 检出 |
|
||||
| 签名漂移 | 靠类型检查(有) | 契约已有 |
|
||||
| **散文描述与实现不符** | **完全无解** | **本设计**(新能力) |
|
||||
| 知识库引用失效 | 靠人工审阅 | 可机械化 |
|
||||
|
||||
### 7.2 它**不解决**什么
|
||||
|
||||
- 模型凭空编造(幻觉的另一种)
|
||||
- 代码本身写错
|
||||
- 标签写得含糊但"不算错"(L1 查不到,L2 只能报"变了")
|
||||
|
||||
**所以正确的表述是**:
|
||||
> 它把"**文档可信度**"从"靠人自觉"提升到"**可被机械复核 + 可被 LLM 裁决**"。
|
||||
|
||||
### 7.3 为什么这对"可执行知识体系"是决定性的
|
||||
|
||||
一个知识库的价值 = **断言的密度 × 断言的可信度**。
|
||||
传统知识库只能提高密度(多写),无法保证可信度(写完就腐)。
|
||||
Marqdo 若能把"断言→复核"闭环,就第一次让**知识库有了保鲜机制**——
|
||||
这也正好接上 EKC 已有的 `stale` / `verify` 体系。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与反对意见(诚实清单)
|
||||
|
||||
### 8.1 误报疲劳(最危险)
|
||||
|
||||
如果 `label.stale` 天天响,用户会在三天内学会忽略它。
|
||||
**对策**:
|
||||
- L1 **只在能证明冲突时报**(引用了不存在的实体 / 引用的实体不在语句里)
|
||||
- L2 **默认只报 warning**,且同一标签同一指纹只报一次(台账记录"已复核")
|
||||
- 诊断里必须给**可执行建议**(改哪一行、改成什么),否则就是噪音
|
||||
|
||||
### 8.2 台账的腐烂与合并冲突
|
||||
|
||||
`.marqdo/labels.json` 是缓存,不是真相。对策:
|
||||
- 语义上**可丢弃**:删掉后重建,最多一次全量确认
|
||||
- 合并冲突策略:**重算优先**(以代码指纹为准,冲突时保留 `confirmed_at` 较新者)
|
||||
- 不放进版本库时(`.gitignore`),退化为"本地提示";放进版本库时,成为团队级门禁
|
||||
|
||||
### 8.3 语义鸿沟
|
||||
|
||||
L1 只能查引用;标签写"算总价"而代码改成了"算单价",若两者都引用 `税率`,L1 沉默。
|
||||
**这是 L2 存在的理由**,也是必须承认的能力边界。
|
||||
|
||||
### 8.4 LLM 修标签可能引入新幻觉
|
||||
|
||||
"用幻觉修幻觉"是真风险。对策:
|
||||
- 护栏:**只允许改标签行或代码行**(`repair_apply` 已强制)
|
||||
- 修改必须**双向可逆**:诊断里给出"过去/现在"两侧,让模型做**判定**而不是**创作**
|
||||
- 知识库仓建议:L2 级修改需人工确认(`--confirm`)
|
||||
|
||||
### 8.5 标签不得参与安全判定
|
||||
|
||||
这是我在上一份文档里提的、也是你关心的"agent 误导"的另一面:
|
||||
**如果沙箱/权限判定读标签,那标签就成了攻击面。**
|
||||
硬约束:**策略、沙箱、工具白名单只读 `()` 的语义,永不读 `[]`。**
|
||||
标签只服务于"人读"与"AI 复核",不服务于"机器授权"。
|
||||
|
||||
### 8.6 成本
|
||||
|
||||
每标签一次指纹计算与比对。可增量:只对**本次变更的文件**做 L2 校验
|
||||
(与 EKC 的增量编译一致)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 分阶段落地
|
||||
|
||||
| 阶段 | 内容 | 依赖 | 风险 |
|
||||
|------|------|------|------|
|
||||
| **P0** | 纯度语法:`[标签](表达式)` + `label.missing` + 普通取元(A 或 C) | 解析器 | 中(506 处迁移) |
|
||||
| **P1** | L1 引用一致性 + `label.stale` 诊断(无状态) | 诊断字段已有 | 低 |
|
||||
| **P2** | 诊断 schema + MLSP ranges 并集 + 修复回路 | `mlsp.rs` / `repair.rs` | 低 |
|
||||
| **P3** | L2 指纹台账 + 增量校验 | `fingerprint.rs` | 中 |
|
||||
| **P4** | L3 LLM 复核 + `confirmed` 写回 + CI 门禁 | P2+P3 | 中 |
|
||||
|
||||
**建议先做 P1**:它零状态、确定性、能立刻抓住"引用了不存在的东西"这类最硬的腐烂,
|
||||
且不依赖纯度迁移——可以在旧语法上先验证"标签断言"这个概念是否好用。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **普通取元选 A(`at value=… index=…`,零新语法)还是 C(`at(篮子, 1)`,需逗号参数)?**
|
||||
2. **L1 的断言规则**:只认标签内的反引号 `` `名` ``,还是也认"与代码标识符同名"的中文词?
|
||||
(只认反引号更准;认中文词更聪明但假阳性高)
|
||||
3. **台账位置**:`.marqdo/labels.json`(默认忽略)还是纳入版本库(团队门禁)?
|
||||
4. **`label.stale` 默认级别**:warning(推荐)还是 error?
|
||||
5. **是否先只做 P1**(在旧语法上验证"标签断言"概念),再决定纯度迁移?
|
||||
|
||||
> 我的建议顺序:**P1 → P2 → P0 → P3 → P4**。
|
||||
> 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度),
|
||||
> 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。
|
||||
@@ -0,0 +1,218 @@
|
||||
# 方案评估:Markdown 链接式调用 `[函数名](参数…)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 已被 [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) 取代** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「markdown 的链接语义似乎很适合做这种操作」 |
|
||||
| 相邻 | [spaced-function-names-d8.md](spaced-function-names-d8.md)(方括号调用 + 空格) |
|
||||
| 影响面 | **核心解析**:`[key](coll)` 链接索引与调用语法冲突 |
|
||||
|
||||
> **后续更正**:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。
|
||||
> 用户问的是**调用写法**本身。最新评估(含原型实测 554/0 回归)见
|
||||
> [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md):
|
||||
> 方括号确实不可行(2 个真实冲突文件),但**去掉方括号的 `f(args)` 是空闲语法且可行**。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**语法本身很优雅,但它与既有特性「链接索引 `[key](map)`」正面冲突。**
|
||||
冲突不是「难实现」,而是「同一个写法要表示两种语义」。
|
||||
建议**不要**把它做成调用的主形式;若要引入,只能作为**受限变体**(见 §4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状事实(实测)
|
||||
|
||||
### 1.1 `[…](…)` 目前是链接索引
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"a":1}**
|
||||
**v = [a](m)** # 取 map 的 a 成员
|
||||
> print text=`v` # → 1
|
||||
```
|
||||
|
||||
这是 v0.3 的**正式特性**,文档里写作「集合取元优先 `[键](集合)`」。
|
||||
实现有专门入口 `parse_link_index`,并由 `link_index_shape_ahead` 判定:
|
||||
|
||||
> `[` … `]` 后面紧跟 `(` → **链接索引**
|
||||
|
||||
### 1.2 提议的写法今天会怎样
|
||||
|
||||
```markdown
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
*"hi " + `who`*
|
||||
|
||||
# main
|
||||
|
||||
**r = [greet](alice)**
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
error: l2.mq.md:12:1: undefined variable `alice`
|
||||
```
|
||||
|
||||
因为它被当作链接索引 `[greet](alice)`:拿 `alice` **当变量名**去查,
|
||||
查不到就报错。也就是说**链接索引已经把这块语法占满了**。
|
||||
|
||||
### 1.3 歧义判定只有一行
|
||||
|
||||
```rust
|
||||
fn link_index_shape_ahead(s: &str) -> bool {
|
||||
// '[' … ']' 后紧跟 '(' → 链接索引
|
||||
}
|
||||
```
|
||||
|
||||
任何 `[X](Y)` 都会走链接索引,没有例外。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么这个提议有吸引力
|
||||
|
||||
先说我认可的部分,避免低估它:
|
||||
|
||||
1. **视觉语义准确**。Markdown 里 `[文本](目标)` 的直觉是「链接一个东西到另一个」。
|
||||
调用 `[greet](alice)` 读作「调用 greet,指向 alice」,对非程序员也直观。
|
||||
2. **参数在括号里,边界清晰**。相比 `> greet alice`(空格切词),
|
||||
`(alice bob)` 的边界是**显式**的 —— 这恰好是 D8「带空格函数名」痛点的天然解药。
|
||||
3. **与 Markdown 完全兼容**。`[a](b)` 是合法链接写法,编辑器不会标红。
|
||||
|
||||
**但**:这些优点必须在「不破坏链接索引」的前提下才能兑现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 冲突分析
|
||||
|
||||
### 3.1 根本矛盾
|
||||
|
||||
| 写法 | 链接索引语义 | 调用语义 | 能否并存 |
|
||||
|------|-------------|---------|---------|
|
||||
| `[a](m)` | 取 `m` 的成员 `a` | 用参数 `m` 调用 `a` | **看内容才知道** |
|
||||
| `[greet](alice)` | 取 `alice` 的成员 `greet` | 用 `alice` 调用 `greet` | 同上 |
|
||||
|
||||
**两者形状完全一致**,区别只在「`greet` 是函数还是键名」「`alice` 是集合还是实参」——
|
||||
这需要**符号表信息**,而语法判定发生在解析期(此时未必知道有哪些函数)。
|
||||
|
||||
### 3.2 用「函数表已知」来消歧能行吗
|
||||
|
||||
理论上:若 `greet` 是已定义函数 → 调用;否则 → 链接索引。
|
||||
|
||||
**问题**:
|
||||
1. **跨模块不可知**:`[lib.greet](x)` 需要 import 结果,词法/语法期拿不到。
|
||||
2. **名字冲突**:如果既有 `greet` 函数,又有 map 里叫 `greet` 的键,语义就靠猜。
|
||||
3. **错误信息会变差**:本意是链接索引但键不存在时,会被误判成调用,
|
||||
报 `unknown function` 而不是 `missing map key` —— 把清晰错误变成误导错误。
|
||||
4. **修改即破坏**:今天所有 `[键](集合)` 写法都要进符号表做一次判定,
|
||||
这是**全量语义变更**,不是增量特性。
|
||||
|
||||
### 3.3 冲突的严重度
|
||||
|
||||
链接索引是 v0.3 **明确推广**的写法(「集合取元优先 `[键](集合)`」),
|
||||
仓库里大量使用。让调用去抢这块语法,等于**用新特性侵蚀既有特性**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 可选的受限方案
|
||||
|
||||
### 方案 L1 — 参数列表必须「非单个标识符」(不可靠,不推荐)
|
||||
|
||||
仅在 `(…)` 内含**分隔符**时判为调用,如 `[greet](alice, bob)`。
|
||||
|
||||
- 优点:`[a](m)` 单参数时保留链接索引语义
|
||||
- **致命缺陷**:`[greet](alice)` 这种最常见的单参数调用无法表达;
|
||||
而 `[greet](a, b)` 又和「链接索引 + 逗号」冲突。**语义随参数个数漂移**,最坏的一类设计。
|
||||
|
||||
### 方案 L2 — 独立标记前缀(可行,但失去「链接感」)
|
||||
|
||||
```markdown
|
||||
> [call]greet(alice) # 或 @greet(alice)
|
||||
```
|
||||
|
||||
- 优点:零歧义
|
||||
- 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力
|
||||
|
||||
### 方案 L3 — 方括号调用 + 括号参数(**推荐**)
|
||||
|
||||
保留既有的方括号调用形式,但允许**参数写在括号里**:
|
||||
|
||||
```markdown
|
||||
> [加一 号](n=1) # 具名参数
|
||||
> [加一 号](1) # 位置参数
|
||||
> [greet](alice bob) # 多参数
|
||||
```
|
||||
|
||||
关键:**`]` 后面跟 `(` 时仍优先判为链接索引**——
|
||||
除非方括号内是「已知的函数名形状」且**调用上下文**成立。
|
||||
|
||||
等等,这与 §3 的矛盾相同。**所以 L3 的真正形态是**:
|
||||
|
||||
```markdown
|
||||
> [加一 号] (n=1) # 方括号与括号之间有空格 → 调用+参数组,不是链接
|
||||
```
|
||||
|
||||
用「`]` 与 `(` 之间是否有空格」消歧:
|
||||
- `[key](coll)`(紧贴)→ 链接索引(**既有语义完全不变**)
|
||||
- `[callee] (args)`(有空格)→ 调用,参数为一组
|
||||
|
||||
- 优点:**零歧义**、**零回归**(紧贴形式完全不动)、保留了「括号包参数」的可读性、
|
||||
顺带解决 D8 的空格函数名
|
||||
- 缺点:视觉上 `] (` 有个空格,略不自然;但 Markdown 渲染不受影响
|
||||
|
||||
### 方案 L4 — 不在语法层做,在文档层说明(保守)
|
||||
|
||||
明确「链接索引是取元,不是调用」,调用一律用 `> callee args` 或 `> [callee] args`。
|
||||
`[函数名](参数)` 留作**不做**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 方案对比
|
||||
|
||||
| 方案 | 歧义 | 回归风险 | 保留「链接感」 | 解决 D8 | 推荐 |
|
||||
|------|------|---------|--------------|---------|------|
|
||||
| L1 参数需含分隔符 | **高**(随参数个数漂移) | 中 | 部分 | 否 | ❌ |
|
||||
| L2 独立前缀 | 无 | 无 | **否** | 是 | 备选 |
|
||||
| **L3 空格消歧** | **无** | **无** | 大部分 | **是** | ✅ |
|
||||
| L4 不做 | 无 | 无 | 否 | 否 | 退路 |
|
||||
| 直接抢 `[x](y)` | **不可解** | **高** | 是 | 是 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 6. 我的建议
|
||||
|
||||
1. **不要**把 `[函数名](参数)` 直接定为调用——它和链接索引形状相同,无法可靠消歧。
|
||||
2. 采纳 **L3**:`[callee] (args)`(中间有空格)作为「带括号参数组的调用」,
|
||||
紧贴的 `[key](coll)` 语义**一字不动**。
|
||||
3. 这样同时满足:
|
||||
- 「完全兼容 Markdown」(`[x](y)` 仍是链接语义)
|
||||
- 参数边界显式(括号括起来)
|
||||
- D8 的空格函数名(方括号内允许空格)
|
||||
4. 若你觉得 `] (` 的空格不好看,退一步选 **L2**(`> callee(args)` 这种函数式写法),
|
||||
牺牲链接感换取零歧义。
|
||||
|
||||
---
|
||||
|
||||
## 7. 若采纳 L3 的验证计划
|
||||
|
||||
| 编号 | 用例 | 期望 |
|
||||
|------|------|------|
|
||||
| L3-1 | `[a](m)` 紧贴 | 链接索引,取成员(**不变**) |
|
||||
| L3-2 | `[greet] (alice)` 有空格 | 调用,`alice` 作为位置参数 |
|
||||
| L3-3 | `[加一 号] (n=1)` | 调用带空格名函数,返回 2 |
|
||||
| L3-4 | `[greet] (a b)` | 两个位置参数 |
|
||||
| L3-5 | `[a](m)` 中 `a` 恰好也是函数名 | **仍走链接索引**(紧贴优先) |
|
||||
| L3-6 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不受影响 |
|
||||
| L3-7 | 全量 `cargo test` | 554 全绿 |
|
||||
| L3-8 | 全仓库 `.mq.md` 回归 | 无变化(紧贴形式未动) |
|
||||
|
||||
---
|
||||
|
||||
## 8. 待你决策
|
||||
|
||||
1. **选 L3、L2、还是 L4?**
|
||||
2. 若选 L3:`] (` 的空格你能接受吗?(渲染上无差别,源码里能看见)
|
||||
3. 是否同时支持全角 `【函数名】(参数)`?与 D2 全角冒号问题一致考虑。
|
||||
@@ -1,14 +1,14 @@
|
||||
# 文档会话(Document Session)
|
||||
# 文档会话(View Cells)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / notebook 交互) |
|
||||
| 层 | Runtime + Document(view 服务端 / 交互单元) |
|
||||
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无(读取既有 AST 与表格) |
|
||||
|
||||
> 文档会话是 view 背后的“notebook 运行时”:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。
|
||||
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,11 +23,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 1.1 实施状态(2026-10-17)
|
||||
## 1.1 实施状态(2026-10-18)
|
||||
|
||||
| 能力 | 状态 | 位置 |
|
||||
|---|---|---|
|
||||
| `内核表` / `会话表` 解析(中英列名) | ✅ | `src/notebook/mod.rs` |
|
||||
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
|
||||
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
|
||||
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
|
||||
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
|
||||
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
|
||||
@@ -39,8 +40,8 @@
|
||||
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
|
||||
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
|
||||
| cell step | ✅ | 同上 |
|
||||
| Marqdo statement step | ✅(notebook 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/notebook/mod.rs` |
|
||||
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
|
||||
| writeback 集成 | 待做 | `writeback` |
|
||||
| replay / 持久化 | 待做 | — |
|
||||
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
|
||||
@@ -50,18 +51,18 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 两种执行模式
|
||||
## 2. 两个执行面(不是两个 CLI 模式)
|
||||
|
||||
### 2.1 Program mode(规范)
|
||||
### 2.1 Program execution(规范)
|
||||
|
||||
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
|
||||
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
|
||||
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
|
||||
- 结果:可复现;是文档的“真理”。
|
||||
|
||||
### 2.2 Notebook mode(交互)
|
||||
### 2.2 View cells(交互)
|
||||
|
||||
- 入口:`marqdo view doc.mq.md` → Session 面板。
|
||||
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
|
||||
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
|
||||
- 状态:内核持久;可切换、重启、单步。
|
||||
- 结果:默认临时显示;可显式 writeback。
|
||||
@@ -72,7 +73,7 @@
|
||||
```text
|
||||
.mq.md
|
||||
/ \
|
||||
Program mode Notebook mode
|
||||
Program run View cells
|
||||
(canonical) (interactive)
|
||||
\ /
|
||||
Document Session
|
||||
@@ -83,8 +84,8 @@
|
||||
```
|
||||
|
||||
- 共享 cell index 与 kernel registry。
|
||||
- Program mode 可以不使用 notebook 表;Notebook mode 可以使用。
|
||||
- 冲突时以 Program mode 为准;Notebook mode 不改变文档语义。
|
||||
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
|
||||
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
|
||||
|
||||
---
|
||||
|
||||
@@ -107,7 +108,7 @@ DocumentSession
|
||||
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
|
||||
├── journal: Vec<ExecutionRecord>
|
||||
├── created_ms / last_active_ms
|
||||
└── mode: program | notebook
|
||||
└── surface: program | view
|
||||
```
|
||||
|
||||
### 3.1 Cell
|
||||
@@ -130,7 +131,7 @@ DocumentSession
|
||||
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
|
||||
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
|
||||
3. 记录 name、lang、source、span、source hash。
|
||||
4. 读取 `内核表` / `会话表` 绑定(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
|
||||
6. 生成执行顺序:
|
||||
- 有会话表 → 行顺序;
|
||||
@@ -233,7 +234,7 @@ resolve cell -> resolve kernel
|
||||
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
|
||||
| **Foreign line step** | 不做;未来 DAP |
|
||||
|
||||
- Cell step 是 Notebook mode 的主单步。
|
||||
- Cell step 是 view cells 的主单步。
|
||||
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
|
||||
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
|
||||
|
||||
@@ -333,7 +334,7 @@ resolve cell -> resolve kernel
|
||||
|
||||
### 7.1 默认
|
||||
|
||||
- Notebook mode 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- View cells 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
|
||||
- 不写 execution_count 到文档。
|
||||
|
||||
@@ -463,7 +464,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
### 12.1 服务端
|
||||
|
||||
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
|
||||
- 表解析:内核表/会话表/自动模式/重复/未知/语言不匹配。
|
||||
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
|
||||
- 会话:open/close/reload;kernel 启动/重启/中断。
|
||||
- cell run:状态机 never→running→clean/error;dirty/stale。
|
||||
- step:cell step 顺序;statement step 与 debug 联动。
|
||||
@@ -474,7 +475,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
|
||||
### 12.2 金样例
|
||||
|
||||
- `tests/notebook/kernels.mq.md`:内核表/会话表。
|
||||
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
|
||||
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
|
||||
- `tests/notebook/step.mq.md`:cell step 顺序。
|
||||
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
|
||||
@@ -495,7 +496,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
| 源 | `.ipynb` | `.mq.md` |
|
||||
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
|
||||
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
|
||||
| 多语言 | 一 notebook 一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 单步 | cell | cell + statement |
|
||||
| 复现 | 手动 | Restart & Run All + journal + replay |
|
||||
| Git | 输出/计数噪声 | 源码干净;输出显式 |
|
||||
@@ -509,7 +510,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
| 阶段 | 内容 |
|
||||
|---|---|
|
||||
| D0 | 设计/语法/决策文档(本文件) |
|
||||
| D1 | `src/notebook/`:cell index、表解析、session 结构、诊断 |
|
||||
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
|
||||
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
|
||||
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
|
||||
| D4 | statement step 接入;dirty/stale;writeback |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 文档原生 Notebook 语法
|
||||
# 文档原生 view cells 语法
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -110,7 +110,7 @@ Marqdo 的选择:
|
||||
````markdown
|
||||
# main
|
||||
|
||||
这份文档演示一个最小 notebook:两个 Python 单元共享 `分析` 内核,
|
||||
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
|
||||
一个绘图单元在隔离的 `绘图` 内核里运行。
|
||||
|
||||
`内核表` =
|
||||
@@ -211,7 +211,7 @@ print(x + 1)
|
||||
|
||||
## 5. 可读性规则(语法评审标准)
|
||||
|
||||
新增/修改任何 notebook 语法,必须满足:
|
||||
新增/修改任何 cell 表约定,必须满足:
|
||||
|
||||
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
|
||||
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
|
||||
@@ -231,7 +231,7 @@ print(x + 1)
|
||||
| 情况 | 诊断(中文示例) | 修复建议 |
|
||||
|---|---|---|
|
||||
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
|
||||
| 会话引用未知内核 | `会话表: 单元「汇总」引用了未声明的内核「分析」` | 在 `内核表` 声明,或改用语言 id |
|
||||
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
|
||||
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
|
||||
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
|
||||
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
|
||||
@@ -243,15 +243,15 @@ print(x + 1)
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 Program mode 的关系
|
||||
## 7. 与 program execution 的关系
|
||||
|
||||
- `内核表` / `会话表` 是**声明**,不是执行指令。
|
||||
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
|
||||
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
|
||||
- Program mode 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);表只服务 view 的 notebook 会话与一键 Run All。
|
||||
- 两种模式可以并存:
|
||||
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
|
||||
- 两者可以并存:
|
||||
- 文档用表描述“交互时怎么跑”;
|
||||
- `# main` 用显式调用描述“CI 时怎么跑”。
|
||||
- 如果两者冲突,以 Program mode 的程序语义为准;Notebook mode 的表只影响 view。
|
||||
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
|
||||
|
||||
这样避免把“执行计划”变成第二套程序语义。
|
||||
|
||||
@@ -295,7 +295,7 @@ v2 **不**为状态交换新增表格/注释。原因:
|
||||
|
||||
| 逻辑 | 位置 |
|
||||
|---|---|
|
||||
| 识别 `内核表` / `会话表` 绑定 | `src/notebook/syntax.rs`(新) |
|
||||
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
|
||||
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
|
||||
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
|
||||
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
|
||||
|
||||
@@ -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 的标签保鲜都成立,
|
||||
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
|
||||
@@ -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 条警告。
|
||||
@@ -54,8 +54,8 @@
|
||||
### 结论 C:Hybrid 执行模型
|
||||
|
||||
- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。
|
||||
- **Notebook mode(交互模式)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;Notebook mode 是 Program mode 的**交互镜头**,不是替代品。
|
||||
- **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。
|
||||
|
||||
理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。
|
||||
|
||||
@@ -99,7 +99,7 @@
|
||||
|
||||
### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md`
|
||||
|
||||
- Notebook mode 的输出默认只在 view 中显示,不修改文档。
|
||||
- View cells 的输出默认只在 view 中显示,不修改文档。
|
||||
- 需要持久化时显式 writeback(沿用 `<!-- marqdo-out … -->`),可 Git 跟踪、可忽略。
|
||||
- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。
|
||||
- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。
|
||||
|
||||
@@ -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` |
|
||||
@@ -0,0 +1,416 @@
|
||||
# Marqdo 常见陷阱手册
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 使用向**(全部条目在 `marqdo 1.5.2` 上实测) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | qdagent 重构期间(文档门禁 + 输出契约)逐条踩坑复现 |
|
||||
| 关联 | [02-基本语法.md](02-基本语法.md) · [06-函数.md](06-函数.md) · [11-模块与导入.md](11-模块与导入.md) · [design/markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
|
||||
| 缺陷来源 | [research/qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 怎么用这份文档
|
||||
|
||||
不是语言教程,而是**避坑清单**。每条都给出:
|
||||
|
||||
- **现象**:你会看到什么(报错原文)
|
||||
- **原因**:为什么这样
|
||||
- **改法**:可直接抄的写法
|
||||
|
||||
全部结论来自实测,不是推测。文中「✅ 安全」表示实测通过,不要靠猜。
|
||||
|
||||
---
|
||||
|
||||
## 1. 写文档(最常见的一类)
|
||||
|
||||
Marqdo 是「文档即程序」,所以**文档写得像正常中文**恰恰是最容易出错的地方。
|
||||
门禁类工具(如 qdagent 的 `execution/docgate`)主要就是在防这些。
|
||||
|
||||
### 1.1 行首数字 → 一定报错 ⚠️ 最高频
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: a.mq.md:7:1: unrecognized statement: 2026 年发布。
|
||||
error: b.mq.md:7:1: unrecognized statement: 42
|
||||
error: c.mq.md:7:1: unrecognized statement: 9 号是数字。
|
||||
```
|
||||
|
||||
**原因**
|
||||
|
||||
行首是数字时,该行被当成**语句**去解析(数字是字面量表达式),而非叙述。
|
||||
|
||||
**改法**
|
||||
|
||||
以文字开头即可。中文里「2026 年」「42 个」「3 个要点」「1. 第一步」这类写法极常见,
|
||||
凡是整行以数字起头都会被拦:
|
||||
|
||||
```markdown
|
||||
# 结论
|
||||
|
||||
发布年份是 2026 年。 ← 把数字后移
|
||||
共收录 42 条。 ← 不要以 42 起行
|
||||
有三个要点需要说明。 ← 不要写 "3 个要点…" 起行
|
||||
```
|
||||
|
||||
确需保留行首数字时,包进行内代码或围栏:
|
||||
|
||||
```markdown
|
||||
`2026` 是发布年份。
|
||||
|
||||
````markdown
|
||||
42
|
||||
````
|
||||
|
||||
### 1.2 行首 `+` → 报错
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: tmm.mq.md:7:1: unrecognized statement: + 加号
|
||||
```
|
||||
|
||||
**原因**:`+` 是形参声明与列表语法的前导符。
|
||||
|
||||
**改法**:叙述区不要用 `+ ` 起行做列表;需要列表用 `- `(见下条)。
|
||||
|
||||
### 1.3 `-` / `>` / `|` / `[` 起行:**多数情况安全**
|
||||
|
||||
这一条要纠正一个常见误解。实测:
|
||||
|
||||
| 行首 | 叙述区 | 说明 |
|
||||
|------|--------|------|
|
||||
| `- 列表项` | ✅ 安全 | 不构成有效 foreach → 跳过 |
|
||||
| `> 引用` | ✅ 安全 | 无对应函数时不当调用 |
|
||||
| `\| a \| b \|` | ✅ 安全 | 未绑定表不算语句 |
|
||||
| `[{"a":1}]` | ✅ 安全 | 无归属的链接索引 → 跳过 |
|
||||
| `9 号是数字。` | ❌ 报错 | 数字字面量是真语句 |
|
||||
| `+ 加号` | ❌ 报错 | 前导符是真语法 |
|
||||
|
||||
但**在函数体内且上下文成立时**它们会真的执行(例如 `- [`x`](`xs`)` 是真循环)。
|
||||
判断标准:**能不能被解析成一条完整语句**。能,就执行;不能,就当叙述跳过。
|
||||
|
||||
### 1.4 未闭合引号 → 静默吞行 ⚠️ 危险
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**s = "abc
|
||||
> print text=hi
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `hi`,**没有报错**,`s` 那一行凭空消失。
|
||||
|
||||
**原因**:未闭合的双引号让该行被当作叙述而不是语句。
|
||||
|
||||
**影响**:这类错误不会中断程序,只会让变量「不存在」,随后在别处报
|
||||
`undefined variable`,把排查方向引偏。
|
||||
|
||||
**改法**:写完立即 `marqdo check`,或注意「变量莫名未定义」时先看引号是否配对。
|
||||
|
||||
---
|
||||
|
||||
## 2. 变量作用域
|
||||
|
||||
### 2.1 模块级变量在函数之间**不可见**
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show
|
||||
*""
|
||||
|
||||
## show
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
```
|
||||
|
||||
```
|
||||
error: t1.mq.md:13:1: undefined variable `g`
|
||||
```
|
||||
|
||||
兄弟函数之间同样不可见:
|
||||
|
||||
```markdown
|
||||
## a
|
||||
|
||||
**x = 1**
|
||||
> b
|
||||
*None*
|
||||
|
||||
## b
|
||||
|
||||
> print text=`x` ← undefined variable `x`
|
||||
*None*
|
||||
```
|
||||
|
||||
**原因**:每个 `##` 是独立作用域;`# main` 与各函数之间**不共享变量**,只共享参数与返回值。
|
||||
|
||||
**改法**:一切跨函数数据走**参数与返回值**。
|
||||
|
||||
```markdown
|
||||
## show
|
||||
+ `g`
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show g=`g`
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.2 顶层不许有裸语句
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: e.mq.md: 5:1: expected heading (`#` object or `##` function), got: **x = 1**
|
||||
```
|
||||
|
||||
**原因**:文件顶层只能是 frontmatter、叙述、`#` 对象、`##` 函数。
|
||||
语句必须放进 `# main` 或某个 `##` 里。
|
||||
|
||||
**改法**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: e
|
||||
---
|
||||
|
||||
**x = 1** ← 挪走
|
||||
|
||||
# main
|
||||
|
||||
**x = 1**
|
||||
> print text=ok
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.3 `table.put` **不**原地修改
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"n":0}**
|
||||
**r = > table.put in=`m` at="n" value=1**
|
||||
```
|
||||
|
||||
之后 `m` 仍是 `{"n":0}`,`r` 才是 `{"n":1}`。
|
||||
|
||||
**影响**:想靠 `> table.put in=`state` ...` 累积状态**不会生效**,
|
||||
计数永远是 0,且不报错。
|
||||
|
||||
**改法**:接住返回值。
|
||||
|
||||
```markdown
|
||||
**state = > table.put in=`state` at="ok_n" value=`n2`**
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 函数
|
||||
|
||||
### 3.1 函数名含空格 → 定义成功,**调用必崩** ⚠️ 缺陷
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 加一 号 n=1**
|
||||
```
|
||||
|
||||
```
|
||||
error: t8.mq.md:13:1: undefined variable `号`
|
||||
```
|
||||
|
||||
英文同样:
|
||||
|
||||
```markdown
|
||||
## my func
|
||||
```
|
||||
调用 → `undefined variable func`。
|
||||
|
||||
**原因**:调用处按空格切分,第一个词当函数名,其余词当位置参数或变量插值。
|
||||
定义侧允许空格,**两侧不对称**。
|
||||
|
||||
**改法**:函数名**不要含空格**。用连字符、下划线或去掉空格:
|
||||
|
||||
```markdown
|
||||
## 加一_号
|
||||
## assert-no-main
|
||||
## my_func
|
||||
```
|
||||
|
||||
命名建议:中文标识符直接连写(`断言干净`、`门禁沉淀`),英文用下划线。
|
||||
|
||||
### 3.2 函数内变量名别和叙述里的裸词撞车
|
||||
|
||||
叙述里的裸词一般是安全的(实测 `大约 head 的位置。` 不报错)。
|
||||
但**在函数名或调用参数位置**出现未定义标识符会立刻报 `undefined variable`。
|
||||
判断标准同上:会被当成语句/表达式的上下文才插值。
|
||||
|
||||
---
|
||||
|
||||
## 4. 字符串与拼接
|
||||
|
||||
### 4.1 引号内 `**`、`|`、`#` 多数安全,不必恐慌
|
||||
|
||||
实测以下全部 ✅:
|
||||
|
||||
```markdown
|
||||
**s = "a ** b"**
|
||||
**s = "a | col | b"**
|
||||
**s = "abc # main def"**
|
||||
**s = "sum: total items"**
|
||||
```
|
||||
|
||||
只有**引号不配对**才会出问题(回到 §1.4)。
|
||||
|
||||
### 4.2 拼装文档正文时,`"`、`*`、`|` 仍建议转义
|
||||
|
||||
当你用字符串拼接**生成一份 `.mq.md`**(而不是自己写)时,字面量容易提前闭合标记。
|
||||
稳妥写法是用 Unicode 转义:
|
||||
|
||||
```markdown
|
||||
**qt = "\u{22}"**
|
||||
**star = "\u{2a}"**
|
||||
**pipe = "\u{7c}"**
|
||||
**nl = "\n"**
|
||||
|
||||
**doc = "---" + `nl` + "title: x" + `nl` + "---" + `nl` + `nl` + "# main" + `nl` + `nl`**
|
||||
**doc = `doc` + "> print text=" + `qt` + "hi" + `qt` + `nl` + `star` + "None" + `star` + `nl`**
|
||||
```
|
||||
|
||||
### 4.3 heredoc 写含 `\n` 的 `.mq.md` 会自毁
|
||||
|
||||
用 `cat <<'EOF'` 写文件时,若内容本身包含反斜杠转义序列,shell 虽不展开,
|
||||
但若中间出现 `EOF` 相邻的变体或内容被后续 `sed`/脚本改写,极易截断。
|
||||
**建议**:生成 .mq.md 用脚本(Python/Node)或编辑器,别用长 heredoc。
|
||||
|
||||
---
|
||||
|
||||
## 5. 导入
|
||||
|
||||
### 5.1 相对路径以**当前文件**为基准
|
||||
|
||||
`execution/a.mq.md` 里导入同目录的 `b.mq.md`,写 `import b:b.mq.md`。
|
||||
写 `import b:execution/b.mq.md` 或 `../execution/b.mq.md` 都可能失败:
|
||||
|
||||
```
|
||||
error: cannot resolve import `../execution/docgate.mq.md` from
|
||||
```
|
||||
|
||||
**跨目录**才用 `..`:
|
||||
|
||||
```markdown
|
||||
import ctx:../knowledge/context.mq.md
|
||||
```
|
||||
|
||||
### 5.2 库名必须导入,不能用裸名
|
||||
|
||||
```
|
||||
error: unknown library `json` (import it in frontmatter)
|
||||
```
|
||||
|
||||
```markdown
|
||||
import json:lib/json.mq.md
|
||||
```
|
||||
|
||||
标准库函数要**带库名前缀**:`json.parse`、`txt.contains`、`table.put`。
|
||||
裸 `str_split`、`contains` 会报 `unknown function`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见函数签名(易记错)
|
||||
|
||||
| 函数 | 参数名 | 备注 |
|
||||
|------|--------|------|
|
||||
| `txt.contains` | `text`, `sub` | 是 `sub` 不是 `part` |
|
||||
| `table.put` | `in`, `at`, `value` | 返回新表,见 §2.3 |
|
||||
| `table.get` | `map`, `key` | 取可选键,键缺失不崩 |
|
||||
| `json.get` | `value`, `key` | 同上 |
|
||||
| `split` | `value`, `sep` | 内置,无库名前缀 |
|
||||
| `sys.env_get` | `name` | |
|
||||
|
||||
**取元 `[key](map)` 是断言式**:键缺失直接 `missing map key 'error'`。
|
||||
取「可能不存在」的键一律用 `table.get` / `json.get`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结构
|
||||
|
||||
### 7.1 `# main` 的体不会被 `##` 截断
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=first
|
||||
|
||||
## helper
|
||||
|
||||
*1*
|
||||
|
||||
> print text=last ← 仍属于 main,会执行
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `first` `last`。**但可读性差**,建议 `# main` 只做编排,函数都放前面。
|
||||
|
||||
### 7.2 `1.` `2.` `3.` 是一条 if/elif/else 链
|
||||
|
||||
```markdown
|
||||
1. `a` > 10
|
||||
...
|
||||
2. `a` > 5
|
||||
...
|
||||
3. *
|
||||
...
|
||||
```
|
||||
|
||||
两段独立的 `1.` 是**两个** if,不是链。嵌套靠缩进。
|
||||
`2. *` 是 else 分支。
|
||||
|
||||
---
|
||||
|
||||
## 8. 自查清单
|
||||
|
||||
提交前跑一遍:
|
||||
|
||||
```bash
|
||||
marqdo check 你的文件.mq.md # 契约/语法检查
|
||||
marqdo run 你的文件.mq.md # 真跑,退出码 0 才算过
|
||||
```
|
||||
|
||||
逐项确认:
|
||||
|
||||
- [ ] 叙述区没有以**数字**或 `+` 起头的行
|
||||
- [ ] 所有双引号成对
|
||||
- [ ] 函数名不含空格
|
||||
- [ ] 没有依赖「函数间共享变量」
|
||||
- [ ] `table.put` 的返回值都接住了
|
||||
- [ ] import 路径以当前文件为基准
|
||||
- [ ] 可选键用 `table.get` / `json.get`,不用 `[key](map)`
|
||||
- [ ] 文件有 `# main`,且 `# main` 无副作用
|
||||
|
||||
---
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-10-22 | 首次发布;全部条目在 1.5.2 实测 |
|
||||
@@ -51,6 +51,7 @@
|
||||
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
|
||||
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
|
||||
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
|
||||
| [第 15 章:常见陷阱](./15-常见陷阱.md) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/feed
|
||||
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
|
||||
import table:lib/table.mq.md
|
||||
@@ -11,13 +12,13 @@ import text:lib/text.mq.md
|
||||
给定帖子行记录列表,输出 `ul.home-posts-list` 标记(首页与列表页共用)。
|
||||
|
||||
**段 = None**
|
||||
- [帖](行)
|
||||
**板 = [board](帖)**
|
||||
**题 = [title](帖)**
|
||||
**链 = [slug](帖)**
|
||||
**作 = [author](帖)**
|
||||
**评 = [comments_count](帖)**
|
||||
**时 = [created_at](帖)**
|
||||
- [帖](遍历 行 为 帖)
|
||||
**板 = [board](access(帖, "board"))**
|
||||
**题 = [title](access(帖, "title"))**
|
||||
**链 = [slug](access(帖, "slug"))**
|
||||
**作 = [author](access(帖, "author"))**
|
||||
**评 = [comments_count](access(帖, "comments_count"))**
|
||||
**时 = [created_at](access(帖, "created_at"))**
|
||||
1. not 作
|
||||
**作 = "匿名"**
|
||||
2. *
|
||||
@@ -41,11 +42,11 @@ import text:lib/text.mq.md
|
||||
给定新闻行记录列表,输出 `.news-timeline` 标记。
|
||||
|
||||
**段 = None**
|
||||
- [讯](行)
|
||||
**题 = [title](讯)**
|
||||
**链 = [slug](讯)**
|
||||
**板 = [board](讯)**
|
||||
**时 = [created_at](讯)**
|
||||
- [讯](遍历 行 为 讯)
|
||||
**题 = [title](access(讯, "title"))**
|
||||
**链 = [slug](access(讯, "slug"))**
|
||||
**板 = [board](access(讯, "board"))**
|
||||
**时 = [created_at](access(讯, "created_at"))**
|
||||
1. not 板
|
||||
**板 = ""**
|
||||
2. *
|
||||
@@ -79,9 +80,9 @@ import text:lib/text.mq.md
|
||||
**全链 = 前缀 + "?" + 查询键 + "=0"**
|
||||
**全项 = "<a href=\"" + 全链 + "\" class=\"" + 全部类 + " active\" " + 数据属 + "=\"0\">" + 全标签 + "</a>"**
|
||||
**段 = > table.append list=段 item=全项**
|
||||
- [板](板块)
|
||||
**名 = [name](板)**
|
||||
**号 = [id](板)**
|
||||
- [板](遍历 板块 为 板)
|
||||
**名 = [name](access(板, "name"))**
|
||||
**号 = [id](access(板, "id"))**
|
||||
**链 = 前缀 + "?" + 查询键 + "=" + 号**
|
||||
**项 = "<a href=\"" + 链 + "\" class=\"" + 全部类 + "\" " + 数据属 + "=\"" + 号 + "\">" + 名 + "</a>"**
|
||||
**段 = > table.append list=段 item=项**
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: browser-app (route E+)
|
||||
description: list CRUD, storage, navigate, interval, fetch_all, ws — GFM + lib/browser
|
||||
import browser:lib/browser.mq.md
|
||||
@@ -64,7 +65,7 @@ import text:lib/text.mq.md
|
||||
**`bag` = bag + "\n" + value**
|
||||
**`parts` = > text.str_split s=bag sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"**
|
||||
**`ret` = > browser.set_html sel="#items" html=html**
|
||||
@@ -81,7 +82,7 @@ import text:lib/text.mq.md
|
||||
1. `data_id` != ""
|
||||
**`parts` = > text.str_split s=bag sep="\n"**
|
||||
**`next` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
1. `item` != `data_id`
|
||||
1. `next` == ""
|
||||
@@ -91,7 +92,7 @@ import text:lib/text.mq.md
|
||||
**`bag` = next**
|
||||
**`parts2` = > text.str_split s=bag sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts2)
|
||||
- [item](遍历 parts2 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"**
|
||||
**`ret` = > browser.set_html sel="#items" html=html**
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 代码即文档 · 周末咖啡手账
|
||||
description: >-
|
||||
一份可读可跑的周末手账:菜单是表,计价写在段落里,结账读起来像日记。
|
||||
@@ -55,13 +56,13 @@ description: >-
|
||||
上午来了位会员,点两杯拿铁。品名写进`名`,价钱从菜单里取:
|
||||
|
||||
**名 = "拿铁"**
|
||||
**价 = [`名`](菜单)**
|
||||
**价 = [名](access(菜单, `名`))**
|
||||
**摘要 = [结账摘要] 品名=`名` 价=`价` 杯数=2 会员=True**
|
||||
**打印 内容=`摘要`**
|
||||
|
||||
旁桌只要一杯普通美式,对照一下原价:
|
||||
|
||||
**对照 = [结账摘要] 品名="美式" 价=[美式](菜单)**
|
||||
**对照 = [结账摘要] 品名="美式" 价=[美式](access(菜单, "美式"))**
|
||||
**打印 内容=`对照`**
|
||||
|
||||
---
|
||||
@@ -75,8 +76,8 @@ description: >-
|
||||
| 1 | 燕麦拿铁 | 32 | 1 | True |
|
||||
| 2 | 美式 | 18 | 2 | False |
|
||||
|
||||
- [行](今日订单)
|
||||
**一行 = 结账摘要 品名=[品名](行) 价=[单价](行) 杯数=[杯数](行) 会员=[会员](行)**
|
||||
- [行](遍历 今日订单 为 行)
|
||||
**一行 = 结账摘要 品名=[品名](access(行, "品名")) 价=[单价](access(行, "单价")) 杯数=[杯数](access(行, "杯数")) 会员=[会员](access(行, "会员"))**
|
||||
**打印 内容=`一行`**
|
||||
|
||||
打烊前给积分卡盖一个章:
|
||||
|
||||
@@ -24,7 +24,7 @@ import data:ext/data/db.mq.md
|
||||
|
||||
| title | slug | summary | content | tag | created_at |
|
||||
|-------|------|---------|---------|-----|------------|
|
||||
| Hello Marqdo | hello | Welcome | # Hello\n\nExecutable documents. | intro | 2026-09-01 |
|
||||
| Hello Marqdo | hello | Welcome | Hello — executable documents. | intro | 2026-09-01 |
|
||||
| Artifact Web | artifact-web | Document first | Pages are mq.md files. | design | 2026-09-28 |
|
||||
|
||||
*rows*
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# oa2026-showcase
|
||||
|
||||
用于 2026 开源项目大赛作品介绍文档的可运行示例。
|
||||
|
||||
| 文件 | 展示的能力 | 运行 |
|
||||
|------|------------|------|
|
||||
| `add.mq.md` | 叙述统一、粗体即代码、斜体即返回 | `marqdo run examples/oa2026-showcase/add.mq.md` |
|
||||
| `invoice.mq.md` | 表格即数据、循环、分支、断言 | `marqdo run examples/oa2026-showcase/invoice.mq.md` |
|
||||
| `calculus.mq.md` | 公式即变量、求导、求根、绘图 | `marqdo run examples/oa2026-showcase/calculus.mq.md` |
|
||||
| `bell.mq.md` | 量子电路、概率、断言、SVG 派生物 | `marqdo run examples/oa2026-showcase/bell.mq.md` |
|
||||
| `foreign-node.mq.md` | 外联一次性执行、持久会话、显式传值 | `marqdo run examples/oa2026-showcase/foreign-node.mq.md` |
|
||||
|
||||
## 预期输出
|
||||
|
||||
```text
|
||||
$ marqdo run examples/oa2026-showcase/add.mq.md
|
||||
42
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/invoice.mq.md
|
||||
960
|
||||
912
|
||||
966
|
||||
within-cap
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/calculus.mq.md
|
||||
3*x^2 - 3
|
||||
9
|
||||
[-1.7320508076, 0, 1.7320508076]
|
||||
plot-ok
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/foreign-node.mq.md
|
||||
{华东: 420, 华北: 220, 华南: 230}
|
||||
华东: 420
|
||||
华南: 230
|
||||
华北: 220
|
||||
|
||||
华东: 420
|
||||
华北: 300
|
||||
华南: 230
|
||||
|
||||
$ marqdo run examples/oa2026-showcase/bell.mq.md
|
||||
{00: 0.5, 11: 0.5}
|
||||
0.5
|
||||
0.5
|
||||
bell-00-ok
|
||||
bell-11-ok
|
||||
bell-draw-ok
|
||||
```
|
||||
|
||||
`bell.mq.md` 运行后会生成 `bell-circuit.svg` 与 `bell-probs.svg`;
|
||||
`calculus.mq.md` 运行后会生成 `calculus-plot.svg`。
|
||||
@@ -0,0 +1,10 @@
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,我们执行 **`n` = `n` + 1**,然后把更新后的值作为结果返回 *`n`*。
|
||||
|
||||
# main
|
||||
|
||||
从 41 出发调用「加一」,把结果存进`r`并打印。
|
||||
|
||||
**`r` = > 加一 n=41**
|
||||
> print text=`r`
|
||||
@@ -0,0 +1,24 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="320" height="136" viewBox="0 0 320.0 136.0" data-theme="light" role="img" aria-label="quantum circuit"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#eef3f9"/>
|
||||
<stop offset="55%" stop-color="#ffffff"/>
|
||||
<stop offset="100%" stop-color="#eef3f9"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#3d5afe" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="320.0" height="136.0" rx="14" fill="url(#mq-bg)"/>
|
||||
<rect x="1.5" y="1.5" width="317.0" height="133.0" rx="12.5" fill="none" stroke="#e2eaf3" stroke-width="1" opacity="0.55"/><line x1="96" y1="36" x2="296" y2="36" stroke="#4a5a6a" stroke-width="3.2" stroke-linecap="round" opacity="0.28"/>
|
||||
<line x1="96" y1="36" x2="296" y2="36" stroke="#4a5a6a" stroke-width="1.8" stroke-linecap="round"/><rect x="51" y="25" width="38" height="22" rx="7" fill="#ffffff" stroke="#e2eaf3" stroke-width="1"/>
|
||||
<text x="70" y="36" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="13" font-weight="700" letter-spacing="0.02em" fill="#15202b">q0</text><line x1="96" y1="100" x2="296" y2="100" stroke="#4a5a6a" stroke-width="3.2" stroke-linecap="round" opacity="0.28"/>
|
||||
<line x1="96" y1="100" x2="296" y2="100" stroke="#4a5a6a" stroke-width="1.8" stroke-linecap="round"/><rect x="51" y="89" width="38" height="22" rx="7" fill="#ffffff" stroke="#e2eaf3" stroke-width="1"/>
|
||||
<text x="70" y="100" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="13" font-weight="700" letter-spacing="0.02em" fill="#15202b">q1</text><rect x="116" y="16" width="40" height="40" rx="8" fill="#3d5afe" stroke="#ffffff" stroke-width="1.1" data-gate-family="clifford" filter="url(#mq-soft)" opacity="0.98"/>
|
||||
<text x="136" y="36" text-anchor="middle" dominant-baseline="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="14" font-weight="700" fill="#ffffff">H</text><line x1="216" y1="36" x2="216" y2="100" stroke="#1a237e" stroke-width="2.25" data-gate-family="clifford"/>
|
||||
<circle cx="216" cy="36" r="5.2" fill="#1a237e" filter="url(#mq-glow)"/>
|
||||
<circle cx="216" cy="100" r="13" fill="#3d5afe" stroke="#1a237e" stroke-width="1.6" filter="url(#mq-soft)" opacity="0.96"/>
|
||||
<line x1="216" y1="87" x2="216" y2="113" stroke="#1a237e" stroke-width="2"/>
|
||||
<line x1="203" y1="100" x2="229" y2="100" stroke="#1a237e" stroke-width="2"/></svg>
|
||||
|
After Width: | Height: | Size: 2.7 KiB |
@@ -0,0 +1,14 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="light" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#eef3f9"/>
|
||||
<stop offset="55%" stop-color="#ffffff"/>
|
||||
<stop offset="100%" stop-color="#eef3f9"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#3d5afe" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#4a5560" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#4a5560" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#15202b">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#15202b">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#3d5afe" stroke="#1a237e" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#15202b">00</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#5a6a7a">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#3d5afe" stroke="#1a237e" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#15202b">11</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#5a6a7a">0.50</text></svg>
|
||||
|
After Width: | Height: | Size: 2.0 KiB |
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 贝尔态:两个量子比特如何一起回答
|
||||
description: 从一条假设开始,搭电路、看概率、画图,并用断言验收。
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
贝尔态:一次可读的量子实验。
|
||||
|
||||
我们先做一个假设:如果对第一个量子比特施加 Hadamard 门,再用它控制第二个量子比特翻转,
|
||||
那么测量结果不会出现「一个 0、一个 1」,只会出现「00」或「11」。
|
||||
|
||||
下面的表不是配置,而是实验步骤本身。读者先读实验设计,再读执行结果。
|
||||
|
||||
`步骤` =
|
||||
|
||||
| 步骤 | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
**`电路` = > quantum.circuit qubits=2 steps=`步骤`**
|
||||
**`概率` = > `电路`.probabilities**
|
||||
|
||||
> print text=`概率`
|
||||
|
||||
---
|
||||
|
||||
我们期待什么?如果假设成立,`概率`应该只在「00」与「11」上有值,而且各占一半。
|
||||
先把两个关键概率取出来,读者不必在长映射里找:
|
||||
|
||||
**`p00` = [00](概率)**
|
||||
**`p11` = [11](概率)**
|
||||
|
||||
> print text=`p00`
|
||||
> print text=`p11`
|
||||
|
||||
下面的断言不是装饰:如果电路写错,或者门接错,运行会直接失败。
|
||||
|
||||
1. `p00` > 0.49
|
||||
> print text=bell-00-ok
|
||||
2. *
|
||||
> print text=bell-00-fail
|
||||
|
||||
1. `p11` > 0.49
|
||||
> print text=bell-11-ok
|
||||
2. *
|
||||
> print text=bell-11-fail
|
||||
|
||||
---
|
||||
|
||||
图不是截图,而是这份文档运行后生成的派生物。电路图和概率图都来自同一个`电路`。
|
||||
|
||||
**`_` = > `电路`.draw path="bell-circuit.svg" theme="light"**
|
||||
**`_` = > `电路`.draw kind="probs" path="bell-probs.svg" theme="light"**
|
||||
|
||||
> print text=bell-draw-ok
|
||||
@@ -0,0 +1,17 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="289.09" x2="484" y2="289.09" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="216.36" x2="484" y2="216.36" class="grid"/><line x1="36" y1="180.00" x2="484" y2="180.00" class="grid"/><line x1="36" y1="143.64" x2="484" y2="143.64" class="grid"/><line x1="36" y1="107.27" x2="484" y2="107.27" class="grid"/><line x1="36" y1="70.91" x2="484" y2="70.91" class="grid"/><line x1="36" y1="180.00" x2="484" y2="180.00" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="184.00" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="176.00" x2="36.00" y2="184.00" class="tick"/><text x="36.00" y="194.00" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="176.00" x2="110.67" y2="184.00" class="tick"/><text x="110.67" y="194.00" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="176.00" x2="185.33" y2="184.00" class="tick"/><text x="185.33" y="194.00" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="176.00" x2="334.67" y2="184.00" class="tick"/><text x="334.67" y="194.00" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="176.00" x2="409.33" y2="184.00" class="tick"/><text x="409.33" y="194.00" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="176.00" x2="484.00" y2="184.00" class="tick"/><text x="484.00" y="194.00" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="289.09" x2="264.00" y2="289.09" class="tick"/><text x="252.00" y="289.09" text-anchor="end" dominant-baseline="middle" class="tick-label">-15</text><line x1="256.00" y1="252.73" x2="264.00" y2="252.73" class="tick"/><text x="252.00" y="252.73" text-anchor="end" dominant-baseline="middle" class="tick-label">-10</text><line x1="256.00" y1="216.36" x2="264.00" y2="216.36" class="tick"/><text x="252.00" y="216.36" text-anchor="end" dominant-baseline="middle" class="tick-label">-5</text><line x1="256.00" y1="143.64" x2="264.00" y2="143.64" class="tick"/><text x="252.00" y="143.64" text-anchor="end" dominant-baseline="middle" class="tick-label">5</text><line x1="256.00" y1="107.27" x2="264.00" y2="107.27" class="tick"/><text x="252.00" y="107.27" text-anchor="end" dominant-baseline="middle" class="tick-label">10</text><line x1="256.00" y1="70.91" x2="264.00" y2="70.91" class="tick"/><text x="252.00" y="70.91" text-anchor="end" dominant-baseline="middle" class="tick-label">15</text><text x="252.00" y="194.00" class="tick-label">0</text><path d="M 36.00 310.91 L 38.24 305.73 L 40.48 300.67 L 42.72 295.72 L 44.96 290.89 L 47.20 286.18 L 49.44 281.57 L 51.68 277.07 L 53.92 272.69 L 56.16 268.41 L 58.40 264.24 L 60.64 260.18 L 62.88 256.22 L 65.12 252.36 L 67.36 248.61 L 69.60 244.96 L 71.84 241.40 L 74.08 237.95 L 76.32 234.60 L 78.56 231.34 L 80.80 228.17 L 83.04 225.11 L 85.28 222.13 L 87.52 219.25 L 89.76 216.45 L 92.00 213.75 L 94.24 211.13 L 96.48 208.61 L 98.72 206.17 L 100.96 203.81 L 103.20 201.53 L 105.44 199.34 L 107.68 197.23 L 109.92 195.20 L 112.16 193.25 L 114.40 191.38 L 116.64 189.58 L 118.88 187.86 L 121.12 186.22 L 123.36 184.64 L 125.60 183.14 L 127.84 181.71 L 130.08 180.35 L 132.32 179.06 L 134.56 177.83 L 136.80 176.67 L 139.04 175.57 L 141.28 174.54 L 143.52 173.57 L 145.76 172.67 L 148.00 171.82 L 150.24 171.03 L 152.48 170.30 L 154.72 169.62 L 156.96 169.00 L 159.20 168.44 L 161.44 167.93 L 163.68 167.47 L 165.92 167.06 L 168.16 166.70 L 170.40 166.39 L 172.64 166.12 L 174.88 165.90 L 177.12 165.73 L 179.36 165.60 L 181.60 165.51 L 183.84 165.46 L 186.08 165.46 L 188.32 165.49 L 190.56 165.56 L 192.80 165.67 L 195.04 165.81 L 197.28 165.98 L 199.52 166.19 L 201.76 166.43 L 204.00 166.70 L 206.24 167.01 L 208.48 167.33 L 210.72 167.69 L 212.96 168.07 L 215.20 168.48 L 217.44 168.91 L 219.68 169.36 L 221.92 169.84 L 224.16 170.33 L 226.40 170.84 L 228.64 171.38 L 230.88 171.92 L 233.12 172.48 L 235.36 173.06 L 237.60 173.65 L 239.84 174.25 L 242.08 174.86 L 244.32 175.49 L 246.56 176.12 L 248.80 176.75 L 251.04 177.39 L 253.28 178.04 L 255.52 178.69 L 257.76 179.35 L 260.00 180.00 L 262.24 180.65 L 264.48 181.31 L 266.72 181.96 L 268.96 182.61 L 271.20 183.25 L 273.44 183.88 L 275.68 184.51 L 277.92 185.14 L 280.16 185.75 L 282.40 186.35 L 284.64 186.94 L 286.88 187.52 L 289.12 188.08 L 291.36 188.62 L 293.60 189.16 L 295.84 189.67 L 298.08 190.16 L 300.32 190.64 L 302.56 191.09 L 304.80 191.52 L 307.04 191.93 L 309Line truncated
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 6.8 KiB |
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: 一份可执行的求导讲义
|
||||
description: 公式、求导、求根、求值与绘图,在同一条叙述里完成。
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
我们从一条曲线开始。下面这个公式既是排版出来的数学对象,
|
||||
也是运行时可以直接求导、求根与绘图的`f`。
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^3 - 3*x
|
||||
$$
|
||||
|
||||
对它求导,得到`df`;再让`df`在 x = 2 处取值,得到切线斜率。
|
||||
|
||||
**`df` = [math.diff] formula=`f` var="x"**
|
||||
**`slope` = [math.eval] formula=`df` var="x" value=2**
|
||||
> print text=`df`
|
||||
> print text=`slope`
|
||||
|
||||
曲线与 x 轴的交点同样可以被机器找出来。这里不需要另写一段脚本。
|
||||
|
||||
**`roots` = [math.solve] formula=`f` var="x" min=-3 max=3**
|
||||
> print text=`roots`
|
||||
|
||||
最后把公式画成图。图不是截图,而是本文档运行产生的派生物。
|
||||
|
||||
**`_svg` = [math.plot] formula=`f` var="x" min=-3 max=3 path="calculus-plot.svg"**
|
||||
> print text=plot-ok
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 外联:把 Node 当作文档里的计算车间
|
||||
description: 一次性执行、持久会话、显式传值,以及可读的结果。
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这份文档要回答一个很具体的问题:同一批订单,按区域汇总之后,总金额分别是多少?
|
||||
数据已经写在文档里,计算交给 Node,结果回到文档里继续被阅读与断言。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
|
||||
先做一次性执行。`foreign.call` 把`订单`编码成 JSON 放到 stdin,
|
||||
Node 读完、汇总、打印 JSON;外联再把 stdout 解析成 Marqdo 的值。
|
||||
没有 shell,也没有隐式的 stdin 约定——传什么、读什么,都写在代码里。
|
||||
|
||||
`汇总代码` =
|
||||
```javascript
|
||||
const incoming = JSON.parse(require('fs').readFileSync(0, 'utf8'));
|
||||
|
||||
const byRegion = {};
|
||||
for (const row of incoming) {
|
||||
byRegion[row["区域"]] = (byRegion[row["区域"]] || 0) + Number(row["金额"]);
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(byRegion));
|
||||
```
|
||||
|
||||
**`汇总` = > foreign.call code=`汇总代码` input=`订单`**
|
||||
> print text=`汇总`
|
||||
|
||||
---
|
||||
|
||||
一次性执行适合「算完就走」。如果想让同一个 Node 内核保留变量,
|
||||
就显式开启会话、显式设值、显式求值、显式关闭——状态不会藏在某个看不见的 cell 里。
|
||||
|
||||
**`会话` = > foreign.session_open lang="node"**
|
||||
**> foreign.session_set id=`会话` name="orders" value=`订单`**
|
||||
|
||||
`排序代码` =
|
||||
```javascript
|
||||
const ranked = Object.entries(
|
||||
orders.reduce((acc, row) => {
|
||||
acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
|
||||
return acc;
|
||||
}, {})
|
||||
).sort((a, b) => b[1] - a[1]);
|
||||
|
||||
console.log(ranked.map(([region, total]) => `${region}: ${total}`).join("\n"));
|
||||
```
|
||||
|
||||
**`第一次` = > foreign.session_eval id=`会话` code=`排序代码`**
|
||||
> print text=[stdout](access(`第一次`, "stdout"))
|
||||
|
||||
内核状态是持续的。下面这段代码在同一个`orders`上追加一条华北订单,
|
||||
再重新排序;不需要重新传一遍整张表。
|
||||
|
||||
`追加代码` =
|
||||
```javascript
|
||||
orders.push({ 区域: "华北", 金额: 80 });
|
||||
|
||||
const rankedAgain = Object.entries(
|
||||
orders.reduce((acc, row) => {
|
||||
acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
|
||||
return acc;
|
||||
}, {})
|
||||
).sort((a, b) => b[1] - a[1]);
|
||||
|
||||
console.log(rankedAgain.map(([region, total]) => `${region}: ${total}`).join("\n"));
|
||||
```
|
||||
|
||||
**`第二次` = > foreign.session_eval id=`会话` code=`追加代码`**
|
||||
> print text=[stdout](access(`第二次`, "stdout"))
|
||||
|
||||
**> foreign.session_close id=`会话`**
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 一张订单,一份可执行的业务说明
|
||||
description: 叙述、数据、计算与断言共享同一个 .mq.md 源文件。
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这份文档不是代码旁边的说明,也不是说明里贴的代码。下表既是给人读的订单,
|
||||
也是运行时直接使用的记录集合;下面的句子既解释业务规则,也参与计算。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 客户 | 单价 | 数量 | 提前天数 |
|
||||
|---|------|------|------|----------|
|
||||
| 1 | 青山实验室 | 120 | 3 | 10 |
|
||||
| 2 | 远望中心 | 80 | 5 | 4 |
|
||||
| 3 | 星尘工坊 | 200 | 1 | 14 |
|
||||
|
||||
逐行把「单价 × 数量」累加进`小计`。读者看到的是清单,机器执行的是同一张表。
|
||||
|
||||
**`小计` = 0**
|
||||
- [行](遍历 订单 为 行)
|
||||
**`小计` = `小计` + [单价](access(行, "单价")) * [数量](access(行, "数量"))**
|
||||
|
||||
业务约定写在叙述里:提前不少于七天,整单按九五折;否则原价。
|
||||
本单最早提前 14 天。
|
||||
|
||||
**`最早提前` = 14**
|
||||
1. `最早提前` >= 7
|
||||
**`折后` = `小计` * 95 / 100**
|
||||
2. *
|
||||
**`折后` = `小计`**
|
||||
|
||||
把结果、依据和判断一起写进文档。下面的断言如果跑不通,文档本身就是错的。
|
||||
|
||||
**`含税` = `折后` * 106 / 100**
|
||||
> print text=`小计`
|
||||
> print text=`折后`
|
||||
> print text=`含税`
|
||||
|
||||
1. `含税` < 10000
|
||||
> print text=within-cap
|
||||
2. *
|
||||
> print text=over-cap
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
markup: occlusion
|
||||
import table:lib/table.mq.md
|
||||
title: Marqdo 语法全景(v1.6 现状)
|
||||
description: 一页看完全部现行语法:遮蔽、调用、取值、循环、分支、表格、契约
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
—— 1. 变量与插值 ——
|
||||
|
||||
**π = 3.14159**
|
||||
**名 = "Marqdo"**
|
||||
**开 = True**
|
||||
|
||||
> print text=名字是`名`,π 约等于 `π`
|
||||
|
||||
反引号取值,正文里的反引号是插值:
|
||||
|
||||
`长度` = [名字长度](len(`名`))
|
||||
|
||||
> print text=`名` 的长度是 `长度`
|
||||
|
||||
—— 2. 函数:参数、返回、契约 ——
|
||||
|
||||
税率函数接收档位与金额,返回应缴税额。
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
|
||||
`税率表` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.1 |
|
||||
| 3 | 0.2 |
|
||||
|
||||
—— 3. 调用的四种形态 ——
|
||||
|
||||
> print text="形态一:> 前缀 + 具名实参"
|
||||
|
||||
**甲 = 加(1 2)**
|
||||
**乙 = 加(1, 2)**
|
||||
**丙 = 加(加(1 2), 10)**
|
||||
**丁 = 加一 号(31)**
|
||||
|
||||
> print text=形态二 括号位置实参:`甲`
|
||||
> print text=形态三 括号逗号:`乙`
|
||||
> print text=形态四 嵌套:`丙`
|
||||
> print text=形态五 带空格的函数名:`丁`
|
||||
|
||||
—— 4. 取值:access / at / get ——
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
|
||||
`饮品价` =
|
||||
|
||||
| 拿铁 | 美式 |
|
||||
|------|------|
|
||||
| 28 | 18 |
|
||||
|
||||
`取第一` = [第一颗](access(`篮子`, "1"))
|
||||
`取配置` = [拿铁多少钱](access(`饮品价`, "拿铁"))
|
||||
`个数` = [篮子有几颗](table.len(`篮子`))
|
||||
`表取` = [用 table.get 读同一个键](table.get(`饮品价`, "美式"))
|
||||
|
||||
> print text=access 取列表第 1 项:`取第一`
|
||||
> print text=access 取 Map 的键:`取配置`
|
||||
> print text=table.len 数个数:`个数`
|
||||
> print text=table.get 读键:`表取`
|
||||
|
||||
—— 5. 遮蔽:把实现藏进括号 ——
|
||||
|
||||
描述给人读,`()` 里才是机器执行的部分。
|
||||
|
||||
写法用 `` `名` = [描述](实现) ``(裸赋值),而不是 `**名 = [描述](实现)**`:
|
||||
粗体会把描述也包成"代码味",读者一眼看到的是强调而不是人话。
|
||||
|
||||
`留存` = [客户留存率,模拟数据](0.42)
|
||||
|
||||
> print text=遮蔽的值:`留存`
|
||||
|
||||
未接通的功能用空载荷申报(会得到一条 warning,提醒写清返回值):
|
||||
|
||||
`待接` = [搜索接入,接口未接,待开发]()
|
||||
|
||||
> print text=空载荷桩的值:`待接`
|
||||
|
||||
—— 6. 循环 ——
|
||||
|
||||
- [篮子里的每个果子](遍历 `篮子` 为 `果`)
|
||||
> print text=果子:`果`
|
||||
|
||||
`n` = 3
|
||||
|
||||
- `n` > 0
|
||||
> print text=倒数 `n`
|
||||
**n = n - 1**
|
||||
|
||||
—— 7. 分支 ——
|
||||
|
||||
**分数 = 86**
|
||||
|
||||
1. `分数` >= 90
|
||||
> print text=等级 A
|
||||
2. `分数` >= 60
|
||||
> print text=等级 B
|
||||
3. *
|
||||
> print text=等级 C
|
||||
|
||||
—— 8. 表格的三态 ——
|
||||
|
||||
竖表(单列)→ List:
|
||||
|
||||
`城市` =
|
||||
|
||||
| 城 |
|
||||
|----|
|
||||
| 北京 |
|
||||
| 上海 |
|
||||
|
||||
横表(1 行)→ Map:
|
||||
|
||||
`配置` =
|
||||
|
||||
| 超时 | 重试 |
|
||||
|------|------|
|
||||
| 30 | 2 |
|
||||
|
||||
行向(首列 `行`)→ List of Map:
|
||||
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
|
||||
- [每条订单](遍历 `订单` 为 `单`)
|
||||
> print text=订单:`单`
|
||||
|
||||
> print text=配置超时是 `配置`
|
||||
|
||||
—— 9. 值类型 ——
|
||||
|
||||
**整数 = 42**
|
||||
**小数 = 1.5**
|
||||
**真值 = True**
|
||||
**空值 = None**
|
||||
**串 = "引号里的文本"**
|
||||
|
||||
> print text=整数 `整数` 小数 `小数` 真值 `真值` 空值 `空值`
|
||||
> print text=`串`
|
||||
|
||||
—— 10. 收尾 ——
|
||||
|
||||
> print text="以上全部可执行;描述只是描述,机器只跑括号里的东西。"
|
||||
|
||||
## 计税
|
||||
+ `档位`
|
||||
+ `金额`
|
||||
|
||||
**率 = 0.1**
|
||||
|
||||
1. `档位` == 1
|
||||
**率 = 0.03**
|
||||
2. `档位` == 3
|
||||
**率 = 0.2**
|
||||
3. *
|
||||
**率 = 0.1**
|
||||
|
||||
*`金额` * `率`*
|
||||
|
||||
## 加
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
*`a` + `b`*
|
||||
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: spa client
|
||||
description: routes table + memory store; list / detail / edit
|
||||
import browser:lib/browser.mq.md
|
||||
@@ -87,7 +88,7 @@ Routes (documentation + titles). Runtime switches panels by `path`.
|
||||
1. `cur_id` != ""
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`next` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
1. `item` == `cur_id`
|
||||
1. `next` == ""
|
||||
@@ -145,7 +146,7 @@ Routes (documentation + titles). Runtime switches panels by `path`.
|
||||
**`body` = ""**
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts)
|
||||
- [item](遍历 parts 为 item)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li data-id=\"" + item + "\">" + item + "</li>"**
|
||||
`persist` =
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.5.0
|
||||
2.0.0
|
||||
+2
-2
@@ -36,7 +36,7 @@ The runbook `.mq.md` is ground truth (code as documentation). Default budgets ke
|
||||
**skill = > skill_brief depth=`skill_depth`**
|
||||
**task_s = > json.stringify value=`task`**
|
||||
|
||||
**esc = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nCall ONLY names listed under --- tools --- (whitelist). If that section is empty or says none, do NOT emit CALL / 调用 — reply with the final answer only.\nNever CALL internal framework helpers (build_step_context, plan, inspect_workbook, etc.).\nContext is budgeted: if you see a [truncated …] marker, you may first emit exactly one line READ:source or READ:skill (Chinese: 读取:source|skill) to deepen, then you will be re-prompted.\nWhen calling an allowed tool, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"}**
|
||||
**esc = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nCall ONLY names listed under --- tools --- (whitelist). If that section is empty or says none, do NOT emit CALL / 调用 — reply with the final answer only.\nNever CALL internal framework helpers (build_step_context, plan, inspect_workbook, etc.).\nContext is budgeted: if you see a [truncated …] marker, you may first emit exactly one line READ:source or READ:skill (Chinese: 读取:source|skill) to deepen, then you will be re-prompted.\nWhen calling an allowed tool, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nIf 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.\nTools run via Marqdo subtask (spawn fn / wait).\n"}**
|
||||
**a = > json.get value=`esc` key="a"**
|
||||
**b = > json.get value=`esc` key="b"**
|
||||
**c = > json.get value=`esc` key="c"**
|
||||
@@ -45,7 +45,7 @@ The runbook `.mq.md` is ground truth (code as documentation). Default budgets ke
|
||||
**f = > json.get value=`esc` key="f"**
|
||||
**g = > json.get value=`esc` key="g"**
|
||||
|
||||
**p = "You are a Marqdo agent. Code is documentation: this runbook source and call site are your ground truth — not a hidden system prompt."**
|
||||
**p = "You are a Marqdo agent. Code is documentation: this runbook source and call site are your ground truth — not a hidden system prompt. When you cannot wire a capability, declare it in the description (待开发 / 模拟) instead of faking success."**
|
||||
**p = p + a + up + b + task_s + d + site_s + c + tools_s + e + src + f + skill + g**
|
||||
*p*
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/ai/llm/openai
|
||||
description: >-
|
||||
OpenAI-compatible chat completions transport (HTTP + SSE).
|
||||
@@ -56,7 +57,7 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
1. not `choices`
|
||||
*> table.empty_list*
|
||||
2. *
|
||||
**c0 = [1](choices)**
|
||||
**c0 = [1](access(choices, "1"))**
|
||||
**msg = > json.get value=`c0` key="message"**
|
||||
1. not `msg`
|
||||
*> table.empty_list*
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/ai/sandbox
|
||||
description: >-
|
||||
CoW trial workspace for AI-generated Marqdo: open / run / diff / commit.
|
||||
@@ -172,9 +173,9 @@ O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report
|
||||
**body = "# Sandbox diff report\n\nPending changes: "**
|
||||
**body = body + n**
|
||||
**body = body + "\n\n| path | kind |\n|------|------|\n"**
|
||||
- [row](pending)
|
||||
**p = [path](row)**
|
||||
**k = [kind](row)**
|
||||
- [row](遍历 pending 为 row)
|
||||
**p = [path](access(row, "path"))**
|
||||
**k = [kind](access(row, "kind"))**
|
||||
**body = body + "| "**
|
||||
**body = body + p**
|
||||
**body = body + " | "**
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/cache
|
||||
description: Cache Resource (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -27,7 +28,7 @@ Key–value cache. Use `memory:` for in-process (tests / single process) or `red
|
||||
## get
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_get url=`url` key=`key`*
|
||||
|
||||
## set
|
||||
@@ -37,24 +38,24 @@ Key–value cache. Use `memory:` for in-process (tests / single process) or `red
|
||||
|
||||
Optional `ttl` is seconds until expiry.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`*
|
||||
|
||||
## del
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_del url=`url` key=`key`*
|
||||
|
||||
## exists
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_exists url=`url` key=`key`*
|
||||
|
||||
## ttl
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_cache_ttl url=`url` key=`key`*
|
||||
|
||||
+32
-31
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/db
|
||||
description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -30,7 +31,7 @@ Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` /
|
||||
|
||||
Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_init url=`url` name=`name` fields=`fields`*
|
||||
|
||||
## insert
|
||||
@@ -38,7 +39,7 @@ Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引
|
||||
+ `rows`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
|
||||
|
||||
## select
|
||||
@@ -50,9 +51,9 @@ Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引
|
||||
|
||||
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
||||
*[rows](r)*
|
||||
*[rows](access(r, "rows"))*
|
||||
|
||||
## paginate
|
||||
+ `table`
|
||||
@@ -64,7 +65,7 @@ Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作
|
||||
|
||||
Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10).
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`*
|
||||
|
||||
## get
|
||||
@@ -72,7 +73,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `id`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## update
|
||||
@@ -81,7 +82,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `row`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
||||
|
||||
## delete
|
||||
@@ -89,7 +90,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `id`
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## exec
|
||||
@@ -97,7 +98,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
+ `args`=None
|
||||
+ `txn`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## query
|
||||
@@ -107,7 +108,7 @@ Like `select` but returns `{ rows, total }` — the total counts rows matching `
|
||||
|
||||
Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## count
|
||||
@@ -117,16 +118,16 @@ Run bare SQL and return the result set — count / join / group / subqueries. Re
|
||||
|
||||
Count rows matching a `where` filter (same syntax as `select`). Returns a number.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`**
|
||||
*[count](r)*
|
||||
*[count](access(r, "count"))*
|
||||
|
||||
## migrate
|
||||
+ `steps`
|
||||
|
||||
Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_migrate url=`url` steps=`steps`*
|
||||
|
||||
## fts
|
||||
@@ -136,7 +137,7 @@ Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` ta
|
||||
|
||||
Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`*
|
||||
|
||||
## search
|
||||
@@ -147,7 +148,7 @@ Create an FTS5 index on `table` for the listed content columns (CSV string or li
|
||||
|
||||
Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`*
|
||||
|
||||
## 事务
|
||||
@@ -156,7 +157,7 @@ Begin a transaction: borrows the pooled connection exclusively and returns a
|
||||
`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back).
|
||||
Every statement runs on the same connection, so a batch is atomic.
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_db_begin url=`url`*
|
||||
|
||||
# txn
|
||||
@@ -172,8 +173,8 @@ connection; finish with `提交` or `回滚`.
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
|
||||
|
||||
## select
|
||||
@@ -184,17 +185,17 @@ connection; finish with `提交` or `回滚`.
|
||||
|
||||
Same filters as `db.select`; runs inside the transaction.
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
||||
*[rows](r)*
|
||||
*[rows](access(r, "rows"))*
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## update
|
||||
@@ -202,37 +203,37 @@ Same filters as `db.select`; runs inside the transaction.
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None
|
||||
|
||||
**url = [url](self)**
|
||||
**txn = [txn](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
|
||||
|
||||
## 提交
|
||||
|
||||
Commit the transaction and return its connection to the pool.
|
||||
|
||||
**txn = [txn](self)**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_commit txn=`txn`*
|
||||
|
||||
## 回滚
|
||||
|
||||
Roll the transaction back (undo every write) and return its connection.
|
||||
|
||||
**txn = [txn](self)**
|
||||
**txn = [txn](access(self, "txn"))**
|
||||
*> web_db_rollback txn=`txn`*
|
||||
|
||||
+2
-1
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/form
|
||||
description: Form Resource — fields, validate, submit (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -62,6 +63,6 @@ Localized submit / cancel copy for rendered forms.
|
||||
+ `data`
|
||||
+ `db`
|
||||
|
||||
**url = [url](db)**
|
||||
**url = [url](access(db, "url"))**
|
||||
*> web_form_submit form=`self` data=`data` url=`url`*
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/data/storage
|
||||
description: Object storage Resource (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -32,25 +33,25 @@ Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?e
|
||||
|
||||
Provide either `body` (text) or `path` (local file to upload).
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_storage_put url=`url` key=`key` body=`body` path=`path` content_type=`content_type`*
|
||||
|
||||
## get
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_storage_get url=`url` key=`key`*
|
||||
|
||||
## delete
|
||||
+ `key`
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_storage_delete url=`url` key=`key`*
|
||||
|
||||
## list
|
||||
+ `prefix`=""
|
||||
|
||||
**url = [url](self)**
|
||||
**url = [url](access(self, "url"))**
|
||||
*> web_storage_list url=`url` prefix=`prefix`*
|
||||
|
||||
# media
|
||||
@@ -79,7 +80,7 @@ Offline helpers for upload validation and saving into `# storage` (also used by
|
||||
|
||||
**st = storage**
|
||||
1. `st` == None
|
||||
**st = [storage](self)**
|
||||
**st = [storage](access(self, "storage"))**
|
||||
2. *
|
||||
|
||||
*> web_upload_save storage=`st` path=`path` key=`key` content_type=`content_type` prefix=`prefix`*
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/net/websocket
|
||||
description: WebSocket client Resource (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -37,5 +38,5 @@ WebSocket client helper.
|
||||
|
||||
Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply.
|
||||
|
||||
**timeout = [timeout_sec](self)**
|
||||
**timeout = [timeout_sec](access(self, "timeout_sec"))**
|
||||
*> web_ws_connect url=`url` message=`message` headers=`headers` timeout_sec=`timeout`*
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: ext/security/auth
|
||||
description: Auth Resource (ADR 0007).
|
||||
import plugin:lib/plugin.mq.md
|
||||
@@ -31,8 +32,8 @@ Session/auth helper. Constructs a config object; `login` validates against the u
|
||||
|
||||
Validate credentials against the users table and create a session. Returns `{ok, session_id, username, role}`.
|
||||
|
||||
**users = [users](self)**
|
||||
**ttl = [session_ttl](self)**
|
||||
**users = [users](access(self, "users"))**
|
||||
**ttl = [session_ttl](access(self, "session_ttl"))**
|
||||
*> web_auth_login username=`username` password=`password` users=`users` session_ttl=`ttl`*
|
||||
|
||||
## check
|
||||
|
||||
+32
-2
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
Run bound code fences and inline sources via local interpreters.
|
||||
@@ -148,6 +149,25 @@ in input order. Raises with the failing index after all workers finish.
|
||||
|
||||
*> host_foreign_call_many inputs=`inputs` code=`code` lang=`lang` source=`source` cmd=`cmd` env=`env` cwd=`cwd` timeout=`timeout` args=`args` max_output=`max_output` concurrency=`concurrency`*
|
||||
|
||||
## session
|
||||
+ `kernels`=None
|
||||
+ `cells`=None
|
||||
+ `values`=None
|
||||
+ `inputs`=None
|
||||
|
||||
Declare a document view session. `kernels` and `cells` are ordinary tables:
|
||||
kernels are `|名称|语言|命令|` (ZH or EN), cells are `|单元|内核|`.
|
||||
Returns a foreign session handle consumed by `view`; without this handle the
|
||||
view has no persistent kernel state.
|
||||
|
||||
**p = > table.empty_map**
|
||||
**p = > table.put in=`p` at="kind" value="foreign-session"**
|
||||
**p = > table.put in=`p` at="kernels" value=`kernels`**
|
||||
**p = > table.put in=`p` at="cells" value=`cells`**
|
||||
**p = > table.put in=`p` at="values" value=`values`**
|
||||
**p = > table.put in=`p` at="inputs" value=`inputs`**
|
||||
*p*
|
||||
|
||||
## session_open
|
||||
+ `lang`
|
||||
+ `cmd`=None
|
||||
@@ -165,12 +185,14 @@ default per-eval timeout.
|
||||
+ `code`=None
|
||||
+ `source`=None
|
||||
+ `input`=None
|
||||
+ `stdin`=None
|
||||
+ `timeout`=None
|
||||
|
||||
Evaluate code (a code value) or source text in session id; returns a record
|
||||
with id/alive. `input` is JSON-encoded for the kernel.
|
||||
with id/alive. `input` is JSON-encoded for the kernel; `stdin` is raw program
|
||||
stdin for this evaluation.
|
||||
|
||||
*> host_foreign_session_eval id=`id` code=`code` source=`source` input=`input` timeout=`timeout`*
|
||||
*> host_foreign_session_eval id=`id` code=`code` source=`source` input=`input` stdin=`stdin` timeout=`timeout`*
|
||||
|
||||
## session_set
|
||||
+ `id`
|
||||
@@ -203,6 +225,14 @@ Kill and remove a session; returns whether it existed.
|
||||
|
||||
*> host_foreign_session_close id=`id`*
|
||||
|
||||
## session_interrupt
|
||||
+ `id`
|
||||
|
||||
Interrupt the current evaluation of a persistent kernel. The session remains
|
||||
usable for the next evaluation when the worker supports interruption.
|
||||
|
||||
*> host_foreign_session_interrupt id=`id`*
|
||||
|
||||
## session_list
|
||||
|
||||
List live sessions with id/lang/cmd/evals/alive/started_ms.
|
||||
|
||||
+27
-1
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: lib/外联
|
||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
通过本机解释器运行绑定的代码围栏与内联源码。
|
||||
@@ -146,6 +147,23 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
|
||||
|
||||
*> host_foreign_call_many inputs=`输入表` code=`代码` lang=`语言` source=`源码` cmd=`命令` env=`环境` cwd=`工作目录` timeout=`超时` args=`参数` max_output=`最大输出` concurrency=`并发`*
|
||||
|
||||
## 会话
|
||||
+ `内核表`=None
|
||||
+ `单元表`=None
|
||||
+ `值表`=None
|
||||
+ `输入表`=None
|
||||
|
||||
声明文档视图会话。内核表和单元表都是普通表格;返回一个 foreign 会话句柄,
|
||||
供 view 消费。没有这个句柄时,view 的 cells 是无状态的。
|
||||
|
||||
**p = > table.empty_map**
|
||||
**p = > table.put in=`p` at="kind" value="foreign-session"**
|
||||
**p = > table.put in=`p` at="kernels" value=`内核表`**
|
||||
**p = > table.put in=`p` at="cells" value=`单元表`**
|
||||
**p = > table.put in=`p` at="values" value=`值表`**
|
||||
**p = > table.put in=`p` at="inputs" value=`输入表`**
|
||||
*p*
|
||||
|
||||
## 会话开启
|
||||
+ `语言`
|
||||
+ `命令`=None
|
||||
@@ -162,12 +180,13 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
|
||||
+ `代码`=None
|
||||
+ `源码`=None
|
||||
+ `输入`=None
|
||||
+ `标准输入`=None
|
||||
+ `超时`=None
|
||||
|
||||
在会话中求值代码(code 值)或源码文本;返回带 id/alive 的记录。
|
||||
`输入` 会编码为 JSON 交给内核。
|
||||
|
||||
*> host_foreign_session_eval id=`标识` code=`代码` source=`源码` input=`输入` timeout=`超时`*
|
||||
*> host_foreign_session_eval id=`标识` code=`代码` source=`源码` input=`输入` stdin=`标准输入` timeout=`超时`*
|
||||
|
||||
## 会话设值
|
||||
+ `标识`
|
||||
@@ -186,6 +205,13 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
|
||||
|
||||
*> host_foreign_session_get id=`标识` name=`名称`*
|
||||
|
||||
## 会话中断
|
||||
+ `标识`
|
||||
|
||||
中断持久内核当前求值;worker 支持时,会话仍可用于下一次求值。
|
||||
|
||||
*> host_foreign_session_interrupt id=`标识`*
|
||||
|
||||
## 会话变量
|
||||
+ `标识`
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
@@ -15,6 +16,6 @@ description: AI禁止更改
|
||||
|lib|
|
||||
|
||||
|
||||
- [`测试文件夹`](`测试目录`)
|
||||
- [测试文件夹](遍历 `测试目录` 为 `测试文件夹`)
|
||||
> 打印 `测试文件夹`
|
||||
|
||||
@@ -11,5 +11,6 @@ name = "agent"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
|
||||
serde_json = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
+72
-380
@@ -11,96 +11,23 @@ mod route;
|
||||
mod sandbox;
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ffi::CString;
|
||||
use std::os::raw::{c_char, c_int};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
use std::ptr;
|
||||
use std::sync::{LazyLock, Mutex};
|
||||
|
||||
const ABI_VERSION: u32 = 2;
|
||||
use marqdo_plugin_sdk::*;
|
||||
|
||||
const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json";
|
||||
const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"];
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
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>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
static HISTORIES: LazyLock<Mutex<HashMap<String, Vec<serde_json::Value>>>> =
|
||||
LazyLock::new(|| Mutex::new(HashMap::new()));
|
||||
static AGENT_SEQ: LazyLock<Mutex<u64>> = LazyLock::new(|| Mutex::new(0));
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<serde_json::Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Err("null args".into());
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
|
||||
unsafe fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
|
||||
v.get(key)
|
||||
.and_then(|x| x.as_str())
|
||||
.ok_or_else(|| format!("missing text `{key}`"))
|
||||
@@ -543,21 +470,6 @@ unsafe extern "C" fn agent_bump_load(
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
pub(crate) fn host_query_json(name: &str) -> Result<serde_json::Value, String> {
|
||||
host_query_json_args(name, &serde_json::json!({}))
|
||||
}
|
||||
|
||||
pub(crate) fn host_query_json_args(
|
||||
name: &str,
|
||||
args: &serde_json::Value,
|
||||
@@ -587,22 +499,6 @@ pub(crate) fn host_query_json_args(
|
||||
serde_json::from_str(&out).map_err(|e| format!("host_query `{name}` bad JSON: {e}"))
|
||||
}
|
||||
|
||||
fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_str()
|
||||
.ok()
|
||||
.map(|s| s.to_string());
|
||||
unsafe {
|
||||
if let Some(free) = HOST_FREE {
|
||||
free(p as *mut c_void);
|
||||
}
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_alloc(
|
||||
_args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
@@ -947,279 +843,75 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
if host.host_query.is_none() {
|
||||
if (*host).host_query.is_none() {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_ensure_layout", "root", agent_ensure_layout) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_probe", "root", agent_probe) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_scaffold",
|
||||
"root,name,template,dest",
|
||||
agent_scaffold,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_match_skill", "skill,members", agent_match_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_alloc", "", agent_alloc) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_history_get", "id", agent_history_get) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_history_clear", "id", agent_history_clear) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_history_append", "id,item", agent_history_append) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_module_source", "", agent_module_source) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_call_site", "", agent_call_site) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_marqdo_skill", "", agent_marqdo_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_format_tools", "tools", agent_format_tools) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_tool_allowed", "tools,name", agent_tool_allowed) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_goal_sig", "goal", agent_goal_sig) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_goal_slug", "goal", agent_goal_slug) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_canonicalize", "goal", agent_kb_canonicalize) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_lookup", "kb_dir,goal", agent_kb_lookup) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_near_match", "kb_dir,goal", agent_kb_near_match) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_list_tasks", "kb_dir", agent_kb_list_tasks) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_corpus_search", "query", agent_corpus_search) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_mcp_fixture", "action,fixture", agent_mcp_fixture) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_mcp_serve", "name,tools,transport", mcp_server::agent_mcp_serve)
|
||||
!= 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_mcp_client",
|
||||
"action,command",
|
||||
mcp_client::agent_mcp_client,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_resume_save", "id,goal,status,round", agent_resume_save) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_resume_load", "id,resume_dir", agent_resume_load) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_resume_clear", "id,resume_dir", agent_resume_clear) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_resume_list", "resume_dir", agent_resume_list) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_kb_promote",
|
||||
"kb_dir,goal,workbook",
|
||||
agent_kb_promote,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_kb_quarantine",
|
||||
"kb_dir,slug",
|
||||
agent_kb_quarantine,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_record_hit", "kb_dir,goal", agent_kb_record_hit) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_workbook_solidify", "path", agent_workbook_solidify) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_task_files", "kb_dir,goal", agent_kb_task_files) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_memory_ensure", "memory_dir", agent_memory_ensure) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_record_episode",
|
||||
"task,status,result,mode",
|
||||
agent_record_episode,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_list_episodes", "memory_dir,task", agent_list_episodes) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_get_episode", "id", agent_get_episode) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_cluster_episodes",
|
||||
"memory_dir,task,threshold",
|
||||
agent_cluster_episodes,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_extract_pattern", "task", agent_extract_pattern) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_generalize", "task", agent_generalize) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_synthesize_skill", "task", agent_synthesize_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_compile_skill",
|
||||
"task,kb_dir,min_evidence",
|
||||
agent_compile_skill,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_maybe_learn",
|
||||
"task,kb_dir,improve_every",
|
||||
agent_maybe_learn,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_metrics", "memory_dir", agent_metrics) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_resolve", "task,kb_dir", agent_resolve) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_route", "task,backend,kb_dir,memory_dir", agent_route) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_route_apply", "task,reply,kb_dir", agent_route_apply) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_compile_policy",
|
||||
"memory_dir,min_evidence",
|
||||
agent_compile_policy,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_maybe_compile_policy",
|
||||
"memory_dir,min_evidence",
|
||||
agent_maybe_compile_policy,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_eng_preflight",
|
||||
"task",
|
||||
agent_eng_preflight,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_eng_reuse", "task", agent_eng_reuse) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_eng_record",
|
||||
"decision",
|
||||
agent_eng_record,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
// Optional JSON keys only — empty params CSV so omitted args are not required.
|
||||
if register(host, "sandbox_open", "", sandbox::sandbox_open) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_write", "", sandbox::sandbox_write) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_read", "", sandbox::sandbox_read) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_remove", "", sandbox::sandbox_remove) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_diff", "", sandbox::sandbox_diff) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_commit", "", sandbox::sandbox_commit) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_discard", "", sandbox::sandbox_discard) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_inspect", "", sandbox::sandbox_inspect) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_run", "", sandbox::sandbox_run) != 0 {
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
let regs: &[(&str, &str, PluginFn)] = &[
|
||||
("agent_find_root", "start,markers", agent_find_root),
|
||||
("agent_ensure_layout", "root", agent_ensure_layout),
|
||||
("agent_probe", "root", agent_probe),
|
||||
("agent_scaffold", "root,name,template,dest", agent_scaffold),
|
||||
("agent_match_skill", "skill,members", agent_match_skill),
|
||||
("agent_bump_load", "member,delta", agent_bump_load),
|
||||
("agent_alloc", "", agent_alloc),
|
||||
("agent_history_get", "id", agent_history_get),
|
||||
("agent_history_clear", "id", agent_history_clear),
|
||||
("agent_history_append", "id,item", agent_history_append),
|
||||
("agent_module_source", "", agent_module_source),
|
||||
("agent_call_site", "", agent_call_site),
|
||||
("agent_marqdo_skill", "", agent_marqdo_skill),
|
||||
("agent_format_tools", "tools", agent_format_tools),
|
||||
("agent_tool_allowed", "tools,name", agent_tool_allowed),
|
||||
("agent_goal_sig", "goal", agent_goal_sig),
|
||||
("agent_goal_slug", "goal", agent_goal_slug),
|
||||
("agent_kb_canonicalize", "goal", agent_kb_canonicalize),
|
||||
("agent_kb_lookup", "kb_dir,goal", agent_kb_lookup),
|
||||
("agent_kb_near_match", "kb_dir,goal", agent_kb_near_match),
|
||||
("agent_kb_list_tasks", "kb_dir", agent_kb_list_tasks),
|
||||
("agent_corpus_search", "query", agent_corpus_search),
|
||||
("agent_mcp_fixture", "action,fixture", agent_mcp_fixture),
|
||||
("agent_mcp_serve", "name,tools,transport", mcp_server::agent_mcp_serve),
|
||||
("agent_mcp_client", "action,command", mcp_client::agent_mcp_client),
|
||||
("agent_resume_save", "id,goal,status,round", agent_resume_save),
|
||||
("agent_resume_load", "id,resume_dir", agent_resume_load),
|
||||
("agent_resume_clear", "id,resume_dir", agent_resume_clear),
|
||||
("agent_resume_list", "resume_dir", agent_resume_list),
|
||||
("agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias),
|
||||
("agent_kb_promote", "kb_dir,goal,workbook", agent_kb_promote),
|
||||
("agent_kb_quarantine", "kb_dir,slug", agent_kb_quarantine),
|
||||
("agent_kb_record_hit", "kb_dir,goal", agent_kb_record_hit),
|
||||
("agent_workbook_solidify", "path", agent_workbook_solidify),
|
||||
("agent_kb_task_files", "kb_dir,goal", agent_kb_task_files),
|
||||
("agent_memory_ensure", "memory_dir", agent_memory_ensure),
|
||||
("agent_record_episode", "task,status,result,mode", agent_record_episode),
|
||||
("agent_list_episodes", "memory_dir,task", agent_list_episodes),
|
||||
("agent_get_episode", "id", agent_get_episode),
|
||||
("agent_cluster_episodes", "memory_dir,task,threshold", agent_cluster_episodes),
|
||||
("agent_extract_pattern", "task", agent_extract_pattern),
|
||||
("agent_generalize", "task", agent_generalize),
|
||||
("agent_synthesize_skill", "task", agent_synthesize_skill),
|
||||
("agent_compile_skill", "task,kb_dir,min_evidence", agent_compile_skill),
|
||||
("agent_maybe_learn", "task,kb_dir,improve_every", agent_maybe_learn),
|
||||
("agent_metrics", "memory_dir", agent_metrics),
|
||||
("agent_resolve", "task,kb_dir", agent_resolve),
|
||||
("agent_route", "task,backend,kb_dir,memory_dir", agent_route),
|
||||
("agent_route_apply", "task,reply,kb_dir", agent_route_apply),
|
||||
("agent_compile_policy", "memory_dir,min_evidence", agent_compile_policy),
|
||||
("agent_maybe_compile_policy", "memory_dir,min_evidence", agent_maybe_compile_policy),
|
||||
("agent_eng_preflight", "task", agent_eng_preflight),
|
||||
("agent_eng_reuse", "task", agent_eng_reuse),
|
||||
("agent_eng_record", "decision", agent_eng_record),
|
||||
("sandbox_open", "", sandbox::sandbox_open),
|
||||
("sandbox_write", "", sandbox::sandbox_write),
|
||||
("sandbox_read", "", sandbox::sandbox_read),
|
||||
("sandbox_remove", "", sandbox::sandbox_remove),
|
||||
("sandbox_diff", "", sandbox::sandbox_diff),
|
||||
("sandbox_commit", "", sandbox::sandbox_commit),
|
||||
("sandbox_discard", "", sandbox::sandbox_discard),
|
||||
("sandbox_inspect", "", sandbox::sandbox_inspect),
|
||||
("sandbox_run", "", sandbox::sandbox_run),
|
||||
];
|
||||
init_plugin(host, regs)
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
|
||||
@@ -11,4 +11,5 @@ name = "demo"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
|
||||
serde_json = "1"
|
||||
+7
-104
@@ -1,64 +1,10 @@
|
||||
//! Demo Marqdo plugin (C ABI v1). Registers `demo_add` and `demo_echo`.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
use std::ffi::CStr;
|
||||
use std::os::raw::{c_char, c_int};
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
use marqdo_plugin_sdk::*;
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_add(
|
||||
args_json: *const c_char,
|
||||
@@ -121,50 +67,7 @@ unsafe extern "C" fn demo_echo(
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let name_add = CString::new("demo_add").unwrap();
|
||||
let params_add = CString::new("a,b").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_add.as_ptr(),
|
||||
params_add.as_ptr(),
|
||||
demo_add,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
let name_echo = CString::new("demo_echo").unwrap();
|
||||
let params_echo = CString::new("text").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_echo.as_ptr(),
|
||||
params_echo.as_ptr(),
|
||||
demo_echo,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
marqdo_plugin!(1, [
|
||||
("demo_add", "a,b", demo_add),
|
||||
("demo_echo", "text", demo_echo),
|
||||
]);
|
||||
@@ -11,5 +11,6 @@ name = "linalg"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
+37
-201
@@ -7,106 +7,14 @@ mod factor;
|
||||
mod matexpr;
|
||||
mod metrics;
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
use std::os::raw::{c_char, c_int};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use marqdo_plugin_sdk::*;
|
||||
|
||||
use matexpr::{Dim, Expr};
|
||||
|
||||
const ABI_VERSION: u32 = 2;
|
||||
|
||||
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;
|
||||
|
||||
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>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<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())
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
macro_rules! la_ffi {
|
||||
($name:ident, $body:expr) => {
|
||||
@@ -132,47 +40,6 @@ macro_rules! la_ffi {
|
||||
};
|
||||
}
|
||||
|
||||
fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_str()
|
||||
.ok()
|
||||
.map(|s| s.to_string());
|
||||
unsafe {
|
||||
if let Some(free) = HOST_FREE {
|
||||
free(p as *mut c_void);
|
||||
}
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
fn host_query_json(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let query = unsafe { HOST_QUERY }.ok_or_else(|| "host_query not available".to_string())?;
|
||||
let userdata = unsafe { HOST_USERDATA };
|
||||
let c_name = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let c_args = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out_ptr: *mut c_char = ptr::null_mut();
|
||||
let mut err_ptr: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe {
|
||||
query(
|
||||
userdata,
|
||||
c_name.as_ptr(),
|
||||
c_args.as_ptr(),
|
||||
&mut out_ptr,
|
||||
&mut err_ptr,
|
||||
)
|
||||
};
|
||||
let err = take_host_string(err_ptr);
|
||||
let out = take_host_string(out_ptr);
|
||||
if rc != 0 {
|
||||
return Err(err.unwrap_or_else(|| format!("host_query `{name}` failed")));
|
||||
}
|
||||
let out = out.unwrap_or_else(|| "null".into());
|
||||
serde_json::from_str(&out).map_err(|e| format!("host_query `{name}` bad JSON: {e}"))
|
||||
}
|
||||
|
||||
fn record_plot(svg: &str, path: Option<&str>) -> Result<(), String> {
|
||||
let mut args = json!({ "svg": svg });
|
||||
if let Some(p) = path {
|
||||
@@ -182,7 +49,7 @@ fn record_plot(svg: &str, path: Option<&str>) -> Result<(), String> {
|
||||
.insert("path".into(), json!(p));
|
||||
}
|
||||
}
|
||||
host_query_json("record_plot", &args)?;
|
||||
host_query_json_with("record_plot", &args)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
@@ -622,67 +489,36 @@ fn dense_arg(args: &Value, keys: &[&str]) -> Result<dense::Mat, String> {
|
||||
Err(format!("missing dense matrix among {:?}", keys))
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let regs = [
|
||||
("linalg_ping", "", linalg_ping as PluginFn),
|
||||
("linalg_symbol", "name,rows,cols", linalg_symbol as PluginFn),
|
||||
("linalg_eye", "n", linalg_eye as PluginFn),
|
||||
("linalg_zeros", "rows,cols", linalg_zeros as PluginFn),
|
||||
("linalg_from_list", "data", linalg_from_list as PluginFn),
|
||||
("linalg_declare", "table,type_tag", linalg_declare as PluginFn),
|
||||
("linalg_from_formula", "formula", linalg_from_formula as PluginFn),
|
||||
("linalg_mul", "a,b", linalg_mul as PluginFn),
|
||||
("linalg_add", "a,b", linalg_add as PluginFn),
|
||||
("linalg_sub", "a,b", linalg_sub as PluginFn),
|
||||
("linalg_transpose", "expr", linalg_transpose as PluginFn),
|
||||
("linalg_inv", "expr", linalg_inv as PluginFn),
|
||||
("linalg_simplify", "expr", linalg_simplify as PluginFn),
|
||||
("linalg_ascii", "expr,raw", linalg_ascii as PluginFn),
|
||||
("linalg_latex", "expr,raw", linalg_latex as PluginFn),
|
||||
("linalg_shape", "expr", linalg_shape as PluginFn),
|
||||
("linalg_show", "expr,path,raw", linalg_show as PluginFn),
|
||||
("linalg_explicit", "expr,raw", linalg_explicit as PluginFn),
|
||||
("linalg_det", "expr", linalg_det as PluginFn),
|
||||
("linalg_trace", "expr", linalg_trace as PluginFn),
|
||||
("linalg_solve", "a,b,factor", linalg_solve as PluginFn),
|
||||
("linalg_matmul", "a,b", linalg_matmul as PluginFn),
|
||||
("linalg_kron", "a,b", linalg_kron as PluginFn),
|
||||
("linalg_block", "blocks", linalg_block as PluginFn),
|
||||
("linalg_collapse", "expr", linalg_collapse as PluginFn),
|
||||
("linalg_factorize", "matrix,kind", linalg_factorize as PluginFn),
|
||||
("linalg_draw", "factor,kind,path,theme", linalg_draw as PluginFn),
|
||||
("linalg_lstsq", "a,b", linalg_lstsq as PluginFn),
|
||||
("linalg_norm", "expr,ord", linalg_norm as PluginFn),
|
||||
("linalg_cond", "expr", linalg_cond as PluginFn),
|
||||
("linalg_rank", "expr", linalg_rank as PluginFn),
|
||||
];
|
||||
for (name, params, f) in regs {
|
||||
let c_name = CString::new(name).unwrap();
|
||||
let c_params = CString::new(params).unwrap();
|
||||
if register(host.userdata, c_name.as_ptr(), c_params.as_ptr(), f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("linalg_ping", "", linalg_ping),
|
||||
("linalg_symbol", "name,rows,cols", linalg_symbol),
|
||||
("linalg_eye", "n", linalg_eye),
|
||||
("linalg_zeros", "rows,cols", linalg_zeros),
|
||||
("linalg_from_list", "data", linalg_from_list),
|
||||
("linalg_declare", "table,type_tag", linalg_declare),
|
||||
("linalg_from_formula", "formula", linalg_from_formula),
|
||||
("linalg_mul", "a,b", linalg_mul),
|
||||
("linalg_add", "a,b", linalg_add),
|
||||
("linalg_sub", "a,b", linalg_sub),
|
||||
("linalg_transpose", "expr", linalg_transpose),
|
||||
("linalg_inv", "expr", linalg_inv),
|
||||
("linalg_simplify", "expr", linalg_simplify),
|
||||
("linalg_ascii", "expr,raw", linalg_ascii),
|
||||
("linalg_latex", "expr,raw", linalg_latex),
|
||||
("linalg_shape", "expr", linalg_shape),
|
||||
("linalg_show", "expr,path,raw", linalg_show),
|
||||
("linalg_explicit", "expr,raw", linalg_explicit),
|
||||
("linalg_det", "expr", linalg_det),
|
||||
("linalg_trace", "expr", linalg_trace),
|
||||
("linalg_solve", "a,b,factor", linalg_solve),
|
||||
("linalg_matmul", "a,b", linalg_matmul),
|
||||
("linalg_kron", "a,b", linalg_kron),
|
||||
("linalg_block", "blocks", linalg_block),
|
||||
("linalg_collapse", "expr", linalg_collapse),
|
||||
("linalg_factorize", "matrix,kind", linalg_factorize),
|
||||
("linalg_draw", "factor,kind,path,theme", linalg_draw),
|
||||
("linalg_lstsq", "a,b", linalg_lstsq),
|
||||
("linalg_norm", "expr,ord", linalg_norm),
|
||||
("linalg_cond", "expr", linalg_cond),
|
||||
("linalg_rank", "expr", linalg_rank),
|
||||
]);
|
||||
@@ -11,6 +11,7 @@ name = "llm"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
|
||||
serde_json = "1"
|
||||
# Pin with host (edition2024-safe for rustc 1.81).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
|
||||
+7
-134
@@ -1,105 +1,15 @@
|
||||
//! Marqdo LLM transport plugin (C ABI v2): OpenAI-compatible chat completions.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::io::{BufRead, BufReader, Read};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
use std::os::raw::{c_char, c_int};
|
||||
use std::time::Duration;
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
const ABI_VERSION: u32 = 2;
|
||||
use marqdo_plugin_sdk::*;
|
||||
|
||||
const MAX_BODY: usize = 32 * 1024 * 1024;
|
||||
|
||||
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;
|
||||
|
||||
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>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<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())
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
|
||||
}
|
||||
@@ -362,44 +272,7 @@ unsafe extern "C" fn llm_ping(
|
||||
reply(out_json, err_msg, Ok(json!({"ok": true, "plugin": "llm"})))
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
let regs = [
|
||||
("llm_ping", "", llm_ping as PluginFn),
|
||||
(
|
||||
"llm_chat_completions",
|
||||
"base_url,api_key,model,prompt,stream,echo,suffix,bearer",
|
||||
llm_chat_completions as PluginFn,
|
||||
),
|
||||
];
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,model,prompt,stream,echo,suffix,bearer", llm_chat_completions),
|
||||
]);
|
||||
@@ -11,5 +11,6 @@ name = "quantum"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
+44
-254
@@ -10,98 +10,8 @@ use std::ptr;
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
const ABI_VERSION: u32 = 2;
|
||||
use marqdo_plugin_sdk::*;
|
||||
|
||||
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;
|
||||
|
||||
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>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<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())
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
macro_rules! q_ffi {
|
||||
($name:ident, $body:expr) => {
|
||||
@@ -880,166 +790,46 @@ fn parse_usize_list(v: &Value) -> Result<Vec<usize>, String> {
|
||||
}
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
let regs = [
|
||||
("quantum_ping", "", quantum_ping as PluginFn),
|
||||
(
|
||||
"quantum_circuit_new",
|
||||
"qubits,steps",
|
||||
quantum_circuit_new as PluginFn,
|
||||
),
|
||||
("quantum_h", "circuit,qubit", quantum_h as PluginFn),
|
||||
("quantum_x", "circuit,qubit", quantum_x as PluginFn),
|
||||
("quantum_y", "circuit,qubit", quantum_y as PluginFn),
|
||||
("quantum_z", "circuit,qubit", quantum_z as PluginFn),
|
||||
("quantum_s", "circuit,qubit", quantum_s as PluginFn),
|
||||
("quantum_t", "circuit,qubit", quantum_t as PluginFn),
|
||||
("quantum_i", "circuit,qubit", quantum_i as PluginFn),
|
||||
("quantum_rx", "circuit,qubit,theta", quantum_rx as PluginFn),
|
||||
("quantum_ry", "circuit,qubit,theta", quantum_ry as PluginFn),
|
||||
("quantum_rz", "circuit,qubit,theta", quantum_rz as PluginFn),
|
||||
(
|
||||
"quantum_cx",
|
||||
"circuit,control,target",
|
||||
quantum_cx as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_cz",
|
||||
"circuit,control,target",
|
||||
quantum_cz as PluginFn,
|
||||
),
|
||||
("quantum_swap", "circuit,a,b", quantum_swap as PluginFn),
|
||||
(
|
||||
"quantum_simulate",
|
||||
"circuit",
|
||||
quantum_simulate as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_probabilities",
|
||||
"circuit",
|
||||
quantum_probabilities as PluginFn,
|
||||
),
|
||||
("quantum_run", "circuit,shots,seed", quantum_run as PluginFn),
|
||||
("quantum_barrier", "circuit", quantum_barrier as PluginFn),
|
||||
(
|
||||
"quantum_measure",
|
||||
"circuit,qubits",
|
||||
quantum_measure as PluginFn,
|
||||
),
|
||||
("quantum_append", "circuit,op", quantum_append as PluginFn),
|
||||
("quantum_noise", "circuit,kind,p", quantum_noise as PluginFn),
|
||||
("quantum_state", "circuit", quantum_state as PluginFn),
|
||||
(
|
||||
"quantum_draw_circuit",
|
||||
"circuit,path,kind,qubit",
|
||||
quantum_draw_circuit as PluginFn,
|
||||
),
|
||||
// `matrix` is optional (custom unitary); omit from required bind list.
|
||||
("quantum_gate_new", "name,theta", quantum_gate_new as PluginFn),
|
||||
(
|
||||
"quantum_gate_from_matrix",
|
||||
"matrix",
|
||||
quantum_gate_from_matrix as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_gate_matrix",
|
||||
"gate",
|
||||
quantum_gate_matrix as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_gate_matches_matrix",
|
||||
"gate,matrix,tol",
|
||||
quantum_gate_matches_matrix as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_gate_draw",
|
||||
"gate,path,kind",
|
||||
quantum_gate_draw as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_apply",
|
||||
"circuit,gate,qubits",
|
||||
quantum_apply as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_from_state",
|
||||
"state",
|
||||
quantum_density_from_state as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_from_matrix",
|
||||
"matrix",
|
||||
quantum_density_from_matrix as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_matrix",
|
||||
"density",
|
||||
quantum_density_matrix as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_purity",
|
||||
"density",
|
||||
quantum_density_purity as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_partial_trace",
|
||||
"density,keep",
|
||||
quantum_density_partial_trace as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_eig",
|
||||
"density",
|
||||
quantum_density_eig as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_expect",
|
||||
"density,obs",
|
||||
quantum_density_expect as PluginFn,
|
||||
),
|
||||
(
|
||||
"quantum_density_draw",
|
||||
"density,path,kind",
|
||||
quantum_density_draw as PluginFn,
|
||||
),
|
||||
("quantum_kron", "a,b", quantum_kron as PluginFn),
|
||||
(
|
||||
"quantum_schmidt",
|
||||
"state,cut",
|
||||
quantum_schmidt as PluginFn,
|
||||
),
|
||||
("quantum_fidelity", "a,b", quantum_fidelity as PluginFn),
|
||||
];
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("quantum_ping", "", quantum_ping),
|
||||
("quantum_circuit_new", "qubits,steps", quantum_circuit_new),
|
||||
("quantum_h", "circuit,qubit", quantum_h),
|
||||
("quantum_x", "circuit,qubit", quantum_x),
|
||||
("quantum_y", "circuit,qubit", quantum_y),
|
||||
("quantum_z", "circuit,qubit", quantum_z),
|
||||
("quantum_s", "circuit,qubit", quantum_s),
|
||||
("quantum_t", "circuit,qubit", quantum_t),
|
||||
("quantum_i", "circuit,qubit", quantum_i),
|
||||
("quantum_rx", "circuit,qubit,theta", quantum_rx),
|
||||
("quantum_ry", "circuit,qubit,theta", quantum_ry),
|
||||
("quantum_rz", "circuit,qubit,theta", quantum_rz),
|
||||
("quantum_cx", "circuit,control,target", quantum_cx),
|
||||
("quantum_cz", "circuit,control,target", quantum_cz),
|
||||
("quantum_swap", "circuit,a,b", quantum_swap),
|
||||
("quantum_simulate", "circuit", quantum_simulate),
|
||||
("quantum_probabilities", "circuit", quantum_probabilities),
|
||||
("quantum_run", "circuit,shots,seed", quantum_run),
|
||||
("quantum_barrier", "circuit", quantum_barrier),
|
||||
("quantum_measure", "circuit,qubits", quantum_measure),
|
||||
("quantum_append", "circuit,op", quantum_append),
|
||||
("quantum_noise", "circuit,kind,p", quantum_noise),
|
||||
("quantum_state", "circuit", quantum_state),
|
||||
("quantum_draw_circuit", "circuit,path,kind,qubit", quantum_draw_circuit),
|
||||
("quantum_gate_new", "name,theta", quantum_gate_new),
|
||||
("quantum_gate_from_matrix", "matrix", quantum_gate_from_matrix),
|
||||
("quantum_gate_matrix", "gate", quantum_gate_matrix),
|
||||
("quantum_gate_matches_matrix", "gate,matrix,tol", quantum_gate_matches_matrix),
|
||||
("quantum_gate_draw", "gate,path,kind", quantum_gate_draw),
|
||||
("quantum_apply", "circuit,gate,qubits", quantum_apply),
|
||||
("quantum_density_from_state", "state", quantum_density_from_state),
|
||||
("quantum_density_from_matrix", "matrix", quantum_density_from_matrix),
|
||||
("quantum_density_matrix", "density", quantum_density_matrix),
|
||||
("quantum_density_purity", "density", quantum_density_purity),
|
||||
("quantum_density_partial_trace", "density,keep", quantum_density_partial_trace),
|
||||
("quantum_density_eig", "density", quantum_density_eig),
|
||||
("quantum_density_expect", "density,obs", quantum_density_expect),
|
||||
("quantum_density_draw", "density,path,kind", quantum_density_draw),
|
||||
("quantum_kron", "a,b", quantum_kron),
|
||||
("quantum_schmidt", "state,cut", quantum_schmidt),
|
||||
("quantum_fidelity", "a,b", quantum_fidelity),
|
||||
]);
|
||||
@@ -626,10 +626,12 @@ pub fn value_as_matrix(v: &Value) -> Result<(usize, Mat), String> {
|
||||
}
|
||||
|
||||
/// Helper for JSON amps list export (re-export style).
|
||||
#[allow(dead_code)] // kept: referenced by draw/JSON export paths in the host
|
||||
pub fn amps_json(amps: &[C]) -> Value {
|
||||
amps_to_json(amps)
|
||||
}
|
||||
|
||||
#[allow(dead_code)] // kept: referenced by draw/JSON export paths in the host
|
||||
pub fn density_map_insert_matrix(obj: &mut Map<String, Value>, rho: &Mat, dim: usize) {
|
||||
obj.insert(
|
||||
"matrix".into(),
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_web"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo web plugin (ABI v2) — HTTP, SQLite, page assemble"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "web"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "sync", "time", "signal"] }
|
||||
axum = { version = "0.8", features = ["ws", "json", "query", "multipart"] }
|
||||
tower-http = { version = "0.6", features = ["fs", "cors", "compression-gzip", "limit", "set-header", "trace", "propagate-header"] }
|
||||
rusqlite = { version = "0.32", features = ["bundled"] }
|
||||
tokio-tungstenite = "0.24"
|
||||
futures-util = "0.3"
|
||||
argon2 = "0.5"
|
||||
getrandom = "0.2"
|
||||
pulldown-cmark = "0.12"
|
||||
postgres = { version = "0.19", features = ["with-serde_json-1"] }
|
||||
redis = { version = "0.27", default-features = true }
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls"] }
|
||||
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream", "json"] }
|
||||
bytes = "1"
|
||||
hmac = "0.12"
|
||||
sha2 = "0.10"
|
||||
hex = "0.4"
|
||||
@@ -1,9 +0,0 @@
|
||||
# web-rust-archive
|
||||
|
||||
Former Rust/axum implementation of the Marqdo web plugin (`marqdo_plugin_web`).
|
||||
|
||||
**Status (W-G13):** archived reference only. The official plugin is Go under
|
||||
[`plugins/web/`](../web/). This crate is **not** a Cargo workspace member and is
|
||||
not built by CI or `marqdo ext add web`.
|
||||
|
||||
Do not evolve features here — see [ext-web-go-rewrite.md](../../doc/design/ext-web-go-rewrite.md) C5 / ADR 0004.
|
||||
@@ -1,607 +0,0 @@
|
||||
//! Site icons, `<head>` link/script assembly, and image HTML assembly.
|
||||
//! Tables stay data; assembly is a function — 配置即数据、装配即函数.
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use crate::table::normalize_ref;
|
||||
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct HeadLink {
|
||||
pub rel: String,
|
||||
pub href: String,
|
||||
pub type_: String,
|
||||
pub sizes: String,
|
||||
pub media: String,
|
||||
pub as_: String,
|
||||
pub crossorigin: String,
|
||||
/// When `Some(true)`, emit `defer` on classic scripts (not modules).
|
||||
pub defer: Option<bool>,
|
||||
pub async_: bool,
|
||||
/// Query `?v=` bump for cache busting.
|
||||
pub version: String,
|
||||
}
|
||||
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct IconRoute {
|
||||
pub url: String,
|
||||
pub path: PathBuf,
|
||||
pub content_type: String,
|
||||
}
|
||||
|
||||
fn cell_str(v: &Value) -> String {
|
||||
match v {
|
||||
Value::Null => String::new(),
|
||||
Value::String(s) => s.clone(),
|
||||
Value::Bool(b) => b.to_string(),
|
||||
Value::Number(n) => n.to_string(),
|
||||
other => other.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
fn pick<'a>(m: &'a Map<String, Value>, keys: &[&str]) -> Option<&'a Value> {
|
||||
keys.iter().find_map(|k| m.get(*k))
|
||||
}
|
||||
|
||||
fn cell_boolish(v: &Value) -> Option<bool> {
|
||||
match v {
|
||||
Value::Bool(b) => Some(*b),
|
||||
Value::Number(n) => Some(n.as_i64().unwrap_or(0) != 0),
|
||||
Value::String(s) => {
|
||||
let s = s.trim();
|
||||
if s.is_empty() {
|
||||
return None;
|
||||
}
|
||||
if matches!(
|
||||
s,
|
||||
"1" | "true" | "True" | "yes" | "on" | "真" | "是"
|
||||
) {
|
||||
Some(true)
|
||||
} else if matches!(
|
||||
s,
|
||||
"0" | "false" | "False" | "no" | "off" | "假" | "否"
|
||||
) {
|
||||
Some(false)
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn row_bool(m: &Map<String, Value>, keys: &[&str]) -> Option<bool> {
|
||||
pick(m, keys).and_then(cell_boolish)
|
||||
}
|
||||
|
||||
fn row_str(m: &Map<String, Value>, keys: &[&str]) -> String {
|
||||
pick(m, keys)
|
||||
.map(|v| normalize_ref(&cell_str(v)))
|
||||
.unwrap_or_default()
|
||||
.trim()
|
||||
.to_string()
|
||||
}
|
||||
|
||||
/// Append `?v=` / `&v=` for cache busting.
|
||||
pub fn href_with_version(href: &str, version: &str) -> String {
|
||||
let version = version.trim();
|
||||
if version.is_empty() {
|
||||
return href.to_string();
|
||||
}
|
||||
if href.contains('?') {
|
||||
format!("{href}&v={version}")
|
||||
} else {
|
||||
format!("{href}?v={version}")
|
||||
}
|
||||
}
|
||||
|
||||
fn esc(s: &str) -> String {
|
||||
s.replace('&', "&")
|
||||
.replace('<', "<")
|
||||
.replace('>', ">")
|
||||
.replace('"', """)
|
||||
}
|
||||
|
||||
/// Infer Content-Type from file extension.
|
||||
pub fn mime_for_path(path: &str) -> &'static str {
|
||||
let lower = path.to_ascii_lowercase();
|
||||
if lower.ends_with(".ico") {
|
||||
"image/x-icon"
|
||||
} else if lower.ends_with(".png") {
|
||||
"image/png"
|
||||
} else if lower.ends_with(".svg") {
|
||||
"image/svg+xml"
|
||||
} else if lower.ends_with(".webp") {
|
||||
"image/webp"
|
||||
} else if lower.ends_with(".jpg") || lower.ends_with(".jpeg") {
|
||||
"image/jpeg"
|
||||
} else if lower.ends_with(".gif") {
|
||||
"image/gif"
|
||||
} else if lower.ends_with(".webmanifest") || lower.ends_with(".json") {
|
||||
"application/manifest+json"
|
||||
} else if lower.ends_with(".css") {
|
||||
"text/css; charset=utf-8"
|
||||
} else if lower.ends_with(".js") || lower.ends_with(".mjs") {
|
||||
"text/javascript; charset=utf-8"
|
||||
} else {
|
||||
"application/octet-stream"
|
||||
}
|
||||
}
|
||||
|
||||
fn rows_of(table: &Value) -> Vec<Map<String, Value>> {
|
||||
match table {
|
||||
Value::Array(a) => a
|
||||
.iter()
|
||||
.filter_map(|v| v.as_object().cloned())
|
||||
.collect(),
|
||||
Value::Object(m) => {
|
||||
// Columnar GFM: { 关系: […], 地址: […] }
|
||||
let keys: Vec<String> = m.keys().cloned().collect();
|
||||
if keys.is_empty() {
|
||||
return Vec::new();
|
||||
}
|
||||
let len = m
|
||||
.values()
|
||||
.filter_map(|v| v.as_array().map(|a| a.len()))
|
||||
.max()
|
||||
.unwrap_or(0);
|
||||
if len == 0 {
|
||||
return vec![m.clone()];
|
||||
}
|
||||
let mut out = Vec::with_capacity(len);
|
||||
for i in 0..len {
|
||||
let mut row = Map::new();
|
||||
for k in &keys {
|
||||
if let Some(Value::Array(a)) = m.get(k) {
|
||||
row.insert(k.clone(), a.get(i).cloned().unwrap_or(Value::Null));
|
||||
} else if i == 0 {
|
||||
row.insert(k.clone(), m.get(k).cloned().unwrap_or(Value::Null));
|
||||
}
|
||||
}
|
||||
out.push(row);
|
||||
}
|
||||
out
|
||||
}
|
||||
_ => Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Normalize a Head resource table → list of HeadLink.
|
||||
pub fn as_head_links(table: &Value) -> Vec<HeadLink> {
|
||||
let mut out = Vec::new();
|
||||
for m in rows_of(table) {
|
||||
let rel = row_str(&m, &["关系", "rel", "Rel"]);
|
||||
let href = row_str(
|
||||
&m,
|
||||
&["地址", "href", "src", "url", "Href", "Src", "URL"],
|
||||
);
|
||||
if href.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let rel = if rel.is_empty() {
|
||||
"stylesheet".into()
|
||||
} else {
|
||||
rel
|
||||
};
|
||||
out.push(HeadLink {
|
||||
rel,
|
||||
href,
|
||||
type_: row_str(&m, &["类型", "type", "Type"]),
|
||||
sizes: row_str(&m, &["尺寸", "sizes", "Sizes"]),
|
||||
media: row_str(&m, &["媒体", "media", "Media"]),
|
||||
as_: row_str(&m, &["作为", "as", "As"]),
|
||||
crossorigin: row_str(&m, &["跨域", "crossorigin", "crossOrigin"]),
|
||||
defer: row_bool(&m, &["推迟", "defer", "Defer"]),
|
||||
async_: row_bool(&m, &["异步", "async", "Async"]).unwrap_or(false),
|
||||
version: row_str(&m, &["版本", "version", "Version", "v"]),
|
||||
});
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn head_links_to_json(links: &[HeadLink]) -> Value {
|
||||
Value::Array(
|
||||
links
|
||||
.iter()
|
||||
.map(|l| {
|
||||
let mut o = json!({
|
||||
"rel": l.rel,
|
||||
"href": l.href,
|
||||
"type": l.type_,
|
||||
"sizes": l.sizes,
|
||||
"media": l.media,
|
||||
"as": l.as_,
|
||||
"crossorigin": l.crossorigin,
|
||||
"async": l.async_,
|
||||
"version": l.version,
|
||||
});
|
||||
if let Some(d) = l.defer {
|
||||
o.as_object_mut()
|
||||
.unwrap()
|
||||
.insert("defer".into(), json!(d));
|
||||
}
|
||||
o
|
||||
})
|
||||
.collect(),
|
||||
)
|
||||
}
|
||||
|
||||
pub fn head_links_from_json(v: &Value) -> Vec<HeadLink> {
|
||||
let Some(arr) = v.as_array() else {
|
||||
return as_head_links(v);
|
||||
};
|
||||
let mut out = Vec::new();
|
||||
for item in arr {
|
||||
let Some(m) = item.as_object() else {
|
||||
continue;
|
||||
};
|
||||
let href = row_str(m, &["href", "src", "url", "地址"]);
|
||||
if href.is_empty() {
|
||||
continue;
|
||||
}
|
||||
out.push(HeadLink {
|
||||
rel: row_str(m, &["rel", "关系"]),
|
||||
href,
|
||||
type_: row_str(m, &["type", "类型"]),
|
||||
sizes: row_str(m, &["sizes", "尺寸"]),
|
||||
media: row_str(m, &["media", "媒体"]),
|
||||
as_: row_str(m, &["as", "作为"]),
|
||||
crossorigin: row_str(m, &["crossorigin", "跨域"]),
|
||||
defer: row_bool(m, &["defer", "推迟"]),
|
||||
async_: row_bool(m, &["async", "异步"]).unwrap_or(false),
|
||||
version: row_str(m, &["version", "版本", "v"]),
|
||||
});
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Render HeadLink list to HTML (link / script tags).
|
||||
pub fn render_head_links(links: &[HeadLink]) -> String {
|
||||
render_head_links_with_version(links, "")
|
||||
}
|
||||
|
||||
pub fn render_head_links_with_version(links: &[HeadLink], asset_version: &str) -> String {
|
||||
let mut s = String::new();
|
||||
for l in links {
|
||||
let rel = l.rel.trim().to_ascii_lowercase();
|
||||
let ver = if !l.version.trim().is_empty() {
|
||||
l.version.as_str()
|
||||
} else {
|
||||
asset_version
|
||||
};
|
||||
let href = href_with_version(&l.href, ver);
|
||||
if rel == "script" || rel == "module" {
|
||||
let mut tag = String::from("<script");
|
||||
let is_module = rel == "module" || l.type_ == "module";
|
||||
if is_module {
|
||||
tag.push_str(" type=\"module\"");
|
||||
} else if !l.type_.is_empty() {
|
||||
tag.push_str(&format!(" type=\"{}\"", esc(&l.type_)));
|
||||
}
|
||||
// Modules are deferred by browsers; classic scripts honor explicit defer.
|
||||
if !is_module && l.defer == Some(true) {
|
||||
tag.push_str(" defer");
|
||||
}
|
||||
if l.async_ {
|
||||
tag.push_str(" async");
|
||||
}
|
||||
if !l.crossorigin.is_empty() {
|
||||
tag.push_str(&format!(" crossorigin=\"{}\"", esc(&l.crossorigin)));
|
||||
}
|
||||
tag.push_str(&format!(" src=\"{}\"></script>", esc(&href)));
|
||||
s.push_str(&tag);
|
||||
continue;
|
||||
}
|
||||
let mut tag = format!("<link rel=\"{}\" href=\"{}\"", esc(&l.rel), esc(&href));
|
||||
if !l.type_.is_empty() {
|
||||
tag.push_str(&format!(" type=\"{}\"", esc(&l.type_)));
|
||||
}
|
||||
if !l.sizes.is_empty() {
|
||||
tag.push_str(&format!(" sizes=\"{}\"", esc(&l.sizes)));
|
||||
}
|
||||
if !l.media.is_empty() {
|
||||
tag.push_str(&format!(" media=\"{}\"", esc(&l.media)));
|
||||
}
|
||||
if !l.as_.is_empty() {
|
||||
tag.push_str(&format!(" as=\"{}\"", esc(&l.as_)));
|
||||
}
|
||||
if !l.crossorigin.is_empty() {
|
||||
tag.push_str(&format!(" crossorigin=\"{}\"", esc(&l.crossorigin)));
|
||||
}
|
||||
tag.push_str("/>");
|
||||
s.push_str(&tag);
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
/// Module-level preview: assemble head table → HTML string.
|
||||
pub fn make_head_html(table: &Value) -> String {
|
||||
render_head_links(&as_head_links(table))
|
||||
}
|
||||
|
||||
/// Normalize icons table → (icons json array, site_head links, file routes).
|
||||
pub fn normalize_icons(table: &Value) -> (Value, Vec<HeadLink>, Vec<IconRoute>) {
|
||||
let mut icons = Vec::new();
|
||||
let mut head = Vec::new();
|
||||
let mut routes = Vec::new();
|
||||
let mut saw_favicon_url = false;
|
||||
|
||||
for m in rows_of(table) {
|
||||
let path = row_str(&m, &["路径", "path", "file", "Path"]);
|
||||
let mut rel = row_str(&m, &["关系", "rel", "Rel"]);
|
||||
if rel.is_empty() {
|
||||
rel = "icon".into();
|
||||
}
|
||||
let mut type_ = row_str(&m, &["类型", "type", "Type"]);
|
||||
let sizes = row_str(&m, &["尺寸", "sizes", "Sizes"]);
|
||||
let mut url = row_str(&m, &["地址", "url", "href", "Href", "URL"]);
|
||||
|
||||
if type_.is_empty() && !path.is_empty() {
|
||||
type_ = mime_for_path(&path).to_string();
|
||||
}
|
||||
if url.is_empty() {
|
||||
if !path.is_empty() {
|
||||
let name = Path::new(&path)
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("icon");
|
||||
let lower = path.to_ascii_lowercase();
|
||||
if rel.to_ascii_lowercase().contains("icon") && lower.ends_with(".ico") {
|
||||
url = "/favicon.ico".into();
|
||||
} else {
|
||||
url = format!("/icons/{name}");
|
||||
}
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
if url == "/favicon.ico" {
|
||||
saw_favicon_url = true;
|
||||
}
|
||||
|
||||
icons.push(json!({
|
||||
"path": path,
|
||||
"rel": rel,
|
||||
"type": type_,
|
||||
"sizes": sizes,
|
||||
"url": url,
|
||||
}));
|
||||
|
||||
if !url.is_empty() {
|
||||
head.push(HeadLink {
|
||||
rel: rel.clone(),
|
||||
href: url.clone(),
|
||||
type_: type_.clone(),
|
||||
sizes: sizes.clone(),
|
||||
media: String::new(),
|
||||
as_: String::new(),
|
||||
crossorigin: String::new(),
|
||||
defer: None,
|
||||
async_: false,
|
||||
version: String::new(),
|
||||
});
|
||||
}
|
||||
|
||||
if !path.is_empty() && !url.is_empty() {
|
||||
routes.push(IconRoute {
|
||||
url: url.clone(),
|
||||
path: PathBuf::from(&path),
|
||||
content_type: if type_.is_empty() {
|
||||
mime_for_path(&path).to_string()
|
||||
} else {
|
||||
type_.clone()
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Ensure browser default path if we have an icon file but no /favicon.ico.
|
||||
if !saw_favicon_url {
|
||||
if let Some(first) = icons.iter().find(|v| {
|
||||
v.get("rel")
|
||||
.and_then(|r| r.as_str())
|
||||
.map(|r| r.to_ascii_lowercase().contains("icon"))
|
||||
.unwrap_or(false)
|
||||
&& v.get("path")
|
||||
.and_then(|p| p.as_str())
|
||||
.map(|p| !p.is_empty())
|
||||
.unwrap_or(false)
|
||||
}) {
|
||||
let path = first.get("path").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let type_ = first
|
||||
.get("type")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or_else(|| mime_for_path(path));
|
||||
routes.push(IconRoute {
|
||||
url: "/favicon.ico".into(),
|
||||
path: PathBuf::from(path),
|
||||
content_type: type_.to_string(),
|
||||
});
|
||||
head.insert(
|
||||
0,
|
||||
HeadLink {
|
||||
rel: "icon".into(),
|
||||
href: "/favicon.ico".into(),
|
||||
type_: type_.to_string(),
|
||||
sizes: first
|
||||
.get("sizes")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string(),
|
||||
media: String::new(),
|
||||
as_: String::new(),
|
||||
crossorigin: String::new(),
|
||||
defer: None,
|
||||
async_: false,
|
||||
version: String::new(),
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
(Value::Array(icons), head, routes)
|
||||
}
|
||||
|
||||
/// Convention: if static_dir has favicon.ico|png|svg and icons empty, register defaults.
|
||||
pub fn convention_favicon(static_dir: &Path) -> Option<(Vec<HeadLink>, Vec<IconRoute>)> {
|
||||
for name in ["favicon.ico", "favicon.png", "favicon.svg"] {
|
||||
let p = static_dir.join(name);
|
||||
if p.is_file() {
|
||||
let ct = mime_for_path(name).to_string();
|
||||
let head = vec![HeadLink {
|
||||
rel: "icon".into(),
|
||||
href: "/favicon.ico".into(),
|
||||
type_: ct.clone(),
|
||||
sizes: String::new(),
|
||||
media: String::new(),
|
||||
as_: String::new(),
|
||||
crossorigin: String::new(),
|
||||
defer: None,
|
||||
async_: false,
|
||||
version: String::new(),
|
||||
}];
|
||||
let routes = vec![IconRoute {
|
||||
url: "/favicon.ico".into(),
|
||||
path: p,
|
||||
content_type: ct,
|
||||
}];
|
||||
return Some((head, routes));
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
/// Merge site_head into a page value (dedupe by href+rel).
|
||||
pub fn merge_site_head(page: &mut Value, site_head: &[HeadLink]) {
|
||||
if site_head.is_empty() {
|
||||
return;
|
||||
}
|
||||
let obj = match page.as_object_mut() {
|
||||
Some(o) => o,
|
||||
None => return,
|
||||
};
|
||||
let mut existing = obj
|
||||
.get("head")
|
||||
.map(head_links_from_json)
|
||||
.unwrap_or_default();
|
||||
for link in site_head {
|
||||
let dup = existing.iter().any(|e| {
|
||||
e.href == link.href && e.rel.eq_ignore_ascii_case(&link.rel)
|
||||
});
|
||||
if !dup {
|
||||
existing.push(link.clone());
|
||||
}
|
||||
}
|
||||
obj.insert("head".into(), head_links_to_json(&existing));
|
||||
}
|
||||
|
||||
/// GFM image table → HTML fragment.
|
||||
pub fn make_images_html(table: &Value) -> String {
|
||||
let mut figures = String::new();
|
||||
for m in rows_of(table) {
|
||||
let src = row_str(&m, &["源", "src", "Src", "url", "URL"]);
|
||||
if src.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let alt = row_str(&m, &["替代", "alt", "Alt"]);
|
||||
let title = row_str(&m, &["标题", "title", "Title"]);
|
||||
let class = row_str(&m, &["类", "class", "Class"]);
|
||||
let href = row_str(&m, &["链接", "href", "link", "Href", "Link"]);
|
||||
let width = row_str(&m, &["宽度", "width", "Width"]);
|
||||
let height = row_str(&m, &["高度", "height", "Height"]);
|
||||
let mut loading = row_str(&m, &["加载", "loading", "Loading"]);
|
||||
if loading.is_empty() {
|
||||
loading = "lazy".into();
|
||||
}
|
||||
let caption = row_str(&m, &["图注", "caption", "Caption"]);
|
||||
|
||||
let mut img = format!("<img src=\"{}\" alt=\"{}\"", esc(&src), esc(&alt));
|
||||
if !title.is_empty() {
|
||||
img.push_str(&format!(" title=\"{}\"", esc(&title)));
|
||||
}
|
||||
if !width.is_empty() {
|
||||
img.push_str(&format!(" width=\"{}\"", esc(&width)));
|
||||
}
|
||||
if !height.is_empty() {
|
||||
img.push_str(&format!(" height=\"{}\"", esc(&height)));
|
||||
}
|
||||
img.push_str(&format!(" loading=\"{}\"/>", esc(&loading)));
|
||||
|
||||
let inner = if href.is_empty() {
|
||||
img
|
||||
} else {
|
||||
format!("<a href=\"{}\">{}</a>", esc(&href), img)
|
||||
};
|
||||
|
||||
let fig_class = if class.is_empty() {
|
||||
"mq-img".into()
|
||||
} else {
|
||||
format!("mq-img {}", class)
|
||||
};
|
||||
figures.push_str(&format!("<figure class=\"{}\">{}", fig_class, inner));
|
||||
if !caption.is_empty() {
|
||||
figures.push_str(&format!("<figcaption>{}</figcaption>", esc(&caption)));
|
||||
}
|
||||
figures.push_str("</figure>");
|
||||
}
|
||||
if figures.is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
format!("<div class=\"mq-images\" data-slot=\"main\">{figures}</div>")
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::json;
|
||||
|
||||
#[test]
|
||||
fn images_basic() {
|
||||
let t = json!([
|
||||
{"源": "/a.png", "替代": "A", "类": "logo", "加载": "eager"}
|
||||
]);
|
||||
let h = make_images_html(&t);
|
||||
assert!(h.contains("mq-images"));
|
||||
assert!(h.contains("src=\"/a.png\""));
|
||||
assert!(h.contains("loading=\"eager\""));
|
||||
assert!(h.contains("class=\"mq-img logo\""));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn head_script_and_icon() {
|
||||
let t = json!([
|
||||
{"关系": "icon", "地址": "/favicon.ico", "类型": "image/x-icon"},
|
||||
{"关系": "script", "地址": "/static/a.js"}
|
||||
]);
|
||||
let h = make_head_html(&t);
|
||||
assert!(h.contains("rel=\"icon\""));
|
||||
assert!(h.contains("<script src=\"/static/a.js\"></script>"));
|
||||
assert!(!h.contains(" defer"), "{h}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn head_script_defer_async_version() {
|
||||
let t = json!([
|
||||
{"关系": "script", "地址": "/static/a.js", "推迟": true, "版本": "3"},
|
||||
{"关系": "module", "地址": "/static/b.js", "版本": "9"},
|
||||
{"关系": "stylesheet", "地址": "/static/t.css", "版本": "1"},
|
||||
]);
|
||||
let h = make_head_html(&t);
|
||||
assert!(h.contains("<script defer src=\"/static/a.js?v=3\"></script>"), "{h}");
|
||||
assert!(h.contains("type=\"module\""), "{h}");
|
||||
assert!(h.contains("src=\"/static/b.js?v=9\""), "{h}");
|
||||
assert!(h.contains("href=\"/static/t.css?v=1\""), "{h}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn head_asset_version_fallback() {
|
||||
let links = as_head_links(&json!([
|
||||
{"关系": "script", "地址": "/static/a.js", "推迟": "真"},
|
||||
]));
|
||||
let h = render_head_links_with_version(&links, "2026-09-04");
|
||||
assert!(
|
||||
h.contains("<script defer src=\"/static/a.js?v=2026-09-04\"></script>"),
|
||||
"{h}"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -1,242 +0,0 @@
|
||||
//! `# cache` — Redis or in-process memory (design ext-web-drivers).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Mutex;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
struct Entry {
|
||||
value: String,
|
||||
/// Absolute expiry unix secs; `None` = no TTL.
|
||||
exp: Option<u64>,
|
||||
}
|
||||
|
||||
struct MemStore {
|
||||
data: HashMap<String, Entry>,
|
||||
}
|
||||
|
||||
enum Backend {
|
||||
Memory(MemStore),
|
||||
/// Redis URL — connections opened per call (simple; enough for W4).
|
||||
RedisUrl(String),
|
||||
}
|
||||
|
||||
static HANDLES: Mutex<Option<HashMap<String, Backend>>> = Mutex::new(None);
|
||||
|
||||
fn now() -> u64 {
|
||||
SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|d| d.as_secs())
|
||||
.unwrap_or(0)
|
||||
}
|
||||
|
||||
fn with_map<T>(f: impl FnOnce(&mut HashMap<String, Backend>) -> T) -> T {
|
||||
let mut g = HANDLES.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let m = g.get_or_insert_with(HashMap::new);
|
||||
f(m)
|
||||
}
|
||||
|
||||
fn is_memory(url: &str) -> bool {
|
||||
let u = url.trim().to_ascii_lowercase();
|
||||
u.is_empty() || u == "memory:" || u == "memory://" || u.starts_with("memory:")
|
||||
}
|
||||
|
||||
fn is_redis(url: &str) -> bool {
|
||||
let u = url.trim().to_ascii_lowercase();
|
||||
u.starts_with("redis://") || u.starts_with("rediss://")
|
||||
}
|
||||
|
||||
/// Open (or reuse) a cache handle. Returns `{ _type, url }`.
|
||||
pub fn open(url: &str) -> Result<Value, String> {
|
||||
let url = if url.trim().is_empty() {
|
||||
"memory:"
|
||||
} else {
|
||||
url.trim()
|
||||
};
|
||||
if !is_memory(url) && !is_redis(url) {
|
||||
return Err(format!(
|
||||
"cache url must be `memory:` or `redis://…`, got `{url}`"
|
||||
));
|
||||
}
|
||||
with_map(|m| {
|
||||
if !m.contains_key(url) {
|
||||
let backend = if is_memory(url) {
|
||||
Backend::Memory(MemStore {
|
||||
data: HashMap::new(),
|
||||
})
|
||||
} else {
|
||||
Backend::RedisUrl(url.to_string())
|
||||
};
|
||||
m.insert(url.to_string(), backend);
|
||||
}
|
||||
});
|
||||
Ok(json!({ "_type": "cache", "url": url }))
|
||||
}
|
||||
|
||||
fn prune_mem(store: &mut MemStore) {
|
||||
let t = now();
|
||||
store.data.retain(|_, e| e.exp.map(|x| x > t).unwrap_or(true));
|
||||
}
|
||||
|
||||
fn with_backend<T>(url: &str, f: impl FnOnce(&mut Backend) -> Result<T, String>) -> Result<T, String> {
|
||||
with_map(|m| {
|
||||
let b = m
|
||||
.get_mut(url)
|
||||
.ok_or_else(|| format!("cache `{url}` not opened — call cache.new first"))?;
|
||||
f(b)
|
||||
})
|
||||
}
|
||||
|
||||
pub fn get(url: &str, key: &str) -> Result<Value, String> {
|
||||
with_backend(url, |b| match b {
|
||||
Backend::Memory(store) => {
|
||||
prune_mem(store);
|
||||
match store.data.get(key) {
|
||||
Some(e) => Ok(json!({ "ok": true, "value": e.value })),
|
||||
None => Ok(json!({ "ok": false })),
|
||||
}
|
||||
}
|
||||
Backend::RedisUrl(u) => redis_get(u, key),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn set(url: &str, key: &str, value: &str, ttl_sec: Option<u64>) -> Result<Value, String> {
|
||||
with_backend(url, |b| match b {
|
||||
Backend::Memory(store) => {
|
||||
prune_mem(store);
|
||||
let exp = ttl_sec.filter(|t| *t > 0).map(|t| now() + t);
|
||||
store.data.insert(
|
||||
key.to_string(),
|
||||
Entry {
|
||||
value: value.to_string(),
|
||||
exp,
|
||||
},
|
||||
);
|
||||
Ok(json!({ "ok": true }))
|
||||
}
|
||||
Backend::RedisUrl(u) => redis_set(u, key, value, ttl_sec),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn del(url: &str, key: &str) -> Result<Value, String> {
|
||||
with_backend(url, |b| match b {
|
||||
Backend::Memory(store) => {
|
||||
let ok = store.data.remove(key).is_some();
|
||||
Ok(json!({ "ok": ok }))
|
||||
}
|
||||
Backend::RedisUrl(u) => redis_del(u, key),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn exists(url: &str, key: &str) -> Result<Value, String> {
|
||||
with_backend(url, |b| match b {
|
||||
Backend::Memory(store) => {
|
||||
prune_mem(store);
|
||||
Ok(json!({ "ok": store.data.contains_key(key) }))
|
||||
}
|
||||
Backend::RedisUrl(u) => redis_exists(u, key),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn ttl(url: &str, key: &str) -> Result<Value, String> {
|
||||
with_backend(url, |b| match b {
|
||||
Backend::Memory(store) => {
|
||||
prune_mem(store);
|
||||
match store.data.get(key) {
|
||||
Some(e) => {
|
||||
let left = match e.exp {
|
||||
Some(x) => x.saturating_sub(now()) as i64,
|
||||
None => -1,
|
||||
};
|
||||
Ok(json!({ "ok": true, "ttl": left }))
|
||||
}
|
||||
None => Ok(json!({ "ok": false, "ttl": -2 })),
|
||||
}
|
||||
}
|
||||
Backend::RedisUrl(u) => redis_ttl(u, key),
|
||||
})
|
||||
}
|
||||
|
||||
fn redis_get(url: &str, key: &str) -> Result<Value, String> {
|
||||
let client = redis::Client::open(url).map_err(|e| e.to_string())?;
|
||||
let mut con = client.get_connection().map_err(|e| e.to_string())?;
|
||||
let v: Option<String> = redis::cmd("GET")
|
||||
.arg(key)
|
||||
.query(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
match v {
|
||||
Some(s) => Ok(json!({ "ok": true, "value": s })),
|
||||
None => Ok(json!({ "ok": false })),
|
||||
}
|
||||
}
|
||||
|
||||
fn redis_set(url: &str, key: &str, value: &str, ttl_sec: Option<u64>) -> Result<Value, String> {
|
||||
let client = redis::Client::open(url).map_err(|e| e.to_string())?;
|
||||
let mut con = client.get_connection().map_err(|e| e.to_string())?;
|
||||
match ttl_sec.filter(|t| *t > 0) {
|
||||
Some(t) => {
|
||||
redis::cmd("SETEX")
|
||||
.arg(key)
|
||||
.arg(t)
|
||||
.arg(value)
|
||||
.query::<()>(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
}
|
||||
None => {
|
||||
redis::cmd("SET")
|
||||
.arg(key)
|
||||
.arg(value)
|
||||
.query::<()>(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
}
|
||||
}
|
||||
Ok(json!({ "ok": true }))
|
||||
}
|
||||
|
||||
fn redis_del(url: &str, key: &str) -> Result<Value, String> {
|
||||
let client = redis::Client::open(url).map_err(|e| e.to_string())?;
|
||||
let mut con = client.get_connection().map_err(|e| e.to_string())?;
|
||||
let n: i64 = redis::cmd("DEL")
|
||||
.arg(key)
|
||||
.query(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
Ok(json!({ "ok": n > 0 }))
|
||||
}
|
||||
|
||||
fn redis_exists(url: &str, key: &str) -> Result<Value, String> {
|
||||
let client = redis::Client::open(url).map_err(|e| e.to_string())?;
|
||||
let mut con = client.get_connection().map_err(|e| e.to_string())?;
|
||||
let n: i64 = redis::cmd("EXISTS")
|
||||
.arg(key)
|
||||
.query(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
Ok(json!({ "ok": n > 0 }))
|
||||
}
|
||||
|
||||
fn redis_ttl(url: &str, key: &str) -> Result<Value, String> {
|
||||
let client = redis::Client::open(url).map_err(|e| e.to_string())?;
|
||||
let mut con = client.get_connection().map_err(|e| e.to_string())?;
|
||||
let t: i64 = redis::cmd("TTL")
|
||||
.arg(key)
|
||||
.query(&mut con)
|
||||
.map_err(|e| e.to_string())?;
|
||||
Ok(json!({ "ok": t >= -1, "ttl": t }))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn memory_roundtrip() {
|
||||
let url = "memory:test-cache";
|
||||
open(url).unwrap();
|
||||
set(url, "a", "1", Some(60)).unwrap();
|
||||
let g = get(url, "a").unwrap();
|
||||
assert_eq!(g["ok"], true);
|
||||
assert_eq!(g["value"], "1");
|
||||
assert_eq!(exists(url, "a").unwrap()["ok"], true);
|
||||
del(url, "a").unwrap();
|
||||
assert_eq!(get(url, "a").unwrap()["ok"], false);
|
||||
}
|
||||
}
|
||||
@@ -1,248 +0,0 @@
|
||||
//! Page assemble: compose_components / compose_main.
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
use crate::table::{
|
||||
as_bind, as_compose, as_css_named, bind_table_name, normalize_ref, normalize_slot,
|
||||
parse_site_path, SitePath,
|
||||
};
|
||||
|
||||
pub fn compose_components(
|
||||
page: &Value,
|
||||
layout: &Value,
|
||||
mut call_lib: impl FnMut(&str) -> Result<Value, String>,
|
||||
) -> Result<Value, String> {
|
||||
let mut obj = page.as_object().cloned().unwrap_or_default();
|
||||
let rows = as_compose(layout);
|
||||
let mut css = obj
|
||||
.get("styles_css")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let mut slot_class = obj
|
||||
.get("slot_class")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let mut parts = Map::new();
|
||||
let mut compose_out = Vec::new();
|
||||
|
||||
for row in rows.as_array().cloned().unwrap_or_default() {
|
||||
let src_raw = row.get("src").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let style_raw = row.get("style").and_then(|v| v.as_str()).unwrap_or("");
|
||||
if src_raw.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let (name, bind_table) = match parse_site_path(src_raw) {
|
||||
SitePath::LibMember { lib, member } => {
|
||||
let t = call_lib(&format!("{lib}.{member}"))?;
|
||||
(member, t)
|
||||
}
|
||||
SitePath::Plain(s) => {
|
||||
let t = call_lib(&format!("{s}.{s}"))?;
|
||||
(s, t)
|
||||
}
|
||||
SitePath::DbField { .. } => {
|
||||
return Err(format!("component cell cannot be a db field: {src_raw}"));
|
||||
}
|
||||
};
|
||||
let slot = normalize_slot(&name);
|
||||
let style_name = if style_raw.is_empty() {
|
||||
String::new()
|
||||
} else {
|
||||
match parse_site_path(style_raw) {
|
||||
SitePath::LibMember { lib, member } => {
|
||||
let st = call_lib(&format!("{lib}.{member}"))?;
|
||||
css.push_str(&as_css_named(&member, &st));
|
||||
member
|
||||
}
|
||||
SitePath::Plain(s) => s,
|
||||
SitePath::DbField { .. } => normalize_ref(style_raw),
|
||||
}
|
||||
};
|
||||
let binds = as_bind(&bind_table);
|
||||
match slot.as_str() {
|
||||
"nav" => obj.insert("nav".into(), binds.clone()),
|
||||
"sidebar" => obj.insert("sidebar".into(), binds.clone()),
|
||||
"footer" => obj.insert("footer".into(), binds.clone()),
|
||||
_ => obj.insert("main".into(), binds.clone()),
|
||||
};
|
||||
if !style_name.is_empty() {
|
||||
slot_class.insert(slot.clone(), json!(style_name));
|
||||
}
|
||||
compose_out.push(json!({ "src": name, "style": style_name, "slot": slot }));
|
||||
|
||||
let mut part = Map::new();
|
||||
part.insert("_type".into(), json!("page"));
|
||||
part.insert("slot".into(), json!(slot));
|
||||
part.insert("fragment".into(), json!(slot));
|
||||
match slot.as_str() {
|
||||
"nav" => {
|
||||
part.insert("nav".into(), binds);
|
||||
}
|
||||
"sidebar" => {
|
||||
part.insert("sidebar".into(), binds);
|
||||
}
|
||||
"footer" => {
|
||||
part.insert("footer".into(), binds);
|
||||
}
|
||||
_ => {
|
||||
part.insert("main".into(), binds);
|
||||
}
|
||||
}
|
||||
parts.insert(name, Value::Object(part));
|
||||
}
|
||||
|
||||
obj.insert("compose".into(), Value::Array(compose_out));
|
||||
if !css.is_empty() {
|
||||
obj.insert("styles_css".into(), json!(css));
|
||||
}
|
||||
if !slot_class.is_empty() {
|
||||
obj.insert("slot_class".into(), Value::Object(slot_class));
|
||||
}
|
||||
if !parts.is_empty() {
|
||||
obj.insert("parts".into(), Value::Object(parts));
|
||||
}
|
||||
Ok(Value::Object(obj))
|
||||
}
|
||||
|
||||
pub fn compose_main(
|
||||
page: &Value,
|
||||
main_table: &Value,
|
||||
mut call_lib: impl FnMut(&str) -> Result<Value, String>,
|
||||
) -> Result<Value, String> {
|
||||
let mut obj = page.as_object().cloned().unwrap_or_default();
|
||||
let raw = as_bind(main_table);
|
||||
let arr = raw.as_array().cloned().unwrap_or_default();
|
||||
let mut binds = Vec::new();
|
||||
let mut css = obj
|
||||
.get("styles_css")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
|
||||
for b in arr {
|
||||
let front = b
|
||||
.get("front")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let back_raw = b.get("back").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let css_raw = b.get("css").and_then(|v| v.as_str()).unwrap_or("");
|
||||
|
||||
let back = match parse_site_path(back_raw) {
|
||||
SitePath::DbField { table, field } => format!("{table}.{field}"),
|
||||
SitePath::Plain(s) => s,
|
||||
SitePath::LibMember { lib, member } => {
|
||||
// Try a module member (e.g. `theme.hero`); if the lib is unknown,
|
||||
// treat `a.b` as a DB field `a.b` (table `a`, column `b`).
|
||||
match call_lib(&format!("{lib}.{member}")) {
|
||||
Ok(v) => match v {
|
||||
Value::String(s) => s,
|
||||
other => other.to_string(),
|
||||
},
|
||||
Err(_) => format!("{lib}.{member}"),
|
||||
}
|
||||
}
|
||||
};
|
||||
let css_name = match parse_site_path(css_raw) {
|
||||
SitePath::LibMember { lib, member } => {
|
||||
let st = call_lib(&format!("{lib}.{member}"))?;
|
||||
css.push_str(&as_css_named(&member, &st));
|
||||
member
|
||||
}
|
||||
SitePath::Plain(s) => s,
|
||||
SitePath::DbField { .. } => normalize_ref(css_raw),
|
||||
};
|
||||
binds.push(json!({ "front": front, "back": back, "css": css_name }));
|
||||
}
|
||||
|
||||
if let Some(t) = bind_table_name(&binds) {
|
||||
obj.insert("table".into(), json!(t));
|
||||
}
|
||||
obj.insert("main".into(), Value::Array(binds.clone()));
|
||||
if !css.is_empty() {
|
||||
obj.insert("styles_css".into(), json!(css));
|
||||
}
|
||||
|
||||
let mut parts = obj
|
||||
.get("parts")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let mut part = Map::new();
|
||||
part.insert("_type".into(), json!("page"));
|
||||
part.insert("slot".into(), json!("main"));
|
||||
part.insert("fragment".into(), json!("main"));
|
||||
part.insert("main".into(), Value::Array(binds));
|
||||
if let Some(intro) = obj.get("intro") {
|
||||
part.insert("intro".into(), intro.clone());
|
||||
}
|
||||
parts.insert("index".into(), Value::Object(part));
|
||||
obj.insert("parts".into(), Value::Object(parts));
|
||||
Ok(Value::Object(obj))
|
||||
}
|
||||
|
||||
/// Embed a form into the page main slot (`form_id` → POST `/_form/{id}`).
|
||||
///
|
||||
/// Optional `form_target` (CSS id / `#id`) mounts the form **inside** intro HTML
|
||||
/// at that element instead of appending a sibling `.site-form` (GAP-11).
|
||||
pub fn compose_form(
|
||||
page: &Value,
|
||||
form: &Value,
|
||||
form_id: &str,
|
||||
form_target: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
let id = form_id.trim();
|
||||
if id.is_empty() {
|
||||
return Err("compose_form requires non-empty `id`".into());
|
||||
}
|
||||
let mut obj = page.as_object().cloned().unwrap_or_default();
|
||||
let mut frm = form.clone();
|
||||
if let Some(m) = frm.as_object_mut() {
|
||||
// Quieter meta when sitting inside a page shell.
|
||||
m.entry("show_meta".to_string()).or_insert(json!(false));
|
||||
if !m.contains_key("title") {
|
||||
m.insert("title".into(), json!(id));
|
||||
}
|
||||
}
|
||||
obj.insert("form_id".into(), json!(id));
|
||||
obj.insert("form".into(), frm.clone());
|
||||
let target = form_target
|
||||
.map(str::trim)
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string());
|
||||
if let Some(ref t) = target {
|
||||
obj.insert("form_target".into(), json!(t));
|
||||
} else {
|
||||
obj.remove("form_target");
|
||||
}
|
||||
let mut forms = obj
|
||||
.get("forms")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
forms.insert(id.to_string(), frm.clone());
|
||||
obj.insert("forms".into(), Value::Object(forms));
|
||||
|
||||
let mut parts = obj
|
||||
.get("parts")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let mut part = Map::new();
|
||||
part.insert("_type".into(), json!("page"));
|
||||
part.insert("slot".into(), json!("main"));
|
||||
part.insert("fragment".into(), json!("main"));
|
||||
part.insert("form_id".into(), json!(id));
|
||||
part.insert("form".into(), frm);
|
||||
if let Some(ref t) = target {
|
||||
part.insert("form_target".into(), json!(t));
|
||||
}
|
||||
if let Some(intro) = obj.get("intro") {
|
||||
part.insert("intro".into(), intro.clone());
|
||||
}
|
||||
parts.insert(format!("form_{id}"), Value::Object(part));
|
||||
obj.insert("parts".into(), Value::Object(parts));
|
||||
Ok(Value::Object(obj))
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,676 +0,0 @@
|
||||
//! Postgres backend for `# db` (same author-facing API as SQLite).
|
||||
|
||||
use crate::driver::{db_kind, rewrite_placeholders_pg, DbKind};
|
||||
use postgres::types::ToSql;
|
||||
use postgres::{Client, NoTls, Row};
|
||||
use serde_json::{json, Map, Value};
|
||||
use std::collections::HashMap;
|
||||
use std::sync::{Arc, Mutex};
|
||||
|
||||
static POOL: Mutex<Option<HashMap<String, Arc<Mutex<Client>>>>> = Mutex::new(None);
|
||||
static TXNS: Mutex<Option<HashMap<String, (String, Arc<Mutex<Client>>)>>> = Mutex::new(None);
|
||||
|
||||
pub fn is_postgres(url: &str) -> bool {
|
||||
matches!(db_kind(url), DbKind::Postgres)
|
||||
}
|
||||
|
||||
fn pooled(url: &str) -> Result<Arc<Mutex<Client>>, String> {
|
||||
let mut guard = POOL.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let pool = guard.get_or_insert_with(HashMap::new);
|
||||
if let Some(c) = pool.get(url) {
|
||||
return Ok(c.clone());
|
||||
}
|
||||
let client = Client::connect(url, NoTls).map_err(|e| format!("postgres connect: {e}"))?;
|
||||
let arc = Arc::new(Mutex::new(client));
|
||||
pool.insert(url.to_string(), arc.clone());
|
||||
Ok(arc)
|
||||
}
|
||||
|
||||
fn conn_for(url: &str, txn_id: Option<&str>) -> Result<Arc<Mutex<Client>>, String> {
|
||||
if let Some(tid) = txn_id {
|
||||
let guard = TXNS.lock().unwrap_or_else(|e| e.into_inner());
|
||||
match guard.as_ref().and_then(|m| m.get(tid)) {
|
||||
Some((_, c)) => Ok(c.clone()),
|
||||
None => Err(format!("unknown transaction `{tid}`")),
|
||||
}
|
||||
} else {
|
||||
pooled(url)
|
||||
}
|
||||
}
|
||||
|
||||
fn next_txn_id() -> String {
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
let nanos = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|d| d.subsec_nanos())
|
||||
.unwrap_or(0);
|
||||
format!("pg-txn-{}-{nanos}", std::process::id())
|
||||
}
|
||||
|
||||
fn ident(s: &str) -> Result<&str, String> {
|
||||
let s = s.trim();
|
||||
if s.is_empty()
|
||||
|| !s
|
||||
.chars()
|
||||
.all(|c| c.is_ascii_alphanumeric() || c == '_')
|
||||
{
|
||||
return Err(format!("bad identifier `{s}`"));
|
||||
}
|
||||
Ok(s)
|
||||
}
|
||||
|
||||
fn cell_str(v: &Value) -> String {
|
||||
match v {
|
||||
Value::Null => String::new(),
|
||||
Value::String(s) => s.clone(),
|
||||
Value::Bool(b) => b.to_string(),
|
||||
Value::Number(n) => n.to_string(),
|
||||
other => other.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
fn pg_type(t: &str) -> &'static str {
|
||||
match t.trim().to_ascii_lowercase().as_str() {
|
||||
"int" | "integer" => "INTEGER",
|
||||
"real" | "float" | "double" => "DOUBLE PRECISION",
|
||||
"blob" | "bytea" => "BYTEA",
|
||||
"bool" | "boolean" => "BOOLEAN",
|
||||
"timestamp" | "datetime" | "timestamptz" | "审计" => "TIMESTAMPTZ",
|
||||
_ => "TEXT",
|
||||
}
|
||||
}
|
||||
|
||||
fn to_pg_box(v: &Value) -> Box<dyn ToSql + Sync + Send> {
|
||||
match v {
|
||||
Value::Null => Box::new(None::<String>),
|
||||
Value::Bool(b) => Box::new(*b),
|
||||
Value::Number(n) => {
|
||||
if let Some(i) = n.as_i64() {
|
||||
Box::new(i)
|
||||
} else if let Some(f) = n.as_f64() {
|
||||
Box::new(f)
|
||||
} else {
|
||||
Box::new(n.to_string())
|
||||
}
|
||||
}
|
||||
Value::String(s) => Box::new(s.clone()),
|
||||
other => Box::new(other.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
fn row_to_json(row: &Row) -> Value {
|
||||
let mut m = Map::new();
|
||||
for (i, col) in row.columns().iter().enumerate() {
|
||||
let name = col.name().to_string();
|
||||
let v: Value = if let Ok(x) = row.try_get::<_, Option<i64>>(i) {
|
||||
x.map(|n| json!(n)).unwrap_or(Value::Null)
|
||||
} else if let Ok(x) = row.try_get::<_, Option<f64>>(i) {
|
||||
x.map(|n| json!(n)).unwrap_or(Value::Null)
|
||||
} else if let Ok(x) = row.try_get::<_, Option<bool>>(i) {
|
||||
x.map(|b| json!(b)).unwrap_or(Value::Null)
|
||||
} else if let Ok(x) = row.try_get::<_, Option<String>>(i) {
|
||||
x.map(Value::String).unwrap_or(Value::Null)
|
||||
} else {
|
||||
Value::Null
|
||||
};
|
||||
m.insert(name, v);
|
||||
}
|
||||
Value::Object(m)
|
||||
}
|
||||
|
||||
fn exec_sql(client: &mut Client, sql: &str, params: &[Value]) -> Result<u64, String> {
|
||||
let sql = rewrite_placeholders_pg(sql);
|
||||
let boxes: Vec<Box<dyn ToSql + Sync + Send>> = params.iter().map(to_pg_box).collect();
|
||||
let refs: Vec<&(dyn ToSql + Sync)> = boxes
|
||||
.iter()
|
||||
.map(|b| b.as_ref() as &(dyn ToSql + Sync))
|
||||
.collect();
|
||||
client
|
||||
.execute(sql.as_str(), refs.as_slice())
|
||||
.map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn query_sql(client: &mut Client, sql: &str, params: &[Value]) -> Result<Vec<Value>, String> {
|
||||
let sql = rewrite_placeholders_pg(sql);
|
||||
let boxes: Vec<Box<dyn ToSql + Sync + Send>> = params.iter().map(to_pg_box).collect();
|
||||
let refs: Vec<&(dyn ToSql + Sync)> = boxes
|
||||
.iter()
|
||||
.map(|b| b.as_ref() as &(dyn ToSql + Sync))
|
||||
.collect();
|
||||
let rows = client
|
||||
.query(sql.as_str(), refs.as_slice())
|
||||
.map_err(|e| e.to_string())?;
|
||||
Ok(rows.iter().map(row_to_json).collect())
|
||||
}
|
||||
|
||||
/// Equality-map / filter-table → `(AND exprs with ?, vals)`.
|
||||
fn parse_where_simple(where_v: Option<&Value>) -> Result<(Vec<String>, Vec<Value>), String> {
|
||||
let Some(w) = where_v else {
|
||||
return Ok((vec![], vec![]));
|
||||
};
|
||||
let w = crate::table::as_rows(w);
|
||||
let mut exprs = Vec::new();
|
||||
let mut vals = Vec::new();
|
||||
match w {
|
||||
Value::Array(arr) => {
|
||||
for item in arr {
|
||||
let Value::Object(m) = item else {
|
||||
continue;
|
||||
};
|
||||
let field = m
|
||||
.get("field")
|
||||
.or_else(|| m.get("字段"))
|
||||
.or_else(|| m.get("列"))
|
||||
.map(cell_str)
|
||||
.unwrap_or_default();
|
||||
if !field.is_empty() {
|
||||
let col = ident(&field)?;
|
||||
let op = m
|
||||
.get("op")
|
||||
.or_else(|| m.get("操作"))
|
||||
.map(cell_str)
|
||||
.unwrap_or_else(|| "=".into());
|
||||
let op = match op.trim().to_ascii_lowercase().as_str() {
|
||||
"" | "=" | "eq" | "等于" => "=",
|
||||
"!=" | "<>" | "ne" | "不等于" => "!=",
|
||||
">" | "gt" | "大于" => ">",
|
||||
">=" | "gte" => ">=",
|
||||
"<" | "lt" | "小于" => "<",
|
||||
"<=" | "lte" => "<=",
|
||||
"like" | "包含" => "LIKE",
|
||||
other => return Err(format!("unsupported where op `{other}`")),
|
||||
};
|
||||
let val = m
|
||||
.get("value")
|
||||
.or_else(|| m.get("值"))
|
||||
.cloned()
|
||||
.unwrap_or(Value::Null);
|
||||
exprs.push(format!("\"{col}\" {op} ?"));
|
||||
vals.push(val);
|
||||
} else {
|
||||
for (k, v) in &m {
|
||||
if k == "@" || k == "行" || k == "row" || k.starts_with('_') {
|
||||
continue;
|
||||
}
|
||||
let col = ident(k)?;
|
||||
exprs.push(format!("\"{col}\" = ?"));
|
||||
vals.push(v.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
Ok((exprs, vals))
|
||||
}
|
||||
|
||||
fn parse_fk(raw: &str) -> Result<(String, String), String> {
|
||||
let s = raw.trim();
|
||||
if s.is_empty() {
|
||||
return Err("empty foreign key".into());
|
||||
}
|
||||
if let Some((t, rest)) = s.split_once('(') {
|
||||
let col = rest.trim().trim_end_matches(')').trim();
|
||||
let t = ident(t)?.to_string();
|
||||
let col = if col.is_empty() {
|
||||
"id".into()
|
||||
} else {
|
||||
ident(col)?.to_string()
|
||||
};
|
||||
return Ok((t, col));
|
||||
}
|
||||
if let Some((t, c)) = s.split_once('.') {
|
||||
return Ok((ident(t)?.to_string(), ident(c)?.to_string()));
|
||||
}
|
||||
Ok((ident(s)?.to_string(), "id".into()))
|
||||
}
|
||||
|
||||
fn utc_now_iso() -> String {
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
let secs = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|d| d.as_secs())
|
||||
.unwrap_or(0);
|
||||
let days = secs / 86400;
|
||||
let tod = secs % 86400;
|
||||
let h = tod / 3600;
|
||||
let m = (tod % 3600) / 60;
|
||||
let s = tod % 60;
|
||||
let z = days as i64 + 719468;
|
||||
let era = if z >= 0 { z } else { z - 146096 } / 146097;
|
||||
let doe = (z - era * 146097) as u64;
|
||||
let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
|
||||
let y = yoe as i64 + era * 400;
|
||||
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
|
||||
let mp = (5 * doy + 2) / 153;
|
||||
let d = doy - (153 * mp + 2) / 5 + 1;
|
||||
let mo = if mp < 10 { mp + 3 } else { mp - 9 };
|
||||
let y = if mo <= 2 { y + 1 } else { y };
|
||||
format!("{y:04}-{mo:02}-{d:02}T{h:02}:{m:02}:{s:02}Z")
|
||||
}
|
||||
|
||||
fn column_names(url: &str, table: &str, txn_id: Option<&str>) -> Result<Vec<String>, String> {
|
||||
let table = ident(table)?;
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(
|
||||
&mut c,
|
||||
"SELECT column_name FROM information_schema.columns WHERE table_name = ? ORDER BY ordinal_position",
|
||||
&[json!(table)],
|
||||
)?;
|
||||
Ok(rows
|
||||
.into_iter()
|
||||
.filter_map(|r| {
|
||||
r.get("column_name")
|
||||
.or_else(|| r.get("COLUMN_NAME"))
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string())
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
|
||||
pub fn init(url: &str, table: &str, fields: &Value) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let cols = crate::table::as_fields(fields);
|
||||
let arr = cols.as_array().ok_or("fields must be a list")?;
|
||||
if arr.is_empty() {
|
||||
return Err("empty fields".into());
|
||||
}
|
||||
let mut parts = Vec::new();
|
||||
let mut has_pk = false;
|
||||
let mut index_sql = Vec::new();
|
||||
for c in arr {
|
||||
let name = c
|
||||
.get("name")
|
||||
.or_else(|| c.get("字段"))
|
||||
.map(cell_str)
|
||||
.unwrap_or_default();
|
||||
let name = ident(&name)?;
|
||||
let ty = c
|
||||
.get("type")
|
||||
.or_else(|| c.get("类型"))
|
||||
.map(cell_str)
|
||||
.unwrap_or_else(|| "text".into());
|
||||
let nullable = c
|
||||
.get("nullable")
|
||||
.or_else(|| c.get("可空"))
|
||||
.and_then(|v| match v {
|
||||
Value::Bool(b) => Some(*b),
|
||||
Value::String(s) => {
|
||||
Some(matches!(s.as_str(), "true" | "True" | "1" | "是" | "可"))
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.unwrap_or(true);
|
||||
let unique = c
|
||||
.get("unique")
|
||||
.or_else(|| c.get("唯一"))
|
||||
.and_then(|v| match v {
|
||||
Value::Bool(b) => Some(*b),
|
||||
Value::String(s) => {
|
||||
Some(matches!(s.as_str(), "true" | "True" | "1" | "yes" | "是" | "唯一"))
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.unwrap_or(false);
|
||||
let index = c
|
||||
.get("index")
|
||||
.or_else(|| c.get("索引"))
|
||||
.and_then(|v| match v {
|
||||
Value::Bool(b) => Some(*b),
|
||||
Value::String(s) => {
|
||||
Some(matches!(s.as_str(), "true" | "True" | "1" | "yes" | "是" | "索引"))
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.unwrap_or(false);
|
||||
let part = if name == "id" && !has_pk && pg_type(&ty) == "INTEGER" {
|
||||
has_pk = true;
|
||||
format!("\"{name}\" SERIAL PRIMARY KEY")
|
||||
} else if name == "id" && !has_pk {
|
||||
has_pk = true;
|
||||
format!("\"{name}\" {} PRIMARY KEY", pg_type(&ty))
|
||||
} else {
|
||||
let mut col = format!("\"{name}\" {}", pg_type(&ty));
|
||||
if !nullable {
|
||||
col.push_str(" NOT NULL");
|
||||
}
|
||||
if unique {
|
||||
col.push_str(" UNIQUE");
|
||||
}
|
||||
let fk_raw = c
|
||||
.get("fk")
|
||||
.or_else(|| c.get("外键"))
|
||||
.map(cell_str)
|
||||
.unwrap_or_default();
|
||||
if !fk_raw.is_empty() {
|
||||
let (ref_table, ref_col) = parse_fk(&fk_raw)?;
|
||||
col.push_str(&format!(" REFERENCES \"{ref_table}\"(\"{ref_col}\")"));
|
||||
}
|
||||
col
|
||||
};
|
||||
parts.push(part);
|
||||
if (index || unique) && name != "id" {
|
||||
let kind = if unique { "UNIQUE " } else { "" };
|
||||
index_sql.push(format!(
|
||||
"CREATE {kind}INDEX IF NOT EXISTS \"idx_{table}_{name}\" ON \"{table}\" (\"{name}\")"
|
||||
));
|
||||
}
|
||||
}
|
||||
let sql = format!(
|
||||
"CREATE TABLE IF NOT EXISTS \"{table}\" ({})",
|
||||
parts.join(", ")
|
||||
);
|
||||
let conn = pooled(url)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
c.batch_execute(&sql).map_err(|e| e.to_string())?;
|
||||
for stmt in index_sql {
|
||||
let _ = c.batch_execute(&stmt);
|
||||
}
|
||||
Ok(json!({ "_type": "db_table", "name": table, "url": url }))
|
||||
}
|
||||
|
||||
pub fn insert(url: &str, table: &str, rows: &Value, txn_id: Option<&str>) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let cols_present = column_names(url, table, txn_id).unwrap_or_default();
|
||||
let has_created = cols_present.iter().any(|c| c == "created_at");
|
||||
let has_updated = cols_present.iter().any(|c| c == "updated_at");
|
||||
let rows = crate::table::as_rows(rows);
|
||||
let arr = rows.as_array().ok_or("rows must be a list")?;
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let mut n = 0i64;
|
||||
let now = utc_now_iso();
|
||||
for row in arr {
|
||||
let obj = row.as_object().ok_or("row must be a map")?;
|
||||
let mut cols = Vec::new();
|
||||
let mut ph = Vec::new();
|
||||
let mut vals = Vec::new();
|
||||
let mut seen_created = false;
|
||||
let mut seen_updated = false;
|
||||
for (k, v) in obj {
|
||||
if k == "@" || k == "行" || k == "row" {
|
||||
continue;
|
||||
}
|
||||
let _ = ident(k)?;
|
||||
if k == "created_at" {
|
||||
seen_created = true;
|
||||
}
|
||||
if k == "updated_at" {
|
||||
seen_updated = true;
|
||||
}
|
||||
cols.push(format!("\"{k}\""));
|
||||
ph.push("?");
|
||||
vals.push(v.clone());
|
||||
}
|
||||
if has_created && !seen_created {
|
||||
cols.push("\"created_at\"".into());
|
||||
ph.push("?");
|
||||
vals.push(json!(now.clone()));
|
||||
}
|
||||
if has_updated && !seen_updated {
|
||||
cols.push("\"updated_at\"".into());
|
||||
ph.push("?");
|
||||
vals.push(json!(now.clone()));
|
||||
}
|
||||
if cols.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let sql = format!(
|
||||
"INSERT INTO \"{table}\" ({}) VALUES ({})",
|
||||
cols.join(", "),
|
||||
ph.join(", ")
|
||||
);
|
||||
exec_sql(&mut c, &sql, &vals)?;
|
||||
n += 1;
|
||||
}
|
||||
Ok(json!({ "ok": true, "inserted": n }))
|
||||
}
|
||||
|
||||
pub fn select_order(
|
||||
url: &str,
|
||||
table: &str,
|
||||
limit: i64,
|
||||
where_v: Option<&Value>,
|
||||
order: Option<&str>,
|
||||
offset: Option<i64>,
|
||||
txn_id: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let (exprs, mut vals) = parse_where_simple(where_v)?;
|
||||
let mut sql = format!("SELECT * FROM \"{table}\"");
|
||||
let where_sql = if exprs.is_empty() {
|
||||
String::new()
|
||||
} else {
|
||||
format!(" WHERE {}", exprs.join(" AND "))
|
||||
};
|
||||
sql.push_str(&where_sql);
|
||||
if let Some(order) = order.map(str::trim).filter(|s| !s.is_empty()) {
|
||||
let mut order_exprs = Vec::new();
|
||||
for part in order.split(',').map(str::trim).filter(|p| !p.is_empty()) {
|
||||
let (col, dir) = match part.strip_prefix('-') {
|
||||
Some(c) => (c, " DESC"),
|
||||
None => (part, ""),
|
||||
};
|
||||
order_exprs.push(format!("\"{}\"{}", ident(col)?, dir));
|
||||
}
|
||||
if !order_exprs.is_empty() {
|
||||
sql.push_str(" ORDER BY ");
|
||||
sql.push_str(&order_exprs.join(", "));
|
||||
}
|
||||
}
|
||||
sql.push_str(" LIMIT ?");
|
||||
vals.push(json!(limit));
|
||||
if let Some(off) = offset {
|
||||
if off > 0 {
|
||||
sql.push_str(" OFFSET ?");
|
||||
vals.push(json!(off));
|
||||
}
|
||||
}
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(&mut c, &sql, &vals)?;
|
||||
if offset.is_some() {
|
||||
let mut count_sql = format!("SELECT COUNT(*) AS count FROM \"{table}\"");
|
||||
count_sql.push_str(&where_sql);
|
||||
let count_vals: Vec<Value> = vals
|
||||
.iter()
|
||||
.take(exprs.len())
|
||||
.cloned()
|
||||
.collect();
|
||||
let total = query_sql(&mut c, &count_sql, &count_vals)?
|
||||
.first()
|
||||
.and_then(|r| r.get("count"))
|
||||
.and_then(|v| v.as_i64())
|
||||
.unwrap_or(rows.len() as i64);
|
||||
Ok(json!({ "rows": rows, "total": total }))
|
||||
} else {
|
||||
Ok(json!({ "rows": rows }))
|
||||
}
|
||||
}
|
||||
|
||||
pub fn get(url: &str, table: &str, id: &str, txn_id: Option<&str>) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let sql = format!("SELECT * FROM \"{table}\" WHERE \"id\" = ? LIMIT 1");
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(&mut c, &sql, &[json!(id)])?;
|
||||
Ok(rows.into_iter().next().unwrap_or(Value::Null))
|
||||
}
|
||||
|
||||
pub fn update(
|
||||
url: &str,
|
||||
table: &str,
|
||||
id: &str,
|
||||
row: &Value,
|
||||
txn_id: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let cols_present = column_names(url, table, txn_id).unwrap_or_default();
|
||||
let has_updated = cols_present.iter().any(|c| c == "updated_at");
|
||||
let obj = row.as_object().ok_or("row must be a map")?;
|
||||
let mut sets = Vec::new();
|
||||
let mut vals = Vec::new();
|
||||
let mut seen_updated = false;
|
||||
for (k, v) in obj {
|
||||
if k == "id" || k == "@" || k == "行" || k == "row" {
|
||||
continue;
|
||||
}
|
||||
let _ = ident(k)?;
|
||||
if k == "updated_at" {
|
||||
seen_updated = true;
|
||||
}
|
||||
sets.push(format!("\"{k}\" = ?"));
|
||||
vals.push(v.clone());
|
||||
}
|
||||
if has_updated && !seen_updated {
|
||||
sets.push("\"updated_at\" = ?".into());
|
||||
vals.push(json!(utc_now_iso()));
|
||||
}
|
||||
if sets.is_empty() {
|
||||
return Ok(json!({ "ok": true, "updated": 0 }));
|
||||
}
|
||||
vals.push(json!(id));
|
||||
let sql = format!(
|
||||
"UPDATE \"{table}\" SET {} WHERE \"id\" = ?",
|
||||
sets.join(", ")
|
||||
);
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let n = exec_sql(&mut c, &sql, &vals)?;
|
||||
Ok(json!({ "ok": true, "updated": n }))
|
||||
}
|
||||
|
||||
pub fn delete(url: &str, table: &str, id: &str, txn_id: Option<&str>) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let sql = format!("DELETE FROM \"{table}\" WHERE \"id\" = ?");
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let n = exec_sql(&mut c, &sql, &[json!(id)])?;
|
||||
Ok(json!({ "ok": true, "deleted": n }))
|
||||
}
|
||||
|
||||
pub fn exec(url: &str, sql: &str, args: Option<&Value>, txn_id: Option<&str>) -> Result<Value, String> {
|
||||
let vals: Vec<Value> = match args {
|
||||
Some(Value::Array(a)) => a.clone(),
|
||||
_ => Vec::new(),
|
||||
};
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let n = exec_sql(&mut c, sql, &vals)?;
|
||||
Ok(json!({ "ok": true, "changes": n }))
|
||||
}
|
||||
|
||||
pub fn query(url: &str, sql: &str, args: Option<&Value>, txn_id: Option<&str>) -> Result<Value, String> {
|
||||
let vals: Vec<Value> = match args {
|
||||
Some(Value::Array(a)) => a.clone(),
|
||||
_ => Vec::new(),
|
||||
};
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(&mut c, sql, &vals)?;
|
||||
Ok(json!({ "rows": rows, "count": rows.len() }))
|
||||
}
|
||||
|
||||
pub fn count(
|
||||
url: &str,
|
||||
table: &str,
|
||||
where_v: Option<&Value>,
|
||||
txn_id: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
let table = ident(table)?;
|
||||
let (exprs, vals) = parse_where_simple(where_v)?;
|
||||
let mut sql = format!("SELECT COUNT(*) AS count FROM \"{table}\"");
|
||||
if !exprs.is_empty() {
|
||||
sql.push_str(&format!(" WHERE {}", exprs.join(" AND ")));
|
||||
}
|
||||
let conn = conn_for(url, txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(&mut c, &sql, &vals)?;
|
||||
let n = rows
|
||||
.first()
|
||||
.and_then(|r| r.get("count"))
|
||||
.and_then(|v| v.as_i64())
|
||||
.unwrap_or(0);
|
||||
Ok(json!({ "count": n }))
|
||||
}
|
||||
|
||||
pub fn begin(url: &str) -> Result<Value, String> {
|
||||
let conn = pooled(url)?;
|
||||
{
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
c.batch_execute("BEGIN").map_err(|e| e.to_string())?;
|
||||
}
|
||||
let id = next_txn_id();
|
||||
{
|
||||
let mut guard = TXNS.lock().unwrap_or_else(|e| e.into_inner());
|
||||
guard
|
||||
.get_or_insert_with(HashMap::new)
|
||||
.insert(id.clone(), (url.to_string(), conn));
|
||||
}
|
||||
Ok(json!({ "_type": "txn", "txn": id, "url": url, "事务": id, "地址": url }))
|
||||
}
|
||||
|
||||
pub fn commit(txn_id: &str) -> Result<Value, String> {
|
||||
let (_, conn) = take_txn(txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
c.batch_execute("COMMIT").map_err(|e| e.to_string())?;
|
||||
Ok(json!({ "ok": true }))
|
||||
}
|
||||
|
||||
pub fn rollback(txn_id: &str) -> Result<Value, String> {
|
||||
let (_, conn) = take_txn(txn_id)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
c.batch_execute("ROLLBACK").map_err(|e| e.to_string())?;
|
||||
Ok(json!({ "ok": true }))
|
||||
}
|
||||
|
||||
fn take_txn(txn_id: &str) -> Result<(String, Arc<Mutex<Client>>), String> {
|
||||
let mut guard = TXNS.lock().unwrap_or_else(|e| e.into_inner());
|
||||
guard
|
||||
.as_mut()
|
||||
.and_then(|m| m.remove(txn_id))
|
||||
.ok_or_else(|| format!("unknown transaction `{txn_id}`"))
|
||||
}
|
||||
|
||||
pub fn list_tables(url: &str) -> Result<Vec<String>, String> {
|
||||
let conn = pooled(url)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(
|
||||
&mut c,
|
||||
"SELECT tablename AS name FROM pg_catalog.pg_tables WHERE schemaname = 'public' ORDER BY tablename",
|
||||
&[],
|
||||
)?;
|
||||
Ok(rows
|
||||
.iter()
|
||||
.filter_map(|r| r.get("name").and_then(|v| v.as_str()).map(|s| s.to_string()))
|
||||
.collect())
|
||||
}
|
||||
|
||||
pub fn table_info(url: &str, table: &str) -> Result<Vec<crate::db::ColumnInfo>, String> {
|
||||
let table = ident(table)?;
|
||||
let conn = pooled(url)?;
|
||||
let mut c = conn.lock().unwrap_or_else(|e| e.into_inner());
|
||||
let rows = query_sql(
|
||||
&mut c,
|
||||
"SELECT column_name AS name, data_type AS sql_type, \
|
||||
CASE WHEN is_nullable = 'NO' THEN true ELSE false END AS notnull \
|
||||
FROM information_schema.columns \
|
||||
WHERE table_schema = 'public' AND table_name = ? \
|
||||
ORDER BY ordinal_position",
|
||||
&[json!(table)],
|
||||
)?;
|
||||
Ok(rows
|
||||
.iter()
|
||||
.map(|r| crate::db::ColumnInfo {
|
||||
name: r.get("name").and_then(|v| v.as_str()).unwrap_or("").into(),
|
||||
sql_type: r
|
||||
.get("sql_type")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("text")
|
||||
.into(),
|
||||
notnull: r.get("notnull").and_then(|v| v.as_bool()).unwrap_or(false),
|
||||
pk: r.get("name").and_then(|v| v.as_str()) == Some("id"),
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
@@ -1,54 +0,0 @@
|
||||
//! Driver URL schemes for `# db` / `# cache` / `# storage` (design ext-web-drivers).
|
||||
|
||||
/// Which SQL backend a `# db` URL selects.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum DbKind {
|
||||
Sqlite,
|
||||
Postgres,
|
||||
}
|
||||
|
||||
pub fn db_kind(url: &str) -> DbKind {
|
||||
let u = url.trim().to_ascii_lowercase();
|
||||
if u.starts_with("postgres://") || u.starts_with("postgresql://") {
|
||||
DbKind::Postgres
|
||||
} else {
|
||||
DbKind::Sqlite
|
||||
}
|
||||
}
|
||||
|
||||
/// Rewrite SQL written with `?` placeholders into Postgres `$1,$2,…` form.
|
||||
pub fn rewrite_placeholders_pg(sql: &str) -> String {
|
||||
let mut out = String::with_capacity(sql.len() + 8);
|
||||
let mut n = 0usize;
|
||||
let mut chars = sql.chars().peekable();
|
||||
while let Some(c) = chars.next() {
|
||||
if c == '?' {
|
||||
n += 1;
|
||||
out.push('$');
|
||||
out.push_str(&n.to_string());
|
||||
} else {
|
||||
out.push(c);
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn kind_from_url() {
|
||||
assert_eq!(db_kind("sqlite:a.db"), DbKind::Sqlite);
|
||||
assert_eq!(db_kind("postgres://u:p@h/db"), DbKind::Postgres);
|
||||
assert_eq!(db_kind("postgresql://localhost/x"), DbKind::Postgres);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rewrite_qmark() {
|
||||
assert_eq!(
|
||||
rewrite_placeholders_pg("SELECT * FROM t WHERE a = ? AND b IN (?, ?)"),
|
||||
"SELECT * FROM t WHERE a = $1 AND b IN ($2, $3)"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -1,701 +0,0 @@
|
||||
//! Form fields / validate / render / submit (design §5.5).
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
use crate::db;
|
||||
use crate::table::normalize_ref;
|
||||
|
||||
const FIELD_KEYS: &[&str] = &["字段", "name", "field", "列"];
|
||||
const LABEL_KEYS: &[&str] = &["标签", "label"];
|
||||
const TYPE_KEYS: &[&str] = &["类型", "type"];
|
||||
const REQ_KEYS: &[&str] = &["必填", "required"];
|
||||
const DEF_KEYS: &[&str] = &["默认", "default"];
|
||||
const RULE_FIELD_KEYS: &[&str] = &["字段", "field", "name"];
|
||||
const RULE_KEYS: &[&str] = &["规则", "rule"];
|
||||
const MSG_KEYS: &[&str] = &["消息", "message", "msg"];
|
||||
|
||||
fn cell_str(v: &Value) -> String {
|
||||
match v {
|
||||
Value::Null => String::new(),
|
||||
Value::String(s) => s.clone(),
|
||||
Value::Bool(b) => b.to_string(),
|
||||
Value::Number(n) => n.to_string(),
|
||||
other => other.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
fn as_str_list(v: &Value) -> Vec<String> {
|
||||
match v {
|
||||
Value::Array(a) => a.iter().map(cell_str).collect(),
|
||||
Value::Null => Vec::new(),
|
||||
other => vec![cell_str(other)],
|
||||
}
|
||||
}
|
||||
|
||||
fn pick<'a>(m: &'a Map<String, Value>, keys: &[&str]) -> Option<&'a Value> {
|
||||
keys.iter().find_map(|k| m.get(*k))
|
||||
}
|
||||
|
||||
fn boolish(v: &Value) -> bool {
|
||||
match v {
|
||||
Value::Bool(b) => *b,
|
||||
Value::String(s) => matches!(
|
||||
s.trim(),
|
||||
"1" | "true" | "True" | "yes" | "是" | "必填" | "required"
|
||||
),
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
|
||||
fn esc(s: &str) -> String {
|
||||
s.replace('&', "&")
|
||||
.replace('<', "<")
|
||||
.replace('>', ">")
|
||||
.replace('"', """)
|
||||
}
|
||||
|
||||
/// Normalize author field table → `[{name,label,type,required,default}, …]`
|
||||
pub fn as_form_fields(table: &Value) -> Value {
|
||||
match table {
|
||||
Value::Array(rows) => {
|
||||
let mut out = Vec::new();
|
||||
for row in rows {
|
||||
if let Some(m) = row.as_object() {
|
||||
let name = normalize_ref(&pick(m, FIELD_KEYS).map(cell_str).unwrap_or_default());
|
||||
if name.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let label = pick(m, LABEL_KEYS).map(cell_str).unwrap_or_else(|| name.clone());
|
||||
let ty = pick(m, TYPE_KEYS)
|
||||
.map(cell_str)
|
||||
.unwrap_or_else(|| "text".into());
|
||||
let required = pick(m, REQ_KEYS).map(boolish).unwrap_or(false);
|
||||
let default = pick(m, DEF_KEYS).map(cell_str).unwrap_or_default();
|
||||
out.push(json!({
|
||||
"name": name,
|
||||
"label": label,
|
||||
"type": ty,
|
||||
"required": required,
|
||||
"default": default,
|
||||
}));
|
||||
}
|
||||
}
|
||||
Value::Array(out)
|
||||
}
|
||||
Value::Object(m) => {
|
||||
let names = pick(m, FIELD_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let labels = pick(m, LABEL_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let types = pick(m, TYPE_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let reqs = pick(m, REQ_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let defs = pick(m, DEF_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let mut out = Vec::new();
|
||||
for (i, name_raw) in names.iter().enumerate() {
|
||||
let name = normalize_ref(name_raw);
|
||||
if name.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let label = labels.get(i).cloned().unwrap_or_else(|| name.clone());
|
||||
let ty = types.get(i).cloned().unwrap_or_else(|| "text".into());
|
||||
let required = reqs
|
||||
.get(i)
|
||||
.map(|s| boolish(&Value::String(s.clone())))
|
||||
.unwrap_or(false);
|
||||
let default = defs.get(i).cloned().unwrap_or_default();
|
||||
out.push(json!({
|
||||
"name": name,
|
||||
"label": label,
|
||||
"type": ty,
|
||||
"required": required,
|
||||
"default": default,
|
||||
}));
|
||||
}
|
||||
Value::Array(out)
|
||||
}
|
||||
_ => json!([]),
|
||||
}
|
||||
}
|
||||
|
||||
/// Normalize rules table → `[{field,rule,message}, …]`
|
||||
pub fn as_form_rules(table: &Value) -> Value {
|
||||
match table {
|
||||
Value::Array(rows) => {
|
||||
let mut out = Vec::new();
|
||||
for row in rows {
|
||||
if let Some(m) = row.as_object() {
|
||||
let field =
|
||||
normalize_ref(&pick(m, RULE_FIELD_KEYS).map(cell_str).unwrap_or_default());
|
||||
let rule = pick(m, RULE_KEYS).map(cell_str).unwrap_or_default();
|
||||
if field.is_empty() || rule.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let message = pick(m, MSG_KEYS).map(cell_str).unwrap_or_default();
|
||||
out.push(json!({ "field": field, "rule": rule, "message": message }));
|
||||
}
|
||||
}
|
||||
Value::Array(out)
|
||||
}
|
||||
Value::Object(m) => {
|
||||
let fields = pick(m, RULE_FIELD_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let rules = pick(m, RULE_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let msgs = pick(m, MSG_KEYS).map(as_str_list).unwrap_or_default();
|
||||
let n = fields.len().max(rules.len());
|
||||
let mut out = Vec::new();
|
||||
for i in 0..n {
|
||||
let field = normalize_ref(&fields.get(i).cloned().unwrap_or_default());
|
||||
let rule = rules.get(i).cloned().unwrap_or_default();
|
||||
if field.is_empty() || rule.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let message = msgs.get(i).cloned().unwrap_or_default();
|
||||
out.push(json!({ "field": field, "rule": rule, "message": message }));
|
||||
}
|
||||
Value::Array(out)
|
||||
}
|
||||
_ => json!([]),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn form_new(table: Option<&str>, action: &str, id: Option<&str>) -> Value {
|
||||
let action = match action {
|
||||
"update" | "更新" => "update",
|
||||
_ => "insert",
|
||||
};
|
||||
let mut m = Map::new();
|
||||
if let Some(t) = table.filter(|s| !s.is_empty()) {
|
||||
m.insert("table".into(), json!(t));
|
||||
}
|
||||
m.insert("action".into(), json!(action));
|
||||
if let Some(i) = id.filter(|s| !s.is_empty()) {
|
||||
m.insert("id".into(), json!(i));
|
||||
}
|
||||
m.insert("fields".into(), json!([]));
|
||||
m.insert("rules".into(), json!([]));
|
||||
m.insert("redirect".into(), json!("/"));
|
||||
Value::Object(m)
|
||||
}
|
||||
|
||||
fn sql_type_to_input(sql_type: &str, name: &str) -> &'static str {
|
||||
let t = sql_type.to_ascii_uppercase();
|
||||
if t.contains("INT") || t.contains("REAL") || t.contains("FLOAT") || t.contains("DOUBLE") {
|
||||
return "number";
|
||||
}
|
||||
if name == "body" || name.ends_with("_body") || name.ends_with("_text") {
|
||||
return "textarea";
|
||||
}
|
||||
if name.contains("email") {
|
||||
return "email";
|
||||
}
|
||||
if name.contains("url") || name == "href" {
|
||||
return "url";
|
||||
}
|
||||
"text"
|
||||
}
|
||||
|
||||
/// Build a form handle from live SQLite schema (admin new/edit).
|
||||
/// `admin_prefix` is the mount root (default `/admin`), without trailing slash.
|
||||
pub fn from_schema(
|
||||
db_url: &str,
|
||||
table: &str,
|
||||
action: &str,
|
||||
id: Option<&str>,
|
||||
admin_prefix: &str,
|
||||
) -> Result<Value, String> {
|
||||
let action = match action {
|
||||
"update" | "更新" => "update",
|
||||
_ => "insert",
|
||||
};
|
||||
let cols = db::table_info(db_url, table)?;
|
||||
if cols.is_empty() {
|
||||
return Err(format!("unknown table `{table}`"));
|
||||
}
|
||||
let mut fields = Vec::new();
|
||||
for c in &cols {
|
||||
if action == "insert" && c.pk && c.name == "id" {
|
||||
continue; // SERIAL / AUTOINCREMENT
|
||||
}
|
||||
let input = sql_type_to_input(&c.sql_type, &c.name);
|
||||
let required = c.notnull || (action == "update" && c.pk);
|
||||
fields.push(json!({
|
||||
"name": c.name,
|
||||
"label": c.name,
|
||||
"type": input,
|
||||
"required": required,
|
||||
"default": "",
|
||||
"pk": c.pk,
|
||||
}));
|
||||
}
|
||||
let base = admin_prefix.trim_end_matches('/');
|
||||
let table_href = format!("{base}/{table}");
|
||||
let mut form = form_new(Some(table), action, id);
|
||||
if let Some(obj) = form.as_object_mut() {
|
||||
obj.insert("fields".into(), Value::Array(fields));
|
||||
obj.insert("redirect".into(), json!(&table_href));
|
||||
if action == "insert" {
|
||||
obj.insert("action_url".into(), json!(format!("{table_href}/new")));
|
||||
obj.insert("title".into(), json!(format!("New {table}")));
|
||||
} else if let Some(i) = id {
|
||||
obj.insert(
|
||||
"action_url".into(),
|
||||
json!(format!("{table_href}/{i}/edit")),
|
||||
);
|
||||
obj.insert("title".into(), json!(format!("Edit {table} #{i}")));
|
||||
obj.insert("id".into(), json!(i));
|
||||
}
|
||||
obj.insert("cancel_href".into(), json!(&table_href));
|
||||
}
|
||||
Ok(form)
|
||||
}
|
||||
|
||||
pub fn set_fields(form: &Value, fields: &Value) -> Value {
|
||||
let mut obj = form.as_object().cloned().unwrap_or_default();
|
||||
obj.insert("fields".into(), as_form_fields(fields));
|
||||
Value::Object(obj)
|
||||
}
|
||||
|
||||
pub fn set_rules(form: &Value, rules: &Value) -> Value {
|
||||
let mut obj = form.as_object().cloned().unwrap_or_default();
|
||||
obj.insert("rules".into(), as_form_rules(rules));
|
||||
Value::Object(obj)
|
||||
}
|
||||
|
||||
fn data_map(data: &Value) -> Map<String, Value> {
|
||||
let rows = crate::table::as_rows(data);
|
||||
if let Some(Value::Object(m)) = rows.as_array().and_then(|a| a.first()) {
|
||||
return m.clone();
|
||||
}
|
||||
match data {
|
||||
Value::Object(m) => m.clone(),
|
||||
_ => Map::new(),
|
||||
}
|
||||
}
|
||||
|
||||
fn field_text(data: &Map<String, Value>, name: &str) -> String {
|
||||
data.get(name).map(cell_str).unwrap_or_default()
|
||||
}
|
||||
|
||||
fn default_message(rule: &str, field: &str) -> String {
|
||||
if let Some(rest) = rule.strip_prefix("min:") {
|
||||
return format!("{field} must be at least {rest}");
|
||||
}
|
||||
if let Some(rest) = rule.strip_prefix("max:") {
|
||||
return format!("{field} must be at most {rest}");
|
||||
}
|
||||
if let Some(other) = rule.strip_prefix("match:") {
|
||||
return format!("{field} must match {other}");
|
||||
}
|
||||
if rule.starts_with("in:") {
|
||||
return format!("{field} is not an allowed value");
|
||||
}
|
||||
match rule {
|
||||
"required" => format!("{field} is required"),
|
||||
"email" => format!("{field} must be an email"),
|
||||
"url" => format!("{field} must be a URL"),
|
||||
_ => format!("{field} failed `{rule}`"),
|
||||
}
|
||||
}
|
||||
|
||||
fn check_rule(rule: &str, field: &str, data: &Map<String, Value>) -> Option<String> {
|
||||
let val = field_text(data, field);
|
||||
let trimmed = val.trim();
|
||||
if rule == "required" {
|
||||
return if trimmed.is_empty() {
|
||||
Some(default_message(rule, field))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
}
|
||||
if trimmed.is_empty() {
|
||||
return None; // other rules skip empty (required covers emptiness)
|
||||
}
|
||||
if let Some(n) = rule.strip_prefix("min:") {
|
||||
if let Ok(min) = n.parse::<i64>() {
|
||||
if let Ok(num) = trimmed.parse::<f64>() {
|
||||
if num < min as f64 {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
} else if (trimmed.chars().count() as i64) < min {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
}
|
||||
return None;
|
||||
}
|
||||
if let Some(n) = rule.strip_prefix("max:") {
|
||||
if let Ok(max) = n.parse::<i64>() {
|
||||
if let Ok(num) = trimmed.parse::<f64>() {
|
||||
if num > max as f64 {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
} else if (trimmed.chars().count() as i64) > max {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
}
|
||||
return None;
|
||||
}
|
||||
if let Some(other) = rule.strip_prefix("match:") {
|
||||
let other_val = field_text(data, other);
|
||||
if val != other_val {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
return None;
|
||||
}
|
||||
if let Some(list) = rule.strip_prefix("in:") {
|
||||
let allowed: Vec<&str> = list.split(',').map(|s| s.trim()).collect();
|
||||
if !allowed.contains(&trimmed) {
|
||||
return Some(default_message(rule, field));
|
||||
}
|
||||
return None;
|
||||
}
|
||||
match rule {
|
||||
"email" => {
|
||||
if !(trimmed.contains('@') && trimmed.contains('.')) {
|
||||
Some(default_message(rule, field))
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
"url" => {
|
||||
if !(trimmed.starts_with("http://") || trimmed.starts_with("https://")) {
|
||||
Some(default_message(rule, field))
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Merge field-required + author rules; return `{ok, errors:[{field,message}]}`.
|
||||
pub fn validate(form: &Value, extra_rules: Option<&Value>, data: &Value) -> Value {
|
||||
let data = data_map(data);
|
||||
let fields = form
|
||||
.get("fields")
|
||||
.cloned()
|
||||
.unwrap_or(json!([]));
|
||||
let mut rules = form
|
||||
.get("rules")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
if let Some(extra) = extra_rules {
|
||||
if let Some(arr) = as_form_rules(extra).as_array() {
|
||||
rules.extend(arr.clone());
|
||||
}
|
||||
}
|
||||
// Auto required from field table (message overridable by later explicit rules)
|
||||
if let Some(arr) = fields.as_array() {
|
||||
for f in arr {
|
||||
let name = f.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let required = f.get("required").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
if required && !name.is_empty() {
|
||||
let already = rules.iter().any(|r| {
|
||||
r.get("field").and_then(|v| v.as_str()) == Some(name)
|
||||
&& r.get("rule").and_then(|v| v.as_str()) == Some("required")
|
||||
});
|
||||
if !already {
|
||||
rules.insert(
|
||||
0,
|
||||
json!({
|
||||
"field": name,
|
||||
"rule": "required",
|
||||
"message": format!("{name} is required"),
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let mut errors = Vec::new();
|
||||
for r in &rules {
|
||||
let field = r.get("field").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let rule = r.get("rule").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let msg = r.get("message").and_then(|v| v.as_str()).unwrap_or("");
|
||||
if field.is_empty() || rule.is_empty() {
|
||||
continue;
|
||||
}
|
||||
if let Some(default_msg) = check_rule(rule, field, &data) {
|
||||
errors.push(json!({
|
||||
"field": field,
|
||||
"message": if msg.is_empty() { default_msg } else { msg.to_string() },
|
||||
}));
|
||||
}
|
||||
}
|
||||
json!({
|
||||
"ok": errors.is_empty(),
|
||||
"errors": errors,
|
||||
})
|
||||
}
|
||||
|
||||
/// Form markup only (no document shell) — for page main-slot embed and `/_form`.
|
||||
pub fn render_body(
|
||||
form: &Value,
|
||||
form_id: &str,
|
||||
data: Option<&Value>,
|
||||
errors: Option<&Value>,
|
||||
csrf: Option<&str>,
|
||||
) -> String {
|
||||
let fields = form
|
||||
.get("fields")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let data = data.map(data_map).unwrap_or_default();
|
||||
let mut err_map = Map::new();
|
||||
if let Some(Value::Array(errs)) = errors {
|
||||
for e in errs {
|
||||
if let (Some(f), Some(m)) = (
|
||||
e.get("field").and_then(|v| v.as_str()),
|
||||
e.get("message").and_then(|v| v.as_str()),
|
||||
) {
|
||||
err_map.insert(f.to_string(), json!(m));
|
||||
}
|
||||
}
|
||||
} else if let Some(Value::Object(m)) = errors {
|
||||
err_map = m.clone();
|
||||
}
|
||||
|
||||
let action = form
|
||||
.get("action")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("insert");
|
||||
let table = form
|
||||
.get("table")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("");
|
||||
let heading = form
|
||||
.get("title")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(form_id);
|
||||
let post_to = form
|
||||
.get("action_url")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string())
|
||||
.unwrap_or_else(|| format!("/_form/{form_id}"));
|
||||
let cancel = form
|
||||
.get("cancel_href")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("/");
|
||||
let row_id = form.get("id").map(cell_str).unwrap_or_default();
|
||||
let show_meta = form
|
||||
.get("show_meta")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(true);
|
||||
|
||||
let mut body = String::from("<div class=\"site-form\">");
|
||||
if show_meta {
|
||||
body.push_str(&format!(
|
||||
"<p class=\"meta\">table=<code>{}</code> · action=<code>{}</code> · id=<code>{}</code></p>",
|
||||
esc(table),
|
||||
esc(action),
|
||||
esc(heading)
|
||||
));
|
||||
}
|
||||
body.push_str(&format!(
|
||||
"<form method=\"post\" action=\"{}\"{}>",
|
||||
esc(&post_to),
|
||||
if fields.iter().any(|f| {
|
||||
f.get("type")
|
||||
.and_then(|v| v.as_str())
|
||||
.is_some_and(|t| t.eq_ignore_ascii_case("file"))
|
||||
}) {
|
||||
" enctype=\"multipart/form-data\""
|
||||
} else {
|
||||
""
|
||||
}
|
||||
));
|
||||
if let Some(token) = csrf.filter(|s| !s.is_empty()) {
|
||||
body.push_str(&format!(
|
||||
"<input type=\"hidden\" name=\"_csrf\" value=\"{}\"/>",
|
||||
esc(token)
|
||||
));
|
||||
}
|
||||
if action == "update" && !row_id.is_empty() {
|
||||
body.push_str(&format!(
|
||||
"<input type=\"hidden\" name=\"id\" value=\"{}\"/>",
|
||||
esc(&row_id)
|
||||
));
|
||||
}
|
||||
for f in &fields {
|
||||
let name = f.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
||||
if name.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let label = f.get("label").and_then(|v| v.as_str()).unwrap_or(name);
|
||||
let ty = f.get("type").and_then(|v| v.as_str()).unwrap_or("text");
|
||||
let required = f.get("required").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let default = f.get("default").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let pk = f.get("pk").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let value = if data.contains_key(name) {
|
||||
field_text(&data, name)
|
||||
} else if name == "id" && !row_id.is_empty() {
|
||||
row_id.clone()
|
||||
} else {
|
||||
default.to_string()
|
||||
};
|
||||
let readonly = action == "update" && pk && name == "id";
|
||||
if readonly {
|
||||
body.push_str(&format!(
|
||||
"<label>{}<input type=\"text\" value=\"{}\" readonly/></label>",
|
||||
esc(label),
|
||||
esc(&value)
|
||||
));
|
||||
continue;
|
||||
}
|
||||
let req_attr = if required { " required" } else { "" };
|
||||
body.push_str("<label>");
|
||||
body.push_str(&esc(label));
|
||||
if ty == "textarea" {
|
||||
body.push_str(&format!(
|
||||
"<textarea name=\"{}\" rows=\"5\"{}>{}</textarea>",
|
||||
esc(name),
|
||||
req_attr,
|
||||
esc(&value)
|
||||
));
|
||||
} else {
|
||||
let input_type = match ty {
|
||||
"number" | "email" | "url" | "checkbox" | "file" => ty,
|
||||
_ => "text",
|
||||
};
|
||||
if ty == "checkbox" {
|
||||
let checked = matches!(value.as_str(), "1" | "true" | "on" | "yes");
|
||||
body.push_str(&format!(
|
||||
"<input type=\"checkbox\" name=\"{}\" value=\"1\"{}{}/>",
|
||||
esc(name),
|
||||
if checked { " checked" } else { "" },
|
||||
req_attr
|
||||
));
|
||||
} else if ty == "file" {
|
||||
body.push_str(&format!(
|
||||
"<input type=\"file\" name=\"{}\"{}/>",
|
||||
esc(name),
|
||||
req_attr
|
||||
));
|
||||
} else {
|
||||
body.push_str(&format!(
|
||||
"<input type=\"{}\" name=\"{}\" value=\"{}\"{}/>",
|
||||
esc(input_type),
|
||||
esc(name),
|
||||
esc(&value),
|
||||
req_attr
|
||||
));
|
||||
}
|
||||
}
|
||||
if let Some(msg) = err_map.get(name).and_then(|v| v.as_str()) {
|
||||
body.push_str(&format!("<span class=\"err\">{}</span>", esc(msg)));
|
||||
}
|
||||
body.push_str("</label>");
|
||||
}
|
||||
body.push_str(&format!(
|
||||
"<div class=\"actions\"><button type=\"submit\">Submit</button><a href=\"{}\">cancel</a></div>",
|
||||
esc(cancel)
|
||||
));
|
||||
body.push_str("</form></div>");
|
||||
body
|
||||
}
|
||||
|
||||
/// Standalone form document (`GET|POST /_form/{id}`).
|
||||
pub fn render(
|
||||
form: &Value,
|
||||
form_id: &str,
|
||||
data: Option<&Value>,
|
||||
errors: Option<&Value>,
|
||||
csrf: Option<&str>,
|
||||
) -> String {
|
||||
let heading = form
|
||||
.get("title")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(form_id);
|
||||
let mut body = String::from(
|
||||
r#"<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/>"#,
|
||||
);
|
||||
body.push_str(&format!("<title>{}</title>", esc(heading)));
|
||||
body.push_str(
|
||||
r#"<style>
|
||||
body{font-family:"IBM Plex Sans","Noto Sans SC",sans-serif;margin:1.5rem;background:#fafaf9;color:#1c1917}
|
||||
.site-form form{max-width:28rem;display:grid;gap:.85rem}
|
||||
.site-form label{display:grid;gap:.25rem;font-size:.9rem}
|
||||
.site-form input,.site-form textarea{padding:.5rem .6rem;border:1px solid #e7e5e4;border-radius:4px;font:inherit}
|
||||
.site-form input[readonly]{background:#f5f5f4;color:#57534e}
|
||||
.site-form .err{color:#b91c1c;font-size:.85rem}
|
||||
.site-form .actions{display:flex;gap:.75rem;align-items:center;flex-wrap:wrap}
|
||||
.site-form button{background:#0f766e;color:#fff;border:0;padding:.55rem 1rem;border-radius:4px;cursor:pointer}
|
||||
.site-form a{color:#0f766e}
|
||||
.site-form .meta{color:#57534e;font-size:.9rem}
|
||||
</style></head><body>"#,
|
||||
);
|
||||
body.push_str(&format!("<h1>{}</h1>", esc(heading)));
|
||||
body.push_str(&render_body(form, form_id, data, errors, csrf));
|
||||
body.push_str("</body></html>");
|
||||
body
|
||||
}
|
||||
|
||||
pub fn submit(form: &Value, data: &Value, db_url: &str) -> Result<Value, String> {
|
||||
let action = form
|
||||
.get("action")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("insert");
|
||||
let mut row_map = data_map(data);
|
||||
if action == "update" {
|
||||
if let Some(fid) = form.get("id").map(cell_str).filter(|s| !s.is_empty()) {
|
||||
if !row_map.contains_key("id") {
|
||||
row_map.insert("id".to_string(), json!(fid));
|
||||
}
|
||||
}
|
||||
}
|
||||
let data = Value::Object(row_map.clone());
|
||||
let v = validate(form, None, &data);
|
||||
if !v.get("ok").and_then(|x| x.as_bool()).unwrap_or(false) {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"errors": v.get("errors").cloned().unwrap_or(json!([])),
|
||||
}));
|
||||
}
|
||||
let table = form
|
||||
.get("table")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "form missing `table`".to_string())?;
|
||||
let row = Value::Object(row_map);
|
||||
let result = if action == "update" {
|
||||
let id = form
|
||||
.get("id")
|
||||
.map(cell_str)
|
||||
.filter(|s| !s.is_empty())
|
||||
.or_else(|| data_map(&data).get("id").map(cell_str))
|
||||
.ok_or_else(|| "update requires `id`".to_string())?;
|
||||
db::update(db_url, table, &id, &row, None)?
|
||||
} else {
|
||||
db::insert(db_url, table, &json!([row]), None)?
|
||||
};
|
||||
let redirect = form
|
||||
.get("redirect")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("/");
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"result": result,
|
||||
"redirect": redirect,
|
||||
}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::json;
|
||||
|
||||
#[test]
|
||||
fn file_field_adds_multipart_enctype() {
|
||||
let form = json!({
|
||||
"table": "x",
|
||||
"fields": [
|
||||
{"name": "title", "label": "Title", "type": "text"},
|
||||
{"name": "file", "label": "File", "type": "file"},
|
||||
]
|
||||
});
|
||||
let html = render(&form, "up", None, None, None);
|
||||
assert!(html.contains("enctype=\"multipart/form-data\""), "{html}");
|
||||
assert!(html.contains("type=\"file\""), "{html}");
|
||||
assert!(html.contains("name=\"file\""), "{html}");
|
||||
}
|
||||
}
|
||||
|
||||
Loaded 100 of 259 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user