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
7.8 KiB
name, description
| name | description |
|---|---|
| value-scan | Use when the user wants to inventory the mechanisms worth talking about in code that is already delivered — "盘点这个域/模块的价值点", "扫一下 order 域有什么值得讲的", "提取功能点", "这个项目有什么值得讲的设计", or when interview/resume material must be reconstructed backwards from an existing module. Read-only — never modifies the scanned project. Stops at the human selection gate; deep write-up is a separate skill. |
value-scan · 价值点盘点（广度枚举）
一句话
从已交付的代码里，逆向枚举出值得讲的机制点，交人勾选后停下。
三条核心原则
- agent 判不了"价值"——判据不是分类体系，而是简历行填空测试。
- 价值优先，本阶段不找缺陷。 缺陷是深入链路时自然浮现的副产物，归
value-dig。 - 只读。 不修改被扫描项目的任何文件。
流程
S0 定范围 → S1 枚举 → S2 勾选【终点：产出清单后必须停】
↓（人勾选后）
value-dig（轻理由 → 设计复盘 / 功能点 / 改造方案）
| 需求 | 该用 |
|---|---|
| 盘点 / 扫一遍 / 提取候选价值点 | 本 skill |
| 把选中的点写成深度文档 | value-dig |
| 找 bug、修缺陷 | diagnose |
S0 · 定范围
- 快路：仓库已有域清单（
.aspirecode/sdd/rules.md§9、pom.xml、wiki/目录）→ 直接读。 - 慢路：陌生仓库 → 按接口路径前缀、
-apiFeign 接口名、controller 清单切出能力面，一次一个 package。 - 范围由人给定（一个域/模块），不一次扫全库。
域是入口锚点，不是物理边界。 完整链路往往跨模块，用两头夹的办法拼：
- 聚合层（web）定链路形状：controller / Kafka consumer / XxlJob / callback 四类入口全在聚合层，且分包与路径自带业务语义（
/consumer/fulfillment/、topic 名、请求路径）——从这里正向切出"有哪些触发者、哪些链路"。MQ 消费、定时任务这类非 Feign 入口靠反推找不到。 - 原子域挖机制内容：锁/幂等/状态机等机制本体大多在原子域的 service 实现，聚合层只有编排——读实现要去原子域。
- 中间用调用图接（
gitnexus_route_map/gitnexus_cypher）；被驱动型域也可用"谁 import 了我的 Feign 接口"反查调用方作兜底。 - 只读链路经过的路径，不通读途径模块。
S1 · 枚举
取材顺序（信噪比递减）
| 顺序 | 来源 | 备注 |
|---|---|---|
| 1 | wiki/*.md、.claude/docs/**、devflow/projects/** |
先读「设计说明类」，后读「问题分析类」——先读问题分析会把清单带成缺陷导向 |
| 2 | git log：feat(...) / refactor(...)、带单号、单次大改动 |
有意识的改动藏着设计意图 |
| 3 | gitnexus_query / gitnexus_route_map |
用图查结构，不读全文 |
| 4 | 代码结构统计 + 关键字 grep（锁/重试/MQ/Job/条件更新/状态机/延时/对账） | 只做清单式定位，不通读代码 |
⚠️ 读完文档必须回代码验一遍"文档写的方案是否落地"。"文档 vs 代码分叉"本身就是高价值点。
怎么看结构：按「触发者」拆链路
不按业务功能拆，按谁触发拆：找出「同一行数据被几个触发者改」（如回调/查单/取消都改同一行支付流水）——收敛点多半就是机制所在。通常 1–4 条链路，被驱动型模块可到 5–6 条（超过要写一句为什么）。
每条链路挂 1–4 个机制节点。候选颗粒度 = 机制/能力，不是注解、类、配置项——"用了 @LockAction、有 4 个 handler"是实现清单；跨 ≥2 个写类入口或 ≥2 张表的才够"机制"。
判据 · 简历行测试
一级 · 准入（三条硬标准，全过才进清单）
| 标准 | 反例（据此剔除） |
|---|---|
| ① 核心链路（资金/履约/交付这类业务闭环） | 购物车 key 命名、查询接口 |
| ② 高级工程师的设计（设计决策，非框架常识） | Redis GETDEL、Spring 自注入修事务自调用 |
| ③ 简历够硬（能写成"我设计了 X 机制解决 Y"） | 定长文件 + 签名 + SFTP 的对接实现 |
二级 · 表达：用【机制】解决了【具体问题/场景】，代价是【取舍】——本阶段只试填"机制+问题"两格；填不出机制 → 并入「已剔除」表（标 机制格填不出，待复核）；填不出取舍不误杀（取舍归 value-dig）。
⚠️
机制格填不出的剔除门槛（防误杀，实测翻案教训）：机制本体常藏在实现大类（2000+ 行）的私有方法群里，入口类名/Job 类名只是壳——没读过入口方法向下 ~100 行，不得以此理由定稿剔除。剔除非此理由的照常。被剔除后复评翻案的，在剔除表原行标注撤销原因与日期（如"2026-09-18 复评撤销：快照轮询机制实存，升级为 ★N"），不删行——翻案记录本身就是筛选口径的进化证据。
被剔除的点进「已剔除」表（注明未过哪条标准），不丢弃。
数量
亮点 5–8 条为宜。超过 12 条 = 颗粒度掉到实现层，退回重并。
S2 · 门控（终点，不可跳过）
- 候选清单已落盘（每条含「一句话价值」与锚点），头部「闸门状态」节写明"S1 已完成 · 待勾选"；
- 回复里显式请求勾选（"请从这 N 条里挑 3–6 条"）。用户禁用提问时也一样停——把请求写成文字，不是替他挑完继续写文档。
- 否决即校准：人否决候选（"不够硬"/"一般"）时，把否决原因记入清单（闸门状态或剔除表）——下次扫同域/同仓先读上次的否决记录，同类点不再重复上报；整批否决且未给新目标 = 流程终点，不强续。
硬规则（合并版，替代旧的硬规则/反模式/Gotchas 三张表）
| # | 规则 | 为什么 |
|---|---|---|
| 1 | 深度闸门：无围栏代码块（Mermaid 除外，行内反引号可用）；不贴源码、不写行号、不逐层拆解、不展开取舍 | 本阶段是广度层 |
| 2 | 不找缺陷、不读"坏味道报告"；把克制当设计（"manager 只有 3 个"可能是有意的） | 缺陷导向会摧毁清单 |
| 3 | 证据真实性：锚点 ⟨简写⟩/路径#方法名（机制级可锚到类；不写行号），读过再写，拿不准标【待确认】，每条 ≤2 个 |
错锚点毁掉可信度 |
| 4 | 每条链路（含未入选的）都要写「是什么 + 为什么入选/未入选」；0 机制先问"真没有，还是采样不到位" | 链路是骨架，不因无亮点而省略 |
| 5 | 三层结构：域 → 链路 → 机制节点，机制必须挂在链路图上 | 并列清单会显得"都是散的" |
| 6 | 只读 + 门控：不改被扫项目文件；产出后必停 | — |
格式保证
- 模板外置：读
assets/候选清单模板.md填空，不照印象写。 - 机械校验：产出后跑
python <skills>/value-scan/assets/check.py scan -Product <产物> -Template <skills>/value-scan/assets/候选清单模板.md（跨平台 Python 版；Windows 下若中文乱码先设PYTHONIOENCODING=utf-8。旧check.ps1保留但不再维护）。FAIL 必须为 0；WARN 允许保留但写明原因。 - 偏差回写：被纠正过就回写模板。模板是活资产。
触发词与落盘
触发词：「盘点这个模块的价值点」「扫一下 X 域有什么值得讲的」「提取功能点」。
落盘：<项目根>/docs/{域}-候选价值点.md（可被用户覆盖）。
下一步：用户勾选后，用 value-dig 接手。