- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
120 lines
4.8 KiB
Markdown
Executable File
120 lines
4.8 KiB
Markdown
Executable File
# 代码即文档 · 叙述面摩擦(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 |
|