weichen
acd34769bf
Why: the Gitea server moved to https://gitea.naitangbaobao.cn with SSH on port 52222; endpoint references must follow or superproject CI checkout refuses the old URLs. Evidence: host-verified API reach and SSH auth (Dev task card fix/gitea-endpoint-migration) Impact: configuration only; no runtime behavior change. Refs: Dev PR #706
108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
# 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@gitea.naitangbaobao.cn:52222/weichen/Error-Code-System.git`
|