可观测 / 排障地图

怎么读

把诊断码当成入口：先辨认是 协议硬门、Run/Plugin 执行 还是 本机/Schema 存储，再顺着 产出面 → 落点 → 排障入口 查。

失败/成功链总索引：../FAILURE-CHAINS.md。

Work SSE：路由决策投影与续跑通知（2026-10-13 钉点）

• capability_route_decision：Work 观察流只转发脱敏投影——status 与已选能力（primaryCapabilityId 及其置信信号；refused 时为空），不下发其它候选、原话或抽取槽位。
• run_recovering：实例下线排空时发 reasonCode: SERVER_DRAINING 后正常结束流。租约丢失/中断的 Run 由 decideOwnerLostRecovery 决定：未产生写入提案/来源写入且未发布回复的轮次回 pending 重新领取（有上限），已写入或超限转 manual_recovery（*_AFTER_WRITE）。
• Desktop（钉点 8eecd12081db）收到 run_recovering 只在界面显示「续跑中…」（active / processing，60 秒权威窗口），不改服务端 Run 状态。

只读 Run 消息流与诊断轨迹（钉点 e2adc9a3c325 / 8eecd12081db）

• 只读 AI SDK 消息流：GET /api/runs/:runId/stream 复用拥有者可见性鉴权，从 chat_sse 账本按序号整条重放；POST /api/runs 与非 GET 的 /:runId/stream 一律 405 UI_MESSAGE_READ_ONLY，拒绝 SDK 自动审批回写。生产 Chat Work 的公开事实由 common-control 事务在 savepoint 里写入 run_projection_events（每 Root 10000 条 / 16 MiB，超限或投影失败写 chat_sse_truncated，Work 核心状态照常提交；见 storage-planes）。
• 诊断轨迹交付：Agent 只在 chat 角色、Redis 可连通时开 RedisDesktopTrajectoryDelivery（TTL 300s、8 MiB、10000 事件、每主体 8 会话），这只是临时传输；Desktop Main 的 DesktopTrajectoryStore 是唯一持久日志与本地归档，由 Main 的 developer 模式与轨迹面板偏好共同控制，新任务提交时自动准备采集，不再提供独立 start-capture 控件/IPC；准备握手最多等待 2 秒，迟到结果不得在业务提交后开启采集。身份/设置失效撤销采集，不保存凭证、不授予恢复权限。
• 流内生命周期（见视图 runs-stream）：首读为空或账本不完整返回 409，不把丢失历史当空回复；开流后每轮先重新鉴权（会话或租户变了即中断），按 cursor 增量 listAfter、空批时 250ms 轮询；结束条件是投影 finished、Run 终态、恢复中、300s 期限或重放事件数 / 字节上限，中断时补 interruption 帧再 [DONE]。
• 证据：aida-agent · packages/agent/src/gateway/api-runs.ts L116–171 · runUIMessageStream · e2adc9a3c325；aida-agent · packages/agent/src/gateway/run-ui-message-stream.ts L35–221 · runUIMessageStream · e2adc9a3c325；aida-agent · packages/agent/src/index.ts L2342–2368 · RedisDesktopTrajectoryDelivery · e2adc9a3c325；aida-agent · packages/agent/src/gateway/api-trajectory-delivery.ts L33–46 · CAPTURE_DESKTOP_IDENTITY_REQUIRED · e2adc9a3c325；aida-desktop · apps/desktop/electron/trajectory/desktop-trajectory-store.ts L40–80 · DesktopTrajectoryStore · 4346d79eb364；aida-agent · packages/agent/src/gateway/chat-routes.ts L560–600 · RUNTIME_WORK_MESSAGE_TOO_LONG · e2adc9a3c325

运行时指标、待办快照与显式 Stop（钉点 e2adc9a3c325，STA-33）

• 指标基线（MR1，9ed5e3fbc）：接入现有 /metrics，标签都是有限枚举。chat 受理结果（accepted / duplicate / not_started{reason} / rejected{status} / unavailable / reply_replayed，每次请求只记一次）、按 quota_bucket 的排队时长、LLM_BUSY 与 LLM 排队等待、首次公开正文发布耗时、reply_user 与兜底发布计数、Worker 名额。记录失败只记日志，不改业务结果。
• 待办快照（MR3，ba37f6827）：GET /api/work/attention 只读、轮询优先，返回本人前台 Work / 后台 Work / 业务事项 / 待办卡（state：running / queued / waiting / needs_action / terminal）；只读 repeatable-read + 5 秒期限，候选各限 1000，最近结束 24 小时 / 100 项；游标 HMAC 签名、5 分钟有效，可见集合变了 409。runtime-capabilities 增加 attention { apiVersion: 1, polling: true, enabled }。SSE 订阅留给 MR9。
• 显式 Stop（ADR-0095 2a-2）：Stop 必须指向明确 root run id——POST /api/runs/:runId/work-stop 只停该原工作，GET 同路径只查该命令受理事实；没有会话级批量 Stop；getActiveByConversation / attach fallback / 受理占用都排除后台 root。
• 证据：aida-agent · packages/agent/src/observability/runtime-metrics.ts L84–136 · recordChatAdmission · e2adc9a3c325；aida-agent · packages/agent/src/gateway/api-work-attention.ts L10–24 · /attention · e2adc9a3c325；aida-agent · packages/agent/src/gateway/work-attention.ts L74–76 · ATTENTION_CANDIDATE_LIMIT · e2adc9a3c325；aida-agent · packages/agent/src/gateway/api-runs.ts L216–250 · work-stop · e2adc9a3c325；aida-agent · packages/agent/src/session/run-store.ts L1785–1820 · listBackgroundByConversation · e2adc9a3c325
• 未核：指标在各环境是否被采集 / 告警；Desktop 是否已接 attention 接口（本钉点 Desktop 源码未见调用）。

合同 fixture、观察重试、Pack 发布门与超长消息回执（钉点 e2adc9a3c325 / 8eecd12081db）

• work-attention-v1 fixture：fixtures/desktop-contract/work-attention-v1.json 归 Agent 所有，写明 GET /api/work/attention 的字段、示例和反例（轮询快照、无 SSE 补读、HMAC 游标 5 分钟、变化 409、stop 只在可控前台 root 上），Agent 合同测试按生产 schema 校验；Desktop 消费 / 镜像和 SSE 补读是后续工作。
• Work 观察超时可重试（89c9bdad3）：chat 流观察原 Work 出错时，只有 RUNTIME_WORK_READ_TIMEOUT 标 retryable: true——读预算耗尽不代表 run 失败，run 继续执行；绑定 / 授权失败仍是终局。
• Pack 发布门 / readyz packs：同一检查跑在部署前脚本（exit 1 阻断）、服务内 readyz（后台刷新）、部署后逐租户冒烟；1d07cf06a 起包含没有订阅行、隐式跟随默认 Pack 的租户。单租户失败 → degraded，全部失败 → unavailable，读不到订阅 → unreachable。
• Desktop 超长消息回执（9fdc200c）：Main 只在 400 响应体完整符合 RUNTIME_WORK_MESSAGE_TOO_LONG 合同、且本条消息确实超长时，才生成绑定原 POST 的拒绝回执；只看状态码或错误码前缀不算。
• 证据：aida-agent · fixtures/desktop-contract/work-attention-v1.json L1–23 · work-attention-v1 · e2adc9a3c325；aida-agent · fixtures/desktop-contract/README.md L5–8 · work-attention-v1.json · e2adc9a3c325；aida-agent · packages/agent/src/gateway/chat-routes.ts L172–180 · observationErrorRetryable · e2adc9a3c325；aida-agent · packages/agent/src/gateway/chat-routes.ts L1298–1304 · observationErrorRetryable · e2adc9a3c325；aida-agent · packages/agent/src/config/services/pack-release-gate.ts L1–12 · readyz · e2adc9a3c325；aida-agent · packages/agent/src/config/services/pack-release-gate.ts L130–153 · checkAllTenantPacks · e2adc9a3c325；aida-desktop · apps/desktop/electron/agent-loop/runtime-execution-client.ts L73–98 · messageAdmissionRejectionSchema · 4346d79eb364；aida-desktop · apps/desktop/shared/runtime-work-admission-rejection.ts L3–18 · RUNTIME_WORK_MESSAGE_TOO_LONG · 4346d79eb364

readyz：工具契约漂移（2026-10-14 钉点）

ToolContractMonitor 在启动与周期性比对代码声明的后端工具需求与后端 listTools 实际清单；钉点 e2adc9a3c325 起还用进程已加载的工具 schema 比对参数契约（TOOL_ARGUMENT_CONTRACTS：Agent 会发而后端没有的参数、后端必填而 Agent 不发的参数，只报会导致调用失败的差异；未配置后端的域跳过）。结果以 toolContracts（missing + argumentDrift）出现在 readyz；任一漂移只把状态置 degraded、readyz 仍为 200；任一漂移集合变化时发高严重度审计与错误日志，用户指引标注“暂不可用”。

视图

• main — 诊断码 → 产出面 → DB/本机落点 → 排障入口。
• runs-stream — 只读 GET /api/runs/:runId/stream：鉴权、账本重放、增量轮询与中断收尾。

归属边与非目标

• Owner：各码的产出模块（Gateway / UnifiedEntry / PluginHost / Main / Boot）。
• 非目标：不替代完整错误码表（见 desktop-runtime）；不做日志平台接入设计。
• 相关：enterprise-task-e2e、state-authority、storage-planes、vertical-plugin-mount、trust-boundaries、time-bounds。

证据与范围

• aida-agent · packages/agent/src/gateway/chat-routes.ts L520–524 · desktopPayloadVersionUnsupported · e2adc9a3c325
• aida-agent · packages/agent/src/gateway/api-conversation-interactions.ts L465–495 · interaction_protocol_upgrade_required · e2adc9a3c325
• aida-agent · packages/agent/src/gateway/chat-routes.ts L381–421 · RUNTIME_EXECUTION_PROTOCOL_UNSUPPORTED · e2adc9a3c325
• aida-agent · packages/agent/src/gateway/unified-entry.ts L2660–2682 · RUN_LEASE_LOST · e2adc9a3c325
• aida-agent · packages/agent/src/gateway/unified-entry.ts L1948–1978 · RUN_LEASE_BUSY · e2adc9a3c325
• aida-desktop · apps/desktop/electron/local-files-v4/write-state-persistence.ts L730–746 · LOCAL_FILE_WRITE_STATE_LEGACY_DROPPED · 4346d79eb364
• aida-agent · packages/agent/src/config/schema-identity.ts L661–701 · assertCurrentConfigSchema · e2adc9a3c325
• aida-agent · packages/agent/src/connectors/tool-contract-monitor.ts L1–16 · readyz · e2adc9a3c325
• aida-agent · packages/agent/src/connectors/tool-contract-monitor.ts L229–251 · argumentDrift · e2adc9a3c325
• aida-agent · packages/agent/src/connectors/tool-argument-contracts.ts L192–219 · evaluateToolArgumentContracts · e2adc9a3c325

结论来自固定版本的静态源码与合同阅读；实现存在、默认开关和生产启用分别判断。本站代码证据面板列出声明状态与具体限制。

• aida-agent · packages/agent/src/gateway/chat-work-sse-response.ts L27–41 · projectRouteDecisionEvent · e2adc9a3c325
• aida-agent · packages/agent/src/gateway/chat-work-sse-response.ts L127–132 · SERVER_DRAINING · e2adc9a3c325
• aida-agent · packages/agent/src/runtime/execution/run-execution-storage.ts L952–968 · decideOwnerLostRecovery · e2adc9a3c325
• aida-desktop · apps/desktop/src/chat/core/runTimeline.ts L444–453 · run_recovering · 4346d79eb364

Desktop 轨迹采集更新（2026-10-29）

Main captureIdentity 要求 isDeveloper() 与 isPanelVisible() 同时成立；prepareSubmission 以 clientRequestId 去重并限制诊断等待，诊断失败不创造 Run 失败。invalidate 增加 epoch、清除当前采集身份并停止交付。证据：aida-desktop · apps/desktop/electron/trajectory/desktop-trajectory-controller.ts L100–105 / L81–134 · 4346d79eb364。这是代码静态复核，不代表真机采集验收。

Runtime 提交 wire 与原 Work identity

chat POST 的 Runtime 提交门接受缺省/空值（无 policy）、runtime-work-v1（无 policy），以及 runtime-work-skill-v2 且携带合法 skillExecutionPolicy；其他非空头为 RUNTIME_EXECUTION_PROTOCOL_UNSUPPORTED，头与 policy 不匹配为 RUNTIME_WORK_SKILL_POLICY_MISMATCH，均返回 426。原 Work binding 仍是 runtime-work-v1；取消提交、补充材料等路由单独判定，见协议地图。

证据：提交门 与 实际 chat POST 调用。