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

1. Ask the user which mode to run before gameplay starts.
2. Prepare runtime (download/install/start, browser, key setup).
3. Branch to human-guided mode or AI REST mode.
4. 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

1. If repository does not exist locally, run: git clone https://github.com/dinghuanghao/openword.git
2. Install and start: npm install npm run dev
3. Ensure browser opens http://127.0.0.1:30000.
4. Prompt the user to enter GEMINI_API_KEY in the key modal or Settings.
5. Confirm the game can reach interactive state before sending turns.

Human-Guided Mode

1. Confirm user can input actions in the browser.
2. Help user craft opening world prompt and style.
3. For each turn, provide a short recap and 3 action options with different risk/reward.
4. Let the user pick or rewrite the action.
5. Remind controls only when relevant: 机器人按钮 toggles built-in Auto Player, Esc exits auto mode/panels, Settings has Connect API Bridge.

AI REST Mode

1. Ensure one browser tab is online at http://127.0.0.1:30000.
2. In Settings, ensure Connect API Bridge is connected.
3. Check server health (GET /health).
4. Start or resume game via REST (create_game or load_game).
5. Loop: call get_current_game_state -> choose next action -> call do_action.
6. 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.

1. Share updates at least every 1-2 turns.
2. At meaningful branch points, ask user preference before committing.
3. Surface scene image paths and display scene images when possible.
4. Highlight interesting moments: scene changes, risky decisions, major rewards, unexpected twists.

Failure Handling

1. NO_BRIDGE: ask user to open game tab and enable Connect API Bridge.
2. Bridge occupied: another tab owns the bridge; disconnect that tab first.
3. Missing key/model errors: ask user to configure GEMINI_API_KEY.
4. Slow/timeout calls: increase timeout, avoid overlapping requests.