feat: 新增部分套餐账单查询（v0.6.4）

- 账单/用量查询：balance:kimi（Moonshot 开放平台余额）、NewAPI 中转站余额（accessToken+userId）、Kimi/智谱/MiniMax 套餐档位（5小时/7天） - managed:kimi-code 走 Kimi Code OAuth 登录凭据查询订阅用量，access token 过期自动 refresh 并写回凭据（单 flight 锁 + 写回前重读防 CLI 竞态） - 全屏「配置用量查询」页面：启用开关 / 自动检测 vs NewAPI 模板 / 超时与自动查询间隔 / 测试查询 - 供应商卡片紧凑用量行（切换使用左侧）+ 多档明细行；managed 供应商列表置顶（仅展示层） - 用量显示中英文适配（five_hour→5小时、weekly_limit→7天，Rust 错误串本地化映射） - 修复：usage_kinds serde rename 导致账单入口不显示；测试查询因 save 触发 loading 翻页卸载面板导致结果丢失（silent save）
2026-08-01 09:44:36 +08:00
1 parent 12dcb17771
commit ace9842556
@@ -0,0 +1,112 @@
+# 工作交接：账单查询功能（2026-08-01）
+
+> 新会话续作入口：先读本文件 + `docs/USAGE-QUERY-ADAPTATION.md`（调研文档），然后按「二、下一步」继续。
+
+## 一、当前进度总览
+
+**已提交（1 个 commit，分支 `Dev_20260801`）**：
+- `12dcb17` — docs: 账单查询适配调研 + OpenCode Zen 预设补推荐链接
+
+**工作区未提交改动**——用户硬约束：**实现完成不提交，等用户逐批测试确认后才提交**。
+`git status` 实测清单（注意：`src-tauri/Cargo.toml` 现含**真实改动**——批次 4 新增 tokio 依赖行，另混有用户自己的行尾差异，提交时只保留 tokio 行）：
+
+```
+M  docs/USAGE-QUERY-ADAPTATION.md   M  src/App.tsx
+M  src-tauri/Cargo.toml（含 tokio 真实改动）  M  src/components/ProviderList.tsx
+M  src-tauri/src/commands.rs        M  src/components/UsageFooter.tsx
+M  src-tauri/src/db.rs              M  src/config/providerPresets.ts
+M  src-tauri/src/kimi_code_io.rs    M  src/hooks/useConfig.ts
+M  src-tauri/src/lib.rs             M  src/i18n/en.ts
+M  src-tauri/src/models.rs          M  src/i18n/zh.ts
+M  src-tauri/src/pi_io.rs           M  src/types/index.ts
+M  src-tauri/src/services/balance.rs / coding_plan.rs / mod.rs
+?? docs/HANDOVER-usage-billing.md（本文件）
+?? src-tauri/src/oauth.rs
+?? src/components/UsageConfigModal.tsx
+?? src/lib/usage-display.ts
+```
+
+### 批次 1：P0 `balance:kimi` + usageKinds 字段修复
+- `src-tauri/src/services/balance.rs` — `query_kimi`/`parse_kimi`（`api.moonshot.cn|ai/v1/users/me/balance`，CNY/USD 消歧）+ 5 单测
+- `src-tauri/src/services/mod.rs` — `UsageKind::BalanceKimi`（"balance:kimi"）、detect_provider 加 `api.moonshot.cn/.ai`
+- `src/config/providerPresets.ts` — union/SUPPORTED 加 `balance:kimi`，moonshot 预设挂 usageKinds
+- `src-tauri/src/models.rs` — **`usage_kinds` 加 `#[serde(rename = "usageKinds")]`**（修复历史 bug：Rust 序列化 snake_case、前端读 camelCase 导致所有账单入口不显示）
+
+### 批次 2：A/B/C 三阶段（OAuth + 配置面板 + NewAPI）
+Rust：
+- `src-tauri/src/oauth.rs`（新增）— 读 `~/.kimi-code/credentials/kimi-code.json` access_token，30s 过期缓冲，**不做 refresh**（避免与 CLI 的 refresh_token 轮换竞态）
+- `src-tauri/src/models.rs` — `UsageConfig` struct（camelCase）+ `Provider.usage_config`（rename="usageConfig"）
+- `src-tauri/src/services/balance.rs` — `query_newapi`/`parse_newapi`/`fetch_newapi_status`（NewAPI 中转站：`{base}/api/user/self` + Bearer accessToken + `New-Api-User` userId；`/api/status` 拉 quota_per_unit/货币符号，进程内缓存 5min；quota=0 视为无限额度）
+- `src-tauri/src/services/mod.rs` — `BalanceNewapi`（"balance:newapi"，ALL=10），`query_kind` 签名加 `usage_config: Option<&UsageConfig>`
+- `src-tauri/src/commands.rs` — `usage_config_key` + merge_usage_kinds 同时 merge usage_config（SQLite `usage_config:<name>`）；save 时持久化；`query_provider_usage`：usageConfig.enabled=false 拒绝、templateType=="newapi" 走 NewAPI 分支、managed 供应商读 OAuth token（api_key 优先，OAuth 兜底）
+- `src-tauri/src/lib.rs` — 注册 `pub mod oauth;`
+- `src-tauri/src/db.rs` / `kimi_code_io.rs` / `pi_io.rs` — Provider 构造点补 `usage_config: None`（8 处）
+
+前端：
+- `src/types/index.ts` — `UsageConfig` 接口 + `Provider.usageConfig`
+- `src/components/UsageConfigModal.tsx`（新增）— 配置面板（批次 3 已改全屏）
+- `src/components/UsageFooter.tsx` — 拆 compact（卡片右侧：主摘要 + `x 分钟前` + 刷新，含自动查询 interval）/ detail（底部：多档明细 + 错误/重试）；模块级缓存 + 3 并发信号量
+- `src/components/ProviderList.tsx` — BarChart3 配置入口按钮；紧凑用量行嵌入按钮组、位于「切换使用」左侧（cc-switch 布局）
+- `src/App.tsx` — `usageConfigProvider` 状态 + `handleSaveUsageConfig` + modal 挂载
+- `src/i18n/zh.ts` / `en.ts` — 新增约 34 个 key
+
+### 批次 3：全屏配置页面 + 超时配置
+- `src/components/UsageConfigModal.tsx` — **居中弹窗 → 全屏页面**（参考 cc-switch FullScreenPanel）：`fixed inset-0 flex flex-col bg-app`，header 64px（ArrowLeft 返回 + 标题），内容 `max-w-3xl` 居中滚动，footer 固定底部；ESC 关闭但输入框聚焦时不关（isTextEditableTarget）
+- 新增页面元素：**支持的变量区**（`{{baseUrl}}`/`{{apiKey}}` 脱敏 + 眼睛切换明文）、**超时时间输入**（与自动查询间隔并排两列）
+- 超时接线：`UsageConfig.timeout_seconds`（models.rs camelCase）+ `types/index.ts timeoutSeconds`；`balance.rs::get_json` 及全部 `query_*`、`fetch_newapi_status`、`coding_plan` 3 函数加 `timeout: Duration` 参数；`query_kind` 从 usage_config 计算（0/None 回退 8s），`commands.rs` 无改动
+- i18n：`usageTimeout`/`usageTimeoutHint`/`usageSupportedVars`/`usageBack`（zh+en）
+- **测试查询体验修复**（2026-08-01 用户反馈「测试查询没有生效」）：
+  - 测试结果框改为 **sticky bottom-0**（在 body 滚动容器内），始终浮在 footer 上方，点了立即可见
+  - 「自动检测 + 无识别类型」短路：handleTest 前置检查 detectedKinds.length===0，直接展示 `usageUnsupportedProvider` 中文提示，不发无效请求
+  - 「未识别查询类型」区改为带「切换到 NewAPI 模板」快捷按钮的 amber 提示框（替换原灰色单行）
+  - 新增 i18n：`usageNoKindsHint`/`usageSwitchToNewapi`/`usageUnsupportedProvider`
+
+**验证（三批累计）**：`cargo test --lib` 46 全过、`cargo check` 干净、`tsc --noEmit` 零错误。
+**最新打包产物**（批次 3 + 体验修复 已交付用户测试）：
+- `D:\AIGC\KimiSwitch\src-tauri\target\release\bundle\nsis\Kimi Switch_0.6.3_x64-setup.exe`
+- `D:\AIGC\KimiSwitch\src-tauri\target\release\bundle\msi\Kimi Switch_0.6.3_x64_en-US.msi`
+
+### 批次 4（2026-08-01）：OAuth refresh + 测试查询短路修复
+- **背景**：用户反馈「Kimi login 又失效」——根因是 access token 15 分钟过期且 refresh 未实现（§三.3 已拍板实现）；refresh 端点与 client_id 已从 kimi.exe 二进制实测确认（`POST https://auth.kimi.com/api/oauth/token`，client_id `17e5f671-d194-4dfb-9706-5516cb48c098`，form-encoded grant_type=refresh_token）
+- `src-tauri/src/oauth.rs` — `get_valid_access_token()`：过期 → `tokio::sync::Mutex` 单 flight 锁内重读文件（CLI/其他等待者可能已刷新则直接采用）→ `refresh_credentials()` 调 token 端点 → 写回前再重读（CLI 若已轮换则采纳其 token，避免覆盖 CLI 的新 refresh_token）→ `merge_token_response()` 纯函数合并写回（保留未知字段）+ 3 个新单测
+- `src-tauri/src/commands.rs` — managed 分支改为 `get_valid_access_token().await`，错误信息直接用 refresh 的具体失败原因（含 invalid_grant 时提示重新 `kimi login`）
+- `src-tauri/Cargo.toml` — 新增 `tokio = { version = "1", features = ["sync"] }`（项目本无 tokio 直接依赖）
+- `src/components/UsageConfigModal.tsx` — 「无识别类型短路」加 `!isManaged` 守卫（managed 走 OAuth 与 detectedKinds 无关，防误伤）
+- **验证**：cargo test 48 过（+2 merge 用例）、tsc 零错误
+
+### 批次 5（2026-08-01）：用量显示本地化 + 按钮顺序调整
+- `src/lib/usage-display.ts`（新增）— `planLabel()`（five_hour→"5小时"/"5-hour"、weekly_limit→"7天"/"Weekly"，其余专名透传）+ `localizeUsageError()`（Rust 英文错误串按前缀/正则映射到 i18n，未知错误透传保留诊断信息）
+- `src/components/UsageFooter.tsx` — compact/detail 的 tier 标签与错误显示接入两个 helper
+- `src/components/UsageConfigModal.tsx` — 测试结果的 planName/错误同样本地化；catch（瞬时失败）统一显示 usageNetworkError
+- `src/components/ProviderList.tsx` — BarChart3（配置用量查询）按钮从图标组首位移到 Activity（连通测试）与 Trash（删除）之间
+- i18n 新增：`usageTier5h`/`usageTierWeekly`/`usageErrNoKey`/`usageErrDisabled`/`usageErrLoginExpired`/`usageErrNoOauth`/`usageErrNewapiCreds`（zh+en）
+- **验证**：tsc 零错误（纯前端改动，Rust 未动）
+
+### 批次 6（2026-08-01）：测试查询「无结果」根因修复
+- **根因**：`App.tsx` 顶层 `if (loading || !config) return <loading 页>`——`handleTest` 先 `onSave` → `void save()` → `setLoading(true)` → App 整树换成 loading 页 → **modal 被卸载**；查询结果回来后 setState 打到已卸载实例（无效），save 结束 modal 全新重挂载（testResult=null）。自配置面板引入即存在，任何「先保存再查询」的路径都中招。
+- `src/hooks/useConfig.ts` — `refresh`/`save` 加 `{ silent?: boolean }` 选项：silent 时不翻 loading 页（不 setLoading）
+- `src/App.tsx` — `handleSaveUsageConfig` 改为 `return save({ silent: true })`；error 分支重试按钮 `onClick={refresh}` 改箭头包装（MouseEvent 会当 opts 传入）
+- `src/components/UsageConfigModal.tsx` — `onSave` 类型改 `Promise<void> | void`；`handleTest` **await onSave 完成后再 invoke 查询**（保证后端读到同一份配置）
+- `src/components/ProviderList.tsx` — **managed（OAuth 登录托管）供应商置顶**：组件内 `[...providers].sort()` 稳定排序，仅展示层，不改 config.toml/SQLite 存储顺序
+- **验证**：tsc 零错误
+
+## 二、下一步
+
+1. **等用户测批次 3 的包**（重点：卡片图表图标 → 全屏配置页 → 变量区/超时输入 → 测试查询 → 保存后紧凑行刷新）。用户反馈优先处理。
+2. **用户确认后才 `git commit`**（建议拆 3 个 commit 对应批次 1/2/3，提交信息中文 + scope 前缀；排除 `src-tauri/Cargo.toml` 行尾改动）。
+3. 后续候选（均待用户拍板，见 §三）：OAuth refresh、NewAPI 面板自动探测、自定义 JS 提取器模板（P3）。
+
+## 三、悬而未决（用户已知情，待决定）
+
+1. **OpenCode Go 账单查询**：已实测全部端点 404（`/zen/go/v1/usages`、`/api/usage`、`/api/billing` 等 12+ 路径），cc-switch 源码也不支持 → **结论：无公开 API，不可查**。文档已记录。
+2. **Kimi login 配 API key**：可以，代码已支持（api_key 优先于 OAuth）。但 managed 供应商编辑页隐藏 key 输入框（`ProviderEdit.tsx:301` `{!provider.managed && ...}`）。选项：① 用户新建 kimi-coding 预设供应商填 key；② 改 UI 让 managed 显示可选 key 输入。
+3. **OAuth refresh**：**已实现**（批次 4）。过期自动用 refresh_token 换新并写回凭据文件；单 flight 锁 + 写回前重读防 CLI 竞态。已知边界：若 access token 未过期但被服务端吊销（罕见），401 不会触发重读重试——暂不处理。
+4. **NewAPI 面板自动探测**：打开配置面板时探测 `{base}/api/status` 含 `quota_per_unit` → 自动预选 NewAPI 模板。已提议，未确认。
+
+## 四、关键环境信息
+
+- 项目：`D:\AIGC\KimiSwitch`（Tauri 2 + React 18 + TS + Tailwind + Rust/rusqlite/reqwest），分支 `Dev_20260801`
+- 参考项目：`D:\AIGC\cc-switch`（MIT，账单查询功能源头；全屏面板参考其 `src/components/common/FullScreenPanel.tsx`）
+- 构建：`npm run tauri-build`（前后端一起，产出 msi+nsis）；`cargo test --lib`（src-tauri 下）；`npx tsc --noEmit`
+- 提交信息风格：中文 + scope 前缀（`docs:`/`build:`/`fix:`/`feat:`）
+- 用户 NewAPI 站点：`https://ai.codingplan.site`（quota_per_unit=500000，符号 ¤）；Access Token 需网页后台生成（sk- 推理 key 查不了 `/api/user/self`，实测 401）
@@ -212,8 +212,48 @@ KimiSwitch 的 `providerPresets.ts` 已镜像这套体系（`baseUrl` 与 OpenCo
 | `bailian`（阿里云百炼） | pay_as_you_go | `usageKinds` 为空 | 百炼 2026-07 上线 Coding Plan（专属 key 格式 `sk-sp-`，按**调用次数**扣额度，与 token 无关）；官方文档仅提供"控制台 Coding Plan 页面查看"，**未发现公开查询 API**。预留为待跟踪项（套餐上线早期，API 可能随后开放） |
 | `moonshot`（Kimi 开放平台） | pay_as_you_go | `usageKinds` 为空 | → 即 P0 的 `balance:kimi`，见 §4.3 |

+### 4.7 NewAPI / OneAPI 类中转站账单查询（本次重点调研）
+
+**背景**：用户使用自建 NewAPI 中转站（实测 `https://ai.codingplan.site`，`sk-` API Key 验证有效）。结论先行：
+
+1. **`sk-` API Key 查不了余额**（实测 401）。NewAPI 站点的**管理接口只认「登录 Access Token」**，不认推理令牌。cc-switch 也是这个结论——它的 NEW_API 模板填的不是 `apiKey`，而是 `accessToken` + `userId` 两个独立字段。
+2. **参考实现（cc-switch，完整链路）**：
+   - 模板代码（`UsageScriptModal.tsx:90`）：`GET {{baseUrl}}/api/user/self`，头 `Authorization: Bearer {{accessToken}}` + **`New-Api-User: {{userId}}`**；extractor 取 `data.quota`、`data.used_quota`，余额 = `quota ÷ 500000`，已用 = `used_quota ÷ 500000`（单位按站点 `quota_per_unit`，实测本站为 500000；`custom_currency_symbol` 决定是 ¥ 还是 $）。
+   - 凭据模型（`types.ts UsageScript`）：`accessToken?` / `userId?`，与 `apiKey`、`baseUrl` 并列，存供应商 `meta.usage_script`。
+   - 后端占位符替换（`usage_script.rs:413-416`）：`{{accessToken}}` / `{{userId}}` 仅在脚本含对应占位符时替换；查询凭证由 `resolve_script_credentials` 决定（显式值优先，回退供应商配置）。
+   - 安全校验（`usage_script.rs`）：**非 custom 模板强制 HTTPS + 与 base_url 同源（host+port）**；custom 模板放开（可任意 HTTPS 域名/HTTP）。
+   - 前端表单（`UsageScriptModal.tsx:1154-1230`）：NEW_API 模板下显示 Base URL / Access Token（密码框带显隐）/ User ID 三个输入；模板切换联动清理多余字段。
+3. **本站在 cc-switch 下的配置方式**：新建 Claude/Codex 供应商 → 开启用量查询 → 选 NEW_API 模板 → 填 `https://ai.codingplan.site`（Base URL）+ 网页后台 Access Token + 数字用户 ID。实测确认该站 `/api/status` 返回 `quota_per_unit: 500000`、`display_in_currency: true`、`custom_currency_symbol: ¤`（金额符号需按站确认）。
+
+### 4.8 NewAPI 适配 KimiSwitch 的落地方案
+
+KimiSwitch 现有 `usageKinds` 枚举是**每家中转站一个 Rust 函数**的路子，不适合任意 NewAPI 站。对照 cc-switch，推荐**声明式配置（不引入 JS 引擎）**：
+
+- **存储**：`Provider` 增加可选 `usageConfig?: { accessToken?: string; userId?: string }`（不写进 TOML，与 `usageKinds` 一样存 SQLite settings `usage_config:<provider_name>`，避免污染 Kimi Code 原生配置）。
+- **查询**：新增一个 `UsageKind::BalanceNewApi`（`"balance:newapi"`），Rust 侧 `query_kind` 分支：
+  - 端点：`{base_url}/api/user/self`（同源，复用 provider 的 base_url）；
+  - 头：`Authorization: Bearer {accessToken}` + `New-Api-User: {userId}`；
+  - 解析：`data.quota / data.used_quota` ÷ `quota_per_unit`（从 `/api/status` 拉取，避免硬编码 500000；失败时回退 500000）；
+  - 金额符号：`custom_currency_symbol`（未取到默认 ¥）。
+- **错误通道**：遵循现有约定（`bytes()` 再解析、瞬时/确定性分离）。
+- **前端**：`UsageFooter` 无需改；`ProviderEdit` 在启用 `usageKinds` 含 `balance:newapi` 时显示 Access Token / User ID 输入（参考 cc-switch 表单），或做成独立小弹窗。
+- **风险**：`sk-` 用户拿不到 Access Token 时无解（需登录网页后台）；同源校验天然防误查其他站。
+
 ## 5. 新增能力实现清单（改动点）

+> 实施状态（2026-07-31）：**P0 已实现，未验证、未提交**。
+> 展示方案已确认为 **A（供应商卡片底部 UsageFooter，零前端改动）**。
+> 改动文件：`src-tauri/src/services/balance.rs`（query_kimi/parse_kimi + 单测）、`src-tauri/src/services/mod.rs`（枚举/路由/detect + 单测）、`src/config/providerPresets.ts`（UsageKind/SUPPORTED_USAGE_KINDS + moonshot 预设挂 `balance:kimi`）。
+> 待办：用户确认后 `cargo test` + `tsc` 验证，验证通过再提交。
+> 遗留风险：国际站 `api.moonshot.ai/v1/users/me/balance` 端点与币种（按 USD 处理）未实测，见 §4.3。
+
+> 实施状态更新（2026-07-31 晚）：**A + B + C 已全部实现（打包验证中，未提交）**。
+> - **A（OAuth）**：新增 `src-tauri/src/oauth.rs`（读 `~/.kimi-code/credentials/kimi-code.json` access_token，过期 30s 缓冲，不做 refresh），`query_provider_usage` 的 managed 分支从"报 API key 错误"改为读 OAuth 凭据走 `plan:kimi_coding` 查询；`managed:kimi-code` 卡片不再显示"API Key 无效"。
+> - **B（NewAPI）**：`services/balance.rs` 加 `query_newapi`（`{base_url}/api/user/self` + Bearer accessToken + `New-Api-User` userId，`/api/status` 运行态拉 `quota_per_unit` 与 `custom_currency_symbol`，进程内缓存）；`UsageKind` 加 `BalanceNewApi`（`"balance:newapi"`，ALL 变 10）；`query_kind` 签名加 `usage_config` 参数。
+> - **C（配置面板 + 布局）**：新增 `UsageConfigModal.tsx`（启用开关 / 自动检测 vs NewAPI 模板 / 凭据输入 / 自动查询间隔 / 测试按钮，参考 cc-switch UsageScriptModal 但裁剪）；`UsageFooter` 拆分 compact（卡片右上：主摘要 + `x 前` + 刷新）与 detail（底部：多档明细 + 错误/重试）；`ProviderList` 加 BarChart3 配置入口按钮；`usageConfig` 存 SQLite settings（`usage_config:<provider_name>`），不进 config.toml。
+> - **验证**：`cargo test` 46 通过（新增 oauth 凭据解析/过期、newapi 解析 5 个用例、UsageKind roundtrip 10 项）、`tsc --noEmit` 零错误；打包供用户测试。
+> - **改动文件**：Rust 6 个（oauth.rs 新增、models.rs、commands.rs、services/mod.rs、services/balance.rs、lib.rs）+ 前端 7 个（types/index.ts、UsageConfigModal.tsx 新增、UsageFooter.tsx、ProviderList.tsx、App.tsx、i18n/zh.ts、i18n/en.ts）。
+
 以 **P0：Kimi 开放平台余额（`balance:kimi`）** 为例，完整改动点如下（严格套用现有四步模式，前端展示零改动）：

 1. **Rust** `src-tauri/src/services/balance.rs`
@@ -238,8 +278,10 @@ KimiSwitch 的 `providerPresets.ts` 已镜像这套体系（`baseUrl` 与 OpenCo
 | **P0** | Kimi 开放平台余额 `balance:kimi` | balance.rs + mod.rs + providerPresets.ts | 小（~1 天） | 低；EN 端点待实测 |
 | P1 | ZenMux 套餐（照搬 cc-switch） | coding_plan.rs + mod.rs + 预设 | 小 | 低 |
 | P1 | 火山方舟 Coding Plan（AK/SK 签名 V4） | coding_plan.rs + 凭据存储 + 表单 | 中 | 签名细节易错，需单测 |
-| P2 | 智谱团队版 / 中转站声明式配置（new-api 类） | 架构决策后实施 | 中-大 | 需先定方案 |
-| P3 | JS 脚本引擎 / 官方 OAuth 订阅 / 托盘用量 | — | 大 | 与目标 CLI 不匹配，建议不做 |
+| P2 | 智谱团队版 | coding_plan.rs + 凭据存储 + 表单 | 中 | 需扩展 Provider 凭据 |
+| **P1** | **NewAPI 中转站余额 `balance:newapi`**（§4.8 声明式方案：`usageConfig{accessToken,userId}` + `/api/user/self`） | balance.rs + mod.rs + db 存储 + ProviderEdit 表单 | 中 | 需用户提供 Access Token；站点 quota_per_unit/符号需运行态拉取 |
+| P3 | JS 脚本引擎（custom/general） | usage_script.rs 移植（rquickjs） | 大 | 覆盖面广但工程量大；被 `balance:newapi` 声明式方案覆盖主场景后可暂缓 |
+| P3 | 官方 OAuth 订阅 / 托盘用量 | — | 大 | 与目标 CLI 不匹配，建议不做 |
 | P3 | 查询请求走代理（见 §6.1） | balance.rs 共用 Client 改造 | 小-中 | 依赖全局代理设置是否已存在 |

 ### 6.1 遗漏盘点（首轮调研未覆盖，本次补查确认）
@@ -262,6 +304,8 @@ KimiSwitch 的 `providerPresets.ts` 已镜像这套体系（`baseUrl` 与 OpenCo
 4. **响应读体与解析分离**：所有查询先 `bytes()` 再 parse，保持瞬时/确定性错误通道不混淆（已统一在 `balance.rs::get_json`）。
 5. **金额单位**：Novita ×0.0001 USD；Kimi 余额为 CNY；Go 套餐按 USD 计。
 6. **TS/Rust 枚举漂移**：新增 kind 必须同时改 `UsageKind` union + `SUPPORTED_USAGE_KINDS` + Rust 枚举三处，否则 dev 断言报错。
+7. **NewAPI 特有点（§4.7 实测）**：`sk-` API Key 与 Access Token 是两套凭据，前者**查不了** `/api/user/self`；`New-Api-User` 头必须带；余额 = `quota/used_quota ÷ quota_per_unit`（本站 500000）；`quota` 为 0 常表示该令牌"无限额度"（后台设置），不要显示成余额为 0。
+8. **NewAPI 同源**：`/api/user/self` 与推理同源（同一 base_url host），天然可复用车基地址；若经代理访问站点，`/api/status` 也要走代理（见 §6.1 代理改造）。

 ---

@@ -289,6 +333,9 @@ KimiSwitch 的 `providerPresets.ts` 已镜像这套体系（`baseUrl` 与 OpenCo
 - Kimi Code 文档（服务地址 / 环境变量 / 错误参考）：https://www.kimi.com/code/docs/ 、 https://www.kimi.com/code/docs/kimi-code-cli/configuration/env-vars.html
 - Kimi 帮助中心（余额与用量、会员权益）：https://www.kimi.com/zh-cn/help/kimi-api/api-balance-and-usage 、 https://www.kimi.com/zh-cn/help/kimi-code/membership-guide
 - 智谱 GLM Coding Plan 额度 API（cc-switch issue 社区确认）：https://github.com/farion1231/cc-switch/issues/1588 、 https://github.com/seakee/CPA-Manager-Plus/issues/379
+- NewAPI / OneAPI `/api/user/self` 接口（社区文档）：https://juejin.cn/post/7493007002832551988 、 https://allinone.apifox.cn/399558528e0 、 https://docs.laozhang.ai/faq/balance-query-api
+- NewAPI 用户管理文档：https://www.newapi.ai/zh/docs/guide/feature-guide/admin/user
+- 实测站点：`https://ai.codingplan.site`（`/api/status`：quota_per_unit=500000、display_in_currency=true）
 - Kimi 余额查询（cc-switch issue，官方 API 引入）：https://github.com/farion1231/cc-switch/issues/4455
 - OpenCode Go 套餐额度：https://opencode.ai/docs/go/
 - OpenCode providers / 配置：https://opencode.ai/docs/providers/