OpenWord Player

Read references/session-runbook.md before running a session. Treat repository README.md as the source of truth for install/startup/API details, and re-check it when commands fail or look outdated.

Session Workflow

• Ask the user which mode to run before gameplay starts.

• Prepare runtime (download/install/start, browser, key setup).

• Branch to human-guided mode or AI REST mode.

• Keep the user involved during play, including AI-driven sessions.

Use this exact mode-selection question:

这局你想怎么进行：你自己玩（我引导）还是我用 REST API 代玩？

If the user does not choose, default to human-guided mode.

Runtime Preparation

• If repository does not exist locally, run: git clone https://github.com/dinghuanghao/openword.git

• Install and start: npm install

npm run dev

• Ensure browser opens http://127.0.0.1:30000 .

• Prompt the user to enter GEMINI_API_KEY in the key modal or Settings.

• Confirm the game can reach interactive state before sending turns.

Human-Guided Mode

• Confirm user can input actions in the browser.

• Help user craft opening world prompt and style.

• For each turn, provide a short recap and 3 action options with different risk/reward.

• Let the user pick or rewrite the action.

• Remind controls only when relevant: 机器人按钮 toggles built-in Auto Player, Esc exits auto mode/panels, Settings has Connect API Bridge .

AI REST Mode

• Ensure one browser tab is online at http://127.0.0.1:30000 .

• In Settings, ensure Connect API Bridge is connected.

• Check server health (GET /health ).

• Start or resume game via REST (create_game or load_game ).

• Loop: call get_current_game_state -> choose next action -> call do_action .

• Use last_scene_image_path to share scene visuals with the user.

Use scripts/openword_rest.sh first (curl-only, Python-free).

REST API Schema

Method Path Body Success fields

GET

/health

none status , bridge_online

POST

/api/create_game

{ "description": string, "style": string }

status , game_id

GET

/api/show_history_games

none status , games

POST

/api/load_game

{ "game_id": string }

status

GET

/api/get_current_game_state

none status , game_id , world_view , narrative , player_profile , last_scene_image_path

POST

/api/do_action

{ "description": string }

status , game_id , world_view , narrative , player_profile , last_scene_image_path

Interaction Contract

Never run long silent streaks. Keep the user in the loop even when AI plays.

• Share updates at least every 1-2 turns.

• At meaningful branch points, ask user preference before committing.

• Surface scene image paths and display scene images when possible.

• Highlight interesting moments: scene changes, risky decisions, major rewards, unexpected twists.

Failure Handling

• NO_BRIDGE : ask user to open game tab and enable Connect API Bridge .

• Bridge occupied: another tab owns the bridge; disconnect that tab first.

• Missing key/model errors: ask user to configure GEMINI_API_KEY .

• Slow/timeout calls: increase timeout, avoid overlapping requests.