AI 驱动的文字 MUD 引擎。世界观只提供开场设定，地图、剧情、NPC 由 DM（Pi 或 Codex AI backend）在游戏中动态生成。
使用本项目之前，用户需要先安装并配置好至少一个 AI backend：默认推荐 Pi；如果客户只有 Codex，也可以使用本地 Codex CLI。本项目不会提交、保存或要求你把密钥写进仓库；只读取用户本机已经登录/配置好的 AI 能力。
curl -fsSL https://bun.sh/install | bash也可以参考 Bun 官方文档：https://bun.sh/docs/installation
Pi 官方 README 当前推荐的 npm 安装方式：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent官方安装脚本方式：
curl -fsSL https://pi.dev/install.sh | sh更多说明见 Pi 官网和官方文档：
先打开 Pi 并完成登录或 API key 配置：
pi在 Pi 里可以使用：
/login # 选择 provider 并登录
/model # 查看或切换模型
也可以通过环境变量/API key 使用 Pi 支持的 provider。模型列表和自定义 provider 配置请参考 Pi 官方文档中的 Providers & Models / Custom Models。
如果客户本地只有 Codex，先确认已安装并登录 Codex：
codex login
codex doctor然后在 .env 中设置：
AI_BACKEND=codex
# 可选：不填则使用 Codex 默认模型
# CODEX_MODEL=gpt-5.1# 1. 安装依赖
bun install
# 2. 复制配置模板
cp .env.example .env
# 3. 编辑 .env：选择 AI_BACKEND=pi 或 codex，并配置模型名称
# 大模型负责 DM 叙事与世界推进；小模型负责玩家指令解析。
# 4. 启动
# 新游戏会先选择剧本，再创建角色
bun start开发模式：
bun run dev启动选项：
bun start --world station-dream # 指定世界包
bun start --save station-dream-001 # 读取存档
bun start --name 旅行者 # 兼容旧用法：预填玩家姓名新游戏启动后会先进入剧本选择流程；选择剧本后再进入角色创建流程：选择故事包预设主角，或输入自己的姓名和角色描述，由 AI 根据世界观生成候选主角后再选择。玩家姓名限制为 1-16 个字符；背景、作品参考和人物描述请写到“角色描述”里。非交互环境会自动使用 .env 中的 WORLD_PACK。
本项目支持 Pi SDK 和 Codex CLI 两种 backend。请先在对应工具中完成登录/模型配置，然后在 .env 中选择 backend 和模型名。
| 变量 | 说明 | 默认值 |
|---|---|---|
AI_BACKEND |
默认 AI backend：pi 或 codex |
pi |
DM_BACKEND |
可选：DM 单独使用的 backend | 继承 AI_BACKEND |
INTERPRETER_BACKEND |
可选：指令解析单独使用的 backend | 继承 AI_BACKEND |
CHARACTER_BACKEND |
可选：角色生成单独使用的 backend | 继承 AI_BACKEND |
DM_PROVIDER |
Pi backend 下 DM 大模型 provider | openai-proxy |
DM_MODEL |
Pi backend 下 DM 大模型名称 | claude-sonnet-4.6 |
INTERPRETER_PROVIDER |
Pi backend 下指令解析小模型 provider | openai-proxy |
INTERPRETER_MODEL |
Pi backend 下指令解析小模型名称 | gpt-5.4-mini |
CODEX_MODEL |
Codex backend 默认模型；留空使用 Codex 自己的默认模型 | — |
CODEX_DM_MODEL |
可选：Codex backend 下 DM 模型 | 继承 CODEX_MODEL |
CODEX_INTERPRETER_MODEL |
可选：Codex backend 下指令解析模型 | 继承 CODEX_MODEL |
CODEX_CHARACTER_MODEL |
可选：Codex backend 下角色生成模型 | 继承 CODEX_MODEL |
DM_THINKING |
DM 思考深度：off/minimal/low/medium/high | low |
WORLD_PACK |
默认世界包；非交互启动或直接回车时使用 | station-dream |
DEFAULT_PLAYER_NAME |
默认玩家名 | 旅行者 |
Pi 用户可先运行 pi，再用 /model 查看可用 provider/model id。Codex 用户可运行 codex doctor 检查本机登录和运行状态。.env 应保留在本地，不要提交。
.env、本地存档saves/、node_modules/等已在.gitignore中排除。- 不要把 API key、OAuth token、cookie、私钥或本地 Pi 登录态提交到仓库。
- Pi / Codex 的认证信息保存在用户本机对应工具的配置目录中，本项目不会把认证信息写入项目文件。
- 游戏存档可能包含玩家输入、生成剧情和测试内容，默认不提交。
look [目标] 查看周围或物品
go <方向> 移动（东/西/南/北）
say <内容> 说话（DM 会让 NPC 响应）
get <物品> 拾取
drop <物品> 丢弃
equip <物品> 装备
attack <目标> 攻击
inv 查看背包
status 查看状态
help 显示帮助
quit 保存并退出
每局游戏自动保存在本地 saves/{worldId}/：
state.json— 当前世界快照turns.jsonl— 完整轮次日志（追加写入，不修改）
saves/ 是本地运行数据，默认不提交。
在 worlds/ 下新建目录：
worlds/my-world/
├── world.json # 初始房间、NPC、物品
└── lore.md # 世界观（注入给 DM）
然后启动：
bun start --world my-worldsrc/
├── types/
│ ├── world.ts # WorldState 数据结构
│ └── mutations.ts # EngineMutation + DmMutation（所有变更类型）
├── store/
│ ├── apply.ts # applyMutation() — 唯一变更入口
│ └── persist.ts # state.json + turns.jsonl 读写
├── engine/
│ ├── commands.ts # 指令 → EngineMutation[]
│ └── world-loader.ts # 世界包加载
├── ai/
│ ├── backend.ts # AI backend 抽象
│ ├── pi-backend.ts # Pi SDK backend
│ ├── codex-backend.ts # Codex CLI backend
│ ├── character-generator.ts # 用户描述 → 主角候选
│ ├── interpreter.ts # 小模型：文本 → ParsedCommand
│ ├── dm-session.ts # DM 会话封装
│ ├── dm-prompt.ts # 构建每轮 DM prompt
│ └── dm-parser.ts # DM 返回 → DmMutation[]
└── main.ts # CLI 入口
每个世界包可以在 world.json 中提供 defaultProtagonistId 和 protagonists[]。新游戏启动后，玩家会在 CLI 中选择预设主角，或输入自己的姓名和角色描述，让 AI 生成符合世界观的候选角色。姓名只接受短名称；AI 生成角色会被要求创作原创角色，不复刻已有小说、影视、游戏、动漫或其他作品中的角色。
角色信息会保存到 state.player.profile 快照中，并注入每轮 DM prompt，使叙事能稳定参考角色背景、动机、初始物品和开场钩子。存档保存的是创建时的角色快照，因此故事包后续更新不会改变旧存档。
世界包加载时会校验引用关系和属性范围：出生点、出口、NPC 房间、物品位置、默认主角、初始物品、属性 key 都必须有效。若某个 NPC 或主角需要超过 schema 默认上限，可以显式提供 hpMax、mpMax 这类 {stat}Max override。
世界包主角示例：
{
"defaultProtagonistId": "lost_commuter",
"protagonists": [
{
"id": "lost_commuter",
"name": "迟归的通勤者",
"summary": "每天搭乘末班车的人，却忘了自己要回哪里。",
"background": "你总觉得自己错过了一站，但车票上没有目的地。",
"motivation": "找回自己真正想回去的地方。",
"initialStats": { "hp": 100, "attack": 6, "defense": 3 },
"initialInventory": ["ticket"],
"openingHook": "你在空白时刻表前醒来，手里攥着一张没有目的地的旧车票。"
}
]
}当 AI_BACKEND=codex 时，mud-pi 会通过本地 codex exec 调用 Codex，并使用：
codex exec --ephemeral --ignore-rules --sandbox read-only --ask-for-approval never这样 Codex 只作为只读 AI 生成 backend 使用，不会让 Codex 修改项目文件。DM、指令解析、角色生成都可以统一走 Codex；也可以用 DM_BACKEND / INTERPRETER_BACKEND / CHARACTER_BACKEND 混用 Pi 和 Codex。
bun install # 安装依赖
bun run dev # watch 模式启动
bun start # 启动游戏
bun test # 运行测试
bun run typecheck # TypeScript 类型检查