weichen
00384d807f
Why: the r1 attempt ended failed-unknown (invalid terminal record); fail-stop requires reconciliation before a fresh attempt. Evidence: receipt /tmp/gov-receipt-Error-Code-System-r1.json; worktree clean, no transport ref (SELF). Impact: task card only. Refs: .task/feature-governance-adoption.md
Error-Code-System
跨系统共用的错误码目录、进程内错误类型，以及可独立部署的查询服务。目标是让失败能够按稳定码定位，而不是依赖各服务自己拼接的错误文本。
本仓库是该模块的源码位置。Go 模块路径为 error-code-system。不依赖 Agent-Native、Agent-Squad 或任何第三方模块。
分层
| 包 | 职责 | 依赖边界 |
|---|---|---|
| errcode | 码格式、定义、注册表、E 错误类型 |
只依赖标准库 |
| domains | sys / agent / squad / intent 种子码；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 不得无条件重放。
映射表：
进程内用法
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
依赖本仓库
消费方把本库固定为 submodule，推荐路径 deps/error-code-system。版本以消费方 gitlink 为准，不执行 submodule update --remote。
require error-code-system v0.0.0
replace error-code-system => ./deps/error-code-system
并列检出、还没放进 deps/ 时，也可以暂时写 replace error-code-system => ../Error-Code-System。本库不导入 Agent-Native、Agent-Squad 或日志库。若消费方同时依赖 Agent-Native，而 Agent-Native 的 deps/ 里还有一份本库，编译时只认消费方自己的 replace；两份 gitlink 必须相同。
远程：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Error-Code-System.git