feat(otel): diagnose code agent traces

.agents/skills/unidesk-otel/SKILL.md

@@ -88,6 +88,28 @@ OTel trace 内常见业务关联属性：
 
 追 `Code Agent 代理暂时无法连接上游`、`provider-stream-disconnected`、Workbench 加载/转圈、turn idle 报错、AgentRun command terminal 状态时：
 
+优先用一条诊断命令汇总业务 trace、OTel trace、服务追穿、AgentRun 终态、HWLAB 读模型和 HTTP 403/401/5xx 根因：
+
+```bash
+bun scripts/cli.ts platform-infra observability diagnose-code-agent \
+  --target D601 \
+  --business-trace-id <trc_...>
+```
+
+默认输出必须保持有界低噪声，重点看：
+
+- `mapping.businessTraceId` / `mapping.otelTraceId`
+- `servicePath` 是否同时到达 `hwlab-cloud-api`、`agentrun-manager`、`agentrun-runner`
+- `identity` 里的 `runId`、`commandId`、`sessionId`、`runnerJobId`、`runnerId`、`backendProfile`、`sourceCommit`
+- `agentrun.terminalStatus`、`terminalEventType`、`runnerProviderClassification`
+- `hwlabReadModel.sourceEventCount`、`requestedSinceSeq`、`turnStatusCounts`
+- `http.problemCounts` 和 `projectionLag.status`
+- `summary.rootCause` 与按置信度排序的 `rootCauseCandidates`
+
+只有需要展开 span 明细时使用 `--full`；只有排查 Tempo raw 响应或 CLI 解析器时使用 `--raw`。默认输出不得包含 Secret、Authorization header、DSN、可复制凭据或完整运行 transcript。
+
+若没有业务 traceId 或诊断结果还需要 drill-down，再使用低层 trace/search：
+
 1. 先确认 OTel backend ready：
    `bun scripts/cli.ts platform-infra observability status --target D601`
 2. 查业务 trace 对应 OTel trace：