本地 LLM 文字冒险引擎（ai-adventure）

隐私与前置条件

要使用模型进行游玩，需要满足以下条件：

• 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 返回的精确标识符。引擎会以文本模式请求模型，并附带明确的 JSON 输出契约，随后独立校验模型提出的叙述和事件，确认无误后才保存回合。

运行示例世界

使用以下命令可以快速体验示例世界：

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"

其他常用命令包括 sessions list、sessions create、reindex、play --session 以及 export --session ID --format markdown|json --output PATH。

在游玩过程中，输入 /help 可以查看状态检查、撤销、分支、检查点、重新加载、上下文诊断等命令，以及 /export markdown PATH 或 /export json PATH。/continue 命令会在不替玩家角色选择行动的情况下，推进一个由模型引导的场景节拍。当玩家行动提示就绪时，交互式终端会收到配置的通知铃声；如果希望静音，可以在终端设置中关闭铃声。

运行时数据默认存放在 .local-adventure/ 目录下（或由 LOCAL_ADVENTURE_HOME 指定），包括 SQLite 数据库、用户选择放置的导出文件以及日志。备份该目录即可保留会话。

会话管理

会话是一个已保存的、只追加的游戏时间线。每个有效动作都会自动保存，无需单独的保存命令。

创建会话但不立即开始游玩：

python -m local_adventure sessions create \
  --world worlds/ember_hollow \
  --scenario opening \
  --name "Example Journey"

或者使用 play --world 创建并立即进入会话。可选的 --name 仅在创建新会话时生效，默认值为 First Journey；使用 play --session 恢复会话时该参数会被忽略。

python -m local_adventure play --world worlds/ember_hollow --name "Example Journey"
python -m local_adventure sessions list
python -m local_adventure play --session SESSION_ID

若希望进行可重复的游玩，可以在任一 play 形式中添加 --actions-file PATH。该 UTF-8 文本文件每行包含一个玩家动作。游戏会依次显示每个动作及其提交的叙述，最后一行结束后会提示正常输入。在自动游玩过程中按 Ctrl-C 可停止并手动输入动作。空行和游戏内命令会被拒绝；该文件仅用于玩家动作。如果某个动作的模型响应在配置的修复尝试后仍然无效，游玩会最多再重试该动作两次；若仍失败，则该动作不会保存任何回合，自动游玩会在交互提示处停止。传输错误会直接报告，不会自动重试。

python -m local_adventure play --world worlds/ember_hollow --actions-file actions.txt

在游玩内部，以下命令用于管理当前会话：

/continue           Advance from the prior narrated beat without player input.
/history [N]        Show up to the last N turns on the current timeline.
/undo               Move back one turn without deleting later history.
/branch NAME        Create and switch to a new session at the current turn.
/checkpoint NAME    Save or replace a named pointer to the current turn.
/restore NAME       Return the current session to a named checkpoint.
/sessions           List sessions for the loaded world.

分支会共享创建之前的所有历史，仅在播放新回合时产生分歧。撤销和恢复会移动会话的当前位置，但永远不会删除回合。检查点名称在会话内唯一。

需要时导出当前时间线和权威状态：

python -m local_adventure export --session SESSION_ID --format markdown --output session.md
python -m local_adventure export --session SESSION_ID --format json --output session.json

相同的导出格式在游玩过程中也可通过 /export markdown PATH 和 /export json PATH 使用。导出内容仅包含当前祖先链、重放状态和检查点，不包含模型提示词和原始模型响应。

开发与测试

开发相关命令：

python -m unittest discover -s tests -v
python -m compileall local_adventure tests
python -m local_adventure doctor

更多文档请参阅架构、数据模型、世界编写、隐私与安全、故障排除以及实现状态等文档。