Add a shared error-code catalog so failures can be traced by stable codes.

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>

docs/code-format.md

@@ -0,0 +1,34 @@
+# 错误码格式
+
+规范码只有一种形式：`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。不得当成成功。