dsh-tidewatch
DeepSeek 峰谷时刻悬浮徽章：一张悬浮在输入框旁的潮汐卡，告诉你此刻是峰期还是谷期、距下一阶段还有多久、本次会话花了多少钱。
- 状态点：峰期橙红 / 谷期蓝绿，一眼可辨
- 折叠态：
● 峰期 距谷期 03:33 · ¥0.12 - 展开态（点击展开）：官方峰谷时段表（北京时间）、当前档位价格、本次会话 Token 明细、币种切换
- 计费：官方峰谷两档价格（美元口径；含 基础价 / 首版峰谷价 / V4.1 Flash 新价 三段历史档），按每次调用实际发生时刻的档位计价，缓存命中/未命中分开
- 峰谷判定：周末、中国法定节假日（2026 年官方安排表内置）与调休上班的周末全天按谷期计价
- 币种：默认人民币显示（直接取官方中文定价页数字），展开面板可一键切换美元（官方英文页数字，4 位小数）
- 跟随 GUI 亮/暗主题（
--dsw-*变量） - 前端优先采用 DSH 官方 UI 原语（shell 共享模块表中的
@deepseek-ai/dsh-client-ui-primitives）：状态点StateDot、标签Tag、悬浮提示Tooltip、外点关闭useDismissOnOutsidePointer，观感与官方控件一致；老版 shell 的模块表若没有该包，自动降级到内置实现，功能不受影响
峰谷时段（官方依据）
DeepSeek 官方自 2026-08-17 起实施峰谷分时定价：
| 时段（UTC） | 北京时间 | 档位 |
|---|---|---|
| 01:00 – 04:00 | 09:00 – 12:00 | 峰 |
| 04:00 – 06:00 | 12:00 – 14:00 | 谷 |
| 06:00 – 10:00 | 14:00 – 18:00 | 峰 |
| 10:00 – 次日 01:00 | 18:00 – 次日 09:00 | 谷 |
谷期价格为峰期的一半。徽章按 UTC 窗口判定当前档位（官方英文页即按 UTC 小时书写），周几与法定节假日按北京自然日判定（官方中文页把周期锚在「北京时间周一至周五」上）；两种读法在当前窗口取值下等价——窗口均落在同一北京自然日内、且不成对跨越 UTC 日界。时段表展示一律按北京时间。
周末与法定节假日规则：周六/周日全天按谷期计价（2026-08-23 00:00 北京时间起，官方公告原文「周六、周日全天不再区分峰谷时段，统一按低谷时段价格收取调用费用」）；中国法定节假日全天按谷期计价、无峰谷切换、无生效时间（官方定价页脚注，2026-10-10 核对：「高峰时段为北京时间周一至周五（不含中国法定节假日）……包括周末及中国法定节假日全天均为空闲时段」）；调休上班的周末同样全天谷期（官方 2026-09-19 说明：「调休上班的周末、中国法定节假日全天均按空闲时段计费」）。下一阶段切换点为下一个工作日首次进入峰时。节假日表依据《国务院办公厅关于 2026 年部分节假日安排的通知》（国办发明电〔2025〕7号，共 33 天）：元旦 1/1–1/3、春节 2/15–2/23、清明 4/4–4/6、劳动节 5/1–5/5、端午 6/19–6/21、中秋 9/25–9/27、国庆 10/1–10/7。
计费口径
- 价格单位：美元 / 1M tokens（官方英文定价页口径，也是本插件的唯一计费基准），成本 = 输入未命中 × cacheMiss + 输出 × output + (缓存读 + 缓存写) × cacheHit；其中「输出」已含推理 token
- 人民币数字另存一份官方中文定价页数字原样用于展示，不做汇率换算——官网两个模型的隐含汇率并不相同（flash 约 6.67、pro 约 6.82），统一换算会让 pro 的元数字比官网低约 2%
- 三段价格时代，按调用发生时刻选档（历史正确性；档位顺序为 缓存命中 / 输入未命中 / 输出）：
| 时代 | 时间范围（UTC） | deepseek-flash 档位 |
|---|---|---|
| 基础价 | 2026-08-16 16:00 之前 | 0.0028 / 0.14 / 0.28 |
| 首版峰谷价 | 2026-08-16 16:00 ~ 2026-09-10 04:00 | 峰 0.014 / 0.44 / 1.32，谷为峰的一半 |
| V4.1 Flash 新价 | 2026-09-10 04:00 起 | 峰 0.006 / 0.3 / 1.2，谷为峰的一半 |
- 每次调用的费用按事件发生时刻的档位计算，跨峰谷切换与跨调价均不漂移
- 账本金额以美元存储；人民币显示直接取官方中文页数字（默认），美元显示取官方英文页数字（4 位小数）
安装
> 需求：Node.js ≥ 20 + 带 dsh plugin 命令的 DeepSeek Harness。
# 方式一：从 GitHub 直装（推荐，跟随 main 最新）
dsh plugin --profile web add github:KhalilYamber/dsh-tidewatch
# 方式二：链接本地仓库目录（改完源码即时生效，开发时最省事）
dsh plugin --profile web add link:/path/to/dsh-tidewatch
# 方式三：从 Release 的 tgz 安装（可固定版本、可离线）
# 先到 Releases 页面下载 dsh-tidewatch-<版本>.tgz（当前为 1.1.9），然后：
dsh plugin --profile web add ./dsh-tidewatch-1.1.9.tgz
> 本仓库只保留当前版本的 tgz：历史版本（0.1.0 ~ 1.1.9）已归档移出仓库，只剩 dsh-tidewatch-1.1.9.tgz。旧版多含已修正的计价缺陷（金额恒显示 ¥0.00），不要再用它们安装。
> npm 渠道已暂停：npm 上仅有一个 2026-08-22 发布的旧版本（1.0.6），其价格与规则均已过时。请勿安装该版本，也不要据它判断当前计价——以上面两种方式为准。
安装后重启 dsh web 生效，输入框右侧会出现潮汐徽章。
升级与卸载
dsh plugin --profile web update dsh-tidewatch # 或重新执行上面的 add
dsh plugin --profile web list dsh-tidewatch # 查看已安装版本
dsh plugin --profile web remove dsh-tidewatch # 卸载
> v1.1.9 取消节假日分界：官网的节假日口径是无条件的——「调休上班的周末、中国法定节假日全天均按空闲时段计费」，没有生效时间。此前版本在代码里留了一道自设的「节假日规则生效日 = 2026-09-19」，导致 2026 年 91 个小时（元旦、春节、清明、劳动节、端午的部分峰窗时刻）按工作日判峰，与官网表述不符。本版取消该分界，节假日判定无条件适用。账单金额为零影响：那 91 小时全部早于峰谷定价生效（2026-08-17），调用按当时的基础价计费，峰谷档位不参与；实测改判前后成本同为 0.4200 USD。投影 stateVersion 不变，升级无需重放会话；界面仅在回看这些往日时会显示为谷期。
>
> v1.1.8 峰谷规则依据与判定口径：按官网现行口径（2026-10-10 核对中文页、英文页与更新日志）复核峰段判定，并把三处口径落到代码。① 补全官方依据——中文页把周期锚在「北京时间周一至周五」，英文页按 UTC 小时书写，本插件两个窗口（UTC 01:00–04:00 / 06:00–10:00）均落在同一北京自然日内、且不成对跨越 UTC 日界，两种读法当前等价；判定周几因此改为按北京自然日取（原先按 UTC 星期，数值上恰好一致，改动为零行为差异，见 verify 的北京日边界断言）。② 调休上班的周末口径写入注释与面板文案（官方 2026-09-19 说明：调休上班的周末、中国法定节假日全天均按空闲时段计费）——调休上班的周末照旧全天空闲，不是工作日。③ 人民币展示改为直接取官方中文页数字：官网两模型隐含汇率不同（flash 约 6.67、pro 约 6.82），原先统一 6.67 会让 pro 的元数字比官网低约 2%；计费数学仍走美元精确值，历史账单不重算，投影 stateVersion 不变，升级无需重放会话。
>
> v1.1.7 适配 DSH 0.1.7-rc.2：两处修正。① 计费事件源收敛到 assistant/message——旧代码还读 assistant/chunk，而该事件自会话格式 v3 起已被折叠（现行 agent loop 只发 assistant/attempt，其 payload 里没有 usage 字段），那条分支是永不触发的死代码，已删除；costUsage 投影 stateVersion 随之 4→5（折叠口径变了，历史会话重放一次）。② 会话归属判据重写——旧代码用 props.useSessions(s => s.current) 取当前会话，而壳层交给 root 插槽的 state 没有 current 字段，判据恒为 undefined，导致卡片金额长期恒显示 ¥0.00；现改由会话作用域的探针申报归属（它的 sessionId 即权威值），壳层只做「归属会话仍在列表里」的存活校验。失败/被重试的 assistant/attempt 仍不计费，与官方 token-meter 同口径——这是口径上限，不是遗漏。价格表与峰谷规则未动，实时计费金额不变。
>
> v1.1.6 节假日规则：官方定价页脚注（2026-09-19 核对）明确「高峰时段为周一至周五（不含中国法定节假日），周末及法定节假日全天空闲」。本版为峰谷判定与计费加入 2026 年法定节假日表（国办发明电〔2025〕7号）：即将生效的中秋 9/25–9/27、国庆 10/1–10/7 全天按谷期计价。价格数字与 1.1.5 完全一致（官方本轮未调价）；无 stateVersion 变更——节假日规则分界（2026-09-19）之前不存在受影响节假日，历史会话无需重放。
>
> v1.1.2 计价修正：官方定价页脚注(2)与更新日志（2026-09-10）已声明 —— 2026-09-14 之后继续提供 V4 Pro API 服务、计费方式保持不变，如有变动另行通知。此前版本依据新闻发布页的旧口径，把 deepseek-v4-pro 从 2026-09-14 04:00 UTC 起路由到 Flash 价，会低估 pro 调用（缓存未命中约 4.4 倍、缓存命中约 7.3 倍、输出约 3.3 倍）。本版把换价分界 V4_PRO_RETIRE_BOUNDARY 恢复为哨兵值，pro 恒按自身价目计费；路由分支保留，将来接到官方通知把日期填回即可。影响仅限 pro 调用，flash 与其它模型不受影响；本次不改 stateVersion，历史会话无需重放。
>
> v1.1.1 升级提示：该版本把计价口径改为「按调用时刻在三段价格时代中选档」，并把 costUsage 投影版本提升到 stateVersion 4。升级后已持久化的历史会话会重放一次，2026-08-16 ~ 2026-09-10 窗口的费用会恢复为当时的首版峰谷价（此前按新价计算，偏低）。实时计费不受影响。
使用
- 徽章内联在输入框下方的官方统计行里，紧贴「缓存命中 xx%」右侧整齐并列（水平间距与垂直对齐都由该行自身的布局给出，窗口缩放不会错位）；官方统计行尚未渲染时（旧版 shell，或会话尚无 token 统计）回退为输入框右侧的浮动定位
- 点击徽章展开/收起详情面板：时段表、当前档位价格、Token 明细、币种切换（¥ / $）
- 点击「本次会话费用」行可展开分模型花费明细（各模型的 token 与花费分别列出，合计 = 分模型之和）
- 币种选择即时生效并记住；人民币 2 位小数，美元 4 位小数
文件结构
dsh-tidewatch
├── package.json # dsh.bundle.patch + dsh.client.platform 声明
├── cordis.patch.yml # 装配行
├── scripts/build.sh # 构建：语法检查 + zod junction
├── lib/
│ ├── pricing.js # 纯函数：峰谷窗口、isPeakHour/peakPhaseAt、三段价格时代、节假日表、costOf
│ ├── index.js # 宿主：costUsage 会话投影（按事件时刻计费）
│ └── client.js # 前端：悬浮徽章（__ModuleLoader__ bundle）
├── docs/PORTING.md # 移植到其他宿主的适配说明
├── test/
│ ├── verify.mjs # 全套自检入口（node test/verify.mjs）
│ ├── client-fixture.mjs # 前端夹具：真实加载 lib/client.js 的假 React 环境
│ ├── adapt-repro.mjs # 宿主计费口径回归（真实投影折叠）
│ └── ownership-repro.mjs # 前端归属判据回归（会话切换序列）
数据流
模型调用 usage 块（assistant/message 事件，DSH 0.1.7-rc.2 起唯一带 usage 的事件）
│ lib/index.js：costUsage 会话投影（zod schema 校验）
▼
token 桶 + 美元成本（按事件时刻峰谷档位）
│ useProjection('costUsage')（浏览器端）
▼
lib/client.js：悬浮徽章渲染（秒级倒计时 + 汇率换算显示）
开发与验证
DSH_CHECKOUT= bash scripts/build.sh # 语法检查 + zod junction
node test/verify.mjs # 全套自检（峰谷数学、双份常量一致性、计费口径回归、归属判据回归）
> Git Bash 下 DSH_CHECKOUT 需用 Windows 形式路径（如 D:/DeepSeek-Harness/DSHAR工作目录/deepseek-harness-src）：传 /d/... 会被 Node 解析成 D:\d\...，生成悬空 junction —— 插件是 link 安装，坏链接会在下次 dsh web 启动时导致插件装配失败（Cannot find package 'zod'）。脚本已在替换链接之前校验解析结果，坏路径当场报错且不留破坏。
已知限制
- 价格表内置，含三段价格时代（基础价 / 首版峰谷价 / V4.1 Flash 新价）；V4-Pro 为官方 2026-08-17 价；官方定价页脚注(2)与更新日志（2026-09-10）声明 2026-09-14 之后继续提供 V4 Pro 服务、计费方式保持不变（如有变动另行通知），故 pro 恒按自身价目计费，换价分界
V4_PRO_RETIRE_BOUNDARY保持哨兵值待官方通知。官方调价后需手动同步lib/pricing.js（计费）与lib/client.js的DISPLAY_PRICES（展示）两处常量，并为旧价补一段历史档 - 模型名映射：现役
deepseek-flash（V4.1 Flash）；别名deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-v4.1-flash均按现役 flash 价计费（见MODEL_ALIASES） - 时段判定固定按 UTC（官方口径），时段表展示按北京时间（UTC+8）；周末与中国法定节假日全天谷期——节假日表内置 2026 年（国办发明电〔2025〕7号），2027 年安排官方发布后需手动同步
CN_PUBLIC_HOLIDAYS（lib/pricing.js与lib/client.js两处）；调休上班的周末按官方口径恒为谷期 - 花费为美元账本 × 固定汇率 6.67 换算人民币（与官方人民币标价一致）；展开面板可切换美元显示
借鉴与许可
峰谷数学（isPeakHour / peakPhaseAt / tierFor / costOf）与会话投影结构借鉴自 dsh-cost-meter（MIT License），按精简目标改写。
MIT © 2026 KhalilYamber
