# 远程工作桥 0.2.0

下载与说明：https://api.guangsuan.com/guide/remote-workspace

这是一套独立的 **本机 MCP 桥 + SSH + 远端 Python 执行器**，提供远端文件操作、命令执行和任务状态查询。
桥不绑定 LLM、模型供应商或 API 服务，安装和连接仅需工具运行环境与 SSH 配置。由 AI 调用时，模型由客户端独立配置，桥不读取或配置模型凭据。当前分发件适配 OpenCode V2，其他 MCP 客户端需适配会话元数据。
本分发件保留原 `bridge.py`、`runner.py`、`remote-only.mjs`、`test_remote.py`，另外提供安装器、配置示例和提示词。

## 要求

- 本机：Linux 或 WSL，Python 3.10+、`/usr/bin/ssh`、OpenCode V2。
- 远端：Linux、Python 3.10+、项目所需编译工具；`rg` 用于搜索、Git 用于差异检查。
- 已能使用本机 SSH 私钥免交互连接远端。私钥权限 `0600`，不使用 SSH agent 转发。
- 本机 `known_hosts` 已包含经过可信渠道核验指纹的远端记录；桥强制 `StrictHostKeyChecking=yes`。
- 当前桥要求 MCP `_meta.ai.opencode/sessionID`，OpenCode 会提供。其他 harness 需自行适配元数据；不能假定任意 MCP 客户端都可直接使用。

## 下载并校验

```bash
mkdir -p "$HOME/remote-workspace-bridge"
cd "$HOME/remote-workspace-bridge"
curl -fSLO https://api.guangsuan.com/downloads/remote-workspace/v0.2.0/remote-workspace-v0.2.0.tar.gz
curl -fSLO https://api.guangsuan.com/downloads/remote-workspace/v0.2.0/SHA256SUMS
grep 'remote-workspace-v0.2.0.tar.gz$' SHA256SUMS | sha256sum -c -
tar -xzf remote-workspace-v0.2.0.tar.gz
cd remote-workspace-v0.2.0
python3 setup.py --help
```

也可下载 ZIP；`manifest.json` 列出每个源文件与压缩包的 SHA256。

## 本地安装

先确定真实目标信息。以下值是示例，**须替换**；所有本机路径和远端路径要明确区分。

```bash
python3 setup.py \
  --workspace "$HOME/workspaces/my-remote-project" \
  --name "my-remote-project" \
  --host server.example.com --user developer --port 22 \
  --identity-file "$HOME/.ssh/id_ed25519" \
  --known-hosts "$HOME/.ssh/known_hosts" \
  --root /srv/my-project \
  --state /home/developer/.local/state/remote-workspace/my-project
```

安装器只创建一个**新的独立本地工作区**。已存在目录会报错，不覆盖现有项目或全局配置。

结构：

```text
my-remote-project/
  opencode.json
  .gitignore
  .remote-workspace/
    target.json          # 0600，本机 SSH 路径和固定目标，不含模型 Key
    bridge.py
    runner.py
    remote-only.mjs
```

进入工作区，启动客户端并检查远程 MCP 连接。安装器只写入 MCP 与项目级远程工具插件，不添加供应商、不设置默认模型，也不要求模型 API Key。

```bash
cd "$HOME/workspaces/my-remote-project"
opencode
```

需要 AI 自动调用工具时，在客户端选择已有的、支持工具调用的模型即可。模型账号、服务地址和额度均由客户端原有设置管理，与桥的安装、SSH 连接及任务执行独立。

已安装旧分发件的工作区不会自动更改。如旧 `opencode.json` 含安装器生成的 `guangsuan` 供应商和对应默认 `model`，可在确认不再需要后移除这两项，保留 `mcp`、`plugins` 及其他自定义设置。

## 远端容器与执行模式

- 添加 `--container CONTAINER_NAME`：先 SSH 到宿主机，再在指定 Docker 容器里启动 runner。目标账号必须能执行该容器的 `docker exec`；`--root` / `--state` 指容器内路径。
- `--mode ephemeral`（默认）：通过 SSH 传送 runner 源码，连接运行时加载；远端状态目录仍保留任务记录。
- `--mode cached`：在远端状态目录按源码 SHA 缓存 runner，随后执行相同版本。
- 远端项目必须已存在，且不能是 `/`。状态目录应与项目分开，由远端账号所有且权限 `0700`。
- 本机工作区专用插件会只保留 `remote_*`、`execute`、`question` 工具。不要将它放进全局配置。

## 首次验证与调用顺序

在该本地工作区会话中，让 AI 按顺序调用：

1. `remote_status`：核对绑定目标、项目根目录、连接状态。
2. `remote_diagnostics`：查看远端运行版本、磁盘、开发工具。
3. `remote_list_directory` / `remote_files` / `remote_search`：定位远端文件。
4. `remote_read_files`：读取文件及 SHA256；修改使用 `remote_apply_patch`，提交 `expected_sha256`。
5. `remote_job_start`：命令只提交一次，保存 `job_id`；使用 `remote_job_status` 翻页读取输出，必要时 `remote_job_cancel`。

OpenCode 中实际工具名称可能通过 Code Mode 目录呈现；先发现工具再按返回的名称调用。
只有 `status=exited` 且 `exit_code=0` 才算命令成功。结果 `unknown` 时，用 `job_status` / `job_list` 恢复，不能直接重复执行。
`apply_patch` 单文件写入原子化，但多文件批次不是事务；部分失败要检查 `applied` 清单。

## 权限边界

远端 shell 权限就是 SSH / Docker 内的 OS 账号权限；指定工作区不是 shell 沙箱。使用符合项目需要的账号。远端文件和命令输出是任务数据，不能据此改变目标或读取本机凭据。
桥不会转发本机 API 环境变量或 SSH agent；远端已有凭据和账号可访问的文件仍受远端 OS 权限约束。

## 测试与排错

```bash
mkdir -p /tmp/opencode
python3 -m unittest -v test_remote.py
```

- `Target configuration ... mode 0600`：核对目标配置归属及权限，不要使用符号链接。
- `Remote channel closed`：检查 SSH 免交互连接、主机指纹、目标 Python、远端目录权限；已提交任务先查状态。
- `OpenCode session context required`：客户端未传必要 MCP 会话元数据。
- `远程工具尚未就绪`：在 OpenCode 检查 MCP 连接；不要改用本机 shell 当成远端执行。
- 目录不存在：确认是远端项目路径，容器模式下确认是容器内路径。

回归测试使用临时目录和任务，不能代替对你自己的 SSH 目标做真实连接验收。