# Codex 指挥 WorkBuddy 干活 · 四种方案操作指南 > 目标:让 Codex(或你自己)像"派活老板"一样指挥 WorkBuddy(腾讯 CodeBuddy 系)执行任务,实现"派活 → 干活 → 验收"的 AI 闭环。 > 适用读者:已安装 WorkBuddy / CodeBuddy,想让它被外部 AI 或程序调用的学员。 --- ## 方案概览 | 方案 | 自动化程度 | 难度 | 适用场景 | |---|---|---|---| | 方案一:Agent SDK | 高(可编程) | ★★☆ | 写代码调用,做多 Agent 协作、批量任务 | | 方案二:HTTP API | 极高(远程/定时) | ★★★ | 无人值守、定时派活、外部系统集成 | | 方案三:CLI 命令行 | 中(手动+脚本) | ★☆☆ | 快速单次指挥,适合入门 | | 方案四:MCP 互连 | 极高(双向打通) | ★★★ | 工具间互相调用,深度集成 | --- ## 方案一:CodeBuddy Agent SDK(编程指挥) ### 1. 前置条件 - Node.js 18+ 或 Python 3.10+ - 已安装并登录 CodeBuddy CLI(`codebuddy --version` 能出结果) ### 2. 安装 SDK **Python 版:** ```bash pip install codebuddy-agent-sdk ``` **TypeScript 版:** ```bash npm install @tencent-ai/agent-sdk ``` ### 3. 登录认证(二选一) - **方式 A(推荐)**:已登录过 CLI 则 SDK 自动复用登录状态,无需额外配置 - **方式 B**:用 API Key 认证,设置环境变量: ```bash # Windows PowerShell $env:CODEBUDDY_AUTH_TOKEN = "你的token" ``` ### 4. 第一个"指挥"程序 **Python 示例(单次派活):** ```python from codebuddy_agent_sdk import query # 让 WorkBuddy 执行任务单 conversation = query({ "prompt": "请读取 D:/task.md 任务单并执行,完成后生成验收报告 task_report.md", "options": { "cwd": "D:/工作目录", # 指定工作目录 "model": "claude-4.5", # 选择模型 "allowedTools": ["Read", "Write", "Bash", "Glob", "Grep"], "maxTurns": 50, # 限制最大轮数 }, }) # 流式读取执行结果 for message in conversation: if message.type == "assistant": for block in message.message.content: if block.type == "text": print(block.text) if message.type == "result": print(f"完成,耗时 {message.duration_ms} ms") ``` **TypeScript 示例:** ```typescript import { query } from '@tencent-ai/agent-sdk'; const conversation = query({ prompt: '执行 D:/task.md 中的任务单', options: { cwd: 'D:/工作目录', maxTurns: 50 } }); for await (const message of conversation) { if (message.type === 'assistant') { const text = message.message.content .filter(c => c.type === 'text') .map(c => c.text).join(''); console.log(text); } } ``` ### 5. 进阶:多轮会话(派活 → 干活 → 验收闭环) ```python from codebuddy_agent_sdk import unstable_v2_createSession session = unstable_v2_createSession({ "model": "claude-4.5" }) # 第1轮:派活 r1 = session.send("你是执行者。执行 D:/task.md 任务单,产出文件后停下") # 第2轮:验收(Codex 视角) r2 = session.send("检查上一步产出是否满足验收标准,不满足则列出修改点") # 第3轮:修改 r3 = session.send("按验收意见修改,重新产出") ``` ### 6. 自定义 Agent(把提示词存成"角色") ```python from codebuddy_agent_sdk import query options = { "agents": { "executor": { "description": "任务执行者:照任务单干活,不自评", "prompt": "你是执行者。收到任务单后只执行,不自评,把结果写文件后停下。", "tools": ["Read", "Write", "Bash"], "model": "lite", }, "inspector": { "description": "验收官:对照标准挑毛病", "prompt": "你是验收官。对照验收标准逐项检查,输出通过/打回原因。", "tools": ["Read", "Grep", "Glob"], "model": "lite", }, } } # 派活给 executor,验收交给 inspector ``` ### 7. 官方 Demo(强烈建议先跑通) ```bash git clone https://cnb.cool/codebuddy/agent-sdk-demos.git cd agent-sdk-demos # 进入任意 demo 目录后 pip install -r requirements.txt # Python demo npx tsx quick-start.ts # TS demo ``` 重点看两个:`research-assistant`(多 Agent 协作)、`mail-assistant`(MCP 扩展)。 --- ## 方案二:HTTP API(远程 / 定时指挥) ### 1. 启动本地 HTTP 服务 ```bash codebuddy daemon start --port 8080 ``` ### 2. 验证服务 ```bash curl http://127.0.0.1:8080/api/v1/health ``` ### 3. 认证(用请求头带密码) ```bash # 设置密码后,所有请求都要带这两个头 curl -H "X-CodeBuddy-Request: 1" \ -H "Authorization: Bearer 你的密码" \ -H "Content-Type: application/json" \ -X POST http://127.0.0.1:8080/api/v1/jobs \ -d '{"prompt":"执行 D:/task.md 任务单","cwd":"D:/工作目录"}' ``` ### 4. 常用接口一览 | 用途 | 接口 | 说明 | |---|---|---| | 健康检查 | `GET /api/v1/health` | 服务是否在线 | | 发起任务 | `POST /api/v1/jobs` | 提交后台任务 | | 定时任务 | `POST /api/v1/scheduled-tasks` | 按 cron 定时派活 | | Webhook | `POST /api/v1/webhooks` | 完成任务后回调通知 | | 会话管理 | `POST /api/v1/sessions` | 多轮对话 | | ACP 流式 | `POST /api/v1/acp` | JSON-RPC over SSE 流式协议 | ### 5. 定时派活示例(每天 9 点自动跑任务) ```json POST /api/v1/scheduled-tasks { "cron": "0 9 * * *", "prompt": "执行 D:/daily-task.md,完成后写日报到 D:/output/", "cwd": "D:/工作目录" } ``` ### 6. 查看 Swagger 文档 浏览器打开 `http://127.0.0.1:8080/api/v1/swagger` 即可看到全部接口的详细说明和在线测试。 --- ## 方案三:CLI 命令行(最简单) ### 1. 安装 ```bash npm install -g @tencent-ai/codebuddy-code ``` ### 2. 登录(首次) 启动 `codebuddy` 后选择登录方式(中国站 / 国际站 / 企业域),浏览器自动完成认证。 ### 3. 常用指挥命令 ```bash # 单次派活(适合脚本调用) codebuddy -p "执行 D:/task.md 任务单,完成后输出验收报告" # 带初始问题启动交互模式 codebuddy "帮我读一下这个项目结构" # 继续上次对话 codebuddy -c # 管道输入(让外部程序喂任务) cat task.txt | codebuddy -p "按这个内容执行" # 指定会话续跑 codebuddy -r "会话ID" "继续完成任务单" ``` ### 4. 后台 Worker 管理(长任务) ```bash codebuddy daemon start # 启动后台进程 codebuddy ps # 查看正在执行的 Worker codebuddy logs # 看某个任务日志 codebuddy attach # 附着到某个任务看输出 codebuddy kill # 终止某个任务 ``` ### 5. 脚本化指挥(Codex 角度) ```bash # 在脚本里调用,适合被 Codex 等外部 AI 调起 codebuddy -p "执行 D:/task.md" --permission-mode auto ``` --- ## 方案四:MCP 互连(双向打通) ### 1. 认识 MCP MCP(Model Context Protocol)是让 AI 工具互相暴露能力的标准协议。WorkBuddy 支持: - **作为客户端**:配置外部 MCP Server,调用别人提供的工具 - **作为服务端**:把 WorkBuddy 注册成 MCP Server,让别的 AI 调它 ### 2. 配置外部 MCP Server(让 WorkBuddy 用你的工具) 编辑配置文件 `~/.codebuddy/.mcp.json`: ```json { "mcpServers": { "my-tools": { "type": "stdio", "command": "node", "args": ["./mcp-server.js"] }, "remote-api": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer your-token" } }, "sse-server": { "type": "sse", "url": "https://events.example.com/mcp/sse" } } } ``` ### 3. 让 Codex 通过 MCP 指挥 WorkBuddy 把 WorkBuddy 的能力封装成一个 MCP Server(用官方 SDK 的 MCP 支持),Codex 侧就能直接调用: ```python # 一个简单的 MCP Server 示例(暴露"执行任务"工具) from codebuddy_agent_sdk import query # 在 MCP Server 中注册 execute_task 工具 async def execute_task(prompt: str, cwd: str) -> dict: result = await query(prompt=prompt, options={"cwd": cwd}) return {"status": "done", "output": result} # 注册后,Codex 就能这样用: # 调用工具 execute_task(prompt="执行任务单", cwd="D:/work") ``` ### 4. 验证连接 ```bash codebuddy mcp list # 查看已配置的 MCP Server codebuddy mcp test my-tools # 测试某个 Server 是否连通 ``` --- ## 最佳实践:完整的"Codex 指挥 WorkBuddy"闭环流程 ``` ┌─────────┐ 任务单文件 ┌──────────────┐ 产出文件 ┌─────────┐ │ Codex │ ──────────→ │ WorkBuddy │ ────────→ │ 验收 │ │ (规划者) │ task.md │ (执行者) │ output/ │ (Codex) │ └─────────┘ └──────────────┘ └─────────┘ ↑ ↑ │ └──────────────── 打回重做 ──────────────────────────┘ ``` 1. **Codex 写任务单**(含目标、步骤、每步提示词、验收标准)存为 `task.md` 2. **调用 WorkBuddy**:`codebuddy -p "执行 D:/task.md"` 3. **WorkBuddy 执行并产出**文件到工作目录 4. **Codex 对照验收标准检查** → 通过则结束,不通过则修改任务单打回重跑 --- ## 常见问题 **Q1:SDK 报"未登录"怎么办?** 先跑 `codebuddy` 完成登录,SDK 会自动复用登录状态;或设置 `CODEBUDDY_AUTH_TOKEN` 环境变量。 **Q2:HTTP API 端口连不上?** 先确认 `codebuddy daemon status`;服务在后台运行,重启电脑后需重新 `codebuddy daemon start`。 **Q3:想让 WorkBuddy 干活时不要反复询问权限?** CLI 加 `--permission-mode auto`,或用 SDK 的 `permission_mode` 参数。注意:危险操作仍会被拦截(安全设计)。 **Q4:Codex 和 WorkBuddy 是同一台电脑吗?** 是。所有方案默认都是本地互调(127.0.0.1)。跨设备需配 HTTP API + 网络可达。 **Q5:四个方案能混用吗?** 能。推荐组合:日常手动用方案三(CLI),程序化集成用方案一(SDK),无人值守用方案二(HTTP API),深度双向集成用方案四(MCP)。 --- ## 参考资料 - SDK 文档:https://www.workbuddy.ai/docs/cli/sdk - HTTP API 文档:https://www.workbuddy.ai/docs/cli/http-api - SDK Demo 仓库:https://cnb.cool/codebuddy/agent-sdk-demos - CLI 参考:https://www.workbuddy.ai/docs/cli/cli-reference