「命令与征服」HTML5 复刻版（Command & Conquer）

这是一个以教学演示为目的的文本地下城探索项目：玩家在命令行中以普通英文描述行动，由本地的 Qwen2.5-3B 模型扮演“地下城主”进行解说、判断意图并选择可用的工具调用，而真正决定角色生死与房间状态的始终是 Python 代码。项目本身定位为 GenAI 课程作业，因此刻意把职业、技能树、程序化地图等复杂系统排除在外，把重点放在“大模型如何在受控边界内驱动一个可玩的游戏循环”这一命题上。

从可玩内容看，冒险被组织成七个地点：入口、十字路口、军械库、哥布林巢穴、封印之门、Boss 圣所与最终出口。主线路径相当明确——先击败哥布林取得铁钥匙，用钥匙打开北侧封印之门，再击败死灵法师 Morcant，最后从黎明之门离开地牢完成通关。军械库中有一把可选的钢剑，拾取后能显著降低战斗难度；玩家也可以使用治疗药水等消耗品。README 给出的示例指令覆盖了探索、移动、对话与战斗等基本动作，例如“look around”“go north”“talk to the stranger”“go west”“attack the skeleton”“pick up steel sword”“use health potion”“save game”，输入 help 可以查看提示，quit 或 exit 退出游戏。

架构上最值得关注的是“权威状态”与“语言模型”的严格分离。Python 侧掌管所有房间定义、玩家生命值、物品、战斗结算、门锁、存档与胜负条件；模型只能通过工具请求动作，无法直接设置敌人血量、切换房间、执行任意 Python 代码或访问文件系统。每个工具在真正执行前都会校验参数，并把 Game 对象返回的真实结果回传给模型。可用工具包括检查类（inspect_room、check_inventory、check_status）、行动类（move、attack、use_item、pick_up_item）以及交互与流程类（talk_to_stranger、save_current_game、load_saved_game）。这种设计实际上给 LLM 套上了一层受限 API：模型负责“理解和表达”，游戏逻辑负责“裁判”。

核心特性

Agent 的工作流程由 ai/prompts.py 中的系统提示约束：地下城主必须通过工具获取状态、不得凭空编造结果、回答保持简洁。DungeonAgent 负责调用带工具的本地模型，执行模型请求的工具，再把结果回传，形成一轮工具调用循环。为了在本地小模型上保持响应速度，它只保留最近四轮玩家与 DM 的对话，并附加一段由 Python 生成的紧凑冒险摘要（当前位置、背包、已击败敌人、已发现线索），因此像“他刚才跟我说了什么”这类指代问题仍能获得有效上下文，同时聊天记录不会被当作游戏状态的真相来源。项目还内置了一个刻意做得很小的意图兜底解析器：当 Ollama 暂时不可用时，常见的探索类指令依然能被接受，游戏不会直接崩溃，只是自然语言理解、叙述与工具选择的质量会下降。

运行方式在 README 中说明得比较具体：先安装 Ollama 并执行 ollama pull qwen2.5:3b 拉取模型，然后可选地创建并激活 Python 虚拟环境、通过 requirements.txt 安装依赖，确认 Ollama 服务在运行后执行 python main.py 启动。文中给出的命令示例为 PowerShell 形式，并明确指出应在 Windows 终端或 VS Code 终端中运行。存档以 JSON 写入 data/saves/dungeon_save.json，游戏事件记录在 data/game.log，两者都由 utils/file_manager.py 中的辅助函数负责读写。

代码结构清晰且规模很小，适合课堂讲解：main.py 是命令行主循环，game/ 目录存放玩家、敌人、房间与权威机制，ai/ 目录存放 Ollama 模型封装、系统提示与 LangChain agent，utils/file_manager.py 负责存档与日志，data/ 用于存放生成的存档和日志文件。README 也列出了后续可扩展方向，包括更多房间与任务、更丰富的敌人能力、多个 NPC，以及一个 Streamlit 图形界面；当前版本刻意让类与机制保持简单，以便在课程演示中逐步解释。

技术要点

适合学习的点主要集中在三处：一是用系统提示与工具白名单把模型限制在“提议者”角色，理解工具调用与状态机之间的边界；二是用少量的对话历史加结构化摘要而非全量聊天记录来维持上下文，这是在本地小模型上控制延迟的实用技巧；三是用兜底解析器处理依赖服务不可用的降级场景。需要注意的地方在于，模型输出质量受限于本地 3B 规模模型与机器性能，游戏内容体量很小，更接近技术验证与教学样例而非完整可长期游玩的商业作品；此外跨平台运行虽在技术上可行，但文档只覆盖了 Windows 终端流程，其他系统需自行验证环境依赖。