可观测性导出器 PerryLink/dsh-observe

📊 dsh-observe

- 1024 store channel：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-observe（计入 deepseek1024.com 安装排行）。

dshfind

DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测性导出器。

把会话事件转成 OTLP trace 和 Langfuse observation —— 已脱敏、带缓冲、默认关闭。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-observe

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-observe —— prepare 脚本只带生产依赖构建。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-observe。
- tarball 渠道：在本仓库执行 pnpm pack，再执行 dsh plugin --profile web add ./dsh-observe-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-observe（或从配置档补丁里删掉对应行）。
如果 pnpm 对这个包报 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制校验，无害），在 pnpm-workspace.yaml 里加上 allowBuilds: { esbuild: true } —— dsh 命令行会打印出这段配置的原文。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（共 95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-observe 是什么？

DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测性导出器。

把会话事件转成 OTLP trace 和 Langfuse observation —— 脱敏、缓冲、默认关闭。

dsh-observe 的工作流示意图：安装 → 打开面板 → 操作。

工作流概览：安装 → 打开面板 → 操作。下面的示例用的都是真实命令。

兼容性

| 层面 | 状态 |
| 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 流内嵌在 assistant/message / assistant/attempt 中，系统提示词是表面节点 0（system/message）；插件只消费实时事件流，从不读取会话日志文件。peer 范围 >=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 保证每个已发布版本都可安装（完整的本地门禁链；兼容性工作流覆盖配置档安装冒烟测试）。 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 后端 | OpenTelemetry OTLP/HTTP（trace + 指标，JSON 编码）和 Langfuse（LLM 可观测性）—— 二选一或同时使用 |
| 模型 | 与模型无关：它导出会话/事件流，不发起任何模型调用 |

你能得到什么

dsh-observe 把 harness 的 session/event 流转成标准的可观测性协议：

- Span —— turn、step、tool-call（时长、状态、重试推导）和 LLM 生成 span，用确定性 id 串成按 turn 划分的 trace。
- 指标 —— 按服务商/模型的 token 计数器、USD 成本计数器（价格表可配置），以及来自 ctx.tokenMeter 的可选上下文压力 gauge。
- 脱敏捕获 —— 提示词和补全正文在入队或发送之前先做脱敏（结构化键名 + 内置密钥模式 + 你自己的模式）并截断。
- 可靠性 —— 异步批处理（按大小和定时器触发）、有界持久化离线缓冲（storage-domain）按最旧优先淘汰、确定性指数退避重试；投递不出去的批次在重启后仍会保留。
- 运行时开关 — 可选的 Typert 远程接口（observe/status、observe/setEnabled）让设置页能暂停和恢复导出，无需卸载。
- 默认关闭 — enabled: true 且至少配置一个后端，才算显式开启；否则不采集、不导出任何数据。

session/event stream
│ collector (turn/step/tool/llm spans, metrics)
│ sanitize (keys, secrets, budgets)
├──▶ pipeline "otlp" ── queue ── flush ──▶ OTLP /v1/traces + /v1/metrics
│ └─ retry/backoff ─┐
├──▶ pipeline "langfuse" ── queue ── flush ──▶ Langfuse ingestion
│ └─ retry/backoff ─┤
└────────── durable spool (offline buffer, bounded) ◀┘

快速开始

dsh plugin --profile web add github:PerryLink/dsh-observe

1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-observe

or from npm (published releases)
dsh plugin --profile web add dsh-observe

2. configure a backend in your profile patch (cordis.yml) and restart
dsh --profile web

最小 OTLP 配置（cordis.patch.yml 里这一行默认被注释掉）：

- insert:
- id: dsh-observe
name: dsh-observe
config:
enabled: true
otlp:
endpoint: http://localhost:4318

然后确认这一行已挂载：

dsh --profile web --dump-config | grep -A2 'id: dsh-observe'

示例

本插件不注册任何面向用户的命令；它作为后台导出器运行，通过设置来配置。

配置

所有可调项都是 Schemastery 的 Config 字段（可在 cordis.yml 中修改）。按 id 定向的覆盖会替换整行 —— 你需要把用到的每个键都重新写一遍。cordis.patch.yml 中每个键都有行内说明。

| 键 | 默认值 | 含义 |
| 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 上的发布标签 |
| langfuse.traceName | session {session} turn {turn} | trace 名称模板；{session}/{turn} 按每条 trace 插值 |
| langfuse.tags | [] | 打到每条 trace 上的静态标签 |
| langfuse.timeoutMs | 10000 | 单次请求超时 |
| capture.turns | true | 轮次生命周期 span |
| capture.steps | true | 步骤生命周期 span |
| capture.tools | true | 工具调用 span，参数与结果经脱敏处理 |
| capture.llm | true | LLM 生成 span |
| llm.prompt | true | 捕获脱敏后的请求提示词（false = 只记录大小） |
| llm.completion | true | 捕获脱敏后的补全内容（false = 只记录大小） |
| metadata.sessionId | true | 会话 id 属性 |
| metadata.cwd | false | 会话工作目录（本地路径，默认关闭） |
| metadata.agentPreset | true | 智能体预设 id 属性 |
| metadata.model | true | 服务商/模型属性 |
| metrics.tokens | true | 按服务商/模型统计的 token 计数器 |
| metrics.cost | true | 美元成本计数器（需要 pricing 规则匹配） |
| metrics.contextTokens | true | 上下文压力仪表（需要 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 | 提示词字符预算 |
| sanitize.truncateCompletionChars | 4000 | 补全内容字符预算 |
| sanitize.truncateToolInputChars | 2000 | 工具参数字符预算 |
| sanitize.truncateToolOutputChars | 2000 | 工具结果字符预算 |
| sanitize.truncateAttributeChars | 512 | span 属性字符串预算 |
| batch.maxRecords | 256 | 队列达到这么多条记录时刷新一次 |
| batch.flushIntervalMs | 5000 | 定时刷新间隔 |
| 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 远程服务（总开关） |

工具与接口

本插件不注册任何模型工具——它是后台导出器。它的接口：

- 消费 session/event（收集 span/指标）、session/flush（尽力触发导出——持久化检查点从不等待远程后端）、session/disposed。
- 可选远程服务 observe——observe/status 返回总开关状态、已配置的后端、队列深度和缓冲区占用；observe/setEnabled 在运行时停止和恢复导出。

权限与数据

- 权限：network:outbound 只放行你配置的端点，session:read 读取事件流，storage:write 写入离线缓冲区；不含原生代码，不访问文件系统。
- 数据：所有发出的内容都来自会话日志，并在排队、缓冲或传输之前完成脱敏（redaction + truncation）。离线缓冲区只存脱敏后的记录，读回时会再次校验。
- 凭据：Langfuse 的 public/secret key 只发往配置的 Langfuse 端点；OTLP headers 只发往配置的 OTLP 端点。插件本身不存凭据——请把它们放在凭据引用或环境注入的值里。

安全边界

- 默认关闭——除非你明确开启，否则不采集、不导出任何内容。
- 发送前脱敏——结构化 key 脱敏、内置密钥模式（API keys、GitHub tokens、AWS keys、bearer credentials、private keys）、你自定义的模式、字符预算，全部在记录离开内存之前生效。
- 持久化边界二次校验——从存储读回的记录会再检查一遍，之后才交给 sink。
- 失败要响，失败要兜住——导出失败会告警、计数、重试，最后落盘暂存；会话处理器抛错会被捕获并记录，可观测性永远不能打断 harness 热路径。
- 模型可见 ⟺ 已记录——prompt/completion 导出只投影会话表面（其节点 0 是 system prompt）和已记录的 header（调用配置与工具）；导出器不编造任何内容。

已知限制

- npm 0.1.7-rc.2——插件基于 @deepseek-ai/dsh@0.1.7-rc.2 开发和测试（devDeps 与 CI 的主标尺）；peer 范围 >=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 保证每条已发布线都可安装，第二标尺（typecheck:ci）加兼容性工作流覆盖更早的基线。
- 审计事件不持久化——导出器自己的 observe/ 记录只用于审计：当前宿主线上会话追加门只放行 surface 事件，所以不会有 observe/ 事件写进会话日志，插件也不会用未标记的追加去伪造一条（那会让会话读不出来）。请把 /observe 状态输出和 OTLP/Langfuse 后端当作审计面。
- 指标绕过重试/暂存路径——OTLP 指标按累积方式聚合，丢一次 flush 会在下一次自愈（这是设计，不是 bug）。
- 不做采样——每个启用的 span 族都会导出；高流量会话请设置 capture.* 开关和 batch.maxBufferRecords。

开发

pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the 0.1.7-rc.2 devDeps (no tsconfig paths)
pnpm run typecheck:ci # tsc against the published line (no paths)
pnpm run check:ruler-live # canary: must fail to compile, proving the ruler is live
pnpm test # vitest: 126 tests, 18 suites (real Context/Session/storage seam)
pnpm run test:coverage # coverage gate (90/80/90/90)
pnpm run build # tsdown bundle + tsc declarations (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:artifacts # built ESM face + bundle patch present
node scripts/check-readme-sync.mjs # five-language README sync gate
pnpm pack # the published tarball

话题标签

dsh、dsh-plugin、deepseek-harness、deepseek、cordis、observability、opentelemetry、otlp、langfuse、tracing

贡献者

- @PerryLink — 创建者与维护者：采集器、流水线、spool、OTLP/Langfuse 输出端、脱敏处理，以及五语言文档。

PerryLink DSH 插件家族

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下面的名单默认折叠，好让每份 README 的首屏都保持简短；展开即可看到每一行及其状态。

展开全部插件

| 插件 | 状态 |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| dsh-demurrage-ledger | |
| dsh-doublecheck | |
| dsh-drill-script-check | |
| dsh-eia-guide-check | |
| dsh-emergency-plan | |
| dsh-essay-rubric-check | |
| dsh-evidence-check | |
| dsh-export-ctl-check | |
| dsh-fast | |
| dsh-fmea-table-check | |
| dsh-forecast-penalty | |
| dsh-fund-research | |
| dsh-github | |
| dsh-gongwen-flow-check | |
| dsh-gongwen-word-check | |
| dsh-guard-plan-qc | |
| dsh-hazchem-check | |
| dsh-hazplan-check | |
| dsh-hidden-risk-map | |
| dsh-hs-classify | |
| dsh-icd-rule-check | |
| dsh-industry-research | |
| dsh-lawcite-adapter | |
| dsh-laya | |
| dsh-lc-doc-check | |
| dsh-learning-gap-check | |
| dsh-library | |
| dsh-local-ai | |
| dsh-lsp-actions | |
| dsh-mask | |
| dsh-mcp-panel | |
| dsh-medrec-qc | |
| dsh-memento | |
| dsh-nsfc-form-check | |
| dsh-nurse-record-check | |
| dsh-observe | |
| dsh-origin-rvc-check | |
| dsh-ota-review-check | |
| dsh-output-styles | |
| dsh-paper-doc-adapter | |
| dsh-permission-rules | |
| dsh-permit-report-check | |
| dsh-pipeline-check | |
| dsh-pleading-draft | |
| dsh-plugin-doctor | |
| dsh-plugin-guide | |
| dsh-plugin-kit | |
| dsh-plugin-upgrade | |
| dsh-policy-brief-draft | |
| dsh-power-loss-split | |
| dsh-power-ticket-check | |
| dsh-ppap-check | |
| dsh-protest-deadline | |
| dsh-railway-window | |
| dsh-repair-order-qc | |
| dsh-research-report | |
| dsh-review-reply-check | |
| dsh-rulefile-check | |
| dsh-safety-brief-check | |
| dsh-score | |
| dsh-session-sync | |
| dsh-site-log-check | |
| dsh-skill-pack-security | |
| dsh-soe-decision-check | |
| dsh-soilwater-check | |
| dsh-sop-sync-check | |
| dsh-spc-gbt-adapter | |
| dsh-talk | |
| dsh-tender-extract | |
| dsh-tender-matrix | |
| dsh-test-drive | |
| dsh-ticktick | |
| dsh-translate | |
| dsh-warranty-calc | |
| dsh-budget | 🧊 已冻结 — 见仓库 README |
| dsh-claude-move | 🧊 已冻结 — 见仓库 README |
| dsh-defend | 🧊 已冻结 — 见仓库 README |
| dsh-draw | 🧊 已冻结 — 见仓库 README |
| dsh-reach | 🧊 已冻结 — 见仓库 README |
| dsh-background-agents | 🚫 已退役 — 见仓库 README |
| dsh-session-pin | 🚫 已退役 — 见仓库 README |
| dsh-team-rooms | 🚫 已退役 — 见仓库 README |

许可证

Apache License 2.0 © 2026 dsh-observe contributors