@kairyou/agent-tools 0.1.0 → 0.2.0

package/README.md

@@ -12,40 +12,129 @@ agent-tools/
 ├── .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.
 ├── skills/            # Reusable Agent Skills for CLI discovery and plugin manifests.
-│   └── 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.
+│   ├── 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.
 ├── statusline/        # Statusline scripts/templates, grouped by agent.
 │   └── claude/        # Claude command-backed statusLine script + example config.
 └── lib/               # Shared implementation used by hooks, statuslines, and installers.
 ```
 
-## Current Skills
+## Skills
 
-- `at-commit`: Generate a Conventional Commits message from staged changes and wait for user confirmation before committing.
-- `at-review`: Review changes for correctness bugs, regressions, convention violations, and high-value cleanup findings.
-- `at-simplify`: Refactor changes to reduce duplication, lower complexity, and improve code quality.
-
-## Usage
-
-List available skills:
+### Install
 
 ```bash
+# List available skills
 npx -y skills@latest add kairyou/agent-tools --list
+
+# Install globally (pass one or more names after --skill)
+npx -y skills@latest add kairyou/agent-tools --skill <name...> -g -y
 ```
 
-Install skills globally:
+### at-commit
+
+Generate a Conventional Commits message from staged changes and wait for user confirmation before committing.
 
 ```bash
 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)
+
+### at-review
+
+Review changes for correctness bugs, regressions, convention violations, and high-value cleanup findings.
+
+```bash
 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
+
+### at-simplify
+
+Refactor changes to reduce duplication, lower complexity, and improve code quality.
+
+```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 ```
 
-Pass multiple skills after `--skill`, for example `--skill at-commit at-review at-simplify`.
+- Usage: `/at-simplify [<pr|branch|path>]`
+
+### at-zentao
+
+Work ZenTao (禅道) bugs/tasks end to end: fix, verify, stage; asks before committing and before writing status back.
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
+```
+
+Usage:
+
+- `/at-zentao bugs` — list bugs assigned to you (the configured account); pick one or several (several = batch mode)
+- `/at-zentao tasks` — same, for tasks
+- `/at-zentao bug <id>` — work a specific bug
+- `/at-zentao task <id>` — work a specific task
+
+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
+
+### 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:
+
+```bash
+npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "What are the navbar background color and height?"
+```
 
 ## Runtime integrations
 
@@ -55,11 +144,11 @@ Pass multiple skills after `--skill`, for example `--skill at-commit at-review a
 
 ```bash
 # Install or update
-npx -y github:kairyou/agent-tools statusline -a claude
+npx -y @kairyou/agent-tools@latest statusline -a claude
 
 # Preview or uninstall
-npx -y github:kairyou/agent-tools statusline -a claude --dry-run
-npx -y github:kairyou/agent-tools statusline -a claude --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
@@ -82,11 +171,11 @@ it preserves top-of-file comments and existing values.
 
 ```bash
 # Install or update
-npx -y github:kairyou/agent-tools usage -a codex
+npx -y @kairyou/agent-tools@latest usage -a codex
 
 # Preview or uninstall
-npx -y github:kairyou/agent-tools usage -a codex --dry-run
-npx -y github:kairyou/agent-tools usage -a codex --uninstall
+npx -y @kairyou/agent-tools@latest usage -a codex --dry-run
+npx -y @kairyou/agent-tools@latest usage -a codex --uninstall
 ```
 
 The installer adds the hook to `UserPromptSubmit` and `Stop` in
@@ -112,11 +201,11 @@ the plan expiry; `balance` is wallet credit; `today` and `30d` are API spend.
 
 ```bash
 # Install or update
-npx -y github:kairyou/agent-tools usage -a opencode
+npx -y @kairyou/agent-tools@latest usage -a opencode
 
 # Preview or uninstall
-npx -y github:kairyou/agent-tools usage -a opencode --dry-run
-npx -y github:kairyou/agent-tools usage -a opencode --uninstall
+npx -y @kairyou/agent-tools@latest usage -a opencode --dry-run
+npx -y @kairyou/agent-tools@latest usage -a opencode --uninstall
 ```
 
 The installer adds global server and TUI plugins. After the active session
@@ -136,21 +225,30 @@ balance $244 | today $45.8 | 30d $604
 Balance, quota, and plan usage queries support compatible Sub2API-like,
 NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like, and OpenRouter gateways.
 
+### Run from Git
+
+To run directly from the repository, replace the npm package name with
+`github:kairyou/agent-tools` (Git required):
+
+```bash
+npx -y github:kairyou/agent-tools usage -a codex
+```
+
 ## FAQ
 
-### Why does a global install report `Failed to install 1`?
+### Why does global installation fail for PromptScript?
 
 `PromptScript does not support global skill installation` means that the
 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
+
+- [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)
+
 ## Notes
 
-- `skills/` contains reusable `SKILL.md` capabilities.
-- `hooks/` keeps stable ownership directories for shared and agent-specific integrations.
-- `plugins/` contains runtime plugin implementations such as opencode usage.
-- `statusline/claude/` contains the command-backed Claude statusLine script.
-- `lib/` contains shared implementation such as API usage query logic.
 - The installer marks and removes only the config entries it owns.
-
-Run local checks with `npm test`.
+- Run local checks with `npm test`.

package/README.zh-CN.md

@@ -10,40 +10,129 @@ agent-tools/
 ├── .codex-plugin/     # Codex plugin manifest。
 ├── hooks/             # 通用 hook 逻辑及各 agent 的适配实现。
 ├── plugins/           # 由各 agent 加载的 runtime plugins.
+│   └── vision/        # 跨模型识图(inspect_image MCP server + 内置 at-vision skill)。
 ├── scripts/           # 安装、同步、校验和仓库维护脚本。
 ├── skills/            # 可复用 Agent Skills，供 CLI 扫描和 plugin manifest 声明。
-│   └── workflow/      # 工作流类 skills。
-│       ├── at-commit/   # 生成 Conventional Commits message.
-│       ├── at-review/   # 审查改动中的 bug 与回归风险.
-│       └── at-simplify/ # 减少改动中的冗余和复杂度.
+│   ├── workflow/      # 工作流类 skills。
+│   │   ├── at-commit/   # 生成 Conventional Commits message.
+│   │   ├── at-review/   # 审查改动中的 bug 与回归风险.
+│   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
+│   └── integrations/  # 对接外部系统的 skills。
+│       └── at-zentao/   # 禅道 bug/task 修复工作流.
 ├── statusline/        # Statusline 配置片段/模板，按 agent 分组。
 │   └── claude/        # Claude command-backed statusLine 脚本和示例配置。
 └── lib/               # hooks、statusline、installer 复用的共享实现。
 ```
 
-## 当前 Skills
+## Skills
 
-- `at-commit`: 根据暂存区改动生成 Conventional Commits message, 并在提交前等待用户确认.
-- `at-review`: 审查改动中的正确性 bug, 回归风险, 约定违规和高价值清理项.
-- `at-simplify`: 重构改动, 减少冗余, 降低复杂度, 提升代码质量.
-
-## 使用方式
-
-查看可用 skills：
+### 安装
 
 ```bash
+# 查看可用 skills
 npx -y skills@latest add kairyou/agent-tools --list
+
+# 全局安装(--skill 后面可以跟一个或多个名字)
+npx -y skills@latest add kairyou/agent-tools --skill <name...> -g -y
 ```
 
-全局安装 skill：
+### at-commit
+
+根据暂存区改动生成 Conventional Commits message, 并在提交前等待用户确认.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
+```
+
+- 用法: `/at-commit [<语言>]` — 指定 commit description 的语言(Conventional Commits 语法部分保持英文)
+
+### at-review
+
+审查改动中的正确性 bug, 回归风险, 约定违规和高价值清理项.
+
+```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
+```
+
+- 用法: `/at-review [--fix] [<pr|分支|路径>]` — 输出审查结果; 加 `--fix` 则同时应用修复
+
+### at-simplify
+
+重构改动, 减少冗余, 降低复杂度, 提升代码质量.
+
+```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 ```
 
-多个 skill 可以跟在 `--skill` 后面，例如 `--skill at-commit at-review at-simplify`。
+- 用法: `/at-simplify [<pr|分支|路径>]`
+
+### at-zentao
+
+读取禅道 bug/task 并端到端处理: 修复, 验证, 暂存; 提交和回写状态前均需确认.
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
+```
+
+用法:
+
+- `/at-zentao bugs` — 列出指派给你(配置的账号)的 bug, 挑一个或多个(多个 = 批量模式)
+- `/at-zentao tasks` — 同上, 任务清单
+- `/at-zentao bug <id>` — 直接处理指定 bug
+- `/at-zentao task <id>` — 直接处理指定 task
+
+配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 首次使用会引导; `password` 自己填进文件(或设环境变量 `ZENTAO_PASSWORD`), 不要发在对话里.
+
+## Plugins
+
+### Vision(跨模型识图)
+
+让不支持图片的主模型借助多模态模型识图: 针对图片(本地路径或 http(s) URL)提出具体问题, 拿到答案后继续自己的推理. 常见场景: 读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题. 一个安装器 capability 包含三部分: `inspect_image` MCP stdio server, `at-vision` 策略 skill, 以及人工诊断 CLI.
+
+#### 安装
+
+```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
+```
+
+安装会把预构建的自包含 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 配置.
+
+#### 配置
+
+`~/.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 — 保存成文件再给路径.
+
+人工排查配置或测试识别质量时可用:
+
+```bash
+npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背景色和高度是多少"
+```
 
 ## Runtime integrations
 
@@ -53,11 +142,11 @@ npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 
 ```bash
 # 安装或更新
-npx -y github:kairyou/agent-tools statusline -a claude
+npx -y @kairyou/agent-tools@latest statusline -a claude
 
 # 预览或卸载
-npx -y github:kairyou/agent-tools statusline -a claude --dry-run
-npx -y github:kairyou/agent-tools statusline -a claude --uninstall
+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`. 默认显示:
@@ -78,11 +167,11 @@ npx -y github:kairyou/agent-tools statusline -a claude --uninstall
 
 ```bash
 # 安装或更新
-npx -y github:kairyou/agent-tools usage -a codex
+npx -y @kairyou/agent-tools@latest usage -a codex
 
 # 预览或卸载
-npx -y github:kairyou/agent-tools usage -a codex --dry-run
-npx -y github:kairyou/agent-tools usage -a codex --uninstall
+npx -y @kairyou/agent-tools@latest usage -a codex --dry-run
+npx -y @kairyou/agent-tools@latest usage -a codex --uninstall
 ```
 
 安装器会把 hook 添加到 `~/.codex/hooks.json` 的 `UserPromptSubmit` 和
@@ -107,11 +196,11 @@ warning: API | balance $362 | today $61.7 | 30d $566
 
 ```bash
 # 安装或更新
-npx -y github:kairyou/agent-tools usage -a opencode
+npx -y @kairyou/agent-tools@latest usage -a opencode
 
 # 预览或卸载
-npx -y github:kairyou/agent-tools usage -a opencode --dry-run
-npx -y github:kairyou/agent-tools usage -a opencode --uninstall
+npx -y @kairyou/agent-tools@latest usage -a opencode --dry-run
+npx -y @kairyou/agent-tools@latest usage -a opencode --uninstall
 ```
 
 安装器会添加全局 server plugin 和 TUI plugin. 当前 session 进入 idle 后, server
@@ -130,20 +219,28 @@ balance $244 | today $45.8 | 30d $604
 余额, 额度和套餐用量查询支持兼容 Sub2API-like,
 NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like 与 OpenRouter 的网关.
 
+### 从 Git 运行
+
+如需直接使用仓库版本，可将 npm 包名替换为 `github:kairyou/agent-tools`（本机需已安装 Git）：
+
+```bash
+npx -y github:kairyou/agent-tools usage -a codex
+```
+
 ## FAQ
 
-### 全局安装为什么显示 `Failed to install 1`？
+### 为什么全局安装提示 PromptScript 不支持？
 
 `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)
+
 ## 说明
 
-- `skills/` 放可复用的 `SKILL.md` 能力。项目可以只安装自己需要的 skills。
-- `hooks/` 按通用逻辑和各 agent 适配实现划分目录。
-- `plugins/` 放 opencode usage 等 runtime plugin 实现.
-- `statusline/claude/` 放 Claude command-backed statusLine 脚本。
-- `lib/` 放 API usage 查询等共享实现。
 - 安装器只标记并移除自己写入的配置项。
-
-本地检查运行 `npm test`。
+- 本地检查运行 `npm test`。