FantasyTavernNPC - 奇幻酒馆老板NPC对话模型

基于 HelloAgents 框架与 FastAPI 构建的动态交互式奇幻角色扮演 AI 智能体。

💡 项目简介

本项目是从零搭建的一个“与玩家进行沉浸式角色扮演对话的 AI 智能体”。玩家将置身于『飞龙与烈酒』旅店，与脾气火爆但沉迷卡牌游戏的矮人酒保进行互动。

• 解决什么问题？ 传统游戏中的 NPC 往往只能按照预设的脚本（选项树）进行对话，缺乏真实感、记忆力与动态情感反馈。本项目探索了 LLM 在游戏 NPC 自然语言交互中的应用。
• 有什么特色功能？ 包含自定义的 FIFO（先进先出）短期记忆管线、动态好感度驱动的提示词系统，以及一个极具代入感的中世纪酒馆 Web UI 界面。
• 适用于什么场景？ 游戏 NPC 交互系统原型设计、TRPG（桌上角色扮演游戏）辅助工具、大模型 Prompt 工程与角色扮演（Cosplay）测试。

✨ 核心功能

• 动态好感度注入: 根据 affinity_level 参数，动态调整 NPC 的语气、态度及对话策略。
• 定制化短期记忆 (Working Memory): 手写 FIFO 机制管理上下文窗口，既让 NPC 拥有记忆连贯性，又防止了 Token 溢出。
• 深度特色人设: 赋予 NPC 独特的爱好（精通“基础牌型结合武将生存技能”的奇幻卡牌游戏），大幅提升聊天可玩性。
• Web 可视化交互: 基于 FastAPI 构建后端，提供具有奇幻风格的 HTML/CSS/JS 响应式网页聊天界面。

🛠 技术栈

• HelloAgents框架: 使用了 v0.1.1 基础版本的 HelloAgentsLLM 和 SimpleAgent 组件。
• 使用的智能体范式: 基于 上下文工程 (Context Engineering) 的对话范式，通过数组队列手动拼接近期对话历史以维持 Agent 的角色一致性。
• 使用的工具和API: 兼容 OpenAI 格式的各大语言模型 API（如 Qwen, GLM 等）。
• 其他依赖库: FastAPI (Web框架), Uvicorn (ASGI服务器), Pydantic (数据校验), python-dotenv (环境变量管理)。

🚀 快速开始

环境要求

• Python 3.10+
• 建议使用虚拟环境 (venv)

安装依赖

pip install fastapi uvicorn pydantic python-dotenv "hello-agents==0.1.1"

pip install -r requirements.txt

配置API密钥

1. 在项目根目录创建 .env 文件。
2. 编辑 .env 文件，填入你的大模型 API 密钥及配置：

LLM_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
LLM_MODEL_ID="你的模型名称"
LLM_BASE_URL="你的模型请求地址"

运行项目

# 激活虚拟环境 (Windows)
venv\Scripts\activate
# (Mac/Linux)
# source venv/bin/activate

# 启动 FastAPI 后端服务器
uvicorn app:app --reload

启动成功后，打开浏览器访问：http://127.0.0.1:8000 即可开始体验！

🎯 使用示例

运行结果示例：

铜须 (Bronzebeard): 哟，又是个面生的冒险者。要住宿还是喝麦酒？先说好，没钱就滚出去！

你 (冒险者): 老板，来一杯黑麦啤酒！听说你很懂怎么把武将生存技能融合到斗地主里去？咱们切磋一下。

铜须 (Bronzebeard): (重重地把一大杯黑麦啤酒砸在吧台上，酒花四溢) 嗝~ 算你小子有眼光！以我胡子起誓，没人比我更懂这游戏！告诉你，用“张飞”的咆哮技能配合一把顺子，那伤害，见鬼，连巨龙都能干趴下！怎么，你想来一局？先把酒钱结了！

🌟 项目亮点

• 亮点1: 灵活的记忆闭环设计：在早期框架未内置复杂记忆组件的情况下，通过简单的 Python 列表和截断策略，低成本、高效地解决了 NPC 的“健忘”问题。
• 亮点2: 极简的前后端分离：摒弃了终端控制台的枯燥黑框，使用 FastAPI + 纯原生前端代码实现了“开箱即用”的图形化界面，用户体验极佳。
• 亮点3: 拒绝AI感：通过严格的 System Prompt 设计和对具体事物（卡牌规则）的探讨约束，成功抑制了 LLM 的“AI 助手味”，让角色扮演更生动。

📊 性能评估

• 角色扮演维持率: > 95%（在多轮测试中，极少出现跳出矮人酒保设定的情况）。
• 响应时间: 取决于所选用的 LLM API 网络延迟，通常在 1~3 秒内。
• 上下文开销: 严格控制在单次请求携带最近 10 条交互记录，有效控制 Token 消耗成本。

📅 未来计划

• 接入 EpisodicMemory (长期向量记忆)，让 NPC 能跨越不同会话记住玩家的名字和过往事件。
• 引入 Function Calling (工具调用)，让 NPC 可以真正执行“发牌”、“扣除玩家金币”或“查询天气”等动作。
• 增加 TTS (Text-to-Speech) 语音生成，实现带口音的矮人语音实时播报。

🤝 贡献指南

欢迎提出 Issue 和 Pull Request！如果你有更棒的卡牌游戏规则设计，或者想给旅店增加新的 NPC 角色，请随时参与共创。

📄 许可证

MIT License

👨‍💻 作者

• GitHub: kiri603
• Email: 1306842652@qq.com

🙏 致谢

感谢 Datawhale 社区和 Hello-Agents 项目提供的优秀教程与开源框架支持，让我能够从零理解并落地 AI 智能体开发！