PerryLink/dsh-observe

📊 dsh-observe

• 1024 商店渠道：先 npm i -g dsh1024，再 dsh1024 plugin --profile web add dsh-observe（计入 deepseek1024.com 安装排行）。

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

把会话事件变成 OTLP 追踪与 Langfuse 观测 —— 脱敏、缓冲、默认关闭。

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

---

⭐ 如果它帮到了你

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

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

Compatibility

方面	状态
Harness	DeepSeek Harness dsh-v0.1.7-rc.2（2026-09-22 已适配）：会话格式 V4 把工具结果改为 role: 'tool' 的一等消息，顶层携带 toolCallId + content + 可选 isError —— V3 的 tool-result 内容块已从宿主 ContentBlockMap 移除，本插件只读 V4 形状（升级前的 V3 日志仍可经只读兼容路径投影）。会话格式 V3 的其余特征沿用：助手流内嵌到 assistant/message / assistant/attempt，系统提示词为 surface 节点 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 保持每条已发布线可安装（本地完整门禁链；profile 安装冒烟由 compat 工作流覆盖）。
Node	^22.19.0 || >=24.0.0
后端	OpenTelemetry OTLP/HTTP（traces + metrics，JSON 编码）与 Langfuse（LLM 可观测）——二选一或同时
模型	与模型无关：它导出 session/event 流，自身不调用任何模型

What you get

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

• 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（离线缓冲，有界）◀┘

Quick start

# 1. 把 bundle 装进你的 profile
dsh plugin --profile web add "github:PerryLink/dsh-observe#main"

# 或从 npm 安装（正式发布版）
dsh plugin --profile web add dsh-observe

# 2. 在 profile patch（cordis.yml）里配置后端并重启
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'

Install & uninstall

• git 通道（最新 main）：dsh plugin --profile web add "github:PerryLink/dsh-observe#main" —— 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（或从 profile patch 中删除该行）。

如果 pnpm 对本包报 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制无害校验），在你的 pnpm-workspace.yaml 中加入 allowBuilds: { esbuild: true } —— dsh CLI 会打印确切片段。

Configuration

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

Key	Default	Meaning
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 只记大小）
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（总开关）

Tools & surfaces

本插件不注册任何模型工具 —— 它是后台导出器。其界面：

• 消费 session/event（span/metric 采集）、session/flush（尽力导出 kick —— 持久化检查点绝不等待远端后端）、session/disposed。
• 可选 remote 服务 observe —— observe/status 返回总开关状态、已配置后端、队列深度与缓冲占用；observe/setEnabled 在运行时停止/恢复导出。

Permissions & data

• 权限：对你配置的端点出网（network:outbound）、读取事件流（session:read）、写离线缓冲（storage:write）；无原生代码、无文件系统访问。
• 数据：所有外发内容都来自会话日志，并在入队、缓冲、发送前完成脱敏（脱敏 + 截断）。离线缓冲只存脱敏记录，读回时再次校验。
• 凭据：Langfuse 公钥/密钥只发往你配置的 Langfuse 端点；OTLP 请求头只发往你配置的 OTLP 端点。插件自身不存任何凭据 —— 请使用凭据引用或环境注入。

Security boundaries

• 默认关闭 —— 不显式开启则不采集、不导出。
• 发送前脱敏 —— 结构性键名脱敏、内置密钥模式（API key、GitHub token、AWS key、bearer 凭据、私钥）、自定义模式与字符预算，全部在任何记录离开内存前生效。
• 持久边界再校验 —— 从存储读回的记录在到达 sink 前再次检查。
• 失败大声、失败隔离 —— 导出失败会告警、计数、重试并最终入缓冲；会话事件处理失败被捕获并记录，可观测性永远不会拖垮 harness 热路径。
• 模型可见 ⟺ 已记录 —— prompt/completion 导出只投影会话 surface（其节点 0 即系统提示词）与已记录的 header（调用配置与工具）；导出器不发明任何内容。

Known limitations

• 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）及 compat 工作流共同覆盖。
• 审计事件不落盘 —— 本插件自身的 observe/* 记录仅作审计：当前宿主线的会话 append 闸门只接纳 surface 事件，因此不会有 observe/* 事件写入会话日志；插件也不会用未标记 append 伪造一条（那会让会话不可读）。审计面请以 /observe 状态输出与 OTLP/Langfuse 后端为准。
• Metrics 不走重试/缓冲路径 —— OTLP metrics 按累计聚合，丢失一次 flush 会在下一次自愈（设计如此，非缺陷）。
• 无采样 —— 每个启用的 span 族都会导出；大流量会话请调整 capture.* 开关与 batch.maxBufferRecords。

Development

pnpm install        # node ^22.19 || >=24
pnpm run typecheck  # tsc：src + tests，对照 0.1.7-rc.2 devDeps（无 tsconfig paths）
pnpm run typecheck:ci  # tsc：对照已发布线（无 paths）
pnpm run check:ruler-live  # canary：必须编译失败，以证明尺子仍是活的
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

Topics

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

Contributors

• @PerryLink —— 创建者与维护者：collector、pipeline、spool、OTLP/Langfuse sink、脱敏层与五语文档。

PerryLink DSH Plugin Family

This project is one of the 45 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Plugin	One-liner
dsh-auto-review	Second-model auto-review on the approval chain, fail-closed by default
dsh-autotier	Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command
dsh-background-agents	Durable background child agents with a Web UI sidebar, messaging and interrupt
dsh-budget	Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.
dsh-catalog	DSH Desktop Market standard catalog source for the PerryLink family
dsh-cert-mcp	Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence
dsh-checkpoint-rewind	Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore
dsh-claude-move	Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH
dsh-click	Cross-platform native desktop control for DeepSeek Harness — Windows first.
dsh-composer-history	Terminal-style input history for the web composer: arrows, Ctrl+R search
dsh-data-quality	Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here)
dsh-defend	Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness.
dsh-doublecheck	Engineering-discipline guard: requirements grill, test gates, adversary review
dsh-draw	Unified static-image generation routing for DeepSeek Harness.
dsh-fast	Read-only performance diagnostics for DeepSeek Harness.
dsh-fund-research	Deterministic research reports for Chinese public mutual funds
dsh-github	GitHub PR/issues integration for DSH, every write gated by approval
dsh-industry-research	Industry research orchestration that seals its deliverables through this plugin's ctx.researchReport.assemble
dsh-laya	Laya typed decisions (noul/choice/score) as a first-class Cordis service and model-visible tools
dsh-library	Local document knowledge base for DeepSeek Harness.
dsh-local-ai	Local-model (Ollama) integration for DeepSeek Harness.
dsh-lsp-actions	LSP diagnostics, formatting, completion, code actions and rename over language servers
dsh-mask	PII masking middleware: anonymize at the model boundary, restore at the display layer
dsh-mcp-panel	Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors
dsh-memento	Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool
dsh-observe	OpenTelemetry and Langfuse observability exporter for DeepSeek Harness.
dsh-output-styles	Claude Code outputStyles-equivalent runtime style switching
dsh-permission-rules	Claude Code-style declarative allow/deny/ask permission rules with audit
dsh-plugin-certification	Community certification registry with repro-checkable grades and badges
dsh-plugin-doctor	Zero-dependency static + sandbox smoke detector for DSH plugins
dsh-plugin-guide	Plugin-development knowledge base as an on-demand agent skill
dsh-plugin-kit	Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins
dsh-plugin-upgrade	One-package, one-corridor-index plugin upgrade skill: routes a repository to the matching closed corridor card
dsh-plugin-upgrade-015	Merged 0.1.3-alpha.1 → 0.1.5-rc.1 upgrade corridor card plus a zero-dependency seam scanner
dsh-reach	Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console
dsh-research-report	Verifiable research-report engine: content-addressed evidence ledger and sealed versions
dsh-score	Multi-dimensional quality scoring for DeepSeek Harness plugins.
dsh-session-pin	Pin sessions in the Web sidebar with durable ordering
dsh-session-sync	Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store.
dsh-skill-pack-security	Security-audit skill pack: secret scan, dependency and supply-chain review
dsh-talk	Voice-first session loop for DeepSeek Harness: talk to it, hear it answer.
dsh-team-rooms	Cross-session team rooms: shared message bus, task board and timeline
dsh-test-drive	Isolated install-and-smoke test drives for DeepSeek Harness plugins.
dsh-ticktick	TickTick/Dida365 task bridge: session-header panel + 11 tools
dsh-translate	Vendor parameter translation and deterministic JSON repair for DeepSeek Harness.

License

Apache License 2.0 © 2026 dsh-observe contributors

从 DSH Desktop 市场安装

所有 PerryLink 插件均可在 DSH Desktop 内置市场中浏览：市场 → 来源 → 添加来源 → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选中。安装仍需通过市场的 npm 身份校验与你的确认。