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
113 lines
7.8 KiB
Markdown
113 lines
7.8 KiB
Markdown
---
|
||
name: value-scan
|
||
description: 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 · 价值点盘点（广度枚举）
|
||
|
||
## 一句话
|
||
|
||
从**已交付的代码**里，逆向枚举出**值得讲的机制点**，交人勾选后**停下**。
|
||
|
||
**三条核心原则**
|
||
|
||
1. **agent 判不了"价值"**——判据不是分类体系，而是**简历行填空测试**。
|
||
2. **价值优先，本阶段不找缺陷。** 缺陷是深入链路时自然浮现的副产物，归 `value-dig`。
|
||
3. **只读。** 不修改被扫描项目的任何文件。
|
||
|
||
## 流程
|
||
|
||
```
|
||
S0 定范围 → S1 枚举 → S2 勾选【终点：产出清单后必须停】
|
||
↓（人勾选后）
|
||
value-dig（轻理由 → 设计复盘 / 功能点 / 改造方案）
|
||
```
|
||
|
||
| 需求 | 该用 |
|
||
|---|---|
|
||
| 盘点 / 扫一遍 / 提取候选价值点 | **本 skill** |
|
||
| 把选中的点写成深度文档 | `value-dig` |
|
||
| 找 bug、修缺陷 | `diagnose` |
|
||
|
||
## S0 · 定范围
|
||
|
||
- **快路**：仓库已有域清单（`.aspirecode/sdd/rules.md` §9、`pom.xml`、`wiki/` 目录）→ 直接读。
|
||
- **慢路**：陌生仓库 → 按接口路径前缀、`-api` Feign 接口名、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 · 门控（终点，不可跳过）
|
||
|
||
1. 候选清单**已落盘**（每条含「一句话价值」与锚点），头部「闸门状态」节写明"S1 已完成 · 待勾选"；
|
||
2. 回复里**显式请求勾选**（"请从这 N 条里挑 3–6 条"）。用户禁用提问时也一样停——把请求写成文字，**不是**替他挑完继续写文档。
|
||
3. **否决即校准**：人否决候选（"不够硬"/"一般"）时，把否决原因记入清单（闸门状态或剔除表）——下次扫同域/同仓先读上次的否决记录，同类点不再重复上报；整批否决且未给新目标 = 流程终点，不强续。
|
||
|
||
## 硬规则（合并版，替代旧的硬规则/反模式/Gotchas 三张表）
|
||
|
||
| # | 规则 | 为什么 |
|
||
|:-:|---|---|
|
||
| 1 | **深度闸门**：无围栏代码块（Mermaid 除外，行内反引号可用）；不贴源码、不写行号、不逐层拆解、不展开取舍 | 本阶段是广度层 |
|
||
| 2 | **不找缺陷、不读"坏味道报告"**；把克制当设计（"manager 只有 3 个"可能是有意的） | 缺陷导向会摧毁清单 |
|
||
| 3 | **证据真实性**：锚点 `⟨简写⟩/路径#方法名`（机制级可锚到类；不写行号），**读过再写**，拿不准标【待确认】，每条 ≤2 个 | 错锚点毁掉可信度 |
|
||
| 4 | **每条链路（含未入选的）都要写「是什么 + 为什么入选/未入选」**；0 机制先问"真没有，还是采样不到位" | 链路是骨架，不因无亮点而省略 |
|
||
| 5 | **三层结构**：域 → 链路 → 机制节点，机制必须挂在链路图上 | 并列清单会显得"都是散的" |
|
||
| 6 | **只读 + 门控**：不改被扫项目文件；产出后必停 | — |
|
||
|
||
## 格式保证
|
||
|
||
1. **模板外置**：读 `assets/候选清单模板.md` 填空，不照印象写。
|
||
2. **机械校验**：产出后跑 `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 允许保留但写明原因。
|
||
3. **偏差回写**：被纠正过就回写模板。模板是活资产。
|
||
|
||
## 触发词与落盘
|
||
|
||
**触发词**：「盘点这个模块的价值点」「扫一下 X 域有什么值得讲的」「提取功能点」。
|
||
**落盘**：`<项目根>/docs/{域}-候选价值点.md`（可被用户覆盖）。
|
||
|
||
**下一步**：用户勾选后，用 `value-dig` 接手。
|