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 对话通过 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 提供。

兼容范围

不支持早于 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

支持以下 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