Local Adventure Engine 本地冒险引擎

项目简介

Local Adventure Engine 是一个本地运行、开源、对 Git 友好的交互式小说引擎，灵感来自初代 AI Dungeon。你用 TOML 与 Markdown 编写世界，在终端里游玩，权威状态与只追加的历史都保存在本地 SQLite 中。

核心设计是职责分离：模型只负责提出散文式叙事和带类型的事件，引擎负责校验、归约并持久化。这样既保留了 LLM 的想象力，又避免了状态被模型随意改写。

主要特性

• 本地优先：无遥测、无云账号，提示词与游戏内容只发送到 world.toml 中配置的模型端点。
• 只追加时间线：每个有效行动自动保存，无需手动存档；撤销与恢复只移动当前位置，不删除历史。
• 分支与检查点：可在任意回合创建分支会话，或保存命名检查点随时回滚。
• 可导出：支持 Markdown / JSON 导出当前时间线与权威状态。
• 世界即文件：世界设定用 TOML + Markdown 编写，天然适合版本管理与分享。

快速上手

需要 Python 3.12+ 与本地运行的 LM Studio 服务。测试、世界校验、会话创建、回放、分支与导出均可离线完成。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

在 LM Studio 中启动本地服务，并把 worlds/ember_hollow/world.toml 里的 model.name 设为 /v1/models 返回的准确标识。

python -m local_adventure doctor --world worlds/ember_hollow
python -m local_adventure validate-world --world worlds/ember_hollow
python -m local_adventure play --world worlds/ember_hollow --name "First Journey"

游玩内命令

进入游戏后可用斜杠命令管理会话：

/continue          不输入行动，推进一个模型主导的场景节拍
/history [N]       查看当前时间线最近 N 个回合
/undo              回退一回合，不删除后续历史
/branch NAME       在当前回合创建并切换到新会话
/checkpoint NAME   保存或替换当前回合的命名指针
/restore NAME      将当前会话恢复到命名检查点
/export markdown PATH

适用与注意

项目适合作为本地 LLM 文字冒险原型、交互式叙事研究以及「模型提议 + 引擎校验」工程范式的参考。需要注意的是：它依赖你自行部署本地模型服务；仅提供终端交互；模型输出异常时虽有修复重试，仍可能导致自动游玩中断。运行时数据默认位于 .local-adventure/，记得备份该目录以保留会话。