@skylandnpm/octopus-proxy 0.1.74 → 0.1.76

package/README.md

@@ -2,10 +2,50 @@
 
 **Embodied Dots** 意为**具身智能体节点**，是连接远程主机与智能体工作空间的节点。Taskhub 和 Claw 的菜单和列表使用复数 Dots，单个节点及其设置使用单数 Dot；接口字段 `botId`、CLI 参数 `--bot-id` 和数据库表 `hub_bots` 保持不变，已有节点和凭据可继续使用。
 
-Octopus Proxy 是运行在 macOS 或 Linux 主机上的 Octopus 代理，提供 `octopus-proxy` 命令来初始化配置、安装系统服务和检查运行状态。需要 Node.js 22 或更高版本。
+Octopus Proxy 可运行在 macOS、Linux 和 Windows 主机上，需要 Node.js 22 或更高版本。macOS 和 Linux 支持系统服务；Windows x64 从已登录的本机桌面前台运行。
 
 ## 安装
 
+### 一键检查和安装
+
+在仓库根目录运行以下脚本。脚本会先探测本机程序的版本，Git、OpenSSL、Node.js 22（含 npm）、OpenCode 2.0.19 和 Octopus Proxy 符合要求时会显示 `already installed` 或已安装版本并跳过安装。首次安装 Proxy 使用 npm 的 `@latest`。OpenCode 固定为 `2.0.19`，与[当前适配器的兼容基线](../../docs/opencode-compatibility.md)一致。
+
+Linux 或 WSL（x64 / ARM64）
+
+```bash
+./scripts/installer/install-octopus-tools.sh
+```
+
+脚本以当前用户安装。安装完成后执行脚本输出的 `export`，将检测到的工具目录加入 PATH。也可把该命令写入 shell 启动文件。安装需要 `flock`，自动下载的 Node.js 需要 glibc 及 `curl`、`tar`、`sha256sum`。Alpine 等 musl 发行版可先通过发行版软件源安装 Node.js 22 和 npm，再运行脚本。Proxy 的 `node-pty` 依赖在 Linux 上需要 Python 3、`make` 和 C/C++ 编译器，Debian、Ubuntu 或 WSL 的 Ubuntu 可用 `sudo apt install python3 build-essential` 安装。如果脚本安装了 Proxy，运行 `NPM_CONFIG_PREFIX="$HOME/.local/share/octopus-tools/npm" octopus-proxy update` 可用 CLI 更新这份安装。
+
+更新 PATH 后，运行 `octopus-proxy onboard --tool opencode` 配置 Proxy。
+
+缺少 Git 或 OpenSSL 时，脚本使用系统已配置的软件源，通过 `apt-get`、`dnf`、`yum`、`zypper`、`pacman` 或 `apk` 安装。普通用户安装这两个系统工具时会调用 `sudo`。
+
+Windows（x64 / ARM64）
+
+以管理员身份打开 PowerShell，从仓库根目录运行安装脚本。脚本会复用系统 PATH 中版本符合要求的工具，也会检查本机的 Program Files 安装目录。安装缺少的工具时使用 `%ProgramFiles%\Octopus\Tools`。脚本将所选工具的目录加入系统 PATH，供本机所有用户使用。 [Windows 环境变量作用域](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables)
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\installer\install-octopus-tools.ps1
+```
+
+用 Windows 自带的 `powershell.exe` 启动。若系统缺少 PowerShell 7（`pwsh.exe`），脚本会以自身所在目录为基准，优先查找 `PowerShell-7.6.9-win-x64.zip` 或 `PowerShell-7.6.9-win-arm64.zip`，从任意工作目录启动都适用。将对应架构的 ZIP 与脚本一起复制到目标 Windows 主机即可使用本地包。脚本校验 SHA-256 后解压到 `%ProgramFiles%\Octopus\Tools\powershell`，再继续安装其余工具。
+
+本地包缺失或无法通过校验时，脚本会在线下载。可将 `OCTOPUS_POWERSHELL_MIRROR` 设为镜像基址，脚本会拼接 `v7.6.9/PowerShell-7.6.9-win-<架构>.zip`。镜像下载或校验失败时回退到官方源。 [PowerShell 7.6.9 官方发行页](https://github.com/PowerShell/PowerShell/releases/tag/v7.6.9)
+
+缺少 Git 时，脚本优先使用同目录下的 `MinGit-2.56.1-64-bit.zip` 或 `MinGit-2.56.1-arm64.zip`。本地包缺失或校验失败时，从国内镜像下载，失败后回退到 Git for Windows 官方源。可用 `OCTOPUS_GIT_MIRROR` 指定包含 `v2.56.1.windows.1/` 的镜像基址。校验通过后，脚本将 MinGit 安装到 `%ProgramFiles%\Octopus\Tools\git`。 [Git for Windows 2.56.1 官方发行页](https://github.com/git-for-windows/git/releases/tag/v2.56.1.windows.1)
+
+缺少 OpenSSL 时，脚本优先校验并使用同目录下的 `OpenSSL-3.5.9-win-x64.zip` 或 `OpenSSL-3.5.9-win-arm64.zip`，用 PowerShell 的 `Expand-Archive` 安装到 `%ProgramFiles%\Octopus\Tools\openssl`。如果系统级 `OPENSSL_CONF` 尚未设置，脚本会配置它，供 Proxy 生成主机证书。ZIP 缺失或校验失败时，脚本会查找或下载 Git for Windows 的上游包，先用 XZ Utils 解压，再交给 Windows 的 `tar.exe`。可用 `OCTOPUS_OPENSSL_MIRROR` 指定保留相同发行标签子目录的上游包镜像。 [Git for Windows OpenSSL x64](https://github.com/git-for-windows/pacman-repo/releases/tag/2026-09-30T09-24-18.347486000Z) · [ARM64](https://github.com/git-for-windows/pacman-repo/releases/tag/2026-09-30T10-08-42.867521900Z) · [XZ Utils](https://github.com/tukaani-project/xz/releases/tag/v5.8.4)
+
+安装完成后新开终端即可读取更新的系统 PATH。支持 Windows 远控的 Proxy 版本可直接在原生 Windows x64 执行 `octopus-proxy onboard` 和 `octopus-proxy run`，详见[主机安装与配对](../../docs/claw-remote-desktop.md#windows-被控主机)。脚本安装的 npm 版本需要包含此功能。
+
+只检查版本时，Linux 追加 `--check`，Windows 追加 `-Check`。Windows 从系统 PATH 检查各工具，包含 PowerShell 7，检查时无需管理员权限。任何一项缺失或版本不符时返回退出码 `1`。
+
+Node.js 和 npm 默认使用 `https://npmmirror.com/mirrors/node` 和 `https://registry.npmmirror.com`，下载或安装失败时回退到官方源。可通过 `OCTOPUS_NODE_MIRROR` 和 `OCTOPUS_NPM_REGISTRY` 为本次运行指定源。Node.js 压缩包按官方 SHA-256 校验，npm 源设置仅用于本次安装。
+
+### 手动安装
+
 ```sh
 npm install -g @skylandnpm/octopus-proxy@latest --prefer-online --registry https://registry.npmjs.org
 octopus-proxy help
@@ -14,11 +54,11 @@ octopus-proxy onboard
 octopus-proxy identity
 ```
 
-向导默认安装服务；使用 `--no-install-service` 时，之后运行 `octopus-proxy install`。安装和重装会保留原主机密钥。`--prefer-online` 会让 npm 在安装时重新校验 registry 中的包元数据，避免本地缓存使 `@latest` 仍指向旧版本，不再需要先运行 `npm view @skylandnpm/octopus-proxy versions`。如果升级后 `octopus-proxy version` 仍显示旧版本，运行 `command -v npm`、`npm prefix -g` 和 `command -v octopus-proxy`，确认 npm 的全局安装目录与实际执行的命令属于同一套 Node.js 环境；使用 NVM 与 Homebrew 时尤其要检查这一点。
+在 macOS 和 Linux 上，向导默认安装服务；使用 `--no-install-service` 时，之后可运行 `octopus-proxy install`。在 Windows 上，完成向导后先运行 `octopus-proxy run`，再从另一个终端执行 `octopus-proxy identity`。安装和重装会保留原主机密钥。`--prefer-online` 会让 npm 在安装时重新校验 registry 中的包元数据，避免本地缓存使 `@latest` 仍指向旧版本，不再需要先运行 `npm view @skylandnpm/octopus-proxy versions`。如果升级后 `octopus-proxy version` 仍显示旧版本，运行 `command -v npm`、`npm prefix -g` 和 `command -v octopus-proxy`，确认 npm 的全局安装目录与实际执行的命令属于同一套 Node.js 环境；使用 NVM 与 Homebrew 时尤其要检查这一点。
 
 向导默认使用 `https://octopus.wuyehao.com` 作为 Hub 地址；按需可输入其他地址，或用 `--hub-url` 指定。再次运行向导时会读取现有配置，直接回车即可保留各项设置；Dot Secret 只提示已配置，不在终端显示原值。macOS 上选择编码工具时，向导优先显示已配置或探测到的命令路径，否则给出该工具的 macOS 路径示例；回车后会检查文件可执行性并运行版本命令，失败时要求重新输入。无交互环境可使用 `octopus-proxy onboard --non-interactive`，未提供 `--hub-url` 时也使用该默认地址；完整选项见 `octopus-proxy help`。安装服务后可运行 `octopus-proxy status` 和 `octopus-proxy doctor` 检查状态。
 
-Proxy 主动连接 Hub 的 `/ws/proxy-chat`，无需开放入站端口或安装 sshd。Claw 经 `/ws/claw-chat` 建立到 Proxy 的内层 TLS 1.3 会话；Hub 只转发加密字节。首次打开工作区显示主机公钥指纹；核对后点击 Trust，未授权设备还需输入主机终端生成的配对码。Proxy 校验设备签名、配对码及主机密码并持久化设备授权，Claw 在认证成功后按 Hub 地址和 Dot ID 固定指纹；之后指纹变化会拒绝连接。每次连接都要输入运行 Proxy 服务账号的主机密码，由主机上的 PAM（Linux）或 Open Directory（macOS）验证。断线或连续 60 分钟没有用户操作后需要重新认证。服务安装时生成主机身份，`octopus-proxy identity` 显示指纹并生成 3 天内有效、最多可成功配对 10 次的配对码。安装主机需提供 OpenSSL 和 C 编译器；Linux 还需 PAM 开发头文件。Dot Secret 仅用于 Hub 路由，不能单独授权工作区。
+Proxy 主动连接 Hub 的 `/ws/proxy-chat`，无需开放入站端口或安装 sshd。Claw 经 `/ws/claw-chat` 建立到 Proxy 的内层 TLS 1.3 会话；Hub 只转发加密字节。首次打开工作区显示主机公钥指纹；核对后点击 Trust，未授权设备还需输入主机终端生成的配对码。Proxy 校验设备签名、配对码及主机密码并持久化设备授权，Claw 在认证成功后按 Hub 地址和 Dot ID 固定指纹；之后指纹变化会拒绝连接。每次连接都要输入运行 Proxy 服务账号的主机密码，由主机上的 PAM（Linux）、Open Directory（macOS）或 Windows 账户认证验证。断线或连续 60 分钟没有用户操作后需要重新认证。服务安装时生成主机身份，`octopus-proxy identity` 显示指纹并生成 3 天内有效、最多可成功配对 10 次的配对码。安装主机需提供 OpenSSL；macOS 和 Linux 还需 C 编译器，Linux 另需 PAM 开发头文件。Windows 使用系统的 .NET Framework 编译辅助程序。Dot Secret 仅用于 Hub 路由，不能单独授权工作区。
 
 macOS 12.3 及以上运行 `octopus-proxy onboard` 时，配置保存后、服务启动前会准备截屏辅助程序并申请系统屏幕录制权限；已授权时不会重复弹窗。交互模式和 `--non-interactive` 均执行此步骤，`--no-install-service` 也会申请。请在系统弹窗中允许访问；拒绝、超时或辅助程序编译失败时，向导提示原因与授权路径，并继续初始化。在“系统设置 → 隐私与安全性 → 屏幕录制（或屏幕与系统音频录制）”中应授权弹窗显示的实际程序，可能是 Terminal、iTerm、编辑器或 node，不保证出现 `octopus-desktop-capture`。onboard 和 doctor 会显示辅助程序路径，文件名不等于系统授权名称。终端授权不代表后台服务已授权，需在 Claw 点击截屏，让实际服务申请权限，按实际名称授权后重启 Proxy。Linux 没有通用的截屏授权弹窗，需使用桌面用户的图形会话环境；平台依赖与设置见[桌面快照说明](../../docs/claw-desktop-snapshots.md)。
 
@@ -35,6 +75,8 @@ octopus-proxy doctor
 octopus-proxy restart
 ```
 
+Windows 上，Claw 的项目终端使用 `ComSpec` 指向的本机可执行文件，找不到时使用 `%SystemRoot%\System32\cmd.exe`。无需设置 `SHELL`。若看到 `/bin/sh` 报错，请更新 Windows 主机上的 Proxy，并从本机终端重新运行 `octopus-proxy run` 后在 Claw 新建终端。
+
 Claw 新建终端时若出现 `posix_spawnp failed.`，错误来自 Proxy 主机上的 PTY 启动。`node-pty 1.1.0` 的 macOS 预编译 `spawn-helper` 存在安装后缺少执行权限的[上游问题](https://github.com/microsoft/node-pty/issues/850)；同一 macOS 版本的两台电脑也可能因安装方式、CPU 架构和安装目录不同而只有一台失败。
 
 Proxy 在新建终端前检查实际加载的辅助程序，并自动补齐缺失的执行权限。`octopus-proxy doctor` 会显示辅助程序路径及当前 Node 架构，`doctor --fix` 可修复权限；检查独立于配置是否有效。若安装目录不允许当前账号修改，诊断会提示由安装账号修复或重新安装，不会自动提权。辅助程序缺失需重新安装；权限正常仍失败时，终端错误会显示 shell、工作目录、辅助程序路径和 Node 版本，供进一步核查。诊断应在发生错误的 Proxy 主机、同一 Node 安装环境下运行，之后执行 `octopus-proxy restart` 并在 Claw 新建终端。
@@ -115,13 +157,15 @@ octopus-proxy onboard --tool pi
 
 ## 更新
 
-在交互式终端中运行：
+macOS 和 Linux 上可运行：
 
 ```sh
 octopus-proxy update
 ```
 
-命令通过 `npm view @skylandnpm/octopus-proxy@latest version` 查询最新版本。存在新版本时，输入 `y` 或 `yes` 确认覆盖安装；直接回车或输入其他内容会取消。确认后使用 npm 全局安装查到的版本，校验安装版本成功后才重启已安装的服务，并检查运行状态后反馈结果。安装期间不会主动停止服务。配置、主机身份和已有服务定义会保留；未安装服务时仅更新 npm 包。
+命令通过 `npm view @skylandnpm/octopus-proxy@latest version` 查询最新版本。存在新版本时，输入 `y` 或 `yes` 确认覆盖安装；直接回车或输入其他内容会取消。脚本中可使用 `octopus-proxy update -y`（或 `--yes`），发现新版本就直接安装，无需交互终端。当前版本已是最新或高于 npm 最新版本时，不安装也不重启服务。
+
+命令使用 npm 全局安装查到的版本，校验安装版本成功后才重启已安装的服务，并检查运行状态后反馈结果。安装期间不会主动停止服务。配置、主机身份和已有服务定义会保留；未安装服务时仅更新 npm 包。Windows 请先停止前台 Proxy，通过 npm 更新后再运行 `octopus-proxy run`。
 
 安装或版本校验失败时不会触发服务重启；包安装失败不保证旧版本文件完整保留。已安装新版本但重启失败时会单独提示，可运行 `octopus-proxy doctor` 和 `octopus-proxy logs` 排查。此命令用于 npm 全局安装，覆盖安装前会检查 npm 安装目录是否与当前命令一致；源码、本地安装或 Node.js 环境不一致时会中止并给出提示。