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 索引。未改代码。
This commit is contained in:
cflmy committed 2026-10-22 14:08:54 +08:00
1 parent fac68e85ea
commit dfe99a10b4
3 files changed
+374 -1

No files matched your search

+1
View File
@@ -105,6 +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-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 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
+3 -1
View File
@@ -7,6 +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** |
---
@@ -441,8 +442,9 @@ 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 | 低 |
**顺序建议**:M0 → M1 → M2 → M4 → M6 → M5 → M3 → M7 → M8
**顺序建议**:M0 → M1 → M2 → (M2.5 标签/空载荷) → M4 → **M9** → M6 → M5 → M3 → M7 → M8
理由:**先把"断言 + 复核 + 修复回路"跑通(M2/M4/M6),再动 506 处迁移(M7)**。
迁移一旦开始,中间态很痛;而 L1/T1 在旧语法上就能验证。
+370
View File
@@ -0,0 +1,370 @@
# 遮蔽标签与桩:把「假接通」改造为可结算的欠据
| | |
|---|---|
| 状态 | **Proposed · 待批准**(含标签规范、桩语义、内部语法定稿) |
| 日期 | 2026-10-22 |
| 提出 | 用户:LLM 喜欢"假接通";允许它,但描述里写 `[某某功能-示例-待开发](…)`,编译器扫描后 LLM 就知道还有多少没开发 |
| 授权 | 用户授权自行制定 `()` 内部实际语法 → 本文 §2 定稿 |
| 前置 | [occlusion-syntax.md](occlusion-syntax.md) |
---
## 0. 一句话
> **遮蔽是承诺。承诺有三种状态:兑现(fresh)、过期(stale)、尚未兑现(pending)。**
> 前两种靠新鲜度机制管,**第三种靠标签管**——于是"假接通"从无法追踪的谎言,
> 变成一张**可被编译器结算的欠据**。
---
## 1. 动机:LLM 的「假接通」有三条路
模型被要求"接入搜索"时,最省力的做法是写个返回固定值的函数,然后声称已接通。
| 处理方式 | 结果 | 问题 |
|---------|------|------|
| **A 禁止**(提示词里写"不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 |
| **B 放任** | 静默假功能 | 文档撒谎,且**没人知道欠了多少** |
| **C 申报**(本方案) | 假接通仍允许,但**必须写在描述里** | 代码照跑;欠据可数、可查、可结算 |
**C 的关键**:不是提高道德要求,而是**改变激励**——
申报比伪造更省力(多写四个字),且申报之后代码**照样能跑**。
这与遮蔽语法的核心定理同源:
> 遮蔽创造信任负债。**桩是明写出来的负债;不写标签的桩,是不可见的诈骗。**
---
## 2. 内部实际语法定稿(用户授权)
`()` 内不再有"取元 / 调用 / 循环"三套写法,统一为**函数形**:
### 2.1 取元
| 语义 | 写法 |
|------|------|
| Map 取成员 | `at(表, 键)` |
| 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)` | 与现有一致 |
### 2.3 循环
```markdown
- [从篮子里取出的每个果子](遍历 篮子 为 果)
```
`遍历 <集合> 为 <变量>`;**变量名在 `()` 里**,`[]` 只写人话。
### 2.4 带空格函数名为什么成立(已实测)
`(` 是**明确分隔符**,callee 取 `(` 之前全部文本,空格不再参与切词:
| 写法 | 实测 |
|------|------|
| `> 加一 号 31` | ❌ `unknown function 加一`(空格切断) |
| `加一 号(31 )` | ✅ `32` |
> 这解决了缺陷 D8,且不是"绕过",是**结构上正确的消歧**。
### 2.5 空载荷
```markdown
[某某功能-待开发]()
```
- **空 `()` 只在带桩标签时合法**(返回 `None`)
- 无桩标签的空载荷 → `label.empty_payload`(error)
---
## 3. 标签规范
### 3.1 形态
```markdown
[ <描述文字> -<标签>[ -<标签>…] ]( <实现> )
```
```markdown
[搜索接入-模拟-待开发](搜索桩("关键词"))
[报表导出-示例](导出示例())
[旧版鉴权-废弃](旧鉴权())
```
### 3.2 提取规则(编译器实现)
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.4 为什么标签必须放在 `[]` 里
| 理由 | 说明 |
|------|------|
| 人必须看得见 | 读者一眼知道"这不是真功能" |
| 与新鲜度同处一室 | 描述与状态在同一格,机器一次读完 |
| 不可执行 | `[]` 永不执行,标签因此**不可能改变程序行为**(守住铁律 1) |
| 天然可检索 | `[^]]*-待开发` 即可全文检索,无需 AST |
---
## 4. 桩的语义:能跑,但不假装能跑
### 4.1 三条硬规则
| # | 规则 | 原因 |
|---|------|------|
| 1 | **桩必须能跑**(不得报错) | 文档要能整体执行;否则桩会阻断整篇 |
| 2 | **桩必须有标签** | 无标签的假实现就是诈骗 |
| 3 | **桩不得被当成已完成** | 编译器/LLM 读取时必须能看到 pending 状态 |
### 4.2 桩返回什么
| 手段 | 做法 |
|------|------|
| **空载荷** | `[某某功能-待开发]()` → `None` |
| **常量占位** | `[税率-待开发](0.1)` → 返回 `0.1` |
| **假数据** | `[搜索结果-模拟](json.parse text="[]")` |
| **契约约束(推荐)** | 配合契约表声明返回类型,桩返回值必须**类型正确** → 桩是"有类型的洞" |
**推荐写法**:桩 + 契约,让桩"形似"。这样下游代码能跑、类型检查能过、
而债务被明确记录。
```markdown
## 搜索
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表(当前为桩) |
```markdown
[搜索接入-模拟-待开发](json.parse text="[]")
```
---
## 5. 生命周期:欠据会自己结清
这是本设计最有价值的部分——**桩的结算与新鲜度回路共用一条通道**。
```
① 写桩 [搜索接入-模拟-待开发](json.parse text="[]")
↓
② 编译器计数 marqdo stubs → 待开发 12 处(可门禁、可给 LLM 当待办清单)
↓
③ 后续开发 把 json.parse 换成真实 HTTP 调用
↓
④ T1 检测 () 变了、[] 没变 → stale(注意:带标签者豁免!见 §5.1)
↓
⑤ LLM 复核 "这段已不是桩了" → 去掉 -待开发 标签、改写描述
↓
⑥ 债务 -1 计数自动下降
```
### 5.1 但带桩标签的遮蔽**豁免 stale**——这是刻意的
理由:桩本来就是"未完成的实现",描述也明说了。
若桩被改动就报 stale,那 12 个桩会天天报——**正好制造我们要消灭的疲劳**。
| 标签 | stale 行为 |
|------|-----------|
| 待开发 / 模拟 / 废弃 | **豁免**(不报 stale) |
| 示例 / 实验 | 正常报 |
| 无标签 | 正常报 |
于是"什么时候该去标签"由**人去判断并在开发时完成**,而不是靠报警催。
### 5.2 但需要一个反向提醒:桩可能已经悄悄实现了
豁免 stale 有代价:**桩做完了却忘了去标签**,债务就永远挂着。
对策(低成本,一次性):
- `marqdo stubs --changed`:列出**本次变更中被改过的桩**,
提示「这些桩的实现已变化,请确认是否已完成」
- 会话末汇总里带一行:`stubs_touched: 2`(不逐条报,只提数字)
这样既不天天报警,也不会永远漏掉。
---
## 6. 与防疲劳机制的协同
| 机制 | 作用 |
|------|------|
| 桩豁免 stale | 12 个桩不会变成 12 条常驻警告 |
| 债务用**棘轮**而非警告 | `stubs: 12` 进基线;CI 只在**数字增加**时失败 |
| `stubs` 是**按需命令**,不进 `check` 人类输出 | 零噪音 |
| 会话末汇总带 `stubs_touched` | 闭合,不重复 |
**棘轮示例**:
```json
// .marqdo/stubs.json(可丢弃缓存)
{ "待开发": 12, "模拟": 3, "示例": 5, "废弃": 1 }
```
`marqdo stubs --check` 只在数量**增加**时非零退出 → 老债不阻塞、新债立刻拦。
---
## 7. 编译器实现点
| 位置 | 要做的事 |
|------|---------|
| `src/parse` | 解析 `[描述](实现)` 时**从描述里抽取尾标签**,存进 AST 节点 |
| `src/ast.rs` | `Expr::Occluded { label, tags: Vec<Tag>, 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` 增加"桩"一节 |
**关键**:标签**绝不影响求值**——`[x-待开发](0.1)` 的值就是 `0.1`。
标签只影响**诊断、统计、呈现**。这守住了铁律 1(`[]` 永不执行)。
---
## 8. 示例集(全部按 LLM 真实生成风格写)
### 8.1 假装接入了搜索
```markdown
# 调研助手
## 检索资料
| 参数 | 类型 | 说明 |
|------|------|------|
| 关键词 | text | 检索词 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表 |
[检索资料-模拟-待开发](json.parse text="[]")
# main
**命中 = > 检索资料 关键词="Marqdo"**
> print text="命中 " + (len value=`命中`) + " 条"
```
**效果**:文档整体可运行(输出「命中 0 条」),债务被记 1 笔,
LLM 扫描 `stubs` 立刻知道"检索还没接"。
### 8.2 假装算出了复杂指标
```markdown
本季度 **[客户留存率-待开发](0.0)**,环比变化 **[留存环比-模拟](0.0)**。
```
**效果**:叙述读得通顺,数字是 0(不是编造的 0.73),读者与模型都看得见"未实现"。
### 8.3 假接通一个外部系统
```markdown
## 同步到 ERP
[ERP 推送-模拟-待开发](json.parse text={"ok":true,"stub":true})
```
**注意**:桩返回值里显式带 `stub: true`——**下游即使跑通也知道这是假的**。
建议写成惯例。
### 8.4 已废弃的旧实现
```markdown
## 旧版鉴权
[旧版鉴权-废弃](检查旧令牌())
```
`废弃` 不进 stale 检查;`stubs` 把它列进"待清理"。
### 8.5 反例:不该用桩的地方
```markdown
[税率-待开发](0.1) # ❌ 税率是已知常量,不是未实现功能
```
**判据**:桩只用于"**应该存在但暂未实现的连接/计算**",
不用于"作者懒得查的真实数据"。后者滥用标签会让债务失去意义。
---
## 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. 风险与反对意见
| 风险 | 说明 | 缓解 |
|------|------|------|
| **标签被滥用**(什么都标待开发) | 债务数字虚高,失去意义 | 棘轮 + `stubs --changed` + 评审约定「桩只用于未实现的连接」 |
| **桩腐化**(忘了结算) | 债务永远挂着 | 改动桩时提示(§5.2),不靠常驻警告 |
| **假功能上生产** | 最坏情况 | `废弃`/`待开发` 在 `view` 中显著标记;知识库仓可设 `--check` 为 error |
| 标签词汇不够用 | 作者想标别的 | v1 闭集;后续可扩(前端 `标签:` 配置),但**必须可枚举** |
| 与新鲜度机制打架 | 桩豁免 stale | 已明确分级(§5.1) |
| LLM 伪造标签 | 模型把真实现标成"待开发"以逃避检查 | 反向:标签**只增加可见性**,不减少任何检查(豁免 stale 换来的代价是计入债务) |
| 空载荷返回 `None` 导致下游崩 | 类型不匹配 | 推荐桩 + 契约(§4.2),让桩有类型 |
---
## 11. 待你决策
| # | 问题 | 我的建议 |
|---|------|---------|
| 1 | 标签词汇表就这 5 个(待开发/模拟/示例/实验/废弃)吗 | 是,先闭集 |
| 2 | 多重标签的"最强决定语义"顺序认可吗 | 认可则实现简单 |
| 3 | 空载荷 `()` 仅限桩标签,接受吗 | 接受(防止随手写空实现) |
| 4 | 桩是否**豁免 stale** | **是**(否则 12 个桩变 12 条常驻警告) |
| 5 | 债务用**棘轮**(禁增、容存)还是直接 error | 棘轮 |
| 6 | 是否采用「桩返回值带 `stub: true`」惯例 | 建议写进教程,不作强制 |
| 7 | 标签抽取用**从右往左**剥离已知标签,接受吗 | 接受(比从左往右稳) |
> 这七条一定,我就可以开工 M1(`()` 内语法:`,`/`)`/嵌套/空格 callee)+ M2(遮蔽 + 标签抽取),
> 然后用 **§8 的五个示例**做首批金样——它们正好覆盖 LLM 最常见的"假接通"形态。