这不是一个帮你写小说的 AI,而是一个让你造一个世界、再公平地活在里面的引擎。 它的全部本事,是在你看不见的地方,守住这个世界的一致和秘密。

详尽设计见 世界引擎_开发文档.md。

English (TL;DR). WorldEngine is not an AI that writes novels for you — it is an engine that lets you build a world and live inside it fairly. Facts live in a local, structured, append-only canon; the LLM only proposes prose and plot, and every proposal is adjudicated against hard rules before it becomes real. It is fail-closed: when in doubt, it refuses rather than let a contradiction through. Everything — NPCs and the player — is a "character with an epistemic boundary," so the same projection mechanism keeps NPCs from leaking secrets and keeps the player from seeing the hidden cards. Runs fully offline with a deterministic stub (no API key needed); plug in any Anthropic / OpenAI-compatible endpoint to use a real model. Quickstart is below.

1. LLM 提议,Canon 裁决 —— 事实留在本地结构化档案,LLM 只生成文字与提议剧情。
2. 失败即关闭 (fail-closed) —— 拿不准就拒绝/卡住,绝不放一条矛盾过关。
3. 一切皆"有认知边界的角色" —— 同一套视角投影机制,既让 NPC 不泄密,也让玩家看不见底牌。

M1 = 玩家行动 → 生成 → 核对 → 出画面的命令行闭环:视角投影(脊柱)、四条硬规则 (认知边界/生死/位置/持有)、NPC 由真实 LLM 生成且只见投影上下文、fail-closed 重写/STALL、 单写者事务。

# 1) 准备环境(已自带 .venv;如需重建)
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

# 2)(可选)接真实模型:复制 .env.example 为 .env 并填入 base_url/model/key
#    不配置则默认离线 Stub,闭环照常可跑。连通性自验:
.venv\Scripts\python.exe scripts\llm_smoketest.py

# 3) 进入最小可玩闭环(命令:look / go <地点> / say <话> / give <物> <人> / quit)
.venv\Scripts\python.exe -m world_engine.cli.play

# 4) 跑骨架演示(装配世界 + 空回合 + 不变量校验)
.venv\Scripts\python.exe -m world_engine.bootstrap

# 5) 跑测试(291 个,全程离线)
.venv\Scripts\python.exe -m pytest

# 6)(M4)导演演示:多 NPC 经事务排队 + sealed 秘密懒生成→择机 reveal
.venv\Scripts\python.exe -m world_engine.director.demo

# 7)(M3)记忆与遗忘演示:主角刻骨 / 龙套过耳 / 支线被一次回溯重评救回
.venv\Scripts\python.exe -m world_engine.memory.demo

# 8)(M2)认知脊柱演示:多 NPC 投影 / 知识传播 / 认知核对 / false_belief 可照说
.venv\Scripts\python.exe -m world_engine.scenarios

# 9)(M7)涌现式生成演示:空屋里"环顾" → 世界自发长出一个新角色登场(离线确定性)
.venv\Scripts\python.exe -m world_engine.genesis.demo

M5/M6 在独立 worktree 基于协议契约开发,合并入已含 M1/M2/M3 的 main:M5 的加固管线 复用 M1 的 Rule 协议与脊柱(epistemics),仅扩入 timeline 硬规则、软核对(grounding + 交叉裁判)与指标看板;红队语料里依赖 M1 的 epistemic_leak/life_status/location 样本 由真规则确定性裁决。设计与合并取舍见 ADR 0009 / ADR 0010。

# 跑一致性红队回归:打印记分卡,崩坏率非 0 则退出码 1(可接 CI)
.venv\Scripts\python.exe -m world_engine.qa

• M5 加固核对(world_engine/validator/):扩硬规则(持有/时序)、软核对带 grounding + 交叉裁判、崩坏率/软核对触发率指标看板。详见 M5 进度报告。
• M6 红队基线(world_engine/qa/):带金标签的对抗语料 + 崩坏率=0 门禁。 详见 M6 进度报告。

world_engine/        # 主包(分层见开发文档 §11)
├── schemas/         # 跨模块共享 Pydantic 模型(叶子层)+ 账本折叠
├── canon/           # 事实权威:事件账本 + 当前状态投影(三值查询)
├── epistemics/      # 脊柱:视角投影 + 认知边界成员判定(防泄密)
├── memory/          # 记忆与遗忘(M3)
├── director/        # 导演:单写者事务 + 剧情推进 + sealed 秘密(M4;turn loop 暂用最小版)
├── validator/       # 核对管线:硬规则(含时序)+ 软核对(交叉裁判)+ 指标看板
├── qa/              # 一致性红队与回归基线(崩坏率门禁,M6)
├── generation/      # 生成:投影上下文产出 / 抽取 / 重写
├── engine/          # 回合编排:run_turn + 时钟
├── store/           # 持久化:append-only JSONL 账本
├── llm/             # LLM Provider 适配(可替换:Anthropic/OpenAI 兼容/Stub)
├── config/          # 全局配置 + .env 加载
├── cli/             # 最小可玩闭环入口 play.py
└── bootstrap.py     # 最小世界引导 + 空回合演示
tests/               # pytest 测试(离线)
scripts/             # llm_smoketest.py 等
docs/                # 决策记录(ADR)、问题日志、进度报告

• 版本控制:每个功能点/修复在独立分支开发;里程碑完成打 tag(可回退)。
• 决策记录:关键技术选型写进 docs/adr/。
• 问题追踪:开发中遇到的问题与解决记录在 docs/PROBLEMS.md。
• 进度报告:每个阶段的报告在 docs/progress/。

M4 说明:按"叠加式模块"落进已带 M1/M3 的 main —— 单写者事务(多 NPC 写-写冲突决议)、 剧情推进、sealed 秘密三件套已实现并单测(python -m world_engine.director.demo 看闭环)。 与在用的 M1 turn loop 并存:后者仍用最小版 SimpleDirector,把 StoryDirector 接进 turn loop(相遇/秘密进到可玩闭环)是下一步。详见 docs/progress/M4.md。

欢迎 issue 与 PR。请遵循上文「开发约定」:每个功能点走独立分支,关键技术选型补 ADR, 改动尽量带离线测试(python -m pytest 全程不依赖网络)。

Issues and pull requests are welcome. Please follow the conventions above: one branch per change, record notable design decisions as an ADR under docs/adr/, and keep the test suite green (python -m pytest runs fully offline, no network or API key required).

本项目以 MIT 许可证 开源 — 自由使用、修改与分发,保留版权与许可声明即可。

Released under the MIT License.