# 代码即文档 · 叙述面摩擦(v0.3 实测) | | | |---|---| | 状态 | **Done** | | 日期 | 2026-09-14 | | 触发 | `examples/code-as-docs/index.mq.md` 试跑 | | 宪法 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) | | 路线 | [code-as-docs-gaps.md](../roadmap/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](../../src/parse/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 |