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.5 KiB
1.5 KiB
错误码格式
规范码只有一种形式：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。不得当成成功。