错误分类与修复

概览

daemon 的失败模式刻意做成封闭联合，SDK 消费方可以穷举 switch、路由 handler 给出一致 HTTP 响应。本文按三层列每个 typed 错误：

1. packages/cli/src/serve/ —— HTTP 边界（auth、workspace 文件系统、daemon-host preflight）。
2. packages/acp-bridge/ —— bridge / mediator（daemon ↔ ACP child 缝隙）。
3. packages/sdk-typescript/src/daemon/ —— SDK 侧包装与结构化错误字段。

Wire 错误形状在 ../qwen-serve-protocol.md；本文加 cause-and-remediation 视角。

文件系统边界（packages/cli/src/serve/fs/errors.ts）

FsError 带 { kind, message, status, cause? }。FsErrorKind 联合（14 种，默认 HTTP 状态）：

io_error 与 permission_denied 严格区分是刻意的，监控按 errorKind 路由 —— 把 ENOSPC 折进 permission_denied 会让 df -h 问题误叫安全 oncall。

Bridge 错误（packages/acp-bridge/src/bridgeErrors.ts）

bridge / mediator 抛的 typed class，多数路由 handler 通过 switch 给出 HTTP 状态。

Boot 时配置错误（packages/cli/src/serve/runQwenServe.ts）

Device Flow auth（packages/cli/src/serve/auth/deviceFlow.ts）

Daemon-host 错误 kind（packages/cli/src/serve/status.ts）

DaemonErrorKind 枚举，给 GET /workspace/preflight 单元在 daemon-host check 失败时用：

通过 preflight cell 的 errorKind 暴露，让客户端 UI 渲染结构化修复（而不是裸 stack trace）。

Auth 错误形状

完整 auth 模型见 12-auth-security.md。

权限结果（wire-vs-audit 重载）

PermissionResolution 两种终态：

• {kind: 'option', optionId} — 投票胜。
• {kind: 'cancelled', reason: 'timeout' \| 'session_closed' \| 'agent_cancelled'} — 被取消。wire 形状是单一 {outcome: 'cancelled'}；审计日志通过 decisionReason.type 区分 timeout / session_closed / voter-cancelled / agent-cancelled。这种重载是为了不破坏 permission.ts 冻结契约而刻意保留。

SDK 侧错误包装

DaemonClient 把 HTTP 错误转成 rejected Promise，rejection value 是解析后的 body。命中 404 unknown session 的方法 reject {error, sessionId}；SDK 当下没把它们包成 typed class（不鼓励调用方 instanceof Error + .message.includes(...)，改成 switch body 的 err.code / err.kind）。

parseSseStream 16 MiB 缓冲溢出时中断 iterator（防御性边界）。

流程

把错误浮给用户

flowchart LR
    A[HTTP 4xx/5xx body] --> B["switch on body.code OR errorKind"]
    B --> C["Render remediation per this doc's table"]
    B --> D["fallback: render body.error as toast"]

区分 auth 失败

flowchart TD
    A["401 received"] --> B{"body.code == 'token_required'?"}
    B -->|yes| C["mutation-gate strict — guide user to --token / --require-auth"]
    B -->|no| D["plain Unauthorized — generic 'check token' UI"]

依赖

• 所有错误类从各自包导出；SDK 消费方在同一 Node 进程里可以对 bridgeErrors.ts 类型用 instanceof。跨 wire 改用 body.code / body.kind / body.errorKind 路由。

注意 & 已知局限

• io_error 与 permission_denied 严格区分是刻意的，不要混。
• PermissionForbiddenError 的 reason（designated_mismatch / remote_not_allowed） 在 designated 和 consensus 之间重载；审计精确区分，wire 不区分。
• CancelSentinelCollisionError 指示 agent 侧 bug，不是安全事件 —— bridge 拒掉请求而不是让哨兵默默匹到真实 option。
• SDK 侧 typed error 仍在演进。调用方应当 route on body 字段，而不是依赖 wire 上的 JS 类身份。
• internal_error 必须查。它表示 FsError 构造时用了为非 errno 路径预留的 kind（程序员错），响应 body 的 cause 字段可能带原 throw。

参考

• packages/cli/src/serve/fs/errors.ts（FsErrorKind、FsErrorStatus）
• packages/acp-bridge/src/bridgeErrors.ts（所有 typed class）
• packages/cli/src/serve/status.ts（DaemonErrorKind）
• packages/cli/src/serve/auth.ts（auth body）
• wire 参考：../qwen-serve-protocol.md。