bridge-workspace 0.1.0

package/.bridgeignore

@@ -0,0 +1,46 @@
+# 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

package/README.md

@@ -0,0 +1,302 @@
+# Bridge Workspace
+
+Bridge Workspace 是一个轻量级、去中心化的研发协同工具。它让前端侧 AI 工具通过 MCP SSE 网关读取多个固定 IP 后端的接口层代码，并以“补丁提案 + 后端人工确认”的方式安全发起跨端修改。
+
+## 安装与运行方式
+
+Bridge Workspace 是一个标准 npm 二进制 CLI 包，发布后前后端同学不需要下载源码。
+
+远程按需运行：
+
+```bash
+npx bridge-workspace host
+npx bridge-workspace gateway
+```
+
+包名为 `bridge-workspace`。
+
+前端项目也可以安装到 `devDependencies`：
+
+```bash
+npm install -D bridge-workspace
+```
+
+然后在 `package.json` 中配置：
+
+```json
+{
+  "scripts": {
+    "bridge:gateway": "bridge gateway"
+  }
+}
+```
+
+## 后端：启动 Bridge Host
+
+在后端项目根目录运行：
+
+```bash
+npx bridge-workspace host
+```
+
+启动时必须输入本次允许前端 AI 访问的 include，直接回车则不启动：
+
+```text
+请输入本次允许前端 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` 端口。可通过参数覆盖：
+
+```bash
+npx bridge-workspace host --port 3001
+```
+
+停止服务：在前台运行的终端中，直接按下 `Ctrl + C` 即可优雅退出并释放监听。
+
+若因终端异常关闭导致 `3001` 端口被残留占用，可运行以下命令强制一键清理：
+
+```bash
+npx bridge-workspace stop
+```
+
+也可以清理指定端口：
+
+```bash
+npx bridge-workspace stop --port 3001
+```
+
+如果要写进脚本，也可以使用参数：
+
+```bash
+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 阅读和修改的目录或文件。日常直接在提示中粘贴一行逗号分隔内容即可：
+
+```text
+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`：
+
+```gitignore
+# 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` 中排除非接口目录，例如：
+
+```gitignore
+docs/
+scripts/
+test/
+tests/
+__tests__/
+fixtures/
+examples/
+mock/
+logs/
+```
+
+## 前端：启动 Gateway
+
+在前端项目根目录创建 `bridge.config.json`：
+
+```json
+{
+  "project": "my-frontend-app",
+  "all_backends": {
+    "li-si-order": "192.168.1.50:3001",
+    "wang-wu-pay": "192.168.1.62:3001"
+  }
+}
+```
+
+启动网关：
+
+```bash
+npx bridge-workspace gateway
+```
+
+启动后会在终端展示 `all_backends`，支持输入编号或名称多选：
+
+```text
+请选择要连接的后端服务（可多选，逗号分隔；直接回车则不启动）：
+
+[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”。
+
+```text
+local 本次会话 include（可为空，表示使用后端开放范围；逗号分隔）
+示例：src/main/java/**/dto/**,src/main/java/**/controller/**,README.md
+include >
+```
+
+默认从 `9999` 端口启动；如果本机端口已被占用，会自动递增寻找下一个可用端口，例如 `10000`、`10001`。也可以通过参数指定起始端口：
+
+```bash
+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 调用：
+
+```text
+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、终端确认后写入：已实现。
+
+## 验证
+
+```bash
+npm test
+```

package/bin/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { runBackendHost } = require('../src/backend');
+const { runGateway } = require('../src/gateway');
+const { runStop } = require('../src/stop');
+
+function printHelp(output = process.stdout) {
+  output.write(`Bridge Workspace\n\n`);
+  output.write(`Usage:\n`);
+  output.write(`  bridge host [--port 3001] [--include <glob>]\n`);
+  output.write(`  bridge gateway [--port 9999]\n\n`);
+  output.write(`  bridge stop [--port 3001]\n\n`);
+  output.write(`Commands:\n`);
+  output.write(`  host      Start backend source-of-truth host service\n`);
+  output.write(`  gateway   Start frontend aggregation gateway and MCP SSE server\n`);
+  output.write(`  stop      Stop process listening on a Bridge port\n`);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const command = argv[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return null;
+  }
+
+  if (command === 'host') {
+    return runBackendHost(argv.slice(1));
+  }
+
+  if (command === 'gateway') {
+    return runGateway(argv.slice(1));
+  }
+
+  if (command === 'stop') {
+    return runStop(argv.slice(1));
+  }
+
+  process.stderr.write(`Unknown command: ${command}\n\n`);
+  printHelp(process.stderr);
+  process.exitCode = 1;
+  return null;
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, printHelp };

package/bridge.config.json.example

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "bridge-workspace",
+  "version": "0.1.0",
+  "description": "Lightweight decentralized MCP bridge for frontend/backend collaboration.",
+  "type": "commonjs",
+  "bin": {
+    "bridge": "./bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".bridgeignore",
+    "README.md",
+    "bridge.config.json.example"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "chokidar": "^3.6.0",
+    "express": "^4.19.2",
+    "ignore": "^5.3.2",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {}
+}