agent-bridge-task-ops-cli-client

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

• 支持多种工具类型：claude-code、qoder、gemini-cli
• 支持自定义工具命令名（如 ccp 替代 claude）
• 后台守护进程运行，带心跳机制
• 多实例按工具类型隔离，支持同时启动不同类型实例
• 任务会话按 taskId 隔离，自动同步会话元数据到后端
• 任务 payload 中若携带 skills，会在 Prompt 末尾追加技能调用说明（curl 示例），Agent 可按需通过 executeSkill 回调后端执行

技能调用

订阅上绑定的技能会随任务一起下发（payload.skills），CLI 会把每个技能渲染成如下调用示例注入 Prompt：

curl -X POST '${gateway}/luyou/public/gateway/executeHsf.json' \
  -H 'Content-Type: application/json' \
  -d '{
    "appName": "onetouch-logistics-operation",
    "hsfName": "com.alibaba.onetouch.logistics.compass.service.AgentBridgeTaskOpsRemoteService#executeSkill(com.alibaba.onetouch.logistics.compass.dto.agentbridge.skill.AgentBridgeSkillExecuteRequestDTO)~com.alibaba.onetouch.basedata.api.Result",
    "args": [{
      "taskId": "<当前任务 taskId，必填>",
      "skillCode": "<技能码，如 common.dingtalk_progress_notify>",
      "runtimeArgs": { /* 按技能 runtimeArgsSchema 组装 */ },
      "operator": "agent"
    }]
  }'

关键约定：

• taskId 必填：后端据此校验技能归属的订阅、回填用户侧配置（如钉钉 webhookUrl / signSecret），Agent 不需要持有敏感配置。
• skillCode 与 runtimeArgs 由任务正文的"可用技能"段落给出，请按每个技能的 usageGuide 说明组装。
• 返回 Result<AgentBridgeSkillExecuteResultDTO>，含 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
# 重新启动各实例

快速开始

# 启动一个 Claude Code 实例（后台运行）
npx agent-bridge-task-ops-cli-client start \
  --type claude-code \
  --gatewayBaseUrl https://pre-clawtask.alibaba-inc.com \
  --instanceId billing_agent \
  --instanceName "计费结算域 Agent" \
  --adminUser 12345

# 启动一个 Qoder 实例
npx agent-bridge-task-ops-cli-client start \
  --type qoder \
  --gatewayBaseUrl https://pre-clawtask.alibaba-inc.com \
  --instanceId code_review_agent

# 查看所有运行中的实例
npx agent-bridge-task-ops-cli-client list

# 停止所有 claude-code 类型实例
npx agent-bridge-task-ops-cli-client stop --type claude-code

# 停止所有实例
npx agent-bridge-task-ops-cli-client stop --all

命令

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

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

| 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | --type | 是 | - | 工具类型：claude-code、qoder、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

显示帮助信息。

支持的工具类型

| 类型 | 默认命令 | 说明 | |------|----------|------| | claude-code | claude | Claude Code CLI，支持 --resume 恢复会话，JSON 输出解析 | | qoder | qoder | Qoder CLI，支持 --session 会话和 --non-interactive 模式 | | gemini-cli | gemini | Gemini CLI，支持 --resume 恢复会话 |

通过 --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/ | 本地会话持久化文件 |