用LLM做文字冒险游戏：从状态循环到CaLLMar工程实践

最近在 HN 上看到一个挺有意思的项目方向CaLLMar把经典文字冒险游戏text-based adventure game直接搬进 LLM 聊天窗口里玩。传统文字游戏靠开发者写死谜题和场景分支而 CaLLMar 的思路相反——让大模型当叙事引擎玩家用自然语言输入动作剧情、场景、物品、NPC 都由模型实时生成聊天界面就是游戏界面。这个方向很适合三类人折腾一是喜欢老式文字冒险的玩家想找回当年对着屏幕打字的感觉二是正在做 LLM Agent 应用开发的工程师想找一个含状态管理、上下文控制、结构化输出的小项目练手三是做互动叙事、教育演示或轻量游戏原型的设计师。这篇文章不打算堆概念我会按“先想清楚设计再跑通最小版本再做校验和批量场景最后给排查思路”的顺序把这些内容完整拆开。1. 先理解 CaLLMar 的核心聊天框不是用来聊天的是用来推进游戏状态很多第一次接触这个项目的人会误以为它就是一个“能陪你玩文字游戏的角色扮演机器人”。实际上差别很大。普通角色扮演对话只要求模型说的话符合人设剧情走向是松散的而文字冒险游戏要求玩家输入、模型输出、游戏状态三者形成稳定的循环。CaLLMar 解决的核心问题就是把 LLM 从“会说话的模型”变成“能维持一个虚构世界的游戏引擎”。1.1 从“一问一答”到“状态循环”常规 LLM 聊天是这样的用户你好 模型你好有什么可以帮你 用户帮我写一首诗 模型好的下面是……对话是“无状态”的。模型不会主动维护“你当前在哪、背包里有什么、哪个 NPC 欠你钱”。但文字冒险游戏完全是另一套逻辑系统状态player_location: forest, inventory: [], health: 100 玩家输入向北走 模型输出你穿过灌木丛来到一片湖边。岸边有一艘小船。 状态更新player_location: lake, inventory: [], health: 100玩家每输入一条指令模型都要参考当前状态生成一段剧情同时更新状态。这就是 CaLLMar 最有价值的地方它把 LLM 当成一个会即兴创作、但必须遵守规则的“游戏主持人”而不是一个随便聊天的机器人。1.2 和普通 Agent 应用的关联如果你做过 LLM Agent 或工具调用类应用会发现两者有共同点都要处理结构化输出、都要维护多轮上下文、都要对模型的“幻觉”做约束。文字冒险游戏本质上就是一个轻量级 Agent 场景——把“调用工具”改成“更新游戏状态”把“函数参数”改成“玩家动作解析”。所以很多 Agent 开发经验在这里完全适用比如让模型输出 JSON 而不是纯文本用程序解析状态。使用 function calling 或结构化输出能力降低格式错误率。对模型输出做二次校验避免出现不合理状态。这也是我建议开发者玩一下 CaLLMar 的原因它比写“会议室预订 Agent”有意思但技术挑战一点也不少。1.3 适用边界先说清楚CaLLMar 不是要替代图形化游戏也不是做“3A 大作”。它的优势在于内容生成成本极低不需要策划写一万条分支。玩家自由度很高可以尝试各种脑洞操作。适合原型、教学、互动故事、AI 伴玩等场景。短期内不要指望它做到传统文字冒险游戏那种“可精确验证的谜题逻辑”。比如玩家输入“用钥匙打开宝箱”模型可能会生成“宝箱开了”而不是先检查背包里有没有钥匙。这种问题需要靠状态校验和提示词约束去缓解后面会详细说。2. 跑起来之前先把三件事想清楚很多项目失败不是因为模型不行而是状态模型没设计好。CaLLMar 这类应用最核心的不是提示词有没有文采而是程序能不能稳定拿到“当前剧情对应的结构化状态”。2.1 定义最小游戏状态第一次做不需要设计复杂 RPG 系统。我建议只保留四种基础字段字段作用示例player_location玩家当前位置forest, lake, caveinventory背包物品列表[rusty_key, apple]health玩家状态100game_status游戏是否继续running / win / dead这四类字段足够支撑一场完整的文字冒险。额外可以加 scene_description保存当前场景的描述文本避免模型每次都要重新脑补。{ player_location: forest, inventory: [], health: 100, game_status: running }状态存储方式可以先用一个 JSON 字符串放在会话变量里。后续需要持久化再迁到数据库。2.2 系统提示词要同时干三件事我给这类项目写系统提示词时会把内容拆成三层角色设定你是一个文字冒险游戏的主持人负责描述场景、回应玩家动作、给出合理反馈。世界规则只有玩家输入的动作会影响状态物品必须符合逻辑玩家死亡或达成目标时结束游戏。输出格式必须返回 JSON包含 narrative 和 new_state 两个字段。其中第三层最关键。如果只让模型“自由发挥”你会在解析输出时疯掉。下面是我常用的输出结构{ narrative: 你走进一片阴暗的森林脚下传来枯枝断裂的声音。, new_state: { player_location: forest, inventory: [], health: 100, game_status: running } }注意这里的示例是我的通用写法不是 CaLLMar 官方格式。实际项目落地时以自己的需求为准。2.3 上下文策略决定“记忆”和“幻觉”文字冒险游戏最大的矛盾在于模型上下文窗口有限但游戏世界需要长期记忆。如果每轮把全部历史都塞给模型很快就会爆掉如果完全不塞历史模型会忘记你已经拿走某件物品。常见的做法有三种短游戏只保留最近 5-10 轮对话加最新状态适合快速原型。中长游戏维护一个“事件摘要”每轮更新摘要替换旧对话。复杂游戏把关键事件、地点、人物关系向量化用 RAG 方式做长期记忆类似小规模记忆库。我建议先做第一种跑通之后再升级到第二种。第三种的工程复杂度较高不是第一版需要考虑的。3. 最小可玩版本先把第一轮跑通不要一上来就写服务端、加数据库、做前端。先把“玩家输入一句话 - 模型返回剧情和状态 - 程序打印结果”这条链路跑通后面所有功能都建立在这条主链路上。3.1 环境准备CaLLMar 这类玩法对运行环境要求其实不高核心是能调用一个 chat completion 接口。你可以选在线 API也可以选本地模型。在线 API 方式需要有效的 API Key。网络能访问对应服务。请求超时和额度需要关注。效果一般较好适合快速验证。本地模型方式用 Ollama、LM Studio 或类似工具加载模型。不需要 API Key但需要一定内存和磁盘空间。速度取决于硬件低配机器能跑但单轮响应可能偏慢。模型精度很重要fp16、bf16、fp32 会影响显存占用和输出质量。以本地部署为例遇到显示问题优先看量化精度而不是直接换模型。我不建议第一版就上大型框架。CaLLMar 本身不需要 Spring AI、Agent 框架才能跑等到需要并行会话、工具调用、复杂记忆时再引入编排层。3.2 一个最简单的主循环用 Python 写的话核心逻辑大概长这样import json from openai import OpenAI client OpenAI() system_prompt 你是一个文字冒险游戏主持人。 玩家会输入动作。 你必须返回 JSON格式如下 { narrative: 剧情描述, new_state: { player_location: 地点, inventory: [物品], health: 100, game_status: running } } 只输出 JSON。 game_state { player_location: forest, inventory: [], health: 100, game_status: running } while game_state[game_status] running: player_input input( ) messages [ {role: system, content: system_prompt}, {role: user, content: f当前状态{json.dumps(game_state, ensure_asciiFalse)}}, {role: user, content: f玩家输入{player_input}} ] response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, temperature0.8 ) raw response.choices[0].message.content parsed json.loads(raw) print(parsed[narrative]) game_state parsed[new_state]这段代码只是演示主循环不是完整工程。真实环境里你至少还要补充异常处理、JSON 修复和状态一致性检查。3.3 第一轮验证标准代码写完先别急着加功能。用这几个问题检查主链路是否正常输入“向北走”模型是否返回一个符合当前地点的剧情输入“捡起石头”返回的 inventory 是否增加了 stone连续输入两三句后状态是否仍然能对上只要这三项通过说明核心链路已经成立。很多人会在这一步卡住最常见的问题是模型返回的 JSON 解析失败。解决思路不是马上换模型而是先检查系统提示词是否明确要求只输出 JSON以及是否限制了字段名。4. 从“能聊”到“能玩”状态校验和命令解析跑通第一轮之后你会很快发现一个问题模型有时候会“自作主张”。你背包里明明没有钥匙模型却说“你用钥匙打开了门”。这就是 LLM 的幻觉。要处理这种情况核心手段不是提示词写得天花乱坠而是程序层面加校验。4.1 为什么必须校验返回格式模型返回的 JSON 可能缺字段可能把 new_state 写成 state可能整段返回 Markdown 代码块。如果直接json.loads程序很容易崩溃。我一般会做三层处理提取 JSON如果返回内容里包含 json 代码块先剥离。校验必填字段narrative、new_state 必须存在。校验状态字段player_location、inventory、health、game_status 是否合法。def normalize_state(raw_state): valid_locations {forest, lake, cave, village} state { player_location: raw_state.get(player_location, forest), inventory: raw_state.get(inventory, []), health: raw_state.get(health, 100), game_status: raw_state.get(game_status, running) } if state[player_location] not in valid_locations: state[player_location] forest return state这样即使模型输出了不合理的字段游戏也能兜底不会直接崩溃。4.2 把玩家输入做一层预处理玩家的输入是不可控的。有人会输入“把电脑关机”有人会输入“我不想玩了”。与其让模型自由理解所有输入不如先做一层简单的意图解析识别动词、方向和物品名。DIRECTIONS [北, 南, 东, 西, up, down, north, south] VERBS [拿, 捡, 打开, 攻击, talk, use, take, open] def parse_input(text): direction None verb None for d in DIRECTIONS: if d in text: direction d for v in VERBS: if v in text: verb v return {direction: direction, verb: verb, raw: text}解析结果可以不以“丢弃用户输入”为目的而是把它作为辅助信息让模型知道这一轮玩家主要想干什么降低理解偏差。4.3 记录关键事件避免上下文爆炸当游戏进行到五六十轮时把所有对话历史塞给模型不仅慢而且会让模型注意力分散。这时需要引入“记忆摘要”机制。做法是这样的每轮结束后让模型额外生成一句“这一轮发生了什么”的摘要。当历史超过 N 轮时用摘要替换最早的历史。最新状态始终单独传入。历史消息[摘要1, 摘要2, 本轮玩家输入] 系统消息当前状态 JSON这就类似于 RAG 里“压缩-检索”的思想。对于 CaLLMar 这种长流程游戏控制上下文长度比堆一个大上下文窗口更重要。5. 模型选择、参数和成本怎么取舍这个项目对模型的要求比较微妙。不是越强越好而是要看“叙事创意”和“格式稳定”的平衡。有人用顶级模型跑得很顺换小模型后状态满天飞也有人用小模型加严格校验玩得很流畅。关键是理解不同参数的含义。5.1 在线 API 和本地模型怎么选两种方式各有适用场景我给一张对比表对比项在线 API本地模型效果综合较好尤其复杂叙事取决于模型大小和量化精度隐私数据会发送到服务端数据不出本机成本按 token 计费长局较贵硬件电费和折旧部署无需下载模型需要安装推理工具模型体积可能几十 GB格式稳定性大厂模型较强小模型可能经常输出非法 JSON如果你只是学习或做 Demo在线 API 足够如果想长期跑或者需要离线使用本地模型值得折腾。但本地模型遇到速度慢、显存不够时优先检查量化精度和模型规模不要一上来就买新显卡。5.2 温度、输出长度和上下文窗口文字冒险游戏里的 temperature 通常可以给到 0.7 到 1.0剧情会更有变化。但要注意温度太高容易导致逻辑跳跃玩家明明在北边的森林下一轮却出现在海边。如果你发现剧情太乱可以把 temperature 降到 0.6 左右。max_tokens 要同时容纳“narrative”和“new_state”两部分输出。如果剧情描述太长而 max_tokens 太短JSON 可能被截断。建议至少留出 1024 到 2048 个 token 的输出空间。上下文窗口则决定你能直接塞多少历史。如果是 8K 窗口建议只保留最近几轮加摘要如果是 128K 窗口也不能无限塞因为处理时间会变长。5.3 别把“模型能力”当成所有问题的原因代码报错时先看错误来自哪里。很多时候不是模型不行而是API Key 配置错误、余额不足或网络超时。返回内容被 Markdown 包裹解析正则写错。某个字段名和提示词不一致。本地模型服务没启动或端口配置不对。我建议在请求模型之外先打印原始响应三秒钟再想怎么调。6. 做成小产品从命令行到 Web、接口和日志跑通命令行版本后你会发现这东西给别人玩还是不方便。把人拉过来看终端不如直接发一个网页链接。CaLLMar 的最终形态可以是一个带聊天界面的小 Web 应用。6.1 用接口包一层服务界面不是重点重点是“每个玩家要有独立游戏会话”。用一个简单的 Python Web 框架比如 FastAPI可以这样抽象POST /api/action Body: {session_id: abc123, player_input: 向北走} Response: { narrative: 你来到湖边……, state: {...} }接口内部做的事和命令行完全一样读当前状态、组装消息、调模型、校验、更新状态、返回结果。唯一多出来的是 session 管理。6.2 会话隔离和持久化如果你只是自己玩单用户内存字典存 state 就够了sessions {} def get_session(session_id): if session_id not in sessions: sessions[session_id] load_initial_state() return sessions[session_id]但如果你把游戏开放给别人玩就要考虑每个 session 的状态独立存储不能互相覆盖。推荐把状态存到数据库或 Redis防止服务重启丢进度。状态文件命名要规范例如session_id.json。记录每一步的请求和响应日志方便事后排查玩家为什么卡住。在多人同时玩之前先确保单人的状态快照、恢复和日志是完整的。并发问题可以先不管但数据持久化必须提前考虑。6.3 日志和失败重试文字冒险游戏虽然不像数据处理任务那样需要大批量执行但也存在两种“批量”场景多个玩家同时玩需要并发处理。一次生成大量游戏剧本或结局分支需要批量请求模型。遇到批量请求时不要盲目把并发拉到 50。先看 API 限流和本地模型显存。我通常的做法是先用 1 个并发跑 10 条样例记录耗时和失败率再逐步上调。每次请求都写日志日志里至少包含 session_id、请求时间、模型返回的原始内容、解析结果、异常信息。[2025-01-01 10:00:01] sessionabc123 action向北走 response_time1.2s parseok state{player_location:lake}有了这种日志出问题时可以快速定位是模型返回问题、网络问题还是状态更新问题。7. 常见的坑和排查顺序最后这部分是我个人建议的排查顺序不是官方说明。按这个顺序走大部分问题都能在几分钟内锁定方向。7.1 先看输入、输出再谈调模型遇到任何异常第一步永远先打印原始内容玩家输入是什么有没有被预处理逻辑误改模型返回的原始文本长什么样是 JSON 还是大段废话解析后的状态是什么是否出现了不该出现的物品只要把这三份信息放到眼前很多问题立刻清楚。比如“地图总跳到随机地点”多半是状态字段没有被正确传进上下文而不是模型疯了。7.2 检查状态更新是否被覆盖一个典型的 bug 是玩家明明捡起了石头下一轮状态里石头不见了。原因通常是系统提示词要求模型输出“完整状态”但模型只返回了部分字段而你的代码又直接覆盖了整个状态。解决办法是合并而不是覆盖merged { player_location: new_state.get(player_location, game_state[player_location]), inventory: new_state.get(inventory, game_state[inventory]), health: new_state.get(health, game_state[health]), game_status: new_state.get(game_status, game_state[game_status]) }这样即使模型漏掉了 inventory玩家的背包也不会凭空消失。7.3 再查上下文、提示词和资源占用如果输入输出都没有明显问题再往下查历史消息是否太长是否把最新状态挤出了模型注意力系统提示词是不是自相矛盾例如既说“玩家必须有钥匙才能开门”又没在状态里传钥匙。API 调用是否超时本地模型是否因为并发太高而卡死磁盘空间、内存、显存是否告急排查时优先看最容易确认的网络、Key、格式、资源。最后才怀疑“模型不够聪明”。7.4 一份可以照抄的检查清单我把自己常用的检查项整理成清单遇到问题逐项打勾检查项怎么验证原始响应可读打印 response.choices[0].message.contentJSON 能解析json.loads 不报错字段齐全narrative / new_state 存在状态合理player_location 属于预置地点上下文不过长发送 token 数小于窗口上限API 未超时response_time 在预期范围内会话隔离正常两个 session 互相不串状态日志完整可以还原每一轮状态快照这八项覆盖了 CaLLMar 类项目八成以上问题。踩过几次坑之后我的真实感受是这类项目真正难的不是“让 LLM 说出好故事”而是“让 LLM 的说法和程序状态保持一致”。游戏机制的稳定性依赖的是状态校验、格式约束和上下文管理而不是单靠模型文笔。如果你打算做一个完整的 CaLLMar 体验先把单人命令行的状态循环跑稳再决定要不要加 Web 界面、批量生成和复杂记忆。所有扩展都建立在最基础的那条主链路上主链路不稳后面都是空中楼阁。