chore: import upstream snapshot with attribution

docs/developer/conf.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+project = "GOD"
+author = "GOD contributors"
+copyright = f"{datetime.now().year}, GOD contributors"
+release = "0.2.0"
+version = "0.2"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+DOCS_DIR = Path(__file__).resolve().parent
+templates_path = ["_templates"] if (DOCS_DIR / "_templates").exists() else []
+
+html_theme = "furo"
+html_title = "GOD Developer Docs"
+html_short_title = "GOD Docs"
+html_static_path = ["_static"] if (DOCS_DIR / "_static").exists() else []
+
+html_theme_options = {
+    "navigation_with_keys": True,
+    "source_repository": "https://github.com/XiaoLuoLYG/GOD/",
+    "source_branch": "main",
+    "source_directory": "docs/developer/",
+}
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": False,
+}
+autodoc_typehints = "description"
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "html_image",
+    "linkify",
+    "replacements",
+    "strikethrough",
+    "tasklist",
+]
+myst_heading_anchors = 3
+
+rst_epilog = f"""
+.. |repo_root| replace:: {ROOT}
+"""

docs/developer/en/agent-studio.rst

@@ -0,0 +1,42 @@
+Agent Studio
+============
+
+Agent Studio is the map-aware editor for residents.
+
+Where it appears
+----------------
+
+Agent Studio can be opened from:
+
+- Setup, while editing a generated draft.
+- PixelReplay, while inspecting or extending the current experiment.
+- The standalone Agent Builder route during focused editing.
+
+What it edits
+-------------
+
+The Studio flow covers:
+
+- Seed and role direction.
+- Identity, biography, and profile metadata.
+- Appearance and map-compatible sprite settings.
+- Personality, routines, social ties, goals, needs, worries, and secrets.
+- Review before saving.
+
+Persistence path
+----------------
+
+For setup drafts, saved agents flow into the draft that will become ``init/init_config.json``. For replay-side edits, the frontend saves the experiment config and asks the backend to sync live agents when a live session is waiting.
+
+Generated sprites
+-----------------
+
+Generated ``Generated_Agent_*.png`` files are local user output by default and should not be committed unless a later release explicitly changes that policy.
+
+Related backend routes
+----------------------
+
+- ``POST /api/v1/god/setup/agent-studio/generate``
+- ``POST /api/v1/god/setup/agent-studio/character``
+- ``POST /api/v1/god/setup/agent-studio/complete-role-visuals``
+- ``PUT /api/v1/experiment-configs/{hypothesis_id}/{experiment_id}/init``

docs/developer/en/commands.rst

@@ -0,0 +1,51 @@
+Commands
+========
+
+Run commands from the repo root.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Command
+     - Use it when
+   * - ``./scripts/god.sh menu``
+     - You want an interactive menu.
+   * - ``./scripts/god.sh setup``
+     - You only want to install or check dependencies.
+   * - ``./scripts/god.sh configure``
+     - You want to reopen setup, switch the current experiment, or publish a custom experiment.
+   * - ``./scripts/god.sh start``
+     - You want the normal idempotent startup path.
+   * - ``./scripts/god.sh restart``
+     - You want to stop processes and start again without wiping replay state.
+   * - ``./scripts/god.sh new-run``
+     - You want to wipe the current experiment run and start a fresh live session.
+   * - ``./scripts/god.sh stop``
+     - You want to stop GOD and release ports.
+   * - ``./scripts/god.sh status``
+     - You want ports, URLs, model status, and current experiment details.
+   * - ``./scripts/god.sh tail``
+     - You want to follow GOD service logs.
+   * - ``./scripts/god.sh open``
+     - You want to open the control room and runtime UI again.
+
+Useful examples
+---------------
+
+Start without opening browser tabs:
+
+.. code-block:: bash
+
+   GOD_OPEN_BROWSER=0 ./scripts/god.sh start
+
+Run PKU Trump Visit as the current shell invocation:
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+Follow logs while another terminal runs the UI:
+
+.. code-block:: bash
+
+   ./scripts/god.sh tail

docs/developer/en/configuration.rst

@@ -0,0 +1,81 @@
+Configuration
+=============
+
+GOD separates machine settings from experiment selection.
+
+``.env``
+--------
+
+``.env`` stores local model, port, and startup settings. It is created from ``.env.example`` and ignored by Git.
+
+Required model settings:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+     - Default
+   * - ``GOD_LLM_API_KEY``
+     - OpenAI-compatible API key
+     - empty
+   * - ``GOD_LLM_API_BASE``
+     - OpenAI-compatible API base URL
+     - ``https://api.openai.com/v1``
+   * - ``GOD_LLM_MODEL``
+     - Chat model used by GOD and the runtime
+     - empty; required before model-backed runs
+   * - ``GOD_EMBEDDING_MODEL``
+     - Embedding model
+     - ``text-embedding-3-large``
+
+``.god/current_experiment.json``
+--------------------------------
+
+The setup wizard writes the active experiment here. ``start``, ``open``, and ``new-run`` read this file so ``.env`` does not accidentally decide the current map or scenario.
+
+Explicit overrides
+------------------
+
+For one-off runs, these environment variables override current-experiment state:
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+Common ports
+------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Variable
+     - Default
+     - Service
+   * - ``GOD_BACKEND_PORT``
+     - ``8001``
+     - FastAPI backend
+   * - ``GOD_FRONTEND_PORT``
+     - ``5174``
+     - GOD control room
+   * - ``RUNTIME_AGENT_PORT``
+     - ``19092``
+     - JiuwenClaw agent WebSocket
+   * - ``RUNTIME_WEB_PORT``
+     - ``20000``
+     - JiuwenClaw web service
+   * - ``RUNTIME_GATEWAY_PORT``
+     - ``20001``
+     - JiuwenClaw gateway
+   * - ``RUNTIME_UI_PORT``
+     - ``6173``
+     - Runtime UI
+
+Browser opening
+---------------
+
+Disable automatic browser opening:
+
+.. code-block:: bash
+
+   GOD_OPEN_BROWSER=0 ./scripts/god.sh start

docs/developer/en/contributing.rst

@@ -0,0 +1,41 @@
+Contributing
+============
+
+Start from the normal local path:
+
+.. code-block:: bash
+
+   git clone https://github.com/XiaoLuoLYG/GOD.git
+   cd GOD
+   ./scripts/god.sh start
+
+Before a PR
+-----------
+
+Run the checks relevant to your change:
+
+.. code-block:: bash
+
+   git diff --check
+   npm run build --prefix agentsociety/frontend
+   cd agentsociety
+   uv run pytest -q packages/agentsociety2/tests/test_god_setup_router.py \
+     packages/agentsociety2/tests/test_map_packages.py \
+     packages/agentsociety2/tests/test_pixel_town_social_env.py
+
+For map package changes:
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>
+
+Artifact hygiene
+----------------
+
+Keep runtime data out of public PRs. Do not stage ``.god/``, ``.live/``, ``.superpowers/``, ``.DS_Store``, generated map output, or generated test sprites.
+
+More detail
+-----------
+
+See ``CONTRIBUTING.md`` and ``CONTRIBUTING.zh-CN.md`` at the repo root.

docs/developer/en/custom-experiments.rst

@@ -0,0 +1,48 @@
+Custom Experiments
+==================
+
+The primary custom-experiment path is the setup wizard.
+
+Browser flow
+------------
+
+Run:
+
+.. code-block:: bash
+
+   ./scripts/god.sh configure
+
+Then choose **Create Custom Experiment**. The wizard asks for scenario context, generates a draft, lets you edit agents and steps, and publishes the result as the current experiment.
+
+Published shape
+---------------
+
+Custom experiments are written under:
+
+.. code-block:: text
+
+   agentsociety/quick_experiments/hypothesis_<slug>/experiment_1/
+
+The important files are:
+
+``init/init_config.json``
+   World context, map module, initial locations, agent profiles, enabled skills, and runtime-facing config.
+
+``init/steps.yaml``
+   Start timestamp, step count, and tick duration.
+
+``README.md`` and ``README.zh-CN.md``
+   Human explanation for the experiment.
+
+``run.sh``
+   Optional foreground runner for debugging.
+
+Current experiment pointer
+--------------------------
+
+When you click **Save and Launch**, setup writes ``.god/current_experiment.json``. The shell script then starts that experiment without changing ``.env``.
+
+Manual editing
+--------------
+
+You can edit experiment files directly, but the setup wizard is safer for first drafts because it keeps IDs, map selection, and runtime config aligned.

docs/developer/en/env-vars.rst

@@ -0,0 +1,61 @@
+Environment Variables
+=====================
+
+User-facing variables
+---------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Variable
+     - Default
+     - Notes
+   * - ``GOD_LLM_API_KEY``
+     - empty
+     - Required for model-backed runs.
+   * - ``GOD_LLM_API_BASE``
+     - ``https://api.openai.com/v1``
+     - Any OpenAI-compatible endpoint.
+   * - ``GOD_LLM_MODEL``
+     - empty
+     - Required main chat model. Examples: ``qwen-plus``, ``gpt-4o-mini``.
+   * - ``GOD_LLM_NANO_MODEL``
+     - ``GOD_LLM_MODEL``
+     - Optional high-frequency smaller model slot.
+   * - ``GOD_EMBEDDING_API_KEY``
+     - ``GOD_LLM_API_KEY``
+     - Optional override.
+   * - ``GOD_EMBEDDING_API_BASE``
+     - ``GOD_LLM_API_BASE``
+     - Optional override.
+   * - ``GOD_EMBEDDING_MODEL``
+     - ``text-embedding-3-large``
+     - Embedding model.
+   * - ``GOD_BACKEND_HOST``
+     - ``127.0.0.1``
+     - Backend bind host.
+   * - ``GOD_BACKEND_PORT``
+     - ``8001``
+     - Backend port.
+   * - ``GOD_FRONTEND_PORT``
+     - ``5174``
+     - Control room port.
+   * - ``GOD_OPEN_BROWSER``
+     - ``1``
+     - Set ``0`` to suppress automatic browser opening.
+   * - ``GOD_SKIP_SETUP``
+     - ``0``
+     - Set ``1`` to skip dependency checks.
+   * - ``GOD_PRIME_FIRST_STEP``
+     - ``1``
+     - Set ``0`` to skip automatic first-step priming.
+
+Advanced runtime variables
+--------------------------
+
+Runtime ports can be changed with ``RUNTIME_AGENT_PORT``, ``RUNTIME_WEB_PORT``, ``RUNTIME_GATEWAY_PORT``, and ``RUNTIME_UI_PORT``. The default runtime instance name is ``RUNTIME_INSTANCE=god-town``.
+
+Legacy compatibility
+--------------------
+
+``scripts/god.sh`` accepts older ``AGENTSOCIETY_*`` and ``JIUWENCLAW_*`` names, maps them into ``GOD_*`` values, and exports the internal names needed by the integrated services.

docs/developer/en/experiment-contract.rst

@@ -0,0 +1,46 @@
+Experiment Contract
+===================
+
+Experiment folders live under:
+
+.. code-block:: text
+
+   agentsociety/quick_experiments/hypothesis_<hypothesis_id>/experiment_<experiment_id>/
+
+Required files
+--------------
+
+``init/init_config.json``
+   Main scenario and runtime configuration. It includes experiment context, map module settings, agent profiles, initial locations, and enabled skill/runtime metadata.
+
+``init/steps.yaml``
+   Step plan with simulation start time, step count, and tick settings.
+
+Recommended files
+-----------------
+
+``README.md`` and ``README.zh-CN.md``
+   Human-facing experiment explanation.
+
+``run.sh``
+   Foreground debug runner.
+
+``OPERATOR_SCRIPT.md``
+   Optional live-operator prompts for scripted demos.
+
+Current experiment state
+------------------------
+
+The active experiment is stored in:
+
+.. code-block:: text
+
+   .god/current_experiment.json
+
+It records the selected ``hypothesis_id``, ``experiment_id``, and workspace path. Startup reads this file unless the shell command explicitly sets ``GOD_EXPERIMENT`` or ``GOD_EXPERIMENT_RUN``.
+
+Built-in examples
+-----------------
+
+- ``agentsociety/quick_experiments/hypothesis_god_town/experiment_1/``
+- ``agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_1/``

docs/developer/en/index.rst

@@ -0,0 +1,45 @@
+GOD Developer Docs
+==================
+
+GOD combines a local control room, FastAPI backend, Pixel Town replay environment, and JiuwenClaw-backed agent runtime. These docs are for people who want to run, customize, or extend the GOD repo.
+
+.. note::
+
+   The upstream AgentSociety docs describe the framework that GOD builds on. This site documents the integrated GOD product and its current repo layout.
+
+Start Here
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   installation
+   quickstart
+   configuration
+   commands
+
+Build With GOD
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   custom-experiments
+   agent-studio
+   map-studio
+   map-packages
+   runtime-skills
+   contributing
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   reference
+   env-vars
+   experiment-contract
+   live-replay-api
+   python-api

docs/developer/en/installation.rst

@@ -0,0 +1,70 @@
+Installation
+============
+
+Prerequisites
+-------------
+
+GOD currently expects:
+
+- macOS/Linux: Python 3.11 or newer, Node.js and ``npm``, ``uv``, and ``screen``.
+- Windows: PowerShell 5.1+ and ``winget``. The PowerShell entrypoint auto-installs missing Git, Node.js LTS/npm, and ``uv``; ``uv`` supplies the managed Python runtime.
+
+On macOS:
+
+.. code-block:: bash
+
+   brew install python node uv screen
+
+Clone
+-----
+
+.. code-block:: bash
+
+   git clone https://github.com/XiaoLuoLYG/GOD.git
+   cd GOD
+
+The repo contains the integrated AgentSociety and JiuwenClaw checkouts needed by the local GOD stack.
+
+Install by starting
+-------------------
+
+The recommended install path is the same as the start path:
+
+.. code-block:: bash
+
+   ./scripts/god.sh start
+
+On Windows PowerShell, use:
+
+.. code-block:: powershell
+
+   .\scripts\god.cmd start
+
+On first run, the script creates ``.env`` from ``.env.example``, installs backend/runtime/frontend dependencies, opens the setup wizard, and waits for model configuration.
+
+Install only
+------------
+
+To check or install dependencies without opening the full live stack:
+
+.. code-block:: bash
+
+   ./scripts/god.sh setup
+
+If you already know the dependencies are ready and want to skip setup checks during startup:
+
+.. code-block:: bash
+
+   GOD_SKIP_SETUP=1 ./scripts/god.sh start
+
+Local-only files
+----------------
+
+Do not commit local runtime state:
+
+- ``.env``
+- ``.god/``
+- ``.live/``
+- ``agentsociety/quick_experiments/**/run*/``
+- generated ``Generated_Agent_*.png`` sprite files
+- generated map packages under ``agentsociety/custom/generated_maps/``

docs/developer/en/live-replay-api.rst

@@ -0,0 +1,74 @@
+Live and Replay API
+===================
+
+GOD's browser UI uses a small set of backend API families.
+
+Live experiment control
+-----------------------
+
+Base prefix:
+
+.. code-block:: text
+
+   /live-experiments/{hypothesis_id}/{experiment_id}
+
+Important actions:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Method
+     - Path
+     - Purpose
+   * - ``POST``
+     - ``/start``
+     - Start or attach a live experiment.
+   * - ``GET``
+     - ``/status``
+     - Read live status.
+   * - ``POST``
+     - ``/run-step``
+     - Advance one step.
+   * - ``POST``
+     - ``/intervene``
+     - Inject instructions into the next step.
+   * - ``POST``
+     - ``/ask``
+     - Ask one target, a group, or the whole town.
+   * - ``POST``
+     - ``/auto``
+     - Toggle auto-run.
+   * - ``POST``
+     - ``/pause``
+     - Pause auto-run.
+   * - ``POST``
+     - ``/stop``
+     - Stop live execution.
+
+Replay data
+-----------
+
+Base prefix:
+
+.. code-block:: text
+
+   /replay/{hypothesis_id}/{experiment_id}
+
+Common reads:
+
+- ``/info``
+- ``/datasets``
+- ``/map``
+- ``/map/tiled``
+- ``/map/assets/{tileset_index}``
+- ``/map/preview``
+- ``/map/characters/{character_name}``
+- ``/map/location-assets/{location_id}``
+- ``/timeline``
+
+Setup and configuration
+-----------------------
+
+- ``/api/v1/god/setup/*`` owns setup wizard model config, draft generation, Agent Studio generation, publish, and start-request flow.
+- ``/api/v1/experiment-configs/*`` owns experiment config read/write and agent import/apply flows.
+- ``/api/v1/god/map-studio/*`` owns map draft generation, upload, validation, and publish.

docs/developer/en/map-packages.rst

@@ -0,0 +1,39 @@
+Map Packages
+============
+
+GOD discovers map packages from:
+
+.. code-block:: text
+
+   agentsociety/custom/maps/<map_id>/
+
+Minimum package shape
+---------------------
+
+.. code-block:: text
+
+   custom/maps/<map_id>/
+     map.yaml
+     README.md
+     visuals/
+       map.json
+       map_assets/
+       preview.png
+
+``map.yaml`` is the manifest. ``visuals/map.json`` is the Tiled JSON map consumed by PixelReplay. The Tiled map must include a ``Collisions`` layer where ``0`` means walkable.
+
+Validation
+----------
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>
+
+More detail
+-----------
+
+The maintained contract lives in the repo docs:
+
+- ``docs/MAP_PACKAGES.md``
+- ``docs/MAP_PACKAGES.zh-CN.md``

docs/developer/en/map-studio.rst

@@ -0,0 +1,47 @@
+Map Studio
+==========
+
+Map Studio creates and publishes local map packages.
+
+Flow
+----
+
+Map Studio can:
+
+1. Generate a draft map from a prompt.
+2. Upload a reference image as a draft.
+3. Configure image generation.
+4. Calibrate locations, anchors, and collision data.
+5. Validate the package.
+6. Publish the map into the local map package directory.
+7. Return to setup with the new ``map_id`` selected.
+
+Generated packages
+------------------
+
+Generated packages are local output under:
+
+.. code-block:: text
+
+   agentsociety/custom/generated_maps/
+
+That path is ignored by Git. Curated maps that should ship with GOD belong under ``agentsociety/custom/maps/<map_id>/``.
+
+Important routes
+----------------
+
+- ``POST /api/v1/god/map-studio/drafts``
+- ``POST /api/v1/god/map-studio/drafts/upload``
+- ``PATCH /api/v1/god/map-studio/drafts/{draft_id}``
+- ``POST /api/v1/god/map-studio/drafts/{draft_id}/validate``
+- ``POST /api/v1/god/map-studio/drafts/{draft_id}/publish``
+
+Validation
+----------
+
+For a curated map package:
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>

docs/developer/en/overview.rst

@@ -0,0 +1,47 @@
+Overview
+========
+
+GOD stands for Govern, Observe, Direct. It is a local-first operator console for running an agent society, watching it step by step, asking residents questions, and injecting instructions into the next live step.
+
+What GOD adds
+-------------
+
+GOD is not only a simulation framework:
+
+- The setup wizard configures model settings, chooses built-in experiments, and publishes custom experiments.
+- PixelReplay shows the town, timeline, residents, chat, and live controls in one browser UI.
+- Agent Studio edits residents with map-aware identity, appearance, personality, routine, and review steps.
+- Map Studio generates or uploads map drafts, calibrates anchors and collisions, validates them, and publishes map packages.
+- ``scripts/god.sh`` owns the local startup lifecycle so a new contributor does not need to wire four services manually.
+
+Runtime shape
+-------------
+
+The normal local stack is:
+
+1. Operator opens the control room in the browser.
+2. The React/Vite frontend calls the local FastAPI backend.
+3. The backend reads the current experiment from ``.god/current_experiment.json`` and experiment files under ``agentsociety/quick_experiments``.
+4. The live experiment runner talks to JiuwenClaw over a local WebSocket.
+5. Pixel Town writes replay data so the frontend can scrub and inspect each step.
+
+Primary repo areas
+------------------
+
+``scripts/god.sh``
+   One-command setup, start, restart, status, browser opening, and cleanup.
+
+``agentsociety/frontend``
+   GOD control room, setup wizard, Agent Studio, Map Studio, and PixelReplay UI.
+
+``agentsociety/packages/agentsociety2``
+   Backend routers, live experiment runner, map package services, replay services, and selected extension points.
+
+``agentsociety/quick_experiments``
+   Built-in and user-published experiments.
+
+``agentsociety/custom/maps``
+   Pluggable map packages.
+
+``jiuwenclaw``
+   Integrated out-of-process agent runtime.

docs/developer/en/python-api.rst

@@ -0,0 +1,35 @@
+Selected Python API
+===================
+
+This page names source files that are stable enough to inspect when extending GOD. It does not attempt to publish the whole upstream AgentSociety API.
+
+Backend routers
+---------------
+
+- ``agentsociety2.backend.routers.god_setup``
+- ``agentsociety2.backend.routers.live_experiments``
+- ``agentsociety2.backend.routers.replay``
+- ``agentsociety2.backend.routers.experiment_configs``
+- ``agentsociety2.backend.routers.map_studio``
+- ``agentsociety2.backend.routers.agent_skills``
+
+Map services
+------------
+
+- ``agentsociety2.backend.services.map_packages``
+- ``agentsociety2.backend.services.map_generation``
+
+Replay services
+---------------
+
+- ``agentsociety2.backend.services.replay_catalog``
+- ``agentsociety2.storage.replay_writer``
+
+Custom agent/runtime paths
+--------------------------
+
+- ``agentsociety2.backend.services.custom``
+- ``agentsociety2.agent``
+- ``agentsociety/custom/agents/``
+
+When adding public API documentation later, prefer documenting extension points used by GOD setup, Agent Studio, Map Studio, and PixelReplay before exposing broad internal modules.

docs/developer/en/quickstart.rst

@@ -0,0 +1,60 @@
+Quickstart
+==========
+
+Start GOD
+---------
+
+.. code-block:: bash
+
+   ./scripts/god.sh start
+
+``start`` is idempotent: if a service is already running, the script reuses it where possible.
+
+First-run flow
+--------------
+
+On a clean checkout, GOD will:
+
+1. Create ``.env`` from ``.env.example``.
+2. Install Python and Node dependencies.
+3. Start the setup backend and control room.
+4. Open the browser setup wizard at ``/setup``.
+5. Ask for an OpenAI-compatible API key, base URL, and model name.
+6. Let you choose GOD Town, PKU Trump Visit, or create a custom experiment.
+7. Start the full stack for the selected current experiment.
+8. Create a live session, prime the first step, and open PixelReplay.
+
+Expected control room URL
+-------------------------
+
+For the default GOD Town experiment, the URL looks like:
+
+.. code-block:: text
+
+   http://127.0.0.1:5174/pixel-replay/god_town/1
+
+For PKU Trump Visit:
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+Then open:
+
+.. code-block:: text
+
+   http://127.0.0.1:5174/pixel-replay/pku_trump_visit/1
+
+Verify
+------
+
+.. code-block:: bash
+
+   ./scripts/god.sh status
+
+Healthy output should show backend, control room, agent runtime, runtime web, runtime gateway, and runtime UI ports as up.
+
+When to use ``new-run``
+-----------------------
+
+Use ``restart`` for process cleanup without wiping the current replay. Use ``new-run`` when you want a fresh live session and clean replay state for the current experiment.

docs/developer/en/reference.rst

@@ -0,0 +1,11 @@
+Reference
+=========
+
+This section collects stable contracts for developers extending GOD.
+
+- :doc:`env-vars`
+- :doc:`experiment-contract`
+- :doc:`live-replay-api`
+- :doc:`python-api`
+
+Use this reference together with the source files named on each page. The docs intentionally cover GOD's public extension paths, not every upstream AgentSociety class.

docs/developer/en/runtime-skills.rst

@@ -0,0 +1,29 @@
+Runtime Skills
+==============
+
+GOD uses JiuwenClaw as the out-of-process agent runtime and AgentSociety as the product-level skill execution path.
+
+Runtime bridge
+--------------
+
+The default local runtime instance is ``god-town``. Startup maps GOD model settings to both AgentSociety and JiuwenClaw environment variables, then starts JiuwenClaw services on local ports.
+
+Relevant defaults:
+
+- Agent WebSocket: ``RUNTIME_AGENT_PORT=19092``
+- Runtime web: ``RUNTIME_WEB_PORT=20000``
+- Runtime gateway: ``RUNTIME_GATEWAY_PORT=20001``
+- Runtime UI: ``RUNTIME_UI_PORT=6173``
+
+Skill packages
+--------------
+
+Custom agent skills are managed through backend routes under ``/api/v1/agent-skills``. Setup and Agent Studio keep skill runtime metadata synchronized with experiment config so agents use the same runtime path after generation, import, and apply flows.
+
+Where to inspect
+----------------
+
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/agent_skills.py``
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/god_setup.py``
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiment_configs.py``
+- ``jiuwenclaw/``

docs/developer/index.rst

@@ -0,0 +1,14 @@
+GOD Developer Documentation
+===========================
+
+GOD is a local-first operator console for controllable agent societies. Choose a language to start:
+
+- :doc:`English developer docs <en/index>`
+- :doc:`中文开发者文档 <zh/index>`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   en/index
+   zh/index

docs/developer/requirements.txt

@@ -0,0 +1,4 @@
+sphinx>=8.2.3
+furo>=2024.8.6
+myst-parser>=4.0.0
+linkify-it-py>=2.0.3

docs/developer/zh/agent-studio.rst

@@ -0,0 +1,42 @@
+Agent Studio
+============
+
+Agent Studio 是地图感知的居民编辑器。
+
+入口
+----
+
+Agent Studio 可以从这些位置打开：
+
+- Setup 中编辑生成草稿。
+- PixelReplay 中检查或扩展当前实验。
+- 单独的 Agent Builder 路由。
+
+编辑内容
+--------
+
+Studio 流程覆盖：
+
+- seed 和角色方向。
+- 身份、简介和 profile metadata。
+- 外貌和地图兼容 sprite 设置。
+- 性格、日程、社交关系、目标、需求、担忧和秘密。
+- 保存前 review。
+
+持久化路径
+----------
+
+Setup 草稿中的 agent 会进入即将发布的 ``init/init_config.json``。Replay 侧编辑会保存实验配置；如果 live session 正在等待，前端还会请求后端同步 live agents。
+
+生成 sprite
+-----------
+
+生成的 ``Generated_Agent_*.png`` 默认是本地用户输出，不应提交，除非之后的 release 明确改变策略。
+
+相关后端路由
+------------
+
+- ``POST /api/v1/god/setup/agent-studio/generate``
+- ``POST /api/v1/god/setup/agent-studio/character``
+- ``POST /api/v1/god/setup/agent-studio/complete-role-visuals``
+- ``PUT /api/v1/experiment-configs/{hypothesis_id}/{experiment_id}/init``

docs/developer/zh/commands.rst

@@ -0,0 +1,51 @@
+命令
+====
+
+所有命令都在仓库根目录运行。
+
+.. list-table::
+   :header-rows: 1
+
+   * - 命令
+     - 何时使用
+   * - ``./scripts/god.sh menu``
+     - 打开交互菜单。
+   * - ``./scripts/god.sh setup``
+     - 只安装或检查依赖。
+   * - ``./scripts/god.sh configure``
+     - 重新打开 setup，切换当前实验，或发布自定义实验。
+   * - ``./scripts/god.sh start``
+     - 常规可重复启动路径。
+   * - ``./scripts/god.sh restart``
+     - 停止进程并重启，不清空 replay 状态。
+   * - ``./scripts/god.sh new-run``
+     - 清空当前实验 run，启动新的 live session。
+   * - ``./scripts/god.sh stop``
+     - 停止 GOD 并释放端口。
+   * - ``./scripts/god.sh status``
+     - 查看端口、URL、模型状态和当前实验。
+   * - ``./scripts/god.sh tail``
+     - 跟随 GOD 服务日志。
+   * - ``./scripts/god.sh open``
+     - 重新打开控制台和 runtime UI。
+
+常用例子
+--------
+
+启动但不自动打开浏览器：
+
+.. code-block:: bash
+
+   GOD_OPEN_BROWSER=0 ./scripts/god.sh start
+
+一次性运行 PKU Trump Visit：
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+另一个终端里跟随日志：
+
+.. code-block:: bash
+
+   ./scripts/god.sh tail

docs/developer/zh/configuration.rst

@@ -0,0 +1,81 @@
+配置
+====
+
+GOD 把机器配置和实验选择分开管理。
+
+``.env``
+--------
+
+``.env`` 保存本地模型、端口和启动配置。它由 ``.env.example`` 创建，并被 Git 忽略。
+
+必需模型配置：
+
+.. list-table::
+   :header-rows: 1
+
+   * - 变量
+     - 用途
+     - 默认值
+   * - ``GOD_LLM_API_KEY``
+     - OpenAI 兼容 API key
+     - 空
+   * - ``GOD_LLM_API_BASE``
+     - OpenAI 兼容 API base URL
+     - ``https://api.openai.com/v1``
+   * - ``GOD_LLM_MODEL``
+     - GOD 和 runtime 使用的聊天模型
+     - 空；模型运行前必填
+   * - ``GOD_EMBEDDING_MODEL``
+     - embedding 模型
+     - ``text-embedding-3-large``
+
+``.god/current_experiment.json``
+--------------------------------
+
+配置向导会把 active 实验写到这里。``start``、``open`` 和 ``new-run`` 读取这个文件，因此 ``.env`` 不会意外决定当前地图或剧本。
+
+显式覆盖
+--------
+
+一次性运行可以用环境变量覆盖当前实验：
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+常用端口
+--------
+
+.. list-table::
+   :header-rows: 1
+
+   * - 变量
+     - 默认值
+     - 服务
+   * - ``GOD_BACKEND_PORT``
+     - ``8001``
+     - FastAPI 后端
+   * - ``GOD_FRONTEND_PORT``
+     - ``5174``
+     - GOD 控制台
+   * - ``RUNTIME_AGENT_PORT``
+     - ``19092``
+     - JiuwenClaw agent WebSocket
+   * - ``RUNTIME_WEB_PORT``
+     - ``20000``
+     - JiuwenClaw web 服务
+   * - ``RUNTIME_GATEWAY_PORT``
+     - ``20001``
+     - JiuwenClaw gateway
+   * - ``RUNTIME_UI_PORT``
+     - ``6173``
+     - Runtime UI
+
+浏览器打开
+----------
+
+禁止自动打开浏览器：
+
+.. code-block:: bash
+
+   GOD_OPEN_BROWSER=0 ./scripts/god.sh start

docs/developer/zh/contributing.rst

@@ -0,0 +1,41 @@
+参与贡献
+========
+
+从常规本地路径开始：
+
+.. code-block:: bash
+
+   git clone https://github.com/XiaoLuoLYG/GOD.git
+   cd GOD
+   ./scripts/god.sh start
+
+提交 PR 前
+----------
+
+运行与改动相关的检查：
+
+.. code-block:: bash
+
+   git diff --check
+   npm run build --prefix agentsociety/frontend
+   cd agentsociety
+   uv run pytest -q packages/agentsociety2/tests/test_god_setup_router.py \
+     packages/agentsociety2/tests/test_map_packages.py \
+     packages/agentsociety2/tests/test_pixel_town_social_env.py
+
+地图包改动：
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>
+
+产物边界
+--------
+
+不要把运行数据提交到公开 PR。不要 stage ``.god/``、``.live/``、``.superpowers/``、``.DS_Store``、生成地图输出或生成测试 sprite。
+
+更多细节
+--------
+
+见仓库根目录的 ``CONTRIBUTING.md`` 和 ``CONTRIBUTING.zh-CN.md``。

docs/developer/zh/custom-experiments.rst

@@ -0,0 +1,48 @@
+自定义实验
+==========
+
+主要的自定义实验路径是 setup wizard。
+
+浏览器流程
+----------
+
+运行：
+
+.. code-block:: bash
+
+   ./scripts/god.sh configure
+
+然后选择 **Create Custom Experiment**。向导会要求输入场景背景，生成草稿，允许编辑 agent 和 steps，最后发布为当前实验。
+
+发布后的结构
+------------
+
+自定义实验会写到：
+
+.. code-block:: text
+
+   agentsociety/quick_experiments/hypothesis_<slug>/experiment_1/
+
+重要文件：
+
+``init/init_config.json``
+   世界背景、地图模块、初始位置、agent profile、启用技能和 runtime 配置。
+
+``init/steps.yaml``
+   起始时间、步数和每步时长。
+
+``README.md`` 和 ``README.zh-CN.md``
+   给人看的实验说明。
+
+``run.sh``
+   可选的前台调试 runner。
+
+当前实验指针
+------------
+
+点击 **Save and Launch** 后，setup 会写入 ``.god/current_experiment.json``。脚本随后启动该实验，而不是修改 ``.env`` 来决定实验。
+
+手动编辑
+--------
+
+你可以直接编辑实验文件，但第一次起草建议用 setup wizard，因为它能保持 ID、地图选择和 runtime 配置一致。

docs/developer/zh/env-vars.rst

@@ -0,0 +1,61 @@
+环境变量
+========
+
+用户可见变量
+------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - 变量
+     - 默认值
+     - 说明
+   * - ``GOD_LLM_API_KEY``
+     - 空
+     - 模型运行必需。
+   * - ``GOD_LLM_API_BASE``
+     - ``https://api.openai.com/v1``
+     - 任意 OpenAI 兼容 endpoint。
+   * - ``GOD_LLM_MODEL``
+     - 空
+     - 必填主聊天模型。示例：``qwen-plus``、``gpt-4o-mini``。
+   * - ``GOD_LLM_NANO_MODEL``
+     - ``GOD_LLM_MODEL``
+     - 可选高频小模型槽位。
+   * - ``GOD_EMBEDDING_API_KEY``
+     - ``GOD_LLM_API_KEY``
+     - 可选覆盖。
+   * - ``GOD_EMBEDDING_API_BASE``
+     - ``GOD_LLM_API_BASE``
+     - 可选覆盖。
+   * - ``GOD_EMBEDDING_MODEL``
+     - ``text-embedding-3-large``
+     - embedding 模型。
+   * - ``GOD_BACKEND_HOST``
+     - ``127.0.0.1``
+     - 后端绑定 host。
+   * - ``GOD_BACKEND_PORT``
+     - ``8001``
+     - 后端端口。
+   * - ``GOD_FRONTEND_PORT``
+     - ``5174``
+     - 控制台端口。
+   * - ``GOD_OPEN_BROWSER``
+     - ``1``
+     - 设为 ``0`` 可禁止自动打开浏览器。
+   * - ``GOD_SKIP_SETUP``
+     - ``0``
+     - 设为 ``1`` 可跳过依赖检查。
+   * - ``GOD_PRIME_FIRST_STEP``
+     - ``1``
+     - 设为 ``0`` 可跳过自动预跑第一步。
+
+高级 runtime 变量
+-----------------
+
+Runtime 端口可以通过 ``RUNTIME_AGENT_PORT``、``RUNTIME_WEB_PORT``、``RUNTIME_GATEWAY_PORT`` 和 ``RUNTIME_UI_PORT`` 修改。默认 runtime instance 名是 ``RUNTIME_INSTANCE=god-town``。
+
+兼容旧变量
+----------
+
+``scripts/god.sh`` 会接受旧的 ``AGENTSOCIETY_*`` 和 ``JIUWENCLAW_*`` 名称，将其映射为 ``GOD_*`` 值，并导出集成服务需要的内部变量。

docs/developer/zh/experiment-contract.rst

@@ -0,0 +1,46 @@
+实验 Contract
+=============
+
+实验目录位于：
+
+.. code-block:: text
+
+   agentsociety/quick_experiments/hypothesis_<hypothesis_id>/experiment_<experiment_id>/
+
+必需文件
+--------
+
+``init/init_config.json``
+   主要场景和 runtime 配置，包括实验背景、地图模块设置、agent profile、初始位置和启用技能/runtime metadata。
+
+``init/steps.yaml``
+   Step 计划，包括模拟开始时间、步数和 tick 设置。
+
+推荐文件
+--------
+
+``README.md`` 和 ``README.zh-CN.md``
+   给人看的实验说明。
+
+``run.sh``
+   前台调试 runner。
+
+``OPERATOR_SCRIPT.md``
+   可选的 live operator prompts，适合脚本化 demo。
+
+当前实验状态
+------------
+
+Active 实验保存在：
+
+.. code-block:: text
+
+   .god/current_experiment.json
+
+它记录 ``hypothesis_id``、``experiment_id`` 和 workspace path。启动时会读取该文件，除非命令显式设置 ``GOD_EXPERIMENT`` 或 ``GOD_EXPERIMENT_RUN``。
+
+内置示例
+--------
+
+- ``agentsociety/quick_experiments/hypothesis_god_town/experiment_1/``
+- ``agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_1/``

docs/developer/zh/index.rst

@@ -0,0 +1,45 @@
+GOD 开发者文档
+==============
+
+GOD 把本地控制台、FastAPI 后端、Pixel Town 回放环境和 JiuwenClaw Agent runtime 组合成一个可操作的 agent society 产品。这份文档面向想运行、定制或扩展 GOD 仓库的人。
+
+.. note::
+
+   上游 AgentSociety 文档介绍的是 GOD 所依赖的框架。本网站介绍的是 GOD 当前仓库里的产品化集成路径。
+
+开始使用
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   installation
+   quickstart
+   configuration
+   commands
+
+用 GOD 构建
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   custom-experiments
+   agent-studio
+   map-studio
+   map-packages
+   runtime-skills
+   contributing
+
+参考
+----
+
+.. toctree::
+   :maxdepth: 1
+
+   reference
+   env-vars
+   experiment-contract
+   live-replay-api
+   python-api

docs/developer/zh/installation.rst

@@ -0,0 +1,70 @@
+安装
+====
+
+前置条件
+--------
+
+GOD 当前需要：
+
+- macOS/Linux：Python 3.11 或更新版本、Node.js 和 ``npm``、``uv``，以及 ``screen``。
+- Windows：PowerShell 5.1+ 和 ``winget``。PowerShell 入口会自动补齐缺失的 Git、Node.js LTS/npm 与 ``uv``；Python 运行时由 ``uv`` 管理。
+
+macOS:
+
+.. code-block:: bash
+
+   brew install python node uv screen
+
+克隆仓库
+--------
+
+.. code-block:: bash
+
+   git clone https://github.com/XiaoLuoLYG/GOD.git
+   cd GOD
+
+这个仓库已经包含本地 GOD 栈需要的 AgentSociety 和 JiuwenClaw 集成目录。
+
+通过 start 安装
+---------------
+
+推荐的安装路径就是启动路径：
+
+.. code-block:: bash
+
+   ./scripts/god.sh start
+
+Windows PowerShell 使用：
+
+.. code-block:: powershell
+
+   .\scripts\god.cmd start
+
+首次运行时，脚本会从 ``.env.example`` 创建 ``.env``，安装后端/runtime/前端依赖，打开 setup wizard，并等待你配置模型。
+
+只安装依赖
+----------
+
+如果只想检查或安装依赖，不打开完整 live 栈：
+
+.. code-block:: bash
+
+   ./scripts/god.sh setup
+
+如果依赖已经准备好，启动时想跳过依赖检查：
+
+.. code-block:: bash
+
+   GOD_SKIP_SETUP=1 ./scripts/god.sh start
+
+本地文件边界
+------------
+
+不要提交本地运行状态：
+
+- ``.env``
+- ``.god/``
+- ``.live/``
+- ``agentsociety/quick_experiments/**/run*/``
+- 生成的 ``Generated_Agent_*.png`` sprite
+- ``agentsociety/custom/generated_maps/`` 下的生成地图

docs/developer/zh/live-replay-api.rst

@@ -0,0 +1,74 @@
+Live 和 Replay API
+==================
+
+GOD 浏览器 UI 使用几组后端 API。
+
+Live experiment 控制
+--------------------
+
+基础 prefix：
+
+.. code-block:: text
+
+   /live-experiments/{hypothesis_id}/{experiment_id}
+
+重要动作：
+
+.. list-table::
+   :header-rows: 1
+
+   * - 方法
+     - 路径
+     - 用途
+   * - ``POST``
+     - ``/start``
+     - 启动或附着 live experiment。
+   * - ``GET``
+     - ``/status``
+     - 读取 live 状态。
+   * - ``POST``
+     - ``/run-step``
+     - 推进一步。
+   * - ``POST``
+     - ``/intervene``
+     - 向下一步注入指令。
+   * - ``POST``
+     - ``/ask``
+     - 向目标、群组或全镇提问。
+   * - ``POST``
+     - ``/auto``
+     - 切换自动运行。
+   * - ``POST``
+     - ``/pause``
+     - 暂停自动运行。
+   * - ``POST``
+     - ``/stop``
+     - 停止 live 执行。
+
+Replay 数据
+-----------
+
+基础 prefix：
+
+.. code-block:: text
+
+   /replay/{hypothesis_id}/{experiment_id}
+
+常见读取：
+
+- ``/info``
+- ``/datasets``
+- ``/map``
+- ``/map/tiled``
+- ``/map/assets/{tileset_index}``
+- ``/map/preview``
+- ``/map/characters/{character_name}``
+- ``/map/location-assets/{location_id}``
+- ``/timeline``
+
+Setup 和配置
+------------
+
+- ``/api/v1/god/setup/*`` 管理 setup wizard 的模型配置、草稿生成、Agent Studio 生成、发布和 start-request。
+- ``/api/v1/experiment-configs/*`` 管理实验配置读写和 agent import/apply。
+- ``/api/v1/god/map-studio/*`` 管理地图草稿生成、上传、校验和发布。

docs/developer/zh/map-packages.rst

@@ -0,0 +1,39 @@
+地图包
+======
+
+GOD 会从这里发现地图包：
+
+.. code-block:: text
+
+   agentsociety/custom/maps/<map_id>/
+
+最小结构
+--------
+
+.. code-block:: text
+
+   custom/maps/<map_id>/
+     map.yaml
+     README.md
+     visuals/
+       map.json
+       map_assets/
+       preview.png
+
+``map.yaml`` 是 manifest。``visuals/map.json`` 是 PixelReplay 使用的 Tiled JSON 地图。Tiled map 必须包含 ``Collisions`` layer，其中 ``0`` 表示可行走。
+
+校验
+----
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>
+
+更多细节
+--------
+
+维护中的 contract 在仓库文档里：
+
+- ``docs/MAP_PACKAGES.md``
+- ``docs/MAP_PACKAGES.zh-CN.md``

docs/developer/zh/map-studio.rst

@@ -0,0 +1,47 @@
+Map Studio
+==========
+
+Map Studio 用于创建和发布本地地图包。
+
+流程
+----
+
+Map Studio 可以：
+
+1. 根据 prompt 生成地图草稿。
+2. 上传参考图作为草稿。
+3. 配置图像生成。
+4. 校准地点、anchor 和 collision 数据。
+5. 校验地图包。
+6. 发布到本地地图包目录。
+7. 回到 setup，并选中新 ``map_id``。
+
+生成包
+------
+
+生成地图默认是本地输出：
+
+.. code-block:: text
+
+   agentsociety/custom/generated_maps/
+
+该路径被 Git 忽略。需要随 GOD 发布的精选地图应放在 ``agentsociety/custom/maps/<map_id>/``。
+
+重要路由
+--------
+
+- ``POST /api/v1/god/map-studio/drafts``
+- ``POST /api/v1/god/map-studio/drafts/upload``
+- ``PATCH /api/v1/god/map-studio/drafts/{draft_id}``
+- ``POST /api/v1/god/map-studio/drafts/{draft_id}/validate``
+- ``POST /api/v1/god/map-studio/drafts/{draft_id}/publish``
+
+校验
+----
+
+精选地图包：
+
+.. code-block:: bash
+
+   cd agentsociety
+   uv run python scripts/validate_map_package.py custom/maps/<map_id>

docs/developer/zh/overview.rst

@@ -0,0 +1,47 @@
+概览
+====
+
+GOD 是 Govern, Observe, Direct 的缩写。它是一个 local-first 的 agent society 操作台：你可以运行一个小镇，逐步观察它，向居民提问，并把指令注入到下一步 live 执行里。
+
+GOD 增加了什么
+---------------
+
+GOD 不只是模拟框架：
+
+- Setup Wizard 负责模型配置、内置实验选择和自定义实验发布。
+- PixelReplay 在一个浏览器界面里显示地图、时间线、居民、聊天和 live 控制。
+- Agent Studio 用地图感知的流程编辑居民身份、外貌、性格、日程和 review。
+- Map Studio 生成或上传地图草稿，校准 anchor 和 collision，校验后发布地图包。
+- ``scripts/god.sh`` 统一本地启动生命周期，新贡献者不用手动串四个服务。
+
+运行结构
+--------
+
+常规本地栈是：
+
+1. 操作者在浏览器打开控制台。
+2. React/Vite 前端调用本地 FastAPI 后端。
+3. 后端从 ``.god/current_experiment.json`` 和 ``agentsociety/quick_experiments`` 读取当前实验。
+4. live experiment runner 通过本地 WebSocket 连接 JiuwenClaw。
+5. Pixel Town 写入 replay 数据，前端可以按 step 拖动和检查。
+
+主要目录
+--------
+
+``scripts/god.sh``
+   一键 setup、start、restart、status、打开浏览器和清理。
+
+``agentsociety/frontend``
+   GOD 控制台、配置向导、Agent Studio、Map Studio 和 PixelReplay UI。
+
+``agentsociety/packages/agentsociety2``
+   后端路由、live runner、地图包服务、replay 服务和扩展点。
+
+``agentsociety/quick_experiments``
+   内置实验和用户发布的实验。
+
+``agentsociety/custom/maps``
+   可插拔地图包。
+
+``jiuwenclaw``
+   集成的 out-of-process agent runtime。

docs/developer/zh/python-api.rst

@@ -0,0 +1,35 @@
+精选 Python API
+===============
+
+本页列出扩展 GOD 时相对稳定、值得阅读的源码位置。它不会发布完整上游 AgentSociety API。
+
+后端路由
+--------
+
+- ``agentsociety2.backend.routers.god_setup``
+- ``agentsociety2.backend.routers.live_experiments``
+- ``agentsociety2.backend.routers.replay``
+- ``agentsociety2.backend.routers.experiment_configs``
+- ``agentsociety2.backend.routers.map_studio``
+- ``agentsociety2.backend.routers.agent_skills``
+
+地图服务
+--------
+
+- ``agentsociety2.backend.services.map_packages``
+- ``agentsociety2.backend.services.map_generation``
+
+Replay 服务
+-----------
+
+- ``agentsociety2.backend.services.replay_catalog``
+- ``agentsociety2.storage.replay_writer``
+
+自定义 agent/runtime 路径
+-------------------------
+
+- ``agentsociety2.backend.services.custom``
+- ``agentsociety2.agent``
+- ``agentsociety/custom/agents/``
+
+以后增加公开 API 文档时，优先文档化 GOD setup、Agent Studio、Map Studio 和 PixelReplay 使用到的扩展点，再考虑暴露更广泛的内部模块。

docs/developer/zh/quickstart.rst

@@ -0,0 +1,60 @@
+快速开始
+========
+
+启动 GOD
+--------
+
+.. code-block:: bash
+
+   ./scripts/god.sh start
+
+``start`` 是可重复执行的：如果服务已经运行，脚本会尽量复用已有服务。
+
+首次运行流程
+------------
+
+在干净 checkout 里，GOD 会：
+
+1. 从 ``.env.example`` 创建 ``.env``。
+2. 安装 Python 和 Node 依赖。
+3. 启动 setup 后端和控制台。
+4. 在浏览器打开 ``/setup``。
+5. 要求填写 OpenAI 兼容 API key、base URL 和模型名。
+6. 选择 GOD Town、PKU Trump Visit，或创建自定义实验。
+7. 为当前实验启动完整服务栈。
+8. 创建 live session，预跑第一步，并打开 PixelReplay。
+
+预期控制台 URL
+--------------
+
+默认 GOD Town 的 URL 类似：
+
+.. code-block:: text
+
+   http://127.0.0.1:5174/pixel-replay/god_town/1
+
+PKU Trump Visit:
+
+.. code-block:: bash
+
+   GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
+
+然后打开：
+
+.. code-block:: text
+
+   http://127.0.0.1:5174/pixel-replay/pku_trump_visit/1
+
+验证
+----
+
+.. code-block:: bash
+
+   ./scripts/god.sh status
+
+健康状态应该显示 backend、control room、agent runtime、runtime web、runtime gateway 和 runtime UI 端口均为 up。
+
+什么时候用 ``new-run``
+----------------------
+
+``restart`` 用于清理进程但不清空当前 replay。``new-run`` 用于为当前实验开一个全新的 live session 和干净 replay。

docs/developer/zh/reference.rst

@@ -0,0 +1,11 @@
+参考
+====
+
+本节收集扩展 GOD 时相对稳定的 contract。
+
+- :doc:`env-vars`
+- :doc:`experiment-contract`
+- :doc:`live-replay-api`
+- :doc:`python-api`
+
+请结合每页列出的源码文件阅读。本参考刻意只覆盖 GOD 的公开扩展路径，不枚举所有上游 AgentSociety 内部类。

docs/developer/zh/runtime-skills.rst

@@ -0,0 +1,29 @@
+Runtime Skills
+==============
+
+GOD 使用 JiuwenClaw 作为 out-of-process agent runtime，并把 AgentSociety 作为产品层 skill 执行路径。
+
+Runtime bridge
+--------------
+
+默认本地 runtime instance 是 ``god-town``。启动时会把 GOD 模型配置映射到 AgentSociety 和 JiuwenClaw 环境变量，然后在本地端口启动 JiuwenClaw 服务。
+
+相关默认值：
+
+- Agent WebSocket: ``RUNTIME_AGENT_PORT=19092``
+- Runtime web: ``RUNTIME_WEB_PORT=20000``
+- Runtime gateway: ``RUNTIME_GATEWAY_PORT=20001``
+- Runtime UI: ``RUNTIME_UI_PORT=6173``
+
+Skill 包
+--------
+
+自定义 agent skills 通过 ``/api/v1/agent-skills`` 下的后端路由管理。Setup 和 Agent Studio 会让 skill runtime metadata 与实验配置同步，因此生成、导入和应用之后，agent 使用同一条 runtime 路径。
+
+查看位置
+--------
+
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/agent_skills.py``
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/god_setup.py``
+- ``agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiment_configs.py``
+- ``jiuwenclaw/``