@kairyou/agent-tools 0.2.0 → 0.3.0

package/README.md

@@ -1,19 +1,19 @@
 # Agent Tools
 
-Reusable skills and runtime integrations for Codex, Claude Code, and opencode. This repository keeps each capability in predictable locations so projects can opt into only what they need.
+Reusable Agent Skills, plus runtime integrations for Codex, Claude Code, and opencode.
 
 [中文](README.zh-CN.md)
 
-## Directory Layout
+## Repository Structure
 
 ```text
 agent-tools/
 ├── .claude-plugin/    # Claude Code/plugin ecosystem manifest.
 ├── .codex-plugin/     # Codex plugin manifest.
-├── hooks/             # Shared and agent-specific hook integrations.
-├── plugins/           # Runtime plugins loaded by supported agents.
-│   └── vision/        # Cross-model image understanding (inspect_image MCP server + bundled at-vision skill).
-├── scripts/           # Install, sync, validation, and maintenance scripts.
+├── integrations/      # Installable capabilities, one directory each; files named by agent + form.
+│   ├── statusline/    # Claude Code command-backed statusLine script.
+│   ├── usage/         # Provider usage (query core + codex hook, opencode plugins, CLI, at-usage skill template).
+│   └── vision/        # Cross-model image understanding (inspect_image MCP server + at-vision skill).
 ├── skills/            # Reusable Agent Skills for CLI discovery and plugin manifests.
 │   ├── workflow/      # Workflow-oriented skills.
 │   │   ├── at-commit/   # Conventional Commit message skill.
@@ -21,9 +21,7 @@ agent-tools/
 │   │   └── at-simplify/ # Reduce complexity and duplication in changes.
 │   └── integrations/  # Skills that integrate external systems.
 │       └── at-zentao/   # ZenTao bug/task fixing workflow.
-├── statusline/        # Statusline scripts/templates, grouped by agent.
-│   └── claude/        # Claude command-backed statusLine script + example config.
-└── lib/               # Shared implementation used by hooks, statuslines, and installers.
+└── scripts/           # Install, sync, validation, and maintenance scripts.
 ```
 
 ## Skills
@@ -85,70 +83,27 @@ Usage:
 
 Config: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. First run guides you; fill `password` in the file yourself (or env `ZENTAO_PASSWORD`), never in chat.
 
-## Plugins
+## Integrations
 
-### 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.
-
-#### Install
-
-```bash
-# One command per agent (or list several)
-npx -y @kairyou/agent-tools@latest vision -a claude
-npx -y @kairyou/agent-tools@latest vision -a codex claude opencode
-
-# Preview or uninstall (uninstall keeps your vision provider config)
-npx -y @kairyou/agent-tools@latest vision -a claude --dry-run
-npx -y @kairyou/agent-tools@latest vision -a claude --uninstall
-```
-
-Install atomically writes a prebuilt, self-contained MCP runtime to `~/.agent-tools/vision-runtime`, registers it per agent (Claude Code: `~/.claude.json`; Codex: a marker-delimited block in `~/.codex/config.toml`; OpenCode: `opencode.json`), and installs the `at-vision` skill into the agent's global skills directory (Claude Code: `~/.claude/skills`; Codex: `~/.agents/skills`; OpenCode: its config directory's `skills`). Installation does not download a second dependency tree; re-run the command to update. Uninstalling the last agent that references the shared runtime removes it while preserving the vision provider config.
-
-#### Configure
-
-`~/.agent-tools/config.jsonc` is the only config entry point:
-
-```jsonc
-{
-  "vision": {
-    "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
-    // optional: "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.
-
-#### 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.
-
-To diagnose the provider setup or test recognition quality manually:
+Runtime capabilities, installed per agent:
 
 ```bash
-npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "What are the navbar background color and height?"
+npx -y @kairyou/agent-tools@latest <capability> -a <agent...>
 ```
 
-## Runtime integrations
+`--dry-run` previews, `--uninstall` removes, and re-running the install command
+updates.
 
-### Claude Code
+| Capability | Claude Code | Codex | OpenCode |
+| --- | --- | --- | --- |
+| `statusline` | ✓ | – | – |
+| `usage` | `/at-usage` skill | hook + `$at-usage` skill | toast + `/at-usage` command |
+| `vision` | ✓ | ✓ | ✓ |
 
-#### Statusline
+### Statusline
 
 ```bash
-# Install or update
 npx -y @kairyou/agent-tools@latest statusline -a claude
-
-# Preview or uninstall
-npx -y @kairyou/agent-tools@latest statusline -a claude --dry-run
-npx -y @kairyou/agent-tools@latest statusline -a claude --uninstall
 ```
 
 The installer writes `statusLine` to `~/.claude/settings.json`. The default
@@ -165,67 +120,92 @@ To choose what appears, edit `statusline.fields` in
 `~/.agent-tools/config.jsonc`. The installer may add new default keys on update;
 it preserves top-of-file comments and existing values.
 
-### Codex
+### Provider usage
 
-#### Provider usage hook
+Shows the active API provider's balance / quota inside each agent.
 
 ```bash
-# Install or update
+npx -y @kairyou/agent-tools@latest usage -a claude
 npx -y @kairyou/agent-tools@latest usage -a codex
-
-# Preview or uninstall
-npx -y @kairyou/agent-tools@latest usage -a codex --dry-run
-npx -y @kairyou/agent-tools@latest usage -a codex --uninstall
+npx -y @kairyou/agent-tools@latest usage -a opencode
 ```
 
-The installer adds the hook to `UserPromptSubmit` and `Stop` in
-`~/.codex/hooks.json`. After installation, run `/hooks` inside Codex and approve
-the agent-tools usage hooks.
+- **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. Hook output only appears in the Codex CLI; in clients that do
+  not show it (e.g. Paseo), invoke `$at-usage`.
+- **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.
 
 Output examples:
 
 ```text
 # Subscription / plan quota.
-warning: API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
 
 # Wallet balance.
-warning: API | balance $362 | today $61.7 | 30d $566
+API | 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.
 
-### OpenCode
+#### Supported gateways
 
-#### Provider usage plugin
+Balance, quota, and plan usage queries support compatible Sub2API-like,
+NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like, and OpenRouter gateways.
 
-```bash
-# Install or update
-npx -y @kairyou/agent-tools@latest usage -a opencode
+### Vision (cross-model image understanding)
 
-# Preview or uninstall
-npx -y @kairyou/agent-tools@latest usage -a opencode --dry-run
-npx -y @kairyou/agent-tools@latest usage -a opencode --uninstall
+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.
+
+#### Install
+
+```bash
+npx -y @kairyou/agent-tools@latest vision -a claude
+npx -y @kairyou/agent-tools@latest vision -a codex claude opencode
 ```
 
-The installer adds global server and TUI plugins. After the active session
-becomes idle, the server plugin refreshes usage and shows it as a toast. The TUI
-plugin also registers `/at-usage` for the latest cached value. Restart opencode
-after installing or updating the plugins.
+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.
 
-Toast example:
+#### Configure
 
-```text
-Provider usage
-balance $244 | today $45.8 | 30d $604
+`~/.agent-tools/config.jsonc` is the only config entry point:
+
+```jsonc
+{
+  "vision": {
+    "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
+    // optional: "timeoutMs": 30000, "maxImageBytes": 20971520, "maxOutputTokens": 8192,
+    //           "maxConcurrentRequests": 2, "maxRequestsPerMinute": 30
+  }
+}
 ```
 
-### Supported gateways
+`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.
 
-Balance, quota, and plan usage queries support compatible Sub2API-like,
-NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like, and OpenRouter gateways.
+#### 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.
+
+To diagnose the provider setup or test recognition quality manually:
+
+```bash
+npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "What are the navbar background color and height?"
+```
 
-### Run from Git
+## Run from Git
 
 To run directly from the repository, replace the npm package name with
 `github:kairyou/agent-tools` (Git required):

package/README.zh-CN.md

@@ -1,17 +1,17 @@
 # Agent Tools
 
-面向 Codex、Claude Code 与 opencode 的可复用 skills 和 runtime integrations. 本仓库把各项能力放在可预期的位置; 不同项目可以只安装自己需要的部分.
+可复用的 Agent Skills, 以及面向 Codex、Claude Code 与 opencode 的 runtime integrations.
 
-## 目录结构
+## 仓库结构
 
 ```text
 agent-tools/
 ├── .claude-plugin/    # Claude Code/plugin 生态的 manifest。
 ├── .codex-plugin/     # Codex plugin manifest。
-├── hooks/             # 通用 hook 逻辑及各 agent 的适配实现。
-├── plugins/           # 由各 agent 加载的 runtime plugins.
+├── integrations/      # 可安装的 capability, 一个一目录; 文件按 agent + 形态命名.
+│   ├── statusline/    # Claude Code command-backed statusLine 脚本.
+│   ├── usage/         # Provider usage (查询核心 + codex hook, opencode plugins, CLI, at-usage skill 模板).
 │   └── vision/        # 跨模型识图(inspect_image MCP server + 内置 at-vision skill)。
-├── scripts/           # 安装、同步、校验和仓库维护脚本。
 ├── skills/            # 可复用 Agent Skills，供 CLI 扫描和 plugin manifest 声明。
 │   ├── workflow/      # 工作流类 skills。
 │   │   ├── at-commit/   # 生成 Conventional Commits message.
@@ -19,9 +19,7 @@ agent-tools/
 │   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
 │   └── integrations/  # 对接外部系统的 skills。
 │       └── at-zentao/   # 禅道 bug/task 修复工作流.
-├── statusline/        # Statusline 配置片段/模板，按 agent 分组。
-│   └── claude/        # Claude command-backed statusLine 脚本和示例配置。
-└── lib/               # hooks、statusline、installer 复用的共享实现。
+└── scripts/           # 安装、同步、校验和仓库维护脚本。
 ```
 
 ## Skills
@@ -83,70 +81,26 @@ npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
 
 配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 首次使用会引导; `password` 自己填进文件(或设环境变量 `ZENTAO_PASSWORD`), 不要发在对话里.
 
-## Plugins
+## Integrations
 
-### Vision(跨模型识图)
-
-让不支持图片的主模型借助多模态模型识图: 针对图片(本地路径或 http(s) URL)提出具体问题, 拿到答案后继续自己的推理. 常见场景: 读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题. 一个安装器 capability 包含三部分: `inspect_image` MCP stdio server, `at-vision` 策略 skill, 以及人工诊断 CLI.
-
-#### 安装
+Runtime capability, 按 agent 选装:
 
 ```bash
-# 每个 agent 一条命令(也可以一次列多个)
-npx -y @kairyou/agent-tools@latest vision -a claude
-npx -y @kairyou/agent-tools@latest vision -a codex claude opencode
-
-# 预览或卸载(卸载默认保留 vision provider 配置)
-npx -y @kairyou/agent-tools@latest vision -a claude --dry-run
-npx -y @kairyou/agent-tools@latest vision -a claude --uninstall
+npx -y @kairyou/agent-tools@latest <capability> -a <agent...>
 ```
 
-安装会把预构建的自包含 MCP runtime 原子写入 `~/.agent-tools/vision-runtime`, 为每个 agent 注册(Claude Code: `~/.claude.json`; Codex: `~/.codex/config.toml` 中带标记的独立块; OpenCode: `opencode.json`), 并把 `at-vision` skill 装入对应 agent 的全局 skills 目录(Claude Code: `~/.claude/skills`; Codex: `~/.agents/skills`; OpenCode: 配置目录下的 `skills`). 安装过程不再二次下载依赖; 更新 = 重新执行安装命令. 卸载最后一个引用该 runtime 的 agent 时会一并清理 runtime, 但保留 vision provider 配置.
+`--dry-run` 预览, `--uninstall` 卸载, 重新执行安装命令即为更新.
 
-#### 配置
+| Capability | Claude Code | Codex | OpenCode |
+| --- | --- | --- | --- |
+| `statusline` | ✓ | – | – |
+| `usage` | `/at-usage` skill | hook + `$at-usage` skill | toast + `/at-usage` 命令 |
+| `vision` | ✓ | ✓ | ✓ |
 
-`~/.agent-tools/config.jsonc` 是唯一配置入口:
-
-```jsonc
-{
-  "vision": {
-    "provider": "openai-compatible",       // 或 "anthropic-compatible"
-    "baseUrl": "https://gateway.example.com/v1",  // anthropic-compatible 填网关根地址, 会自动拼 /v1/messages
-    "model": "internal-vlm",
-    "apiKey": { "env": "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 图片使用私有临时文件, 每次请求结束后自动删除.
-
-#### 使用
-
-在消息里给出图片的文件路径或 URL 即可. Agent 优先调用 MCP 的 `inspect_image`; 模型网关不支持 MCP namespace tools 时, 改用已安装的本地 vision CLI. 不要直接粘贴截图: 主模型不支持图片时, 粘贴会在到达工具前就报 API 400 — 保存成文件再给路径.
-
-人工排查配置或测试识别质量时可用:
+### Statusline
 
 ```bash
-npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背景色和高度是多少"
-```
-
-## Runtime integrations
-
-### Claude Code
-
-#### Statusline
-
-```bash
-# 安装或更新
 npx -y @kairyou/agent-tools@latest statusline -a claude
-
-# 预览或卸载
-npx -y @kairyou/agent-tools@latest statusline -a claude --dry-run
-npx -y @kairyou/agent-tools@latest statusline -a claude --uninstall
 ```
 
 安装器会把 `statusLine` 写入 `~/.claude/settings.json`. 默认显示:
@@ -161,65 +115,90 @@ npx -y @kairyou/agent-tools@latest statusline -a claude --uninstall
 如需控制显示项, 修改 `~/.agent-tools/config.jsonc` 里的
 `statusline.fields`. 安装器更新时可能补充新的默认键; 文件顶部注释和已有值会保留.
 
-### Codex
+### Provider usage
 
-#### Provider usage hook
+在各 agent 内显示当前 API provider 的余额/额度.
 
 ```bash
-# 安装或更新
+npx -y @kairyou/agent-tools@latest usage -a claude
 npx -y @kairyou/agent-tools@latest usage -a codex
-
-# 预览或卸载
-npx -y @kairyou/agent-tools@latest usage -a codex --dry-run
-npx -y @kairyou/agent-tools@latest usage -a codex --uninstall
+npx -y @kairyou/agent-tools@latest usage -a opencode
 ```
 
-安装器会把 hook 添加到 `~/.codex/hooks.json` 的 `UserPromptSubmit` 和
-`Stop`. 安装后, 在 Codex 里运行 `/hooks` 并批准 agent-tools usage hooks.
+- **Claude Code** — 把 `at-usage` skill 装入 `~/.claude/skills`; 调用
+  `/at-usage` 即可在对话中显示当前用量.
+- **Codex** — 把 hook 添加到 `~/.codex/hooks.json` 的 `UserPromptSubmit` 和
+  `Stop`, 并把 `at-usage` skill 装入 `~/.agents/skills`. 安装后在 Codex 里运行
+  `/hooks` 批准一次. Hook 输出只在 Codex CLI 里显示; Paseo 等不显示 hook 输出的
+  前端, 可调用 `$at-usage` 按需查询.
+- **OpenCode** — 添加 server plugin 和 TUI plugin: session 进入 idle 后自动刷新
+  usage 并以 toast 显示, `/at-usage` 查看最新缓存值. 安装或更新后需要重启 opencode.
 
 显示效果示例:
 
 ```text
 # 订阅/套餐额度.
-warning: API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
 
 # 钱包余额.
-warning: API | balance $362 | today $61.7 | 30d $566
+API | balance $362 | today $61.7 | 30d $566
 ```
 
 字段含义: `D/W/M` 是日/周/月套餐消耗与上限, `Exp` 是套餐到期日,
 `balance` 是钱包余额, `today` / `30d` 是今日与近 30 天 API 消耗.
 
-### OpenCode
+#### 支持的网关
 
-#### Provider usage plugin
+余额, 额度和套餐用量查询支持兼容 Sub2API-like,
+NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like 与 OpenRouter 的网关.
 
-```bash
-# 安装或更新
-npx -y @kairyou/agent-tools@latest usage -a opencode
+### Vision(跨模型识图)
 
-# 预览或卸载
-npx -y @kairyou/agent-tools@latest usage -a opencode --dry-run
-npx -y @kairyou/agent-tools@latest usage -a opencode --uninstall
+让不支持图片的主模型借助多模态模型识图: 针对图片(本地路径或 http(s) URL)提出具体问题, 拿到答案后继续自己的推理. 常见场景: 读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题. 一个安装器 capability 包含三部分: `inspect_image` MCP stdio server, `at-vision` 策略 skill, 以及人工诊断 CLI.
+
+#### 安装
+
+```bash
+npx -y @kairyou/agent-tools@latest vision -a claude
+npx -y @kairyou/agent-tools@latest vision -a codex claude opencode
 ```
 
-安装器会添加全局 server plugin 和 TUI plugin. 当前 session 进入 idle 后, server
-plugin 会刷新 usage 并通过 toast 显示; TUI plugin 还会注册 `/at-usage`, 用于查看最新
-缓存值. 安装或更新 plugin 后需要重启 opencode.
+卸载默认保留 vision provider 配置. 安装器会为每个 agent 注册 `inspect_image`
+MCP server (Claude Code: `~/.claude.json`; Codex: `~/.codex/config.toml`;
+OpenCode: `opencode.json`), 并把 `at-vision` skill 装入对应 agent 的 skills 目录.
 
-显示效果示例:
+#### 配置
 
-```text
-Provider usage
-balance $244 | today $45.8 | 30d $604
+`~/.agent-tools/config.jsonc` 是唯一配置入口:
+
+```jsonc
+{
+  "vision": {
+    "provider": "openai-compatible",       // 或 "anthropic-compatible"
+    "baseUrl": "https://gateway.example.com/v1",  // anthropic-compatible 填网关根地址, 会自动拼 /v1/messages
+    "model": "internal-vlm",
+    "apiKey": { "env": "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 图片使用私有临时文件, 每次请求结束后自动删除.
 
-余额, 额度和套餐用量查询支持兼容 Sub2API-like,
-NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like 与 OpenRouter 的网关.
+#### 使用
+
+在消息里给出图片的文件路径或 URL 即可. Agent 优先调用 MCP 的 `inspect_image`; 模型网关不支持 MCP namespace tools 时, 改用已安装的本地 vision CLI. 不要直接粘贴截图: 主模型不支持图片时, 粘贴会在到达工具前就报 API 400 — 保存成文件再给路径.
+
+人工排查配置或测试识别质量时可用:
+
+```bash
+npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背景色和高度是多少"
+```
 
-### 从 Git 运行
+## 从 Git 运行
 
 如需直接使用仓库版本，可将 npm 包名替换为 `github:kairyou/agent-tools`（本机需已安装 Git）：
 

package/dist/vision/cli.mjs

@@ -1,13 +1,13 @@
-// lib/vision/cli.mjs
+// integrations/vision/lib/cli.mjs
 import fs4 from "node:fs";
 import path5 from "node:path";
 import { fileURLToPath } from "node:url";
 
-// lib/vision/inspect.mjs
+// integrations/vision/lib/inspect.mjs
 import crypto3 from "node:crypto";
 import path4 from "node:path";
 
-// lib/vision/config.mjs
+// integrations/vision/lib/config.mjs
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -871,7 +871,7 @@ var ParseErrorCode;
   ParseErrorCode2[ParseErrorCode2["InvalidCharacter"] = 16] = "InvalidCharacter";
 })(ParseErrorCode || (ParseErrorCode = {}));
 
-// lib/vision/errors.mjs
+// integrations/vision/lib/errors.mjs
 var ERROR_CODES = Object.freeze({
   CONFIG: "config_error",
   INPUT: "input_error",
@@ -899,7 +899,7 @@ function toVisionError(err, fallbackCode = ERROR_CODES.PROVIDER_HTTP) {
   return new VisionError(fallbackCode, message, { cause: err });
 }
 
-// lib/vision/config.mjs
+// integrations/vision/lib/config.mjs
 var PROVIDERS = Object.freeze(["openai-compatible", "anthropic-compatible"]);
 var CONFIG_DEFAULTS = Object.freeze({
   timeoutMs: 3e4,
@@ -1037,7 +1037,7 @@ function loadVisionConfig({ file, env = process.env } = {}) {
   };
 }
 
-// lib/vision/image-source.mjs
+// integrations/vision/lib/image-source.mjs
 import fs2 from "node:fs";
 import os2 from "node:os";
 import path2 from "node:path";
@@ -1285,7 +1285,7 @@ async function loadImageSource(source, { maxImageBytes, timeoutMs, fetchImpl } =
   throw new VisionError(ERROR_CODES.INPUT, `Unsupported image_source.type: ${JSON.stringify(source.type)}`);
 }
 
-// lib/vision/rate-limit.mjs
+// integrations/vision/lib/rate-limit.mjs
 import crypto from "node:crypto";
 import fs3 from "node:fs";
 import path3 from "node:path";
@@ -1442,7 +1442,7 @@ function createLimiter(config, now = Date.now, { stateFile = null } = {}) {
   return stateFile ? createSharedLimiter(config, now, stateFile) : createProcessLimiter(config, now);
 }
 
-// lib/vision/redact.mjs
+// integrations/vision/lib/redact.mjs
 var MASK = "***";
 function redactSecrets(text, secrets) {
   if (typeof text !== "string" || text.length === 0) return text;
@@ -1454,7 +1454,7 @@ function redactSecrets(text, secrets) {
   return out;
 }
 
-// lib/vision/providers/shared.mjs
+// integrations/vision/lib/providers/shared.mjs
 import crypto2 from "node:crypto";
 async function* encodeBase64(readable) {
   let carry = Buffer.alloc(0);
@@ -1667,7 +1667,7 @@ async function postJson({ url, headers, body, timeoutMs, fetchImpl, providerLabe
   }
 }
 
-// lib/vision/providers/anthropic-compatible.mjs
+// integrations/vision/lib/providers/anthropic-compatible.mjs
 function messagesUrl(baseUrl) {
   return baseUrl.endsWith("/v1") ? `${baseUrl}/messages` : `${baseUrl}/v1/messages`;
 }
@@ -1718,7 +1718,7 @@ async function inspectWithAnthropicCompatible({ config, image, questions, fetchI
   return normalizeAnswers(text, questions);
 }
 
-// lib/vision/providers/openai-compatible.mjs
+// integrations/vision/lib/providers/openai-compatible.mjs
 function replyText2(json) {
   const message = json?.choices?.[0]?.message;
   if (typeof message?.content === "string") return message.content;
@@ -1765,7 +1765,7 @@ async function inspectWithOpenAICompatible({ config, image, questions, fetchImpl
   return normalizeAnswers(text, questions);
 }
 
-// lib/vision/inspect.mjs
+// integrations/vision/lib/inspect.mjs
 var PROVIDER_IMPL = {
   "openai-compatible": inspectWithOpenAICompatible,
   "anthropic-compatible": inspectWithAnthropicCompatible
@@ -1849,7 +1849,7 @@ function createVisionService({ config, fetchImpl, now, limiterStateFile } = {})
   return { config: resolved, inspect };
 }
 
-// lib/vision/cli.mjs
+// integrations/vision/lib/cli.mjs
 function printHelp() {
   const lines = [];
   for (const line of fs4.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n")) {