vibeinging/dsh-trace

English | 中文

dsh-trace 将 DeepSeek Harness 会话遥测存入本地嵌入式 yiTrace 数据库。它观察宿主 telemetry/record waterfall 处理后的记录，把每个 DSH 轮次投影为一条 yiTrace trace，并通过 yiTrace 的 Node-API 数据库写入 SDK 原生的开始、日志和结束事件。无需 HTTP 服务器、端口或 token。该插件需要主动启用，不会增加模型可见上下文，并独立于 DeepSeek Harness monorepo。

功能

• 嵌入式本地存储：直接通过 @yitrace/db 写入；无需 HTTP 服务、端口或访问 token。
• agent（智能体）的完整 trace 树：每个 DSH 轮次记录一条根 trace，其下是模型步骤 span，每个步骤下再记录工具调用 span。
• 调试上下文：保留模型身份、token 用量、消息和工具输入／输出、错误状态，以及轮次内的通用日志事件。
• 生命周期恢复：标记从轮次中途开始的 trace，将未完成 span 标记为失败并关闭，在自然边界 flush，并在数据库重新打开时恢复已提交数据。
• 本地查询：针对所配置目录提供 yiTrace trace、span、全文搜索和聚合 API。

本插件不提供查看器或内置脱敏规则。请使用兼容 yiTrace 的本地工具或 @yitrace/db 查询 API 检查所配置数据目录中的内容。

使用场景

• 重建一个 agent 轮次，查看哪个模型步骤或工具调用导致失败。
• 开发提示词或工作流时，对比 token 用量、模型输出和工具行为。
• 搜索本地历史 trace，查找重复错误消息、工具结果或会话属性。
• 不需要或不允许 HTTP 遥测服务时，将可观测性数据保留在同一台机器上。

前提

• Node.js ^22.19.0 || >=24.0.0 和 pnpm 11.7.0。
• 一个可写的 yiTrace 本地数据目录。
• 可读取私有插件仓库的 Git 凭据。
• 提供 Session Telemetry 和 invariant service 的兼容 DSH web 或 headless profile。

本包为私有包，不会发布到 npm registry。仓库中已提交的 lib/ 运行时允许从私有 GitHub 仓库安装固定的 commit，不会针对未发布的 DSH 对等依赖执行依赖构建。DSH Profile 是 pnpm workspace 根目录，因此安装命令必须包含 -w。

快速上手

bundle 会禁用 DSH 自带的 OTLP 遥测后端，并用本地嵌入式 yiTrace 取代它。它可能存储用户和 assistant 文本、推理、工具参数与结果、会话 id 以及所配置的身份。请先确认本地保留和脱敏策略可接受，再启动该 profile。

1. 选择一个绝对本地数据目录：

export DSH_TRACE_DATA_DIR=/absolute/path/to/dsh-traces
export DSH_TRACE_TENANT_ID=1
mkdir -p "$DSH_TRACE_DATA_DIR"

2. 直接从私有 GitHub 仓库安装已审查的 commit：

dsh plugin --profile web add -w github:dsh-external/dsh-trace#<reviewed-commit>

本包的 dsh.bundle.patch 会禁用 telemetry-otel，加载 dsh-trace（数据目录来自 DSH_TRACE_DATA_DIR），并加载配套的 invariant 插件。使用同样的命令并指定 --profile headless，即可为该独立 profile 启用插件。

3. 启动 profile 前检查组合后的配置，然后启动 DSH：

dsh --profile web --dump-config
dsh --profile web

配置输出必须显示 telemetry-otel 已禁用，并包含 dsh-trace 和 dsh-trace-invariant。每个已完成轮次都会存入 DSH_TRACE_DATA_DIR；shutdown 还会关闭未完成的 span 并 flush 数据库。使用 dsh plugin --profile web remove -w @deepseek-ai/dsh-trace 移除 bundle。

4. DSH 释放数据目录后，使用 @yitrace/db 检查 trace：

import { YiTraceDB } from '@yitrace/db'

const dataDir = process.env.DSH_TRACE_DATA_DIR
if (!dataDir) throw new Error('DSH_TRACE_DATA_DIR is required')

const tenantId = process.env.DSH_TRACE_TENANT_ID
const database = await YiTraceDB.open({
  dataDir,
  ...(tenantId ? { tenantId } : {}),
})

try {
  const traces = await database.traces()
  console.dir(traces, { depth: null })

  const first = traces[0]
  const traceId = first?.externalTraceId
    ?? first?.external_trace_id
    ?? first?.traceId
    ?? first?.trace_id
  if (traceId !== undefined) {
    console.dir(await database.trace(traceId), { depth: null })
  }

  console.dir(await database.search({ text: 'tool process exited' }), { depth: null })
} finally {
  await database.close()
}

写入和读取必须使用相同的 tenantId。示例 profile 写入 tenant 1；运行查询脚本前，请设置 DSH_TRACE_TENANT_ID=1。

配置参考

字段	必填项或默认值	用途
database.dataDir	必填	本地 yiTrace 目录。插件加载时，相对路径从进程工作目录解析；服务部署请使用绝对路径。
database.tenantId	可选	写入时附加的 64 位无符号 tenant 作用域。查询时使用相同值。
database.maxBuffered	batchSize × 16	嵌入式 ingest 失败后保留在内存中的最大事件数；超过限制后丢弃最旧事件。
batchSize	256	每次串行嵌入式 ingest 前收集的事件数。
nodeId	由 yiTrace 派生	0..1023 范围内的 Snowflake 节点 id。并行写入方不得共用显式值。
agentName	Harness 产品身份	附加到每个 span 的 agent 名称。
shutdownTimeoutMillis	3000	DSH 等待关闭的最长时间。截止时间无法取消正在执行的原生数据库调用。

数据目录为空、64 位无符号 tenant id 无效、节点 id 无效，或大小／截止时间不是正数，都会使插件在加载时失败。

遥测 seam 在每个 Cordis 上下文中只允许一个后端。同时加载本包与 session-telemetry-otel 时，会因服务重复而失败，不会重复记录。宿主级隐私开关必须禁用每一条已配置的遥测项；该插件不会绕过这项宿主策略。

验证与 CI

项目 .npmrc 选择私有 @deepseek-ai/* scope；pnpm 11 使用 ${NPM_TOKEN} 认证映射，该映射来自受信任的用户级 ~/.npmrc。请设置 NPM_TOKEN，然后运行 pnpm install --ignore-scripts。SDK 包固定为经过评审的 0.0.1-rc.2 版本组。不要将 DSH 源码链接或 checkout 到本仓库。pnpm run check 会检查仓库边界、运行源码 lint 和严格类型检查、针对真实嵌入式数据库和真实 YAML Loader profile 执行 7 个测试、构建生产入口、运行 publint 且不创建 tarball，并用纯 Node 导入构建后的入口。CI 会将 NPM_TOKEN secret 映射到 setup-node 的受信任用户配置。

Trace 映射

DSH 来源	yiTrace 投影	重要字段
turn/start … turn/end	一个根 dsh.turn span 和一条 yiTrace trace	DSH 会话 id、轮次编号、结束原因、状态
step/start … step/end	子 dsh.step span	提供方、模型、token 用量、最新系统提示词、该后端实例观察到的已脱敏消息历史、assistant 输出
tool/call … tool/result	子 tool.<name> span	调用 id、工具名称、参数、结果、错误状态
已打开轮次内的其他账本事件	已打开步骤或轮次上的 yiTrace 日志事件	事件类型、来源 seq、已脱敏 body
agent-error	错误日志，并将已打开的步骤／轮次标记为失败	规范化的错误名称和 body
shutdown	将仍处于打开状态的所有 span 标记为失败并关闭，再 flush 并关闭数据库	不创建合成的独立 span

适配器保留来源事件的时间戳，并根据其毫秒时间计算 span 持续时长。确定性事件 id、批处理和协议编码由 @yitrace/trace-sdk 负责；嵌入式预写式日志、恢复、持久读取模型和查询由 @yitrace/db 负责。DSH 的字符串会话 id 通过确定性的 FNV-1a 64 位哈希映射为 yiTrace 的数值 session_id；原始 id 仍保留在 dsh.session.id span 属性中。

数据与可靠性边界

每条记录都先经过 seam 的 telemetry/record waterfall（瀑布式事件），随后该后端才会读取。用户与 assistant 文本、推理（reasoning）、工具参数／结果、通用事件 body、会话 id，以及配置的 agent（智能体）／tenant 身份都可能存入 database.dataDir。seam 不附带任何脱敏规则，因此不得保留原始敏感值的部署必须先挂载自己的规则，再启用 yiTrace。数据始终留在所配置的目录中；该插件不会打开网络连接。

emit() 会创建 yiTrace SDK 事件并将其加入内存队列。轮次／会话 flush 提示会串行执行：每次排空 BatchExporter，重试有界的嵌入式写入缓冲区，再 flush 数据库。资源释放会关闭尚未完成的 span，排空同一条队列，flush yiTrace 的持久状态，并在配置的截止时间内关闭数据库。进程突然崩溃仍可能丢失尚未到达嵌入式数据库的事件；已经提交的 yiTrace 数据会在重新打开该目录时恢复。

模型体验

无，因为该插件只观察日志写入后的会话记录，绝不更改模型请求、工具 schema 或响应。

KV Cache 影响

无；本包既不组装也不发送提供方请求。

已知限制与延期工作

• 私有 Git 分发：本包不会发布到 registry。安装需要经授权的 GitHub 访问权限、pnpm 11.7.0、已审查的 commit 和兼容的 DSH profile。
• 数据库是原生依赖：@yitrace/db 目前为 macOS arm64／x64、glibc Linux arm64／x64 和 Windows x64 提供预构建包。本包当前的 lockfile 不覆盖其他操作系统、CPU 目标和 musl Linux。
• 只有一种本地存储模式：该插件刻意不提供 HTTP 后端或跨机器传输。并发运行的 DSH 进程应使用各自独立的可写数据目录，除非 yiTrace 数据库已为该部署明确记录共享写入方配置。
• 遥测重载会分隔状态：资源释放会将已打开的 span 标记为失败并关闭，同时重置适配器的消息累积器。后续带位置的事件（turn/step）会打开一个标记为 dsh.recovered_segment 的 span；其输入只包含该后端实例加载后观察到的已脱敏消息事件。单独一条 user/message 的 payload 中没有位置信息，无法自行重建缺失的步骤。
• 哈希后的会话身份：yiTrace 的 TypeScript SDK 接受数值 session_id，而 DSH 持有不透明字符串 id。FNV-1a 使映射保持稳定，但理论上仍存在 64 位碰撞风险；未来 SDK 若提供字符串 id 接口，就能消除这一折中。