10 Commits
Author SHA1 Message Date
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
cflmy 307c8efa81 feat(labels): 支持多路径扫描;docs: 里程碑全量完成状态与变更文档索引
- labels 接受多个 PATH(默认 .),合并去重后扫描
- occlusion-syntax.md §13.1 记录 M0–M10 全部完成,附 11 份变更文档索引
- 全仓校验:98 个文件 check 零诊断(label.* 全为 0,确认无噪音)
- cargo test --release 605 passed / 0 failed;0 编译警告
2026-10-22 15:34:29 +08:00
cflmy 9dbcc728b6 docs(design): 记录里程碑进度 — M0/M1/M2/M2.5/M3/M4/M5/M6/M9/M10 已完成,M7/M8 待做 2026-10-22 15:23:54 +08:00
cflmy 8926f7bed6 docs(design): M0 语义冻结 — 遮蔽语法系列文档标记 Accepted
用户已批准:内置词表先按现方案(六组、两级检索),后续可调。
本提交只改文档状态,不动代码:

- occlusion-syntax.md:Proposed → Accepted · 实施中(M0 起)
- occlusion-description-and-search.md:Proposed → Accepted · 实施中
- warning-fatigue-control.md:Proposed → Accepted(机制基线:stale 是变更报告)
- staleness-providers.md:Proposed → Accepted · 修订
- t1-session-staleness.md:Proposed → Accepted · 机制说明
- label-freshness-and-repair.md:Proposed → Accepted

后续按 M1 → M2 → M2.5 → M4 → M9 → M10 → M6 → M5 → M3 → M7 → M8 逐步落地。
2026-10-22 15:03:26 +08:00
cflmy 18b0c655f7 docs: 两级词表定稿 + README 工程习惯 + M10 提示词落点
按用户决定:内置词表保留(作范例与默认检索集),检索语义仍由参数指定;
工程化写进 README;有提示词的更新提示词。

一、occlusion-description-and-search.md 改为「两级检索」
- 第一级 内置词表 = 范式 + 默认检索集 + 默认豁免集(零配置可用,跨项目可比,
  给 LLM 稳定范本,避免它每次发明措辞)。六组:未完成/假数据/演示/不稳/将删/待核;
  pending = 未完成 ∪ 假数据。
- 第二级 参数:--grep A,B 替换;--also-builtin 并集;--group 选内置组;MLSP 同构
  (labels.search { grep, also_builtin })。
- 明确:内置词表是数据不是语法;词表扩容不动语法;写别的措辞完全合法。
- 空载荷一律 warning(写 None 消除);「命中内置集则降为 hint」留作非默认旋钮。
- stale 豁免默认用内置 pending/将删组,--stub-words 可覆盖。
- 识别仍为纯子串、无位置/分隔符要求;识别不到不报错;误判只影响计数。

二、README.md 新增「工程习惯:允许申报未完成,但不允许假装完成」
- 示例:空载荷桩 / 假数据桩 + 桩契约
- 四条约定:桩必须能跑、必须写明返回值、申报有范例、接不了就申报别声称完成
- 盘点与门禁命令:labels pending / labels search --grep / --also-builtin /
  --count --baseline --fail-on-increase(棘轮)
- 指向两份设计文档

三、总纲增补 M10(工程化落点):README 一节 + ext/ai/agent.mq.md 提示词两处
(:48 默认 standing、:39 how-to-act 协议段)追加申报约定;顺序
M0→M1→M2→(M2.5)→M4→M9→M10→M6→M5→M3→M7→M8。

四、实现点明确分层:内置词表是常量数据、检索是纯函数、语法零依赖。

未改代码(README 为文档)。
2026-10-22 14:25:51 +08:00
cflmy 924885969f docs(design): 删除内置词表,检索改为调用方传词;空载荷一律 warning
用户质疑「关键词表其实不是很有必要,为什么不能允许 LLM 直接传入某个关键词做检索」——成立,
词表是冗余层。本文重写并改名 occlusion-description-and-search.md(原 occlusion-tags-and-stubs.md)。

一、编译器不再内置任何词表
只做两件事:原样保存描述字符串 + 提供参数化检索。
  marqdo labels search --grep 待开发,未实现,开发中   # OR 子串匹配
  marqdo labels search --grep 接口 --json            # 任意词
  marqdo labels search --grep 待开发 --count         # 只数数
MLSP 对应 labels.search。
删词表的理由:词表是语义偏见("什么算未完成"是项目判断);永远不全
(开发中/未接/待联调/占位/TODO 追不上真实语言);闭集要改编译器;分类应在查询期而非编译期;
LLM 更会挑词。**编译器保持哑,查询保持聪明。**

二、唯一代价与其解法
CI 需要"什么算欠债"的定义 → 不是把词表放回编译器,而是**在调用处声明**(通常写在 CI 脚本):
  marqdo labels search --grep "待开发,未实现,开发中,模拟,桩" --count \
    --baseline .marqdo/pending.json --fail-on-increase
词集在仓库里可读可改可评审,换项目只换词集,编译器一行不改。

三、空载荷改为**一律 warning**
原设计"已申报则不打扰"依赖词表;词表删掉后无法判定是否申报,故改为一律:
() 为空 → label.empty_payload。修法极简——写 None 或一个真实返回值。
实测确认 None 是合法表达式(json.stringify → null),所以 [功能开发中](None) 可用。
补充:遮蔽语法是新形式,今天仓库里一处都没有,**这条 warning 不可能产生历史债**。

四、stale 豁免也改为调用方决定
check --stub-words "待开发,模拟" / MLSP validate.stub_words;**不传则不豁免**。
与"参数化"一致:豁免也是调用方的判断,不在编译器里写死。

五、检索语义 v1:子串匹配(CJK 无词边界)+ OR + 英文忽略大小写;
输出含文件/行号/描述原文/() 代码/命中词;误判必然存在但只影响计数,且输出带原文可人工判断;
不做否定语法(留 v1.1「否定词窗口」可选项)。

六、工程化章节保留并简化:agent 提示词(写不了就申报、桩必须能跑、写清返回值、
收尾用 labels.search 自查)、四个工具面、四个指标(pending_count/unlabeled_empty/stub_ratio/stub_age)。

七、实现点:无任何词表常量;src/label.rs 为索引与检索器;
check 三条硬规则(label.missing error / label.ref_dangling error / label.empty_payload warning);
描述不影响求值;空载荷 → None。

同步 occlusion-syntax.md(空载荷说明改为一律 warning、M9 改为「描述检索与桩」、增补链接)
与 doc/README.md 索引;文档改名为 occlusion-description-and-search.md。未改代码。
2026-10-22 14:21:36 +08:00
cflmy 619271b8eb docs(design): 关键词改为纯子串检索(无分隔符)+ 空载荷 warning + 工程化实践
按用户两点修正:

一、关键词匹配不再有任何位置/分隔符规则 —— **纯子串检索**
[某某功能开发中]() 合法且可被统计;[搜索接入,待开发]、[【待开发】x] 同样命中。
关键词表扩为六组(未完成/假数据/演示/不稳/将删/待核),每组含同义词
(待开发·未开发·开发中·未实现·待接…;模拟·假数据·桩·占位·stub…)。
识别不到不报错不提示;最多取 3 组,最强者决定语义(未完成>假数据>示例>实验,将删正交)。
诚实写明子串必然误判([不属于待开发范围] 会命中):不影响执行,只让计数偏大;
stubs --list 显示描述原文可人工识别;否定词窗口留作 v1.1 可选。

二、空载荷必须提示,不得静默
() 为空 → label.empty_payload(**warning**);**若描述已含关键词(已申报)则不报**
——否则每个桩都报,正好制造要消灭的疲劳。
文案:「空载荷遮蔽:请补 (),或在描述里写明未完成状态」。

三、新增「工程化」一节(本设计的真正落点)
- §5.1 可直接放进 agent standing 的提示词片段:接不了就申报,别静默伪造、别声称已完成;
  桩必须能跑,返回值建议带 stub:true;收尾用 stubs 工具确认剩余项。
  要点:把"编造"变成"填表"——模型不必判断算不算伪造,只需写状态词。
- §5.2 三个 LLM 工具面:stubs --json(待办)/ --changed(本次改过的桩)/ labels --grep(任意词检索)
- §5.3 工程指标:pending_count、unlabeled_empty、stub_ratio、stub_age
- §5.4 CLI 示例

四、生命周期与防疲劳协同保持:桩(含空载荷、含未完成/假数据/将删)豁免 stale;
债务用棘轮;空载荷只在未申报时警告(说过的不再重复)。

实现点更新:src/label.rs 为检索器(label_text.contains(word)),
check 三条硬规则(label.missing / label.ref_dangling / label.empty_payload warning),
关键词不影响求值,空载荷→None。

同步 occlusion-syntax.md(文法允许空载荷 + 空载荷说明 + M9 改为「关键词与桩」+ 增补措辞)
与 doc/README.md 索引。未改代码。
2026-10-22 14:18:58 +08:00
cflmy 719b7a8d82 docs(design): 修正标签定位 — 描述是自由文本,内置词只做检索不做语法
按用户修正重写 occlusion-tags-and-stubs.md:
1. `[]` 里是**纯粹的描述文字,对执行零作用**;编译器不解析,只在其内**检索**
   (供统计、清单、LLM 待办)。写成 `[某个功能,没开发完成]()` 完全合法。
2. **标签不是语法**,是内置词;想被统计就顺手写上 `[某个功能,没开发完成。待开发]()`。
3. 标签的作用是"让人和模型多看一眼",不是审批、不是门禁——所以标在任何地方都无害。

识别规则改为检索语义:
- 结尾识别([搜索接入,待开发] / [搜索接入-待开发] / [功能待开发])
- 显式括号识别(【待开发】可出现在任意位置)
- 句中裸词不识别(避免误判)
- **识别不到不报错、不提示**(描述自由,机器只是"看见了就记一笔")

撤回上一版的错误判断:原把 `[税率-待开发](0.1)` 列为反例是错的。
标在已知常量上也无害——多四个字换来一次深入检查与阅读,按用户判断**收益优先**。
仅保留不报警的提醒:stubs --changed / --uncounted 展示债务构成,避免数字被撑大后失去参考。

空载荷语义调整:描述非空时 `()` 可空(返回 None),并**自动计入 `stubs --uncounted`**
(未标注的桩也会被看见),不再把"必须有内置词"作为语法门槛。

桩豁免 stale 保持(待开发/模拟/废弃,以及空载荷),并补"防忘去标签"的兜底:
stubs --changed + 会话汇总里的 stubs_touched(一次性,不催)。

实现点相应改为"检索层":parse 原样保存描述字符串;src/label.rs 为检索器;
Tag 为闭集枚举但词表可扩(后续支持 frontmatter 自定义),**不影响任何语法规则**;
check 只保留两条硬规则(label.missing 描述为空、label.ref_dangling 引用悬空)。

同步 occlusion-syntax.md(增补措辞 + M9 改为"检索层")与 doc/README.md 索引。未改代码。
2026-10-22 14:14:15 +08:00
cflmy dfe99a10b4 docs(design): 遮蔽标签与桩 — 把 LLM 的「假接通」改造成可结算的欠据
按用户提议新增:描述文字内可带尾标签([某某功能-示例-待开发](实现)),
编译器在描述里检索标签,从而让"未开发"变成可枚举、可统计、可门禁的债务。

核心框架:**遮蔽是承诺,承诺有三态** —— 兑现(fresh) / 过期(stale) / 尚未兑现(pending)。
前两态由新鲜度机制管,第三态由标签管。于是假接通从"无法追踪的谎言"变成"可结算的欠据"。

一、动机:LLM 假接通的三条路 —— 禁止(改隐蔽)、放任(静默撒谎)、**申报(本方案)**。
关键不是提高道德要求,而是改变激励:申报比伪造省力,且申报后代码照样能跑。

二、()` 内部语法定稿(用户授权自行制定)
- 取元:at(表, 键) / get(表, 键, 默认)
- 调用:callee(args),逗号可选;**callee = 第一个 '(' 之前的全部文本**(空格合法,解决 D8)
- 循环:- [描述](遍历 集合 为 变量),变量名搬进 ()
- 空载荷:() 仅在带桩标签时合法(返回 None),否则 label.empty_payload

三、标签规范
形态 [描述-标签[-标签]](实现);抽取规则:**从右往左**剥离已知标签(最多 3 个),
分隔符 - 或 -;剩余为描述;未知尾段不剥离([报表-2026] 描述不变);
疑似拼错报 label.tag_suspect;字面尾标签用 \- 转义。
词汇表 v1 闭集:待开发 / 模拟 / 示例 / 实验 / 废弃(闭集才可枚举、可统计、可门禁)。
多标签以最强者决定语义:待开发 > 模拟 > 示例 > 实验;废弃正交。
标签放 [] 里而不是 () 里:人必须看得见、与描述同处一室、不可执行(守住铁律)、可正则检索。

四、桩的语义:必须能跑(不得报错)、必须有标签、不得被当成已完成。
返回手段:空载荷 None / 常量占位 / 假数据 / **桩+契约=有类型的洞**(推荐)。
建议惯例:桩返回值显式带 stub:true,下游跑通也知道是假的。

五、生命周期(自愈):写桩 → 计数 → 开发 → T1 检测 → 复核去标签 → 债务-1。
**桩豁免 stale**(待开发/模拟/废弃):否则 12 个桩变 12 条常驻警告,正好制造要消灭的疲劳。
代价是"做完了忘去标签" → 用 stubs --changed 与会话汇总里的 stubs_touched 兜住(一次性,不催)。

六、与防疲劳机制协同:桩豁免 stale;债务用**棘轮**(stubs.json 基线,只在增加时失败);
stubs 是按需命令不进 check 人类输出;会话末汇总带 stubs_touched。

七、编译器实现点:parse 抽标签 → ast Expr::Occluded{label,tags,inner} → 新增 src/label.rs →
check 报 label.missing/empty_payload/tag_suspect → interp **标签绝不影响求值** →
mlsp stubs → main marqdo stubs → view 桩徽章。
**铁律守住:[] 永不执行,标签只影响诊断/统计/呈现。**

八、示例集(按 LLM 真实风格):假装接入搜索 / 假算指标 / 假接通 ERP / 已废弃旧实现 /
反例(税率不该标待开发——桩只用于"应存在但未实现的连接",不是懒得查的数据)。

九、实施增补:M2 抽标签、M2.5 空载荷与 label.missing、M4 L1(桩不影响引用校验)、
**M9(新)marqdo stubs(清单/--json/--check 棘轮/--changed)+ MLSP stubs**、M6 汇总加
stubs_touched、M8 view 徽章与教程。顺序 M2→M2.5→M4→M9→M6→M8。

十、风险:标签滥用(棘轮+评审约定)、桩腐化(--changed 提示,不靠常驻警告)、
假功能上生产(view 显著标记 + 知识库仓可 error)、词汇不够(后续可配但须可枚举)、
**LLM 伪造标签**(标签只增加可见性,不减少任何检查)。

同步更新 occlusion-syntax.md(增补引用 + M9 行 + 顺序)与 doc/README.md 索引。未改代码。
2026-10-22 14:08:54 +08:00
cflmy fac68e85ea docs(design): 遮蔽语法总纲(实施依据)— 示例先行 + M0–M8 实施计划
按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成
**遮蔽语法(occlusion syntax)**:用叙述显示逻辑、用括号承载实现,
解决"刻意语法设计导致文档不可读",并依靠链接特性使知识过期可被检查。

一、示例先行(六个)
1 嵌套取值:三层 [1]([苹果]([水果类](货架))) → [水果类里苹果的第 1 项价格](at(at(at(货架,水果类),苹果),1))
2 长表达式打断叙述 → [应缴税额](...) 让句子完整
3 抽象层次混杂 → 论证留在叙述,算法退居括号
4 循环来源不可见 → - [从篮子里取出的每个果子](遍历 篮子 为 果)
5 **带空格函数名(已实测)**:> 加一 号 31 ❌ unknown function 加一;
   括号调用 加一 号(31 ) ✅ 32 —— 因为 callee = 第一个 '(' 之前的全部文本,空格不再是切词依据
6 反例:描述=实现时不该遮蔽

二、核心定理(本文档的理论支点)
**遮蔽创造信任负债**:把实现藏起来,读者就必须相信描述;
不遮蔽时描述过期无伤大雅,遮蔽后描述过期=文档变假。
所以「新鲜度校验」不是附加功能,而是遮蔽语法的**合法性来源**与代价。

三、场景按动机分类(不按语法分类)
A 不可读 / B 打断叙述 / C 层次混杂 / D 来源不明 / E 名称受限。
D 与 E 是遮蔽顺带解决的问题,不是目的;按动机写才能覆盖未来没想到的不可读情形。

四、语法规范:[] 永不执行、() 唯一执行;空标签 label.missing(error);
() 内用现有表达式文法,callee 允许空格;取元改为 at/get(纯度);
循环 - [描述](遍历 集合 为 变量),变量名从 [] 搬进 ()。

五、两种遮蔽关系,**都要查**
显式遮蔽([]())与**隐式遮蔽(叙述段 + 紧接 > 调用)**——
按用户要求把 > 调用也纳入过期检查:取上方紧邻叙述段为描述,
其反引号实体须出现在实参/callee;无叙述或无反引号则跳过(零噪音)。

六、新鲜度机制:L1 引用一致性(零依赖)+ T1 会话内(repair_apply 前后版对比)
+ **会话末一次性汇总(用户要求做)**:{labels_stale_seen, fixed, outstanding, items};
能力自述与无 git 降级(沙箱 exec=false / WASM 均可用)。

七、实施计划 M0–M8(每个里程碑含目标/改动文件/关键点/测试/验收/回滚)
M0 语义冻结 / M1 () 内调用增强() 终止·逗号·嵌套·空格 callee)/ M2 遮蔽语法 /
M3 at·get 与循环 / M4 L1 / M5 隐式遮蔽 / M6 T1+汇总 / M7 迁移与版本门 / M8 呈现与门禁。
**顺序建议 M0→M1→M2→M4→M6→M5→M3→M7→M8**:先让"断言+复核+修复"跑通,
再动 506 处迁移(中间态最痛)。

八、迁移实测规模:取元 506 处/136 文件,循环 44 处/24 文件,可执行方括号调用 0
(189 行是 lib/* 的 Caller 说明,不执行)。旧形必须 syntax.legacy_index 硬报错
(同形换义最危险),并用 label.provisional 承接机械迁移,避免 506 处全红。

九、测试计划与风险登记:单元/金样/回归 554/双后端/迁移差异/反向验证/环境矩阵/性能;
硬要求"每个新检查必须证明它会响"。

十、附环境前置(踩过的坑):scripts/dev-env.sh + build-web-plugin.sh;
$HOME 不可写 → zig 缓存重定向;/tmp 是 noexec → TMPDIR 必须可执行。
基线 cargo test 554/0;check 对 59 文件 0 warning/0 error,任何里程碑不得变差。

同步在 doc/README.md 登记 5 份新设计文档。未改代码。
2026-10-22 14:03:31 +08:00