pi-ark-usage 0.1.4 → 0.1.6

package/README.md

@@ -3,14 +3,15 @@
 在 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
+1% 4h38m | 15% 5d4h | 54% 23d4h | 3m ago
 ```
 
 ## 特性
 
 - **AK/SK 直连 OpenAPI**：不走子进程、不依赖 SSO 登录态；凭据只从环境变量或配置文件读取，本扩展不保存、不上传任何 Key
 - **三个周期同屏**：session（会话）/ weekly（周）/ monthly（月），并显示各周期重置倒计时
-- **Powerline 状态段（唯一展示位）**：通过 `ctx.ui.setStatus("ark-usage", …)` 发布单行摘要（`1% 4h38m | 15% 5d4h | 54% 23d4h`，固定按 session/weekly/monthly 顺序），显示在 [pi-powerline-footer](https://www.npmjs.com/package/pi-powerline-footer) 上；百分比按阈值绿/黄/红着色，时间部分紫色，分隔符跟随主题 `thinkingHigh`（编辑器边框色）。不安装 powerline 时也可通过内置 footer 的 extension statuses 区域或 `/arkusage` 查看
+- **Powerline 状态段（唯一展示位）**：通过 `ctx.ui.setStatus("ark-usage", …)` 发布单行摘要（`1% 4h38m | 15% 5d4h | 54% 23d4h | 3m ago`，固定按 session/weekly/monthly 顺序），显示在 [pi-powerline-footer](https://www.npmjs.com/package/pi-powerline-footer) 上；百分比按阈值绿/黄/红着色，各周期重置倒计时紫色 `#7A5FD0`，` | ` 分隔符与末尾的「上次刷新」统一用粉色 `#D787AF`（与 powerline 模型名段同色）。所有颜色均为固定 hex，不随 pi 主题变化。不安装 powerline 时也可通过内置 footer 的 extension statuses 区域或 `/arkusage` 查看
+- **上次刷新时间**：状态段末尾显示距今多久前**成功**刷新过（分钟精度：`just now` / `3m ago` / `4h38m ago` / `5d4h ago`）。抓取失败时沿用上一次成功的时间，因此该值持续变大即表示刷新已经失败或长时间未刷新
 - **阈值着色**：低用量绿色（<50%）、接近上限黄色（50–79%）、超过红线红色（≥80%，默认值，可用 `/arkset` 调整）
 - **持久化缓存**：重启 pi 后立即显示上次快照（`~/.pi/agent/pi-ark-usage/cache.json`，0600 权限，临时文件原子写入）
 - 可选空闲自动刷新（默认关闭）
@@ -97,7 +98,7 @@ pi install npm:pi-ark-usage
 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. 摘要通过 `ctx.ui.setStatus("ark-usage", …)` 发布到 extension status，由 pi-powerline-footer 渲染到 powerline 行；每分钟 ticker 在空闲时重发，保持重置倒计时刷新。
+4. 摘要通过 `ctx.ui.setStatus("ark-usage", …)` 发布到 extension status，由 pi-powerline-footer 渲染到 powerline 行；每分钟 ticker 在空闲时重发，保持重置倒计时与「上次刷新」时长显示为最新。
 
 ## 开发
 

package/extensions/index.ts

@@ -6,7 +6,9 @@
  * the official `@volcengine/openapi` Signer. This extension never stores keys:
  * credentials come from VOLC_ACCESSKEY/VOLC_SECRETKEY or ~/.volc/config.
  *
- * Powerline status (via `ctx.ui.setStatus`): 1% 4h38m | 15% 5d4h | 54% 23d4h
+ * Powerline status (via `ctx.ui.setStatus`):
+ *   1% 4h38m | 15% 5d4h | 54% 23d4h | 3m ago
+ * The trailing segment is how long ago the data was last refreshed.
  * Commands:
  *   /arkcheck          force refresh
  *   /arkusage          show snapshot in a notification
@@ -124,7 +126,7 @@ function renderStatus(ctx: ExtensionContext): void {
   // Publish the one-line summary to the extension-status slot (powerline).
   // The ticker calls renderStatus every minute while idle, keeping the
   // reset countdown fresh without refetching.
-  const compact = buildCompactStatus(snap, widgetStatus, ctx.ui.theme);
+  const compact = buildCompactStatus(snap, widgetStatus);
   if (compact) {
     ctx.ui.setStatus(STATUS_KEY, compact);
   } else {

package/extensions/lib/widget.ts

@@ -4,7 +4,6 @@
  * colored one-line summary published via `ctx.ui.setStatus`.
  */
 
-import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { ArkSettings, Language, PlanSnapshot } from "./types.js";
 
 /* ---------------------------------- i18n ---------------------------------- */
@@ -140,7 +139,14 @@ export const HEX_COLORS = {
   green: "#1FA87A",
   yellow: "#F09A3E",
   red: "#EE7A5F",
+  /** Reset countdowns, and the `…` placeholder for a fetch in flight. */
   purple: "#7A5FD0",
+  /**
+   * The ` | ` separators and the trailing refresh age. Kept in sync with the
+   * model-name segment of pi-powerline-footer, whose `model` color is
+   * #d787af, so the separators read as part of the prompt line's palette.
+   */
+  pink: "#D787AF",
 } as const;
 
 export function hexFg(hex: string, text: string): string {
@@ -202,34 +208,58 @@ export function formatCompactRemaining(ms: number): string {
   return `${m}m`;
 }
 
+/**
+ * Age of the last successful refresh, for the trailing status segment:
+ * `just now`, `3m ago`, `4h38m ago`, `5d4h ago`. Minute is the finest unit —
+ * seconds would only make the line jitter — and a stale cached snapshot thus
+ * reads as old at a glance.
+ */
+export function formatRefreshAgo(ts: number, now: number = Date.now()): string {
+  if (!Number.isFinite(ts) || ts <= 0) return "";
+  const ms = now - ts;
+  // Clock skew can make a fresh fetch look negative; treat it as "now".
+  if (ms < 60_000) return "just now";
+  // Drop a zero lower unit (`1h0m` -> `1h`, `5d0h` -> `5d`).
+  const age = formatCompactRemaining(ms).replace(/([dh])0[mh]$/, "$1");
+  return `${age} ago`;
+}
+
 /**
  * One-line colored summary for the powerline extension-status slot:
- * `1% 4h38m | 15% 5d4h | 54% 23d4h`
+ * `1% 4h38m | 15% 5d4h | 54% 23d4h | 3m ago`
  *
  * Periods are shown in API order (session / weekly / monthly) without
  * labels — the order itself is the convention. Percent follows the
- * yellow/red thresholds (green below yellow, yellow below red, red at/above
- * red); the time part is always purple; the ` | ` separator uses the
- * editor border color (`thinkingHigh`, pink in the dark theme).
+ * yellow/red thresholds on the used amount (green below yellow, yellow
+ * below red, red at/above red); reset countdowns stay purple; the ` | `
+ * separators and the trailing refresh age are pink (`HEX_COLORS.pink`,
+ * matching the powerline model-name segment).
+ *
+ * Every color is a fixed hex value — the slot renders identically in any pi
+ * theme, so `HEX_COLORS` is the only palette this line depends on.
  *
  * Returns null when nothing should be shown (the powerline item hides).
  */
 export function buildCompactStatus(
   snapshot: PlanSnapshot | null,
   status: WidgetStatus,
-  theme: Theme,
+  now: number = Date.now(),
 ): string | null {
   if (snapshot && snapshot.periods.length > 0) {
-    const sep = theme.fg("thinkingHigh", " | ");
-    return snapshot.periods
+    const sep = hexFg(HEX_COLORS.pink, " | ");
+    const periods = snapshot.periods
       .map((p) => {
         const pct = coloredPct(clampPct(p.percent));
         const reset = p.reset_at
-          ? formatCompactRemaining(new Date(p.reset_at).getTime() - Date.now())
+          ? formatCompactRemaining(new Date(p.reset_at).getTime() - now)
           : "";
         return reset ? `${pct} ${hexFg(HEX_COLORS.purple, reset)}` : pct;
       })
       .join(sep);
+    const refreshed = formatRefreshAgo(snapshot.fetchedAt, now);
+    return refreshed
+      ? `${periods}${sep}${hexFg(HEX_COLORS.pink, refreshed)}`
+      : periods;
   }
   if (status === "fetching") return hexFg(HEX_COLORS.purple, "…");
   if (status === "failed") return hexFg(HEX_COLORS.red, "failed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ark-usage",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI (AK/SK OpenAPI)",
   "keywords": [
     "pi",