# 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` 不得无条件重放。

映射表：

- [码格式](docs/code-format.md)
- [注册治理](docs/governance.md)
- [agent-native](docs/agent-native-mapping.md)
- [agent-squad](docs/agent-squad-mapping.md)
- [agent-intent](docs/agent-intent-mapping.md)
- [和日志系统对齐](docs/integration.md)

## 进程内用法

```go
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 信封

```json
{"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

```bash
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。

## 自定义域

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

## 开发

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

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

```bash
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`