18 · 错误码与诊断
当前实现以 thiserror 变体 + 文本消息为主，尚未统一数字错误码。
本表是发布前的稳定化约定；新增变体必须登记。
18.1 CLI 退出码
| 退出码 |
含义 |
| 0 |
成功 |
| 1 |
参数/编译/运行/网络错误 |
| 2（建议） |
保留给“用户取消/超时” |
18.2 核心（ain-core）
| 变体/前缀 |
场景 |
处理 |
invalid net: |
端口/线/ID/规则模板非法 |
修复 JSON/规则 |
no interaction rule for |
活跃对没有规则（stuck） |
补规则或改为正常数据 cell |
unknown agent |
未注册 agent |
在 agents 声明 |
agent ... arity |
端口越界 |
检查 arity |
fuel exhausted |
step/fuel 上限 |
调大 fuel 或检查循环 |
json error |
反序列化失败 |
检查 schema/version |
18.3 运行时（ain-runtime）
| 变体/前缀 |
场景 |
unknown behavior |
FlowSpec kind 未注册 |
unknown edge target / unknown agent |
edge/input 指向不存在 agent |
duplicate agent id |
FlowSpec agent id 重复 |
unsupported flow version |
FlowSpec major 不兼容 |
budget exceeded |
usd/tokens 超预算 |
step limit reached |
steps 超上限 |
agent ... did not declare effect |
调用了未声明的 effect |
protocol violation on |
edge protocol tag 不匹配 |
effect ... failed |
provider/HTTP/shell 失败 |
replay mismatch |
trace/effect cursor/hash 不一致 |
json error |
FlowSpec/trace 解析失败 |
18.4 调度（ain-sched）
| 变体 |
场景 |
no worker nodes configured |
--nodes 为空 |
worker ...: ... |
连接/超时/协议错误 |
remote error from ... |
worker 返回 error（含 unauthorized） |
18.5 集群（ain-cluster）
| 变体 |
场景 |
no live nodes |
所有节点 dead |
unknown cell / unknown node |
placement/路由缺失 |
transport: |
TCP 连接/超时/重置 |
remote: |
worker 返回 error（capability/unknown behavior 等） |
backpressure: |
coordinator 队列达到上限 |
effect ledger: |
ledger 读写/解析失败（--effect-ledger） |
remote: effect \x` failed` |
coordinator 执行 effect 失败 |
18.6 诊断约定
- 语言层（ain-lang）已有
severity[code] line:col: message + caret。
- 运行时/集群建议后续统一为
E-<layer>-<nn> 数字码；在此之前按文本前缀搜索。
- 任何 P0 错误必须附带最小复现（FlowSpec/trace/命令）。
在 GitHub 编辑本文