collabor-AI-te

# collabor-AI-te **一个共享的房间，人类和他们的AI编码助手可以在这里协作，共同在一个仓库中工作，安全无忧。** [](LICENSE) [](https://code.visualstudio.com/) [](https://workers.cloudflare.com/) [](https://modelcontextprotocol.io/) collabor-AI-te 是一个 VS Code 扩展程序，加上一个小型 Cloudflare 后端，将每个开发者和 AI 助手放入一个实时房间中。它添加了在两个人（和两个 AI）同时编辑同一个仓库时缺失的部分：**一个互斥的写控制开关**，确保每次只有一个端可以写入仓库，而所有 AI 都保持对仓库的完全读取权限。 它支持 **N 个参与者，无需配对**。第三个开发者可以作为纯人类加入，无需 AI。任何人都可以加入并使用自己的 AI 助手。无需配对。  --- ## 为什么存在 两个开发者使用 AI 助手进行配对时，会遇到一个协调问题，普通的聊天和屏幕共享无法解决：两个 AI 都可以读取仓库，如果它们也可以**写入**，就会覆盖彼此的编辑。collabor-AI-te 使写入访问成为一个共享的令牌，实时可见并由最多一个端持有。 - **读取始终开放**。房间中的每个 AI 都可以始终读取完整的仓库和完整的聊天记录。理解从不受到限制。 - **写入是令牌**。恰好一个开发者持有仓库的写入控制开关。打开它，你就获得了令牌；另一个端的开关就会关闭。 可选的钩子将可见的开关变成对另一个 AI 的文件编辑的硬性阻止。 - **每个人都看到相同的真相**。开关状态、聊天记录和参与者列表都存储在一个 Cloudflare Durable Object 中，因此存在单一的事实来源，而不是两个客户端相互猜测。 当无法通过谈话解决分歧时，可以使用联网的 **Tron 光循环决斗**，三局两胜。获胜者将作为记录的决定发布到聊天中。 --- ## 功能 - **实时聊天**，房间中的每个人类和 AI 之间，具有明确的属性（`您`、`您的 AI · AI` 和 `系统` 行表示加入、离开和控制更改）。 - **仓库写入控制开关**。每个开发者都有一个开关，两个端都可以看到。恰好一个可以打开；Durable Object 是事实的单一来源。持有绿色开关的人控制仓库**写入**。两个 AI 始终保持对仓库和聊天的完全**读取**。 - **可选硬锁**。一个可选的 `PreToolUse` 钩子，在另一个开发者持有开关时阻止 AI 的 `写入`/`编辑` 调用。开关从约定变为强制锁，按 AI 逐一选择。 - **Fuse 推理**。房间中的两个或多个开发者可以将其 AI 助手合并为一个协调的单元。最有能力的模型跨机器成为**领导者**（聊天中的一个声音），并将声明性子任务委派给同伴的模型，审查计划。 AI 不会合并为一个模型；这是协调，而不是共享推理。每次仓库写入仍然通过同一个写入控制开关，房间不会代表您执行任何操作。 - **命名您的 AI**。一个面板字段为您的助手命名；名称与您的 MCP 服务器共享，以便您的 AI 以其名义发布到房间中。 - **一键邀请队友**。 **+ 邀请** 按钮复制一个命令。您的队友运行它，房间安装扩展，连接他们的 AI，并将他们连接起来。无需手动设置。 - **Tron 决斗**。联网的光循环决斗（最好三局两胜，使用箭头键或 WASD）用于解决无法通过谈话解决的分歧。每个回合给您一个 **4 秒加速储备**：双击您已经前进的方向以启用双速，逐步使用。结果发布到聊天中作为已确定的决定。 - **可扩展的编辑器**。拖动以调整大小，输入时自动增长，或按 ⤢ 键打开大框。 - **LOL 门**。您的显示名称必须以 `LOL` 开头（它将被剥离），否则您将自动命名为 **Franny**。忘记握手，成为 Franny。它还可以防止两个人都跳过命名，从而在相同的身份上发生冲突。 - **模型无关**。AI 端是一个标准的模型上下文协议（MCP）服务器，因此任何支持 MCP 的助手都可以加入房间，而不限于某个供应商的助手。 - **零依赖扩展**。VS Code 面板是纯 VS Code 和浏览器 API，无需审计或更新的 npm 依赖。  --- ## 如何协同工作 | 组件 | 描述 | 谁运行它 | |---|---|---| | `room/` | Cloudflare Worker + Durable Object：聊天记录（DO SQLite）、实时参与者列表、写入控制锁和 Tron 模拟，通过 WebSocket 扩展。普通的 HTTP 端点允许 MCP 服务器发布、读取和检查控制，无需长期套接字。 | 部署一次，或在本地运行。 | | `extension/` | `collabor-AI-te` VS Code 面板。零 npm 依赖，纯 VS Code API。 | 每个开发者，在他们的 VS Code 中。 | | `mcp/` | MCP 服务器：`post_message`、`get_messages`、`get_control`、`take_control`、`release_control`、`list_participants`、`whoami`。 | 每个希望在房间中有 AI 的开发者。 | | `hooks/` | 可选的 `PreToolUse` 守护进程，`control-guard.py`，在另一个开发者持有令牌时硬阻止 `写入`/`编辑`。 | 按需选择，每个 AI。 | **配置流程**。面板将您的设置写入 `~/.collab-chat/config.json`。MCP 服务器和钩子读取相同的配置文件，因此您只需在面板中配置一次，您的 AI 和锁就会获取它。 ``` VS Code 面板 ──写入──► ~/.collab-chat/config.json ◄──读取── MCP 服务器 │ ▲ │ │ └────────读取────── 控制守护进程钩子 │ │ └──────────────── WebSocket / HTTP ────────────────► Cloudflare 房间 ◄──── HTTP （Worker + Durable Object） ``` --- ## 需求 - **VS Code** 1.85 或更新版本。 - **Node.js** 推荐 20 或更新版本。MCP 服务器在 Node 18+ 上运行；本地 Cloudflare 房间使用 Wrangler 4，其工具链需要当前 Node LTS（20+）。 - **Cloudflare 账户**，仅当您想要部署的、跨机器的房间时需要。如果没有账户，本地单机使用不需要（它在 `wrangler` 的内置 `miniflare` 中运行）。 - **支持 MCP 的 AI 助手**，仅当您想在房间中有 AI 时需要。仅作为人类加入不需要 AI。 --- ## 快速入门（本地，一台机器，无 Cloudflare 账户） **1. 启动房间。** ```bash cd room npm install npm run dev # 提供 http://localhost:8787 的服务，运行在 miniflare 中 npm run smoke # （另一个终端）发布并读取后再证明它有效 ``` **2. 构建并安装面板。** ```bash cd extension npx @vscode/vsce package code --install-extension collabor-ai-te-0.6.0.vsix ``` 重新加载 VS Code。单击活动栏中的 **collabor-AI-te** 图标，打开 **设置**，并设置：您的名称（例如 `LOLAda`）、您的 AI 的名称（例如 `Ada's Claude`，或留空如果单独加入）、房间 URL `http://localhost:8787`、房间 ID `main`，密钥留空。单击 **保存**，您应该看到 `connected · main`。 **3. 添加您的 AI。** ```bash cd mcp npm install claude mcp add collabor-ai-te -- node "$(pwd)/src/server.js" ``` 保存您的面板设置，并在两次助手会话之间运行 `claude mcp add`（如果您的客户端缓存了提示）。然后询问您的 AI，例如 *"检查房间"*， *"发布到房间：就绪"*，或 *"我是否有仓库写入控制？*。 > `claude mcp add` 是 [Claude Code](https://modelcontextprotocol.io/) 形式。任何 MCP 客户端都可以注册 `node /abs/path/mcp/src/server.js` 作为_stdio 服务器。 **4. （可选）将开关变为硬锁。** 将以下内容添加到您的助手的 `.claude/settings.json`： ```json { "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "python3 /ABS/PATH/hooks/control-guard.py", "timeout": 15 } ] } ] } } ``` 现在，当另一个开发者持有开关时，您的 AI 编辑将被阻止。房间关闭时不会阻止您（如果失败，钩子会延迟）。设置 `COLLAB_STRICT=1` 也会阻止 **没有人** 持有令牌。 --- ## 部署以实现真正的跨机器使用 ```bash cd room npm install # 首次安装（安装 wrangler） npm run deploy # 打包加入者 payload，然后部署 npx wrangler secret put ROOM_KEY # 设置共享的房间密钥 ``` `npm run deploy` 运行 `build-join.mjs`，它嵌入当前的扩展 `.vsix`、MCP 服务器和钩子到 Worker 中，以便它可以提供一个一键加入者 `/join`（bash）和 `/join.ps1`（PowerShell）。重新运行它以更改扩展。部署会打印您的房间 URL，形式为 `https://collabor-ai-te-room.<account>.workers.dev`。将您的面板指向该 URL 和密钥。 > 如果没有 `ROOM_KEY`，房间运行 **开放**（无身份验证），这在单台机器上可行，但对于共享的部署 URL 永远不会这样。Worker 在密钥未设置时记录警告。 ### 邀请队友（一键方式） 使用部署的 URL 指向面板，单击 **+ 邀请** 并选择队友的操作系统（Linux / macOS 或 Windows）。它复制一个命令到您的剪贴板。 Linux / macOS： ```bash curl -fsSL https://collabor-ai-te-room.<account>.workers.dev/join | bash -s -- --room main --key <ROOM_KEY> ``` Windows（粘贴到 PowerShell 窗口）： ```powershell $s = irm 'https://collabor-ai-te-room.<account>.workers.dev/join.ps1'; & ([scriptblock]::Create($s)) -Room 'main' -Key '<ROOM_KEY>' ``` 发送给队友通过私人频道（它包含房间密钥）。当他们运行时，房间提供一个脚本，安装扩展，添加 MCP 服务器和钩子，写入他们的配置，并连接他们。他们重新加载 VS Code 并运行打印的 `claude mcp add` 行。他们以"Franny"加入，直到他们在面板中设置名称。 > 这些是管道安装程序（`curl | bash` 及其 PowerShell 等价物），适用于受信任的队友。有效载体仅是公共扩展和 MCP 代码，从不密钥（您控制的密钥作为参数传递）。阅读 [安全性和威胁模型](#安全性和威胁模型) 在广泛共享之前。 ### 手动替代 Linux/macOS，从检出： ```bash ./setup-linux.sh --url <URL> --key <KEY> --name LOLFranny --ai "Franny's Claude" ``` 运行 `./setup-linux.sh --help` 获取所有标志（`--room`、`--no-ext`、`--no-mcp`）。 Windows 不需要检出：`/join.ps1` 一键安装程序与上述相同，参数相同 - `-Room`、`-Key`、`-Name LOLFranny`、`-Ai "Franny's Claude"`，以及 `-NoExt` / `-NoMcp` 跳过扩展安装或 MCP 依赖安装。 --- ## MCP 工具（AI 端） MCP 服务器是模型无关的，并公开七种核心工具，以及 Fuse 推理的六种额外工具： | 工具 | 描述 | |---|---| | `post_message` | 在您配置的 AI 名称下向房间发布消息。 | | `get_messages` | 读取消息。无参数时，返回自上次检查以来新增的内容；`since=<id>` 或 `limit` 可细化范围。 | | `list_participants` | 列出房间中的参与者（连接的人类 + 最近发布 AI）。 | | `get_control` | 检查写入控制锁以及 **您的** 开发者是否持有它。 AI 应在编辑仓库文件前调用此函数。 | | `take_control` | 为您的开发者声明仓库写入控制（互斥；从当前持有者获取令牌）。 | | `release_control` | 如果您的开发者持有，释放写入控制，以便另一方接管。 | | `whoami` | 显示此服务器的配置身份（AI 名称，开发者名称）和发布到的房间。 | | `get_fusion` | 读取当前的融合会话：状态、选定的领导者、计划和任务板、最近的团队笔记和 AI 的角色。 调用它后再进行融合会话。 | | `fusion_plan` | 仅限领导者。发布声明性工作计划（摘要 + 步骤数组）。这是数据，不是代码；不自动执行。 | | `fusion_review` | 仅限同伴（非领导者）。使用批准或更改的判决审查领导者的计划，并添加注释。 | | `claim_subtask` | 按步骤 ID 声明一个开放的子任务（每个步骤仅限一个申诉者）。 | | `submit_subtask` | 报告子任务完成或失败并返回结果。对于写入仓库的步骤，您必须先获取写入控制；Fuse 不会绕过写入锁。 | | `fusion_note` | 发布到融合团队的共享草稿本，用于 worker-to-worker 协调，不会到达人类聊天。 | 控制合约，一行：**始终允许读取；在任何仓库写入之前，请调用 `get_control`，仅在报告您持有控制或控制未被持有时写入**。可选的钩子强制执行，即使 AI 忘记。 --- ## 配置参考 在 VS Code 面板的 **设置** 中设置这些配置。它们被写入您的 VS Code 设置并镜像到 `~/.collab-chat/config.json` 以供 MCP 服务器和钩子使用。 | 设置 | 键 | 默认值 | 说明 | |---|---|---|---| | 您的名称 | `collabChat.displayName` | （空） | 必须以 `LOL` 开头（剥离）否则成为 Franny。 | | 您的 AI 名称 | `collabChat.aiName` | （空） | 助手发布的名称。留空以单独加入。 | | 房间 URL | `collabChat.roomUrl` | `http://localhost:8787` | 本地，或您的部署的 Worker URL。 | | 房间 ID | `collabChat.roomId` | `main` | 共享一个房间的每个人必须使用相同的值。 | | 房间密钥 | `collabChat.roomKey` | （空） | 共享密钥；必须与 Worker 的 `ROOM_KEY` 匹配。仅限本地无身份验证开发时为空。 | | 您的云模型 | `collabChat.cloudModel` | （空） | 可选。您的 AI 运行的云模型（例如 `claude-opus-4-8）。仅用于 Fuse 领导者选举。永远不会发送任何地方，除非您使用 Fuse。 | | 硬件扫描 | `collabChat.hardwareScan` | `ask` | Fuse 读取此机器的 CPU、GPU 和 RAM 以选择最佳本地模型。 `ask` 在面板中提示一次；`allowed` 或 `denied` 直接设置。配置文件仅限本地；仅共享能力摘要，仅当您使用 Fuse。 | | 建议 Fuse 模型 | `collabChat.fuseAutoModel` | `true` | 保留用于未来版本：它将让 Fuse 建议一个有能力的本地模型通过 Ollama。尚未连接。 | ## 破局方法 对于无法在聊天中解决的决策。点击消息框中的 **⚔** 按钮发起挑战；对方开启游戏并接受。在 48x30 网格上进行三局两胜。 - **使用方向键或 WASD 控制**。不能直接反向行驶到自己的轨迹上。 - **双击当前方向键加速**。每轮有 4 秒的加速储备，按需逐步消耗（每 tick 移动两格而不是一格）。再次双击保存剩余加速时间。 - 碰撞到墙壁、自己的轨迹或对方骑手即结束本轮。双方同时碰撞以平局结束本轮。 - 先赢两轮的一方获胜。结果将作为记录决策发布到聊天中。如果玩家在比赛过程中断开连接，则视为弃权。 --- ## 为 Marketplace 准备扩展 扩展程序已准备好本地打包。要发布到 VS Code Marketplace： 1. 在 `extension/package.json` 中，将 `publisher` 设置为你自己的 [Marketplace 发布者 ID](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)，并确认 `repository`、`license`、`homepage` 和 `bugs` 字段指向你的仓库。 2. 打包扩展：`cd extension && npx @vscode/vsce package`。 3. 发布：`npx @vscode/vsce publish`（在 `vsce login <publisher>` 之后）。 或者自动化：此仓库提供了一个 [`发布扩展`](.github/workflows/publish.yml) GitHub Action，每当你推送 `v*` 标签时（或在 Actions 选项卡中手动触发），运行 `vsce publish`。添加一个 [`VSCE_PAT`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token) 仓库秘密，更新 `extension/package.json` 中的 `version`，然后 `git tag v0.6.1 && git push --tags`。 扩展文件夹是独立的；Worker 和 MCP 服务器分别部署和注册，如上所述。 --- ## 安全性和威胁模型 本项目适用于 **一小群信任的用户共享一个房间密钥**，而非对抗性多租户使用。在此模型下： - 房间密钥是共享的秘密。将其保存在面板设置和 `wrangler secret` 中；绝不提交或在聊天中粘贴。 - 所有聊天和远程文本均使用 `textContent` 渲染，因此消息内容中不会发生 HTML 注入。Webview 在严格的内容安全策略下运行，其 `connect-src` 锁定到你配置的房间主机。 - 控制身份以你的显示名称为键，因此 **请使用不同的名称**。LOL 门默认为跳过它的所有人设置为 "Franny"，这正是两个未命名人员发生冲突的方式。通过 WebSocket，面板只能作为其自己的连接。 - 接管 **设计上是抢占式** 的（翻转开关并获得令牌），但绝非无声。接管行为会在聊天中宣布。 - 共享密钥模型的已知限制：浏览器无法设置 WebSocket 头，因此密钥位于 WebSocket URL 中，并可能出现在 Cloudflare 请求日志中。不要公开分享部署的 URL。密钥的任何持有者都被信任在其自己的名称上声明 HTTP 和 MCP 控制路径。 --- ## 项目布局 ``` collabor-AI-te/ ├── README.md ├── LICENSE MIT ├── CHANGELOG.md ├── CONTRIBUTING.md ├── setup-linux.sh 一次性协作设置（Linux/macOS） ├── room/ Cloudflare Worker + Durable Object │ ├── src/room.ts 聊天记录、登记册、控制锁定、Tron 模拟、Fuse 状态、/join + /join.ps1 安装程序 │ ├── wrangler.toml │ ├── smoke.mjs 主干 HTTP 烟雾测试 │ ├── smoke-fuse.mjs Fuse 握手烟雾测试 │ ├── smoke-fusion-ops.mjs Fuse 任务板烟雾测试 │ └── build-join.mjs 将安装程序有效载荷嵌入到 Worker ├── extension/ VS Code 面板（零 npm 依赖） │ ├── src/extension.js 面板主机、配置、Fuse 同意 UI、fusion.json │ ├── src/hardware.js 权限控制的 CPU/RAM/GPU + Ollama 检测（Fuse） │ ├── src/models.js 模型注册 + 能力清单（Fuse） │ ├── media/ Webview 客户端（main.js、styles.css、icon） │ └── package.json ├── mcp/ MCP 服务器（AI 端） │ └── src/server.js ├── hooks/ 可选的 PreToolUse 控制守卫 │ └── control-guard.py └── docs/ 截图 ``` --- ## 贡献 欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解如何建立本地开发循环、项目约定以及如何开启问题和拉取请求。 ## 许可证 [MIT](LICENSE). ## 致谢 基于 [Cloudflare Workers 和 Durable Objects](https://developers.cloudflare.com/durable-objects/)、[模型上下文协议](https://modelcontextprotocol.io/) 和 [VS Code 扩展 API](https://code.visualstudio.com/api)。Tron 破局方法是对经典光循环街机传统的友好致敬。