From b67696d393e7abfbdd16fdde1064c07f5ecd2f72 Mon Sep 17 00:00:00 2001
From: weichen <weichen@local>
Date: Tue, 29 Sep 2026 13:51:57 +0000
Subject: [PATCH] Document how error codes line up with trace ids in the
 logging system.

Callers can follow one request from the HTTP envelope into the log collector without coupling the two modules.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md           |  1 +
 docs/integration.md | 13 +++++++++++++
 2 files changed, 14 insertions(+)
 create mode 100644 docs/integration.md

diff --git a/README.md b/README.md
index ddaf73e..e0a6794 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@
 - [注册治理](docs/governance.md)
 - [agent-native](docs/agent-native-mapping.md)
 - [agent-squad](docs/agent-squad-mapping.md)
+- [和日志系统对齐](docs/integration.md)
 
 ## 进程内用法
 
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..8d5789b
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,13 @@
+# 错误码、日志与 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)。