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

📊 dsh-observe
- 1024 商店渠道：先执行一次 npm i -g dsh1024，然后执行 dsh1024 plugin --profile web add dsh-observe（计入 deepseek1024.com 安装排名）。
Gitee

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

将会话事件转换为 OTLP 追踪与 Langfuse 观测数据——经过脱敏、带缓冲、默认关闭。

License
DSH plugin
dsh-doctor
Node
CI
Version
npm version
npm downloads

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

兼容性

| 层面 | 状态 |
|---|---|
| Harness | DeepSeek Harness dsh-v0.1.6-alpha.2（适配于 2026-09-18）：会话格式 V3 将助手流嵌入 assistant/message / assistant/attempt，并将系统提示表示为表面节点 0（system/message）；本插件仅消费实时事件流，从不读取会话日志文件。对等依赖范围 >=0.1.2-rc.1 =0.1.5-alpha.1 =0.1.6-0 =24.0.0 |
| 后端 | OpenTelemetry OTLP/HTTP（追踪 + 指标，JSON 编码）与 Langfuse（LLM 可观测性）——可任选其一或同时使用 |
| 模型 | 与模型无关：它导出会话/事件流；不发起任何模型调用 |

你将获得

dsh-observe 将 harness 的 session/event 流转换为标准的可观测性协议：

- Span —— 轮次、步骤、工具调用（时长、状态、重试推导）以及 LLM 生成 span，通过确定性 id 链接为每轮次的追踪。
- 指标 —— 按提供商/模型的 token 计数器、USD 成本计数器（可配置定价表），以及来自 ctx.tokenMeter 的可选上下文压力仪表。
- 脱敏捕获 — 提示词和补全内容在进入队列或发送之前，会先经过脱敏（结构化键名 + 内置密钥模式 + 你的自定义模式）并截断。
- 可靠性 — 异步批处理（按大小和定时器触发）、有界持久化离线缓冲区（存储域）采用最旧优先淘汰策略，以及确定性的指数退避重试；无法投递的批次在重启后仍会保留。
- 运行时终止开关 — 可选的 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) ◀┘

快速开始

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

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'

安装与卸载

- 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-.tgz。
- 卸载：dsh plugin --profile web remove dsh-observe（或从 profile patch 中移除该行）。

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

配置

所有可调项都是 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 | （无） | 标记到追踪上的发布标签 |
| langfuse.traceName | session {session} turn {turn} | 追踪名称模板；{session}/{turn} 按追踪插值 |
| langfuse.tags | [] | 标记到每个追踪上的静态标签 |
| 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/metric 采集）、session/flush（尽力而为的导出触发——持久性检查点从不等待远程后端）以及 session/disposed。
- 可选远程服务 observe——observe/status 返回终止开关状态、已配置的后端、队列深度和缓冲区占用情况；observe/setEnabled 在运行时停止和恢复导出。

权限与数据

- 权限：对你配置的端点需要 network:outbound，对事件流需要 session:read，对离线缓冲区需要 storage:write；无原生代码，无文件系统访问。
- 数据：发送的所有内容均派生自会话日志，并在排队、缓冲或传输之前经过净化（脱敏 + 截断）。离线缓冲区仅存储净化后的记录，读回时会重新验证。
- 凭据：Langfuse 公钥/密钥仅传输到配置的 Langfuse 端点；OTLP 标头仅传输到配置的 OTLP 端点。插件本身不存储任何凭据——请将它们保存在凭据引用或环境注入的值中。

安全边界

- 默认关闭——除非你明确选择启用，否则不会捕获或导出任何内容。
- 发送前净化——结构化键脱敏、内置密钥模式（API 密钥、GitHub 令牌、AWS 密钥、bearer 凭据、私钥）、你的自定义模式以及字符预算，均在任何记录离开内存之前生效。
- 持久边界重新验证——从存储中读回的记录在 sink 可见之前会再次检查。
- 失败要响亮，失败要受控——导出失败会发出警告、计数、重试，最后暂存；失败的会话处理器会被捕获并记录，因此可观测性永远不会破坏 harness 热路径。
- 模型可见 ⟺ 已记录——提示/补全导出仅投射会话表面（其节点 0 为系统提示）和已记录的标头（调用配置和工具）；导出器不会凭空捏造内容。

已知限制

- npm 0.1.6-alpha.2——该插件针对 @deepseek-ai/dsh@0.1.6-alpha.2 进行开发和测试（devDeps 和 CI 的主要标尺）；peer 范围 >=0.1.2-rc.1 =0.1.5-alpha.1 =0.1.6-0 =24
pnpm run typecheck  # tsc: src + tests against the 0.1.6-alpha.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 —— 创建者与维护者：收集器、管道、暂存、OTLP/Langfuse 接收器、净化处理，以及五种语言的文档。

PerryLink DSH 插件家族

本项目是由 PerryLink 维护的 40 个 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：

| 插件 | 一句话简介 |
|---|---|
| dsh-auto-review | 审批链上的第二模型自动审查，默认故障关闭 | |
| dsh-background-agents | 持久的后台子代理，带 Web UI 侧边栏、消息传递和中断 | |
| dsh-budget | DeepSeek Harness 的成本治理：预算、碳排和延迟集于一个面板。 | |
| dsh-checkpoint-rewind | 等同于 Claude Code /rewind：快照、会话分叉、一次性恢复 | |
| dsh-claude-move | 将 Claude Code 会话、记忆、技能和 CLAUDE.md 迁移到 DSH | |
| dsh-click | 面向 DeepSeek Harness 的跨平台原生桌面控制 —— Windows 优先。 | |
| dsh-composer-history | 面向 Web 编辑器的终端风格输入历史：方向键、Ctrl+R 搜索 | |
| dsh-data-quality | 数据集质量检查与引用交叉核对（此处消费的可选数值桥接） | |
| dsh-defend | 面向 DeepSeek Harness 的提示注入、越狱与密钥泄露防御。 | |
| dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗式审查 | |
| dsh-draw | 面向 DeepSeek Harness 的统一静态图像生成路由。 | |
| dsh-fast | 面向 DeepSeek Harness 的只读性能诊断。 | |
| dsh-fund-research | 面向中国公募基金的确定性研究报告 | |
| dsh-github | 面向 DSH 的 GitHub PR/issue 集成，每次写入均需审批 | |
| dsh-industry-research | 行业研究编排，通过本插件的 ctx.researchReport.assemble 封存其交付物 | |
| dsh-library | 面向 DeepSeek Harness 的本地文档知识库。 | |
| dsh-local-ai | 面向 DeepSeek Harness 的本地模型（Ollama）集成。 | |
| dsh-lsp-actions | 基于语言服务器的 LSP 诊断、格式化、补全、代码操作与重命名 | |
| dsh-mask | PII 脱敏中间件：在模型边界匿名化，在展示层还原 | |
| dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 设置选项卡，含状态、工具与错误 | |
| dsh-memento | 需审批的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 | |
| dsh-output-styles | 等效于 Claude Code outputStyles 的运行时风格切换 | |
| dsh-permission-rules | Claude Code 风格的声明式允许/拒绝/询问权限规则，带审计 | |
| dsh-personal-directive | 带顶栏开关的个人指令注入器（框架版） | |
| dsh-plugin-guide | 作为按需智能体技能的插件开发知识库 | |
| dsh-plugin-doctor | 面向 DSH 插件的零依赖静态 + 沙箱冒烟检测器 | |
| dsh-reach | 多通道审批/提问桥接：微信/Telegram/飞书，会话控制台 |
| dsh-research-report | 可验证的研究报告引擎：内容寻址的证据账本与密封版本 | |
| dsh-score | 面向 DeepSeek Harness 插件的多维度质量评分。 | |
| dsh-session-pin | 在 Web 侧边栏中固定会话，并保持持久排序 | |
| dsh-session-sync | DeepSeek Harness 的跨设备会话同步——你的会话存储的专用 git 镜像。 | |
| dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖与供应链审查 | |
| dsh-talk | DeepSeek Harness 的语音优先会话循环：对它说话，听它回答。 | |
| dsh-test-drive | 面向 DeepSeek Harness 插件的隔离式安装与冒烟测试试驾。 | |
| dsh-ticktick | TickTick/滴答清单任务桥接：会话头部面板 + 11 个工具 | |
| dsh-translate | 面向 DeepSeek Harness 的供应商参数翻译与确定性 JSON 修复。 | |
| dsh-wechat | 微信 ↔ DSH 桥接（腾讯 iLink 机器人）：文本/图片/文件/语音，在聊天中审批 | |
| dsh-autotier | 自动进行强/廉价模型层级路由，具备确定性风险防护和 /tier 命令 | |
| dsh-catalog | PerryLink 系列的 DSH Desktop Market 标准目录源 | |
| dsh-cert-mcp | 只读 MCP 服务器，公开认证注册表：等级、快照和五维证据 | |
| dsh-kit | 一键安装核心系列入门包 | |
| dsh-plugin-certification | 社区认证注册表，提供可复现检查的等级和徽章 | |
| dsh-plugin-kit | 面向 PerryLink DSH 插件的共享零运行时依赖工具包 | |
| dsh-plugin-portal | 零依赖静态门户，将整个插件系列渲染为一个页面 | |
| dsh-plugin-upgrade-015 | 合并的 0.1.3-alpha.1 → 0.1.5-rc.1 升级通道卡片，外加零依赖接缝扫描器 | |
| dsh-team-rooms | 跨会话团队房间：共享消息总线、任务板和时间线 | |

从 DSH Desktop Market 安装

所有 PerryLink 插件都可以在内置的 DSH Desktop Market 中浏览：Market → Sources → add source → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选择它。安装仍需通过 Market 的 npm 身份验证和你的确认。

许可证

Apache License 2.0 © 2026 dsh-observe contributors