loongsuite/dsh-plugin

DeepSeek Harness 的 LoongSuite 可观测插件

@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 对话通过 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 =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//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