@autoagc/admin-cli

@autoagc/admin-cli 是 autoagc-a2a-server 的官方 CLI 包，安装后的命令为 autoagc-admin，用于统一访问 Agent Card、A2A JSON-RPC、管理接口，以及运维排障接口。

安装

npm install -g @autoagc/admin-cli

安装与构建

cd cli
pnpm install
pnpm build

本地运行：

autoagc-admin --help

配置

CLI 默认把配置写到 ~/.config/autoagc-cli/config.json。如果设置了 XDG_CONFIG_HOME，则会写到 $XDG_CONFIG_HOME/autoagc-cli/config.json。

当前部署优先使用 A2A_MASTER_KEY。CLI 通过 config set adminKey 持久化该值，并在请求时映射为 X-Master-Key。如果后续服务端创建了业务 API key，再使用 apiKey / --api-key。

autoagc-admin config set server http://localhost:8080
autoagc-admin config set adminKey your-master-key
autoagc-admin doctor --format pretty
autoagc-admin config list --format pretty

支持通过全局参数临时覆盖：

• --profile
• --server
• --api-key
• --admin-key
• --format json|pretty
• --output <path>
• --dry-run

常用命令

服务发现

autoagc-admin discover --format pretty
autoagc-admin agent-card show --format pretty
autoagc-admin doctor --format pretty

Raw 调用

autoagc-admin raw rpc --method tasks/get --body '{"id":"task_123"}' --admin-key your-master-key
autoagc-admin raw http --http-method GET --path /admin/api-keys --admin-key your-master-key

任务查询

autoagc-admin task get --task-id task_123 --admin-key your-master-key
autoagc-admin task wait --task-id task_123 --interval 5 --timeout 600 --admin-key your-master-key
autoagc-admin task list --state COMPLETED --page 1 --size 20 --admin-key your-master-key

管理接口

autoagc-admin admin api-keys list --admin-key your-master-key
autoagc-admin admin vendors list --admin-key your-master-key
autoagc-admin admin routing-trace get --task-id task_123 --admin-key your-master-key --format pretty
autoagc-admin admin routing-trace tail --provider sora --event-type SUBMIT_FAILURE --limit 50 --admin-key your-master-key

Ops 运维 / 排障

ops 是面向运维、故障排查和受控运维动作的命令入口；admin 保留原有管理能力。

autoagc-admin ops task get --task-id task_123 --admin-key your-master-key --format pretty

## Release

使用下面的命令可以自动执行一次 patch 版本发布：

```bash
npm run release

该脚本会按顺序执行以下动作：

• 自动把 package.json 的版本号做 patch 自增
• 执行 npm test
• 执行 npm publish --access public

注意事项：

• 该脚本不会自动执行 git commit、tag 或其他仓库操作
• 发布前需要确保本机已经登录 npm，并且账号拥有 @autoagc scope 的发布权限 autoagc-admin ops timeout trace --task-id task_123 --admin-key your-master-key --format pretty autoagc-admin ops timeout list --action image-generate --timeout-type POLLING --page 1 --size 20 --admin-key your-master-key autoagc-admin ops runtime overview --admin-key your-master-key --format pretty autoagc-admin ops runtime backlog --state WORKING --older-than-minutes 30 --type video --admin-key your-master-key autoagc-admin ops runtime anomalies --hours 24 --admin-key your-master-key --format pretty autoagc-admin ops debug response --uri s3://bucket/debug/responses/vendor/task.json --admin-key your-master-key autoagc-admin ops action consistency-check --admin-key your-master-key --dry-run --format pretty autoagc-admin ops action vendor-weight-refresh --admin-key your-master-key --dry-run --format pretty autoagc-admin ops action free-queue-submit --admin-key your-master-key --dry-run --format pretty

### Product skills

```bash
autoagc-admin skill list --format pretty

product skills 位于仓库顶层 skills/，模板位于 skill-template/。

Dry Run

写操作和底层请求支持 --dry-run 预览：

autoagc-admin admin api-keys create --name ci-bot --expire-days 7 --admin-key your-master-key --dry-run --format pretty
autoagc-admin ops action consistency-check --admin-key your-master-key --dry-run --format pretty
autoagc-admin raw rpc --method message/send --input payload.json --admin-key your-master-key --dry-run

--dry-run 只输出解析后的请求，不会真正发送网络调用。

SQL 排障

ops sql 提供只读 SQL 诊断入口，底层调用 POST /admin/sql/query，适合 CLI 做失败任务联表分析。

autoagc-admin ops sql query --sql "select id, state from a2a_tasks order by created_at desc" --limit 20 --admin-key your-master-key --format pretty
autoagc-admin ops sql query --input query.sql --timeout-ms 3000 --admin-key your-master-key --format json
autoagc-admin ops sql failed-task --task-id task_123 --admin-key your-master-key --format pretty

示例场景：

• 查询某个 task 的 task / mapping / timeout / routing 关联线索
• 查询最近 24 小时失败任务 Top N
• 查询某个 vendor 某个 model 的失败原因分布