oasis7 docs

Viewer Manual

oasis7 Viewer 使用手册

覆盖启动方式、交互说明、自动聚焦、自动步骤、Web 闭环调试与常见问题，适用于 `oasis7_viewer` 联调与回归。

先跑起来 进入 Web 闭环 返回文档目录

快速开始

1) 启动 live server（推荐）

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

`oasis7_viewer_live` 当前默认走 LLM 模式；正式 gameplay 需要已配置且可连通的 LLM provider。

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

`--no-llm` 仅用于观战/调试；`gameplay_action/prompt/chat` 会直接返回 `llm_mode_required` 或 `llm_init_failed`，`step/play` 则会返回带 `Blocked + error_code/error_message` 的 `ControlCompletionAck`。

2) 启动 viewer

env -u RUSTC_WRAPPER cargo run -p oasis7_viewer -- 127.0.0.1:5023

3) 离线模式（不连服务端）

OASIS7_VIEWER_OFFLINE=1 env -u RUSTC_WRAPPER cargo run -p oasis7_viewer

4) 浏览器模式（Bevy + wasm）

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`。

5) 发行模式（P2P 推荐）

`oasis7_viewer_live` 当前为纯 Viewer live 服务，不再承载 `--release-config`、`--runtime-world` 与 `--node-*` 控制面参数。

P2P 发行建议使用 `oasis7_chain_runtime`（可由 `oasis7_game_launcher` / `oasis7_web_launcher` / `oasis7_client_launcher` 托管）锁定链参数，Viewer 仅保留 `--bind`、`--web-bind`、`--llm/--no-llm`；其中 `--no-llm` 只用于 observer/debug。

常用交互

自动聚焦（Auto Focus）

启动时可通过环境变量自动定位目标：

支持语法：`first_fragment`、`first_location`、`first_agent`、`location:<id>`、`agent:<id>`（兼容简写 `fragment/location/agent`）。

自动聚焦目标仅支持 Agent / Location / Fragment 三类。

自动步骤（Auto Select / Automation Steps）

./scripts/capture-viewer-frame.sh \
  --scenario llm_bootstrap \
  --addr 127.0.0.1:5131 \
  --auto-select-target first_agent \
  --automation-steps "mode=3d;focus=first_agent;zoom=0.8;select=fragment:frag-0"

Web 闭环（默认推荐）

前置要求

标准流程

终端 A：启动 live server。

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

默认链路要求 active LLM access；若显式切到 `--no-llm`，该 Web 路径只能用于 observer/debug 诊断，不计入正式可玩性证据。

终端 B：启动 Web Viewer。

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

终端 C：执行 agent-browser 闭环采样。

command -v agent-browser >/dev/null || { echo "missing agent-browser" >&2; exit 1; }
mkdir -p output/playwright/viewer
agent-browser --headed open "http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011&test_api=1"
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser eval "JSON.stringify(window.__AW_TEST__?.getState?.() ?? null)"
agent-browser console | tee output/playwright/viewer/console.log
agent-browser screenshot output/playwright/viewer/viewer-web.png
agent-browser close

注：产物目录当前沿用历史路径 output/playwright/viewer/。`render_mode` 默认为 auto：硬件 WebGL 正常时进入标准 Viewer；检测到 SwiftShader / software renderer / 无 WebGL 时会自动切到 software_safe。若要强制安全模式，可在 URL 后追加 &render_mode=software_safe。

`sendControl(\"step\")` 语义校验

可在浏览器控制台或 agent-browser evaluate 中执行以下调用，验证逐步推进生效：

window.__AW_TEST__.sendControl("step");
window.__AW_TEST__.sendControl("step", { count: 3 });
window.__AW_TEST__.sendPromptControl("preview", { agentId: "agent-0", shortTermGoal: "software-safe preview" });
window.__AW_TEST__.sendPromptControl("apply", { agentId: "agent-0", shortTermGoal: "software-safe apply" });
window.__AW_TEST__.sendAgentChat("agent-0", "hello from software_safe");
window.__AW_TEST__.getState();

当页面由 oasis7_game_launcher 提供并注入 viewer auth bootstrap 时，software_safe 还会开放选中 Agent 的最小 prompt/chat 控制面；对应自动化接口为 sendPromptControl(mode, payload) 与 sendAgentChat(agentId, message)。

Prompt Overrides 已改为默认收起的“高级 Prompt 设置”项；选中 Agent 后手动展开，才会显示 preview/apply/rollback 编辑表单。该开关会记住本地浏览器上一次的展开状态，但不影响 __AW_TEST__.sendPromptControl(...)。

输出目录与最小验收

native fallback（仅 Web 无法复现时）

./scripts/capture-viewer-frame.sh --scenario asteroid_fragment_detail_bootstrap --addr 127.0.0.1:5131 --viewer-wait 12 --auto-focus-target first_fragment --auto-focus-radius 18

常用增强参数：`--capture-max-wait`、`--no-prewarm`、`--keep-tmp`、`--auto-focus-keep-2d`。

右侧综合面板与 Chat 面板

模块显隐与本地缓存

选中详情面板

快速定位 Agent

全览图缩放切换（2D）

文本可选中/复制面板

UI 语言切换

推荐调试场景

开采损耗可视化

常见问题排查

参考文档

Fragment 元素分块渲染（默认开启）