weichenandCursor
bd53e9ba79
Services can resolve legacy aliases and expose the catalog over CLI and HTTP instead of ad-hoc error strings. Co-authored-by: Cursor <cursoragent@cursor.com>
1.9 KiB
1.9 KiB
agent-squad 错误码映射
本轮不修改 Agent-Squad。当前 HTTP 层只有 {"error":"<文本>"}（server.writeErr），没有稳定码，也没有 trace。接入时把下表套进响应信封，正文理由仍放在 reason。
| 现状 | 规范码 | HTTP | 说明 |
|---|---|---|---|
role %s not found |
squad.role_not_found | 404 | handleDeleteRole 等 |
blueprint %s not found |
squad.blueprint_not_found | 404 | 蓝图删除 |
| Inspect / 黑板找不到运行 | squad.run_not_found | 404 | 磁盘为权威，重启后仍可能存在 |
goal.text is required |
squad.goal_required | 400 | 创建运行 |
运行处于 HITL 挂起（RunStatus.IsHeld） |
squad.hitl_pending | 409 | 用 respond 续跑，不要并发再 Run |
| 计划确认 abort / 质检前的计划拒绝 | squad.plan_rejected | 422 | confirmation 挂起点拒绝 |
| 未知 backend，fail-closed | squad.unknown_backend | 400 | 禁止回落 stub |
步骤 EvStepFailed |
squad.step_failed | 500 | 瞬时失败仍受步骤重试上限约束 |
| 质检失败且自动修复预算用尽 | squad.quality_failed | 422 | 可转 quality_review 人工放行 |
context cancelled |
squad.cancelled | 499 | 步骤保持 pending，可恢复 |
| JSON 解码失败 | sys.invalid_argument | 400 | 框架域，不单开小队码 |
| 未分类的 500 | sys.internal | 500 | 必须带 trace_id |
事件名（step_failed、run_failed 等）保持不变。事件文本里建议追加 code 字段，便于和日志系统的 trace_id 对齐。脱敏仍沿用现有 Redact，日志系统提供同形实现。
与执行错误的边界
步骤失败的根因优先用 agent 域码（例如 agent.missing_deliverable），小队只在编排层再包一层 squad.step_failed：
squad.step_failed
└─ agent.missing_deliverable
└─ 原始执行错误
这样查 squad.step_failed 能看到编排后果，查 agent.missing_deliverable 能看到执行根因。