Files
marqdo/doc/design/code-as-docs-gaps.md
cflmyandCursor 5e74ff39f2 feat(markup): code-as-docs narration surface (G1–G4) and drop --- body end
Treat --- as Markdown HR everywhere, end side-effect helpers with empty returns,
and accept soft emphasis, float literals, and dynamic footnote keys so LLM-friendly
.mq.md stays runnable. Ship the weekend coffee example plus gold fixtures.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 10:16:48 +08:00

4.8 KiB
Raw Permalink Blame History

代码即文档 · 叙述面摩擦(v0.3 实测)

状态 Done
日期 2026-09-14
触发 examples/code-as-docs/index.mq.md 试跑
宪法 markdown-mapping-v0.3.md
路线 code-as-docs-gaps.md

0. 原则

修复必须同时服务:

  1. 代码即文档:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
  2. 适配 LLM 输出:模型习惯写 --- 分段、**加粗强调**、0.85 小数、map[^`key`] 动态键——运行时应尽量「写出来就能跑」。
  3. 可执行标记仍清晰:真正的赋值 / 调用 / 返回不被误判成装饰。

1. 四个问题(实测)

G1 — 模块级 --- 被当成结构错误

现象 文件标题段落后写 Markdown 分隔线 ---,报 expected heading … got: ---
根因 词法上整行 -/* 为 Code;旧实现把函数体内 --- 当收束,模块顶却当非法。现统一为叙述跳过
人/LLM 期望 任意处 --- = GFM thematic break = 叙述噪音
决议 处处 frame 行 skip;副作用收束用 *None* / ** / ****(返回即结束函数体解析)

G2 — 叙述里的 **强调** / *斜体强调* 被当成代码/返回

现象 「本文件既是说明也是程序」→ 粗体 说明 不是赋值/调用,解析失败;*only* 类英文强调升成返回/only 变量
根因 v0.3 叙述扫描凡 **…** / *…* 一律可执行(prose.rs);Skill 曾禁止强调,但与 LLM/Markdown 习惯冲突
人/LLM 期望 装饰性强调可出现;像代码的粗体/斜体仍执行
决议 形状启发式(见 §2):像代码则执行,否则当作叙述装饰(不产生 Stmt,不升参)

G3 — 小数面量 0.85 不可用

现象 **x = 0.85** → trailing input: ".85";28 * 0.85 解析错乱;即便进到求值,* 仍只接受 int
根因 表达式主词只吃整数字面量(Literal 无 Num);运行时已有 Value::Num,二元运算未接浮点
人/LLM 期望 0.85、3.14、折扣=0.85 可写可算
决议 解析 数字.数字 → Literal::Num;* / + - 及比较在 Int/Num 间提升(与已有 cmp_ord 一致)

G4 — 动态脚注键 菜单[^`名`]

现象 菜单[^`名`] → missing map key ``名`` (把字面 `名` 当键,或解析失败)
根因 [^label] 的 label 仅为静态字符串;AST Expr::Index { label: String } 无变量槽
人/LLM 期望 表/映射按变量取键:`菜单`[^`品名`] 或 菜单[^品名]
决议 支持 [^`ident`] → 运行时用变量值作键(文本化后走现有 footnote get);静态 [^拿铁] 不变

2. 粗体/斜体「像代码」启发式

粗体 **inner** → 可执行,当且仅当

满足任一:

  • 含 =(赋值 / 命名参数调用);或
  • 以 > 开头(显式调用);或
  • 含运算符 / 索引 / 调用形:+ - * / ( ) [ ];或
  • 空白分词 ≥2 段,且其后段含数字面量、引号串、或 =(如 **加一 37**、**print text="hi"**)

否则(如 **说明**、**代码即文档**)→ 装饰,忽略。

斜体 *inner* → 返回,当且仅当

满足任一:

  • 空 / None / 无 / 空 / bool 字面;或
  • 以 > 开头;或
  • 含 = 或运算符 / 索引;或
  • 整行仅为 *…*(含缩进)——整行返回 *总额* / *n*;或
  • 行内且前方紧邻「返回」二字(叙述「接着返回n」)

否则行内简单词(如 *only*、*named*)→ 装饰,忽略。

整行 *n* 仍是返回;行内「返回n。」仍是返回。英文强调词在句中被忽略。


3. 非目标

  • 不恢复 v0.2 双模式
  • 不引入 if/return 关键字
  • 不把任意 **任意自然语言句子** 都当代码(必须过 §2)
  • 动态键第一期只做 [^`ident`],不做完整表达式 [^a+b]

4. 验收

用例 期望
顶层段落之间的 --- 可解析、可运行
「既是说明也是程序」 可解析;无 Stmt
**应付 = 原价 * 0.85** / 折扣=0.85 数值正确(浮点)
**价 = 菜单[^`名`]**(名 已绑定) 取到对应价
examples/code-as-docs/index.mq.md 用回浮点折扣与动态键后仍绿
既有 tests/markup-v03/* 与 gold 不回归

5. 修订历史

日期 说明
2026-09-14 初稿:四缝 + 启发式 + 验收
2026-09-14 落地:G1–G4 实现 + 金样;顶层 Comment 引言 skip