Resume Diagnosis

诊断不是连续时段——你正跑 check 命令，被拉去开会，回来 agent 上下文已被 compact，诊断链路丢失。

接手外来交接包（跨机那一半）

上家把一单打包带过来时（典型：路由与验证在前一台机器上做到一半，真正的大日志在另一台机器上），不要用 /diagnose 重开一单——那会把它当新问题重新收集、重新路由，得到的是一份与上家不同的现场，而真实状态本来就在包里。

1. 落位（机械动作归脚本）：python3 scripts/import_trace.py <包.zip | 包.md | 包目录>——它校验包、落到 traces/、比对知识库版本、点出缺件，并打印一屏交接简报。同名冲突时它落成 <sid>-imported-<n> 而不自动合并（两台机器为同一个问题各开一单是常态，要不要合并是判断，交人）；同一份包重复接手它不重复落位。
2. 读那句简报 + traces/handoff/<sid>.yaml（外来单才有这个文件，是交接单的机器可读那一份）：来源主机与知识库版本、交接意图（继续定位 / 复核结论 / 转上游）、上家留下的待补材料（needs）、未纳入与未内联的清单。
3. 版本不一致照实说：本机知识库与上家不同时简报会点出来——excluded_cases 里的 id 可能不存在、候选排序可能不同。以本机库为准执行，发现候选集与 trace 记的对不上就如实说明，别把差异当成上家写错。
4. 缺件不等于"证据已齐"：简报点名的 missing（单文件 md 通道未内联的大文件、传输丢件）要在第一屏就讲清，并按 needs 索取；缺着它们把上家的结论当已验证继续往下推，是把"上家没验完的部分"冒充成已验证。
5. 然后照下面的主流程续接——外来包接手只负责把现场放到本地，恢复现场与继续定位的规则一条不变。

只查上游（不续接）

已收尾的单不在可续接之列（status: resolved 不续接），但它可能带着上游锚点。这时要知道的是 "上游动了没有"，不是"上次查到哪一步"：这条路径不续接、不写 trace、不改状态，只做一次查证， 外加一句判断。

1. 跑 python3 scripts/verify_upstream_outcomes.py --case <case-id>。默认就是 dry-run，不写任何文件； --case 可重复，按名单一次查几条。案例没有上游锚点时它不发查询，只在汇总里报一行「不可对照」。
2. 按结局说一句话，四种结局分开讲：
   • 上游确认（issue 关闭为 completed / PR 已合入 / 旧 issue 由提交关闭）：内容被上游证实了。 这不等于你的部署已有这个修复——要升级建议就先做落地实证（skills/diagnose 步骤 5 与 skills/diagnose/references/diagnosis-procedure.md 的「上游修复的落地实证」）。写回 validation_record 再加 --apply；写回是知识库改动，走 PR。
   • 上游否定且案例声明修复已合入（脚本把这条印成 [矛盾]，退出码 1）：停，交人判——是改锚点 （指向修复 PR）还是改案例结论。dry-run 下脚本只把它列进「本次将写回」的计划，--apply 并走 PR 之后才真的记 inconsistent——别说成「已经记了」。
   • 未验证（issue 仍 open / 没有 PR 合入）：上游还没有结论。不写任何字段——「没证据」不是 负结论。
   • 不可查证（无 gh、未登录、网络失败、限流）：报查不到，不猜结局。
3. 结果只进对话，不进 trace：resume 事件只属于续接，这条路径一行 trace 都不写。

流程

先清反馈债——按 feedback.case 的取值分三种，别混：扫到的 state 文件里若有 feedback.outcome: pending，先看 feedback.case 是真实 case id、占位串 pending-investigation，还是空值/缺失（三种都出现过，定义见 diagnosis_state.yaml.example）。

• 真实 case id（上次命中 case 并给了可应用 fix）：追问“上次 <case-id> 的 fix 应用后解决了吗？（解决 / 没解决 / 部分解决）”——trace 记 {action: feedback, case, outcome}、把 feedback.outcome 从 pending 改成实际结果，再进入续接——计数不在这里写，由知识整理收尾的结算步骤落进条目使用记录。
• 占位串 pending-investigation（没命中 case，只给了建议）：不念这个占位串（它不是 case id），也不要求记 feedback 结算（没有 case 可结算，结算脚本只会跳过它）。这类单等的是现场材料：按顶层 last_action 追问上次要求的那几项材料拿到了吗（没有它才退到最近一条 evidence.missing），把新证据接回诊断主循环。它不是终态——status 仍是 in_progress；结论出来时结果记在 status 与 summary，并把遗留的 feedback.outcome: pending 清掉（无命中单不用反馈轴承载结果，否则会出现“状态已结、反馈轴仍挂着”的两轴打架）。
• 空值/缺失（写了 outcome: pending 却没填 case）：一个字都别念——照字面追问会问出“上次 的 fix 应用后解决了吗”，读者无从判断你在指哪一单。按占位串那一路处理（问现场材料、不记结算），并顺手把这笔写清：该单没命中就清掉 pending，确实在等材料就补成 pending-investigation。空值悬在那里，下次续接还得再猜一遍。

状态与结局词表见仓库根的 trace-status.yaml（不是 feedback_pending 那个旧说法）。两条轴各管一件事：status: resolved 表示诊断已收尾（根因定位明确），不表示 fix 生效；fix 行不行只由 feedback.outcome 记。命中单在给 fix 时挂 pending，这里追问后追加 feedback 事件改值——改的是 outcome，不是给 status 补一句"修好了"（status 早在收尾时就该落）。

这份债为什么由续接来清、而不是由新诊断开屏来问：续接续的正是那一单，问得其所；新问题的第一屏只服务新问题——/diagnose 若在开屏逐单追问历史 pending（积压时可能十几单），那是审讯，不是诊断。其他 pending 挂面板待办面（谁欠、哪一单、欠多久），人到那儿清。

续接只清被续那一单，不顺手清算全库：工程师开局说"继续上次那个"、或面板把某一单推过来时，只处理那一单的 pending。扫到别的 session 还挂着 pending 时，一句话带过（几笔、最早那笔挂了多少天、"面板待办面有『补反馈』入口"），不在新诊断的开屏逐单念、也不要求他当场逐笔回报——积压时那是审讯，不是诊断。想看全量债账的人去面板；续接的职责是把手上这一单推完。

0. 先解析 trace 目录：python3 scripts/shared_dir.py traces 打印的绝对路径就是本会话要读写的 traces/（锚在主检出、跨 worktree 共读）——下面所有 traces/… 读写都以它为准，别写相对 traces/。 解析后先同步再比漂移：kb_drift.py 会先调 kb_sync.py 做一次 fetch（只拉不合——诊断正在进行，不改工作区），再比 kb_rev..远端分支 与 git status -- knowledge/。

   输出分两种说清：

   • 「远端已合入这单用过的 case」；
   • 「本机未同步（落后未合并，旧内容下的结论仍成立，同步后要重验）」。

   后者给显式命令 python3 scripts/kb_sync.py --merge --force（跳过失败缓存直接试 ff-only，失败即报）。有漂移就先点出「这条 case 变了、按新内容重验」，再继续；没有 kb_rev 的旧单报「不可比」，不阻塞。

1. 读活跃的 traces/*.yaml（每个并发诊断一个文件；模板见 diagnosis_state.yaml.example，含 trace 数组）。多个时列出让工程师选续接哪个
   • 先看有没有配套的人读报告 traces/<session_id>.report.md（diagnose 步骤 6 产出）：它把结论、证据链、源码分析、机制图、修复方案、当前状态与下一步、沉淀候选集中在一处。先读报告能最快恢复"这单在查什么、停在哪、待回报什么"，也直接告诉你这次能沉淀什么知识（顶层 sediment_candidates 是同一份内容的结构化版本）。读报告不替代读 trace：报告的结论要用 trace 的 reason/证据核对，两者冲突时以 trace 的现场记录为准并记下冲突。
   • 报告是活件——续接中要顺手修订它（不是只读）：把新证据并入第 3 节对应强度段、更新第 7 节"当前状态与下一步"、必要时补第 4/5 节、元信息"最后更新"与第 10 节追加一行修订记录；同一份文件改到底，不另起一份。规则见 skills/diagnose/references/report-template.md 第 2 节。
   • 报告不存在（老 session 或未走完步骤 6）→ 照下面第 2、3 步从 trace 恢复，不视为异常。
2. 恢复完整现场（读 trace 全轨迹，不只元信息）：
   • 复述：session_id、status、current_step、已排除的 case（excluded_cases）、当前 active_case、last_action（上次等你做什么）
   • last_action 是当前提问：按它追问上次要的材料或决定拿到了吗；历史 evidence.missing 只作背景，不逐条重问。拿到回答后改写或清空 last_action，再继续。
   • 读 trace 数组恢复对话上下文：上次问了用户什么、用户已回答了什么、已排除哪些候选及原因（reason）——续接是接着上次的对话继续，不是从头开始（用户已提供的信息不重复要）
3. 证据确认（跨 agent/session 的关键——agent 无法自证摘要够，必须用户裁决）：
   • 复述证据清单：每个 user 事件的 content（摘要）+ evidence（内联了什么 / 引用了哪些文件 files / 来源 sources / 已知缺口 missing）
   • 问用户："证据齐全吗？有遗漏吗？"——跨 agent 时新 agent 只见过摘要，无法判断摘要是否等于原文；missing 字段自动列出已知缺口。用户确认齐全 → 继续；用户补充 → 更新该 user 事件的 evidence 后再继续
   • 文件证据可读：evidence.files 是相对仓库路径（traces/evidence/<session_id>/），同工作区可直接读；读不到 → 问用户要
4. 续接必写 trace（与 diagnose 同要求，闭环关键）：确认续接开始后，往 traces/<session_id>.yaml 追加一条 {role: agent, action: resume, harness_session: "$DSH_SESSION_ID", step: <current_step+1>, output: "续接 <session_id>，恢复到 step <N>"}，并刷新顶层 updated_at: <ISO 时间>——这是诊断面板"最新活动置顶"的依据（续接 = 该 session 又活跃了）；后续续接中的关键决策同样带 reason（与 diagnose 的 trace 要求一致）。harness_session 写当前会话号，顶层 harness_session 保持原始值不覆盖：前者让状态条与跳转知道这一单在哪个会话被接手，后者继续用于成本 / 工具调用归因。
5. 等人执行上次要求的命令并贴回输出，从 current_step 继续

恢复后的约束（继承 diagnose，不降低）

resume 只负责恢复现场——恢复后继续的是 /diagnose 的完整诊断循环（步骤 2-6），不是更松的模式。续接中以下 diagnose 约束同样生效（完整定义以 skills/diagnose/SKILL.md 为准，此处只列续接时最易被丢失的）：

• severity 闸门：data-loss-risk 不给 fix，先停/保留现场/通知 owner；service-affecting 标 fix_side_effects。
• 命中输出格式 + 强度标注：结构化推理链 + 已验证/推测/数据 + 分数校准，别甩一句 fix。
• 经验证后给 fix：对照已提供信息验证 diagnosis checks，缺就问；fix_on_mismatch 带 rollback。
• 版本软匹配：compat 不符只降排序分数，不硬排除。
• 证据落盘铁律：用户证据完整落 traces/evidence/<session_id>/，不写摘要/指纹；每次写 trace 刷新顶层 updated_at。
• 深度排查：Tier 3 / 源码分析一律走 scripts/src_fetch.py（复用、不自行 clone）。
• 误诊归因：反馈 not_resolved/partial → 读 trace 判 case_error/execution_error。
• 连续失败 ≤2：两次未解决转人工，不连续试第三个。
• trace 边界：续接后同样别把流程/设计讨论写进本 trace（走 _evnote.md）。
• 检索面：若续接中需重新路由/加载（如 active_case 丢失），照 diagnose 的 tier1 / 步骤 2 收尾的先验查询 / 两阶段 tier2 / 阶段 2.5 流程执行——那是续接中必要的重新定位，不是"回到起点"。

单一数据源纪律：上表是"易丢项清单"，权威定义仍在 diagnose；两者冲突时以 diagnose 为准，并在 diagnose 同步修正。

不要做

• 不要从头重新收集症状——state 文件里都有
• 如果 session_id 和当前不匹配，提示"该问题可能已被其他人接手——是否继续？"（并发检测，脆弱机制，只作提示不硬阻塞）
• 不要在这份 trace 里记录本 resume 期间发生的流程/设计讨论（与 diagnose 的"trace 边界"一致——那是自演进信号，走 EV card / 自演进通道，不污染本问题的诊断 trace）。resume 事件只承载诊断状态（恢复到哪步、待办什么），不掺流程改进内容
• 续接中若需源码分析，用 scripts/src_fetch.py <repo> --ref <tag> --verify "<签名>"（缓存按版本平铺在 src-code/<org>/<repo>/<tag>/、缓存根在主检出跨 worktree 共读；--list-versions 看本地已有版本，--list 看已知仓库与 host；仓不在已知表时用 --list-orgs、--list-org-repos 找），不自行决定 clone 到哪、不重复拉取。退出码即契约：0 = 该版本已产出并核对通过（带 --verify 时签名也命中；stdout 末行 = 路径）；3/4/5 = 没拿到（tag 名不对 / 拉取失败 / 本地目录核对不通过）；6 = 拿到了但签名没命中，不能证明是它——非零就别拿本地其他版本的目录去读，也不用 web 搜索代替源码

状态文件生命周期

case 标 resolved/escalated 时留在 traces/ 原位（用 status 字段标记闭环，不挪去 postmortems/history/——诊断面板与 ascend_trace_status 都只读 traces/，挪走会看不到/打不开）。traces/ 持有全部诊断记录（进行中 + 已闭环），判"可续接"看 status：只把 in_progress/feedback_pending 的当活跃可续接；resolved/escalated 的只作参考不可续接（不再提示"续接"）。trace 历史不删——它是路由准确率、执行保真度等指标的数据源（见 docs/guide/metrics.md）。postmortems/ 只放知识 postmortem 工件（.md，Tier 3），不是 trace 的归档处（trace 是 gitignored 机密记录）。

与诊断面板的闭环：resume 是 trace 的写入方之一——续接追加 resume 事件 + 刷新 updated_at，使该 session 在面板"更新 X 前"重置、置顶。面板"继续诊断"按钮 → 复制指令 → 本 skill 触发 → 续接写 trace → 面板刷新可见活动。任一环缺失（如续接不写 trace）闭环断，面板不反映续接。