Compare commits

..
200 Commits
Author SHA1 Message Date
cflmy ae97891266 release: v2.1.0 — file-scoped occlusion 2026-10-23 12:59:28 +00:00
cflmy aea86746e7 feat: migrate corpus to file-scoped occlusion 2026-10-23 12:45:01 +00:00
cflmy c773503938 Merge branch 'main' of https://github.com/cflmy/marqdo
# Conflicts:
#	tests/migrate.rs
#	tests/occlusion/classic-index.mq.md
2026-10-23 12:11:58 +00:00
cflmy 939e23ee88 refactor: scope markup compatibility per invocation 2026-10-23 12:11:26 +00:00
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00
cflmy eac9b45263 feat: compile executable knowledge semantic artifacts 2026-10-23 09:16:52 +00:00
cflmy 74b298e80d build: add portable development toolchain setup 2026-10-23 09:00:56 +00:00
cflmy fc7097bae4 test: validate executable knowledge syntax across libraries 2026-10-23 08:47:49 +00:00
cflmy b624084745 feat: classify associated and instance symbols 2026-10-23 08:26:33 +00:00
cflmy 0bbe735c3c feat: add stable executable knowledge symbols 2026-10-23 08:24:10 +00:00
cflmy 92de46aca4 docs: define executable knowledge implementation baseline 2026-10-23 08:06:38 +00:00
cflmy 8bbe017a5e docs: define executable knowledge step architecture 2026-10-23 15:46:02 +08:00
cflmy 1a13989230 fix(ext/ai): 变量引用补反引号;prompt 缺失回退空串
- llm/agent 模板中的变量引用统一加反引号
- ask/stream 在 prompt/path 均缺失时回退空串,避免直接退出
- 修正 stream 分支返回缩进;agent workbook 模板改用 ** 代码块
2026-10-23 14:52:26 +08:00
cflmy 5ad1a07f5c docs(language): 链接语法与知识分层设计声明 + 示例
- []() 零新语法:描述 + 已有类/函数调用,不引入 ref/别名/开关
- # 是类、## 是函数;类.函数 是类调用;跨文档用项目类索引
- 知识分层:原始语料 / 本体 / 单体知识类 / 调用面;出处与还原验证
- 新增 link-syntax、knowledge-layers 设计声明与两组可运行/目标示例
2026-10-23 14:52:23 +08:00
cflmy bcfc763ba4 fix(parse): 孤立 * 行不再 panic(exit 101 → 干净诊断)
qdagent 全仓 labels 扫描期间实测:任何 .mq.md 里有一行只含单个 `*`
(markdown 强调残留)时,`*…* = 返回` 分支同时满足 starts_with/ends_with('*'),
切片 &trimmed[1..0] 越界,整条 labels 扫描被一个文件打死(exit 101)。

修复:斜体返回分支要求 len >= 2,裸 `*` 落回 "unrecognized statement"
干净错误而非崩溃。

实测:
- tests/errors/lone-asterisk.mq.md → check 报 "unrecognized statement: *",
  exit 1(不再 101)
- gold 回归 error_lone_asterisk_line 通过
- cargo test --release 全套件 0 failed
2026-10-22 19:04:25 +08:00
cflmy bf76e069ee release: v2.0.0 — 遮蔽语法落地([描述](实现) / 标签欠据 / 全仓迁移)
Bump CLI, wasm and plugin SDK to 2.0.0; sync ext/VERSION, Cargo.lock,
CHANGELOG (Highlights + 核心表面 Δ), README, release highlights stub,
skills and debian/changelog.
2026-10-22 16:26:29 +08:00
cflmy 9015de26e5 feat(view): M8 遮蔽呈现 — 描述为正文、实现为代码片、桩有徽章;并修复 view 解析模式回归
一、先修回归(用户看到"没渲染"的真因)
view 多处直接用 crate::parse::parse_source 重新解析文件,而 per-file markup:
是在 load 层生效的(M7)。于是任何带 markup: occlusion 的文档在结构区报
"parse/load error: expected ')' after link-index collection",退化成源码视图。
→ 新增 load::parse_source_auto(source):先读 frontmatter 的 markup:,用
  with_markup 包住解析;view 的 4 处解析点全部改用。

二、遮蔽呈现
浏览视图(document.rs / /file):
  <div class="doc-line doc-occl">
    <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 一致。

卡片视图(render.rs / /debug):按 AST 匹配 Expr::Occluded(Assign/Expr/Return),
渲染 card occl-card:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩。

样式刻意不加虚线下划线(易读成链接):描述即正文,靠代码片边框区分。

验证:
- /file 页面 0 处 parse/load error;7 个遮蔽行全部渲染
  (6 代码片 + 1 桩),文本抽取为「留存 = 客户留存率,模拟数据 [0.42]」
- 4 个单测(裸赋值/粗体赋值/空载荷+嵌套/非遮蔽不误判)
- 全量 cargo test --release 613 passed / 0 failed

未能截图:本机无任何浏览器,puppeteer 的 Chromium 下载被网络阻断;
改为 DOM 断言 + /.preview/occlusion.html 方案对照页由作者目视确认。

文档:doc/design/change-m8-view-occlusion.md
2026-10-22 16:16:32 +08:00
cflmy 8c24d96626 docs(examples): 遮蔽改用裸赋值 名 = [描述](实现),不再包进粗体
用户指出:`**留存 = [客户留存率,模拟数据](0.42)**` 在阅读器/高亮里
描述被粗体吞成"代码味",人话反而不显眼。

改为裸赋值形式(与粗体形式语义完全等价,实测四项一致):
  `留存` = [客户留存率,模拟数据](0.42)
  `待接` = [搜索接入,接口未接,待开发]()
  `取第一` = [第一颗](access(`篮子`, "1"))
  `个数` = [篮子有几颗](table.len(`篮子`))
  `表取` = [用 table.get 读同一个键](table.get(`饮品价`, "美式"))
  `长度` = [名字长度](len(`名`))

等价性实测(b.mq.md):留存=0.42 / 待接=None / 取第一=苹果 / 个数=2,
check 只报同一条 label.empty_payload,labels 命中同样两处。

并在第 5 节补一句为什么这样写:粗体是给"表达式赋值"用的紧凑写法,
而遮蔽的前提是"描述给人读",所以描述不该被强调形式包住。

顺带说明(不是本次改动):view 的代码区展示的是**高亮后的源码**,
不是 Markdown 渲染,所以 `[..](..)` 在两种写法下都不是可点链接;
真正的呈现改进(描述为正文、实现为代码块)属于 M8 未做部分。
2026-10-22 16:03:59 +08:00
cflmy 4a2f5bf226 docs(examples): 新增 examples/syntax-tour — 一页跑通全部现行语法
十个板块,全部可执行(marqdo run 实测通过):
1 变量与插值  2 函数与契约  3 调用四种形态(> 前缀 / 括号位置 / 逗号 /
  嵌套 / 带空格函数名)  4 取值 access / table.len / table.get
5 遮蔽(普通 + 空载荷桩)  6 循环(遮蔽循环 + while 式递减)
7 分支  8 表格三态(竖表 List / 横表 Map / 行向 List[Map])
9 值类型  10 收尾

写作过程中踩到的真实约束(都已按现行语义修正):
- `##` 是函数定义,正文分节不能用 `##`(改用散文分隔行)
- 函数内看不到模块级变量,`计税` 改为自包含的分支查表
- 反引号插值只接受变量名,不能写 `len(`名`)`,需先算出变量
- `()` 内的 payload 是表达式,空格形调用要写成括号形
  (`table.get(表, 键)` 而非 `table.get map=… key=…`)

实测:run 输出 25 行符合预期;check 仅 1 条有意保留的
label.empty_payload(正是第 5 节要演示的空载荷规则);
labels 命中 2 个已申报桩。
2026-10-22 15:57:48 +08:00
cflmy 86e921e959 feat(migrate): 支持多路径;docs: 体量审计修正两条不成立的判断
- migrate labels 接受多个 PATH(与 labels 一致);全仓干跑幂等:
  lib/ext/cli/examples/public 均为 0,tests 仅剩刻意保留的 classic 样例 1 处
- 审计修正:
  * html.rs 皮肤"重复声明基础 CSS" —— 实测 312 vs 128 条规则、选择器零重叠,不成立
  * debug_page "复刻 shell" —— 仅 head/favicon 约 10 行相似,它没有 nav/topbar,不成立
  * HostFn 五表合一标记为已完成(−404 行)
- 结论:可机械消除的重复已清完;剩余体量全是特性实现

全仓校验:63 个文件 check 零诊断(label.* 全 0);
cargo test --release 609 passed / 0 failed。" && timeout 300 git push origin main 2>&1 | tail -1
2026-10-22 15:52:22 +08:00
cflmy b196a44685 refactor(host): HostFn 五张表合一 — HOST_FN_TABLE 单一来源(−404 行)
202 个宿主函数的元数据原本分散在 from_u16 / from_name / name /
required_params / optional_params 五个手写 match 里,必须同步维护,
审计已记录过 from_name 与 name() 的漂移。

改动:
- 新增 HostFnDef + HOST_FN_TABLE(203 项:id, 变体, 规范名, 必填, 可选)
- from_u16 按 id 查表;name / required_params / optional_params 按判别值查表
- call_host 的 202 个一行臂保持不变(只集中元数据,不动分派逻辑)
- from_name 保留:它是别名注册表(http_get/中文别名…),语义与规范名不同

等价性证明(快照比对):
1. 先在旧实现导出全部 203 项的 (id,name,required,optional) 到 TSV
2. 合并后用同一段代码再导出
3. diff 两份 → 完全一致;快照测试用后即删

长期守护(4 个不变量测试,上一轮已加):
id↔as_u16 往返、name→from_name 往返、规范名唯一、required/optional 不重叠。

验证:cargo build 零警告;cargo test --release 609 passed / 0 failed。
行数:dispatch.rs 2052 → 1648;src 合计 53,040 → 52,668。

文档:doc/design/change-hostfn-table.md
2026-10-22 15:51:26 +08:00
cflmy c8ed5bffb7 docs: 体量审计更新 — 插件 SDK 完成(净减 674 行),合计 67,786 2026-10-22 15:49:26 +08:00
cflmy fb135ae2f8 refactor(plugins): 抽出 marqdo-plugin-sdk — ABI 前言从 5 份变 1 份
新增工作区成员 crates/marqdo-plugin-sdk:ABI 类型、HOST_* 静态回调、
host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/
take_host_string/init_plugin,以及生成四个 #[no_mangle] 导出的
marqdo_plugin! 宏。ABI 常量、符号名、结构体布局一律未变。

5 个插件改为依赖 SDK + 一行宏调用:
  agent  1237 → 929  (-308)
  quantum 1045 → 835 (-210)
  linalg  688 → 524  (-164)
  llm     405 → 278  (-127)
  demo    170 → 73   (-97)
  SDK 新增 232 行 → 净减约 674 行

迁移中发现并修正三次"编译通过但语义已变":
1. 注册项抽取漏 11 项 —— 正则 [a-z_0-9]+ 匹配不到 mcp_server::agent_mcp_serve、
   sandbox::* 这类路径限定函数名;改为允许 :: 后重抽。
   已用脚本逐项比对 (名称, 参数串, 函数) 三元组:agent 63/63、quantum 41/41、
   linalg 31/31、llm 2/2、demo 2/2,全部 0 差异。
2. mcp_client 被误判死模块(删 327 行后才发现 agent_mcp_client 正注册它)→ 恢复。
3. 量子插件两个"未使用"函数删除时连带吃掉 density_from_amps/flat_to_nested
   → 恢复原文件并改为 #[allow(dead_code)]。

验证:cargo build --release(含 5 个插件)零警告;
cargo test --release 609 passed / 0 failed;
量子金样实跑 p00-ok / p11-ok / ping-ok。

文档:doc/design/change-plugin-sdk.md
2026-10-22 15:49:13 +08:00
cflmy 69fcdd6227 docs: 代码体量审计 — 53k 行构成、已清 14.5k 冗余、剩余为特性面
把账算清楚,避免行数多=冗余多的误判:
- src 53,072(其中 5,220 是内联测试)+ plugins/crates 15,423
- 最大的 10 个文件逐一标注性质(html.rs 4,451 行里 3,861 是页面皮肤字符串)
- 已清除 14,235 + ~400 行,逐项列提交号
- 顺带修出的 4 个真实缺陷(Access 隐式判别值、escape_js_string 漏 U+2028/2029、
  view 双 handler 路由、HOST id 稀疏无测试守护)
- 剩余可精简项:插件 ABI SDK(~550)、html 皮肤(~250)、debug_page(~120)、
  HostFn 五表(~450),合计约总量 2%,标注风险
- 结论:继续压体量的正确方向是砍特性,而不是在特性内部找重复(已找完)
2026-10-22 15:44:37 +08:00
cflmy deac53d0f5 refactor(view): AST 遍历器合流 — walk_stmts / stmt_line 收进 ast
三处各自实现的「深度优先遍历函数体」合并为一个:
- ast::walk_stmts(fun, &mut |stmt| ...):body + 分支臂 + 循环体 + 子函数
- ast::stmt_line(stmt):语句行号(原 view::document 私有副本)

改造:view/annot.rs::fun_stmt_lines、view/document.rs::index_stmt_lines
(annot 的 collect_name_sites 保留自己的收集逻辑,只借遍历)

cargo build 零警告;cargo test --release 609 passed / 0 failed。
view/annot.rs -30 行、view/document.rs -41 行。
2026-10-22 15:44:20 +08:00
cflmy 932403237a test(host): HostFn id/name/params 一致性测试;refactor: 转义函数去重
一、先暴露问题:写 4 个一致性测试后发现——
- id 空间是**稀疏**的(10 个退役 id),不是连续的;测试按"每个已分配 id 都能还原"重写
- Access 变体只有隐式判别值,补 `= 212` 使之显式(避免重排时静默错位)
- 四个测试现在锁定:id→as_u16 往返、name→from_name 往返、名称唯一、
  required/optional 不重叠且无重复参数。审计提到的 from_name/name 漂移由此可被捕获。

二、转义去重
- urlencoding_encode 与 urlencoding_path 逐字相同 → 合并为 urlencoding_path(pub(crate))
- escape_js_string 两份:debug_page 的副本漏了 U+2028/2029 转义(真实缺陷)
  → 保留 html 的完整版并 pub(crate),debug_page 改为引用

cargo build 零警告;cargo test --release 609 passed / 0 failed(605 + 4 个新测试)。
2026-10-22 15:42:42 +08:00
cflmy a14a6e221d refactor: 删除无调用点的死代码(审计项)
- src/parse/mod.rs: parse_italic_assign(17 行,0 引用)
- src/host/sandbox_fs.rs: unavailable
- src/knowledge/extract.rs: stem_of
- src/knowledge/lifecycle.rs: _system_time_now
- src/debug/ctrl.rs: action_channel
- 连带清理 3 处随之失效的 import

cargo build 零警告;cargo test --release 605 passed / 0 failed。
src 行数 53,079 → 52,96x。
2026-10-22 15:40:31 +08:00
cflmy 8b0ea9ed7a refactor: 精简三处重复 — as_text×18、catalog 助手×4、view 路由 34 臂
按审计结论清理冗余(不改变行为):
1. as_text:17 个 host 模块各自复制同一函数(两种措辞),合并为
   crate::host::as_text(统一 "{label} needs text",无测试依赖旧措辞)
2. catalog.rs:extract_fm_field / extract_nested_by / extract_fm_list /
   yaml_escape 与 knowledge::util 逐字相同,改为直接引用
3. view/mod.rs:handle 29 臂 + handle_debug 5 臂折叠成两张路由表
   (Notebook/Debug/Action 三种处理器),每臂原本重复同一 api_debug_post 包装

实测:
- cargo build 零警告;cargo test --release 605 passed / 0 failed
- view 服务实测:GET / → 200;POST /api/debug/continue → 200(真实响应
  {"error":"unknown session"});POST /api/nope → 405

行数:view/mod.rs -99(168 删 69 增);src 合计由 53,276 降至约 53,000
(as_text 18 文件各约 6 行、catalog 4 函数约 70 行)

期间发现并修正一处真实风险:路由臂分布在两个 handler(handle / handle_debug),
首次只替换了一个导致 debug 路由 405;已按 handler 分别建表并由实测覆盖。
2026-10-22 15:39:18 +08:00
cflmy 6ae0d39e5a feat(labels): 兼容文档里的 labels pending / labels search 写法
设计文档写的是 `labels pending` / `labels search --grep`,CLI 是扁平参数。
把 pending/search 作为无意义位置词过滤掉,使两种写法都可用(不动参数语义)。
实测:labels pending --count → 2;labels search --grep 联调 --count → 1。
全量 605 passed / 0 failed。
2026-10-22 15:34:55 +08:00
cflmy 307c8efa81 feat(labels): 支持多路径扫描;docs: 里程碑全量完成状态与变更文档索引
- labels 接受多个 PATH(默认 .),合并去重后扫描
- occlusion-syntax.md §13.1 记录 M0–M10 全部完成,附 11 份变更文档索引
- 全仓校验:98 个文件 check 零诊断(label.* 全为 0,确认无噪音)
- cargo test --release 605 passed / 0 failed;0 编译警告
2026-10-22 15:34:29 +08:00
cflmy 34b0911218 feat(labels): M8 债务棘轮 — --baseline + --fail-on-increase
规则:未完成项只许减少,不许增加。
- 台账不存在 → 建立(写入当前计数)并提示,exit 0
- 当前 > 台账 → 失败并提示"未完成项增加了 K",exit 1
- 当前 ≤ 台账 → 通过;若减少则**收紧**台账(N → M)

为什么减少即收紧:否则债务可先降后升,棘轮形同虚设;
收紧后回退到旧数量同样失败(测试第 4 步验证)。

台账格式 {"count":N,"words":[…]},记录词集使"口径变更"可审计。

为什么用棘轮而非硬门禁:硬门禁(必须为 0)会让存量债立刻红一片、逼人关检查;
棘轮做到"老账不追、新账必拦",与防疲劳机制的结论一致。

呈现面复核:expr_display / view 把遮蔽渲染为 [描述](实现)、桩为 [描述](),
实测 view output 页面含 access(;未做桩徽章——桩已是显眼形状,再加装饰是噪音。

测试:四步集成用例(建账 → 增加失败 → 减少收紧 → 回退再次失败);
全量 605 passed / 0 failed(M7 后 604 + 1)。

文档:doc/design/change-m8-ratchet.md
2026-10-22 15:34:07 +08:00
cflmy 4488a3cb70 feat(migrate): M7 迁移与版本门 — per-file markup + migrate labels + 全仓迁移
原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同,
翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。

一、per-file markup
- frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式
- load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析
- 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认
- 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义

二、`marqdo migrate labels [--write|--json]`
改写规则:
  [键](集合)      → [键](access(集合, "键"))
  [`名`](集合)    → [名](access(集合, `名`))
  - [项](集合)    → - [项](遍历 集合 为 项)

安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B
- 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index)
- Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动

只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰;
链式索引由内向外改写,已迁移的有守卫不二次改。

三、access 提升为宿主函数 HostFn::Access(u16 id 212)
与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key);
进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。

四、顺带修的两处真实语义缺陷
1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用
   → `()` 内永远允许 callee(args)
2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽
   → 要求 `]` 后紧跟 `(`,否则落回方括号调用

五、全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝;
迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。

等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、
遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。

测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 /
等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。

文档:doc/design/change-m7-migration.md
2026-10-22 15:33:31 +08:00
cflmy 9dbcc728b6 docs(design): 记录里程碑进度 — M0/M1/M2/M2.5/M3/M4/M5/M6/M9/M10 已完成,M7/M8 待做 2026-10-22 15:23:54 +08:00
cflmy 0405a60d68 feat(lang): M3 access 内建与遮蔽循环 — 为 M7 迁移准备等价语义
access(集合, 键)(别名 取/取值):
- 复用 builtin_footnote_get,与旧 [键](集合) 语义完全一致
  (Map 按键 / List 1-based 下标 / 缺键报 missing map key,不静默 None)
- 不新增平行实现,避免两套索引语义漂移
- 用途:M7 把 506 处 [k](c) 机械改写成 access(c, k),语义零漂移

遮蔽循环:- [描述](遍历 集合 为 变量)
- 仅 occlusion 模式识别;接受 遍历/for 与 为/as/in
- 描述存入 Stmt::ForEach.label(Option<String>),供 M8 渲染/诊断

为什么先 M3 后 M7:迁移目标必须先存在且等价,否则就是"边迁移边发明语义"。

实测:
  access(`表`,"键") → 值;access(`列`,2) → 二;
  缺键 → missing map key(与旧取元同一错误)
  - [篮子里的每个果子](遍历 `列` 为 `果`) → 果=一 / 果=二

测试:2 个集成(含缺键错误保真);全量 595 passed / 0 failed(M5 后 593 + 2)

文档:doc/design/change-m3-access-and-loop.md
2026-10-22 15:23:36 +08:00
cflmy 409b8df2cb feat(check): M5 隐式遮蔽 — > 调用上方的叙述作为描述(默认关闭)
规则:`>` 调用上方的叙述段即其"描述";段内反引号实体必须被该调用用到,
或能解析到模块/内置,否则报 label.implicit_stale(warning)。
段落边界:紧邻上一行起,允许一个分隔空行(blockquote 前常空一行),
遇第二个空行/标题/代码行即止。

关键决策:**默认关闭(--implicit-labels 开启)**,依据是实测噪音:
- 初版(任何反引号都算断言):lib+ext/ai 上 6 条警告,**全为误报**
  (`## open`、`{ path, kind }`、`source=`、`exec`/`net`)
- 加"实体名形状"过滤后:2 条
- 再加默认关闭:**0 条**
理由:描述一个调用可以用任意措辞,机械校验必然模糊;
默认开启就制造疲劳(违背 warning-fatigue-control)。这与 L1 不同:
L1 是"能证明才报",隐式检查是"可疑就报",必须 opt-in。

实体名过滤:首字符字母/_/非ASCII,其余字母数字/_/./非ASCII非空白
→ 排除 `## open` / `{ path, kind }` / `source=` / `path=`。

用法:marqdo check 文件 --implicit-labels

测试:3 个集成(默认静默 / opt-in 报不一致 / opt-in 对一致描述仍静默,
后两条是反向验证"不乱响");全量 593 passed / 0 failed(M6 后 590 + 3)。

文档:doc/design/change-m5-implicit-occlusion.md
2026-10-22 15:21:23 +08:00
cflmy 6bba0be6d2 feat(mlsp): M6 T1 会话内陈旧检测 — repair_apply 前后对照 + session.summary
机制:repair_apply 内同一作用域已同时持有 source(改前) 与 new_source(改后),
所以「描述是否还成立」可纯内存判定,无需 git/台账/exec:
  stale ⟺ 标签文本未变 ∧ payload 指纹变了
按 (标签文本, 出现序号) 配对 → 移动代码不误报。

协议:
  请求加可选 check_labels(默认 false,零开销零噪音)
  响应加 labels.stale[{label,line,code_past,code_now}] + newly_seen
  新增 session.summary → {labels_stale_seen, labels_fixed, labels_outstanding, items},
  返回后清零(客户端收尾调用一次即闭合,不主动打屏)

取舍:
- 标签变了 → 不报(作者改描述即"已复核"信号)
- 新标签 → 不报(无历史可比)
- 指纹用 Debug:只需进程内一致;跨版本稳定指纹留给 T2/T3
- code_past/code_now 用 view::expr_display 渲染成人可读的表面语法

实测:
  改 payload 0.1→0.2、标签不变 → stale 且带 code_past="100 * 0.1" / code_now="100 * 0.2"
  同时改标签 → stale: []
  session.summary → stale_seen=1, outstanding=1, items=["按税率算总价"]

测试:3 个集成(含反向验证"改描述即复核不误报");
全量 cargo test --release:590 passed / 0 failed(M10 后 587 + 3)

文档:doc/design/change-m6-t1-session.md
2026-10-22 15:19:17 +08:00
cflmy 1c90312c02 feat(ai): M10 把「接不了就申报」写进 agent 提示词(standing + how-to-act)
两处:
1) how-to-act 协议段(每轮都带):无法真正接通的capability 不许静默伪造、不许声称完成,
   改写成带状态的遮蔽,例如 [按关键词检索,接口未接,待开发](None);
   桩必须能跑并写清返回值(None 亦可);收尾用 labels.search 自查。
2) 默认 standing(p):追加一句"接不了就在描述里申报(待开发/模拟),别假装成功"。

为什么两处:standing 定基调(每轮开头),how-to-act 定动作(每轮),
只写一处会被长上下文冲淡或缺动机。
设计要点:给范式而非规则(可直接抄)、给返回值要求(对应 label.empty_payload)、
给自查动作(labels.search)、用英文与既有协议一致。

验证:marqdo check ext/ai/agent.mq.md(occlusion 模式)通过;
grep 确认两处文本落地;全量回归 587 passed / 0 failed(不改逻辑)。

文档:doc/design/change-m10-engineering-habits.md
2026-10-22 15:17:43 +08:00
cflmy fd0cfcb566 feat(labels): M9 两级词表检索 — labels CLI + MLSP labels.search
第一级(内置,数据常量):六组关键词 —— 未完成/假数据/示例/实验/废弃/待校验,
pending = 未完成 ∪ 假数据。作用是默认查询、LLM 范例、跨项目可比。
第二级(参数):--grep 替换,--also-builtin 并集,--group 选组。
**词表是数据不是语法**:扩充它不改任何解析规则。

CLI:
  marqdo labels .                              # pending 口径
  marqdo labels . --grep "联调"                 # 自定义替换
  marqdo labels . --grep "联调" --also-builtin   # 并集
  marqdo labels . --group 示例,实验
  marqdo labels . --count / --json

MLSP:{"method":"labels.search","params":{path|source, grep?, also_builtin?, group?}}
→ {"ok":true,"words":[…],"count":N,"hits":[{line,unit,label,words,has_payload}]}
与 CLI 共用同一份 label::search。

检索语义 v1:子串匹配(CJK 无词边界)、多词 OR、英文大小写不敏感;
误判只影响计数,输出带描述原文可人工判断;不做否定语法(留 v1.1)。

测试:4 个集成(pending=2 / grep 替换=1 / also-builtin 并集=3 / MLSP 返回 hits);
全量 cargo test --release:587 passed / 0 failed(M4 后 583 + 4)。

实测:
  pending → 2 命中("待开发"、"模拟"两处)
  --grep 联调 → 1 命中
  --grep 联调 --also-builtin → 3 命中

文档:doc/design/change-m9-label-search.md
2026-10-22 15:16:39 +08:00
cflmy 6dd0ce47b1 feat(check): M4 L1 引用一致性 — 描述里的反引号实体必须可解析(label.ref_dangling)
规则:描述里的 `名字` = 断言,必须能解析 ——
要么 () 的实现用到它,要么文档定义了它(函数/参数/import 绑定/frontmatter 键),
要么是内置函数。否则报 label.ref_dangling(error)。

只认反引号(可证伪原则):普通汉字不参与判定,避免海量假阳性;
代价是作者不写反引号就得不到保护,这是刻意的——机器只校验它看得懂的断言。

实现:
- refs(label):扫描成对反引号取内部(未闭合/空串忽略,不 panic)
- payload_idents(payload):Var / callee / path 段 / receiver / [k] 变量键 / 插值变量
- module_symbols(module):函数与子函数、参数、import/use 绑定、frontmatter 键
- 内置函数用 crate::host::HostFn::from_name 判定
- OcclusionSite 增加 payload_idents,collect 阶段一次算好

实测:
  悬空 → "描述引用了不存在的实体:`税率` ..." 1 error, exit 1
  可解析(payload 变量 / len 内置 / `> 加 1 2` 行内调用)→ 零诊断

测试:3 个单测(抽取/多引用与散文混排/未闭合不 panic)
+ 2 个集成(悬空 exit 1;三类可解析零诊断)
全量 cargo test --release:583 passed / 0 failed(M2.5 后 578 + 5)

文档:doc/design/change-m4-label-refs.md
2026-10-22 15:14:50 +08:00
cflmy 1a94cc8490 feat(check): M2.5 遮蔽标签诊断 — label.missing(error) / label.empty_payload(warning)
新增 src/label.rs:
- OcclusionSite { label, has_payload, line, unit }
- collect(module):遍历函数/分支/循环/表达式收集遮蔽点(描述只读,不产生读引用)
- check(module, path):产出两条诊断

两条诊断:
- label.missing(error):[](...) 描述为空 —— 写一句人话,或改用不带遮蔽的写法
- label.empty_payload(warning):[描述]() 载荷为空 —— 写清桩返回什么(None/0),或补实现
warning 不影响退出码;JSON 出口自动继承既有 schema(含 doc_quote/span/suggestion)。

接入 check_module:walk 之后 extend(crate::label::check(..)),保持一行;
M4(引用一致性)与 M9(检索)都往 label 模块加,check 不再膨胀。

测试:
- 3 个集成(tests/occlusion.rs):空描述 exit 1、空载荷 exit 0、干净样例无诊断
- 全量 cargo test --release:578 passed / 0 failed(M2 后 575 + 3)
反向验证:干净样例必须零输出,证明不会误响。

实测:
  MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md    # 1 error, exit 1
  MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md  # 1 warning, exit 0

文档:doc/design/change-m25-label-diagnostics.md
2026-10-22 15:13:33 +08:00
cflmy 11417c42e0 feat(lang): M2 遮蔽语法 [描述](实现) — 描述不执行,payload 是唯一执行体
新增 Expr::Occluded { label, payload: Option<Box<Expr>> }:
- [] 描述:自由文本,永不执行(仅用于检索/统计/过期校验)
- () 实现:唯一执行体;为空时值为 None(空载荷桩)
- 支持嵌套遮蔽、描述含空格与中文标点、\] 转义

关键决策:**模式开关,暂不切换语义**
[键](集合) 与 [描述](实现) 外形完全相同;M2 若直接改语义,全仓 506 处取元会
静默变成"遮蔽整个集合"(同形换义,文档点名的最坏一类)。
故 M2 只实现能力:
- 默认 Classic:MARQDO_MARKUP 未设 → [a](b) 仍是取元
- 纯度 Occlusion:MARQDO_MARKUP=occlusion/purity/1/on → 遮蔽
M7 才迁移语料、翻转默认、对旧形报 syntax.legacy_index 硬错误。

实现:
- ast.rs 新节点
- parse/expr.rs:Markup 枚举 + set_markup_default + parse_expr_markup(显式模式,
  避免测试依赖全局) + parse_occluded(描述扫描到 ]、\] 转义、必须紧跟 (、
  空载荷 → None)+ Parser.markup 字段
- interp.rs:有 payload 求值 payload,否则 None;collect_decl_reads 递归 payload
- bytecode/compile.rs:编译 payload(空则 Op::None_),双后端一致
- view/render.rs:expr_prec 渲染 [描述](payload) / [描述]()
- parse/mod.rs:pub mod expr
- main.rs:MARQDO_MARKUP 环境变量(init_markup_from_env)

测试:
- 8 个单元(值直通/空载荷/描述空格标点/转义/嵌套/classic 仍取元/缺括号报错)
- 3 个集成 tests/occlusion.rs + tests/occlusion/*.mq.md
- 全量 cargo test --release:575 passed / 0 failed(M1 后 565 + 10)
- tree 与 bytecode 双后端一致

文档:doc/design/change-m2-occlusion.md
2026-10-22 15:11:59 +08:00
cflmy 13012cac0e refactor: 精简 — 删除归档的 Rust web 插件(14,235 行)
审计结论:plugins/web-rust-archive/ 不是 Cargo workspace 成员、默认不构建、
无任何脚本/代码引用,官方 web 插件早已是 Go 版(plugins/web/ + libweb.so)。
仅作为"参考"留在树里,占 Rust 代码量约 18%。

删除内容:
- plugins/web-rust-archive/(31 个文件,14,235 行 Rust,528K)
- 更新三处指向:Cargo.toml 注释、plugins/web/README.md、ext-web-go-rewrite.md,
  说明历史保留在 git 中
- CHANGELOG Unreleased 记录此次精简

验证:cargo build --release 通过;cargo test --release 565 passed / 0 failed。

这是「不要让冗余代码毁坏 marqdo 设计」的第一步;后续按审计报告继续:
HostFn 元数据表合一(~400L)、plugin ABI 共用 SDK(~550L)、
catalog 复用 knowledge 助手(~140L)、view 路由表化(~130L)、
as_text 19→1(~90L)、view/html 字符串拆分与去重(~300L)。
2026-10-22 15:09:31 +08:00
cflmy 5a0f4ed747 refactor(parse): M1 收尾 — 删除重构后变成死代码的两个函数
- parse_call_arg_value_prefer_var:统一成 parse_call_arg_value_mode 后无调用点
- Parser::new_plain:改回 new(唯一构造点)

cargo build --release 警告清零;cargo test --lib 248 passed。
2026-10-22 15:08:55 +08:00
cflmy 05b8edc186 feat(parse): M1 ()内调用语法 — ) 终止 / 逗号 / 嵌套 / 带空格 callee
实现 M1(occlusion-syntax.md §13):把 `(…)` 变成一等调用外形。

四件事:
1. `)` 是参数终止符(历史缺陷:末个位置实参吞掉 `)`,导致 `加(31)` 报
   unknown function `加(31`)
2. 可选逗号分隔:`加(1, 2)` / `加(1 2)` 等价
3. 嵌套调用:`加(加(1 2), 10)` → 13
4. **callee 可含空格**:`加一 号(31)` → 32 —— 这是缺陷 D8 的结构性解法
   (`(` 是明确分隔符,空格不再参与切词)

实现要点:
- split_first_token / find_next_arg_boundary 重写为深度感知扫描器:
  跟踪 ()[]{} 嵌套 + 字符串 + 反引号;顶层 )/空白(括号形还含逗号)终止 token
  且不吞终止符;字符串内逗号不受影响。
- 新增 try_paren_call:callee = 第一个 '(' 之前的全部文本。
  护栏:callee 含 = [ ] ( ) " ' 即拒绝(避免把 `text=a(b)` 具名实参与
  `trim [stdout](…)` 方括号实参误判为调用);反引号允许(保留 `obj`.方法 写法)。
- 表达式级 postfix 调用(parse_primary 裸词分支,要求 `(` 紧跟)。
- is_bracket_callee_inner 允许空格:[加一 号] 31 亦可用。

关键决策(回归测试逼出来的):括号形与空格形的**参数值语义不同**——
括号形是表达式(允许嵌套调用),空格形仍是文本(`source=print(2+2)` 必须保持文本,
否则 foreign.run_lang 报 source must be text)。用 Parser.allow_paren_call +
parse_call_arg_value_mode(input, prefer_var, allow_call) 区分。

测试:新增 11 个单测(TDD:先 10 红后全绿);全量 cargo test --release
565 passed / 0 failed(基线 554 + 11);tree 与 bytecode 双后端输出一致;
端到端 marqdo run 六用例符合预期。

顺带:删除变成死代码的 end_of_quoted_string(编译警告清零)。

文档:doc/design/change-m1-paren-call.md(含决策依据、护栏表、边界)。
2026-10-22 15:08:02 +08:00
cflmy 8926f7bed6 docs(design): M0 语义冻结 — 遮蔽语法系列文档标记 Accepted
用户已批准:内置词表先按现方案(六组、两级检索),后续可调。
本提交只改文档状态,不动代码:

- occlusion-syntax.md:Proposed → Accepted · 实施中(M0 起)
- occlusion-description-and-search.md:Proposed → Accepted · 实施中
- warning-fatigue-control.md:Proposed → Accepted(机制基线:stale 是变更报告)
- staleness-providers.md:Proposed → Accepted · 修订
- t1-session-staleness.md:Proposed → Accepted · 机制说明
- label-freshness-and-repair.md:Proposed → Accepted

后续按 M1 → M2 → M2.5 → M4 → M9 → M10 → M6 → M5 → M3 → M7 → M8 逐步落地。
2026-10-22 15:03:26 +08:00
cflmy 18b0c655f7 docs: 两级词表定稿 + README 工程习惯 + M10 提示词落点
按用户决定:内置词表保留(作范例与默认检索集),检索语义仍由参数指定;
工程化写进 README;有提示词的更新提示词。

一、occlusion-description-and-search.md 改为「两级检索」
- 第一级 内置词表 = 范式 + 默认检索集 + 默认豁免集(零配置可用,跨项目可比,
  给 LLM 稳定范本,避免它每次发明措辞)。六组:未完成/假数据/演示/不稳/将删/待核;
  pending = 未完成 ∪ 假数据。
- 第二级 参数:--grep A,B 替换;--also-builtin 并集;--group 选内置组;MLSP 同构
  (labels.search { grep, also_builtin })。
- 明确:内置词表是数据不是语法;词表扩容不动语法;写别的措辞完全合法。
- 空载荷一律 warning(写 None 消除);「命中内置集则降为 hint」留作非默认旋钮。
- stale 豁免默认用内置 pending/将删组,--stub-words 可覆盖。
- 识别仍为纯子串、无位置/分隔符要求;识别不到不报错;误判只影响计数。

二、README.md 新增「工程习惯:允许申报未完成,但不允许假装完成」
- 示例:空载荷桩 / 假数据桩 + 桩契约
- 四条约定:桩必须能跑、必须写明返回值、申报有范例、接不了就申报别声称完成
- 盘点与门禁命令:labels pending / labels search --grep / --also-builtin /
  --count --baseline --fail-on-increase(棘轮)
- 指向两份设计文档

三、总纲增补 M10(工程化落点):README 一节 + ext/ai/agent.mq.md 提示词两处
(:48 默认 standing、:39 how-to-act 协议段)追加申报约定;顺序
M0→M1→M2→(M2.5)→M4→M9→M10→M6→M5→M3→M7→M8。

四、实现点明确分层:内置词表是常量数据、检索是纯函数、语法零依赖。

未改代码(README 为文档)。
2026-10-22 14:25:51 +08:00
cflmy 924885969f docs(design): 删除内置词表,检索改为调用方传词;空载荷一律 warning
用户质疑「关键词表其实不是很有必要,为什么不能允许 LLM 直接传入某个关键词做检索」——成立,
词表是冗余层。本文重写并改名 occlusion-description-and-search.md(原 occlusion-tags-and-stubs.md)。

一、编译器不再内置任何词表
只做两件事:原样保存描述字符串 + 提供参数化检索。
  marqdo labels search --grep 待开发,未实现,开发中   # OR 子串匹配
  marqdo labels search --grep 接口 --json            # 任意词
  marqdo labels search --grep 待开发 --count         # 只数数
MLSP 对应 labels.search。
删词表的理由:词表是语义偏见("什么算未完成"是项目判断);永远不全
(开发中/未接/待联调/占位/TODO 追不上真实语言);闭集要改编译器;分类应在查询期而非编译期;
LLM 更会挑词。**编译器保持哑,查询保持聪明。**

二、唯一代价与其解法
CI 需要"什么算欠债"的定义 → 不是把词表放回编译器,而是**在调用处声明**(通常写在 CI 脚本):
  marqdo labels search --grep "待开发,未实现,开发中,模拟,桩" --count \
    --baseline .marqdo/pending.json --fail-on-increase
词集在仓库里可读可改可评审,换项目只换词集,编译器一行不改。

三、空载荷改为**一律 warning**
原设计"已申报则不打扰"依赖词表;词表删掉后无法判定是否申报,故改为一律:
() 为空 → label.empty_payload。修法极简——写 None 或一个真实返回值。
实测确认 None 是合法表达式(json.stringify → null),所以 [功能开发中](None) 可用。
补充:遮蔽语法是新形式,今天仓库里一处都没有,**这条 warning 不可能产生历史债**。

四、stale 豁免也改为调用方决定
check --stub-words "待开发,模拟" / MLSP validate.stub_words;**不传则不豁免**。
与"参数化"一致:豁免也是调用方的判断,不在编译器里写死。

五、检索语义 v1:子串匹配(CJK 无词边界)+ OR + 英文忽略大小写;
输出含文件/行号/描述原文/() 代码/命中词;误判必然存在但只影响计数,且输出带原文可人工判断;
不做否定语法(留 v1.1「否定词窗口」可选项)。

六、工程化章节保留并简化:agent 提示词(写不了就申报、桩必须能跑、写清返回值、
收尾用 labels.search 自查)、四个工具面、四个指标(pending_count/unlabeled_empty/stub_ratio/stub_age)。

七、实现点:无任何词表常量;src/label.rs 为索引与检索器;
check 三条硬规则(label.missing error / label.ref_dangling error / label.empty_payload warning);
描述不影响求值;空载荷 → None。

同步 occlusion-syntax.md(空载荷说明改为一律 warning、M9 改为「描述检索与桩」、增补链接)
与 doc/README.md 索引;文档改名为 occlusion-description-and-search.md。未改代码。
2026-10-22 14:21:36 +08:00
cflmy 619271b8eb docs(design): 关键词改为纯子串检索(无分隔符)+ 空载荷 warning + 工程化实践
按用户两点修正:

一、关键词匹配不再有任何位置/分隔符规则 —— **纯子串检索**
[某某功能开发中]() 合法且可被统计;[搜索接入,待开发]、[【待开发】x] 同样命中。
关键词表扩为六组(未完成/假数据/演示/不稳/将删/待核),每组含同义词
(待开发·未开发·开发中·未实现·待接…;模拟·假数据·桩·占位·stub…)。
识别不到不报错不提示;最多取 3 组,最强者决定语义(未完成>假数据>示例>实验,将删正交)。
诚实写明子串必然误判([不属于待开发范围] 会命中):不影响执行,只让计数偏大;
stubs --list 显示描述原文可人工识别;否定词窗口留作 v1.1 可选。

二、空载荷必须提示,不得静默
() 为空 → label.empty_payload(**warning**);**若描述已含关键词(已申报)则不报**
——否则每个桩都报,正好制造要消灭的疲劳。
文案:「空载荷遮蔽:请补 (),或在描述里写明未完成状态」。

三、新增「工程化」一节(本设计的真正落点)
- §5.1 可直接放进 agent standing 的提示词片段:接不了就申报,别静默伪造、别声称已完成;
  桩必须能跑,返回值建议带 stub:true;收尾用 stubs 工具确认剩余项。
  要点:把"编造"变成"填表"——模型不必判断算不算伪造,只需写状态词。
- §5.2 三个 LLM 工具面:stubs --json(待办)/ --changed(本次改过的桩)/ labels --grep(任意词检索)
- §5.3 工程指标:pending_count、unlabeled_empty、stub_ratio、stub_age
- §5.4 CLI 示例

四、生命周期与防疲劳协同保持:桩(含空载荷、含未完成/假数据/将删)豁免 stale;
债务用棘轮;空载荷只在未申报时警告(说过的不再重复)。

实现点更新:src/label.rs 为检索器(label_text.contains(word)),
check 三条硬规则(label.missing / label.ref_dangling / label.empty_payload warning),
关键词不影响求值,空载荷→None。

同步 occlusion-syntax.md(文法允许空载荷 + 空载荷说明 + M9 改为「关键词与桩」+ 增补措辞)
与 doc/README.md 索引。未改代码。
2026-10-22 14:18:58 +08:00
cflmy 719b7a8d82 docs(design): 修正标签定位 — 描述是自由文本,内置词只做检索不做语法
按用户修正重写 occlusion-tags-and-stubs.md:
1. `[]` 里是**纯粹的描述文字,对执行零作用**;编译器不解析,只在其内**检索**
   (供统计、清单、LLM 待办)。写成 `[某个功能,没开发完成]()` 完全合法。
2. **标签不是语法**,是内置词;想被统计就顺手写上 `[某个功能,没开发完成。待开发]()`。
3. 标签的作用是"让人和模型多看一眼",不是审批、不是门禁——所以标在任何地方都无害。

识别规则改为检索语义:
- 结尾识别([搜索接入,待开发] / [搜索接入-待开发] / [功能待开发])
- 显式括号识别(【待开发】可出现在任意位置)
- 句中裸词不识别(避免误判)
- **识别不到不报错、不提示**(描述自由,机器只是"看见了就记一笔")

撤回上一版的错误判断:原把 `[税率-待开发](0.1)` 列为反例是错的。
标在已知常量上也无害——多四个字换来一次深入检查与阅读,按用户判断**收益优先**。
仅保留不报警的提醒:stubs --changed / --uncounted 展示债务构成,避免数字被撑大后失去参考。

空载荷语义调整:描述非空时 `()` 可空(返回 None),并**自动计入 `stubs --uncounted`**
(未标注的桩也会被看见),不再把"必须有内置词"作为语法门槛。

桩豁免 stale 保持(待开发/模拟/废弃,以及空载荷),并补"防忘去标签"的兜底:
stubs --changed + 会话汇总里的 stubs_touched(一次性,不催)。

实现点相应改为"检索层":parse 原样保存描述字符串;src/label.rs 为检索器;
Tag 为闭集枚举但词表可扩(后续支持 frontmatter 自定义),**不影响任何语法规则**;
check 只保留两条硬规则(label.missing 描述为空、label.ref_dangling 引用悬空)。

同步 occlusion-syntax.md(增补措辞 + M9 改为"检索层")与 doc/README.md 索引。未改代码。
2026-10-22 14:14:15 +08:00
cflmy dfe99a10b4 docs(design): 遮蔽标签与桩 — 把 LLM 的「假接通」改造成可结算的欠据
按用户提议新增:描述文字内可带尾标签([某某功能-示例-待开发](实现)),
编译器在描述里检索标签,从而让"未开发"变成可枚举、可统计、可门禁的债务。

核心框架:**遮蔽是承诺,承诺有三态** —— 兑现(fresh) / 过期(stale) / 尚未兑现(pending)。
前两态由新鲜度机制管,第三态由标签管。于是假接通从"无法追踪的谎言"变成"可结算的欠据"。

一、动机:LLM 假接通的三条路 —— 禁止(改隐蔽)、放任(静默撒谎)、**申报(本方案)**。
关键不是提高道德要求,而是改变激励:申报比伪造省力,且申报后代码照样能跑。

二、()` 内部语法定稿(用户授权自行制定)
- 取元:at(表, 键) / get(表, 键, 默认)
- 调用:callee(args),逗号可选;**callee = 第一个 '(' 之前的全部文本**(空格合法,解决 D8)
- 循环:- [描述](遍历 集合 为 变量),变量名搬进 ()
- 空载荷:() 仅在带桩标签时合法(返回 None),否则 label.empty_payload

三、标签规范
形态 [描述-标签[-标签]](实现);抽取规则:**从右往左**剥离已知标签(最多 3 个),
分隔符 - 或 -;剩余为描述;未知尾段不剥离([报表-2026] 描述不变);
疑似拼错报 label.tag_suspect;字面尾标签用 \- 转义。
词汇表 v1 闭集:待开发 / 模拟 / 示例 / 实验 / 废弃(闭集才可枚举、可统计、可门禁)。
多标签以最强者决定语义:待开发 > 模拟 > 示例 > 实验;废弃正交。
标签放 [] 里而不是 () 里:人必须看得见、与描述同处一室、不可执行(守住铁律)、可正则检索。

四、桩的语义:必须能跑(不得报错)、必须有标签、不得被当成已完成。
返回手段:空载荷 None / 常量占位 / 假数据 / **桩+契约=有类型的洞**(推荐)。
建议惯例:桩返回值显式带 stub:true,下游跑通也知道是假的。

五、生命周期(自愈):写桩 → 计数 → 开发 → T1 检测 → 复核去标签 → 债务-1。
**桩豁免 stale**(待开发/模拟/废弃):否则 12 个桩变 12 条常驻警告,正好制造要消灭的疲劳。
代价是"做完了忘去标签" → 用 stubs --changed 与会话汇总里的 stubs_touched 兜住(一次性,不催)。

六、与防疲劳机制协同:桩豁免 stale;债务用**棘轮**(stubs.json 基线,只在增加时失败);
stubs 是按需命令不进 check 人类输出;会话末汇总带 stubs_touched。

七、编译器实现点:parse 抽标签 → ast Expr::Occluded{label,tags,inner} → 新增 src/label.rs →
check 报 label.missing/empty_payload/tag_suspect → interp **标签绝不影响求值** →
mlsp stubs → main marqdo stubs → view 桩徽章。
**铁律守住:[] 永不执行,标签只影响诊断/统计/呈现。**

八、示例集(按 LLM 真实风格):假装接入搜索 / 假算指标 / 假接通 ERP / 已废弃旧实现 /
反例(税率不该标待开发——桩只用于"应存在但未实现的连接",不是懒得查的数据)。

九、实施增补:M2 抽标签、M2.5 空载荷与 label.missing、M4 L1(桩不影响引用校验)、
**M9(新)marqdo stubs(清单/--json/--check 棘轮/--changed)+ MLSP stubs**、M6 汇总加
stubs_touched、M8 view 徽章与教程。顺序 M2→M2.5→M4→M9→M6→M8。

十、风险:标签滥用(棘轮+评审约定)、桩腐化(--changed 提示,不靠常驻警告)、
假功能上生产(view 显著标记 + 知识库仓可 error)、词汇不够(后续可配但须可枚举)、
**LLM 伪造标签**(标签只增加可见性,不减少任何检查)。

同步更新 occlusion-syntax.md(增补引用 + M9 行 + 顺序)与 doc/README.md 索引。未改代码。
2026-10-22 14:08:54 +08:00
cflmy fac68e85ea docs(design): 遮蔽语法总纲(实施依据)— 示例先行 + M0–M8 实施计划
按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成
**遮蔽语法(occlusion syntax)**:用叙述显示逻辑、用括号承载实现,
解决"刻意语法设计导致文档不可读",并依靠链接特性使知识过期可被检查。

一、示例先行(六个)
1 嵌套取值:三层 [1]([苹果]([水果类](货架))) → [水果类里苹果的第 1 项价格](at(at(at(货架,水果类),苹果),1))
2 长表达式打断叙述 → [应缴税额](...) 让句子完整
3 抽象层次混杂 → 论证留在叙述,算法退居括号
4 循环来源不可见 → - [从篮子里取出的每个果子](遍历 篮子 为 果)
5 **带空格函数名(已实测)**:> 加一 号 31 ❌ unknown function 加一;
   括号调用 加一 号(31 ) ✅ 32 —— 因为 callee = 第一个 '(' 之前的全部文本,空格不再是切词依据
6 反例:描述=实现时不该遮蔽

二、核心定理(本文档的理论支点)
**遮蔽创造信任负债**:把实现藏起来,读者就必须相信描述;
不遮蔽时描述过期无伤大雅,遮蔽后描述过期=文档变假。
所以「新鲜度校验」不是附加功能,而是遮蔽语法的**合法性来源**与代价。

三、场景按动机分类(不按语法分类)
A 不可读 / B 打断叙述 / C 层次混杂 / D 来源不明 / E 名称受限。
D 与 E 是遮蔽顺带解决的问题,不是目的;按动机写才能覆盖未来没想到的不可读情形。

四、语法规范:[] 永不执行、() 唯一执行;空标签 label.missing(error);
() 内用现有表达式文法,callee 允许空格;取元改为 at/get(纯度);
循环 - [描述](遍历 集合 为 变量),变量名从 [] 搬进 ()。

五、两种遮蔽关系,**都要查**
显式遮蔽([]())与**隐式遮蔽(叙述段 + 紧接 > 调用)**——
按用户要求把 > 调用也纳入过期检查:取上方紧邻叙述段为描述,
其反引号实体须出现在实参/callee;无叙述或无反引号则跳过(零噪音)。

六、新鲜度机制:L1 引用一致性(零依赖)+ T1 会话内(repair_apply 前后版对比)
+ **会话末一次性汇总(用户要求做)**:{labels_stale_seen, fixed, outstanding, items};
能力自述与无 git 降级(沙箱 exec=false / WASM 均可用)。

七、实施计划 M0–M8(每个里程碑含目标/改动文件/关键点/测试/验收/回滚)
M0 语义冻结 / M1 () 内调用增强() 终止·逗号·嵌套·空格 callee)/ M2 遮蔽语法 /
M3 at·get 与循环 / M4 L1 / M5 隐式遮蔽 / M6 T1+汇总 / M7 迁移与版本门 / M8 呈现与门禁。
**顺序建议 M0→M1→M2→M4→M6→M5→M3→M7→M8**:先让"断言+复核+修复"跑通,
再动 506 处迁移(中间态最痛)。

八、迁移实测规模:取元 506 处/136 文件,循环 44 处/24 文件,可执行方括号调用 0
(189 行是 lib/* 的 Caller 说明,不执行)。旧形必须 syntax.legacy_index 硬报错
(同形换义最危险),并用 label.provisional 承接机械迁移,避免 506 处全红。

九、测试计划与风险登记:单元/金样/回归 554/双后端/迁移差异/反向验证/环境矩阵/性能;
硬要求"每个新检查必须证明它会响"。

十、附环境前置(踩过的坑):scripts/dev-env.sh + build-web-plugin.sh;
$HOME 不可写 → zig 缓存重定向;/tmp 是 noexec → TMPDIR 必须可执行。
基线 cargo test 554/0;check 对 59 文件 0 warning/0 error,任何里程碑不得变差。

同步在 doc/README.md 登记 5 份新设计文档。未改代码。
2026-10-22 14:03:31 +08:00
cflmy 639b0ebcd1 docs(design): 讲清 T1「会话内陈旧检测」— 为什么模型在结构上收不到重复警告
回答:能不能在不改变的情况下让模型免于多次警告疲劳。能,且几乎不用改什么。

一、机制成立的根据(代码事实)
repair_apply(src/mlsp.rs:233)里 source(before)与 apply_edits 后的 new_source(after)
在同一个函数作用域内同时存在。所以"比较改动前后"不需要任何外部东西:
改动前 AST / 改动后 AST / 标签配对 / () 指纹 / [] 文本,全部在内存里算完。
零 git、零台账、零缓存文件、零环境依赖——这就是"agent 回路根本不需要 VCS"的确切含义。

二、时序:模型在自己这次编辑的响应里收到
validate → repair_targets → 模型产出 edits → repair_apply(source, ranges, edits)
→ 内部 before/after 对比 → 响应追加 labels.stale[{text, code_past, code_now, span}]。
模型只需回答一个问题:"你刚动了这段实现,描述还成立吗"。

三、重复为什么在结构上消失(三性质,缺一不可)
作用域=自己的 diff(旧债永不进上下文);投递=一次(后续 validate 不再出现);
自包含(下一轮 diff 是新的,没碰就不提)。刻意取舍:**宁可漏一次,也不反复骚扰**。
对比:20 处标签的文件 5 轮修复,扫描式累计上百条,T1 最多 0–2 条且每条一次。

四、关键重构:它在性质上不是 warning,而是**编辑期诊断**
对照 lint 警告 / 编译器错误 / T1 stale 的四个维度(时机、数量、是否重复、用户态度)。
没有人抱怨"编译器又报语法错了",因为那是一次性、可归因、改动驱动的。
**疲劳不是靠压制解决的,是把 stale 从 lint 类别搬到编译错误类别解决的。**

五、「不改变」到什么程度
文档内容不变(不嵌指纹、不加 noqa);工作流不变;不新增状态文件;不依赖 VCS;
纯内存计算。唯一改动:MLSP 加一个可选参数 check_labels + 一个响应字段 labels。
缺省关闭 = 零开销零噪音。

六、配对规则(按标签文本配,不按行号)
标签未变+() 变=stale;标签变了=作者在更新描述(不报);新增/删除不报;移动位置不报。
→ "挪位置"不误报,"改计算"必报警。

七、漏掉的三层兜底:循环预算(现有 max_attempts:2 直接可用)、可选阻塞
check_labels:"block"、会话末一次性汇总。建议默认 true + 循环预算。

八、边界:T1 保证"改动者当场被问一次",不保证"全仓库始终新鲜"(那是 T2/T3 的活,
可选、不进默认路径)。

附 §1.1 指纹可行性:Expr 目前只有 Debug 无 PartialEq;T1 只需进程内一致,
用 format!("{:?}", expr) 即可;更严谨可补 derive(PartialEq)(Literal 含 f64,只能 PartialEq)。
T2/T3 才需要跨版本稳定指纹,那时再用 knowledge/fingerprint.rs。

未改代码。附四项待确认。
2026-10-22 13:52:26 +08:00
cflmy 2c4dac005c docs(design): 修订 — 标签保鲜不该依赖 git,改为「前一状态」provider 分层
用户反驳成立:不是所有开发都用 git,依赖 git 不是好设计。三条理由:
1. 环境覆盖不到:沙箱 allow_exec=false(src/host/sandbox_fs.rs:378)文档内调不了 git;
   浏览器 WASM(wasm32)无进程能力;单文件/zip 工件无 .git;非 git 用户无从使用
2. 语言不该绑定 VCS:把语义正确性外包给"某工具目录是否存在"
3. 最要命的:最高价值场景(agent 修复回路)恰在不能调 git 的环境里

修订方案:保住 M5 的**原则**(变更驱动而非扫描驱动),把"前一状态"抽象为 provider:
判定逻辑只有一份 stale ⟺ fingerprint(()) 变 ∧ label 未变;变的只是 prev 从哪来。

四层能力:
- T0 引用一致性(零依赖,纯文档)——查引用腐烂
- T1 会话内前后对照(零依赖,最高性价比)——repair_apply / view 保存 / 编辑器钩子 / agent diff
- T2 外部历史源(可选,git/hg/svn 适配器)——跨会话漂移
- T3 台账(可选,.marqdo/labels.json)——无 VCS 时的持久化 + 确认状态

环境能力矩阵:CLI+git / CLI 无 VCS / agent 沙箱 / 浏览器 WASM / 单文件 / 对象存储,
**没有一行全 ❌**——T0+T1 在所有环境成立,足以支撑"agent 改动即时提醒"。

最关键一条:repair_apply 已同时持有 before(source) 与 after(应用 edits 后),
所以建议协议加一个可选 base_code / check_labels 字段,Marqdo 在同一次调用内即可算出
"哪些标签的 () 指纹变了而 [] 没变",返回带 code_past / code_now 的 stale 列表。
零外部状态、零依赖、零 git——而这正是模型改完代码别忘了改描述的场景。

provider 五条硬规则:核心不依赖 / 缺失即静默降级(不报错不提示)/ 能力必须自述
(labels status 显示启用层级,避免"没报=没问题"的误判)/ 判定单一定义 / 不写进文档。

被否:强制 git、文档内嵌指纹、零宽字符、mtime 启发式、# noqa、静音清单。

同步修订 warning-fatigue-control.md:M5a 由"核心"降级为可选 T2 适配器,
补一条验收指标"provider 缺失时标签相关输出也必须为 0"。其余结论不受影响。

未改代码。附五项待决策(是否接受分层、T1 是否够、能力自述、T2 适配范围、T3 是否推迟)。
2026-10-22 13:49:03 +08:00
cflmy 0ac661eef2 docs(design): 防警告疲劳机制 — stale 必须是「变更报告」而非「扫描报告」
触发:用户指出 []() 每次报 warning 会导致烦躁与忽略,机制必须先定再开工。

一、为什么标签检查特别容易被忽视
高频(标签密度≈每个取值/调用)、主观(自然语言断言,机器只能近似)、
持续(代码天天改)。且实测基线是**零噪音**:lib/ + ext/ai/ 共 59 文件跑 check,
warning=0、error=0 —— 标签校验会成为项目第一个持续警告源,一次就要做对。

二、疲劳的真正根因不是"报得多",而是「同一件已知的事被反复告知」。
目标改成三条硬约束:没有新信息就不说话 / 说了就能做点什么 / 说过的就不再重复。

三、六个机制评估
M1 分级(按证据强度:error=能证明断裂,warning=能证明变化但不知谁错,hint=弱信号)
M2 聚合(check 人类输出最多一行,细节进 --json / view / labels)
M3 基线(bootstrap 静默吸收,用于迁移后的存量)
M4 确认即静默(ack 台账,同指纹不再报)
M5 **结构化 diff(推荐核心)**:stale 只在「() 变了 ∧ [] 没变 ∧ 在本次变更集」时报
M6 文档内抑制 # noqa —— **否决**(污染文档、不可审计、会永久化;抑制只放台账/配置)

四、M5 的性质(这是把疲劳问题降级的关键)
零台账(git 即台账,无新文件/无合并冲突)、零基线(首次也安静)、
零重复(提交后 diff 清空报告即消失)、天生带 before/after(正好是 LLM 复核输入)、
格式化免疫(比 AST 指纹而非文本)。非 git 环境降级为 L1,仍安静。

五、推荐组合
默认:M5a + 默认 hint + check 最多一行 + 每条带定位/before-after/建议 + 变更集去重 + 非 git 降级
严格模式(知识库仓 opt-in):升 warning/error + 基线与确认台账 + **棘轮(允许存量、禁止新增)**
+ labels status 进 CI。棘轮是最值得抄的机制:老债不阻塞、新债立刻拦、债务数字可下降。

六、确认的三种语义:改标签 / 改代码 / 显式确认。
建议三者都提供,但显式确认留痕(confirmed_by + 次数)——**被反复确认的标签本身是坏味道**。

七、可证伪原则:只有能被证伪的断言才被检查。标签含反引号实体→参与 L1;纯口语→L1 不检查。
检查成本由书写具体程度决定,同时反向抑制"为凑数写废话"。

八、agent 节流:只对它自己刚改到的标签做检查,每轮一次,超 N 条只报前 N+汇总。
模型看到的是"你刚改的这处描述可能不成立",而不是"全仓库 200 处过期"。

九、防「用忽视解决」三道闸:债务可见(labels status 给数字)、可 gate(error)、
可审计抑制(labels audit + 过期抑制提示)。

十、验收指标(写进文档防走样):无变更时标签相关输出=0;单变更集提示≤3 或≤20%;
重复=0;可行动率 100%;误报≤10%;check 人类输出≤1 行;hint/warning 不影响退出码。

未改代码。附五项待决策(核心机制、默认级别、棘轮、确认留痕、check 聚合行是否常显)。
2026-10-22 13:44:36 +08:00
cflmy 1dd74578b5 docs(design): 纯度路线落地 + 标签过期检测(L1/L2/L3),对接 MLSP 修复回路
决策:取纯度(() 只装机器语句,取元搬进 ());标签可省略书写但编译器必须报错;
循环写法不追求统一。

一、纯度强制两件事(推论)
① 必须有不带标签的普通表达式写法(否则每个访问都被迫配人话 = 仪式感复辟)
② 带标签形式是「想做断言时的可选包装」——由此解决「标签凑数」退化:
   不想断言就别用这个形式。
普通取元四个候选:A 现有内建 at value= index=(零新语法、啰嗦)、
B 后置方括号 篮子[1](自然但引入第二种方括号角色)、C at(篮子, 1)(需逗号参数,
与之前想要的 f(args) 同一改动)、D 点号(与库路径/方法冲突)。建议 C,零风险选 A。
空标签 [](…) → label.missing 硬错误。
循环:- [从篮子取出的每个果子](foreach 篮子 为 果),变量名从 [] 搬进 (),不再让 [] 兼任标识符。

二、标签 = 可校验断言的载体(不是注释)
锚定 AST(有 span)/ 可机械核验 / 可进修复协议 / 变更可感知。

三、过期检测三层
L1 引用一致性(无状态):标签内反引号=实体断言,必须可解析且出现在 () 中。
   低假阳性(只有显式反引号才算),但查不出语义腐烂(乘改除)。
L2 指纹台账(有状态):.marqdo/labels.json 记 hash(())+code_quote。
   复用 knowledge/fingerprint.rs(collect_calls/ops_hint/fingerprint_hash)。
   键=规范化标签文本+序号,移动代码不误报。能查语义腐烂。
   存 code_quote = 「保留内容用于校验」的对称物:doc_quote 留 [],code_quote 留 ()。
L3 LLM 复核:诊断同时带 doc_quote / code_past / code_now,模型三选一
   (改标签 / 改代码 / 确认无害),走 repair_targets → repair_apply 越界必拒 → 复验 → 写回台账。

四、与现有设施对接(落地成本低的关键)
- diagnostics.rs to_json 已有 doc_anchor / doc_quote / contract_ref{declared} / suggestion
  → 无需新造字段;contract_ref.declared 就是「声明 vs 实际」的现成先例,只是从类型层下沉到散文层
- contract.rs:203 Contract::diagnostic 一次性装配同一组字段,标签诊断照抄,kind 换 "label"
- mlsp repair_apply 的 ranges 天然支持多区间 → 允许「标签行 ∪ 代码行」,护栏不变
- knowledge/lifecycle.rs 已有 find_stale/stale_json/verify → 标签过期走同一条 stale 通道,
  成为知识库健康指标(知识腐烂的新类型:文档断言 vs 实现)

五、诊断 schema 草案:code=label.stale,doc_quote=标签原文,
label_ref{text,refs,missing_refs,code_past,code_now,fingerprint_past/now,layer},
suggestion 给可执行建议,ranges=[[行,行]]。

六、反幻觉的精确表述:只解决「文档断言与实现不一致」这一类;
不解决模型编造、代码本身写错、标签含糊。价值 = 把文档可信度从「靠人自觉」
提升到「可机械复核 + 可被 LLM 裁决」。

七、风险诚实清单:误报疲劳(最危险,L1 只在能证明冲突时报、L2 同指纹只报一次)、
台账腐烂与合并冲突(视为可丢弃缓存、重算优先)、语义鸿沟(L1 边界)、
LLM 用幻觉修幻觉(护栏+双向信息+人工确认)、
**标签不得参与安全判定**(策略/沙箱/工具白名单只读 () 语义,永不读 [])、增量成本。

八、分阶段 P0 纯度语法 / P1 L1 / P2 schema+MLSP / P3 台账 / P4 L3+CI。
建议先做 P1(零状态、确定性、不依赖纯度迁移),先把「断言→复核→修复」链路跑通。

未改代码。附五项待决策。
2026-10-22 13:40:02 +08:00
cflmy 14114993c4 docs(design): 评定「[描述](语句)」提案 — 方括号=人话、圆括号=机器话
提案:`[]()` 不再读作"两个部分两个含义",而是 `[描述性显示文字](实际执行的简短语句)`;
表格取元的嵌套难描述也没关系——括号里可以写长,方括号只放人话。

一、为什么这个写法"美":三处真实同构
- 超链接 `<a>`:可见文本 ↔ 目标
- 文学编程 chunk 名(Knuth `<<name>>`)
- **Marqdo 自己的 `![marqdo-out](…)`**:方括号放指令、圆括号放负载
经验佐证:`[f] args` 可执行用量 **0**;189 处全是 lib/* 的 `Caller:` 用法说明(给人看)。
`[]` 在实践中的天性确实偏"描述"。

二、三个真实收益(本文最大的肯定)
1. 两条规则变一条:**解散 link-call 死结**。前几轮反复撞墙是因为默认 `()` 只能是集合;
   改成"任意语句"后,取元只是特例,不再独占外形。
2. 嵌套可读:`[1]([苹果](货架))` → `[货架里苹果的第一项](…)`,人读标签、机器读嵌套。
3. 循环来源可见 —— 但要精确限定:`view` 已把 foreach 渲染成带徽章的 loop-card
   (render.rs:1354),取元仍渲染为字面 `[键](集合)`(1502)。所以问题只在**通用 Markdown
   阅读器**里成立,而这恰是多数场合。由此升级为更强的论点:
   **语义正确性不该依赖读者是否用了 marqdo view。**
附:标签→锚点→点击跳转可行(view 已有 span),且 agent 用人话定位比行列号稳。

三、结构性弱点(代价最大、最易被忽略)
若 `[]` 只是标签,`(菜单)` 就只是"整个菜单",取元必须搬进 `()`:
点号 / 函数式 / 嵌套方括号 / 英文式,每种都有消歧问题。
→ **收益一能否兑现,取决于愿不愿新增一条取元规则**。用一条新规则换一条旧规则,不必然净简化。

四、描述漂移:不同意"不重要"
1. 它是注释的回归(贴在执行体上、必须短、可说谎的文本)
2. 一旦作为定位锚点,漂移就有操作后果(错误信息也撒谎)
3. agent 安全面:标签是模型会信任的自然语言,"标签写只读、代码做写入"从文档瑕疵升级为误导通道
缓释:①标签永不参与绑定 ②check 做词重叠校验(标签提到的名字全不在 () 中出现 → warn)
③trace 双输出 ④策略判定绝不读标签。**② 最划算,能抓住最恶劣的一类漂移。**

五、采用风险:可能重演 v0.3 废除 `+ 名` 的"仪式感"(原文理由:仪式感强、与正文脱节)。
两种可预测退化:凑数、噪音。矛盾在于"可省略 vs 歧义回归"必须在设计里正面解决。

六、迁移面实测:索引 506 处 / 136 文件;循环 44 处 / 24 文件;可执行方括号调用 0。
若 `[]` 改纯标签,506 处是**同形换义**(不报错就变义)——最坏一类,必须硬报错 + 版本门。

七、两条落地路线
- 路线一(推荐)双层:长形 `[描述](语句)` + 短形 `[键](集合)` 定义为长形缩写。零迁移、
  调用零成本收编、收益全拿;代价是短形两义仍在但可解释。
- 路线二(纯度):`()` 只装机器语句,取元搬进去;语义最纯但要新增取元规则 + 506 处迁移。

八、评定:本系列结构最强的提案(哲学自洽 ★★★★★,解决问题 ★★★★☆,
规则净简化 ★★★☆☆,迁移风险 ★★☆☆☆,漂移风险 ★★★☆☆)。
建议走双层 + 先把「词重叠校验」做出来,让标签从装饰变成可轻度核验的描述,
才配得上"AI 定位锚点"与"点击跳转"两个职责。

未改代码。附五项待决策。
2026-10-22 13:30:07 +08:00
cflmy e80c944c40 docs(design): 函数的水土不服与「命名/代入」重构 — 设计哲学层(含 1322 函数实测分类)
命题(来自用户):函数是预先抽象,自然语言是即席描述;正常人不会说「要算 37 的两倍
得先抽象一个函数」,而是直接说乘二。故函数在代码即文档里错位。

本文只谈语义表示与自然语言映射,不谈编译器与语法糖。

一、量化证据:Marqdo 的 ## 其实不是「过程」
1322 个函数:
- 纯返回式(零可执行语句,只有一个返回表达式)765(57.9%)
- 一行式 935(70.7%);可执行语句数中位数 0、平均 2.2
- 较长(≥10 行)仅 62(4.7%)
按语义功能分类:
- 纯命名式 754(57.0%)→ 对应「所谓 X,是指…」
- 条款式(有分支无副作用)103(7.8%)→ 对应「凡…则…」
- 遍历式 26(2.0%)、命令式(含 print)83(6.3%)、线性计算 356(26.9%)
结论:命名+条款 = 64.8%,真实副作用只有 6.3%。
即三分之二的 ## 落在「定义/条款」两种自然语言形态里,不需要过程语义。

二、复用经济学:为什么文档里抽象格外别扭
成本 = 定义 + 读者的跳转 + 维护;收益 = N 次复用省下的重复。
抽象值得做 ⟺ 复用次数×复杂度 > 定义成本 + N×跳转成本。
代码里 N 大、跳转便宜;文档里 N 常为 1、跳转昂贵(读者被打断)。
→ 大量文档中的「函数」是负收益:只用一次却强迫回头查定义。
这正是「正常人不会这么说话」的形式化解释:说话默认对方不知道你的定义,倾向就地展开。

三、自然语言复用的六种形态(程序语言只承认一种)
重复 / 指称(该金额)/ 命名(所谓 X)/ 条款(凡…则…)/ 范例(以 37 为例)/ 表格。
命名只是六分之一,却被程序语言变成唯一入口。

四、三个语义立场
甲 定义—代入:一段正文被命名,使用=按角色代入后重述。覆盖 58% 现状,与 ## 结构一致。
乙 条款—援引:条件→结论,援引条款给出适用事实。最贴中文说明文,1./2./3. 已有。
丙 配方—配料:用料表+做法,参数=配料行。最可读但表达力最弱、无法组合。
→ 推荐甲为主、乙为辅;丙作为甲的呈现(契约表)。

五、代入 vs 调用(为什么代入更贴人话)
心理动作、输入意义(一套名字 vs 两套)、结果意义、可嵌入叙述、一次性使用可取消。
关键:抽象必须能被「取消」——就地描述与命名代入是同一切换,提升/展开是编辑动作而非必经入口。

六、落到已有载体:只缺一环
命名(#/##)、正文(叙述+标记)、未定的量(体推断)、结论(*…*)、条款(1./2./3.)、
配料表(GFM+契约表)全部已有。**唯一缺的是「具名给值」**——问题因此缩小。

七、硬边界:自然性 vs 可判定性
角色具名(可判定,略啰嗦)/ 位置(实测叙述顺序一变绑定就翻转)/
语境隐式(130 个形参名撞车,不可判定)。
→ 只有「具名」同时可读且可判定。也解释了为何叙述式动词不可取:把判定交给未标记的词。

八、三个未决哲学难题:副作用(6.3% 需保留命令语义)、递归(代入=有限展开)、定义时序(能否前向引用)。

未改代码。附四项待裁决(含是否接受「不支持递归」、具名给值的最小形态)。
2026-10-22 13:14:03 +08:00
cflmy 30cd5a0833 docs(design): 在「只执行标记」原则下设计调用语法 — 含 3.8× 后端实测与叙述顺序实验
接受纠正:上一轮的「叙述式动词」L0 方案违背「叙述默认安全、只执行标记」的底层原则,
已否决。本文从该原则重新推导调用语法。

设计约束(硬):调用的每个语义成分(被调者、每个实参、绑定关系)必须落在标记内,
叙述词只能连接与解释,永不改变语义。

一、标记字母表:可承载调用的只有 `> 行`、`**…**`、`[callee]` 三种;
`[k](coll)` 已被取元独占(前几轮结论)。问题收敛为「在标记内如何连接函数名与槽赋值」。

二、三个候选
- A 括注具名 `**加一函数(n=31)**` —— 与通用函数调用同构,取元不冲突,具名可静态映射槽位
- B 箭头 `**n=31 → 加一函数**` —— 最贴汉语语序、链式可读,但优先级与返回值语义需增设计
- C 空格式 `**加一函数 n=31**` —— 今天就能跑(实测 **r = 加 1 2** 已可用),但参数边界靠空格

三、「不分实参形参」的编译器面(实测,结论意外)
| 路径 | 绑定方式 | 200k 次(1 int) | 2000 次(500 元素) |
| 树遍历(默认) | Env{HashMap},实参 k.clone()+v.clone() 深拷贝 | 167ms | 66ms |
| 字节码 | slots:Vec<Value>,pop 按位置移动,无克隆无哈希 | 44ms | 23ms |
即「变量始终在某个位置」已是字节码现实(vm.rs Op::Call),收益 3.8× 是真的。
但**它与语法无关**:槽位化只需编译期知道形参顺序,而体推断已给出顺序。
瓶颈是树遍历用名字哈希+深拷贝、以及默认后端是 Tree。
→ 不要用性能论证语义变更;省 IO 走「默认切字节码/解释器槽位化」这条正交工程路径。

四、真实耦合点:具名 vs 位置(决定性实验)
形参顺序 = 叙述里首次声明顺序(v0.3 §8.2),而叙述可自由改写。两文件只差语序:
| 调用 | 叙述 a,b | 叙述 b,a |
| a=10 b=3 | 7 | -7(随函数体改变,符合预期) |
| 位置 10 3 | 7(a=10,b=3) | **7(b=10,a=3)绑定翻转,不报错** |
→ 「实参形参不分」时位置传参等于把语义挂在可改写的叙述顺序上。
推论:调用应以具名为准;具名同时让编译期静态映射 slots[i],既稳又快。

五、建议
- 主形态 A:`**f(k=v)**`;单参允许 `f(31)`;多参要求具名,旧位置写法 check 期 warn
- B 箭头作后续可选项(定位为语句式组合子)
- 明确不做:未标记动词、[f](args)(撞取元,已实测 2 个真实冲突文件)、
  动态作用域(七条硬伤 + 130 个撞车形参名)、位置实参作主流

附优劣总表与待决策四项(含是否把默认后端切字节码)。未改代码。
2026-10-22 13:06:57 +08:00
cflmy e2068c2051 docs(design): 参数能否从上下文推断 — 拆成 L0/L1/L2 三层,附 1322 函数语料实测
回应「让函数参数从上下文推断,写成 对**n=31**执行**加一函数** 可能吗」。

核心结论:**用户示例其实不需要隐式推断** —— n=31 就写在句子里,
缺的是「叙述式调用」语法,不是新的作用域语义。拆成三层:
- L0 叙述式调用(绑定在句中)→ 纯语法糖,安全,建议做
- L1 就近绑定(上一行绑定,下一行只写函数)→ 段落级隐式,不建议
- L2 真隐式(动态作用域)→ 不建议,七条硬伤

实测(1.5.2,8 组):
1. 示例原样跑:无输出、无报错、exit 0 —— 静默 no-op
2. 拆开看:散文行里的 **n=31** **真的执行了**(main 的 n 变 31);
   而 **加一函数** 只被求值丢弃,从未被当作调用
3. `**n = 31**` + `> 加一函数`(不传参)→ missing argument for parameter n
   —— 函数看不见调用者作用域(严格分离,这是语义基石)
4. `> 加一函数 n=31` → 32,今天就能做
5. `# main` 读 frontmatter `税率` → 0.1 ✅;`## 函数` 读同一个 → undefined ❌

用户担心的「大项目变量名难用」有数据支撑(全仓库扫描 1322 个函数):
- 819 个不同形参名,其中 **130 个被 ≥5 个函数共用**
- 最严重:path 70、value 59、text 53、id 47、list 38、内容 38、路径 35
→ 若参数靠上下文推断,调用任何读 text 的函数都会捡到作用域里的 text,撞车是常态

L2 七条硬伤:同名捕获、递归自毁、无法复用、契约报废(call_arg_diag 没有校验点)、
指纹/arity 失真(隐式调用在 AST 上像零参)、沙箱隔离破坏、不可审计。

给出受控替代:**常量默认值** —— 形参未传入时取文件级常量(frontmatter),
静态可判定、不随调用者变化、契约与序列化都不受影响。

顺带发现并记录 **D11(高)**:函数可见环境随运行面不同。
- # main 走 Env::with_metadata(interp.rs:473)→ 能读 frontmatter
- 普通函数调用走 Env::new() → 读不到
- 浏览器 WASM 入口 invoke_in_entry(interp.rs:365)→ metadata + entry_bindings 都给
即同一份文档在 Web 能跑、在 CLI 报 undefined variable。已写入缺陷实录(含复现与两条修法,
倾向「统一为函数可见 metadata」,正好成为常量默认值的现成基础)。

未修改任何代码。
2026-10-22 13:00:01 +08:00
cflmy 9cda80ee7d docs(design): [函数名](参数) 与 f(参数) 调用写法评估 — 原型实测 554/0(已回退)
更正前两轮对用户意图的误读:用户问的是**调用写法**,不是表/函数即值。

核心结论:
- [函数名](参数) 技术上能做,但撞的是已定的取元语义
  「方括号=取出的名字,圆括号=从哪取」(collection-access-link.md §1;
  call-arguments.md §2 锁定 `]` 紧邻 `(` = 取元)
- 按名字消歧不可行(**实测证据**):全仓库 851 文件 / 2367 个 ## 名 /
  983 次 [k](c),键名与同文件函数名冲突 5 处、去重后 2 个真实文件:
    ext/data/db.mq.md:122        *[count](r)*        (## count + r 里的 count 列)
    examples/code-as-docs/index.mq.md:79  价=[单价](行)  (## 单价 + 行里的单价字段)
  函数名优先 → 打断这两处取元;数据优先 → 永远无法 [f](1) 调用。两条都走不通。
- 且存在不可消除的歧义子集:[f](1) 与 [1](篮子) 同形,单参调用永远无法表达;
  「多参能用、单参不能用」的语法不可教。

但去掉方括号的 函数名(参数) 是**完全空闲的语法**(实测原型前 加(1) 报
trailing input in expression),且原型验证可行:

原型(已回退,仅验证):
1. src/parse/expr.rs 新增 try_paren_call,紧随其后的 ( 视为参数列表
2. src/parse/mod.rs 两处「像调用」判定加 looks_like_paren_call,让单 token 也能进调用分支

原型实测:
- 加(1) / 加(1 2 ) / 加("1" "2") / txt.str_trim("  x  ") 均通过
- 加(1 2)、加(a=1 b=2)、加(1, 2)、嵌套 加(加(1 2) 3) 失败
- **全量 cargo test --release: 554 passed / 0 failed(零回归)**

关键判断:失败点不在语法而在**参数分词器**——加(1 2) 失败、加(1 2 ) 成功,
差别只是 ) 前多一个空格,说明 parse_call_args/split_first_token 把 ) 当成了
token 的一部分;修它要动所有调用共享的分词器。这解释了「看着 10 行、实为一次核心改动」。

另一个重要性质:f(args) 最终仍产出 CallExpr{callee,args},
EKC 指纹 collect_calls、契约校验、字节码 Op::Call(fid,argc) **全部自动兼容**——
它只换写法,不改调用模型(与一等函数方案本质不同)。

人读性:f(1 2) / f(a=1 b=2) 与数学记号同构、参数边界显式、渲染不成超链接,
优于 [f](1 2)(预览里会变成链接)。

建议:不做 [f](args);做 f(args),先具名后位置。
附工作量清单 9 项与三档实施选择(A 仅具名 / B 具名+位置 / C 全量)。未改代码。
2026-10-22 12:53:03 +08:00
cflmy eae4815fc7 docs(design): 函数能否解释为 GFM 表 — 11 组实验 + 史料考古(未改代码)
回应「代码函数(## 名 + 参数 + 体)从某种角度能否解释成 GFM 表,
这样的解释运行时有没有巨大风险、有没有实际收益、历史上出现过吗为什么放弃」。

核心答案:命题在 Marqdo 里**已经实现**,但实现的是「关于函数的表」(契约表),
不是「函数本身」。界:表能描述外延(输入→结果)与签名(元数据),
不能描述内涵(怎么算);而调用恰恰是内涵操作。
[k](集合) 是投影已有数据,f(x) 是计算新数据,只有 f 已是预先枚举的表函数才重合。

一、固定表格几何(实测)
- 1 列 N 行 → List;≥2 列 1 行 → Map 记录(实测 {"x":1,"y":2})
- ≥2 列 N 行 → **列向聚合** Map(实测 {"档位":[1,2],"税率":[...]})
- 行向记录必须显式标记(行/@/row),文档原话「不得与默认列向字典静默混用」
→ 「行 = 参数」在 Marqdo 里不是自然形态

二、命题已存在:契约表(tests/contracts/ok_contract.mq.md)
src/contract.rs:表头含 参数/返回/字段 + 必须有「类型」列 → 契约块。
契约表的首列标头正是 §3.5 那种「显式形态标记」的同类做法。

三、11 组实验(1.5.2 实跑)划定边界
- E1b 表列 n 但体不读 → > f 无参调用成功 → 表**不能声明**形参
- E3 叙述声明 n + 表 + 传"七" → 参数 n 期望 number,实际 text(契约校验)
- E4 无表 → 七1,不校验
- E5 + `n` 旧式形参行 + 表 → 契约生效(用户草图形态可用)
- E6 表写 2 行、体只读 1 个 → too many positional(**表 ≠ arity**)
- E7 单列参数表 → 七1,**契约静默失效**(1 列 = List,且 check 报"无契约问题")
- E8 重复行 → 取首行无诊断;E9 幽灵行 → 静默忽略
- E10 同一张表加 `tc` = 绑定 → 契约消失
→ 隐含规则:**未绑定的表 = 声明/元数据;绑定的表 = 数据**

四、若表成为定义(把静默漂移从"少个校验"升级为"少个参数")
漏类型列/表体漂移/重复行/调换行序都会变成绑定语义;
最致命的是行序携带语义——「把 b 行移到 a 上面」这个无害编辑会改变位置参数绑定。
而 [键](集合) 之所以安全是因为**键是显式的**,取元不依赖顺序。

五、链接式调用第三次论证(带史料)
collection-access-link.md §1「方括号 = 取出的名字,圆括号 = 从哪取」;
§4 非目标排除点号/在/箭头/(键)[集合];call-arguments.md 锁定 `]` 紧邻 `(` = 取元。
→ [f](args) 不是未决定,而是**已被明确分配给取元**。

六、史料:这条路是被反向走过的
- v0.2 要求手写 `+ 名` 形参表 → v0.3 列为**代价**(仪式感强、与正文脱节),
  P4 改为体推断,`+ 名` 标注「过渡兼容,新代码不推荐」
- objects.md §6 非目标:**用表格声明字段 schema**(表格仍表示数据集合)
- tables-maps-footnotes §3.3 行向记录「不默认」,§3.5 显式标记才开启
- collection-access-link §3 记录了取元语法的迁移与定稿

七、收益(诚实)
tool schema 最实:tools 已能写成记录行(tool_names 接受含 name/工具 的 Object),
但 agent_format_tools 只渲染 `- name`,说明与参数被丢弃——能力已在那儿,只差接上签名。

八、建议:表做声明不做定义,补三件事
① 消灭静默:契约表缺类型列/幽灵行/重复行/与 arity 不符 → check 应 warn(当前全静默)
② 反向生成:marqdo view 从签名生成契约表草案(单一真相仍是体,表是投影)
③ 签名可供机器消费:knowledge 能力条目带参数 schema → tool schema 自动生成
零语法改动。§9 给了「双写 + 一致性校验」的可试写法(E5 已验证可跑)。

未修改任何代码。
2026-10-22 12:46:13 +08:00
cflmy 3260494e5c docs(design): 评估「函数作为变量 / 函数即表」(未改代码)
回应「函数能不能是变量的一种,`函数名` = 参数|函数体 表,取元即调用」的提议。

核心结论:这个直觉在数学上成立,但一句话里混了四种不同的「函数」观,必须拆开:
- 外延观:函数是图 → 就是表,调用是查表(有限域才成立)
- 内涵观:函数是规则 → 调用是执行(定义域无穷,写不成表)
- 闭包观:函数 = 代码 + 环境
- 名字观:函数是命名空间一条(Marqdo 现状)
用户草图是「参数声明 + 函数体」的混合体,而「像表格取元」的直觉来自外延观。

现状实测(1.5.2,六组实验):
1. Value 枚举十种无函数;函数是 AST,挂 Module.functions
2. CallExpr.callee 是 String 不是 Expr → 语法上无法调用「计算出来的值」
3. 对象本来就是 Value::Map + _type 标签(对象是值,函数不是,这个不对称是关键)
4. 已存在 call_fn 按名字间接调用,但零参、限当前模块、只在运行期校验
5. 实验:`**f = > greet**` 报 missing argument(> 名字 是调用语法,无法引用函数本身)
6. 实验:表里存函数名 + [h](reg) + call_fn → 动态派发今天就能做

关键实测纠正(我最初写错、已改):
GFM 两列表绑定为「列映射」{"档位":[1,2],"税率":[...]},不是按首列键控的映射,
所以 [2](两列表) 报 missing map key 2。真正键→值查表需 Map(json.parse)
或用 table.index_of + table.at 显式索引(两条配方均已跑通)。

三条断裂点:表格有限 vs 函数常无限;函数体是代码不是数据(需 eval,静态检查/契约/
EKC 全失效);[k](x) 会被语义重载(与上一轮 [函数名](参数) 冲突同源)。

五条路径与代价对比(值模型改动/静态可索引/契约/EKC 指纹/序列化沙箱/成本),
并逐项分析对 Marqdo 特有机制的冲击:契约 T2.1/T2.2 依赖静态 target、
EKC 指纹 collect_calls 读静态 callee(src/knowledge/fingerprint.rs:76)、
value_to_json 对 Value 穷举(src/host/json.rs:98)、字节码 Op::Call(fid) 用编译期 id
(src/bytecode/compile.rs:709)。

建议分阶段:
- 立即:决策表(零改动),但补 table.lookup / table.by_column 库缺口
- 短期:扩展 call_fn(args=、跨模块、字面量静态校验)——不动值模型
- 中期:若要一等函数,走 ADR 并回答匿名函数如何进 EKC 索引
- 不建议:「函数即表」强主张(语义重载 + 削弱静态可索引性)

§9 给出折中:数据在表、逻辑在命名函数,兼顾表驱动直觉与可索引性。
未修改任何代码。
2026-10-22 12:35:40 +08:00
cflmy 3330a0fc66 chore: 还原 go.mod 被构建副产物改动的依赖分类
上一个提交误带入 plugins/web/go.mod 变更:构建 libweb 时用了 -mod=mod,
Go 把 jackc/pgx/v5 与 yuin/goldmark 从 indirect 提升为 direct。
这与本次文档提交无关,属于构建副产物,还原为提交前状态(内容与版本不变,
仅 require 块归类复原)。
2026-10-22 11:59:50 +08:00
cflmy 42a1a46383 docs: 链接式调用 [函数名](参数) 评估 + 开发环境脚本 dev-env.sh
两件事:

1. doc/design/link-style-call-evaluation.md(Proposed · 待决策)
   评估用户提议的 Markdown 链接式调用 [函数名](参数…)。

   结论:语法优雅,但与既有特性「链接索引 [key](map)」形状完全相同,无法可靠消歧。
   实测证据:
   - [a](m) → 链接索引,取成员,返回 1(既有特性,v0.3 明确推广)
   - [greet](alice) → 被当链接索引处理,报 undefined variable alice
   两者区别只在「greet 是函数还是键名」,需要符号表信息,而语法判定发生在
   解析期(跨模块时未知)。若靠「已知函数表」消歧,会把清晰的
   missing map key 变成误导性的 unknown function。

   给出四个受限方案并对比,推荐 L3:用「] 与 ( 之间是否有空格」消歧
   - [key](coll)  紧贴 → 链接索引,语义一字不动(零回归)
   - [callee] (args) 有空格 → 调用,参数显式成组,顺带解决 D8 空格函数名
   并附 8 条验证计划。未改任何代码。

2. scripts/dev-env.sh(新增,可 source 复用)
   本机测试环境缺失导致基线本来就有失败,本次装好并固化:
   - 约束1:$HOME 不可写 → zig/rust 缓存显式重定向
   - 约束2:/tmp 是 noexec tmpfs → TMPDIR 必须指向可写且可执行目录
     (这是 Go 链接报 "signal: aborted"、zig 报 AccessDenied 的真正原因)
   - 提供 rust 1.81 / go 1.25 / python 3.12 / gcc shim(zig, glibc 2.36)

   环境修复前后:
   - 无 python3:231 passed / 2 failed
   - 加 python3:233 / 0(lib)
   - 加 go + libweb:gold 284 / 0
   - 全量:554 passed / 0 failed

   libweb.so 构建要点:Go cgo 需要 gcc,用 zig cc 充当
   (/workspace/qdagent/.tools/zigcc/bin/gcc,过滤 Go 传入的
   -Qunused-arguments,该参数会让 zig 驱动 abort)。

变更文档同步追加 §8 记录环境安装过程与前后对比。
2026-10-22 11:59:14 +08:00
cflmy b6629e5450 fix(parse): D9 未闭合引号不再静默吞行(分类层 + 解析层双层修复)
缺陷:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0,
没有输出也没有报错,该行凭空消失。对「文档即程序」来说这是最危险的一类
错误——文档看起来完整、能跑、check 通过,实际少了一节。

根因在**分类层**而不是解析层:
parse_quoted_string 里 `unterminated " string` 的报错一直都在,
但 matching_bold_close 扫描时遇到未闭合的 '"' 后一直处于 in_str 状态,
再也找不到收尾 '**',于是 is_marqdo_star_line 返回 false,
该行被判为 LineKind::Comment 成为叙述,解析器根本看不到它。
解析层精心准备的报错不可达。

修复(两层,缺一不可):
1. src/lex/mod.rs
   - 新增 pub fn has_unterminated_string:统计未被 \ 转义的 '"',奇数即「开了没收」
   - is_marqdo_star_line:粗体起始且找不到收尾时,若引号未闭合则仍判 Code
     (判 Comment 会静默丢行;判 Code 才能让解析器说话)
2. src/parse/mod.rs
   - parse_simple_stmt 紧跟既有粗体分支之后,对「粗体起始 + 引号未闭合」
     给出精确报错,而不是笼统的 unrecognized statement

影响面(改前量化,避免凭直觉改核心解析):
- 全仓库 845 个 .mq.md、620 个含代码行文件
- 引号计数为奇数的代码行:**0**
- 结论:不改变任何现有文件的解析结果,只作用于畸形输入

测试(TDD,先写测试确认失败再修):
- 新增 4 个单测:未闭合→Code、闭合→Code、叙述含引号→Comment、
  叙述含孤立引号→Comment
- 修复前 unterminated_quote_inside_bold_is_code_not_comment 如期失败
- 修复后 lex 14/14;cargo test --lib 237 passed 0 failed(基线 233 + 新增 4)
- cargo test --test gold 276 passed 8 failed;git stash 验证基线同样 8 failed,
  失败全部是 ext_web_*(依赖 Go 插件 libweb,本机环境不具备),与本次无关

文档:
- doc/design/parser-diagnostics-d8-d9.md  设计依据、根因链路、候选方案评判、影响面
- doc/design/change-d9-unterminated-string.md  变更记录(现象/根因/改法/测试/边界)
- doc/design/spaced-function-names-d8.md  D8 方案评估(待审阅,未改代码)

已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估
(单引号兼作英文撇号,误判风险高于双引号)。
2026-10-22 11:52:27 +08:00
cflmy ecd7d5e433 examples: 新增 oa2026-showcase(2026 开源项目大赛作品介绍示例集)
五个可运行示例,覆盖 Marqdo 的核心能力面:

| 文件 | 展示 |
|------|------|
| add.mq.md | 叙述统一、粗体即代码、斜体即返回 |
| invoice.mq.md | 表格即数据、循环、分支、断言 |
| calculus.mq.md | 公式即变量、求导、求根、绘图 |
| bell.mq.md | 量子电路、概率、断言、SVG 派生物 |
| foreign-node.mq.md | 外联一次性执行、持久会话、显式传值 |

全部实测跑通(1.5.2),输出与 README「预期输出」一节一致:
- add → 42
- invoice → 960 / 912 / 966 / within-cap
- calculus → 3*x^2 - 3 / 9 / [-1.73, 0, 1.73] / plot-ok
- bell → {00: 0.5, 11: 0.5} / bell-00-ok / bell-11-ok / bell-draw-ok
- foreign-node → 区域汇总表 + 持久会话复读

仓库侧改动:
- examples/oa2026-showcase/*.svg 随示例入库(README 有说明,属固定产物)
- .gitignore 忽略根目录 bell-*.svg / calculus-*.svg —— 从仓库根运行示例时
  draw/plot 会把 SVG 写到 cwd,那是运行产物不是源文件
- examples/marqdo-blog/db/posts.mq.md 首行正文去掉了内嵌 `#` 标题写法
2026-10-22 10:41:41 +08:00
cflmy aeb5a2a43d docs(tutorial): 新增《常见陷阱手册》,并补 D8–D10、按实测收敛 D3
把 qdagent 重构期间踩到的坑整理成**使用向**手册 doc/tutorial/15-常见陷阱.md
(417 行,全部条目在 1.5.2 逐条实测,含现象/原因/改法三段式与提交前自查清单)。

手册要点:
- §1 写文档:行首数字必报错(2026 年 / 42 条 / 3 个要点 都中招);
  行首 + 报错;未闭合引号静默吞行(最危险)
- §2 变量作用域:模块级变量在 # main 与各 ## 之间不可见;
  顶层不许裸语句;table.put 不原地修改
- §3 函数:函数名含空格时定义成功但调用必崩
- §4 字符串:引号内 ** / | / # 实为安全,只有引号不配对才出事
- §5 导入:相对路径以当前文件为基准;标准库必须带库名前缀
- §6 易记错的函数签名(txt.contains 的 sub、table.put 的 in/at/value …)
- §7 结构:# main 体不被 ## 截断;1./2./3. 是 if/elif/else 链
- §8 自查清单(marqdo check + run 双跑)

同步修正缺陷实录 research/qdagent-refactor-defects-2026-10.md:
- D3 收敛:实测证明 - / > / | / [ 在叙述区**安全**,只有行首数字与 +
  会被当语句;判据是「该行能否被解析成完整语句」
- 新增 D8 函数名含空格:定义成功、调用必崩,check 却通过(不对称)
- 新增 D9 未闭合引号静默吞行,退出码 0(静默类最危险)
- 新增 D10 table.put 非原地,累积计数静默失效
- 同步复现清单与变更记录

索引:tutorial/README 增第 15 章;doc/README 增手册与缺陷实录两行。
手册内所有代码示例均实测跑通(含参数传递修法、if 链、标准库前缀)。
2026-10-22 09:46:17 +08:00
cflmy f2d651e063 docs(research): qdagent 重构期间发现的运行时缺陷实录(D1–D7)
在 qdagent 实现「智能体输出必须是可运行 .mq.md」的机械门禁
(提取 → 结构检查 → 沙箱试跑)时,暴露 Marqdo 1.5.2 的一批
行为与文档不一致、诊断不可用、静默降级问题,逐条记录并给出建议:

- D1 高 sandbox.profile 仅回显不生效:readonly 与 default 等价,
  RunOptions 硬编码 allow_fs_write=true(安全语义静默失效)
- D2 高 全角冒号 调用:<name> 无法解析,但提示文案推荐全角;
  extract_tool_name 用 split sep=":",与 READ/DECISION 的全半角支持不一致
- D3 中 叙述行行首执行标记(数字/-/>/|/[/**/*)导致中文文档解析失败;
  对 LLM 生成文档是高频陷阱,建议增强诊断与 check 规则
- D4 中 sandbox.run source= 报错丢上下文:文件名显示 <memory>,
  未提示「源文本必须含 # main」
- D5 中 [key](map) 键缺失硬崩:sandbox.run 成功形状无 error 键,
  按防御式写法在成功路径崩溃;建议统一形状
- D6 低 未绑定 GFM 表不可迭代,报错不指向根因
- D7 低 沙箱内 subtask spawn path= 设计性不可用,未在沙箱文档明示

附「确认正常的项」以避免误报,与逐条复现清单。
2026-10-22 09:03:07 +08:00
cflmyandCursor b020b9d218 Ignore PLDI harness scratch and test plot SVG leftovers.
Keep experiment temp trees and regenerated *-plot-*.svg out of the interpreter tree.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 12:56:51 +08:00
cflmy 33a14d272c release: v1.5.2 — foreign v3 P0/P1 (stdin, plan API, snapshot, capture, persist) 2026-10-18 14:57:15 +08:00
cflmy 6ed70fd8b8 docs(design): defer G7 and G8 from the v3 target
Keep the cross-document scope and non-Python/Node adapter designs in the document for future work, but remove them from the current implementation target and priorities.
2026-10-18 14:51:12 +08:00
cflmy 115d1f6c0b feat(view): explicit persist and nested-plan boundary
Add per-cell Persist backed by lib/writeback and /api/session/cell/persist. Reject nested foreign.session plans with a top-level diagnostic and tests.
2026-10-18 14:47:54 +08:00
cflmy 7dc5e56850 feat(foreign): reject nested view plans
Enforce the v3 plan boundary: foreign.session must be a top-level binding. Nested plans are diagnosed instead of silently becoming stateless. Tests cover the AST helper and DocumentSession open.
2026-10-18 14:46:57 +08:00
cflmy 514caa55ae docs(design): mark G9 snapshot capture implemented
view capture and view output --snapshot are implemented with source-hash validation; remaining gaps are G3/G7/G8/G10.
2026-10-18 14:46:20 +08:00
cflmy 74908ebf04 feat(view): capture live snapshots for static export
Add view capture to record per-cell outputs and session summary with source hashes. view output --snapshot consumes the capture without re-executing and rejects source drift. Includes snapshot parsing tests.
2026-10-18 14:45:26 +08:00
cflmy 0f852593bc docs(design): record foreign v3 P0/P1 implementation status
Mark stdin/per-cell inputs/interrupt and plan/snapshot APIs as implemented; keep G3/G7/G8/G9/G10 as pending design items.
2026-10-18 14:44:29 +08:00
cflmy 34e2fb4f74 feat(foreign): snapshot export, import and replay
Export JSON-safe kernel values, cells and journal; restore values into a matching plan; replay cells with recorded stdin. Add /api/session/snapshot/{export,import,replay}.
2026-10-18 14:43:53 +08:00
cflmy 0e407b2bd3 feat(foreign): runtime plan updates and generation
Add explicit add/remove cell and set-value operations with a plan generation counter. Expose /api/session/plan/{assign,add,remove,value}.
2026-10-18 14:43:26 +08:00
cflmy e5e532d83f fix(foreign): keep session_list arity empty
ForeignSessionList accepts no id; only ForeignSessionInterrupt takes id.
2026-10-18 14:38:27 +08:00
cflmy 064522a338 feat(foreign): raw stdin, per-cell inputs and interrupt
Persistent Python/Node kernels receive raw program stdin per eval; foreign.session accepts an inputs table and view exposes per-cell stdin. Add session interrupt host API and view control.
2026-10-18 14:37:45 +08:00
cflmy c85f1a2829 feat(foreign): support raw stdin and per-cell inputs
Session eval now carries raw stdin, and the Python/Node workers temporarily replace program stdin during evaluation. foreign.session accepts an inputs table; view exposes per-cell stdin and Run All sends a per-cell input map. Stateless and persistent cells share the same input semantics.
2026-10-18 14:36:47 +08:00
cflmy a7266185b2 docs(design): propose foreign v3 capability plan
Document the remaining foreign runtime gaps: persistent raw stdin, per-cell input, dynamic plan boundaries, runtime plan updates, interrupt, state export/replay, cross-document scope, non-Python/Node adapters, live-to-static snapshots and explicit writeback policy.
2026-10-18 14:31:44 +08:00
cflmy 4d7c0bea1b fix: sync Cargo.lock with v1.5.1 version bump 2026-10-18 14:23:20 +08:00
cflmy 53758ebd1c debian: changelog entry for 1.5.1-1ppa1 2026-10-18 14:20:24 +08:00
cflmy dff0b700ae release: v1.5.1 — view static/live unified + foreign value passing 2026-10-18 14:05:19 +08:00
cflmy 4da07c1b26 fix(view): do not turn documentation tables into call chips
Keep descriptive table labels non-callable and suppress call annotations on table blocks. This removes the collapsed call {步骤...} chip while preserving the table and the return 950 chips at the actual foreign/writeback calls.
2026-10-18 13:59:24 +08:00
cflmy 78922102e4 fix(view): anchor imported-function returns at their call site
Track the caller line on CallFrame and use it for return annotations instead of the callee library line. Return 950 stays visible on the actual foreign/writeback calls; the Markdown table remains intact and no longer receives stray return chips.
2026-10-18 13:56:50 +08:00
cflmy 064bae2c65 docs(view): keep writeback table labels as inline code
Wrap foreign.run/session and writeback.record table labels in code spans so the prose table is not traced as executable calls; this removes the stray return 950 chips.
2026-10-18 13:52:51 +08:00
cflmy 92b91ffc81 fix(view): group and theme writeback blocks
Render contiguous writeback comment lines as one block, and map output-card/writeback tokens to the View dark theme. Static and live pages no longer show three dashed fragments or light output cards on dark.
2026-10-18 13:51:11 +08:00
cflmy ab6648ae0e docs(view): make the writeback page itself the runnable example
Move the foreign + writeback demo into the user persistence page. The page runs a Python code fence, records a keyed total slot, and the slot is visible in both source and static rendering. Remove the separate example document.
2026-10-18 13:48:05 +08:00
cflmy 5acf026e0c docs(view): add a runnable foreign writeback example
Move persistence guidance out of the walkthrough into separate static pages. Add examples/foreign-writeback/index.mq.md, which executes a foreign code fence and writes a keyed total slot into its own source.
2026-10-18 13:45:27 +08:00
cflmy 8dcd69412f docs(view): recommend static snapshots and writeback persistence
Add a persistence recommendation to the user-facing foreign walkthrough: static export for published snapshots, and lib/writeback for opt-in result slots in the .mq.md source. Show a readable code-fence based writeback example.
2026-10-18 13:40:44 +08:00
cflmy 2a13e52981 docs(view): show low-level session evaluation as code fences
Replace inline source strings with readable Python code fences bound as Marqdo code values. The low-level session evaluates those values; no long escaped source argument remains.
2026-10-18 13:35:51 +08:00
cflmy 9b269f6447 feat(foreign): pass Marqdo values into multi-kernel view sessions
foreign.session accepts a values table and initializes each kernel from ordinary Marqdo values. The static walkthrough now uses two kernels and a shared 订单 value instead of redefining orders inside Python. Static pages embed the session summary so kernel controls and Clean stay visible.
2026-10-18 13:32:51 +08:00
cflmy 15362cb048 fix(view): restore per-cell kernel switch and Clean
Code cards again show a kernel selector and a Clean button. Clean calls /api/session/cell/clear for live sessions and clears local output in static snapshots, without restarting kernels.
2026-10-18 13:27:15 +08:00
cflmy 05d48f68a4 docs(view): show kernel state and Marqdo value passing
Rewrite the static foreign walkthrough without stdin-driven examples. It now demonstrates session_set from an ordinary Marqdo table, persistent kernel state across evaluations, and a foreign.session view plan sharing state across cells. Static export executes those cells and embeds the real outputs.
2026-10-18 13:23:03 +08:00
cflmy e4387259ba fix(view): make static examples self-contained
Foreign cell examples read stdin with a deterministic fallback, so static exports show real output without tracebacks. Low-level session bindings named 会话 are no longer mistaken for a view plan; static export runs all cells again.
2026-10-18 13:19:41 +08:00
cflmy 518f8e386b fix(view): avoid stdin tracebacks in static snapshots
Static export skips cells that read stdin when the document has no preset stdin, and shows a short explanation instead of a traceback. Preset stdin still executes normally.
2026-10-18 13:14:17 +08:00
cflmy 9da12c9093 feat(view): add cell stdin for live and static runs
View gets a Cell stdin/input field wired to cell Run, Step and Run All. Stateless cells receive raw stdin; persistent kernels receive marqdo_input. Static export uses the document preset stdin and the same run_all path.
2026-10-18 13:10:08 +08:00
cflmy e0d34669e0 fix(view): use the same run path for static and live cells
Run All now records per-cell failures and continues; static export uses the same foreign_doc run_all and injects those records. A cell that succeeds in view therefore succeeds in the static snapshot, and failures match.
2026-10-18 13:03:46 +08:00
cflmy 0ba4d3d2d7 feat(view): render real cell outputs in static exports
Static export opens the foreign document session, runs cells once, and injects stdout/stderr/error into the code cards. Failures are shown as real errors; --no-exec still skips execution.
2026-10-18 13:00:41 +08:00
cflmy ad3ebf243a fix(view): keep static buttons with a no-live notice
Static pages now render the same toolbar and Execution Clear button as live view. Clicking any execution control shows a static-export notice instead of hiding controls or pretending to run.
2026-10-18 12:55:07 +08:00
cflmy 142d30ce08 fix(view): share the same shell between static and live output
Static exports now include the View shell and dark theme; interactive toolbar and Execution Clear stay hidden, while dynamic pages show them.
2026-10-18 12:52:48 +08:00
cflmy 4757b82edd fix(view): run stateless documents and clear Execution output
No-session view Run All now runs the document and renders stdout into Execution; Clear outputs clears Execution output, plots and plan cards as well as cell outputs.
2026-10-18 12:51:13 +08:00
cflmy bff2f53e52 fix(view): clear Execution output from the view surface
Add an Execution Clear button and clear the Execution out/plots/plan card in addition to code-cell outputs. The same clearOutputs path calls /api/session/clear, so ordinary stateless pages and foreign sessions are both wired.
2026-10-18 12:47:56 +08:00
cflmy fb28eee62f feat(foreign): own view sessions and clear outputs
foreign.session returns a handle from ordinary kernel/cell tables; view consumes only the 会话 binding. Sessions live in host foreign_doc. Without 会话, view cells run stateless one-shot. Add /api/session/clear and a Clear outputs button for every view page; clearing keeps persistent kernel state.
2026-10-18 12:42:15 +08:00
cflmy 01468ad976 test(view): add foreign and non-foreign preview fixtures
Add a pure Marqdo control page and make the Python view-cells example explicitly import lib/foreign.
2026-10-18 12:22:36 +08:00
cflmy f3791d11b4 refactor(view): evaluate cell plans through the interpreter
Delete the source-line table scanner. 内核表/会话表 are now evaluated as ordinary Marqdo bindings (with simple assignment dependencies) via Interpreter::capture_declarations. Every view page uses the same cell toolbar; run/watch semantics are unchanged; no new CLI or Markdown marker.
2026-10-18 12:17:42 +08:00
cflmy 7fef690167 refactor(view): unify cells into the view surface
Cell controls now appear only when a document declares 内核表/会话表. Remove Notebook branding and Jupyter In/Out prompts; ordinary view pages stay classic. There is no new CLI command or second interactive mode; run remains canonical execution and view is the only interactive surface.
2026-10-18 12:03:17 +08:00
cflmy 024cdee82a debian: add 1.5.0 PPA changelog 2026-10-18 03:36:53 +08:00
cflmy f666eaaf40 release: v1.5.0
Foreign v2 + document-native notebooks, view contrast/themes/resize, public OKF/EKC and Python examples. Bump CLI/wasm/ext to 1.5.0; no core surface delta.
2026-10-18 03:17:53 +08:00
cflmy e6f05c7748 docs(public): showcase foreign v2, OKF and EKC
Rewrite the public foreign reference, add bilingual complex Python notebook and OKF/EKC pages, and expand both homepages with executable foreign, notebook, knowledge and preflight examples.
2026-10-18 03:15:34 +08:00
cflmy 81f9ea0072 fix(view): map document tokens to the active theme
Legacy view tokens (--ink, --fill, --line, --muted) now resolve from the notebook theme. This fixes dark text and white annotation chips on the dark STRUCTURE surface, including function names, binding labels, tables, and the right rail.
2026-10-18 03:05:29 +08:00
cflmy dbf3f3a14b fix(view): raise code contrast and unify syntax colors
Remove the two conflicting highlight.js stylesheets and define one high-contrast token palette. Dark code foreground is #f0f0f0 on #1e1e1e (14.6:1); light is #24292f on #f6f8fa (13.8:1). Keywords, strings, and comments stay above readable contrast, and base view code blocks are resizable too.
2026-10-18 03:03:08 +08:00
cflmy 654e89d98c style(view): make cell resize affordance visible
Style the native vertical resize grip and add a hover hint on code and output panes.
2026-10-18 02:59:36 +08:00
cflmy be20629496 feat(view): resizable cells and light/dark themes
Add native vertical resize to code and output panes; add a VS Code Light token set with Jupyter light syntax highlighting, a toolbar theme toggle, and localStorage persistence. Keep the restored three-column layout.
2026-10-18 02:59:21 +08:00
cflmy 3223295841 fix(view): restore notebook left nav and right rail
Keep the original three-column layout (file navigation, main structure, Functions/Variables rail) and execution/source sections; restyle them with the same VS Code dark surface tokens so the notebook remains readable and consistent.
2026-10-18 02:56:34 +08:00
cflmy beb5bdbe8c style(view): align notebook with VS Code dark and Jupyter cells
Flat VS Code Dark surfaces and borders, Jupyter In[n]/Out[] cell structure, unified top cell toolbar, consistent typography and spacing, removed gradients, glows, heavy shadows, and multi-color pills.
2026-10-18 02:51:28 +08:00
cflmy b8cb022018 style(view): redesign notebook layout and controls
Single-column notebook shell, sticky glass toolbar, card cells with language/kernel/status pills, output panel, dark-mode support, responsive layout, and hidden duplicate Execution/Source sections.
2026-10-18 02:45:10 +08:00
cflmy b9e331cb31 test(notebook): add Python business-insights example
Five-cell Python notebook sharing one kernel: deterministic order generation, regional/product metrics, z-score anomaly detection, ASCII report + JSON, and an isolated second Python kernel that validates the report through an explicit file bridge.
2026-10-18 02:38:48 +08:00
cflmy 476c2b607b fix(view): use relative API URLs for path-prefix reverse proxy
Notebook and debugger controls now call api/... and open debug?path=... relative to the page, so the same HTML works under a path prefix such as /marqdo-view/<token>/. This enables same-origin DSH preview without publishing another Docker port.
2026-10-18 02:33:50 +08:00
cflmy d99b275336 fix(parse): do not over-promote branch-local variables to params
If/else arms that all bind a local (e.g. # llm key/url/mdl/nm) no longer leak it into constructor params. This fixes the missing `key` error in llm.create and restores the agent/llm gold tests. Adds a regression test.
2026-10-18 02:09:16 +08:00
cflmy 1415aee08f docs(notebook): record D1–D3 implementation status 2026-10-18 01:45:41 +08:00
cflmy 0f2c12b636 feat(notebook): link statement debugger from view
Expose /debug and /api/debug/* on the live view server; add a notebook Debug button so Marqdo statement stepping is reachable from the same page/session as cell stepping.
2026-10-18 01:44:05 +08:00
cflmy 9873df7099 feat(notebook): reload, journal and state panel polish
D3 (partial): reload re-parses the document while preserving kernels, marks changed cells dirty; Journal and Reload view actions; filtered Node variable names for the state panel; per-session timeout parsing before spawn.
2026-10-18 01:41:36 +08:00
cflmy 3001ed7ba5 feat(notebook): document session with shared kernels and view controls
D1/D2: 内核表/会话表 parsing, DocumentSession cell index, named/default kernels, shared state + isolation, run_cell/step/run_all/restart/assign, state bridge, journal, POST /api/session/*, and a live-view notebook bar with status badges, per-cell kernel selector, step/run-all and push/pull state form.
2026-10-18 01:39:36 +08:00
cflmy 050d71927f feat(foreign): persistent Python/Node kernels and state bridge
F3/F3.5: session_open/eval/close/list, session_set/get/names, Python and Node bootstraps, strict serial protocol, per-session timeout, crash isolation, drop cleanup, and node/bash gold tests (python conditional).
2026-10-18 01:32:48 +08:00
cflmy 7859170aec feat(foreign): JSON call and parallel fan-out
F2: call/call_many JSON bridge, run_many ordered parallel execution with per-item isolation and concurrency cap, plus node gold tests for call and call_many.
2026-10-18 01:29:15 +08:00
cflmy e32ff8f6b3 feat(foreign): structured invoke, presets, probe and config
F0/F1: safe execution core (exec gate, bounded IO, process-group timeout), structured invoke records, run options, 15 language presets, register/unset/probe/config, view stderr/exit/ms, and node/bash gold tests.
2026-10-18 01:26:53 +08:00
cflmy c21a28c3bc docs(foreign): design kernel runtime and document session
Record the Jupyter-beyond discussion, decisions, and the document-native notebook syntax (内核表/会话表). Split the design into F (foreign kernel runtime) and D (document session) layers, with roadmaps, state bridge, stepping, journal, and security rules.
2026-10-18 00:43:31 +08:00
cflmyandCursor 1e61dca9d8 release: Marqdo 1.4.6
CLI and wasm only. Bare self-increment now promotes a required parameter, matching design §8.2. Extension pack stays 1.4.5.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 23:58:09 +08:00
cflmyandCursor ba675a4767 fix(parse): promote a bare self-increment to a required parameter.
Design §8.2 treats the first bold assignment as a declaration, but merging only walked backtick mentions, so n = n + 1 never entered the signature.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 23:55:30 +08:00
cflmyandCursor bfd468d5e3 release: Marqdo 1.4.5
Streamable HTTP MCP, web invoke Bearer/401, openai/agent json.get hardening.
Bump CLI/Ext/wasm and debian changelog.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 17:36:07 +08:00
cflmyandCursor 8353ba38fe Add Streamable HTTP MCP and harden web /v1 invoke auth.
agent_mcp_serve gains http transport; invoke injects Bearer/X-Api-Key and maps
unauthorized to 401; openai/agent field access prefers json.get over footnotes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 17:33:24 +08:00
cflmyandCursor b43a08b2e2 release: Marqdo 1.4.4
Soft LLM transport errors and table-first ext/ai; CLI + Ext + wasm SemVer bump.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 14:38:16 +08:00
cflmyandCursor 1908bf1a53 fix(ai): soft LLM transport errors and strip ext/ai json glue
Host/plugin HTTP failures return structured finish|status=error instead of
aborting the VM; agent/llm/openai/智能体 result maps use GFM tables and
table.put. SKILL gains positive copy-paste examples so agents stop mirroring
legacy json.set chains.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 14:27:45 +08:00
cflmyandCursor c44ea38ae2 release: Ext pack 1.4.3 — agent.run cold EFI / resolve llm_free
Bump ext/VERSION only (CLI stays 1.4.2). Ships agent facade + native miss-field fix for qdagent cold OKF.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:56:40 +08:00
cflmyandCursor d489f7c088 fix(ext/ai): cold agent.run EFI — self.preflight and resolve llm_free
Miss resolve omitted llm_free and run called bare preflight, which crashed
qdagent on empty OKF. Align miss fields, use self.preflight + json.get, add
regression gold and research note.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:54:00 +08:00
cflmyandCursor a993cfd76a chore: sync Cargo.lock package versions to 1.4.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:21:23 +08:00
cflmyandCursor d5f826a8c8 release: Marqdo 1.4.2
Bump CLI/wasm/ext to 1.4.2 for Agent/LLM optimize O1–O5 (sandbox trial,
promote proof, step_route/EFI, lint, quarantine).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:51:41 +08:00
cflmyandCursor 0f72173d08 feat(ext/ai): land Agent/LLM optimize waves O1–O5
Wire opt-in sandbox trial into agent, require sandbox proof before OKF
promote, add step_route/EFI/cost surfaces, style lint + quarantine, and
offline policy optimize script—keeping GFM tables over json glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:47:28 +08:00
cflmyandCursor a707758d47 docs: research and plan Agent/LLM optimization with OKF and sandbox
Capture the 2026-10 landscape (skills, Skill Lift, routing, GEPA) against Marqdo’s code-as-docs assets and list feasible optimize directions without editing doc/next.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:13:48 +08:00
cflmyandCursor 63bcb882a6 feat(ext/ai): add CoW sandbox for Marqdo-only agent trials
Give agents a capability-capped run path that stages workspace edits until commit, so generated .mq.md can be verified without polluting the real tree.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:11:54 +08:00
cflmyandCursor 1bb16dd6db release: Marqdo 1.4.1
View annot leaders mid-to-mid SVG, frame chip id unify; bump CLI/wasm/ext.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:37:24 +08:00
cflmyandCursor 58ec2172d6 fix(view): mid-to-mid annot leaders and prose chip density
Unify frame chip ids with marks, reorder chips under anchors, and draw
SVG leaders from underline mid-bottom to chip mid-top so crowded bands
stay readable.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:36:12 +08:00
cflmyandCursor 66926e9e0a release: Marqdo 1.4.0
Prose-unified control flow, formula meta bind, image writeback, view
inferred params; sync CLI/wasm/ext/VERSION and install docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:54:45 +08:00
cflmyandCursor dcf4c05663 fix(ext/net): wrap url.encode via lib/net, not host_*
Gold rule bans host_* from ext/**; encode must go through stdlib.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:47:07 +08:00
cflmyandCursor f47a1e143a feat(writeback): image form ![marqdo-out](…) with view parity
Auto-persist image paths/URLs as Markdown images (validated extension);
keep HTML comment for text. View and static export share styled source
markers and output-card <img> rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:45:52 +08:00
cflmyandCursor 9cf98a98b5 feat: block formula meta bind and control-flow prose
Support $$ % marqdo: var= binding, arm/loop narrative (fix comment-paragraph
swallow of branch arms), foreach ZH/EN sugar, and condition-line narrative.
Welcome pages and gold samples updated; view skips meta formula fence bodies.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:28:46 +08:00
cflmyandCursor f99d552d87 feat(view): show inferred param values; migrate welcome to v0.3 prose
Param chips carry call-frame values (and refresh with the call picker).
Welcome pages and the marqdo skill prefer body-inferred, conversational markup.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 14:32:50 +08:00
cflmyandCursor 7d49c358c1 fix(view): nested-call welcome + clean formula/code cards
Welcome pages put greet calls in # main so CallFrames/pickers appear;
document surface skips fence body lines and Bind chips under formula/code cards.
Adds view-static-interactive design and entry-vs-method regression tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 14:13:42 +08:00
cflmyandCursor a32c0cd78f fix(ppa): skip cp when local orig already sits in build-area
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:42:37 +08:00
cflmyandCursor 0a8f76d9b4 release: v1.3.3 — view document-surface Structure
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:18:51 +08:00
cflmyandCursor 4e2419b598 feat(view): document-surface Structure with frame-aware annotations
Browse Structure keeps narration and surfaces post-stmt values, branch
arms, and call/loop pickers; static `view output` shares the same render
path so exported HTML matches live view.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:12:53 +08:00
cflmy f6374d1593 release: ext pack v1.3.2 trailing slash route fix 2026-10-13 15:37:42 +08:00
cflmy 9ede4bc63d fix(web): strip trailing slash so /post/foo/ matches /post/foo
Go ServeMux does exact-match routing; a trailing slash caused dynamic
routes like /post/{slug} to fall through to the 404 catch-all. Add
withStripTrailingSlash middleware as the outermost handler wrapper so
all downstream middleware (RBAC, tenant, mux) see the normalized path.

Tested: static routes, dynamic routes, root path, query-string preservation.
2026-10-13 15:24:26 +08:00
cflmyandCursor 3ae8f2c843 release: ext pack v1.3.1 OIDC path redirect_uri
Bump ext/VERSION only; CLI remains 1.3.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-08 11:42:08 +08:00
cflmyandCursor e9c1a8a730 feat(web): resolve OIDC redirect_uri from request Host
Allow path-style redirect_uri (/oidc/callback) so apex/www and
proxied HTTPS share one config; persist the absolute URI for token exchange.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-08 11:35:12 +08:00
cflmyandCursor 5554b1642c feat(run): add --fs-root / MARQDO_FS_ROOT for subdirectory entries
marqdo run cli/… sandboxes to the entry directory by default; repo-root
sandbox+cwd lets qdagent keep thin CLI wrappers under cli/ without
escaping .marqdo or polluting cli/.marqdo.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 22:17:24 +08:00
cflmyandCursor fe15603a91 fix(llm): hoist ask result fields out of the return table
Table cells shadowed self/column names (model, usage), so [model](self)
and [total_tokens](usage) raised "footnote index needs list or map" and
blocked live agent.step / qdagent BUILD.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 22:08:48 +08:00
cflmyandCursor 1418742655 Skip docker/data/.cursor when compiling engineering knowledge.
Packaging trees and runtime vaults were inflating EKC with duplicate noise; dogfood agents should index product sources only.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 21:50:58 +08:00
cflmyandCursor ed31a2b31d release: v1.3.0 Engineering Knowledge Compiler (EKC)
Bump CLI/ext/wasm to 1.3.0; document L0–L4 catalog, reuse preflight, and
agent eng_* surfaces for AI-native engineering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 16:46:30 +08:00
cflmyandCursor 56ab52356f feat(knowledge): land Engineering Knowledge Compiler (EKC) from 008
Give agents Engineering First Information before codegen: L0–L4 catalog,
reuse/preflight (REUSE→ADAPT→CREATE), graph, and CLI surfaces so large
repos stop reinventing existing capabilities.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 16:44:39 +08:00
cflmyandCursor 2e425c3010 chore: sync Cargo.lock to 1.2.0 for PPA vendor
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:59:48 +08:00
cflmyandCursor 46a0263d7f release: v1.2.0 Web Artifact (ADR 0007) Document/Endpoint/Resource
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:39:25 +08:00
cflmyandCursor ff252fd469 feat(web): land Artifact serve/endpoint path and retire compose golds
Wire data_source into Document render, register Endpoint handlers via
run_artifact, restore marqdo-blog as an Artifact site, and replace old
compose_* web golds with ADR 0007 fixtures and docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:36:45 +08:00
cflmyandCursor 67bac1bf02 feat(web): Document/Endpoint/Resource artifact rewrite (ADR 0007)
Replace the monolithic compose_*/configure author surface with file-level
web|endpoint artifacts, split ext/{web,data,security,net}, and lock
no-degrade rules so the model cannot regress to God-object APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:06:38 +08:00
cflmyandCursor 33f8b94bb0 release: v1.1.1 AI stack (llm/agent/metadata) + ship plugins/llm
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:34:08 +08:00
cflmyandCursor 0ed57b6d54 feat(agent): ext APIs, goldens, and docs for MCP/resume/small-llm routing
Wire mcp_connect/list/call, resume_*, and demote Jev in author docs.
Offline goldens cover MCP client, resume, and small-llm/jev-alias route.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor c29d48f38c feat(agent): MCP stdio client, resume checkpoints, small-llm router alias
Add agent_mcp_client and agent_resume_* plugin APIs. Treat jev as a
compat alias of small-llm; auto cascade no longer probes MARQDO_JEV.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor f1e82ce4e5 feat(llm): optional plugins/llm Transport ABI for chat completions
OpenAI transport prefers llm_chat_completions when the native plugin is
resolvable, and falls back to lib/net HTTP/SSE so CI stays green without the .so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor 2d412e3bba feat(llm): LLMResult.tool_calls from OpenAI-shaped responses
Parse choices[0].message.tool_calls into the ask Result; empty list when
absent. Offline gold covers tool_calls_from.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:07:59 +08:00
cflmyandCursor 46d78c6e15 feat(core): Phase 2 Metadata scope lift (no body ${})
Inject bound frontmatter keys into the entry env as ordinary variables.
Reject body ${env…}; bytecode entry prologue seeds the same locals.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:05:25 +08:00
cflmyandCursor 81a14f9b38 feat(llm): sys.module_source + entry prompt / meta offline paths
Expose entry source via sys.module_source; ask/stream fall back to
prompt_body of the entry document. Add meta-binding and entry-prompt golds.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:52:57 +08:00
cflmyandCursor 88dc6d5a54 feat(core): Artifact Metadata Binding (${env|arg|sys|secret})
Load-time resolve of frontmatter bindings into Module.metadata; Secret
masking; sys.meta / --bind; llm ctor prefers meta over env_get.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:51:24 +08:00
cflmyandCursor 4a2d89406b fix(agent): preserve llm_free resources under plan force
Stop plan from clobbering an existing resources workbook with an explore
skeleton. Add llm.prompt helpers and agent-plan-preserve gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:34:05 +08:00
cflmyandCursor d8d435fead feat(ai-stack): metrics, named handles, prompt docs, backends, zero-LLM
Finish ai-stack steps 1–5: model_turn usage, fast/reasoning, type:prompt
load, openai/ollama split, and agent-zero-llm gold. Fix compiled-skill
Marqdo syntax so llm_free await no longer falls through to plan+HTTP.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:30:25 +08:00
cflmyandCursor 1f8e61f3bf feat(llm): semantic ask/stream/collect surface (005)
Lift ext/ai/llm from OpenAI HTTP client to an intelligence primitive;
keep complete as compat. Add unified ai-stack roadmap linking agent + llm.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:35:38 +08:00
cflmyandCursor a9ee858f53 feat(agent): Skill Compilation + Adaptive Routing (v2/P4)
Episode → maybe_learn → llm_free skills, plus abstract router backends
(marqdo/small-llm/jev?/llm/auto) via plugins/agent; no core host changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:28:50 +08:00
cflmyandCursor 8489d90926 docs(public): 新增 feature 18 —— AI 原生闭环(契约 + MLSP)中英各一篇
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:46:03 +08:00
cflmyandCursor 5272acaea0 release: v1.1.0 —— 核心表面守卫 + 渐进式契约 + MLSP for AI
- Cargo.toml / marqdo-wasm / ext/VERSION → 1.1.0(CLI 与扩展同步)
- CHANGELOG v1.1.0(含核心表面 Δ = 无增删;诚实标注 P4(b) 盲测未达标)
- README 现状/安装/示例更新(新命令 check / --json / mlsp)
- debian/changelog 1.1.0-1ppa1;release.yml Highlights stub 更新
- 核心表面 Δ:无增删(19 构造不变;本版为 Runtime/Document 层变更)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:31:27 +08:00
cflmyandCursor cba51238b6 doc/next/002: 智能体框架「认知编译」构想(Learning → Compilation)
用户维护文档归档:每次执行沉淀 mq.md;>3 次调用自动总结优化出记忆文档;
完全学会后降能耗运行(少 LLM 思考 / Jev 决策模型 / 纯分支控制)。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:19:56 +08:00
cflmyandCursor 5fffb800f9 P4(b) 收口:mimo-v2.6-pro 两跑均端点 infra 不可评估,判据以 deepseek-flash 为准
- perf-validation-report §3 记录重跑终局(12/12→11/12 infra),(b) 判据判定不改
- three-problems-plan Phase 4 落地记录同步

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:10:28 +08:00
cflmyandCursor 1a729eb9ec P4 验证执行:(a)锚点消融✅/(c)契约消融✅/(d)防漂移✅/(e)守卫演练✅;(b)盲测 deepseek-flash 完成未达标、mimo-v2.6-pro 重跑中
- perf-validation.md:五实验协议/判据/材料(2026-09-23 自设计)
- perf-validation-report-2026-09-23.md:汇总报告(判据逐项对照 + 诚实结论)
- tests/blind_experiment.rs + tests/blind/:盲测 harness(查询通道/修复回路/usage 计量)+ 冻结材料(6 任务书 + docs-bundle)
- tests/contract_ablation.rs:四边界×三情形消融(拦截 100%/误报 0%/零回归)
- tests/drift_drill.rs:9 漂移必报 + 2 负对照
- src/mlsp.rs:syntax 卡片自持化(semantics/rule/sample/doc_quote)
- three-problems.md §5.1 判据矩阵逐行判定(问题 1✅ 2✅ 3❌);three-problems-plan.md Phase 4 落地记录
- 全量干净回归零失败

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 05:06:30 +08:00
cflmyandCursor 00c763300e test(repair): mimo-v2.6-flash cross-check + measurement-side hardening
mimo-v2.6-flash 终测:anchor 臂一轮 20/20=100%、plain 90%(最终 95%);
三轮双臂一轮修复率全部 >=85%(目标 >=80%),护栏 0 越界。

'测试不稳定'定性为三类测量端问题并全部加固(与 Marqdo 语义无关):
- 网关空体抖动 -> curl --retry + 5s 退避(加固后 0 次失败)
- 推理模型 reasoning_content 吃光 token 预算 -> max_tokens 2000->8000
- 模型输出格式畸形 -> parse_edits 容错(数组/单对象/NDJSON 多对象流/
  字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补 unquote_line_nums)

报告按模型分文件(repair-experiment-<date>-<model>.md),cflmy/mimo 双报告并存;
计划记录更新为三轮对照表。干净环境 cargo test 444/444 全绿(零回归);
ext_llm_*/ext_agent_*_live 为环境开关型实况测试,与本期无关。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 01:27:01 +08:00
cflmyandCursor 224b3d4a66 test(repair): §5.2(a) 模型在环修复实验 —— 锚点消融:anchor 100%(20/20) vs plain 85%,≥80% 目标达成
- tests/repair_experiment.rs:真实消费 validate → repair_targets → 模型行编辑 → repair_apply(越界必拒)
  → 复验 的完整闭环(≤2 轮;容错重试;cflmy @ llm.cflmy.cn,.env 读取,#[ignore] 不进常规回归)
- 双臂消融:anchor(诊断带 doc_anchor/doc_quote/suggestion)vs plain(剥掉)——
  anchor 一轮修复 20/20=100%;plain 17/20=85%(3 例失败均为网络空体抖动)
- tests/common/mod.rs:golden 20 例与诊断/应用共享件抽出(repair_loop + experiment 同源)
- parse_edits 容错(数组/单对象/字符串化元素/围栏);越界必拒/abstain 由 repair_loop 硬断言覆盖
- 报告:doc/roadmap/repair-experiment-2026-09-22.md;.gitignore 补 .env(密钥不入库)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 21:10:03 +08:00
cflmyandCursor 81d26a265a docs(roadmap): 落地记录 —— T3.4 修复回路工程项完成(护栏 + golden 20 例);T3.3 编号归位
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:14:32 +08:00
cflmyandCursor 5b599125d1 feat(repair): T3.3 修复护栏 + golden 20 例 —— 机械护栏(有界行编辑·越界必拒·abstain)+ mlsp repair_apply
- src/repair.rs:行编辑有界应用(replace/delete/insert;触碰行必须落在靶点范围内,
  越界 ⇒ 整体拒绝 + 越界清单,源零字节不改 = abstain;表尾追加允许 end+1)
- mlsp repair_apply:护栏的 MLSP 出口(ranges + edits → 新源;越界报 mlsp.repair_out_of_scope)
- tests/repair_loop.rs:golden 20 例(10 骨架 × 2)走完整修复循环
  (诊断 → 靶点 → 金修复行编辑自动推导 → 范围自检 = 「易锚定」机器验证 → 应用 → 复验)
  + 护栏负例(越界必拒 + 源零字节不改 + 部分越界全拒)
- 待做:模型修复实验(把金修复换成模型编辑,测 ≥80% 修复率)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:13:41 +08:00
cflmyandCursor 18d89d6cf2 docs(roadmap): 落地记录更新 —— T3.4 完成;T3.3 golden 实验待做
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:47:19 +08:00
cflmyandCursor 199b5c532f docs(skill): T3.4 AI Skill 换骨 —— 背语法 → 查 MLSP;渐进式契约入语法面
- marqdo/SKILL.md: 置顶「查 MLSP」查询式工作流(五方法 + 行分隔 JSON 协议 + 修复护栏);
  渐进式契约三种表格形状/位置/四边界;工作流与 checklist 增加 validate/check 环节
- marqdo-dev/SKILL.md: 契约/MLSP/三层准入/错误出口唯一的开发戒律

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:46:25 +08:00
cflmyandCursor db5f0e830b feat(mlsp): Phase 3 MLSP for AI —— locate/syntax/validate/repair_targets/schema(T3.1/T3.2 + T2.6)
- src/mlsp.rs: 行分隔 JSON 协议 + 五 handler;语法唯一事实来源 = CORE_CONSTRUCTS(只加检索别名)
- repair_targets 带有界护栏策略(anchored-local / 越界必拒 abstain / max_attempts=2)
- schema 契约导出(T2.6):形参/返回/字段契约 + 升参清单 + 锚点
- marqdo mlsp 子命令:stdio 行分隔 JSON 服务
- tests/mlsp.rs 7 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:44:35 +08:00
cflmyandCursor 7a449c40b1 feat(contract): Phase 2 渐进式契约层 —— 契约表提取 + 四边界校验 + marqdo check 防漂移(T2.1–T2.5)
- src/contract.rs: 类型词汇(渐进标注)、参数/返回/字段三形状契约表解析、合并、四边界校验诊断
- src/parse/mod.rs: extract_function_contract —— 位置+形状双重判定,在升参推断之前提取;
  绑定表/普通文档表绝不吃(P1 零回归),契约表从 body 移除(元数据永不执行)
- src/interp.rs: 四边界校验 —— 调用实参(3 条调用路径)/返回/表绑定/字段访问
- src/check.rs + marqdo check [--json]: 漂移双向互查、未知类型名(附建议)、错位契约
- src/load.rs: label_error 保留结构化诊断(错误出口唯一,不拍平成字符串)
- T2.4: 全部契约诊断带 doc_anchor/doc_quote/contract_ref
- tests/contracts.rs 12 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:40:08 +08:00
cflmyandCursor 97fda7aa10 feat(core): Phase 1 —— 核心收口 + 诊断地基(core-surface 守卫 · 三层准入 · Diagnostic JSON)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:03:03 +08:00
cflmyandCursor a49592a3ba docs: 三大问题设计移出 doc/next/ → roadmap/three-problems.md;新增落地计划 three-problems-plan.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:46:09 +08:00
cflmyandCursor ed9ac03c0c docs: README 前置核心优势与愿景(Executable Knowledge 定位);doc/next 交流笔记入库
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:07:33 +08:00
cflmyandCursor cb46ad7abe fix(ppa): trim bundled Rust to build essentials; clean extract on failure
Launchpad builds only need rustc + cargo + rust-std (debian/rules PATH),
but install.sh was still shipping rust-docs-json-preview / rustfmt /
rls (~1G). Also drop the 1.5G extract dir via EXIT trap when install
fails — the leftover is what filled /tmp last run.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 16:40:39 +08:00
cflmyandCursor 586975090b release: v1.0.7 — WS/网络边界加固
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:40:48 +08:00
cflmyandCursor 544805266b fix(wasm): mark marqdo-bridge.js as ESM for Node consumers
The canonical bridge uses ESM exports but, with no package.json in scope,
Node loads untyped .js as CommonJS — tests/wasm/smoke.mjs could not see
applyDomPatch et al (Named export not found). Scope type=module to the js
dir only; marqdo wasm build copies just the single .js file, so nothing
ships differently.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:27:09 +08:00
cflmyandCursor f3051fb536 fix(test): align P3 gold with quiet-admin gate semantics
b752cd4 stopped auto-gating admin_prefix when admin=false but did not
update the P3 gold, which still expected the removed /admin auto gate
(ng >= 2). Assert the new intent instead: exactly one explicit gate
registered with the declared path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:20:48 +08:00
cflmyandCursor 86b183e2d7 fix(web): harden WebSocket and net host boundaries
- WS handshake: same-origin CheckOrigin instead of allow-all
- route_ws require_auth/需要登录: broadcast/room need a session by default,
  explicit opt-out for public feeds; unauthenticated handshakes get 401
- WS limits: 1 MiB per message, 256 replies per connect; transport errors
  return {ok:false, error} instead of an empty success; empty rooms GC'd
- net host: enforce the 8 MiB response cap while reading (incl. error and
  SSE error paths) so a peer cannot exhaust memory
- url_encode: %20 for space (URL segment semantics, not form +)
- docs: sync 网页 (route_ws 需要登录, connect caps) and CHANGELOG
- tests: gold expectations, live fixture opt-out, hub GC, ws auth gate

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:14:35 +08:00
978 changed files with 81511 additions and 25273 deletions

No files matched your search

+26
View File
@@ -0,0 +1,26 @@
---
description: Marqdo Web Artifact — no degradation; Document/Endpoint/Resource only
globs: ext/web/**,ext/net/**,ext/data/**,ext/security/**,examples/**/*,tests/ext/web*,doc/design/ext-web*,doc/adr/0007*
alwaysApply: true
---
# Web Artifact — 不允许降级
Canonical: `doc/adr/0007-web-document-endpoint.md` · `doc/design/ext-web-artifact.md` · `doc/next/007.md` (superseded).
## Hard bans
1. **Do not** restore or reintroduce author-facing `compose_main` / `compose_intro` / `compose_*` fragmented table DSLs, god `# page` mutation piles, or `app.configure(...)` junk-drawer APIs.
2. **Do not** use `json.set` / `json.append` bag glue for pages, routes, or middleware. Tables = data. View schema is only `|type|slot|value|attrs|style|` (ZH aliases allowed).
3. **Do not** call `ensure_plugin` or `host_*` from author programs or from `ext/**` (plugin load is facade/capability only).
4. **Do not** register implicit user routes. Declared routes come from Artifact metadata or `web.route`. System routes (`/_part`, `/_form`, …) must appear in `web.inspect`.
5. **Do not** invent DSL, nested frontmatter under `##`, or new table dialects when the design is silent — **stop and ask**.
6. **Do not** mix EN/ZH API names in one `.mq.md`.
7. **Do not** silently delete capabilities. Removals require design text + tests updated in the same change.
8. **Do not** put DB/auth/cache/storage/websocket author APIs back into `ext/web/web.mq.md` — they live in `ext/data`, `ext/security`, `ext/net`.
## Required direction
- Document (`type: web` / `类型: 网页`), Endpoint (`type: endpoint` / `类型: 端点`), Resource modules.
- Facade only: `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect` (ZH mirrors).
- Code is documentation: the `.mq.md` is the page/API docs and the implementation.
+75 -6
View File
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
### 2. Good patterns
### 2. Good patterns (copy these — not `json.set`)
**Wire / steps / commands** — `@` record table:
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
| `wire` | `set_text` |
```
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
```markdown
`out` =
| status | task | result | llm_calls | tokens |
|--------|------|--------|-----------|--------|
| ok | `task` | `reply` | `llm_calls` | `tokens` |
*out*
```
**Soft error pack** (transport / gate failure) — still a table humans can skim:
```markdown
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
```markdown
`out` =
| status | task |
|--------|------|
| error | `task` |
1. `err`
**out = > table.put in=`out` at="error" value=`err`**
2. *
**_ = 1**
```
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
```markdown
**empty_tc = > table.empty_list**
**empty_map = > table.empty_map**
```
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
```markdown
**`set_text` = table.put in=None at="#log" value=msg**
@@ -73,14 +119,20 @@ Better still — call a named helper:
**browser.set_text sel="#log" text=msg**
```
### 3. Bad pattern (do not write)
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
```markdown
**`ret` = json.set map=None key="set_text" value=…**
**`ret` = json.set map=ret key="canvas" value=…**
**`cmds` = json.append list=cmds item=c0**
**`out` = json.parse text={"status":"ok"}**
**`out` = json.set map=out key="task" value=task**
```
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
## Writing application `.mq.md`
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
@@ -92,7 +144,7 @@ Better still — call a named helper:
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
Browser client programs: prefer nested `import:` with `browser: lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
## Developing libraries (`lib/*`, `ext/*`)
@@ -121,7 +173,9 @@ Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code
| Need | Place |
|------|--------|
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
| Site HTML / HTTP / DB | `ext/web` classes + compose from tables |
| Site HTML / HTTP | `ext/web` Document/Endpoint + View tables |
| DB / cache / storage | `ext/data` |
| Auth / OIDC / RBAC | `ext/security` |
| List/map primitives | `lib/table.mq.md` |
| Parse JSON text | `lib/json.mq.md` only |
@@ -132,7 +186,7 @@ When editing a file full of `json.set`:
1. Turn static structures into GFM tables.
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
3. Leave at most sparse `table.put` for dynamic keys.
4. Drop `import json:…` if unused.
4. Drop unused `json:` (or other) entries under nested `import:`.
## Anti-patterns
@@ -150,3 +204,18 @@ When editing a file full of `json.set`:
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
- Release: [marqdo-release](../marqdo-release/SKILL.md)
## 渐进式契约 + MLSP(Phase 2/3 落地后的开发戒律)
- **契约实现**:`src/contract.rs`(类型词汇 / 三形状契约表解析 / 合并 / 四边界校验诊断);
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行;
绑定表与普通文档表绝不吃 ⇒ 无契约文件零回归)。契约表从 body 移除——元数据永不执行。
- **静态互查**:`src/check.rs`(`marqdo check [--json]`)——契约行 vs 升参推断形参双向漂移、
未知类型名、错位契约;Error ⇒ 非零退出。
- **AI 工具面**:`src/mlsp.rs`(`marqdo mlsp`,行分隔 JSON)——`locate` / `syntax` / `validate` /
`repair_targets` / `schema`。语法唯一事实来源 = `parse::CORE_CONSTRUCTS`(CI 守卫与
`doc/design/core-surface.md` 同步);MLSP 只加检索别名,**不定义语法**。
- **准入戒律**:新特性先过 `doc/design/layers.md` 三层归属(Language 层改动须 ADR + core-surface);
新契约形状/类型词汇 = 文档层扩展,进 `src/contract.rs`,不进词法/语法。
- **错误出口唯一**:`src/load.rs::label_error` 已示范——装载层/任何新代码都**不许**把
`Diagnostic` 拍平成字符串;错误链里必须能 `Diagnostic::find` 找回结构化诊断(AI/MLSP 面)。
+1 -1
View File
@@ -85,7 +85,7 @@ Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secret
|------|------|-----|-----|
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
| `ext/VERSION` | bump | — | bump |
| `CHANGELOG.md` | `## vVER` | `## vVER` | `## Ext pack vVER` |
| `CHANGELOG.md` | `## vVER`(含**核心表面 Δ**,见 `doc/design/layers.md`) | same | `## Ext pack vVER` |
| `README.md` / `public/**` install + download table | update | update | update ext notes |
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
+63 -82
View File
@@ -4,39 +4,40 @@ description: >-
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
syntax (functions, calls, statements, returns, control flow). Use when writing
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
building dynamic sites with ext/web, quantum circuits with ext/quantum,
formula-first linear algebra with ext/linalg, or when the user mentions
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
or linalg/线性代数 extension.
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
sites with ext/web, quantum circuits with ext/quantum, or when the user
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
quantum/量子 extension.
---
# Marqdo development
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
## Markup → meaning (v0.3)
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
@@ -47,23 +48,32 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| GFM table after empty RHS bind | Collection; get with `access(coll, "key")` (legacy `` `m`[^key] `` remains available) |
| `- [item](遍历 coll 为 item)` | Foreach |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.1.0)
Occlusion is the default syntax. Shipped source declares `markup: occlusion` (or `标记: 遮蔽`) explicitly so imports stay deterministic. Legacy `[key](collection)` requires `markup: classic` or the one-cycle CLI flag `--legacy-markup`; `MARQDO_MARKUP` does not change parsing.
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --mark --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
## Minimal program
```markdown
@@ -103,17 +113,17 @@ Chinese builtins (same functions, no import):
## Statements, returns, branches
```markdown
**x = 1**
**y = x + 2**
*x = 1*
*y = x + 2*
## add_one
+ `n`
*n + 1*
**n + 1**
```
```markdown
**n = 0**
*n = 0*
1. `n` > 0
> print text=positive
@@ -125,27 +135,28 @@ Chinese builtins (same functions, no import):
## Frontmatter imports + stdlib
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
Imports use nested YAML `import:` (`导入:` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
import text:lib/text.mq.md
import clock:lib/time.mq.md
import:
text: lib/text.mq.md
clock: lib/time.mq.md
---
# main
**xs = > text.str_split s="a,b,c" sep=","**
*xs = > text.split value="a,b,c" sep=","*
> print text=`xs`
**t = > clock.now_unix**
*t = > clock.now_unix*
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -162,48 +173,22 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
## Official extension: `ext/web` (Document / Endpoint / Resource)
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- EN: `import web:ext/web/web.mq.md`
- ZH: `导入 网页:ext/web/网页.mq.md`
**Hard rules (web):**
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`).
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
**Typical layout:**
```text
index.mq.md # entry + home page table + listen
pages/ # sub-pages
components/ # reusable |属性|值|样式| tables
styles/ # CSS modules
public/ # static + favicon.ico|png|svg
db/ # schema + open/init
data/ # sqlite runtime (gitignore)
```
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **表驱动引言** `page.compose_intro` / `页面.引言装配`(属性/值/样式表 → `.main-intro`,避免手写 HTML 字符串);**D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
## Official extension: `ext/quantum` (circuits + Q7/Q8)
@@ -229,18 +214,15 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## Official extension: `ext/linalg` (formula-first LA)
## Foreign kernels (v1.5.0)
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
- EN: `import la:ext/linalg/linalg.mq.md`
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
## AI authoring workflow
@@ -264,13 +246,12 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
| `json.set` / `compose_*` page parts | `type: web` Document + View table / `web.render` / `web.serve` |
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
+72 -12
View File
@@ -141,7 +141,8 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
```markdown
---
import browser:lib/browser.mq.md
import:
browser: lib/browser.mq.md
---
# main
@@ -162,12 +163,64 @@ import browser:lib/browser.mq.md
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
## 6e. Agent / LLM result maps — GFM first (positive)
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
```markdown
---
import:
table: lib/table.mq.md
---
## step_ok
+ `task`
+ `reply`
`out` =
| status | task | result |
|--------|------|--------|
| ok | `task` | `reply` |
*out*
## step_err
+ `task`
+ `err`
`out` =
| status | task | error |
|--------|------|-------|
| error | `task` | `err` |
*out*
## soft_http_pack
+ `msg`
+ `usage0`
**empty_tc = > table.empty_list**
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
## 7. Import text stdlib
```markdown
---
title: split demo
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -180,8 +233,9 @@ import text:lib/text.mq.md
```markdown
---
import re:lib/re.mq.md
import enc:lib/encoding.mq.md
import:
re: lib/re.mq.md
enc: lib/encoding.mq.md
---
# main
@@ -196,8 +250,9 @@ import enc:lib/encoding.mq.md
```markdown
---
import log:lib/log.mq.md
import uuid:lib/uuid.mq.md
import:
log: lib/log.mq.md
uuid: lib/uuid.mq.md
---
# main
@@ -228,7 +283,8 @@ After a blank line, code runs:
```markdown
---
description: loads math
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -276,7 +332,8 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
```markdown
---
import agent:ext/agent.mq.md
import:
agent: ext/agent.mq.md
---
# main
@@ -328,8 +385,9 @@ if x > 0:
```markdown
---
title: hello-site
import web:ext/web/web.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
db: db/index.mq.md
---
# main
@@ -366,7 +424,8 @@ import db:db/index.mq.md
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# main
@@ -395,7 +454,8 @@ import quantum:ext/quantum/quantum.mq.md
```markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# main
+4 -2
View File
@@ -122,7 +122,8 @@ Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc
```markdown
---
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -141,7 +142,8 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
```markdown
---
import foreign:lib/foreign.mq.md
import:
foreign: lib/foreign.mq.md
---
# main
+15
View File
@@ -0,0 +1,15 @@
## 层归属(必填,见 doc/design/layers.md)
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
## 核心表面(见 doc/design/core-surface.md)
- [ ] 不涉及核心标记
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
## 验收
- [ ] 相关验收(机器可验证)全绿
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
+34 -8
View File
@@ -38,7 +38,7 @@ jobs:
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Checkout extension sources (branch vscode-extension only)
@@ -87,6 +87,7 @@ jobs:
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
Copy-Item target/release/llm.dll "$stageNative/native/llm.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
@@ -100,6 +101,7 @@ jobs:
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
Copy-Item target/release/llm.dll "$stage/ext/native/llm.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -124,11 +126,35 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com);CLI/扩展可分发;noble 捆绑 Rust 工具链
- **v1.0.3**: Ubuntu PPA + extension CDN; independent CLI/ext packs; bundled Rust for noble
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
- **v2.1.0**:文件级 Occlusion 默认语义——全仓迁移 · `migrate labels --mark` · `access` / `遍历` · 可执行知识语义投影
- **v2.1.0**: File-scoped Occlusion by default — corpus migration, `migrate labels --mark`, `access` / `for`, executable-knowledge projections
- **v2.1.0 ext**:扩展包同步 2.1.0 / Ext pack 2.1.0
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
### Downloads
@@ -136,7 +162,7 @@ jobs:
|-------|----------|
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`/`llm`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
@@ -181,7 +207,7 @@ jobs:
run: |
set -euo pipefail
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Package Linux native zip + CLI bundle
@@ -190,7 +216,7 @@ jobs:
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
for lib in libweb.so libagent.so libquantum.so liblinalg.so; do
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
src="target/release/${lib}"
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
src="plugins/web/build/libweb.so"
+19
View File
@@ -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/
@@ -84,3 +94,12 @@ plugins/*/tmp/
# ephemeral sqlite / test artifacts
tests/ext/:memory:
# local secrets
.env
# sandbox gold leftovers
tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
+593
View File
@@ -1,5 +1,598 @@
# 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 行构成。
## v2.1.0 — 2026-10-23
### Highlights
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
```bash
git checkout v2.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
### Added
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
### Fixed
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
### Changed
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
## Unreleased
## v1.5.2 — 2026-10-18
### Highlights
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
```bash
git checkout v1.5.2 && cargo build --release
marqdo ext add web # CDN → 1.5.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
### Added
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
### Fixed
- **`session_list` arity**:保持空 arity。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
## v1.5.1 — 2026-10-18
### Highlights
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
```bash
git checkout v1.5.1 && cargo build --release
marqdo ext add web # CDN → 1.5.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
### Added
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
### Fixed
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
- **写回表标签**:写回表标签保持为行内代码。
### Changed
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
## v1.5.0 — 2026-10-18
### Highlights
**外联 v2 / 文档原生 Notebook**:`lib/foreign` 从“运行一段代码”升级为完整外联内核:结构化 `invoke` 记录、JSON 进出的 `call` / `call_many`、并行扇出、Python/Node 持久内核、显式状态桥,以及用绑定表声明的 Notebook 单元。`view` 增加 cell 单步、Run All、内核切换、journal、状态面板、浅/深主题与可调高度代码区;高对比度 token 修复了代码和 STRUCTURE 文字与背景区分度不足的问题。CLI · wasm · ext **1.5.0**。
```bash
git checkout v1.5.0 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v2 只扩展 `lib/foreign` 的库 API;Notebook 的 `内核表` / `会话表` 是既有绑定表;没有新增 Markdown 标记。
### Added
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
- **Notebook D1/D2**:`内核表` / `会话表` 文档原生语法;`DocumentSession`(cell index / 命名内核 / journal / value store);view Notebook 工具栏(Run All / Restart & Run All / Step / State / Journal / Reload)、状态徽标、内核下拉、Push/Pull 状态表单;`POST /api/session/*`。
- **Notebook D3**:`reload` 重新解析并保留内核,源码变更的 cell 标为 `dirty`;Journal/Reload/Debug 按钮;Debug 打开同一 view 服务的语句级单步页(`/debug` + `/api/debug/*`);状态桥 Push/Pull。
- **安全与健壮性**:所有外联入口检查 `exec` 能力;有界 stdout/stderr 读取与截断标记;stdin 写线程;Unix 进程组 / Windows `taskkill /T` 超时清理;shell-like argv 切分。
### Fixed
- **view 文档表面与标注 chip**:把旧 view 的 `--ink` / `--fill` / `--line` 等 token 映射到当前主题,修复 STRUCTURE 中 `main`、`内核表 =`、函数名和 annot-chip 深色文字/白色卡片与暗色背景不一致的问题。
- **view 代码对比度**:移除会互相覆盖的 highlight.js 深/浅两套外链样式,改用内置高对比 token 变量;深色代码正文 `#f0f0f0` on `#1e1e1e`(14.6:1),浅色 `#24292f` on `#f6f8fa`(13.8:1);关键词/字符串/注释均使用可读的对比色。
- **view 反向代理兼容**:Notebook / Debug 的 API 与 Debug URL 改为相对路径,可在 `/marqdo-view/...` 路径前缀下工作,便于 Docker 内通过 DSH 同源预览。
- **分支内共同局部变量**:if/else 各臂都赋值的局部变量不再被误提升为必选形参;修复 `# llm` 构造器无端要求 `key`,恢复 agent/llm/ext 全量测试。新增 `branch_else_common_local_is_not_a_param` 回归测试。
- **外联临时脚本路径**:入口目录为相对路径时,脚本参数现在使用绝对路径,避免 `tests/lib/tests/lib/...` 双拼接。
- **外联失败可观测**:解释器不存在时进入 `invoke` 记录,`run` 仍报错;view 显示 stderr / exit / ms。
### Changed
- **Notebook view 视觉重做**:采用 VS Code Dark 的扁平色板与 Jupyter 的 cell 组织:单一深色底、明确 surface/border 层级、`In [n]` / `Out [ ]` 提示、顶部 cell 工具栏、无渐变/无重阴影、暗色代码区与一致的字号/间距;保留并统一原始左侧文件导航、右侧 Functions/Variables 栏与 Execution/Source 区块;支持深色/浅色主题切换(localStorage 记忆)与代码区、输出区纵向拖拽调整高度。
- **`langs`** 现在返回「预设 ∪ 注册 ∪ 配置」的已知语言(原集合是子集)。
- 大输出从 `Err` 改为「截断 + `truncated=true`」;`subtask` 外联输出同步采用该语义。
## v1.4.6 — 2026-10-16
### Highlights
**裸自增升参**:粗体首次赋值的左值按设计 §8.2 视为声明。`**n = n + 1**` 在没有反引号提及时也会把 `n` 升成必选形参;缺参报 `missing argument for parameter`,不再是函数体内的 `undefined variable`。纯局部赋值(`**score = 1**`)与循环变量不升参。CLI · wasm **1.4.6**(扩展包仍为 **1.4.5**)。
```bash
git checkout v1.4.6 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——升参与 §8.2 对齐(赋值左值声明);不改 MQ 关键词 / 表几何。
### Fixed
- **升参**:`merge_inferred_params` 纳入首次粗体赋值左值。右值在绑定前读取同名(`n = n + 1`)时,该名成为必选推断形参。
### Changed
- CLI / wasm SemVer **1.4.6**。扩展包保持 **1.4.5**。
## v1.4.5 — 2026-10-16
### Highlights
**Streamable HTTP MCP + web `/v1` 鉴权硬化**:`agent_mcp_serve` 支持 `transport=http`(MCP Streamable HTTP 2025-03-26);web invoke 注入 `Authorization` / `X-Api-Key`,`ok=false`+`unauthorized` → HTTP 401;`ext/ai` openai/agent 字段访问改 `json.get`,消除 footnote 硬崩。CLI · Ext · wasm **1.4.5**。
```bash
git checkout v1.4.5 && cargo build --release
cargo build --release -p marqdo_plugin_agent
# HTTP MCP:
# QDAGENT_MCP_TRANSPORT=http marqdo run cli/求道-mcp.mq.md
marqdo ext add agent # CDN → 1.4.5
```
**核心表面 Δ(Core surface Δ)**:**新增** MCP Streamable HTTP 传输(`transport=http|streamable-http`);web invoke 契约扩展(header 注入 · 401);**无** MQ 关键词 / 表几何变更。
### Added
- **`agent_mcp_serve` Streamable HTTP**:`transport=http` · `host`/`port`/`path`;POST JSON-RPC + 可选 GET SSE;`Mcp-Session-Id`。facade:`ext/ai/agent` `## serve`。
### Fixed
- **web invoke**:`Authorization` / `X-Api-Key` 注入 payload;`jsonWrapInvokeValue` 对 `unauthorized` 返回 401;`{sse}` 自动 event-stream。
- **`ext/ai/llm/openai` · `agent` · `llm`**:字段访问改 `json.get` / `at`,避免 `[field](x)` 在非 map 上硬崩。
- **explore workbook**:子任务 `stream=False`(网关 SSE 524 更稳)。
### Changed
- CLI / Ext / wasm SemVer **1.4.5**。
- 设计:[doc/design/ext-web-artifact.md](doc/design/ext-web-artifact.md)(sse / bearer)。
## v1.4.4 — 2026-10-16
### Highlights
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
```bash
git checkout v1.4.4 && cargo build --release
cargo build --release -p marqdo_plugin_llm
marqdo run tests/ext/agent-llm-transport-soft.mq.md
marqdo ext add agent # CDN → 1.4.4
```
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
### Fixed
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
### Changed
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
- CLI / Ext / wasm SemVer **1.4.4**。
## Ext pack v1.4.3 — 2026-10-16
### Highlights
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
```bash
marqdo ext add agent # CDN latest → 1.4.3
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
### Fixed
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
### Changed
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
## v1.4.2 — 2026-10-16
### Highlights
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
```bash
git checkout v1.4.2 && cargo build --release
cargo build --release -p marqdo_plugin_agent
marqdo run tests/ext/agent-sandbox-optin.mq.md
marqdo run examples/agent-sandbox-okf/index.mq.md
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add agent # CDN latest → 1.4.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
### Added
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
### Fixed
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
## v1.4.1 — 2026-10-15
### Highlights
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
```bash
git checkout v1.4.1 && cargo build --release
marqdo view public/00-welcome.mq.md --no-open
marqdo view output public -o /tmp/mq-public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
### Added
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
### Fixed
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
## v1.4.0 — 2026-10-15
### Highlights
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 `![marqdo-out](…)`(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
```bash
git checkout v1.4.0 && cargo build --release
marqdo run tests/markup-v03/formula-meta-var.mq.md
marqdo run tests/markup-v03/foreach-narrative.mq.md
marqdo view tests/view/document-annot-demo.mq.md --no-open
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.0
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
### Added
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
- **图片自写回**:路径/URL 且扩展名合法 → `![marqdo-out](…)`;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
### Fixed
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
## v1.3.3 — 2026-10-15
### Highlights
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
```bash
git checkout v1.3.3 && cargo build --release
marqdo view tests/view/document-annot-demo.mq.md --no-open
marqdo view output public -o public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.3.3
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
### Added
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
### Fixed
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
## Ext pack v1.3.2 — 2026-10-13
### Highlights
**Trailing slash 路由修复(CLI 仍为 v1.3.0)**:Go `ServeMux` 精确匹配导致 `/post/foo/`(带尾部斜杠)落入 404。新增 `withStripTrailingSlash` 中间件作为最外层 handler wrapper,所有下游中间件(RBAC、Tenant、路由)均看到规范化路径。覆盖静态路由、动态路由、根路径、查询参数保留。
```bash
marqdo ext add web # CDN latest → 1.3.2
# 或:MARQDO_EXT_VERSION=1.3.2 marqdo ext add web
```
### Fixed
- **web**: `/post/foo/` trailing slash now routes the same as `/post/foo` (dynamic and static routes). Root `/` unchanged. Query strings preserved after normalization.
## Ext pack v1.3.1 — 2026-10-08
### Highlights
**OIDC 路径型 `redirect_uri`(CLI 仍为 v1.3.0)**:`redirect_uri=/oidc/callback` 按请求 Host / `X-Forwarded-*` 拼绝对回调,写入会话供 token 交换;可选 `redirect_origins` allowlist。apex / www 多域名无需写死单一绝对 URI。
```bash
marqdo ext add web # CDN latest → 1.3.1
# 或:MARQDO_EXT_VERSION=1.3.1 marqdo ext add web
```
### Added
- **路径型 redirect_uri**:绝对 URL 行为不变;路径模式解析 public origin,session 键 `oidc_redirect_uri`。
- **`redirect_origins` / `回调来源`**:逗号分隔 origin allowlist(路径模式)。
- **ABI**:`web_app_oidc` 透传 `redirect_origins`;`ext/security/oidc.attach` 文档同步。
### Changed
- 扩展包 SemVer **1.3.1**(`ext/VERSION`);与 CLI **v1.3.0** 可独立安装。
## v1.3.0 — 2026-09-28
### Highlights
**Engineering Knowledge Compiler(EKC)**:把仓库投影为 AI 可查询的工程知识系统——L0–L4 Catalog、Capability / Decision / Constraint / Failure、知识图、Reuse Preflight(REUSE→ADAPT→CREATE)与 Context Pack。本版 CLI 与扩展包 **同步为 1.3.0**。
- **杀手命令**:`marqdo reuse "task"` / `find` / `duplicate` / `impact` / `conflicts` / `stale` / `verify` / `knowledge`
- **Agent**:`agent.preflight` · `agent_eng_*`;`plan … eng_preflight=True` 在造轮子前强制 EFI
- **投影**:`.marqdo/catalog|knowledge|graph|agent/` + `engineering.yaml`;`catalog` 默认挂钩 EKC
- **示例 / 金样**:`examples/engineering-knowledge/` · `tests/engineering/` · `tests/ext/eng-preflight.mq.md`
```bash
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.3.0 && cargo build --release
marqdo knowledge . -o .marqdo
marqdo reuse "resolve configuration"
marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(知识编译器 + CLI + agent 插件),不触碰语言标记。
### Added
- **`src/knowledge/` EKC**:L0–L4 IR、指纹、能力推导、图边、compile、find/reuse/preflight、impact/lifecycle/duplicate、metrics、policy、learn。
- **CLI**:`knowledge` · `find` · `reuse` · `impact` · `conflicts` · `stale` · `duplicate` · `verify`;`catalog`/`sync` 默认编译 EKC(`--no-knowledge` 可关)。
- **Agent**:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`;`ext/ai` `## preflight` + `plan eng_preflight`。
- **规范**:`doc/design/engineering-knowledge.md`;提案叙事 `doc/next/008.md`(已实现标注)。
### Fixed
### Changed
- **OKF type 注册表**扩展 Capability/Decision/Constraint/Failure/Context Pack/Policy 等([okf.md](doc/design/okf.md))。
- **核心表面 Δ**:**无增删**。
## v1.2.0 — 2026-09-28
### Highlights
**Web Artifact 重写(ADR 0007)**:Document / Endpoint / Resource 一等公民;`type: web|endpoint`(ZH `类型: 网页|端点`);facade `web.page|route|serve|render|inspect|use`;DB/auth/ws 拆到 `ext/data` · `ext/security` · `ext/net`。本版 CLI 与扩展包 **同步为 1.2.0**。
- **Document**:文件级 Artifact + `data_source` / `data_order` / `data_where`;正文 Markdown → HTML;列表卡片 / 详情文章由 serve 时加载。
- **Endpoint**:`# main` 处理器;请求经 `run_artifact` Binding 注入;`response` 序列化 JSON/text/html。
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`;旧 web gold 移除,新金样 `ext_web_*`。
- **示例**:`examples/marqdo-blog/` Artifact 站(pages/api/db + smoke);`web-client-site` serve 扫描。
```bash
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.2.0 && cargo build --release
bash scripts/build-web-plugin.sh && marqdo ext add web
marqdo run examples/marqdo-blog/serve.mq.md
```
**核心表面 Δ(Core surface Δ)**:**无增删**——复用 Metadata `type`;装配语义在 ext + plugin。语言标记不变。
### Added
- **Web Artifact 模型(ADR 0007)**:`type: web|endpoint`(ZH `类型: 网页|端点`);核心 `src/artifact/`;`sys.artifact_kind`;无 `# main` 时 Result 摘要。
- **`ext/web` facade**:`page` · `route` · `serve` · `render` · `inspect` · `use`;子模块 page/route/dom/client/component。
- **`ext/data` · `ext/security` · `ext/net`**:从 monolithic web 拆出 Resource。
- **统一 View** `|type|slot|value|attrs|style|` + ABI `web_render_nodes` / `web_serve_root` / `web_inspect` / `web_app_use`。
- **规则**:`.cursor/rules/web-artifact-no-degrade.mdc`;设计 `doc/design/ext-web-artifact.md`。
### Fixed
- Document `data_source` / `data_where` now drive list cards and detail articles under `web.serve` (ADR 0007 flat metadata).
### Changed
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`。旧 web gold 已移除;新金样 `web-artifact-*` / `ext_web_*`。
- **核心表面 Δ**:**无增删**(复用 Metadata `type`)。
- 修订 `ext-web.md` C1;`doc/next/007.md` superseded。
## v1.1.1 — 2026-09-24
### Highlights
**AI 栈收口(agent + llm)**:语义 `ask`/`stream`/`collect`、Artifact Metadata Binding、Skill Compilation + Adaptive Routing、MCP 客户端与 resume 检查点、可选 `plugins/llm` Transport ABI。
本版 CLI 与扩展包 **同步为 1.1.1**。
- **LLM 原语**:`ext/ai/llm` 从 OpenAI HTTP 客户端提升为 `ask`/`stream`/`collect` 智能原语(`complete` 保留兼容);`LLMResult.tool_calls`;可选原生 `llm_chat_completions`(无 `.so` 时回退 `lib/net`)。
- **Metadata Binding**:frontmatter `${env|arg|sys|secret}` 加载期解析;Phase 2 将绑定键注入入口 env(正文禁止 `${…}`);`sys.meta` / `--bind`;llm ctor 优先 meta。
- **Agent**:Skill Compilation(episode → llm_free skills)+ Adaptive Routing(`marqdo` / `small-llm` / `llm` / `auto`;`jev` 为 `small-llm` 兼容别名);MCP **stdio 客户端**;resume 检查点;零 LLM 金样路径。
- **度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.1 && cargo build --release
marqdo ext add llm && marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime**(Metadata Binding、LLM/agent 插件与扩展)变更,不触碰语言标记。
### Added
- **`ext/ai/llm` 语义表面**:`ask` / `stream` / `collect`(`complete` 兼容);`LLMResult.tool_calls`(OpenAI-shaped `choices[0].message.tool_calls`);`sys.module_source` + 入口文档 `prompt_body` 离线路径。
- **`plugins/llm` Transport ABI**(`llm_chat_completions`):`ext/ai/llm/openai` 优先原生插件,否则 `lib/net` HTTP/SSE。
- **Artifact Metadata Binding**:frontmatter `${env|arg|sys|secret}` → `Module.metadata`;Secret 掩码;`sys.meta` / `--bind`;Phase 2 入口 env 注入(正文拒绝 `${…}`;字节码 prologue 同源)。
- **Agent Skill Compilation + Adaptive Routing**:episode → `maybe_learn` → llm_free skills;路由后端 `marqdo` / `small-llm` / `llm` / `auto`(`jev` = `small-llm` 兼容别名,不再探测 `MARQDO_JEV`)。
- **Agent MCP stdio 客户端**(`agent_mcp_client` / `mcp_connect` / `mcp_client_list` / `mcp_client_call`)+ Python mock 离线金样。
- **Agent resume 检查点**(`.marqdo/agent-resume/<id>.json` — save/load/clear/list;`run` 可设 `resume_id=`)。
- **AI 栈度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流、agent-zero-llm 金样。
### Fixed
- **plan force 不再冲掉已有 `resources` workbook**(保留 llm_free 资源;金样 `agent-plan-preserve`)。
- **compiled-skill Marqdo 语法**:llm_free await 不再误落到 plan+HTTP。
### Changed
- Adaptive Routing:决策面为 `router_model`(任意 llm handle);`jev` 降为 `small-llm` 文档/兼容别名。
## v1.1.0 — 2026-09-23
### Highlights
**AI 原生闭环三件套落地**:核心表面守卫(问题一)· 渐进式契约(问题二)· MLSP for AI(问题三)。
`marqdo check` 静态契约防漂移、`marqdo mlsp` 让 AI **按需查询**语法而非背诵、`run --json` 统一结构化诊断(错误即数据,供 AI 直接消费)。
本版 CLI 与扩展包 **同步为 1.1.0**。
- **核心要小(问题一)**:`doc/design/core-surface.md` 列出 19 个核心构造 + `CORE_CONSTRUCTS` 守卫测试——任一侧(清单/文档/金样)单边改动 CI 必红;三层架构(Core / Runtime / Document)入 `doc/design/layers.md`。
- **语义校验(问题二)**:渐进式契约表(`参数`/`返回`/`字段`/集合)嵌入文档叙述;四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);`marqdo check` 静态防漂移(类型 typo / 参数名漂移 / 重复契约必报)。
- **AI 可靠反馈 + 不必学语法(问题三)**:`marqdo mlsp`(MLSP,行分隔 JSON over stdio)提供 `locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片机械携带戒律原文 / 样例 / 文档锚点,AI 无需预学语法。修复护栏:有界行编辑、越界必拒(abstain)。
- **验证(P4)**:锚点消融 anchor 一轮修复率 **100%**(双模型,plain 85%/90%);契约消融拦截 100% / 误报 0%;防漂移必报 9/9;核心守卫演练 3/3 必红。详见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造(`heading` / `bold-code` / `italic-return` / `param-list` / `call-quote` / `branch-list` / `loop-list` / `table-bind` / `footnote-index` / `link-index` / …)与 v1.0.7 完全一致,未新增标记。本版为 **Runtime 层(契约校验 / MLSP / 诊断 JSON)** 与 **Document 层(core-surface / layers)** 变更,不触碰语言核心。
### Added
- **MLSP(`marqdo mlsp`)**:面向 AI 的语言服务协议(行分隔 JSON over stdio)——`locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片含 `semantics` / `rule` / `sample` / `doc_quote`(自持,机器可读戒律原文)。
- **`marqdo check`**:静态契约漂移检查(未知类型词 / 参数名漂移 / 返回越约 / 重复契约表 / 错位契约表)。
- **渐进式契约(Progressive contracts)**:文档叙述内嵌契约表(`参数`/`返回`/`字段` + 集合 `字段`),四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);被绑定的 `字段|类型` 表是**数据**、永不误判为契约。
- **`marqdo run --json`**:统一结构化诊断(`code` / `severity` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`),错误即数据。
- **修复护栏**:`mlsp repair_apply` 有界行编辑——只允许落在 `doc_anchor` 指定范围内的编辑,越界整体拒绝(all-or-nothing / abstain)。
- **守卫与文档**:`doc/design/core-surface.md`(19 构造)、`doc/design/layers.md`(三层架构)、`tests/core_surface.rs`(守卫生效验证)。
### Fixed
- **错误链不再扁平化**:`src/load.rs` 以 `label_error` 保留结构化 `Diagnostic`("Error Exit Only" 原则),修复契约类错误被降级为字符串的回归。
- **契约 parse 边界**:`interp.rs` 键访问优先给出 `index_diag`(索引/键诊断先于取值),空字段 vs 缺字段语义消歧。
### Changed
- **`.cursor/skills/marqdo`**:由「背诵式压缩操作手册」改为**查询式工作流**——写码前 `mlsp syntax` / `locate`,提交前 `mlsp validate` + `marqdo check`,修复照 `doc_anchor` 局部改。
- **契约表一经出现即为完整声明**(新推断的升参未覆盖 ⇒ `contract.param_drift` 警告,不静默)。
- 取元**主推** `[键](集合)`(`link-index`);`` `集合`[^键] ``(`footnote-index`)保留兼容。
### 已知未决(诚实标注)
- **P4 实验 (b) 盲测未达标**:「查询式 vs 全文档背诵」四判据未全立(`deepseek-flash`:docs 4/6 vs query 0/3;端点 infra 削样本)。查询机制本身已验证无缺陷,瓶颈在**模型自查纪律**(不知道自己不知道 ⇒ 不查询)——协议改进(写码前强制自检 / 陌生构造强制查询)列入下一阶段。见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md) §3。
## Unreleased
## v1.0.7 — 2026-09-22
### Highlights
**WS / 网络边界加固**:WebSocket 握手同源校验、broadcast/room 默认需登录(`require_auth`/`需要登录` 可显式关闭)、消息 1 MiB × 256 条上限、空 room 回收;HTTP 响应 8 MiB 在读流时截断;`url_encode` 空格 `%20`。本版 CLI 与扩展包 **同步为 1.0.7**。
- **安全默认**:浏览器 WS 握手仅同源;有状态 fan-out 端点未登录 401 / 公开直播流显式 `require_auth=False`
- **资源上限**:WS 单条 1 MiB、单连接 256 条;HTTP/SSE 8 MiB 读流截断——对端无法借大响应耗尽内存
- **测试**:P3 金样对齐 quiet-admin 门禁语义;wasm smoke 以 ESM 加载官方 bridge
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.0.7 && cargo build --release
marqdo ext add web
```
### Fixed
- **WS 安全默认**:握手改为同源校验(不再放行任意 Origin);`route_ws` 新增 `require_auth`/`需要登录`,broadcast/room 默认要求登录会话,公开直播流需显式设假,未认证握手 401。
- **WS 资源上限**:单条消息 1 MiB、单连接最多收集 256 条回复;传输错误/超时返回 `{ok:false, error}`,不再伪装空成功;空 room 自动回收(防 URL 派生 room 名耗尽内存)。
- **HTTP 响应上限**:8 MiB 上限在读流时截断(含错误路径与 SSE 错误路径),上游无法借超大响应耗尽内存。
### Changed
- `net.url_encode`:空格编码为 `%20`(原 `+`),URL 段语义下与字面 `+` 消歧义。
- `web`/`网页` 文档同步:`route_ws` 的 `require_auth`/`需要登录` 与 `ws.connect` 的收集上限语义。
## Unreleased
### Added
Generated
+24 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.0.3"
version = "2.1.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -601,9 +601,16 @@ dependencies = [
"zip",
]
[[package]]
name = "marqdo-plugin-sdk"
version = "2.0.0"
dependencies = [
"serde_json",
]
[[package]]
name = "marqdo-wasm"
version = "1.0.3"
version = "2.1.0"
dependencies = [
"marqdo",
"serde_json",
@@ -614,6 +621,7 @@ name = "marqdo_plugin_agent"
version = "0.1.0"
dependencies = [
"chrono",
"marqdo-plugin-sdk",
"serde_json",
]
@@ -621,6 +629,7 @@ dependencies = [
name = "marqdo_plugin_demo"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde_json",
]
@@ -628,14 +637,27 @@ dependencies = [
name = "marqdo_plugin_linalg"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
[[package]]
name = "marqdo_plugin_llm"
version = "0.1.0"
dependencies = [
"idna_adapter",
"marqdo-plugin-sdk",
"serde_json",
"ureq",
"zeroize",
]
[[package]]
name = "marqdo_plugin_quantum"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
+6 -4
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.0.3"
version = "2.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,7 +19,7 @@ cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
exec-host = ["dep:libc"]
fs-host = []
tty = ["dep:libc"]
wasm-core = []
@@ -58,12 +58,14 @@ getrandom = { version = "=0.2.17", default-features = false, features = ["custom
members = [
"plugins/demo",
"plugins/agent",
"plugins/llm",
"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]
+228 -24
View File
@@ -1,12 +1,134 @@
# Marqdo
# Marqdo
**代码即文档。文档即代码。文档即知识库。**
**代码即文档。文档即知识库。知识即可执行。**
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。**
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
```text
.mq.md(同一份文件)
┌─────────┼─────────┐
文稿 知识 程序
└─────────┼─────────┘
▼
Marqdo 运行时
▼
可执行知识(Executable Knowledge)
```
| 真正的核心优势 | 说明 |
|------|------|
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
---
## 链接语法:链接即调用(v2.1 设计声明)
> **这是 v2.1 的可执行知识模型。**
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
### 两文档,一次类调用
知识文档 `libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
*701*
```
- `# 李白` = 类;
- `## 李白的出生年份` = 函数;
- `*701*` = 返回值。
调用文档 `main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
要终端输出,就把同一段代码放进代码链接并加 `print`:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 四条语义
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
### 现状与目标
| 能力 | v2.0.0 | v2.1 |
|------|-------------|-----------|
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
| `links.lock` 可复现 | ❌ | ✅ 可选 |
### 知识分层:本体 → 知识个体 → 调用面
| 层 | 写法 | 语义 |
|----|------|------|
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
---
## 愿景与期许
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
---
@@ -23,24 +145,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.3)
## 语法速览
| 标记 | 含义 |
|------|------|
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合;取元优先 `[键](集合)` |
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
```markdown
# main
@@ -58,6 +186,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
---
@@ -68,7 +198,53 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
2. **返回是架构;打印只是函数。**
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
---
## 工程习惯:允许申报未完成,但不允许假装完成
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
而欠账是可见、可数、可结算的(而不是假装完成):
```markdown
## 检索资料
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表(当前未接) |
[按关键词检索,接口未接,待开发](None)
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
**四条约定**
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
**盘点与门禁**
```bash
marqdo labels --count # 内置口径:还有多少未完成
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
```
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
---
@@ -79,6 +255,13 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
marqdo knowledge [PATH] -o OUT_DIR
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo duplicate [--fail]
marqdo verify
```
| 参数 | 默认 | 说明 |
@@ -86,7 +269,7 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
| `-o` / `--out` | `.marqdo` | 输出目录 |
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。产物示例:`catalog.yaml`、`engineering.yaml`、`catalog/capabilities/`、`graph/graph.json`。设计见 [engineering-knowledge.md](doc/design/engineering-knowledge.md) · [catalog-cli.md](doc/design/catalog-cli.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
@@ -98,29 +281,45 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.0.3)
## 现状(v2.1.0)
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock) · 扩展包同步 **2.1.0**
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `![marqdo-out](…)` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));**表驱动引言**(`compose_intro` / `引言装配`);原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [web-site](examples/web-site/) · [web-site-zh](examples/web-site-zh/) · [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **Streamable HTTP**)+ Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`(`web` 为 Go;其余为 Rust)
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- **浏览器 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.0.3)
### 如何使用最新 Marqdo(v2.1.0)
**安装解释器(任选其一)**
@@ -135,7 +334,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.0.3 # 或留在 main
git checkout v2.1.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -148,19 +347,24 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
# 4) 动态站示例(扩展装好后)
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
marqdo run examples/marqdo-blog/index.mq.md
marqdo run examples/marqdo-blog/serve.mq.md
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
@@ -169,7 +373,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.0.3
# https://github.com/cflmy/marqdo/releases/tag/v2.1.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+7
View File
@@ -0,0 +1,7 @@
[package]
name = "marqdo-plugin-sdk"
version = "2.0.0"
edition = "2021"
[dependencies]
serde_json = "1"
+195
View File
@@ -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) ),* ])
}
};
}
+2 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.0.3"
version = "2.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
[dependencies]
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
serde_json = "1"
serde_json = "1"
+5
View File
@@ -0,0 +1,5 @@
{
"name": "marqdo-bridge",
"private": true,
"type": "module"
}
+144
View File
@@ -1,3 +1,147 @@
marqdo (2.1.0-1ppa1) noble; urgency=medium
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
standard/extension libraries and executable-knowledge projections.
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
marqdo (2.0.0-1ppa1) noble; urgency=medium
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
bracketed label is inert prose and the parenthesized payload is the
only executed part. Adds paren-call arguments, access() element
access, occlusion loops, marqdo labels (two-tier search + debt
ratchet), marqdo migrate labels, and label.missing / empty_payload /
ref_dangling diagnostics; view renders labels as prose, payloads as
code, stubs with a badge. 80 corpus files migrated.
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
marqdo (1.5.2-1ppa1) noble; urgency=medium
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
interrupt, plan generation/add/remove/value API, snapshot
export/import/replay, view capture for static export, explicit Persist
button, nested plan boundary.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
marqdo (1.5.1-1ppa1) noble; urgency=medium
* Marqdo 1.5.1: View static/live execution path unified; foreign value
passing into multi-kernel sessions; cell stdin for live/static/persistent
kernels; build-time execution with stdout injection in static exports;
runnable foreign writeback example; writeback block grouping.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
marqdo (1.5.0-1ppa1) noble; urgency=medium
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
parallel fan-out, persistent Python/Node kernels, explicit state
bridge) and document-native notebooks in view; high-contrast
light/dark view themes, resizable code/output panes, OKF/EKC and
Python examples on the user site. Fixes branch-local variables
leaking into required constructor parameters.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
marqdo (1.4.6-1ppa1) noble; urgency=medium
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
The first bold assignment LHS is a declaration (design §8.2); a missing
argument reports missing argument for parameter, not undefined variable.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
marqdo (1.4.5-1ppa1) noble; urgency=medium
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
field access via json.get (no footnote hard-fail).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
marqdo (1.4.4-1ppa1) noble; urgency=medium
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
ext/ai table-first refactor (no json.set glue).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
marqdo (1.4.2-1ppa1) noble; urgency=medium
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
marqdo (1.4.1-1ppa1) noble; urgency=medium
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
to chip top-center), unify frame chip ids, L-to-R chip density.
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
marqdo (1.4.0-1ppa1) noble; urgency=medium
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
arm/loop narrative + foreach sugar, image writeback ![marqdo-out](...),
view inferred-param values; welcome pages on v0.3 prose surface.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
marqdo (1.3.3-1ppa1) noble; urgency=medium
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
view output / gh-pages share the same render path as live view.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
marqdo (1.3.0-1ppa1) noble; urgency=medium
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
marqdo knowledge/find/reuse/duplicate/verify, Agent preflight
(REUSE→ADAPT→CREATE), graph + context packs.
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 16:50:00 +0800
marqdo (1.2.0-1ppa1) noble; urgency=medium
* Marqdo 1.2.0: Web Artifact rewrite (ADR 0007) — Document/Endpoint/Resource,
type:web|endpoint, web.serve/render/inspect, ext/data|security|net split,
compose_* author surface removed; marqdo-blog Artifact example.
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 11:39:04 +0800
marqdo (1.1.1-1ppa1) noble; urgency=medium
* Marqdo 1.1.1: AI stack closure — llm ask/stream/collect, Metadata Binding,
Skill Compilation + Adaptive Routing, MCP stdio client + resume checkpoints,
optional plugins/llm Transport ABI (fallback lib/net).
-- cflmy <pingan@cflmy.cn> Thu, 24 Sep 2026 20:32:00 +0800
marqdo (1.1.0-1ppa1) noble; urgency=medium
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
`run --json` unified structured diagnostics; contract tables
(参数/返回/字段/集合) with four validation boundaries; anchored repair
guardrails (bounded line edits, out-of-scope refused).
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
marqdo (1.0.7-1ppa1) noble; urgency=medium
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
require_auth/需要登录, message caps, empty-room GC); HTTP 8 MiB cap
enforced while reading; url_encode space -> %20.
-- cflmy <pingan@cflmy.cn> Tue, 22 Sep 2026 15:40:00 +0800
marqdo (1.0.3-1ppa2) noble; urgency=medium
* Fix Launchpad build: dh_clean -Xvendor/ so cargo vendor checksums keep
+32 -2
View File
@@ -13,6 +13,8 @@
## 当前文档
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
@@ -25,6 +27,7 @@
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
| [design/engineering-knowledge.md](design/engineering-knowledge.md) | **Engineering Knowledge Compiler(EKC)**:L0–L4、reuse、EFI |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
@@ -47,7 +50,13 @@
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
@@ -89,10 +98,31 @@
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
+42
View File
@@ -0,0 +1,42 @@
# ADR 0006:Artifact Metadata Binding(`${…}` 进核心 · Metadata-only)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-24 |
| Related | [binding.md](../design/binding.md) · [core-surface.md](../design/core-surface.md) · [layers.md](../design/layers.md) · [doc/next/006.md](../next/006.md) |
## Context
- Executable Document 需要声明「依赖哪些外部运行时资源」(模型名、API 密钥、base URL),而不是在 `ext/*` 里各自 `sys.env_get`。
- [doc/next/006.md](../next/006.md) 提出 **Marqdo Binding**(`${namespace.name}`)与 Artifact Metadata 统一解析。
- [layers.md](../design/layers.md):Language 层变更须 ADR;核心构造计数只许持平或下降;默认进 ext。
- 正文插值会与 `$$…$$` 公式面冲突,且会新增内联构造压力。
## Decision
1. 采纳 **Artifact Metadata Binding** 为 Language 层能力;正式规范见 [binding.md](../design/binding.md)。
2. **`${…}` 仅**在文件头 `---` Metadata 中生效;正文 / 粗体 / 调用 / 表 / 叙述 **永不**写 Binding Expression(否决 [006 §17](../next/006.md))。
3. **不**把 Binding 记入 [core-surface.md](../design/core-surface.md) 的 19 构造守卫表——与 `import` 同属 §4「其它语言面」。
4. 核心只做声明与解析;扩展(如 `ext/ai/llm`)消费已绑定的 `Module.metadata` / `sys.meta*` / 入口提升变量。
5. 第一版 namespace:`env` · `arg` · `sys` · `secret`。`config` / `file` 推迟。
6. 加载期一次 resolve → Bound Artifact;`Value::Secret` 遮掩展示;`sys.env_get` 保留为逃逸口。
7. **Phase 2**:入口执行前把 metadata 键提升为普通变量(形参/赋值可覆盖);正文用 `` `model` ``,不再 `${env…}`。
## Consequences
### Positive
- 配置成为文档的一部分;LLM / agent / 其它 ext 共用同一套 Binding,避免各写一套 getenv。
- 缺失 `!` 在加载期失败,而不是运行到 HTTP 401。
- 不膨胀 CORE_CONSTRUCTS;与公式 `$$` 无冲突。
- 正文保持普通变量语义,不引入第二套环境变量语法。
### Negative / Risks
- Secret 在 `Text + Secret` 拼接时会揭示明文(供 Authorization);须约束日志面。
- metadata 键与业务变量同名时依赖「形参/赋值覆盖」规则,作者需注意命名。
### Neutral
- `#` / `##` / `**` / `*` 等核心标记不变;frontmatter `import` 句法不变。
+54
View File
@@ -0,0 +1,54 @@
# ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-28 |
| Related | [ext-web-artifact.md](../design/ext-web-artifact.md) · [ext-web.md](../design/ext-web.md) · [binding.md](../design/binding.md) · ADR [0006](0006-artifact-metadata-binding.md) · [layers.md](../design/layers.md) · [doc/next/007.md](../next/007.md) |
## Context
- [`ext/web/web.mq.md`](../../ext/web/web.mq.md) 已膨胀为小型 Web Framework(Page God Object、`configure` 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。
- [doc/next/007.md](../next/007.md) 提出 Document / Endpoint / Resource 三原语与拆分 `ext/web` · `ext/net` · `ext/data` · `ext/security`。
- 现行 [ext-web.md](../design/ext-web.md) **C1** 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata `type`,**不**新增 CORE_CONSTRUCTS 标记)。
- Binding(ADR 0006)已提供文件级 Metadata;`type: prompt` 先例在扩展侧消费 metadata。
## Decision
1. **采纳** Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
2. **修订 ext-web C1**:允许核心在装载期识别 `type: web|endpoint`(及中文 `类型: 网页|端点`)并暴露 artifact 分类;**装配 / HTTP / DB 语义仍在 ext + plugin**。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。
3. **文件级 Artifact only**:不在 `##` 函数体嵌套 `---` frontmatter(与 Binding Phase 1 / 解析器一致)。
4. **破坏性重写作者面**:删除 `compose_*` 碎片 DSL、god `# page` 变异堆、`app.configure` 多参数抽屉、作者 `ensure_plugin`;examples 与 `tests/ext/web*` 同步重写。
5. **目录定稿**(007 §三十五 + §四十):
- `ext/web/` — page · route · component · dom · client · facade
- `ext/net/` — http · websocket · url
- `ext/data/` — db · cache · storage
- `ext/security/` — auth · oidc · rbac
6. **统一 View 表**:`| type | slot | value | attrs | style |`;Table = Data,禁止每函数私有方言。
7. **declared vs system routes**:用户 route 须声明;`/_part` · `/_form` 等为 system,经 `web.inspect` 可见。
8. **import = capability**:`import web:…` 由 facade 自动加载 native plugin;作者程序不写 `ensure_plugin` / `host_*`。
9. **Metadata v1 锁定(原 007 未决项)**:
- 发现:`web.serve root=` 扫描 `root/**/*.mq.md`,仅注册 `type`/`类型` ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。
- Data:仅 flat 键 `data_source` · `data_order` · `data_where`(text;where 为 `col=val` 逗号分隔)。嵌套 YAML `data:` 推迟。
- Result:`{ok: bool, value: any, error: text|None}`。
- Realtime 模块名:`ext/net/websocket.mq.md`(ZH:`实时.mq.md`)。
- ZH metadata:`类型`←type,`路由`←route,`方法`←method,`路径`←path,`请求`←request,`响应`←response,`鉴权`←auth,`数据源`←data_source,`排序`←data_order,`条件`←data_where。
## Consequences
### Positive
- `.mq.md` 同时是文档、路由、实现与鉴权声明。
- 与 LLM/Agent Artifact Metadata 统一心智。
- 职责边界清晰,可独立演化 data/security/net。
### Negative / Risks
- 破坏性:全部现有 web 作者程序与 smokes 必须改写。
- Endpoint 热路径仍经 plugin → `CallLibPath` / 文件装载回调;须保持 ABI 稳定演进。
- flat data 键表达力弱于嵌套 YAML;后续另 ADR。
### Neutral
- 不新增 Markdown 核心标记;`${…}` 仍仅 Metadata。
- Go `plugins/web` 可分波删除死 compose ABI;作者面先断。
+250
View File
@@ -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 的所有验证结论。
+187
View File
@@ -0,0 +1,187 @@
# Marqdo Binding · Artifact Metadata
| | |
|---|---|
| 状态 | **Accepted · Phase 1 + Phase 2(scope lift)** |
| 日期 | 2026-09-24 |
| ADR | [0006-artifact-metadata-binding.md](../adr/0006-artifact-metadata-binding.md) |
| 讨论稿 | [doc/next/006.md](../next/006.md) |
| 实现 | `src/binding/` · `Module.metadata` · entry env lift · `sys.meta` / `sys.meta_get` · `marqdo run --bind` |
> **边界**:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
> **`${…}` 只出现在文件头 Artifact Metadata**——正文 / 粗体 / 调用 / 表 **永不**写 `${env…}`(否决讨论稿 §17)。正文使用已绑定的普通名字。
---
## 1. Artifact Metadata
文件开头成对 `---` 之间为 **Artifact Metadata**(声明式元信息环境),不是「随便贴的 YAML」。
```text
.mq.md
├── Metadata ← Identity / Configuration / Dependencies / Bindings
└── Executable Body
```
- `import bind:…` / `导入` 行:模块依赖(既有语义不变)。
- 其它 `key: value` 行:元信息;值可为字面量或 **Binding Expression**。
- Phase 1 仅支持 **flat** 键(同级 `key: value`);块标量 `>` / `|` 收成 Text。
例:
```yaml
---
title: demo
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import:
sys: lib/sys.mq.md
---
```
加载后内部为已绑定的 `Module.metadata`(确定性快照),执行期不再对同一键反复 `getenv`。
---
## 2. Binding Expression
外形:
```text
${expression}
```
### 2.1 路径
```text
${namespace.name}
```
| Namespace | 意义 | Phase 1 |
|-----------|------|---------|
| `env` | 进程环境变量 | ✅ |
| `arg` | CLI / Runtime 绑定(`marqdo run --bind KEY=VALUE`) | ✅ |
| `sys` | 系统信息:`cwd` · `platform` | ✅ |
| `secret` | 敏感环境变量 → `Value::Secret` | ✅ |
| `config` | 配置 Artifact | 推迟 |
| `file` | 外部文件内容 | 推迟 |
### 2.2 默认与必需
```text
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
${secret.OPENAI_API_KEY!}
```
- `A ?? B`:A 缺失(未设置 / 空)则用 B。
- `A!`:A 必须存在,否则加载失败(`config.required_binding_missing`)。
### 2.3 类型转换
```text
${int(env.MAX_TOKENS ?? "4096")}
${float(env.TEMPERATURE ?? "0.2")}
${bool(env.STREAM ?? "false")}
```
### 2.4 独占 value vs 插值
| 形态 | 语义 |
|------|------|
| `model: ${env.OPENAI_MODEL}` | **Value binding** — 保留解析后的类型(含 Secret) |
| `title: "Hello ${env.USER}"` | **Interpolation** — 结果为 Text |
| `model: gpt-4o-mini` | **Literal** — 字面量;**不会**被环境变量静默覆盖 |
---
## 3. Resolution Policy
对每个 metadata 键:
1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
2. 若 CLI 提供了同名 `--bind KEY=VALUE`,**覆盖**该键的最终值(Text)。
3. Binding 内部查找顺序(仅当表达式写出时):`arg` / `env` / `secret` / `sys` 按表达式 namespace;`??` 链从左到右。
推荐作者意图:
```text
CLI --bind
→ Artifact 字面量 / 已写死的 Binding 结果
→ Binding 源(env / secret / …)
→ ?? 默认
```
---
## 4. Secret
`${secret.NAME}` → `Value::Secret`。
- `print` / `str` / Display → `<secret>`(不泄露)。
- `type` → `secret`。
- 与 Text 拼接(如 `bearer + api_key`)时**揭示**明文,供 HTTP Authorization。
- 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
---
## 5. Runtime API
| API | 语义 |
|-----|------|
| `sys.meta` / `系统.元信息` | 入口模块已绑定 metadata(map) |
| `sys.meta_get` / `系统.取元信息` | `key=` → 值或 `None` |
| `marqdo run FILE --bind KEY=VALUE` | 可重复;写入 `arg` 并覆盖同名 metadata 键 |
| `sys.env_get` | **保留**逃逸口;新代码优先 Metadata Binding |
---
## 6. 错误
| code | 何时 |
|------|------|
| `config.required_binding_missing` | `${ns.name!}` 且源缺失 |
| `config.unknown_binding_ns` | 未知 namespace |
| `config.bad_binding` | 表达式非法 / cast 失败 |
诊断尽量带 frontmatter 行号。
---
## 7. 与扩展的分工
- **核心**:解析 Metadata、resolve Binding、暴露 `Module.metadata` / `sys.meta*`,并在入口把 metadata **提升为普通变量**。
- **`ext/ai/llm`**:构造次序为 **显式实参 → 入口作用域同名变量 / `sys.meta_get` → `sys.env_get` 回退 → 默认**。
---
## 8. Phase 2 · Metadata scope lift(Accepted)
加载期绑定完成后,入口执行(`# main` 或唯一无参顶层对象)前,把 `Module.metadata` 的每个键注入 entry 环境,成为**普通变量**:
```yaml
---
model: ${env.ModelName ?? "gpt-4o-mini"}
---
```
```marqdo
# main
> print text=`model`
```
### 规则
1. 注入时机:进入入口函数之前。
2. 冲突:形参 / 调用实参 **覆盖** 同名 metadata;程序内赋值亦然。metadata **不**覆盖已存在的绑定。
3. `sys.meta` / `sys.meta_get` 仍可用(显式通道)。
4. **拒绝** 正文 / 粗体 / 表 / 叙述中的 `${…}`(讨论稿 006 §17 否决)。普通语言也不在语句里 `${ENV}`。
### 仍推迟(P3+)
- `config` / `file` namespace
- 嵌套 YAML map
- 显式 `override:` 糖
- 计入 `CORE_CONSTRUCTS`
+300
View File
@@ -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](图片路径)
```
- `[]` 里是**指令/说明**(`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. 我的评定
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
| 维度 | 评分 | 说明 |
|------|------|------|
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`![alt](src)` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
让短形成为"读得懂但不必写"的兼容层。这样:
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
- 506 处零迁移
- 调用终于有家,且成本为零
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
---
## 9. 待你决策
1. **路线一(双层)还是路线二(纯度)?**
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
5. 循环的新写法你倾向哪一种:
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
- `- [篮子里的果子](篮子 → 果)`
- 保留 `- [果](篮子)` 作短形
+2 -1
View File
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
+287
View File
@@ -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 回归 → 写变更文档。
+5
View File
@@ -23,15 +23,20 @@ YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配
marqdo catalog [PATH] -o OUT_DIR
# 别名(与早期草案一致)
marqdo sync [PATH] -o OUT_DIR
# 跳过 Engineering Knowledge 投影(仅旧式 catalog)
marqdo catalog [PATH] -o OUT_DIR --no-knowledge
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
| `--no-knowledge` | off | 不跑 EKC;默认在 catalog 成功后编译 L0–L4 / graph |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
Engineering Knowledge 命令见 [engineering-knowledge.md](engineering-knowledge.md)(`find` / `reuse` / `duplicate` / …)。
---
## 3. 生成物
+231
View File
@@ -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** |
+99
View File
@@ -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` | 本文件 |
+134
View File
@@ -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` | 本文件 |
+126
View File
@@ -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` | 本文件 |
+89
View File
@@ -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` | 本文件 |
+84
View File
@@ -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` | 本文件 |
+103
View File
@@ -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` | 本文件 |
+109
View File
@@ -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` | 本文件 |
+127
View File
@@ -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` | 本文件 |
+81
View File
@@ -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` | 本文件 |
+89
View File
@@ -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` | 本文件 |
+113
View File
@@ -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` | 本文件 |
+103
View File
@@ -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` | 本文件 |
+103
View File
@@ -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` 引擎),
而不是继续在特性内部找"重复"——那已经找完了。
+47
View File
@@ -0,0 +1,47 @@
# 核心表面清单(core-surface)
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
## 2. 内联标记
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
## 4. 范围外(进 Language 层,但不在本守卫)
frontmatter / Artifact Metadata(元信息)、`import` 行(模块装载)、以及 Metadata 内的 **Binding Expression**(`${ns.name}`,见 [binding.md](binding.md) · [ADR 0006](../adr/0006-artifact-metadata-binding.md))属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,**暂不进本清单守卫**(不增 CORE_CONSTRUCTS 计数)。Phase 2 将已绑定 metadata **提升为入口普通变量**(仍非新标记)。如需一并守卫,走 ADR 扩表。
+1 -1
View File
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
+97
View File
@@ -0,0 +1,97 @@
# Engineering Knowledge Compiler(EKC)
| | |
|---|---|
| 状态 | **Accepted(v1 已落地)** |
| 日期 | 2026-09-28 |
| 提案 | [next/008.md](../next/008.md) |
| 相关 | [okf.md](okf.md) · [catalog-cli.md](catalog-cli.md) · [ext-agent.md](ext-agent.md) |
## 1. 定位
Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识系统。Source of Truth 仍是 `*.mq.md`;`.marqdo/**` 是 GENERATED 投影。
```text
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
│
▼
Agent preflight (REUSE → ADAPT → CREATE)
```
**Engineering First Information (EFI)**:生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
## 2. 五层 Catalog
| 层 | 内容 | 落盘 |
|----|------|------|
| L0 Repository | 语言/规模 | `.marqdo/catalog/repository.mq.md` |
| L1 Module | imports/exports/responsibility | `.marqdo/catalog/modules/` |
| L2 Symbol | signature/calls/fingerprint | `.marqdo/catalog/symbols/` |
| L3 Capability | 工程能做什么 | `.marqdo/catalog/capabilities/` |
| L4 Knowledge | Decision/Constraint/Failure/… | `.marqdo/knowledge/{decisions,constraints,…}/` |
既有 `marqdo catalog` 根级 `catalog.yaml` / `index.md` / `modules/` / `concepts/` **保留**;`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。
## 3. 知识类型(OKF `type`)
| type | 含义 |
|------|------|
| `Capability` / `Function` | 能力与符号投影 |
| `Decision` | 为什么这样做 |
| `Constraint` | 必须/禁止 |
| `Failure` / `AntiPattern` | 负面知识 |
| `Pattern` / `Migration` / `Fact` | 模式、迁移、事实 |
| `Marqdo Context Pack` | Agent 上下文制品 |
| `Marqdo Policy` | 复用决议编译结果 |
| `Marqdo Engineering Knowledge` | 总览 / `engineering.yaml` |
未知 type 优雅降级(可读,不专属逻辑)。
## 4. 图边
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
## 5. CLI
```bash
marqdo knowledge [PATH] -o .marqdo # compile(默认)
marqdo knowledge preflight "task"
marqdo knowledge record REUSE
marqdo knowledge learn --task ... --failure ...
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo impact path/to/file.mq.md
marqdo conflicts | stale | duplicate [--fail] | verify
```
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
## 6. Reuse 协议
三态:**REUSE → ADAPT → CREATE**(硬顺序)。Reuse budget:`min_candidates` / `allow_create_after`。仅 `create_allowed: true` 时允许盲生成。
## 7. Context Pack
`.marqdo/agent/contexts/task-<id>.mq.md`:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
## 8. Agent
- Plugin:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`
- Facade:`agent.preflight` · `agent.eng_reuse` · `agent.eng_record`
- `agent.plan … eng_preflight=True` 在 agent-kb 之前跑 EFI;缺知识图时 `missing_knowledge` 放行(兼容纯 agent-kb 测试)
## 9. 指标
`.marqdo/agent/episodes/reuse_metrics.json`:`reuse_ratio` / `adapt_ratio` / `novel_ratio` / `duplication_rate`。
## 10. 原则(五条)
1. Discover before Create
2. Reuse before Adapt
3. Adapt before Duplicate
4. Verify before Promote
5. Code changes update knowledge
**不做**:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。
+206
View File
@@ -0,0 +1,206 @@
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
| | |
|---|---|
| 状态 | **Design Draft · v2.1 语义重构** |
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
---
## 0. 一句话
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
源位置、输入/输出、依赖和影响范围。
```text
代码投影: eval([名称](载荷)) = eval(载荷)
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
```
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
三者同源,才是代码即文档、文档即知识、知识即可执行。
---
## 1. 统一节点:`Named<T>`
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
```text
Named<T> { label, inner: T, span }
```
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
| 既有位置 | `T` | 示例 | 知识角色 |
|---|---|---|---|
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
### 1.1 每个节点都有角色,而不是两套语法
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
| role | 如何识别 | `check` 应问什么 |
|---|---|---|
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
---
## 2. 知识层不是目录隔离,而是同一图的不同投影
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
同一份 `.mq.md` 可以同时有多层节点。
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|---|---|---|---|
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
这正是通用语法本身兼容知识体系的含义。
### 2.1 `#` / `##` 的位置
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
`[]()` 是知识单元的内部结构。
---
## 3. 大项目的寻址:可读短名与稳定身份同时成立
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
1. 文件的既有 frontmatter `id` 是稳定身份;
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
3. `#` / `##` 是人可读的路径段;
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
```markdown
---
id: knowledge.people.li-bai
import:
li_bai: knowledge/people/li-bai.mq.md
---
# 回答
**year = [李白的出生年份](li_bai.李白.出生年份)**
李白出生于[公元 701 年](李白.出生年份)。
```
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
而是可读的查询,必须由 lock 固化。
---
## 4. 每个 `[]()` 产生统一的知识记录
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
"inputs": ["订单.行"],
"outputs": ["行"],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
],
"effect": "pure",
"fingerprint": "sha256:…"
}
```
此记录就是统一知识图节点:
- 本地取元有输入/类型边;
- 纯计算有输入/输出/公式边;
- 循环有集合、变量绑定和循环体边;
- 调用有 `calls`/`uses` 边;
- 有来源的事实再增加 `derived_from` 边;
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
---
## 5. 闭环:写、跑、看、查、变
```text
作者写 Named<T>
│
├─ run:擦除 label,按原语义执行
├─ view:显示 label,可展开值、输入、步骤和来源
└─ check:解析所有依赖,编译统一知识图
│
catalog / lock / context pack
│
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
│
作者或 agent 修复后重新 check/verify
```
### 5.1 命令边界
| 操作 | 做什么 | 不做什么 |
|---|---|---|
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
---
## 6. 实施顺序
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
+2 -1
View File
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
```markdown
---
import plugin:lib/plugin.mq.md
import:
plugin: lib/plugin.mq.md
---
# main
+6 -5
View File
@@ -159,11 +159,12 @@ REPLACE
```markdown
---
title: agent-run-…
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import writeback:lib/writeback.mq.md
import subtask:lib/subtask.mq.md
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
writeback: lib/writeback.mq.md
subtask: lib/subtask.mq.md
---
# 总目标
+24 -7
View File
@@ -4,7 +4,7 @@
|---|---|
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**engineering-knowledge.md**](engineering-knowledge.md)(**EKC / EFI preflight**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
## 0. 为什么要改掉旧方案
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
```markdown
---
导入 智能体:ext/ai/智能体.mq.md
导入 大模型:ext/ai/大模型.mq.md
导入 自写回:lib/自写回.mq.md
导入 时间:lib/时间.mq.md
导入:
智能体: ext/ai/智能体.mq.md
大模型: ext/ai/大模型.mq.md
自写回: lib/自写回.mq.md
时间: lib/时间.mq.md
---
## 获取时间
@@ -167,8 +168,9 @@ ext/
**分层纪律(硬规则,勿破)**:
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …;以及 EKC:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
4. **Engineering preflight**:`agent.preflight` / `plan … eng_preflight=True` 在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 [engineering-knowledge.md](engineering-knowledge.md))。缺 `.marqdo` 知识图时返回 `missing_knowledge` 并放行,以兼容纯任务包测试。
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
@@ -180,11 +182,26 @@ ext/
| 中文 | 英文 | 角色 |
|------|------|------|
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) |
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near |
| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev` 为 `small-llm` 兼容别名) |
| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:<slug>` / `EXPLORE`)落到 kb 技能 |
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/vN.mq.md` + 可选 OKF promote |
| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) |
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。`plan` 对已存在的 `resources/<slug>.mq.md` **不覆盖**(`agent-plan-preserve`)。
**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。
**Adaptive Routing(P4)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(`router_model` 任意 llm 句柄)/ `llm` / `auto` 级联。`jev` 仅为 `small-llm` 兼容别名,**不进入框架专属设计**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。
构造参数(v1):
| 参数 | 说明 |
+142
View File
@@ -0,0 +1,142 @@
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
| | |
|---|---|
| 状态 | **Accepted · O1–O5 locked** |
| 日期 | 2026-10-16 |
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
---
## 0. 方案立场
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
---
## 1. 架构愿景(闭环)
```text
目标 / 任务
│
▼
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
│ miss
▼
small-llm 路由 / 父分解
│
▼
生成或修补 .mq.md(代码即文档风格)
│
▼
sandbox.open → sandbox.run(caps)→ diff
│
├─ 失败 → writeback error / 隔离,不 promote
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
│
▼
下次 REUSE(降本)
```
---
## 2. 可行方向全集
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
### A. 沙盒 × Agent 闭环
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
### B. OKF / EKC / 技能层
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
### C. 大模型 / 路由 / 成本
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
### D. 代码即文档(产出质量)
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
### E. 评测与产品化
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
### F. 明确不优先 / 需单独论证
| ID | 方向 | 理由 |
|----|------|------|
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
---
## 3. 执行顺序(O1→O5 locked)
| 波次 | 方向组合 | 为何先做 |
|------|----------|----------|
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
| **O∞** | C4 / A6 | 研究项,单独立项 |
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
---
## 4. 验收原则(任一波次)
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
---
## 5. 落地
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
+104
View File
@@ -0,0 +1,104 @@
# Official AI sandbox (`ext/ai/sandbox`)
| | |
|---|---|
| Status | **Accepted · implementing** |
| Date | 2026-10-16 |
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
---
## 0. One-liner
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
---
## 1. Goals / non-goals
### Goals
| # | Goal |
|---|------|
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
| G3 | `diff` / `discard` / `inspect` for review gates |
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
### Non-goals (this wave)
| # | Non-goal |
|---|----------|
| N1 | Embed wasmtime in CLI |
| N2 | True Wasm ABI plugins (linalg/quantum) |
| N3 | bwrap / microVM |
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
| N5 | Symlink-forest workspace isolation |
| N6 | Default host-proxy of all native ABI plugins |
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
---
## 2. Layering
```text
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
↓ host_query
HostContext + CowSession
(fs / writeback see upper)
```
| Layer | May call `host_*` | Role |
|-------|-------------------|------|
| `ext/ai/sandbox` | **No** | Author facade |
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
---
## 3. Author API
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
| Method | Params | Result |
|--------|--------|--------|
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
| `write` | `id=`, `path=`, `text=` | none |
| `read` | `id=`, `path=` | text |
| `remove` | `id=`, `path=` | none (whiteout) |
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
| `commit` | `id=` | `{ ok, applied }` |
| `discard` | `id=` | `{ ok }` |
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
| `inspect` | `id=` | caps, root, change count, notes |
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
---
## 4. CoW semantics
- **lower** = real workspace root (read-through).
- **upper** = session map path → bytes.
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
---
## 5. Hard bans
1. No public `lib/sandbox`.
2. No symlink forest as the isolation story.
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
4. `ext/**` must not call `host_*`.
5. Do not treat empty `# main` as sandbox completeness.
---
## 6. ABI / host_query
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
+2 -1
View File
@@ -197,7 +197,8 @@
````markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# 转置反序
+3 -2
View File
@@ -201,8 +201,9 @@ $$
````markdown
---
import la:ext/linalg/linalg.mq.md
import table:lib/table.mq.md
import:
la: ext/linalg/linalg.mq.md
table: lib/table.mq.md
---
# main
+76 -52
View File
@@ -2,84 +2,108 @@
| | |
|---|---|
| Status | Accepted (v0.1.x) |
| Date | 2026-08-06 |
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) |
| Date | 2026-09-24 |
| Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) |
## Scope
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
`ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper.
```text
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
Compat: complete / chat
```
Import:
```markdown
---
import llm:ext/ai/llm.mq.md
import:
llm: ext/ai/llm.mq.md
---
```
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
## Platform prerequisites
| Capability | Surface |
|------------|---------|
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
| JSON quote | `lib/json` → `quote` |
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
## Public API
| English | Chinese | Role |
|---------|---------|------|
| `## load_env` | `## 加载环境` | Free function: load `.env` |
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
| `# llm` | `# 大模型` | Object ctor → handle map |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
| `## load_env` | `## 加载环境` | Load `.env` |
| `## create` | `## 创建` | Factory → LLM handle |
| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles |
| `## prompt_load` / `## prompt` / `## prompt_body` | `## 加载提示` / `## 提示` / `## 提示正文` | Prompt artifacts (`type: prompt` → body) |
| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) |
| `## collect` | `## 收集` | Events → text |
| `## stream_result` | `## 流式结果` | Alias of `collect` |
| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) |
| `## ask` (method) | `## 提问` | → **LLMResult** map |
| `## stream` | `## 流式` | → event list |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive |
### Preferred
```markdown
---
import llm:ext/ai/llm.mq.md
---
**answer = > llm.ask prompt="What is Marqdo?"**
*answer*
# main
**model = > llm.create**
**result = > `model`.ask prompt=`prompt`**
*[text](result)*
> load_env
**fast = > llm.fast**
**events = > `fast`.stream prompt=`prompt`**
**text = > llm.collect events=`events`**
*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`
*`events` = > `model`.complete prompt=Say hi stream=True *
- [`ev`](`events`)
*`t` = > json.get value=`ev` key=type *
1. `t` == "delta"
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. *
*`_` = 1*
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
**body2 = > llm.prompt text=`raw`**
```
Environment (create a **project-local** `.env`; do not commit secrets):
### LLMResult
| Field | Meaning |
|-------|---------|
| `text` | Answer string |
| `model` | Model id |
| `finish` | Finish reason (`stop`, …) |
| `backend` | e.g. `openai-compatible` / `ollama` |
| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` |
| `tokens` | Alias of `usage.total_tokens` (agent metrics) |
| `name` | Optional handle tag (`fast` / `reasoning`) |
| `llm_calls` | `1` per ask |
| `tool_calls` | List of OpenAI-shaped tool call objects (empty when none) |
### Compat
`complete` / `chat` still return a bare string (or event list when `stream=True`) so `ext/ai/agent` and older runbooks keep working. **New code should use `ask` / `stream` / `collect`.**
## Environment
```env
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
MARQDO_LLM_FAST_MODEL=...
MARQDO_LLM_REASONING_MODEL=...
OLLAMA_HOST=http://127.0.0.1:11434/v1
```
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`.
## Backends
| `backend=` | Module | Notes |
|------------|--------|-------|
| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE |
| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` |
## Tests
- Import smoke: `tests/ext/llm-import.mq.md`
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
- `tests/ext/llm-import.mq.md`
- `tests/ext/llm-ctor-offline.mq.md`
- `tests/ext/llm-ask-offline.mq.md` (create + collect)
- `tests/ext/llm-stream-offline.mq.md`
- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load)
- `tests/ext/llm-tool-calls-offline.mq.md` (`tool_calls_from` / Result field)
- `tests/ext/llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md`
- Live: `llm-complete.mq.md` · `llm-stream-live.mq.md`
+4 -2
View File
@@ -101,7 +101,8 @@ marqdo ext add quantum
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
```
@@ -341,7 +342,8 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
```markdown
---
title: Bell state
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
+199
View File
@@ -0,0 +1,199 @@
# 官方扩展:Web Artifact(Document / Endpoint / Resource)
| | |
|---|---|
| 状态 | **Accepted · 破坏性(取代 page/app God Object 作者面)** |
| 日期 | 2026-09-28 |
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
| 安装 | `marqdo ext add web`(`web` / `网页`) |
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
---
## 0. 一句话
> **Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.**
---
## 1. 三原语
| Artifact | Metadata `type` / `类型` | 含义 |
|----------|--------------------------|------|
| **Document** | `web` / `网页` | Markdown 正文 + View → HTML;`route`/`路由` 注册 declared HTTP |
| **Endpoint** | `endpoint` / `端点` | 可执行正文为 handler;`path`+`method` 注册 API |
| **Resource** | (绑定/导入) | `ext/data` · `ext/security` · 未来 LLM 等,经 metadata / import 声明 |
核心装载识别 `type`/`类型`(见 `src/artifact/`);渲染与 listen 在 `ext/web` + `plugins/web`。
---
## 2. 目录
```text
ext/web/
web.mq.md · 网页.mq.md # facade: page route serve render inspect
page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md
ext/net/ http.mq.md · websocket.mq.md · url.mq.md
ext/data/ db.mq.md · cache.mq.md · storage.mq.md
ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md
```
作者入口通常:
```text
site/
index.mq.md # type: web · route: / · 或 # main → web.serve
pages/*.mq.md # type: web
api/*.mq.md # type: endpoint
data/ # sqlite runtime (gitignore)
```
---
## 3. Document(`type: web`)
```markdown
---
type: web
title: Marqdo Blog
route: /
method: GET
data_source: posts
data_order: -created_at
import:
web: ext/web/web.mq.md
data: ext/data/db.mq.md
---
# Marqdo
Welcome to the executable web.
```
| 键 (EN) | 键 (ZH) | 说明 |
|---------|---------|------|
| `type` | `类型` | `web` / `网页` |
| `route` | `路由` | 路径,可含 `{param}` |
| `method` | `方法` | 默认 `GET` |
| `title` | `标题` | 文档标题 / `<title>` |
| `data_source` | `数据源` | 表名 |
| `data_order` | `排序` | 如 `-created_at` |
| `data_where` | `条件` | `col=val,col2=val2` |
正文 Markdown 经 `dom` 变为 DOM Artifact,再 `web.render`。可选 View 表:
```markdown
`nodes` =
| type | slot | value | attrs | style |
|------|------|-------|-------|-------|
| text | kicker | AI Native | | eyebrow |
| title | title | Marqdo | | title |
```
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
---
## 4. Endpoint(`type: endpoint`)
```markdown
---
type: endpoint
method: POST
path: /api/posts
request: json
response: json
auth: member
import:
data: ext/data/db.mq.md
---
**post = > data.db.insert …**
*post*
```
| 键 (EN) | 键 (ZH) | 说明 |
|---------|---------|------|
| `type` | `类型` | `endpoint` / `端点` |
| `path` | `路径` | URL |
| `method` | `方法` | GET/POST/… |
| `request` | `请求` | `json` / `form` / `none` |
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
**Handler 约定(锁定)**:Endpoint 文件用 `# main` 作为请求处理器。请求体/query/path 参数经 `run_artifact` 以 Metadata Binding 覆盖注入(与 `--bind` 同源),正文用已提升的普通变量名。无 `# main` 时返回 Artifact Result 摘要(`ok`/`value`/`error`),适合作文档型 ping。
---
## 5. Facade API(EN / ZH)
| EN | ZH | 作用 |
|----|-----|------|
| `web.page` | `网页.页面` | 从 metadata/正文/nodes 构造 Document 句柄 |
| `web.route` | `网页.路由` | 注册 declared Document 或 Endpoint |
| `web.serve` | `网页.服务` | `root=` 扫描注册 + listen |
| `web.render` | `网页.渲染` | Document → HTML(离线/预览) |
| `web.inspect` | `网页.检视` | `{declared, system}` 路由表 |
Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(cors, security, …)` 垃圾抽屉。
---
## 6. 发现算法(锁定)
`web.serve root=DIR host=… port=…`:
1. 递归枚举 `DIR` 下 `*.mq.md`(跳过 `data/`、隐藏目录、`node_modules`)。
2. 解析文件头 Metadata;无 `type`/`类型` 或非 web/endpoint → 跳过。
3. Document → declared route(缺 `route` 则相对 `root` 的路径映射,`index.mq.md` → `/`)。
4. Endpoint → declared path+method(`path`/`路径` 必需)。
5. System routes(`/_part/*`、`/_form/*`、静态等)由 runtime 挂载,仅出现在 `inspect.system`。
6. 调用 native listen。
---
## 7. Table 规则
- **View**:仅 `|type|slot|value|attrs|style|`(及列名 ZH 别名:`类型|槽|值|属性|样式`)。
- **Resource schema**:`|字段|类型|可空|` 等 — 专用且文档化,不是函数私有方言。
- **禁止** `|属性|值|样式|` / `|front|back|css|` / `|组件|样式|` 作为页面主装配(已删除)。
- Raw HTML/CSS = escape hatch(`dom.raw` / `page.css`),不是默认语言。
---
## 8. Result
所有易失败的 Resource / Endpoint 边界返回 map:
| 键 | 类型 | 说明 |
|----|------|------|
| `ok` | bool | 成功 |
| `value` | any | 成功载荷 |
| `error` | text \| None | 失败信息 |
---
## 9. 硬约束(取代旧 C1–C7 作者面)
| # | 约束 |
|---|------|
| A1 | Document/Endpoint 由核心识别 `type`;装配在 ext(ADR 0007) |
| A2 | 禁止 `json.set` 袋胶水;Table = Data |
| A3 | 中英分文件;同文件禁止混 API |
| A4 | 禁止作者 `ensure_plugin` / `host_*` |
| A5 | 禁止隐式用户 route;system 须 `inspect` 可见 |
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
---
## 10. 与旧 ext-web.md
旧「页面表 + compose_* + app.route」作者面 **废止**。历史能力矩阵见 [web-net-capabilities.md](web-net-capabilities.md);迁移后以本文件与 ADR 0007 为准。
+2 -1
View File
@@ -49,7 +49,8 @@
英文:
```markdown
import web:ext/web/web.mq.md
import:
web: ext/web/web.mq.md
# main
+2 -1
View File
@@ -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 产物与解析
+33 -27
View File
@@ -2,18 +2,21 @@
| | |
|---|---|
| 状态 | **Accepted · W0–W7 + P3 + W8(站点图标/Head/图片装配)完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap / **favicon·头资源·图片装配**;Postgres 等见 §9) |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18) |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
| 状态 | **Superseded(作者面)· 历史能力档案** — 现行作者面见 **[ext-web-artifact.md](ext-web-artifact.md)** · ADR [0007](../adr/0007-web-document-endpoint.md) |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18;Artifact 重构:2026-09-28) |
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
| 本文目的 | **历史**类 API 与能力矩阵;新站请勿按本文 `compose_*` / `app.configure` 写作 |
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。C1 已由 ADR 0007 修订。下文保留作迁移对照,**不是**现行推荐 API。
---
## 0. 一句话
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
**现行**:`.mq.md` Artifact(`type: web|endpoint`)描述页面与交互;见 [ext-web-artifact.md](ext-web-artifact.md)。
**历史(废止)**:`ext/web` 曾用 GFM 表格 + `# page`/`# app` 类方法拼装站点。该模型因 God Object / 碎片 DSL / 隐式路由被破坏性替换。
---
@@ -41,13 +44,14 @@
| # | 约束 |
|---|------|
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进。**落实**:原生层 Go 全量重写见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md);作者面 ABI 名保持兼容 |
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
| C1 | **修订(ADR 0007)**:核心可识别 Artifact `type: web\|endpoint`(及 ZH);**不**新增 CORE_CONSTRUCTS 标记;单元格求值 / import 句法不变;装配语义仍在 ext + plugin。旧文「禁止为 web 改核心」作废 |
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水(现行见 ext-web-artifact A2) |
| C3 | 中英分文件;同文件禁止混 API(现行 A3) |
| C4 | **废止**「页面表 + compose」心智 → Document Artifact + `pages/` · `api/` |
| C5 | 破坏性重写作者面(ADR 0007);原生 Go 演进见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) |
| C6 | DB 迁至 **`ext/data`**;CRUD 仍须完整(`select` / `查询`) |
| C7 | 表单校验仍须在写库前执行;挂载经 declared Endpoint / system `/_form`(inspect 可见) |
| A1–A8 | **现行硬约束**见 [ext-web-artifact.md](ext-web-artifact.md) §9 |
---
@@ -124,13 +128,14 @@ myapp/
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
import web:ext/web/web.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
@@ -167,13 +172,14 @@ Main content is not a reusable component, so it is authored here.
```markdown
---
title: 站点
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
导入:
网页: ext/web/网页.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
@@ -0,0 +1,60 @@
# 块公式元数据绑定 · 控制流叙述统一
| | |
|---|---|
| 状态 | Active |
| 日期 | 2026-10-15 |
| 相关 | [stdlib-math.md](stdlib-math.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 块公式 `% marqdo: var=`
在 `$$…$$` 块内用 **TeX 行注释**声明绑定名(渲染通常不可见;运行时剥离后解析公式体):
```markdown
$$
% marqdo: var=f
x^2 - 2
$$
```
- 指令:`% marqdo:` + 空白 + `var=<ident>`;未知键 → Error。
- 可无前置 `` `f` = ``;若同时写空 RHS 与 `var=`,**同名允许、异名 Error**。
- **保留**旧空 RHS + 后随 `$$`。
- **不做**:行内 `$% marqdo:…$`;\`\`\` 代码围栏内语言注释 meta(本波)。
- 行内公式继续传统绑定:`` `g` = $x+1$ ``(单 `$…$` → `formula`)或 `` `g` = $$x+1$$ ``。
无名叙述区 `$$` 仍仅展示;可执行区裸块既无空 RHS 又无 `var=` → Error。
---
## 2. 臂 / 循环体叙述(与函数体同权)
`parse_indented_body` 与函数体相同:消费 `` `名` `` / `**代码**` / `*返回*`;纯叙述跳过。
斜体返回结束**当前臂或当前循环体**,不结束外层函数。
---
## 3. 循环头
| 面 | 写法 | 说明 |
|----|------|------|
| **推荐** | `- [项](xs)` / `- [`项`](`xs`)` | 支持嵌套 |
| 中文糖 | `- 对`xs`的每一项`项`` | 可选后缀「遍历」 |
| 英文糖 | `- for each `item` in `xs`` | 大小写不敏感 `for each` / `in` |
糖与链接头语义相同,可混用嵌套。
---
## 4. 分支条件行叙述
结构行仍以 `1.` / `2.` 开头。条件提取顺序:
1. 整段可解析为表达式(现状);
2. 行内粗体代码条件 `**`n` > 0**`;
3. 剥离「当/若/如果/when/if」与「时/则」后,将「大于/小于/等于…」映射为运算符再解析。
else:`N. *`(可夹「否则」等叙述,条件位仍为 `*`)。
禁止无标记自然语言整句当条件。
+449
View File
@@ -0,0 +1,449 @@
# 外联内核(Foreign Kernel)
| | |
|---|---|
| 状态 | **F0–F3.5 已实现** |
| 日期 | 2026-10-17 |
| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无 |
> 外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 `marqdo run` 里的显式调用使用,也能被 view 的 notebook 会话使用。
---
## 1. 定位与边界
### 1.1 负责
- 解释器发现、注册、配置、探测。
- 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
- 持久内核:启动、求值、状态、关闭、列表。
- 状态桥:`session_set` / `session_get` / `session_names`。
- JSON 值桥:Marqdo `Value` ↔ JSON。
- 结构化记录:`ok/code/stdout/stderr/ms/timed_out/truncated/result/error`。
- 安全:`exec` 门禁、`cwd` 沙箱、进程组、并发/输出上限。
- 视图诊断:代码卡片 Run 的完整结果。
### 1.2 不负责
- 文档语法(`内核表` / `会话表`)→ [notebook-syntax.md](notebook-syntax.md)。
- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。
- Foreign → Marqdo 函数回调(v2 不做)。
- 依赖安装(pip/npm)。
- 远程 / 容器执行。
### 1.3 与相邻模块的区别
| 模块 | 生命周期 | 用途 |
|---|---|---|
| `foreign` | 一次性或持久 | 调外部语言;状态可选 |
| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 |
| `plugin` | 进程内 | 原生 C ABI 扩展 |
| `writeback` | 文档级 | 把输出写回 `.mq.md` |
`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。
---
## 1.4 实施状态(2026-10-17)
| 阶段 | 状态 | 关键文件 |
|---|---|---|
| F0 安全执行 / `invoke` 记录 | ✅ | `src/host/foreign.rs` |
| F1 预设 / probe / register / config | ✅ | `src/foreign/registry.rs` · `src/host/foreign.rs` |
| F2 JSON 桥 / run_many / call_many | ✅ | `src/host/foreign.rs` |
| F3 Python/Node 持久内核 | ✅ | `src/host/foreign_session.rs` |
| F3.5 session_set/get/names | ✅ | 同上 |
| F4 history / view 打磨 / 发布 | 部分 | — |
测试:`cargo test --lib foreign`(11+)、`cargo test --test gold lib_foreign`(12,python 条件跳过)、`tests/notebook/shared.mq.md` 手工 view 验证。
---
## 2. 语言与内核模型
### 2.1 语言预设
| lang | 别名 | 默认命令 | 扩展名 | 版本探测 | 会话 |
|---|---|---|---|---|---|
| `python` | `python3`, `py` | `python3`(Windows `python`) | `.py` | `--version` | ✅ |
| `node` | `javascript`, `js` | `node` | `.js` | `-v` | ✅ |
| `deno` | — | `deno run` | `.ts` | `--version` | ❌ |
| `bun` | — | `bun` | `.js` | `--version` | ❌ |
| `ruby` | — | `ruby` | `.rb` | `--version` | ❌ |
| `perl` | — | `perl` | `.pl` | `--version` | ❌ |
| `php` | — | `php -r {inline}` | `.php` | `--version` | ❌ |
| `lua` | — | `lua` | `.lua` | `-v` | ❌ |
| `r` | `rscript` | `Rscript` | `.R` | `--version` | ❌ |
| `julia` | — | `julia` | `.jl` | `--version` | ❌ |
| `go` | — | `go run {file}` | `.go` | `version` | ❌ |
| `bash` | `sh`, `shell` | `bash` | `.sh` | `--version` | ❌ |
| `powershell` | `pwsh`, `ps1` | `pwsh`(Windows `powershell`) | `.ps1` | `--version` | ❌ |
| `sqlite` | `sqlite3` | `sqlite3` | `.sql` | `--version` | ❌ |
| `tsx` | `typescript` | `tsx` | `.ts` | `--version` | ❌ |
说明:
- 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
- 会话能力首批只有 Python / Node;其它语言一次性执行。
- `php` 用 `{inline}`,围栏里直接写 PHP,不需要 `<?php`。
- `deno` 默认不给权限;需要时通过配置追加 `--allow-*`。
### 2.2 解析优先级
从高到低:
1. 调用级 `cmd`(整行 argv,shell-like 切分)+ `args`(追加)。
2. 进程内注册:`register` / `set_cmd`。
3. 环境变量 `MARQDO_FOREIGN_<LANG>`(整行或 JSON 数组)。
4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。
5. 内置预设。
6. 都没有 → 带修复建议的诊断。
Python 额外发现顺序(在预设层内):
1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`);
2. `<cwd>/.venv` / `venv` / `env`;
3. 入口目录与 `fs_root` 向上查找;
4. PATH 的 `python3` / `python`。
`MARQDO_FOREIGN_NO_VENV=1` 关闭 venv 探测;显式 `cmd` / `set_cmd` / `MARQDO_FOREIGN_PYTHON` 优先。
相对路径:配置里的 `cmd` 相对配置目录;注册 / `set_cmd` / 环境变量里的 `cmd` 相对 `cwd`。
### 2.3 注册与模板
`register(lang, cmd?, args?, template?, ext?, env?, version_args?)`。
模板占位符:
| 占位符 | 展开 |
|---|---|
| `{file}` | 临时脚本绝对路径 |
| `{dir}` | 临时目录 |
| `{base}` | 脚本文件名 |
| `{inline}` | 源码作为一个 argv;不写临时文件 |
| `{lang}` | 语言 id |
| `{cwd}` | 实际工作目录 |
规则:
- `cmd` 与 `template` 至少一个;都给 → 报错。
- `{file}` 与 `{inline}` 不能同时出现。
- 都没有时自动追加 `{file}`。
- `{inline}` 超过 60 KiB → 报错并建议 `{file}`。
- 模板不做 shell 转义;需要 shell 时显式写 `bash -c`,路径由引擎生成(安全字符)。
配置示例:
```toml
[python]
cmd = ".venv/bin/python"
args = ["-u"]
[go]
template = ["go", "run", "{file}"]
[rust]
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]
[php]
template = ["php", "-r", "{inline}"]
```
---
## 3. 一次性执行
### 3.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `run` | `运行` | `code`, 可选 `stdin` `env` `cwd` `timeout` `args` `max_output` | stdout 文本(v1 兼容) |
| `run_lang` | `按语言运行` | `lang`, `source`, 可选同上 | stdout 文本 |
| `invoke` | `执行` | 可选 `code` / `lang`+`source` / `stdin` / `input` / `env` / `cwd` / `timeout` / `args` / `output` / `max_output` / `cmd` / `keep` / `cache` | 记录 map |
| `call` | `调用` | 可选 `code` / `lang`+`source` / `input` / `stdin` / `env` / `cwd` / `timeout` / `args` | 解析后的 JSON 值 |
| `run_many` | `批量运行` | `runs`, 可选 `concurrency` | 记录列表 |
| `call_many` | `批量调用` | `inputs`, 可选 `code` / `lang`+`source` / `cmd` / `env` / `cwd` / `timeout` / `args` / `max_output` / `concurrency` | 结果值列表 |
### 3.2 记录结构
`invoke` / `run_many` / `session_eval` 共用:
| 键 | 类型 | 含义 |
|---|---|---|
| `ok` | Bool | exit=0 且未超时 |
| `code` | Int | 退出码;未启动 / kill → -1 |
| `stdout` | Text | 原始 stdout(可能截断) |
| `stderr` | Text | 原始 stderr(可能截断) |
| `ms` | Int | 墙钟毫秒 |
| `lang` | Text | 实际语言 |
| `cmd` | Text | 实际 argv |
| `timed_out` | Bool | 是否超时 |
| `truncated` | Bool | stdout/stderr 是否截断 |
| `result` | 任意 / None | 按 `output` 解析 |
| `result_error` | Text | json 解析失败原因 |
| `error` | Text | 启动 / 超时 / 策略原因 |
| `script` | Text | `keep=True` 的脚本路径 |
| `cached` | Bool | 缓存命中(P4) |
`session_eval` 额外:`id`、`alive`。
### 3.3 输出模式
| `output=` | `result` |
|---|---|
| `auto`(默认) | 尝试 JSON;失败 → None |
| `text` | None |
| `json` | 解析;失败 → `result_error` |
| `lines` | 行列表 |
| `bytes` | stdout 原始字节的 base64 |
`call` 固定 JSON:空 stdout → None;非空非法 JSON → 错误。
### 3.4 失败语义
- `run` / `call`:执行失败 → `Err`;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
- `invoke` / `run_many`:执行失败 → 记录;只有参数非法 / 策略拒绝 → `Err`。
- 输出过大:截断 + `truncated=true`,不再 OOM / 报错。
---
## 4. JSON 状态桥
### 4.1 值映射
| Marqdo | JSON |
|---|---|
| None | null |
| Bool | bool |
| Int | number |
| Num | number(NaN/Inf → null) |
| Text | string |
| List | array |
| Map | object |
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
| Code | 源码字符串 |
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
### 4.2 输入
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
- `stdin=` 文本与 `input=` 互斥。
- 都不给 → stdin EOF。
- 大输入走文件,避免环境变量大小限制。
### 4.3 输出
- `result` 按 `output` 解析。
- 原始 stdout/stderr 始终保留(截断到上限)。
- `call` 返回解析值;`invoke` 返回记录。
### 4.4 类型限制
v2 是**值拷贝**,不是对象引用:
- Python DataFrame / NumPy / Node 对象 → 需要先 `to_dict` / `to_json` / `JSON.stringify`。
- 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
- Secret 不默认进入 JSON;需要 env 显式交付。
---
## 5. 持久内核与会话
### 5.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `session_open` | `会话开启` | `lang`, 可选 `cmd` `env` `cwd` `timeout` | 会话 id(Text) |
| `session_eval` | `会话求值` | `id`, 可选 `code` / `source` / `input` / `timeout` | 记录(含 id/alive) |
| `session_set` | `会话设值` | `id`, `name`, `value` | None |
| `session_get` | `会话取值` | `id`, `name` | JSON 值 / None |
| `session_names` | `会话变量` | `id` | 名称列表 |
| `session_close` | `会话关闭` | `id` | Bool |
| `session_list` | `会话表` | — | map 列表 |
### 5.2 支持语言
| 语言 | 方式 |
|---|---|
| python | `python3 -u -c <bootstrap>` |
| node | `node -e <bootstrap>` |
| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` |
### 5.3 线路协议
stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:
```json
{"id":1,"code":"x = 41","input":null}
{"id":2,"code":"x + 1","input":null}
```
```json
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
```
- 同一会话严格串行:等到匹配响应后才发下一条。
- 响应单行;JSON 转义换行。
- 崩溃 / EOF → `alive=false`,会话移除。
- 超时 → kill 会话(状态不可信)。
### 5.4 Python bootstrap
- 保留原始 `sys.stdout` 写协议;用户输出用 `redirect_stdout/stderr` 捕获。
- `ast.parse`:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
- 异常 → `traceback.format_exc(limit=8)`,`ok=false`;会话继续。
- `input` → 全局 `marqdo_input`。
- 不可序列化 → `default=str`。
### 5.5 Node bootstrap
- 保存原始 `process.stdout.write` 写协议。
- eval 期间替换 `console.*` 与 `process.stdout/stderr.write`;结束后恢复。
- `vm.runInThisContext` 保留全局状态;`require` 挂到 `globalThis`。
- Promise → await;顶层 await 需用户包 `(async()=>{…})()`。
- 序列化失败 → `String(result)`。
### 5.6 状态桥
- `session_set`:值 → JSON → 请求 `{"set": name, "value": ...}` 或执行一段赋值。
- `session_get`:请求 `{"get": name}` → JSON → Marqdo Value。
- `session_names`:请求变量名列表。
- 与 `session_eval` 同一线路协议;严格串行。
- 名称必须是合法标识符;保留名(`marqdo_input` 等)另行文档。
### 5.7 生命周期
- id 为 `s1`、`s2`…。
- 每会话独立进程、cwd、env。
- `HostContext` drop → 全部 kill + wait。
- `subtask` 不继承会话。
- 不跨文档共享。
---
## 6. 环境契约
| 变量 | 值 |
|---|---|
| `MARQDO_FOREIGN` | `1` |
| `MARQDO_FOREIGN_LANG` | 语言 id |
| `MARQDO_FOREIGN_SCRIPT` | 脚本路径(文件模式) |
| `MARQDO_FOREIGN_DIR` | 脚本目录 |
| `MARQDO_FOREIGN_CWD` | 实际 cwd |
| `MARQDO_ENTRY` | 入口 `.mq.md` 路径 |
| `MARQDO_ENTRY_DIR` | 入口目录 |
| `MARQDO_INPUT` | input JSON(≤8 KiB) |
| `MARQDO_INPUT_FILE` | input JSON 文件(任意大小) |
语言默认:
- Python:`PYTHONUNBUFFERED=1`、`PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`;`PYTHONPATH` 前插 cwd。
- Node:`NODE_PATH` 前插 cwd(可选)。
`env` 是 map;值 `as_display()`;Secret 取真实值(显式交付)。不主动清空父环境。
---
## 7. 临时文件与 cwd
- 默认 `<cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/`;不可写 → 系统临时目录。
- `MARQDO_FOREIGN_TMPDIR` 覆盖。
- 脚本 `main.<ext>`;Python 加 utf-8 声明。
- 默认 cwd = 入口目录;调用级 cwd 经 `resolve_path` + `fs_root` 校验。
- 成功/失败/超时都清理;`keep=True` 保留并回填 `script`。
- Node 相对 `require('./x')` 相对脚本目录;需要项目相对路径时用 `MARQDO_FOREIGN_CWD` 或 `{inline}` 模板。
---
## 8. 超时、IO、进程组
- `timeout`:秒,可小数;默认 10s;上限 3600s;`<=0` 报错。
- 超时 kill 进程组:
- Unix:`process_group(0)` + `kill(-pid, SIGKILL)`;
- Windows:`taskkill /PID <pid> /T /F`。
- `max_output`:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;`truncated=true`。
- stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
- stdout/stderr 两个读线程;UTF-8 lossy。
- 记录原始字节(至上限)以支持 `bytes` 输出。
---
## 9. 安全
| 项 | 策略 |
|---|---|
| 能力门禁 | `run` / `invoke` / `probe` / `session_*` 全部检查 `allow_exec()`;沙箱 → 拒绝 |
| shell | 默认不经 shell;模板显式 `bash -c` 才走 |
| cwd | `resolve_path` + `fs_root`;越界拒绝 |
| 输出 | 有界读取 + 丢弃式排空 |
| 时间 | 上限 + 进程组 kill |
| 并发 | 默认 4,上限 32 |
| 会话 | 每文档独立;关闭/drop 清理;超时即杀 |
| Secret | JSON 不默认暴露;env 显式;面板打码 |
| wasm | `exec-host` 关闭时全部返回清晰错误;`langs` 返回 [] |
---
## 10. 兼容性
- `run` / `run_lang` / `set_cmd` / `langs` 既有调用可用。
- `run` 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
- `set_cmd` 增加可选 `args`。
- `langs` 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
- `subtask` 的 `spawn code=` / `lang=` 仍返回 stdout 文本。
- HostFn id 只追加;字节码参数 < 255。
- 无核心表面 Δ。
---
## 11. 测试矩阵
| 测试 | 依赖 | 断言 |
|---|---|---|
| 既有 `foreign-python` / `run-lang` / `外联-python` | python | 兼容 |
| `foreign-invoke` | node | ok/code/stdout/stderr/ms |
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
| `foreign-timeout` | node | timed_out, 无遗留进程 |
| `foreign-call-json` | node | 嵌套 list/map 往返 |
| `foreign-call-many` / `run-many` | node | 顺序/隔离/并发 |
| `foreign-session` | node(python 可选) | 跨 eval 状态、异常不杀 |
| `foreign-session-set-get` | node | 变量推拉 |
| `foreign-session-timeout` | node | alive=false |
| `foreign-probe` | node | path/version/ok |
| `foreign-register` | node | 模板 `{inline}` |
| `foreign-config` | node | `MARQDO_FOREIGN_CONFIG` |
| `foreign-caps` | 无 | exec=false 拒绝 |
| 单元测试 | 无 | shell 切分/模板/别名/JSON |
当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 `python_available()` / `bash_available()` 守卫。
---
## 12. 实现落点
| 文件 | 内容 |
|---|---|
| `src/foreign/registry.rs` | 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑) |
| `src/host/foreign.rs` | Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config |
| `src/host/foreign_session.rs` | Python/Node bootstrap;会话生命周期;set/get/names |
| `src/host/dispatch.rs` | HostFn 追加 |
| `src/aliases.rs` | 参数别名 |
| `lib/foreign.mq.md` / `lib/外联.mq.md` | L1 API + 文档 |
| `src/view/mod.rs` / `html.rs` / `debug_page.rs` | Run 诊断;后续接文档会话 |
| `tests/gold.rs` / `tests/lib/foreign-*.mq.md` | 测试 |
---
## 13. 明确不做
- Foreign line-level step。
- Foreign → Marqdo 函数 callback。
- 自动镜像变量。
- 跨语言共享对象引用。
- 全进程快照。
- 自动安装依赖。
- 浏览器 wasm 外联。
+654
View File
@@ -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 变成第二套解释器;
- 不把“未实现”伪装成支持。
+304
View File
@@ -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 个函数**——
看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?
+335
View File
@@ -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 需要回调)
若有真实用例,评估会完全不同——请给我场景,我按场景重新评估。
+443
View File
@@ -0,0 +1,443 @@
# 知识分层:原始语料、可执行知识、调用面
| | |
|---|---|
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
| 日期 | 2026-10-23 |
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
| 示例 | [examples/knowledge-layers/](../../examples/knowledge-layers/) |
---
## 0. 结论先行
### 0.1 一句话
> **分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 `#`/`= >` 语法。**
> 如果「实例化」指**知识个体**,用 `# 李白 = > 诗人` 编码即可,零新语法;
> 如果「实例化」指**运行时对象**,就需要新的可寻址实例声明/注册表,语法成本明显更高。
### 0.2 三层 / 四层:推荐四层
| 层 | 名称 | 内容 | 语法载体 |
|----|------|------|---------|
| **L0** | 原始语料 | 原文、出处、引用、版本 | `.md` / `.mq.md` 叙述 + `来源` 表 |
| **L1** | 本体 / 模式 | 类、字段、类型、约束 | `# 诗人` + 字段/类型表 |
| **L2** | 可执行知识 | 知识个体、事实、返回值、出处 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` |
| **L3** | 调用面 | 链接、类调用、view、LinkInfo、EKC、agent | `[出生年份](李白.出生年份)` |
三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把**本体**与**个体**分开,正好对应 EKC 的 schema/knowledge 分层。
### 0.3 核心判断
| 判断 | 结论 |
|------|------|
| 原始语料 → 可执行知识 → 调用面,逻辑成立 | ✅ |
| 可执行知识能还原/验证回原始语料 | ✅ 需要出处/校验约定,语法上可行 |
| `# 诗人` 是类 | ✅ 现有 `#` 语义 |
| `# 李白 = > 诗人` 是「实例化」 | ⚠️ **语法上是继承/特化,不是运行时实例化** |
| `李白.出生年份` 是类调用 | ✅ 需要类函数 + 项目类索引(v2.1 目标) |
| `[]()` 是调用面,不新增语法 | ✅ `[描述](类.函数)` = 描述 + 已有调用 |
---
## 1. 你的模型(精确复述)
1. 有一个**诗人**类(`# 诗人`),定义诗人应该有什么字段/函数;
2. 用**李白的知识**把这个类「实例化」:
- 李白是诗人;
- 李白有姓名、出生年份等事实;
3. 通过 `[]()` 链接语法调用这个知识:
- `[出生年份](李白.出生年份)`;
4. 整个体系分层:
- 原始语料;
- 改写/抽象后的可执行知识(可还原验证回原始知识);
- 智能体回答/思考时的调用面。
这个模型在**知识架构**上没有问题;问题只在第 2 步的「实例化」如何落到语法。
---
## 2. 当前语法事实
| 语法 | 当前语义 | 对模型的影响 |
|------|---------|-------------|
| `# 诗人` | 类/类型;正文是构造体 | ✅ 可做本体 |
| `# 李白 = > 诗人` | **继承/子类**;不是实例 | ⚠️ 与「实例化」字面不符 |
| `## 李白的出生年份` | 方法;可用 `self`/`自` | ⚠️ 当前是实例方法 |
| `> 李白` | 构造实例(map + `_type`) | ✅ 运行时实例 |
| `李白.李白的出生年份` | 当前被当变量/实例方法路径 | ❌ 类调用未实现 |
| `[描述](...)` | 描述 + 表达式 | ✅ 调用面 |
| `import` | 跨文档绑定 | ⚠️ 当前跨文档继承/调用需 import |
**实测**(`marqdo 2.0.0`):
- `# 李白 = > 诗人` 在**另一个文档**定义 `# 诗人` 时,未 import 会报 `unknown base type 诗人`;
- import 后可以继承,但调用仍需 `> libai.李白` 构造实例,再 `` `li`.李白的出生年份() `` → `701`;
- `李白.李白的出生年份` 直接调用报 `undefined variable`;
- 跨文档类索引不存在。
所以「诗人类 → 李白实例 → 链接调用」在**目标模型**上成立,在**当前语法**上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。
---
## 3. 自洽性检查:逐层
### 3.1 L0 原始语料
| 问题 | 结论 |
|------|------|
| 原始语料是否可执行? | 否;它是出处,不是程序 |
| 能否被引用? | ✅ 现有 Markdown 相对链接/`来源` 表 |
| 能否保留原文? | ✅ 叙述、引用块、表格 |
| 语法负担 | 零:就是现有文档 |
**要点**:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要**物理/逻辑分离**(`corpus/` vs `knowledge/`)。
### 3.2 L1 本体 / 模式
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
```
| 问题 | 结论 |
|------|------|
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
### 3.3 L2 可执行知识:关键歧义
「用李白的知识实例化诗人」有两种落法:
#### A. 单体知识类(推荐)
```markdown
# 李白 = > 诗人
## 李白的出生年份
*701*
```
- 语法:`# 李白 = > 诗人` = 继承/特化;
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
#### B. 运行时实例(不推荐作为 v2.1 语法)
```markdown
# 诗人
## 李白
*> 诗人 姓名="李白" 出生年份=701*
```
- 语法:`## 李白` 是函数,返回一个实例 map;
- 调用:`李白().出生年份`(函数返回实例,再取方法);
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
#### C. 显式个体声明(未来可选)
```markdown
# 李白 : 诗人
```
- `:` 明确「李白是诗人个体」;
- 语法更贴近本体(instance-of),但**新增一个标记**;
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
- 不建议 v2.1 引入;可作为 v2.2 的候选。
### 3.4 L3 调用面
```markdown
[出生年份](李白.李白的出生年份)
```
| 问题 | 结论 |
|------|------|
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
| 终端输出? | 代码链接 + `print` |
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
| view 能否显示调用点? | 需要新增(工具,不是语法) |
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
---
## 4. 推荐模型:单体知识类
### 4.1 定义
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
调用:
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 4.2 为什么推荐 A
| 维度 | A 单体类 | B 运行时实例 |
|------|---------|-------------|
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
### 4.3 术语约定
| 术语 | 含义 | 语法 |
|------|------|------|
| **类 / 本体** | 诗人的模式 | `# 诗人` |
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
### 4.4 多诗人怎么办
```markdown
# 李白 = > 诗人
# 杜甫 = > 诗人
# 王维 = > 诗人
```
- 每个个体是一个单体类;项目类索引登记它们;
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
- 这是「命名个体注册表」,不是运行时实例集合;
- 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。
---
## 5. 与 EKC 的映射
| 层 | EKC 层 | 节点/边 |
|----|--------|---------|
| L0 原始语料 | Repository / sources | `documented_by` / `derived_from` |
| L1 本体 | Capability / Schema | `# 诗人` class 节点 |
| L2 知识个体 | Knowledge / Symbol | `# 李白` class 节点 + `##` fact 节点;`specializes` 边 → `诗人` |
| L3 调用面 | Symbol / Capability | `[]()` 链接 → `calls` 边;LinkInfo |
| L4 Agent | Agent / Context Pack | `find`/`reuse`/`link.resolve` |
**新增边(建议)**:
- `specializes`:`# 李白 = > 诗人`(语法上是继承;知识语义上是 is-a);
- `derived_from`:fact → 原始语料;
- `calls`:调用文档 → `李白.出生年份`;
- `has_fact`:`# 李白` → `## 出生年份`。
EKC 现有 `depends_on`/`uses`/`implements`/`documented_by` 可以复用;`specializes` 建议新增。
---
## 6. 还原 / 验证(L2 → L0)
「可执行知识能还原验证回原始知识」需要三件事:
### 6.1 出处是数据,不是注释
```markdown
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
- `来源` 列指向原始语料(路径 + 标题/锚点);
- 也可以放 frontmatter `sources:`;
- `check` 验证来源存在;`verify` 验证值/引文一致(能自动化的部分)。
### 6.2 可还原的渲染
- `view` 把 `# 李白` 渲染成「知识文档」:字段 + 值 + 来源;
- `catalog` 生成 OKF `Fact` 页,`resource:` 指向 `.mq.md`;
- 渲染结果与原始语料可人工/机器对照;
- 这不是新语法,是 view/catalog 的输出。
### 6.3 漂移检查
| 诊断 | 触发 |
|------|------|
| `knowledge.source_missing` | 事实没有来源 |
| `knowledge.source_dangling` | 来源路径/锚点不存在 |
| `knowledge.value_mismatch` | 事实值与来源引文不一致(可自动判断时) |
| `knowledge.schema_mismatch` | `# 李白` 字段与 `# 诗人` 不匹配 |
| `knowledge.fact_drift` | 原始语料变了,知识未复核 |
这些是**工具诊断**,不是语法。
---
## 7. 调用面:智能体如何使用
```markdown
# main
用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
```
- `view` 显示:`李白.李白的出生年份` → `701` → 来源 `corpus/libai.md#出生年份`;
- `check --json` 返回 LinkInfo(class/function/value/source);
- agent 通过 `link.resolve` / `find` 取到值 + 出处,回答时可引用来源;
- `run` 加 `print` 才输出;正文链接不执行,保证叙述安全。
**这就是「调用面」**:不是自然语言猜,而是可解析、可验证、可引用的类调用。
---
## 8. 反例与边界
| 场景 | 用 A 单体类 | 说明 |
|------|-----------|------|
| 李白、杜甫、王维 | 三个单体类 | 类索引;命名个体 |
| 同一诗人的多个版本 | 多个事实/来源,或子个体 | 版本是事实维度,不是实例 |
| 需要运行时状态(可变对象) | `> 李白` 构造实例 | 运行时实例仍存在,但与知识个体分离 |
| 上千个诗人 | 类索引/表驱动注册 | v2.2 优化;语法不变 |
| 需要 `instanceof` | `# 李白 = > 诗人` 的 `specializes` 边 | 知识语义;不是运行时 `_type` |
| 需要多继承 | 现有不支持 | 不在本设计范围 |
---
## 9. 决策建议
1. **v2.1 采用 A(单体知识类)**:`# 诗人` + `# 李白 = > 诗人` + `##` 事实 + `[]()` 类调用;零新语法。
2. **术语冻结**:`# 李白 = > 诗人` 叫「知识个体/单体类」,不叫「实例」;`> 诗人` 才是运行时实例。
3. **补类函数与类索引**:不使用 `self` 的 `##` 是类函数;项目类索引解析跨文档 `李白`。
4. **补出处/验证**:`来源` 列或 `sources:`;`check`/`verify`;`view`/`catalog` 可还原。
5. **EKC 边**:`specializes` / `derived_from` / `calls` / `has_fact`。
6. **保留 B/C 作为未来**:如果真需要运行时实例/个体声明,再评估 `# 李白 : 诗人` 或实例注册表;不在 v2.1 引入。
### 9.1 备选:frontmatter 个体声明(零语法,但换元数据)
如果不想把 `= >` 的继承语义借给「个体」,可以用 frontmatter 标记:
```markdown
---
type: Individual
class: 诗人
id: libai
---
# 李白
## 出生年份
*701*
```
| 维度 | 单体类 A | frontmatter 个体 |
|------|----------|------------------|
| 可见性 | `# 李白 = > 诗人` 一眼可见 | 类型在 frontmatter,正文只看到 `# 李白` |
| 语法 | 现有 `= >` | 现有 frontmatter,无新标记 |
| 语义纯度 | 继承/特化 | 明确 individual-of |
| EKC | class + specializes | individual + instance_of |
| 代价 | 术语「个体」不是「实例」 | 两套 is-a 表达(`= >` 与 `class:`)需要约定 |
**建议**:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter `type: Individual`,并规定「`= >` 只用于类-类,个体用 frontmatter」。
---
## 10. 结论
> **三层/四层模型自洽;「实例化」是唯一需要修正的词。**
> 在 Marqdo 的语法里,`# 李白 = > 诗人` 是**继承/特化**,不是运行时实例;
> 把它用作**单体知识类**,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、`李白.出生年份` 可调用」。
> 这正是 EKC 的「文档即知识、知识可执行」:**类是本体的地址,单体类是知识个体的地址,`[]()` 是调用面。**
---
## 附录 A:一页对照
```markdown
# L1 本体
# 诗人
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# L2 知识个体(单体类)
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
| 层 | 语法 | 语义 |
|----|------|------|
| L0 | `.md` 原文 + 来源 | 不可执行 |
| L1 | `# 诗人` + 字段表 | 类/模式 |
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
| L3 | `[描述](类.函数)` | 类调用/链接 |
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
## 附录 B:与现有文档的关系
| 文档 | 关系 |
|------|------|
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
+414
View File
@@ -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 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。
+29
View File
@@ -0,0 +1,29 @@
# 三层归属与准入戒律(layers)
| | |
|---|---|
| 状态 | **Accepted · 准入制度(问题一落地)** |
| 日期 | 2026-09-22 |
| 相关 | [core-surface.md](core-surface.md)(核心表面守卫)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.2 |
> **目的**:语言核心保持小——**Language / Runtime / Document 三层分明,生态功能不淹没语言身份**。本制度是机制不是宣言:违反即 CI 红 / PR 不评审。
## 1. 三层归属表
| 层 | 内容 | 仓库位置 |
|----|------|----------|
| **Language** | 标记映射、词法/行分类、AST、语义、升参、契约检查器、诊断 | `src/lex/` `src/parse/` `src/ast.rs` `src/interp.rs` `src/diagnostics.rs`(及 `contract`/`check`)· 宪法 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [core-surface.md](core-surface.md) |
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema / mcp CLI、字节码后端 | `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view/` `src/debug/` `src/builtin.rs` `src/bytecode/` |
| **Document** | 知识单元、AI skills、示例、官方扩展、用户站 | `*.mq.md` `skills/` `ext/` `public/` `examples/` `doc/` |
## 2. 准入戒律
1. **先填层归属**:任何新特性提案(issue / PR / 设计文档)必须先声明进哪层;未填 = 不评审。
2. **Language 层变更 = ADR**:新增核心标记必须有 `doc/adr/` 编号 + 「为什么现有标记不够」+ [core-surface.md](core-surface.md) 增行 + 样例 + `CORE_CONSTRUCTS` 同步(缺任一 → CI 守卫红)。
3. **核心计数只许持平或下降**:每个 release 的核心标记计数不得增长;确需增长即触发 Language 层复盘(ADR 里写明不可替代理由)。
4. **默认进 ext**:能用扩展、stdlib、插件解决的,一律不进核心。
5. **CHANGELOG 单列「核心表面 Δ」**:每个 release 写明增删(无 Δ 写「无」);发版 checklist(`.cursor/skills/marqdo-release/SKILL.md`)含此步。
## 3. PR 模板
`.github/PULL_REQUEST_TEMPLATE.md` 含「层归属」必填项与「核心表面」勾选——与本制度一一对应。
+218
View File
@@ -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 全角冒号问题一致考虑。
+799
View File
@@ -0,0 +1,799 @@
# 链接语法:命名载荷、类-函数调用与可执行知识
| | |
|---|---|
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
| 日期 | 2026-10-23 |
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
---
## 0. 设计声明
### 0.1 一句话
> **`[]()` 本身不制作新语法。**
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
它始终同时有三种投影:
| 投影 | 规则 | 目的 |
|------|------|------|
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
例如:
```markdown
**name = [订单收件人](at(订单, "收件人"))**
**gross = [含税金额](金额 * (1 + 税率))**
- [逐个订单行](遍历 订单.行 为 行)
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
```
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
不能要求每一次取元或循环都伪造来源表。
这才同时实现三件事:
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
完整的跨文件闭环、稳定寻址和层次投影见
[executable-knowledge-system.md](executable-knowledge-system.md)。
### 0.2 三个「不新增」
| 不新增 | 说明 |
|--------|------|
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
**本文定义四件事**:
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
### 0.3 原始意图
第一个可执行文档:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白出生于*某年*
```
在 Marqdo 里:
- `# 李白` = **类**;
- `## 李白的出生年份` = 该类下的**函数**;
- `李白.李白的出生年份` = **类调用这个函数**。
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
第二个文档:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
这不是两套语法,而是同一套语法的两种呈现:
- `**year = 李白.李白的出生年份**` 是代码;
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
### 0.4 当前实现的偏差
v2.0.0 把「类-函数」收窄成了「实例方法」:
| 设计意图 | 当前实现 | 后果 |
|----------|---------|------|
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
### 0.5 三个统一
| 统一 | 链接语法的作用 |
|------|---------------|
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
形式化:
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
---
## 1. 术语
| 术语 | 定义 |
|------|------|
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
| **类(class)** | `# 名称`;知识命名空间/类型 |
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
---
## 2. 语义
### 2.1 描述永不执行,载荷唯一执行
```text
[label](expr) ≡ expr
```
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
- `()` 是唯一执行体;空 `()` 值为 `None`;
- `label.missing` / `label.empty_payload` 仍是结构诊断;
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
### 2.2 `#` 是类,`##` 是函数
| 标记 | 语义 |
|------|------|
| `# 名称` | 类/知识命名空间;正文是构造体 |
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
| `###` … | 更深层函数/子命名空间 |
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
**函数与实例的关系**:
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
- 类函数不执行 `# 类` 的构造体,不产生实例;
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
### 2.3 `类.函数` 是类调用
| 写法 | 语义 |
|------|------|
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
### 2.4 跨文档:模块身份优先,类索引只做发现
链接目标可以跨文档。可运行代码的解析顺序:
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
2. **当前文档类/函数**:`# 类` / `## 函数`;
3. **已 import 的模块**:现有 `import bind:target` 绑定;
4. **内置/插件**。
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
按名加载机制:
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
- 排除 `# main`;
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
- 索引只在项目根内(`--fs-root`),不访问网络;
- 索引可缓存(按文件 mtime)。
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
### 2.5 `()` 与 `**代码**` 同权
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|------|-----------|----------------------|
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
| 变量/插值 | ✅ | ✅ |
| 本地调用 `callee(args)` | ✅ | ✅ |
| 类调用 `类.函数` | ✅ | ✅ |
| 实例调用 `obj.函数` | ✅ | ✅ |
| 表/列/映射 | ✅ | ✅ |
| 返回值 | Value | Value(同类型系统) |
| 副作用 | 可 | 可(受沙箱限制) |
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
**代码链接 vs 正文链接**:
| 上下文 | `[]()` 行为 |
|--------|-------------|
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
| 标题 / frontmatter | 不执行;按普通文本处理 |
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
要终端输出,就把同一段代码放进代码链接并加 `print`。
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
### 2.6 输出:值知识必须有值,过程知识必须声明效果
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
```markdown
## 李白的出生年份
*701*
```
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
- `run` 得到 `None`;
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
- view 显示「无返回值」;
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
### 2.7 view 显示调用信息
**代码链接**:
```text
┌─ 链接 ─────────────────────────────┐
│ `year` = [李白的出生年份] │
│ → 李白.李白的出生年份 │
│ class 李白 · function · () -> number │
│ value 701 · ok │
└────────────────────────────────────┘
```
**正文链接**:
```text
用户想要知道李白的出生年份,我们要告诉用户 701。
↑
悬浮:李白的出生年份 → 李白.李白的出生年份
class 李白 · () -> number · value 701
```
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
- Execution 模式:显示值;
- 点击目标:跳到目标文档/类/函数;
- 错误:错误 chip + 诊断码 + 修复建议;
- 无返回值:显示「无返回值」,不伪造值。
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
### 2.8 编译器返回 LinkInfo
每个 `[]()` 产出:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
"outputs": [{"name": "行", "type": "订单行"}],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
],
"effect": "pure",
"value": null,
"fingerprint": "sha256:…"
}
```
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
`LinkInfo` 至少要区分三类状态:
| 层 | 要回答的问题 | 典型状态 |
|------|-------------|----------|
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
`link.unresolved` 或副作用越权。
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
### 2.9 链接既是步骤节点,也是图边
```text
定价.订单定价 --contains--> step#逐个订单行
step#逐个订单行 --observes--> 订单.行
step#逐个订单行 --calls--> 定价.订单定价.含税价
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
```
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
`narrates` 等边的一种;
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
- `catalog` 模块页显示「链接到/被链接」;
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
都可精确找出受影响的代码步骤和句子;
- view 的 Structure 面板显示上下游。
### 2.10 安全
| 风险 | 规则 |
|------|------|
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
| 循环 | 链接图检测环;运行时深度/步数上限 |
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
### 2.11 可复现(可选,生成物)
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
- 这是生成物/工具,不是新语法。
### 2.12 知识分层:类、知识个体、调用面
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
```markdown
# 诗人 # L1 本体:类/模式
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# 李白 = > 诗人 # L2 知识个体:单体知识类
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
**术语**:
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
- `> 李白` 才是运行时实例(map + `_type`);
- `李白.李白的出生年份` 是类调用;
- `[]()` 是调用面,不新增语法。
**为什么不在 v2.1 引入运行时实例作为知识实体**:
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
- EKC 的节点是文档/类/函数,不是运行时 map;
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
---
## 3. 当前实现 vs 目标
### 3.1 已具备(v2.0.0)
| 能力 | 状态 | 证据 |
|------|------|------|
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
| view 本地链接卡 | ✅ | `render.rs:1227` |
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
### 3.2 缺失(v2.1 目标)
| 能力 | 状态 | 影响 |
|------|------|------|
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
| LinkInfo | ❌ | 编译器不返回链接信息 |
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
### 3.3 为什么旧例子失败
| 层 | 旧例子 | 设计要求 |
|----|--------|---------|
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
| 类索引 | 无 import | 项目类索引解析 `李白` |
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
| 静态检查 | 不解析 | `check` 报 `link.*` |
---
## 4. 编译器 / view / CLI 表面
### 4.1 `check --json`
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
- 不执行目标函数;
- `link.ok` 可作 info,不阻断;
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
### 4.2 MLSP
| method | 作用 |
|--------|------|
| `link.resolve` | 解析一个链接 → LinkInfo |
| `links.list` | 列出文件/项目所有链接 |
| `links.graph` | 返回链接图 |
| `link.check` | 校验一个链接 |
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
### 4.3 `catalog` / EKC
- `catalog` 增加 `links:` 段与链接图;
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
### 4.4 `links` CLI(可选)
```bash
marqdo links list [PATH] --json
marqdo links resolve FILE:LINE:COL
marqdo links graph [PATH] --json
marqdo links lock [PATH] # 可选,生成指纹锁
```
### 4.5 诊断
| code | 级别 | 触发 | 建议 |
|------|------|------|------|
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
| `label.missing` | error | 空描述 | 写一句人话 |
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
---
## 5. 开发指导
### 5.1 里程碑
| 阶段 | 目标 | 交付 |
|------|------|------|
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
### 5.2 文件级改动
| 文件 | 改动 |
|------|------|
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
| `src/catalog.rs` | links 段/图 |
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
| `src/main.rs` | `links` 子命令;check 选项 |
| `README.md` | 链接语法章节(不新增语法) |
| `doc/README.md` | 登记本文/示例 |
| `examples/link-syntax/` | 用户原始示例 + compat |
### 5.3 关键实现点
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
4. **`[]()` 分类**:
- payload 是类/函数路径 → 知识链接;
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
- 正文 `[]()` → 正文链接(view/check)。
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
**最小改动原则**(证明「不新增语法」):
| 层 | 现状 | v2.1 改动 |
|----|------|-----------|
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
### 5.4 测试
| 层 | 用例 |
|----|------|
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
| 双后端 | tree + bytecode 一致 |
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
### 5.5 迁移
- `#`/`##` 的实例调用保持;
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
- `类.函数` 是新增解析,不改变旧调用;
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
---
## 6. 示例
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
### 6.1 用户原始示例(目标)
`libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白的出生年份是公元 701 年。
*701*
```
`main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
- `check --json`:LinkInfo(target/class/function/signature/status);
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
### 6.2 加 print(终端输出)
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 6.3 带参数
```markdown
# main
**greeting = [问候](李白.问候("世界"))**
> print text=`greeting`
```
### 6.4 当前兼容写法(v2.0.0)
```markdown
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
---
## 7. 验收标准
| # | 验收 | 判定 |
|---|------|------|
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
| 5 | 同名类 → `link.ambiguous` | 反例 |
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
| 7 | 无返回值 → `link.no_value` | 反例 |
| 8 | EKC 出现 `calls` 边 | graph.json |
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
**一句话验收**:
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
---
## 8. 风险与开放问题
| 风险 | 说明 | 缓解 |
|------|------|------|
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
**开放问题**:
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
---
## 9. 结论
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
v2.1 要补的是**语义**,不是语法:
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
2. `类.函数` → 类调用;跨文档用项目类索引;
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
**一句话**:
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
---
## 附录 A:一页速查
```markdown
# 类
## 函数
*701*
# 代码链接(求值)
**year = [出生年份](李白.李白的出生年份)**
> print text=`year`
# 正文链接(view/check 解析,run 不执行)
李白出生于 [李白的出生年份](李白.李白的出生年份)。
# 带参类调用
**g = [问候](李白.问候("世界"))**
```
| 写法 | 执行 | 用途 |
|------|------|------|
| `**类.函数**` | ✅ | 普通代码/调用 |
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
| `[描述](url)` | ❌ | 普通导航 |
## 附录 B:与旧文档的关系
| 旧文档 | 关系 |
|--------|------|
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |
+4 -1
View File
@@ -215,7 +215,9 @@ v0.3:
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
| ` ```lang ` | 外联(不变) |
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
@@ -616,3 +618,4 @@ FnDef.params:
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
+1 -1
View File
@@ -130,7 +130,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
## 5. Frontmatter 与跨文件
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
文件头 `---` 对为 **Artifact Metadata**。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。其它 `key: value` 可为字面量或 **Binding**(`${env.NAME}` 等,加载期解析);见 [binding.md](binding.md)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
+40 -27
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
| 日期 | 2026-08-13 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
@@ -16,9 +16,9 @@
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
---
@@ -29,8 +29,8 @@
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import` / `导入`。
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import:` / `导入:`。
### 2.2 非目标
@@ -54,27 +54,38 @@
### 3.2 导入句法(frontmatter)
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
```yaml
---
import:
utils: utils.mq.md
json: lib/json.mq.md
fmt: time.format
---
```
| 含义 | 英文 | 中文 |
|------|------|------|
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
规则:
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
- `:` 右侧 `target`:
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
- 映射值 `target`:
- 以 `.mq.md` 结尾 → **文件导入**;
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
- 同一文件不得同时出现 `import:` 与 `导入:`。
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
### 3.3 废除的旧规则
不再支持:
- 一行式 `import bind:target` / `导入 bind:target`;
- 省略绑定名时用文件名茎作库名;
- 导入侧 `as` / `作为`;
- 独立关键字 `use` / `使用`。
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
json: lib/json.mq.md
---
# main
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
import:
time: lib/time.mq.md
fmt: time.format
---
# main
@@ -153,10 +166,11 @@ import fmt:time.format
```markdown
---
import time:lib/time.mq.md
import writeback:lib/writeback.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
writeback: lib/writeback.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
---
# main
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
| 旧 | 新 |
|----|----|
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
| `import fmt`:time.format
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
| `import fmt:time.format` | `import:` → `fmt: time.format` |
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧 `>` 导入过渡开关。
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
---
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
## 8. 实现要点
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
| 阶段 | 内容 |
|------|------|
| M1+M2 | 点号路径 + 短名 — 已落地 |
| **Import 句法** | 统一 `import bind:target` — **本波次** |
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
---
## 9. 决议摘要
1. 导入 = `import bind:target`(`导入` 等价)。
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
+531
View File
@@ -0,0 +1,531 @@
# 文档会话(View Cells)
| | |
|---|---|
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
| 日期 | 2026-10-17 |
| 层 | Runtime + Document(view 服务端 / 交互单元) |
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无(读取既有 AST 与表格) |
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
---
## 1. 目标
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
5. **多语言**:命名内核 + 显式状态桥。
6. **可复现**:Run All / journal / dirty / stale / replay。
---
## 1.1 实施状态(2026-10-18)
| 能力 | 状态 | 位置 |
|---|---|---|
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
| `kernel/interrupt` | 待做 | — |
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
| cell step | ✅ | 同上 |
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
| writeback 集成 | 待做 | `writeback` |
| replay / 持久化 | 待做 | — |
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
| Node 会话 | ✅ | 同上 |
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
---
## 2. 两个执行面(不是两个 CLI 模式)
### 2.1 Program execution(规范)
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
- 结果:可复现;是文档的“真理”。
### 2.2 View cells(交互)
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
- 状态:内核持久;可切换、重启、单步。
- 结果:默认临时显示;可显式 writeback。
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
### 2.3 两者关系
```text
.mq.md
/ \
Program run View cells
(canonical) (interactive)
\ /
Document Session
├── cell index
├── kernel registry
├── journal
└── state panel
```
- 共享 cell index 与 kernel registry。
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
---
## 3. 文档会话模型
```text
DocumentSession
├── doc_path / doc_hash
├── cells: Vec<Cell>
│ ├── id (name / anon@line)
│ ├── name (binding)
│ ├── lang
│ ├── line_start / line_end
│ ├── source_hash
│ ├── kernel (resolved)
│ └── status: never | clean | dirty | stale | error | running
├── kernels: KernelRegistry
│ ├── name → ForeignSession
│ └── default per language
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
├── journal: Vec<ExecutionRecord>
├── created_ms / last_active_ms
└── surface: program | view
```
### 3.1 Cell
- 只有**绑定名**的代码围栏才是 cell:
```markdown
`加载` =
```python
...
```
```
- 未绑定围栏仍是叙述,不是 cell。
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
- 同名 cell 重复 → 诊断;会话表按名字引用。
- `source_hash` 用于 dirty 判断。
- `line_start/line_end` 用于定位;编辑后重建索引。
### 3.2 Cell index 构建
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
3. 记录 name、lang、source、span、source hash。
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
6. 生成执行顺序:
- 有会话表 → 行顺序;
- 无 → 文档顺序。
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
### 3.3 Kernel registry
- key:`<document_id>:<kernel_name>`。
- 默认:`default:python`、`default:node`,按需启动。
- 命名:来自 `内核表`,首次执行时启动。
- 状态:`idle | starting | ready | busy | dead`。
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
- 关闭:kill + 移除。
### 3.4 Value store(Marqdo 侧会话值)
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
- 用途:
- 状态面板显示;
- Push 到内核;
- 作为 `session_set` 的值来源;
- journal 记录。
### 3.5 Journal
每次执行追加一条:
```json
{
"seq": 3,
"cell": "汇总",
"kernel": "分析",
"lang": "python",
"ok": true,
"code": 0,
"ms": 42,
"source_hash": "…",
"stdout_hash": "…",
"result_hash": "…",
"started_ms": 1760000000000,
"error": ""
}
```
用途:
- 执行序号 / 顺序;
- dirty/stale 判断;
- replay;
- 视图显示;
- 调试(“为什么这个 cell 有值”)。
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
---
## 4. 执行语义
### 4.1 操作
| 操作 | 语义 |
|---|---|
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
| **Run above** | 按会话顺序执行到选中 cell(含) |
| **Run all** | 按会话顺序执行全部;可选 `restart` |
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
| **Step next statement** | Marqdo 语句级单步(DebugController) |
| **Restart kernel** | kill + 重建;cell 状态 `never` |
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
| **Reset session** | 关闭所有 kernel,清 journal / value store |
### 4.2 执行一个 cell
```text
resolve cell -> resolve kernel
-> ensure kernel ready
-> [送入?] 显式 bridge 由文档代码/UI 负责
-> foreign.session_eval(kernel, source, input?)
-> record -> update cell status
-> [取回?] 由文档代码/UI 负责
-> journal append
-> view update
```
- 默认 cwd = 文档目录;env = kernel env。
- 输出:stdout / stderr / result / ms / truncated。
- 失败:cell 状态 `error`;journal 记录;不自动重试。
- 同一 kernel 串行;UI 禁用并发 Run。
### 4.3 Step 语义
| 类型 | 行为 |
|---|---|
| **Cell step** | 执行下一个会话 cell;状态保留 |
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
| **Foreign line step** | 不做;未来 DAP |
- Cell step 是 view cells 的主单步。
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
### 4.4 中断
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
- 不允许“中断后继续用同一 kernel”除非确认状态。
### 4.5 并发
- 同一 kernel:一次一个 cell。
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
- 并发上限沿用 foreign(32)。
---
## 5. 状态桥(会话层)
### 5.1 显式 API
文档代码:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
### 5.2 状态面板
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
- 操作:
- Push:选 Marqdo 值 → kernel 变量;
- Pull:选 kernel 变量 → value store / 显示;
- Refresh;
- 复制名称/值。
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
### 5.3 自动镜像
- v2 不做。
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
### 5.4 类型
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
- 大对象:v2 显示摘要;传输用文件/DB。
- 未来:Arrow / Parquet / 共享文件句柄。
---
## 6. Dirty / Stale / Run All
### 6.1 定义
| 状态 | 条件 |
|---|---|
| `never` | 未执行 |
| `clean` | 上次执行成功后源码未变 |
| `dirty` | 源码 hash 变了 |
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
| `error` | 上次执行失败 |
| `running` | 正在执行 |
| `unlisted` | 不在会话表 |
### 6.2 依赖
- v2:会话表行顺序 + 简单规则:
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
- 若 kernel 重启,全部 `never`。
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
### 6.3 Run All
- 默认:按会话顺序执行;可选 `restart=true`。
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
- 未重启时:显示“当前 kernel 有历史状态”警告。
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
### 6.4 Replay
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
- 比较 stdout/result hash;
- 输出 divergence 报告。
- v2 可选;至少保留 journal 以便未来实现。
---
## 7. 输出与文档
### 7.1 默认
- View cells 输出只在 view 中显示;不写 `.mq.md`。
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
- 不写 execution_count 到文档。
### 7.2 显式 writeback
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
- 可选:
- 单 cell 写回;
- 全部写回;
- 只写回文本/数值,不写复杂对象。
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
### 7.3 不写回
- 避免 Jupyter 的 `.ipynb` 输出噪声。
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
---
## 8. View 交互
### 8.1 工具栏
```text
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
[State] [Journal] [Writeback ▾]
```
### 8.2 每个 code card
```text
`加载` python · kernel 分析 · run #3 · 42ms · clean
[Run] [Step] [Kernel ▾] [State] [Copy output]
```
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
- 输出区:stdout / stderr / result / 截断提示。
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
- `Step` = 执行此 cell(cell step)。
### 8.3 状态面板
- Marqdo / kernel 分栏。
- Push/Pull。
- Secret 打码。
- 大对象摘要 + 复制 JSON。
### 8.4 Journal 面板
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
- 点击跳转 cell。
- 导出 JSON。
### 8.5 键盘
- `Ctrl/Cmd + Enter`:Run cell。
- `Shift + Enter`:Run cell + 下一个。
- `Alt + Enter`:Run cell + 插入?不做。
- `F10`:Step statement(与 debug 一致)。
- `F5`:Run All。
---
## 9. 服务端 API
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
| POST | `/api/session/cell/run` | 执行指定 cell |
| POST | `/api/session/cell/step` | 执行下一个 cell |
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
| POST | `/api/session/state/pull` | kernel 变量 → value store |
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
| POST | `/api/session/journal` | 执行日志 |
| GET | `/api/session` | 当前会话摘要 |
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
---
## 10. 生命周期与持久化
- Session key:`<root>/<doc_rel>`;每个文档一个。
- 打开:解析、建 cell index、按需启动 kernel。
- 空闲超时:默认 30 分钟关闭(可配置)。
- 文档关闭 / 服务退出:kill 所有 kernel。
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
- 持久化(可选):
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
- 默认 git 忽略;
- 不持久化进程状态 / 大对象。
- 不把 session 状态写进 `.mq.md`。
---
## 11. 安全
| 项 | 策略 |
|---|---|
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
| cwd | 文档目录 / `fs_root`;越界拒绝 |
| 输出 | 有界;截断标记 |
| 超时 | cell 级;进程组 kill |
| 中断 | 杀进程组;kernel 标记 dead |
| Secret | 状态面板打码;JSON 不默认暴露 |
| 未信任文档 | 不自动打开会话;必须显式 Run |
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
| writeback | 显式;路径沙箱;不自动改文档 |
---
## 12. 测试
### 12.1 服务端
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
- 会话:open/close/reload;kernel 启动/重启/中断。
- cell run:状态机 never→running→clean/error;dirty/stale。
- step:cell step 顺序;statement step 与 debug 联动。
- state:push/pull/list;Secret 打码;大对象摘要。
- journal:顺序、hash、失败。
- 并发:同 kernel 串行;不同 kernel 并行。
- 安全:exec=false 拒绝;cwd 越界;超时。
### 12.2 金样例
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
- `tests/notebook/step.mq.md`:cell step 顺序。
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
- `tests/notebook/invalid-*.mq.md`:诊断。
- 依赖:node 为主,python 条件跳过。
### 12.3 UI
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
- 不引入前端测试框架;用服务端 API + 静态检查。
---
## 13. 与 Jupyter 对照
| 维度 | Jupyter | Document Session |
|---|---|---|
| 源 | `.ipynb` | `.mq.md` |
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
| 单步 | cell | cell + statement |
| 复现 | 手动 | Restart & Run All + journal + replay |
| Git | 输出/计数噪声 | 源码干净;输出显式 |
| 知识 | 无 | OKF / catalog |
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
---
## 14. 实现顺序(D 层)
| 阶段 | 内容 |
|---|---|
| D0 | 设计/语法/决策文档(本文件) |
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
| D4 | statement step 接入;dirty/stale;writeback |
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
---
## 15. 明确不做(v2)
- Foreign line-level step。
- 自动镜像变量。
- 跨文档共享 kernel。
- 全进程快照。
- 自动执行 cell。
- 把 session 状态写进 `.mq.md`。
- 前端 SPA 框架重写;沿用现有 HTML/JS。
+305
View File
@@ -0,0 +1,305 @@
# 文档原生 view cells 语法
| | |
|---|---|
| 状态 | **Decided;D1 解析已实现** |
| 日期 | 2026-10-17 |
| 层 | Document(读取约定) + Runtime(校验) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) |
| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 |
> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。
---
## 1. 为什么不用围栏元数据
Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**:
- 读者看到的是一行属性,不是一段知识;
- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图;
- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行;
- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。
Marqdo 的选择:
> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。**
这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。
---
## 2. 两个约定数据表
它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列:
```markdown
# main
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 读取与清洗数据 |
| 绘图 | python | | 独立环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
```
为什么是“绑定的表”,不是 `# 外联内核` 对象:
- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。
- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。
- View / 文档会话读取 AST 中的绑定值,不需要执行文档。
- 解析器零改动。
### 2.1 `内核表` / `kernels`
| 列 | 必填 | 含义 |
|---|---|---|
| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) |
| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … |
| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 |
| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 |
规则:
- 名称在文件内唯一;重复 → 诊断。
- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。
- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。
- 没有 `内核表`:每种语言自动一个 `default` 内核。
- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。
### 2.2 `会话表` / `session`
| 列 | 必填 | 含义 |
|---|---|---|
| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** |
| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 |
| `说明` / `Notes` | 可选 | 给人读的一句话 |
规则:
- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。
- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。
- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。
- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。
- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。
- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。
- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。
- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。
### 2.3 为什么放在 `# main` 体内
- `# main` 是入口;cell 绑定与元数据表同一作用域。
- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。
- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。
- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。
---
## 3. 完整示例
````markdown
# main
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
一个绘图单元在隔离的 `绘图` 内核里运行。
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 数据读取与聚合 |
| 绘图 | python | | 独立绘图环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
`加载` =
```python
import json
rows = [
{"city": "上海", "value": 3},
{"city": "北京", "value": 5},
]
print(json.dumps(rows, ensure_ascii=False))
```
`清洗` =
```python
rows = [r for r in rows if r["value"] > 0]
```
`汇总` =
```python
from collections import Counter
counts = Counter(r["city"] for r in rows)
print(dict(counts))
```
`绘图` =
```python
print("plot-ready")
```
`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。
需要共享时,用 Marqdo 显式把值送过去:
**> foreign.session_set id="绘图" name="rows" value=`rows`**
````
读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。
---
## 4. 自动模式(没有表)
### 4.1 没有任何约定表
````markdown
# main
`分析` =
```python
x = 41
```
`结论` =
```python
print(x + 1)
```
````
解释:
- 两个 cell 都是 `python`;
- 自动使用 `default:python` 内核(一个);
- 按文档顺序执行;
- 共享 `x`。
现有文档不需要改一行就能在 view 里 cell-by-cell 运行。
### 4.2 只有内核表
- 所有 cell 按文档顺序;
- 每种语言解析到该语言的 `default` 内核;
- 命名内核只有被 `会话表` 引用时才使用。
### 4.3 只有会话表
- `内核` 列只能写语言 id;
- 每个语言 id 解析到该语言默认内核;
- 未列出的 cell 不入会话。
---
## 5. 可读性规则(语法评审标准)
新增/修改任何 cell 表约定,必须满足:
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。
4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。
5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。
6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。
7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。
8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。
10. **无表也能跑**:约定表是增强,不是前置条件。
---
## 6. 诊断规范
| 情况 | 诊断(中文示例) | 修复建议 |
|---|---|---|
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 |
| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 |
| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 |
原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。
---
## 7. 与 program execution 的关系
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
- 两者可以并存:
- 文档用表描述“交互时怎么跑”;
- `# main` 用显式调用描述“CI 时怎么跑”。
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
这样避免把“执行计划”变成第二套程序语义。
---
## 8. 状态桥的语法边界
v2 **不**为状态交换新增表格/注释。原因:
- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
- v2 先用显式 API,把时序讲清楚:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要;
- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。
这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。
---
## 9. 未来扩展(不承诺进 v2)
1. `共享表`:
`| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。
2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。
3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。
4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。
5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。
---
## 10. 实现落点
| 逻辑 | 位置 |
|---|---|
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
| 只读展示 | view Structure:表渲染成普通表格 + 徽标 |
| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) |
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
@@ -0,0 +1,426 @@
# 遮蔽描述与两级检索:内置词表做范例,参数做扩展
| | |
|---|---|
| 状态 | **Accepted · 实施中**(与 [occlusion-syntax.md](occlusion-syntax.md) 同步) |
| 日期 | 2026-10-22 |
| 关键决策 | ①`[]` 是自由描述,不执行 ②**两级词表**:内置=范例/默认,参数=扩展 ③空载荷**一律 warning** ④工程化写进 README,提示词同步更新 |
| 前置 | [occlusion-syntax.md](occlusion-syntax.md) |
---
## 0. 五条定调
1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** 编译器**不解析**,只做**检索**。
2. **两级词表**:
- **内置词表 = 范例 + 默认检索集**(零配置可用;给 LLM 一个稳定范式)
- **参数 = 扩展/覆盖**(`--grep 任意词`,项目自己的说法照样能搜)
3. **空载荷一律 warning**:`()` 为空说明"这段遮蔽里没有可执行内容",写 `None` 即消除。
4. **强力推荐 LLM 申报**:写不了真接口就"申报",别"假装"。提示词同步更新。
5. **工程化实践写进 README**,不另造文档。
一句话:
> **描述给人读;内置词给个范式;参数给自由;空着不写会被提醒。**
---
## 1. 为什么要允许「假接通」
模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。
| 处理方式 | 结果 | 问题 |
|---------|------|------|
| **A 禁止**("不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 |
| **B 放任** | 静默假功能 | 文档撒谎,没人知道欠了多少 |
| **C 申报**(本方案) | 允许,但写进描述 | 代码照跑;欠据可数、可查 |
C 的关键:**不改道德要求,改激励**——申报比伪造省力,且申报后代码照样跑。
---
## 2. `()` 内部语法定稿
### 2.1 取元
| 语义 | 写法 |
|------|------|
| Map 取成员 | `at(表, 键)` |
| List 第 n 项(1-based) | `at(列表, 1)` |
| 缺键取默认(不崩) | `get(表, 键, 默认值)` |
### 2.2 调用
| 形态 | 写法 |
|------|------|
| 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) |
| 具名实参 | `计税(档位=2, 金额=100)` |
| **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 |
| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` |
实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。
**`(` 是明确分隔符**——这是缺陷 D8 的结构性解法。
### 2.3 循环
```markdown
- [从篮子里取出的每个果子](遍历 篮子 为 果)
```
### 2.4 空载荷:**一律 warning**
| 写法 | 结果 |
|------|------|
| `[功能,开发中]()` | ⚠️ `label.empty_payload` |
| `[功能,开发中](None)` | ✅ 无警告 |
| `[功能,开发中](json.parse text="[]")` | ✅ 无警告 |
**为什么一律报**:空 `()` 就是"什么都没写"。哪怕桩也该说明返回什么——
`None` 也是答案,下游能据此判断。
**为什么不会造成存量噪音**:遮蔽语法是新形式,**今天仓库里一处都没有**。
> 可调旋钮(**非默认**):若实际使用中觉得"已申报的桩也报警"太吵,
> 可开启「命中内置词表则降为 hint」。默认关闭——遵守"空载荷必须被看见"。
---
## 3. 两级词表
### 3.1 第一级:内置词表(范式 + 默认检索集)
**它是什么**:编译器内置的一张**小词表**,用途三个——
| 用途 | 说明 |
|------|------|
| **范式** | 给 LLM 一个稳定写法:不知道怎么写状态,就照这个词表写 |
| **默认检索集** | `marqdo labels pending` 零配置即可用;跨项目可比 |
| **默认豁免集** | 命中这些词的遮蔽默认跳过 stale(见 §6.1) |
**它不是什么**:**不是语法**。写不写、怎么写都不影响解析与执行。
### 3.2 内置词表(v1)
| 组 | 关键词(子串任一命中即算) | 计入 |
|----|--------------------------|------|
| **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | pending |
| **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | pending |
| **演示** | `示例` `样例` `demo` | demo |
| **不稳** | `实验` `试验` `experimental` | experimental |
| **将删** | `废弃` `弃用` `deprecated` | deprecated |
| **待核** | `待校验` `未验证` `待确认` | unverified |
- 组间**独立计数**,不合并
- `pending` = 未完成 ∪ 假数据(默认口径,最常用)
- 词表版本随编译器走;扩词表**不动语法**
### 3.3 第二级:参数(扩展与覆盖)
```bash
# 默认:内置 pending 集
marqdo labels pending
# 覆盖:只用我给的词
marqdo labels search --grep "接口未联调,联调中"
# 合并:我给的 + 内置
marqdo labels search --grep "联调中" --also-builtin
```
| 参数 | 语义 |
|------|------|
| `--grep A,B` | **替换**为 A、B(子串、OR、英文大小写不敏感) |
| `--also-builtin` | 与内置词表**取并集** |
| `--group pending,demo` | 用内置的某几组(不带 `--grep` 时) |
MLSP 对应:
```json
{ "method": "labels.search",
"params": { "grep": ["联调中"], "also_builtin": true, "json": true } }
```
### 3.4 为什么保留内置词表
| 理由 | 说明 |
|------|------|
| **LLM 有范本** | 模型不必发明措辞,照着写即可,稳定性显著提高 |
| **跨项目可比** | 大家用同一套词,"还有多少没做"才有统一含义 |
| **零配置可用** | CI 不必先写一份词表才能统计 |
| **失败模式可控** | 词不全时用参数补,而不是每个项目各自发明一套 |
**代价**:内置词表是一种"语义偏见"。缓解方式是**两级**——
内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。
### 3.5 识别规则:纯子串,无位置/分隔符要求
```rust
// 语义示意
for (group, words) in TABLE(words_from_params_or_builtin) {
if words.iter().any(|w| label_text.contains(w)) { hits.insert(group) }
}
```
| 写法 | 命中 |
|------|------|
| `[某某功能开发中]` | ✅ 无分隔符 |
| `[搜索接入,待开发]` | ✅ 逗号 |
| `[搜索接入-待开发]` | ✅ 连字符 |
| `[【待开发】搜索接入]` | ✅ 括号 |
| `[这段还没写完]` | ❌ 无词(合法,不计数) |
- **识别不到不报错、不提示**——描述自由
- **误判必然存在**(`[不属于待开发范围]` 会命中):只影响计数,不影响执行;
输出带描述原文,人可判断;否定词窗口留 v1.1 可选
---
## 4. 桩的语义
### 4.1 三条规则
| # | 规则 | 原因 |
|---|------|------|
| 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 |
| 2 | **桩必须写明返回什么** | 空载荷 → warning;写 `None` 也行,但不能什么都不写 |
| 3 | **桩不得被当成已完成** | 描述里申报;检索能查到;`view` 有徽章 |
### 4.2 桩返回什么
| 手段 | 写法 |
|------|------|
| 显式空值 | `[某某功能开发中](None)` |
| 常量占位 | `[税率预报,模拟](0.1)` |
| 假数据 | `[搜索结果,模拟](json.parse text="[]")` |
| **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" |
```markdown
## 搜索
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表(当前未接) |
[按关键词检索,接口未接,模拟](json.parse text="[]")
```
### 4.3 惯例(不强制):桩返回值带 `stub: true`
```markdown
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
---
## 5. 工程化:写进 README,提示词同步更新
### 5.1 README 增补(`README.md` 新节)
> **工程习惯:允许申报未完成,但不允许假装完成**
>
> ```markdown
> [按关键词检索,接口未接,待开发](None)
> ```
>
> - 桩必须能跑,并写清返回值(写 `None` 也比空着好)
> - 描述是自由文本;内置词表只是推荐用词与默认检索集
> - 盘点:`marqdo labels pending`;自定义:`--grep 你的词 --also-builtin`
> - 门禁:`--baseline` + `--fail-on-increase`(棘轮:只拦新增,不追旧账)
> - LLM:接不了就申报;提示词见 `ext/ai/agent.mq.md`
### 5.2 提示词更新(`ext/ai/agent.mq.md`)
| 位置 | 现状 | 增补 |
|------|------|------|
| `:48` 默认 standing(`You are a Marqdo agent…`) | 只讲"源码是真相" | 追加一句申报约定 |
| `:39` how-to-act 协议段 | 只讲 CALL/READ | 追加"未完成必须申报" |
**建议追加文本**(英文,与现有 standing 一致):
```text
When you cannot truly wire a capability, do not fake it silently and never claim it works.
Write it as an occlusion with an explicit status instead:
[按关键词检索,接口未接,待开发](None)
Stubs must run without error and must state their return value (None is acceptable).
Before finishing, check your own declarations with labels.pending.
```
**为什么这条对 LLM 有效**:把"编造"变成"填表"——模型不必判断算不算伪造,
只需写出状态词并给一个返回值。
### 5.3 工具面
| 工具 | 用途 |
|------|------|
| `labels pending` | 内置词表口径的未完成清单 |
| `labels search --grep … [--json/--count/--also-builtin]` | 任意词盘点 |
| `labels search … --changed` | 只看本次变更涉及的 |
| MLSP `labels.search` | 协议内同上 |
### 5.4 指标
| 指标 | 算法 |
|------|------|
| `pending_count` | `labels pending --count` |
| `unlabeled_empty` | `label.empty_payload` warning 数 |
| `stub_ratio` | pending / 遮蔽总数 |
| `stub_age` | 需 VCS(可选,不进默认路径) |
---
## 6. 生命周期
```
① 写桩 [按关键词检索,接口未接,待开发](None)
↓
② 盘点 labels pending → 列出它
↓
③ 开发 换成真实 HTTP 调用
↓
④ 复核 去掉"待开发"字样、改写描述
↓
⑤ 数字-1 检索结果自动减少
```
### 6.1 stale 豁免(默认用内置集)
| 情形 | stale 行为 |
|------|-----------|
| 描述命中**内置 pending 组**(未完成/假数据) | **豁免** |
| 命中 `将删`(废弃) | **豁免** |
| 命中 `示例` / `实验` / `待核` | 正常报 |
| 空载荷 | **豁免**(它就是桩) |
| 无命中、有实现 | 正常报 |
| `check --stub-words "A,B"` | **覆盖**内置集,用 A,B 判定豁免 |
理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale,
12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。
### 6.2 防"做完了忘去掉申报"
- `labels search --grep … --changed`:本次变更中被改过的桩
- 会话末汇总带一行 `pending_touched: 2`(只给数字,不逐条)
---
## 7. 与防疲劳机制的协同
| 机制 | 作用 |
|------|------|
| 桩豁免 stale(默认内置集) | 12 个桩不会变成 12 条常驻警告 |
| 债务用**棘轮**(`--baseline` + `--fail-on-increase`) | 老债不阻塞、新债立刻拦 |
| 检索是**按需命令**,不进 `check` 人类输出 | 零噪音 |
| 搜不到**不报错** | 描述自由,机器不纠正用词 |
| 空载荷 warning 仅作用于新语法 | 不可能产生历史债 |
---
## 8. 编译器实现点
| 位置 | 要做的事 |
|------|---------|
| `src/parse` | 解析 `[描述](实现)`,**原样保存描述**(不解析、不分类) |
| `src/ast.rs` | `Expr::Occluded { label: String, inner: Option<Box<Expr>> }` |
| `src/label.rs`(新增) | **内置词表常量** + 描述索引/检索(子串、OR、大小写不敏感)+ L1 引用一致性 + T1 前后对比 |
| `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、`label.empty_payload`(**warning,一律**) |
| `src/interp.rs` | 描述**不影响求值**;空载荷 → `None` |
| `src/main.rs` | `labels pending/search --grep … [--also-builtin/--json/--count/--changed]`;`check --stub-words …` |
| `src/mlsp.rs` | `labels.search`(含 `also_builtin`)、`validate.stub_words`、会话汇总 `pending_touched` |
| `src/view/render.rs` | 遮蔽渲染:描述为正文、实现可折叠;桩徽章 |
| `README.md` | 新增「工程习惯」一节(§5.1) |
| `ext/ai/agent.mq.md` | `:48` standing 与 `:39` 协议段追加申报约定(§5.2) |
**分层**:内置词表是**数据**(常量表),检索是**纯函数**,语法**零依赖**——
扩词表不改语法,改语法不动词表。
---
## 9. 示例
### 9.1 无分隔符申报
```markdown
[某某功能开发中](None)
```
```bash
marqdo labels pending # 命中(内置「开发中」)
```
### 9.2 假算指标
```markdown
本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。
```
### 9.3 假接通外部系统
```markdown
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
### 9.4 该报 warning 的空载荷
```markdown
[应纳税额]() # ⚠️ label.empty_payload
```
### 9.5 项目自己的说法(参数层)
```markdown
[接口还在联调,先返回空](json.parse text="[]")
```
```bash
marqdo labels search --grep "联调" --also-builtin # 内置 + 自定义一起数
```
### 9.6 任意措辞(合法、不被自动分类,但可被搜)
```markdown
[这段还没写完](0)
```
```bash
marqdo labels search --grep 还没写完 # LLM 自己挑的词,照样搜到
```
---
## 10. 风险与取舍
| 风险 | 说明 | 缓解 |
|------|------|------|
| 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数;输出带原文;否定词窗口留 v1.1 |
| 内置词表是语义偏见 | 规定了"什么算未完成" | **两级**:内置只做默认,参数可覆盖/扩展 |
| 空载荷 warning 偏多 | 作者爱留空 | 修法极简(写 `None`);仅影响新语法;可留降级旋钮 |
| 桩腐化 | 忘去掉申报 | `--changed` + 会话汇总,不做常驻警告 |
| 假功能上生产 | 最坏情况 | `view` 显著标记;CI 可 `--count` 门禁 |
| LLM 滥用申报逃避检查 | 把真实现标成待开发 | 申报只增加可见性、不减少检查;豁免 stale 的代价是计入债务 |
---
## 11. 已定 vs 待定
**已定(本文即规范)**
| 项 | 结论 |
|----|------|
| 描述性质 | 自由文本,不执行,不参与类型/作用域 |
| 词表 | **两级**:内置范例/默认 + 参数扩展 |
| 空载荷 | **一律 warning**(写 `None` 消除) |
| 检索语义 | 子串 + OR + 英文大小写不敏感 |
| stale 豁免 | 默认内置 pending/将删组;`--stub-words` 覆盖 |
| 棘轮 | `--baseline` + `--fail-on-increase` |
| 工程化落点 | README 一节 + `ext/ai` 提示词两处 |
**待你点头**
| # | 问题 | 建议 |
|---|------|------|
| 1 | 内置词表就 §3.2 这六组 | 是 |
| 2 | `pending` = 未完成 ∪ 假数据 | 是 |
| 3 | `--grep` 替换、`--also-builtin` 合并 | 是 |
| 4 | 空载荷"降级旋钮"先不做 | 是(先按一律 warning 跑一段看噪音) |
| 5 | 提示词追加文本按 §5.2 写 | 是 |
> 点头后即按 M1 → M2 → M4 → M9 → M6 开工;首批金样用 §9 的六个例子。
+624
View File
@@ -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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
---
## 附:一句话总结
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
> 它用链接的天然分工(人话 / 目标)实现这一点,
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
> 而 `>` 调用同样在负债之列。
+28 -7
View File
@@ -143,13 +143,18 @@ Marqdo 对齐的判断是:
| `type` | 状态 | 含义 | 主要生产者 |
|--------|------|------|------------|
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
| `Marqdo Catalog` | **已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **已实现** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **已实现** | 指向可执行工作簿的技能 | `plan` 晋升 |
| `Capability` / `Function` | **EKC** | 工程能力 / 符号投影 | `marqdo knowledge` |
| `Decision` / `Constraint` / `Failure` / `AntiPattern` / `Pattern` / `Migration` / `Fact` | **EKC** | L4 工程知识 | 源 frontmatter + learn |
| `Marqdo Context Pack` | **EKC** | Agent EFI 上下文制品 | `reuse` / `preflight` |
| `Marqdo Policy` | **EKC** | 复用决议编译 | `marqdo reuse` |
| `Marqdo Engineering Knowledge` | **EKC** | 工程知识总览 | `engineering.yaml` / `index.mq.md` |
| 其他 | 开放 | 第三方/未来扩展 | — |
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
完整 EKC 规范见 [engineering-knowledge.md](engineering-knowledge.md)。
---
@@ -309,10 +314,15 @@ type: Marqdo Agent Skill
title: <短名>
sig: <12hex>
resource: ../../resources/<slug>.mq.md
status: stable | candidate
status: stable | candidate | quarantine
llm_free: true | false
quality: <int>
hits: <int>
# O2 optional metadata (from workbook frontmatter; see §7.5):
applies_when: <text condition or tag>
fixtures: <relative .mq.md proof path>
sandbox_profile: default | readonly | <name>
proof: <relative .mq.md> # alias of fixtures for sandbox gate
generated:
by: marqdo-agent/plan
at: <ISO8601>
@@ -326,7 +336,7 @@ verified:
Prefer spawning `resource` over re-planning.
```
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
### 7.3 任务签名 → Concept 路径
@@ -396,6 +406,17 @@ Prefer spawning `resource` over re-planning.
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
### 7.5a 技能 frontmatter 约定(O2 B1)
| 字段 | 含义 |
|------|------|
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
---
@@ -0,0 +1,229 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
| 日期 | 2026-10-22 |
| 提出 | 「`[函数名](参数1 参数2)` 这种写法有没有可能成立;调用能否更符合人读习惯」 |
| 更正 | 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法) |
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [function-as-table-semantics.md](function-as-table-semantics.md) · [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) |
---
## 0. 结论
| 问题 | 答案 |
|------|------|
| `[函数名](参数1 参数2)` 能否成立 | **技术上能,但代价在方括号**:它撞的是取元 `[键](集合)`,而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义 |
| 更人读的调用能否成立 | **能,而且更干净**:`函数名(参数1 参数2)`(**不带方括号**)目前是**完全空闲的语法**,原型实测全量 **554 passed / 0 failed**,零回归 |
一句话:**想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。**
```markdown
**税率 = 查询税率(档位=2)** # 具名,读起来像函数调用
**合计 = 加(1 2)** # 位置,读起来像数学
**名 = txt.str_trim(" x ")** # 库函数同样适用(原型已验证)
```
---
## 1. 现状:今天的调用写法盘点(全部实测)
| 写法 | 位置 | 实测 |
|------|------|------|
| `> 加 1 2` | 语句 | ✅ 位置参数 |
| `> 加 a=1 b=2` | 语句 | ✅ 具名参数 |
| `[加] 1 2` | 语句 | ✅ 方括号标记 + 位置参数(用于消歧/前置修饰) |
| `**r = > [加] 1 2**` | 粗体赋值 | ✅ 返回 3(方括号调用**已支持空格参数**) |
| `**r = 加 1 2**` | 粗体赋值 | ✅ **不带 `>` 也能调用,已可用**(打印 3) |
| `**r = > 加 a=1**` | 粗体赋值 | ✅ 显式 `>` 形态 |
| `**r = 加(1)**` | 粗体赋值 | ❌ `trailing input in expression: "(1)"` |
| `**r = [加](1 2)**` | 粗体赋值 | ❌ `unknown function `[加](1`` |
| `> [加](1 2)` | 语句 | ❌ `unknown function `[加](1`` |
也就是说:**「参数放在括号里」这件事今天完全不存在**。
---
## 2. `[函数名](参数)` 为什么碰壁
### 2.1 方括号 + 圆括号 = 取元,这是**已定的语义**
[collection-access-link.md](collection-access-link.md) §1 写的是心智模型:
> **方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)** # 从菜单里取出「拿铁」
```
[call-arguments.md](call-arguments.md) §2 进一步锁定:
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
所以 `[f](x)` 不是「还没被用的语法」,而是**已经被取元占用**。
### 2.2 靠「名字是函数还是键」消歧,会真的打断现有代码
这是本轮新增的硬证据。我把全仓库扫了一遍:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件 | 851 |
| `##` 级函数名 | 2367 |
| `[键](…)` 出现次数 | 983 |
| **键名与同文件函数名相同的冲突** | **5(去重后 2 个真实文件)** |
两个真实冲突(不是构造出来的):
```
ext/data/db.mq.md:122 *[count](r)* # 函数名 ## count,同时 r 里有 count 列
examples/code-as-docs/index.mq.md:79 价=[单价](行) # 函数名 ## 单价,同时 行 里有 单价 字段
```
**这说明任何「函数名优先」的规则都会改变这两处的行为**:它们本意是取元,却会被解释成调用。
反过来「数据优先」则永远无法用 `[f](1)` 调用。**两条路都走不通**——这不是实现难度问题,
而是同一外形承载两种语义的固有代价。
### 2.3 但有一个「无歧义子集」确实存在
`[f](1 2)` 与 `[f](a=1)` 里的括号内容**不是合法表达式**(实测 `x=1` 报
`unknown function`、`1 2` 报 `unknown function`),所以理论上可判为参数列表:
| 括号内容 | 能否是取元 | 可否判为调用 |
|---------|-----------|-------------|
| `(1 2)` 多 token | 否(非单一表达式) | ✅ 无歧义 |
| `(a=1)` 具名 | 否 | ✅ 无歧义 |
| `(1)` 单 token | **能** | ❌ 与 `[1](篮子)` 冲突 |
| `(m)` 单变量 | **能** | ❌ 与 `[a](m)` 冲突 |
于是 `[f](1)`(最常见的单参调用)**永远无法**与取元区分。
一个「多参数能用、单参数不能用」的语法,对使用者是最难记的一类。
---
## 3. `函数名(参数)`:空闲语法,原型验证通过
### 3.1 它是空闲的
实测 `**r = 加(1)**`(原型前)报 `trailing input in expression: "(1)"` ——
说明 `名字(` 今天既不表示取元,也不表示任何别的含义。**没有既有语义要保护。**
### 3.2 原型做了什么
改了两处(**已回退,仅作验证**):
1. `src/parse/expr.rs`:新增 `try_paren_call` —— 紧随其后的 `(` 视为参数列表;
在 `parse_call_tail` 里优先尝试。
2. `src/parse/mod.rs`:粗体赋值与 `>` 两条路径的「像调用」判定加上
`looks_like_paren_call`(让单 token 的 `加(1)` 也能进入调用分支)。
### 3.3 原型实测结果
| 用例 | 结果 |
|------|------|
| `加(1)` | ✅ 返回 2(单参) |
| `加(1 2 )` | ✅ 返回 3(多参) |
| `加("1" "2")` | ✅ 返回 `12`(字符串参数) |
| `加(1 2)` | ❌ 末参数把 `)` 吞了 |
| `加(a=1 b=2)` | ❌ 具名参数值把 `)` 吞了 |
| `加(1, 2)` | ❌ 逗号不是分隔符 |
| `加(加(1 2) 3)` | ❌ 嵌套未支持 |
| `txt.str_trim(" x ")` | ✅ 返回 `x`(**库函数路径可用**) |
| **全量测试** | ✅ **554 passed / 0 failed** |
**两条关键结论**:
1. **零回归**:新语法是纯增量,没有破坏任何既有用例(含 4 个 `[k](c)` 取元金样)。
2. **真正的落点在参数分词器,不在语法**:`加(1 2)` 失败、`加(1 2 )` 成功,
差别只是 `)` 前多一个空格——说明 `parse_call_args` 的分词把 `)` 当成了 token 的一部分。
要修就得动 `parse_call_args` / `split_first_token` / `find_next_arg_boundary`,
而这个分词器是**所有调用**(含今天在用的 `> f a=1`)共享的。
这解释了为什么这件事「看起来 10 行、实际一次核心改动」。
---
## 4. 人读性对比
同一个意思,五种写法:
| 写法 | 读起来 | 现状 |
|------|--------|------|
| `> 加 1 2` | 「调用加,1 和 2」 | ✅ |
| `**合计 = 加 1 2**` | 同上,无 `>` | ✅ |
| `**合计 = 加(1 2)**` | 「加(1, 2)」,**像数学/函数调用** | 原型通过 |
| `**合计 = 加(a=1 b=2)**` | 「加,a=1、b=2」,自解释 | 原型通过 |
| `**[加](1 2)**` | 像链接,但与取元同形 | ❌ 不建议 |
我的判断:**`f(args)` 是这几种里最符合人读习惯的**,理由有三:
1. **与数学记号同构**:`税率(2)`、`sin(x)` 是跨语言、跨学科的通用写法,不需要学。
2. **参数边界显式**:括号天然划定起止,解决了 `> f a b` 里「参数到哪结束」的模糊
(这也是 D8「函数名含空格」难题的天然解药)。
3. **不占用 Markdown 的链接语义**:渲染出来是普通文本 `f(1)`,
不会像 `[f](1)` 那样在预览里变成超链接。
---
## 5. 要走完这条路,需要做什么(评估工作量)
原型只验证了「方向可行」,要合入还缺这些:
| # | 事项 | 位置 | 风险 |
|---|------|------|------|
| 1 | `)` 作为参数终止符 | `parse_call_args` / `split_first_token` / `find_next_arg_boundary` | **中高**:所有调用共享 |
| 2 | 逗号分隔 `f(1, 2)` | 同上 | 中:逗号在文本参数里合法(`"a,b"` 已加引号则无碍) |
| 3 | 嵌套 `f(g(1) 2)` | `parse_call_args` 递归 | 中:需要括号深度跟踪 |
| 4 | 方法 `obj.m(1)` / 库 `lib.fn(1)` | `try_paren_call` 已有基础(库路径实测通过) | 低 |
| 5 | 位置/具名混用规则 | 复用 [call-arguments.md](call-arguments.md) §3 | 低 |
| 6 | 空参 `f()` | 需定义语义(零参调用) | 低 |
| 7 | EKC 指纹 | `collect_calls` 已读 `c.callee`,`CallExpr` 不变 → 自动兼容 | 无 |
| 8 | `view` 渲染 | `[callee]` 已有 `bracket_marked` 标记,需决定是否回显括号形式 | 低 |
| 9 | `marqdo check` | 需新增「`名字(` 但不是函数」的诊断 | 低 |
**注意第 7 条**:因为 `f(args)` 最终仍产出 `CallExpr { callee, args }`,
EKC 指纹、契约、字节码 `Op::Call(fid, argc)` **全部自动兼容**——
这正是它与「一等函数」方案([functions-as-values-evaluation.md](functions-as-values-evaluation.md) §5 路径 A)的本质区别:
**它只是换了一种写法,没有改变调用模型。**
---
## 6. 建议
### 6.1 推荐路线
1. **不做 `[f](args)`**:与取元同形,且已证明按名消歧会打断 2 个真实文件;
而「多参能用、单参不能用」的规则不可教。
2. **做 `f(args)`**:空闲语法、零回归、人读性好、不动调用模型。
3. 先落**具名**形态 `f(k=v)`(最无争议、自解释),再补位置 `f(1 2)`,最后考虑逗号与嵌套。
### 6.2 若你想保留方括号的「链接感」
有一个不碰取元的位置:**语句位置**。
```markdown
> [加](1 2) # 今天报 unknown function;语句位置的 [k](c) 无实际用途
```
`[k](c)` 作为**独立语句**今天只会算出值然后丢弃。全仓库扫描(851 文件):
以 `[` 起行且形如 `[k](c)` 的独立行只有 **2 处**,且都是样式示例文件里的
普通 Markdown 链接文本(`[海上花开](https://…)`),并非取元代码。
所以在**语句调用**里允许 `[f](args)` 几乎无成本,表达式里则不允许。
代价是「同一写法在两种位置含义不同」,可教性差;我倾向不做。
---
## 7. 待你决策
1. **是否采纳 `f(args)`**(不带方括号)作为新调用写法?
2. 若采纳,**先做哪一档**:
- A 只做具名 `f(k=v)`(最小、最稳)
- B 具名 + 位置 `f(1 2)`(需改分词器,价值最大)
- C 再加逗号与嵌套(一次做全)
3. **`[f](args)` 是否彻底放弃**(我建议放弃,理由 §2.2);
还是只允许在语句位置(§6.2)?
4. 是否需要我按 B 档做一次完整实现(含分词器改造 + 金样例 + 变更文档),
做完再走 554 回归?
原型代码已全部回退,工作区干净。等你定档我再动手。
+208
View File
@@ -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`)
每一步独立提交,便于回滚。
+216
View File
@@ -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 相关代码。
+223
View File
@@ -0,0 +1,223 @@
# 修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层
| | |
|---|---|
| 状态 | **Accepted · 修订**(取代 [warning-fatigue-control.md](warning-fatigue-control.md) §2 的 M5a) |
| 日期 | 2026-10-22 |
| 触发 | 用户:不是所有开发都用 git,依赖 git 是否是好设计 |
| 结论 | **不是好设计**。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖 |
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
---
## 0. 直接回答:不该依赖 git
三条理由,一条比一条硬:
### 0.1 环境覆盖不到
| 环境 | 能调 git 吗 | 依据 |
|------|------------|------|
| 浏览器 WASM | ❌ | `marqdo-wasm`(wasm32-unknown-unknown),无进程能力 |
| **沙箱内执行** | ❌ | `src/host/sandbox_fs.rs`:`allow_exec: false` |
| 单文件分发 / zip 工件 | ❌ | 没有 `.git` |
| CI 容器(浅克隆/无 VCS) | ⚠️ 常常没有 | 取决于流水线 |
| 非 git 用户(hg / svn / fossil / 无) | ❌ 或需另写适配 | — |
### 0.2 语言不该绑定某个 VCS
Marqdo 是**语言与运行时**。把"断言是否过期"的判定建立在"某个工具的目录是否存在"上,
等于把语言的语义正确性外包给环境。今天 git 是主流,明天不是;语言不能跟着换。
### 0.3 最要命的:最重要的消费者恰在不能调 git 的地方
标签过期检测的**最高价值场景**是 agent 修复回路——
模型改了代码,Marqdo 提醒它"你改的这处描述可能不成立了"。
而这个回路:
- 常在沙箱里跑(`exec=false`,**调不了 git**)
- 编辑目标是内存中的文本(`repair_apply` 的 `source`),不一定落在 git 工作区
**如果核心机制依赖 git,那它恰好在最需要它的地方失灵。** 这是设计错误的铁证。
---
## 1. 但 M5 的原则要保住
上一份文档的 M5 有两个部分,必须分开看:
| 部分 | 判定 |
|------|------|
| **原则**:stale 是"变更报告",不是"扫描报告"(没有新信息就不说话) | ✅ **保留**,这是防疲劳的根 |
| **实现**:用 `git diff` 提供"前一状态" | ❌ **降级为可选 provider** |
也就是说:
> **判定逻辑只有一份:`stale ⟺ fingerprint(()) 变了 ∧ label 没变`。
> 变的只是「前一个 `()` 从哪来」。**
这一步抽象之后,git 只是**四种来源之一**。
---
## 2. 四层能力(provider 分层)
### T0 — 引用一致性(零依赖,永远可用)
纯文档分析:标签里的 `` `实体` `` 必须可解析、且出现在 `()` 中。
- 需要:只读当前文件(甚至只需文本)
- 能力:查**引用腐烂**(改名、删除、错引)
- 查不了:语义腐烂(`*` 改 `/`)
### T1 — 会话内前后对照(零依赖,最高性价比)
**任何"编辑前 + 编辑后"都在手的场合**都能算 stale:
| 场合 | 前一状态从哪来 |
|------|---------------|
| `MLSP repair_apply` | 调用方传入的 `source` + `edits` → 前/后两版都在内存里 |
| `view`(保存后检查) | 保存前的模块 AST |
| 编辑器保存钩子 | 编辑器持有的旧缓冲 |
| agent 的 diff | 它自己的编辑集 |
**关键**:只看「本次会话改了哪些标签的 `()` 且没改 `[]`」。
天然变更驱动、天然零台账、天然带 before/after——**而且不需要 git**。
### T2 — 外部历史源(可选,自动探测)
`git` / `hg` / `svn` / 任意"能取到上一版文件内容"的适配器。
- 检测:工作区存在 `.git` / `.hg` 且二进制可用
- 用途:**跨会话**漂移(昨天改了代码,今天才检查)
- 缺失时:**静默关闭**,不报错、不提示、不产生噪音
### T3 — 台账(可选,无 VCS 时的持久化)
`.marqdo/labels.json`:`{标签键 → {code_fingerprint, code_quote, confirmed_at}}`
- 用途:没有 VCS 的环境(沙箱长期任务、编辑器插件)+ 严格模式的"确认"状态
- 语义:**可丢弃缓存**(删了重建,最多一次全量确认)
- 已知代价:合并冲突、需要 bootstrap(因此作为 opt-in,不做默认)
---
## 3. 环境能力矩阵
| 环境 | T0 引用 | T1 会话内 | T2 历史源 | T3 台账 |
|------|--------|----------|----------|--------|
| CLI + git 仓库 | ✅ | ✅ | ✅ | ✅ |
| CLI + hg/svn(有适配) | ✅ | ✅ | ✅ | ✅ |
| CLI 无 VCS | ✅ | ✅ | ❌ | ✅ |
| **agent 沙箱(exec=false)** | ✅ | ✅ | ❌ | ⚠️ CoW 内可写但不持久 |
| **浏览器 WASM** | ✅ | ✅ | ❌ | ❌ 无持久 fs |
| 单文件 / zip 工件 | ✅ | ✅ | ❌ | ❌ |
| 数据库/对象存储里的 `.mq.md` | ✅ | ✅ | ❌ | 由宿主提供 |
**读法**:矩阵里**没有一行全 ❌**。T0+T1 在所有环境都成立——
这两层就足以支撑"agent 改动即时提醒"这个最高价值场景。
---
## 4. 各层的能力边界(必须诚实)
| 层 | 能查 | 查不了 |
|----|------|--------|
| T0 | 引用了不存在的实体;引用的实体不在语句里 | 语义腐烂(乘改除) |
| T1 | **本次会话内**的 `()` 变化 | 跨天/跨机器的漂移 |
| T2 | 跨会话、跨机器的漂移(若 VCS 有历史) | 未提交历史之外的变化;跨仓库移动 |
| T3 | 持久化的漂移(若台账被维护) | 台账未覆盖的标签;合并后需重算 |
**组合起来的语义**:
- 有 T2 → 严格(能查历史)
- 只有 T0+T1 → **会话级严格**(够 agent 用)
- 什么都没有(WASM 首次打开) → 只查引用(T0),且**明确告知能力级别**
---
## 5. 最关键的一条:agent 回路不需要任何 VCS
`MLSP repair_apply` 的参数里**已经同时有前后两版**:
```rust
// src/mlsp.rs:repair_apply 收到 source + ranges + edits
let source = source_text(params)?;
// → 应用 edits 得到 after
```
所以只要给协议补一个字段 `base_code`(或让 `repair_apply` 自己在内部保留 before),
Marqdo 就能在**同一次调用内**算出:
> 哪些标签的 `()` 指纹变了、而 `[]` 没变 → 输出 stale 提示。
**零外部状态、零依赖、零 git。** 而这正是"模型改了代码别忘了改描述"的场景。
**具体协议建议**(只需一个可选字段):
```json
{ "method": "repair_apply",
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
"check_labels": true } }
```
返回里附:
```json
{ "labels": [{ "stale": 1, "items": [{ "text": "按 `税率` 计算总价",
"code_past": "…* 金额", "code_now": "…/ 金额", "span": {...} }] }] }
```
这样 agent 每轮只看到**自己刚弄脏的那几条**,且带前后对照。
---
## 6. provider 契约(五条硬规则)
1. **核心不依赖**:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。
2. **缺失即降级**:provider 不可用 → 静默关闭该层能力,**绝不报错、绝不提示**。
3. **能力必须自述**:`labels status` 必须显示"当前启用 T0/T1/T2/T3 中的哪些"。
——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。
4. **判定单一定义**:`stale` 的定义只有一处实现;provider 只提供 `prev`,不参与判定。
——否则不同环境会给出不同结论,语言就没有统一语义了。
5. **不写进文档**:provider 的状态、指纹、抑制**一律不进 `.mq.md`**。
文档里只允许有人的语言与代码。
> 第 3 条是我这次最想强调的:**宁可少报,也不能假装"检查过了"。**
---
## 7. 被否决的方案
| 方案 | 否决理由 |
|------|---------|
| **强制 git 作为核心** | 环境覆盖不到(§0.1);语言绑定 VCS(§0.2);最关键场景失灵(§0.3) |
| 文档内嵌指纹 | 污染文档;作者一改就失效;与"文档即散文"冲突 |
| 零宽字符隐藏指纹 | 不可见 = 不可审计;复制粘贴即损坏;工具链噩梦 |
| mtime 启发式 | 不可靠(checkout、touch、云同步都会变) |
| `# noqa` 抑制 | 已否(污染 + 不可审计 + 会永久化) |
| 只做全量扫描 + 静音清单 | 静音清单就是台账,且首次即爆炸 |
---
## 8. 对上一份文档的修订
| 原条目 | 修订后 |
|--------|--------|
| M5a「git 结构化 diff」为核心机制 | 降级为 **T2 的一个适配器**;核心改为 **T0 + T1** |
| 严格模式依赖台账 | 严格模式 = 任意 T2 **或** T3 可用即可;无 provider 时按 T0/T1 运行 |
| 验收指标「无变更时输出 = 0」 | 保留,且补一条:**provider 缺失时也必须为 0,并在 `labels status` 里说明** |
---
## 9. 待你决策
1. **接受「T0+T1 为核心,T2/T3 可选」这个分层吗?**
2. **T1 是否足够**作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景)
3. **能力自述**要不要做成 `labels status` 的固定输出
(含"本次无法检测历史漂移"这类明确提示)?
4. **T2 的适配范围**:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现?
5. **T3 台账**是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实)
> 我的建议:**先只做 T0 + T1**,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。
> 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立,
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
+2 -2
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **已落地(v1)** |
| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) |
| 日期 | 2026-08-06 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) |
---
+4 -2
View File
@@ -35,7 +35,8 @@
```markdown
---
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -44,7 +45,8 @@ import text:lib/text.mq.md
```markdown
---
导入 文本:lib/文本.mq.md
导入:
文本: lib/文本.mq.md
---
# main
+14 -4
View File
@@ -34,7 +34,16 @@
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
````markdown
$$
% marqdo: var=f
sin(x) + x
$$
````
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
````markdown
# main
@@ -52,13 +61,14 @@ $$
也支持:
- 单行围栏:下一行 `$$x^2 - 2$$`
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
### 2.3 从文本构造
+2 -1
View File
@@ -17,7 +17,8 @@
```markdown
---
import table:lib/table.mq.md
import:
table: lib/table.mq.md
---
# main
+22 -5
View File
@@ -8,9 +8,11 @@
## 定位
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
## 存储格式
## 存储格式(两种,可并存)
### 1. HTML 注释(文本 / 结构化输出)
```markdown
*`n` = > len value=`xs` *
@@ -30,11 +32,26 @@ pending
-->
```
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
### 2. Markdown 图片(生成图 / 审计友好)
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
```markdown
![marqdo-out](plots/out.svg)
![marqdo-out ok](plots/ok.png)
```
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
- 非图片路径仍走注释块;把非图片硬写成 `![marqdo-out](…)` 时扫描会忽略(校验失败)。
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
### 共用规则
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
- 默认在**调用行下方**插入或替换紧邻**无键**块
- `at_end=true`:替换文件末尾的**无键**块
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
### 替换跨度与空行
+3 -2
View File
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
```markdown
---
import text:lib/text.mq.md
import table:lib/table.mq.md
import:
text: lib/text.mq.md
table: lib/table.mq.md
---
```
+233
View File
@@ -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——**第一天就不会有任何存量警告**。
+1 -1
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
---
+3 -3
View File
@@ -4,14 +4,14 @@
|---|---|
| 状态 | **v1(独立 debug 页)** |
| 日期 | 2026-08-05 |
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
## 分工
| 命令 | 角色 |
|------|------|
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
静态 `gh-pages` / `view output` **不能**真断点。
+113
View File
@@ -0,0 +1,113 @@
# View:文档面与结果引出标注
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 动机
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
## 2. 模式分工
| 命令 | Structure | 叙述 | 结果 |
|------|-----------|------|------|
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
## 3. 视觉语法
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注
```
1. 叙述正文正常排版(Markdown)。
2. 可执行片段高亮,并带底部分割线(underline)。
3. 段落下方 **annotation band** 放结果 callout。
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
## 4. 文档面渲染
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
| 源内容 | 呈现 |
|--------|------|
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
## 5. ViewAnnot
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
| 字段 | 含义 |
|------|------|
| `id` | 稳定短 id(页内唯一) |
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
| `anchor_line` | 1-based 源行 |
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
| `label` | 短标题(名 / return / arm / loop) |
| `value` | 截断显示 |
| `detail` | 完整文本(inspect) |
| kind | 数据来源 | 锚点 |
|------|----------|------|
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
## 6. 布局与密度
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
- 静态导出:页载 JS 跑一次布局。
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
## 7. 非目标
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
- 不新增作者侧标注 DSL / frontmatter 指令。
- 不引入外链字体、npm 组件或 SVG leader。
- 不把 DB/auth 等塞进 view 壳层。
## 8. 验收
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
5. 无外链字体/新依赖;`view output` 可离线打开。
## 9. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
+103
View File
@@ -0,0 +1,103 @@
# View:执行轨迹与文档面保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
---
## 1. 目标
`marqdo view` Browse Structure 必须同时做到:
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
4. **执行臂**:高亮实际走的分支臂。
5. **多调用帧**:同函数多次调用可用下拉切换经历。
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
## 2. 标记面
| 源标记 | 显示(无定界符) | class |
|--------|------------------|-------|
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
## 3. 结构块
| 块 | 呈现 |
|----|------|
| GFM 表 | `<table class="doc-table">` |
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
| 公式 / 外联代码 | 现有 formula-card / code-card |
| `>` 调用 | 表面高亮,非整行灰 code |
## 4. StmtEvent / CallFrame
解释器 capture 时静默采集(非 `trace_eval` stderr):
```text
StmtEvent {
line, kind, // assign | return | call | branch | loop | bind_ref
name?, value_after?, // post-stmt 或求值结果
arm_index?, iter?,
call_id // 当前用户函数调用帧
}
CallFrame {
call_id, fn_name, fn_line, ordinal,
args_brief, // 短摘要供下拉
events[] // 或全局 events 用 call_id 过滤
}
```
- Assign → 写入后的值挂在**该行**。
- 循环内多次写入:UI 默认末次;可带次数。
- Branch → taken `arm_index` + 条件摘要。
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
## 5. ViewExecutionReport(AI)
```json
{
"version": 1,
"path": "…",
"ok": true,
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
"bindings_final": { "均分": "73", "等级": "及格" }
}
```
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
## 6. UI
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
- CSS L-leader(非 SVG);拥挤 keyed 降级。
## 7. 验收
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
3. `总分 = 0` 标注 `0`,非终态累加。
4. 命中臂可视化;多调用下只显示当前帧的 taken。
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
## 8. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
+123
View File
@@ -0,0 +1,123 @@
# View:调用帧 / 循环帧选择与结构保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
---
## 1. 问题(对照实测)
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
## 2. 定稿原则
| 原则 | 含义 |
|------|------|
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
## 3. 函数调用帧
### 数据
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
### UI
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
- 选项:`1: 等级=及格` / `2: 等级=优秀`
- 默认选中最后一次
### 客户端(`applyCallFrame`)
1. 读 `#mq-view-trace` JSON。
2. 过滤 `events` where `call_id == selected`。
3. **不**设置结构节点 `hidden`。
4. 更新该函数作用域内:
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
## 4. 循环迭代帧
### 数据
```text
LoopFrame {
loop_id, line,
item_name?, // "分"
collection?, // "分数表"
iterations: [{ index, item_value, call_id }] // index 0-based
}
```
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
### UI
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
- 默认最后一次
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
### 客户端(`applyLoopFrame`)
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
3. 不隐藏循环体源码。
## 5. 分支臂渲染
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
- 高亮仅反映**当前帧**的 taken `arm_index`。
## 6. AI JSON 增量
`ViewExecutionReport` 增加:
```json
"loops": [{
"loop_id": 1,
"line": 27,
"item": "分",
"collection": "分数表",
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
}]
```
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
## 7. 验收
1. 未选中分支臂源码始终可见(含返回句)。
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
5. `cargo test --lib view::` 全绿。
## 8. 开发计划(已执行)
| 阶段 | 内容 | 状态 |
|------|------|------|
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
## 9. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
| 2026-10-15 | 按计划落地 D1–D6 |
+145
View File
@@ -0,0 +1,145 @@
# View:叙述面标注缺口(prose annot gaps)
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
---
## 1. 为何「改了却几乎没变化」
| 原因 | 说明 |
|------|------|
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
---
## 2. 目标视觉语法(既有,不新造)
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注 chip
```
- underline:`mark.mq-anchor.mq-{decl|code|return}`
- band:段落下方 `.annot-band` → leaders + chips
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
---
## 3. 管线
```mermaid
flowchart LR
CLI["marqdo view / view output"] --> build["build_file_view"]
build --> cap["run_file_capture"]
cap --> annot["build_view_annots"]
annot --> doc["document::render_module_document"]
doc --> page["html.rs page_file"]
page --> js["initAnnotLeaders + initCallPickers"]
```
| 步骤 | 位置 |
|------|------|
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
| Capture + Call 事件 | `src/interp.rs` |
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
| 文档面 HTML | `src/view/document.rs` |
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
| CSS / leader JS | `src/view/html.rs` |
---
## 4. 四条用户问题 → 根因 → 验收
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
### P1 — 叙述与代码同段时信息不显示
| | |
|---|---|
| 现象 | underline 在,chip / 连线弱或无 |
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
### P2 — 函数内变量不显示
| | |
|---|---|
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
### P3 — ` ```text ` 渲染不一致
| | |
|---|---|
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
### P4 — 函数引用 / 代码卡未渲染
| | |
|---|---|
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
### call_id 语义(写死)
| 位置 | call_id |
|------|---------|
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
---
## 5. 修复约定(实现红线)
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
---
## 6. 验收命令
```bash
cargo build -q
./target/debug/marqdo version # 须为当前工作树版本
./target/debug/marqdo view public/00-welcome.mq.md --no-open
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
cargo test -q --lib view::
```
---
## 7. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
+239
View File
@@ -0,0 +1,239 @@
# View:静态页交互与公式/代码卡视觉
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view.md](view.md) · [user-site.md](user-site.md) · [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [ADR 0002 browser WASM](../adr/0002-browser-marqdo-wasm.md) |
**已确认(2026-10-15)**
| 决策 | 选择 |
|------|------|
| 引擎 | **B**(快照 + S1 帧切换 + 可选懒加载 WASM S2) |
| 体验原则 | 静态页与 live view **尽量同构**;控件形态对齐;无服务端时用 WASM/JS 补齐 |
| 视觉原则 | **一层主视觉**;一眼能懂;公式/代码不与 Bind chip / 源残留叠床架屋 |
| 演示参数条 | **要**(历史实参 select + 可编辑;S1 切帧 / S2 重跑) |
| code-card Run | 有 WASM 时可用;否则隐藏(不对齐「假按钮」) |
| 公式 Bind chip | **卡内不显示**;Variables 可留终值 |
---
## 1. 动机(对照 `public/00-欢迎.mq.md` / gh-pages)
静态导出(`marqdo view output` → `gh-pages`)与 live `marqdo view` 已共用**文档面 Structure** 渲染路径,但用户站实测仍有三类落差:
1. **交互控件缺失 / 偏弱**
- 函数「问候」仅有参数 chip「谁」,没有可切换的调用帧下拉(即便源里 `> 问候` 写了两次)。
- 参数行 `+ 谁` 在文档面呈声明高亮,读者无法在静态页改「谁」并看到新输出。
- 外联 `code-card` 的 Run 在静态模式被禁用(`Run is available in live marqdo view`)。
- 静态 stdin 仅在有 preset 时显示只读提示,**不能**再跑。
2. **无服务端时仍可交互的预期**
用户站是纯静态托管:没有 `/api/run`。合理路径是 **页内 JS** 和/或 **嵌入 Marqdo WASM**,在浏览器里重算 Structure 标注、Execution 区,甚至模拟 `input` / 外联(沙箱约束另定)。
3. **公式 / 代码块视觉凌乱**
同一赋值同时出现多层表象,信息重复、线框错位:
| 层 | 公式 `f = $$…$$` | 外联 `hi = ```python…``` |
|----|------------------|---------------------------|
| A 卡片 | `formula` badge + KaTeX | `code` badge + 高亮源码 + cmd/Run |
| B 标注 chip | `f` → `x^2 - 2` | `hi` → 整段 fence 摘要 |
| C 源残留 | 卡片外/旁再露 `$$` 或 ASCII | 卡片下再露 `python print…` 明文 |
再叠加 CSS L-leader 与卡内边框,首屏显得碎、重复、「坏掉的线」。
**本文件只定问题与方案;确认前不改代码。**
---
## 2. 现状解剖
### 2.1 静态 vs live(同一 `page_file`)
| 能力 | Live | Static(`LinkMode::Static`) |
|------|------|------------------------------|
| 文档面 Structure + annot | ✅(跑后) | ✅(导出时跑后写入) |
| call / loop picker JS | ✅(读 `#mq-view-trace`) | ✅(同源 JS;若轨迹未写入则无控件) |
| `/api/run` · Stream | ✅ | ❌ |
| stdin 表单 | ✅ 可再跑 | 只读 hint(或无) |
| code-card Run | ✅ `POST` 外联 | ❌ 禁用按钮 |
| WASM 重算 | ❌(未接) | ❌(未接) |
结论:**不是「静态另做一套皮肤」**,而是「导出瞬间的快照 + 部分 JS 帧切换」;**没有**浏览器内重执行闭环。
### 2.2 欢迎页结构(问题复现源)
```text
> 问候 谁=marqdo
> 问候 谁=marqdo user
## 问候
+ `谁`
> 打印 内容=欢迎,`谁`!
`f` = $$ x^2 - 2 $$
`hi` = ```python … ```
```
- 期望:`## 问候` 旁 **调用** 下拉(`1: 谁=marqdo` / `2: 谁=marqdo user`),切换时打印行的绑定/输出随帧变。
- 现状风险:若导出时 CallFrame &lt; 2、或 picker 未挂上、或读者期望的是「编辑谁」而非「选历史调用」,都会表现为「没有下拉框」。
- 公式/代码:`SpecialAssign` → formula/code **card**,同时又对同名绑定建 **Bind annot**,文档面还可能保留块源视觉 → 三重展示。
### 2.3 已有红线(方案不得破坏)
- 代码即文档:`.mq.md` 源可读;不发明第二套嵌套 DSL(见 web-artifact / marqdo-dev)。
- Browse ≠ Debug:静态站不做断点。
- `public/**/*.html` 不入库;gh-pages 由 CI/`view output` 生成([user-site.md](user-site.md))。
- 外链字体禁令仍在 [view.md](view.md);WASM/重型资源须 **可选加载**,默认站可降级为纯快照。
---
## 3. 目标(验收口径)
### G1 — 帧与参数交互(静态可读、可拨)
1. 同函数 ≥2 次调用时,静态页 **必有**「调用」下拉;默认末次;切换只改 chip/臂/相关输出,**源码常显**(同 [view-frame-selection.md](view-frame-selection.md))。
2. 导出保证写入完整 `#mq-view-trace`(含 `calls` / `events` / 可选 `loops`)。
3. (增强)演示向参数可提供 **受控输入**:默认值来自末次调用或 FM;改参后可触发页内重算(见 §5 引擎选项)。
### G2 — 无服务端可重算(可选引擎)
| 档位 | 能力 | 依赖 |
|------|------|------|
| **S0 快照**(现状加强) | 导出时跑完;帧 picker;只读 Execution | 无 WASM |
| **S1 页内重放轨迹** | 不重跑程序,只切换已序列化帧/标注 | JSON only |
| **S2 WASM 重跑** | `marqdo_wasm` + bridge:改 stdin/实参后重跑,刷新 Structure/Execution | WASM 包(可 CDN/`public/wasm/`) |
| **S3 外联沙箱** | code-card Run:浏览器内 pyodide **或** 明确标「仅 live」 | 可选;默认可关 |
默认用户站:**S0 + S1 必达**;**S2 为推荐主路径**(与「用 wasm 模拟输出」对齐);S3 单独开关。
### G3 — 公式 / 代码视觉单层真相
对「特殊赋值」块约定 **一层主视觉 + 至多一层结果**:
| 块 | 主视觉 | 允许的结果层 | 禁止 |
|----|--------|--------------|------|
| 公式 | KaTeX(formula-card 精简) | 无 Bind chip,或仅在 Variables | 再渲一份 `$$` 明文;annot 与卡重复同一 TeX |
| 外联代码 | 高亮源码(code-card) | 运行输出区 `code-out`;静态可藏 Run 或接 S2/S3 | annot 再贴整段 fence;卡下重复裸源 |
| 普通赋值 | 标记面语句 | Bind chip + L-leader | — |
Leader:仅连接「主视觉锚点 → 唯一结果 chip」;卡内不用第二套 L 线。
---
## 4. 问题清单(成文)
| ID | 问题 | 严重度 | 根因假设 |
|----|------|--------|----------|
| P1 | 静态页看不到调用/循环下拉 | 高 | 轨迹未导出完整 / picker 条件(≥2)未满足 / 读者要的是编辑参而非选帧 |
| P2 | 不能改参/stdin 再看输出 | 高 | Static 禁用 `/api/run`;无 WASM 闭环 |
| P3 | code-card Run 静态无效 | 中 | `initForeignCards` 显式禁用 |
| P4 | 公式卡 + chip + `$$` 三重 | 高 | card 与 Bind annot 叠加;块源未完全被 SpecialAssign 吞掉 |
| P5 | 代码卡 + chip + 明文三重 | 高 | 同 P4 |
| P6 | 卡内/旁碎线、错位 | 中 | leader 锚到错误节点;卡 CSS 与 annot-band 叠层 |
| P7 | 静态 stdin 体验差 | 中 | 仅有只读 hint |
---
## 5. 解决方案(详案,待选)
### 5.1 引擎策略(三选一,推荐 **B**)
| 方案 | 做法 | 优点 | 代价 |
|------|------|------|------|
| **A. 纯快照 + S1** | 加强导出轨迹与 picker;不引入 WASM | 体积小、离线稳 | 不能改参真重算 |
| **B. 快照默认 + 可选 WASM(S0/S1/S2)** | `view output` 仍嵌入跑后 HTML;页脚/侧栏「在浏览器中重跑」懒加载 WASM;改参后 patch Structure/Execution | 对齐用户预期;无 WASM 时仍可读 | 打包/加载体积;宿主能力子集 |
| **C. 静态页全面 WASM 首屏** | 打开即 WASM 跑 | 交互最强 | 冷启动慢;gh-pages 带宽;与「文档先可读」冲突 |
**推荐 B**:文档先可读(S0),帧切换不依赖 WASM(S1),需要改参/演示时再拉 WASM(S2)。
### 5.2 交互控件(与文档面一致)
1. **调用 / 循环 picker**(已有组件)
- 导出验收:欢迎页「问候」必须出现调用下拉。
- 单测:对 `00-欢迎.mq.md` / `document-annot-demo` 断言 HTML 含 `call-picker` 且 options≥2。
2. **演示参数条(新,窄范围)**
- 仅当函数被标记为「可演示」**或**静态页检测到 ≥1 形参且存在 CallFrame 时,在函数标题旁增加:
`谁 [ text input | select(历史实参) ] [应用]`
- **不**改 `.mq.md` 语法;数据来自 trace 的 `args_brief` / 末次绑定。
- 「应用」:S1 仅切换已有帧;S2 调 WASM `run` 后替换 `#structure` / Execution。
3. **stdin**
- 静态:若源含 `input`,渲染与 live 同形的 textarea +「重跑」(S2)或说明「需 WASM」。
- 无 input 则不显示。
### 5.3 公式 / 代码去重(视觉)
**规则:SpecialAssign 行只走 card,不再为同名同值挂 Bind chip。**
```text
公式赋值行
└─ formula-card(badge + 名 + KaTeX)
└─ ✗ 不再 render_annot_band(Bind f)
└─ ✗ 不再在卡外输出 $$ 源
外联赋值行
└─ code-card(badge + 名 + 高亮体 + 可选 Run)
└─ ✗ 不再 Bind chip 贴 fence 全文
└─ 运行结果只进 .code-out
```
静态 Run 策略(与 §5.1 对齐):
- S0:隐藏 Run,或保留禁用并 tooltip「打开 live view / 启用 WASM」。
- S2:Run → WASM 宿主 `foreign`(若 WASM 支持)或提示不支持。
- S3:可选 Pyodide(默认关)。
CSS:formula-card / code-card 与 `.annot-band` 垂直节奏统一;禁止对 KaTeX 节点拉 L-leader。
### 5.4 导出管线
```text
marqdo view output
→ build_file_view(跑 + annot + trace_json) // 已有
→ page_file(Static)
+ 嵌入 #mq-view-trace
+ (可选)data-wasm-url / 懒加载脚本
+ 公式/代码去重后的 structure_html
→ public/ + gh-pages
```
`--no-exec`:文档面无标注;可提示「本页为结构-only」;S2 仍可尝试 WASM 首跑(可选,默认关以免惊喜执行)。
### 5.5 明确不做(本提案)
- 静态页断点调试(仍属 `marqdo debug`)。
- 在 `public/*.mq.md` 发明新的「交互表」DSL(除非另开设计并获批)。
- 默认全站加载 Pyodide。
- 提交生成 HTML 进 `main`。
---
## 6. 分阶段开发计划(确认后执行)
| 阶段 | 内容 | 交付 | 依赖确认 |
|------|------|------|----------|
| **D0** | 本文定稿;选定引擎 **A/B/C**;是否要「演示参数条」 | 状态 → Active | **本次决策** |
| **D1** | P4/P5/P6:SpecialAssign 与 Bind 互斥;卡 CSS;去掉重复源 | 欢迎页公式/代码干净;单测 | D0 |
| **D2** | P1:导出轨迹验收 + 欢迎页 call-picker 金样;修任何「≥2 调用无下拉」bug | HTML 断言 | D0 |
| **D3** | P2/P7 S1 夯实:静态 stdin UI 形态;无 WASM 时文案清晰 | UX | D0 |
| **D4** | (若选 B)S2:静态页懒加载 WASM;「应用参数 / 重跑」刷新 Structure+Execution | `public/wasm` 或 CDN 策略;体积预算 | D0=B |
| **D5** | P3:code-card 与 S2/S3 策略落地;默认隐藏无效 Run | — | D1+D4 |
| **D6** | `build-public` / pages CI 回归;更新 [user-site.md](user-site.md) · [view.md](view.md) 验收条 | gh-pages 抽检欢迎页 | D1–D5 |
建议默认路径:**D0 选 B → D1 → D2 → D3 → D4 → D5 → D6**。
---
## 7. 决策记录
见文首「已确认」。开发按 §6:D1 → D2 → D3 → D4 → D5 → D6。
---
## 8. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:静态交互缺口、公式/代码凌乱、S0–S3 与阶段 D0–D6 |
| 2026-10-15 | Active:引擎 B;对齐 live;干净视觉;演示参数条;Run 接 WASM 否则隐藏 |
+6 -4
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定(v0.0.2 方向) |
| 日期 | 2026-08-04 |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
---
@@ -77,7 +77,7 @@ OUT_DIR/
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
- 渲染逻辑与实时 `view` **共用**同一路径:`build_file_view` → 文档面 Structure(`document.rs` + annots)→ `page_file`(同一 CSS/JS,含 call/loop picker、`#mq-view-trace`)。禁止第二套皮肤。`--no-exec` 时仍出文档面,但无运行标注。
示例:
@@ -90,14 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
## 4. 信息架构
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
侧栏文件索引 + 主区:**文档面 Structure** · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 **CSS L-leader** 引出——见 [view-document-annotations.md](view-document-annotations.md) · [view-execution-trace.md](view-execution-trace.md)。**不是** AST 卡片栈(那是 debug)。
结构旁**右侧栏**(现有 outline 槽)为:
| 区块 | 内容 |
|------|------|
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板;终态亦可刷新 Structure 内标注。
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
+261
View File
@@ -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 条警告。
+12 -5
View File
@@ -2,16 +2,23 @@
| | |
|---|---|
| 状态 | **Accepted · W0–W7 + P3 完结**(2026-08-28 复核) |
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核) |
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 |
| 状态 | **Historical capability matrix** — 作者面以 **[ext-web-artifact.md](ext-web-artifact.md)** / ADR [0007](../adr/0007-web-document-endpoint.md) 为准(2026-09-28) |
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核)· 2026-09-28(Artifact 标注) |
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状;**下文 API 名多为 W0–W7 历史面**(`compose_*` / `configure` 已废止) |
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。
> - Document/Endpoint:`type: web|endpoint` + `web.serve` / `web.render` / `web.inspect`
> - DB/cache/storage → `ext/data`;auth/oidc/rbac → `ext/security`;ws → `ext/net`
> - 统一 View:`|type|slot|value|attrs|style|`;中间件:`web.use`
> 本文件保留为**原生能力矩阵**对照,勿再按 `compose_*` / `app.configure` 写作。
---
## 0. 一句话结论
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
**能力层(plugins/web)**:中间件/JSON API、数据层、安全、内容站点、上传下载、sitemap、WebSocket 等仍在原生实现中。
**作者面(2026-09-28)**:改为 Artifact Metadata + facade;`compose_*` / `configure` **已删除**。边界不变:**纯解析进 `lib/net`,HTTP 服务器进 `plugins/web`,作者 API 进 `ext/web` + `ext/data` + `ext/security` + `ext/net`**。
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
Loaded 100 of 978 files, more files were not shown because too many files have changed in this diff. Show more