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>
35 lines
1.5 KiB
Markdown
35 lines
1.5 KiB
Markdown
# 错误码格式
|
||
|
||
规范码只有一种形式：`domain.mnemonic`。
|
||
|
||
| 部分 | 规则 | 例子 |
|
||
|---|---|---|
|
||
| domain | 2–32 字符，小写字母开头，仅含小写字母、数字、连字符 | `sys`、`agent`、`squad` |
|
||
| mnemonic | 2–64 字符，小写字母开头，仅含小写字母、数字、下划线 | `provider_unavailable` |
|
||
|
||
正则：`^[a-z][a-z0-9-]{1,31}\.[a-z][a-z0-9_]{1,63}$`
|
||
|
||
## 别名
|
||
|
||
历史码不是第二套规范码。它们登记为别名，解析后必须回到规范码：
|
||
|
||
- agent-native `contract.ErrorCode`：`provider_unavailable` → `agent.provider_unavailable`
|
||
- pitransport：`PROMPT_EMPTY` → `agent.prompt_empty`，`CANCELLED` → `agent.canceled`，`MISSING_TARGET` → `agent.missing_deliverable`
|
||
|
||
别名匹配大小写敏感，格式为 `^[A-Za-z][A-Za-z0-9_-]{1,63}$`。
|
||
|
||
## 元数据
|
||
|
||
每条码必须同时声明：
|
||
|
||
| 字段 | 取值 | 用途 |
|
||
|---|---|---|
|
||
| http | 100–599 | HTTP 接口的默认状态码。取消使用 499（客户端关闭） |
|
||
| severity | info / warn / error / fatal | 日志与告警 |
|
||
| retry | never / transient / always | 默认重试策略。实例仍可另附是否重试 |
|
||
| side_effects | none / possible / unknown | 对齐 agent-native：possible 与 unknown 禁止无条件重放 |
|
||
| summary | 非空中文 | 给调用方的稳定摘要 |
|
||
| hint | 非空中文 | 处置建议，方便值班定位 |
|
||
|
||
未知码 `Resolve` 到 `sys.unknown_code`，HTTP 500，retry=never，side_effects=unknown。不得当成成功。
|