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>
4.8 KiB
4.8 KiB
代码即文档 · 叙述面摩擦(v0.3 实测)
| 状态 | Done |
| 日期 | 2026-09-14 |
| 触发 | examples/code-as-docs/index.mq.md 试跑 |
| 宪法 | markdown-mapping-v0.3.md |
| 路线 | code-as-docs-gaps.md |
0. 原则
修复必须同时服务:
- 代码即文档:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
- 适配 LLM 输出:模型习惯写
---分段、**加粗强调**、0.85小数、map[^`key`]动态键——运行时应尽量「写出来就能跑」。 - 可执行标记仍清晰:真正的赋值 / 调用 / 返回不被误判成装饰。
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 |