# 错误码、日志与 trace_id

错误码仓库与日志仓库互不导入。对齐方式、调用顺序和查询命令见同级仓库 Logging-System 的 `docs/integration.md`。两个仓库需要放在同级目录时，可运行示例是 `Logging-System/examples/trace`。

本地副本要点：

1. HTTP 层回显 `X-Trace-Id`（`httpx.Trace`）。
2. 用 `errcode.Wrap` 带上规范码；未知码回落 `sys.unknown_code`。
3. `httpx.WriteError` 的信封带 `code` 和 `trace_id`。
4. 同一 context 上的日志会带同一个 `trace_id`。若错误实现了 `ErrorCode()` / `ErrorFields()`，日志条目同时带上码和字段。
5. 用 `trace_id` 到采集器查这一次调用，用 `code` 查同一类失败。

副作用为 `possible` 或 `unknown` 的码禁止无条件重放。agent-native 与 agent-squad 的现有字符串如何落到规范码，见 [agent-native-mapping.md](agent-native-mapping.md) 与 [agent-squad-mapping.md](agent-squad-mapping.md)。