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 版:
pip install codebuddy-agent-sdk
TypeScript 版:
npm install @tencent-ai/agent-sdk
3. 登录认证(二选一)
- 方式 A(推荐):已登录过 CLI 则 SDK 自动复用登录状态,无需额外配置
- 方式 B:用 API Key 认证,设置环境变量:
bash # Windows PowerShell $env:CODEBUDDY_AUTH_TOKEN = "你的token"
4. 第一个"指挥"程序
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 示例:
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. 进阶:多轮会话(派活 → 干活 → 验收闭环)
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(把提示词存成"角色")
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(强烈建议先跑通)
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 服务
codebuddy daemon start --port 8080
2. 验证服务
curl http://127.0.0.1:8080/api/v1/health
3. 认证(用请求头带密码)
# 设置密码后,所有请求都要带这两个头
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 点自动跑任务)
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. 安装
npm install -g @tencent-ai/codebuddy-code
2. 登录(首次)
启动 codebuddy 后选择登录方式(中国站 / 国际站 / 企业域),浏览器自动完成认证。
3. 常用指挥命令
# 单次派活(适合脚本调用)
codebuddy -p "执行 D:/task.md 任务单,完成后输出验收报告"
# 带初始问题启动交互模式
codebuddy "帮我读一下这个项目结构"
# 继续上次对话
codebuddy -c
# 管道输入(让外部程序喂任务)
cat task.txt | codebuddy -p "按这个内容执行"
# 指定会话续跑
codebuddy -r "会话ID" "继续完成任务单"
4. 后台 Worker 管理(长任务)
codebuddy daemon start # 启动后台进程
codebuddy ps # 查看正在执行的 Worker
codebuddy logs <pid> # 看某个任务日志
codebuddy attach <pid> # 附着到某个任务看输出
codebuddy kill <pid> # 终止某个任务
5. 脚本化指挥(Codex 角度)
# 在脚本里调用,适合被 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:
{
"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 侧就能直接调用:
# 一个简单的 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. 验证连接
codebuddy mcp list # 查看已配置的 MCP Server
codebuddy mcp test my-tools # 测试某个 Server 是否连通
最佳实践:完整的"Codex 指挥 WorkBuddy"闭环流程
┌─────────┐ 任务单文件 ┌──────────────┐ 产出文件 ┌─────────┐
│ Codex │ ──────────→ │ WorkBuddy │ ────────→ │ 验收 │
│ (规划者) │ task.md │ (执行者) │ output/ │ (Codex) │
└─────────┘ └──────────────┘ └─────────┘
↑ ↑ │
└──────────────── 打回重做 ──────────────────────────┘
- Codex 写任务单(含目标、步骤、每步提示词、验收标准)存为
task.md - 调用 WorkBuddy:
codebuddy -p "执行 D:/task.md" - WorkBuddy 执行并产出文件到工作目录
- 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

想实现哪一种,直接把这份文件下载,然后丢给AI,说按【方案X】帮我安装并调试
自己没研究明白的,请耐心等待,后续我会专门出一期教程.
