DeepSeek Harness 的 LoongSuite 可观测插件

English | 简体中文

@loongsuite/dsh-plugin 是面向 DeepSeek Harness（dsh）的独立开源可观测插件。它观测 DSH 原生的会话、Agent 循环、LLM 流和工具生命周期，将其转换为 OpenTelemetry GenAI Trace 与 Metric，并通过标准 OTLP/HTTP Protobuf 上报到任意兼容后端。

LoongSuite 是基于 OpenTelemetry 的开源可观测采集体系。本仓库是它面向 DSH 的原生集成。插件不依赖也不要求安装 LoongSuite Pilot，不需要 sidecar、本地 JSONL 采集点，也不绑定任何厂商的后端。

当前状态：稳定的 0.1.x 版本。可从 npm 或 DSH 插件市场安装 @loongsuite/dsh-plugin。

DSH 的一轮对话作为 OpenTelemetry GenAI 调用链，在自建 Langfuse 中查看
一轮 DSH 对话通过 OTLP 上报到自建 Langfuse：4 个 react step、每次调用的耗时与 token、 web_search 失败后回退到 bash，以及 ENTRY span 上的 GenAI 语义属性。该截图显式开启了正文采集，默认是关闭的。

数据模型

DSH session/event + llm/stream
                │
                ▼
          生命周期协调器
                │
                ▼
   LoongSuite GenAI OTel 工具库
                │
                ▼
 私有 TracerProvider + MeterProvider
                │  OTLP/HTTP Protobuf
                ▼
   任意 OpenTelemetry 兼容后端

DSH 的每一轮对话生成一条调用链：

ENTRY
└── AGENT
    └── STEP
        ├── LLM
        └── TOOL

每次真实 LLM 调用都会生成独立的 LLM span，因此重试会保留为同一个 STEP 下的多次尝试。工具调用通过 DSH call ID 与结果关联。错误、中止、不完整的流以及插件卸载都会以错误状态关闭未结束 span，不会留下悬挂链路。Subagent 会话生成独立 trace，并携带 DSH 父会话和委派层级属性。

开启正文采集时，ENTRY 和 AGENT 的输入消息只包含本轮 source.kind=user 的直接输入。Runtime 快照、Agent 指令、Skill Catalog、Goal 和 Coordinator relay 等 DSH 合成上下文仍保留在 LLM span 上，但会排除之前 turn 的会话历史，确保每条 trace 只包含自身 turn 的上下文。同一 turn 的工具循环中，后续 LLM span 仍会保留本 turn 前面产生的 Assistant 工具调用和工具结果。ENTRY 和 AGENT 的输出消息只包含最终 stop 回复；如果 turn 没有到达 stop，则回退到最后一条可用的 Assistant 消息。

插件还会上报标准的 gen_ai.client.operation.duration 与 gen_ai.client.token.usage 指标。它不上报 OpenTelemetry Log，可与独立的 DSH 日志导出插件同时使用。

GenAI Invocation 构建与语义属性由 @loongsuite/otel-util-genai SDK 提供。

兼容范围

组件	支持范围	已完整验证版本
DeepSeek Harness	`>=0.1.0-rc.6 <0.2.0`	`0.1.0-rc.6` 的 headless 与 Web profile
Node.js	`>=22.19.0`	macOS 上的 `22.19`、`24.19` 和 `25.9`

不支持早于 0.1.0-rc.6 的 DSH RC 版本。每个插件版本都以 DSH 当前最新发布版为准进行验证，不会仅凭 bundle 能成功组合就宣称具备完整运行时兼容性。

安装与使用

手上还没有 OTLP 后端的话，examples/quickstart 会起一个本地 Jaeger 后端，三条命令看到第一条调用链。

在需要观测的每个 DSH profile 中安装插件：

dsh plugin --profile web add @loongsuite/dsh-plugin
dsh plugin --profile headless add @loongsuite/dsh-plugin

本地开发时，把包名换成本仓库的绝对路径：

dsh plugin --profile web add /absolute/path/to/dsh-plugin

设置服务名和 OTLP/HTTP Collector 地址，然后照常启动该 profile：

export OTEL_SERVICE_NAME=dsh-agent
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20your-token'

dsh --profile web
# 或：dsh --profile headless "总结这个工作区"

共享 endpoint 会自动补成 /v1/traces 与 /v1/metrics。未配置 endpoint 时，导出器使用 OpenTelemetry 标准默认值。

插件配置

大部分部署只需环境变量。也可以修改 $DSH_HOME/profiles/<profile>/cordis.patch.yml（默认位于 ~/.dsh）中的插件配置：

- id: loongsuite-observability
  config:
    endpoint: http://localhost:4318
    serviceName: dsh-agent
    headers:
      authorization: Bearer your-token
    resourceAttributes:
      deployment.environment.name: development
    captureContent: false
    exportMetrics: true

显式插件配置的优先级高于环境变量。

如果不想修改 profile，可在启动 DSH 前通过 GenAI 正文采集模式开启：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
dsh --profile web

配置项	默认值	含义
`enabled`	`true`	不卸载 bundle，直接停止采集。
`endpoint`	未设置	OTLP/HTTP 公共基地址；插件自动追加 signal 路径。
`traceEndpoint` / `metricEndpoint`	未设置	完整的单 signal 地址；优先于 `endpoint`。
`headers`	`{}`	同时添加到两个导出器的请求头。
`serviceName`	`OTEL_SERVICE_NAME` 或 `deepseek-harness`	OpenTelemetry `service.name`。
`resourceAttributes`	`{}`	额外的字符串类型 Resource 属性。
`captureContent`	环境变量配置或 `false`	上报提示词、回复、工具定义、参数和结果正文。
`contentMaxChars`	`128000`	每个正文属性序列化后保留的最大字符数。
`exportMetrics`	环境变量配置或 `true`	上报 LLM 耗时和 token 指标。
`maxExportBatchSize`	`512`	每批最多上报的 span 数。
`maxQueueSize`	`2048`	最多排队的 span 数，不能小于 batch size。
`traceExportIntervalMs`	`5000`	Trace 批量导出间隔。
`metricExportIntervalMs`	`60000`	Metric 导出间隔。
`exportTimeoutMs`	`30000`	OTLP 导出超时。
`debug`	`false`	通过 DSH logger 输出额外的插件生命周期诊断。

支持以下 OpenTelemetry 标准环境变量：

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 和 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS
OTEL_EXPORTER_OTLP_TRACES_HEADERS 和 OTEL_EXPORTER_OTLP_METRICS_HEADERS
OTEL_SERVICE_NAME
OTEL_RESOURCE_ATTRIBUTES
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT（未显式配置 captureContent 时，SPAN_ONLY 或 SPAN_AND_EVENT 开启 span 正文）
OTEL_METRICS_EXPORTER（未显式配置 exportMetrics 时，none 关闭指标导出）

Header 与 Resource 值使用标准的逗号分隔、百分号编码 key=value 格式。

隐私与运行时行为

默认不采集正文：提示词、回复、工具 schema、参数和结果不会进入 span，但结构元数据和 token 用量仍会上报。启用 captureContent，或将正文采集环境变量设为 SPAN_ONLY / SPAN_AND_EVENT 后，源码、凭据、个人数据或其他敏感内容可能被发送到已配置后端；启用前应先确认后端的留存和访问控制策略。如果某个 profile 必须忽略进程环境并始终禁止正文采集，请显式配置 captureContent: false。

插件持有私有 OpenTelemetry Provider，不会替换 DSH 或其他库的全局 Provider；监听器和 Provider 也会随 DSH 插件生命周期释放和 flush。插件附加到已运行或 HMR 重载的 profile 时，只接管现有会话的身份，并从下一次原生 turn/start 开始采集，不会重放历史事件或生成重复链路。

开发

需要 Node.js 22.19 或更高版本以及 pnpm。

pnpm install
pnpm run check
pnpm test
pnpm run build
pnpm pack

实现约束与发布检查清单见贡献指南。

许可证

Apache-2.0

dsh-plugin

Cài đặt

Mã nguồn

Thẻ

Tác giả

Readme