前言¶

DSH 的理念是“一切皆插件”。对 dsh 插件作者来说，dsh 已有会话级 OTel 遥测，但插件维度的 trace、log、metric 往往需要自行处理 OpenTelemetry providers、导出器和配置。dsh-o11y-plugin 的目标是把这部分能力收敛到插件层：注册全局 OpenTelemetry providers，让使用标准 @opentelemetry/api 的插件导出 traces、metrics、logs，并将 dsh 会话遥测桥接为 OTel logs。

这是什么¶

dsh-o11y-plugin 是为 deepseek-harness（dsh）提供统一插件维度可观测性的 dsh 插件。仓库 owner 是 fly3366，许可证为 MIT。它适合希望使用标准 @opentelemetry/api 输出遥测、而不是每个插件各自实现 OTel 导出的插件作者。

核心功能¶

• 为 dsh 插件提供统一的 trace、log、metric 可观测性。
• 注册全局 OpenTelemetry providers，使标准 @opentelemetry/api 插件能够导出 traces、metrics、logs。
• 将 dsh 会话遥测桥接为 OTel logs。
• 通过 OTLP/HTTP endpoint 导出遥测；未配置或 endpoint 不可达时静默丢弃。
• 支持 headless 与 web profile。
• 插件无状态，移除后不需要数据清理。
• 不写文件，不读取或存储凭据；遥测在导出前保持在内存中。
• 可在 dsh Web settings UI 以 o11y namespace 查看和编辑配置；在缺少 settings service 的 dsh 版本上无操作。

兼容环境¶

• DSH 兼容：@deepseek-ai/dsh 0.1.0-rc.6–rc.8。
• 运行时依赖：@deepseek-ai/cordis 4.0.1。
• Node：^22.19 || >=24。
• Profiles：headless、web。

安装与启用¶

从 npm 安装到 web profile：

dsh plugin --profile web add dsh-o11y-plugin

从 git 仓库安装到 web profile：

dsh plugin --profile web add github:fly3366/dsh-o11y-plugin

在 headless profile 安装：

dsh plugin --profile headless add github:fly3366/dsh-o11y-plugin

从 web profile 移除：

dsh plugin --profile web remove dsh-o11y-plugin

插件无状态，移除时不需要额外数据清理。

典型用法¶

安装后，将 OTLP endpoint 指向 collector，再运行 dsh：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 dsh --profile headless "say hi"

如果插件调用 @opentelemetry/api 的 trace.getTracer(...)、metrics.getMeter(...) 或 logs.getLogger(...)，这些 signals 会经过该插件注册的全局 OpenTelemetry pipeline 导出。未配置 endpoint 或 collector 不可达时，遥测会静默丢弃。

适用场景与注意¶

适合在 dsh 插件中使用标准 @opentelemetry/api，并希望在 headless 与 web profile 下使用统一 OTLP/HTTP 导出路径的场景。

使用注意：

• 插件以当前 dsh 进程权限运行；安装前应检查源码与许可证。
• 网络访问仅面向配置的 OTLP/HTTP endpoint；没有 collector 可达时静默丢弃。
• 插件不写文件、不读取或存储凭据；遥测在导出前保持在内存中。
• dsh Web settings UI 的 o11y namespace 可在缺少 settings service 的 dsh 版本上无操作。Web settings card 在 wip/settings-ui 分支开发，未随 main 发布；dsh 尚未允许外部 bundle 注入 web client composition。

结尾¶

dsh-o11y-plugin 提供了一套统一的 dsh 插件可观测性路径：全局 OpenTelemetry providers、OTLP/HTTP 导出、dsh 会话遥测到 OTel logs 的桥接，以及无状态移除。

GitHub：https://github.com/fly3366/dsh-o11y-plugin