Update deployment prerequisites and current guide

DEPLOY.zh.md

@@ -0,0 +1,224 @@
+# GPA policy 部署与启动（含冻结经验与运行环境）
+
+更新：2026-09-18。本仓库根目录的 `DEPLOY.zh.md` 是最新部署说明；若压缩包内 `START.zh.md` 未包含系统 Python 的 `websockets` 安装检查，以本文为准。
+
+官方 RoboDojo 环境已经就绪。本说明只启动 GPA 的代理、账号池、OpenWAM、policy WebSocket 和看板，不安装、不启动、不修改官方环境。
+
+## 1. 解压与依赖
+
+在 policy 服务器执行，替换所有 `/path/to`：
+
+```bash
+umask 077
+export PACKAGES=/path/to/packages
+export RUNTIME_PARENT=/path/to/gpa-runtime
+export PRIVATE_PARENT=/path/to/gpa-secrets
+mkdir -p "$RUNTIME_PARENT" "$PRIVATE_PARENT"
+tar -xzf "$PACKAGES/GPA-XPolicyLab-runtime.tar.gz" -C "$RUNTIME_PARENT"
+tar -xzf "$PACKAGES/GPA-private-config.tar.gz" -C "$PRIVATE_PARENT"
+export GPA_ROOT="$RUNTIME_PARENT/XPolicyLab/policy/GPA"
+export GPA_PRIVATE_ROOT="$PRIVATE_PARENT/private-runtime"
+chmod -R go-rwx "$GPA_PRIVATE_ROOT"
+```
+
+运行时包包含 XPolicyLab checkout、GPA 代码、cursor step 58000 权重，以及 42 个任务的完整 A→B 对话链和冻结 task skill。私有包包含代理、账号凭据、邮件配置和看板密码，始终放在 XPolicyLab 外。不要用解压内容覆盖官方已有的 XPolicyLab。
+
+policy 主机需要 Linux x86_64、兼容的 NVIDIA 驱动、ffmpeg、tmux、curl。不需要在 policy 主机安装仿真器。
+
+**启动账号服务和 agent 前，先给系统 Python 安装 `websockets`。** agent 的 shell 可能直接调用 `python` / `python3`；仅在 policy 环境里安装不够。包名为 `websockets`，不要安装成 `websocket` 或 `websocket-client`。
+
+```bash
+python3 -m pip install 'websockets>=14'
+python3 -c 'import sys; from websockets.asyncio.client import connect; print(sys.executable, "websockets OK")'
+# 若 agent 使用 python，也检查该命令对应的解释器。
+if command -v python >/dev/null 2>&1; then
+  python -c 'from websockets.asyncio.client import connect' || python -m pip install 'websockets>=14'
+  python -c 'import sys; from websockets.asyncio.client import connect; print(sys.executable, "websockets OK")'
+fi
+```
+
+如果 pip 提示 `externally-managed-environment`，需由机器管理员按该系统的软件包管理规则安装；导入检查通过后再启动账号服务。需要 NumPy、SciPy、Pillow、OpenCV 的完整 harness 脚本仍使用下面配置的 `$POLICY_ENV/bin/python`；不要引用历史服务器上的 Python 路径。
+
+公共仓库另附 `envs/gpa-policy-python.tar.gz` 与 `envs/node-codex.tar.gz`，下载到 `$PACKAGES` 后解压：
+
+```bash
+export GPA_ENV_ROOT=/path/to/gpa-envs
+mkdir -p "$GPA_ENV_ROOT/policy" "$GPA_ENV_ROOT/node-codex"
+tar -xzf "$PACKAGES/gpa-policy-python.tar.gz" -C "$GPA_ENV_ROOT/policy"
+tar -xzf "$PACKAGES/node-codex.tar.gz" -C "$GPA_ENV_ROOT/node-codex"
+export POLICY_ENV="$GPA_ENV_ROOT/policy"
+export PATH="$GPA_ENV_ROOT/node-codex/node/bin:$PATH"
+"$POLICY_ENV/bin/python" "$POLICY_ENV/bin/conda-unpack"
+# 首次部署时创建；已有 node_modules 则先确认来源，不覆盖。
+ln -s "$GPA_ENV_ROOT/node-codex/node_modules" "$GPA_ROOT/node_modules"
+cd "$GPA_ROOT"
+npm run build
+"$POLICY_ENV/bin/python" -m pip install --no-index --no-deps --no-build-isolation -e third_party/OpenWAM
+"$POLICY_ENV/bin/python" -c 'import torch; print(torch.__version__, torch.cuda.is_available())'
+```
+
+最后一行应显示 CUDA 可用。Python 包用 conda-pack 重定位；OpenWAM 的可编辑安装重新指向解压后的源码。Node/Codex 包包含 Node、npm 和已锁定的 node_modules。冻结经验随 policy 包位于 `experience/`，不需要旧机器上的目录。历史全量实验录像、GT 数据集和 RoboDojo 仿真环境不包含在内。
+
+## 2. 保存 policy 配置
+
+把以下内容保存为 `$GPA_PRIVATE_ROOT/env.local.sh`，每个终端先 source：
+
+```bash
+export GPA_ROOT=/path/to/gpa-runtime/XPolicyLab/policy/GPA
+export GPA_ENV_ROOT=/path/to/gpa-envs
+export POLICY_ENV="$GPA_ENV_ROOT/policy"
+export GPA_PRIVATE_ROOT=/path/to/gpa-secrets/private-runtime
+export GPA_ACCOUNTS_ROOT="$GPA_PRIVATE_ROOT/accounts"
+export GPA_MAIL_CONFIG="$GPA_ACCOUNTS_ROOT/.notifications/mail.json"
+export GPA_EXPERIENCE_ROOT="$GPA_ROOT/experience"
+export GPA_DATA_ROOT=/path/to/large-disk/gpa-output
+export GPA_RUN_ROOT="$GPA_DATA_ROOT/eval-001"
+export GPA_DEPLOYMENT_CONFIG="$GPA_PRIVATE_ROOT/deployment.json"
+export GPA_POLICY_URLS='http://127.0.0.1:19650'
+export http_proxy=http://127.0.0.1:7890
+export https_proxy="$http_proxy"
+export NO_PROXY=localhost,127.0.0.1
+export no_proxy="$NO_PROXY"
+export PATH="$POLICY_ENV/bin:$GPA_ENV_ROOT/node-codex/node/bin:$GPA_ROOT/node_modules/.bin:$PATH"
+export PYTHONPATH="$GPA_ROOT/python:$GPA_ROOT/third_party/OpenWAM:$GPA_ROOT/../..:${PYTHONPATH:-}"
+```
+
+```bash
+source "$GPA_PRIVATE_ROOT/env.local.sh"
+mkdir -p "$GPA_RUN_ROOT"
+cd "$GPA_ROOT"
+"$POLICY_ENV/bin/python" scripts/configure.py \
+  --out "$GPA_DEPLOYMENT_CONFIG" --data-root "$GPA_DATA_ROOT" \
+  --python "$POLICY_ENV/bin/python"
+```
+
+迁移后重新 configure，不直接沿用私有包 `cursor-runtime.json` 中旧机器的路径。每任务读取对应冻结 B context 和 task skill；评测期间 skill 不变，不做轮后总结。新实验使用新的 `GPA_RUN_ROOT`。
+
+## 3. 代理与账号池
+
+分别在独立 tmux 会话中执行；Ctrl-B、D 可脱离会话，保持服务运行。已有 7890 代理可直接复用。
+
+```bash
+tmux new -s gpa-proxy
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+"$GPA_PRIVATE_ROOT/clash/mihomo" -d "$GPA_PRIVATE_ROOT/clash" \
+  -f "$GPA_PRIVATE_ROOT/clash/config.yaml"
+```
+
+另一个终端检查代理及一次真实模型调用：
+
+```bash
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+curl --proxy "$http_proxy" --connect-timeout 15 --max-time 30 -I https://auth.openai.com
+# 将 pro-01 换成已登录槽位。
+CODEX_HOME="$GPA_ACCOUNTS_ROOT/pro-01" codex -c 'cli_auth_credentials_store="file"' login status
+CODEX_HOME="$GPA_ACCOUNTS_ROOT/pro-01" codex exec \
+  --ignore-user-config --ephemeral --sandbox read-only --skip-git-repo-check \
+  -m gpt-6-astra -c 'model_reasoning_effort="low"' \
+  -c 'service_tier="default"' -c 'features.fast_mode=false' \
+  '不要联网、读取文件或调用工具。只回复：你好。'
+```
+
+只启动一个共享账号监控器：
+
+```bash
+tmux new -s gpa-accounts
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+cd "$GPA_ROOT"
+"$POLICY_ENV/bin/python" python/account_pool.py monitor
+```
+
+最多 50 个账号，按周剩余额度加权分配；低于 3% 不接新任务，每号最多 16 workers。额度查询失败重试三次、间隔一分钟。账号服务使用本机 19901–19950。新 episode 和故障接管执行已有 Gemini 准入检查，当前要求回答 `3.1`；这是指定的启发式门槛，不是可靠的模型能力鉴定。不要同时运行使用同一批复制凭据的旧部署。
+
+## 4. 启动共享 OpenWAM
+
+```bash
+tmux new -s gpa-model
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+cd "$GPA_ROOT"
+"$POLICY_ENV/bin/python" scripts/start-cursor-models.py \
+  --config "$GPA_DEPLOYMENT_CONFIG" --out "$GPA_RUN_ROOT/models" \
+  --gpus 0 --port 19650 --run
+```
+
+看到 `READY` 后，在另一终端检查：
+
+```bash
+curl --noproxy '*' -fsS http://127.0.0.1:19650/health
+```
+
+应为 `ready`、`cursor`、step 58000 checkpoint。每张模型卡独立排队，最大 batch 8。多副本用 `--gpus 0,1`，端口为 19650、19651，并将 `GPA_POLICY_URLS` 改成两个 URL、以空格分隔；全部副本是同一个 cursor 模型。
+
+## 5. 启动 policy WebSocket
+
+单端口启动：
+
+```bash
+tmux new -s gpa-policy-19660
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+cd "$GPA_ROOT"
+"$POLICY_ENV/bin/python" stage-c/multi_policy.py \
+  --port 19660 --out "$GPA_RUN_ROOT/port-19660" \
+  --config "$GPA_DEPLOYMENT_CONFIG" --experience-root "$GPA_EXPERIENCE_ROOT" \
+  --xpolicylab "$GPA_ROOT/../.." --policy-urls $GPA_POLICY_URLS
+```
+
+这只启动 policy，监听 `ws://127.0.0.1:19660`。每端口最多 10 个环境 ID，分别对应独立对话、动作队列、恢复状态和 debug 目录；任务由官方 instruction 自动识别。
+
+若使用 8 个端口 × 每端口最多 10 环境，用下面命令替代单端口启动，避免重复占用端口：
+
+```bash
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+for port in $(seq 19660 19667); do
+  tmux new-session -d -s "gpa-policy-$port" \
+    "source '$GPA_PRIVATE_ROOT/env.local.sh'; cd '$GPA_ROOT'; exec '$POLICY_ENV/bin/python' stage-c/multi_policy.py --port $port --out '$GPA_RUN_ROOT/port-$port' --config '$GPA_DEPLOYMENT_CONFIG' --experience-root '$GPA_EXPERIENCE_ROOT' --xpolicylab '$GPA_ROOT/../..' --policy-urls $GPA_POLICY_URLS"
+done
+```
+
+19660–19667 共享模型副本和账号监控器；不同端口的相同环境 ID 不冲突。80 环境协议隔离有合成测试，不代表已经完成 80 个真实环境的性能压测。
+
+官方接入只需以下信息：
+
+- policy 名称 `GPA`，使用官方 WS 协议、`arx_x5`、`ee` 动作格式。
+- 将包内 `policy/GPA/deploy.py`、`deploy.yml`、`__init__.py` 放入官方现有 XPolicyLab 的 `policy/GPA/`，由其现有评测入口加载，并配置约定的 host/port。无需替换官方仓库。
+- 使用 GPA `deploy.py` 的异步 batch 适配；每个环境独立连接和请求，不等待整批对话返回。
+- policy 默认仅监听回环地址。跨机器时用约定的 SSH 隧道转发，例如在 policy 主机执行下面命令，把对端 6320 转发到本机 19660。占位值需先替换；其余端口同理。
+
+```bash
+ssh -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes \
+  -R 127.0.0.1:6320:127.0.0.1:19660 \
+  -p SSH_PORT -i /path/to/tunnel_key SSH_USER@SSH_HOST
+```
+
+公网看板与 policy WebSocket 是两个独立接口。
+
+## 6. 看板与新增账号
+
+```bash
+tmux new -s gpa-dashboard
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+cd "$GPA_ROOT"
+bash scripts/public-dashboard.sh
+```
+
+启动 policy 不会自动开放公网；运行上面的脚本才开启公网看板。URL 在 `$GPA_RUN_ROOT/dashboard/tunnel.log`，用户名/密码在 `$GPA_PRIVATE_ROOT/dashboard-access.json`。回环入口是 18780，公网隧道接入带认证的 18781；不要直接公开 18780。Quick Tunnel 重启后 URL 可能变化。
+
+看板每 15 秒刷新任务、截图、已执行录像和公开对话/工具日志，每 10 分钟读取额度快照。“新增账号”显示设备码、登录链接和登录结果；“刷新该次登录”结束旧的未完成登录，重新生成设备码，不覆盖已登录凭据。
+
+凭据只写入私有账号目录。监控器约每分钟发现新账号并查询额度；下一轮选号经过 Gemini 检查后参与调度，不中断现有对话。公网登录写接口要求看板认证和同源请求。
+
+## 7. 检查、日志与停止
+
+```bash
+source /path/to/gpa-secrets/private-runtime/env.local.sh
+cd "$GPA_ROOT"
+"$POLICY_ENV/bin/python" tests/check_async_xpolicylab.py
+python3 tests/test_dashboard_login.py
+"$POLICY_ENV/bin/python" python/account_pool.py status
+curl --noproxy '*' -fsS http://127.0.0.1:18780/api/status
+tmux ls
+```
+
+两项脚本检查不调用 Astra；合成测试不代表成功率。实际观测、动作、state、视频、对话和恢复记录按端口、环境、episode 写入 `$GPA_RUN_ROOT/port-*/env-*/`。没有明确官方结果时不把断开连接当作成功。
+
+停止单个 policy：`tmux attach -t gpa-policy-19660` 后 Ctrl-C。全部停止时依次停止 policy、model、dashboard、accounts、proxy 会话，保留结果目录。