diff --git a/doc/README.md b/doc/README.md index 85011b7..43e8382 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 | diff --git a/doc/design/occlusion-syntax.md b/doc/design/occlusion-syntax.md index e636c43..832eddb 100644 --- a/doc/design/occlusion-syntax.md +++ b/doc/design/occlusion-syntax.md @@ -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 在旧语法上就能验证。 diff --git a/doc/design/occlusion-tags-and-stubs.md b/doc/design/occlusion-tags-and-stubs.md new file mode 100644 index 0000000..b38871b --- /dev/null +++ b/doc/design/occlusion-tags-and-stubs.md @@ -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, 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 最常见的"假接通"形态。