Files
marqdo/doc/design/occlusion-description-and-search.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

427 lines
15 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 遮蔽描述与两级检索:内置词表做范例,参数做扩展
| | |
|---|---|
| 状态 | **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<Box<Expr>> }` |
| `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 的六个例子。