pillumina/ascend-sleuth / skills/diagnose
diagnose
Verified昇腾训练/推理问题的核心诊断循环:收集症状、按 triage-tree 路由、两阶段加载 并验证 Tier 2 case、命中给 fix(高危 root cause 改提示 halt)或转深度排查。 Tier-2 未命中但最终解决时起草候选 case。全程写 trace。 仅在能执行命令的 agent(Claude Code / Codex / pi)中可用。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 45.1 KB |
| references/collect-gates.yaml | config | 17.4 KB |
| references/diagnosis-procedure.md | markdown | 46.4 KB |
| references/diagnosis-trace.md | markdown | 46.2 KB |
| references/platform-dispatch.md | markdown | 1.6 KB |
| references/procedure-gates.yaml | config | 4.3 KB |
| references/report-template.md | markdown | 23.7 KB |
| references/script-integration.md | markdown | 2.2 KB |
| references/src-fetch.md | markdown | 9.2 KB |
references/diagnosis-trace.md
View on GitHub# Diagnosis Trace(trace 写作细节展开)
`/diagnose` 的 SKILL.md「每步必写 trace」写主干(事件结构/证据落盘铁律/时间戳/trace 边界),这里展开**细节**(词表、外部事实落盘、agent 事件两层、反馈闭环词表)。执行时按需加载。
## KNOWN_ACTIONS 词表(与 `scripts/trace_metrics.py` 一致,新增 action 必须两处同步)
trace 的 agent 事件 `action` 必须落在词表内(词表外 action 会被 `trace_metrics.py` 报为纪律违规):
```
triage | load_index | quickly_check | load_full | run_check | hit | miss | tier3
| feedback | reference_lookup | triage_semantic | source_analysis | attribution | resume
| procedure_follow | report | external_lookup
```
user 事件无 `action`,不参与词表检查。**新增 action 时同步改 `trace_metrics.py` 的 `KNOWN_ACTIONS` 与本文**(单一数据源纪律)。
### `triage` 事件(Tier-1 路由决策)
字段 `{action: triage, workload_type, workload_type_source, branch, category, routed, output, reason}`:
- **`routed` 必写**,值是被路由到的 namespace 列表(按该负载类型 `search_namespaces` 的顺序,如 `["inference/vllm-ascend", "common"]`)。负载类型必须在 `routed` 的目录前缀里看得到。
- **没命中任何分支也要写 `routed: []`,不要省略这个字段**——省略会被结算读成「未记录」,而「未记录」与「没错」在数据上同形(路由准确率的分母与 router 错例池都取这个字段)。
- 命中分支后走了语义兜底,另记 `triage_semantic`(带 `namespace` + `category`):它同样计入路由准确率,**不要只留 triage 而不带 routed**。
- 完全无法分类时写 `routed: []`,并在 `reason` 里写明「无可用 namespace(原因)」,然后按流程走 Tier 3。
**`workload_type` 与 `workload_type_source`("负载类型"这一步可观测的唯一来源)**:路由先分负载类型(训练 / 推理)、再在负载类型内判性质,所以"这一单在哪一负载类型"必须落进 trace——它是这一层唯一的证据面,不记就回答不了"负载类型是怎么定下来的、有多少单要问一句"。
```yaml
- {step: 2, action: triage, workload_type: training, workload_type_source: framework,
branch: interrupt, category: interrupt, routed: [training/mindspeed-llm/, common/]}
```
- `workload_type`:`training` / `inference` / `unknown`(他一时没答、材料也没写——那就不猜,训练与推理都查)
- `workload_type_source` 四档,收敛写、别自造:
| 值 | 含义 | 例 |
|---|---|---|
| `evidence` | 材料里读到的 | 贴的是训练脚本 / loss 曲线;贴的是 `vllm serve` 启动命令 |
| `user` | 问了、他答的 | 追问「这单是训练还是推理」后他回答 |
| `framework` | 由框架名对到库里目录 | 框架是 verl → `knowledge/training/verl/` |
| `unknown` | 一时拿不到(`workload_type` 同时为 `unknown`) | 他没回、材料里也没有线索 |
中途证据与他的说法相反时以证据为准:`workload_type_source: evidence`,并在 `reason` 里写明改向的理由与回给他那句话。
- `branch` 现在是**性质**名(`interrupt` / `precision` / `performance`),不再带 `training_` / `inference_` 前缀——负载类型已经在 `workload_type` 里,分支名再带一次就是两处记同一件事。**分层前写下的历史 trace 保持原样、不改写**(那时的分支 id 是当时口径的真实记录)。
- **字段改过名,读的时候两种都认**:早期 trace 里这两个字段叫 `side` / `side_source`(同一个意思)。新写的 trace 用 `workload_type` / `workload_type_source`;**历史 trace 不回填**——trace 是运行时件,回填等于改写当时的记录。**当前还没有读端**(这一层暂时算不出数),将来接入统计时两个键名都取。
**`workload_type: unknown` 的占比是这一层的体检读数**:它按设计是保底路径(训练与推理都查),占比持续偏高说明步骤 1 那句问话没问出去,而不是"负载类型判不出来"——那时的修法是改流程,不是加词。
### `reference_lookup` 事件(五触发点 + 三态)
先验层的五个触发点各记一条,字段 `{action, purpose, outcome, ref_id, platform, output, reason}`:
| `purpose` | 触发点(时点) | `ref_id` |
|---|---|---|
| `collect` | 数据缺口:采集面(**步骤 3 候选加载后**,精度 / 性能单必留一条) | 采集面词条 id,或 `null` |
| `signature` | 键触发:证据里的错误码 / 故障签名 / 环境变量名 / 版本组合(步骤 2 收尾,**先于候选加载**) | 命中的族表 / 词条 id |
| `background` | 背景层:平台 / 软件 / 工具事实(**步骤 2 收尾,与键触发同一时点,先于候选加载**;**与候选是否命中无关**) | 读到的背景词条 id,或 `null` |
| `fix` | 修复依据:候选命中后按 `ref_knowledge.role` 或工具名取修复路径的依据(步骤 3 阶段 2.5) | 读到的词条 id,或 `null` |
| `procedure` | 方法缺口:候选全未命中后的流程取用(步骤 5,与 `procedure_follow` 成对) | 流程词条 id |
**`background` 与 `fix` 分开记**:前者不依赖候选(未命中单同样要记),后者依赖候选(无候选即不适用)——两条合记会让"未命中单有没有读背景"这件事在数据上消失,而它是这条流程改动要检验的量。
`outcome` 三态(词表与 `scripts/trace_metrics.py` 的 `KNOWN_OUTCOMES` 一致):
- `hit`:查到并用于本次推理(`output` 记"用了哪个事实",不是"读了整页");
- `miss`:查了,但没有相关词条(`reason` 写清按什么键查的、为何无关)——它记的是**知识库的覆盖缺口**;
- `skipped`:**没有查**(`reason` 必写为什么)。两种常见情形:本触发点不在本轮路径上(如候选全未命中时的 2.5 修复依据那一半)、证据里没有可检索键(框架自定义断言文本、Python traceback、业务日志)。**背景层几乎总能查到词**(平台 / 组件名在证据里),所以它的正常负结果是 `miss` 而不是 `skipped`;只有连平台都判不出时才写 `skipped`。
**为什么要有 `skipped`**:不查不留痕时,"查了没命中"与"根本没查"在数据上完全同形——消费率无法归因,也就分不清该改知识库(覆盖缺口)还是改流程(执行错)。`skipped` 不计入 reference 引用次数(那是"查过"的口径)。
### `external_lookup` 事件(外部查证;三态)
外部查证(工具由 DSH 插件提供,端点在 `~/.dsh/sleuth-kb.json`)每调一次记一条,字段 `{action, capability, outcome, reason, endpoint?}`:
| `capability` | 何时用 |
|---|---|
| `versioned-code` | 步骤 5 按版本或镜像定位源码(`vllm_kb_code`) |
| `upstream-fix` | 步骤 5 查修复链、要给「已修复 / 升级即可」的依据(`vllm_kb_fix`) |
| `manual-doc` | 需要手册原文而不是一句话结论(`vllm_kb_doc`) |
| `image-to-text` | 步骤 1 工程师给的是截图(`vllm_kb_ocr`) |
`outcome` 三态与 `reference_lookup` 同一套词表:
- `hit`:拿到结果并用于本次推理(`output` 记"用了哪条证据",不是"读了整页");
- `miss`:查了,但没有相关内容(`reason` 写清按什么查的);
- `skipped`:**没有查**(与 `reference_lookup` 的 `skipped` 同义,不是"查了没命中"),`reason` 必写,取值:
- `probe-failed`:探测不通或查询超时(服务不可达、连接失败);
- `not-configured`:还没配端点;
- `not-applicable`:本单框架不是 vllm-ascend / vllm,这条路不适用;
- `not-needed`:本步用不上。
服务不可达后本单不再重试。**`external_evidence` 的取值写引号**(`'on'` / `'off'`):裸写 `on` 会被 YAML 解析成布尔 `true`。
**不写服务名、不写端点地址**:`capability` 与 `outcome` 就是全部机器面。端点由配置文件决定,报告里可以写端点名称(工程师自己起的标签),trace 里不写。
**不复用 `reference_lookup`**:它按 `ref_id` 计先验消费次数,外部调用没有 `ref_id`,混进去会把消费率算脏。
### `report` 事件(人读定位报告产出,全路步骤 6 必写一条)
**快路不写这一条**,也不写顶层 `report_file`:那条路径按开屏所选范围不产报告(面板与导出脚本对没有报告的 session 有同名兜底,不会报缺件)。**不产报告不等于不落证据**——`user` 事件的 `evidence` 落盘与 agent 事件的 `reason` 照旧必写:没有报告时,trace 就是这单唯一的回放依据,缺了它续接与误诊归因都没有现场。
报告是 diagnose 的三份产出之一(另两份是 trace 与对话输出):trace 管过程可回放,对话输出管现场能行动,
报告管"结论可复述 + 证据可核对 + 沉淀可执行"。结构与行文见 `report-template.md`(本目录)。产出时记:
```yaml
- {step: 6, action: report, report_file: "<session_id>.report.md",
sediment_candidates: 3, output: "产出报告(9 节 + N 张 mermaid 图)",
reason: "为什么写报告;命中型也要写清机制,不因已知根因缩水"}
```
- `report_file`:文件名(与 trace 同目录、同名不同后缀),面板据此提供"打开报告"入口。
**只写文件名,别写 `traces/` 前缀或绝对路径**——面板统一在 `traces/` 下拼路径,写 `traces/<名>.md`
会拼成 `traces/traces/<名>.md`(读与打开都对不上;面板现在会归一,但别依赖它兜底);
- `sediment_candidates`:候选条数(内容见顶层字段,别在事件里重复正文)。
**报告是活件**:报告后来被修订时(resume 续接、用户回报 fix 结果、新证据推翻原结论、沉淀动作发生),
**再记一条** `{action: report, step: <当前步>, report_file, output: "修订了什么(哪几节)", reason: "触发来源"}`——
step 递增即可。没有这条,"报告被维护过"就不可观测(面板与指标都只能看到初稿)。
### 顶层 `sediment_candidates`(结构化沉淀候选)
报告第 8 节与 trace 的这个字段是**同一份内容**的两种呈现:报告给人读,trace 给机器与 resume 读——
resume 时不必重读报告全文即可知道"这单能沉淀什么"。每条四项:
```yaml
sediment_candidates:
- kind: reference # case | reference | triage
summary: 一句话说清可复用的结构事实(跨事故稳定,不绑定本次个案)
evidence: 本轮哪条证据支撑它(trace 事件 / 文件 / issue)
suggested_skill: to-reference # to-postmortem | to-reference | knowledge-groom
status: proposed # drafted(本轮已起草)| proposed(建议做,未做)| produced(已产出)
ref_id: <ref-id> # 仅 produced:产出词条的 id,由 to-reference 回写
```
判"能不能当 reference"的口径:换个事故、换个客户还成立吗?只对本次个案成立的内容属于 case(走 to-postmortem)。
`produced` 只用于 `kind: reference`:to-reference 产出词条后把对应候选从 `proposed`/`drafted` 改成 `produced` 并写 `ref_id`(写入口是 `scripts/trace_transition.py --field candidate`)。它回答"这单产出了哪些词条",也让面板把"已产出"与"待复核"分开;case 候选的沉淀状态仍由 `sedimented` 那条轴记,不写 `produced`。
### `procedure_follow` 事件(方法缺口消费点)
流程闸门命中后,按流程执行时记一条:
```yaml
- {step: N, action: procedure_follow, ref_id: msprof-comm-bottleneck-thresholds,
steps_executed: [1, 2, 3], branch_taken: 慢卡, gap: null}
```
- `ref_id`:本轮加载并按之执行的流程词条(对应一条 `reference_lookup` 事件,purpose: `procedure`);
- `steps_executed`:实际走完的 step 序号;**跳步要写理由**(`skipped` 字段,如 `{2: "本导出无计算列"}`);
- `branch_taken`:流程给出分流时的实际分支(如"慢卡" / "链路异常");无分流写 `null`;
- `gap`:流程某步所需数据不在手上时如实记缺口(缺什么、怎么补),**不臆断分支结论**;
- `conflict`:流程的前提/分支与现场证据**明确矛盾**时记该矛盾(如"流程假设可采到逐卡计算耗时,本导出无此列")——
这是"以证据为准、换一条或转深度排查"的依据;无冲突写 `null`。**记冲突不是记叛逆**:流程被判据推翻是正常结果,
写下来才能让流程层知道自己哪一步在这个现场不成立。
**流程走完但没解决**:在 `attribution` 事件里带 `component: reference:<ref_id>`(verdict 照旧按
case 错 / 执行错判)——让 `component_tally.py` 能聚合出"被跟随后仍失败"的流程簇。否则流程层只有加载率、
没有失败率(加载率是活动度量,加了触发点必然接近 100%),错流程会被稳定注入而无人察觉。
这组字段是"流程是否被真正使用、用得对不对"的唯一数据源——没有它,流程层不可观测(原则八),
也就无法判断某条流程该留、该改、该摘。
## `user` 事件的 `evidence.quotes`(原件引文回验)
**只在工程师交了原件时填**。原件 = agent 之外、能按路径重新打开并在第 N 行读到那句话的文件:日志文件、解开的日志包、交接包里的原件。对话里粘贴的片段不是原件。
```yaml
- role: user
step: 1
content: 客户日志包与 plog 路径
evidence:
files: [plog/host-10.0.0.1/device-3.log]
quotes:
- {file: plog/host-10.0.0.1/device-3.log, line: 1234, quote: "[ERROR:DEV] device 3 ecc error ..."}
```
- `file` 用**相对日志包根目录**的路径(正斜杠,不带 `./`)——接手的人要按这个路径在原包里定位;`line` 是原件里的行号(`grep -n` 或脚本输出给的那个数);`quote` 从原件**逐字复制**,不转述。
- **长行截断要显式标 `...`**:核对时按 `...` 切成若干段、要求各段**按顺序**出现在该行内。不带 `...` 的引文只认逐字相等。这样既不用贴整行,也不给"看起来像就能过"留口子——引文里混进原件没有的内容会被判不一致。
- **粘贴件不填 `quotes`**:没有原件就是没有,在 `evidence.inline` 里存原文、写一句"无原件可核"即可。**它不因此降级,也不主张"已验证"**。
- **核对与降级**:`python3 scripts/verify_evidence.py <trace> --root <原件根>` 逐条重读原件比对,退出非零表示至少一条不能用。按结果处理:
| 判定 | 含义 | 处理 |
|---|---|---|
| `PASS` | 与原件一致(含显式截断按序命中) | 该结论可标"已验证" |
| `MISMATCH` | 读得到但对不上 | 该结论降级为推测,或回步骤 4 重新取证,报告写明原因 |
| `NOFILE` / `NOLINE` | 文件不在 / 行号非法或越界 | 同上——路径与行号也是引文的一部分,对不上就不能用 |
| `READ-ERROR` | 文件解不开(utf-8 与 gbk 都不行) | 编码问题,不判成"引文错";退回让人确认编码后再核 |
| `NO-ORIGIN` | 没有原件 | 不进判定,也不写进报告读者视野 |
- **判据只有两种**:逐字相等(空白归一化),或显式截断的分段按序命中。**不做大小写、全半角、标点的规整**——规整越多,"核对过"越接近"看起来像"。
- **为什么要有这一层**:报告要求"每条结论都指回证据",但"指回去了"和"引文与原件一致"是两件事。后者原先只是人审项(`report_lint.py` 只查结构:必需节、字段配对、路径存在),改写引文与行号漂移都不报错。
## 外部事实获取落盘(agent 侧,与 `user.evidence` 分开)
诊断中为**形成结论**而做的外部获取——`web_search` / `web_fetch` / `gh api` / `git clone` / 源码 `grep` 读——**记到 agent 事件**(`source_analysis` 的 `tool_calls`,或 `reference_lookup`)。
- 每条 = `[<工具/来源>: <该来源确立的关键事实 或 失败原因>]`,**记"用了哪个事实"而非"抓了整页"**(token 纪律)。
- 失败的源也记("哪源不可达/404"是可复用教训,备选源清单由此沉淀)。
- 判据:这条外部事实是否**进入了本次诊断结论的推理链**——是 → 记;纯背景、未用 → 不必记。
- **别与 `user.evidence` 混**:外部是 agent 查到的、可再查证(记来源+事实即可);用户**提供**的现场证据是跨 agent 必须自包含的(走 `inline`/`file`)。
### `source_analysis` 的取用字段(源码取用读数)
记一条 `source_analysis` 时,除 `tool_calls` 外,把这次取源码的事实写进同一事件:`repo`(`org/repo`,与 `source-catalog.d` 同一写法)、`ref`(版本)、`fetch_exit`(`src_fetch.py` 的退出码整数)、`verify`(hit / miss / skipped)。
`fetch_exit` 与 `verify` 不写时读数按"未记录"分字段计,不回填;两值越界由 `trace_metrics.py` 报违规,不中断整张表。仓与版本按原值计数,别名不合并:同一仓写成两种名字就算两种写法,要合并先在 `source_catalog` 统一写法再记。汇总入口:`python3 scripts/trace_metrics.py --source-usage`(只进人读输出与 `--json`,不进 `--emit-yaml` 快照)。
## agent 事件分两层(output 给用户 / reason 记决策依据,缺一不可)
- `output`:给用户看的内容(可精简)——透明性的呈现层。
- `reason`:**决策依据/推理过程**(回放、误诊归因、知识沉淀的证据)——**关键决策必写**:triage 路由(为什么命中此分支)、quickly_check 排除(比对了哪些候选、为何排除)、hit/miss(证据链、比对结果)、reference 甄别(为何部分适用/不适用)、根因判断(证据→结论)。**output 和 reason 分开**:结论简洁,推理要完整。
### 行文口径(这两个字段同样要守)
**字段齐全不等于读得懂**:面板把顶层 `summary` 与逐事件的 `output`/`reason` 直接摊给读者。共用条目与必须保留的四类原值见同目录 `report-template.md` 的「行文规范」一节——同一 skill 内随 `references/` 一起分发,不依赖 `docs/`;完整判定口径、各面差异与核对配方另见 `docs/spec/writing-norms.md`(可选论证层)。
- **一条只说一件事**,超一个分句就拆行;不把多件事压进 `①②③` 长句——并列掩盖因果,读者读完只知道"有几条",不知道"哪条导致哪个动作"。
- **`summary` 装什么**:按五块写,各一小段——现象(含读数)、排除链(排除了哪些候选或方向、为什么)、根因、处置(给了什么 fix 或下一步)、状态(等回报 / 已收尾 / 待更正)。没有的块跳过。面板这块的标签是「本次诊断摘要」,读者按摘要读,所以背景之外必须有结论。
- **长度可数**:`summary` 按小段写、每段不超过 3 句;每条 `output` 不超过 3 句,超了拆成几条(一步一条)或改成列表。面板把整段直接摊开,单条上千字就是一堵墙,没人读完。
- **拆段不删句**:拆段只改信息落在哪一行,不改信息有没有。原文里的 issue 号、`文件:行号`、命令、数字、报错原文一句不少;改完把原值清单逐条 grep 回来,缺一条就是改坏了。
- **主语用具体对象、谓语用动词**。"指南里那句『已按此拓扑验证』出自只改文档的 PR" 读得懂;"验证措辞来自文档 PR" 读不懂(抽象名词当主语)。
- **自造代称首次出现即定义**:为本次诊断临时起的简称(给某个中间状态起的别名之类),只有写的人看得懂,读者没有那段上下文。
- **不造比喻、不排比、不加强调副词、不自我评价**:"如实记录""不冒充"一类删掉——如实是默认要求,不必在正文里声明。
**发出前先问一句**:把「首先」「值得注意的是」「总而言之」这类词划掉,句子还成立吗?成立就把词删掉——填充词删掉之后不留下缺口,能删就该删。然后过下面那条(简称第一次出现就展开、原值照抄),两条都过了再发。
trace 特有的一条:**读者没有会话上下文,也没读过报告**。所以字段要能独立读懂——首次出现的简称当场展开,`output`(给用户)与 `reason`(决策依据)分开写;证据原值(case/issue 编号、`文件:行号`、命令、数字、报错原文)照抄,不翻译。
## 顶层 `severity` 与 `fix_emitted`(收尾时各写一次)
```yaml
severity: data-loss-risk # benign | service-affecting | data-loss-risk
fix_emitted: false # 本次有没有给出可执行的修复或规避方案
```
- `severity` 与命中 case 的同名字段同源;未命中时按根因判,会丢数据的写 `data-loss-risk`。它决定读的人第一件事是"先停"还是"打补丁"——面板据此给「数据风险 · 先停」徽标,**不给 fix 是 severity 闸门的要求,不是漏写**。
- `fix_emitted: false` 的常见情形:等上游修复、只定位到根因、根因清楚但规避方案未验证。它与 `feedback.outcome` 不是一回事:前者说"我们给没给",后者说"给了的那个管不管用"。
- 两个字段都缺时面板不占位(不显示徽标),也不会报错——代价只是这类单在列表上与 benign 无差别,所以收尾时必写。
## 顶层 `incident_env` 与 `incident_timeline`(现场故障时间线)
本节与下面两节的字段是面板前三段时间线的数据源:现场故障时间线(客户环境里发生的事,下称「现场侧」)→ 故障过程(日志)→ 上游与查证;面板第四层是诊断步骤,来自 `trace[]` 的步骤事件。`revisions` 是这三段当前值的修订记录,不是第四层。全都可选;旧 trace 没有就按「未记录」显示,**不回填**——回填只能靠事后回忆,会把事后想到的写成当时看到的。
**写时机**:步骤 1 收集症状时写现场侧与环境;读日志定位时写故障过程;查上游时写上游;每次改当前值经 content 写入口(`scripts/trace_transition.py --field content`),写入口自动落一条修订。
`incident_env` 一行写现场环境,`incident_timeline` 按材料时序记现场侧发生的事实。字段缺省或写 `null` 都按「未记录」;写 `[]` 表示字段在、还没有事实。
```yaml
incident_env: "平台 / 框架 / 版本 / 部署形态,一行"
incident_timeline:
- id: inc-1
at: "YYYY-MM-DDTHH:MM:SS+08:00"
at_note: "起服务约 8 分钟后"
what: "日志开始重复打同一行,计数冻结"
source: log
step: 1
evidence: {files: ["traces/evidence/<sid>/worker.log"], quote: "日志原文一行", line: 12}
```
| 字段 | 要求 |
|---|---|
| `id` | `inc-<n>`,在本列表内唯一;`revisions` 按它指认改的是哪一条 |
| `at` | 材料给到什么精度写到什么精度;只有日期就写 `YYYY-MM-DD`;没有时点写 `null` |
| `at_note` | 相对时间原文(「重启后第 3 次迭代」这类),`at` 为空时它可能仍是唯一的时序线索 |
| `what` | 一句话事实,不写推断;判断留在诊断步骤的 `reason` |
| `source` | `log` / `user` / `issue` / `comment` / `commit` / `doc` / `field_test` / `observation` |
| `step` | 来源步骤(整数),回答「这条事实是哪一步拿到的」 |
| `evidence` | 证据指针:`files`(相对仓库根的路径,形如 `traces/evidence/<sid>/…`)、`quote`(原文)、`line`(行号) |
`id` / `what` / `source` 必填,`at` 可空;其余字段按手上有什么写。列表最多 16 条(写入口校验)——现场事实超过 16 条时先合并同类、只留转折;面板段头按总数显示,超出面板显示量时写「显示前 N 条」。
**只收现场侧**:现象、变更(谁改了什么)、规避与恢复。上游的 issue / PR / 维护者答复进 `upstream_timeline`,不混进这一段。
**`at` 照材料原值写,不换算时区、不补精度**。日志与墙钟有时差时写在 `failure_process.clock_note`,不在每条时间戳上改算。
## 顶层 `failure_process`(日志证据层)
从日志里读出的一段过程:从哪个状态转到哪个状态、在哪一行开始、重复了多久。面板默认收起,有 `clock_note` 时在段头提示日志时间与墙钟不一致。
```yaml
failure_process:
axis: time
window: {from: "YYYY-MM-DDTHH:MM:SS+08:00", to: "YYYY-MM-DDTHH:MM:SS+08:00"}
clock_note: "日志时间比墙钟晚 8 h(日志 08:34:22 = 墙钟 16:34:22)"
nodes:
- id: fp-1
at: "YYYY-MM-DDTHH:MM:SS+08:00"
x: null
what: "从空闲转入重试"
quote: "日志原文一行"
repeat: "每 ~1 s 一次,持续到 YYYY-MM-DDTHH:MM:SS+08:00(约 50 min)"
evidence: {file: "traces/evidence/<sid>/evidence.txt", line: 17}
```
- `axis` 取 `time` / `step` / `request`。当前面板只按 `time` 渲染,另两种轴仍要写 `axis` 与 `x`,为后续读端留字段。
- `nodes` **最多 8 条**:挑状态转折的节点,不按日志行数记。全量日志不进 trace,原文落 `traces/evidence/<sid>/`。
- `nodes` 里 `id` / `what` / `quote` 必填;`axis` 与 `nodes` 是整段必填项,`window` / `clock_note` 可省。
- `quote` 是日志原文一行。`repeat` 记重复节奏与持续时长,用来表达「同一行打了几千次」而不贴几千行。
- **时钟偏差必写**:多机日志、或日志与墙钟对不上时,`clock_note` 写清谁比谁差多少。不写它,读者会把日志时间当墙钟时间排先后。
- `evidence.file` 与 `line` 指回原件,读者能按行重读。
- **写时机**:读日志定位(步骤 3–5)时边读边记;一批日志只提炼转折点,不做全量转录。
- 只放可观察事实:节点写「日志出现了什么」,推断写进对应步骤的 `reason`。
## 顶层 `upstream_timeline`(上游与查证时间线)
上游侧的事件与查证结论:issue 何时开、维护者怎么回、PR 何时合入、哪个版本带这个修复。面板「上游与查证」段读它。
```yaml
upstream_timeline:
- id: up-1
at: "YYYY-MM-DD"
what: "维护者确认是已知问题,指向修复 PR"
source: comment
ref: "#13976"
evidence: {files: ["traces/evidence/<sid>/issue.txt"]}
```
| 字段 | 要求 |
|---|---|
| `id` | `up-<n>`,在本列表内唯一 |
| `at` | 同现场侧:照材料精度,没有时点写 `null` |
| `what` | 事件一句话事实。「维护者说 X」与「由此判断 Y」分开写 |
| `source` | `issue` / `comment` / `commit` / `doc` / `maintainer` / `vendor` / `field_test` / `observation` |
| `ref` | issue / PR / commit 编号或链接,原文照抄 |
| `evidence` | 证据指针,同现场侧 |
- **写时机**:查上游时每拿到一条证据记一条——步骤 5 的上游 follow-up、vllm-kb 的修复链查询都算。
- **只放查到的事实**:维护者说了什么、PR 合没合、哪个 release 声称带修复。对部署版本的判断写进结论与 `reason`,不写成上游事实。
- **字段存在且为空**(`upstream_timeline: []`)表示查过、上游没有修复记录,面板显示「无上游修复记录」;字段缺省或写 `null` 表示没查过(旧单),面板不显示这一句。三态不要混。
- **「已修复」是待验证的假设**:PR 或 issue 已 closed 不等于部署版本带这个修复,落地实证的结论写进 `what`,不把「升级即可」直接当上游事实。
- 列表最多 12 条(写入口校验);超出时先合并同一条 issue / PR 的多次回复,不逐条搬。
## 顶层 `revisions`(修订记录,只追加)
trace 的当前值会变:用户更正、新证据推翻结论、上游状态变了。变的时候留一条修订,写清改前、改后与为什么改。
```yaml
revisions:
- at: "YYYY-MM-DDTHH:MM:SS+08:00"
by: agent
kind: fact_corrected
changes:
- {target: inc-3, before: "旧值", after: "新值"}
- {target: failure_process, before: "旧 axis / window / clock_note 的 JSON", after: "新的 JSON"}
- {target: "removed:<id>", before: "被删条目的摘要", after: ""}
reason: "为什么改(新证据 / 用户更正)"
evidence: {files: ["traces/evidence/<sid>/..."]}
hashes: {incident_timeline: "sha256:..."}
```
**当前值只经写入口改**:`summary`、`incident_env`、`incident_timeline`、`failure_process`、`upstream_timeline` 用 `scripts/trace_transition.py --field content --content-file <json>` 写。写入口只更新 `set` 里给出的字段,按 id 比对生成这条修订,并给被改字段记 `hashes`。
```bash
python3 scripts/trace_transition.py <sid> --field content --content-file /tmp/content.json --by agent --json
```
`/tmp/content.json` 的形状(`set` 至少一个字段;没有变化时写入口返回 `E_NO_CHANGE`,不产生修订):
```json
{
"set": {
"incident_env": "平台 / 框架 / 版本 / 部署形态,一行",
"incident_timeline": [{"id": "inc-1", "at": "YYYY-MM-DDTHH:MM:SS+08:00", "what": "…", "source": "log", "step": 1}]
},
"kind": "fact_corrected",
"reason": "用户更正起服务时间",
"evidence": {"files": ["traces/evidence/<sid>/msg.txt"]}
}
```
| `kind` | 什么时候用 |
|---|---|
| `fact_corrected` | 现场事实写错或补全(时间、原文、来源) |
| `conclusion_overturned` | 结论被新证据推翻,`summary` 与相关段一起改 |
| `scope_changed` | 问题范围变了(如从单机扩到多机) |
| `severity_changed` | `severity` 改了(先停改成可打补丁,或反过来) |
| `sediment_changed` | 沉淀状态或候选变了 |
`changes` 的写法:
- `target` 三选一:被整体替换的字段名(如 `incident_timeline` / `failure_process` / `summary`)、当前条目的 id(`inc-3` / `fp-2` / `up-1`)、或删除条目的 `removed:<id>`。
- `before` / `after` 写人读摘要,不抄整段 JSON——面板的写入历史要让人一眼看出改了什么。
- 新增条目 `before` 写空串;删除条目 `after` 写空串,`target` 用 `removed:<id>`,校验不要求被删的 id 还在当前列表里。
- 例外是 `failure_process` 的结构字段(`axis` / `window` / `clock_note`):它们没有单条 id,变化时 `target` 写 `failure_process`,`before` / `after` 写这几个键的 compact JSON(不是整段字段);节点变化仍按 id 一条一条记。
- `hashes` 由写入口填,不手写。
`by` 取 `user` / `agent` / `cli`,由写入口的 `--by` 传:agent 自发改写传 `agent`,脚本与人工命令行传 `cli`;面板当前没有 content 写路径。
**状态转移顺带改摘要也要留修订**:收尾时用 `trace_transition.py --to … --summary …` 改 `summary`,写入口会追加一条 `fact_corrected` 修订(before / after 与 `summary` 的 hash);与 content 写入口同一份口径。
**手改会被查出来**:写入口给每个被改字段记 `hashes`,`python3 scripts/verify_trace_status.py --all` 重算当前值时与最近一条带该字段的修订比对,不等即绕过;另有一条兜底——内容字段有值、却没有任何修订 hash 时直接报错,首次手写或删掉整段 `revisions` 也跑不掉。`summary` 不在这条兜底里(它还有状态转移这一条合法的写入路径)。
**报告同步**:改了会影响结论或时间线的字段,报告对应小节与第 10 节修订记录同一次改完(规则见同目录 `report-template.md` 第 2 节)。
## 零执行评估所需的三项记录
trace 不止当过程记录读,还有第二个用途:换一个探索策略在这段历史上走一遍(同一批决策点,换不同的展开方式与停止点),用来判断当时的做法好不好。这个用途对记录有三项要求,缺了它,重放只能按写的人事后回忆重讲:
- **顶层 `stop_reason`(会话收尾写一次)**:这一单为什么停。取值 `resolved_confirmed`(工程师确认修复生效)/ `halted_ask_user`(按流程停下等人回报)/ `budget_exhausted`(上下文或预算到线)/ `escalated_tier3`(转深度排查后仍无结论)/ `abandoned`(主动放弃,如材料不足)/ `closed_by_user`(用户在面板直接收尾)/ `unknown`(当时确实拿不到原因)。停止点本身是探索策略的一部分:不记它,就判断不了当时该不该停在这里。
- **事件的 `parallel_group`(同批并发标记)**:同一次并行展开的几个动作共用一个值(自己起个短名即可),串行展开的动作不写。它记的是同时展开几个候选。
- **事件的 `considered_candidates`(候选全集)**:筛选时看过的候选 id 列表,含没有取全文的那些。事件原有的 `candidates` 仍只写实际取全文的候选,所以 `candidates` 必须是 `considered_candidates` 的子集。
三项都可选:旧 trace 没写就按"未记录"统计,不回填、不猜;回填只能靠回忆,会把事后想到的写成当时做的。字段违规由 `scripts/trace_metrics.py` 报出来,不静默收下:停止原因不是字符串或不在词表里、并发标记不是非空字符串、候选全集不是候选 id 列表、取全文的候选不在候选全集里或本身不是列表。读数先给违规总处数,再列前 5 条。
## 事件级 `ts`(可选,写了才有每步成本)
每个 agent 事件可带 `ts`:epoch 毫秒(`python3 -c 'import time;print(round(time.time()*1000))'` 的输出),也认秒级浮点与 ISO 8601。
**它换来看什么**:会话账单按 `harness` 的轮次计,轨迹按诊断步计,两套编号不同源。有了 `ts`,收尾脚本就能用「相邻两个步边界之间的时间窗」把每次工具调用与 token 用量折进**诊断步**——面板上才有「每步花了多少、哪一步最贵」。没有 `ts` 时那一格写「本次没记」,因为按事件顺序硬猜会把耗时挂到相邻的步上,比没有更坏。
**它不是什么**:不是把耗时与 token 抄进轨迹(那条已被否决,见 [docs/adr/0011](../../../docs/adr/0011-diagnosis-observability-data-plane.md) 的「把 token 与耗时写进轨迹事件」)。`ts` 只是**关联键**,计量仍在会话账单那一份。
**怎么写得省事**:不必每个事件都打。**每一步至少一个事件带 `ts`**(通常就是这一步的第一条)就够切窗口;窗口右边界取下一条带 `ts` 的事件。
## 顶层 `ended_at`(可选,写了收尾段才有数)
诊断收尾时写一条 `ended_at`(ISO 8601)。它是每步成本右上角的边界:最后一步的窗口从它的 `ts` 开到 `ended_at`。
**不写会怎样**:收尾段的边界只能退到 `updated_at`,而那次更新之后往往还有复核、改面板、跑别的活——这些会被算进最后一步。摘要把这种情形标成 `window_truncated`,面板写「收尾段未记」,**不给一个数**:给一个混了别的活的秒数比不给更坏。
**它也是单次成本的右边界。** 单次的总耗时与 token 按 `created_at` → `ended_at` 切窗口(`cost.window`):会话账单记的是整条 harness 会话,同一段对话里做过两单时,两单会拿到同一份本会话累计,读数一模一样。不写 `ended_at` 时窗口退到 `updated_at`,明细里标 `bound_to: updated_at`、面板上写明——那个数之后可能混着诊断之外的活。
## 建 trace 的入口
用 `python3 scripts/trace_begin.py --slug <日期>-<issue 号>-<短名>` 起顶层 header:`session_id` / `harness_session` /
`created_at` / `kb_rev` 都是派生值,由脚本填;`$DSH_SESSION_ID` 取不到时它**留空并说明**,不猜。
之后每步只往 `trace[]` 追加事件(字段口径见本文件其余部分)。
## 顶层 `harness_session`(可选,一次写定)
harness 侧的会话号(DSH 里是 `$DSH_SESSION_ID`)。**用途有两个**:收尾汇总时把这一次诊断与 harness 会话日志关联起来,读出逐次工具调用与 token 账单(会话日志里有这两样,轨迹里没有;轨迹里自己写一份是复制而不是关联,两边不一致时没有判据说该信哪一份);以及让侧栏「待回报」标记能找到这一次诊断对应的会话行——标记按这个字段匹配,缺了它,欠回报的那一单在侧栏上就标不出来。
拿得到就写;拿不到留空——留空让那次会话的成本与工具分布缺席(汇总脚本会如实说明),也让侧栏少一个标记;写一个猜的值会让账单对到另一个会话上。
**缺了两边都停摆**:面板只能说「未记会话号」(它只看得见字段缺失,分不出是建会话时漏写还是旧单——所以文案不猜年纪);侧栏的行首记号与「待回报」标记也挂不上。补的时候给已知会话号最快:
`python3 scripts/link_harness_sessions.py --trace <文件名> --session-id "$DSH_SESSION_ID" --apply`(不扫日志,秒级);历史单不给 `--session-id`,脚本去会话日志里按名字认。
**它还是「从轨迹跳到原始会话」的依据**:`session_id` 不是 DSH 的会话号,面板的「打开会话」与侧栏「诊断记录」都只认这个字段;没有它时面板显示「未记原始会话号」。
**续接不覆盖这个顶层字段**:每次 `resume` 事件带 `harness_session: "$DSH_SESSION_ID"`,插件按续接链把当前会话标成续接归属;顶层字段仍只做原始会话与成本 / 工具归因。所以没有顶层字段但有 `resume` 事件时,面板仍能显示续接会话,只是原始会话显示未记。
历史轨迹缺这一栏时用 `python3 scripts/link_harness_sessions.py --apply` 补:按「会话时间窗覆盖 `created_at`、且会话开始时间离它最近」判定是谁写的那一单;只补空,只有弱证据(命中次数)的默认不写,`--allow-weak` 才写。显式给 `--session-id "$DSH_SESSION_ID"` 时允许把空值(`harness_session: ""`)补上,非空值不覆盖。
**诊断会话的名字(`session_id`)与 harness 会话号是两套**:前者是这次诊断自己起的(形如 `<日期>-<issue 号>-<短名>`),后者是 harness 分配的。汇总脚本不写这个字段时按 `session_id` 试一次。
## 顶层 `external_evidence`(会话级,一次写定)
建 session 时按主组工具(`vllm_kb_code` / `vllm_kb_fix` / `vllm_kb_doc`,DSH 里由 `vllm-kb-tools` 行控制)在不在写一次,之后不改;`vllm_kb_ocr` 有独立一行,只影响截图转文字,不改变这个字段:
- `on`:工具在(外部查证可用);
- `off`:工具不在(没装、或工具行关着)。
没有它,"没有 `external_lookup` 事件"分不清是没开还是没用到——这正是 `reference_lookup` 要分 `skipped` 的理由。**开了但服务挂了仍写 `on`**:那是事件级 `skipped` 加 `reason: probe-failed` 的事,两者不要混。
## 顶层 `kb_rev`(知识基线:会话级,一次写定)
建 session 时把当时那份 `knowledge/` 的版本写进去——知识基线是诊断读知识库的那一版 commit 坐标(`python3 scripts/kb_rev.py` 的末行 = 检出 HEAD 短 sha),**之后不改**。两个用途:
- **跨机接手**:一单在一台机器上做到一半、换到另一台继续时(更多日志在另一台),接手方要拿这个值比对本机知识库版本。不一致意味着 `excluded_cases` 里的 id 可能不存在、同一条 case 的排序分数不同、甚至那条 case 当时还没沉淀出来——接手方会复现出一套**与上家不同的候选集而不自知**。口径与工具见 `docs/guide/handoff.md`。
- **事后归因**:判"当时为什么没命中"要能回答"当时库里有什么",只看今天的库会把"库里当时没有"读成"检索没找到"。
拿不到 git(非检出、无 git)就如实写 `unknown`——写 `unknown` 只让版本无法比对,编一个值会让比对给出假结论。
工作区有未提交的已跟踪改动时,`trace_begin.py` 另写顶层 `kb_rev_dirty: true`。`kb_rev` 的 sha
只标识提交,不能单独指认脏工作区里的规则;续接时的漂移检查会把未提交改动一并算入。
远端版本与落后数不写进 `kb_rev`:下一节的同步字段记「这一单同步到哪、差多少」。
## 顶层知识库同步字段(建单时由 `trace_begin.py` 写定)
`trace_begin.py` 在建单时同步一次知识库,并把结果写进下表的六个字段;顺序是校验 → 同步 → 写文件,参数校验不过时不联网、也不落 trace。`kb_rev` 的语义不变:它仍是这一单**实际读的那份工作区 HEAD**,下表只记**同步动作**,两者不要互相替代。
| 字段 | 记什么 |
|---|---|
| `kb_remote` | 同步源远端名与分支,如 `origin/main`;取不到时留空 |
| `kb_remote_rev` | 本机 `remote/branch` 引用的短 sha;fetch 未成功或本机没有这个引用时写 `unknown` |
| `kb_behind` | `HEAD..远端分支` 的提交数,或 `unknown`;与 `kb_rev` 一起回答「读的哪版、差多少」 |
| `kb_sync` | 同步结果:`ok` / `failed` / `off` / `skipped`(`ok` 只表示 fetch 成功,合没合看 `kb_merge`;`off` = 同步关闭、部署声明离线或建单时显式不联网;`skipped` = 失败缓存期内) |
| `kb_sync_reason` | 没同步、同步失败或没合并的原因,如超时 / 网络不通(含代理不可达)/ 无远端 / 非检出 / 撞 ref 锁(git fetch 并发更新引用时的锁冲突,按失败降级、不重试)/ 工作区有改动 / 分支不符;没有原因时留空 |
| `kb_merge` | 这一单有没有动过检出:`ff-only`(做了快进合并)/ `none`(没有合并) |
一次合并同时更新知识与流程:`knowledge/` 在运行时读取立即生效,`skills/` 要下一次会话才重新加载。自动合并只在这四条同时成立时发生:当前分支 = 配置 `branch`、HEAD 是远端分支的祖先、`git status --porcelain -uno` 为空、无进行中 merge / rebase / cherry-pick;worktree 与 detached HEAD 不自动合并。
## 顶层 `last_action`(当前在等什么,提问后更新)
`last_action` 记这一单现在等谁做什么:等哪份材料、等哪个决定、等哪条命令输出。写入口是
`trace_begin.py`(建单时写空串);每轮以提问结束时写,**下一轮拿到回答后改写或清空**。
它和 `evidence.missing` 分工不同:`missing` 挂在那一轮的 user 事件上,记的是**当时缺的材料**,
历史事件不改写;`last_action` 是**当前**那一个问题,可以随回答变化。面板与续接只读
`last_action` 判断「等什么」,不按事件顺序推断「后来的进展等于回答了问题」。
状态投影里的 `waitingFor` / `waitingOn` 是这两个字段的派生量(`scripts/_trace_state.py`),
不写盘。收尾后通常为 `ended`;等现场回报或等上游时分别是 `user_feedback` / `upstream`。历史缺口不再显示成「还在等」。
## 值的写法(YAML 语法陷阱)
值里**含 ` #`(空格 + 井号)或 `: `(冒号 + 空格)时必须加引号**——不加的话 YAML 从那里起当注释或当新键,
值会被**静默截断**。实测:`active_case: pending-investigation (upstream #14728)` 读出来是
`pending-investigation (upstream`(少一个反括号);读到的人以为是"面板把反括号吃了",
而 PyYAML 与面板读到的其实是同一份被截断的值——根因在写侧。issue 号、带 `#` 的片段都属这一类,统一加引号。
顶层 `active_case` 只写**命中的 case id**,没命中写 `null`。占位串 `pending-investigation` 是
`feedback.case` 的取值(表示"没有 case 可结算"),不要写进 `active_case`——写进去面板会把它
当 case 显示,并按它生成"该 case 的 fix 生效了吗"这类指令。要记"转上游 / 上游未修"这类说明,写进
`summary` 或 `last_action`。
## 反馈闭环词表
反馈确认后,顶层 `feedback: {case, outcome, confirmed_at}` 要填——`status=resolved 且 feedback.outcome=resolved` 是该 trace 升格为 fixture(强断言基准)的资格条件(`scripts/replay_trace.py --emit-fixtures` 只看这种)。
**终态的收尾方式(`ending`)由写入口写**:`status` 进入终态时必须同时有 `ending`(`{kind, handed_to, duplicate_of, note}`,取值见 `trace-status.yaml` 的 `ending_kinds:`),并追加一条 `transitions` 事件(从什么到什么、收尾方式、谁、何时、来源)。收尾走 `python3 scripts/trace_transition.py`,不要手改 YAML——手改没有校验、没有事件,`verify_trace_status.py` 事后才能发现。
**无命中 case 的单没有 feedback 可写**:它的闭环只记 `status: resolved`(面板的「已解决」命令就是这么做的)。别为了"留一条"而补占位 `case` 的 feedback 事件——结算侧找不到 case 会把它挂成"待结算"、游标不再前进;升格闸门对这一类读 `status`(见 `scripts/verify_case_draft.py`)。
## 沉淀状态(`sedimented`,第三条轴)
顶层 `sedimented: {state, case_id, inbox_path}` 记"这单的结论进知识库了没"。它与 `status`(诊断收尾)、`feedback.outcome`(命中 case 的 fix 行不行)不是同一件事,三条轴各有名字,不互相借;但无命中单没有 case 可写 `outcome`,它的闭环落在 `status` 上。
字段写法以 `diagnosis_state.yaml.example` 为准(`case_id` / `inbox_path`);面板读端同时认旧 trace 里的 `caseId`:
- `submitted`:to-postmortem 产出草稿、落 `postmortems/inbox/` 时回写(动作发生时写,不做推断);
- `knowledge` / `archived`:knowledge-groom 转正后回写,并记 `case_id`;
- 字段缺失按 `none` 读,不显式写。
取值与写入时机以仓库根 `trace-status.yaml` 的 `sedimented:` 段为准。诊断面板的「待升格」筛选就是 `submitted` 且来源诊断未闭环——这类草稿升格时会被 `scripts/verify_case_draft.py` 的闸门拦下;强外部证据档(上游修复已合入等)可走 owner 双签。
## 词表同步纪律
`trace` 的 action 词表与 `scripts/trace_metrics.py` 的 `KNOWN_ACTIONS` 保持一致;`reference_lookup` 的 `purpose` 与 `outcome` 分别与 `KNOWN_PURPOSES` / `KNOWN_OUTCOMES` 保持一致;顶层 `stop_reason` 与 `KNOWN_STOP_REASONS` 保持一致;新增取值必须两处同步(本文 + 脚本)。user 事件无 action,不参与词表检查。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |