pi-ark-usage 0.1.4 → 0.1.5

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) 上；百分比按阈值绿/黄/红着色，时间部分紫色，分隔符跟随主题 `thinkingHigh`（编辑器边框色），末尾的「上次刷新」用 `dim` 渲染以示区隔。不安装 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

package/extensions/lib/widget.ts

@@ -202,9 +202,25 @@ 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
@@ -212,24 +228,32 @@ export function formatCompactRemaining(ms: number): string {
  * red); the time part is always purple; the ` | ` separator uses the
  * editor border color (`thinkingHigh`, pink in the dark theme).
  *
+ * The last segment is how long ago the data was fetched, in `dim` — it is
+ * meta information, not usage, so it stays visually secondary.
+ *
  * 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 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}${theme.fg("dim", 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.5",
   "description": "Show Volcengine Ark Coding Plan / Agent Plan usage in the pi TUI (AK/SK OpenAPI)",
   "keywords": [
     "pi",