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

15 KiB
Executable File
Raw Permalink Blame History

遮蔽描述与两级检索:内置词表做范例,参数做扩展

状态 Accepted · 实施中(与 occlusion-syntax.md 同步)
日期 2026-10-22
关键决策 ①[] 是自由描述,不执行 ②两级词表:内置=范例/默认,参数=扩展 ③空载荷一律 warning ④工程化写进 README,提示词同步更新
前置 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 循环

- [从篮子里取出的每个果子](遍历 篮子 为 果)

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 第二级:参数(扩展与覆盖)

# 默认:内置 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 对应:

{ "method": "labels.search",
  "params": { "grep": ["联调中"], "also_builtin": true, "json": true } }

3.4 为什么保留内置词表

理由 说明
LLM 有范本 模型不必发明措辞,照着写即可,稳定性显著提高
跨项目可比 大家用同一套词,"还有多少没做"才有统一含义
零配置可用 CI 不必先写一份词表才能统计
失败模式可控 词不全时用参数补,而不是每个项目各自发明一套

代价:内置词表是一种"语义偏见"。缓解方式是两级—— 内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。

3.5 识别规则:纯子串,无位置/分隔符要求

// 语义示意
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="[]")
桩 + 契约(推荐) 配合返回契约声明类型 → 桩是"有类型的洞"
## 搜索

| 返回 | 类型 | 说明 |
|------|------|------|
|  | list | 命中列表(当前未接) |

[按关键词检索,接口未接,模拟](json.parse text="[]")

4.3 惯例(不强制):桩返回值带 stub: true

[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})

5. 工程化:写进 README,提示词同步更新

5.1 README 增补(README.md 新节)

工程习惯:允许申报未完成,但不允许假装完成

[按关键词检索,接口未接,待开发](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 一致):

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 无分隔符申报

[某某功能开发中](None)
marqdo labels pending            # 命中(内置「开发中」)

9.2 假算指标

本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。

9.3 假接通外部系统

[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})

9.4 该报 warning 的空载荷

[应纳税额]()          # ⚠️ label.empty_payload

9.5 项目自己的说法(参数层)

[接口还在联调,先返回空](json.parse text="[]")
marqdo labels search --grep "联调" --also-builtin   # 内置 + 自定义一起数

9.6 任意措辞(合法、不被自动分类,但可被搜)

[这段还没写完](0)
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 的六个例子。