cli-subagent

一个通过 MCP 暴露 CLI 子代理工作流的桥接服务。 它允许 Antigravity、Claude Desktop、Codex 等宿主把任务委派给外部 CLI 工具执行。

English | 背景 | 工具列表 | 安装 | 在 Antigravity 中使用 | 其他 MCP 宿主 | 许可证

---

背景

cli-subagent 的目标是把一套轻量任务工作流通过 MCP 暴露出来，让 AI 编码助手无需手动逐条执行 shell 命令，也能完成任务拆分、委派执行和仓库校验。

典型流程：

1. 把 epic JSON 拆分成原子 task 文件。
2. 用 CLI provider 执行单个 task。
3. 审阅生成结果。
4. 自动探测并执行仓库可用的校验脚本。

服务端会严格限制在配置的工作区内读写文件。

---

工具列表

工具	说明
split_epic	将 epic JSON 拆分为原子 task 文件
run_task	将 task 委派给 Gemini、Qwen 等 CLI 模型子代理执行
validate	自动探测并执行工作区内可用的校验脚本
list_tasks	读取某个 epic 的 manifest 并返回 task 列表
read_task	读取单个 task JSON 的完整内容

---

安装

cd cli-subagent
npm install

需要 Node.js >= 20。

---

在 Antigravity 中使用

Antigravity 会从目标仓库根目录下的 .mcp.json 加载 MCP 服务。

第一步：创建 .mcp.json

{
  "mcpServers": {
    "cli-subagent": {
      "command": "node",
      "args": ["D:/dev/cli-subagent/index.mjs"],
      "env": {
        "HB_WORKSPACE": "D:/dev/your-target-repo"
      }
    }
  }
}

args 里填写 cli-subagent/index.mjs 的绝对路径。
HB_WORKSPACE 填写目标仓库的绝对路径。

如果 cli-subagent 和目标仓库位于同一级目录，部分宿主也支持相对路径：

{
  "mcpServers": {
    "cli-subagent": {
      "command": "node",
      "args": ["../cli-subagent/index.mjs"],
      "env": {
        "HB_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

第二步：开启新对话

.mcp.json 会在对话启动时读取。修改后请开启新对话，让 Antigravity 重新加载配置。

第三步：通过自然语言调用工具

例如：

把 tasks/epics/my-feature.json 拆分成 task 文件

用 gemini 执行 tasks/my-feature/my-feature-001-xxx.json

用 qwen 执行 tasks/my-feature/my-feature-001-xxx.json

检查当前仓库是否通过校验

验证是否加载成功

你可以直接问：

列出 cli-subagent 提供的工具

如果 Antigravity 能列出 split_epic、run_task、validate、list_tasks、read_task，说明集成成功。

---

其他 MCP 宿主

Codex

Codex 使用 ~/.codex/config.toml 配置 MCP 服务。

在 config.toml 中添加：

[mcp_servers.cli-subagent]
command = "node"
args = ["D:/dev/cli-subagent/index.mjs"]
env = { HB_WORKSPACE = "D:/dev/your-target-repo" }

如果 config.toml 里已经有其他 MCP 服务，直接追加一个新的 [mcp_servers.cli-subagent] 段即可：

model = "gpt-5.4"
model_reasoning_effort = "medium"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp_servers.cli-subagent]
command = "node"
args = ["D:/dev/cli-subagent/index.mjs"]
env = { HB_WORKSPACE = "D:/dev/your-target-repo" }

修改 ~/.codex/config.toml 后，重启 Codex，并在目标仓库里开启一个新的 thread。

如果 Codex 能列出 split_epic、run_task、validate、list_tasks、read_task，说明配置已经生效。

Claude Desktop

Windows 添加到 %APPDATA%\Claude\claude_desktop_config.json，
macOS 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "cli-subagent": {
      "command": "node",
      "args": ["D:/dev/cli-subagent/index.mjs"],
      "env": {
        "HB_WORKSPACE": "D:/dev/your-target-repo"
      }
    }
  }
}

保存后重启 Claude Desktop。

手动启动

HB_WORKSPACE=D:/dev/your-repo node index.mjs

---

环境变量

变量	说明	默认值
HB_WORKSPACE	目标仓库根目录的绝对路径	进程启动目录 (cwd)
GEMINI_BIN	Gemini CLI 的路径或命令名	gemini
QWEN_BIN	Qwen CLI 的路径或命令名	qwen

---

校验行为

validate 不再写死为 npm run lint 和 npm run build。

它会读取目标仓库的 package.json，自动识别包管理器，然后按以下优先级选择可用脚本：

• validate、check、lint、typecheck、test、test:ci
• build、compile

如果仓库中没有可识别的校验脚本，会返回明确错误，而不是盲目执行硬编码命令。

---

Qwen 冒烟测试

默认测试不会调用外部模型 provider。

在你已经配置好 Qwen CLI 认证后，可以用下面的方式执行真实冒烟测试：

$env:RUN_LIVE_QWEN_SMOKE=1
npm test

这个测试会验证 runTask('qwen', ...) 是否成功返回，并且确实写出了非空 artifact 文件。

---

项目结构

index.mjs                   MCP 服务入口
src/
  actions.mjs               核心业务逻辑
  adapters/
    run-gemini.mjs          Gemini CLI 适配层
    run-qwen.mjs            Qwen CLI 适配层
  lib/
    paths.mjs               工作区路径约束
    schemas.mjs             Epic / Task 结构校验
    task-io.mjs             文件读写与 prompt 构建
test/
  core.test.mjs             回归测试

---

贡献

提交规范和贡献说明见 CONTRIBUTING.md。

许可证

本项目采用 MIT License。