# value-scan / value-dig · 设计文档（Latest Design）

> **定位**：从**已交付的代码**里逆向萃取「值得讲的价值点」，交人勾选后深挖成可讲、可追问、可被审的文档。
> **适用**：面试/简历素材重建、模块价值盘点、交接文档提级。
> **形态**：两个 skill 接力 —— `value-scan`（广度枚举，停在人工勾选门）→ `value-dig`（深度产出，三件套任选）。
> **战果**（its 仓库实测，2026-09-18）：4 轮扫描产出 9 份文档全部通过机械校验；2 条主链路各带 1 个 P0 级实锤缺陷。

---

## 1. 为什么要有这两个 skill

盘点代码价值时，agent 有三个系统性偏差：

| 偏差 | 表现 | 解药 |
|---|---|---|
| **判不了价值** | 把"用了 Redis""有 4 个 handler"当亮点 | 简历行填空测试：`用【机制】解决了【问题】，代价是【取舍】`——机制格填不出就不是价值点 |
| **缺陷导向** | 扫一遍变成挑毛病大会，清单全是负面 | 阶段隔离：S1 只产亮点，缺陷是深挖链路时自然浮现的副产物，归宿在改造方案 |
| **自作主张** | 替用户挑完直接开写 | 门控：产出候选清单后**必须停**，勾选权在人 |

一句话设计哲学：**agent 负责采样与结构化，人负责价值判断**。

## 2. 两段流水线

```
S0 定范围 → S1 枚举 → S2 勾选【硬门：必须停】
                              ↓（人勾选 / 否决改向 A′）
                    value-dig：①功能点清单 ②设计复盘 ③改造方案（各自独立，可只做其一）
```

### value-scan（广度）

- **三层结构**：域 → 链路 → 机制节点。链路按**触发者**拆（谁在改这行数据），不按业务功能拆——收敛点多半是机制所在。
- **三条硬标准**（全过才进清单）：① 核心链路 ② 高级工程师的设计（非框架常识）③ 简历够硬。
- **数量闸**：5–8 条为宜，>12 = 颗粒度掉到实现层，退回重并。
- **两层锚点**：机制级 `路径#方法名`（不写行号，防漂移），深挖级 `文件:行号`（必须读过再写）。

### value-dig（深度）

三份文档三种读者：

| 文档 | 读者 | 灵魂 |
|---|---|---|
| ① 功能点清单 | 自己/接手人 | **主干调用骨架**：整条链压成一段伪代码，每行标方式（`[锁]``[幂等]``[MQ]`），功能点互为索引 |
| ② 设计思路与取舍 | 面试官 | 第一人称复盘 + **"与代码的对照说明"**：判断与代码事实不一致处逐条列出——诚实性是可信度唯一来源 |
| ③ 改造方案 | 架构评审 | 缺陷唯一归属地；**产出门槛**：必须有②加机制/③重构档改造点才立方案，全是补漏档不立（防灌水） |

跨文档资产复用：`tb_order_anomaly` 台账、token 锁工具、巡检 Job——两链路方案共用一套，是"结构必然"不是"省事"。

## 3. 机制设计要点（为什么这样设计）

### 3.1 门控（S2 必停）

价值判断权如果不在人，整个流水线退化成"agent 自嗨产出没人看的文档"。所以：
- 候选清单落盘 + 显式请求勾选（"请从 N 条挑 3–6 条"）；
- 用户禁用提问工具也一样停——请求写成文字；
- **整批否决且未给新目标 = 流程终点**，不强续。

### 3.2 判据外化为填空

"价值"无法定义，但"简历行填得出来吗"可判定。两级：
- **准入**：三条硬标准（反例驱动的剔除表）；
- **表达**：机制+问题两格必填，取舍格留给 value-dig（不误杀）。

被剔除的点不丢弃——进「已剔除」表注明未过哪条标准，供复核筛选口径。

### 3.3 机械校验（check.py）与模板外置

- 模板是**活资产**：产出照模板填空，被纠正过就回写模板；
- check.py 十余条规则：引号配对 / mermaid 合法性 / 表格列一致+不缩进 / 章节完整性（模板必备节 ⊆ 产出节）/ scan 专属（无代码围栏、锚点格式、候选数 ≤12）/ dig 专属（骨架行必带方式标记、证据必含行号）/ doc 专属（改造方案必有关键片段）；
- FAIL 必须为 0，WARN 允许保留但写明原因。

### 3.4 缺陷的归宿隔离

缺陷只在改造方案出现，且**不是枚举出来的是贴着链路走出来的**——三把刀（按触发者拆链路 / 竞态矩阵 / 幂等键清单+状态流转图）+ 机制模式库（结构性限制 → 可引入机制对照表）+ 三档尺度（补漏⭐/加机制⭐⭐⭐/重构⭐⭐⭐，每缺陷必追问"能否升一档"）。

## 4. 实战演化记录（its 仓库 4 轮，2026-09-18）

这轮实战暴露的边界案例与回写（模板活资产的实证）：

| # | 事件 | 回写 |
|---|---|---|
| 1 | 用户否决 5 条单点："都不够硬，直接分析整链路" | value-dig 新增**入口 A′（否决改向）**：否决原因入清单、按 B 重走、产物声明 |
| 2 | 权益域首轮以"机制格填不出"剔除，复评翻案（快照轮询机制实存，藏在 2349 行大类的私有方法群） | "机制格填不出"剔除加**硬门槛**：没读过入口方法向下 ~100 行不得定稿剔除；翻案不删行留痕 |
| 3 | "不够硬"出现两次（单点否决、权益否决） | S2 门控新增**否决即校准**：负反馈记入清单，同域复扫先读否决记录 |
| 4 | 勾选回写两次压列（3 列变 2 列） | 候选清单模板补**回写示例**（3 列不压列）；check.py 报错**附行内容摘要** |
| 5 | check.ps1 仅 Windows | 移植 **check.py**（等价回归 8 产物一致）；顺带发现初版 `__name__` 损坏静默 exit 0——校验工具自身的静默通过比报错更危险 |

### 实测产出骨架（可作参考样例）

```
docs/
├── 赢客下单-候选价值点.md        S1 清单（5 候选 + 5 剔除）
├── 赢客下单-功能点清单.md        7 功能点 + 主干骨架
├── 赢客下单-设计思路与取舍.md    4 不变量 / 7 决策 / 口述版
├── 赢客下单-改造方案.md          6 缺陷（3🔴）→ 3 阶段
├── 全仓其余域-候选价值点.md      二轮 8 候选（含翻案 ★7/★8）
├── 工单全生命周期-{功能点清单,设计思路与取舍,改造方案}.md
```

两个 P0 实锤（深挖才浮现的典型）：
- 幂等双关口键不一致：bossOrderId vs requestId，组合穿透 → 重复扣权益；
- `updateConfirmInfo` 条件更新漏 `status=51`：设计是 DB 仲裁，落地是应用层检查 → 人工确认可被自动确认覆盖。

## 5. 已知限制与下一步

| 限制 | 说明 | 候选方向 |
|---|---|---|
| 单域节奏 | 一次一域，全仓扫描靠人反复发起 | 域清单自动切片 + 断点续扫 |
| 判据主观残留 | "简历够硬"仍依赖人对目标岗位的校准 | 按 JD 关键词加权候选排序 |
| 深挖成本 | 一个功能点 ≈ 1–2 份 20KB 文档，人工审读压力大 | 功能点清单先行 + 复盘/方案按勾选再出 |
| 校验器无自检 | check.py 自身损坏会静默通过 | CI 里对已知 BAD 样例断言必 FAIL |