dsh-session-spend

源码：github.com/weiwang988/dsh-session-spend · 兼容 DSH 0.1.5 线（dsh-v0.1.5-alpha.1，session format v3 词表；见兼容性注记）

DSH（DeepSeek Harness）Web 客户端插件：实时显示当前会话花费（¥），按官方峰谷计价逐笔选档，悬停查看节省分解。零 host 改动，纯客户端。适配 DSH 0.1.5 线（浏览器端契约 = @deepseek-ai/dsh-client-* 0.1.5-alpha.1 线，session format v3：assistant/attempt + 内嵌 stream、transient assistant/live-chunk、llm/retry-started 槽位语义）；host 半经 sessionPersistence.open(id,'read') → handle.read()（返回 {eventState, events}）直接读取解码后的逻辑事件流（格式迁移由 DSH 的 v0→v1→v2→v3 链完成），完整会话账本同价同规则。

功能

• 会话花费：只算当前会话主对话调用——与聊天统计行的 token 账目同源且逐笔对齐（v2 规则：assistant/attempt / assistant/message 各贡献其内嵌 stream 的最后一条 usage（data.usage 优先），按 (turn, step, generation) 槽位 last-wins；llm/retry-started 开新槽，重试请求与失败请求都计入——与 token-meter 的 replacement/retry 语义一致）。
• 峰谷计价：每笔请求按事件时间戳判定高峰/低谷，套对应单价；显示「当前高峰中/低谷中」徽标。
• 切模型按模型计：会话中途切换模型时，每笔按该步实际路由模型的单价计价（message.source.model 逐笔归属；failed/attempt 记录无自带模型 → 归因最近先行 request/header 的 config.model，与 DSH 每请求的路由一致）；tooltip 的「模型分解」列出每个模型的花费份额。
• 节省分解（悬停 tooltip）：总计 / 低峰节省 / 缓存节省 / 模型分解；未配置价格的模型显示「价格未知」，从不猜测。
• 账户余额：每轮结束后同源刷新一次（事件驱动，无轮询）；经 host 端 GET /user/balance 官方接口（凭证取 DSH 设置的 DEEPSEEK_API_KEY），失败（未配置 key / 网络错误）静默隐藏，多币种非零显示。
• 价目可配置：设置页「插件配置」卡片（session-cost 命名空间）编辑三档模型高峰价（¥/百万）+ 低谷系数，即时生效于下一次结算。
• 口径：不含压缩总结、标题生成、子代理调用（后续版本提供开关）。
• 展示位：conversation.composer.dock——与统计行同一横带（虚拟列表插槽，第三方可直接注册）。

官方价目（内置默认 · 采集日 2026-08-28）

来源：DeepSeek API 官方价目页（用户截图核对）。默认值随插件版本固化，官方调价后请更新 src/core/price.ts 与 src/core/window.ts，或改用自定义价目（见下）。

单位 ¥/百万 token：

高峰时段 = 北京时间周一至周五 9:00–12:00、14:00–18:00（区间起点含、终点不含；周末、午间、晚间、凌晨均为低谷），低谷价 = 高峰价 × 0.5。

安装（bundle + profile 机制）

本包是一个 bundle（dsh.bundle + cordis.patch.yml），安装进 DSH 的 profile（$DSH_HOME/profiles/<name>）即生效——与其它 DSH 插件一致，"放进 profile"由 dsh plugin 命令完成：

# 1) 先构建（package.json 有 prepare 脚本；本地 add 链接的是源码检出，需要 lib/ 产物）
pnpm install && pnpm run build

# 2) 安装进你的 Web profile（`dsh web` 即 `--profile web`；相对路径以调用目录为准，所以在 checkout 内 `add .` 装的就是这个 checkout）
dsh plugin --profile web add .
# 或从任意目录：dsh plugin --profile web add ./dsh-session-spend

# 3) 核对层，然后启动
dsh --profile web --dump-config      # 应出现 "# == dsh-session-spend" 层
dsh --profile web

其它来源同样支持（本包不发布 npm，推荐 GitHub git 安装或 tarball）：

dsh plugin --profile web add github:weiwang988/dsh-session-spend#v0.1.0   # git 安装（推荐，pin 发布标签）
                                                            # 包内有 prepare 会自动构建，
                                                            # 需按提示在 profile 的 pnpm-workspace.yaml
                                                            # 允许该包构建（allowBuilds）
dsh plugin --profile web add ./dsh-session-spend-0.1.0.tgz   # pnpm pack 产物（免构建许可）
dsh plugin --profile web remove dsh-session-spend     # 卸载

若未来要发 npm：pnpm publish 的 prepare 构建已配置好，发布后用户侧 dsh plugin --profile web add dsh-session-spend。

源码仓库：https://github.com/weiwang988/dsh-session-spend（main + 发布标签 v0.1.0）。

生效机制：patch 行 {id: session-spend, name: dsh-session-spend} 进入 Web 组合；@deepseek-ai/dsh-client-modules 扫描组合行，发现本包 dsh.client 清单 → 解析 exports["./client"] → 生成 window.__DSH_BOOT__ 清单并 serve /plugins/session-spend/client.js → 浏览器端 apply 注册定义/视图/dock 条目。无需 fork DSH、无需改任何 bundle 源码。

开发热更新：本地 add ./ 后改了源码，运行 pnpm run build（服务端 serve 的是 lib/client.js 而非源码），刷新浏览器即可。从未 build 就 add 会报 client-modules: ...exports no "./client" bundle。

层序：profile bundles 列表序 → 各 bundle patch → profile 自身 cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch 参数。后续层可覆盖/禁用本包行（- {id: session-spend, disabled: true}），改动不用碰本包。

定义不再重复：本包同时声明 dsh.client（插件面）与 dsh.bundle（安装面）——两者可共存；只有 bundle 声明而无 client 清单的包装进去只算普通依赖，不会激活。

开发期自检

pnpm install && pnpm run build   # 构建 lib/ 产物
npm test                         # node:test（纯函数核心 + ViewBuilder）
npm run typecheck                # 需安装 @deepseek-ai/* 真实类型
npm run typecheck:offline        # 无网络环境（经 types/ 类型镜像）

架构

事件流(窗口+实时) ──> conversationEvents.register(NodeDefinition 'session-cost')
                        每步一个 Context（step/start 起始；live-chunk/attempt/message/
                        retry-started 增量更新：append-only 采样+重试历史）
                        每个 request/header 一个 Context（路由模型事实）
                     └─> conversationViews.register(ViewDefinition 'cost')
                        全部节点 → seq 有序 foldCostItems：按 (turn,step,generation)
                        槽位 last-wins、retry 追加、header 模型归因 → 逐笔高峰/低谷计价
conversation.composer.dock 条目 ← 读快照 session.views.get('cost')

• 分页/重放：引擎 replaceWindow 重建全部节点（Context 从 matches 重放，append-only 状态确定），ViewBuilder replace() 全量重算——不会重复计费。
• 实时：live-chunk usage 帧 animation-frame 节奏刷新（引擎结算时 transient 被退休、Context 以其实际 matches 重放）；与统计行节奏一致，无流式粗估。

兼容性注记（适配 DSH 0.1.5-alpha.1 线）

适配对象为 format v3 事件词表（dsh-v0.1.5-alpha.1，当前 master；v3 自 0.1.3-alpha.2 起生效），要点：

• 持久化面：sessionPersistence.open(id, 'read') → handle.read(offset?, length?, options?) 解析为 SessionHandleReadResult（{ eventState, events }，0.1.5 线起）——本包取 .events（注意 0.1.3 线旧形态是裸 SessionEvent[]，两者本包都兼容：旧线返回数组时 .events 为 undefined，请以 0.1.5 为准；0.1.2 线的 readRaw/supportsRawArtifacts 回退已移除——旧线请用 tag v0.1.0 的包）。
• 词表变化（相对 0.1.2 线）：持久化词表里再无 assistant/chunk，新增 assistant/attempt（失败的模型尝试也留账）；assistant/message 内嵌完整紧凑模型流 stream（usage 仍在）；客户端事件的 SessionEventLike 新增 transient assistant/live-chunk（{attemptId, turn, step, chunk}，结算后由 settle-assistant 退休替换）；llm/retry / llm/retry-started 为持久化重试记录。
• v3 增量（相对 0.1.3-alpha.1，均与计费无关）：system prompt 上浮为 surface 节点（新事件 system/message，request/header 不再携带 system，但 config.model 不变）；tool/code-dispatch* → tool/ptc-dispatch*；新增 feedback/message-put/delete；sourceEventSeqs 从 wire 类型移除；token-meter 的 usage 提取重构为 lastAssistantStreamChunk（语义不变：data.usage 优先，否则 stream 最后一条 usage chunk）。
• 计费口径：usage = data.usage ?? 内嵌 stream 中最后一条 usage chunk（plain {type:'chunk'} 记录；packed text/reasoning/tool-call 行不含 usage）；llm/retry-started(turn,step) 开新槽位——重试后的下载样本是追加不是替换（失败请求与重试请求都真实计费）。
• 模型归属：assistant/attempt 无 model 字段；归因最近先行的 request/header（header.config.model，DSH 只在配置变化时重新记录，因此"最近先行头"就是本次请求的模型）；取不到才标「价格未知」。
• 浏览器端契约（conversation.composer.dock、NodeDefinition/ViewDefinition/register、locale、settingsScope）在 0.1.2-rc.1 → 0.1.5-alpha.1 之间无破坏性变化；事件词表与持久化返回值是唯一破坏点。本包 src 对事件做结构化访问（CostEventLike），因此在 0.1.2 发布类型的笔形下也可 typecheck；devDeps 在 0.1.5-alpha.1 发布 npm 后应升到该版本。

注：0.1.5 线把聊天区的「统计条」换成了两个图标 pill + 点击打开的统计对话框——本包挂在 conversation.composer.dock 槽位，与统计条布局相互独立；如果官方新的统计对话框也提供同源数据入口，可作为后续对齐点。

与现有同类插件的差异

RoxsLee/dsh-cost-plugin（峰谷按时间戳+余额）、Lzh3070/dsh-session-cost（逐消息+明细+余额）等已覆盖「统计行旁读金额」。本项目差异化：

1. 事件级 last-wins（含重试槽位）与统计行账目逐笔对齐——failed attempt、重试与终值消息均按 token-meter 的 replacement/retry 语义折算，同一口径可逐笔核对；
2. 低峰+缓存节省分解与峰/谷当前状态徽标；
3. 未知模型不猜价、显示「价格未知」；
4. 纯函数核心（window/price/fold/cost）独立可测，价目与窗口规则全量配置化。

Known Limitations and Deferred Work

• 读数是"全量"且零窗口成本：会话总账由 host 端从持久化日志折叠（0.1.5 线 sessionPersistence.open(id, 'read') → handle.read() 取解码后的逻辑事件流（{eventState, events}；v0/v1/v2 旧文件由 DSH 格式链自动迁移到 v3，未知词表 fail-closed），客户端永不翻页——客户端窗口从不膨胀，会话二次进入零额外成本（补齐了纯客户端窗口方案的短板）。每次轮次结算 host 重读一次该会话日志（大日志的 host 侧成本，后续可加 revision 缓存）。注意 0.1.5 线的 eventState 指示事件值所有权——本包只读取折叠，不保留引用，无需特殊处理。
• 今日(DSH)：host 端跨所有会话按北京时间今日边界汇总（同口径=主对话调用）；与官方控制台差异（标题/压缩等隐性调用）依旧体现在"今日"之外。
• 「当前高峰/低谷」徽标按组件渲染时刻计算——会话空闲时不会自动翻牌（下一次事件驱动重渲染时更新）。后续可改为定时刷新。
• 不含压缩总结/标题生成/子代理——这些调用在官方口径下同样计费；未来以配置开关引入（includeCompaction / includeTitleGen / includeSubagents）。
• 默认价目为 2026-08-28 采集——官方再次调价后需同步更新 price.ts（或提供自定义价目配置通道，待接入 DSH 配置系统）。
• 余额/今日 = host 端能力：需要 Vite 同源 /_dsh-cost/summary 路由（本包 host 半）与 DSH 配置的 DEEPSEEK_API_KEY；未配置/失败时余额段静默隐藏（其余功能不受影响）。
• 本插件仅按模型单价估算，不构成官方账单；对账以 DeepSeek 控制台为准。