dsh-deepseek-pricing 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-deepseek-pricing contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,164 @@
1
- # Temporary Holding Version
1
+ # dsh-deepseek-pricing
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ DSH(DeepSeek Harness)插件:在输入框工具栏显示 DeepSeek API 当前是**高峰**还是**空闲**计费时段、距离下次切换还有多久,并在设置页同步官方各模型单价。
4
+
5
+ - 输入框工具栏徽章:`高峰 · 全价` / `空闲 · 半价` + 倒计时,点击展开今日时段与价格小卡片。
6
+ - 设置 →「DeepSeek 价格」:完整价格表(¥ / $ 可切换)、时段规则、节假日状态、数据来源、手动刷新。
7
+ - 每轮花费估算(可选,默认关闭):在已完成轮次的页脚上方显示 `~¥1.22`,悬停查看完整精度与分项。
8
+ - 功能开关:设置页里集中管理花费估算、查询工具、节假日同步、刷新间隔;最常用的两个也出现在**本插件详情页**上。
9
+ - 可选 AI 工具 `deepseek_pricing`:让模型自己判断"现在贵不贵、要不要等到空闲时段"。
10
+
11
+ ## 安装
12
+
13
+ ```sh
14
+ dsh plugin --profile <profile名> add dsh-deepseek-pricing
15
+ ```
16
+
17
+ 或在 DSH 的 **插件(Plugins)→ 添加插件** 里输入包名 `dsh-deepseek-pricing`,装好后重启一次 DSH。
18
+ 从源码目录安装则把包名换成该目录的绝对路径。
19
+
20
+ ## 计费时段规则
21
+
22
+ 来源:[DeepSeek 官方定价页](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)(脚注 2)
23
+
24
+ - 高峰:**北京时间(UTC+8)周一至周五 09:00–12:00、14:00–18:00**,不含中国法定节假日。
25
+ - 空闲:其余全部时间,包括周末与中国法定节假日全天。
26
+ - 空闲价 = 高峰价的一半。
27
+
28
+ 周末补班(调休上班日)不影响判定:规则本身已把周末定义为全天空闲。
29
+
30
+ ## 价格与节假日数据
31
+
32
+ | 数据 | 来源 | 回退 |
33
+ |---|---|---|
34
+ | 模型价格(¥) | `https://api-docs.deepseek.com/zh-cn/quick_start/pricing.md` | 内置快照 → 上次成功值 |
35
+ | 模型价格($) | `https://api-docs.deepseek.com/quick_start/pricing.md` | 内置快照 → 上次成功值 |
36
+ | 法定节假日 | `https://timor.tech/api/holiday/year/{year}` | `holiday-cn`(GitHub)→ 内置 2026 快照 |
37
+
38
+ - 价格默认每 360 分钟自动刷新一次,也可在设置页手动刷新;抓取失败时界面会明确标注"离线快照"与数据时间。
39
+ - 节假日数据按当前年 + 次年的顺序获取;次年数据尚未发布时会提示"尚未发布,假期期间可能误判为高峰"。
40
+ - **一次刷新失败不会丢数据**:每次成功抓到的日历会按年份记住,之后失败只标成「沿用上次」(含上次成功时间与失败原因),高峰判定继续用旧日历,不会退化成"没有节假日"。只有从未成功抓过、也没有内置快照的年份才会显示「获取失败 / 按无节假日计算」。
41
+ - **节假日缓存写在包目录内**(`<包目录>/.cache/holidays.json`,约 3 KB)。卸载会删除整个包目录,缓存随之消失;升级或重装会重建目录,缓存丢失(它只是缓存,下一次抓取就会补回)。缓存里只保留当年与次年。
42
+ - **抓取时机**(节假日):① 冷启动后第一次状态请求,缓存缺失或已超过 7 天时同步抓一次;② 缓存 7 天内,重启**完全不联网**;③ 连续运行满 7 天,下一次状态请求触发一次后台刷新;④ 失败时前 3 次每 60 秒重试、之后每 15 分钟;⑤ 手动点「刷新」立即抓取;⑥ 跨年时抓「当年 + 次年」,缓存里的旧年份自动剪掉。稳定状态下是**每周一次**。
43
+ - 状态含义:`已同步`(最近一次抓取成功)、`沿用上次`(本次失败,用上次成功的日历)、`本地缓存`(关闭了自动同步,用磁盘里上次成功的数据)、`内置快照`(从未抓成功,用内置数据)、`尚未发布`(数据源明确返回空)、`检查中`(首次抓取进行中)。
44
+ - **第一次状态请求不再等待抓取**:冷启动先用内置快照回答(当年数据可用,次年标记「检查中」),抓取在后台完成后由页面在 5s/20s/75s 各补读一次。抓取本身给 20 秒超时(实测 timor 偶尔要 11 秒),所以"超时导致状态乱跳"不会再发生。
45
+ - 解析采用"关键词识别 + 末尾金额"的双路匹配,并对"高峰价 = 2 × 空闲价"做校验;官方页面结构变化时宁可保留旧值,也不显示半解析结果。
46
+
47
+ ## 每轮花费估算
48
+
49
+ - 开关在设置页「功能开关」里(本插件详情页也有同一个);模型映射与数字格式合并在「花费估算」一张卡片里,紧跟在功能开关下面。**默认关闭**;设置只保存在本浏览器。
50
+ - 费用 = 未缓存输入 × 未命中价 + 缓存读取 × 命中价 + 输出 × 输出价,按**该轮结束时刻**的高峰/空闲价计算;跨 18:00 的轮次整轮按结束时段计价。
51
+ - 只对已完成、且官方用量完整的轮次显示。模型从用量里的 provider/model 识别(含 flash / pro);识别不到时可在映射表里按 `provider/model` 指定,或设为「不计价」。
52
+ - 悬停提示显示完整精确小数、分项、时段与价格快照时间。
53
+ - 数字写法在「花费估算」卡片的下半部分「数字格式」里调(见下节);默认 `~¥1 234.568`。
54
+ - 数据缺失(缺路由、缺缓存读取、模型无法识别、混合模型、价格不可用)时只显示 `~`,悬停说明原因。
55
+ - 位置限制:插件无法插进 ui-chat 的「用量 · 时间」那一行,只能渲染在它**上方、右对齐**(`conversation.chat.turnTail`)。
56
+
57
+ ## 数字格式
58
+
59
+ 「花费估算」卡片里的「数字格式」区块只改显示,不改价格:
60
+
61
+ | 设置 | 可选 | 默认 |
62
+ | --- | --- | --- |
63
+ | 分隔符 | 空格 / 英文逗号 `,` / 竖线 `\|` / 竖虚线 `┊` / 不分隔 | 空格 |
64
+ | 分组 | 每 3 位(`1 234 567`)/ 每 4 位(`1┊2345┊6789`) | 每 3 位 |
65
+ | 小数位 | 1–8 | 3 |
66
+ | 小额显示 | `~¥0.000…` / `<¥0.001` | `~¥0.000…` |
67
+
68
+ - **固定位数**:选 3 位就显示 3 位(`1.220` 不会缩成 `1.22`),四舍五入,进位会进到整数部分(`0.9999` → `1.000`)。
69
+ - **小数部分也分组**:选 8 位小数时是 `12.345 678 90`;默认 3 位时小数不够一组,看不到分隔符。
70
+ - **小额兜底**:四舍五入后为 0 但确有花费时,按上面选的模式显示 `~¥0.000…` 或 `<¥0.001`(`<` 模式不带 `~`)。
71
+ - **悬停提示**跟随分隔符与分组,但始终是完整精度,不受小数位影响;价格表与弹出卡片不受影响。
72
+ - 设置存在 `localStorage` 的 `dsh-deepseek-pricing.cost` 里(与开关、映射同一个键),老版本数据缺字段会自动落默认值。
73
+
74
+ ## 功能开关
75
+
76
+ 开关分三层,**各归其位**,不会互相顶替:
77
+
78
+ | 层 | 位置 | 控制什么 |
79
+ | --- | --- | --- |
80
+ | 插件总开关 | 设置 → 插件 → 本插件 | bundle 是否启用 |
81
+ | 组件开关 | 设置 → 插件 → 本插件 → 包含的组件 | `deepseek-pricing` 这一行是否运行 |
82
+ | 功能开关 | 设置 → DeepSeek 价格(完整)/ 本插件详情页(常用) | 插件内部行为 |
83
+
84
+ 功能开关本身:
85
+
86
+ | 开关 | 存哪 | 生效 |
87
+ | --- | --- | --- |
88
+ | 每轮花费估算 | 浏览器 localStorage | 立即 |
89
+ | AI 查询工具 `deepseek_pricing` | profile 的 `cordis.patch.yml` | 本插件重载(约 1 秒) |
90
+ | 同步法定节假日 | 同上 | 同上 |
91
+ | 价格自动刷新间隔 | 同上 | 同上 |
92
+
93
+ - Host 侧开关通过 `POST /api/deepseek-pricing/config` 写入,内部走 DSH 的 `configEditor`,所以配置**只有一个真源**(profile patch 里那一行),重启后仍然有效,卸载时随行消失。
94
+ - 写入完成前先回 202,再由 Loader 重新应用本行;页面在 1.2s / 3s 后重新读取 `/state`,因此看到的值总是已持久化的值,而不是乐观更新。
95
+ - 插件详情页的卡片只在你打开本插件那一页时渲染(按 `subject` 过滤),别人的插件页不受影响。
96
+ - 若当前 DSH 版本没有 `configEditor` 服务,接口返回 501,界面提示手动编辑 `cordis.patch.yml`,不会静默失败。
97
+
98
+ ## 配置
99
+
100
+ 插件不导出 Config schema,配置直接写在 `cordis.patch.yml` 的行上(从源码目录、以 `link:` 方式安装时,裸 `@deepseek-ai/*` 依赖还会因为真实路径解析不到,所以保持无 schema 最稳):
101
+
102
+ ```yaml
103
+ - id: deepseek-pricing
104
+ name: dsh-deepseek-pricing
105
+ config:
106
+ tool: true # 是否注册 deepseek_pricing 工具(默认 false)
107
+ currency: CNY # 默认币种:CNY / USD(默认 CNY)
108
+ refreshMinutes: 360 # 价格自动刷新间隔,0 = 仅手动(默认 360)
109
+ holidayRefresh: true # 是否同步法定节假日(默认 true)
110
+ ```
111
+
112
+ - `tool` 为 `true` 时,模型会多一个无参数的 `deepseek_pricing` 工具;关闭时模型侧零开销。
113
+ - `tool`、`refreshMinutes`、`holidayRefresh` 可以在界面里改(见上一节),改完会写回这条行;`currency` 只作为界面显示偏好,不写回配置。
114
+ - 界面里的 ¥ / $ 切换只影响显示,保存在浏览器 localStorage。
115
+
116
+ ## 实现结构
117
+
118
+ ```
119
+ index.js Host 入口:三条 /api/deepseek-pricing/* 路由 + 可选工具
120
+ client.js 浏览器入口:工具栏徽章 + 弹出卡片 + 设置页 + 插件详情页卡片
121
+ src/peak.js 纯函数:北京时间换算、高峰判定、下次切换
122
+ src/pricing.js 官方 Markdown 定价表解析与校验
123
+ src/holidays.js 节假日源 URL 与解析
124
+ src/data.js 缓存、抓取、回退、状态组装(可注入时钟与 fetch 测试)
125
+ src/options.js 开关写入规则:哪些字段可写、如何找到本插件的配置行
126
+ src/snapshot.js 内置价格与 2026 节假日离线快照
127
+ src/format.js 工具结果的 Markdown 文本
128
+ test/ node 单元测试 + 手动联调脚本
129
+ ```
130
+
131
+ ## 手动检查
132
+
133
+ ```sh
134
+ node test/state.test.js # Host 状态:价格、节假日日期、时段
135
+ node test/client-cost.test.js # 费用计算、时段判定、分组与小数位
136
+ node test/config.test.js # 开关写入规则、配置行查找、详情页归属判断
137
+ node test/holiday-cache.test.js # 节假日缓存:失败保留、磁盘缓存、过期与剪枝
138
+ node test/number-format.test.js # 可配置的数字格式:分组、分隔符、小数位、小额兜底
139
+ node test/render-smoke.test.js # 槽位注册 + 无数据渲染 + 卸载说明
140
+ ```
141
+
142
+ ## 已知限制
143
+
144
+ - 启动顺序:Web 服务是在插件行开始激活之后才发布 `webServer` 服务的。Host 端用 `export const inject = ['webServer']` + `ctx.inject(['webServer'], …)` 等待并注册路由(与 `dsh-model-health`、`dsh-our-free-model` 同一模式),所以冷启动后路由会自动出现,不需要手动禁用/启用插件。
145
+ - 页面仍可能在路由注册前就发出第一次请求;客户端对失败做退避重试(1s/2s/4s…最多 30s),切回标签页也会重试,弹出卡片里还有「重试」按钮。
146
+ - DSH 的模型目录没有价格字段,本插件只能维护自己的价格表,不会改写模型配置。
147
+ - 每轮花费估算按轮结束时刻取价,跨时段轮次不拆分;只是估算,不替代账单。缓存写入没有单独价格,未计入。
148
+ - 官方页面改版导致解析失败时,价格停留在上次成功值或内置快照,界面会提示。
149
+ - 节假日以官方发布的法定节假日为准;次年安排通常要到年底才公布。
150
+ - 窗口弹出卡片使用固定定位;若宿主后续给输入框容器加上 `transform`/`contain` 导致裁剪,可改为 `conversation.composer.dock` 内的常驻条。
151
+
152
+ ## 卸载
153
+
154
+ 正常卸载:**插件(Plugins)→ dsh-deepseek-pricing → 移除**(内部执行 `plugin_manager remove_bundle`)。它会移除 profile 的依赖、bundle 选择、`node_modules` 副本和锁文件条目,同时卸载 Host 路由与客户端槽位。
155
+
156
+ 插件自身不写 profile 数据、不写会话事件、没有后台任务。唯一的磁盘文件是**包目录内的节假日缓存**(`node_modules/dsh-deepseek-pricing/.cache/holidays.json`),它随包目录一起被卸载删除,**不需要手动清理**。
157
+
158
+ 同一份清单也显示在**插件详情页**(设置 → 插件 → 本插件)的「卸载说明」里,并标注每一项都是**可选**的:不清理没有任何副作用,介意残留再按操作处理。卸载后仍可能留下这些**外部**痕迹:
159
+
160
+ - **浏览器本地设置**:`localStorage` 里的 `dsh-deepseek-pricing.currency` 与 `dsh-deepseek-pricing.cost`。到设置页「花费估算」点 **清除本地设置** 即可(不用卸载也能清)。
161
+ - **行级配置残留**:在界面里动过「查询工具 / 节假日 / 刷新间隔」之后,`cordis.patch.yml` 里会多出一条 `- id: deepseek-pricing` 覆盖(由 `configEditor` 写入,不是本插件自己写文件)。把值改回默认值时 DSH 会自己清掉这条;没清掉也不影响,卸载后它不再生效,可直接删除。
162
+ - **pnpm 发布龄豁免**:如果安装的版本发布还不到 pnpm 的 `minimumReleaseAge`,pnpm 会在 profile 的 `pnpm-workspace.yaml` 里写一条 `minimumReleaseAgeExclude: dsh-deepseek-pricing@x.y.z`;这是 pnpm 的行为,卸载不会自动删,可手动删除。
163
+
164
+ 以上三条都不影响 DSH 或其它插件;删掉后 profile 就回到安装前的状态。