docs(design): 关键词改为纯子串检索(无分隔符)+ 空载荷 warning + 工程化实践
按用户两点修正: 一、关键词匹配不再有任何位置/分隔符规则 —— **纯子串检索** [某某功能开发中]() 合法且可被统计;[搜索接入,待开发]、[【待开发】x] 同样命中。 关键词表扩为六组(未完成/假数据/演示/不稳/将删/待核),每组含同义词 (待开发·未开发·开发中·未实现·待接…;模拟·假数据·桩·占位·stub…)。 识别不到不报错不提示;最多取 3 组,最强者决定语义(未完成>假数据>示例>实验,将删正交)。 诚实写明子串必然误判([不属于待开发范围] 会命中):不影响执行,只让计数偏大; stubs --list 显示描述原文可人工识别;否定词窗口留作 v1.1 可选。 二、空载荷必须提示,不得静默 () 为空 → label.empty_payload(**warning**);**若描述已含关键词(已申报)则不报** ——否则每个桩都报,正好制造要消灭的疲劳。 文案:「空载荷遮蔽:请补 (),或在描述里写明未完成状态」。 三、新增「工程化」一节(本设计的真正落点) - §5.1 可直接放进 agent standing 的提示词片段:接不了就申报,别静默伪造、别声称已完成; 桩必须能跑,返回值建议带 stub:true;收尾用 stubs 工具确认剩余项。 要点:把"编造"变成"填表"——模型不必判断算不算伪造,只需写状态词。 - §5.2 三个 LLM 工具面:stubs --json(待办)/ --changed(本次改过的桩)/ labels --grep(任意词检索) - §5.3 工程指标:pending_count、unlabeled_empty、stub_ratio、stub_age - §5.4 CLI 示例 四、生命周期与防疲劳协同保持:桩(含空载荷、含未完成/假数据/将删)豁免 stale; 债务用棘轮;空载荷只在未申报时警告(说过的不再重复)。 实现点更新:src/label.rs 为检索器(label_text.contains(word)), check 三条硬规则(label.missing / label.ref_dangling / label.empty_payload warning), 关键词不影响求值,空载荷→None。 同步 occlusion-syntax.md(文法允许空载荷 + 空载荷说明 + M9 改为「关键词与桩」+ 增补措辞) 与 doc/README.md 索引。未改代码。
This commit is contained in:
1 parent
719b7a8d82
commit
619271b8eb
3 files changed
+178
-171
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) | **遮蔽描述与桩**:描述自由文本 + 关键词子串检索(非语法)· 空载荷 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 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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<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/parse` | 解析 `[描述](实现)`,**原样保存描述字符串**(不解析关键词) |
|
||||
| `src/ast.rs` | `Expr::Occluded { label: String, tags: Vec<TagGroup>, 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 的六个示例。
|
||||
Reference in new issue
Block a user