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>
33 lines
1.9 KiB
Markdown
33 lines
1.9 KiB
Markdown
# 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`：
|
||
|
||
```text
|
||
squad.step_failed
|
||
└─ agent.missing_deliverable
|
||
└─ 原始执行错误
|
||
```
|
||
|
||
这样查 `squad.step_failed` 能看到编排后果，查 `agent.missing_deliverable` 能看到执行根因。
|