diff --git a/doc/README.md b/doc/README.md index dc263f5..8e5a158 100644 --- a/doc/README.md +++ b/doc/README.md @@ -105,7 +105,7 @@ | [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus | | [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) | | [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) | -| [design/occlusion-tags-and-stubs.md](design/occlusion-tags-and-stubs.md) | **遮蔽描述与桩**:描述自由文本 + 内置词检索(非语法)· 内部语法定稿 · 债务可结算 | +| [design/occlusion-tags-and-stubs.md](design/occlusion-tags-and-stubs.md) | **遮蔽描述与桩**:描述自由文本 + 关键词子串检索(非语法)· 空载荷 warning · 债务可结算 + agent 申报习惯 | | [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 | | [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 | | [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 | diff --git a/doc/design/occlusion-syntax.md b/doc/design/occlusion-syntax.md index e0c07eb..0c6ea0a 100644 --- a/doc/design/occlusion-syntax.md +++ b/doc/design/occlusion-syntax.md @@ -7,7 +7,7 @@ | 决策 | 纯度;标签可省略书写但**编译器报错**;新鲜度校验**不依赖 git**;**会话末做一次性汇总** | | 定位 | 本文把 `[]()` 从「若干语法的集合」重新定义为**一种语法、一个目的:遮蔽** | | 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) · [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) · [staleness-providers.md](staleness-providers.md) · [t1-session-staleness.md](t1-session-staleness.md) | -| 增补 | [occlusion-tags-and-stubs.md](occlusion-tags-and-stubs.md) — **描述是自由文本,内置词只做「检索」不做语法**;桩语义;**`()` 内部语法定稿见该文 §2** | +| 增补 | [occlusion-tags-and-stubs.md](occlusion-tags-and-stubs.md) — **描述自由文本;关键词纯子串检索(不做语法)**;空载荷 warning;桩与工程化实践;**`()` 内部语法定稿见该文 §2** | --- @@ -232,9 +232,9 @@ source scripts/dev-env.sh # rust 1.81 + go 1.25 + python 3.12 + zig(gcc ## 5. 文法 ``` -遮蔽 ::= '[' 描述 ']' '(' 表达式 ')' -描述 ::= 非空文本(可含 `实体`、可含空格、可跨行?→ v1 不跨行) -表达式 ::= 现有表达式文法(含 §6 的调用形) +遮蔽 ::= '[' 描述 ']' '(' 表达式? ')' +描述 ::= 非空自由文本(可含 `实体`、空格、关键词;v1 不跨行) +表达式 ::= 现有表达式文法(含 §6 的调用形);**可空** → 值为 None 带括号的调用 ::= callee '(' 实参列表? ')' callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2) @@ -245,6 +245,10 @@ callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2) 出现位置:**表达式位置 / 语句位置 / 循环项位置**(三处形态一致)。 +> **空载荷 `()`**:合法(值 `None`)。若描述里**没有**申报关键词 → `label.empty_payload`(warning); +> 已申报则不打扰。描述是自由文本,关键词只做**子串检索**(无位置/分隔符要求), +> 详见 [occlusion-tags-and-stubs.md](occlusion-tags-and-stubs.md) §3–§4。 + ## 6. `()` 之内 ### 6.1 表达式文法不变 @@ -442,7 +446,7 @@ T1 刻意"不重复",因此需要**闭合**: | **M6** | T1 + 会话汇总 | `repair_apply.check_labels` + 汇总 | M2 | 低 | | **M7** | 迁移与版本门 | `marqdo migrate labels`、`syntax.legacy_index` | M3 | **高** | | **M8** | 呈现与门禁 | `view` 徽章、`labels status/review`、CI | M4–M6 | 低 | -| **M9** | 标签与桩 | **检索层**:内置词识别、`marqdo stubs`(清单/棘轮/`--changed`/`--uncounted`)、MLSP `stubs` | M2 | 低 | +| **M9** | 关键词与桩 | **检索层**:描述子串匹配(无分隔符要求)、`marqdo stubs`(清单/棘轮/`--changed`)、`labels --grep`、MLSP `stubs`、空载荷 warning | M2 | 低 | **顺序建议**:M0 → M1 → M2 → (M2.5 标签/空载荷) → M4 → **M9** → M6 → M5 → M3 → M7 → M8 diff --git a/doc/design/occlusion-tags-and-stubs.md b/doc/design/occlusion-tags-and-stubs.md index 7911006..d6ac4f0 100644 --- a/doc/design/occlusion-tags-and-stubs.md +++ b/doc/design/occlusion-tags-and-stubs.md @@ -1,51 +1,46 @@ -# 遮蔽描述与内置标签:让「假接通」变成可见的欠据 +# 遮蔽描述与关键词:让「假接通」变成可见的工程欠据 | | | |---|---| -| 状态 | **Proposed · 待批准**(含描述自由性、标签检索规则、桩语义、内部语法定稿) | +| 状态 | **Proposed · 待批准**(含描述自由性、关键词检索、空载荷警告、工程化实践) | | 日期 | 2026-10-22 | -| 提出 | 用户:允许 LLM 的"假接通",但描述里写清;编译器在描述内**检索**,让 LLM 知道还有多少没开发 | -| 修正 | **`[]` 内部是自由描述文本,标签只是「可被检索的内置词」——不是语法** | +| 提出 | 用户:允许 LLM 的"假接通",但描述里写清;编译器在描述内检索关键词 | +| 修正 | ①**空载荷必须 warning**,不得静默 ②**关键词匹配不要求任何分隔符**(纯子串检索) | | 前置 | [occlusion-syntax.md](occlusion-syntax.md) | --- -## 0. 三条定调(本文全部结论都由此推出) +## 0. 四条定调 1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** - 编译器**不解析**它,只在里面**检索**(给统计、清单、LLM 待办用)。 -2. **标签是内置词,不是语法。** 写成 `[某个功能,没开发完成]()` 完全合法; - 想让它**被统计**,再顺手写上内置词 `[某个功能,没开发完成。待开发]()`。 -3. **标签的作用是"让人和模型多看一眼"**,不是审批、不是门禁。 - 所以**标在任何地方都无害**——哪怕标在已知常量上,它只换来一次复核。 + 编译器**不解析**它,只在里面**做关键词匹配**(供统计、清单、LLM 待办)。 +2. **关键词不是语法。** `[某个功能,没开发完成]()` 合法;`[某某功能开发中]()` 也合法, + **不需要任何分隔符**——匹配就是子串检索。 +3. **空载荷必须提示。** `()` 为空 → **warning**;若描述里已有关键词(已申报),则不打扰。 +4. **强力推荐 LLM 这么写**:写不了真接口就"申报",别"假装"。 + 这一条要写进 agent 的 standing 提示词,让 Marqdo 从"语言"变成"**工程习惯**"。 一句话: -> **描述给人读,内置词给机器数;两者都不执行。** +> **描述给人读,关键词给机器数;两者都不执行;空着不写会被提醒。** --- ## 1. 为什么要允许「假接通」 -模型被要求"接入搜索"时,最省力的是写个返回固定值的函数然后声称接通。 +模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。 | 处理方式 | 结果 | 问题 | |---------|------|------| -| **A 禁止**(提示词里"不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 | +| **A 禁止**(提示词"不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 | | **B 放任** | 静默假功能 | 文档撒谎,且**没人知道欠了多少** | | **C 申报**(本方案) | 假接通仍允许,但**写进描述** | 代码照跑;欠据可数、可查、可结算 | C 的关键:**不改道德要求,改激励**——申报比伪造省力(多写几个字),且申报后代码照样跑。 -与遮蔽语法的核心定理同源: - -> 遮蔽创造信任负债。**桩是明写出来的负债;不写出来的桩,是看不见的诈骗。** - --- -## 2. 内部实际语法定稿(用户授权) - -`()` 内统一为**函数形**,不再有"取元/调用/循环"三套写法。 +## 2. `()` 内部语法定稿 ### 2.1 取元 @@ -64,8 +59,8 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 | | 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` | -**实测**:`加一 号(31 )` → `32`;而 `> 加一 号 31` → `unknown function 加一`。 -`(` 是明确分隔符,空格不再参与切词——**这是缺陷 D8 的结构性解法**。 +实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。 +**`(` 是明确分隔符,空格不再参与切词**——这是缺陷 D8 的结构性解法。 ### 2.3 循环 @@ -73,62 +68,86 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( - [从篮子里取出的每个果子](遍历 篮子 为 果) ``` -### 2.4 空载荷 +### 2.4 空载荷 → **warning** ```markdown -[某某功能,还没做]() +[某某功能,还没做]() # ⚠️ label.empty_payload ``` -- 描述非空时,`()` 可以为空 → 返回 `None`,文档照样能跑 -- **空载荷 = 桩的默认形态**,会被自动计入 `stubs --uncounted`(见 §5.3) +| 情形 | 级别 | 说明 | +|------|------|------| +| `()` 为空,描述**无**关键词 | **warning** | 「空载荷遮蔽:请补 `()`,或在描述里写明未完成状态」 | +| `()` 为空,描述**有**关键词(已申报) | 不报 | 已申报的桩,提示即噪音 | + +**为什么要 warning**:空 `()` 意味着"这段遮蔽里没有可执行内容"。 +它要么是忘了写实现,要么是桩——**两者都必须被人看见**。 +有申报就不打扰,是为了守住"说过的不再重复"。 --- -## 3. 描述文字与内置标签 +## 3. 描述文字与关键词 ### 3.1 描述是自由文本 ```markdown -[某个功能,没开发完成]() # ✅ 合法,纯人话 -[某个功能,没开发完成。待开发]() # ✅ 合法,且会被统计 -[按 `税率` 与 `档位` 计算应缴税额](…) # ✅ 可校验引用(反引号 = 断言) +[某个功能,没开发完成]() # ✅ 合法 +[某某功能开发中]() # ✅ 合法,且会被统计(无分隔符) +[按 `税率` 与 `档位` 计算应缴税额](…) # ✅ 反引号 = 可校验断言 ``` -**规则**:`[]` 内容**不参与执行、不参与类型、不参与作用域**。 -唯一约束:**不能为空**(`[](…)` → `label.missing`,因为你没写描述)。 +唯一约束:**不能为空**(`[](…)` → `label.missing`)。 +`[]` 不参与执行、类型、作用域。 -### 3.2 内置标签 = 可被检索的词(v1 词表) +### 3.2 关键词表(v1:核心词 + 同义词) -| 标签 | 含义 | 计入 | -|------|------|------| -| **待开发** | 尚未实现 | 未完成 | -| **模拟** | 假接通 / 假数据 | 未完成 | -| **示例** | 演示质量,非生产 | 示例类 | -| **实验** | 可能随时变动 | 实验类 | -| **废弃** | 将被移除 | 清理项 | +| 组 | 关键词(任一命中即算) | 计入 | +|----|----------------------|------| +| **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | 未完成 | +| **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | 未完成 | +| **演示** | `示例` `样例` `demo` | 示例类 | +| **不稳** | `实验` `试验` `experimental` | 实验类 | +| **将删** | `废弃` `弃用` `deprecated` | 清理项 | +| **待核** | `待校验` `未验证` `待确认` | 待核类 | -词表是**闭集**——只有可枚举才能统计、门禁。自由措辞("没开发完成")不计数, -但**照样合法可读**。 +**闭合但可扩**:这张表是**检索词表**,不是语法关键字。 +扩充词表**不影响任何语法规则**(后续可支持 frontmatter 自定义,见 §9)。 -### 3.3 识别规则(检索,不是解析) +### 3.3 识别规则:**纯子串匹配,无任何位置/分隔符要求** -| 位置 | 例子 | 是否识别 | -|------|------|---------| -| **描述结尾** | `[搜索接入,待开发]` / `[搜索接入-待开发]` | ✅ | -| **显式括号内**(任意位置) | `[【待开发】搜索接入]` / `[搜索接入【模拟】]` | ✅ | -| 句中裸词 | `[这个功能不需要待开发处理]` | ❌ 不识别(避免误判) | -| 拼错 | `[功能,待开发中]` | ❌ 不识别、**也不报错** | +```rust +// 语义示意:对描述原文做子串检索 +for (group, words) in KEYWORDS { + if words.iter().any(|w| label_text.contains(w)) { tags.insert(group) } +} +``` -- 最多识别 **3 个**;多个标签以**最强者**决定语义:`待开发 > 模拟 > 示例 > 实验`;`废弃` 正交 -- 分隔符随意:`-` / `-` / `,` / `,` / 空格 / 无(`[功能待开发]` 也算结尾识别) -- **识别不到不报错、不提示**——描述是自由的,机器只是"看见了就记一笔" - -### 3.4 为什么不许它影响执行 - -| 铁律 | 说明 | +| 写法 | 识别 | |------|------| -| `[]` 永不执行 | 标签因此**不可能改变程序行为**;写错标签不会让程序崩 | -| 只影响诊断/统计/呈现 | 想让程序变,只能改 `()` | +| `[某某功能开发中]` | ✅ 无分隔符 | +| `[搜索接入,待开发]` | ✅ 逗号 | +| `[搜索接入-待开发]` | ✅ 连字符 | +| `[【待开发】搜索接入]` | ✅ 括号 | +| `[这段还没写完]` | ❌ 无关键词(合法但**不计数**) | +| `[功能,待开发中]` | ✅ 命中 `待开发`(子串) | + +- 最多取 **3 组**;多组时以最强者决定语义:`未完成 > 假数据 > 示例 > 实验`;`将删` 正交 +- **识别不到不报错、不提示**——描述自由,机器只是"看见了就记一笔" + +### 3.4 误判怎么处理(诚实说明) + +子串匹配必然有误判: + +```markdown +[这段不属于待开发范围,已全部完成](真实现()) # 会命中「待开发」 +``` + +**处理原则:不设语法级否定词,靠"看得见"解决。** + +- 误判只会让**债务数字偏大**,不会让程序出错(关键词不参与执行) +- `stubs --list` 会**列出描述原文**,人一眼能看出是误判 +- 若确需排除,写反面词即可:把"待开发"改成"已完成",或加一句"(非待开发)"?—— + 注意后者仍会命中。**v1 不做否定语法**;若实际使用中误判过多,再做 + 「否定词窗口」(如 `不再|无需|非` + 关键词 → 不计),作为 v1.1 的可选项 --- @@ -139,14 +158,14 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | # | 规则 | 原因 | |---|------|------| | 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 | -| 2 | **桩必须可见** | 有内置标签 **或** 空载荷(自动计入"未标注") | +| 2 | **桩必须可见** | 有关键词(申报)或空载荷(触发 warning) | | 3 | **桩不得被当成已完成** | 编译器/LLM 读取时能看到 pending 状态 | ### 4.2 桩返回什么 | 手段 | 写法 | |------|------| -| 空载荷 | `[某某功能,没做]()` → `None` | +| 空载荷 | `[某某功能开发中]()` → `None` | | 常量占位 | `[税率预报,模拟](0.1)` | | 假数据 | `[搜索结果,模拟](json.parse text="[]")` | | **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" | @@ -156,9 +175,9 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | 返回 | 类型 | 说明 | |------|------|------| -| | list | 命中列表(当前为桩) | +| | list | 命中列表(当前未接) | -[搜索接入,模拟,待开发](json.parse text="[]") +[按关键词检索,接口未接,模拟](json.parse text="[]") ``` ### 4.3 惯例(不强制):桩返回值带 `stub: true` @@ -167,86 +186,85 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( [ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` -下游即使跑通也能看出"这是假的"。建议写进教程,但不做检查。 - --- -## 5. 标签到底带来什么 +## 5. 工程化:把"申报"变成习惯 -### 5.1 四个收益 +这是本设计真正的落点——**它不只是一个语法特性,而是一套工程习惯**。 -| 收益 | 说明 | +### 5.1 写进 agent 提示词(强烈推荐) + +```text +当你要接入一个你无法真正接入的能力时: +1) 不要静默伪造,也不要声称已完成。 +2) 用遮蔽语法写出该能力,并在描述里写明状态,例如: + [按关键词检索,接口未接,待开发]() + [搜索结果,模拟](json.parse text="[]") +3) 桩必须能跑(不得报错),返回值建议带 stub: true。 +4) 收尾时用 stubs 工具确认剩余未完成项。 +``` + +**为什么这条对 LLM 特别有效**:它把"编造"变成"填表"—— +模型不需要判断"这算不算伪造",只需要写出状态词。 + +### 5.2 三个 LLM 可用的工具面 + +| 工具 | 用途 | |------|------| -| **可统计** | `marqdo stubs` → 待开发 12 处、模拟 3 处 | -| **可门禁** | 棘轮:只拦"新增桩",不追旧账 | -| **可给 LLM 当待办** | `stubs --json` → 模型直接知道还有哪些没做 | -| **促使人/模型复核** | **这才是最实在的**:看到标签就会去读那段实现 | +| `stubs --json` | 待办清单(位置 + 描述 + 关键词) | +| `stubs --changed` | 本次变更中被改过的桩 → 判断是否已完成 | +| `labels --grep 词` | 在描述里搜任意关键词(不限词表) | -### 5.2 关于"标在已知常量上也无害" +### 5.3 工程指标(可进 CI 报告) -你说得对,我上一版把它写成反例是错的: +| 指标 | 含义 | +|------|------| +| `pending_count` | 未完成桩数(棘轮:只拦新增) | +| `unlabeled_empty` | 空载荷但无关键词(**warning 数**) | +| `stub_ratio` | 桩数 / 遮蔽总数(衡量"文档里有多少是承诺而非实现") | +| `stub_age` | 桩存在时长(需 VCS,可选) | -```markdown -[税率](0.1) # 描述 -[税率,待开发](0.1) # 多四个字 → 模型会来复核这个 0.1 是否正确 +### 5.4 检索语法示例 + +```bash +marqdo stubs # 人类读:按文件列出未完成项 +marqdo stubs --json # LLM 读 +marqdo stubs --check # 棘轮:数量增加则非零退出 +marqdo stubs --changed # 本次变更中被改过的桩 +marqdo labels --grep 接口未接 # 任意词检索描述 ``` -**代价**:债务指标被稀释(一个常量被算进"未完成")。 -**收益**:换来一次深入检查与阅读。 - -**我同意按收益优先**。但要留一个提醒机制(不报警): -`stubs --changed` 与 `stubs --uncounted` 让人能看到债务构成, -避免"全是常量占位"把数字撑大而失去参考价值。 - -### 5.3 未标注的桩也会被看见 - -```markdown -[某某功能,还没做]() # 没写内置词 -``` - -它不会被 `stubs` 的"待开发"计数捕获,但会出现在 `stubs --uncounted`: - -``` -未标注的空载荷遮蔽 3 处(建议补一个内置标签,便于统计) -``` - -**只列清单,不报警。** 这样"允许自由措辞"与"债务可见"两者都保住。 - --- ## 6. 生命周期:欠据会自己结清 ``` -① 写桩 [搜索接入,模拟,待开发](json.parse text="[]") +① 写桩 [按关键词检索,接口未接,待开发]() ↓ ② 计数 marqdo stubs → 待开发 +1 ↓ ③ 开发 换成真实 HTTP 调用 ↓ -④ 复核 复核时去掉 -待开发、改写描述 +④ 复核 复核时去掉关键词、改写描述 ↓ ⑤ 债务-1 stubs 数字自动下降 ``` -**桩与新鲜度机制共用同一条复核回路。** - -### 6.1 带桩标签的遮蔽豁免 stale +### 6.1 带桩关键词的遮蔽豁免 stale | 情况 | stale 行为 | |------|-----------| -| 有 `待开发` / `模拟` / `废弃` | **豁免**(不报) | -| 有 `示例` / `实验` | 正常报 | -| 无标签、空载荷 | **豁免**(它就是桩) | -| 无标签、有实现 | 正常报 | +| 含 `未完成` / `假数据` / `将删` 组词 | **豁免** | +| 含 `示例` / `实验` | 正常报 | +| 空载荷 | **豁免**(它就是桩) | +| 无关键词、有实现 | 正常报 | -理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale, -12 个桩会变成 12 条常驻警告——**正好制造我们要消灭的疲劳**。 +理由:桩本就是"未完成",描述已明说。若桩一被改动就报 stale, +12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。 -### 6.2 但要防"做完了忘去掉标签" +### 6.2 防"做完了忘去掉关键词" -豁免的代价是债务可能永远挂着。对策(一次性、不催): - -- `marqdo stubs --changed`:列出**本次变更中被改过的桩** → 「这些桩实现已变,确认是否已完成」 +- `stubs --changed`:列出本次变更中被改过的桩 - 会话末汇总带一行 `stubs_touched: 2`(只给数字,不逐条) --- @@ -258,13 +276,8 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | 桩豁免 stale | 12 个桩不会变成 12 条常驻警告 | | 债务用**棘轮**(基线 + 只拦新增) | 老债不阻塞、新债立刻拦 | | `stubs` 是按需命令,不进 `check` 人类输出 | 零噪音 | -| 识别不到标签**不报错** | 自由措辞不会被机器纠正 | -| 会话末汇总带 `stubs_touched` | 闭合,不重复 | - -```json -// .marqdo/stubs.json(可丢弃缓存) -{ "待开发": 12, "模拟": 3, "示例": 5, "废弃": 1, "未标注": 3 } -``` +| 关键词识别不到**不报错** | 自由措辞不会被机器纠正 | +| **空载荷只在"未申报"时警告** | 说过的不再重复 | --- @@ -272,70 +285,60 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | 位置 | 要做的事 | |------|---------| -| `src/parse` | 解析 `[描述](实现)`,**原样保存描述字符串**(不解析标签) | -| `src/ast.rs` | `Expr::Occluded { label: String, tags: Vec, inner }`;`tags` 由检索层填充 | -| `src/label.rs`(新增) | **检索器**:结尾识别 + `【】` 显式识别;`Tag` 闭集枚举;L1 引用一致性;T1 前后对比 | -| `src/check.rs` | 仅两条硬规则:`label.missing`(描述为空)、`label.ref_dangling`(引用悬空,error) | -| `src/interp.rs` | **标签不影响求值**;空载荷 → `None` | -| `src/main.rs` | `marqdo stubs [--json] [--check] [--changed] [--uncounted]`、`marqdo labels --grep 词` | +| `src/parse` | 解析 `[描述](实现)`,**原样保存描述字符串**(不解析关键词) | +| `src/ast.rs` | `Expr::Occluded { label: String, tags: Vec, inner }` | +| `src/label.rs`(新增) | **检索器**:`label_text.contains(word)` 子串匹配;`TagGroup` 闭集枚举;L1 引用一致性;T1 前后对比 | +| `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、**`label.empty_payload`(warning,有关键词则不报)** | +| `src/interp.rs` | **关键词不影响求值**;空载荷 → `None` | +| `src/main.rs` | `marqdo stubs [--json/--check/--changed]`、`marqdo labels --grep` | | `src/mlsp.rs` | `stubs` 方法;会话汇总带 `stubs_touched` | | `src/view/render.rs` | 桩徽章(显著而非隐藏) | -| `doc/` | 教程补"描述与内置标签";陷阱手册补一节 | +| `doc/` | 教程补"描述与关键词 + 申报习惯";陷阱手册补一节 | -**关键设计**:标签走"**检索层**",与语法解析解耦。 -好处:词表可以随时扩充(甚至项目自定义),**不影响任何语法规则**。 +**关键**:关键词走"**检索层**",与语法解析解耦——词表可随时扩充,不动语法。 --- -## 9. 示例集(按 LLM 真实生成风格) +## 9. 示例集(LLM 真实生成风格) -### 9.1 假装接入了搜索(空载荷) +### 9.1 无分隔符申报(你举的例子) ```markdown ## 检索资料 -| 参数 | 类型 | 说明 | -|------|------|------| -| 关键词 | text | 检索词 | - -[按关键词检索,接口还没接]() +[某某功能开发中]() ``` -文档整体可跑;`stubs --uncounted` 会列出它。 +→ 命中 `开发中` → 计入"未完成";同时因已申报,**空载荷不报警**。 -### 9.2 同样的桩,写成可统计的 - -```markdown -[按关键词检索,接口还没接。模拟,待开发](json.parse text="[]") -``` - -`stubs` → 模拟 +1、待开发 +1;LLM 的待办清单里有它。 - -### 9.3 假算指标 +### 9.2 假算指标 ```markdown 本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。 ``` -叙述读得通顺,数字是 0(**不是编造的 0.73**),人和模型都看得见未实现。 - -### 9.4 假接通外部系统 +### 9.3 假接通外部系统 ```markdown [ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` -### 9.5 已废弃 +### 9.4 混着写(描述自由) ```markdown -[旧版鉴权,废弃](检查旧令牌()) +[等接口给到再做,先返回空列表,模拟](json.parse text="[]") ``` -### 9.6 任意措辞都行(不计数,但可读) +### 9.5 该报警的空载荷 + +```markdown +[应纳税额]( ) # ⚠️ label.empty_payload:既没实现也没申报 +``` + +### 9.6 任意措辞(合法、不计数、不报错) ```markdown [这段还没写完](0) -[等接口给到再做](json.parse text="{}") ``` --- @@ -344,12 +347,12 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | 风险 | 说明 | 缓解 | |------|------|------| -| 债务指标被稀释 | 什么都标待开发 → 数字虚高 | `stubs --changed` / `--uncounted` 展示构成;**按你的判断接受这点代价** | -| 桩腐化 | 做完了忘去掉标签 | 改动时提示(§6.2),不靠常驻警告 | +| 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数不影响执行;`stubs --list` 显示原文可人工识别;必要时 v1.1 加否定词窗口 | +| 债务指标被稀释 | 什么都标 | `--changed` / `--list` 展示构成;按用户判断接受代价 | +| 桩腐化 | 做完了忘去掉词 | 改动时提示(§6.2),不靠常驻警告 | | 假功能上生产 | 最坏情况 | `view` 显著标记;知识库仓可 `--check` 为 error | -| 自由措辞无法统计 | "没开发完成"不计数 | 正是取舍:**机器只数它认得的词**;需要统计就补一个内置词 | -| LLM 滥用标签逃避检查 | 把真实现标成待开发 | 标签**只增加可见性**,不减少任何检查(豁免 stale 的代价是计入债务) | -| 词表不够用 | 想标别的 | 检索层可扩(后续支持 frontmatter 自定义词表),**不影响语法** | +| 词表不够用 | 想标别的 | 检索层可扩(后续 frontmatter 自定义),不动语法 | +| LLM 滥用关键词逃避检查 | 把真实现标成待开发 | 关键词**只增加可见性**,不减少任何检查;豁免 stale 的代价是计入债务 | --- @@ -357,13 +360,13 @@ C 的关键:**不改道德要求,改激励**——申报比伪造省力( | # | 问题 | 建议 | |---|------|------| -| 1 | 内置词表就这 5 个(待开发/模拟/示例/实验/废弃) | 是,先闭集 | -| 2 | 识别位置:**结尾 + `【】` 显式**,句中裸词不认 | 是(避免误判) | -| 3 | 识别不到**不报错** | 是(描述自由) | -| 4 | 空载荷 `()` 合法(描述非空即可),并计入"未标注" | 是 | -| 5 | 桩(含空载荷)**豁免 stale** | 是 | +| 1 | 关键词表就 §3.2 这六组吗 | 是,先闭集,可后续扩 | +| 2 | 识别方式确认是**纯子串、无位置/分隔符要求** | 是(你的定调) | +| 3 | 空载荷:**未申报 → warning;已申报 → 不报** | 是(否则每个桩都报) | +| 4 | 多组命中以最强者决定语义 | 是 | +| 5 | 桩(含空载荷、含未完成/假数据/将删)**豁免 stale** | 是 | | 6 | 债务用**棘轮**(只拦新增) | 是 | -| 7 | `stubs --uncounted` 列未标注桩 | 是(不报警) | +| 7 | 是否把 §5.1 的提示词片段正式写进 `ext/ai` 的 standing 文本 | **建议写**(这是"工程化"的落点) | -> 这七条定完,M1(`()` 内语法)+ M2(遮蔽 + 描述检索)就可以开工。 -> 首批金样用 §9 的六个示例——它们覆盖了 LLM 最常见的假接通形态。 +> 这七条定完,M1(`()` 内语法)+ M2(遮蔽 + 关键词检索 + 空载荷警告)即可开工。 +> 首批金样用 §9 的六个示例。