Error-Code-System

跨系统共用的错误码目录、进程内错误类型，以及可独立部署的查询服务。目标是让失败能够按稳定码定位，而不是依赖各服务自己拼接的错误文本。

本仓库是该模块的源码位置。Go 模块路径为 error-code-system。不依赖 Agent-Native、Agent-Squad 或任何第三方模块。

分层

包	职责	依赖边界
errcode	码格式、定义、注册表、E 错误类型	只依赖标准库
domains	sys / agent / squad 种子码；Go 为权威，JSON 为导出快照	只依赖 errcode
httpx	统一错误信封与 X-Trace-Id	只依赖 errcode
server	HTTP API，默认 :8091	组合根之一
cli	errcode 命令	组合根之一
conformance	种子目录治理验收（格式、唯一、别名、未知码回落）	只用公开 API

码

规范码形如 agent.provider_unavailable。历史字符串（provider_unavailable、TIMEOUT、MISSING_TARGET）登记为别名，解析后回到规范码。未知码 fail-closed，回落 sys.unknown_code（HTTP 500，禁止当成功，禁止无条件重放）。

每条码带有 HTTP 状态、严重级别、默认重试策略、副作用（none / possible / unknown）和中文处置建议。副作用语义与 agent-native 契约一致：possible 与 unknown 不得无条件重放。

映射表：

• 码格式
• 注册治理
• agent-native
• agent-squad
• 和日志系统对齐

进程内用法

err := errcode.Wrap(cause, errcode.AgentProviderUnavailable, "模型不可达", "model", "glm-4")
def := errcode.Default.Resolve(err.ErrorCode()) // 需先导入 error-code-system/domains

E 实现 Unwrap，可用 errors.Is 按码匹配，也可 JSON 传到另一个进程。日志系统若看到 ErrorCode() / ErrorFields() 两个方法，即可把码和字段写入日志，而无需依赖本模块。

HTTP 信封

{"error":{"code":"agent.provider_unavailable","message":"模型提供方不可用","reason":"模型不可达","trace_id":"..."}}

X-Trace-Id 由调用方传入时原样回显；缺失或含空白等非法字符时由中间件生成。用这个标识到日志系统检索同一次请求。

HTTP API

方法/路径	说明
GET /v1/health	健康检查
GET /v1/codes?domain=&q=	列表；q 匹配码、摘要、建议、别名
GET /v1/codes/{code}	规范码或别名；未知返回 sys.not_found
POST /v1/validate	正文 {"code":"..."} 或 {"codes":[...]}，未知回落并标 known:false
GET /v1/export?domain=	导出 JSON

CLI

go build -o bin/errcode .
./bin/errcode list --domain agent
./bin/errcode show TIMEOUT
./bin/errcode search 交付物
./bin/errcode validate provider_unavailable
./bin/errcode export --domain squad
./bin/errcode serve --addr :8091

validate 在码未登记时退出码为 1。

自定义域

reg := errcode.NewRegistry()
domains.RegisterAll(reg)
if err := reg.LoadJSON(data); err != nil { /* 本批回滚 */ }

开发

go vet ./...
go test -count=1 ./...

改种子码后重写导出快照：

WRITE_CATALOG=1 go test ./domains -run TestWriteCatalog -count=1

依赖本仓库

require error-code-system v0.0.0

replace error-code-system => ../Error-Code-System

远程：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Error-Code-System.git