D0cx0011/dsh-turn-tokens

dsh-turn-tokens

在 DeepSeek Harness 的 Web 界面里看清每一轮对话花了多少 token、钱花在哪、一次请求由什么组成。

一个 host + client 双半边的 Web 插件。它只读本机的会话日志与官方会话投影：不联网、不需要 API Key、不上传任何数据。

- 它解决什么
- 功能
- 安装
- 指标口径
- 价格口径
- 数据来源与隐私
- 兼容性与版本要求
- 维护
- 已知限制
- 许可

它解决什么

内置的统计只给一个总数。这个插件回答三个更具体的问题：

1. 每一轮（turn）实际消耗了多少 —— 未缓存输入 / 缓存读 / 输出 / 推理，来自 provider 上报的用量，是精确值；并给出该轮金额。
2. 一次请求由什么组成 —— 系统提示逐段、工具 schema 逐项、消息体分类，各自多少 token。
3. 这些内容从哪来 —— 每段系统提示来自哪个提示节或哪个文件（含绝对路径）；user 角色里那些不是你打的字的注入消息各自来自哪里。

功能

输入框右侧的指示器

一个紧凑控件，显示 ● 上下文 N%。圆点颜色即状态：绿（）会被解析成绝对路径，相对路径用会话工作目录拼接。同一来源经历的「注入 → 更新 → 移除」按来源分组，折叠行显示最新状态。

安装

本插件使用 web profile（dsh web 就是 dsh --profile web）。三种安装方式都适用。

| 前置 | 说明 |
|---|---|
| Node | 随 DSH 提供，无需另装 |
| pnpm | 只有方式一需要，且必须在 PATH 上 |

方式一：dsh plugin（推荐）

本包尚未发布到 npm，因此用仓库地址或本地路径安装：

A. 从 GitHub 直接安装
dsh plugin --profile web add github:D0cx0011/dsh-turn-tokens

B. 先克隆，再从本地路径安装
git clone https://github.com/D0cx0011/dsh-turn-tokens.git
dsh plugin --profile web add file:./dsh-turn-tokens

dsh plugin 是官方 CLI，它把剩余参数转发给 profile 目录下的 pnpm。本包在 package.json 里声明了 dsh.bundle.patch，所以命令跑完后 DSH 会按已安装状态核对：声明了 dsh.bundle 的依赖被自动追加进 profile 的 dsh.profile.bundles，本包自带的 cordis.patch.yml 随之作为一层 bundle patch 生效——无需手工编辑任何配置文件。

两个需要注意的前置：

- 必须先有 pnpm。 dsh plugin 只是 pnpm 的转发器；PATH 上没有 pnpm 时它会报 pnpm not found on PATH 并返回退出码 127。
- 用 git 规格安装要留意构建授权。 pnpm 会为 git 依赖执行 prepare 脚本，默认被拦截并导致安装失败；若遇到，按提示把打印出的 key 加进 /pnpm-workspace.yaml 的 allowBuilds 再重试。本包是纯 JS、没有 prepare 脚本，通常不会触发；上面的 B（file: 规格）不走这条路径，最稳。

方式二：本仓库附脚本（无 pnpm / 离线）

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -Uninstall

脚本会自动探测 profile，也可显式指定：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -Profile web
落点：把包复制到 \node_modules\dsh-turn-tokens\，并把挂载行追加到同 profile 的 cordis.patch.yml（改动前自动生成带时间戳的备份）。

这里用 powershell 而不是 pwsh：Windows PowerShell 5.1 一定存在，pwsh（PowerShell 7）通常没有。脚本刻意只用 ASCII 编写，以避开 5.1 读中文脚本时的编码陷阱。

方式三：完全手工（不依赖任何脚本）

等价于方式二，适合想自己控制每一步的情况：

1. 把本包的 package.json、lib\、cordis.patch.yml 复制到
%DSH_HOME%\profiles\\node_modules\dsh-turn-tokens\
2. 在 %DSH_HOME%\profiles\\cordis.patch.yml 末尾追加：

- insert:
- id: turn-tokens
name: 'dsh-turn-tokens'

profile 根目录的 cordis.yml 里写着 "Edit cordis.patch.yml, not this file"——要改的一直是 cordis.patch.yml。

三种方式不要混用

方式一把包登记为 bundle 层，方式二/三往 用户 patch 层写同一条挂载行。两者引用同一个 id: turn-tokens，同时使用会让同一个入口被插入两次。已经手工装过就先别用方式一；要改走方式一，先用 -Uninstall 清掉那条挂载行。

安装后自检

推荐先跑这条——它不需要 pnpm，也不需要插件本身跑起来：

dsh --profile web --dump-config     # 打印合成后的配置树，找 turn-tokens 行

配置树里出现下面两行，就说明挂载成功：

- id: turn-tokens
name: dsh-turn-tokens

其余可选手段：

- 用方式一安装、且 pnpm 可用时，可确认依赖：dsh plugin --profile web why dsh-turn-tokens
- 本仓库的 node scripts/verify-install.mjs 会检查 package.json 契约、挂载行与 client 半边是否齐备，同样不需要 pnpm。

生效规则（重要）

| 改动位置 | 生效方式 |
|---|---|
| client 半边（lib/client.js，界面与价格） | 宿主会重新打包前端 bundle，刷新页面即生效 |
| host 半边（lib/index.js，日志解析与路由） | 模块被 loader 缓存，必须重启 DSH Web 服务 |

安装后请刷新页面；若指示器未出现，再重启服务。

依赖的官方契约

本插件只使用 DSH 的公开契约，不依赖任何对 DSH 源码的修改：

| 契约 | 用途 |
|---|---|
| dsh plugin --profile  … | 官方 CLI，安装入口 |
| package.json 的 dsh.bundle.patch | 由 @deepseek-ai/dsh-app-boot 读取，决定本包的 patch 层 |
| profile 的 cordis.patch.yml | 官方指定的用户 patch 层 |
| 客户端槽位 conversation.input.right | 由官方 @deepseek-ai/dsh-client-ui-conversation 定义 |
| tokenUsage / contextPressure / contextBreakdown 投影 | 官方会话投影 |

如果你改过 DSH 源码、而指示器始终不出现，请先按上面的自检命令确认挂载行与包是否真的进入了配置树——"没挂上"和"挂上了但没渲染"是两类不同的问题，先分清再排查。

指标口径

会话累计用量与每轮明细（精确）

来自 provider 每次调用上报的用量，逐轮累加。换算关系：

合计 = 未缓存输入 + 缓存读 + 输出          （不含推理）

| 指标 | 含义 |
|---|---|
| 未缓存输入 | 未命中前缀缓存的输入 token，最贵的一项 |
| 缓存读 | 命中缓存被复用的输入 token。是所有调用的累计读入量，不等于上下文大小 |
| 缓存写 | 写入缓存的部分；部分 provider 不上报，通常为 0 |
| 输出 | 模型生成的 token |
| 推理 | 思考 token。它含在输出的计费里，因此不单独计价，表内标为「含于输出」 |
| 调用 | 该轮的 API 调用次数 ≈ 步数（一次工具调用 ≈ 一次额外调用） |

为什么缓存读能远超上下文窗口：一轮里常有几十次 API 调用，每次都要重发整段前缀，每次都计入缓存读。它是累计读入量，不是上下文大小。

上下文压力与组成（宿主投影）

| 指标 | 精度 |
|---|---|
| 当前 prompt / 窗口上限 | 精确（provider 上报） |
| 下次请求预估 | 估算 |
| 系统提示 / 工具 schema / 消息体 | 启发式 |

分段与逐项（本插件解析）

system 分段按空行切分；工具 schema 逐项、消息体分类均按字符估算。估算口径：ASCII ≈ 4 字符/token，中文 ≈ 1.5 字符/token，只用于相对比较与排序，不要当作账单。

「上下文组成」的三分类合计不会等于上面的精确用量——一个算"组成"，一个算"计费"。

价格口径

每轮明细的每一格显示为 tokens/¥金额，合计列给出该轮总价；底部的合计行也逐列给出金额。

定价以官方页面为准：

| 项（元/百万 tokens） | deepseek-flash 空闲 | 高峰 | deepseek-v4-pro 空闲 | 高峰 |
|---|---|---|---|---|
| 输入（缓存命中） | 0.02 | 0.04 | 0.15 | 0.30 |
| 输入（缓存未命中） | 1 | 2 | 4.5 | 9.0 |
| 输出 | 4 | 8 | 13.5 | 27.0 |

- 峰谷规则：高峰 = 北京时间周一至周五 9:00-12:00、14:00-18:00，其余空闲（空闲价 = 高峰价的一半）。每轮按它自己开始时刻的档位计价。
- 模型名映射：官方现行模型名是 deepseek-flash，对应模型版本 DeepSeek-V4.1-Flash（支持文本 + 图像）；旧名 deepseek-v4-flash、deepseek-v4-flash-vision-exp 已下线，仍可调用但由 V4.1-Flash 提供服务、按 Flash 价格计费（历史轮次的日志里记的就是这些旧名，插件仍能计价）。deepseek-v4-pro 仍是独立在售模型，按 Pro 价计费。
- 推理不单独计价，理由见上文。
- 未匹配到价目表就只显示 token，不显示价格 —— 不猜。
- 合计行各列的金额是逐轮累加出来的：各轮时段可能不同，所以未缓存输入 / 缓存读 / 输出 三列都按「这一轮的用量 × 这一轮自己的单价」分别算完再相加，三列之和恰好等于最后一列的总价。悬停合计行可以看到这条口径说明。

价格是估算，不等于官方账单；官方保留调价权利，请定期核对上面的定价页。

数据来源与隐私

- 只读：仅读取本机的会话日志、设置文件与少量候选文本文件，不写入、不删除任何被统计的数据。
- 不联网：插件自身不发起任何网络请求；面板里的官方定价链接只是文本。
- 不上传：无遥测、无第三方运行时依赖；host 半边只使用 Node 内置模块。
- 面板会显示提示内容：为了给出“来源”与“完整原文”，面板会展示系统提示段落与注入消息的正文。这些内容本来就在你的会话里，插件只是把它们显示出来。

兼容性与版本要求

验证环境：DSH 0.1.2-alpha.1（日志格式 v0）与 0.1.5-rc.1（日志格式 v3），Windows / PowerShell 5.1。

两代日志格式都支持：0.1.5 起 DSH 把会话日志从 v0 推到 v3 —— 文件名从 session.jsonl.zstd
变成 session.v3.jsonl.zstd，system prompt 也从 request/header.header.system 改成了
system/message 事件流。本插件两代都认（实现上是“两代都试、谁有内容用谁”），你不需要切换任何开关。
报告里的 log.format 与 systemSource 会显示实际读到的是哪一代。

本插件的实现依赖宿主契约，下列契约变动即可能出问题。按症状排查最快：

| 依赖的契约 | 失效症状 | 现有兜底 |
|---|---|---|
| 会话日志路径 $DSH_HOME/sessions//session-/session[.vN].jsonl[.zstd] | 提示“找不到会话日志” | 按 session-* 目录扫描；文件名两代都认（v0 无版本段、vN 带版本段），取版本最高 |
| 日志是多帧 zstd | 只读到最早的一部分，轮次缺失 | 按 zstd magic 切帧逐帧解压，单帧失败不影响其余 |
| 记录类型 session / turn/start / request/header / request/context / system/message / assistant/message / user/message / tool/result | 对应区块为空 | 所有字段访问都带保护，缺失即跳过 |
| 用量字段名 inputTokens / cacheReadTokens / outputTokens / reasoningTokens / totalTokens | 每轮用量静默显示为 0（最危险） | ⚠️ 无兜底：改名不会报错，只会变 0 |
| system prompt 的载体：v0/v1 在 request/header.header.system，v2/v3 在 system/message 事件流 | system 段为空或大面积“未识别” | 两代都试、谁有内容用谁；systemSource 显示实际用了哪一代；事件流按 surface 语义重放 |
| request/header 的 tools / config | 工具列表或模型信息为空 | 有存在性检查（两代都在，v3 只退休了 system） |
| 会话投影名 tokenUsage / contextPressure / contextBreakdown | 面板顶部对应数字消失（显示 —） | 有类型检查，缺失即不渲染 |
| 槽位名 conversation.input.right | 指示器完全不显示 | ⚠️ 无兜底：槽位不存在时控件被静默丢弃（该槽位是官方契约，定义见官方 Web Client Slots 文档） |
| 客户端模块契约 window.__ModuleLoader__.load / require("react") / exports.inject / ctx.slots.register | 前端 bundle 报错或控件不出现 | ⚠️ 无兜底 |
| 提示装配接口返回 { sections: [{ name, text }] } | 节名归因失效 | ✅ 退化为文件比对与文本特征规则 |
| agent/created 事件载荷 | 只能用全局作用域的提示节 | ✅ 退回全局上下文 |
| 日志里的会话 cwd 字段 | 相对路径无法拼成绝对路径 | ✅ 只显示声明的相对路径 |
| 官方定价与模型名 | 价格不显示（token 照常） | ✅ 未匹配即不显示，不猜 |
| React 主版本 | 组件渲染异常 | peer 范围已放宽到 ^18 \|\| ^19 |

排查顺序建议：

1. 指示器不显示 → 先刷新页面，再确认槽位名是否仍存在
2. 面板能开但数字为空 → 检查会话投影名
3. 每轮全是 0 → 优先怀疑用量字段名变了（这类变化不报错）
4. 轮次缺几轮 → 检查日志是否仍是多帧 zstd
5. 来源大面积“未识别” → 检查提示装配接口的返回结构，以及候选文件是否可读

升级适配提示：若宿主整体重构了会话日志或投影语义（例如把用量移到新的记录类型），需要同步修改 lib/index.js 的解析段；界面与价格部分通常不受影响。

升级时怎么排查：日志格式或投影语义的变动集中在 host 半边（会话定位与 system/message 重放），
client 半边与官方投影契约通常不受影响。scripts/formattest.mjs 就是为这类升级准备的：
它在临时目录里合成两代日志，不碰真实会话，升级 DSH 后先跑它，再用 selftest.mjs 对真实数据。

维护

价格维护

以官方定价页为准（见上）。修改点集中在 lib/client.js：

| 位置 | 作用 |
|---|---|
| PRICING | 三档单价表（按模型 × 峰谷） |
| PRICING_ALIAS | 旧模型名 → 价目表键 |
| periodNow() | 峰谷判定（北京时间） |
| cost() / money() | 计价与金额格式化 |

改完刷新页面即可生效（价格表在 client 半边）。

验证脚本

node scripts/selftest.mjs         # host：模拟宿主上下文跑通路由，输出真实的每轮与归因结果
node scripts/formattest.mjs       # 日志格式两代（v0/v3）：system 载体、文件名、surface 重放
node scripts/clienttest.mjs       # client：模拟模块加载器与槽位，真渲染指示器、面板与价格列
node scripts/verify-install.mjs   # 安装后必跑：配置 YAML 合法性 + 包解析 + 模块加载

第 4 个尤其重要：profile 配置语法错误会让整个 Web 界面起不来，不只是本插件。
formattest.mjs 全程使用临时 DSH_HOME，不读也不写任何真实会话数据，升级宿主后可放心先跑它。

目录结构

dsh-turn-tokens/
├── package.json            插件清单（dsh.bundle / dsh.client 声明）
├── cordis.patch.yml        自注册补丁（安装机制读它）
├── lib/
│   ├── index.js            host 半边：日志解析 + 来源归因 + HTTP 路由
│   └── client.js           client 半边：指示器 + 面板 + 价格计算
├── scripts/
│   ├── install.ps1         安装 / 卸载（纯 ASCII，避免编码问题）
│   ├── sync-profile.ps1    同步到已装 profile 的副本（hard link 断裂时用，纯 ASCII）
│   ├── selftest.mjs        host 自测（真实会话）
│   ├── formattest.mjs      日志格式两代自测（合成日志，不碰真实数据）
│   ├── clienttest.mjs      client 自测
│   └── verify-install.mjs  安装校验
├── docs/DEVELOPMENT.md     开发文档：架构、契约与验证方法
├── README.md / README.en.md
└── LICENSE

改代码前请先读 docs/DEVELOPMENT.md，架构、契约与设计取舍都在里面。

已知限制

- 只覆盖当前会话：不做跨会话账本、余额、账单与预算。
- 子代理只统计直接子代理（日志里 parentSession 指向本会话的那些）；子代理再派生的孙代理不并入，它们各自挂在父代理名下。
- 面板为表格与条形，不含趋势图。
- 每轮明细依赖已落盘的日志：正在进行中的那一轮要等该轮结束才完整。
- 不传会话标识时按"最近修改的会话"取，多会话并发时以最后动过的为准。
- system 分段按空行切分，是近似结构，不等于宿主内部的提示节边界。
- 消息体估算统计的是日志里全部消息文本，不等于本次请求实际携带（压缩与替换后会有偏差）。
- 价格按官方刊例价估算，不等于官方账单。

许可

MIT