dsh-ai-credits 0.0.0-stage → 2.4.2

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 TheGoast
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,398 @@
1
- # Temporary Holding Version
1
+ # 赛博鸡蛋领取处
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 的左侧栏最下面多一栏 **「赛博鸡蛋领取处」**,点进去有六个栏目:
4
+
5
+ - **领取入口**:现在哪些地方能领 AI 免费额度 / 积分,附官方领取链接。
6
+ - **各家价格**:各家 AI 的 API 官方标价,按每 100 万 tokens 摆成一张表,输入 / 输出分列,看着挑便宜的那家。
7
+ - **通用订阅**:各家平台的 Token / 会员 / Coding Plan 订阅(腾讯云 Token Plan、阿里云 Token Plan、火山方舟 Token Plan 与 Coding Plan、GLM Coding、小米 MiMo、MiniMax M Plan、Kimi 会员与 Kimi Code,以及 Claude Pro/Max/Ultra、Google AI Pro/Ultra、Manus、ChatGPT Go/Plus/Pro 等)。
8
+ - **编程工具订阅**:**限定本家编程软件使用**的订阅(腾讯 WorkBuddy / CodeBuddy、阿里 Qoder、字节 Trae、Cursor、GitHub Copilot、Windsurf、Devin),不是跨工具的 coding plan。
9
+ - **本机接入**:这台机器上的 DSH 现在接了哪几家模型线路、每条线路有哪些模型、密钥配了没、新会话默认用哪个。
10
+ - **用量花费**:各家模型来源用了多少 tokens。按 token 计费的线路(DeepSeek 官方 / 账户)折成金额;订阅线路(Trae / Qoder / WorkBuddy / CodeArts)只报 token 和剩余积分、不折钱。可按今天 / 近 7 天 / 近 30 天看。
11
+
12
+ ## 它每天做什么
13
+
14
+ 1. **巡检入口**:把清单里每个官方入口真实请求一遍,记下 `能打开 / 打不开 / 被拦` 和最后检查时间。
15
+ 2. **联网发现**:用宿主已有的联网搜索服务搜几句(免费 API 额度 / free AI credits 等),把没收录过、看起来像活动的页面加进「每日新发现」。
16
+ 已在 profile 的 `cordis.patch.yml` 里把 `web.searchProvider` 定为 `deepseek-official`(原来两个搜索源没定默认,`search()` 会报 `WEB_PROVIDER_AMBIGUOUS`)。同一个修复也让 `web_search` 工具恢复可用。
17
+ 候选会去重(同标题 / 同链接)、按站点限量(攻略站 1 条、其它站 2 条),并跳过 pypi / npm / YouTube 这类不会有领取入口的站。
18
+ 3. **核对价格页 / 订阅页**:每 20 小时把价格表、订阅表里各家的官方页面请求一遍,记下「今天能不能打开」。**只核对页面可访问性,不抓数字** —— 各家页面结构不一样(有的整页是 JS 渲染),硬抓很容易抓错价,所以数字用人工核对过的快照(`prices.js` / `plans.js`)。
19
+ 4. **自动跑**:每天 9 点后(`refreshHour`)自动来一次;DSH 某个时间没开着,下次启动会补跑。价格页 / 订阅页单独按 20 小时过期补检,不跟 9 点绑死。
20
+ 5. 页面每 60 秒重读一次宿主数据,所以不用手动刷。
21
+
22
+ ## 领取入口
23
+
24
+ ### 状态点
25
+
26
+ - 灰点:还没查过(刚装的第一次)
27
+ - 绿点:能打开(HTTP 2xx/3xx)
28
+ - 黄点:被目标站拦了自动检查(403),或这台机器网络连不上(0)—— 点开链接手动试试
29
+
30
+ ### 两个按钮
31
+
32
+ - **立即巡检**:只重新检查一遍链接状态(快)。
33
+ - **联网找新的**:巡检 + 跑一次联网发现(会调用联网搜索,取决于你在设置里选的搜索源)。
34
+
35
+ ## 各家价格
36
+
37
+ - 18 家、54 个模型:DeepSeek、阿里通义、智谱、Kimi、MiniMax、豆包、百度文心、腾讯混元、阶跃星辰、OpenAI、Claude、Gemini、Grok、Mistral、Cohere、Meta Llama(Bedrock)、Amazon Nova、NVIDIA Nemotron。
38
+ - 表按 **国内 / 海外** 分组,同一区域里再按标价币种分开(人民币 / 美元),每行一个模型:输入价、输出价、上下文、说明;绿色「最低」是该分组里最便宜的输入 / 输出。
39
+ - 单位是 **每 100 万 tokens**;缓存价、批量价、税费都另算,以「官网核价 →」打开的官方页面为准。
40
+ - 顶部 **价格快照** 是数字的人工核对日期;**最近核对** 是价格页可访问性的检查时间。快照超过 45 天没更新会提醒你去官网看一眼。
41
+ - 标「聚合价」的几家(OpenAI / Google / xAI / Mistral / Amazon / NVIDIA)官网价格页对本机自动访问不友好,数字按 OpenRouter 目录核对;Meta Llama 用 AWS Bedrock 官方按需价;其余都是官网原价。
42
+ - 价格栏的按钮是 **立即核对价格**:只探价格页 / 订阅页(不重跑 38 个领取入口),一分钟左右回来。
43
+ - 价格数据在 `prices.js` 里(`PRICE_SNAPSHOT_AT` + `PRICE_PROVIDERS`),加一家、改一个价,保存后插件热重载就生效。
44
+
45
+ ## 通用订阅 / 编程工具订阅
46
+
47
+ 两个栏目共用一套卡片,只是数据不同:`category: 'general'` 进「通用订阅」,`category: 'coding'` 进「编程工具订阅」。编程工具订阅里只放**限定本家编程软件使用**的套餐(WorkBuddy / CodeBuddy / Qoder / Trae / Cursor / Copilot / Windsurf / Devin);能跨工具用的 coding plan(火山方舟 Coding Plan、Kimi Code)放在通用订阅。
48
+
49
+ - **排序固定**:国内按 腾讯 → 阿里 → 字节 → 智谱 → 小米 → MiniMax → Kimi 从上而下;国外按厂商名首字母排序。同一家的套餐放在同一个厂商栏里横向排开,不同厂商竖向排列。
50
+ - **编程工具订阅只放限定本家软件使用的套餐**:腾讯 WorkBuddy(Pro / Team)、CodeBuddy(标准 / 高级)、阿里 Qoder(Lite / Pro / Pro+ / Ultra)、字节 Trae(Lite / Pro / Pro+ / Ultra),海外 Cursor(Plus / Premium / Super / Ultra)、Copilot(Pro / Pro+ / Max)、Devin(Pro / Max;Windsurf 已并入 Devin);能跨工具用的 coding plan(火山方舟 Coding Plan、Kimi Code)归到通用订阅。
51
+ - 每个套餐一张卡:月付价、`额度:` 一行、3–5 条权益、核对日期、`去订阅 →`;本质是 Agent 套餐的(Devin、Manus、火山 Token Plan)会标「编程 Agent」/「通用 Agent」。
52
+ - 价格按月付展示;年付折扣、按席位、税费另计,额度与权益以「去订阅」页面为准。
53
+ - 标「汇总价」的几家(ChatGPT / Google)官网页拦自动访问,数字按 BenchLM 的 coding plans 汇总核对;其余直接读自官网 / 官方文档。
54
+ - 顶部 **订阅价快照** 是人工核对日期;**最近核对** 是订阅页可访问性的检查时间。超过 45 天也会提醒。
55
+ - 订阅数据在 `plans.js` 里(`PLAN_SNAPSHOT_AT` + `CODING_PLANS`,`category` 区分 `general` / `coding`,`kind: 'agent'` 标 Agent 套餐),加一个套餐、改一个价,保存后热重载就生效。
56
+
57
+ ## 本机接入
58
+
59
+ 这一栏不存数据,每次都直接问宿主当下的活状态:
60
+
61
+ | 问谁 | 拿到什么 |
62
+ |:--|:--|
63
+ | `ctx.llm.listProviders()` | 现在挂着几条线路(含 TRAE / WorkBuddy / Qoder 这类自带登录的) |
64
+ | `ctx.llm.listModels(provider)` | 每条线路现在能用哪些模型,带「图」标记的能吃图片 |
65
+ | `ctx.llm.listConfigurableProviders()` | 这条线路的设置在哪个 settings 命名空间下、profile 在哪一段 |
66
+ | `ctx.settings.describe({ redactSecrets: true })` | 只取 `api` / `baseURL` / `apiKeyEnv` 三个字段,其余一概不带出来 |
67
+ | `ctx.credentials.describe(ref)` | 密钥「配了没 / 从哪来(环境变量 / 凭据库 / .env)/ 能不能改」 |
68
+ | `ctx.get('agentDefaultModel')` | 新会话默认用哪条线路的哪个模型、上下文多大 |
69
+
70
+ - 顶部一条汇总:线路几条、模型几个、密钥配了几条、还缺几条、这次读的时间。
71
+ - 每条线路一张卡:状态点 + 名字 + 线路 id + 模型数;下面一行小字写密钥状态、协议、端点、设置命名空间;再下面是模型名(最多摊 8 个,多的折成「还有 N 个」,鼠标停上去看全名)。
72
+ - 默认线路会标「当前默认」并高亮;`agentDefaultModel` 单独一块显示新会话默认模型。
73
+ - 缺密钥的线路通常读不到模型清单,这时模型数那栏写「缺密钥,模型没读到」,不是「没报模型」。
74
+ - 自带登录的线路(TRAE / Qoder / WorkBuddy / CodeArts / Claude Code / Codex CLI)没有 `apiKeyEnv`,显示「无需密钥」。
75
+ - 右上角按钮在**本机接入**这一栏会变成 **重新读**:宿主那边对线路清单有 30 秒缓存,这个口会强制重新问一遍。
76
+ - **永远不会显示密钥本身**:`credentials.describe()` 按设计只返回 `configured / source / writable`,这个插件也只调它、不调 `resolve()`。
77
+ - 改接入去「设置 → 模型」,这里只负责告诉你现在接了什么。
78
+
79
+ ## 用量花费
80
+
81
+ 这一栏回答两件事:**各家来源各用了多少**,以及**按 token 计费的线路折合多少钱**。
82
+
83
+ ### 三种线路,三种记法
84
+
85
+ 不是所有线路都在花现金,所以先分类再算钱:
86
+
87
+ | 类型 | 哪些线路 | 报什么 | 金额含义 |
88
+ |:--|:--|:--|:--|
89
+ | **按量计费**(`token`) | `deepseek-official`、`deepseek-account`、`siliconflow`、`volcengine`、`ark-cn`、`ark-byteplus`、**`tokenplus`** | token + **金额** | 真金白银的折算 |
90
+ | **套餐 · 给等价参考**(`estimate`) | `qwen-token-plan`、`opencode-go` | token + **等价金额** | 拿官方价当尺子量,**不是账单** |
91
+ | **纯套餐 / 订阅**(`credits`) | `trae`、`qoder`、`workbuddy`、`codearts`、`ark-agent-plan-cn`、`ark-coding-plan-*`、本地 CLI | token + **积分** | 不折金额 |
92
+
93
+ 判据是「**充值后按量扣款**」还是「**按月付 / 买积分包**」:
94
+
95
+ - **TokenPlus 是按量**(官网原话「充值后按实际调用量计费」)→ 真花钱
96
+ - **OpenCode Go 是订阅**($10 / $40 / $20 每人三档,按模型给月度美元额度)→ 不按 token 扣现金
97
+ - **通义 Token Plan 是积分套餐**(阿里云百炼)→ 同上
98
+
99
+ 后两家仍然给一个「等价金额」,是因为卖的也是 DeepSeek 模型,用官方价量一下有个横向参考。但界面上会明确标成「等价参考,不是账单」,视觉上也用虚线框跟真花钱的条目区分开。**等价金额单独汇总(`estimateCNY`),绝不混进实际花费那个数。**
100
+
101
+ 其余套餐渠道(Trae / Qoder / WorkBuddy / CodeArts / Ark 各 Plan)没有公开的「每 token 多少积分」换算,就不折 —— 宁可只报 token,也不编一个看着精确的错数。
102
+
103
+ ### 价格从哪来:官网实时拉取
104
+
105
+ DeepSeek 的价目表**不靠人工抄**,宿主会直接去官网拉:
106
+
107
+ - 来源:`https://api-docs.deepseek.com/zh-cn/quick_start/pricing`
108
+ - 频率:缓存 6 小时(`pricing-sync.js` 的 `CACHE_MS`),点「重新算用量」可强制重拉
109
+ - 解析:官网价目是服务端渲染的真表格,按「功能 → 时段 → 两列(flash / v4-pro)」累积读取
110
+ - **拉到就以官网为准算钱**,拉不到才退回 `prices.js` 里的人工快照
111
+ - 三重校验防止抓错:解析不出 6 个格子 → 失败;数值超出合理区间 → 失败;空闲价不是高峰的 0.3~0.7 倍 → 失败。任何一项失败都**不会改动**已用的价格
112
+
113
+ 界面上会写「DeepSeek 官网价 已核对」或「没拉到(用本地快照)」+ 原因。
114
+
115
+ 方舟托管的 DeepSeek(`deepseek-v4-1-flash-261017`)标了 `followsOfficial: 'deepseek-flash'`,所以官网一改价,它自动跟。
116
+
117
+ ### 官方账单(CSV 导入)—— 唯一能拿到官方口径的途径
118
+
119
+ DeepSeek **没有用量查询 API**(`/user/usage`、`/user/billing` 都是 404),`platform.deepseek.com/usage` 是登录态网页,API key 进不去。所以想拿官方计费口径,只能**导出 CSV**。
120
+
121
+ #### 怎么导入
122
+
123
+ 1. 打开 `platform.deepseek.com` → 用量 / 账单,选好时间段,导出
124
+ 2. 在「用量花费」栏找到 **官方账单** 区块,点「导入官方账单」
125
+ 3. **直接选那个 `.zip`,不用解压**(已经解压过的话,也可以选单个 `.csv`)
126
+
127
+ 导入后页面立刻刷新,多出官方总额卡和「官方账单(按 API key)」区块。换个时间段再导一次会**同名覆盖**,不用手动删旧文件。
128
+
129
+ 什么都没导入时,这一块显示的是操作引导;导入过之后变成一个小的「重新导入」。
130
+
131
+ #### 上传是怎么走的
132
+
133
+ 浏览器沙箱写不了 `$DSH_HOME`,所以:
134
+
135
+ ```
136
+ 页面选文件 → base64 → POST /ai-credits/official-import → 宿主解 zip 写盘
137
+ ```
138
+
139
+ - `.zip` 由宿主自己解(内置极简 ZIP 读取,只认「存储」和「deflate」两种方式,Node 自带 zlib 就够,不引第三方库)
140
+ - 文件名会消毒:只留基名 + 保守字符,强制 `.csv` 结尾(防路径穿越)
141
+ - 大小上限 32 MB
142
+ - 这个路由和其他写操作一样带同源校验,未登录的请求会 401
143
+
144
+ 也可以手动放:把文件丢进 `$DSH_HOME/ai-credits/official-usage/`,效果一样(缓存 60 秒)。
145
+
146
+ **两个 CSV 的分工**:
147
+
148
+ | 文件 | 用途 |
149
+ |:--|:--|
150
+ | `amount-*.csv` | 有 `api_key_name` 维度,能按 key 拆;`price` 是**每 token** 单价(不是每百万),`amount × price` 求和 = 金额 |
151
+ | `cost-*.csv` | 每日每模型的金额小计,用来交叉校验(两者对不上会在界面提示「导出可能不完整」) |
152
+
153
+ `type` 字段取值:`input_cache_hit_tokens` / `input_cache_miss_tokens` / `output_tokens` / `request_count` / `function_call`。
154
+
155
+ **注意 `function_call`**:这是联网搜索(`server-tool-search`)的按次计费,¥0.005/次(= ¥5/千次)。它**不在 token 用量里**,自己折算时很容易漏掉。实测这台机 30 天用了 165 次,¥0.825。
156
+
157
+ ### 为什么不一致:token 结构差异
158
+
159
+ 拿一台机器 30 天的数据(10-19 ~ 11-17)做过逐日对账,结论:
160
+
161
+ | 项目 | 官方 | 日志折算 | 差 |
162
+ |:--|--:|--:|--:|
163
+ | 缓存命中 | 3827.4M | 3810.0M | **-0.45%** |
164
+ | 缓存未命中 | 41.14M | 37.71M | **-8.35%** |
165
+ | 输出 | 7.39M | 6.74M | **-8.84%** |
166
+
167
+ **命中几乎完全一致,但未命中和输出偏小约 8%** —— 这是会话日志与实际计费之间的结构性差异(推测是思考模式下 reasoning token 的归属),不是价格配错。按单价折算,这两项少算约 ¥6,正好是 5% 左右的总额差。
168
+
169
+ 对账时要注意三件事:
170
+
171
+ 1. **同一账号下可能有多个 API key**。官方账单里全都在,但 DSH 只用其中一两个;其余 key 的调用不在会话日志里,折算自然偏小。
172
+ 2. **余额差分(`.dshw-usage.json`)是全账号口径**,所以它应该和「官方账单总额」对得上,而不是和「日志折算」对得上。实测两者分别是 ¥152.0 和 ¥152.25,基本吻合。
173
+ 3. 搜索按次计费不计入 token。
174
+
175
+ ### 分时价(峰谷)与缓存命中
176
+
177
+ 按量渠道的金额不是「token × 一个数」,要拆两层:
178
+
179
+ **① 峰谷**:每家有自己的时段定义,而且时区不一样 ——
180
+
181
+ | 渠道 | 高峰时段 | 时区 | 闲时价 |
182
+ |:--|:--|:--|:--|
183
+ | DeepSeek 官方 | 工作日 9:00-12:00、14:00-18:00(不含法定节假日) | Asia/Shanghai | 高峰的一半 |
184
+ | 火山方舟(托管 DeepSeek) | 同官方 | Asia/Shanghai | 同上 |
185
+ | SiliconFlow | 0:00-2:00 与 8:00-24:00(**低峰只有凌晨 2:00-8:00**) | Asia/Shanghai | 高峰的一半 |
186
+
187
+ 硅基的单价和 DeepSeek 官方**完全一致**(输入 ¥2 / 输出 ¥8 / 命中 ¥0.04,低峰各减半),但**时段完全不同** —— 它只在凌晨 2 点到 8 点给低价,其余时间都是高峰价。所以判断前必须先把时间戳换到**那家自己声明的时区**(`peak.timeZone`),并且按各自的 `ranges` 判,不能共用一个时段表。
188
+
189
+ **每条调用按它自己的时间戳判**,不是拿整批总量套一个价 —— 同一个模型的调用可能一半在峰、一半在谷。
190
+
191
+ **② 缓存命中 / 未命中**:日志里的两个字段本来就是分开的 ——
192
+
193
+ - `inputTokens` = 缓存**未命中**的输入
194
+ - `cacheReadTokens` = 缓存**命中**的输入
195
+ - `outputTokens` = 输出
196
+
197
+ 两者单价差几十倍(DeepSeek Flash:命中 ¥0.04 vs 未命中 ¥2,差 50 倍)。所以三段各用各的价,不能合并。
198
+
199
+ **节假日**:内置 2026 年国务院公布的法定节假日(33 天),这些天全天按空闲价。调休上班的周六 / 周日按官方原文仍算「周末 → 空闲」。
200
+
201
+ ### 实际扣费 vs 折算金额
202
+
203
+ 页面把两个数并排放:
204
+
205
+ - **按标价折算**:日志 token × 官方价,算「这些用量按标价要多少钱」
206
+ - **实际扣费**:DeepSeek 账户余额的真实净扣减(读本机 `.dshw-usage.json` 的按天账本)
207
+
208
+ DeepSeek 官方**没有消费明细 API**(`/user/balance` 只给余额,`/user/usage`、`/user/billing` 都是 404),所以「实际花了多少」只能靠余额差分。本机另一个插件一直在采余额、把每日净扣减记成 `history`,这里**只读它**。
209
+
210
+ **注意口径**:实际扣费只覆盖 **DeepSeek 一个账号**,所以只能跟「DeepSeek 系那两条」(`deepseek-official` + `deepseek-account`)比。硅基、火山、TokenPlus 是独立平台,它们的钱不进这个余额 —— 卡片上会写「对应上方 DeepSeek 系 ¥X」把这个口径点出来,别拿总额去对。
211
+
212
+ 纯 DeepSeek 系折算约 ¥142 / 实际扣费 ¥152,差 7%。**这个差额不是价格算错**——单看没有外部消费的日子(如 10-27)是一分不差的(¥0.44 vs ¥0.44);偏差来自余额差分里那些不产生会话日志的消费:DeepSeek 网页版 / App 聊天、搜索与网页抓取按次计费(¥5/千次)、文件解析(¥1.5/千页)。余额是账号级的,日志只是 DSH 这一侧的。
213
+
214
+ ⚠️ 实际扣费只覆盖 **DeepSeek 一个账号**,硅基流动 / 火山方舟的扣费不在里面(它们没有余额查询接口)。
215
+
216
+ ### 积分:能拿到「线路级」的消耗,拿不到「模型级」的
217
+
218
+ 积分账取自各家连接器自己开的 `/plugins/dsh-connect-xxx/usage`,是**官方那边的真实数字**:
219
+
220
+ | 线路 | 字段 | 消耗怎么算 |
221
+ |:--|:--|:--|
222
+ | Trae | `credits.consumed` | 官方直给 |
223
+ | Qoder / Qoder Global | `credits.packages[]` | `Σsize − Σremain` |
224
+ | WorkBuddy | `credits.packages[]` | `Σsize − Σremain` |
225
+ | CodeArts / 通义 Token Plan 等 | 无 | 只报 token |
226
+
227
+ 所以页面上每条订阅线路会显示:**已耗 N 积分**、**还剩 N 积分**、**总额度 N 积分**,以及这条线路下各模型的 **token 占比**。
228
+
229
+ **为什么积分只到线路级、不到模型级?** 两个原因,都实测过:
230
+
231
+ 1. 官方接口只给整条线路的累计值,没有按模型拆分的明细。
232
+ 2. 各家都没有公开「每 token 扣多少积分」的换算。模型名里那个 `x0.06` 是**相对系数、不是绝对单价** —— 实测反推常数:qoder 约 521、trae 约 48,差 10 倍;trae 自己两次采样还从 43.8 漂到 48(错峰折扣会改单价)。硬乘会得出一个看着精确、其实是错的数。
233
+
234
+ 所以模型那里只列 token 占比,**不硬摊积分**。想算精确的按模型积分消耗,只能等官方开放明细接口。
235
+
236
+ **积分是累计值,不随时间范围变** —— 官方没给按天明细。顶部的今天 / 近 7 天 / 近 30 天只影响 token 用量和折算/实际金额。
237
+
238
+ 这些数字由**页面同源**去问 —— 宿主进程拿不到自己的监听端口,问不了自己;页面本来就在宿主 origin 上,直接问最省事。哪家没装 / 没登录 / 超时都只是那一家没数,不影响用量统计。
239
+
240
+ ### 超过 30 天的数据
241
+
242
+ **不删除,只是不计入统计。** 插件对会话日志是纯只读:
243
+
244
+ - 原始数据在 `$DSH_HOME/sessions/<工作区>/<会话>/session.v4.jsonl.zstd`,由 DSH 自己管理,本插件从不写、不删、不移动
245
+ - 每次请求都重新扫一遍全部日志文件(按 mtime + size 做增量缓存),30 天窗口是在统计时过滤的,不是把老数据清掉
246
+ - 想改回看更长时间,改 `usage.js` 里 `WINDOWS` 的 `days` 即可
247
+
248
+ 顶部的「按天」最多列 31 行(`slice(0, 31)`),那是**显示上限**,不是数据被删。窗口内超过 31 天时才会截断,而最长窗口正好 30 天,所以目前不会触发。
249
+
250
+ ### 时间范围
251
+
252
+ 顶部三个按钮切 **今天 / 近 7 天 / 近 30 天**,切了会带 `?window=day|week|month` 重新读一遍。按天用本地零点切,不用 UTC(否则「今天」会差 8 小时)。
253
+
254
+ ### 时间轴:点开渠道看会话明细
255
+
256
+ **点任意一条渠道(行首出现 ▸)** 就会在行内展开一张时间轴:
257
+
258
+ - **横轴是时间**,每一行是一个**会话**,行尾是该会话在这个窗口内的 token 合计
259
+ - 柱子高度 = 那一格(今天 15 分钟 / 其他 1 小时)消耗的 token,**按平方根缩放** —— 线性画的话几十 M 的大桶会把几百 K 的小桶压成看不见的点
260
+ - 柱子下面的淡色底线表示这个会话的活跃区间
261
+ - **按会话分段、并按父子关系缩进**:subagent 派生出来的子会话(`parentSession`)缩进挂在父会话下面,所以既像时间轴、又能看出「谁是谁派出来的」
262
+ - 鼠标停在柱子上有具体数值和该格调用次数
263
+
264
+ 数据都来自会话日志本身:`session` 事件给 `id / cwd / origin / parentSession`,`session/title` 给可读标题。没标题的显示「(无标题会话)」,79 个会话里只有少数几个从来没有标题事件。
265
+
266
+ 实现细节:只保留**有数据的桶**(稀疏数组),否则 30 天 × 几十个会话 × 每小时就是几万个空格子。父会话和子会话的 id 写法不一样(一个是裸 UUID、一个带 `session-` 前缀),要先归一化才能把父子对上。
267
+
268
+ ### 数据来源
269
+
270
+ 不用猜 —— DSH 自己就在会话日志里记账。每条回复落盘时都带两样东西:
271
+
272
+ | 字段 | 内容 |
273
+ |:--|:--|
274
+ | `message.source` | `{ provider, model }` —— 这条回复是哪条线路的哪个模型答的 |
275
+ | `usage` | `{ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens }` |
276
+
277
+ 所以「deepseek-account 用了 32.7 亿 tokens、trae 用了 4267 万」这种数是宿主自己记的,不是估的。`compaction/summary`(上下文压缩那次调用)也带 usage,一并算进来。
278
+
279
+ ### 去重:fork / 分支会话的复制事件
280
+
281
+ **fork / 分支会话会把父会话的 `assistant/message` 事件原样复制到自己的日志里** —— 时间戳、模型、`usage` 全都一模一样。不去重的话,父会话那段历史会被算两遍,金额虚高一截。
282
+
283
+ 去重办法:给每条调用算一个内容指纹
284
+
285
+ ```
286
+ 时间戳 | 渠道 | 模型 | 未命中输入 | 输出 | 缓存命中 | 缓存写入 | 合计
287
+ ```
288
+
289
+ 八个字段全一样才判为重复。复制出来的事件必然分毫不差;两次真实调用撞在同一毫秒、且 token 数完全相同的概率可以忽略。
290
+
291
+ 配套的两个细节:
292
+
293
+ - **扫描顺序**:复制方(有 `parentSession` 且 `origin` 不是 `subagent`)排在原始方**后面**。否则 fork 先被扫到、占了名额,父会话反而被丢掉 —— 总量虽然对得上,但时间轴上这段历史会记到 fork 名下,归属就错了。
294
+ - **`subagent` 不算复制方**:子代理是独立干活、用自己的调用,不会复制父会话的事件(本机实测 28 个 subagent,0 条重复)。
295
+
296
+ 去重后的条数和 token 会显示在用量栏顶部(「已去重 N 条」),没有重复就不显示。
297
+
298
+ ### 界面
299
+
300
+ - 顶部五张卡:按标价折算、计费 tokens、订阅 tokens、**订阅积分消耗**、调用次数。
301
+ - **按 token 计费**:每条线路一张条,写清楚输入 / 输出 / 缓存读 / 合计,右边是折出来的金额,下面一行小字写清按谁的标价、单价多少。金额条按最大的一条定宽,差距几千倍时小条也看得见。
302
+ - **订阅 / 额度制**:**一条线路一张卡**(不是每个模型一张 —— 积分是线路级的,每个模型都挂同一个数会让人以为各花了这么多)。卡上写「耗 N 积分 / 还剩 N / 总额度 N」,下面按模型列 token 占比条,没有积分接口的标「只看 token」。
303
+ - **按天**:所选范围内每天一条,带横向比例条。同一天里人民币和美元分开累加、显示时合成一行。
304
+ - **点开任一条渠道 → 会话时间轴**:见下面「时间轴」一节。
305
+ - 模型名对不上价格表的,**只统计用量、不折金额**,标「没有标价」—— 宁可留空,也不编一个数。
306
+ - 日志里 `deepseek-v4.1-flash`、`deepseek-v4.1-flash-1017` 这类带日期后缀的 id 会自动归到价格表里的 `deepseek-flash`,卡片上会注明「按 deepseek-flash 计价」。
307
+
308
+ **金额是折算值,不是账单。** 它拿 token 数乘官网标价,回答「这些用量按标价要多少钱」。实际扣款还会被谷时折扣(DeepSeek 谷时半价)、赠金 / 免费额度、各家自己的缓存计价规则拉开。想对真实余额,看「领取」那一栏的 DeepSeek 余额。
309
+
310
+ **性能**:会话日志上百 MB、压缩成一帧一帧的 zstd。为了让「点进这一栏」不卡,做了四层:
311
+
312
+ | 层 | 作用 | 效果(实测,128MB / 79 文件 / 19824 条记录) |
313
+ |:--|:--|:--|
314
+ | **前端首屏快照** | localStorage 存上次 payload,组件初始化直接拿来渲染 | 点进去 **0ms** 有内容,后台静默刷新 |
315
+ | **磁盘扫描缓存** | `$DSH_HOME/ai-credits/usage-cache.json`,插件重载后免于重解日志 | 重载首次 8.9s → **0.7~1.9s**(只重扫变过的文件) |
316
+ | **文件级增量缓存** | 路径 + mtime + size 没变就不重扫 | 热态 **140ms** |
317
+ | **Intl 实例缓存** | `DateTimeFormat` 按 timeZone 复用 | 单这一项就省掉 **约 1 秒** |
318
+
319
+ 关于最后一条:判峰谷要按每条调用的时间戳换算时区,而 `new Intl.DateTimeFormat()` 构造一次要几十微秒 —— 两万条叠起来就是整一秒。缓存成按 timeZone 复用后基本归零。
320
+
321
+ 解压用异步版 —— 同步解会把宿主的事件循环卡住两秒多。点右上角「重新算用量」会强制重算。
322
+
323
+ 前端快照的细节:存在 `localStorage` 的 `ai-credits.snapshot.v1`,24 小时内有效;用到旧快照时顶部会显示「显示的是上次缓存的数据,正在刷新…」,真实结果回来就消失。快照坏了 / 超配额 / 隐私模式禁用 localStorage 都静默放弃,不影响正常加载。
324
+
325
+ ## 数据放哪
326
+
327
+ `$DSH_HOME/ai-credits/catalog.json`(Windows 默认 `C:\Users\<你>\.dsh\ai-credits\catalog.json`),只在本机,不上传。价格 / 订阅数字不存这里,只在 `prices.js` / `plans.js`。
328
+
329
+ 同一个目录下还有两样:
330
+
331
+ - `usage-cache.json`(约 1.4MB):会话日志的扫描结果缓存,删了只会让下次慢一点,不影响正确性
332
+ - `official-usage/*.csv`:你导入的官方用量账单(页面上传或手动放入都行)
333
+
334
+ ## 配置(`cordis.patch.yml` 的 `config`)
335
+
336
+ | 字段 | 默认 | 说明 |
337
+ |:--|:--|:--|
338
+ | `refreshHour` | `9` | 每天几点后自动巡检(0–23) |
339
+ | `dailySearch` | `true` | 自动巡检时要不要顺带联网发现 |
340
+ | `checkTimeoutMs` | `10000` | 单个入口 / 价格页 / 订阅页的超时 |
341
+ | `maxCandidates` | `80` | 「每日新发现」最多留多少条(超过 45 天的自动清掉) |
342
+ | `officialKeyMap` | 自动猜 | 官方用量账单里 `api_key_name` 对应哪条线路,形如 `{"deepseek-official":"4"}` |
343
+
344
+ **全部可选,删光也能跑。** 插件没有导出 `Config`(那需要宿主注入 schema 构造器,拿不到会让整个插件不激活),所以配置在这里自己校验、给默认值 —— 配错了只是退回默认,不会让插件挂掉。
345
+
346
+ `officialKeyMap` 的处理有个细节:配置里写了的名字,如果**当前账单里不存在,会被忽略**,然后按 key 名字自动探测补上。所以把插件分享给别人时,这份带着你本机 key 名的配置不会挡住对方。
347
+
348
+ 价格页 / 订阅页的核对节奏固定为 20 小时(`index.js` 里的 `PRICE_CHECK_HOURS`),不跟 `refreshHour` 绑死,这样白天重开 DSH 也会补一次。
349
+
350
+ 内置入口清单在 `index.js` 的 `SEEDS` 里,想加一个入口直接往里加一条(`id / title / category / url / claim / tags`),重启后会自动并进现有数据。
351
+
352
+ ## 分享给别人
353
+
354
+ 不需要构建、没有依赖,纯 JS 一个目录。打包:
355
+
356
+ ```powershell
357
+ pwsh -File pack.ps1 # 产物在 ../ai-credits-dist/ai-credits-<版本>.zip
358
+ ```
359
+
360
+ 脚本会先自查四件事再打包:语法、`files` 清单覆盖、有没有混进本机绝对路径 / 密钥、zip 内容。
361
+
362
+ 对方怎么装:
363
+
364
+ 1. 解压得到 `ai-credits\` 目录
365
+ 2. DSH → 插件 → **添加插件** → 选这个目录
366
+ 3. 重启 DSH(Host 半边要重启才生效)
367
+
368
+ **装完会是什么样**(没装任何配套插件时):
369
+
370
+ | 栏目 | 状态 |
371
+ |:--|:--|
372
+ | 领取入口 / 各家价格 / 通用订阅 / 编程工具订阅 | 完整可用 |
373
+ | 本机接入 | 完整可用(读的是对方自己的 DSH) |
374
+ | 用量花费 · token 统计 / 时间轴 | 完整可用 |
375
+ | 用量花费 · 金额 | 只有对方配置了按量渠道才有 |
376
+ | 积分 / 实际扣费 / 官方账单 | 显示「—」或「积分未知」,因为依赖 dsh-connect-* 连接器、`.dshw-usage.json`、官方 CSV |
377
+
378
+ 也就是说**核心功能不依赖任何外挂数据**,缺的只是几栏附加对照。
379
+
380
+ ## 目录
381
+
382
+ ```
383
+ plugins/ai-credits/
384
+ ├─ index.js 宿主:清单、巡检、联网发现、价格页 / 订阅页核对、存储、HTTP 路由
385
+ ├─ dsh-api.js 宿主:问 llm / settings / credentials 收集「本机接入」情况(30 秒缓存)
386
+ ├─ usage.js 宿主:扫会话日志统计各家用量,按官方分时价折钱(磁盘 + 内存双层缓存)
387
+ ├─ pricing-sync.js 宿主:实时拉 DeepSeek 官网价目表解析(6 小时缓存,三重校验)
388
+ ├─ official-usage.js 宿主:解析导入的官方用量 CSV(按 API key 拆,60 秒缓存)
389
+ ├─ client.js 网页:侧栏按钮 + 六个栏目(首屏用 localStorage 快照,零等待)
390
+ ├─ prices.js 各家 API 价格快照(人工核对;DeepSeek 由官网实时覆盖)
391
+ ├─ plans.js 各家 coding plan / Agent 套餐快照(人工核对,带核对日期)
392
+ ├─ cordis.patch.yml loader 行
393
+ ├─ locale/{zh,en}.json
394
+ ├─ docs/DETAIL.md 插件详情页的说明(`meta.detail` 指向它)
395
+ ├─ icon.svg
396
+ ├─ pack.ps1 打包脚本(开发用,不进 zip)
397
+ └─ README.md
398
+ ```