diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 9e1dd7c..6eafb66 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6dca3aa..da2b5b1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -126,6 +126,9 @@ 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index ccafa28..6de2df1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,19 +1,54 @@ # 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 -- **M1 `()` 内调用语法**:`加(1)` / `加(1, 2)` / `加(加(1 2), 10)` / `加一 号(31)`(callee 可含空格,解决 D8)/ `txt.str_trim(" x ")`。`)` 是参数终止符,逗号可选,支持嵌套。括号形参数值按表达式解析,空格形(`> f k=v`)仍按文本,`source=print(2+2)` 不受影响。 - ### Fixed -- `加(31)` 曾被解析成 `unknown function 加(31`(末个位置实参吞掉 `)`)。 - ### Changed -- **精简**:删除 `plugins/web-rust-archive/`(14,235 行 Rust,非 workspace 成员、默认不构建;Go `libweb` 已取代)。Git 历史仍可追溯。 - ## v1.5.2 — 2026-10-18 ### Highlights diff --git a/Cargo.lock b/Cargo.lock index 95a7333..14cf5d8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" [[package]] name = "marqdo" -version = "1.5.2" +version = "2.0.0" dependencies = [ "anyhow", "assert_cmd", @@ -603,14 +603,14 @@ dependencies = [ [[package]] name = "marqdo-plugin-sdk" -version = "1.5.2" +version = "2.0.0" dependencies = [ "serde_json", ] [[package]] name = "marqdo-wasm" -version = "1.5.2" +version = "2.0.0" dependencies = [ "marqdo", "serde_json", diff --git a/Cargo.toml b/Cargo.toml index a8b624a..a89dfea 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "marqdo" -version = "1.5.2" +version = "2.0.0" edition = "2021" license = "Apache-2.0" description = "Marqdo — Markdown markers as an interpreted programming language" diff --git a/README.md b/README.md index 595074c..1062f7c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Marqdo +# Marqdo **代码即文档。文档即知识库。知识即可执行。** @@ -193,8 +193,9 @@ marqdo catalog public -o .marqdo --- -## 现状(v1.5.2) +## 现状(v2.0.0) +- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0** - **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2** - **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0** - **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5** @@ -230,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.2) +### 如何使用最新 Marqdo(v2.0.0) **安装解释器(任选其一)** @@ -245,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.2 # 或留在 main +git checkout v2.0.0 # 或留在 main cargo build --release export PATH="$PWD/target/release:$PATH" marqdo version @@ -284,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.2 +# https://github.com/cflmy/marqdo/releases/tag/v2.0.0 ``` 开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`: diff --git a/crates/marqdo-plugin-sdk/Cargo.toml b/crates/marqdo-plugin-sdk/Cargo.toml index 25aa058..6cabd42 100644 --- a/crates/marqdo-plugin-sdk/Cargo.toml +++ b/crates/marqdo-plugin-sdk/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "marqdo-plugin-sdk" -version = "1.5.2" +version = "2.0.0" edition = "2021" [dependencies] diff --git a/crates/marqdo-wasm/Cargo.toml b/crates/marqdo-wasm/Cargo.toml index d763e63..14aa363 100644 --- a/crates/marqdo-wasm/Cargo.toml +++ b/crates/marqdo-wasm/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "marqdo-wasm" -version = "1.5.2" +version = "2.0.0" edition = "2021" license = "Apache-2.0" description = "Marqdo interpreter as WebAssembly (browser host bridge)" diff --git a/debian/changelog b/debian/changelog index 85ebaef..f436d99 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,15 @@ +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 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 diff --git a/ext/VERSION b/ext/VERSION index 4cda8f1..227cea2 100644 --- a/ext/VERSION +++ b/ext/VERSION @@ -1 +1 @@ -1.5.2 +2.0.0 diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index 123c953..d6ff4bf 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -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. +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. 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