zhuyongxin
fddefab0c9
- value-scan: read-only breadth inventory of mechanisms in delivered code, stopping at the human selection gate - value-dig: depth write-up of chosen points (feature list, design review, refactor plan) with templates and mechanical checkers - Add skill-workbench design doc for the pair
116 lines
9.4 KiB
Markdown
116 lines
9.4 KiB
Markdown
---
|
||
name: value-dig
|
||
description: Use when the user has already chosen which mechanisms or value points matter and now wants them written up in depth — "把这个点写成文档", "把这条链路的实现整理成功能点", "写设计思路与取舍", "出改造方案", or when an existing module's design must be reconstructed layer by layer for an interview walkthrough. Read-only — never modifies the scanned project.
|
||
---
|
||
|
||
# value-dig · 深度产出（功能点 / 设计复盘 / 改造方案）
|
||
|
||
## 一句话
|
||
|
||
把**已经选定的**机制点写成**能讲、能追问、能被审**的文档：按需产出三件套。
|
||
|
||
**两条原则**
|
||
|
||
1. **价值优先 → 深入 → 更优方案。** 缺陷与改造只在「改造方案」里出现；功能点清单与设计复盘以"这个设计为什么好、怎么取舍"为主体。
|
||
2. **只读**：不修改被扫描项目的任何文件（新增产物不算）。
|
||
|
||
## 两种入口
|
||
|
||
| 入口 | 情形 | 怎么做 |
|
||
|---|---|---|
|
||
| **A · 有候选清单** | 上游 `value-scan` 已产出且人已勾选 | 直接开工；勾选结果回写候选清单「闸门状态」节（`✅ 已勾选：★N…⟨谁/日期⟩`） |
|
||
| **A′ · 候选被否决改向** | 人看了清单说"都不够硬，直接分析整条链路"——否决候选但给出新目标 | 三步：①原清单「闸门状态」记**否决原因原文摘要**（这是筛选口径的校准数据）；②按 B 的最小枚举对准新目标重走；③产物头部声明"入口 A′（否决改向）" |
|
||
| **B · 直接点名** | 用户直接说"把 XX 链路写成文档"，无候选清单 | 只针对该链路按 `value-scan` 的判据做一次**最小枚举**（按触发者拆链路 + 三条硬标准），在产物头部声明"入口 B" |
|
||
|
||
> **入口 B 不能省粗筛**：跳过判据会把"框架常识/纯业务实现"写成深度文档。
|
||
|
||
## 三份文档（各自独立，可只做其一）
|
||
|
||
> 若用户只要"每个点先给个轻理由看看"再决定深挖谁，可用 `assets/价值点报告模板.md` 快速产出一份轻量报告，不必直接进三件套。
|
||
|
||
| 文档 | 模板 | 内容 | 关键 |
|
||
|---|---|---|---|
|
||
| ① **功能点清单** | `assets/深度模板/功能点清单模板.md` | 链路总览 · **主干调用骨架** · 各功能点 · 推荐组合 · 附录速查 | **只记功能点，不列缺陷** |
|
||
| ② **设计思路与取舍** | `assets/深度模板/设计思路与取舍模板.md` | 第一人称复盘：问题定义 → 不变量 → 怎么拆 → 设计主线 → 逐环节决策表 → 做对的/承接不住的 → 重做改什么 → 面试口述版 | 讲**取舍与代价**，不只讲做法 |
|
||
| ③ **改造方案** | `assets/深度模板/改造方案模板.md` | 缺陷（含严重度）→ **改造前链路骨架**（整体调用关系，伪代码）→ 总体思路 → 分阶段（每点含**关键片段**（伪代码/SQL）+ 验收）→ 迁移灰度 → 不变量由谁保证 | **缺陷的唯一归属地**；复用既有资产，不重复建表。**代码讲解要求：交付标准是"照着能讲代码"**——§1 必有改造前链路骨架（写清谁调谁、每步做了什么，可标类名/方法名，**不写路径与行号**）、每个改造点必有「关键片段」（伪代码/SQL，只示形状）；只有观点没有片段即不达标。**产出门槛：深挖浮现的缺口中至少存在一个②加机制/③重构档的改造点才立方案；全是①档补漏的（加缓存/加判断/加隔离/改配置类），在设计复盘"重做改什么"里带一句即可，不单独成文——硬写就是灌水** |
|
||
|
||
### ① 功能点清单的必备件：主干调用骨架
|
||
|
||
把整条链路的 N 段主干压成**一段连续伪代码**，每行右侧标注方式（`[锁]` `[幂等]` `[策略]` `[MQ]` `[外调]` `[落库]` `[兜底]` `[履历]` `[通知]` `[隔离]` `[验签]`）；附方式图例（反向索引）。**每个功能点必须能在骨架上找到**（互为索引）。
|
||
|
||
### ③ 改造方案的取材工具（深入链路时用）
|
||
|
||
缺陷**不是枚举出来的，是贴着链路走一遍时浮现的**。深挖时用这三把刀看结构，发现的缺口按「机制模式库」比对出改造方向：
|
||
|
||
| 刀 | 怎么做 |
|
||
|---|---|
|
||
| **按触发者拆链路** | 找「同一行数据被几个触发者改」→ 判断收敛/防重是否单点 |
|
||
| **竞态矩阵** | 「并发场景 × 后果」穷举表：重复回调 / 回调与兜底并发 / 并发退款… |
|
||
| **幂等键清单 + 状态流转图** | 列出链路上所有幂等键并标层级；画状态机——"重复入账"与"状态与事实不符"的发现入口 |
|
||
|
||
**机制模式库**（"结构性限制 → 可引入机制"对照表，改造方案的取材清单；**只有这一份，不复制**）：
|
||
|
||
| 结构性限制（发现） | 可引入的机制 / 重构 |
|
||
|---|---|
|
||
| 业务写 + 发消息不原子 | 本地事务表 / Outbox + 投递器（业务与消息同事务，投递可重放） |
|
||
| 兜底任务不可恢复（poll 即删） | 任务表为权威，队列只做加速（宕机可恢复、积压可观测） |
|
||
| 不一致只有日志、无人知 | 一致性异常台账 + 告警 + 处理台（待处理 → 处理中 → 已处理） |
|
||
| 状态靠应用层"猜测" | CAS 条件更新 + 影响行数判定（把判断交给数据库） |
|
||
| 上游码散落多处、口径不一致 | 码字典化：每码标注「是否受理 / 是否终态 / 可重试」，多处共查一份 |
|
||
| "不确定"没有归宿 | 挂起态 + 巡检 + 重放（重放须走同一套分级，因为对方状态可能已变） |
|
||
| 对外调用有副作用却被重复调用 | 幂等键（业务唯一键）+ 冲突当命中 |
|
||
| 资金出去的方向弱于进来 | 对称化：退款补齐同构的锁 / 短路 / 唯一索引 |
|
||
| 重试责任多点（乘法放大） | 重试责任单点 + 显式关闭其他层（应用重试了，MQ 就不重试） |
|
||
| 状态写入早于事实 | 中间态 + 以权威回调驱动终态（不以"发起成功"为准） |
|
||
| 能力只覆盖一条路径 | 铺开：把一个点的分级铺成一张网（全部写类接口统一） |
|
||
| 跨系统没有事务 | 「幂等 + 可重放 + 对账」三件套替代事务 |
|
||
| 关键参数散落、取值无解释 | 参数登记与解释：汇总阈值 / 退避 / 分片并说明取值依据 |
|
||
|
||
### 改进的三档尺度
|
||
|
||
| 档 | 做法 | 简历硬度 |
|
||
|:-:|---|:-:|
|
||
| ① 补漏 | 修一个具体的错：加校验、加索引、补 try-catch | ⭐ |
|
||
| ② 加机制 | 引入一个新机制，替代"靠人 / 靠自觉"的现状 | ⭐⭐⭐ |
|
||
| ③ 重构 / 更合理设计 | 改结构本身：隐式判断变显式判定、口径收敛、方向对称化 | ⭐⭐⭐ |
|
||
|
||
**硬要求：每个缺陷都追问"能不能上升一档"**；改造方案里 ②③ 档应占多数。改进的固定 5 要素：① 结构性限制 ② 机制/方案 ③ 替代了什么 ④ 代价 ⑤ 为什么不用通用方案。
|
||
|
||
**缺陷严重度**：🔴 资金/数据错误 · 🟠 静默失败或重复调用 · 🟡 卫生与可维护性。
|
||
**边界**：只做系统级结构问题（一致性·幂等·可运营性·可恢复性·职责漂移·口径分散），不做代码风格/坏味道/命名/注释。
|
||
|
||
## 硬规则（合并版）
|
||
|
||
| # | 规则 | 为什么 |
|
||
|:-:|---|---|
|
||
| 1 | **深度闸门**：允许简短的伪代码/关键片段（CAS 语句·锁与短路顺序·状态分支·DDL·Lua 脚本）把机制画实——**行数是参考不是硬限，忠实于机制形状优先**；真正禁止的是大段源码摘录、代码块内行号、逐层讲解。**豁免** = 主干调用骨架（技术地图，压成一行一段） | 禁代码会"太空"，贴源码则成"阅读报告" |
|
||
| 2 | **证据真实性**：锚点 `路径:行号`，**必须读过再写**；拿不准标【待确认】 | 错锚点毁掉可信度 |
|
||
| 3 | **只读**：不改被扫项目任何文件（新增产物不算） | — |
|
||
| 4 | **缺陷只进改造方案**：功能点清单与设计复盘不列缺陷表、不标严重度；设计复盘里"承接不住的地方"自然带出即可，不展开成清单 | 价值优先；缺陷集中一处才成体系 |
|
||
| 5 | **改进不停在补漏档；不写通用套话**（"加监控""上分布式事务"）；必须贴合业务的具体语义/表/状态，优先复用既有资产 | ②③ 档才是简历上能写硬的 |
|
||
| 6 | **诚实性**："设计对了但落地不完整"要明说；判断与代码事实不一致处逐条列出；文档写的方案必须回代码验是否落地 | 深度文档可信度的唯一来源 |
|
||
| 7 | **只做被点单的 1–3 个点**；每点先想清楚归哪份文档，不为凑齐三件套而写 | 实测一个功能点 ≈ 1–2 份 20KB 文档 |
|
||
|
||
## 格式保证
|
||
|
||
1. **模板外置**：读 `assets/` 对应模板填空。
|
||
2. **机械校验**（与 `value-scan` 共用 `../value-scan/assets/check.ps1`）：
|
||
|
||
```powershell
|
||
$ck = .agents/skills/value-scan/assets/check.py
|
||
# ① 功能点清单
|
||
python $ck dig <产物> --template .agents/skills/value-dig/assets/深度模板/功能点清单模板.md
|
||
# ② 设计思路与取舍 / ③ 改造方案
|
||
python $ck doc <产物> --template .agents/skills/value-dig/assets/深度模板/<对应模板>.md
|
||
```
|
||
|
||
**FAIL 必须为 0**；WARN 允许保留但写明原因。
|
||
3. **偏差回写**：被纠正过就回写模板。
|
||
|
||
## 触发词与落盘
|
||
|
||
**触发词**：「把这个点写成文档」「把这条链路整理成功能点」「写设计思路与取舍」「出改造方案」。
|
||
**落盘**：`<项目根>/docs/`，与候选清单同目录（可被用户覆盖）。
|
||
|
||
**上游**：候选清单由 `value-scan` 产出。
|