Files
marqdo/doc/design/occlusion-syntax.md
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

625 lines
28 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 遮蔽语法(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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
---
## 附:一句话总结
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
> 它用链接的天然分工(人话 / 目标)实现这一点,
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
> 而 `>` 调用同样在负债之列。