- 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。
15 KiB
Executable File
15 KiB
Executable File
遮蔽描述与两级检索:内置词表做范例,参数做扩展
| 状态 | Accepted · 实施中(与 occlusion-syntax.md 同步) |
| 日期 | 2026-10-22 |
| 关键决策 | ①[] 是自由描述,不执行 ②两级词表:内置=范例/默认,参数=扩展 ③空载荷一律 warning ④工程化写进 README,提示词同步更新 |
| 前置 | occlusion-syntax.md |
0. 五条定调
[]里是纯粹的描述文字,对执行没有任何作用。 编译器不解析,只做检索。- 两级词表:
- 内置词表 = 范例 + 默认检索集(零配置可用;给 LLM 一个稳定范式)
- 参数 = 扩展/覆盖(
--grep 任意词,项目自己的说法照样能搜)
- 空载荷一律 warning:
()为空说明"这段遮蔽里没有可执行内容",写None即消除。 - 强力推荐 LLM 申报:写不了真接口就"申报",别"假装"。提示词同步更新。
- 工程化实践写进 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 的六个例子。