DeepSeek Harness 全景可观测实践：双路线破局 AI 编码 Agent 追踪难题

当 AI 编码 Agent 真正跑起任务后，问题的焦点往往从「它有没有完成」转移到更深层的执行细节：这一轮为什么花了 47 秒？时间究竟卡在模型推理还是工具调用？失败后系统重试了几次？Token 消耗是来自主 Agent 还是 Subagent？这些看似简单的问题，实际上需要完整的可观测性数据才能准确回答。

日志与 Trace：解决不同层面的问题

DeepSeek Harness（以下简称 DSH）是 DeepSeek 开源的编码 Agent 运行时，负责维护会话、组织 ReAct 循环、执行工具调用、管理权限与沙箱，并在需要时派生 Subagent。DSH 以 npm 包形式分发，提供 Web 和 headless 两种 Profile 模板。值得注意的是，DSH 本身已保存完整的 append-only Session 事件流，包含 Turn、Step、工具调用、模型消息和流式增量，甚至还提供了默认关闭的 OTLP Logs 插件。然而，这些日志解决的是「发生了什么」的问题，要回答耗时、调用关系和成本问题，还需要将事件组织成 Trace 和 Metrics。

路线 A：独立插件实现轻量直连

日志是一串按时间排列的事实，记录了系统发生的每一个事件；Trace 则是一棵带父子关系和时间区间的调用树，提供了结构化的性能视角。仅有日志时，我们只能事后回溯「发生了什么」；而有了 Trace，就能更直接地回答：一轮任务的总耗时如何分布在模型、工具和等待的不同阶段；哪次工具调用失败以及它属于哪个推理步骤；同一个 Step 是否触发了模型重试；每次模型调用的 TTFT、输入/输出/缓存 Token 分别是多少；主 Agent 与 Subagent 之间的执行和成本关系如何；多轮会话、多个模型乃至多个 Agent 的整体使用情况。因此，Logs 与 Trace 不是非此即彼的选择，而是互补的关系：日志保留完整的事件账本，Trace 提供适合性能分析、错误追踪和成本分摊的结构化投影。

路线 B：Pilot 统一多 Agent 观测体系

第一条路线是通过独立插件 @loongsuite/dsh-plugin 实现。该插件已发布正式版，被 DSH 社区插件市场收录，可直接从插件市场安装。安装过程非常简洁，只需通过 `dsh plugin --profile web add @loongsuite/dsh-plugin` 命令即可完成。插件直接监听 DSH 的 Session、Turn、Step、llm/stream 和 Tool 生命周期，在进程内构建 ENTRY → AGENT → STEP → LLM / TOOL 调用树。每次真实模型调用都对应独立的 LLM Span，这意味着同一 Step 中的失败与重试不会被合并，能够完整还原执行过程。配置方面，只需设置标准的 OTEL_SERVICE_NAME 和 OTEL_EXPORTER_OTLP_ENDPOINT 即可。该插件支持接入多种后端，包括 Langfuse、云监控 2.0 等，数据遵循 OpenTelemetry GenAI 语义约定，可与用户自选的兼容后端无缝集成。

第二条路线是通过 LoongSuite Pilot 实现多 Agent 统一观测。Pilot 是运行在本机的统一 Agent 可观测采集器，能够发现已安装的各种 Agent，为不同产品部署对应的 Hook、插件或数据读取器，再将不同格式归一化为统一的 GenAI 事件。这条路线的核心价值不仅在于获得 DSH Trace，更重要的是让 DSH 与其他 Agent（如 Claude Code、Codex、Cursor 等）进入同一套查询、成本和审计体系。安装后即使不配置远端后端也能使用，Pilot 默认将归一化事件写入本地 JSONL，并提供本地 Dashboard，用于查看多 Agent 的 Token 消耗、会话记录、模型调用、工具使用和仓库活跃度等关键指标。

如有侵权，请联系删除。