agent-bridge-task-ops-cli-client

通用 CLI 工具任务代理客户端：注册为指定类型实例，轮询拉取任务，调用本地 CLI 工具处理并反馈结果。

• 支持多种工具类型：codex、claude-code、qoder、hermes、opencode、gemini-cli
• 支持自定义工具命令名（如 ccp 替代 claude）
• 后台守护进程运行，带心跳机制
• 多实例按工具类型隔离，支持同时启动不同类型实例
• 任务会话按 taskId 隔离，自动同步会话元数据到后端
• 任务 payload 中若携带 skills，会在 Prompt 末尾追加技能调用说明（curl 示例），Agent 可按需通过 executeSkill 回调后端执行
• 本机控制台：启动后默认拉起一个监听随机端口的 HTTP 控制台（127.0.0.1），URL 随心跳上报到平台，平台「打开控制台」即可在新页面跳转过来查看任务历史、会话、技能模板和主日志。可用 --disableConsole 关闭

本机控制台

start 时默认会启动一个本机控制台 HTTP 服务，绑定 127.0.0.1，监听随机端口。控制台地址会：

1. 写入 PID 文件，可通过 info / list 查看
2. 随每次 registerInstance 心跳上报为 consoleUrl 字段，平台据此提供「打开控制台」入口

控制台界面（浅色 IDE 主题）提供：

• 资源管理器：左侧文件树，递归展开 workspace 内的目录，支持新建文件 / 新建目录 / 重命名 / 删除，单击文件即可在右侧编辑器中查看与编辑（⌘S 保存）；二进制文件会跳过编辑
• 任务历史：左侧底部的折叠面板，列出本工作区每个任务的日志；点击任务进入「任务详情」视图，按 web 端 compass-assets/src/agent-bridge-task-ops 中 TaskDetailView 的视觉风格展示头部状态、基本信息、Prompt 与处理记录时间线
• 欢迎页：右侧默认展示实例概览和元信息

Web 端任务详情已抽出为可复用的 React 组件 pages/TaskDetail/components/TaskDetailView.jsx，路由页面 TaskDetailPage 是其薄包装；CLI 控制台对齐了同样的视觉规范。

所有文件操作严格限定在 worker 启动时指定的 --workspace 目录内，不允许 .. 越界访问。

如果不需要控制台，可在 start 命令上加 --disableConsole。

Agent 渠道

渠道（Channel）是平台一等公民：消息派发现以渠道为入口，渠道下挂载 1..N 个 Agent 实例，由后端的 LoadBalancer 在「渠道绑定的在线实例池」中按策略选实例投递任务。

• 创建 / 编辑渠道：仅在控制台「Agent 渠道」菜单完成，CLI 不再处理订阅相关命令；只有渠道创建者或被授权的用户、部门才能修改渠道（包括挂载实例、改 LB、改权限）。
• 挂载实例：在渠道详情的「负载均衡」tab 把目标 Agent 实例挂上来，前提是你对该实例本身有授权（沿用实例 permissionConfig）。
• 负载均衡策略：内置 ROUND_ROBIN / RANDOM / WEIGHTED（按实例权重加权随机）/ ON_CALL_SCHEDULE（按 Asia/Shanghai 时区的周日值班表选当日值班实例再 RR）。
• info 命令：执行 agent-bridge-cli info --instanceId <id> 时会顺带列出当前实例已被绑定到哪些渠道（仅展示，不可编辑）。

技能调用

渠道上绑定的技能会随任务一起下发（payload.skills），CLI 会把一份可直接执行的 skill 命令示例注入 Prompt。Agent 只要跑同样的命令即可调用：

npx ali-platform-agent-bridge-cli skill \
  --taskId "${TASK_ID}" \
  --skillCode common.dingtalk_progress_notify \
  --title "任务进展" \
  --markdown "**状态**: 已完成 XXX" \
  --atMobiles 13800138000,13900139000

设计约定：

• --gatewayBaseUrl 不用传：worker 启动时已把 AGENT_BRIDGE_GATEWAY_BASE_URL 注入子进程环境变量，skill 命令会自动读取。如需覆盖可显式传 --gatewayBaseUrl。
• taskId 必填：后端据此校验技能归属的订阅，并回填用户配置（如钉钉 webhookUrl / signSecret）、实例上下文与操作人，Agent 不需要持有敏感配置。
• runtimeArgs 以扁平 --key value 表达：除保留参数（--taskId / --skillCode / --gatewayBaseUrl）外，任何 --key value 都会自动归入 runtimeArgs；值里含逗号时会拆成字符串数组（适合 atMobiles / atUserIds 等 list 字段）。
• 命令输出为 Result<AgentBridgeSkillExecuteResultDTO> 的 JSON（含 success / summary / data / errorCode / errorMessage），Agent 可据此继续决策。

安装

npm install -g agent-bridge-task-ops-cli-client

更新

npm update -g agent-bridge-task-ops-cli-client

或指定版本：

npm install -g agent-bridge-task-ops-cli-client@latest

更新后需要重启正在运行的实例：

npx agent-bridge-task-ops-cli-client stop --all
# 重新启动各实例

快速开始

下面按推荐接入顺序给出启动命令，覆盖本机常用 Agent：codex → claude code → qoder → openclaw → hermes → opencode → gemini cli。OpenClaw 由 sibling 包 ali-platform-agent-bridge-openclaw 接入，其它都通过本 CLI 启动。

# 1. Codex CLI（OpenAI Codex）
npx ali-platform-agent-bridge-cli start \
  --type codex \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId billing_codex_agent \
  --workspace ~/agent-bridge-workspaces/billing-codex \
  --instanceName "计费结算域 Codex Agent" \
  --adminUser 12345

# 2. Claude Code
npx ali-platform-agent-bridge-cli start \
  --type claude-code \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId billing_agent \
  --workspace ~/agent-bridge-workspaces/billing \
  --instanceName "计费结算域 Agent" \
  --adminUser 12345

# 3. Qoder
npx ali-platform-agent-bridge-cli start \
  --type qoder \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId code_review_agent \
  --workspace ~/agent-bridge-workspaces/review

# 4. OpenClaw（用 sibling 插件包接入，不走本 CLI）
openclaw plugins install agent-bridge-task-ops-channel-openclaw
openclaw gateway restart
# 详见 ../ali-platform-agent-bridge-openclaw/README.md，配置 channels.agent-bridge-task-ops 即可

# 5. Hermes
npx ali-platform-agent-bridge-cli start \
  --type hermes \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId hermes_agent \
  --workspace ~/agent-bridge-workspaces/hermes

# 6. opencode
npx ali-platform-agent-bridge-cli start \
  --type opencode \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId opencode_agent \
  --workspace ~/agent-bridge-workspaces/opencode

# 7. Gemini CLI
npx ali-platform-agent-bridge-cli start \
  --type gemini-cli \
  --gatewayBaseUrl https://pre-agent-bridge.alibaba-inc.com \
  --instanceId gemini_agent \
  --workspace ~/agent-bridge-workspaces/gemini

# 查看所有运行中的实例
npx ali-platform-agent-bridge-cli list

# 停止所有 codex 类型实例
npx ali-platform-agent-bridge-cli stop --type codex

# 停止所有实例
npx ali-platform-agent-bridge-cli stop --all

命令

npx agent-bridge-task-ops-cli-client start

启动一个工具实例，默认以守护进程方式后台运行。

| 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | --type | 是 | - | 工具类型：codex、claude-code、qoder、hermes、opencode、gemini-cli | | --gatewayBaseUrl | 是 | - | HSF HTTP 网关地址 | | --instanceId | 是 | - | 实例唯一标识 | | --instanceName | 否 | = instanceId | 实例显示名称 | | --instanceDescription | 否 | 空 | 实例描述 | | --adminUser | 否 | 空 | 管理员工号 | | --cmd | 否 | 工具默认命令 | 自定义工具命令名（见下表） | | --foreground | 否 | false | 前台运行（不 daemon 化，用于调试） |

npx agent-bridge-task-ops-cli-client stop

| 参数 | 说明 | |------|------| | --type <类型> | 停止指定工具类型的所有实例 | | --instanceId <ID> | 停止指定实例 | | --all | 停止所有实例 |

npx agent-bridge-task-ops-cli-client list

列出所有运行中的实例，显示工具类型、实例 ID、PID、状态和启动时间。

npx agent-bridge-task-ops-cli-client help

显示帮助信息。

支持的工具类型

| 类型 | 默认命令 | 说明 | |------|----------|------| | codex | codex | OpenAI Codex CLI，codex exec --json --full-auto 走 JSONL 事件流 | | claude-code | claude | Claude Code CLI，-p --output-format stream-json --verbose 流式日志 | | qoder | qodercli | Qoder CLI，--print --output-format stream-json --yolo 模式 | | hermes | hermes | Hermes Agent，hermes chat --json --prompt 一次性调用 | | opencode | opencode | opencode，opencode run --format json + stdin message | | gemini-cli | gemini | Gemini CLI，stdin 注入 prompt |

通过 --cmd 参数可自定义实际调用的命令，例如：

# 用 ccp 替代 claude 命令
npx agent-bridge-task-ops-cli-client start --type claude-code --cmd ccp ...

# 用 my-qoder 替代 qoder 命令
npx agent-bridge-task-ops-cli-client start --type qoder --cmd my-qoder ...

多实例运行

实例按 {type}_{instanceId} 隔离，可以同时运行多个不同类型或不同 ID 的实例：

# 同时运行两个不同业务域的 Claude Code 实例
npx agent-bridge-task-ops-cli-client start --type claude-code --instanceId billing_agent ...
npx agent-bridge-task-ops-cli-client start --type claude-code --instanceId shipping_agent ...

# 同时运行 Claude Code 和 Qoder
npx agent-bridge-task-ops-cli-client start --type claude-code --instanceId main_agent ...
npx agent-bridge-task-ops-cli-client start --type qoder --instanceId review_agent ...

# 查看所有实例
npx agent-bridge-task-ops-cli-client list
#   claude-code/billing_agent  PID=12345  运行中  cmd=claude  启动于=2026-04-11T10:00:00.000Z
#   claude-code/shipping_agent PID=12346  运行中  cmd=ccp     启动于=2026-04-11T10:01:00.000Z
#   qoder/review_agent         PID=12347  运行中  cmd=qoder   启动于=2026-04-11T10:02:00.000Z

处理流程

1. 投递任务 (HTTP / HSF / 管理界面 / 订阅触发)
       ↓
2. 进入队列 (status = pending)
       ↓
3. CLI Client 拉取任务 (状态变更为 processing)
       ↓
4. 调用本地 CLI 工具处理 (claude / qoder / gemini)
       ↓
5. 写入处理日志 + 同步元数据（会话ID、工具类型等）
       ↓
6. 反馈结果 (status → completed / failed)

评论续指令

任务完成后，用户可在控制台添加评论，CLI Client 会自动拉取并恢复之前的会话继续处理：

1. 用户添加评论 (status → comment_pending)
       ↓
2. CLI Client 拉取评论任务
       ↓
3. 恢复已有会话，传入评论内容
       ↓
4. 工具继续处理并反馈结果

任务元数据

CLI Client 处理任务时会自动将以下信息同步到后端任务元数据：

| 字段 | 说明 | |------|------| | localSessionId | 本地工具会话 ID | | toolType | 工具类型（claude-code / qoder / gemini-cli） | | toolCmd | 实际使用的命令名 | | lastActiveAt | 最后活跃时间 |

可通过 HSF 接口 getTaskMeta(taskId) 查询，或通过 updateTaskMeta(taskId, metadata) 更新。

文件位置

| 路径 | 说明 | |------|------| | ~/.agent-bridge-task-ops/pids/ | 守护进程 PID 文件 | | ~/.agent-bridge-task-ops/logs/ | 守护进程日志文件 | | ~/.agent-bridge-task-ops/sessions/ | 本地会话持久化文件 |