agent-tools

Agent 工具

面向 AI 编码 Agent 的安全 CLI 封装工具——GitHub、可观测性、数据库、Kubernetes、Azure 平台、Azure DevOps、日志和 OpenCode 会话。

完整文档：请阅读 README，了解完整的 API 参考、配置和凭据设置。

如何运行（重要）

通过 bun <tool-name> 运行工具（需要将 @blogic-cz/agent-tools 作为开发依赖）：

bun gh-tool pr status
bun observability-tool trace get <trace-id> --env local
bun k8s-tool pods --env test
bun db-tool sql --env local --sql "SELECT 1"

切勿运行原始的 kubectl、gh、psql、az——凭据防护机制会阻止这些命令。

旧版 agent-tools-* 二进制名称（例如 bun gh-tool）仍可使用，但建议使用简短形式。

工具概览

工具	描述	帮助
gh-tool	GitHub CLI 封装工具——PR、议题、工作流、检查、审查、合并	bun gh-tool --help
observability-tool	LGTM 封装工具——Tempo 跟踪、Loki 日志、Prometheus 指标	bun observability-tool --help
db-tool	数据库查询工具——SQL 执行、架构检查	bun db-tool --help
k8s-tool	Kubernetes 工具——通过配置解析上下文的 kubectl	bun k8s-tool --help
az-tool	Azure 平台工具——vm、webapp、storage、aks、acr（只读）	bun az-tool --help
azdo-tool	Azure DevOps 工具——管道、构建、仓库（只读）	bun azdo-tool --help
logs-tool	应用程序日志——读取本地和远程（k8s pod）日志	bun logs-tool --help
session-tool	OpenCode 会话浏览器——列出、读取、搜索会话历史	bun session-tool --help
api-tool	使用操作员签发的能力凭据的 JSON REST 客户端	api-tool request --help
api-proxy	保存上游 REST 凭据的隔离式操作员服务	api-proxy --help

工具优先级

1. CLI 工具（首选）——效率更高，不会加载上下文，并提供完整功能
2. MCP 工具（备用）——仅在没有 CLI 替代方案时使用

始终优先使用 bun gh-tool，而不是原始的 gh；优先使用 bun db-tool，而不是原始的 psql；优先使用 bun k8s-tool，而不是原始的 kubectl。这些封装工具提供安全防护、审计跟踪和项目专用配置。

一致性：命令出错时，工具会在错误响应中提供 hint、nextCommand 和 retryable 字段，帮助你从故障中恢复。命令失败时，务必检查这些字段。

快速参考

api-tool（REST 服务）

使用 api-tool request --config ./api-client.json --profile sample --path /v1/items 调用经操作员批准的 REST 配置文件。在此源码检出目录中，使用带相同标志的 bun run api-tool request。客户端配置仅包含代理源地址和调用方能力凭据。配置或运行 api-proxy 前，请阅读 REST 代理设置；其私有存储和策略需要使用独立于请求 Agent 权限范围之外的服务身份。

gh-tool（GitHub）

bun gh-tool pr status                  # View PR status for current branch
bun gh-tool pr view --pr 123           # View PR details
bun gh-tool pr checks --pr 123         # Check CI status
bun gh-tool pr checks --pr 123 --watch # Watch CI until complete
bun gh-tool pr checks-failed --pr 123  # Get failed check details
bun gh-tool pr merge --pr 123 --strategy squash --delete-branch --confirm
bun gh-tool pr threads --pr 123 --unresolved-only  # Review comments
bun gh-tool pr reply --pr 123 --comment-id 456 --body "Fixed"
bun gh-tool pr resolve --thread-id 789
bun gh-tool pr create --base test --title "feat: X" --body "Description"
bun gh-tool pr review-triage --pr 123  # Combined info, threads, checks
bun gh-tool pr reply-and-resolve --pr 123 --comment-id 456 --thread-id 789 --body "Done"

bun gh-tool workflow list                              # List recent workflow runs
bun gh-tool workflow view --run 123                    # View run details with jobs/steps
bun gh-tool workflow watch --run 123                   # Block until run completes (NO sleep-polling!)
bun gh-tool workflow logs --run 123                    # Fetch logs (failed jobs by default)
bun gh-tool workflow job-logs --run 123 --job "build"  # Clean parsed logs for specific job
bun gh-tool workflow rerun --run 123                   # Rerun failed jobs
bun gh-tool workflow cancel --run 123                  # Cancel in-progress run

切勿使用 sleep N && workflow list/jobs/view——请改用 workflow watch --run N。凭据防护机制会阻止使用 agent-tools 命令进行 sleep 轮询。

bun gh-tool issue list --state open --limit 30
bun gh-tool issue view --issue 123
bun gh-tool issue close --issue 123 --reason completed --comment "Done"
bun gh-tool issue reopen --issue 123
bun gh-tool issue comment --issue 123 --body "text"
bun gh-tool issue edit --issue 123 --title "New title" --add-labels bug
bun gh-tool issue triage --issue 123 --verbosity full --format json

observability-tool（LGTM）

bun observability-tool trace get 0b7bdf0dde1c55458364ba5588a8075e --env local
bun observability-tool trace logs 0b7bdf0dde1c55458364ba5588a8075e --env local --limit 100
bun observability-tool metrics query 'up' --env local --start now-1h --end now --step 60

db-tool（数据库）

bun db-tool sql --env local --sql "SELECT * FROM users LIMIT 5"
bun db-tool sql --env test --sql "SELECT count(*) FROM organizations"
bun db-tool schema --env local --mode tables          # List tables
bun db-tool schema --env local --mode columns --table users # Show table schema

环境可以是任意字符串（例如 local、test、prod）。在配置中设置 defaultEnvironment，即可在每次调用时省略 --env。

数据库前置条件可以在配置文件级别设置（database.default.vpn），也可以在环境级别设置（database.default.environments.prod.vpn）。环境的 vpn/prerequisites 会替换配置文件级前置条件；prerequisites: [] 会禁用继承。DB 命令会先尝试直接访问，再连接 VPN 前置条件。

k8s-tool（Kubernetes）

bun k8s-tool kubectl --env test --cmd "get pods -n test-ns"
bun k8s-tool kubectl --env prod --cmd "logs <pod> --tail=100"
bun k8s-tool kubectl --env test --cmd "describe pod <pod>"
bun k8s-tool pods --env test                     # List pods
bun k8s-tool logs --pod <pod> --env test --tail 50 # Fetch logs
bun k8s-tool describe --resource pod --name <pod> --env test
bun k8s-tool exec --pod <pod> --exec-cmd "ls -la" --env test
bun k8s-tool top --env test                      # Show resource usage

az-tool（Azure Platform）

bun az-tool subscription                       # Which subscription am I pinned to?
bun az-tool groups                             # List resource groups
bun az-tool resources --group my-rg            # List resources in a group
bun az-tool cmd --cmd "vm list"
bun az-tool cmd --cmd "webapp show --name my-app --resource-group my-rg"
bun az-tool cmd --cmd "acr repository list --name my-registry"

只读。订阅由 azurePlatform 配置文件固定指定 — 不接受 --subscription。会阻止修改操作、未知操作、凭据读取 （keyvault secret show、storage account keys list、get-access-token）以及 shell 语法；允许读取元数据，例如 keyvault secret list。以 prod/production 为键的配置文件必须显式传入 --profile。如需了解完整的安全模型，请加载 az-tool 技能。

azdo-tool（Azure DevOps）

bun azdo-tool cmd --cmd "pipelines list"
bun azdo-tool cmd --cmd "pipelines show --id 123"
bun azdo-tool cmd --cmd "pipelines runs list --top 5"
bun azdo-tool cmd --cmd "pipelines runs show --id 456"
bun azdo-tool build summary --build-id 456      # Job status & duration
bun azdo-tool build timeline --build-id 456     # Full event timeline
bun azdo-tool build failed-jobs --build-id 456   # Just failures
bun azdo-tool build logs --build-id 456          # List available logs
bun azdo-tool build log-content --build-id 456 --log-id 78

logs-tool（应用日志）

bun logs-tool list --env local          # List available log files
bun logs-tool read --env local --file app.log  # Read specific log
bun logs-tool read --env test --file app.log --tail 50

session-tool（OpenCode 会话）

bun session-tool list                   # List recent sessions
bun session-tool read --session <session-id> # Read session messages
bun session-tool search "query"         # Search across sessions

配置

从当前工作目录开始逐级向上查找 agent-tools.json5（或 agent-tools.json）并加载配置。

查看完整配置参考：https://github.com/blogic-cz/agent-tools#configuration

defaultEnvironment

在配置文件根目录设置 defaultEnvironment: "test"，即可在每条命令中省略 --env test。为确保安全，如果工具检测到隐式访问 prod，会明确报错。

凭据防护

防护机制会阻止 Agent 访问敏感文件并泄露密钥。通过 agent-tools.json5 中的 credentialGuard 部分进行配置。

阻止的操作：

• 读取密钥文件（.env、.pem、.key、.ssh/ 等）
• 写入包含检测到的密钥的内容（API 密钥、令牌、密码）
• 危险的 shell 模式（printenv、cat .env 等）
• 直接使用 CLI（gh、kubectl、psql、az）——必须使用封装工具

身份验证

每种工具都有自己的身份验证方式——没有统一的令牌存储：

工具	身份验证
gh-tool	gh auth login 或 GITHUB_TOKEN 环境变量
observability-tool	配置中的 Grafana URL，以及来自 tokenEnvVar 的可选令牌
k8s-tool	现有的 kubectl 上下文（kubeconfig）
az-tool	az login 会话
azdo-tool	az login 会话
db-tool	配置中由 passwordEnvVar 定义的环境变量
logs-tool	无需身份验证 — 本地文件，或通过 k8s-tool 远程访问
api-tool	调用方能力及客户端配置中的代理 HTTPS 来源
api-proxy	受保护的操作员凭据存储，使用独立的服务身份