pi-multi-quota 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wyouwd1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# pi-multi-quota
+
+在 pi 的 footer 里实时显示**当前模型所属供应商**的额度 —— 纯 HTTP、零子进程、零运行时依赖。
+
+为「一个 pi 里同时挂着多个供应商、且其中一家有多个账号」的场景设计。
+
+---
+
+## 支持范围
+
+| 供应商 | 显示内容 | 凭据来源 |
+|---|---|---|
+| **火山方舟 Ark**（Coding Plan） | 5h / 周 / 月 已用百分比 | 控制台 cookie（手动维护，见下） |
+| **OpenCode Go**（Zen） | rolling（footer 显示为 5h）/ weekly / monthly 百分比 | 复用 pi 已配置的 API key |
+| **DeepSeek** | 账户余额（CNY / USD 分别显示） | 复用 pi 已配置的 API key |
+
+footer 跟随当前模型：用 Ark 的模型时显示 Ark 的**全部账号**，切到 OpenCode 就整段换成 OpenCode。
+
+---
+
+## 安装
+
+从 npm 安装（推荐，已收录进 [pi.dev/packages](https://pi.dev/packages) 包目录）：
+
+```bash
+pi install npm:pi-multi-quota
+```
+
+从 GitHub 安装：
+
+```bash
+pi install https://github.com/wyouwd1/pi-multi-quota
+```
+
+本地克隆安装（开发用，在仓库根目录执行）：
+
+```bash
+git clone https://github.com/wyouwd1/pi-multi-quota
+cd pi-multi-quota
+pi install .
+```
+
+装完重启 pi 或 `/reload`。
+
+> footer 只在当前模型属于上表三家供应商之一时出现；切到其它 provider 时 footer 段会清空，这是预期行为。
+
+卸载时用**与安装时相同的 source 标识**：
+
+```bash
+pi remove npm:pi-multi-quota                        # 从 npm 安装的
+pi remove https://github.com/wyouwd1/pi-multi-quota   # 从 GitHub 安装的
+pi remove .                                          # 从克隆目录安装的（在仓库根目录执行）
+```
+
+---
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/quota` | 展开**当前供应商**明细（各窗口百分比 + 重置倒计时 / 余额明细） |
+| `/quota all` | 一次查询三家（Ark 每个账号 + Zen + DeepSeek）。仅**当前 provider** 对应的数据源能取到凭据，其余两家显示 `✗ 未配置` |
+| `/quota set <账号>` | 粘贴并**当场校验** Ark cookie（校验失败绝不保存） |
+| `/quota list` | 列出已配置账号及其 cookie 剩余有效期 |
+| `/quota close` | 关闭详情面板 |
+
+---
+
+## 配置 Ark cookie（重点）
+
+Ark 的额度只能通过**控制台接口**读取，需要一份浏览器 cookie。这是唯一需要手动维护的东西。
+
+### 首次配置
+
+1. 浏览器打开并登录：`https://console.volcengine.com/ark/region:cn-beijing/subscription/coding-plan`
+2. `F12` → Console → 输入 `document.cookie` → 回车 → **复制整段结果**
+3. **先创建账号槽位**：编辑 `~/.pi/agent/multi-quota.json`（不存在则新建；若 `~/.pi/agent/` 目录也不存在，先 `mkdir -p ~/.pi/agent`），内容为：
+
+   ```json
+   {"ark":{"accounts":[{"id":"ark-a","provider":"<你在 pi 里配置的 provider id>","cookie":""}]}}
+   ```
+
+   `/quota set` 要求槽位**已存在**，所以必须先建槽位、再用 `/quota set ark-a` 粘贴 cookie；
+   此时 `cookie` 留空字符串即可（footer 会显示该槽位「未配置」而不是报错）。
+   `provider` 填你在 pi 里配置的 provider id（可在 pi 的 provider / 模型配置里查到）。它只用于识别「当前模型对应哪个 Ark 账号」，决定 footer 在窄终端下优先保住哪个账号的完整显示；数据源由模型 baseUrl 的 host 决定，填错不会报错、额度照常显示，但 footer 会退化为单窗口形态。
+   建好文件后建议 `chmod 600 ~/.pi/agent/multi-quota.json`（手工创建时权限取决于 umask；扩展自己写入时会自动收紧到 600）。
+4. 回到 pi 运行 `/quota set ark-a` → 粘贴 → 回车
+5. 扩展会**立刻发一次真实请求**校验：
+   - 通过 → 保存（文件权限 `600`）→ footer 立即刷新，并回显该账号当前额度
+   - 失败 → 告诉你具体原因（`cookie 过期` / `cookie 不完整`），**不会写入任何东西**
+
+### 两个账号（或更多）
+
+⚠️ **火山 SSO 的登录态是浏览器级共享的** —— 在同一个浏览器里登录账号 B，会把账号 A 的 cookie 顶掉。
+
+所以要同时持有两份有效 cookie，需要：
+
+- 一个用正常窗口，另一个用**隐身窗口 / 另一个浏览器 / 另一台设备**
+- 先按「首次配置」第 3 步在 `~/.pi/agent/multi-quota.json` 的 `accounts` 数组里追加 `ark-b` 槽位（`id` 为 `ark-b`、`provider` 填账号 B 对应的 pi provider id、`cookie` 留空）
+- 分别登录 → 各自复制一次 cookie → 分别 `/quota set ark-a`、`/quota set ark-b`
+
+**防呆**：扩展会读取 cookie 里的 `AccountID`，如果新 cookie 与另一个槽位是**同一个火山账号**，会拒绝保存并提示 —— 避免两个槽位贴成同一份。
+
+### cookie 会过期
+
+cookie 里的 `digest` 是 SSO access token，**约 24 小时失效**。
+
+- 剩余 < 2 小时：开会话时 **toast 提示一次**（footer 不额外标记）
+- 已失效：footer 显示 `Ark-A ✗ cookie 过期`（**不影响** Ark-B 等其他账号）
+- 处理：重新走一遍上面的步骤，`/quota set ark-a` 覆盖即可
+
+用 `/quota list` 可以随时查看各账号还剩多久。
+
+---
+
+## 配置文件
+
+路径：`~/.pi/agent/multi-quota.json`（写入时自动设为 `600`）
+
+```json
+{
+  "ark": {
+    "accounts": [
+      { "id": "ark-a", "provider": "volcengine",   "cookie": "<粘贴的整段 cookie>" },
+      { "id": "ark-b", "provider": "volcengine-2", "cookie": "<粘贴的整段 cookie>" }
+    ]
+  }
+}
+```
+
+- `id`：账号标识，决定 footer 里的显示名（`ark-a` → `Ark-A`）
+- `provider`：你在 pi 里的 provider id，仅用于把「当前模型」对应到 Ark 账号（footer 裁剪优先级）；数据源按 baseUrl host 判定，与它无关
+- `cookie`：留空字符串表示「尚未配置」，footer 会显示该槽位未配置而不是报错
+
+> OpenCode 与 DeepSeek 的密钥**不需要写进这个文件** —— 扩展通过 pi 的凭据系统读取，不重复存储。
+
+---
+
+## 状态与错误对照
+
+| footer 显示 | 含义 | 怎么办 |
+|---|---|---|
+| `Ark-A 5h 13% wk 37% mo 100%` | 正常 | — |
+| `~Ark-A 5h 13% …` | 本次刷新失败，显示的是**上次成功数据** | 等待自动退避重试 |
+| `Ark-A ✗ 未配置` / `Zen ✗ 未配置` | Ark：该槽位 cookie 为空；Zen / DeepSeek：当前 provider 的 key 取不到（如 `/quota all` 里的非当前供应商） | Ark 用 `/quota set ark-a`；Zen / DeepSeek 切到对应 provider 即恢复 |
+| `Ark-A ✗ cookie 过期` | `digest` 已失效（约 24h） | `/quota set ark-a` |
+| `Ark-A ✗ cookie 不完整` | 缺 `csrfToken`，多半是没复制全 | 重新复制**整段** cookie |
+| `✗ 接口变更` | 响应结构不认识（供应商改了接口） | 需要更新本扩展 |
+| `✗ 网络错误` / `✗ 超时` | 网络问题 | 自动退避（5min → 30min 封顶） |
+
+---
+
+## 安全边界
+
+- cookie 只存在本地 `~/.pi/agent/multi-quota.json`，权限 `600`
+- **cookie 原文不会出现在**日志、错误信息、footer、session 文件里 —— 错误信息只保留错误码
+- 只向固定的供应商 host 发送凭据：`console.volcengine.com`（Ark）/ `opencode.ai`（OpenCode）/ `api.deepseek.com`（DeepSeek）。三家 URL 都是源码常量；Ark 另在发起前复核目标 host，白名单外直接拒绝
+- 三个供应商的请求都带 `redirect: "error"`：拒绝跟随重定向，防止凭据被转发到其他 host
+- **不**读取浏览器 cookie 数据库、**不**启动浏览器、**不**调用任何外部 CLI、**不**起子进程
+- 额度数据不写入 session，也不发送给模型
+
+---
+
+## 开发
+
+前置要求：Node **>= 20**（见 `package.json` 的 `engines`），且已安装 pi 编码助手。
+仓库不含 `node_modules`，先装依赖再跑测试：
+
+```bash
+npm install     # 安装 tsx / typescript 等开发依赖
+npm test        # node --import tsx --test test/*.test.ts
+npm run typecheck
+pi -e ./src/index.ts   # 临时加载（不写入 settings）
+```
+
+### 结构
+
+```
+src/
+├── index.ts          # 扩展入口：事件订阅 + /quota 命令族
+├── types.ts          # 跨模块类型契约
+├── registry.ts       # baseUrl host → 数据源分派 + 凭据解析
+├── cookie.ts         # Ark cookie 解析（csrfToken / AccountID / digest exp）
+├── config.ts         # 配置文件读写（原子写入 + 权限 600 + 脱敏）
+├── cache.ts          # TTL 缓存 + stale 保留 + 并发去重 + 指数退避
+├── footer.ts         # footer 渲染 + 宽度裁剪 / 详情渲染
+└── sources/
+    ├── ark.ts        # 控制台 GetCodingPlanUsage（POST + csrf）
+    ├── opencode.ts   # /zen/go/v1/usage
+    └── deepseek.ts   # /user/balance
+```
+
+设计与决策记录见 [`SPEC.md`](./SPEC.md)。
+
+### 已知限制
+
+- Ark cookie **必须手动更新**（约每 24 小时一次）；未实现自动续期 —— 控制台接口无公开刷新链路
+- 只支持上述三个供应商，新增供应商需要写一个 `src/sources/*.ts` 适配器并在 `registry.ts` 注册
+- 不做历史用量统计与图表

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-multi-quota",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension: 纯 HTTP 查询 Ark 双账号 / OpenCode Go / DeepSeek 额度，footer 跟随当前模型展示",
+  "license": "MIT",
+  "author": "wyouwd1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wyouwd1/pi-multi-quota.git"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "homepage": "https://github.com/wyouwd1/pi-multi-quota#readme",
+  "bugs": { "url": "https://github.com/wyouwd1/pi-multi-quota/issues" },
+  "keywords": ["pi-package", "pi-extension", "quota", "usage"],
+  "pi": { "extensions": ["./src/index.ts"] },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^26.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.0"
+  },
+  "engines": { "node": ">=20" }
+}

package/src/cache.ts

@@ -0,0 +1,152 @@
+/**
+ * 额度缓存层：TTL、stale 标记、失败退避与并发去重。
+ *
+ * 设计要点：
+ * - 所有时间点通过 `now` 参数注入，测试不依赖真实计时器。
+ * - 缓存内部持有一份浅拷贝，`noteFailure` 不去修改调用方传入的对象。
+ * - 库文件静默，不打印任何日志；错误信息不落缓存（由调用方负责脱敏）。
+ */
+import type { AccountReport } from "./types.js";
+
+export interface QuotaCacheOptions {
+  /** 数据新鲜期，默认 5 分钟。 */
+  ttlMs?: number;
+  /** 退避初值，默认 5 分钟。 */
+  backoffBaseMs?: number;
+  /** 退避上限，默认 30 分钟。 */
+  backoffMaxMs?: number;
+}
+
+/**
+ * 缓存句柄。仅作为不透明标记类型对外暴露，
+ * 内部状态通过 CacheState 在模块内访问。
+ */
+export interface QuotaCache {
+  readonly __brand: "QuotaCache";
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_BACKOFF_BASE_MS = 5 * 60 * 1000;
+const DEFAULT_BACKOFF_MAX_MS = 30 * 60 * 1000;
+
+/** 连续失败计数与下次允许查询的时刻。 */
+interface FailureState {
+  count: number;
+  nextAllowedAt: number;
+}
+
+interface CacheState {
+  readonly __brand: "QuotaCache";
+  readonly ttlMs: number;
+  readonly backoffBaseMs: number;
+  readonly backoffMaxMs: number;
+  /** 最近一次数据（可能已过期、可能已标 stale）。 */
+  readonly reports: Map<string, AccountReport>;
+  readonly failures: Map<string, FailureState>;
+  /** 在途 Promise，key 由 dedupe 调用方决定。 */
+  readonly inflight: Map<string, Promise<unknown>>;
+}
+
+export function createCache(opts: QuotaCacheOptions = {}): QuotaCache {
+  const cache: CacheState = {
+    __brand: "QuotaCache",
+    ttlMs: opts.ttlMs ?? DEFAULT_TTL_MS,
+    backoffBaseMs: opts.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS,
+    backoffMaxMs: opts.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS,
+    reports: new Map(),
+    failures: new Map(),
+    inflight: new Map(),
+  };
+  return cache;
+}
+
+/** 把不透明句柄还原为内部状态。 */
+function stateOf(cache: QuotaCache): CacheState {
+  return cache as CacheState;
+}
+
+/** 第 n 次连续失败（n ≥ 1）的退避时长，以 backoffMaxMs 封顶。 */
+function backoffDelayMs(state: CacheState, failureCount: number): number {
+  const exponent = failureCount > 1 ? failureCount - 1 : 0;
+  const delay = state.backoffBaseMs * 2 ** exponent;
+  return Math.min(delay, state.backoffMaxMs);
+}
+
+/** 未过期（now - fetchedAt < ttlMs）才返回。 */
+export function getFresh(cache: QuotaCache, accountId: string, now?: number): AccountReport | undefined {
+  const state = stateOf(cache);
+  const report = state.reports.get(accountId);
+  if (!report) return undefined;
+  const at = now ?? Date.now();
+  return at - report.fetchedAt < state.ttlMs ? report : undefined;
+}
+
+/** 即使已过期也返回，调用方据 `stale` / `fetchedAt` 判断展示方式。 */
+export function getLastKnown(cache: QuotaCache, accountId: string): AccountReport | undefined {
+  return stateOf(cache).reports.get(accountId);
+}
+
+/** 记录一次成功数据；report.fetchedAt 有效时以它为准，否则用 now。 */
+export function put(cache: QuotaCache, report: AccountReport, now?: number): void {
+  const state = stateOf(cache);
+  const fetchedAt = Number.isFinite(report.fetchedAt) ? report.fetchedAt : (now ?? Date.now());
+  state.reports.set(report.accountId, { ...report, fetchedAt });
+}
+
+/** 查询失败：已有数据标记为 stale，并累计失败计数用于退避。 */
+export function noteFailure(cache: QuotaCache, accountId: string, now?: number): void {
+  const state = stateOf(cache);
+  const at = now ?? Date.now();
+
+  const existing = state.reports.get(accountId);
+  if (existing && existing.stale !== true) {
+    state.reports.set(accountId, { ...existing, stale: true });
+  }
+
+  const count = (state.failures.get(accountId)?.count ?? 0) + 1;
+  state.failures.set(accountId, { count, nextAllowedAt: at + backoffDelayMs(state, count) });
+}
+
+/** 查询成功：清空失败计数与退避窗口。 */
+export function noteSuccess(cache: QuotaCache, accountId: string): void {
+  stateOf(cache).failures.delete(accountId);
+}
+
+/**
+ * 是否应当发起网络查询：
+ * 成功数据仍新鲜 → false；失败后尚在退避窗口内 → false；其余 → true。
+ */
+export function shouldQuery(cache: QuotaCache, accountId: string, now?: number): boolean {
+  const state = stateOf(cache);
+  const at = now ?? Date.now();
+  if (getFresh(cache, accountId, at)) return false;
+
+  const failure = state.failures.get(accountId);
+  if (failure && at < failure.nextAllowedAt) return false;
+
+  return true;
+}
+
+/**
+ * 并发去重：同一 key 的在途 Promise 直接复用。
+ * 无论成功或失败都在 settle 后清除，避免永久缓存 rejected promise；
+ * fn 同步抛错时不入表（否则会留下永不 settle 的条目）。
+ */
+export function dedupe<T>(cache: QuotaCache, key: string, fn: () => Promise<T>): Promise<T> {
+  const state = stateOf(cache);
+  const existing = state.inflight.get(key);
+  if (existing) return existing as Promise<T>;
+
+  let inner: Promise<T>;
+  try {
+    inner = fn();
+  } catch (err) {
+    return Promise.reject(err);
+  }
+
+  const tracked = inner.finally(() => {
+    if (state.inflight.get(key) === tracked) state.inflight.delete(key);
+  });
+  state.inflight.set(key, tracked);
+  return tracked;
+}

package/src/config.ts

@@ -0,0 +1,170 @@
+/**
+ * 配置存储：读写 ~/.pi/agent/multi-quota.json，含权限加固、损坏保护与脱敏工具。
+ *
+ * 约束（SPEC.md §6 安全边界 · §12 Boundaries）：
+ * - 文件损坏时只报错，**绝不覆盖**用户文件；
+ * - 写入走「临时文件 + rename」原子替换，权限固定 600；
+ * - redact() 供一切日志/错误信息使用，禁止 cookie / key 原文外泄。
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** 单个 Ark 账号的配置。 */
+export interface ArkAccountConfig {
+  /** 账号 id，例如 "ark-a"。 */
+  id: string;
+  /** 绑定的 pi provider id，例如 "volcengine"。 */
+  provider: string;
+  /** 控制台 cookie 原文。 */
+  cookie: string;
+}
+
+/** 持久化配置结构。 */
+export interface QuotaConfig {
+  ark: { accounts: ArkAccountConfig[] };
+}
+
+/** 测试用覆盖变量：指向隔离的配置文件，避免测试污染真实 ~/.pi/agent/。 */
+const CONFIG_PATH_ENV = "PI_MULTI_QUOTA_CONFIG";
+
+/** 配置文件绝对路径：~/.pi/agent/multi-quota.json。 */
+export function configPath(): string {
+  const override = process.env[CONFIG_PATH_ENV];
+  if (override !== undefined && override.trim() !== "") return path.resolve(override);
+  return path.join(os.homedir(), ".pi", "agent", "multi-quota.json");
+}
+
+/** 默认空结构。每次返回新对象，避免调用方改到共享引用。 */
+function defaultConfig(): QuotaConfig {
+  return { ark: { accounts: [] } };
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+/** 错误码，用于拼接不含敏感内容的错误信息。 */
+function errorCode(err: unknown): string {
+  const code = asObject(err)?.["code"];
+  return typeof code === "string" ? code : "unknown";
+}
+
+/** 把磁盘上的任意 JSON 规范化成合法 QuotaConfig：缺字段补默认值，非法账号条目丢弃。 */
+function normalizeConfig(raw: unknown): QuotaConfig {
+  const root = asObject(raw);
+  const ark = root === undefined ? undefined : asObject(root["ark"]);
+  const rawAccounts = ark === undefined || !Array.isArray(ark["accounts"]) ? [] : ark["accounts"];
+  const accounts: ArkAccountConfig[] = [];
+  for (const item of rawAccounts) {
+    const entry = asObject(item);
+    if (entry === undefined) continue;
+    const { id, provider, cookie } = entry;
+    if (typeof id !== "string" || typeof provider !== "string" || typeof cookie !== "string") continue;
+    accounts.push({ id, provider, cookie });
+  }
+  return { ark: { accounts } };
+}
+
+/** 文件不存在 → 返回默认空结构；JSON 损坏 → 抛错，绝不覆盖用户文件。 */
+export function loadConfig(): QuotaConfig {
+  const file = configPath();
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return defaultConfig();
+    throw new Error(`读取配置失败：${file}（${errorCode(err)}）`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // 不覆盖用户文件：损坏时只报错，把修复权交回用户。
+    throw new Error(`配置文件不是合法 JSON，已保留原文件未做修改：${file}`);
+  }
+  return normalizeConfig(parsed);
+}
+
+/** 同进程内的临时文件序号，保证同毫秒多次写入不撞名。 */
+let tmpCounter = 0;
+
+/** 写入并将权限设为 600。先写临时文件再 rename，避免中断留下半截配置。 */
+export function saveConfig(cfg: QuotaConfig): void {
+  const file = configPath();
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  tmpCounter += 1;
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}-${tmpCounter}.tmp`);
+  const data = `${JSON.stringify(cfg, null, 2)}\n`;
+  try {
+    // flag "wx"：同名临时文件已存在时直接失败，避免跟随符号链接写入他人文件
+    fs.writeFileSync(tmp, data, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    fs.chmodSync(tmp, 0o600); // umask 可能放宽 mode，显式收紧
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // 清理失败不掩盖原始写入错误
+    }
+    throw err;
+  }
+}
+
+const REDACTED = "<redacted>";
+
+/**
+ * 敏感键值对：`digest=…` / `"csrfToken": "…"` / `CSRF-Token: …` 等形态，值一律替换。
+ * 键名列表是脱敏的唯一来源，新增键名只需改这里。
+ */
+const KEY_VALUE_PATTERN =
+  /(["']?)(digest|csrf_?token|csrf-token|x-csrf-token|cookie|set-cookie|token|access_?token|refresh_?token|sessionid|session_id|jsessionid|session|sso_?token|passport|passwd|password|secret|api[_-]?key)(["']?\s*[=:]\s*)(["']?)([^\s"',;]+)/gi;
+
+/** 形如 `k=v; k=v; ...` 的 cookie 串（≥2 对键值）。 */
+const COOKIE_SHAPE_PATTERN = /[A-Za-z0-9_%.-]+=[^;\s"']*(?:\s*;\s*[A-Za-z0-9_%.-]+=[^;\s"']*)+/g;
+
+/** `authorization` 行通常整段都是凭据，值一律抹掉。 */
+const AUTHORIZATION_PATTERN = /(\bauthorization\b["']?\s*[=:]\s*)(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\r\n]+)/gi;
+
+const BEARER_PATTERN = /(\bBearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+
+/** `sk-` / `ark-` 前缀的 API key。 */
+const API_KEY_PATTERN = /\b(?:sk|ark)-[A-Za-z0-9_-]{6,}/g;
+
+/** 只有含敏感键名的 cookie 串才整段替换，普通 `a=1; b=2` 文本保持原样。 */
+function containsSensitiveKey(cookieText: string): boolean {
+  KEY_VALUE_PATTERN.lastIndex = 0; // 全局正则带状态，进出都复位
+  const found = KEY_VALUE_PATTERN.test(cookieText);
+  KEY_VALUE_PATTERN.lastIndex = 0;
+  return found;
+}
+
+/** 把文本中的 cookie/key 值替换为 <redacted>，供任何日志/错误信息使用。 */
+export function redact(text: string): string {
+  return text
+    .replace(COOKIE_SHAPE_PATTERN, (match) => (containsSensitiveKey(match) ? REDACTED : match))
+    .replace(AUTHORIZATION_PATTERN, `$1${REDACTED}`)
+    .replace(KEY_VALUE_PATTERN, (_match, q1: string, key: string, sep: string, q2: string) => `${q1}${key}${sep}${q2}${REDACTED}`)
+    .replace(BEARER_PATTERN, `$1${REDACTED}`)
+    .replace(API_KEY_PATTERN, REDACTED);
+}
+
+export function findArkAccountByProvider(cfg: QuotaConfig, providerId: string): ArkAccountConfig | undefined {
+  return cfg.ark.accounts.find((account) => account.provider === providerId);
+}
+
+export function findArkAccountById(cfg: QuotaConfig, id: string): ArkAccountConfig | undefined {
+  return cfg.ark.accounts.find((account) => account.id === id);
+}
+
+/** 按 id upsert；若同 id 已存在则替换其 provider/cookie。入参与其中的账号对象都不被修改。 */
+export function upsertArkAccount(cfg: QuotaConfig, account: ArkAccountConfig): QuotaConfig {
+  const next: ArkAccountConfig = { id: account.id, provider: account.provider, cookie: account.cookie };
+  const index = cfg.ark.accounts.findIndex((existing) => existing.id === account.id);
+  if (index === -1) return { ark: { accounts: [...cfg.ark.accounts, next] } };
+  return { ark: { accounts: cfg.ark.accounts.map((existing, i) => (i === index ? next : existing)) } };
+}