@kairyou/agent-tools 0.8.0 → 0.10.0

package/docs/zh-CN/custom-gateway-routes.md

@@ -0,0 +1,47 @@
+# 自定义网关路由
+
+[Provider usage](../../README.zh-CN.md#provider-usage) 的高级指南: 为内置 preset 覆盖不到的中转(比如 cookie 认证的网关)编写自己的用量探测, 无需修改包内代码.
+
+## 声明路由
+
+编写路由模块, 并在 `providerUsage.routes` 里声明(相对 `~/.agent-tools` 解析). 声明的路由优先探测; `"preset"` 填路由 id 可直接选中.
+
+```jsonc
+{
+  "providerUsage": {
+    "routes": [
+      "custom/my-gateway.mjs",
+      "custom/another-gateway.mjs"
+    ],
+    "myGateway": { "username": "me", "password": "..." }
+  }
+}
+```
+
+## 路由模块 API
+
+```js
+// ~/.agent-tools/custom/my-gateway.mjs
+export const meta = { id: "my-gateway" }; // 可选; id 默认取文件名
+
+export async function run(context, { requestJson, agentConfig }) {
+  // context: { baseUrl, key, providerName, provider, label }
+  const { myGateway = {} } = await agentConfig(); // providerUsage 对象, 自定义键随意加
+
+  const login = await fetch(`${context.baseUrl}/api/user/login`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ username: myGateway.username, password: myGateway.password }),
+  });
+  const session = await login.json();
+
+  // requestJson 会解析 JSON, 并在非 2xx 响应时抛错; 需要时可在这里传入
+  // authorization、cookie 等自定义认证 header.
+  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
+    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
+  });
+  return { text: `balance ¥${me?.data?.balance}` };
+}
+```
+
+`text` 是自由字符串; 成功返回 `{ text }`, 抛错则回落到下一条路由. 开启 `providerUsage.debug` 后, 探测失败会记录到 `~/.agent-tools/logs/usage-debug.log`.

package/docs/zh-CN/repository-structure.md

@@ -0,0 +1,20 @@
+# 仓库结构
+
+```text
+agent-tools/
+├── .claude-plugin/    # Claude Code/plugin 生态的 manifest.
+├── .codex-plugin/     # Codex plugin manifest.
+├── integrations/      # 可安装的 capability, 一个一目录.
+│   ├── statusline/    # Agent 状态栏: 分支, 模型, 用量.
+│   ├── usage/         # Provider 余额/额度显示.
+│   └── vision/        # 跨模型识图.
+├── skills/            # 可复用的 Agent Skills.
+│   ├── workflow/      # 工作流类 skills.
+│   │   ├── at-commit/   # 生成 Conventional Commits message.
+│   │   ├── at-review/   # 审查改动中的 bug 与回归风险.
+│   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
+│   └── integrations/  # 对接外部系统的 skills.
+│       └── at-zentao/   # 禅道 bug/task 修复工作流.
+├── docs/              # 高级指南和贡献者参考.
+└── scripts/           # 安装, 同步, 校验和仓库维护脚本.
+```

package/integrations/usage/codex-hook.mjs

@@ -16,6 +16,7 @@ const LOG_PATH = path.join(AGENT_TOOLS_HOME, "logs", "usage-hook.log");
 const TIMEOUT_MS = Number(process.env.AGENT_TOOLS_USAGE_HOOK_TIMEOUT_MS || 4500);
 const MAX_LOG_BYTES = Number(process.env.AGENT_TOOLS_USAGE_HOOK_LOG_BYTES || 256 * 1024);
 const KEEP_LOG_BYTES = 128 * 1024;
+const SILENT = process.argv.includes("--silent");
 
 function hookOut(message) {
   const payload = { continue: true };
@@ -64,6 +65,10 @@ function failureMessage() {
   return `API usage hook failed; see ${LOG_PATH.replace(/\\/g, "/")}`;
 }
 
+function hookFailureOut() {
+  hookOut(SILENT ? "" : failureMessage());
+}
+
 function parseHookJson(stdout) {
   const text = stdout.trim();
   if (!text) return { continue: true };
@@ -73,17 +78,21 @@ function parseHookJson(stdout) {
 async function runUsageScript() {
   if (!fs.existsSync(USAGE_SCRIPT)) {
     logFailure({ reason: "missing usage script", usageScript: USAGE_SCRIPT });
-    hookOut(failureMessage());
+    hookFailureOut();
     return;
   }
 
   const result = await new Promise((resolve) => {
-    const child = spawn(process.execPath, [USAGE_SCRIPT, "hook", "--agent", "codex"], {
-      cwd: process.cwd(),
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"],
-      windowsHide: true,
-    });
+    const child = spawn(
+      process.execPath,
+      [USAGE_SCRIPT, "hook", "--agent", "codex", ...(SILENT ? ["--silent"] : [])],
+      {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      }
+    );
     let stdout = "";
     let stderr = "";
     let settled = false;
@@ -126,7 +135,7 @@ async function runUsageScript() {
       node: process.version,
       platform: `${process.platform} ${os.release()}`,
     });
-    hookOut(failureMessage());
+    hookFailureOut();
     return;
   }
 
@@ -141,7 +150,7 @@ async function runUsageScript() {
       stderr: preview(result.stderr),
       usageScript: USAGE_SCRIPT,
     });
-    hookOut(failureMessage());
+    hookFailureOut();
   }
 }
 
@@ -153,5 +162,5 @@ try {
     error: error?.stack || error?.message || String(error),
     usageScript: USAGE_SCRIPT,
   });
-  hookOut(failureMessage());
+  hookFailureOut();
 }

package/integrations/usage/core.mjs

@@ -7,11 +7,19 @@
 // Everything else lives in ./lib (config, urls, http, cache, format, context,
 // routes) and is bundled into dist/usage/core.mjs at build time.
 
-import { pathToFileURL } from "node:url";
-import { debugLog, usagePreset, snapshotTtlMs } from "./lib/config.mjs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import {
+  debugLog,
+  usagePreset,
+  HOOK_SNAPSHOT_MAX_AGE_MS,
+  REFRESH_INTERVAL_MS,
+} from "./lib/config.mjs";
 import { isOfficialBaseUrl } from "./lib/urls.mjs";
 import {
   readUsageSnapshot,
+  acquireUsageRefreshLease,
+  canRefreshUsage,
   rememberUsageRoute,
   rememberUsageSnapshot,
   rememberRefreshState,
@@ -20,7 +28,7 @@ import { orderedUsageRoutes } from "./lib/routes.mjs";
 import { usageContext, normalizeUsageContext } from "./lib/context.mjs";
 
 function parseArgs(argv) {
-  const opts = { mode: "hook", agent: "codex" };
+  const opts = { mode: "hook", agent: "codex", silent: false };
   let modeSet = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -28,6 +36,8 @@ function parseArgs(argv) {
       opts.agent = argv[++i];
     } else if (arg.startsWith("--agent=")) {
       opts.agent = arg.slice("--agent=".length);
+    } else if (arg === "--silent") {
+      opts.silent = true;
     } else if (!arg.startsWith("-") && !modeSet) {
       opts.mode = arg;
       modeSet = true;
@@ -111,30 +121,68 @@ export async function queryProviderUsage(input, options = {}) {
 }
 
 async function refresh(agent = "codex") {
-  return await queryAgentProviderUsage(agent);
+  const context = await usageContext(agent);
+  const release = await acquireUsageRefreshLease(context);
+  if (!release) return { skipped: true, text: "" };
+  try {
+    if (!(await canRefreshUsage(context, REFRESH_INTERVAL_MS))) return { skipped: true, text: "" };
+    await rememberRefreshState(context, { lastStartedAt: new Date().toISOString() });
+    return await queryUsageContext(context, { agent, rememberSnapshot: true });
+  } finally {
+    await release();
+  }
+}
+
+async function cachedUsage(context) {
+  const cached = await readUsageSnapshot(context);
+  const ageMs = cached?.updatedAt ? Date.now() - Date.parse(cached.updatedAt) : Infinity;
+  return cached?.text && Number.isFinite(ageMs) ? { ...cached, ageMs } : null;
 }
 
 export async function queryAgentProviderUsage(agent = "codex", { maxAgeMs = 0 } = {}) {
   const context = await usageContext(agent);
   if (maxAgeMs > 0) {
-    const cached = await readUsageSnapshot(context);
-    const age = cached?.updatedAt ? Date.now() - Date.parse(cached.updatedAt) : Infinity;
-    if (cached?.text && age < maxAgeMs) return { ...cached, cached: true };
+    const cached = await cachedUsage(context);
+    if (cached && cached.ageMs < maxAgeMs) return { ...cached, cached: true };
   }
   return await queryUsageContext(context, { agent, rememberSnapshot: true });
 }
 
+function scheduleRefresh(agent) {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "refresh", "--agent", agent], {
+    cwd: process.cwd(),
+    env: process.env,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function hook(agent, { silent = false } = {}) {
+  const context = await usageContext(agent);
+  const cached = await cachedUsage(context);
+  if (
+    (!cached || cached.ageMs >= REFRESH_INTERVAL_MS) &&
+    (await canRefreshUsage(context, REFRESH_INTERVAL_MS))
+  ) {
+    scheduleRefresh(agent);
+  }
+  hookOut(silent ? "" : cached && cached.ageMs < HOOK_SNAPSHOT_MAX_AGE_MS ? cached.text : "");
+}
+
 async function main() {
   try {
     if (mode === "refresh") {
       await refresh(cli.agent);
-    } else if (mode === "print" || mode === "print-or-refresh") {
-      const result = await refresh(cli.agent);
+    } else if (mode === "print") {
+      // Explicit request: query directly instead of going through the
+      // background refresh throttle, which would print nothing.
+      const result = await queryAgentProviderUsage(cli.agent);
       textOut(result?.text || "");
     } else if (mode === "hook") {
-      // Hook mode fires on every prompt; serve a fresh snapshot when possible.
-      const result = await queryAgentProviderUsage(cli.agent, { maxAgeMs: snapshotTtlMs() });
-      hookOut(result?.text || "");
+      await hook(cli.agent, { silent: cli.silent });
     } else {
       throw new Error(`unknown mode: ${mode}`);
     }

package/integrations/usage/lib/cache.mjs

@@ -1,9 +1,11 @@
 // On-disk state under ~/.agent-tools/cache: the last working route per
 // gateway, the latest usage snapshot, and refresh bookkeeping.
 
-import { writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { writeFile, mkdir, open, unlink, rename, stat, utimes } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
 import {
+  CACHE_DIR,
   ROUTE_CACHE_PATH,
   SNAPSHOT_PATH,
   REFRESH_STATE_PATH,
@@ -12,104 +14,184 @@ import {
 } from "./config.mjs";
 import { usageRouteCacheKey } from "./urls.mjs";
 
-const ROUTE_CACHE_VERSION = 1;
-const SNAPSHOT_VERSION = 1;
-const REFRESH_STATE_VERSION = 1;
+const CACHE_VERSION = 1;
+const WRITE_LOCK_PATH = join(CACHE_DIR, "usage-cache-write.lock");
 
-export async function readRouteCache() {
+// Every cache file is { version, <field>: { [gatewayKey]: entry } }.
+async function readJsonCache(path, field) {
   try {
-    const raw = await readTextIfExists(ROUTE_CACHE_PATH);
-    if (!raw.trim()) return { version: ROUTE_CACHE_VERSION, routes: {} };
-    const parsed = JSON.parse(raw);
+    const raw = await readTextIfExists(path);
+    const entries = raw.trim() ? JSON.parse(raw)?.[field] : null;
     return {
-      version: ROUTE_CACHE_VERSION,
-      routes: parsed?.routes && typeof parsed.routes === "object" ? parsed.routes : {},
+      version: CACHE_VERSION,
+      [field]: entries && typeof entries === "object" ? entries : {},
     };
   } catch {
-    return { version: ROUTE_CACHE_VERSION, routes: {} };
+    return { version: CACHE_VERSION, [field]: {} };
   }
 }
 
-export async function rememberUsageRoute(context, route, result) {
+// Read-modify-write serialized across processes: the gateway refresh lock
+// covers only one relay, and skill/CLI queries hold no lock at all, so
+// concurrent writers would otherwise drop each other's entries. The temp file
+// plus rename keeps readers from ever seeing a half-written file.
+async function updateJsonCache(path, field, source, mutate) {
+  const release = await acquireWriteLock();
+  if (!release) {
+    // Losing one update is safer than an unlocked read-modify-write, which
+    // would drop the other gateways' entries. Caches refill on the next run.
+    await debugLog({ source, skipped: "cache write lock unavailable" });
+    return;
+  }
   try {
-    const cache = await readRouteCache();
-    const key = usageRouteCacheKey(context.baseUrl);
-    cache.routes[key] = {
-      route: route.id,
-      path: route.path,
-      source: result.source,
-      updatedAt: new Date().toISOString(),
-    };
-    await mkdir(dirname(ROUTE_CACHE_PATH), { recursive: true });
-    await writeFile(ROUTE_CACHE_PATH, `${JSON.stringify(cache, null, 2)}\n`);
+    const cache = await readJsonCache(path, field);
+    mutate(cache[field]);
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(cache, null, 2)}\n`);
+    await rename(temp, path);
   } catch (error) {
-    await debugLog({ source: "route-cache", error: error.message });
+    await debugLog({ source, error: error.message });
+  } finally {
+    await release();
   }
 }
 
-async function readSnapshotCache() {
-  try {
-    const raw = await readTextIfExists(SNAPSHOT_PATH);
-    if (!raw.trim()) return { version: SNAPSHOT_VERSION, items: {} };
-    const parsed = JSON.parse(raw);
-    return {
-      version: SNAPSHOT_VERSION,
-      items: parsed?.items && typeof parsed.items === "object" ? parsed.items : {},
+export async function readRouteCache() {
+  return await readJsonCache(ROUTE_CACHE_PATH, "routes");
+}
+
+export async function rememberUsageRoute(context, route, result) {
+  await updateJsonCache(ROUTE_CACHE_PATH, "routes", "route-cache", (routes) => {
+    routes[usageRouteCacheKey(context.baseUrl)] = {
+      route: route.id,
+      path: route.path,
+      source: result.source,
+      updatedAt: new Date().toISOString(),
     };
-  } catch {
-    return { version: SNAPSHOT_VERSION, items: {} };
-  }
+  });
 }
 
 export async function readUsageSnapshot(context) {
-  const cache = await readSnapshotCache();
+  const cache = await readJsonCache(SNAPSHOT_PATH, "items");
   return cache.items[usageRouteCacheKey(context.baseUrl)] || null;
 }
 
 export async function rememberUsageSnapshot(context, result) {
   if (!result?.text) return;
-  try {
-    const cache = await readSnapshotCache();
-    const key = usageRouteCacheKey(context.baseUrl);
-    cache.items[key] = {
+  await updateJsonCache(SNAPSHOT_PATH, "items", "snapshot-cache", (items) => {
+    items[usageRouteCacheKey(context.baseUrl)] = {
       text: result.text,
       source: result.source,
       baseUrl: context.baseUrl,
       updatedAt: new Date().toISOString(),
     };
-    await mkdir(dirname(SNAPSHOT_PATH), { recursive: true });
-    await writeFile(SNAPSHOT_PATH, `${JSON.stringify(cache, null, 2)}\n`);
-  } catch (error) {
-    await debugLog({ source: "snapshot-cache", error: error.message });
-  }
-}
-
-async function readRefreshState() {
-  try {
-    const raw = await readTextIfExists(REFRESH_STATE_PATH);
-    if (!raw.trim()) return { version: REFRESH_STATE_VERSION, items: {} };
-    const parsed = JSON.parse(raw);
-    return {
-      version: REFRESH_STATE_VERSION,
-      items: parsed?.items && typeof parsed.items === "object" ? parsed.items : {},
-    };
-  } catch {
-    return { version: REFRESH_STATE_VERSION, items: {} };
-  }
+  });
 }
 
 export async function rememberRefreshState(context, patch) {
-  try {
-    const state = await readRefreshState();
+  await updateJsonCache(REFRESH_STATE_PATH, "items", "refresh-state", (items) => {
     const key = usageRouteCacheKey(context.baseUrl);
-    state.items[key] = {
-      ...(state.items[key] || {}),
-      ...patch,
-      baseUrl: context.baseUrl,
-    };
-    await mkdir(dirname(REFRESH_STATE_PATH), { recursive: true });
-    await writeFile(REFRESH_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`);
-  } catch (error) {
-    await debugLog({ source: "refresh-state", error: error.message });
+    items[key] = { ...(items[key] || {}), ...patch, baseUrl: context.baseUrl };
+  });
+}
+
+export async function canRefreshUsage(context, minIntervalMs) {
+  if (minIntervalMs <= 0) return true;
+  const state = await readJsonCache(REFRESH_STATE_PATH, "items");
+  const item = state.items[usageRouteCacheKey(context.baseUrl)] || {};
+  const latest = Math.max(
+    ...[item.lastStartedAt, item.lastSuccessAt, item.lastFailureAt]
+      .map((value) => Date.parse(value || ""))
+      .filter(Number.isFinite),
+    0
+  );
+  return latest === 0 || Date.now() - latest >= minIntervalMs;
+}
+
+// `wx` fails when the file exists, which makes creating it an atomic
+// cross-process lock. Returns a release function, or null when the lock is held.
+//
+// Best-effort, not a guarantee: the holder keeps touching the file so a live
+// holder is unlikely to be declared stale, but a suspended machine, a stalled
+// event loop, or a failing utimes can still make one miss its heartbeat. The
+// owner token on release covers most of what slips through — a takeover that
+// happens between reading the token and unlinking still isn't excluded, and a
+// stale holder's heartbeat can even touch the new owner's file, since utimes
+// works on the path rather than a handle. Good enough for a background usage
+// cache, where the worst case is one duplicated refresh that self-heals.
+async function tryLock(lockPath, staleMs, details = {}) {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const token = randomUUID();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        await handle.writeFile(
+          `${JSON.stringify({ token, pid: process.pid, ...details, startedAt: new Date().toISOString() })}\n`
+        );
+      } finally {
+        await handle.close();
+      }
+      const heartbeat = setInterval(() => {
+        const now = new Date();
+        utimes(lockPath, now, now).catch(() => {});
+      }, Math.max(50, Math.floor(staleMs / 3)));
+      heartbeat.unref(); // must never keep the process alive
+      return async () => {
+        clearInterval(heartbeat);
+        // If we were taken over anyway, the file belongs to someone else and
+        // must survive; this check is why a missed heartbeat is recoverable.
+        try {
+          const held = JSON.parse(await readTextIfExists(lockPath));
+          if (held?.token === token) await unlink(lockPath);
+        } catch {
+          // Unreadable or already gone: nothing of ours left to release.
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST" || attempt > 0) return null;
+      const age = await stat(lockPath).then(
+        ({ mtimeMs }) => Date.now() - mtimeMs,
+        () => Infinity // vanished under us: retry immediately
+      );
+      if (age <= staleMs) return null;
+      // Claim the stale lock by renaming it: rename is atomic, so only one
+      // process wins and nobody deletes a lock another just created.
+      try {
+        const claimed = `${lockPath}.${token}`;
+        await rename(lockPath, claimed);
+        await unlink(claimed).catch(() => {});
+      } catch {
+        return null; // another process claimed it first
+      }
+    }
   }
+  return null;
+}
+
+// One lock per gateway, keyed like the route and snapshot caches, so
+// refreshing one relay never blocks another.
+function refreshLockPath(context) {
+  const key = usageRouteCacheKey(context.baseUrl);
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return join(CACHE_DIR, `usage-refresh-${hash}.lock`);
+}
+
+// The holder keeps its lock warm, so this window mostly decides how soon a
+// crashed refresh is reclaimed rather than how long a slow one may run.
+export async function acquireUsageRefreshLease(context, leaseMs = 60_000) {
+  return await tryLock(refreshLockPath(context), leaseMs, { baseUrl: context.baseUrl });
+}
+
+// Writers wait briefly for each other; null means "skip this write" so a cache
+// update never blocks a background refresh.
+async function acquireWriteLock({ timeoutMs = 500, staleMs = 5_000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const release = await tryLock(WRITE_LOCK_PATH, staleMs);
+    if (release) return release;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  } while (Date.now() < deadline);
+  return null;
 }

package/integrations/usage/lib/config.mjs

@@ -13,9 +13,10 @@ export const AUTH_PATH = join(CODEX_HOME, "auth.json");
 export const CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
 export const AGENT_CONFIG_PATH = join(AGENT_TOOLS_HOME, "config.jsonc");
 export const DEBUG_PATH = join(AGENT_TOOLS_HOME, "logs", "usage-debug.log");
-export const ROUTE_CACHE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-routes.json");
-export const SNAPSHOT_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
-export const REFRESH_STATE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
+export const CACHE_DIR = join(AGENT_TOOLS_HOME, "cache");
+export const ROUTE_CACHE_PATH = join(CACHE_DIR, "usage-routes.json");
+export const SNAPSHOT_PATH = join(CACHE_DIR, "usage-snapshot.json");
+export const REFRESH_STATE_PATH = join(CACHE_DIR, "usage-refresh-state.json");
 export const DEFAULT_USAGE_DAYS = 30;
 export const MAX_USAGE_DAYS = 90;
 export const DEFAULT_NEW_API_QUOTA_SCALE = 500000;
@@ -91,13 +92,13 @@ export async function usagePreset() {
   return String(process.env.PROVIDER_USAGE_PRESET || config.preset || "auto").toLowerCase();
 }
 
-// Passive callers (the codex hook fires per prompt; several sessions may run
-// at once) reuse a fresh snapshot instead of hitting the gateway every time.
-// Same knob the statusline uses; 0 disables.
-export function snapshotTtlMs() {
-  const raw = Number(process.env.AGENT_TOOLS_USAGE_SNAPSHOT_TTL_MS);
-  return Number.isFinite(raw) && raw >= 0 ? raw : 60_000;
-}
+// Timing follows the caller's shape, so it is fixed rather than configurable:
+// the hook never waits on the network (snapshot + background refresh), and
+// every other caller either runs detached or is an explicit user request.
+// Past this age a snapshot is too stale to show instead of nothing.
+export const HOOK_SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
+// Minimum gap between gateway queries, however many hooks fire.
+export const REFRESH_INTERVAL_MS = 60_000;
 
 export async function newApiQuotaScale() {
   const config = await agentConfig();