务实开发分析（pragmatic-analysis）
将「务实开发提示词模板」封装为按需加载的分析工作流技能：方法论通用，
内置 Nebula Boot 判据（BaseEntity/11 公共字段/sys_dict_item/FeignClient 等），
Nebula 系项目开箱即用；其它框架替换 references/modules.md 中标注「Nebula 判据」的条目即可复用。
核心是五阶段编排 + 17 个分析模块：用户用 @模块:XX 激活分析，AI 在对话中输出，
经人审阅后用 @保存 落盘到 docs/分析记录/，用 @查阅 检索复用。
> 代码生成不在本技能内。需要「按 Nebula Boot 规范生成代码」时，另装配套技能 nebula-codegen；
> 生成后的分析/审查/风控回到本技能。
安装与激活范围
- 本技能随仓库放在
<repo>/.github/skills/，打开对应工作区即激活（团队共享）。 - 分发给其他项目/其他用户：复制到
~/.copilot/skills/或发布到 SkillHub 安装——
技能内容与安装位置无关，所有项目路径均通过--root/--out/--migration-dir参数注入，
不硬编码任何仓库路径，任何项目皆可用。
何时用 / 何时不用（边界）
何时用：用户输入 @模块:XX/@角色:XX/@保存/@查阅 任一指令；要求「分析/审查/梳理」代码的某维度（状态机/表结构/规则/依赖/接口等）；要求产出联调文档/测试/健康评分/债务盘点等交付物。
| 不要用本 skill 的场景 | 用什么 |
|---|---|
| 需要「生成新模块代码」 | nebula-codegen（代码脚手架） |
| 需要「一个轻量 prompt 模板」 | 只是想要个分析提示词 → 直接照 references/modules.md 抄一段，不必装整套工作流与知识库协议 |
| 项目非 Java/Spring 体系，但需要 Nebula 公共字段判据 | 改用纯咨询子型（去掉 Nebula 字段判据，参考 references/modules.md 里标「Nebula 判据」的条目） |
| 用户要"修 bug"或"改业务逻辑" | 本 skill 只做分析，不做修改；让用户切到开发 IDE |
| 项目代码 < 1000 行、纯前端/纯脚本 | 小工程不值得建知识库 → @模板:速览 单跑模块 10，不 @保存 即可，不必走全流程 |
| 用户没装 Nebula Boot 但想跑 SQL 静态扫描 | scan_sql.py 可独立运行；告知不查 11 公共字段 |
> 一句话：本 skill 是「代码分析师」，不是「代码生成器」也不是「代码修改器」。
技能资产地图
| 路径 | 用途 |
|---|---|
references/modules.md |
17 个分析模块的完整契约（输出项 + 关键格式） |
references/workflow-protocols.md |
澄清门控 + 知识库协议（产出/反哺/归档/写后即记） |
references/anti-patterns.md |
反模式清单（症状→为什么错→怎么改） |
references/faq.md |
常见问题（症状→怎么处理） |
templates/output/ |
17 个输出骨架（拆解/建模/API设计/状态机/规则/审查/表结构/字典/依赖/风险/债务/接口/联调/测试/健康等报告 + 踩坑错误册） |
scripts/save_analysis.py |
知识库归档：写入 docs/分析记录/{分类}/{模块}/{文档名}.md（带标准头，--module 指定子模块） |
scripts/find_analysis.py |
知识库检索：@查阅 的确定性落地（--index 重建 INDEX.md / --list / --name / --read） |
scripts/log_daily.py |
写后即记：追加 docs/分析记录/daily/{YYYYMMDD}.md |
scripts/log_error.py |
踩坑错误册落盘：ERR-ID 自增 + 索引同步 + 去重（反哺协议的确定性落盘层） |
scripts/find_error.py |
踩坑错误册检索：@查错 的确定性落地（--list / --symptom / --read） |
scripts/scan_state.py |
状态机扫描（模块 3）：grep 状态字段/枚举/流转点/拦截点候选 |
scripts/scan_table.py |
表结构扫描（模块 5）：解析 DDL 字段/索引/11 公共字段合规 |
scripts/scan_enum.py |
字典+枚举扫描（模块 6）：枚举 code/desc + sys_dict_item diff 候选 |
scripts/scan_rpc.py |
RPC 依赖扫描（模块 7）：FeignClient 定义 + RpcService/Helper 注入 + 调用点 |
scripts/scan_api.py |
接口扫描（模块 11）：Controller 端点清单（HTTP 方法/路径/返回类型） |
scripts/scan_debt.py |
技术债务扫描（模块 9）：TODO/FIXME/@Deprecated + 临时方案注释 |
scripts/scan_risk.py |
隐藏风险扫描（模块 10）：空 catch/宽泛捕获/调试残留/SQL 拼接 |
scripts/scan_sql.py |
SQL 静态扫描：手写 SQL 缺 tenant_id/delete_flag、SELECT *、无 LIMIT、LIKE 前导、OR（配 scan_table 索引信息） |
tests/ |
冒烟测试（find_analysis + find_error + log_error + scan 八件套 + 方法契约） |
新手 5 分钟路径（最快的"先跑通再深入"路线）
# 第 1 步（30 秒）：极简风险扫描
@模板:速览 # 仅模块 10（隐藏风险扫描）
# 第 2 步（1 分钟）：跑 SQL 静态扫描，零依赖
python scripts/scan_sql.py --root your-project/
# 第 3 步（2 分钟）：知识库检索（如果项目已有 docs/分析记录/）
python scripts/find_analysis.py --index # 重建 INDEX.md 看有啥
python scripts/find_analysis.py --name "订单" --read # 按名读一条
# 第 4 步（1 分钟）：单模块分析（结果先出在对话里）
@模块:拆解 -- 输入 "用户下单流程"
# 第 5 步（30 秒）：保存（只有 @保存 才写盘=不污染知识库）
@保存:用户下单流程-拆解
> 判断下一步：
> - ✅ 看到结果 → 进入正题：@模块:XX 主流程
> - ❌ 脚本报错 → 看 references/faq.md 或 @查错:症状
> - 😐 结果太宽 → 改用 @模板:审计（健康+债务+审查 三件套）
>
> 完整学习路径（30 分钟）：先读 SKILL.md → 再读 references/modules.md 全部 17 模块契约 → 最后跑 tests/ 冒烟测试验证环境。
核心行为准则（优先级最高，覆盖所有模块）
| # | 准则 |
|---|---|
| ① | 分析结果只输出在对话中，不自动写入文件 |
| ② | 落盘需人手动触发：仅 @保存:文档名 或 @保存:本轮全部 才写入 docs/分析记录/ |
| ③ | 每次分析完成后，在回复末尾主动问一句「是否需要 @保存 本次分析？」 |
| ④ | 代码生成涉及架构变更或新增模块时，主动提醒用户是否需要 @保存 更新分析记录 |
| ⑤ | 不静默覆盖已有分析记录：同名文件已存在时，先展示差异再询问是否覆盖 |
| ⑥ | 输出前自检：每次交付分析前对照 references/anti-patterns.md 自查——是否给了证据锚点、是否凭印象没跑 scan、是否自动写文件；命中即改，不命中则交付 |
工作流：
用户: @模块:XX → AI 在对话中输出分析 → AI 提醒保存 → 用户审阅 → @保存:XX → 写入 docs/分析记录/
协议速览（完整定义见 references/workflow-protocols.md）
| 协议 | 一句话 |
|---|---|
| 澄清门控 | 模糊需求先转 2-3 条可验收标准再执行 |
| 产出协议 | 分析 → 人审阅 → @保存 → 成为 @查阅 的权威上下文 |
| 反哺协议 | AI 翻车 → 判断值得记（人工）→ 写回规范 + scripts/log_error.py 落盘错误册（编号/索引/去重由脚本保证） |
| 归档约定 | docs/分析记录/{分类}/{模块}/{文档名}.md：分类=业务规则/技术框架/模块；模块=base/customer/...（跨域用 system/auth，技术框架不分模块） |
| 新增业务域 | 域名 = Java 包名小写（如 supplier/contract），与 i18n_module 字典 item_value 保持一致；@保存 带 --module 域名 即自动建目录，@查阅 自动识别，零脚本改动 |
| 写后即记 | 实质工作完成后用 scripts/log_daily.py 追加 daily 日记 |
> 原则：宁可多一步手动确认，也不要让 AI 静默污染项目知识库。
五阶段编排 + 17 模块
| 阶段 | 模块 |
|---|---|
| 一：规划 | 17 任务拆解 @模块:拆解 · 15 数据建模 @模块:建模 · 16 API 设计 @模块:接口设计 |
| 二：开发 | 1 规范代码生成 @模块:生成（契约在本技能，实现由 nebula-codegen 承担）· 2 模块化审查 @模块:审查 |
| 三：分析 | 3 状态机 @模块:状态机 · 4 规则 @模块:规则 · 5 表结构 @模块:表结构 · 6 字典 @模块:字典 |
| 四：风控 | 7 依赖 @模块:依赖 · 8 依赖风险 @模块:依赖风险 · 9 债务 @模块:债务 · 10 风险 @模块:风险 |
| 五：交付 | 11 外部接口 @模块:外部接口 · 12 联调文档 @模块:联调文档 · 13 测试 @模块:测试 · 14 健康 @模块:健康 |
完整契约（触发方式、输出项、关键格式）见 references/modules.md。
> 编号沿早期模板历史（1-17 不全按顺序出现，如拆解=17、建模=15、接口设计=16），只看 @模块:XX 的触发名与阶段归属即可，编号不参与使用。
子型拆解（本 skill 的 3 种使用形态）
| 子型 | 适用项目 | 关键差异 | 起手 |
|---|---|---|---|
| Nebula 子型（默认） | Nebula Boot / Nebula-Boot-DDD 系 | 自动用 11 公共字段 + sys_dict_item + FeignClient 判据 | python scripts/scan_table.py 直接出合规报告 |
| Java 通用子型 | Spring 系项目（非 Nebula） | 去掉 Nebula 字段判据，保留状态机/规则/风险扫描 | 修改 references/modules.md 中标「Nebula 判据」的条目为关闭 |
| 纯咨询子型 | 任何代码（含前端/Python/Go） | 只用模块 3/4/10（状态机/规则/风险），不用 scan_* 脚本 | @模板:速览 即可 |
> 子型切换不需重装 skill，只需改 references/modules.md 中标注"Nebula 判据"的条目开关。
卡住速查（失败模式诊断树：症状→排查）
| 症状 | 第一查 | 第二查 | 兜底 |
|---|---|---|---|
@模块:XX 没反应 |
@角色 是否写对 |
输入是否在 17 模块清单内 | 直接说 "帮我分析状态机" 自然语言触发 |
scan_*.py 报"找不到根" |
--root 是否传 |
路径是否含中文/空格 | 用绝对路径 |
@查阅 找不到已存文档 |
find_analysis.py --index 重建 |
文档名是否含特殊字符 | --name 模糊匹配 |
@保存 覆盖已有文档 |
默认不覆盖，展示 diff | 确认 diff 合理 | 手动 mv 改名再保存 |
@查错 ERR-ID 跳号 |
去重是默认行为（同症状报错返回码 2，非 --dedup 参数） |
find_error.py --list 看现有编号 |
显式指定 --err-id 覆盖编号；无法自动重排索引 |
角色组合矩阵（5 角色 × 17 模块）
| 角色 | 默认模块组合 | 何时用 |
|---|---|---|
| 产品 | 3 状态机 + 6 字典 + 4 规则 | 有哪些状态？字典有哪些值？业务规则？ |
| 前端 | 12 联调文档 + 11 接口分析 | 接口、入参出参、枚举值 |
| 开发 | 15 建模 + 16 接口设计 + 1 生成 + 2 审查 | 把模块做出来 |
| 架构 | 8 依赖风险 + 10 隐藏风险 + 14 健康 + 2 审查 | 全局依赖/风险/健康 |
| 运维 | 9 债务 + 10 风险 + 14 健康 | 债务、风险、健康 |
> 自由组合：@模块:A\|B\|C 管道叠加，不强求走角色。
深度 vs 广度（何时全套 vs 何时局部）
| 信号 | 建议 | 用什么 |
|---|---|---|
| 项目代码 ≥ 5 万行 / 5+ 年 / 多人维护 | 广度优先 | @模板:全部（17 模块） |
| 局部改动 / 单服务 / 新模块上线 | 深度优先 | @模块:5\|6\|9\|10 |
| 上线前 1 天 | 风险优先 | @模板:风向 |
| 新人入职 | 全貌优先 | @模板:全部 + @查阅:全部 |
| 老板要"出个报告" | 结构化优先 | @模块:14 健康 + @保存:健康报告 |
指令速查（激活 + 落盘）
| 指令 | 功能 | 落盘脚本 |
|---|---|---|
@模块:XX |
单个分析模块（见 17 模块清单） | — |
@模块:A\|B |
管道：按顺序依次执行 A、B | — |
@模板:全部 |
模块 1–17 全开（大型审计/架构重构/新人交接） | — |
@模板:审计 |
模块 14+9+2（健康+债务+审查） | — |
@模板:风向 |
模块 8+10（依赖风险+隐藏风险） | — |
@模板:速览 |
仅模块 10（快速风险扫描） | — |
@角色:开发/架构/产品/运维/前端 |
按角色组合模块（组合定义见 references/modules.md 角色组合速查） |
— |
@保存:文档名 / @保存:本轮全部 |
落盘到 docs/分析记录/{分类}/{模块}/（带标准头，不覆盖同名） |
scripts/save_analysis.py --module 模块 |
@查阅:文档名 |
按名称模糊匹配，命中唯一时读全文 | scripts/find_analysis.py --name 名 --read |
@查阅:全部 |
重建并打印 INDEX.md（分类→文档→一句话摘要，不炸上下文） | scripts/find_analysis.py --index |
@记错:症状 |
落盘踩坑错误册（ERR-ID 自增 + 索引同步 + 去重） | scripts/log_error.py --symptom 症状 ... |
@查错:症状 |
检索踩坑错误册（诊断前先查索引做模式匹配） | scripts/find_error.py --symptom 症状 [--read] |
断点续做（跨对话怎么续）
分析是「对话中输出 + @保存 落盘」的模式，断点恢复靠知识库：
- 存档：
@保存:文档名把分析落盘到docs/分析记录/{分类}/{模块}/{文档名}.md；@保存:本轮全部落盘整轮。 - 续做：对话断了，先
@查阅:文档名/@查阅:全部找回已保存的分析，再接着跑缺的模块（@模块:XX）。 - 不覆盖：同名文档已存在时，先展示差异再询问是否覆盖，不静默覆盖。
术语速查（大白话）
| 术语 | 一句话 |
|---|---|
| 分析模块 | 一种分析动作（如状态机/表结构/风险），共 17 个，用 @模块:XX 激活 |
@模块:XX / @模板:XX / @角色:XX |
三种触发指令：单个模块 / 预设组合 / 按角色自动组合 |
@保存 |
把对话里审阅过的分析落盘成项目知识库文档（不静默写文件） |
@查阅 |
检索已保存的分析记录（@查阅:全部 看索引，@查阅:名字 读全文） |
@记错 / @查错 |
落盘 / 检索「踩坑错误册」（ERR-ID + 根因/修复/防范，供诊断前模式匹配） |
| 证据锚点 | 每条结论附的 文件:行 / DDL 列名 / 枚举 code——无证据的结论视为未完成 |
| 反哺协议 | AI 翻车 → 人工判断值得记 → 写回规范 + 错误册，让规范越来越懂项目 |
| 知识库 | docs/分析记录/ 下按 分类/模块 组织的归档文档（业务规则/技术框架/模块） |
| scan 八件套 | 8 个取证脚本（state/table/enum/rpc/api/debt/risk/sql），机械提取证据给 AI 补语义 |
