- 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。
28 KiB
Executable File
遮蔽语法(Occlusion Syntax):[描述](实现) 设计与实施总纲
| 状态 | Accepted · 实施中(M0 起,本文档为实施依据) |
| 日期 | 2026-10-22 |
| 决策 | 纯度;标签可省略书写但编译器报错;新鲜度校验不依赖 git;会话末做一次性汇总 |
| 定位 | 本文把 []() 从「若干语法的集合」重新定义为一种语法、一个目的:遮蔽 |
| 前置 | bracket-as-label-evaluation.md · label-freshness-and-repair.md · warning-fatigue-control.md · staleness-providers.md · t1-session-staleness.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)已验证过的完整环境:
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 嵌套取值:不可读 → 可读
今天(读者要在三层括号间来回跳):
**单价 = [1]([苹果]([水果类](货架)))**
遮蔽之后:
**单价 = [水果类里苹果的第 1 项价格](at(at(at(货架, 水果类), 苹果), 1))**
人读方括号,机器读圆括号。嵌套再深,读者也只看一句人话。
1.2 长表达式打断叙述
今天:
本季度应缴税额为 **金额 * 税率 * (1 - 减免比例) + 附加费**,请注意申报期限。
一句话被一串符号劈成两半。
遮蔽之后:
本季度应缴税额为 **[应缴税额](金额 * 税率 * (1 - 减免比例) + 附加费)**,请注意申报期限。
叙述仍然是句子;复杂算式被折进 ()。
1.3 抽象层次混杂:把实现藏到读者不需要看的地方
今天(读者被迫读实现细节):
价格随会员等级浮动,具体为 **基础价 * 会员折扣[等级](折扣表) * (1 + 旺季系数)**。
遮蔽之后(论证留在叙述里,算法藏起来):
价格随会员等级浮动:**[会员最终价](基础价 * at(折扣表, 等级) * (1 + 旺季系数))**。
1.4 循环:来源从此可见
今天(渲染成「名为果的链接指向篮子」,看不出是遍历):
- [果](篮子)
**总重 = 总重 + [重量](果)**
遮蔽之后:
- [从篮子里取出的每个果子](遍历 篮子 为 果)
**总重 = 总重 + [重量](at(果, 重量))**
「从哪来」写进了人话——不再依赖读者是否用了 marqdo view 才能看懂。
1.5 带空格的函数名(已实测验证)
今天(> 调用无法表达,这是缺陷 D8):
> 加一 号 31 # ❌ unknown function `加一` —— 空格把名字切断了
遮蔽之后(( 成为明确分隔符,空格不再是切词依据):
**结果 = [加一之后的值](加一 号(31))**
实测证据(1.5.2 原型):
| 写法 | 结果 |
|---|---|
> 加一 号 31 |
❌ unknown function 加一 |
加一 号(31 )(括号调用) |
✅ 32 |
问候("世界") |
✅ 你好 世界 |
因为
()里的 callee 取「第一个(之前的全部文本」,空格不再有任何歧义。 这正是你说的「()内部对带空格的函数名处理方式很多样」——而且它不只是"很多样", 它是结构上唯一正确的处理:用括号做边界,而不是用空白。
1.6 反例:什么时候不该遮蔽
# 反例:为遮蔽而遮蔽
**总计 = [总计](a + b)** # ❌ 描述等于代码,白加一层
**[价格](price)** # ❌ 描述等于变量名,无信息增量
判据:如果描述不能比实现多提供信息(意图、来源、单位、why),就不要遮蔽。 遮蔽的收益是"读者不用读实现",若描述只是把实现读了一遍,收益为零、成本照付。
2. 定义:遮蔽语法
[ 描述 ] ( 实现 )
└─ 人读 ─┘ └─ 机读 ─┘
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 §3–§4。
6. () 之内
6.1 表达式文法不变
() 里就是今天 Marqdo 的表达式:算术、比较、调用、变量(`名`)、字面量。
不引入第二套表达式语言。
6.2 callee 可以含空格(解决 D8)
规则:callee = 第一个 ( 之前的全部文本(去首尾空白)。
[加一之后的值](加一 号(31)) # callee = "加一 号"
[会员最终价](会员价(等级=2 )) # 具名实参
依据实测:加一 号(31 ) → 32。
(当前实现的参数分词器会把 ) 吞进末个实参,需要 M1 修掉;带尾随空格即可绕过。)
6.3 取元怎么写(纯度要求)
[键](集合) 不再是取元(见 §9 迁移)。取元改为函数形:
| 语义 | 写法 |
|---|---|
| 取 Map 成员 | at(表, 键) 或 get(表, 键) |
| 取 List 第 n 项(1-based) | at(列表, 1) |
| 缺键不崩 | get(表, 键, 默认值) |
理由:与调用同一外形,读者不必区分"这是取元还是调用"—— 而这正是遮蔽语法要消灭的那种"两套读法"。
6.4 循环
- [从篮子里取出的每个果子](遍历 篮子 为 果)
[]= 人读描述(来源、单位都可写)()=遍历 <集合> 为 <变量>- 变量名从
[]搬进():[]不再兼任标识符(否则"描述"与"名字"又打架)
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 | — |
危险点:同形换义。 迁移后 [键](集合) 会变成"遮蔽整个集合",语义静默改变。
因此必须:
- 硬报错:purity 模式下遇到旧形 →
syntax.legacy_index,附迁移示例 - 机械迁移工具:
marqdo migrate labels --write - 临时标签:工具生成的标签 = 原键名,并标记为
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:引用一致性(零依赖、确定性)
规则:断言 = 标签内的 `实体`。
- 实体必须可解析(当前作用域/模块存在)
- 实体必须出现在
()的实际内容中(或经调用链可达)
不满足 → label.ref_dangling(error)。
为什么低假阳性:只有显式反引号才算断言;纯口语不参与判定。
为什么能落地:复用 Marqdo 已有的 `名` = 实体约定,零新记号。
11.2 隐式遮蔽:> 调用的描述从哪来
规则:取 > 行上方紧邻的叙述段落(连续非空行,遇空行/标题/代码行即止)作为描述。
按 `税率` 与 `档位` 计算应缴税额:
> 计税 档位=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运行 - 会话结束时输出一次:
{ "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 编译警告)。
| 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 | 是否把 []() 的官方中文名定为「遮蔽」 |
建议定为遮蔽语法,并在教程里替代"取元/循环/调用语法"的说法 |
附:一句话总结
遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。 它用链接的天然分工(人话 / 目标)实现这一点, 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制—— 而
>调用同样在负债之列。