pi-ark-usage 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # pi-ark-usage
 
-在 pi TUI 中显示**火山引擎方舟 Coding Plan / Agent Plan** 的套餐用量，数据来自 [`arkcli`](https://www.volcengine.com/docs/82379) 的 `arkcli usage plan`。
+在 pi TUI 中显示**火山引擎方舟 Coding Plan / Agent Plan** 的套餐用量，数据直接来自火山方舟 OpenAPI `GetCodingPlanUsage`（AK/SK 签名，官方 [`@volcengine/openapi`](https://github.com/volcengine/volc-sdk-nodejs) SDK 的 Signer）。
 
 ```
 Volc Usage: sess 30%(reset after 4h18m) / wk 37%(reset after 4d) / mo 19%(reset after 29d)        now
@@ -8,7 +8,7 @@ Volc Usage: sess 30%(reset after 4h18m) / wk 37%(reset after 4d) / mo 19%(reset
 
 ## 特性
 
-- **零额外鉴权**：认证完全由 arkcli 自己管理（SSO / profile），本扩展不接触、不保存任何 API Key
+- **AK/SK 直连 OpenAPI**：不走子进程、不依赖 SSO 登录态；凭据只从环境变量或配置文件读取，本扩展不保存、不上传任何 Key
 - **三个周期同屏**：session（会话）/ weekly（周）/ monthly（月），并显示各周期重置倒计时
 - **阈值着色**：低用量绿色、接近上限黄色、超过红线红色
 - **单轮消耗**：以每轮对话开始前的快照为基线，结算时标注各周期增量（如 `(+2)`）
@@ -18,17 +18,21 @@ Volc Usage: sess 30%(reset after 4h18m) / wk 37%(reset after 4d) / mo 19%(reset
 
 ## 前置条件
 
-1. 已安装并登录 arkcli：
+1. 火山引擎 AK/SK（具有方舟/Coding Plan 查询权限），按以下顺序解析：
 
-   ```bash
-   arkcli --help
-   arkcli auth login   # 按 arkcli 自己的流程完成 SSO 登录
+   1. 环境变量 `VOLC_ACCESSKEY` / `VOLC_SECRETKEY`（可选 `VOLC_SESSION_TOKEN`）
+   2. `~/.volc/config`，JSON 格式（与官方 SDK 默认路径一致）：
+
+   ```json
+   { "VOLC_ACCESSKEY": "AKXXX", "VOLC_SECRETKEY": "SKXXX" }
    ```
 
-   也可用环境变量 `PI_ARK_USAGE_ARKCLI` 指定 arkcli 的绝对路径。
+   建议将文件权限设为 0600。
 
 2. pi 版本 >= 0.86（扩展机制）。
 
+> 注：OpenAPI 返回的是凭据所属账号的套餐用量，`/arkset product|seat` 仅影响展示映射，接口本身不支持按产品/Seat 过滤。
+
 ## 安装
 
 开发期可直接加载本地文件：
@@ -63,15 +67,15 @@ pi install npm:pi-ark-usage
 |---|---|
 | `/arkset yellow <n>` | 黄色阈值（百分比，默认 40），须低于红线 |
 | `/arkset red <n>` | 红色阈值（百分比，默认 80），须高于黄线 |
-| `/arkset auto <分钟>` | 空闲自动刷新间隔，0–30 的整数，`0` 关闭（默认关闭） |
-| `/arkset product <id>` | 固定查询的产品：`auto`（默认）/ `coding-plan` / `agent-plan` / `coding-plan-team` / `agent-plan-team` |
+| `/arkset auto <分钟>` | 空闲自动刷新间隔，0–30 的整数，`0` 关闭（默认 5 分钟） |
+| `/arkset product <id>` | 展示映射的产品：`auto`（默认）/ `coding-plan` / `agent-plan` / `coding-plan-team` / `agent-plan-team` |
 | `/arkset seat <id>` | 团队版指定 SeatID；`/arkset seat none` 清除 |
 | `/arkset lang <zh\|en>` | UI language, default English |
 | `/arkset reset` | 恢复全部默认设置 |
 
 ### 产品选择规则
 
-- `/arkset product` 非 `auto` 时，固定查询指定产品（团队版可配合 `seat`）。
+- `/arkset product` 非 `auto` 时，固定展示指定产品。
 - `auto`（默认）：
   1. 按当前模型的 provider 映射（`coding-plan` → coding-plan 等）；
   2. 映射不到时，显示最近一次成功抓取的已订阅产品。
@@ -85,12 +89,14 @@ pi install npm:pi-ark-usage
 | `agent_start` | 建立本轮基线（缓存 1 小时内有效；否则限时 3 秒补抓，超时沿用缓存） |
 | `agent_settled` | 本轮结算抓取，并与基线对比标注消耗 |
 | `/arkcheck` | 手动强制刷新 |
-| 可选自动刷新 | 仅当 `/arkset auto` 开启时按间隔执行 |
+| 可选自动刷新 | 默认每 5 分钟（`/arkset auto` 可调 0–30，`0` 关闭） |
+
+> 注意：`auto` 设置会持久化到磁盘 cache；旧版本用户若曾显式设过 `0`，升级后仍是关闭，需手动 `/arkset auto 5` 开启。
 
 ## 工作原理
 
-1. 通过 `child_process.execFile` 调用 `arkcli usage plan --format json`（固定产品时加 `--product`，团队版可加 `--seat`）。
-2. 对返回 JSON 做结构校验（产品 ID、period 百分比、长度上限），只保留已订阅且含周期数据的条目。
+1. 用官方 `@volcengine/openapi` 的 `Signer` 对 `POST open.volcengineapi.com?Action=GetCodingPlanUsage&Version=2024-01-01`（service `ark`，region `cn-beijing`）做 V4 签名后 fetch。
+2. 解析 `Result.QuotaUsage[]`（`Level/Percent/ResetTimestamp`，秒级时间戳转 `+08:00` ISO 字符串），做结构与取值校验。
 3. 快照存入内存 Map，并以原子写（tmp 文件 + rename）持久化到 `~/.pi/agent/pi-ark-usage/`。
 4. Widget 通过 `ctx.ui.setWidget(..., { placement: "belowEditor" })` 渲染在编辑器下方；age（抓取于多久前）右对齐，终端过窄时自动折成两行。
 

package/extensions/index.ts

@@ -1,9 +1,10 @@
 /**
  * pi-ark-usage
  *
- * Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI via
- * `arkcli usage plan`. Auth is fully handled by arkcli itself; this extension
- * never sees API keys.
+ * Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI, fetched
+ * directly from the Ark OpenAPI (`GetCodingPlanUsage`) with AK/SK signing via
+ * the official `@volcengine/openapi` Signer. This extension never stores keys:
+ * credentials come from VOLC_ACCESSKEY/VOLC_SECRETKEY or ~/.volc/config.
  *
  * Widget (below editor): 火山用量: 会话 4%(...) / 周 34%(...) / 月 17%(...)
  * Commands:
@@ -35,6 +36,7 @@ import {
   flushWrites,
   loadCache,
   markShuttingDown,
+  resetShutdownState,
   saveCache,
 } from "./lib/cache.js";
 import type {
@@ -59,7 +61,7 @@ const PRODUCTS = [
 
 type ProductId = (typeof PRODUCTS)[number];
 
-/** provider id (pi models.json) -> arkcli product id */
+/** provider id (pi models.json) -> plan product id */
 const PROVIDER_PRODUCT: Record<string, ProductId> = {
   "coding-plan": "coding-plan",
   "agent-plan": "agent-plan",
@@ -503,15 +505,26 @@ export default function (pi: ExtensionAPI): void {
     }
   }
 
-  pi.on("session_shutdown", async () => {
-    shuttingDown = true;
-    markShuttingDown();
+  pi.on("session_shutdown", async (event) => {
     stopTicker();
     inFlight?.abort();
+    // Only a real quit is terminal. Session switches (/new, /resume, /fork,
+    // /reload) tear down and then re-enter session_start in the same process;
+    // marking terminal shutdown there would block every future refresh.
+    if (event.reason === "quit") {
+      shuttingDown = true;
+      markShuttingDown();
+    }
     await flushWrites();
   });
 
   pi.on("session_start", (_event, ctx) => {
+    // Session switches reuse this module instance in-process: pi has disposed
+    // the old TUI widget and torn down the previous runtime, so drop stale
+    // handles and revive the shutdown flags before doing anything else.
+    shuttingDown = false;
+    resetShutdownState();
+    activeWidget = null;
     activeProduct = resolveProduct(ctx);
     deltas = null;
     note = null;

package/extensions/lib/aksk.ts

@@ -0,0 +1,263 @@
+/**
+ * Volcengine Ark OpenAPI client (AK/SK).
+ *
+ * Replaces the old `arkcli` subprocess wrapper: usage is fetched directly
+ * from the Ark OpenAPI (`GetCodingPlanUsage`) using the official
+ * `@volcengine/openapi` Signer for V4 request signing.
+ *
+ * Credential resolution (no secrets are ever logged or persisted here):
+ *   1. env: VOLC_ACCESSKEY / VOLC_SECRETKEY (+ optional VOLC_SESSION_TOKEN)
+ *   2. ~/.volc/config — JSON {"VOLC_ACCESSKEY": "...", "VOLC_SECRETKEY": "..."}
+ *      (the same default path the official SDK uses)
+ */
+
+import { homedir } from "node:os";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Signer } from "@volcengine/openapi";
+import type { ArkPlanItem, ArkPlanOutput, ArkPeriod } from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_JSON_BYTES = 1024 * 1024;
+
+const OPEN_HOST = "open.volcengineapi.com";
+const REGION = "cn-beijing";
+const SERVICE = "ark";
+const ARK_VERSION = "2024-01-01";
+const USAGE_ACTION = "GetCodingPlanUsage";
+
+/** Product id reported for this API. The Ark OpenAPI exposes the coding plan usage of the AK/SK account. */
+const REPORTED_PRODUCT = "coding-plan";
+
+export type { ArkPlanOutput };
+
+export type FetchPlanOptions = {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** accepted for interface compatibility; the OpenAPI has no product/seat filter */
+  product?: string;
+  seat?: string;
+};
+
+type Credentials = {
+  accessKeyId: string;
+  secretKey: string;
+  sessionToken?: string;
+};
+
+let cachedCreds: Credentials | null | undefined;
+
+function readEnvCreds(): Credentials | null {
+  const ak = process.env.VOLC_ACCESSKEY;
+  const sk = process.env.VOLC_SECRETKEY;
+  if (!ak || !sk) return null;
+  return {
+    accessKeyId: ak,
+    secretKey: sk,
+    sessionToken: process.env.VOLC_SESSION_TOKEN || undefined,
+  };
+}
+
+async function readConfigFileCreds(): Promise<Credentials | null> {
+  const path = join(homedir(), ".volc", "config");
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new Error(`invalid JSON in ${path}`);
+  }
+  if (!json || typeof json !== "object") return null;
+  const cfg = json as Record<string, unknown>;
+  const ak = cfg.VOLC_ACCESSKEY ?? cfg.AccessKeyId;
+  const sk = cfg.VOLC_SECRETKEY ?? cfg.SecretAccessKey;
+  if (typeof ak !== "string" || typeof sk !== "string" || !ak || !sk) {
+    return null;
+  }
+  const token = cfg.VOLC_SESSIONTOKEN ?? cfg.SessionToken;
+  return {
+    accessKeyId: ak,
+    secretKey: sk,
+    sessionToken: typeof token === "string" && token ? token : undefined,
+  };
+}
+
+/** Resolve credentials once per process; null = none found anywhere. */
+export async function resolveCredentials(): Promise<Credentials | null> {
+  if (cachedCreds !== undefined) return cachedCreds;
+  cachedCreds = readEnvCreds() ?? (await readConfigFileCreds());
+  return cachedCreds;
+}
+
+export async function checkCredentialsAvailable(): Promise<boolean> {
+  return (await resolveCredentials()) !== null;
+}
+
+/* ------------------------------- response types ------------------------------ */
+
+type QuotaEntry = {
+  Level?: unknown;
+  Percent?: unknown;
+  ResetTimestamp?: unknown;
+  [k: string]: unknown;
+};
+
+type UsageResponse = {
+  ResponseMetadata?: {
+    Error?: { Code?: unknown; Message?: unknown; [k: string]: unknown };
+    [k: string]: unknown;
+  };
+  Result?: {
+    Status?: unknown;
+    UpdateTimestamp?: unknown;
+    QuotaUsage?: QuotaEntry[];
+    [k: string]: unknown;
+  };
+};
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === "number" && Number.isFinite(v);
+}
+
+function fmtReset(sec: number): string {
+  // API returns epoch seconds; render as ISO 8601 in UTC+8 for readability.
+  const tz = new Date(sec * 1000);
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  }).formatToParts(tz);
+  const get = (t: string): string =>
+    parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}T${get("hour")}:${get("minute")}:${get("second")}+08:00`;
+}
+
+function validatePeriod(raw: QuotaEntry): ArkPeriod | null {
+  if (!isFiniteNumber(raw.Percent) || raw.Percent < 0) return null;
+  const label =
+    typeof raw.Level === "string" && raw.Level.length > 0
+      ? raw.Level
+      : "unknown";
+  const out: ArkPeriod = {
+    label,
+    percent: Math.min(raw.Percent, 100),
+  };
+  if (isFiniteNumber(raw.ResetTimestamp) && raw.ResetTimestamp > 0) {
+    out.reset_at = fmtReset(raw.ResetTimestamp);
+  }
+  return out;
+}
+
+function itemFromResponse(
+  res: UsageResponse,
+): { item: ArkPlanItem } | { error: string } {
+  const apiError = res.ResponseMetadata?.Error;
+  if (apiError) {
+    const code = typeof apiError.Code === "string" ? apiError.Code : "Unknown";
+    const msg =
+      typeof apiError.Message === "string" ? apiError.Message : "API error";
+    return { error: `${code}: ${msg}` };
+  }
+  const result = res.Result;
+  if (!result || typeof result !== "object") {
+    return { error: "invalid response: missing Result" };
+  }
+  const entries = Array.isArray(result.QuotaUsage) ? result.QuotaUsage : [];
+  const periods = entries
+    .map(validatePeriod)
+    .filter((p): p is ArkPeriod => p !== null);
+  if (periods.length === 0) {
+    return { error: "response has no usable quota periods" };
+  }
+  const item: ArkPlanItem = {
+    product: REPORTED_PRODUCT,
+    edition: "personal",
+    subscribed: true,
+    periods,
+  };
+  if (isFiniteNumber(result.UpdateTimestamp) && result.UpdateTimestamp > 0) {
+    item.updated_at = result.UpdateTimestamp * 1000;
+  }
+  return { item };
+}
+
+/** Parse and validate the raw OpenAPI JSON. Throws on malformed payload. */
+export function parseUsageResponse(raw: string): ArkPlanOutput {
+  if (raw.length > MAX_JSON_BYTES) throw new Error("API response too large");
+  let json: UsageResponse;
+  try {
+    json = JSON.parse(raw) as UsageResponse;
+  } catch {
+    throw new Error("invalid API response: not JSON");
+  }
+  if (!json || typeof json !== "object") {
+    throw new Error("invalid API response");
+  }
+  const r = itemFromResponse(json);
+  if ("error" in r) throw new Error(r.error);
+  return { items: [r.item] };
+}
+
+/* --------------------------------- fetching ---------------------------------- */
+
+/**
+ * Query `GetCodingPlanUsage` via AK/SK-signed OpenAPI request.
+ * Throws on missing credentials, transport errors, API errors or unusable data.
+ */
+export async function fetchPlan(
+  options: FetchPlanOptions = {},
+): Promise<ArkPlanOutput> {
+  const creds = await resolveCredentials();
+  if (!creds) {
+    throw new Error(
+      "no Volcengine credentials: set VOLC_ACCESSKEY/VOLC_SECRETKEY or create ~/.volc/config",
+    );
+  }
+
+  const body = "{}";
+  const request = {
+    region: REGION,
+    method: "POST" as const,
+    pathname: "/",
+    params: { Action: USAGE_ACTION, Version: ARK_VERSION },
+    headers: { "Content-Type": "application/json" } as Record<string, string>,
+    body,
+  };
+  new Signer(request, SERVICE).addAuthorization({
+    accessKeyId: creds.accessKeyId,
+    secretKey: creds.secretKey,
+    sessionToken: creds.sessionToken ?? "",
+  });
+
+  const query = new URLSearchParams(request.params).toString();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const signal = options.signal ?? AbortSignal.timeout(timeoutMs);
+
+  let res: Response;
+  try {
+    res = await fetch(`https://${OPEN_HOST}/?${query}`, {
+      method: "POST",
+      headers: request.headers,
+      body,
+      signal,
+    });
+  } catch (e) {
+    throw new Error(`request failed: ${(e as Error).message}`);
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
+  }
+  return parseUsageResponse(text);
+}

package/extensions/lib/arkcli.ts

@@ -1,129 +1,28 @@
 /**
- * `arkcli` process wrapper: locate the binary, invoke `arkcli usage plan`,
- * parse and validate its JSON output.
+ * Compatibility layer: `lib/arkcli.js` used to wrap the `arkcli` binary; the
+ * extension now talks to the Ark OpenAPI directly with AK/SK (see `aksk.ts`).
+ * All exports keep their names so callers don't change.
  */
 
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import type { ArkPlanOutput, ArkPlanItem, ArkPeriod } from "./types.js";
-
-const execFileAsync = promisify(execFile);
-
-const DEFAULT_TIMEOUT_MS = 10_000;
-const MAX_JSON_BYTES = 1024 * 1024;
-
-const PRODUCT_IDS = new Set([
-  "coding-plan",
-  "agent-plan",
-  "coding-plan-team",
-  "agent-plan-team",
-]);
-
-/** Locate arkcli: explicit env override, else plain name (resolved via PATH). */
-export function arkcliBin(): string {
-  return process.env.PI_ARK_USAGE_ARKCLI || "arkcli";
-}
+import type { ArkPlanOutput } from "./types.js";
+import {
+  fetchPlan as fetchPlanAksk,
+  checkCredentialsAvailable,
+} from "./aksk.js";
+import type { FetchPlanOptions } from "./aksk.js";
+export type { ArkPlanOutput, FetchPlanOptions } from "./aksk.js";
 
+/** @deprecated legacy probe kept only for interface compatibility; always true. */
 export async function checkArkcliAvailable(): Promise<boolean> {
-  try {
-    await execFileAsync(arkcliBin(), ["--help"], { timeout: 5_000 });
-    return true;
-  } catch {
-    // --help may exit non-zero in odd wrappers; fall back to version check.
-    try {
-      await execFileAsync(arkcliBin(), ["version"], { timeout: 5_000 });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
-
-function isFiniteNumber(v: unknown): v is number {
-  return typeof v === "number" && Number.isFinite(v);
+  return checkCredentialsAvailable();
 }
 
-function validatePeriod(raw: unknown): ArkPeriod | null {
-  if (!raw || typeof raw !== "object") return null;
-  const p = raw as Record<string, unknown>;
-  if (typeof p.label !== "string" || p.label.length === 0) return null;
-  if (!isFiniteNumber(p.percent) || p.percent < 0) return null;
-  const out: ArkPeriod = {
-    label: p.label,
-    percent: Math.min(p.percent, 100),
-  };
-  if (typeof p.reset_at === "string" && p.reset_at.length > 0) {
-    out.reset_at = p.reset_at;
-  }
-  return out;
-}
-
-function validateItem(raw: unknown): ArkPlanItem | null {
-  if (!raw || typeof raw !== "object") return null;
-  const it = raw as Record<string, unknown>;
-  if (typeof it.product !== "string" || !PRODUCT_IDS.has(it.product)) return null;
-  if (typeof it.edition !== "string") return null;
-  const out: ArkPlanItem = {
-    product: it.product,
-    edition: it.edition,
-    subscribed: it.subscribed === true,
-  };
-  if (typeof it.error === "string") out.error = it.error;
-  if (isFiniteNumber(it.updated_at)) out.updated_at = it.updated_at;
-  if (Array.isArray(it.periods)) {
-    const periods = it.periods
-      .map(validatePeriod)
-      .filter((p): p is ArkPeriod => p !== null);
-    if (periods.length > 0) out.periods = periods;
-  }
-  return out;
-}
-
-/** Parse and validate raw arkcli JSON. Throws on malformed payload. */
-export function parsePlanOutput(raw: string): ArkPlanOutput {
-  if (raw.length > MAX_JSON_BYTES) throw new Error("arkcli output too large");
-  const json: unknown = JSON.parse(raw);
-  if (!json || typeof json !== "object") throw new Error("invalid arkcli output");
-  const root = json as Record<string, unknown>;
-  if (!Array.isArray(root.items)) throw new Error("invalid arkcli output: missing items");
-  const items = root.items
-    .map(validateItem)
-    .filter((it): it is ArkPlanItem => it !== null);
-  if (items.length === 0) throw new Error("arkcli returned no usable items");
-  const out: ArkPlanOutput = { items };
-  if (root.viewer && typeof root.viewer === "object") {
-    out.viewer = root.viewer as ArkPlanOutput["viewer"];
-  }
-  return out;
-}
-
-export type FetchPlanOptions = {
-  signal?: AbortSignal;
-  timeoutMs?: number;
-  /** specific product id; undefined = auto-discover all subscriptions */
-  product?: string;
-  seat?: string;
-};
-
 /**
- * Run `arkcli usage plan --format json`.
- * Authentication is fully handled by arkcli itself (SSO profiles etc.).
+ * Fetch Coding Plan usage.
+ * `product`/`seat` options are accepted for interface compatibility but
+ * ignored: the AK/SK OpenAPI reports the plan bound to the credential's
+ * account and has no product/seat filter.
  */
-export async function fetchPlan(options: FetchPlanOptions = {}): Promise<ArkPlanOutput> {
-  const args = ["usage", "plan", "--format", "json"];
-  if (options.product) {
-    args.push("--product", options.product);
-  }
-  if (options.seat) {
-    args.push("--seat", options.seat);
-  }
-
-  const { stdout } = await execFileAsync(arkcliBin(), args, {
-    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    maxBuffer: MAX_JSON_BYTES,
-    signal: options.signal,
-    // arkcli may print warnings on stderr; they don't fail the call unless exit code != 0.
-    windowsHide: true,
-  });
-  return parsePlanOutput(stdout);
+export function fetchPlan(options: FetchPlanOptions = {}): Promise<ArkPlanOutput> {
+  return fetchPlanAksk(options);
 }

package/extensions/lib/cache.ts

@@ -172,6 +172,11 @@ export function markShuttingDown(): void {
   shuttingDown = true;
 }
 
+/** Revive cache writes after an in-process session switch (see index.ts). */
+export function resetShutdownState(): void {
+  shuttingDown = false;
+}
+
 async function writeFile(data: string): Promise<void> {
   await mkdir(CACHE_DIR, { recursive: true, mode: DIR_MODE });
   const dir = await lstat(CACHE_DIR);

package/extensions/lib/types.ts

@@ -27,14 +27,14 @@ export type ArkSettings = {
 
 export type PeriodLabel = "session" | "5h" | "weekly" | "monthly";
 
-/** One billing period as returned by `arkcli usage plan`. */
+/** One billing period as returned by the Ark usage API. */
 export type ArkPeriod = {
   label: PeriodLabel | string;
   percent: number;
   reset_at?: string;
 };
 
-/** One product entry as returned by `arkcli usage plan`. */
+/** One product entry in a usage snapshot. */
 export type ArkPlanItem = {
   product: string;
   edition: "personal" | "team" | string;
@@ -44,7 +44,7 @@ export type ArkPlanItem = {
   updated_at?: number;
 };
 
-/** Shape of `arkcli usage plan --format json` output. */
+/** Shape of the normalized usage-fetch output. */
 export type ArkPlanOutput = {
   viewer?: {
     auth_method?: string;

package/extensions/lib/widget.ts

@@ -49,7 +49,7 @@ const ZH: Locale = {
   },
   fetching: "请求中",
   failed: "失败",
-  noBinary: "未找到 arkcli",
+  noBinary: "未配置火山 AK/SK 凭据",
   notSubscribed: "未订阅",
   noData: "暂无数据",
   using: "使用中",
@@ -87,7 +87,7 @@ const EN: Locale = {
   },
   fetching: "fetching",
   failed: "failed",
-  noBinary: "arkcli not found",
+  noBinary: "Volcengine AK/SK credentials not configured",
   notSubscribed: "not subscribed",
   noData: "no data",
   using: "using",
@@ -124,7 +124,7 @@ export const AUTO_REFRESH_MAX_MINUTES = 30;
 export const DEFAULT_SETTINGS: ArkSettings = {
   pctYellow: 40,
   pctRed: 80,
-  autoRefreshMinutes: 0,
+  autoRefreshMinutes: 5,
   product: "auto",
   seat: "",
 };

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "pi-ark-usage",
-  "version": "0.1.0",
-  "description": "Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI via arkcli",
+  "version": "0.1.2",
+  "description": "Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI (AK/SK OpenAPI)",
   "keywords": [
     "pi",
     "pi-package",
     "extension",
     "volcengine",
     "ark",
-    "arkcli",
+    "openapi",
     "coding-plan",
     "usage",
     "quota",
@@ -33,10 +33,14 @@
   },
   "main": "extensions/index.ts",
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --import ./test/ts-resolve-hook.mjs --test --experimental-strip-types test/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@volcengine/openapi": "^1.36.2"
   }
 }