返回目录

dsh-observe

精选清单收录维护状态: 活跃

perrylink/dsh-observe

可观测性导出插件,将轮次、工具与 LLM 调用跨度及费用指标导出至 OpenTelemetry/Langfuse。

前往 GitHub项目主页
$ dsh plugin --profile web add dsh-observe

16

星标

2

Fork

TypeScript

语言

Apache-2.0

许可证

2026-08-16

创建于

2026-11-18

最近推送

Apache-2.0 的 TypeScript 插件(dsh 0.2.x、Node ^22.19 || >=24.9):把 DeepSeek Harness 会话被动导出成 OTLP trace/指标与 Langfuse observations,自带发送前脱敏、有界离线缓冲与退避重试。

DSH 适配

原生运行时

作者声明

安全审计

未审计

最后核验

2026-11-20

许可证

Apache-2.0

01它能帮你完成什么?

  • 把 DeepSeek Harness 的每个会话接进现有的可观测平台,变成标准的 trace 与指标

    一个 turn 一条 trace,step、工具调用(耗时、状态、重试推导)与 LLM 生成各一个 span;另有按 provider/model 的 token 计数、USD 成本计数和可选的上下文压力 gauge

    需要在 OpenTelemetry 或 Langfuse 里看清会话延迟、工具使用与花费的 Agent / 平台工程师

  • 开启 prompt / completion 级别的观测,同时不把密钥和原文送出去

    入队、入缓冲、外发之前就已完成键名脱敏、密钥模式清洗与字符预算截断的记录;只想要体积时还能只发大小与计数

    有数据合规要求、但仍希望拿到 LLM 级别链路的团队

  • 后端抖动或断网时仍不丢观测、也不拖住 harness

    异步批量投递 + 确定性指数退避重试,重试耗尽后落到有界持久缓冲;重启之后未送达批次仍在

    不能接受「观测后端挂了就卡住会话」的运维与 SRE

02如何接入 DeepSeek Harness?

前置条件

  • Node `^22.19.0 || >=24.9.0`——纯 ESM 包,运行时依赖只有 `zod`
  • DeepSeek Harness CLI 的 engines 落在 `>=0.2.1-0 <0.3.0` 或 `>=0.2.2-0 <0.3.0`(插件针对 `@deepseek-ai/dsh@0.2.2-rc.1` 开发与测试)
  • 至少一个后端:OTLP/HTTP 地址(`/v1/traces` 与 `/v1/metrics` 由插件追加),或 Langfuse 的 `baseUrl` + `publicKey` + `secretKey`

安装步骤

  1. 01

    装进 profile:npm 已发布版本用 `dsh plugin --profile web add dsh-observe`;要最新 main 用 `dsh plugin --profile web add github:PerryLink/dsh-observe`;本仓库 `pnpm pack` 出来的 tarball 用 `dsh plugin --profile web add ./dsh-observe-<version>.tgz`。

    $ dsh plugin --profile web add dsh-observe

  2. 02

    如果 pnpm 报 `ERR_PNPM_IGNORED_BUILDS`(esbuild 平台二进制的无害校验),在 `pnpm-workspace.yaml` 里加 `allowBuilds: { esbuild: true }`,dsh CLI 会把确切片段打印出来。

  3. 03

    在 profile patch 里打开:`cordis.patch.yml` 那行默认是关的,需要设 `enabled: true` 并配好 `otlp.endpoint` 或 `langfuse.baseUrl` + `langfuse.publicKey` + `langfuse.secretKey`,两个后端可以同时开。

验证接入成功

  • `dsh --profile web --dump-config | grep -A2 'id: dsh-observe'`,确认插件行和你填的值进了 profile。
  • 没有 `/observe` 之类的命令可手动触发:看后端是否收到第一条 trace 与指标(Langfuse 侧是 observations);把 `remote.enabled` 设为 `true` 后,`observe/status` 能读到已配置后端、队列深度与离线缓冲占用。

回滚

  • `dsh plugin --profile web remove dsh-observe`;或直接从 profile patch 里删掉该行。

03DSH 适配与能力边界

DSH 适配原生运行时

通过 `dsh plugin --profile <name> add dsh-observe` 装进 profile 的原生插件;只监听 harness 的 session/event 流并导出成 OTLP trace/指标与 Langfuse observations,不注册任何工具或命令。

  • turn / step / 工具 / LLM span

    harness 的 session/event 事件流→一个 turn 一条 trace,下挂 step、工具调用(耗时、状态、重试推导)与 LLM 生成 span;span 与 trace 的 id 确定性可复现

  • token / 成本 / 上下文指标

    会话事件里的 provider/model 属性,以及可选的 `pricing` 价格表→按 provider/model 的 token 计数、USD 成本计数(首个匹配的价格规则生效)、以及依赖 `ctx.tokenMeter` 的上下文压力 gauge

    没有 `pricing` 规则命中模型时不会产生成本指标
  • 发送前脱敏与截断

    prompt、completion、工具参数与工具结果→结构性键名脱敏、内置密钥模式加自定义正则、字符预算(prompt/completion 各 4000,工具参数与结果各 2000,span 属性 512)处理后的记录

    正文会被截断,超长 prompt / completion 不会原样保留
  • 异步批量与持久缓冲

    已入队的 span 与指标记录→按数量(256 条)或定时(5000ms)flush,失败按 5 次尝试、1000ms×2 确定性退避(上限 60000ms)重试,最终溢出到有界持久 spool(10000 条、最旧优先淘汰),每 30000ms 回灌一次且重启后仍在

    缓冲会占用存储;容量有界,超出后淘汰最旧记录从存储读回的记录在交给 sink 前会再校验一次
  • 运行时总开关

    `observe/setEnabled`,仅在 `remote.enabled: true` 时可用→不卸载插件也能停止 / 恢复导出;`observe/status` 返回总开关状态、已配置后端、队列深度与缓冲占用

    会向 profile 注册一个名为 `observe` 的 remote 服务,同一 profile 里不要重复注册同名服务

04适合谁?何时不该用?

适合

  • 需要在 OpenTelemetry 或 Langfuse 里看清会话延迟、工具使用与花费的 Agent / 平台工程师
  • 有数据合规要求、但仍希望拿到 LLM 级别链路的团队
  • 不能接受「观测后端挂了就卡住会话」的运维与 SRE

不适合

  • 两头都卡版本:`engines.dsh` 为 `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`,当前基线是 `@deepseek-ai/dsh@0.2.2-rc.1`;包本身要求 Node `^22.19.0 || >=24.9.0` 且为纯 ESM。适配的是会话格式 V4(工具结果变成 `role: 'tool'` 一等消息),所以定位在 0.2.x 这条 harness 线上。
  • Langfuse 公钥/密钥与 OTLP 请求头只发往你自己配置的端点,插件自身不存任何凭据;README 明确要求用凭据引用或环境注入,不要把密钥写进 profile patch 一起提交。

05兼容性、维护与安全提示

  • 两头都卡版本:`engines.dsh` 为 `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`,当前基线是 `@deepseek-ai/dsh@0.2.2-rc.1`;包本身要求 Node `^22.19.0 || >=24.9.0` 且为纯 ESM。适配的是会话格式 V4(工具结果变成 `role: 'tool'` 一等消息),所以定位在 0.2.x 这条 harness 线上。
  • Langfuse 公钥/密钥与 OTLP 请求头只发往你自己配置的端点,插件自身不存任何凭据;README 明确要求用凭据引用或环境注入,不要把密钥写进 profile patch 一起提交。
  • 申请对你配置的端点出网、读取会话事件流、写离线缓冲三项权限;没有原生代码、不访问文件系统,也不注册模型工具、用户可见命令或 client slot,只消费实时事件流而不读取会话日志文件。
  • 没有采样:每个启用的 span 族都会导出,高流量会话得自己调 `capture.*` 开关和 `batch.maxBufferRecords`。另外 OTLP metrics 按设计不走重试 / 缓冲路径,丢一次 flush 会在下一次累计聚合时自愈。
2026-08-162026-11-13v0.2.29

Apache-2.0 · 活跃维护(最新 release v0.2.29,2026-11-18 发布)

06常见问题

prompt 和工具参数会按原文发到后端吗?

不会按原文发出。每条记录在入队之前就完成三层处理:结构性键名脱敏(key / token / secret / password / authorization / credential / apiKey 恒在名单内,可用 `sanitize.redactKeys` 追加子串)、内置密钥模式(API key、GitHub token、AWS key、bearer 凭据、私钥)加上 `sanitize.redactPatterns` 自定义正则,以及字符预算截断——prompt 与 completion 各 4000 字符,工具参数与结果各 2000,span 属性 512。只想要体积不想要正文时,把 `llm.prompt` 与 `llm.completion` 设为 `false`,记录里只剩大小与计数。

后端挂了、网络断了会丢数据吗?

普通 span 与指标走「重试 → 溢出到离线缓冲」这条链:批次按 `retry.maxAttempts`(默认 5 次)与 `retry.baseDelayMs × retry.factor` 的确定性指数退避重试,重试耗尽或内存队列超过 `batch.maxQueueRecords` 时溢出到有界持久 spool(`batch.maxBufferRecords` 默认 10000,最旧优先淘汰),每 `batch.bufferRetryIntervalMs`(默认 30000ms)回灌一次,重启后未送达批次仍在。OTLP metrics 是 README 里写明的例外:它按累计聚合,丢一次 flush 会在下一次自愈。

思维链(reasoning)也会被导出去吗?

默认会。`llm.reasoning` 开着,reasoning 以单独的 `gen_ai.completion.reasoning` 属性外发,绝不混进 `gen_ai.completion`;在 Langfuse 里它放在 generation 的 metadata 中。README 提醒:思维链可能包含用户原文,或模型逐字复述的上下文,外发前请评估合规要求;不需要时设 `llm.reasoning: false`,而 `llm.completion: false` 会同时关掉正文与 reasoning。

会不会拖慢会话?

采集与脱敏在事件处理里同步完成,但发送全部是异步的:队列按数量或定时 flush,`session/flush` 只是一次尽力而为的 kick——持久化检查点绝不等待远端后端。导出失败会告警、计数(`observe.export_failures`)、重试并最终入缓冲;会话事件处理器抛错会被捕获并记录,可观测性不会压在 harness 的热路径上。

同一个 profile 里会和别的插件抢资源吗?

注册面很窄:只注入 `storageDomain` 一个服务键,只监听 `session/event`、`session/flush`、`session/disposed` 三个事件,不注册工具、命令、client slot 或 waterfall。唯一要留意的是可选的 `observe` remote 服务(`remote.enabled`,默认关闭)——同一 profile 里若已有别的插件占用同名服务,只开其中一个。再装一个可观测性插件本身没问题(Cordis 的广播语义不会互相饿死),但你会拿到两份 trace。

08数据与来源

  • 作者声明github.com2491014f11d1…

    把每次会话变成标准 OTLP trace 与 Langfuse 观测——发出去之前先脱敏,默认什么都不发。

  • 作者声明github.com2491014f11d1…

    它只做导出——不注册任何模型工具、不注册用户可见命令,全部行为由配置决定

页面基于项目公开文档、仓库元数据和 DSH Plugins 的结构化解析生成;最后核验于 2026-11-20。发现错误?提交更正。

🏆

最佳 DeepSeek Harness 插件

从全目录挑出的 12 个值得优先安装的插件,覆盖各个分类。

DSH Plugins 是独立的 DeepSeek Harness 插件目录,与 DeepSeek 官方无关,也不代表官方背书。第三方插件未经安全审计,安装前请审查源码。

每周获取最新的 DeepSeek Harness 插件,绝不滥发。