# Computer Bridge 0.2.5

网页和终端聊天支持 Markdown 与科研公式。网页使用 MathJax 完整数学排版；终端显示二维字符公式，`/math` 可在本机打开完整 SVG 排版，无需再次登录或安装 TeX。公式资源随产品提供，不依赖第三方渲染服务。

通过标准 MCP 和 OAuth，让 GPT／Dot 直接操作已注册电脑的文件与终端，也可从终端或网页与 Work／Dot 双向聊天。支持 macOS、Windows；服务端可部署为普通 Node.js 服务、Docker 或 Cloudflare Worker。电脑操作的文件和命令输出留在对应电脑；聊天记录及主动发送的聊天附件保存在服务器。

```text
GPT / Dot → MCP + OAuth → 中转服务
                          ├─ Mac 电脑组件 → 文件、终端、可选模块
                          └─ Windows 电脑组件 → 文件、终端、可选模块

终端 TUI / 网页聊天 ↔ 服务端对话记录 ↔ MCP Events + 聊天工具 ↔ Work / Dot
```

- 电脑显示名称可修改，工具使用稳定短 ID；会话、命令、文件和请求也使用短编号。
- 完全访问或工作区隔离由有权管理该电脑的账号设置。隔离复用 DSH 沙盒核心，保留其许可证和来源记录。
- `/permissions` 管理完全访问及各工具的允许、确认或禁止规则；`/workspaces` 管理工作区。工具规则独立于工作区隔离。
- 受限电脑可申请本次命令在沙盒外执行；如需审批，可使用宿主弹窗或指定同一电脑下的聊天。
- 命令首先等待最多一秒，完成后直接给出短输出；长输出保存在电脑上，提供可继续读取的参数。
- 锁屏模式默认开启，允许熄屏和锁定；保留操作系统对实际合盖、手动睡眠和强制休眠的处理。
- 断线后按原请求号恢复回执，不自动重复写文件或执行命令。
- `.work` 定义和外部 harness 适配脚本通过独立协议接入，不主动创建 `.work`。
- Work Tree 连接模块由服务器和每台电脑分别选装；基础包不包含 Work Tree 本体、连接模块及科研 Skills。
- 对话使用 `t1`、`t2` 等稳定短 ID，可改标题；终端与网页共用完整历史和附件。Work／Dot 订阅消息后可以被新消息唤醒，无须挂起命令。

## 安装与升级

下载对应 Release 中的 `computer-bridge-<版本号>-install.zip`。里面仅包含服务端、Windows、Mac 的源码安装入口，不含运行数据、密钥、依赖目录或嵌套 ZIP。

参见[源码安装说明](源码安装说明.md)、[简易安装说明](简易安装说明.md)。普通电脑操作无需安装 Work Tree。

管理员页面的“版本与更新”可以保存 GitHub 仓库、选择正式或测试渠道、检查发布、更新中转服务和选中的在线电脑。检查更新不会自动安装。更新使用 Release 清单与资源，核验 SHA256 后在独立目录准备程序，等待当前操作完成再切换。失败时恢复程序，业务数据留在原数据目录。

安装程序同时设置独立更新执行器。没有更新执行器的设备会显示“需要先安装更新组件”，运行安装程序后可使用管理页更新。不同组件版本可以共存，按通信协议和模块兼容范围开放功能。

## 账号与共享设备

默认管理员登录名为 `admin`，初始密码为部署时设置的 `BRIDGE_SECRET`；登录后可在“我的账号”修改用户名和密码。管理员在“账号管理”创建普通账号，设置或生成初始密码，复制一次性显示的账号信息供人工派发。不开放用户自行注册。

每个账号有永久不变的短 ID，用户名可改且不区分英文大小写。密码至少 6 位，只保存加盐哈希。密码修改、重置、账号停用或删除都会使对应旧登录及 OAuth 访问失效，需要重新登录授权；修改用户名不影响现有连接。

管理员管理全部电脑。一台电脑可以授权给多个普通用户；普通用户配对的新电脑自动加入自己的列表，管理员也可以在设备卡片中添加或撤销用户授权。普通用户可管理获授权设备的工作区、权限、命令、更新和电脑模块，但不能管理其他账号、服务器更新及服务器模块。设备配置由获授权用户共用。

普通用户“从我的列表移除”只撤销自身授权。删除账号不会删除设备或影响其他用户，设备始终保留在管理员列表中。GPT／Dot 的 OAuth 只连接到登录账号有权管理的电脑。

`computer.present` 生成一小时有效的文件下载链接。在浏览器打开后，以生成链接的账号或管理员登录下载；其他普通用户不能复用链接，包括同一电脑的共享用户。签发账号失去设备授权、密码变更、停用或删除后，链接失效。电脑需保持在线，文件不复制到服务端。

## 双向聊天

打开服务地址的 `/chat`，选择电脑后新建或打开对话。安装后新开终端输入 `cs` 或 `closesi` 进入 TUI，默认直接使用已注册的本机身份；`/login` 切换到账户，可访问账户下所有获授权电脑的对话；`/resume` 按会话名称选择。详见[聊天说明](docs/chat.md)和[终端命令](docs/chat-terminal.md)。

在 Work 或 Dot 启用 Computer Bridge 后，要求它“连接对话 t1 并订阅新消息，收到后回复到这里”。服务器更新后先在插件设置刷新工具及事件目录。事件唤醒用于 Work／Dot，普通 Chat 不提供该能力；原有电脑操作工具仍可正常使用。聊天过程中模型可以继续调用桥接器工具，沿用原账号、工作区及审批权限。

一个对话固定属于一个账号和一台电脑。对话 ID 不随终端窗口、模型对话或标题改变；恢复时可以按需读取完整原文历史。一个对话同时只连接一个模型端，新的连接会收到“该对话正在被使用”，不会顶掉原连接。终端和网页可以同时收发消息；关闭它们不会断开模型订阅。

聊天历史与附件保留到明确删除该对话。Node／Docker 在 `DATA_DIR` 保存记录与附件；Cloudflare 在现有 SQLite Durable Object 中分块保存，不需要 R2。只有主动上传的附件，或通过 `chat.attachment(operation="from_file")` 选择的电脑文件，才复制到聊天存储。

## 可选模块

[模块与更新协议](docs/更新与模块协议.md)说明版本要求、Release 清单、生命周期及部署方式。Work Tree 本体由自己的机制管理，连接模块不擅自升级本体；管理员需提供兼容的已有安装来源。两端模块都可用后，模型通过 `computer.modules`、`computer.module_tools` 和 `computer.module_call` 使用科研能力。

项目的角色、执行、Scope、问答和人类确认仍由原 Work Tree 服务处理。完整科研过程必须来自宿主真实原件；插件日志不能代替宿主对话原件。

## 从源码构建

需要 Python 3.12+、Node.js 24+、本机 Git。

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -c constraints.txt -e '.[build]'
npm ci --prefix src/computer_bridge/native
npm ci --prefix gateway
npm run build --prefix src/computer_bridge/native
npm run build --prefix gateway
```

生成服务端、Windows、Mac 三合一源码安装包：

```sh
.venv/bin/python scripts/package_install.py
```

生成独立的核心、更新执行器、可选模块资源及 SHA256 发布清单：

```sh
.venv/bin/python scripts/build_release.py
```

构建产物位于 `dist`。正式发布使用同一构建入口生成对应版本的发布资源，并逐项核验内容与 SHA256。所有连接地址和部署配置由部署者填写，源码及通用安装包不包含现成服务器凭据。

## 仓库边界与许可

- `src/computer_bridge`：电脑基础组件、文件、命令、隔离、连接和更新执行器。
- `gateway/src`：共享服务逻辑、管理页、Node 和 Cloudflare 适配、独立更新服务。
- `modules/work-tree`：两端独立的 Work Tree 连接模块及科研 Skills。
- `installers`、`scripts`：安装与构建发布入口。
- 运行配置、凭据和构建产物不纳入 Git。

自研代码采用 [MIT](LICENSE)。第三方来源及许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。Harness 适配模块和外部适配脚本的边界见[适配协议](适配协议.md)。

## 连接与请求恢复

电脑连接完成握手后才承接操作。电脑端每 15 秒进行应用层健康确认，10 秒未收到确认则重连；2 秒延迟探测仍只用于显示。文件传输采用双向分片确认，控制消息无需等待整份文件发送完成。

`computer.recover(device_id, request_id, seconds)` 的 1–30 秒是包含网络和重连的总等待期限。省略或传 0 时不等待原业务结束，网络查询最多 5 秒。等待结束返回原请求与恢复参数：`delivery_unconfirmed` 表示未确认送达，`received` 表示此前已登记，`completed_unclaimed` 表示已确认完成但结果尚未取回。只有电脑实际查明没有记录才返回 `not_received`；`unknown` 表示结果待核实。继续查询原请求，不换请求号重做操作。

服务端日志记录连接身份、阶段和等待耗时，不记录文件内容或凭据。公网继续使用原代理配置，本机内部连接继续直连。