Diagnose

Diagnose —— 问题定位入口

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条） > 本 SKILL.md 及其 scripts/ / templates/ 等框架文件在"使用本 skill"过程中只读。 > 发现 bug 必须立刻停下，向用户报告，由用户决定是否开新会话修。 > 唯一豁免：用户在当前会话明确声明"现在就是来改这个 skill 的"。

> Diagnose read-only 铁律 > 本 skill 全程禁止写业务代码、禁止修改 STATUS.md / TDDEVIDENCE.json / Plan / context.json / TASKDEV_NOTES.md。 > 用户要求改代码时，明确回复："请切回入口 2 继续项目 走 Developer skill，diagnose 入口不修改业务代码。"

---

使命

diagnose 是排障阶段的只读协助入口。它从 workspace/ 或 archive/ 中找到项目，按三层金字塔结构装载上下文（L1 实况层 eager-load，L2/L3 懒加载索引），让用户只描述症状就能得到精准排障回答。

---

标准工作流

Step 1 · ASK 档位

先问用户一次，确定扫盘范围（必须 ASK，禁止跳过）：

你目前处于哪个阶段？

a) 联调 / 自测中（项目还在开发，位于 workspace/）
b) 线上 / 已上线（项目已归档，位于 archive/）
c) 不确定 / 想看全部（workspace + archive 合并展示）

档位映射：

• a → --bucket=workspace
• b → --bucket=archive
• c → --bucket=all

用户选 c 后，在扫盘之前主动追问一次时间范围（不需要用户知道 --since 参数）：

项目可能较多，要限制一下时间范围吗？

1. 只看最近 7 天（本周在联调的）
2. 只看最近 30 天（不确定哪次上线引入的）
3. 不限，列出全部

映射：选 1 → --since=7d，选 2 → --since=30d，选 3 → 不加 --since。

用户选 a 或 b 时，不询问时间范围，直接扫盘（workspace 或 archive 单独项目通常不多）。

---

Step 2 · 扫盘

> ⚠️ 路径注意：扫盘脚本位于仓库根目录的 scripts/ 下，不在 skills/diagnose/scripts/ 下。 > 正确路径：scripts/discover_diagnose_targets.py

按 Step 1 确定的 bucket 和 since 参数运行（JSON 模式，禁止加 --human）：

# 示例：用户选 c + 最近7天
python3 scripts/discover_diagnose_targets.py --bucket=all --since=7d

# 示例：用户选 c + 不限时间
python3 scripts/discover_diagnose_targets.py --bucket=all

# 示例：用户选 a
python3 scripts/discover_diagnose_targets.py --bucket=workspace

---

Step 3 · AI 渲染候选列表

解析 JSON 后，必须在自己的回复正文里重渲染候选项目（禁止说"详见上方工具输出"）。

每个项目独占一个段落，段落之间空一行。格式如下：

**N. 项目名** `[bucket]` · mtime_human
`code:` …/父目录/仓库名   `branch:` 分支名（无则写 `—`）
产物: PRD `✓/✗`  TRD `✓/✗`  Plan `✓/✗`  STATUS `✓/✗`
L1: 任务笔记 N 段 / 已知坑 M 条   （或：_无任务笔记 · ContextPack 降级_）

路径截断规则：code_project_path 只展示最后两段（…/父目录/仓库名），避免长路径撑满一行。

渲染示例（供参考，不要原样复制）：

---

1. my-service [workspace] · 4h ago code: …/projects/my-service branch: — 产物: PRD ✓ TRD ✓ Plan ✗ STATUS ✗ L1: 无任务笔记 · ContextPack 降级

2. my-backend [archive] · 39m ago code: …/projects/my-backend branch: feature/my-module-t08 产物: PRD ✓ TRD ✓ Plan ✓ STATUS ✓ L1: 任务笔记 8 段 / 已知坑 7 条

---

末尾问："请回复编号，或输入项目名关键字过滤。"

---

Step 4 · 候选为空的兜底

若 JSON 中 summary.workspace_count + summary.archive_count == 0，禁止让用户选编号，回复：

当前  下没有可诊断项目。建议：
1. 检查档位选错没（重选 a/b/c）
2. 用入口 `1 开始新项目` 先建一个
3. 直接告诉我代码路径，我用临时模式回答（无 ContextPack 增益）

---

Step 5 · 装载前体检（不能跳）

用户选定项目编号后，必须先做以下三项体检再进 Step 6：

体检 A · 代码路径可达性 校验 context.json 中的 code_project_path 是否存在于本机。若不存在：

该项目的 code_project_path 已不可达（可能换机器或目录被搬走）。
选择：
1. 更新 context.json 后重来
2. 暂以无代码模式回答（仅基于产物文档）

等用户拍板后继续。

体检 B · 产物信号 若 signals.has_prd == false && signals.has_trd == false && signals.has_status_md == false（如刚 mkdir 的空壳项目），降级提示：

⚠️ 此项目无 PRD/TRD/STATUS 等产物，diagnose 仅能基于代码（如可达）+ git 历史回答，
建议确认是否选错项目。继续请回复「确认」，或重新选择项目。

体检 C · L1 实况层 若 signals.has_task_dev_notes == false（项目未走完 Developer skill，老项目常见），降级提示：

⚠️ 此项目无 TASK_DEV_NOTES.md（任务实况笔记），diagnose ContextPack 缺少 L1 实况层，
无法做"已知坑库"快速命中，排障精度受限。
建议：继续但接受降级，或切回入口 `2 继续项目` 让项目走完 Developer skill 再排障。

请选择：
1. 继续（接受降级）
2. 切回继续项目入口

---

Step 6 · 装载 ContextPack（三层金字塔）

运行：

python3 skills/diagnose/scripts/build_context_pack.py --project-dir=

脚本返回 action="ai_diagnose" 的 JSON 包，包含三层：

┌──────────────────────────────────────────────────────┐
│  L1 · 实况层（eager-load）                            │
│  TASK_DEV_NOTES.md：全部 task 段标题 +                │
│    所有「### 解决的关键问题」段全文                    │
│  STATUS.md 摘要（completed/in_progress/blocked 数量） │
│  TDD_EVIDENCE.json repair_rounds 摘要                 │
│  *.dev_review_report.json blocking/major 项           │
├──────────────────────────────────────────────────────┤
│  L2 · 设计层（lazy-load 索引）                        │
│  prd.md H1 + 各章节标题                               │
│  trd.md H1 + 各章节标题 + 接口表（如有）              │
│  api-contract.md（如有）H1 + 章节标题                 │
├──────────────────────────────────────────────────────┤
│  L3 · 知识层（lazy-load 索引）                        │
│  /docs/INDEX.md 索引（AIWeave 整合后）        │
│  /docs/BUILD_STATUS.md 状态摘要               │
│  archive/.../review-history/*.json fail/major 项      │
└──────────────────────────────────────────────────────┘

装载规则：

• L1 全部 eager-load（直接读入内存备用）
• L2/L3 只装索引，首次不 dump 全文
• 禁止首次装载就一次性输出 L2/L3 全部内容

> ⚠️ 重要 · 装载分层 ≠ 排查优先级 > > ContextPack 的 L1 / L2 / L3 只是数据装载分层（按 eager/lazy 区分），不是排查顺序。 > 真正的排查优先级见下文 Step 8 排障对话铁律 · 四档优先级： > ① AIWeave docs（L3 核心） → ② 开发笔记（L1 核心） → ③ TRD/PRD（L2）→ ④ ASK 后证据收集。 > AIWeave 整合后的核心收益就是「docs 与代码反向同步」，排障必须优先查 docs， > 不得按 L1→L2→L3 的字段名顺序倒着走（那样会让最权威的模块契约层排到最后）。

> AIWeave 整合后变化：L3 不再读 knowledge///00-index.md（旧 KB 体系已封存），改读业务项目自身的 docs/INDEX.md。 > 非 Go 项目降级（go.mod 不存在 / aiweave_status in {non_go, skipped}）：L3 链路为空，L1 / L2 必须兜底： > - L1（任务/上下文层）：当前/最近任务的 dev_notes、STATUS.md、context.json 进度记录、dev_review_report.json 历史 > - L2（项目/规范层）：归档 archive// 中的 PRD / TRD / Plan / FINISH_REPORT、workspace 中进行中产物、项目 README / CONTRIBUTING / 现有 .claude/skills/ 自定义 skill > - 特别强调：开发笔记（tasks//notes.md、RED/GREEN/REFACTOR 思考记录）在非 Go 项目上是 L3 缺位时的核心证据来源，必须默认装载，优先级提升一档

---

Step 7 · 一行交接语

装载完成后，输出一行交接语（所有参数填实，缺字段写 -）：

已加载「」上下文（code= · branch= · 
L1实况：任务笔记  段 / 已知坑  条 / repair  轮 · L2/L3 索引已就绪）。
请直接描述问题，无需粘贴背景。

若有降级情况，在交接语后附注 ⚠️ ContextPack 已降级：。

---

Step 8 · 排障对话铁律（v2 · AIWeave 优先 · 四档）

用户描述症状后，AI 必走以下四档顺序，禁止跳档。 排查优先级 不等于 ContextPack 的 L1/L2/L3 装载分层（详见 Step 6 末尾警示）。

第一档 · AIWeave 模块契约层（最高优先级）

触发条件：aiweave_preflight.has_docs == true（Go 项目接入 AIWeave）。 跳过条件：aiweave_preflight.has_docs == false（非 Go / aiweave_status ∈ {non_go, skipped} / docs 未生成），直接进第二档。

动作：

1. 按用户提问关键词在 aiweave_preflight.doc_links 里匹配候选篇章。常见映射：

| 用户关键词 | 候选 docs 模块 | |---|---| | 缓存 / Key / TTL / Redis | cache/cache_design.md、cache/cache_helpers.md | | 表 / 字段 / DDL / 分表 / 索引 | schema/database_design.md | | 接口 / 路由 / 入参 / 响应 / 错误码（接口级） | api/audience_*_interfaces.md | | 服务方法 / 伪代码 / 业务流程 | service/*_design.md | | 错误码 / 状态码（全局） | architecture/status_codes.md | | 中间件 / 路由链 / 全局拦截 | architecture/middleware.md、architecture/routing.md | | 配置 / yaml / 资源初始化 | architecture/config.md、architecture/infrastructure.md | | 定时任务 / MQ 消费者 / cobra | service/scheduled_tasks_design.md | | 测试规范 / Mock / fixture | testing/*.md |

1. 命中候选后展开对应章节，必须引证 docs/:# 作为来源（不只引代码行号）。
2. 用 aiweave_preflight.build_status_counts 与 docs/BUILD_STATUS.md 验证模块状态：

• 🟢：已实现且装配，可用 docs 作为权威解
• 🟡：代码已落盘但未装配，先读代码确认签名
• ⬜：设计已定稿、代码未创建——告知用户"该模块尚未实现"
• 🚫：当前阶段明确不实现——告知用户"该模块被明确禁止"
• ❌：未设计未实现——告知用户"未在 docs 中找到设计"

第二档 · 开发笔记实施实况层

触发条件：第一档没命中 / 已跳过。 动作：扫 L1 task_dev_notes，依次查：

1. 「### 解决的关键问题」段 → 判断是否"老坑"
2. 「### 复用方法」段
3. 「### 资源配置」段
4. 「### 测试模式」段

命中则直接答 + 引证 Tx 段标题（如「T03 · 已解决的关键问题 / Redis 反序列化兼容」）。

第三档 · TRD/PRD 设计意图层

触发条件：前两档都没命中。 动作：按 L2 prd / trd / api_contract 索引，找用户提到的接口名 / 字段 / 模块的对应章节，展开全文。 适用场景：业务流程 / 用户场景 / 状态机 / 时序 / 兼容性等"设计意图"问题（设计事实类已被前两档覆盖）。

第四档 · ASK 用户后跑证据收集

触发条件：前三档都不够。 动作：必须先 ASK 用户同意，再跑：

• grep_in_code_project.py（业务源码 grep）
• collect_recent_commits.py（git log）
• collect_branch_status.py（git status）

详见下方「证据收集动作」表。

---

禁止跳档行为举例（直接违反铁律）：

• aiweave_preflight.has_docs=true 时跳过第一档直接扫 L1 笔记 / L2 TRD
• 任一档"文件读取失败 / 路径有特殊字符 / 找不到对应章节"就跳到代码 grep——必须先试下一档
• 证据收集前不 ASK 用户同意，直接 Search / Grep / Read 业务源码
• 引证答案时只给代码行号，不给 docs/:#（第一档命中时尤其严重）
• 看到用户报错就直接说"建议你检查代码的 X 行"，跳过前三档

---

证据收集动作

每个动作必须 ASK 用户同意再执行：

| 脚本 | 触发场景 | 作用 | |---|---|---| | skills/diagnose/scripts/collect_recent_commits.py | "最近改了 X 之后开始报错" | 列出 code_branch 上 N 天内 commit + 涉及文件 | | skills/diagnose/scripts/collect_branch_status.py | 确认现场分支状态 | git status + git log -1 + 当前分支名 | | skills/diagnose/scripts/grep_in_code_project.py | 用户给关键字/接口路径/错误码 | 在 code_project_path 范围内 grep |

脚本参数均通过 CLI 传入，见各脚本 --help。

> 路径权限注意：code_project_path 在本仓库外（如业务仓库）。Cursor sandbox 默认对 workspace 外只读——够做 grep / git log；若需跑测试用例，需用户额外确认。

---

问题档案沉淀（可选）

当用户想记录本次排障结论时，在对应项目目录下创建档案：

workspace//diagnose//
  issue.md          # symptom + 复现步骤 + AI 给出的假设和验证结果
  evidence/         # 跑过的脚本输出（git log、grep 结果、日志片段）
  resolution.md     # 最终结论（如果有）

使用模板：skills/diagnose/templates/issue.md。

软闭环提示：若同一类问题反复出现（>= 2 次），提示用户：

这类问题已出现 N 次，建议提炼成 KB 的 05-pitfalls.md。
是否切到入口 3「提取 AI 知识库」增量补写？（建议，不强制）

finish-project 归档时，workspace//diagnose/ 目录会随项目一并 mv 到 archive//diagnose/，无需手动处理。

---

Step 9 · 修复确认（轻量 Hotfix 模式）

适用于：diagnose 分析出根因后，问题范围小、不需要完整 PRD→TRD→Plan 流程的情况。

9.1 触发条件

Step 8 对话中用户明确表示"要改代码 / 去修这个 bug / 我来 fix"时触发。AI 询问：

已找到根因，是否进入轻量修复模式（跳过 PRD/TRD/Plan，直接改代码）？

请选择：
1. 进入修复模式（按诊断建议直接改代码）
2. 取消（不改代码，本次诊断结束）

用户选 1 → 进入 9.2；选 2 → 结束本次诊断（如需要可手动写入 issue.md 留档，不强制）。

已废弃的旧选项（保留说明用于回溯，2026-05-11 起不再展示）：

• ~~否，我走完整 Developer 流程（入口 2）~~：诊断场景下 Developer 入口需要既有 Plan/STATUS，对一个 bug 修复无法承接，是逻辑死路；想走严格 TDD 应当回主菜单选入口 1 当成新需求处理。
• ~~不改代码，只保存诊断结论~~：与"取消"语义重叠，诊断结论本身已在对话里呈现，无需独立存档作为一个动作。

9.2 准备 Hotfix Workspace 目录

检查 workspace/-hotfix-/ 是否已存在：

• 已存在：直接用，告知用户
• 不存在：创建目录 + context.json

context.json 字段填写规则（禁止照抄原项目 context.json，每个字段有独立来源）：

| 字段 | 来源 | 说明 | |---|---|---| | project | "-hotfix-" | 新建的 hotfix 项目名 | | code_project_path | 复用原项目 | 代码路径不变 | | code_branch | "feature/" | hotfix 分支名，9.3 确定后回填 | | code_base_branch | 用户在 9.3 实际选择的 base-branch | ⚠️ 不能默认填 master；从 setup_hotfix_branch.py --base-branch 参数取 | | code_integration_branch | 同 code_base_branch | hotfix 改完合回这条分支 | | knowledge_base_dirs | 复用原项目 | KB 路径不变 | | hotfix_for | 原项目名 | 溯源用 | | hotfix_issue | 诊断结论一句话 | 方便归档后检索 | | diagnose_ref | issue.md 路径（如有） | 指向诊断档案 | | hotfix_mode | true | 标记为轻量 hotfix 项目，finish-project 据此跳过 PRD/TRD/Plan 检查 |

展示一句确认：

已准备 workspace/-hotfix-/
code_project_path = 
下一步：分支准备（base-branch 确认后会更新 context.json 中的 code_base_branch）

9.3 分支准备

运行分支检测：

python3 skills/diagnose/scripts/collect_branch_status.py --code-dir=

展示当前分支状态，然后给用户选择：

当前在分支 ，计划在  上拉一条 hotfix 分支。

请选择：
1. 自动完成（git checkout  → git pull → git checkout -b feature/）
2. 我手动操作，完成后告诉我
3. 取消

选 1（自动）：运行：

python3 skills/diagnose/scripts/setup_hotfix_branch.py \
  --code-dir= \
  --base-branch= \
  --hotfix-name=

脚本输出成功后：

1. 告知用户当前分支名
2. 将 context.json 中的 code_branch、code_base_branch、code_integration_branch 更新为实际值（code_branch = feature/，code_base_branch / code_integration_branch = 脚本 --base-branch 参数）
3. 进入 9.4

选 2（手动）：等用户说"好了"后，运行 collect_branch_status.py 确认分支已切换，进入 9.4。

> 安全铁律：setup_hotfix_branch.py 只做 checkout + pull + 新建分支，禁止 push、禁止 merge master/dev/main。

9.4 改代码

read_only 标志在此步骤临时解除：AI 可以 Read 业务代码文件、提出修改方案并征得用户确认后执行 Edit/Write。

改动前必须做的事：

1. 先展示"拟改动摘要"（改哪些文件、改什么），等用户回复 确认 再动笔
2. 每次改动后立即说明"已改完 X，下一步 Y"

禁止：

• 自动 push（Git 安全铁律）
• 自动 merge dev / master / main 等受保护分支（Git 安全铁律）
• 修改不在本次根因范围内的代码
• 修改框架文件（铁律 7 继承）

允许（2026-05-11 起）：

• 在 hotfix 分支（如 feature/）上自动 commit。Hotfix 修复改动小、上下文清晰，要求用户每次都手动 commit 是多余阻力；改完且验证通过后，AI 应当直接执行 git add -A && git commit -m ""，让 hotfix 分支留下干净 commit，不再"留尾巴"。Commit message 用 9.5 hotfix-notes.md 里的"根因一句话"，前缀可加 hotfix:。

改完后，问用户：

代码已改完，是否需要我帮你跑一下验证命令（如 go test / pytest）？

请选择：
1. 是，帮我跑测试
2. 我自己跑，跑完告诉你结果
3. 不用跑，直接记录

用户确认验证通过（或选 3 跳过验证）后，AI 立即执行：

git add -A
git commit -m "hotfix: "

并在回复里展示 commit 短哈希（如 已 commit a1b2c3d），然后再进入 9.5。如果 git status --porcelain 显示工作区干净（说明用户自己已 commit），跳过此步。禁止因"会话级 git 约定"为由跳过 commit——hotfix 分支本就是为这次修复创建的隔离工作区，commit 是该流程的天然终点。

9.5 写 Hotfix Notes

改动完成（或用户确认测试通过）后，在 hotfix workspace 目录下生成 hotfix-notes.md：

# 使用模板：skills/diagnose/templates/hotfix-notes.md
workspace/-hotfix-/hotfix-notes.md

内容包含：

• 根因来源（引用 issue.md 档案路径）
• 改动文件列表
• 关键改动说明
• 验证结论
• 建议合并方式（PR 还是直接 cherry-pick）

9.6 收尾

写完 notes 后，向用户输出一句话收尾：

本次问题已修复（已 commit 到 feature/，hotfix-notes.md 已留档）。还有什么问题吗？

不再展示 1/2/3 编号菜单。原因：

• PR / 合并：Git 安全铁律本就禁止框架自动 push / merge，这一条是约束信息不是用户选项
• 入口 4 归档：用户想归档时自己说"归档"或回到主菜单选 4 即可，不需要在这里塞个待办提醒
• 暂不归档：不归档就是默认行为，根本不需要作为一个"选项"

收尾以"还有什么问题吗"邀请下一步对话，用户可以自然继续 diagnose、要求归档、或直接结束。

---

已废弃（2026-05-11 起）：旧的"后续建议 1/2/3"三选项菜单。原因：1 是约束不是选项；2 是另一个 skill 的入口，不应在 diagnose 内放快捷键；3 是默认行为，无需展示。

---

隔离与安全

• read_only=true 是默认值，仅在 Step 9.4（修复代码）期间临时解除，且必须征得用户确认
• 禁止修改 STATUS.md / TDDEVIDENCE.json / Plan / context.json / TASKDEV_NOTES.md
• 框架不可变铁律继承：发现 skills/** / scripts/** 有 bug，停下让用户开"开发者模式"新会话修
• conv_id 隔离：沿用 .nexus/conversation// sidecar，多 Cursor 实例并行不串

---

停顿规则（统一格式）

任何需要用户回复的地方，末尾必须给出明确选项：

请选择：
1. 
2. 
3. 取消 / 暂停

禁止弱引导（"需要的话再说一声" / "回复继续" / "需要我处理再说"）。

---

AIWeave docs 预检（轻量模式）

> AIWeave 整合后：原 KB 预检已废弃（旧 knowledge_base_dirs 字段保留向后兼容但不再读取；旧的 knowledge-qa-reviewer subagent 已物理下沉到 skills/_deprecated/，diagnose 不再调用，仅作 git 历史留档）。

进入 Step 7 之后、用户提问之前，如果 L3 知识层扫到了 /docs/INDEX.md，做一次轻量预检：

> 「我注意到此项目接入了 AIWeave docs（/docs/INDEX.md， 篇章节，BUILD_STATUS：🟢× ⬜× 🚫×）。你描述症状后，我会优先查 L1 实况层，必要时再展开 docs/ 对应章节。」

非 Go 项目（aiweave_status in {non_go, skipped}）跳过本预检，直接进入排障对话；用户描述症状时主 Agent 优先按 L1 实况 + L2 归档 PRD/TRD/Plan 推断。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xurb-nexus
• Source: xurb-nexus/nexus-harness
• License: Apache-2.0
• Homepage: https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.