@kairyou/agent-tools 0.8.0 → 0.10.0

package/README.md

@@ -26,7 +26,9 @@ Generate a Conventional Commits message from staged changes and wait for user co
 npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
 ```
 
-- Usage: `/at-commit [<language>]` — language for the commit description (Conventional Commits tokens stay in English)
+Usage:
+
+- `/at-commit [<language>]` — language for the commit description (Conventional Commits tokens stay in English)
 
 ### at-review
 
@@ -36,7 +38,9 @@ Review changes for correctness bugs, regressions, convention violations, and hig
 npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
 ```
 
-- Usage: `/at-review [--fix] [<pr|branch|path>]` — reports findings; `--fix` also applies them
+Usage:
+
+- `/at-review [--fix] [<pr|branch|path>]` — reports findings; `--fix` also applies them
 
 ### at-simplify
 
@@ -46,7 +50,9 @@ Refactor changes to reduce duplication, lower complexity, and improve code quali
 npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 ```
 
-- Usage: `/at-simplify [<pr|branch|path>]`
+Usage:
+
+- `/at-simplify [<pr|branch|path>]`
 
 ### at-zentao
 
@@ -96,8 +102,9 @@ The installer writes `statusLine` to `~/.claude/settings.json`. Example output:
 # Pick and order the fields via statusline.fields in ~/.agent-tools/config.jsonc:
 ⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
 
-# With a compatible API relay, its quota info is shown instead, e.g.:
+# With a compatible API relay, quota info is shown too:
 ⎇ main | Opus 4.8 | balance $362 | today $61.7 | 30d $566
+
 ```
 
 Here `5h` and `w` are Claude's rolling usage windows and `⟳` is the reset
@@ -106,39 +113,32 @@ compatibility and configuration.
 
 ### Provider usage
 
-For API relay / gateway setups: shows the relay's balance / quota inside the
-agent, so when you pay per use or have plan limits you always know how much you
-have spent and how much is left — without opening the gateway console.
-Works with API-key usage endpoints exposed by Sub2API, One API, New API, and
-OpenRouter. Compatibility depends on the gateway version and whether the
-corresponding usage endpoint is enabled.
+Shows API relay / gateway balance and quota inside the agent. Supports Sub2API,
+One API (including OneHub and DoneHub), New API, Claude Code Hub, and OpenRouter;
+compatibility depends on the gateway version and enabled usage endpoints.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
 ```
 
-- **Claude Code** — installs the `at-usage` skill into `~/.claude/skills`; invoke
-  `/at-usage` to show the current usage in the conversation.
-- **Codex** — adds a hook to `UserPromptSubmit` and `Stop` in `~/.codex/hooks.json`
-  and the `at-usage` skill to `~/.agents/skills`. Run `/hooks` inside Codex once
-  to approve it. The Codex CLI displays hook output; some clients (e.g. Paseo)
-  currently do not — invoke `$at-usage` there.
-- **OpenCode** — adds server and TUI plugins: usage refreshes when the session
-  goes idle and shows as a toast, and `/at-usage` shows the latest cached value.
-  Restart opencode after installing or updating.
-
-The relay endpoint is auto-discovered — Codex: the active provider's `base_url`
-and key from `~/.codex/config.toml` / `auth.json`; Claude Code:
-`ANTHROPIC_BASE_URL` plus `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY`.
-Official (non-relay) endpoints are skipped. If it reports
-`Provider usage is unavailable.`, point it at the relay explicitly —
-`PROVIDER_USAGE_BASE_URL` / `PROVIDER_USAGE_API_KEY` env vars override the
-endpoint and key — and tune `providerUsage` in `~/.agent-tools/config.jsonc`:
+- **Claude Code** — invoke `/at-usage` to show the current usage.
+- **Codex** — run `/hooks` once after installation to approve it. The Codex CLI
+  displays usage automatically; clients that hide hook output can use `$at-usage`.
+- **OpenCode** — usage refreshes when the session goes idle and appears as a
+  toast; `/at-usage` shows it on demand. Restart opencode after installing or updating.
+
+The relay endpoint is auto-discovered from the existing Codex and Claude Code
+configuration; official (non-relay) endpoints are skipped. If it reports
+`Provider usage is unavailable.`, set `PROVIDER_USAGE_BASE_URL` and
+`PROVIDER_USAGE_API_KEY` to override the endpoint and key. Configure
+`providerUsage` in `~/.agent-tools/config.jsonc` only when needed:
 
 ```jsonc
 {
   "providerUsage": {
-    "preset": "auto", // auto | sub2api | one-api | new-api | openrouter | <custom-route-id>
+    // auto | sub2api | openai-compatible | one-api | one-hub |
+    // done-hub | new-api | claude-code-hub | openrouter | <custom-route-id>
+    "preset": "auto",
     "days": 30,       // how many recent days of spend to count
     "debug": false    // true: log probes to ~/.agent-tools/logs/usage-debug.log
   }
@@ -146,74 +146,37 @@ endpoint and key — and tune `providerUsage` in `~/.agent-tools/config.jsonc`:
 ```
 
 Keep `preset` set to `auto` for automatic detection. Select a specific protocol
-only when you know which usage endpoint the gateway exposes; a configured
-custom route id is also accepted.
+only when you know which usage endpoint the gateway exposes; a configured custom
+route id is also accepted.
 
 Output examples:
 
 ```text
-# Relay plan quota.
+# Plan limits (sub2api / openai-compatible).
 D $0.0/$100 | W $0.0/$300 | Exp 07-08
 
-# Wallet balance.
+# Multi-window limits (claude-code-hub).
+5h $2.1/$10.0 | D $8.0/$20.0 | T $19.0/$100 | Exp 08-31
+
+# Balance and usage (one-api / one-hub / done-hub / new-api / openrouter).
+balance $15.0 | used $5.0/$20.0
+
+# Wallet and recent spend (sub2api).
 balance $362 | today $61.7 | 30d $566
 ```
 
-Fields: `D/W/M` are daily/weekly/monthly spend against plan limits; `Exp` is
-the plan expiry; `balance` is wallet credit; `today` and `30d` are API spend.
+Fields: `5h/D/W/M/T` are five-hour/daily/weekly/monthly/total spend against
+limits; `Exp` is the plan expiry; `balance` is wallet credit; `used` is consumed
+credit; `today` and `30d` are today's and the last 30 days' API spend.
 
 #### Custom gateway routes
 
-For gateways the built-in probes cannot reach (e.g. cookie-authenticated
-relays), write your own route module and declare it in `providerUsage.routes`
-(paths resolve against `~/.agent-tools`). Declared routes are probed first;
-setting `"preset"` to a route id selects it directly.
-
-```jsonc
-{
-  "providerUsage": {
-    "routes": [
-      "custom/my-gateway.mjs",
-      "custom/another-gateway.mjs"
-    ],
-    "myGateway": { "username": "me", "password": "..." }
-  }
-}
-```
-
-```js
-// ~/.agent-tools/custom/my-gateway.mjs
-export const meta = { id: "my-gateway" }; // optional; id defaults to the file name
-
-export async function run(context, { requestJson, agentConfig }) {
-  // context: { baseUrl, key, providerName, provider, label }
-  const { myGateway = {} } = await agentConfig(); // the providerUsage object; custom keys welcome
-
-  // Tip: save the token to a file (e.g. under ~/.agent-tools/cache) and reuse
-  // it; log in again only when a query fails with it (e.g. 401), then save the
-  // new token.
-  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();
-
-  // Plain fetch works too; custom headers: authorization, cookie, ...
-  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
-    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
-  });
-  return { text: `balance ¥${me?.data?.balance}` };
-}
-```
-
-`text` is a free-form string; return `{ text }` on success, throw to fall
-through to the next route (with `providerUsage.debug` enabled, failures are
-logged to `~/.agent-tools/logs/usage-debug.log`).
+Gateways not covered by the built-in probes can use a custom route. See
+[Custom gateway routes](docs/en/custom-gateway-routes.md).
 
 ### Vision (cross-model image understanding)
 
-Lets a main model that cannot see images ask a multimodal model specific questions about an image (local path or http(s) URL) and reason on from the answers. Typical uses: reading error screenshots, implementing UI from design mockups, locating the glitch in a bug-report screenshot. One installer capability bundling three parts: the `inspect_image` MCP stdio server, the `at-vision` policy skill, and a human diagnostic CLI.
+Lets a main model that cannot see images use a multimodal model to analyze error screenshots, implement UI from design mockups, and inspect bug-report screenshots.
 
 #### Install
 
@@ -221,10 +184,7 @@ Lets a main model that cannot see images ask a multimodal model specific questio
 npx -y @kairyou/agent-tools@latest vision -a claude codex opencode
 ```
 
-Uninstalling keeps your vision provider config. The installer registers the
-`inspect_image` MCP server for each agent (Claude Code: `~/.claude.json`; Codex:
-`~/.codex/config.toml`; OpenCode: `opencode.json`) and installs the `at-vision`
-skill into the agent's skills directory.
+Uninstalling keeps your vision provider config by default.
 
 #### Configure
 
@@ -236,20 +196,19 @@ skill into the agent's skills directory.
     "provider": "openai-compatible",       // or "anthropic-compatible"
     "baseUrl": "https://gateway.example.com/v1",  // anthropic-compatible: gateway root, /v1/messages is appended
     "model": "internal-vlm",
-    "apiKey": { "env": "OPENAI_API_KEY" }  // reuse an existing env var, or the key itself
+    "apiKey": { "env": "OPENAI_API_KEY" }  // read from the OPENAI_API_KEY environment variable
     // , "timeoutMs": 30000, "maxImageBytes": 20971520, "maxOutputTokens": 8192
     // , "maxConcurrentRequests": 2, "maxRequestsPerMinute": 30
   }
 }
 ```
 
-`apiKey` takes the key itself, or `{ "env": "VARIABLE_NAME" }` to reuse an existing environment variable; omit it if your gateway needs no key.
-The runtime sends provider requests directly, so the API key never enters a shell command; user-facing errors redact it as `***`. `maxConcurrentRequests` and `maxRequestsPerMinute` are shared across local MCP and CLI processes.
-Image bytes are streamed into the provider's base64 JSON request without recompression; URL inputs use a private temporary file that is removed after each request.
+`apiKey` can be a key string such as `"apiKey": "sk-..."`, or an environment variable reference such as `{ "env": "OPENAI_API_KEY" }`. Omit it if your gateway requires no key. Prefer an environment variable to avoid storing the key in the config file.
 
 #### Use
 
-Pass images as file paths or URLs in your message. The agent prefers the `inspect_image` MCP tool and falls back to the installed local vision CLI when its model gateway cannot invoke MCP namespace tools. Do not paste screenshots directly: with a non-vision main model the paste fails with an API 400 before any tool runs — save the image and give its path instead.
+Pass a local image path or URL in your message. If the main model cannot accept
+pasted images, save the image first and pass its file path instead.
 
 To diagnose the provider setup or test recognition quality manually:
 
@@ -266,25 +225,7 @@ To run directly from the repository, replace the npm package name with
 npx -y github:kairyou/agent-tools usage -a codex
 ```
 
-## Repository Structure
-
-```text
-agent-tools/
-├── .claude-plugin/    # Claude Code/plugin ecosystem manifest.
-├── .codex-plugin/     # Codex plugin manifest.
-├── integrations/      # Installable capabilities, one directory each.
-│   ├── statusline/    # Agent status line: branch, model, usage.
-│   ├── usage/         # Provider balance / quota display.
-│   └── vision/        # Cross-model image understanding.
-├── skills/            # Reusable Agent Skills.
-│   ├── workflow/      # Workflow-oriented skills.
-│   │   ├── at-commit/   # Conventional Commit message skill.
-│   │   ├── at-review/   # Review changes for bugs and regressions.
-│   │   └── at-simplify/ # Reduce complexity and duplication in changes.
-│   └── integrations/  # Skills that integrate external systems.
-│       └── at-zentao/   # ZenTao bug/task fixing workflow.
-└── scripts/           # Install, sync, validation, and maintenance scripts.
-```
+Contributors can see the [repository structure](docs/en/repository-structure.md).
 
 ## FAQ
 
@@ -294,8 +235,11 @@ agent-tools/
 PromptScript agent does not support global installation. It does not affect
 other agents and can be ignored. See [`skills` issue #1352](https://github.com/vercel-labs/skills/issues/1352).
 
-## References
+## Acknowledgements
 
-- [OpenCommit](https://github.com/di-sukharev/opencommit)
-- [GitLens](https://github.com/gitkraken/vscode-gitlens)
-- [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)
+- `at-commit` draws on commit-message generation ideas from
+  [OpenCommit](https://github.com/di-sukharev/opencommit) and
+  [GitLens](https://github.com/gitkraken/vscode-gitlens), reimplemented for an
+  Agent Skill workflow.
+- `at-review` and `at-simplify` draw on the corresponding workflows in
+  [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts).

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # Agent Tools
 
+[English](README.md)
+
 可复用的 Agent Skills, 以及面向 Codex, Claude Code 与 opencode 的可安装 integrations: statusline, provider usage 与跨模型识图.
 
 需要 Node.js >= 22.
@@ -24,7 +26,9 @@ npx -y skills@latest add kairyou/agent-tools --skill <name...> -g -y
 npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
 ```
 
-- 用法: `/at-commit [<语言>]` — 指定 commit description 的语言(Conventional Commits 语法部分保持英文)
+用法:
+
+- `/at-commit [<语言>]` — 指定 commit description 的语言(Conventional Commits 语法部分保持英文)
 
 ### at-review
 
@@ -34,7 +38,9 @@ npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
 npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
 ```
 
-- 用法: `/at-review [--fix] [<pr|分支|路径>]` — 输出审查结果; 加 `--fix` 则同时应用修复
+用法:
+
+- `/at-review [--fix] [<pr|分支|路径>]` — 输出审查结果; 加 `--fix` 则同时应用修复
 
 ### at-simplify
 
@@ -44,7 +50,9 @@ npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
 npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 ```
 
-- 用法: `/at-simplify [<pr|分支|路径>]`
+用法:
+
+- `/at-simplify [<pr|分支|路径>]`
 
 ### at-zentao
 
@@ -93,8 +101,9 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 # 显示项与顺序由 ~/.agent-tools/config.jsonc 的 statusline.fields 控制:
 ⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
 
-# 使用兼容的 API 中转时, 显示中转的额度信息, 比如:
+# 使用兼容的 API 中转时, 也会显示中转额度:
 ⎇ main | Opus 4.8 | balance $362 | today $61.7 | 30d $566
+
 ```
 
 其中 `5h` / `w` 是 Claude 的滚动用量窗口, `⟳` 后面是重置倒计时;
@@ -102,35 +111,31 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 
 ### Provider usage
 
-面向使用 API 中转的场景: 在 agent 内直接显示中转网关的余额/额度, 按量付费或
-有套餐限额时, 随时知道花了多少, 还剩多少, 不用切出去登录网关后台.
-支持 Sub2API, One API, New API 与 OpenRouter 提供的 API Key 用量接口.
-具体兼容性取决于网关版本及其是否开放相应接口.
+在 agent 内查看 API 中转网关的余额和额度. 支持 Sub2API, One API (包括 OneHub
+与 DoneHub), New API, Claude Code Hub 和 OpenRouter. 具体兼容性取决于网关版本
+及其是否开放相应接口.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
 ```
 
-- **Claude Code** — 把 `at-usage` skill 装入 `~/.claude/skills`; 调用
-  `/at-usage` 即可在对话中显示当前用量.
-- **Codex** — 把 hook 添加到 `~/.codex/hooks.json` 的 `UserPromptSubmit` 和
-  `Stop`, 并把 `at-usage` skill 装入 `~/.agents/skills`. 安装后在 Codex 里运行
-  `/hooks` 批准一次. Codex CLI 会显示 hook 输出; 部分客户端(如 Paseo)目前不显示,
-  可调用 `$at-usage` 按需查询.
-- **OpenCode** — 添加 server plugin 和 TUI plugin: session 进入 idle 后自动刷新
-  usage 并以 toast 显示, `/at-usage` 查看最新缓存值. 安装或更新后需要重启 opencode.
-
-中转端点自动发现 — Codex: 读取 `~/.codex/config.toml` / `auth.json` 里当前
-provider 的 `base_url` 和密钥; Claude Code: 读取 `ANTHROPIC_BASE_URL` 与
-`ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY`. 官方(非中转)端点会被跳过.
-如果结果是 `Provider usage is unavailable.`, 可用环境变量
-`PROVIDER_USAGE_BASE_URL` / `PROVIDER_USAGE_API_KEY` 显式指定端点和密钥,
-并在 `~/.agent-tools/config.jsonc` 里调整 `providerUsage`:
+- **Claude Code** — 调用 `/at-usage` 在对话中查看当前用量.
+- **Codex** — 安装后运行 `/hooks` 批准一次. Codex CLI 会自动显示用量;
+  不显示 hook 输出的客户端可调用 `$at-usage` 查询.
+- **OpenCode** — 空闲时自动刷新并以 toast 显示, 也可调用 `/at-usage` 查询.
+  安装或更新后需要重启 opencode.
+
+默认会从 Codex 和 Claude Code 的现有配置中自动发现中转端点, 并跳过官方端点.
+如果结果是 `Provider usage is unavailable.`, 可用
+`PROVIDER_USAGE_BASE_URL` / `PROVIDER_USAGE_API_KEY` 显式指定端点和密钥.
+需要调整探测方式时, 在 `~/.agent-tools/config.jsonc` 中配置 `providerUsage`:
 
 ```jsonc
 {
   "providerUsage": {
-    "preset": "auto", // auto | sub2api | one-api | new-api | openrouter | <自定义 route id>
+    // auto | sub2api | openai-compatible | one-api | one-hub |
+    // done-hub | new-api | claude-code-hub | openrouter | <自定义 route id>
+    "preset": "auto",
     "days": 30,       // 统计最近多少天的消耗
     "debug": false    // true: 探测过程写入 ~/.agent-tools/logs/usage-debug.log
   }
@@ -143,65 +148,30 @@ provider 的 `base_url` 和密钥; Claude Code: 读取 `ANTHROPIC_BASE_URL` 与
 显示效果示例:
 
 ```text
-# 中转套餐额度.
+# 套餐限额 (sub2api / openai-compatible).
 D $0.0/$100 | W $0.0/$300 | Exp 07-08
 
-# 钱包余额.
+# 多窗口限额 (claude-code-hub).
+5h $2.1/$10.0 | D $8.0/$20.0 | T $19.0/$100 | Exp 08-31
+
+# 余额与用量 (one-api / one-hub / done-hub / new-api / openrouter).
+balance $15.0 | used $5.0/$20.0
+
+# 钱包与近期消耗 (sub2api).
 balance $362 | today $61.7 | 30d $566
 ```
 
-字段含义: `D/W/M` 是日/周/月套餐消耗与上限, `Exp` 是套餐到期日,
-`balance` 是钱包余额, `today` / `30d` 是今日与近 30 天 API 消耗.
+字段含义: `5h/D/W/M/T` 是 5 小时/日/周/月/总消耗与上限, `Exp` 是套餐到期日,
+`balance` 是钱包余额, `used` 是已用额度, `today` / `30d` 是今日与近 30 天 API 消耗.
 
 #### 自定义网关路由
 
-内置探测覆盖不到的网关(比如 cookie 认证的中转), 可以自己写路由模块并在
-`providerUsage.routes` 里声明(相对 `~/.agent-tools` 解析). 声明的路由优先
-探测; `"preset"` 填路由 id 可直接选中.
-
-```jsonc
-{
-  "providerUsage": {
-    "routes": [
-      "custom/my-gateway.mjs",
-      "custom/another-gateway.mjs"
-    ],
-    "myGateway": { "username": "me", "password": "..." }
-  }
-}
-```
-
-```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 对象, 自定义键随意加
-
-  // 建议: 把 token 存到文件里(如 ~/.agent-tools/cache 下)重复使用,
-  // 用它查询失败(如 401)时才重新登录, 并把新 token 写回文件.
-  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();
-
-  // 用 fetch 也行; 自定义 header: authorization, cookie 等.
-  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`).
+内置探测覆盖不到的网关可以通过自定义路由接入, 详见
+[自定义网关路由](docs/zh-CN/custom-gateway-routes.md).
 
 ### Vision(跨模型识图)
 
-让不支持图片的主模型借助多模态模型识图: 针对图片(本地路径或 http(s) URL)提出具体问题, 拿到答案后继续自己的推理. 常见场景: 读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题. 一个安装器 capability 包含三部分: `inspect_image` MCP stdio server, `at-vision` 策略 skill, 以及人工诊断 CLI.
+让不支持图片的主模型借助多模态模型识图, 适用于读取报错截图、按设计稿还原 UI、定位测试反馈截图里的界面问题.
 
 #### 安装
 
@@ -209,9 +179,7 @@ export async function run(context, { requestJson, agentConfig }) {
 npx -y @kairyou/agent-tools@latest vision -a claude codex opencode
 ```
 
-卸载默认保留 vision provider 配置. 安装器会为每个 agent 注册 `inspect_image`
-MCP server (Claude Code: `~/.claude.json`; Codex: `~/.codex/config.toml`;
-OpenCode: `opencode.json`), 并把 `at-vision` skill 装入对应 agent 的 skills 目录.
+卸载时默认保留 vision provider 配置.
 
 #### 配置
 
@@ -223,20 +191,19 @@ OpenCode: `opencode.json`), 并把 `at-vision` skill 装入对应 agent 的 skil
     "provider": "openai-compatible",       // 或 "anthropic-compatible"
     "baseUrl": "https://gateway.example.com/v1",  // anthropic-compatible 填网关根地址, 会自动拼 /v1/messages
     "model": "internal-vlm",
-    "apiKey": { "env": "OPENAI_API_KEY" }  // 引用已有环境变量, 也可以直接填密钥
+    "apiKey": { "env": "OPENAI_API_KEY" }  // 从环境变量 OPENAI_API_KEY 读取
     // , "timeoutMs": 30000, "maxImageBytes": 20971520, "maxOutputTokens": 8192
     // , "maxConcurrentRequests": 2, "maxRequestsPerMinute": 30
   }
 }
 ```
 
-`apiKey` 可直接填密钥, 或用 `{ "env": "VARIABLE_NAME" }` 引用已有环境变量; 网关不需要密钥时可省略.
-Provider 请求由 runtime 直接发送, API key 不进入 shell 命令; 对外错误会将 key 脱敏为 `***`. `maxConcurrentRequests` 和 `maxRequestsPerMinute` 在本机的 MCP/CLI 进程之间共享.
-图片字节会无损地流式编码到 Provider 的 base64 JSON 请求中, 不做重压缩; URL 图片使用私有临时文件, 每次请求结束后自动删除.
+`apiKey` 可以直接填写密钥字符串, 例如 `"apiKey": "sk-..."`; 也可以使用 `{ "env": "OPENAI_API_KEY" }` 从环境变量读取. 网关不需要密钥时可以省略. 建议优先使用环境变量, 避免把密钥写入配置文件.
 
 #### 使用
 
-在消息里给出图片的文件路径或 URL 即可. Agent 优先调用 MCP 的 `inspect_image`; 模型网关不支持 MCP namespace tools 时, 改用已安装的本地 vision CLI. 不要直接粘贴截图: 主模型不支持图片时, 粘贴会在到达工具前就报 API 400 — 保存成文件再给路径.
+在消息里给出本地图片路径或 URL 即可. 主模型不支持图片时, 请先保存图片,
+再提供文件路径, 不要直接粘贴.
 
 人工排查配置或测试识别质量时可用:
 
@@ -252,25 +219,7 @@ npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背
 npx -y github:kairyou/agent-tools usage -a codex
 ```
 
-## 仓库结构
-
-```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 修复工作流.
-└── scripts/           # 安装, 同步, 校验和仓库维护脚本.
-```
+贡献者可参考[仓库结构](docs/zh-CN/repository-structure.md).
 
 ## FAQ
 
@@ -279,8 +228,11 @@ agent-tools/
 `PromptScript does not support global skill installation` 表示 PromptScript Agent 不支持全局
 安装, 不影响其他 Agent, 可忽略. 参见 [`skills` issue #1352](https://github.com/vercel-labs/skills/issues/1352).
 
-## References
+## 参考与致谢
 
-- [OpenCommit](https://github.com/di-sukharev/opencommit)
-- [GitLens](https://github.com/gitkraken/vscode-gitlens)
-- [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)
+- `at-commit` 借鉴了 [OpenCommit](https://github.com/di-sukharev/opencommit) 和
+  [GitLens](https://github.com/gitkraken/vscode-gitlens) 的提交消息生成思路,
+  并针对 Agent Skill 工作流重新实现.
+- `at-review` 和 `at-simplify` 参考了
+  [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)
+  中对应工作流的设计.

package/dist/usage/cli.mjs

@@ -875,9 +875,10 @@ var AUTH_PATH = join(CODEX_HOME, "auth.json");
 var CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
 var AGENT_CONFIG_PATH = join(AGENT_TOOLS_HOME, "config.jsonc");
 var DEBUG_PATH = join(AGENT_TOOLS_HOME, "logs", "usage-debug.log");
-var ROUTE_CACHE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-routes.json");
-var SNAPSHOT_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
-var REFRESH_STATE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
+var CACHE_DIR = join(AGENT_TOOLS_HOME, "cache");
+var ROUTE_CACHE_PATH = join(CACHE_DIR, "usage-routes.json");
+var SNAPSHOT_PATH = join(CACHE_DIR, "usage-snapshot.json");
+var REFRESH_STATE_PATH = join(CACHE_DIR, "usage-refresh-state.json");
 async function readTextIfExists(path) {
   if (!existsSync(path)) return "";
   return readFile(path, "utf8");
@@ -928,6 +929,7 @@ async function debugLog(event) {
   await writeFile(DEBUG_PATH, `${line}
 `, { flag: "a" });
 }
+var HOOK_SNAPSHOT_MAX_AGE_MS = 10 * 6e4;
 
 // integrations/usage/cli.mjs
 function parseAgent(argv) {

package/dist/usage/codex-hook.mjs

@@ -13,6 +13,7 @@ var LOG_PATH = path.join(AGENT_TOOLS_HOME, "logs", "usage-hook.log");
 var TIMEOUT_MS = Number(process.env.AGENT_TOOLS_USAGE_HOOK_TIMEOUT_MS || 4500);
 var MAX_LOG_BYTES = Number(process.env.AGENT_TOOLS_USAGE_HOOK_LOG_BYTES || 256 * 1024);
 var KEEP_LOG_BYTES = 128 * 1024;
+var SILENT = process.argv.includes("--silent");
 function hookOut(message) {
   const payload = { continue: true };
   if (message) payload.systemMessage = message;
@@ -56,6 +57,9 @@ function rotateLogIfNeeded() {
 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 };
@@ -64,16 +68,20 @@ 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;
@@ -114,7 +122,7 @@ async function runUsageScript() {
       node: process.version,
       platform: `${process.platform} ${os.release()}`
     });
-    hookOut(failureMessage());
+    hookFailureOut();
     return;
   }
   try {
@@ -129,7 +137,7 @@ async function runUsageScript() {
       stderr: preview(result.stderr),
       usageScript: USAGE_SCRIPT
     });
-    hookOut(failureMessage());
+    hookFailureOut();
   }
 }
 try {
@@ -140,5 +148,5 @@ try {
     error: error?.stack || error?.message || String(error),
     usageScript: USAGE_SCRIPT
   });
-  hookOut(failureMessage());
+  hookFailureOut();
 }