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
9.4 KiB
9.4 KiB
name, description
| name | description |
|---|---|
| value-dig | 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 · 深度产出（功能点 / 设计复盘 / 改造方案）
一句话
把已经选定的机制点写成能讲、能追问、能被审的文档：按需产出三件套。
两条原则
- 价值优先 → 深入 → 更优方案。 缺陷与改造只在「改造方案」里出现；功能点清单与设计复盘以"这个设计为什么好、怎么取舍"为主体。
- 只读：不修改被扫描项目的任何文件（新增产物不算）。
两种入口
| 入口 | 情形 | 怎么做 |
|---|---|---|
| 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 文档 |
格式保证
- 模板外置：读
assets/对应模板填空。 - 机械校验（与
value-scan共用../value-scan/assets/check.ps1）：
$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 产出。