Bridge Workspace

Bridge Workspace 是一个轻量级、去中心化的研发协同工具。它让前端侧 AI 工具通过 MCP SSE 网关读取多个固定 IP 后端的接口层代码，并以“补丁提案 + 后端人工确认”的方式安全发起跨端修改。

安装与运行方式

Bridge Workspace 是一个标准 npm 二进制 CLI 包，发布后前后端同学不需要下载源码。

远程按需运行：

npx bridge-workspace host
npx bridge-workspace gateway

包名为 bridge-workspace。

前端项目也可以安装到 devDependencies：

npm install -D bridge-workspace

然后在 package.json 中配置：

{
  "scripts": {
    "bridge:gateway": "bridge gateway"
  }
}

后端：启动 Bridge Host

在后端项目根目录运行：

npx bridge-workspace host

启动时必须输入本次允许前端 AI 访问的 include，直接回车则不启动：

请输入本次允许前端 AI 访问的 include（逗号分隔；为空则不启动）
示例：src/main/java/**/dto/**,src/main/java/**/controller/**,README.md,AGENTS.md
include >
src/main/java/com/company/order/dto/**,src/main/java/com/company/order/controller/**,README.md,AGENTS.md

默认监听 3001 端口。可通过参数覆盖：

npx bridge-workspace host --port 3001

停止服务：在前台运行的终端中，直接按下 Ctrl + C 即可优雅退出并释放监听。

也可以查看当前由 Bridge CLI 登记的本机进程和端口：

npx bridge-workspace ps

若因终端异常关闭导致 Bridge 进程残留，可运行以下命令清理所有已登记的 Bridge 进程：

npx bridge-workspace stop

也可以清理指定端口。该命令会优先停止登记在此端口的 Bridge 进程；如果没有匹配登记记录，则回退到按端口查找并清理监听进程：

npx bridge-workspace stop --port 3001
npx bridge-workspace stop --port 9999

如果要写进脚本，也可以使用参数：

npx bridge-workspace host --include "src/main/java/com/company/order/dto/**" --include "README.md"

后端 Host 提供：

• GET /file-tree：返回 .bridgeignore 过滤后的轻量文件清单，只包含 path、size、mtimeMs，不返回全文。
• GET /file-content?path=<filePath>：按需返回单个文件全文，供 MCP read_backend_file 懒加载使用。
• WebSocket /：当允许范围内的文件变化时推送 { type, path, content } 增量事件。
• POST /api/propose-change：接收前端 AI 的修改提案，但不会直接覆盖源文件。

文件过滤规则

如果后端仓库很大，推荐每次启动 bridge host 时只开放本次对接需要 AI 阅读和修改的目录或文件。日常直接在提示中粘贴一行逗号分隔内容即可：

src/main/java/com/company/order/api/**,src/main/java/com/company/order/dto/**,src/main/java/com/company/order/controller/**,README.md,AGENTS.md,.cursor/rules/**

设置 host include 后，/file-tree、/file-content、WebSocket 增量同步、modify_backend_file 都只允许这些范围内的文件。这样既减少 MCP 上下文，也能限制前端 AI 的跨端读取和修改权限。

Host 会索引两类纯文本文件。

接口代码扩展：

• .java
• .ts
• .js
• .go
• .py

后端协作指导文件：

• README.md
• AGENTS.md
• CLAUDE.md
• GEMINI.md
• SKILL.md
• .cursor/rules/**/*.md
• .claude/skills/**/*.md
• skills/**/*.md

这些指导文件会出现在 list_backend_files 中，方便 AI 在读取和修改接口代码前先理解后端仓库约束；全文仍然通过 read_backend_file 按需懒加载。

为避免大仓库请求过慢，Host 启动时会先构建一次内存索引；后续 GET /file-tree 直接返回轻量元数据快照，不再每次递归扫盘，也不一次性传输所有文件内容。文件全文只在 Cursor 调用 read_backend_file 时通过 /file-content 懒加载。

建议在后端项目根目录维护 .bridgeignore。Bridge Host 的读取顺序是：

1. 优先读取后端项目根目录的 .bridgeignore。
2. 如果没有 .bridgeignore，读取后端项目根目录的 .gitignore。
3. 如果两者都没有，使用 npm 包内置的 .bridgeignore。

推荐 .bridgeignore：

# Dependency and build output
node_modules/
dist/
build/
target/
out/
coverage/
.next/
.nuxt/
.output/
.turbo/
.cache/
tmp/
temp/

# VCS and editor metadata
.git/
.idea/
.vscode/

# Logs, archives, generated files
*.log
logs/
*.map
*.min.js
*.generated.*
generated/
*.zip
*.tar
*.gz

# Binary/media assets
*.png
*.jpg
*.jpeg
*.gif
*.webp
*.pdf
*.class
*.jar
*.war
*.ear
*.exe
*.dll
*.so
*.dylib

如果后端仓库很大，建议进一步在项目 .bridgeignore 中排除非接口目录，例如：

docs/
scripts/
test/
tests/
__tests__/
fixtures/
examples/
mock/
logs/

前端：启动 Gateway

在前端项目根目录创建 bridge.config.json：

{
  "project": "my-frontend-app",
  "all_backends": {
    "li-si-order": "192.168.1.50:3001",
    "wang-wu-pay": "192.168.1.62:3001"
  }
}

启动网关：

npx bridge-workspace gateway

启动后会在终端展示 all_backends，支持输入编号或名称多选：

请选择要连接的后端服务（可多选，逗号分隔；直接回车则不启动）：

[1] li-si-order    192.168.1.50:3001
[2] wang-wu-pay    192.168.1.62:3001

输入编号或名称，例如：1,2 或 li-si-order,wang-wu-pay >

如果直接回车，不会启动 Gateway；这样可以避免误连默认后端。

选择后端后，Gateway 会允许前端再输入本次会话 include；为空表示使用后端已经开放的范围。如果填写，则最终范围是“后端 host include ∩ 前端 gateway include”。

local 本次会话 include（可为空，表示使用后端开放范围；逗号分隔）
示例：src/main/java/**/dto/**,src/main/java/**/controller/**,README.md
include >

默认从 9999 端口启动；如果本机端口已被占用，会自动递增寻找下一个可用端口，例如 10000、10001。也可以通过参数指定起始端口：

npx bridge-workspace gateway --port 9999

Gateway 会读取 bridge.config.json，根据终端多选结果并发请求后端的 /file-tree 轻量清单，在内存中聚合出“全栈虚拟工作区”。文件内容不会在启动时全量下载，而是在 AI 调用 read_backend_file 时按需读取。

辅助 HTTP 接口：

• GET /health：网关健康检查。
• GET /backends：查看当前聚合的后端文件。
• GET /backends/:backend/files/*：读取单个聚合文件。

Cursor / MCP SSE 配置

Gateway 内嵌 MCP SSE Server：

• SSE endpoint：http://127.0.0.1:9999/mcp/sse
• Message endpoint：http://127.0.0.1:9999/mcp/messages

如果终端提示已自动切换端口，请以终端实际输出的 MCP SSE 地址为准。

向 Cursor 暴露的能力：

• Resource：bridge_backend_context，提供当前聚合的全栈上下文。
• Tool：list_backend_files，列出已同步的后端文件。
• Tool：read_backend_file(backendName, filePath)，读取指定后端的指定文件。
• Tool：search_backend_code(query, backendName?, limit?)，在已授权范围内搜索关键词并返回轻量片段。
• Tool：modify_backend_file(backendName, filePath, newContent)，向指定后端发起修改提案。

多前端 / 多后端协作

• 多个前端同学可以同时连接同一个后端 Host；后端的 bridge host 会维护多个 WebSocket 连接，并向所有连接的 Gateway 推送增量更新。
• 多个前端同学都启动 bridge gateway 且都使用 9999 端口不会互相冲突，因为 9999 是各自电脑上的 127.0.0.1:9999。
• 同一台电脑上如果要同时启动多个 Gateway，不需要手动改端口；后启动的进程会从 9999 开始自动递增到下一个可用端口，并在终端打印实际 MCP SSE 地址。
• 同一个后端收到多个前端 AI 的修改提案时，仍然只在后端终端逐个打印 diff 并等待后端人类确认，源文件不会被自动覆盖。

跨端修改安全流程

当前端 AI 调用：

modify_backend_file("li-si-order", "src/api/OrderDTO.java", "...")

实际流程是：

1. Gateway 将 { filePath, newContent } POST 到 http://<后端固定IP>:3001/api/propose-change。
2. 后端 Host 校验文件路径和 .bridgeignore 白名单。
3. 后端 Host 读取本地旧文件，和新文本生成 .bridge/patches/*.patch 临时补丁。
4. 后端终端高亮打印 Diff 预览，并提示：[Bridge] 前端 AI 申请修改 <filePath>，确认应用此改动吗？(Y/N)。
5. 只有后端人类输入 Y 后，Host 才会用 fs.writeFile 写入源文件。
6. 写入后的内容只表现为后端本地 Git 工作区的 Uncommitted Changes，Review 和提交权仍在后端人类手里。

如果输入不是 Y，源文件不会被修改，补丁文件仍保留在 .bridge/patches/ 方便审计。

覆盖确认

当前核心逻辑覆盖如下：

• 后端瘦身过滤、轻量 /file-tree、按需 /file-content、WebSocket 增量同步：已实现。
• Gateway 默认 9999 端口、读取配置、聚合默认后端：已实现。
• MCP SSE Server、list_backend_files、read_backend_file、search_backend_code、modify_backend_file：已实现。
• modify_backend_file 到后端 /api/propose-change 推送：已实现。
• 后端禁止直接覆盖、生成 patch、终端确认后写入：已实现。

验证

npm test