Freeciv-web：HTML5/WebGL 开源回合制策略游戏（文明类）

这是一个用 Python 编写的交互式文字冒险引擎，玩家在终端里输入行动，由大语言模型扮演「地下城主」（Dungeon Master，DM）负责叙述剧情、判定结果，并同步维护物品、地点、关系、事件等游戏状态。与传统的固定分支文字冒险不同，它没有预先写死的故事树，而是把世界设定作为「事实基础」放进提示词，让模型在每一回合根据玩家的自由输入即兴生成下一段剧情，同时把可变的游戏状态抽取成结构化数据保存下来，从而在自由创作与状态一致之间取得平衡。项目通过 Groq API 调用 Llama 3.3 完成推理，README 强调其卖点之一是交互回合的响应速度。

在功能层面，README 列出了四项关键特性。第一是动态叙事：模型依据结构化的世界设定生成有上下文关联的奇幻故事，而不是随机拼接的段落。第二是状态同步：系统采用「双提示」架构，在生成叙事之外，另有一次调用专门把本回合发生的状态变化（获得的物品、到达的地点、人物关系的变化等）抽取为结构化 JSON，使背包、位置等状态可以被程序读取而非只存在于自然语言里。第三是持久上下文：引擎保留最近 12 轮对话作为滑动窗口，并把最新的游戏状态直接注入系统提示，以此在不超出 token 限制的前提下维持长期连贯性。第四是推理速度，依赖 Groq 的推理服务来支撑即时的交互节奏。

核心特性

代码结构在 README 中被明确划分为职责清晰的几块：main.py 负责命令行界面（CLI）的输入输出循环与结果格式化，是玩家直接接触的入口；src/engine.py 是核心编排层，承担提示词构造、与 LLM 的通信以及状态抽取；src/models.py 使用 Pydantic 定义 GameState 与 StateUpdate 等严格的数据模型，为状态数据提供校验与类型约束；data/world.json 则是一份世界设定的「事实基准」数据库，包含初始地点、NPC、物品与阵营历史等信息，作为叙事的知识底座被送入提示词。

技术设计上有两个值得注意的取舍。其一是把「叙事生成」和「状态抽取」拆成两个独立步骤：主调用负责创造性的故事描写，次级调用则强制输出严格的 JSON 结构来追踪背包与玩家选择，用职责分离的方式降低模型在自由发挥时编造物品或错记位置的幻觉风险。其二是记忆策略：对话历史只保留最近 12 轮，但每一回合都会把更新后的 GameState 重新注入系统提示，因此长期信息以结构化状态而非冗长对话的形式被「隐式」保留，这是一个在上下文长度受限时相当实用的折中方案。此外 README 还提到系统提示中设置了语言约束，强制模型始终以英文回应，避免提示词噪声导致语言漂移。

技术要点

技术栈方面，项目要求 Python 3.8 及以上，LLM 服务由 Groq API 提供，数据校验依赖 Pydantic，界面为纯命令行/终端 UI，没有任何图形渲染或游戏引擎依赖。上手流程比较轻量：克隆仓库、创建并激活虚拟环境、执行 pip install groq pydantic 安装依赖、配置 GROQ_API_KEY（README 给出了环境变量与直接写入 src/engine.py 两种方式），最后运行 python main.py 即可开始游戏。README 分别给出了 Windows 的 venv\Scripts\activate 与 macOS/Linux 的 source venv/bin/activate 命令，说明作者预期项目在这两类环境上都能直接运行。Groq 控制台提供免费额度，密钥需要自行申请。

从学习角度看，这个项目更像一个「LLM 游戏状态管理」的教学型骨架，而不是成品游戏：它演示了如何用 Pydantic 建模游戏状态、如何用双提示把自然语言创作与确定性数据结构解耦、如何用滑动窗口加状态注入控制上下文预算，以及如何把世界设定文件（world.json）当作可替换的知识底座。需要注意的限制是：它完全基于文字，没有图形界面；强依赖外部 API 与网络，离线不可玩；语言一致性的约束被固定为英文输出；README 的未来路线图中明确列出存档/读档系统尚待实现，同时计划引入 RAG 做世界设定的向量检索，并把 JSON 模式的状态抽取迁移到原生 Function Calling 以获得更严格的模式遵循。由于项目未附测试、示例运行日志或许可信息，实际生成质量、token 消耗与稳定性仍需自行运行核验。