WorkBuddy 开放平台个人开发者接入实战：从零到 Agent 应用的完整路径

摘要: 我一个人维护三个开源项目，每天花 45 分钟在项目状态同步上。接入 WorkBuddy 开放平台后，这个时间缩到了 3 分钟。这篇文章记录了我从注册 API Key 到跑通 REST API、MCP 工具扩展、企微 Webhook 通知的全过程，附带完整的 Python 代码和五个我实际踩过的坑。

一、我为什么要接入 WorkBuddy 开放平台

去年年底我同时维护三个开源项目，每个项目的 Issue、PR、文档更新都得手动跟进。我写过脚本定时拉 GitHub API 再推企微通知，但项目状态一变还是得挨个登仓库查。光是"今天有哪些新 Issue、哪些 PR 需要 Review"这件事，每天就要花 45 分钟。

更烦的是文档。每周一要把上周的技术方案从本地 Markdown 同步到腾讯文档，再把会议纪要提要点写周报，两小时就没了。

还有 AI 工具碎片化的问题——我用 AI 写代码、写文档、做数据分析，但每个场景都是独立的工具，上下文不互通，每次都要重新描述项目背景。

WorkBuddy 开放平台能同时解决这三个问题：MCP 协议连接外部系统、HTTP API 构建自动化 Agent、Webhook 打通消息通知。下面是我从零接入的过程。

---

二、WorkBuddy 开放平台长什么样

先看一眼平台的整体结构，心里有个数再动手。

WorkBuddy 开放平台提供三层接入能力：

接入方式	协议	适用场景	个人开发者友好度
REST API	HTTP 无状态请求	Webhook 集成、管理操作、简单查询	高——标准 HTTP 调用
ACP 协议	JSON-RPC over SSE	构建完整 Agent 客户端	中——需要理解 SSE 流式协议
MCP 协议	Model Context Protocol	连接外部工具和数据源	高——JSON 配置，无需编码

我的建议是先用 REST API 跑通基础流程，再用 MCP 扩展工具能力，最后搞 ACP。一步步来，别一上来就啃最难的。

---

三、拿到 API Key，把服务跑起来

接入的第一件事是搞到 API Key。WorkBuddy 有三种认证方式，个人开发者用第一种就行：

场景	认证方式	获取方式
个人开发者快速上手	API Key	平台个人设置页面获取
企业/团队集成	OAuth (apiKeyHelper)	创建应用获取 Client ID/Secret
CI/CD 已有 Token	Auth Token	直接使用已有 OAuth Token

获取 API Key

# 1. 访问平台获取 API Key
# 海外版：https://www.codebuddy.ai/profile/keys
# 中国版：https://copilot.tencent.com/profile/

# 2. 设置环境变量
export CODEBUDDY_API_KEY="your-api-key-here"

# 3. 安装 WorkBuddy CLI
npm install -g @anthropic-ai/codebuddy

# 4. 启动 HTTP 服务
codebuddy --serve --port 8080 --session-id my-session

验证服务正常

# 健康检查
curl http://127.0.0.1:8080/api/v1/health

# 预期响应
{
  "data": {
    "status": "ok",
    "uptime": 12.3,
    "platforms": ["generic", "wecom", "wechat-kf"]
  }
}

# 查看交互式 API 文档
# 浏览器访问：http://127.0.0.1:8080/api/docs

认证机制说明

这里有个坑我第一次调就踩了——WorkBuddy 的 REST API 有两层安全校验：

# 所有 API 请求必须携带自定义请求头（防 CSRF）
-H "X-CodeBuddy-Request: 1"

# 同时携带认证凭据（密码或 Token）
-H "Authorization: Bearer $PASSWORD"

首次启动时，CLI 会生成随机密码并写入 ~/.codebuddy/settings.json，同时在终端打印一条带密码的可点链接。

---

四、REST API 实战：构建自动化工作流

REST API 是最直接的玩法，标准 HTTP 调用，没什么学习成本。我用它做了一件事：定时检查 GitHub Issue 然后推企微通知。

核心 API 端点速查

方法	端点	说明
GET	/api/v1/health	健康检查
GET	/api/v1/info	服务信息（版本、OS、CWD）
GET	/api/v1/metrics	系统资源指标
GET	/api/v1/envs	环境变量
POST	/api/v1/acp/connect	建立 ACP 连接
POST	/api/v1/acp	发送对话请求
GET	/api/v1/plugins	列出已安装插件
POST	/api/v1/plugins	安装插件
GET	/api/v1/settings	列出所有配置
PUT	/api/v1/settings/:key	设置配置值
GET	/api/v1/files/read	读取文件
POST	/api/v1/files/write	写入文件
POST	/api/v1/process/start	启动进程
GET	/api/v1/webhooks/:platform	Webhook URL 验证
POST	/api/v1/webhooks/:platform	Webhook 消息入口

Python 完整示例：GitHub Issue 监控 + 企微通知

import requests
import json
import time
from datetime import datetime, timedelta

class WorkBuddyClient:
    """WorkBuddy REST API 客户端封装"""

    def __init__(self, base_url="http://127.0.0.1:8080", password=None):
        self.base_url = base_url
        self.headers = {
            "X-CodeBuddy-Request": "1",
            "Authorization": f"Bearer {password}",
            "Content-Type": "application/json"
        }

    def health_check(self):
        """健康检查"""
        resp = requests.get(
            f"{self.base_url}/api/v1/health",
            headers=self.headers
        )
        return resp.json()

    def send_prompt(self, prompt, session_id="default"):
        """通过 ACP 发送对话请求"""
        # 1. 建立连接
        connect_resp = requests.post(
            f"{self.base_url}/api/v1/acp/connect",
            headers=self.headers,
            json={"sessionId": session_id}
        )
        connection_data = connect_resp.json()
        connection_id = connection_data.get("connectionId")

        # 2. 发送 prompt
        self.headers["acp-connection-id"] = connection_id
        prompt_resp = requests.post(
            f"{self.base_url}/api/v1/acp",
            headers=self.headers,
            json={
                "jsonrpc": "2.0",
                "method": "prompt",
                "params": {"message": prompt},
                "id": 1
            }
        )
        return prompt_resp.json()

    def read_file(self, path):
        """读取远程文件"""
        resp = requests.get(
            f"{self.base_url}/api/v1/files/read",
            headers=self.headers,
            params={"path": path}
        )
        return resp.json()

    def list_plugins(self):
        """列出已安装插件"""
        resp = requests.get(
            f"{self.base_url}/api/v1/plugins",
            headers=self.headers
        )
        return resp.json()


def monitor_github_issues(repo, check_interval=300):
    """
    定时检查 GitHub Issue 并通过 WorkBuddy 处理
    :param repo: 仓库名，如 "owner/repo"
    :param check_interval: 检查间隔（秒），默认 5 分钟
    """
    client = WorkBuddyClient(password="your-password-here")
    last_check = datetime.now() - timedelta(hours=1)

    while True:
        try:
            # 拉取最近的 Issue
            github_url = f"https://api.github.com/repos/{repo}/issues"
            resp = requests.get(github_url, params={
                "since": last_check.isoformat(),
                "state": "open",
                "sort": "created",
                "direction": "desc"
            })
            issues = resp.json()

            if issues:
                # 构建摘要 prompt
                issue_list = "\n".join([
                    f"- #{i['number']} {i['title']} ({i['user']['login']})"
                    for i in issues[:5]
                ])
                prompt = (
                    f"以下是 {repo} 仓库最近的新 Issue：\n{issue_list}\n\n"
                    f"请帮我：\n"
                    f"1. 按紧急程度分类（P0/P1/P2）\n"
                    f"2. 给出每个 Issue 的一句话处理建议\n"
                    f"3. 如果有 P0 级别，生成企业微信告警消息"
                )

                result = client.send_prompt(prompt)
                print(f"[{datetime.now()}] 处理了 {len(issues)} 个新 Issue")
                print(result)

            last_check = datetime.now()
            time.sleep(check_interval)

        except Exception as e:
            print(f"[{datetime.now()}] 监控异常: {e}")
            time.sleep(60)


if __name__ == "__main__":
    monitor_github_issues("your-username/your-repo")

---

五、MCP 协议：让 AI 连接你的整个工具链

MCP（Model Context Protocol）是 WorkBuddy 里我用得最多的能力。简单说，它能让 AI 直接调用企业微信、数据库、内部系统这些外部服务，不用你自己写对接代码。

MCP 工作原理

说白了，MCP 就是一个 JSON 配置的事。你把工具的地址告诉 WorkBuddy，AI 就能自己调用，不用你写一行集成代码。

MCP 配置文件结构

WorkBuddy 支持两种配置级别：

级别	适用场景	配置文件路径
用户级	配置一次，所有项目复用	~/.workbuddy/mcp.json
项目级	仅当前项目生效	<项目目录>/.workbuddy/mcp.json

实战一：接入企业微信机器人

我第一个接入的就是企微机器人，因为通知场景最刚需。

{
  "mcpServers": {
    "wecom": {
      "command": "uvx",
      "args": ["wecom-bot-mcp-server"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

配好之后，直接用人话跟它说就行：

请通过企业微信机器人通知：正式产品已发布，请 @zhangsan 进行验收。

WorkBuddy 会自己判断该调哪个 MCP Server，然后走企微 Webhook 把消息发出去。整个过程你不用管它内部怎么路由的。

实战二：接入本地数据库

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["sqlite-mcp-server", "--db-path", "./data/app.db"]
    }
  }
}

配好之后查数据库也是用人话说：

查询最近 7 天的用户注册趋势，按天分组，输出为表格。

不用写 SQL，WorkBuddy 会自己连数据库、执行查询、格式化结果。

实战三：自定义 MCP Server（连接你的业务系统）

现成的 MCP Server 搞不定你的需求？那就自己写一个，Python 几十行代码的事。

# my_mcp_server.py
from mcp.server import Server
from mcp.types import Tool, TextContent
import json

server = Server("my-business-system")

@server.tool()
async def query_order(order_id: str) -> str:
    """查询订单详情"""
    # 这里对接你的业务系统
    order_data = {
        "order_id": order_id,
        "status": "shipped",
        "total": 299.00
    }
    return json.dumps(order_data, ensure_ascii=False)

@server.tool()
async def send_notification(user_id: str, message: str) -> str:
    """发送站内通知"""
    # 这里对接你的通知系统
    return f"已向用户 {user_id} 发送通知：{message}"

if __name__ == "__main__":
    server.run()

对应的 MCP 配置：

{
  "mcpServers": {
    "my-business": {
      "command": "python",
      "args": ["my_mcp_server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432"
      }
    }
  }
}

---

六、Webhook：把消息推到企微群里

WorkBuddy 支持三种 Webhook 平台：

平台	标识	用途
通用 Webhook	generic	自定义 HTTP 回调
企业微信	wecom	企微群机器人
微信客服	wechat-kf	微信客服消息

Webhook URL 验证

# 验证 Webhook URL 是否有效
curl http://127.0.0.1:8080/api/v1/webhooks/wecom \
  -H "X-CodeBuddy-Request: 1" \
  -H "Authorization: Bearer $PASSWORD"

企业微信 Webhook 完整接入流程

# 第一步：在企业微信群中添加群机器人，获取 Webhook URL
# 格式：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

# 第二步：配置 MCP（见第五节）

# 第三步：测试发送
curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "msgtype": "text",
    "text": {
      "content": "WorkBuddy 测试消息：Webhook 接入成功"
    }
  }'

---

七、到底省了多少时间？我算了笔账

场景量化对比

以"每日项目状态同步"为例，对比接入 WorkBuddy 前后的效率：

指标	接入前（手动）	接入后（自动化）	改善幅度
每日耗时	45 分钟	3 分钟	降低 93%
每周耗时	3.75 小时	15 分钟	降低 93%
每月耗时	15 小时	1 小时	降低 93%
人工出错率	约 5%	接近 0%	降低 100%
响应延迟	最长 4 小时	实时（< 1 分钟）	降低 99%

成本核算

按个人开发者场景计算：

成本项	金额	说明
人力成本	500 元/小时	个人开发者时间估值
每日节省时间	42 分钟	0.7 小时
每日节省成本	350 元	0.7 × 500
每月节省成本	7,700 元	22 个工作日
每年节省成本	92,400 元	12 个月

光是项目状态同步这一项，一年就能省下 9 万多块钱的时间成本。代码审查、Issue 自动分类、文档整理这些还没算进去。

---

八、我踩过的五个坑

踩坑一：403 Missing required header

现象：调用 REST API 返回 403 Missing required header。

根因：所有 API 请求（除豁免路径外）必须携带 X-CodeBuddy-Request: 1 自定义请求头。这是 WorkBuddy 的 CSRF 防护机制——自定义请求头会使浏览器跨域请求变为"非简单请求"，触发 CORS preflight 校验。

解决：

# 错误写法
requests.get("http://127.0.0.1:8080/api/v1/health")

# 正确写法
requests.get(
    "http://127.0.0.1:8080/api/v1/health",
    headers={
        "X-CodeBuddy-Request": "1",
        "Authorization": "Bearer your-password"
    }
)

踩坑二：CORS Origin not allowed

现象：前端页面调用本地 WorkBuddy 服务，浏览器控制台报 CORS 错误。

根因：WorkBuddy 的 CORS 白名单默认只允许回环地址（localhost/127.0.0.1）的同端口访问。如果你的前端 dev server 运行在 5173 端口，后端在 8321 端口，属于跨源请求。

解决：

# 启动时显式声明允许的来源
CODEBUDDY_CODE_CORS_ORIGINS=http://localhost:5173 codebuddy --serve

# 或绑定 0.0.0.0 时自动允许所有来源（仅限非回环场景）
codebuddy --serve --host 0.0.0.0

踩坑三：MCP Server 状态显示红色

现象：配置 MCP 后，界面显示红色状态，工具无法调用。

根因：常见原因包括：命令路径错误、依赖未安装、环境变量缺失、Webhook URL 格式错误。

解决：

# 1. 检查命令是否可用
which uvx  # 确认 uvx 已安装

# 2. 手动测试 MCP Server
uvx wecom-bot-mcp-server  # 看是否报错

# 3. 检查环境变量
echo $WECOM_WEBHOOK_URL  # 确认 URL 格式正确

# 4. 查看 WorkBuddy 日志
codebuddy --serve --log-level debug

踩坑四：API Key 泄露风险

现象：在共享代码仓库中硬编码了 API Key。

根因：API Key 是访问第三方模型账号的关键凭据，泄露可能导致他人使用你的配额。

解决：

# 使用环境变量管理凭据
export CODEBUDDY_API_KEY="sk-xxx"

# 或使用 .env 文件（确保已加入 .gitignore）
echo ".env" >> .gitignore

# 不再使用时清理本地存储
# 编辑 ~/.workbuddy/mcp.json，移除敏感信息

踩坑五：ACP 连接断开后未重连

现象：长时间运行的 Agent 应用，ACP 连接偶尔断开，后续请求失败。

根因：ACP 是有状态的流式协议，网络波动或服务重启会导致连接中断。

解决：

def acp_request_with_reconnect(client, prompt, max_retries=3):
    """带重连的 ACP 请求"""
    for attempt in range(max_retries):
        try:
            # 每次请求建立新连接
            connect_resp = requests.post(
                f"{client.base_url}/api/v1/acp/connect",
                headers=client.headers,
                json={"sessionId": f"session-{attempt}"}
            )
            connection_id = connect_resp.json().get("connectionId")
            client.headers["acp-connection-id"] = connection_id

            # 发送请求
            resp = requests.post(
                f"{client.base_url}/api/v1/acp",
                headers=client.headers,
                json={
                    "jsonrpc": "2.0",
                    "method": "prompt",
                    "params": {"message": prompt},
                    "id": 1
                },
                timeout=120
            )
            return resp.json()

        except (requests.exceptions.ConnectionError,
                requests.exceptions.Timeout) as e:
            print(f"连接断开，第 {attempt + 1} 次重试: {e}")
            time.sleep(2 ** attempt)

    raise Exception("重连失败，已达最大重试次数")

---

九、把它们串起来：我的个人 Agent

REST API、MCP、Webhook 这三个东西单独用都挺好，但串起来才是真正的威力。我现在每天早上 9 点自动跑一个脚本，从 GitHub 拉昨天的 commit 和新 Issue，从腾讯文档读待办，生成站会摘要，然后通过企微推到项目群。整个过程没人干预，我睡醒就能看到结果。

架构设计

快速启动模板

# personal_agent.py — 个人 Agent 启动模板
import asyncio
from workbuddy_client import WorkBuddyClient

class PersonalAgent:
    def __init__(self):
        self.client = WorkBuddyClient(
            base_url="http://127.0.0.1:8080",
            password="your-password"
        )

    async def daily_standup(self):
        """每日站会自动化"""
        # 1. 从 GitHub 拉取昨日提交
        # 2. 从腾讯文档读取待办事项
        # 3. 生成站会摘要
        prompt = """
        请帮我生成今日站会内容：
        1. 昨日完成的工作（从 GitHub commits 提取）
        2. 今日计划（从腾讯文档待办提取）
        3. 遇到的阻塞（从 open issues 提取）
        """
        result = self.client.send_prompt(prompt)

        # 4. 通过企微发送
        # MCP 会自动调用 wecom-bot-mcp-server
        self.client.send_prompt(
            f"请通过企业微信发送以下站会内容：\n{result}"
        )

    async def auto_review_pr(self, pr_url: str):
        """自动代码审查"""
        prompt = f"""
        请审查以下 PR 的代码变更：
        {pr_url}

        关注点：
        1. 是否有安全漏洞
        2. 是否有性能问题
        3. 代码风格是否一致
        4. 测试覆盖是否充分
        """
        return self.client.send_prompt(prompt)


if __name__ == "__main__":
    agent = PersonalAgent()
    asyncio.run(agent.daily_standup())

---

十、接入路上的几个建议

WorkBuddy 开放平台的接入路径其实挺清晰的，从简单到复杂一步步来就行。说几个我自己摸索出来的经验：

先跑通 REST API 再说别的。健康检查、文件读写这些基础接口调通了，认证和网络没问题了，再往上加 MCP 和 ACP。

MCP 优先级最高。一个 JSON 配置就能让 AI 连上你的企微、数据库、内部系统，性价比太高了，不用写集成代码。

通用能力配用户级，项目专属配项目级。企微通知、文档读写这些放 ~/.workbuddy/mcp.json，一次配好所有项目都能用；特定数据库、内部系统放项目目录下的 .workbuddy/mcp.json，互不干扰。

API Key 别硬编码。用环境变量，.env 加进 .gitignore，不用的凭据及时清理。

别贪多，先把一个场景跑稳。我一开始同时搞 Issue 监控、代码审查、文档同步，结果哪个都不稳定。后来退回去只跑 Issue 监控，稳了之后再加别的，反而快很多。

---

参考来源

• WorkBuddy HTTP API 文档：www.workbuddy.cn/docs/cli/ht…
• WorkBuddy MCP 使用指南：www.workbuddy.ai/docs/zh/wor…
• WorkBuddy 身份和访问管理：www.codebuddy.cn/docs/cli/ia…
• WorkBuddy Enterprise MCP 文档：cloud.tencent.com/document/pr…
• 腾讯云 MCP 市场：mcp.tencent.com

本文是 WorkBuddy 开发实战系列的第 1 篇，后续将覆盖 ACP 协议深度解析、自定义 MCP Server 开发和企业级 Agent 架构设计。