pip install -e ".[mcp]"

{ "mcpServers": { "world-walker": { "command": "world-walker-mcp" } } }

python init_game.py                                      # 生成示例世界 game_state.json（青云界）
python engine.py world_state --state game_state.json      # Windows 用 python，macOS/Linux 用 python3

python engine.py combat    --state game_state.json --attacker player --defender goblin --action_type heavy
python engine.py trade     --state game_state.json --location bamboo_tea_booth --item an_zhen_san --quantity 3 --direction buy --entity player
python engine.py social    --state game_state.json --actor player --target old_chen --event help
python engine.py karma     --state game_state.json --actor player --karma_type murder_innocent
python engine.py tick      --state game_state.json
python engine.py flow      --state game_state.json
python engine.py identity  --state game_state.json
python engine.py narrative --state game_state.json
python engine.py world_state  --state game_state.json
python engine.py panarchy  --state game_state.json
python engine.py moral_update   --state game_state.json
python engine.py cognition   --state game_state.json --entity player
python engine.py merit     --state game_state.json --aid 0.8 --sincerity 0.9
python engine.py info_weight --state game_state.json --probability 0.05

game_engine/                      # 仓库根即 game_engine 包（导入别名已放开，目录名任意）
├── engine.py                     # CLI 入口（14 条命令）
├── mcp_server.py                 # MCP 服务器（31 个工具；除 mcp>=2 外无额外依赖）
├── state_schema.py               # 状态结构 + 辅助函数
├── init_game.py                  # 生成示例世界（青云界）
├── pyproject.toml                # pip install -e ".[mcp]"；命令 world-walker / world-walker-mcp
├── panel.py / panel.html / panel.css / panel.js   # 只读实况主舞台（视图模型 + HTTP/SSE + 前端三件套）
├── viz_series.py                 # 长局态势侧写（<状态>.viz.jsonl 采样：图表数据源，不碰状态文件）
├── assets/echarts.min.js         # 离线图表库（Apache-2.0，随包分发，无 CDN 依赖）
├── BRAND.md                      # 品牌规范（名号/标语/配色/可配置化，单一信源）
├── ARCHITECTURE.md               # 架构文档（唯一真理源：视图模型契约/不变量/ADR）
├── scripts/verify_mcp_stdio.py   # MCP 端到端自检（48 项断言，含酒馆生态兼容/图鉴/面板/模型层与确定性）
├── scripts/verify_panel.py       # 面板契约自检（48 项断言：视图模型契约/旧存档兼容/静态白名单/缺档错误态/品牌/帮助/序列采样）
├── scripts/user_playtest.py      # 用户视角试玩（41 项"玩家会不会投诉"检查：钻空子/边界/报错可读性）
├── scripts/stress_freeplay.py    # 自由玩家压力测试（默认 2000 回合，走真实 MCP stdio 通道）
├── docs/screenshots/             # README 预览截图（真实渲染 + 断言；来源说明见该目录 README）
├── demo_state.json               # 演示状态
├── GAME_MASTER_PROTOCOL.md       # AI Agent 调用协议
└── rules/                        # 85+ 学术公式（Python 实现）
    ├── combat.py                 #    战斗 / 命中 / 暴击
    ├── economy.py                #    经济 / 供需 / 价格波动
    ├── social.py                 #    社交二维关系
    ├── karma.py                  #    因果债
    ├── cognition.py              #    认知科学（双系统、前景理论、ACT-R、心流）
    ├── world_dynamics.py         #    世界演化（混沌、进化、Panarchy、PID）
    ├── social_extended.py        #    扩展社交（Haidt、Milgram、Bandura）
    ├── cultural_evolution.py     #    文化进化（DIT、模因、文化棘轮）
    ├── systems_feedback.py       #    系统反馈（Meadows 12 杠杆点、NAT）
    └── narrative_engine.py       #    涌现叙事（Bartle、事件、相位）