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 索引。未改代码。
This commit is contained in:
1 parent
dfe99a10b4
commit
719b7a8d82
3 files changed
+210
-211
No files matched your search
+1
-1
@@ -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 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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<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` 增加"桩"一节 |
|
||||
| `src/parse` | 解析 `[描述](实现)`,**原样保存描述字符串**(不解析标签) |
|
||||
| `src/ast.rs` | `Expr::Occluded { label: String, tags: Vec<Tag>, 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 最常见的假接通形态。
|
||||
Reference in new issue
Block a user