# 错误码格式

规范码只有一种形式：`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。不得当成成功。