Logging-System/docs/integration.md

错误码、日志与 trace_id

两个库互不导入。错误码库负责稳定的码和 HTTP 信封，日志库负责把同一次调用的运行记录留下来。对齐点只有两个：

• 追踪头都是 X-Trace-Id
• 日志通过 ErrorCode() / ErrorFields() 识别错误，不需要 import error-code-system

一次失败怎么串起来

HTTP 中间件生成或沿用 X-Trace-Id
        │
        ▼
errcode.Wrap(...) 得到规范码
        │
        ├─ httpx.WriteError  →  {"error":{"code","message","reason","trace_id"}}
        │
        └─ log.WithContext(ctx).Error(msg, err)
                 │
                 ▼
           日志条目含 trace_id + code + 字段
                 │
                 ▼
           HTTP sink 批量 POST 到 :8092
                 │
                 ▼
           GET /v1/logs?trace_id=... 或 ?q=agent.provider_unavailable

查问题先拿响应里的 trace_id 或 code。trace_id 能拉出这一次调用的全部日志；code 能跨请求看同一类失败。副作用是 possible 或 unknown 的码不要无条件重放，先看日志里这次执行写过什么。

最小示例

可运行副本：Logging-System/examples/trace（需要两个仓库是同级目录）。

reg := errcode.NewRegistry()
domains.RegisterAll(reg)

cfg, _ := config.Load("log.json") // 见 Logging-System/docs/example.json
log, _ := config.Build(cfg)
defer log.Close()

ctx := logsys.WithTrace(r.Context(), httpx.TraceID(r))
err := errcode.Wrap(cause, errcode.AgentProviderUnavailable, "模型不可达", "model", "glm-4")
log.WithContext(ctx).Error("provider down", err)

httpx.WriteError(reg, w, r, err)

日志条目里会有 trace_id=... 和 code=agent.provider_unavailable。采集器侧：

logctl query --addr http://127.0.0.1:8092 --trace <响应里的 trace_id>

接入现有仓库时

本轮不改 Agent-Native / Agent-Squad。对应关系已经写在错误码仓库：

• docs/agent-native-mapping.md
• docs/agent-squad-mapping.md

接入时保持现有事件名和 AssessStepFailure 分类，只把对外的错误字符串换成规范码，并把 run_id 写入日志字段。run_id 回答「哪一次编排」，trace_id 回答「哪一次请求」，两者都保留。