cc-bridge — 把桥装在文件所在的地方，让 AI 从任何地方接入

English | README.en.md

一座双向 MCP 桥：装在文件所在的那台机器上（Windows / macOS 桌面应用），Claude Code / Codex / WorkBuddy 等任意 MCP 客户端从任何地方接入——
模式 A：远程 Linux 上的 Claude Code 直接读写你本地 Windows/macOS 的文件（免 scp、免 SSHFS）；
模式 B：你本地 AI 的工具接进家里 NAS / 公司 Windows 工作机的文件与环境（跨公网走内置 HTTPS 自签）。
全程有路径白名单、审计日志、自动备份、一键还原。安装包 4.5MB（Windows）/ 5.7MB（macOS）。

界面一览

连接页	安全页	设置页	日志 / 审计页

以上为 v2.10.0 Windows 实际界面：连接工作台、安全与白名单、设置（关于页）、审计日志。原图存放于 docs/images/。

这是什么

cc-bridge 是一个运行在「文件所在机器」上的 MCP（Model Context Protocol）桥接服务，以原生桌面应用形式运行（Tauri 2）。支持 Windows 10/11 与 macOS（Apple Silicon），同一套 Rust 代码，两个平台功能一致（防火墙一键放行等 Windows 专属功能除外，详见 已知差异）。任意支持 MCP 的 AI 工具（Claude Code / Codex / WorkBuddy / 通用客户端）通过 MCP 端点接入后，可以直接操作这台机器上白名单内的文件与环境——同一个软件，两个方向都能用。

背景 / 解决的问题

模式 A（最常见）：团队在本地（Windows / macOS）写代码，Claude Code 部署在远程 Linux 上。原来的痛点：

1. 文件传输效率低：每次改动都要 scp，大文件慢，容易版本混乱。
2. SSHFS 不稳定：网络一断挂载点卡死，终端被阻塞。
3. 缺少智能化操作：只能终端命令操作文件，没有批量重构、代码分析能力。
4. 操作无法审计：不知道 Claude 改了哪些文件，误操作后无法追溯恢复。

模式 B（反方向）：你的 AI（Claude Code / Codex…）在云端或笔记本上，但目标环境在另一台 Windows/macOS 机器上——家里的工作机、公司的台式机、跑着特定工具链的 Mac。ssh 过去操作 Windows 很别扭，SFTP 一堆手工步骤。cc-bridge 装在那台机器上，AI 从任何地方接进来，同样的白名单 + 审计 + 备份保护，跨公网时用内置的 HTTPS 自签加密。

两种模式怎么选

核心原则只有一条：桥装在文件所在的那台机器上，AI 从对面接过来。 两个方向用的是同一个安装包、同一套安全模型。

三个真实场景

第一种具体是这样跑起来的（五步，都在一分钟内）：

1. 文件所在的本机装 cc-bridge（4.5MB，双击装完即启动）；
2. 连接页给出 MCP 端点和 Bearer 令牌，在云主机的 Claude Code 里加一条 MCP 配置（内网直连，或走内置 HTTPS 自签）；
3. 之后你在 CC 里说「读一下 src/app.tsx」「把这三处改掉」，这些工具调用落在你本机——代码从来没有上传到云上，编辑器里能立刻看到改动；
4. 每次写入都有审计记录与自动备份，改错了可以按组还原；
5. 白名单以外一律拒绝，AI 碰不到你不想让它碰的目录。

换句话说：AI 在哪里跑不重要，文件始终待在它原来的地方。 把 CC 放在云主机上是为了算力和网络，不是为了把代码交出去。同样这套也适合「公司规定代码不出内网，但想用云端大模型」的情形。

快速开始（约 1 分钟）

第 1 步（两个模式相同）：在文件所在的那台机器上下载安装。到 Releases 按系统选一个：

国内用户：GitHub 下载慢的话走 Gitee 镜像
gitee.com/lzul/cc-bridge 的 releases 分支（发版时由 CI 自动同步到 latest/ 目录）。
注意那里只有 Windows 的 .exe 与 mac 的 .app.tar.gz（自动更新用的包，解开也能用），
没有 mac 的 .zip——mac 首次安装请从 GitHub Releases 拿。
安装后的自动更新也是 Gitee 优先，失败才退回 ghproxy / GitHub，无需手动配置。

暂无 Intel Mac（x86_64）和 Linux 构建。

第 2 步：打开「安全」页 → 点「浏览」把要开放的工作目录加进白名单（默认拒绝一切访问，安全优先）。

模式 A：远程 AI → 读写本地文件（同一内网 / VPN）

1. 切到「连接」页，复制给出的 claude mcp add ... 命令。
2. 粘贴到远程 Linux 终端执行，Claude Code 立刻就能读写你本机的文件了。

仅建议在同一内网 / VPN 下使用，不要暴露到公网（详见文末「已知限制」）。

模式 B：本地 AI → 接入远程机器的文件（跨公网）

1. 在 cc-bridge 的「设置 › 安全 › HTTPS 远程访问」一键开启 HTTPS：自动生成自签证书（绑定本机网卡 IP），显示 SHA-256 指纹。
2. 在装桥那台机器的面板「连接」页选你的 AI 工具，复制对应的配置片段（URL 已自动切 https://）；再把 URL 与 token 抄进你本地 AI 工具的配置里。
3. 核对指纹：把设置页显示的证书指纹与你本地记录的比对一致后再连，防中间人。
4. 接入方式按工具不同——Claude Code 用 CLI 命令（配 NODE_EXTRA_CA_CERTS 信任自签证书）、Codex 写 ~/.codex/config.toml、WorkBuddy 写 ~/.workbuddy/mcp.json，详见 兼容性矩阵。

公网暴露面有底线保护：远程访问开启时强制强 token、连续 401 自动封禁 IP（默认 5 次 → 15 分钟）、路径白名单 fail-closed。有域名时也可改走反向代理 + Let's Encrypt（模板）。

架构

模式 A：远程 AI → 本地文件                模式 B：本地 AI → 远程文件
┌──────────────────────┐                ┌──────────────────────┐
│ 远程 Linux（Claude Code）│              │ 你的笔记本（Claude Code / Codex）│
└──────────┬───────────┘                └──────────┬───────────┘
           │  MCP / Streamable HTTP                │  MCP / HTTPS（自签或反代）
           │  （同一内网 / VPN 直连）                │  （跨公网，TLS 加密）
           ▼                                       ▼
┌─────────────────────────────────────────────────────────────┐
│  文件所在机器（Windows / macOS）                                │
│  │                                                           │
│  └─ cc-bridge.exe / cc-bridge.app ── 单进程 Tauri 2 桌面应用    │
│       │                                                      │
│       ├─ 嵌入式 axum HTTP(S) 服务器 ── MCP JSON-RPC + 24 个工具 │
│       │        + 安全校验 + 自动备份 + 限流 + 401 封禁 + 审计      │
│       ├─ SQLite 配置存储 ── 原子更新，无竞态                     │
│       └─ React 前端 ── Tauri IPC 通信，管理面板                 │
└─────────────────────────────────────────────────────────────┘

同一个安装包、同一个端口、同一套安全模型——方向只取决于 AI 在哪一侧、文件在哪一侧。

关键架构决策：

• 纯 Rust 后端编译进 Tauri 二进制，不再有 Node.js sidecar（安装包 4.5MB / mac zip 5.7MB）
• 单一代码库跑两个平台：平台差异用 cfg(windows) / cfg(target_os = "macos") 在 Rust 侧切开，前端按后端下发的平台信息隐藏不适用的开关，CI 在 windows-latest 与 macos-latest 上各跑一遍 clippy + 测试
• axum 嵌入 Tauri 进程：对外暴露 HTTP 端口供远程 AI 工具连接
• 前端走 Tauri IPC：不走 HTTP，token 只用于远程认证
• SQLite 替换 config.json：原子更新，无 read-modify-write 竞态
• 审计日志保持 JSONL 文件：append-only，人类可读

交互流程

启动流程

用户双击 cc-bridge.exe / 打开 cc-bridge.app
        │
        ▼
  tauri::Builder
        │
        ├─ 1. single-instance 检查
        │     └─ 已有实例运行 → 激活已有窗口，本次退出
        │
        ├─ 2. setup() 初始化
        │     ├─ 创建 AppData 目录
        │     ├─ db::init_database()
        │     │    ├─ 创建 SQLite config 表
        │     │    └─ 检测 config.json → 自动迁移到 SQLite
        │     ├─ config::load_config() → 加载 BridgeConfig
        │     ├─ 构建 AppState（DB / Config / Locks / Stats）
        │     │
        │     ├─ spawn axum HTTP 服务器
        │     │    └─ 监听 0.0.0.0:7823，路由 /health + /mcp
        │     │
        │     ├─ 创建主窗口 (1080×820)，加载 React 前端
        │     │
        │     └─ 创建系统托盘
        │          菜单: 打开面板 / 重启服务 / 退出
        │
        ├─ 3. on_window_event
        │     └─ 点关闭 → 隐藏窗口（不退出进程）
        │
        └─ 4. run() → Tauri 事件循环

两条通信路径

cc-bridge 内部有两条独立的通信路径，共享同一个 AppState：

┌─────────────────────┐                 ┌──────────────────────────────────┐
│  远程 Linux 服务器    │                 │   本地 Windows / macOS           │
│                     │                 │                                  │
│  Claude Code        │   HTTP / TCP    │   cc-bridge (单进程)              │
│  (MCP 客户端)       │────────────────▶│                                  │
│                     │   内网:7823     │   ┌─ axum HTTP 服务器 ─┐         │
│  通过 MCP 协议       │                 │   │  POST /mcp         │         │
│  调用 24 个 MCP 工具  │                 │   │  Bearer token 认证  │         │
│                     │                 │   │  JSON-RPC dispatch │         │
└─────────────────────┘                 │   │  → 24 个工具处理器  │──┐      │
                                        │   │  → 安全校验         │  │      │
                                        │   │  → 审计日志         │  │      │
                                        │   └────────────────────┘  │      │
                                        │                           │      │
                                        │   ┌─ Tauri WebView ──┐    │      │
                                        │   │  React 前端       │    │      │
                                        │   │  invoke() ───────┼─┐  │      │
                                        │   │  (Tauri IPC)     │ │  │      │
                                        │   └──────────────────┘ │  │      │
                                        │                        ▼  │      │
                                        │   ┌─ Rust 后端 ───────┐   │      │
                                        │   │ #[tauri::command] │   │      │
                                        │   │ 23 个 IPC 命令    │◀──┘      │
                                        │   │                  │          │
                                        │   │ AppState ◀───────┼── 共享    │
                                        │   │ (DB/Config/Stats)│          │
                                        │   └──────────────────┘          │
                                        │                                  │
                                        │   ┌─ 本地文件系统 ─────┐          │
                                        │   │ C:\work\...       │◀─────────┘
                                        │   │ D:\projects\...   │  读/写/删/搜
                                        │   └───────────────────┘
                                        └──────────────────────────────────┘

关键设计：两条路径共享同一个 AppState——远程 AI 工具的文件操作会实时反映在本地面板的审计日志和统计数据中。

MCP 工具调用链路

远程 AI 工具调用文件工具时的完整请求链路：

远程 Linux:
  claude mcp add --transport http cc-bridge http://192.168.1.100:7823/mcp \
    --header "Authorization: Bearer abc123..."

AI 工具对话中触发工具调用:
        │
        ▼
  POST /mcp  ──  initialize (首次连接握手)
        │          返回 capabilities + serverInfo
        ▼
  POST /mcp  ──  notifications/initialized (握手完成)
        │
        ▼
  POST /mcp  ──  tools/list (发现可用工具)
        │          返回 24 个工具的 name + description + inputSchema
        ▼
  POST /mcp  ──  tools/call (实际调用)
        │
        ├─ auth_middleware
        │    └─ 验证 Bearer token（常量时间比较）
        │
        ├─ rate_limiter
        │    └─ 滑动窗口检查（100次/分钟）
        │
        ├─ dispatch_tool()
        │    ├─ resolve_safe_path()      ← canonicalize + 白名单校验
        │    ├─ assert_extension_allowed() ← 扩展名检查
        │    ├─ assert_file_size_ok()     ← 大小限制
        │    ├─ path_lock (写操作)        ← DashMap 并发锁
        │    ├─ backup (写/删操作)        ← 自动备份
        │    └─ 执行实际文件操作
        │
        ├─ audit::write_audit_log()       ← 追加 JSONL
        │
        └─ stats.increment_requests()     ← 更新统计
        │
        ▼
  返回 JSON-RPC 响应 → AI 工具拿到结果

用户操作场景

首次使用

1. 安装并启动 cc-bridge
2. 主窗口打开，白名单为空（安全默认：拒绝所有操作）
3. 进入"安全"页，在白名单根目录点"浏览…"
   → DirectoryBrowser 弹窗 → 导航选择工作目录 → 添加
4. 回到"连接"页，选择 scope（全局 / 项目级），复制连接命令
5. 粘贴到远程 Linux 终端执行，AI 工具连上 cc-bridge 即可开始工作

日常使用

开机 → 双击 cc-bridge → 窗口打开，MCP 服务器自动启动
     → 远程 AI 工具自动重连
     → 最小化到托盘（点 X = 隐藏，不退出）

两件事并行:
  ┌── 远程 AI 工具在后台读写文件
  │     每次操作 → 审计日志 + 统计计数
  │
  └── 用户偶尔打开面板查看
        面板每 5s 轮询状态，审计日志每 10s 轮询

改端口/地址

用户在"设置 → 网络"改 port 7823 → 9000，点"保存并重启服务"
  → save_config 检测 port 变更 → 写入 SQLite（restartRequired: true）
  → 前端自动调用 restart_mcp_server
  → abort 旧 axum → sleep 300ms → spawn 新 axum 监听 9000
  → 连接命令自动更新，远程需重新 claude mcp add

系统托盘

托盘图标右键:
  打开面板  → 显示/聚焦主窗口
  重启服务  → 杀旧 axum task + 重新启动
  退出     → 真正结束进程（唯一的退出方式）

数据流向

                    ┌────────────────┐
                    │   SQLite DB    │
                    │   (config 表)  │
                    └───────┬────────┘
                            │ load / save
                            ▼
┌──────────┐  IPC   ┌──────────────┐  HTTP   ┌─────────────┐
│ React UI │◀──────▶│  AppState    │◀───────▶│ 远程 Claude │
│ (WebView)│ invoke │  (内存)       │  /mcp   │   Code      │
└──────────┘        │              │         └─────────────┘
                    │ ┌─ config ─┐ │
                    │ │ RwLock   │ │
                    │ ├─ stats ──┤ │
                    │ │ RwLock   │ │
                    │ ├─ locks ──┤ │
                    │ │ DashMap  │ │
                    │ └──────────┘ │
                    └──────┬───────┘
                           │ read / write
                           ▼
                    ┌──────────────┐
                    │ 本地文件系统   │  白名单目录内
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ audit.log    │  JSONL 追加写入
                    │ .bak 备份    │  写/删前自动备份
                    └──────────────┘

功能清单

24 个 MCP 工具（任意接入的 AI 工具直接调用）

SSH 终端（本地人操作，非 MCP 工具）

第 4 个 Tab「终端」提供一个真正的交互式终端，让你在 cc-bridge 面板里直接连远端 Linux 敲命令——这是给人手动用的，不是给 AI 用的 MCP 工具（所以不计入上面的 24 个 MCP 工具）。

• 后端：调用本机系统自带 OpenSSH（Windows 10/11 自带 C:\Windows\System32\OpenSSH\ssh.exe，macOS 永远有），用 portable-pty 开本地 PTY（Windows = ConPTY / Unix = pty）把 ssh 的输入输出接到 xterm.js。零新网络协议、零重依赖，体积代价可忽略（portable-pty 0.9 只引 windows-sys 0.61.2 等小库）。
• 连接：支持两种认证方式——
  • 密码：名称 / 主机 / 端口 / 用户名 / 密码，可勾「记住密码」——密码用 aes-gcm 加密后落盘（密钥在 data_dir/ssh_key.bin，明文不出本地进程）。
  • 密钥：选「密钥」认证后填私钥路径（id_rsa / id_ed25519 等）+ 可选密码短语（passphrase）。有 passphrase 时同样经 aes-gcm 加密落盘，ssh 握手时由 PTY 自动填充。后端在 key 模式下给 ssh 加 -i <keyfile>，并用 IdentitiesOnly=yes 避免 agent 干扰。
• 交互：xterm.js 渲染，TERM=xterm-256color + 中文 UTF-8；窗口缩放走 PTY resize；ServerAliveInterval=30 / ServerAliveCountMax=3 保活防断；复制粘贴走 WebView 剪贴板。
• 多标签终端：每个 SSH 连接一个独立 xterm 实例 + 会话标签（顶部可切换/关闭），后台连接保持不断开；点连接自动新建标签，断线后标签标红。
• SFTP 文件管理：每个连接带「文件」按钮，弹出文件浏览器抽屉——列目录（解析 ls -la）、进入上级/子目录、上传/下载（走 scp -t / scp -f 子协议）、新建目录、删除。本地路径用输入框（不引原生文件选择器插件，零新增 Rust crate）。
• 安全闸：ssh_enabled 总开关默认关，首次进终端页弹启用确认（锁图标 + 风险说明）。凭据仅经 Tauri IPC 写入本机，明文字段绝不经通用 save_config 补丁，也不经 MCP 暴露给远端。SFTP 与终端共用同一开关与连接池。
• 连接池：复用 AppState 的 DashMap 管理 SSH 会话，60s GC 回收已退出的僵尸会话（含 SFTP 用的无屏 PTY 子进程）。
• 新增 13 个 Tauri IPC 命令（终端 8 + SFTP 5）：ssh_check / ssh_list_connections / ssh_save_connection / ssh_delete_connection / ssh_connect / ssh_input / ssh_resize / ssh_disconnect + ssh_sftp_list / ssh_sftp_get / ssh_sftp_put / ssh_sftp_mkdir / ssh_sftp_remove（见上「Tauri IPC 命令」表）。

⚠️ Windows 极少数精简镜像 / 旧 Win10 可能没装 OpenSSH。ssh_check 返回 absent 时前端弹降级卡，按提示用 Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0（需管理员）安装即可。

安全机制

• 路径白名单（allowedRoots）：只能访问明确允许的根目录，canonicalize() 防软链接逃逸，祖先遍历防路径穿越。被拒时错误信息会附带当前白名单（Allowed roots: ...），远程无需盲猜即可得知可访问范围。
• 扩展名白名单（allowedExtensions）：大小写不敏感匹配，留空表示不限制。
• Bearer token 认证：subtle::ConstantTimeEq 防时序攻击，32 位随机字母数字。
• 限流：DashMap 滑动窗口，默认 100 次/分钟，超限 429。
• 自动备份：写/删/覆盖前备份到配置目录，按时间戳命名，超出保留数自动清理。
• 审计日志：JSONL 格式，记录每次操作的时间/工具/参数/结果/来源 IP/耗时（durationMs）；成功与失败调用均记录真实参数；按保留天数（默认 30 天，0=永久）在启动时自动清理。
• 单文件大小上限：默认 20MB。
• 写锁：DashMap<PathBuf, Arc<Mutex<()>>>，同一文件并发写串行化。
• 401 封禁：远程访问开启时，连续 5 次认证失败封禁来源 IP（默认 15 分钟窗口，成功认证即清零），防爆破。

传输安全（模式 B 必读）

• 默认 HTTP + Bearer：明文传输，只适合内网 / VPN，不要暴露公网。
• 内置 HTTPS 自签（「设置 › 安全 › HTTPS 远程访问」一键开启）：rcgen 自签证书（825 天，SAN 绑定全部网卡 IP + 127.0.0.1），跨公网全程 TLS。接入侧务必核对设置页显示的 SHA-256 指纹防中间人；各 AI 工具对自签证书的信任路径见 兼容性矩阵。
• 反向代理 + Let's Encrypt（有域名时推荐）：桥只出 HTTP，由 Caddy / nginx 终结 TLS，模板见 reverse-proxy.md。
• 公网底线组合：强 token 强制轮换 + 401 封禁 + 路径白名单 fail-closed（空名单拒绝一切）+ 写类工具可关 + 命令执行默认关。

HTTP 接口

Tauri IPC 命令（前端 → 后端）

管理面板（React 前端）

界面采用 shadcn/ui 设计语言，顶部 Tab 分页布局，共 5 个页面：

• 连接：状态概览（请求数/错误数/运行时间，运行时间精确到秒且平滑跳秒）+ 高对比启停服务按钮（loading 态 + 失败内联报错）+ claude mcp add 命令一键复制 + 全局/项目级 scope 选择 + Token 掩码显示/重新生成
• 安全：白名单根目录 CRUD + 目录浏览器弹窗；扩展名/文件大小/限流/备份目录/备份保留，全部即时保存（防抖 800ms + 失焦）
• 设置：网络（host/port，改后一键保存并重启）+ 应用（开机自启开关）+ 审计（日志保留天数）
• 日志：审计日志表，6 列（时间 / 操作 / 参数摘要 / 来源 / 耗时 / 状态）；操作列显示中文名（如「读取文件」）+ 原始工具名；支持按操作/状态下拉筛选 + 关键字搜索（匹配参数与错误）+ 一键导出 JSON；点击行展开结构化详情（参数 KV + 格式化 JSON + 复制 + 错误块）
• 终端：SSH 终端（第 4 个 Tab，Ctrl+4）。人在面板里手动操作远端 Linux 的终端——左栏 SSH 连接列表（名称 + user@host:port + 在线/离线点），右栏 xterm.js 深色终端（复制 / 清屏 / 断开）。支持密码登录、记住密码（aes-gcm 加密落盘）、窗口缩放、ServerAliveInterval 保活；总开关 ssh_enabled 默认关，首次进入弹启用确认（遵循「默认关 + 多层闸」）。仅本地 Tauri IPC 调用，不经过 MCP，远端 AI 工具无法用它
• 深色/浅色主题切换（localStorage 持久化）

技术栈

目录结构

cc-bridge/
├── README.md                           # 本文档
└── desktop/                            # 完整 Tauri 2 桌面应用
    ├── package.json                    # 前端依赖 + tauri CLI
    ├── vite.config.ts                  # Vite 配置（端口 1420）
    ├── tsconfig.json
    ├── index.html
    ├── src/                            # React 前端源码
    │   ├── main.tsx
    │   ├── App.tsx                     # 主应用 + TanStack Query
    │   ├── index.css                   # TailwindCSS + 主题变量
    │   ├── lib/
    │   │   ├── tauri.ts                # invoke() 类型封装
    │   │   └── types.ts                # TypeScript 类型定义
    │   └── components/
    │       ├── layout/Header.tsx       # 状态指示/版本/运行时间/主题切换
    │       ├── ui/                     # 手写 shadcn 风格基础组件
    │       │   ├── button.tsx / input.tsx / label.tsx
    │       │   ├── card.tsx / badge.tsx / alert.tsx
    │       │   ├── tabs.tsx / dialog.tsx / table.tsx / separator.tsx
│       ├── tabs/                   # 5 个 Tab 页面 + 拆分子组件
│       │   ├── ConnectTab.tsx
│       │   ├── ConnectHero.tsx     # 连接页 Hero 卡（状态/指标/启停按钮）
│       │   ├── SecurityTab.tsx
│       │   ├── SettingsTab.tsx     # 网络 + 应用(开机自启) + 审计
│       │   ├── SettingsToggles.tsx # 设置页功能开关卡
│       │   ├── LogTab.tsx
│       │   ├── TerminalTab.tsx      # 第 4 个 Tab：SSH 终端（连接列表 + xterm）
│       │   ├── SshTerminal.tsx      # xterm.js 终端组件（输入/输出/缩放/复制清空）
│       │   └── SshConnectionDialog.tsx # 新建/编辑 SSH 连接弹框
    │       └── modals/
    │           └── DirectoryBrowser.tsx # 目录浏览器弹窗
    └── src-tauri/                      # Rust 后端
        ├── Cargo.toml
        ├── tauri.conf.json
        ├── capabilities/default.json
        ├── icons/                      # 占位图标（发布前用 tauri icon 替换）
        └── src/
            ├── main.rs                 # Tauri 入口 + 系统托盘 + 窗口管理
            ├── lib.rs                  # 模块声明
            ├── state.rs                # AppState（DB/Config/Locks/Stats）
            ├── db.rs                   # SQLite 初始化 + config.json 迁移
            ├── config.rs               # BridgeConfig 结构体 + 读写
            ├── commands.rs             # #[tauri::command] IPC 接口聚合（含开机自启 + SSH 终端）
            ├── commands/               # IPC 命令按职责拆分，commands.rs 用 `pub use` 聚合
            │   └── ssh_cmds.rs         # SSH 终端 8 个命令：ssh_check/list/save/delete/connect/input/resize/disconnect
            ├── ssh_crypto.rs          # SSH 密码 aes-gcm 加密/解密（落盘用，密钥在 data_dir/ssh_key.bin）
            ├── backup.rs               # 文件备份 + 自动清理
            ├── audit.rs                # JSONL 审计日志
            ├── browse.rs               # 全盘目录浏览（Windows 枚举盘符 / macOS 从 / 起）
            ├── network.rs              # LAN IP 检测 + connect 命令
            ├── security/               # 安全模块
            │   ├── mod.rs
            │   ├── path.rs             # 路径校验 + canonicalize
            │   ├── extension.rs        # 扩展名白名单
            │   ├── filesize.rs         # 文件大小限制
            │   ├── auth.rs             # 常量时间 token 校验
            │   └── ratelimit.rs        # 滑动窗口限流
            └── mcp/                    # MCP 协议实现
                ├── mod.rs
                ├── http.rs             # axum 路由 + JSON-RPC dispatch
                ├── transfer.rs         # 文件直传：一次性票据 + PUT|GET /transfer/{ticket}
                └── tools/              # 24 个工具处理器
                    ├── mod.rs
                    ├── list_allowed_roots.rs
                    ├── list_directory.rs
                    ├── read_files.rs
                    ├── write_files.rs
                    ├── edit_files.rs
                    ├── delete_files.rs
                    ├── move_files.rs
                    ├── copy_files.rs
                    ├── create_directory.rs
                    ├── remove_directory.rs
                    ├── search_files.rs
                    ├── analyze_file.rs
                    ├── run_command.rs
                    ├── get_command_output.rs
                    ├── wait_command.rs
                    ├── view_image.rs
                    └── stop_command.rs

部署流程

前置条件

• Windows 10/11，或 macOS（Apple Silicon）
• Rust 工具链（rustup.rs）
• Node.js 18+（仅构建时需要）

构建 & 运行

Windows：

cd desktop
npm install
npm run build     # cargo tauri build → 产出 NSIS 安装包

产出路径：src-tauri/target/release/bundle/nsis/cc-bridge_<版本>_x64-setup.exe（v2.4.0 为 4.48MB）

macOS：

cd desktop
npm install
npm run prebuild
npx tauri build --bundles app     # 必须用 --bundles 覆盖

产出路径：src-tauri/target/release/bundle/macos/cc-bridge.app（以及 updater 用的
cc-bridge.app.tar.gz + .sig）。

为何 mac 必须带 --bundles：tauri.conf.json 的 bundle.targets 固定为 nsis
（Windows 发版路径），不覆盖的话 mac 上会直接失败。故意不往配置里加 mac target，
避开影响已稳定的 Windows 发版。

若要产出可分发的 zip，用 ditto 而不是 zip：
ditto -c -k --sequesterRsrc --keepParent <path>/cc-bridge.app out.zip。
普通 zip 会破坏 .app 的资源叉与符号链接，解压后打不开。

接入 AI 工具

安装并启动 cc-bridge 后，连接页的接入向导会按你选的工具生成配置片段（Claude Code / WorkBuddy / Codex / 通用 MCP 四选一），HTTPS 开启时自动切 https:// 并附「复制 PEM」步骤。

模式 A（内网，Claude Code）——在远程 Linux 执行面板给出的命令：

claude mcp add --transport http cc-bridge http://<局域网IP>:7823/mcp --header "Authorization: Bearer <token>"

模式 B（跨公网，HTTPS）——连接页选工具复制片段；Claude Code 需先信任自签证书：

# 1. 从向导「复制 PEM」保存证书，随后在远程/本地 shell 导出信任变量
export NODE_EXTRA_CA_CERTS=/path/to/cc-bridge.crt
# 2. 面板给出的命令（URL 已是 https）
claude mcp add --transport http cc-bridge https://<IP或域名>:7823/mcp --header "Authorization: Bearer <token>"

其他工具（Codex = TOML、WorkBuddy = JSON）的完整片段与各工具自签信任路径，见 兼容性矩阵。

macOS 安装与更新说明

本节结论均来自 CI 在真实 macOS（arm64）上的实测，不是推测。

适用范围：仅 Apple Silicon（arm64）。包用 ad-hoc 签名，未购买 Apple Developer
账号、未做公证（notarize）——这是内网自用的取舍。

安装

推荐路径：内网直接拷贝。通过共享目录 / U 盘 / scp 拿到 cc-bridge.app 的，
通常不带隔离属性，双击就能开，没有下面那些麻烦。

经浏览器 / 网盘下载的，macOS 会给它打上 com.apple.quarantine 隔离属性，
首次打开会被 Gatekeeper 拦住（实测：带隔离属性时应用起不来，服务端口无响应）。
两种解法：

# 方式一（推荐，一次性）：直接清除隔离属性
xattr -dr com.apple.quarantine /你的路径/cc-bridge.app

方式二（图形界面）：双击 → 被拦 → 系统设置 → 隐私与安全性 → 下拉找到提示 → 点「仍要打开」。

⚠️ macOS 15 (Sequoia) 起，老套路「右键 → 打开」已经失效，必须走系统设置那条。

如果你用 spctl -a -vvv 自己查过并看到 rejected，不用在意：spctl 判的是
「能不能过公证策略」，ad-hoc 包永远过不了；而 Gatekeeper 实际只拦带隔离属性的包。
实测：清掉隔离属性后应用正常启动，尽管 spctl 仍报 rejected。

装到哪里

最后一条的原因：updater 先用 rename 把旧包移到临时目录（在 /var/folders），
而 rename 跨文件系统会返回 EXDEV 而不是「权限不足」——于是它不会尝试提权，
直接失败。这一条是读 源码 发现的，尚未实测（CI 里同卷、碰不到）。

自动更新

可用。完整链路（检查 → 下载 → 验签 → 替换 .app → 重启）已在真实 macOS 上跑通。

一个常见担心可以打消：更新后不会再被 Gatekeeper 拦。因为 updater 是用程序直接
解压并替换文件的，不经浏览器那条路，新包不会被打上隔离属性（实测确认：
更新后的包 xattr 为空、签名校验通过、重启后服务正常）。所以你只需要在首次安装时
放行一次，之后的更新都是无感的。

已知差异（与 Windows 版相比）

• Cmd+W 关不了窗：窗口是自绘标题栏，没有系统关闭按钮，而 Cmd+W 依赖的正是它。
  用标题栏里的关闭按钮（正常）或托盘菜单。Cmd+Q 退出正常。
• 防火墙相关功能不可用：这些靠 Windows 的 netsh，界面上已自动隐藏。
• IP 变化提示不实时：mac 上靠 5 秒轮询兜底（功能正常，只是不是瞬时的）。
• 命令执行壳层为 sh / bash（Windows 是 cmd / Git Bash）。
• 设置页没有「桌面快捷方式」这一行：它靠 Windows 的 .lnk + powershell 实现，
  mac 上没这回事。入口用 Dock / 启动台（把 cc-bridge.app 拖进 Dock 即可）。
• 「安装位置」显示的是 cc-bridge.app 本体（而不是包内的 Contents/MacOS），
  「打开目录」会在访达里选中它。
• 桌面通知尚未在真机确认：mac 侧走 NSUserNotification，若系统设置的「通知」
  里没放行 cc-bridge，通知会静默不弹。现已把失败写进日志（日志页可见），
  push_notification 也会回传 pushed: false，让远程 AI 改用文字告知你。

配置迁移

首次启动时，如果检测到旧版 config.json 文件存在：

• 自动将配置项导入 SQLite
• 旧文件重命名为 config.json.migrated

已知限制

• 平台：仅 Windows 10/11 与 macOS（Apple Silicon）；没有 Intel Mac（x86_64）和 Linux 构建。mac 版的差异见 已知差异。
• 跨公网访问只有两种受支持的形态：内置 HTTPS 自签（无域名）或反向代理 + Let's Encrypt（有域名，见 reverse-proxy.md）。桥本身不做内网穿透、不开裸 HTTP 公网暴露；自签证书对部分 AI 工具的兼容性以 实测矩阵 为准。
• analyze_file 的函数/类计数是正则启发式估算，不是语法解析。
• 亮色主题 × Claude Code 主题跟随：终端会在数据流里代答 OSC 10/11 颜色查询，Claude Code 的 theme: auto 能正确跟随桥的亮/暗主题（亮色下用户消息不再是黑块）；过旧的 Claude Code 版本无 auto 模式，需在会话里手动 /theme light。详见 兼容性矩阵。
• delete_files 只删单个文件，不支持删目录（安全设计）。
• MCP 协议实现为手动 JSON-RPC dispatch（非 rmcp SDK 宏），不做协议协商。
• run_command 的跨调用 shell 会话持久化（拿 sessionId 带住 cwd + 环境变量）默认关闭，不开时必须每次显式传绝对 cwd。
• get_command_output / wait_command 用 outputComplete 区分「进程已退出」与「管道已读完」（exit ≠ close）——前者为 false 时尾部可能还会长，别当最终结果。
• 后台命令（run_command(background=true)）注册表由周期任务按 command_cleanup_secs（默认 120s）自动回收；stop_command 只打终止标记、不删条目，被杀进程的输出在宽容期内仍可取回。kill 未生效的顽固进程也会在宽容期后被清理（否则永久占用并发名额）。
• run_command 前台模式超时后仍会强杀命令（不会自动转后台继续跑）；但超时前已产生的输出会连同 timedOut: true 一起返回（默认超时 120s）。长任务请用 background: true。
• SSH 终端是本地人操作的交互终端（第 4 个 Tab），不是给远程 AI 工具的 MCP 工具，远端无法用它；它需要本机装有 OpenSSH 客户端（Windows 10/11 / macOS 均自带，极少数精简镜像需 Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0 安装）。

版本历史