dsh-token-budget — DSH 自定义插件示例

一个完整的 DSH（DeepSeek Harness）自定义插件：统计每个会话的累计 token 用量（K/M 紧凑格式）、缓存命中率、当前模型，并按模型单价估算花费。 同时作为"如何写 DSH 插件"的参考实现。

它做了什么

1. 注册一个会话投影单元 tokenCost：从会话日志的 assistant/message 事件（携带 provider 上报的 usage）折叠出全日志总量 （输入/输出/缓存读/缓存写 token + 估算金额 + 缓存命中率 + 模型）。 Web UI 通过投影通道实时读取（事件推送，无需刷新页面）。
2. 注册一个模型工具 token_cost_report：agent 自己可以调用它查询当前 会话的用量、命中率、模型与金额（从持久化日志尾部重放，无插件可变状态）。
3. 双面 UI 半区（lib/client.js）：把花费徽标注册进会话头部 conversation.session.header.actions 插槽，显示如 19.2M tokens · 缓存命中 98% · ≈0.91 CNY。

按模型计价

request/context 事件在模型切换时记录 provider/model；投影按事件顺序 fold，每条请求的用量增量用当时生效的模型单价计价后累加——会话中途 切换模型，后续请求自动用新价格，历史请求保持原价，与真实账单一致。

文件结构

dsh-token-cost/
├── package.json          # 包元数据 + 依赖 + dsh.client 双面声明
├── UI-SLOTS.md           # 插槽系统说明
└── lib/
    ├── index.js          # 宿主半区（name / inject / Config / apply）
    ├── client.js         # 浏览器半区（UI 徽标 + 插槽注册）
    └── types/
        ├── index.d.ts    # 宿主类型声明
        └── client/
            └── index.d.ts

按模型 × 按时段计价（自动切换）

DeepSeek 于 2026-08-17 00:00（北京时间） 从固定价切换为峰谷定价 （高峰 09:00-12:00、14:00-18:00，其余空闲半价）。插件为每个模型配置 三档价格（legacy / peak / offPeak），每条请求按自己发生时刻的 模型与时段计价：

• 8/17 之前 → 一律 legacy 价；
• 8/17 之后 → 高峰时刻用 peak 价，空闲时刻用 offPeak 价；
• 会话中途跨过切换点/切换模型 → 历史保持原价，后续自动用新价， 与真实账单一致（增量计价，绝不重算历史）。

官方价格（DeepSeek API 定价）：

| 模型 | 时段 | 缓存命中输入 | 未命中输入 | 输出 | |---|---|---|---|---| | v4-flash | legacy | 0.02 | 1.0 | 2.0 | | v4-flash | 高峰 | 0.10 | 3.0 | 9.0 | | v4-flash | 空闲 | 0.05 | 1.5 | 4.5 | | v4-pro | legacy | 0.025 | 3.0 | 6.0 | | v4-pro | 高峰 | 0.30 | 9.0 | 27.0 | | v4-pro | 空闲 | 0.15 | 4.5 | 13.5 |

安装与启用

本插件是 bundle（package.json 声明了 dsh.bundle），安装后配置层 自动激活，无需手动写 patch：

# 本地路径
dsh plugin --profile web add D:\projects\ds-harness-base\dsh-token-cost
# 或 npm 发布后（推荐给用户）
dsh plugin --profile web add dsh-token-budget
# 或 GitHub 直装（需要 prepare 脚本 + 用户 allowBuilds 授权）
dsh plugin --profile web add github:you/dsh-token-budget

检查合并后的配置树（应看到 # == dsh-token-budget 层）：

dsh --profile web --dump-config

最后重启 dsh web 生效。bundle 自带 DeepSeek 官方默认价格（见包内 cordis.patch.yml）；用户想覆盖时，在自己的 profile cordis.patch.yml 按 id 覆盖（整段 config 替换，不会合并）：

- id: token-cost
  config:
    currency: CNY
    newPriceEffectiveAt: "2026-08-17T00:00:00+08:00"
    peakHours: [[9, 12], [14, 18]]
    prices:
      deepseek-v4-flash:
        legacy:  { input: 1.0, cacheRead: 0.02, cacheWrite: 1.0, output: 2.0 }
        peak:    { input: 3.0, cacheRead: 0.10, cacheWrite: 3.0, output: 9.0 }
        offPeak: { input: 1.5, cacheRead: 0.05, cacheWrite: 1.5, output: 4.5 }
      deepseek-v4-pro:
        legacy:  { input: 3.0, cacheRead: 0.025, cacheWrite: 3.0, output: 6.0 }
        peak:    { input: 9.0, cacheRead: 0.30, cacheWrite: 9.0, output: 27.0 }
        offPeak: { input: 4.5, cacheRead: 0.15, cacheWrite: 4.5, output: 13.5 }
    defaultPrice:
      legacy:  { input: 1.0, cacheRead: 0.02, cacheWrite: 1.0, output: 2.0 }
      peak:    { input: 3.0, cacheRead: 0.10, cacheWrite: 3.0, output: 9.0 }
      offPeak: { input: 1.5, cacheRead: 0.05, cacheWrite: 1.5, output: 4.5 }

发布

# npm 发布（先注册 https://www.npmjs.com/signup，然后 npm login）
npm publish

# 或先本地验证发布内容
pnpm pack   # 检查 Tarball Contents 是否包含 lib/ + cordis.patch.yml + README

GitHub 直装注意：pnpm ≥10 默认拒绝运行 git 依赖的 prepare 脚本，用户需 在 profile 的 pnpm-workspace.yaml 加 allowBuilds: { dsh-token-budget: true } 后重新 add。

插件开发要点（DSH 是基于 cordis 的插件系统）

| 概念 | 说明 | |---|---| | profile | $DSH_HOME/profiles/<name>，一个插件的组合；web、headless 是内置 profile | | bundle | 组合包（如 dsh-base、dsh-web-app），各自带 cordis.patch.yml 贡献一行行插件 entry | | patch 层 | 配置树按序叠加：bundle patches → profile cordis.patch.yml → home 级 → --patch 覆盖 | | entry | { id, name, config, disabled, inject }，name 是插件模块说明符 | | 函数插件 | 导出 name + apply(ctx, config)；inject 声明所需服务，Config 校验配置 | | 服务插件 | class X extends Service，ctx.provide(...)，其他插件经 ctx.x 调用 | | 工具插件 | ctx.tools.register(defineTool({ name, parameters, execute, ... }))，模型可调用 | | 命令插件 | ctx.commands.register({ name, description, handler })，用户 /command 调用 | | 投影单元 | ctx.sessionProjections.register({ key, schema, init, apply, view })，UI 读会话统计 | | 事件 | ctx.on("session/event", (session) => ...) 等 cordis 事件 |

安装插件用 dsh plugin --profile <name> add <pkg>（转发 pnpm）；卸载用 remove。查看合并配置用 --dump-config / --dump-default-config。

参考实现（官方，可照抄模式）

• @deepseek-ai/dsh-token-meter — 服务 + 投影单元（与本文插件同域）
• @deepseek-ai/dsh-session-stats — 纯投影单元
• @deepseek-ai/dsh-tool-todo — 工具 + 投影单元
• @deepseek-ai/dsh-command-compact — 命令插件