遮蔽描述与两级检索:内置词表做范例,参数做扩展
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 第二级:参数(扩展与覆盖)
| 参数 |
语义 |
--grep A,B |
替换为 A、B(子串、OR、英文大小写不敏感) |
--also-builtin |
与内置词表取并集 |
--group pending,demo |
用内置的某几组(不带 --grep 时) |
MLSP 对应:
3.4 为什么保留内置词表
| 理由 |
说明 |
| LLM 有范本 |
模型不必发明措辞,照着写即可,稳定性显著提高 |
| 跨项目可比 |
大家用同一套词,"还有多少没做"才有统一含义 |
| 零配置可用 |
CI 不必先写一份词表才能统计 |
| 失败模式可控 |
词不全时用参数补,而不是每个项目各自发明一套 |
代价:内置词表是一种"语义偏见"。缓解方式是两级——
内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。
3.5 识别规则:纯子串,无位置/分隔符要求
| 写法 |
命中 |
[某某功能开发中] |
✅ 无分隔符 |
[搜索接入,待开发] |
✅ 逗号 |
[搜索接入-待开发] |
✅ 连字符 |
[【待开发】搜索接入] |
✅ 括号 |
[这段还没写完] |
❌ 无词(合法,不计数) |
- 识别不到不报错、不提示——描述自由
- 误判必然存在(
[不属于待开发范围] 会命中):只影响计数,不影响执行;
输出带描述原文,人可判断;否定词窗口留 v1.1 可选
4. 桩的语义
4.1 三条规则
| # |
规则 |
原因 |
| 1 |
桩必须能跑(不得报错) |
否则整篇文档被阻断 |
| 2 |
桩必须写明返回什么 |
空载荷 → warning;写 None 也行,但不能什么都不写 |
| 3 |
桩不得被当成已完成 |
描述里申报;检索能查到;view 有徽章 |
4.2 桩返回什么
| 手段 |
写法 |
| 显式空值 |
[某某功能开发中](None) |
| 常量占位 |
[税率预报,模拟](0.1) |
| 假数据 |
[搜索结果,模拟](json.parse text="[]") |
| 桩 + 契约(推荐) |
配合返回契约声明类型 → 桩是"有类型的洞" |
4.3 惯例(不强制):桩返回值带 stub: true
5. 工程化:写进 README,提示词同步更新
5.1 README 增补(README.md 新节)
工程习惯:允许申报未完成,但不允许假装完成
- 桩必须能跑,并写清返回值(写
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 一致):
为什么这条对 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. 生命周期
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 无分隔符申报
9.2 假算指标
9.3 假接通外部系统
9.4 该报 warning 的空载荷
9.5 项目自己的说法(参数层)
9.6 任意措辞(合法、不被自动分类,但可被搜)
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 的六个例子。