这不是一个帮你写小说的 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.
- LLM 提议,Canon 裁决 —— 事实留在本地结构化档案,LLM 只生成文字与提议剧情。
- 失败即关闭 (fail-closed) —— 拿不准就拒绝/卡住,绝不放一条矛盾过关。
- 一切皆"有认知边界的角色" —— 同一套视角投影机制,既让 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.demoM5/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/。
| 里程碑 | 目标 | 状态 |
|---|---|---|
| M0 | 骨架:能编译、能跑空回合 | ✅ 完成(v0.1.0-m0) |
| M1 | 最小可玩闭环:行动→生成→核对→出画面 | ✅ 完成(v0.2.0-m1) |
| M2 | 认知边界做扎实(脊柱) | ✅ 完成(对象精确信念 + false_belief;见 progress/M2) |
| M3 | 记忆与遗忘 | ✅ 完成(自洽实现,先于 M1/M2;见 progress/M3) |
| M4 | 导演(事务/推进/秘密) | 🧩 模块落地(v0.4.0-m4;StoryDirector/dramaturge/secrets,turn loop 接线待定) |
| M5 | 加固核对(指标驱动) | ✅ 完成 |
| M6 | 一致性红队与回归基线(崩坏率门禁) | ✅ 完成 |
| M7 | 涌现式生成(自发生成角色/场景) | ✅ 完成(world_engine/genesis/;运行时 SPAWN_* 提案过核对;见 progress/M7) |
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.