2.1 KiB
2.1 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,可恢复 |
意图闸门守卫命中(squadintent 适配器,运行入口拒绝) |
squad.intent_refused | 400 | 守卫"识别即拒绝";按引导改写目标,不重试原文本 |
| 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 能看到执行根因。