内容
<div align="center">
```
____ _ _ _ _
/ ___|___ __| | ___| | | (_)_ _____
| | / _ \ / _` |/ _ \ |_| | \ \ / / _ \
| |__| (_) | (_| | __/ _ | |\ V / __/
\____\___/ \__,_|\___|_| |_|_| \_/ \___|
```
### 克劳德代码的实时多人协作功能
**查看队友的改动。锁定文件。获取冲突警告。分享终端输出。**
**Git 分支感知。活动时间线。Telegram 通知。Webhook 集成。**
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org)
</div>
---
## 问题
你和你的队友都在同一个项目中使用克劳德代码。但是克劳德代码不知道其他人正在做什么。你们编辑同一个文件，覆盖彼此的工作，浪费时间在合并冲突上。
**CodeHive 解决了这个问题。**
---
## 功能概述
```
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ 你：＂谁在房间里？＂ │
│ │
│ 克劳德：房间 HIVE-A3K7XY — 3 名成员： │
│ │
│ 爱丽丝（活跃）[main] │
│ 正在编辑：src/auth.ts, src/middleware.ts │
│ 光标位置：src/auth.ts:42:10 │
│ 最后 seen：14:32:01 │
│ │
│ 鲍勃（活跃）[feature/api] │
│ 正在编辑：src/api/routes.ts │
│ 最后 seen：14:32:05 │
│ │
│ 查理（空闲） │
│ 正在编辑：未声明 │
│ 最后 seen：14:28:12 │
│ │
│ 已锁定文件： │
│ 🔒 src/config.ts (由爱丽丝锁定) │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 你：＂我的队友做了哪些改动？＂ │
│ │
│ 克劳德：最近的改动： │
│ [14:31:42] 爱丽丝改动了 src/auth.ts (+8 -2) │
│ + export function hashPassword(pwd: string): string { │
│ + return bcrypt.hashSync(pwd, 12); │
│ + } │
│ [14:32:01] 鲍勃改动了 src/api/routes.ts (+15 -0) │
│ + router.post('/login', validateBody, loginHandler); │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [!] 冲突警告 │
│ 文件＂src/auth.ts＂正在被爱丽丝和你编辑。 │
│ 协调以避免冲突。 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 工作原理
```
大局观
═══════════════════════════════════════════════════════
开发人员 A (巴黎) 开发人员 B (东京)
┌──────────────────┐ ┌──────────────────┐
│ │ │ │
│ 克劳德代码 │ │ 克劳德代码 │
│ ┌──────────┐ │ │ ┌──────────┐ │
│ │ CodeHive │ │ │ │ CodeHive │ │
│ │ MCP │ │ │ │ MCP │ │
│ │ 服务器 │ │ │ │ 服务器 │ │
│ └────┬─────┘ │ │ └────┬─────┘ │
│ │ │ │ │ │
│ ┌────┴─────┐ │ │ ┌────┴─────┐ │
│ │ 文件监视器 │ │ │ │ 文件监视器 │ │
│ └──────────┘ │ │ └──────────┘ │
│ │ │ │
└───────┬──────────┘ └───────┬──────────┘
│ │
│ WebSocket (实时) │
│ │
└──────────────┐ ┌────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌────────────────┐
│ │ │ Telegram 机器人 │
│ CodeHive 中继 │◄──────►│ (可选) │
│ (服务器) │ │ 移动通知 │
│ │ └────────────────┘
│ ┌───────────┐ │
│ │ 房间 │ │ ┌────────────────┐
│ │ HIVE-A3K7 │ │───────►│ Webhooks │
│ │ HIVE-9FMN │ │ │ Slack/Discord │
│ └───────────┘ │ └────────────────┘
│ │
│ ┌───────────┐ │
│ │ 冲突检测 │ │
│ └───────────┘ │
│ │
└─────────────────┘
云 / 本地 / VPS
```
---
## 快速开始
### 1 分钟设置（同一网络）
```bash
# 两位开发人员都运行此命令：
npm install -g codehive && codehive init
# 在克劳德代码中：
# 开发人员 A → ＂创建 CodeHive 房间＂ → 获取 HIVE-A3K7XY
# 开发人员 B → ＂加入 CodeHive 房间 HIVE-A3K7XY＂ → 连接成功！
```
### 远程团队（跨互联网）
```bash
# ── 一次性部署：部署中继服务器（选择一个） ──────────────
# 选项 A：Fly.io（免费）
cd codehive && fly launch --name my-relay && fly deploy
# 选项 B：Docker
docker run -d -p 4819:4819 ghcr.io/CodeHiveAPP/codehive-relay
# 选项 C：任意 VPS
npm install -g codehive && codehive relay --public
# ── 每个开发人员 ─────────────────────────────────────────
npm install -g codehive
codehive init --relay ws://my-relay.fly.dev:4819
# ── 在克劳德代码中 ──────────────────────────────────────────
# 开发人员 A → ＂创建 CodeHive 房间＂ → HIVE-A3K7XY
# 开发人员 B → ＂加入 CodeHive 房间 HIVE-A3K7XY＂ → 连接成功！
```
### 适用于任何现有项目
```bash
cd my-react-app # 或 Python、Rust、Go、Java，任何项目
codehive init # 添加 .mcp.json（60 字节），不修改其他内容
```
---
## 功能
### 14 种 MCP 工具 + 2 种实时资源
这些是您的 AI 编辑器（克劳德代码、Cursor、Windsurf、VS Code + Copilot）可以调用的工具：
| 工具 | 参数 | 功能 |
|------|-----------|-------------|
| `create_room` | `password?`, `is_public?`, `expires_in_hours?` | 创建一个房间，带有可选密码、公共可见性和自动过期 |
| `join_room` | `code`, `password?` | 加入一个房间，房间代码如 `HIVE-A3K7XY` |
| `leave_room` | — | 离开当前房间并停止文件监视 |
| `get_team_status` | — | 查看成员、git 分支、光标位置、打字状态、工作文件、锁定 |
| `get_recent_changes` | — | 查看队友的文件更改，带有逐行差异 |
| `send_message` | `message` | 向房间中的所有队友发送聊天消息 |
| `declare_working` | `files` (逗号分隔) | 声明正在编辑的文件 — 如果其他人也编辑，则触发冲突警报 |
| `get_notifications` | — | 查看未读消息：文件更改、聊天消息、冲突警告、锁定事件、分支警告 |
| `lock_file` | `file` | 锁定文件，以便只有您可以编辑 — 队友无法修改 |
| `unlock_file` | `file` | 解锁以前锁定的文件，允许队友再次编辑 |
| `get_timeline` | `limit?` (默认：30) | 查看时间线：加入、离开、文件更改、聊天、锁定、冲突 |
| `share_terminal` | `command`, `output`, `exit_code?` | 与队友分享终端输出（测试结果、构建日志） |
| `browse_rooms` | — | 发现中继服务器上可用的公共房间 |
| `set_webhook` | `url`, `events?` | 配置房间事件的 Webhook URL（Slack、Discord 或自定义） |
**MCP 资源**（实时可订阅数据）：
- `codehive://room/status` — 实时房间状态（成员、更改、锁定）
- `codehive://notifications` — 未读通知订阅源
### 房间功能
**密码** — 用密码保护房间。只有拥有密码的人才能加入。
```
你：＂用密码 secret123 创建一个受密码保护的房间＂
克劳德：房间 HIVE-A3K7XY 已创建！密码保护：是
邀请链接：codehive://127.0.0.1:4819/join/HIVE-A3K7XY?p=secret123
```
**公共房间** — 使房间对同一中继服务器上的其他开发人员可见。
```
你：＂创建一个公共房间＂
克劳德：房间 HIVE-B5N9QR 已创建！可见性：公共（可发现）
# 其他人可以找到它：
你：＂浏览公共 CodeHive 房间＂
克劳德：找到 2 个公共房间：
HIVE-B5N9QR — 3 名成员
创建者：爱丽丝
成员：爱丽丝，鲍勃，查理
```
**房间过期** — 房间在可配置的空闲小时数后自动删除。
```
你：＂创建一个 24 小时后过期的房间＂
克劳德：房间 HIVE-C7P2KM 已创建！过期时间：24 小时不活动后
```
**邀请链接** — 在创建房间时自动生成。
```
codehive://127.0.0.1:4819/join/HIVE-A3K7XY
codehive://my-relay.fly.dev:4819/join/HIVE-A3K7XY?p=secret123
```
### 冲突检测
```
开发人员 A 声明：＂我正在编辑 auth.ts＂
开发人员 B 声明：＂我正在编辑 auth.ts＂
│
▼
┌─────────────────────────┐
│ ⚠ 冲突警告 │
│ │
│ 文件：auth.ts │
│ 编辑者：开发人员 A，开发人员 B│
│ │
│ 协调以避免合并冲突！ │
└─────────────────────────┘
(发送给两位开发人员)
```
### 文件锁定
```
你：＂锁定 src/config.ts，以免其他人更改它＂
克劳德：已锁定 src/config.ts。只有你现在可以编辑它。使用 unlock_file 完成后。
# 如果队友尝试编辑：
# ⚠ 文件＂src/config.ts＂已被爱丽丝锁定
# 完成后：
你：＂解锁 src/config.ts＂
克劳德：已解锁 src/config.ts。队友现在可以编辑它。
```
### Git 分支感知
自动检测您的 git 分支，并在队友位于不同分支时发出警告：
```
房间 HIVE-A3K7XY — 2 名成员：
爱丽丝（活跃）[main]
正在编辑：src/auth.ts
鲍勃（活跃）[feature/api]
正在编辑：src/routes.ts
⚠ 分支警告：团队成员位于不同的分支：
爱丽丝：main，鲍勃：feature/api。协调后再合并。
```
分支每 30 秒自动刷新。
### 活动时间线
```
你：＂显示房间时间线＂
活动时间线：
+ [14:20:01] 宙斯加入了房间
+ [14:21:15] 爱丽丝加入了房间
~ [14:22:03] 宙斯更改了 src/auth.ts
# [14:23:11] 爱丽丝锁定了 src/config.ts
> [14:24:02] 宙斯：＂完成 auth 模块＂
. [14:25:30] 爱丽丝解锁了 src/config.ts
! [14:26:00] 冲突：src/api.ts 被宙斯和爱丽丝编辑
```
### 终端输出共享
```
你：＂与团队分享测试结果＂
克劳德：共享终端输出：`npm test`（1200 字符）
# 队友看到：
# [终端] 爱丽丝分享：`npm test`（退出 0）
```
### 打字指示器和光标共享
实时查看队友正在输入的内容：
```
爱丽丝正在 src/auth.ts 中输入
鲍勃的光标：src/routes.ts:42:10
```
### Webhook 通知
将房间事件发送到 Slack、Discord 或任何 HTTP 端点：
```
你：＂设置一个 Webhook 到 https://hooks.slack.com/services/xxx＂
克劳德：Webhook 配置完成：https://hooks.slack.com/services/xxx
事件：所有
# 每个房间事件都作为 JSON 发送：
{
"event": "file_change",
"room": "HIVE-A3K7XY",
"timestamp": 1706123456789,
"file": "src/auth.ts",
"author": "爱丽丝",
"type": "change"
}
```
支持的 Webhook 事件：`all`, `join`, `leave`, `chat`, `file_change`, `conflict`
### 实时文件监视
CodeHive 监视您的项目文件，并在您保存时自动通知队友：
- 检测文件添加、修改和删除
- 计算轻量级差异（仅更改的行，不包括整个文件）
- 报告二进制文件大小（图像、字体等）
- 忽略 `node_modules`、`.git`、`dist`、二进制文件、锁定文件
- 每个文件的防抖，以避免在快速保存时泛滥
### 团队聊天
```
你：＂告诉团队我完成了 auth 模块＂
克劳德：消息已发送到 HIVE-A3K7XY：＂我完成了 auth 模块＂
# 所有队友看到：
# [聊天] 爱丽丝：我完成了 auth 模块
```
---
## Telegram 机器人（可选）
通过 Telegram 在手机上监控房间并发送命令。 **100% 可选** — 如果您不配置它，所有功能仍然正常。
### 设置
```bash
# 步骤 1：在 Telegram 上创建一个机器人
# → 打开 Telegram，搜索 @BotFather
# → 发送 /newbot，遵循提示
# → 复制令牌（例如 123456:ABC-DEF1234...）
# 步骤 2：配置令牌（选择一种方法）
# 方法 A：环境变量
export CODEHIVE_TELEGRAM_TOKEN="123456:ABC-DEF1234..."
codehive telegram
# 方法 B：codehive.json
echo '{ "telegramToken": "123456:ABC-DEF1234..." }' > codehive.json
codehive telegram
# 步骤 3：在 Telegram 上向机器人发送 /start
# → 机器人将自动检测您的聊天
```
### Telegram 命令
| 命令 | 功能 |
|---------|-------------|
| `/start` | 欢迎消息 + 命令列表 |
| `/join HIVE-XXXXXX` | 加入一个房间（无密码） |
| `/join HIVE-XXXXXX mypassword` | 加入一个有密码的房间 |
| `/leave` | 离开当前房间 |
| `/status` | 显示房间成员、分支、锁定、工作文件 |
| `/chat Hello team!` | 向所有房间成员发送消息 |
| `/files` | 显示最近的文件更改和差异 |
| `/timeline` | 显示活动时间线（加入、离开、更改、锁定） |
| `/locks` | 显示当前锁定的文件 |
| `/help` | 列出所有可用命令 |
### 推送到 Telegram 的事件
当您在房间中时，机器人会向您发送实时通知：
| 事件 | Telegram 消息示例 |
|-------|------------------------|
| 成员加入 | **爱丽丝** 加入了房间 [main] |
| 成员离开 | **鲍勃** 离开了房间 |
| 文件更改 | **爱丽丝** 更改了 `src/auth.ts` (`+8 -2`) |
| 聊天消息 | **鲍勃**: "完成了 API" |
| 冲突 | **冲突警告** — `src/auth.ts` 被爱丽丝和鲍勃编辑 |
| 文件锁定 | **爱丽丝** 锁定了 `src/config.ts` |
| 文件解锁 | **爱丽丝** 解锁了 `src/config.ts` |
| 共享终端 | **爱丽丝** 共享终端（退出 0）：`npm test` |
| 分支警告 | **分支警告** — 爱丽丝：main，鲍勃：feature/api |
### 在后台运行
```bash
codehive telegram --background # 作为分离的进程运行
```
---
## 命令行参考
### `codehive init` — 设置 CodeHive
```bash
codehive init # 自动检测编辑器，启动本地中继
codehive init --relay ws://host:4819 # 使用远程中继服务器
codehive init --name "爱丽丝" # 设置您的显示名称
codehive init --port 5000 # 自定义本地中继端口
codehive init --global # 全局安装 (~/.claude.json)
codehive init --editor claude-code # 强制使用特定编辑器
codehive init --editor cursor # 支持：claude-code, cursor, windsurf, copilot
codehive init --no-auto-relay # 不自动启动本地中继
```
### `codehive relay` — 中继服务器
```bash
codehive relay # 启动中继（前台，localhost:4819）
codehive relay --public # 绑定到 0.0.0.0（从网络可访问）
codehive relay --port 5000 # 自定义端口
codehive relay --host 192.168.1.100 # 自定义主机
codehive relay --background # 在后台运行（分离）
```
### `codehive telegram` — Telegram 机器人桥接
```bash
codehive telegram # 启动 Telegram 机器人（前台）
codehive telegram --background # 在后台运行（分离）
# 需要 CODEHIVE_TELEGRAM_TOKEN 环境变量或 codehive.json 中的 telegramToken
# 从 Telegram 的 @BotFather 获取令牌：https://t.me/BotFather
```
### `codehive deploy` — 云部署指南
```bash
codehive deploy # 显示 Fly.io、Docker 和 VPS 说明
```
### `codehive status` — 检查配置
```bash
codehive status # 显示配置的编辑器 + 中继连接性
```
### `codehive doctor` — 完整诊断
```bash
codehive doctor # 检查 Node.js 版本、编辑器、中继、git
```
### `codehive uninstall` — 删除 CodeHive
```bash
codehive uninstall # 从所有编辑器中删除（项目配置）
codehive uninstall --global # 从全局配置中删除
codehive uninstall --editor cursor # 仅从特定编辑器中删除
```
---
## 兼容所有环境
CodeHive 是 **与语言无关** 和 **与框架无关** 的。它监控文件 — 它不关心文件内容。
```
┌─────────────────────────────────────────────────────────┐
│ 兼容列表 │
├─────────────────────────────────────────────────────────┤
│ │
│ AI 编辑器 语言 框架 │
│ ────────── ────────── ────────── │
│ Claude Code JavaScript React / Next.js │
│ Cursor TypeScript Vue / Nuxt │
│ Windsurf Python Angular │
│ VS Code + Copilot Rust Django / Flask │
│ Go Express / Fastify │
│ Java Spring Boot │
│ C# / .NET Rails / Laravel │
│ Swift / Kotlin 任意框架 │
│ 任意语言 任意项目 │
│ │
└─────────────────────────────────────────────────────────┘
```
### CodeHive 为您的项目添加的内容
```
your-project/
├── .mcp.json ← CodeHive 配置（60 字节，请提交此文件！）
├── codehive.json ← 可选：中继主机，开发人员名称，Telegram 令牌
├── src/ ← 不受影响
├── package.json ← 不受影响
└── ... ← 所有文件均不受影响
```
---
## 架构
```
src/
├── shared/ 所有模块共享
│ ├── types.ts 30+ TypeScript 接口（完全类型化的协议）
│ ├── protocol.ts 消息编码，常量，类型守卫
│ └── utils.ts 房间代码，去抖动，差异计算
│
├── relay/ WebSocket 中继服务器
│ ├── room.ts 房间类（成员，锁，时间线，冲突）
│ └── server.ts 服务器（路由，心跳，持久化，Webhook）
│
├── mcp/ Claude Code 集成
│ ├── client.ts WebSocket 客户端（自动重连，心跳，队列）
│ ├── tools.ts 14 个 MCP 工具 + 2 个资源
│ └── index.ts MCP 服务器入口点（stdio 传输）
│
├── watcher/ 文件系统监控
│ └── index.ts 基于 chokidar 的监视器，带有差异计算
│
├── telegram/ Telegram 机器人桥接（可选）
│ ├── bot.ts TelegramBot 类（长轮询 + 中继桥接）
│ ├── api.ts Telegram Bot API 包装器（原生 fetch，无依赖）
│ ├── formatter.ts Telegram 消息 HTML 格式化
│ └── types.ts Telegram API 类型定义
│
├── cli/ 命令行界面
│ └── index.ts 所有命令（init，relay，telegram，deploy，doctor...）
│
└── index.ts 程序化使用的公共 API
```
### 技术栈
| 组件 | 技术 | 原因 |
|-----------|-----------|-----|
| 运行时 | Node.js >= 20 | 通用，启动快，原生 fetch |
| 语言 | TypeScript 5.9（严格） | 整个协议的类型安全 |
| MCP SDK | @modelcontextprotocol/sdk 1.26 | 官方 Claude Code 集成 |
| WebSocket | ws 8.19 | 久经考验，无依赖 |
| 文件监视 | chokidar 4 | 跨平台，高性能 |
| 命令行界面 | commander 14 | 行业标准 |
| 验证 | zod 3.25 | MCP 工具的模式验证 |
| Telegram | 原生 fetch() | 无依赖，Telegram Bot API |
| 构建 | tsup 8.5 | 快速 ESM 构建，带有声明文件 |
---
## 部署
### Fly.io（免费层）
```bash
git clone https://github.com/CodeHiveAPP/codehive.git
cd codehive
fly launch --name my-codehive-relay
fly deploy
# → ws://my-codehive-relay.fly.dev:4819
```
### Docker
```bash
docker build -t codehive-relay .
docker run -d -p 4819:4819 --name codehive codehive-relay
# → ws://YOUR_SERVER_IP:4819
```
### PM2（任意 VPS）
```bash
npm install -g codehive pm2
pm2 start codehive -- relay --public
pm2 save
# → ws://YOUR_SERVER_IP:4819
```
---
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CODEHIVE_RELAY_HOST` | `127.0.0.1` | 中继服务器主机 |
| `CODEHIVE_RELAY_PORT` | `4819` | 中继服务器端口 |
| `CODEHIVE_DEV_NAME` | 系统用户名 | 房间中的显示名称 |
| `CODEHIVE_PROJECT` | 当前工作目录 | 项目根路径 |
| `CODEHIVE_HOST` | `127.0.0.1` | 中继绑定主机（服务器端） |
| `CODEHIVE_PORT` | `4819` | 中继绑定端口（服务器端） |
| `CODEHIVE_TELEGRAM_TOKEN` | — | Telegram 机器人令牌（来自 @BotFather） |
### `.mcp.json`（项目配置 — 提交此文件！)
```json
{
"mcpServers": {
"codehive": {
"command": "codehive-mcp",
"env": {
"CODEHIVE_RELAY_HOST": "my-relay.fly.dev",
"CODEHIVE_RELAY_PORT": "4819",
"CODEHIVE_DEV_NAME": "Alice"
}
}
}
}
```
此文件由 `codehive init` 自动生成。提交它 — 当队友克隆项目时，CodeHive 已预先配置。
### `codehive.json`（可选项目配置）
```json
{
"relayHost": "my-relay.fly.dev",
"relayPort": 4819,
"devName": "Alice",
"telegramToken": "123456:ABC-DEF...",
"telegramChatId": 987654321
}
```
| 字段 | 是否必填 | 描述 |
|-------|----------|-------------|
| `relayHost` | 否 | 中继服务器主机名（覆盖环境变量） |
| `relayPort` | 否 | 中继服务器端口（覆盖环境变量） |
| `devName` | 否 | 房间中的显示名称 |
| `telegramToken` | 否 | 用于移动通知的 Telegram 机器人令牌 |
| `telegramChatId` | 否 | Telegram 聊天 ID（如果省略，则从第一个 `/start` 自动检测） |
放置在项目根目录中。配置优先级：环境变量 > codehive.json > 默认值。
---
## 测试
```bash
# 运行所有测试（构建，启动中继，运行所有测试套件）
npm test
# 64 个测试：
# 29 个端到端测试 — 完整的 WebSocket 协议测试
# 13 个边缘情况测试 — 无效输入，限制，错误处理
# 22 个 Telegram 测试 — 格式化，API 包装器，命令解析
```
---
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置和指南。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
---
<div align="center">
**为共同交付的开发者而建。**
[报告 Bug](../../issues/new?template=bug_report.md) · [请求功能](../../issues/new?template=feature_request.md)
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器