将会话事件流导出为 OpenTelemetry OTLP 与 Langfuse 的脱敏、缓冲 traces 与指标,默认关闭。
安装
# npm 包(预构建)
dsh plugin --profile web add dsh-observe
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:PerryLink/dsh-observe
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
dsh-observe
把每次会话变成标准 OTLP trace 与 Langfuse 观测——发出去之前先脱敏,默认什么都不发。
面向 DeepSeek Harness 的可观测性导出器:turn/step/工具调用/LLM 生成 span,token 与 USD 成本指标,异步批量、有界离线缓冲、指数退避重试;OTLP 与 Langfuse 接其一或两个都接。
安装 · 配置 · FAQ · 简体中文 · English · Español · Português · हिन्दी
dsh plugin --profile <name> add dsh-observe
社区插件,与 DeepSeek 官方无关。唯一仓库:https://github.com/PerryLink/dsh-observe(Gitee 为镜像)。
它是什么
dsh-observe 把 harness 的 session/event 流翻译成标准可观测协议:一个 turn 一条 trace,step、工具调用与 LLM 生成各是一个 span,token 与成本是累计指标,prompt/completion 正文先脱敏截断再入队。它只做导出——不注册任何模型工具、不注册用户可见命令,全部行为由配置决定;配置了 OTLP 或 Langfuse 之后重启,数据自己流走,没配置就什么都不采集。
三步上手
安装(三选一):
# git 通道(最新 main;prepare 脚本只用生产依赖构建) dsh plugin --profile web add github:PerryLink/dsh-observe # npm 通道(已发布版本) dsh plugin --profile web add dsh-observe # tarball 通道:本仓库 pnpm pack 后 dsh plugin --profile web add ./dsh-observe-<version>.tgz如果 pnpm 对本包报
ERR_PNPM_IGNORED_BUILDS(esbuild 的平台二进制无害校验),在你的pnpm-workspace.yaml中加入allowBuilds: { esbuild: true }——dshCLI 会打印确切片段。最小配置(在 profile patch 里打开
enabled并至少配一个后端;cordis.patch.yml里该行默认关闭):- insert: - id: dsh-observe name: dsh-observe config: enabled: true otlp: endpoint: http://localhost:4318Langfuse 侧同理:
langfuse.baseUrl+langfuse.publicKey+langfuse.secretKey,两者可以同时开。验证已生效:
dsh --profile web --dump-config | grep -A2 'id: dsh-observe'本插件不注册用户可见命令,所以没有
/observe之类的手动触发面;把remote.enabled设为true后,设置页可经observe/status读到已配置后端、队列深度与离线缓冲占用。
卸载:dsh plugin --profile web remove dsh-observe(或从 profile patch 删掉该行)。
所有 PerryLink 插件均可在 DSH Desktop 内置市场中浏览:市场 → 来源 → 添加来源 → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选中。安装仍需通过市场的 npm 身份校验与你的确认。
核心能力
dsh-observe 把会话事件流变成标准可观测协议:
- Spans —— turn、step、工具调用(耗时、状态、重试推导)与 LLM 生成 span,按 turn 连成 trace,id 确定性可复现。
- Metrics —— 按 provider/model 的 token 计数、USD 成本计数(可配价格表)、以及可选的
ctx.tokenMeter上下文压力 gauge。 - 脱敏采集 —— prompt 与 completion 正文先经结构性键名脱敏 + 内置密钥模式 + 自定义模式 + 字符预算截断,之后才进入队列或发送。
- 可靠性 —— 异步批量(数量与定时双触发)、有界持久离线缓冲(storage-domain,最旧优先淘汰)、确定性指数退避重试;未送达批次重启后仍在。
- 运行时总开关 —— 可选 Typert remote(
observe/status、observe/setEnabled)让设置页在不卸载的情况下停止/恢复导出。 - 默认关闭 ——
enabled: true且至少配置一个后端才是显式开启;否则不采集、不导出。
session/event 流
│ collector(turn/step/tool/llm span、metrics)
│ sanitize(键名、密钥、预算)
├──▶ pipeline "otlp" ── 队列 ── flush ──▶ OTLP /v1/traces + /v1/metrics
│ └─ 重试/退避 ──┐
├──▶ pipeline "langfuse" ── 队列 ── flush ──▶ Langfuse ingestion
│ └─ 重试/退避 ──┤
└────────── 持久 spool(离线缓冲,有界)◀┘
表面
本插件不注册任何模型工具,也不注册用户可见命令——它是后台导出器。它只有三类表面:
- 消费
session/event(span/metric 采集)、session/flush(尽力导出 kick —— 持久化检查点绝不等待远端后端)、session/disposed。 - 可选 remote 服务
observe(remote.enabled,默认关闭)——observe/status返回总开关状态、已配置后端、队列深度与缓冲占用;observe/setEnabled在运行时停止/恢复导出。 - 唯一注入的服务键
storageDomain,用于离线缓冲的持久表。
示例
没有手动触发面:安装后按上面的最小配置打开 enabled,重启后即可在 OTLP 后端看到 trace 与指标、在 Langfuse 看到 observations。要确认「确实在采集」,看后端收到的第一条 trace 即可;要确认「确实在发」,看 observe/status 的队列深度是否随会话推进而回落。
配置
所有可调项都是 Schemastery Config 字段(可在 cordis.yml / profile patch 中修改)。按 id 定向覆盖会替换整行 —— 需要重新声明每个键。cordis.patch.yml 逐键内联注释。
最常用键:
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
false |
总开关;true 且至少一个后端才是显式开启 |
otlp.endpoint |
(必填) | OTLP 基础 URL;/v1/traces 与 /v1/metrics 由插件追加 |
otlp.serviceName |
deepseek-harness |
service.name 资源属性 |
langfuse.baseUrl |
https://cloud.langfuse.com |
Langfuse 基础 URL |
langfuse.traceName |
session {session} turn {turn} |
trace 名称模板;{session}/{turn} 按 trace 插值 |
capture.llm |
true |
LLM 生成 span 开关 |
llm.prompt |
true |
采集脱敏后的请求 prompt(false 只记大小) |
llm.reasoning |
true |
单独采集 reasoning(思维链)到 gen_ai.completion.reasoning(false = 只发正文) |
batch.maxBufferRecords |
10000 |
持久离线缓冲上限;最旧记录先丢 |
remote.enabled |
false |
挂载 observe Typert remote(运行时总开关) |
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
false |
总开关;true 且至少一个后端才是显式开启 |
otlp |
null |
OTLP 后端配置,null 表示禁用 |
otlp.endpoint |
(必填) | OTLP 基础 URL;/v1/traces 与 /v1/metrics 由插件追加 |
otlp.serviceName |
deepseek-harness |
service.name 资源属性 |
otlp.serviceVersion |
(无) | service.version 资源属性 |
otlp.headers |
{} |
合并进每个导出请求的额外请求头 |
otlp.timeoutMs |
10000 |
单请求超时 |
langfuse |
null |
Langfuse 后端配置,null 表示禁用 |
langfuse.baseUrl |
https://cloud.langfuse.com |
Langfuse 基础 URL |
langfuse.publicKey |
(必填) | 项目公钥 |
langfuse.secretKey |
(必填) | 项目密钥 |
langfuse.release |
(无) | 打在各 trace 上的 release 标签 |
langfuse.traceName |
session {session} turn {turn} |
trace 名称模板;{session}/{turn} 按 trace 插值 |
langfuse.tags |
[] |
打在每个 trace 上的静态标签 |
langfuse.timeoutMs |
10000 |
单请求超时 |
capture.turns |
true |
turn 生命周期 span |
capture.steps |
true |
step 生命周期 span |
capture.tools |
true |
工具调用 span(参数/结果脱敏) |
capture.llm |
true |
LLM 生成 span |
llm.prompt |
true |
采集脱敏后的请求 prompt(false 只记大小) |
llm.completion |
true |
采集脱敏后的 completion(false 只记大小) |
llm.reasoning |
true |
单独采集 reasoning(思维链)到 gen_ai.completion.reasoning(false = 只发正文) |
metadata.sessionId |
true |
会话 id 属性 |
metadata.cwd |
false |
会话工作目录(本地路径——默认关闭) |
metadata.agentPreset |
true |
agent preset id 属性 |
metadata.model |
true |
provider/model 属性 |
metrics.tokens |
true |
按 provider/model 的 token 计数 |
metrics.cost |
true |
USD 成本计数(需 pricing 规则匹配) |
metrics.contextTokens |
true |
上下文压力 gauge(需 ctx.tokenMeter) |
pricing |
[] |
价格表,首个匹配生效:{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? } |
sanitize.enabled |
true |
脱敏总开关(false 只关脱敏,不关截断) |
sanitize.redactKeys |
[] |
额外键名子串(key/token/secret/password/authorization/credential/apiKey 恒生效) |
sanitize.redactPatterns |
[] |
额外密钥正则 |
sanitize.truncatePromptChars |
4000 |
prompt 字符预算 |
sanitize.truncateCompletionChars |
4000 |
completion 字符预算 |
sanitize.truncateToolInputChars |
2000 |
工具参数字符预算 |
sanitize.truncateToolOutputChars |
2000 |
工具结果字符预算 |
sanitize.truncateAttributeChars |
512 |
span 属性字符串预算 |
batch.maxRecords |
256 |
队列达到该数量即 flush |
batch.flushIntervalMs |
5000 |
定时 flush 间隔 |
batch.maxQueueRecords |
2000 |
内存队列上限;超出溢入缓冲 |
batch.maxBufferRecords |
10000 |
持久离线缓冲上限;最旧记录先丢 |
batch.bufferRetryIntervalMs |
30000 |
离线缓冲重试间隔 |
retry.maxAttempts |
5 |
每批尝试次数(含首次) |
retry.baseDelayMs |
1000 |
首次退避延迟 |
retry.factor |
2 |
每连续失败一次的退避倍数 |
retry.maxDelayMs |
60000 |
退避上限 |
remote.enabled |
false |
挂载 observe Typert remote(运行时总开关) |
⚠️ reasoning 合规提示:
llm.reasoning默认开启,reasoning 会作为gen_ai.completion.reasoning单独外发(绝不混入gen_ai.completion;在 Langfuse 中放在 generation 的 metadata 里)。思维链可能包含用户原文,或模型逐字复述的上下文,外发前请评估合规要求;不需要时设llm.reasoning: false。llm.completion: false会同时关掉正文与 reasoning。
按 id 覆盖的示例(会替换整行,所以重述需要的键):
- insert:
- id: dsh-observe
name: dsh-observe
config:
enabled: true
otlp:
endpoint: http://localhost:4318
capture:
tools: false
sanitize:
truncatePromptChars: 2000
batch:
maxBufferRecords: 20000
FAQ
不会按原文发出。每条记录在入队之前就完成三层脱敏:结构性键名(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 的周期性回灌,重启后未送达批次仍在。OTLP metrics 是例外:它按累计聚合,丢一次 flush 会在下一次自愈。
离线缓冲里只有已脱敏的记录,且从存储读回时会再校验一次才交给 sink。插件本身不存任何凭据:Langfuse 公钥/密钥只出现在发往你配置的 Langfuse 端点的请求里,OTLP 请求头同理只发往你配置的 OTLP 端点——请用凭据引用或环境注入,不要写进 profile patch 提交。它只读会话事件流,从不读取或改写会话日志文件。
采集与脱敏都在事件处理里同步完成,但发送全部是异步的:队列按数量或定时 flush,session/flush 只是一次尽力而为的 kick——持久化检查点绝不等待远端后端。导出失败会告警、计数(observe.export_failures)、重试,最后进缓冲;会话事件处理器本身抛错会被捕获并记录,可观测性不会拖垮 harness 热路径。
只注入一个服务键 storageDomain,只监听三个 session/* 事件,不注册模型工具、不注册命令、不注册 client slot、不监听任何 waterfall,也不改全局对象。唯一需要留意的命名面是可选 remote 服务 observe(remote.enabled 默认关闭)——同一 profile 里若已有别的插件占用同名服务,只开其中一个。
安全边界
- 默认关闭 —— 不显式开启(
enabled: true且至少一个后端)则不采集、不导出。 - 发送前脱敏 —— 结构性键名脱敏、内置密钥模式(API key、GitHub token、AWS key、bearer 凭据、私钥)、自定义模式与字符预算,全部在任何记录离开内存前生效。
- 持久边界再校验 —— 从存储读回的记录在到达 sink 前再次检查。
- 失败大声、失败隔离 —— 导出失败会告警、计数、重试并最终入缓冲;会话事件处理失败被捕获并记录,可观测性永远不会拖垮 harness 热路径。
- 模型可见 ⟺ 已记录 —— prompt/completion 导出只投影会话 surface(其节点 0 即系统提示词)与已记录的 header(调用配置与工具);导出器不发明任何内容。
权限与数据
- 权限:对你配置的端点出网(
network:outbound)、读取事件流(session:read)、写离线缓冲(storage:write);无原生代码、无文件系统访问。 - 数据:所有外发内容都来自会话日志,并在入队、缓冲、发送前完成脱敏(脱敏 + 截断)。离线缓冲只存脱敏记录,读回时再次校验。
- 凭据:Langfuse 公钥/密钥只发往你配置的 Langfuse 端点;OTLP 请求头只发往你配置的 OTLP 端点。插件自身不存任何凭据 —— 请使用凭据引用或环境注入。
已知限制
- 基线
0.2.2-rc.1—— 插件针对@deepseek-ai/dsh@0.2.2-rc.1开发与测试(devDependencies 与 CI 的主尺子);engines.dsh的>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0与 peer 复合范围让每条已发布线都可安装,更旧的基线由第二把尺子(typecheck:ci)与 compat 工作流覆盖。 - 审计事件不落盘 —— 本插件自身的
observe/*记录仅作审计:当前宿主线的会话 append 闸门只接纳 surface 事件,因此不会有observe/*事件写入会话日志;插件也不会用未标记 append 伪造一条(那会让会话不可读)。审计面请以observe/status输出(需remote.enabled: true)与 OTLP/Langfuse 后端为准。 - Metrics 不走重试/缓冲路径 —— OTLP metrics 按累计聚合,丢失一次 flush 会在下一次自愈(设计如此,非缺陷)。
- 无采样 —— 每个启用的 span 族都会导出;大流量会话请调整
capture.*开关与batch.maxBufferRecords。
与其他 DSH 插件的互操作性
本插件的注册面很窄,因此天然不易与别的插件冲突:
- 无工具名冲突 —— 不注册任何模型工具(README 与
src/index.ts均无工具注册)。 - 无命令名冲突 —— 不注册用户可见命令,斜杠命令命名空间完全不碰。
- 无 client slot 冲突 —— 本包不含浏览器半(无
client/目录),不注册任何 client slot。 - 无 waterfall 短路 —— 只读监听
session/event、session/flush、session/disposed,不监听任何 allow/passthrough 型 waterfall,因此不存在压住别人决策的问题。 - 唯一的服务键 ——
storageDomain(注入,不提供);另有一个可选的 remote 服务observe,仅在remote.enabled: true时注册。 - 出网只去你配置的端点 —— OTLP 与 Langfuse 各自独立,关掉一个不影响另一个。
如果你在同一个 profile 里同时装了别的可观测性插件,注意两点:两者都会消费 session/event(Cordis 的广播语义,互相不会饿死),但会产生两份 trace;以及不要同时注册 observe 这个 remote 服务名。
兼容性
| 维度 | 状态 |
|---|---|
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1(2026-10-04 已适配):会话格式 V4 把工具结果改为 role: 'tool' 的一等消息,顶层携带 toolCallId + content + 可选 isError —— V3 的 tool-result 内容块已从宿主 ContentBlockMap 移除,本插件只读 V4 形状(升级前的 V3 日志仍可经只读兼容路径投影)。会话格式 V3 的其余特征沿用:助手流内嵌到 assistant/message / assistant/attempt,系统提示词为 surface 节点 0(system/message);本插件只消费实时事件流,从不读取会话日志文件。engines.dsh 为 >=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0,profile 安装冒烟由 compat 工作流覆盖。 |
| Node | ^22.19.0 || >=24.9.0,纯 ESM("type": "module") |
| 后端 | OpenTelemetry OTLP/HTTP(traces + metrics,JSON 编码)与 Langfuse(LLM 可观测)——二选一或同时 |
| 模型 | 与模型无关:它导出 session/event 流,自身不调用任何模型 |
peer 依赖:@deepseek-ai/cordis ^4.0.5-alpha.1、@deepseek-ai/schemastery ^3.18.5,以及 @deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/dsh-storage、@deepseek-ai/dsh-storage-domain、@deepseek-ai/dsh-storage-json、@deepseek-ai/dsh-typert-protocol(>=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0;devDependencies 钉 0.2.2-rc.1)。zod 是唯一的运行时依赖,用于离线缓冲的持久边界校验。
生态与质量
- Gitee 镜像(同步镜像,以 GitHub 为准)
- dshfind 插件页(安装量与排名)
- OpenSSF Scorecard 报告(由 .github/workflows/scorecard.yml 驱动)
- dsh-plugin-doctor 验证报告
- DSH Market(已上架)
- 1024 商店渠道:先
npm i -g dsh1024,再dsh1024 plugin --profile web add dsh-observe(计入 deepseek1024.com 安装排行) - 生态实测知识库:插件开发指南 · 选型实测数据 · 维护取舍判据
开发
pnpm install # node ^22.19 || >=24.9
pnpm run typecheck # tsc:src + tests,对照 0.2.2-rc.1 devDeps(无 tsconfig paths)
pnpm run typecheck:ci # tsc:对照已发布线(无 paths)
pnpm run check:ruler-live # canary:必须编译失败,以证明尺子仍是活的(需 checkout 面)
pnpm test # vitest:126 个测试、18 个套件(真实 Context/Session/storage 接缝)
pnpm run test:coverage # 覆盖率门禁(90/80/90/90)
pnpm run build # tsdown bundle + tsc 声明(lib/)
pnpm run verify:self-contained # 依赖声明全部来自 registry
pnpm run verify:artifacts # 构建产物 ESM 面 + bundle patch 齐全
node scripts/check-readme-sync.mjs # 五语 README 同步门
pnpm pack # 发布用 tarball
配图由 scripts/gen-readme-assets.py 程序化生成(Pillow 绘制 1440×576 hero,结构图为手写 1100×660 SVG),输出 docs/assets/dsh-observe-hero-{zh,en}-{light,dark}.webp 四张与 docs/assets/dsh-observe-flow-v5-{light,dark}.svg 一对,可重复执行。旧的 docs/assets/dsh-observe-flow-{light,dark}.svg、dsh-observe-flow.svg、dsh-observe-hero.png 与 dsh-observe-demo.{png,gif} 保留在原处以防外链失效,README 不再引用。
Topics:dsh, dsh-plugin, deepseek-harness, deepseek, cordis, observability, opentelemetry, otlp, langfuse, tracing
家族与致谢
本项目是 PerryLink 维护的 DeepSeek Harness 插件家族成员(全部 Apache-2.0)。如果这个插件帮到了你,给个 star——它不解锁任何功能,但会让下一个人更容易找到它。
- @PerryLink —— 创建者与维护者:collector、pipeline、spool、OTLP/Langfuse sink、脱敏层与五语文档。
License
LICENSE(Apache License 2.0)© 2026 dsh-observe contributors
链接
同类插件
yjh051108/dsh-routing-suite★ 7021
一个仓库三件套:DSH 插件包的运行时注入器(注入、热重载、卸载、开发侧挂区一键转正、路由自愈,外带设置页插件管理:列出、卸载、拖入文件夹内化)、任务感知的思维模式路由 agent 预设(router-standard / router-spec / router-react)、以及分级两级任务协议(commit_star / lock_stage / revise_do / edit_plan / mark_task / redteam_verdict 六个工具,任务状态落盘)。注入器实现直接在库内,安装的是它自己的行为而不是一份依赖清单。
strukto-ai/mirage#dsh★ 3785
把文件系统与 bash 提供者换成 mirage 虚拟工作区:文件工具与 shell 命令作用于挂载的资源(RAM、S3、Redis、Slack、Gmail、Notion、Postgres)而非宿主磁盘,支持按挂载点设置读/写/执行模式、按命令选择沙箱(进程内 monty、pyodide、quickjs;远程 docker、e2b、daytona),并可在虚拟终端中安装 CLI(git、gh、slack、linear、ntn、gws,或自行注册的程序树)作为命令头词。
first-fluke/oh-my-agent#dsh★ 1460
在工具执行前后以及尝试结束当前轮次时运行项目 OMA 检查。随插件安装 OMA CLI 依赖,并在首次使用时初始化未配置的项目。需要 Node.js 22+;首次初始化需要网络连接和项目目录写入权限。
MichengAI/dsh-skills-manager★ 561
在设置里管理本地 DSH 技能,并只读查看公共 Agent 技能。
hust-open-atom-club/oh-dsh★ 324
社区发行版:TUI、桌面端与 Web UI 统一体验,分层安装、一步到位。
Fishquito7/dsh-skill-mcp-panel★ 277
在 DSH Web 设置中管理技能与 MCP 服务器:技能卡片热启停、工作区作用域、分组、批量迁移与拖拽导入,以及 stdio/HTTP MCP 增删改查、连接测试、密钥脱敏,并附带统一 dsh-panel 命令行。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。