giuliastro/harness-remote

# Harness Remote Harness Remote 是一款配套应用程序，可让您通过手机或桌面设备控制 coding-agent harness，即使您不在主工作站也能随时随地进行操作。 它旨在简化日常使用：连接到后端，检查活跃会话，查看进度，发送新的 prompt 或 slash 命令，并在支持的情况下停止正在运行的操作。 ## 支持的 Harness 该应用程序与后端无关：您可以在**设置 (Settings)** 中选择 harness，每个 harness 都保留了各自保存的连接信息，因此您可以随意切换，无需重新输入任何内容。 | Harness | 状态 | 连接方式 | |---|---|---| | [OpenCode](https://github.com/sst/opencode) | 已支持 | 直接连接到 OpenCode HTTP server | | Oh My Pi (OMP) | 已支持 | 通过本仓库中包含的本地 bridge | | [PI](https://pi.dev/) | 计划中 — [#36](https://github.com/giuliastro/harness-remote/issues/36) 已开放，欢迎协助 | 可能通过 PI ACP adapter 使用相同的 ACP bridge | 支持级别因各个 harness 暴露的功能而异。下方的 [OpenCode](#opencode-server-setup) 和 [OMP](#oh-my-pi-bridge-setup) 部分记录了它们的设置说明以及特定后端的限制。 ## 截图 | 会话 | 详情 | |---|---| |  |  | ## 功能 - 配置并测试与受支持 harness（OpenCode server 或 OMP bridge）的连接 - 浏览并监控会话 (`idle`, `busy`, `retry`) - 打开会话并阅读消息、todo 项和进度 - 直接通过聊天输入框发送 prompt（以及 `/commands`） - 在必要时停止正在运行的工作 - 使用适合 Android 的底部导航栏，快速访问会话、详情、设置和帮助 - 在正在运行的会话完成时播放完成提示音 - 在英语、意大利语和繁体中文之间切换 UI 语言 ## 技术栈 - frontend：React + TypeScript + Vite - 移动端打包：Capacitor (Android APK) - 网络：在统一的 app 端 API 之下使用针对特定 harness 的传输方式 —— OpenCode HTTP API，以及 `bridge/` 中的本地 OMP HTTP/SSE bridge - CI/CD：使用 GitHub Actions 进行云端 APK 构建 - i18n：包含英语、意大利语和繁体中文的轻量级自定义 i18n 模块 ## 下载 从 GitHub Releases 页面下载最新的签名 Android APK： https://github.com/giuliastro/harness-remote/releases/latest ## Harness 设置 ### OpenCode Server 设置 启动具有网络访问权限和 Basic Auth 的 OpenCode server。 macOS / Linux (bash/zsh)： ``` OPENCODE_SERVER_USERNAME=opencode OPENCODE_SERVER_PASSWORD=your-password npx -y opencode-ai serve --hostname 0.0.0.0 --port 4096 ``` Windows PowerShell： ``` $env:OPENCODE_SERVER_USERNAME="opencode" $env:OPENCODE_SERVER_PASSWORD="your-password" npx -y opencode-ai serve --hostname 0.0.0.0 --port 4096 ``` Windows cmd： ``` set OPENCODE_SERVER_USERNAME=opencode set OPENCODE_SERVER_PASSWORD=your-password npx -y opencode-ai serve --hostname 0.0.0.0 --port 4096 ``` 对于基于浏览器的 Web 调试，请根据需要添加 CORS 来源： ``` npx -y opencode-ai serve --hostname 0.0.0.0 --port 4096 --cors http://localhost:5173 --cors http://127.0.0.1:5173 ``` 对于 Android APK（Capacitor 原生 HTTP），通常不需要 CORS，但保留显式的来源仍然可以。 如果您从其他主机/IP 使用浏览器模式，请同时包含 localhost 和您的开发主机： ``` npx -y opencode-ai serve --hostname 0.0.0.0 --port 4096 --cors http://localhost --cors http://localhost:5173 --cors http://:5173 ``` 如果远程/移动设备无法连接，请在您的 OS 防火墙和网络防火墙/NAT 中开放 TCP 4096 端口。 ### Oh My Pi Bridge 设置 Harness Remote 通过本仓库中包含的 bridge 连接到 OMP。该 bridge 会在同一台计算机上启动 `omp acp`，将其 ACP stdio 协议转换为应用程序的 HTTP/SSE API，并且绝不会读取或修改 OMP 的内部数据库。 #### 前置条件 - Node.js 20 或更高版本； - `PATH` 中存在可用的 `omp` 命令； - 在运行 OMP 的计算机上检出了本代码仓库。 从代码仓库根目录启动 bridge。使用 `--root` 限制手机可能访问的每一个工作树（worktree）；重复该选项以允许多个根目录。 ``` npx --yes ./bridge \ --host 0.0.0.0 \ --port 4097 \ --username omp \ --password "use-a-long-unique-password" \ --root "$HOME/Software" ``` 默认绑定地址为 `127.0.0.1`。仅在受信任的 LAN 或 VPN 中使用 `0.0.0.0`。如果未同时提供用户名和密码，bridge 将拒绝非环回地址的绑定。 #### 配置应用程序 1. 在**设置 (Settings)** 中，选择 **Oh My Pi (bridge)**。 2. 输入计算机的 LAN 或 VPN 地址，端口 `4097`，以及相同的 Basic Auth 凭据。 3. 选择**测试连接 (Test connection)**。状态正常的 bridge 会报告已安装的 OMP 版本。 4. 创建或打开一个会话，然后发送一个 prompt。用户消息会立即显示，随后是流式的助手输出。 在配置应用程序之前，从主机验证 bridge： ``` curl --user "omp:use-a-long-unique-password" http://127.0.0.1:4097/v1/health ``` 预期响应： ``` {"healthy":true,"backend":"omp","version":"…"} ``` 当 ACP 提供时，OMP 会话会暴露其配置的模型，并且模型更改将应用于后续的 prompt。Agent 选择、持久的会话重命名/删除、server slash 命令以及 VCS/diff 被刻意设为不可用。 在 agent 仍在工作时发送的 prompt 会被排队而不是被拒绝：它会直接显示在对话中，并在当前轮次结束时运行。停止会话将丢弃仍在排队的任何内容。 会话标题来自您在应用程序中为会话指定的名称，否则将使用其第一个 prompt；在应用程序之外创建的会话列为 `OMP session `，因为 OMP 会话列表不包含标题。 #### `--root` 的限制范围 `--root` 限制了 bridge 自身的作用域：即应用程序可以浏览哪些目录 (`/file`, `/path`) 以及新会话可以使用哪个工作目录。它不是 agent 的沙箱。一旦会话开始运行，OMP 将以您的完整用户权限执行并批准其自身的工具调用，因此它可以像在桌面上一样在配置的根目录之外进行读写。请仅将 bridge 指向您已经允许 OMP 无人值守工作的机器和账户。 #### 浏览器访问 原生应用程序构建不需要 CORS 配置。如果要从浏览器使用该应用程序，请使用 `--cors` 列出每个确切的来源；该选项可重复使用，且默认情况下不允许任何来源。 ``` npx --yes ./bridge --port 4097 --username omp --password "…" --root "$HOME/Software" \ --cors http://localhost:5173 ``` #### 实时同步范围 对于通过该 bridge 启动的工作，bridge 会流式传输 `busy` 状态、助手数据块、todos 和完成状态。OMP ACP 不提供全局的跨客户端事件源或运行状态 API：由独立的桌面 OMP 或 harness 进程驱动的会话可以被列出并重新打开，但应用程序无法可靠地显示其真实的 `busy` 状态、思考气泡（thinking bubble）或增量输出。从应用程序发送的 prompt 会被记录并由 bridge 的 ACP 进程处理；它不会向另一个已经在运行的 agent 传输中注入消息。 请将 bridge 创建的会话用于由移动端驱动的工作。要在独立的 OMP 客户端之间实现可靠的实时观察和任务交接，需要 OMP 提供全局的会话事件/状态 API（或与宿主 harness 集成的中继）；bridge 不会读取 OMP 数据库来模拟此功能。 请勿将 bridge 直接暴露在互联网上。请使用 Tailscale、其他 VPN 或 TLS 终结反向代理 (reverse proxy)，并仅向需要该端口的网络开放端口 `4097`。 ## 本地运行 (Web) ``` cd web npm install npm run dev ``` 从您的浏览器（或处于同一局域网的手机）打开显示的 URL。 ## Android APK 构建（云端，无需本地 SDK） 1. 推送到 `main` 分支以运行构建和回归检查，并上传 debug/release APK 制品。 2. 在检查和设备冒烟测试成功后创建 `v*` 标签；这将发布一个 GitHub Release。 3. 从 GitHub Actions 下载 `harness-remote-debug-apk-v` 进行安装测试。 要发布签名的 release APK (`app-release-signed.apk`)，请配置以下 GitHub 仓库 secret： - `ANDROID_KEYSTORE_BASE64` - `ANDROID_KEYSTORE_PASSWORD` - `ANDROID_KEY_ALIAS` - `ANDROID_KEY_PASSWORD` 如果缺少任何签名 secret，已打标签的发布会失败，而不是发布未签名的 APK。该工作流会构建 Web 应用程序，运行 Web 和 bridge 回归测试，同步 Capacitor 以及原生实时事件，构建 Android 制品，并验证 APK 签名。 ## 手动 Android 打包（可选） ``` cd web npm run build npx cap add android npx cap sync android ``` 如果您想要进行本地原生调试，请在 Android Studio 中打开 `web/android`。 ## 应用程序配置 使用您的 server 值： - Host（主机）：计算机的局域网 IP（例如 `192.168.1.20`） - Port（端口）：`4096` - Username/password（用户名/密码）：用于启动 OpenCode server 的 Basic Auth 凭据 该应用程序不仅限于局域网。如果您的网络路由 (NAT/防火墙) 和安全设置配置正确，您也可以通过 WAN/VPN 使用它。 ## 使用的主要 Endpoints - `/global/health` - `/session`, `/session/status`, `/session/:id` - `/session/:id/message`, `/session/:id/command`, `/session/:id/abort` - `/session/:id/todo`, `/session/:id/diff` ## 贡献 设置、CI 预期的检查、回归套件的工作方式，以及每一次更改都必须在一个以上的 harness 上保持稳定的规则，全部记录在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。 [#36](https://github.com/giuliastro/harness-remote/issues/36) (PI 支持) 已开放且无人认领。 ## 贡献者

标签：AI编程助手, Capacitor, MITM代理, React, Syscalls, TypeScript, 安全插件, 桌面应用, 移动端应用, 自动化攻击, 跨平台, 远程控制