WorkBuddy Kimi Bridge

让 WorkBuddy 通过 MCP 协议 调用本地 kimi-code CLI，实现远程通过 QQ 消息控制本地 AI 执行任务。

架构：bridge-core (gRPC) → bridge-api (HTTP) → bridge-mcp-server (MCP) → WorkBuddy

---

✨ 功能特性

• 三层架构：gRPC 核心调度 + HTTP API 层 + MCP 协议适配
• 真实调度器：直接 spawn kimi-code 子进程，捕获 stdout 输出
• MCP 原生接入：WorkBuddy 自动发现 7 个工具，零配置调用
• 事件流驱动：全局事件队列，任务状态实时同步
• 跨平台：支持 Windows（自动检测 Git Bash）

🏗️ 架构

┌─────────────┐     QQ 消息      ┌──────────────┐
│   用户手机   │ ───────────────→ │  WorkBuddy   │
└─────────────┘                  └──────┬───────┘
                                        │ MCP Streamable HTTP
                                        ↓
                              ┌─────────────────────┐
                              │ bridge-mcp-server   │  port 9001
                              │  (MCP 协议适配)      │
                              └──────────┬──────────┘
                                         │ HTTP REST
                                         ↓
                              ┌─────────────────────┐
                              │    bridge-api       │  port 8742
                              │   (HTTP API 层)     │
                              └──────────┬──────────┘
                                         │ gRPC
                                         ↓
                              ┌─────────────────────┐
                              │    bridge-core      │  port 50051
                              │  (进程调度核心)      │
                              └──────────┬──────────┘
                                         │ subprocess
                                         ↓
                              ┌─────────────────────┐
                              │   kimi-code CLI     │
                              │  (本地 AI 执行)      │
                              └─────────────────────┘

🚀 快速开始

前置要求

• Python 3.12+
• kimi-code CLI 已安装并登录
• Git for Windows（bridge-core 自动检测路径）

安装依赖

pip install -r requirements.txt

启动服务

# PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\start-all.ps1

三个服务将依次启动：

服务	端口	说明
bridge-core	50051	gRPC 核心调度
bridge-api	8742	HTTP API
bridge-mcp-server	9001	MCP 服务器

WorkBuddy 配置

编辑文件：

C:\Users\<你的用户名>\.workbuddy\connectors\<connector-id>\mcp.json

添加配置：

{
  "mcpServers": {
    "kimi-bridge": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9001/mcp",
      "timeout": 300000
    }
  }
}

注意：修改后需重启 WorkBuddy 生效。

💬 使用示例

在 QQ 给 WorkBuddy 发消息：

"用 kimi 帮我写一个 Python 快速排序，保存到 C:/Users/lenovo/Documents/quicksort.py"

WorkBuddy 会自动：

1. 识别需求，调用 MCP run_task
2. bridge 创建任务 → 启动 kimi 子进程
3. kimi 执行代码生成和文件写入
4. 返回结果到 QQ

⚠️ 重要提示

文件操作必须使用绝对路径，因为 kimi-code CLI 不会自动使用子进程的工作目录。

✅ 正确：C:/Users/lenovo/Documents/project/hello.py
❌ 错误：./hello.py

📁 项目结构

.
├── bridge-core/              # gRPC 核心调度器
│   ├── server.py             # 真实子进程调度（spawn kimi CLI）
│   ├── proto/bridge.proto    # gRPC 协议定义
│   └── generated/            # 生成的 pb 文件
├── bridge_api/               # HTTP API 层（FastAPI）
│   ├── main.py               # FastAPI 应用入口
│   ├── api/                  # REST 路由
│   ├── services/             # 业务逻辑（task_service, event_processor）
│   ├── storage/              # SessionStore（内存 + 持久化）
│   └── core_client/          # gRPC 客户端
├── bridge-mcp-server.py      # MCP 服务器（FastMCP）
├── bridge-gateway/           # Next.js Web 网关（可选）
├── tests/                    # pytest 测试套件
├── dev_files/                # 设计文档与交付总结
├── docs/                     # 使用说明与配置指南
├── start-all.ps1             # 一键启动脚本
└── requirements.txt          # Python 依赖

🛠️ MCP 工具列表

工具	说明
create_task	创建任务，返回 session_id
get_task_status	查询任务状态
get_task_logs	查询任务输出日志
list_tasks	列出所有任务
stop_task	停止任务
approve_task	审批等待中的工具调用
run_task	创建任务并阻塞轮询直到完成（最常用）

📄 文档

• 交付总结 — 完整的问题排查与修复记录
• 使用说明 — 启动与调用示例
• WorkBuddy 配置 — MCP 接入详细步骤

📜 License

MIT