diff --git a/doc/README.md b/doc/README.md index 43e8382..dc263f5 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) | **遮蔽描述与桩**:描述自由文本 + 内置词检索(非语法)· 内部语法定稿 · 债务可结算 | | [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 832eddb..e0c07eb 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) — **描述是自由文本,内置词只做「检索」不做语法**;桩语义;**`()` 内部语法定稿见该文 §2** | --- @@ -442,7 +442,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`)、MLSP `stubs` | M2 | 低 | +| **M9** | 标签与桩 | **检索层**:内置词识别、`marqdo stubs`(清单/棘轮/`--changed`/`--uncounted`)、MLSP `stubs` | 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 b38871b..7911006 100644 --- a/doc/design/occlusion-tags-and-stubs.md +++ b/doc/design/occlusion-tags-and-stubs.md @@ -1,63 +1,71 @@ -# 遮蔽标签与桩:把「假接通」改造为可结算的欠据 +# 遮蔽描述与内置标签:让「假接通」变成可见的欠据 | | | |---|---| -| 状态 | **Proposed · 待批准**(含标签规范、桩语义、内部语法定稿) | +| 状态 | **Proposed · 待批准**(含描述自由性、标签检索规则、桩语义、内部语法定稿) | | 日期 | 2026-10-22 | -| 提出 | 用户:LLM 喜欢"假接通";允许它,但描述里写 `[某某功能-示例-待开发](…)`,编译器扫描后 LLM 就知道还有多少没开发 | -| 授权 | 用户授权自行制定 `()` 内部实际语法 → 本文 §2 定稿 | +| 提出 | 用户:允许 LLM 的"假接通",但描述里写清;编译器在描述内**检索**,让 LLM 知道还有多少没开发 | +| 修正 | **`[]` 内部是自由描述文本,标签只是「可被检索的内置词」——不是语法** | | 前置 | [occlusion-syntax.md](occlusion-syntax.md) | --- -## 0. 一句话 +## 0. 三条定调(本文全部结论都由此推出) -> **遮蔽是承诺。承诺有三种状态:兑现(fresh)、过期(stale)、尚未兑现(pending)。** -> 前两种靠新鲜度机制管,**第三种靠标签管**——于是"假接通"从无法追踪的谎言, -> 变成一张**可被编译器结算的欠据**。 +1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** + 编译器**不解析**它,只在里面**检索**(给统计、清单、LLM 待办用)。 +2. **标签是内置词,不是语法。** 写成 `[某个功能,没开发完成]()` 完全合法; + 想让它**被统计**,再顺手写上内置词 `[某个功能,没开发完成。待开发]()`。 +3. **标签的作用是"让人和模型多看一眼"**,不是审批、不是门禁。 + 所以**标在任何地方都无害**——哪怕标在已知常量上,它只换来一次复核。 + +一句话: + +> **描述给人读,内置词给机器数;两者都不执行。** --- -## 1. 动机:LLM 的「假接通」有三条路 +## 1. 为什么要允许「假接通」 -模型被要求"接入搜索"时,最省力的做法是写个返回固定值的函数,然后声称已接通。 +模型被要求"接入搜索"时,最省力的是写个返回固定值的函数然后声称接通。 | 处理方式 | 结果 | 问题 | |---------|------|------| -| **A 禁止**(提示词里写"不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 | +| **A 禁止**(提示词里"不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 | | **B 放任** | 静默假功能 | 文档撒谎,且**没人知道欠了多少** | -| **C 申报**(本方案) | 假接通仍允许,但**必须写在描述里** | 代码照跑;欠据可数、可查、可结算 | +| **C 申报**(本方案) | 假接通仍允许,但**写进描述** | 代码照跑;欠据可数、可查、可结算 | -**C 的关键**:不是提高道德要求,而是**改变激励**—— -申报比伪造更省力(多写四个字),且申报之后代码**照样能跑**。 +C 的关键:**不改道德要求,改激励**——申报比伪造省力(多写几个字),且申报后代码照样跑。 -这与遮蔽语法的核心定理同源: +与遮蔽语法的核心定理同源: -> 遮蔽创造信任负债。**桩是明写出来的负债;不写标签的桩,是不可见的诈骗。** +> 遮蔽创造信任负债。**桩是明写出来的负债;不写出来的桩,是看不见的诈骗。** --- ## 2. 内部实际语法定稿(用户授权) -`()` 内不再有"取元 / 调用 / 循环"三套写法,统一为**函数形**: +`()` 内统一为**函数形**,不再有"取元/调用/循环"三套写法。 ### 2.1 取元 | 语义 | 写法 | |------|------| | Map 取成员 | `at(表, 键)` | -| List 取第 n 项(1-based) | `at(列表, 1)` | +| List 第 n 项(1-based) | `at(列表, 1)` | | 缺键取默认(不崩) | `get(表, 键, 默认值)` | ### 2.2 调用 -| 形态 | 写法 | 说明 | -|------|------|------| -| 位置实参 | `加一函数(31)` | 逗号可选 | -| 多参 | `加一函数(31, 2)` ≡ `加一函数(31 2)` | 逗号容错 | -| 具名 | `计税(档位=2, 金额=100)` | `名=值` | -| **带空格的 callee** | `加一 号(31)` | **callee = 第一个 `(` 之前的全部文本**(§2.4) | -| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` | 与现有一致 | +| 形态 | 写法 | +|------|------| +| 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) | +| 具名实参 | `计税(档位=2, 金额=100)` | +| **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 | +| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` | + +**实测**:`加一 号(31 )` → `32`;而 `> 加一 号 31` → `unknown function 加一`。 +`(` 是明确分隔符,空格不再参与切词——**这是缺陷 D8 的结构性解法**。 ### 2.3 循环 @@ -65,101 +73,83 @@ - [从篮子里取出的每个果子](遍历 篮子 为 果) ``` -`遍历 <集合> 为 <变量>`;**变量名在 `()` 里**,`[]` 只写人话。 - -### 2.4 带空格函数名为什么成立(已实测) - -`(` 是**明确分隔符**,callee 取 `(` 之前全部文本,空格不再参与切词: - -| 写法 | 实测 | -|------|------| -| `> 加一 号 31` | ❌ `unknown function 加一`(空格切断) | -| `加一 号(31 )` | ✅ `32` | - -> 这解决了缺陷 D8,且不是"绕过",是**结构上正确的消歧**。 - -### 2.5 空载荷 +### 2.4 空载荷 ```markdown -[某某功能-待开发]() +[某某功能,还没做]() ``` -- **空 `()` 只在带桩标签时合法**(返回 `None`) -- 无桩标签的空载荷 → `label.empty_payload`(error) +- 描述非空时,`()` 可以为空 → 返回 `None`,文档照样能跑 +- **空载荷 = 桩的默认形态**,会被自动计入 `stubs --uncounted`(见 §5.3) --- -## 3. 标签规范 +## 3. 描述文字与内置标签 -### 3.1 形态 +### 3.1 描述是自由文本 ```markdown -[ <描述文字> -<标签>[ -<标签>…] ]( <实现> ) +[某个功能,没开发完成]() # ✅ 合法,纯人话 +[某个功能,没开发完成。待开发]() # ✅ 合法,且会被统计 +[按 `税率` 与 `档位` 计算应缴税额](…) # ✅ 可校验引用(反引号 = 断言) ``` -```markdown -[搜索接入-模拟-待开发](搜索桩("关键词")) -[报表导出-示例](导出示例()) -[旧版鉴权-废弃](旧鉴权()) -``` +**规则**:`[]` 内容**不参与执行、不参与类型、不参与作用域**。 +唯一约束:**不能为空**(`[](…)` → `label.missing`,因为你没写描述)。 -### 3.2 提取规则(编译器实现) +### 3.2 内置标签 = 可被检索的词(v1 词表) -1. **从右往左**剥离**已知标签**(闭集,见 §3.3),最多 3 个 -2. 分隔符:`-`(ASCII)或 `-`(全角)均可 -3. 剩余部分 = **描述文字**(去首尾空白) -4. 描述为空 → `label.missing`(并提示 `[某某功能-待开发]` 的正确形态) -5. **未知尾段不剥离**:`[报表-2026]` 的描述仍是"报表-2026" -6. 疑似拼错 → `label.tag_suspect`(hint):`待开发中` / `待开發` 等编辑距离 1 的尾段 -7. 要写**字面尾标签** → 转义:`\-待开发` +| 标签 | 含义 | 计入 | +|------|------|------| +| **待开发** | 尚未实现 | 未完成 | +| **模拟** | 假接通 / 假数据 | 未完成 | +| **示例** | 演示质量,非生产 | 示例类 | +| **实验** | 可能随时变动 | 实验类 | +| **废弃** | 将被移除 | 清理项 | -### 3.3 标签词汇表(v1,闭集) +词表是**闭集**——只有可枚举才能统计、门禁。自由措辞("没开发完成")不计数, +但**照样合法可读**。 -| 标签 | 含义 | 是否算未完成 | 对新鲜度的作用 | -|------|------|------------|---------------| -| **待开发** | 尚未实现,桩 | ✅ 计入债务 | **豁免 stale** | -| **模拟** | 假接通 / 假数据 | ✅ 计入债务 | **豁免 stale** | -| **示例** | 演示质量,非生产 | ⚠️ 计入"示例"类 | 不豁免 | -| **实验** | 可能随时变动 | ⚠️ 计入"实验"类 | 不豁免 | -| **废弃** | 将被移除 | ✅ 计入清理项 | **豁免 stale** | +### 3.3 识别规则(检索,不是解析) -多重标签时,**最强的一个决定语义**:`待开发 > 模拟 > 示例 > 实验`;`废弃` 正交。 +| 位置 | 例子 | 是否识别 | +|------|------|---------| +| **描述结尾** | `[搜索接入,待开发]` / `[搜索接入-待开发]` | ✅ | +| **显式括号内**(任意位置) | `[【待开发】搜索接入]` / `[搜索接入【模拟】]` | ✅ | +| 句中裸词 | `[这个功能不需要待开发处理]` | ❌ 不识别(避免误判) | +| 拼错 | `[功能,待开发中]` | ❌ 不识别、**也不报错** | -> 词汇表是**闭集**:这样"标签"才是可枚举、可统计、可门禁的; -> 自由标注会退化成注释。 +- 最多识别 **3 个**;多个标签以**最强者**决定语义:`待开发 > 模拟 > 示例 > 实验`;`废弃` 正交 +- 分隔符随意:`-` / `-` / `,` / `,` / 空格 / 无(`[功能待开发]` 也算结尾识别) +- **识别不到不报错、不提示**——描述是自由的,机器只是"看见了就记一笔" -### 3.4 为什么标签必须放在 `[]` 里 +### 3.4 为什么不许它影响执行 -| 理由 | 说明 | +| 铁律 | 说明 | |------|------| -| 人必须看得见 | 读者一眼知道"这不是真功能" | -| 与新鲜度同处一室 | 描述与状态在同一格,机器一次读完 | -| 不可执行 | `[]` 永不执行,标签因此**不可能改变程序行为**(守住铁律 1) | -| 天然可检索 | `[^]]*-待开发` 即可全文检索,无需 AST | +| `[]` 永不执行 | 标签因此**不可能改变程序行为**;写错标签不会让程序崩 | +| 只影响诊断/统计/呈现 | 想让程序变,只能改 `()` | --- -## 4. 桩的语义:能跑,但不假装能跑 +## 4. 桩的语义 -### 4.1 三条硬规则 +### 4.1 三条规则 | # | 规则 | 原因 | |---|------|------| -| 1 | **桩必须能跑**(不得报错) | 文档要能整体执行;否则桩会阻断整篇 | -| 2 | **桩必须有标签** | 无标签的假实现就是诈骗 | -| 3 | **桩不得被当成已完成** | 编译器/LLM 读取时必须能看到 pending 状态 | +| 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 | +| 2 | **桩必须可见** | 有内置标签 **或** 空载荷(自动计入"未标注") | +| 3 | **桩不得被当成已完成** | 编译器/LLM 读取时能看到 pending 状态 | ### 4.2 桩返回什么 -| 手段 | 做法 | +| 手段 | 写法 | |------|------| -| **空载荷** | `[某某功能-待开发]()` → `None` | -| **常量占位** | `[税率-待开发](0.1)` → 返回 `0.1` | -| **假数据** | `[搜索结果-模拟](json.parse text="[]")` | -| **契约约束(推荐)** | 配合契约表声明返回类型,桩返回值必须**类型正确** → 桩是"有类型的洞" | - -**推荐写法**:桩 + 契约,让桩"形似"。这样下游代码能跑、类型检查能过、 -而债务被明确记录。 +| 空载荷 | `[某某功能,没做]()` → `None` | +| 常量占位 | `[税率预报,模拟](0.1)` | +| 假数据 | `[搜索结果,模拟](json.parse text="[]")` | +| **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" | ```markdown ## 搜索 @@ -168,203 +158,212 @@ |------|------|------| | | list | 命中列表(当前为桩) | +[搜索接入,模拟,待开发](json.parse text="[]") +``` + +### 4.3 惯例(不强制):桩返回值带 `stub: true` + ```markdown -[搜索接入-模拟-待开发](json.parse text="[]") +[ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` +下游即使跑通也能看出"这是假的"。建议写进教程,但不做检查。 + --- -## 5. 生命周期:欠据会自己结清 +## 5. 标签到底带来什么 -这是本设计最有价值的部分——**桩的结算与新鲜度回路共用一条通道**。 +### 5.1 四个收益 -``` -① 写桩 [搜索接入-模拟-待开发](json.parse text="[]") - ↓ -② 编译器计数 marqdo stubs → 待开发 12 处(可门禁、可给 LLM 当待办清单) - ↓ -③ 后续开发 把 json.parse 换成真实 HTTP 调用 - ↓ -④ T1 检测 () 变了、[] 没变 → stale(注意:带标签者豁免!见 §5.1) - ↓ -⑤ LLM 复核 "这段已不是桩了" → 去掉 -待开发 标签、改写描述 - ↓ -⑥ 债务 -1 计数自动下降 +| 收益 | 说明 | +|------|------| +| **可统计** | `marqdo stubs` → 待开发 12 处、模拟 3 处 | +| **可门禁** | 棘轮:只拦"新增桩",不追旧账 | +| **可给 LLM 当待办** | `stubs --json` → 模型直接知道还有哪些没做 | +| **促使人/模型复核** | **这才是最实在的**:看到标签就会去读那段实现 | + +### 5.2 关于"标在已知常量上也无害" + +你说得对,我上一版把它写成反例是错的: + +```markdown +[税率](0.1) # 描述 +[税率,待开发](0.1) # 多四个字 → 模型会来复核这个 0.1 是否正确 ``` -### 5.1 但带桩标签的遮蔽**豁免 stale**——这是刻意的 +**代价**:债务指标被稀释(一个常量被算进"未完成")。 +**收益**:换来一次深入检查与阅读。 -理由:桩本来就是"未完成的实现",描述也明说了。 -若桩被改动就报 stale,那 12 个桩会天天报——**正好制造我们要消灭的疲劳**。 +**我同意按收益优先**。但要留一个提醒机制(不报警): +`stubs --changed` 与 `stubs --uncounted` 让人能看到债务构成, +避免"全是常量占位"把数字撑大而失去参考价值。 -| 标签 | stale 行为 | +### 5.3 未标注的桩也会被看见 + +```markdown +[某某功能,还没做]() # 没写内置词 +``` + +它不会被 `stubs` 的"待开发"计数捕获,但会出现在 `stubs --uncounted`: + +``` +未标注的空载荷遮蔽 3 处(建议补一个内置标签,便于统计) +``` + +**只列清单,不报警。** 这样"允许自由措辞"与"债务可见"两者都保住。 + +--- + +## 6. 生命周期:欠据会自己结清 + +``` +① 写桩 [搜索接入,模拟,待开发](json.parse text="[]") + ↓ +② 计数 marqdo stubs → 待开发 +1 + ↓ +③ 开发 换成真实 HTTP 调用 + ↓ +④ 复核 复核时去掉 -待开发、改写描述 + ↓ +⑤ 债务-1 stubs 数字自动下降 +``` + +**桩与新鲜度机制共用同一条复核回路。** + +### 6.1 带桩标签的遮蔽豁免 stale + +| 情况 | stale 行为 | |------|-----------| -| 待开发 / 模拟 / 废弃 | **豁免**(不报 stale) | -| 示例 / 实验 | 正常报 | -| 无标签 | 正常报 | +| 有 `待开发` / `模拟` / `废弃` | **豁免**(不报) | +| 有 `示例` / `实验` | 正常报 | +| 无标签、空载荷 | **豁免**(它就是桩) | +| 无标签、有实现 | 正常报 | -于是"什么时候该去标签"由**人去判断并在开发时完成**,而不是靠报警催。 +理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale, +12 个桩会变成 12 条常驻警告——**正好制造我们要消灭的疲劳**。 -### 5.2 但需要一个反向提醒:桩可能已经悄悄实现了 +### 6.2 但要防"做完了忘去掉标签" -豁免 stale 有代价:**桩做完了却忘了去标签**,债务就永远挂着。 -对策(低成本,一次性): +豁免的代价是债务可能永远挂着。对策(一次性、不催): -- `marqdo stubs --changed`:列出**本次变更中被改过的桩**, - 提示「这些桩的实现已变化,请确认是否已完成」 -- 会话末汇总里带一行:`stubs_touched: 2`(不逐条报,只提数字) - -这样既不天天报警,也不会永远漏掉。 +- `marqdo stubs --changed`:列出**本次变更中被改过的桩** → 「这些桩实现已变,确认是否已完成」 +- 会话末汇总带一行 `stubs_touched: 2`(只给数字,不逐条) --- -## 6. 与防疲劳机制的协同 +## 7. 与防疲劳机制的协同 | 机制 | 作用 | |------|------| | 桩豁免 stale | 12 个桩不会变成 12 条常驻警告 | -| 债务用**棘轮**而非警告 | `stubs: 12` 进基线;CI 只在**数字增加**时失败 | -| `stubs` 是**按需命令**,不进 `check` 人类输出 | 零噪音 | +| 债务用**棘轮**(基线 + 只拦新增) | 老债不阻塞、新债立刻拦 | +| `stubs` 是按需命令,不进 `check` 人类输出 | 零噪音 | +| 识别不到标签**不报错** | 自由措辞不会被机器纠正 | | 会话末汇总带 `stubs_touched` | 闭合,不重复 | -**棘轮示例**: - ```json // .marqdo/stubs.json(可丢弃缓存) -{ "待开发": 12, "模拟": 3, "示例": 5, "废弃": 1 } +{ "待开发": 12, "模拟": 3, "示例": 5, "废弃": 1, "未标注": 3 } ``` -`marqdo stubs --check` 只在数量**增加**时非零退出 → 老债不阻塞、新债立刻拦。 - --- -## 7. 编译器实现点 +## 8. 编译器实现点 | 位置 | 要做的事 | |------|---------| -| `src/parse` | 解析 `[描述](实现)` 时**从描述里抽取尾标签**,存进 AST 节点 | -| `src/ast.rs` | `Expr::Occluded { label, tags: Vec, inner }`(`Tag` 为闭集枚举) | -| `src/label.rs`(新增) | 标签抽取/校验/疑似拼错;L1 引用一致性;T1 前后对比 | -| `src/check.rs` | `label.missing` / `label.empty_payload` / `label.tag_suspect` | -| `src/interp.rs` | 桩的求值:空载荷 → `None`;非空载荷 → 正常求值(标签**不影响语义**) | -| `src/mlsp.rs` | `stubs` 方法(清单)、会话汇总带 `stubs_touched` | -| `src/main.rs` | `marqdo stubs [--json] [--check] [--changed]` | -| `src/view/render.rs` | 渲染桩徽章(`待开发` / `模拟`),默认**显著**而非隐藏 | -| `doc/` | 词汇表进教程;`tutorial/15-常见陷阱.md` 增加"桩"一节 | +| `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/mlsp.rs` | `stubs` 方法;会话汇总带 `stubs_touched` | +| `src/view/render.rs` | 桩徽章(显著而非隐藏) | +| `doc/` | 教程补"描述与内置标签";陷阱手册补一节 | -**关键**:标签**绝不影响求值**——`[x-待开发](0.1)` 的值就是 `0.1`。 -标签只影响**诊断、统计、呈现**。这守住了铁律 1(`[]` 永不执行)。 +**关键设计**:标签走"**检索层**",与语法解析解耦。 +好处:词表可以随时扩充(甚至项目自定义),**不影响任何语法规则**。 --- -## 8. 示例集(全部按 LLM 真实生成风格写) +## 9. 示例集(按 LLM 真实生成风格) -### 8.1 假装接入了搜索 +### 9.1 假装接入了搜索(空载荷) ```markdown -# 调研助手 - ## 检索资料 | 参数 | 类型 | 说明 | |------|------|------| | 关键词 | text | 检索词 | -| 返回 | 类型 | 说明 | -|------|------|------| -| | list | 命中列表 | - -[检索资料-模拟-待开发](json.parse text="[]") - -# main - -**命中 = > 检索资料 关键词="Marqdo"** -> print text="命中 " + (len value=`命中`) + " 条" +[按关键词检索,接口还没接]() ``` -**效果**:文档整体可运行(输出「命中 0 条」),债务被记 1 笔, -LLM 扫描 `stubs` 立刻知道"检索还没接"。 +文档整体可跑;`stubs --uncounted` 会列出它。 -### 8.2 假装算出了复杂指标 +### 9.2 同样的桩,写成可统计的 ```markdown -本季度 **[客户留存率-待开发](0.0)**,环比变化 **[留存环比-模拟](0.0)**。 +[按关键词检索,接口还没接。模拟,待开发](json.parse text="[]") ``` -**效果**:叙述读得通顺,数字是 0(不是编造的 0.73),读者与模型都看得见"未实现"。 +`stubs` → 模拟 +1、待开发 +1;LLM 的待办清单里有它。 -### 8.3 假接通一个外部系统 +### 9.3 假算指标 ```markdown -## 同步到 ERP - -[ERP 推送-模拟-待开发](json.parse text={"ok":true,"stub":true}) +本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。 ``` -**注意**:桩返回值里显式带 `stub: true`——**下游即使跑通也知道这是假的**。 -建议写成惯例。 +叙述读得通顺,数字是 0(**不是编造的 0.73**),人和模型都看得见未实现。 -### 8.4 已废弃的旧实现 +### 9.4 假接通外部系统 ```markdown -## 旧版鉴权 - -[旧版鉴权-废弃](检查旧令牌()) +[ERP 推送,模拟](json.parse text={"ok":true,"stub":true}) ``` -`废弃` 不进 stale 检查;`stubs` 把它列进"待清理"。 - -### 8.5 反例:不该用桩的地方 +### 9.5 已废弃 ```markdown -[税率-待开发](0.1) # ❌ 税率是已知常量,不是未实现功能 +[旧版鉴权,废弃](检查旧令牌()) ``` -**判据**:桩只用于"**应该存在但暂未实现的连接/计算**", -不用于"作者懒得查的真实数据"。后者滥用标签会让债务失去意义。 +### 9.6 任意措辞都行(不计数,但可读) + +```markdown +[这段还没写完](0) +[等接口给到再做](json.parse text="{}") +``` --- -## 9. 实施计划(增补到总纲) - -| M | 增补内容 | 依赖 | -|---|---------|------| -| M2 | 遮蔽语法解析时**顺带抽取标签**(闭集)、`label.tag_suspect` | — | -| M2.5 | `label.missing` / `label.empty_payload`(空载荷仅限桩标签) | M2 | -| M4 | L1 引用一致性(桩标签不影响引用校验) | M2 | -| **M9(新)** | `marqdo stubs`(清单/`--json`/`--check` 棘轮/`--changed`)+ MLSP `stubs` 方法 | M2 | -| M6 | 会话汇总增加 `stubs_touched` | M9 | -| M8 | `view` 桩徽章;教程补"桩"一节 | M9 | - -**建议顺序**:M2 → M2.5 → M4 → M9 → M6 → M8(标签与桩贯穿全过程,但都不动语义) - ---- - -## 10. 风险与反对意见 +## 10. 风险与取舍 | 风险 | 说明 | 缓解 | |------|------|------| -| **标签被滥用**(什么都标待开发) | 债务数字虚高,失去意义 | 棘轮 + `stubs --changed` + 评审约定「桩只用于未实现的连接」 | -| **桩腐化**(忘了结算) | 债务永远挂着 | 改动桩时提示(§5.2),不靠常驻警告 | -| **假功能上生产** | 最坏情况 | `废弃`/`待开发` 在 `view` 中显著标记;知识库仓可设 `--check` 为 error | -| 标签词汇不够用 | 作者想标别的 | v1 闭集;后续可扩(前端 `标签:` 配置),但**必须可枚举** | -| 与新鲜度机制打架 | 桩豁免 stale | 已明确分级(§5.1) | -| LLM 伪造标签 | 模型把真实现标成"待开发"以逃避检查 | 反向:标签**只增加可见性**,不减少任何检查(豁免 stale 换来的代价是计入债务) | -| 空载荷返回 `None` 导致下游崩 | 类型不匹配 | 推荐桩 + 契约(§4.2),让桩有类型 | +| 债务指标被稀释 | 什么都标待开发 → 数字虚高 | `stubs --changed` / `--uncounted` 展示构成;**按你的判断接受这点代价** | +| 桩腐化 | 做完了忘去掉标签 | 改动时提示(§6.2),不靠常驻警告 | +| 假功能上生产 | 最坏情况 | `view` 显著标记;知识库仓可 `--check` 为 error | +| 自由措辞无法统计 | "没开发完成"不计数 | 正是取舍:**机器只数它认得的词**;需要统计就补一个内置词 | +| LLM 滥用标签逃避检查 | 把真实现标成待开发 | 标签**只增加可见性**,不减少任何检查(豁免 stale 的代价是计入债务) | +| 词表不够用 | 想标别的 | 检索层可扩(后续支持 frontmatter 自定义词表),**不影响语法** | --- ## 11. 待你决策 -| # | 问题 | 我的建议 | -|---|------|---------| -| 1 | 标签词汇表就这 5 个(待开发/模拟/示例/实验/废弃)吗 | 是,先闭集 | -| 2 | 多重标签的"最强决定语义"顺序认可吗 | 认可则实现简单 | -| 3 | 空载荷 `()` 仅限桩标签,接受吗 | 接受(防止随手写空实现) | -| 4 | 桩是否**豁免 stale** | **是**(否则 12 个桩变 12 条常驻警告) | -| 5 | 债务用**棘轮**(禁增、容存)还是直接 error | 棘轮 | -| 6 | 是否采用「桩返回值带 `stub: true`」惯例 | 建议写进教程,不作强制 | -| 7 | 标签抽取用**从右往左**剥离已知标签,接受吗 | 接受(比从左往右稳) | +| # | 问题 | 建议 | +|---|------|------| +| 1 | 内置词表就这 5 个(待开发/模拟/示例/实验/废弃) | 是,先闭集 | +| 2 | 识别位置:**结尾 + `【】` 显式**,句中裸词不认 | 是(避免误判) | +| 3 | 识别不到**不报错** | 是(描述自由) | +| 4 | 空载荷 `()` 合法(描述非空即可),并计入"未标注" | 是 | +| 5 | 桩(含空载荷)**豁免 stale** | 是 | +| 6 | 债务用**棘轮**(只拦新增) | 是 | +| 7 | `stubs --uncounted` 列未标注桩 | 是(不报警) | -> 这七条一定,我就可以开工 M1(`()` 内语法:`,`/`)`/嵌套/空格 callee)+ M2(遮蔽 + 标签抽取), -> 然后用 **§8 的五个示例**做首批金样——它们正好覆盖 LLM 最常见的"假接通"形态。 +> 这七条定完,M1(`()` 内语法)+ M2(遮蔽 + 描述检索)就可以开工。 +> 首批金样用 §9 的六个示例——它们覆盖了 LLM 最常见的假接通形态。