# 遮蔽描述与两级检索:内置词表做范例,参数做扩展 | | | |---|---| | 状态 | **Accepted · 实施中**(与 [occlusion-syntax.md](occlusion-syntax.md) 同步) | | 日期 | 2026-10-22 | | 关键决策 | ①`[]` 是自由描述,不执行 ②**两级词表**:内置=范例/默认,参数=扩展 ③空载荷**一律 warning** ④工程化写进 README,提示词同步更新 | | 前置 | [occlusion-syntax.md](occlusion-syntax.md) | --- ## 0. 五条定调 1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** 编译器**不解析**,只做**检索**。 2. **两级词表**: - **内置词表 = 范例 + 默认检索集**(零配置可用;给 LLM 一个稳定范式) - **参数 = 扩展/覆盖**(`--grep 任意词`,项目自己的说法照样能搜) 3. **空载荷一律 warning**:`()` 为空说明"这段遮蔽里没有可执行内容",写 `None` 即消除。 4. **强力推荐 LLM 申报**:写不了真接口就"申报",别"假装"。提示词同步更新。 5. **工程化实践写进 README**,不另造文档。 一句话: > **描述给人读;内置词给个范式;参数给自由;空着不写会被提醒。** --- ## 1. 为什么要允许「假接通」 模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。 | 处理方式 | 结果 | 问题 | |---------|------|------| | **A 禁止**("不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 | | **B 放任** | 静默假功能 | 文档撒谎,没人知道欠了多少 | | **C 申报**(本方案) | 允许,但写进描述 | 代码照跑;欠据可数、可查 | C 的关键:**不改道德要求,改激励**——申报比伪造省力,且申报后代码照样跑。 --- ## 2. `()` 内部语法定稿 ### 2.1 取元 | 语义 | 写法 | |------|------| | Map 取成员 | `at(表, 键)` | | List 第 n 项(1-based) | `at(列表, 1)` | | 缺键取默认(不崩) | `get(表, 键, 默认值)` | ### 2.2 调用 | 形态 | 写法 | |------|------| | 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) | | 具名实参 | `计税(档位=2, 金额=100)` | | **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 | | 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` | 实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。 **`(` 是明确分隔符**——这是缺陷 D8 的结构性解法。 ### 2.3 循环 ```markdown - [从篮子里取出的每个果子](遍历 篮子 为 果) ``` ### 2.4 空载荷:**一律 warning** | 写法 | 结果 | |------|------| | `[功能,开发中]()` | ⚠️ `label.empty_payload` | | `[功能,开发中](None)` | ✅ 无警告 | | `[功能,开发中](json.parse text="[]")` | ✅ 无警告 | **为什么一律报**:空 `()` 就是"什么都没写"。哪怕桩也该说明返回什么—— `None` 也是答案,下游能据此判断。 **为什么不会造成存量噪音**:遮蔽语法是新形式,**今天仓库里一处都没有**。 > 可调旋钮(**非默认**):若实际使用中觉得"已申报的桩也报警"太吵, > 可开启「命中内置词表则降为 hint」。默认关闭——遵守"空载荷必须被看见"。 --- ## 3. 两级词表 ### 3.1 第一级:内置词表(范式 + 默认检索集) **它是什么**:编译器内置的一张**小词表**,用途三个—— | 用途 | 说明 | |------|------| | **范式** | 给 LLM 一个稳定写法:不知道怎么写状态,就照这个词表写 | | **默认检索集** | `marqdo labels pending` 零配置即可用;跨项目可比 | | **默认豁免集** | 命中这些词的遮蔽默认跳过 stale(见 §6.1) | **它不是什么**:**不是语法**。写不写、怎么写都不影响解析与执行。 ### 3.2 内置词表(v1) | 组 | 关键词(子串任一命中即算) | 计入 | |----|--------------------------|------| | **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | pending | | **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | pending | | **演示** | `示例` `样例` `demo` | demo | | **不稳** | `实验` `试验` `experimental` | experimental | | **将删** | `废弃` `弃用` `deprecated` | deprecated | | **待核** | `待校验` `未验证` `待确认` | unverified | - 组间**独立计数**,不合并 - `pending` = 未完成 ∪ 假数据(默认口径,最常用) - 词表版本随编译器走;扩词表**不动语法** ### 3.3 第二级:参数(扩展与覆盖) ```bash # 默认:内置 pending 集 marqdo labels pending # 覆盖:只用我给的词 marqdo labels search --grep "接口未联调,联调中" # 合并:我给的 + 内置 marqdo labels search --grep "联调中" --also-builtin ``` | 参数 | 语义 | |------|------| | `--grep A,B` | **替换**为 A、B(子串、OR、英文大小写不敏感) | | `--also-builtin` | 与内置词表**取并集** | | `--group pending,demo` | 用内置的某几组(不带 `--grep` 时) | MLSP 对应: ```json { "method": "labels.search", "params": { "grep": ["联调中"], "also_builtin": true, "json": true } } ``` ### 3.4 为什么保留内置词表 | 理由 | 说明 | |------|------| | **LLM 有范本** | 模型不必发明措辞,照着写即可,稳定性显著提高 | | **跨项目可比** | 大家用同一套词,"还有多少没做"才有统一含义 | | **零配置可用** | CI 不必先写一份词表才能统计 | | **失败模式可控** | 词不全时用参数补,而不是每个项目各自发明一套 | **代价**:内置词表是一种"语义偏见"。缓解方式是**两级**—— 内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。 ### 3.5 识别规则:纯子串,无位置/分隔符要求 ```rust // 语义示意 for (group, words) in TABLE(words_from_params_or_builtin) { if words.iter().any(|w| label_text.contains(w)) { hits.insert(group) } } ``` | 写法 | 命中 | |------|------| | `[某某功能开发中]` | ✅ 无分隔符 | | `[搜索接入,待开发]` | ✅ 逗号 | | `[搜索接入-待开发]` | ✅ 连字符 | | `[【待开发】搜索接入]` | ✅ 括号 | | `[这段还没写完]` | ❌ 无词(合法,不计数) | - **识别不到不报错、不提示**——描述自由 - **误判必然存在**(`[不属于待开发范围]` 会命中):只影响计数,不影响执行; 输出带描述原文,人可判断;否定词窗口留 v1.1 可选 --- ## 4. 桩的语义 ### 4.1 三条规则 | # | 规则 | 原因 | |---|------|------| | 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 | | 2 | **桩必须写明返回什么** | 空载荷 → warning;写 `None` 也行,但不能什么都不写 | | 3 | **桩不得被当成已完成** | 描述里申报;检索能查到;`view` 有徽章 | ### 4.2 桩返回什么 | 手段 | 写法 | |------|------| | 显式空值 | `[某某功能开发中](None)` | | 常量占位 | `[税率预报,模拟](0.1)` | | 假数据 | `[搜索结果,模拟](json.parse text="[]")` | | **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" | ```markdown ## 搜索 | 返回 | 类型 | 说明 | |------|------|------| | | list | 命中列表(当前未接) | [按关键词检索,接口未接,模拟](json.parse text="[]") ``` ### 4.3 惯例(不强制):桩返回值带 `stub: true` ```markdown [ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` --- ## 5. 工程化:写进 README,提示词同步更新 ### 5.1 README 增补(`README.md` 新节) > **工程习惯:允许申报未完成,但不允许假装完成** > > ```markdown > [按关键词检索,接口未接,待开发](None) > ``` > > - 桩必须能跑,并写清返回值(写 `None` 也比空着好) > - 描述是自由文本;内置词表只是推荐用词与默认检索集 > - 盘点:`marqdo labels pending`;自定义:`--grep 你的词 --also-builtin` > - 门禁:`--baseline` + `--fail-on-increase`(棘轮:只拦新增,不追旧账) > - LLM:接不了就申报;提示词见 `ext/ai/agent.mq.md` ### 5.2 提示词更新(`ext/ai/agent.mq.md`) | 位置 | 现状 | 增补 | |------|------|------| | `:48` 默认 standing(`You are a Marqdo agent…`) | 只讲"源码是真相" | 追加一句申报约定 | | `:39` how-to-act 协议段 | 只讲 CALL/READ | 追加"未完成必须申报" | **建议追加文本**(英文,与现有 standing 一致): ```text When you cannot truly wire a capability, do not fake it silently and never claim it works. Write it as an occlusion with an explicit status instead: [按关键词检索,接口未接,待开发](None) Stubs must run without error and must state their return value (None is acceptable). Before finishing, check your own declarations with labels.pending. ``` **为什么这条对 LLM 有效**:把"编造"变成"填表"——模型不必判断算不算伪造, 只需写出状态词并给一个返回值。 ### 5.3 工具面 | 工具 | 用途 | |------|------| | `labels pending` | 内置词表口径的未完成清单 | | `labels search --grep … [--json/--count/--also-builtin]` | 任意词盘点 | | `labels search … --changed` | 只看本次变更涉及的 | | MLSP `labels.search` | 协议内同上 | ### 5.4 指标 | 指标 | 算法 | |------|------| | `pending_count` | `labels pending --count` | | `unlabeled_empty` | `label.empty_payload` warning 数 | | `stub_ratio` | pending / 遮蔽总数 | | `stub_age` | 需 VCS(可选,不进默认路径) | --- ## 6. 生命周期 ``` ① 写桩 [按关键词检索,接口未接,待开发](None) ↓ ② 盘点 labels pending → 列出它 ↓ ③ 开发 换成真实 HTTP 调用 ↓ ④ 复核 去掉"待开发"字样、改写描述 ↓ ⑤ 数字-1 检索结果自动减少 ``` ### 6.1 stale 豁免(默认用内置集) | 情形 | stale 行为 | |------|-----------| | 描述命中**内置 pending 组**(未完成/假数据) | **豁免** | | 命中 `将删`(废弃) | **豁免** | | 命中 `示例` / `实验` / `待核` | 正常报 | | 空载荷 | **豁免**(它就是桩) | | 无命中、有实现 | 正常报 | | `check --stub-words "A,B"` | **覆盖**内置集,用 A,B 判定豁免 | 理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale, 12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。 ### 6.2 防"做完了忘去掉申报" - `labels search --grep … --changed`:本次变更中被改过的桩 - 会话末汇总带一行 `pending_touched: 2`(只给数字,不逐条) --- ## 7. 与防疲劳机制的协同 | 机制 | 作用 | |------|------| | 桩豁免 stale(默认内置集) | 12 个桩不会变成 12 条常驻警告 | | 债务用**棘轮**(`--baseline` + `--fail-on-increase`) | 老债不阻塞、新债立刻拦 | | 检索是**按需命令**,不进 `check` 人类输出 | 零噪音 | | 搜不到**不报错** | 描述自由,机器不纠正用词 | | 空载荷 warning 仅作用于新语法 | 不可能产生历史债 | --- ## 8. 编译器实现点 | 位置 | 要做的事 | |------|---------| | `src/parse` | 解析 `[描述](实现)`,**原样保存描述**(不解析、不分类) | | `src/ast.rs` | `Expr::Occluded { label: String, inner: Option> }` | | `src/label.rs`(新增) | **内置词表常量** + 描述索引/检索(子串、OR、大小写不敏感)+ L1 引用一致性 + T1 前后对比 | | `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、`label.empty_payload`(**warning,一律**) | | `src/interp.rs` | 描述**不影响求值**;空载荷 → `None` | | `src/main.rs` | `labels pending/search --grep … [--also-builtin/--json/--count/--changed]`;`check --stub-words …` | | `src/mlsp.rs` | `labels.search`(含 `also_builtin`)、`validate.stub_words`、会话汇总 `pending_touched` | | `src/view/render.rs` | 遮蔽渲染:描述为正文、实现可折叠;桩徽章 | | `README.md` | 新增「工程习惯」一节(§5.1) | | `ext/ai/agent.mq.md` | `:48` standing 与 `:39` 协议段追加申报约定(§5.2) | **分层**:内置词表是**数据**(常量表),检索是**纯函数**,语法**零依赖**—— 扩词表不改语法,改语法不动词表。 --- ## 9. 示例 ### 9.1 无分隔符申报 ```markdown [某某功能开发中](None) ``` ```bash marqdo labels pending # 命中(内置「开发中」) ``` ### 9.2 假算指标 ```markdown 本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。 ``` ### 9.3 假接通外部系统 ```markdown [ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` ### 9.4 该报 warning 的空载荷 ```markdown [应纳税额]() # ⚠️ label.empty_payload ``` ### 9.5 项目自己的说法(参数层) ```markdown [接口还在联调,先返回空](json.parse text="[]") ``` ```bash marqdo labels search --grep "联调" --also-builtin # 内置 + 自定义一起数 ``` ### 9.6 任意措辞(合法、不被自动分类,但可被搜) ```markdown [这段还没写完](0) ``` ```bash marqdo labels search --grep 还没写完 # LLM 自己挑的词,照样搜到 ``` --- ## 10. 风险与取舍 | 风险 | 说明 | 缓解 | |------|------|------| | 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数;输出带原文;否定词窗口留 v1.1 | | 内置词表是语义偏见 | 规定了"什么算未完成" | **两级**:内置只做默认,参数可覆盖/扩展 | | 空载荷 warning 偏多 | 作者爱留空 | 修法极简(写 `None`);仅影响新语法;可留降级旋钮 | | 桩腐化 | 忘去掉申报 | `--changed` + 会话汇总,不做常驻警告 | | 假功能上生产 | 最坏情况 | `view` 显著标记;CI 可 `--count` 门禁 | | LLM 滥用申报逃避检查 | 把真实现标成待开发 | 申报只增加可见性、不减少检查;豁免 stale 的代价是计入债务 | --- ## 11. 已定 vs 待定 **已定(本文即规范)** | 项 | 结论 | |----|------| | 描述性质 | 自由文本,不执行,不参与类型/作用域 | | 词表 | **两级**:内置范例/默认 + 参数扩展 | | 空载荷 | **一律 warning**(写 `None` 消除) | | 检索语义 | 子串 + OR + 英文大小写不敏感 | | stale 豁免 | 默认内置 pending/将删组;`--stub-words` 覆盖 | | 棘轮 | `--baseline` + `--fail-on-increase` | | 工程化落点 | README 一节 + `ext/ai` 提示词两处 | **待你点头** | # | 问题 | 建议 | |---|------|------| | 1 | 内置词表就 §3.2 这六组 | 是 | | 2 | `pending` = 未完成 ∪ 假数据 | 是 | | 3 | `--grep` 替换、`--also-builtin` 合并 | 是 | | 4 | 空载荷"降级旋钮"先不做 | 是(先按一律 warning 跑一段看噪音) | | 5 | 提示词追加文本按 §5.2 写 | 是 | > 点头后即按 M1 → M2 → M4 → M9 → M6 开工;首批金样用 §9 的六个例子。