weichen/Error-Code-System

Fork 0

Files

T

weichen f55c6b11b6

ci / docker-checkout-hostgateway (pull_request) Successful in 1s

Details

ci / vet-and-test (pull_request) Successful in 7s

Details

Adopt credential safe CI and retire replaced source gitlinks

Why:
Make independent version consumption work from ordinary clones while retaining historical commits and existing branch workspaces.

Evidence:
SELF Dev task receipts record 24 CI boundary cases, all workflow syntax checks, readonly private-source prefetch in clean exports, provider tests and package installation without acquisition scripts. Platform CI remains pending.

Impact:
Remove only replaced index links, preserve old physical checkouts, and update dependency guidance. Library consumers retain their immutable versions until an explicit dependency update.

Refs:
Agent-System-Dev feature/dependency-workspace; approved versioned-dependency r1, U3-U7 and R15.

2026-10-13 17:11:42 +00:00

4.0 KiB

Raw Blame History

Error-Code-System

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

本仓库是该模块的源码位置。Go 模块路径为 git-ssh.u1680832.nyat.app/weichen/Error-Code-System.git。不依赖 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

依赖本仓库

消费方使用模块 git-ssh.u1680832.nyat.app/weichen/Error-Code-System.git，由 Go 生成可获取的提交版本：

go get git-ssh.u1680832.nyat.app/weichen/Error-Code-System.git@<已审核提交>
GOWORK=off go test -mod=readonly ./...

go.mod 决定实际版本，go.sum 校验内容。私有获取通过 Dev 登记的进程级传输配置，不修改全局 Git 配置。源码联调用本地工作区覆盖，正式消费没有源码目录 replace；旧提交继续按其原固定组合构建。

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

4.0 KiB Raw Blame History