From fac68e85ea0db6eca1e074747d629cdc890d067a Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 22 Oct 2026 14:03:31 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20=E9=81=AE=E8=94=BD=E8=AF=AD?= =?UTF-8?q?=E6=B3=95=E6=80=BB=E7=BA=B2=EF=BC=88=E5=AE=9E=E6=96=BD=E4=BE=9D?= =?UTF-8?q?=E6=8D=AE=EF=BC=89=E2=80=94=20=E7=A4=BA=E4=BE=8B=E5=85=88?= =?UTF-8?q?=E8=A1=8C=20+=20M0=E2=80=93M8=20=E5=AE=9E=E6=96=BD=E8=AE=A1?= =?UTF-8?q?=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成 **遮蔽语法(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 份新设计文档。未改代码。 --- doc/README.md | 5 + doc/design/occlusion-syntax.md | 598 +++++++++++++++++++++++++++++++++ 2 files changed, 603 insertions(+) create mode 100644 doc/design/occlusion-syntax.md diff --git a/doc/README.md b/doc/README.md index d81ef0a..85011b7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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 波次 | diff --git a/doc/design/occlusion-syntax.md b/doc/design/occlusion-syntax.md new file mode 100644 index 0000000..e636c43 --- /dev/null +++ b/doc/design/occlusion-syntax.md @@ -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 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 | + +--- + +## 附:一句话总结 + +> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。** +> 它用链接的天然分工(人话 / 目标)实现这一点, +> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制—— +> 而 `>` 调用同样在负债之列。