oasis7 docs

Viewer Manual

oasis7 Viewer 使用手册

当前仓库仅保留 `viewer` 作为正式 Viewer Web 入口；`software_safe` 只作兼容 alias；本页覆盖启动、闭环验证与常见排查。

本地真实 LLM 游戏测试

仓库 Viewer 手册提供日常预览与 Viewer/debug 指引；干净 checkout 的完整首次启动流程尚未验证。此 preset 需要已有构建与可用的 provider 配置，默认复用已有构建，不能作为零配置启动命令。请运行 ./scripts/run-local-letai-game-test.sh --help-all 查看受支持的配置文件与代理选项；真实模型调用可能产生 provider 费用。

./scripts/run-local-letai-game-test.sh --local-world-playtest

本地真实 LetAI provider-backed 游戏试玩统一从该 preset 启动。它会处理 token config、provider bridge、launcher/runtime/viewer/local-standalone-chain 启动与日常试玩端口 48420/48421/48422；它不连接 formal/public testnet。脚本输出的 GAME_URL 是手工试玩和 agent-browser 留证入口。

不要把裸 run-viewer-web.sh 当作本地真实 provider-backed gameplay 启动方式；它只属于下方 Viewer/debug 闭环。

底层 Viewer Debug 快速开始

1) 启动 live server

env -u RUSTC_WRAPPER cargo run -p oasis7 --bin oasis7_viewer_live -- llm_bootstrap --allow-debug-scenario --llm --bind 127.0.0.1:5023 --web-bind 127.0.0.1:5011

该路径仅用于 Viewer/debug；若显式改用 --no-llm，只允许 observer/debug。

2) 启动 Web Viewer

env -u NO_COLOR ./scripts/run-viewer-web.sh --address 127.0.0.1 --port 4173

访问：http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011

当前只保留 viewer 单一正式入口；software_safe 只保留兼容别名，不再维护其他 Viewer surface 或旧本地 Viewer 入口。

Web 闭环

推荐直接使用 repo 内置脚本：

默认采证使用上方 release/UI 服务：即使带 test_api=1，也不安装 __AW_TEST__。需要语义测试 API 时，先准备 Viewer 的 Node/Rust/WASM 构建依赖，另在独立终端构建并服务隔离测试产物：

npm --prefix crates/oasis7_viewer run build:viewer:visual-test && \
python3 -m http.server 4174 --bind 127.0.0.1 --directory crates/oasis7_viewer/.viewer-test-dist

下方脚本默认 release；测试服务就绪后，才在采证终端设置 export VIEWER_CAPTURE_MODE=visual-test。不要用 run-viewer-web.sh 代替测试产物服务，也不要将 .viewer-test-dist 当 release 发布。test_api=1 只是测试构建的额外 opt-in，不会改变 release 构建、授予玩家权限或提供正式接入凭证。记录所选 profile、source/build 身份与 URL。

使用并通过 agent-browser 0.37.1 的 --version 验证，先运行 doctor --offline --quick --json；每轮创建 worktree-scoped named session，必要时用 session info/list --json 记录诊断，并只关闭本轮自有 session。

set -euo pipefail
VIEWER_CAPTURE_MODE="${VIEWER_CAPTURE_MODE:-release}"
case "$VIEWER_CAPTURE_MODE" in
  release) VIEWER_CAPTURE_PORT=4173 ;;
  visual-test) VIEWER_CAPTURE_PORT=4174 ;;
  *) echo "unknown VIEWER_CAPTURE_MODE: $VIEWER_CAPTURE_MODE" >&2; exit 2 ;;
esac
command -v agent-browser >/dev/null || { echo "missing agent-browser" >&2; exit 1; }
agent-browser --version
agent-browser doctor --offline --quick --json
AB_SESSION="$(agent-browser session id --scope worktree --prefix viewer)"
export AB_SESSION
mkdir -p output/playwright/viewer
VIEWER_EVIDENCE_DIR="$(mktemp -d "output/playwright/viewer/${AB_SESSION}.XXXXXX")"
cleanup() {
  local main_status=$?
  local close_status=0
  trap - EXIT INT TERM
  if agent-browser --session "$AB_SESSION" close >"$VIEWER_EVIDENCE_DIR/close.log" 2>&1; then
    close_status=0
  else
    close_status=$?
  fi
  if (( close_status != 0 )); then
    printf 'cleanup blocker: close_status=%s; see %s/close.log\n' "$close_status" "$VIEWER_EVIDENCE_DIR" >&2
  fi
  if ! printf 'main_status=%s\nclose_status=%s\n' "$main_status" "$close_status" >"$VIEWER_EVIDENCE_DIR/cleanup.status"; then
    printf 'could not write cleanup status\n' >&2
  fi
  if (( main_status != 0 )); then
    exit "$main_status"
  fi
  exit "$close_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
agent-browser --session "$AB_SESSION" --headed open "http://127.0.0.1:${VIEWER_CAPTURE_PORT}/viewer.html?ws=ws://127.0.0.1:5011&render_mode=viewer&test_api=1"
agent-browser --session "$AB_SESSION" wait --load domcontentloaded
if [[ "$VIEWER_CAPTURE_MODE" == "visual-test" ]]; then
  agent-browser --session "$AB_SESSION" wait --fn "typeof window.__AW_TEST__ === 'object'"
else
  agent-browser --session "$AB_SESSION" wait --fn "typeof window.__AW_TEST__ === 'undefined'"
fi
agent-browser --session "$AB_SESSION" session info --json | tee "$VIEWER_EVIDENCE_DIR/session-info.json"
agent-browser --session "$AB_SESSION" snapshot -i
if [[ "$VIEWER_CAPTURE_MODE" == "visual-test" ]]; then
  agent-browser --session "$AB_SESSION" eval "JSON.stringify(window.__AW_TEST__.getState())" | tee "$VIEWER_EVIDENCE_DIR/state.json"
fi
agent-browser --session "$AB_SESSION" console | tee "$VIEWER_EVIDENCE_DIR/console.log"
agent-browser --session "$AB_SESSION" screenshot "$VIEWER_EVIDENCE_DIR/viewer-web.png"

保留采样原失败码；采样成功但 close 失败则返回非零。当前目录的 close.log / cleanup.status 保存 cleanup blocker 诊断；close 非零不代表进程必然仍活着，只回收本轮 session。

最小采证标准：release/UI 页面可加载、__AW_TEST__ 不存在，并保留可见连接状态或明确 blocker 的截图与 console。visual-test 另要求显式构建及 opt-in 后 API 可用、getState().renderMode=viewer（或兼容 alias software_safe）并保留 state。页面加载或测试 API 可用不证明 renderer-ready、真实输入或正式玩法通过。

当前能力边界

常见问题排查