docs(design): 遮蔽语法总纲(实施依据)— 示例先行 + M0–M8 实施计划

按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成
**遮蔽语法(occlusion syntax)**:用叙述显示逻辑、用括号承载实现,
解决"刻意语法设计导致文档不可读",并依靠链接特性使知识过期可被检查。

一、示例先行(六个)
1 嵌套取值:三层 [1]([苹果]([水果类](货架))) → [水果类里苹果的第 1 项价格](at(at(at(货架,水果类),苹果),1))
2 长表达式打断叙述 → [应缴税额](...) 让句子完整
3 抽象层次混杂 → 论证留在叙述,算法退居括号
4 循环来源不可见 → - [从篮子里取出的每个果子](遍历 篮子 为 果)
5 **带空格函数名(已实测)**:> 加一 号 31 ❌ unknown function 加一;
   括号调用 加一 号(31 ) ✅ 32 —— 因为 callee = 第一个 '(' 之前的全部文本,空格不再是切词依据
6 反例:描述=实现时不该遮蔽

二、核心定理(本文档的理论支点)
**遮蔽创造信任负债**:把实现藏起来,读者就必须相信描述;
不遮蔽时描述过期无伤大雅,遮蔽后描述过期=文档变假。
所以「新鲜度校验」不是附加功能,而是遮蔽语法的**合法性来源**与代价。

三、场景按动机分类(不按语法分类)
A 不可读 / B 打断叙述 / C 层次混杂 / D 来源不明 / E 名称受限。
D 与 E 是遮蔽顺带解决的问题,不是目的;按动机写才能覆盖未来没想到的不可读情形。

四、语法规范:[] 永不执行、() 唯一执行;空标签 label.missing(error);
() 内用现有表达式文法,callee 允许空格;取元改为 at/get(纯度);
循环 - [描述](遍历 集合 为 变量),变量名从 [] 搬进 ()。

五、两种遮蔽关系,**都要查**
显式遮蔽([]())与**隐式遮蔽(叙述段 + 紧接 > 调用)**——
按用户要求把 > 调用也纳入过期检查:取上方紧邻叙述段为描述,
其反引号实体须出现在实参/callee;无叙述或无反引号则跳过(零噪音)。

六、新鲜度机制:L1 引用一致性(零依赖)+ T1 会话内(repair_apply 前后版对比)
+ **会话末一次性汇总(用户要求做)**:{labels_stale_seen, fixed, outstanding, items};
能力自述与无 git 降级(沙箱 exec=false / WASM 均可用)。

七、实施计划 M0–M8(每个里程碑含目标/改动文件/关键点/测试/验收/回滚)
M0 语义冻结 / M1 () 内调用增强() 终止·逗号·嵌套·空格 callee)/ M2 遮蔽语法 /
M3 at·get 与循环 / M4 L1 / M5 隐式遮蔽 / M6 T1+汇总 / M7 迁移与版本门 / M8 呈现与门禁。
**顺序建议 M0→M1→M2→M4→M6→M5→M3→M7→M8**:先让"断言+复核+修复"跑通,
再动 506 处迁移(中间态最痛)。

八、迁移实测规模:取元 506 处/136 文件,循环 44 处/24 文件,可执行方括号调用 0
(189 行是 lib/* 的 Caller 说明,不执行)。旧形必须 syntax.legacy_index 硬报错
(同形换义最危险),并用 label.provisional 承接机械迁移,避免 506 处全红。

九、测试计划与风险登记:单元/金样/回归 554/双后端/迁移差异/反向验证/环境矩阵/性能;
硬要求"每个新检查必须证明它会响"。

十、附环境前置(踩过的坑):scripts/dev-env.sh + build-web-plugin.sh;
$HOME 不可写 → zig 缓存重定向;/tmp 是 noexec → TMPDIR 必须可执行。
基线 cargo test 554/0;check 对 59 文件 0 warning/0 error,任何里程碑不得变差。

同步在 doc/README.md 登记 5 份新设计文档。未改代码。
This commit is contained in:
cflmy committed 2026-10-22 14:03:31 +08:00
1 parent 639b0ebcd1
commit fac68e85ea
2 files changed
+603

No files matched your search

+5
View File
@@ -105,6 +105,11 @@
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
+598
View File
@@ -0,0 +1,598 @@
# 遮蔽语法(Occlusion Syntax):`[描述](实现)` 设计与实施总纲
| | |
|---|---|
| 状态 | **Proposed · 待批准后开工**(本文档为实施依据) |
| 日期 | 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) |
---
## 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 的调用形)
带括号的调用 ::= callee '(' 实参列表? ')'
callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2)
实参列表 ::= 实参 (分隔 实参)*
实参 ::= 名 '=' 值 | 值
分隔 ::= 空白 | ',' # 逗号可选、容错
```
出现位置:**表达式位置 / 语句位置 / 循环项位置**(三处形态一致)。
## 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 | 名称 | 产出 | 依赖 | 风险 |
|---|------|------|------|------|
| **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 | 低 |
**顺序建议**:M0 → M1 → M2 → M4 → 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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
---
## 附:一句话总结
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
> 它用链接的天然分工(人话 / 目标)实现这一点,
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
> 而 `>` 调用同样在负债之列。