# WorkBuddy Kimi Bridge

让 [WorkBuddy](https://workbuddy.qq.com) 通过 **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](https://moonshotai.github.io/kimi-code/) 已安装并登录
- Git for Windows（bridge-core 自动检测路径）

### 安装依赖

```bash
pip install -r requirements.txt
```

### 启动服务

```powershell
# 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
```

添加配置：
```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` | 创建任务并阻塞轮询直到完成（最常用） |

## 📄 文档

- [交付总结](dev_files/delivery_summary.md) — 完整的问题排查与修复记录
- [使用说明](USAGE.md) — 启动与调用示例
- [WorkBuddy 配置](docs/workbuddy-mcp-setup.md) — MCP 接入详细步骤

## 📜 License

MIT