- 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。
625 lines
28 KiB
Markdown
Executable File
625 lines
28 KiB
Markdown
Executable File
# 遮蔽语法(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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
|
||
|
||
---
|
||
|
||
## 附:一句话总结
|
||
|
||
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
|
||
> 它用链接的天然分工(人话 / 目标)实现这一点,
|
||
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
|
||
> 而 `>` 调用同样在负债之列。
|