# 可观测性与 Trace 可靠性 MDTODO

范围：长期跟踪跨服务 OTel trace context、业务 trace 与诊断 trace 隔离、Span Link、诊断重复性和 trace 证据稳定性。单个故障或 GitHub issue 作为 MDTODO ITEM 进入本文件，不为一次性 trace 或根因新建 MDTODO FILE。


## R1 [in_progress]

解决 [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 [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 [in_progress]

依赖 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

依赖 R1.2，用固定 warm-session trace 验证重复诊断不改变原业务 trace 的 terminal/instrumentation 判定，诊断 trace 仍完整可查；补跨服务合同和端到端验收，确认实时、刷新回放及纯 Kafka + SSE 事件顺序均无变化，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.3_Task_Report.md)。