From 083085729265421c1eba8ba0adb2d979664f6862 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Sat, 11 Jul 2026 23:11:25 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=86=BB=E7=BB=93=E8=AF=8A=E6=96=AD=20?=
 =?UTF-8?q?trace=20=E8=B7=A8=E4=BB=93=E5=90=88=E5=90=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../R1.1_Task_Report.md                       | 39 +++++++++++++++++++
 .../MDTODO/observability-trace-reliability.md |  6 +--
 2 files changed, 42 insertions(+), 3 deletions(-)
 create mode 100644 docs/MDTODO/details/observability-trace-reliability/R1.1_Task_Report.md

diff --git a/docs/MDTODO/details/observability-trace-reliability/R1.1_Task_Report.md b/docs/MDTODO/details/observability-trace-reliability/R1.1_Task_Report.md
new file mode 100644
index 00000000..7fbb647b
--- /dev/null
+++ b/docs/MDTODO/details/observability-trace-reliability/R1.1_Task_Report.md
@@ -0,0 +1,39 @@
+# R1.1 任务报告
+
+## 结论
+
+- 业务 trace：
+  - 只承载原业务执行 span。
+- diagnostic trace：
+  - 使用独立 traceId；
+  - 通过标准 OTLP Span Link 引用目标业务 trace；
+  - 保留有界关联字段。
+- 禁止路径：
+  - 过滤新增 span；
+  - 关闭 OTel；
+  - 绕过正式 result/events authority；
+  - 修改 Kafka/SSE 链路。
+
+## 固定证据
+
+- 父问题：[UniDesk #1801](https://github.com/pikasTech/unidesk/issues/1801)。
+- 单步调查：[UniDesk #1805](https://github.com/pikasTech/unidesk/issues/1805#issuecomment-4948764852)。
+- AgentRun 实现问题：[AgentRun #302](https://github.com/pikasTech/agentrun/issues/302)。
+- 固定 OTel trace：`de11d47d1bab0ca4d3f6259279f3a332`。
+- 一次诊断后：
+  - span 总数 `375 -> 376`；
+  - `command_result 3 -> 4`；
+  - 证明诊断读取污染了业务 trace。
+
+## 实现边界
+
+- AgentRun：
+  - 接收 request-scoped diagnostic context；
+  - 生成独立 diagnostic trace；
+  - 为 result/events 等读取 span 写入标准 link/correlation。
+- UniDesk：
+  - 生成并注入 diagnostic context；
+  - 展示关联与重复诊断不变性。
+- 保持项：
+  - 普通产品读取维持现有业务语义；
+  - 纯 Kafka + SSE 实时与刷新路径不变。
diff --git a/docs/MDTODO/observability-trace-reliability.md b/docs/MDTODO/observability-trace-reliability.md
index 55b532b0..e04bd969 100644
--- a/docs/MDTODO/observability-trace-reliability.md
+++ b/docs/MDTODO/observability-trace-reliability.md
@@ -7,13 +7,13 @@
 
 解决 [UniDesk #1801](https://github.com/pikasTech/unidesk/issues/1801)：隔离业务 trace 与 diagnostic trace，使诊断读取保持可观测但不再向被诊断业务 trace 补记 span；不得通过静默过滤隐藏真实 span，不改变已验收的纯 Kafka + SSE 实时/刷新链路，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1_Task_Report.md)。
 
-### R1.1 [in_progress]
+### R1.1 [completed]
 
 冻结 [#1801](https://github.com/pikasTech/unidesk/issues/1801) 的 trace-context 合同：业务 trace 只承载原业务执行证据，diagnostic trace 使用独立 traceId，并通过 OTel Span Link 和明确关联字段引用目标 trace；定义跨 UniDesk/AgentRun 的 propagation、采样、错误和兼容边界，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.1_Task_Report.md)。
 
-### R1.2
+### R1.2 [in_progress]
 
-依赖 R1.1，修改诊断入口与相关 instrumentation，使 command/result/events 读取不继承目标业务 trace 的 active parent，同时保留独立诊断 trace、Span Link、businessTraceId/commandId 关联和有界 CLI 可见性；禁止新增 terminal authority 或 Kafka event，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.2_Task_Report.md)。
+依赖 R1.1，执行 [AgentRun #302](https://github.com/pikasTech/agentrun/issues/302) 与 [UniDesk #1805](https://github.com/pikasTech/unidesk/issues/1805)：修改 request-scoped diagnostic context 与相关 instrumentation，使 command/result/events 读取不继承目标业务 trace 的 active parent，同时保留独立诊断 trace、Span Link、businessTraceId/commandId 关联和有界 CLI 可见性；禁止新增 terminal authority 或 Kafka event，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.2_Task_Report.md)。
 
 ### R1.3