dsh-neartoken 0.17.1 → 0.19.0

package/README.md

@@ -47,10 +47,11 @@
    这个按钮走 Host：页面自己 `window.open` 开出来的窗口会被困在承载页面的外壳里（Electron 桌面端会另开一个应用窗口、macOS 上甚至没有任何反应），所以由 Host 调平台启动器交给**系统默认浏览器**（macOS `open` / Windows `rundll32 url.dll,FileProtocolHandler` / Linux `xdg-open`）。地址固定取 Host 自己等待的那个，页面无法让 Host 打开任意 URL。
    卡片同时把确认地址当作可选文字列出来（带「复制链接」按钮）—— 没有桌面环境的机器（远程、容器）启动器可能不存在，把地址贴进自己的浏览器即可。
 4. 插件轮询到批准后自动完成：把站点为该插件铸造的 API key 写进 credentials 的 `NEARTOKEN_API_KEY`，并挂上 `neartoken` provider。
-5. 「断开连接」删掉本地凭据、撤掉 provider，并调用站点的撤销端点。
+5. 卡片右上角的「断开连接」删掉本地凭据、撤掉 provider，并调用站点的撤销端点。
 6. 卡片下方的「模型白名单」勾选即自动保存 —— 未勾选的不再出现在模型选择器里，且当场生效（Host 用 `AdapterRegistrationHandle.replace()` 重新声明同一条路由，同步发布 `llm/adapters-updated`，浏览器重拉目录）。没设置过白名单时默认全部显示，「全部显示」清空白名单。
 7. 账户卡片里的「充值」区：点档位或自己填金额 → 「去支付」→ 站点生成易支付订单，插件把支付页交给系统浏览器打开，付完余额在 5 分钟内自动刷新。**只有 DSH 设备授权签发的密钥能下单**；换成普通令牌时这里会显示「重新连接」。
-8. 再往下的「图像生成」卡片：先勾「启用 generate_image 工具」，再勾要用的生图模型并为每个模型选分组（选的是**计费分组**，不是模型），最后点保存。工具随开关挂载/撤下，模型立刻能用或不能用。
+8. 「数据概览」卡片：右上角切「日 / 周 / 月」，看这个窗口的消耗（括注当前余额）、Token 数，以及按模型堆积的曲线，见下节。
+9. 再往下的「图像生成」卡片：先勾「启用 generate_image 工具」，再勾要用的生图模型并为每个模型选分组（选的是**计费分组**，不是模型），最后点保存。工具随开关挂载/撤下，模型立刻能用或不能用。
 
 备用路径：直接让 credentials 服务存 `NEARTOKEN_API_KEY`，或启动环境导出同名变量 —— provider 会在启动时按凭据现状挂载。
 
@@ -58,6 +59,45 @@
 
 分组路由按同一文档：请求头 `x-neartoken-group` 的值是 `/api/pricing` 的 `group_refs` 给出的 **`#<id>`**（纯 ASCII），分组名只用于展示；某分组没有 ref 时不发该头，按令牌自身分组路由。
 
+## 数据概览（消耗 / Token / 模型堆积）
+
+账户卡片下方是「数据概览」：窗口内的消耗金额（括注当前余额）、窗口内的 Token 数，以及按模型堆积的面积图。右上角的「日 / 周 / 月」切换整个窗口 —— 桶宽由站点给，插件不自己造桶：
+
+| 窗口 | 回看 | 桶宽 | 桶数 |
+|---|---|---|---|
+| 日 | 24 小时 | 1 小时 | 24 |
+| 周 | 7 天 | 6 小时 | 28 |
+| 月 | 30 天 | 1 天 | 30 |
+
+数据来自站点的 `GET /api/dsh/device/usage?range=day|week|month`（契约见 [HANDOFF-new-api.md](HANDOFF-new-api.md) 第七部分），和聊天用同一把 DSH 密钥认证。**不复用站点控制台的统计端点**（`/api/data/self` 之类）：那些要浏览器会话，relay key 读不到；`/api/log/token` 只回最近若干条日志，做不了月视图。
+
+曲线按模型堆叠 Token；模型多于 5 个时其余合并成「其他」，图例给每个模型的占比。每个桶点上去有原生提示（时间 + 该桶总量）。窗口数字取自站点 `quota_data` 聚合表（与站点自己的「消耗分布」同源），所以最近几分钟的花费可能还没进表。
+
+站点没有这个端点、或读不到时，卡片只留一行说明（「站点未提供用量统计。」/「暂时无法从站点读取用量。」），**不画空图** —— 空图会被读成「这段时间没有用量」，那是另一个结论。
+
+## 邀请码（`window.NEARTOKEN_AFF`）
+
+引导用户来到 DSH 的页面可以在窗口上留一个邀请码：`window.NEARTOKEN_AFF = '<code>'`。插件在发起设备授权时读取它，并作为 `aff` 参数拼到站点确认页地址上 —— 卡片里「打开浏览器确认」和「复制链接」用的都是这个带参数的地址：
+
+```
+https://<site>/dsh/device?user_code=K7QM-3XPD&aff=<code>
+```
+
+站点侧不需要为插件做任何改动：New API 前端本来就会把任意页面上的 `?aff=` 存进浏览器 localStorage，注册表单与第三方账号首次登录都从那里取，落库为邀请人。三种情形：
+
+| 用户在站点上的状态 | 结果 |
+|---|---|
+| 已登录 | 设备授权照常完成，`aff` 不参与，无副作用 |
+| 未登录、自己注册 | 注册请求带 `aff_code`，绑定邀请人（奖励按站点后台配置发放） |
+| 未登录、用第三方账号 | 首次登录自动建号时按 `aff` 绑定邀请人 |
+
+边界：
+
+- 只接受 `[A-Za-z0-9_-]{1,64}` 的取值，其它值整条丢弃，**连接照常发起** —— 一个坏邀请码不该让授权失败。
+- 窗口上没有这个全局变量时，地址与以前完全一样（不带 `aff`）。
+- 已有进行中的授权时再点「连接」不会重启，沿用第一次的地址与其中的 `aff`。
+- 站点的 `/sign-in` 页本身没有注册入口：未登录用户从确认页被跳到这里后，只能登录或走第三方账号（首次登录会在站点上自动建号，`aff` 照样生效）；要密码注册就自己打开 `/sign-up?aff=<code>`（确认页已经把取值写进 localStorage，参数可省）。
+
 ## 配置
 
 | 字段 | 默认 | 说明 |
@@ -248,13 +288,14 @@ Gemini 系走原生 surface 而不是 openai 兼容层：同模型同提示词
 - 生图一次一张；`size` 对 images 通道只是建议，上游常忽略（实测不传 size 时 gpt-image-2.5-flare 出 1536x1024）。
 - 生图结果默认只存 attachment；要给文件就传 `path`（必须是不存在的路径，且只对本地文件系统后端生效）。
 - 生图失败按站点原话报错（限流、渠道无可用 channel、模型不支持该端点都会原样透出），不重试、不跨分组兜底 —— 换分组是用户的决定。
+- 数据概览读的是**站点侧**的用量端点，插件自己不做统计也不落盘：站点没升级就只显示一行「站点未提供用量统计。」。金额换算沿用站点 `/api/status` 的 `quota_per_unit` / `usd_exchange_rate`，与账号卡片同源，两块数字不会互相打架。
 
 ## 开发
 
 ```sh
 pnpm install
 pnpm run typecheck
-pnpm run test       # vitest：account / pricing / adapter / model-caps / groups / whitelist / routes / config / wire-parse / images / image-settings / image-tool
+pnpm run test       # vitest：account / pricing / adapter / model-caps / groups / whitelist / routes / usage / config / affiliate / wire-parse / images / image-settings / image-tool
 pnpm run typecheck  # 两个 face 分别检查（host 与 client 的 ctx.sessions 声明互相冲突，不能同 program）
 pnpm run build      # lib/index.js (host) + lib/client.js (client) + lib/types
 ```