企业官网建设流程全解析

用 Godot 与 HelloAgents 构建赛博小镇：多智能体 AI NPC 对话系统实战（记忆、好感度与日志全解析）

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

赛博小镇（Helloagents-AI-Town）是《Hello-agents》教材第 15 章的配套案例项目，它演示了如何基于 HelloAgents 框架构建一个带有 3 个 AI NPC（张三、李四、王五）的 2D 小镇模拟游戏，将多智能体系统、LLM 对话、双级记忆、情感化好感度与游戏引擎深度结合。阅读本文后，你将掌握从零搭建"FastAPI + HelloAgents + Godot"三层智能体游戏应用的完整方案：既能看懂项目 README 与四份配套指南（安装配置、记忆系统、好感度系统、对话日志），也能对照后端源码理解每个系统的底层实现原理。

项目全景：赛博小镇是什么

赛博小镇是一个基于 HelloAgents 框架的 AI 小镇模拟游戏，用于展示多智能体系统（Multi-Agent System）在游戏场景中的应用。玩家可以在一间 2D 办公室中自由移动，走近 NPC 并按 E 键与其实时对话——每个 NPC 都由独立的 Agent 驱动，拥有自己的性格、岗位、记忆和对你（玩家）的好感度。

功能特性一览

项目 README 明确列出的核心能力包括：

• 3 个 AI NPC（张三、李四、王五），各自拥有独立的角色设定；
• 智能对话系统，基于 HelloAgents 的SimpleAgent驱动；
• 记忆系统：短期（工作记忆）+ 长期（情景记忆）双层记忆；
• 好感度系统：5 个关系等级（陌生 / 熟悉 / 友好 / 亲密 / 挚友）；
• NPC 自主行为：即使玩家不交互，NPC 也会"闲逛、工作"并定时产出状态对话；
• 完整的日志系统：控制台 + 文件双路输出，按日期归档。

技术栈

说明：README 中标注 LLM 为 "OpenAI GPT-4 (可配置其余的LLM服务)"，而当前仓库 backend/config.py 实际默认配置为Qwen/Qwen2.5-72B-Instruct与 ModelScope 兼容端点，两者都支持通过环境变量自由切换，下文第 3 节会给出完整参数说明。

三个 NPC 角色

角色定义全部集中在 backend/agents.py 的NPC_ROLES字典中：

每个角色还配置了expertise（专长）、style（说话风格）、hobbies（爱好）等字段，这些字段会直接注入到系统提示词中，决定 NPC 的对话人设。

项目目录结构

code/chapter15/Helloagents-AI-Town/ ├── README.md # 项目总览（本文主文档） ├── SETUP_GUIDE.md # 安装配置指南 ├── MEMORY_SYSTEM_GUIDE.md # 记忆系统指南 ├── AFFINITY_SYSTEM_GUIDE.md # 好感度系统指南 ├── DIALOGUE_LOG_GUIDE.md # 对话日志系统指南 ├── backend/ # FastAPI 后端 │ ├── main.py # 主程序与全部 API 路由 │ ├── config.py # 配置（.env 加载） │ ├── models.py # Pydantic 数据模型 │ ├── agents.py # NPC Agent 管理器（含记忆与好感度集成） │ ├── relationship_manager.py # 好感度管理器 │ ├── batch_generator.py # 批量对话生成器 │ ├── state_manager.py # NPC 状态管理器（定时批量更新） │ ├── logger.py / view_logs.py # 日志系统与查看工具 │ └── memory_data/ # 每个 NPC 独立的记忆存储目录 └── helloagents-ai-town/ # Godot 游戏工程 ├── scenes/ # main / npc / player / dialogue_ui 场景 ├── scripts/ # GDScript（api_client.gd、config.gd 等） └── project.godot # Godot 项目配置

环境要求与安装配置（快速开始）

完整的安装步骤详见 SETUP_GUIDE.md，以下为核心流程整理。

系统要求

• 操作系统：Windows 10/11、macOS、Linux 均可；
• Godot：4.2+（推荐 4.3）；
• Python：3.10+；
• Git（可选，用于克隆项目）。

安装步骤

步骤 1：获取项目。若使用 Git，克隆仓库后进入chapter15目录；也可以直接下载项目 ZIP 解压。

步骤 2：安装 Godot。从 Godot 官网下载 4.2+ 版本，解压后直接运行（无需额外安装依赖）。

步骤 3：配置 Python 环境。在backend目录下创建并激活虚拟环境，然后安装依赖：

cd backend python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate pip install -r requirements.txt

步骤 4：安装 HelloAgents 框架。agents.py、relationship_manager.py、batch_generator.py均通过sys.path.insert(0, .../HelloAgents)将框架目录加入 Python 路径，因此需要先以可编辑模式安装：

cd ../HelloAgents pip install -e . cd ../backend

步骤 5：配置环境变量。创建.env文件（config.py通过dotenv自动加载backend/.env），按需填写 LLM 相关配置：

# API配置 API_HOST=0.0.0.0 API_PORT=8000 # LLM配置 - 请填写你的API密钥 LLM_API_KEY=sk-your-api-key-here LLM_BASE_URL=https://api-inference.modelscope.cn/v1/ LLM_MODEL_ID=Qwen/Qwen2.5-72B-Instruct

重要：LLM_API_KEY必须替换为你的真实密钥。若不配置 API 密钥，后端会以"模拟模式/预设对话模式"运行：agents.py中 LLM 初始化失败会降级为self.llm = None，batch_generator.py则会使用内置的preset_dialogues预设对话库，基础游戏功能仍可用，只是 NPC 不再具备真实 AI 对话能力。

步骤 6：启动后端服务：

cd backend python main.py

预期输出：

📝 对话日志文件: .../backend/logs/dialogue_2025-10-15.log 📂 日志目录: .../backend/logs ============================================================ 🎮 赛博小镇后端服务启动中... ============================================================ ... ✅ 所有服务已启动! 📡 API地址: http://0.0.0.0:8000 📚 API文档: http://0.0.0.0:8000/docs ============================================================

步骤 7：打开 Godot 项目。启动 Godot → 点击"导入" → 选择Helloagents-AI-Town/helloagents-ai-town/scenes/main.tscn→ "导入并编辑"。

步骤 8：运行游戏。在 Godot 编辑器中点击右上角"运行"按钮（或按 F5），游戏窗口打开后即可操作。

游戏操作

快速测试

• 测试后端 API：访问http://localhost:8000/docs（FastAPI 自动生成的 Swagger 文档，可在页面直接调试所有接口）；
• 查看对话日志：cd backend && python view_logs.py tail，实时滚动显示对话记录。

系统架构：FastAPI 后端与 Godot 客户端的协作

三层调用架构

┌─────────────────────────────────────────────────────┐ │ Godot 客户端 (helloagents-ai-town) │ │ api_client.gd ──HTTP──> POST /chat、GET /npcs/status│ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ FastAPI 后端 (backend/main.py) │ │ ├─ NPCAgentManager 对话 + 记忆 + 好感度 │ │ ├─ RelationshipManager LLM 情感分析，更新好感度 │ │ ├─ NPCStateManager 定时批量更新 NPC 自主状态 │ │ └─ NPCBatchGenerator 一次 LLM 调用生成所有 NPC 话 │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ HelloAgents 框架 │ │ SimpleAgent / HelloAgentsLLM / MemoryManager │ │ (SQLite 权威存储 + 向量检索) │ └─────────────────────────────────────────────────────┘

后端模块职责

backend/README.md 给出了清晰的模块划分：

API 路由总览

从 backend/main.py 的源码可以确认以下完整路由：

main.py使用lifespan生命周期钩子：启动时依次执行settings.validate()配置校验、get_npc_manager()初始化 NPC 与记忆、get_state_manager(...)启动状态管理器后台任务；关闭时优雅停止。

配置说明（config.py）

backend/config.py 的Settings类通过load_dotenv加载同目录.env：

Settings.validate()在启动时检查LLM_API_KEY：缺失时打印警告并返回False，提示在.env中配置密钥。

NPC 角色设计与系统提示词工程

系统提示词的生成

create_system_prompt函数（agents.py）将NPC_ROLES中的角色字段动态渲染成一段结构化的 system prompt，包含四个部分：

1. 角色设定：职位、性格、专长、说话风格、爱好、当前位置、当前活动；
2. 行为准则：保持角色一致性、用第一人称"我"、回复控制在 30-50 字、可以提及工作内容与爱好、对玩家友好、超出专长时推荐其他同事、偶尔展现个性化口头禅；
3. 对话示例：给出"你好，你是做什么的？""最近在做什么项目？"两个 few-shot 示例；
4. 重要约束：不能说"我是 AI/语言模型"，要像真实办公室同事一样自然对话，可以表达情绪，回复要有人情味。

这段提示词是 NPC"人设感"的核心来源，也是教学上理解system prompt 工程的最佳范例。

Agent 的创建与降级

NPCAgentManager.__init__先尝试HelloAgentsLLM()初始化 LLM：成功则用SimpleAgent(name=f"{name}-{role['title']}", llm=self.llm, system_prompt=system_prompt)为每个 NPC 创建独立 Agent；失败则进入模拟模式（agent=None），对话返回"当前为模拟模式，请配置 API_KEY 以启用 AI 对话"的提示。

记忆系统：让 NPC 记住你

赛博小镇的 NPC 通过 HelloAgents 的MemoryManager获得记忆能力，能够记住与玩家的对话历史并在后续对话中引用。详见 MEMORY_SYSTEM_GUIDE.md。

核心功能

1. 工作记忆（Working Memory，短期）：存储最近的 10 条对话，2 小时后自动过期，用于当前对话上下文；
2. 情景记忆（Episodic Memory，长期）：持久化存储重要对话，支持语义检索（基于向量索引），最多 100 条，自动遗忘重要性低于 0.3 的记忆；
3. 记忆隔离：每个 NPC 拥有独立的记忆系统，NPC 之间互不干扰；每个玩家的对话独立存储。

使用效果示例

• 短期记忆：玩家 5 分钟后问"还记得我刚才问你什么吗？"，张三能复述之前的问答内容；
• 长期记忆：第二天再问"我们之前聊过编程语言吗？"，NPC 能回忆起前一天的话题；
• 记忆隔离：问李四"我刚才和张三聊了什么？"，李四会明确表示不知道，因为记忆按 NPC 隔离。

技术实现：记忆检索与增强对话

NPCAgentManager.chat()（agents.py）的完整调用链：

1. 记录对话开始（日志系统） 2. 获取当前好感度，生成「当前关系 + 对话风格」上下文 3. 用玩家消息检索相关记忆（working + episodic，limit=5，min_importance=0.3） 4. 构建增强提示词 = 好感度上下文 + 记忆上下文 + 当前对话 5. 调用 agent.run() 生成回复 6. 好感度分析并更新 7. 把玩家消息与 NPC 回复写入记忆（含好感度、情感等元数据）

关键实现细节：

• 记忆检索：memory_manager.retrieve_memories(query=message, memory_types=["working", "episodic"], limit=5, min_importance=0.3)，同时检索短期与长期记忆，并按重要性和相关性过滤；
• 记忆上下文构建：_build_memory_context将检索到的记忆按时间戳（%H:%M）格式化为"【之前的对话记忆】"段落；
• 记忆写入：_save_conversation_to_memory将"玩家说：..."（importance=0.5）与"我说：..."（importance=0.6）两条记录写入工作记忆，同时附带affinity（当时好感度）、affinity_change（变化量）、sentiment（情感）等元数据，实现记忆与好感度两个系统的数据联动。

记忆配置（MemoryConfig）

每个 NPC 初始化记忆管理器时的默认配置（agents.py）：

memory_config = MemoryConfig( storage_path=f"./memory_data/{npc_name}", # 存储路径 working_memory_capacity=10, # 工作记忆容量（最近10条） working_memory_tokens=2000, # 工作记忆token限制 max_capacity=100, # 长期记忆总容量 importance_threshold=0.3, # 重要性阈值 decay_factor=0.95 # 时间衰减系数 ) memory_manager = MemoryManager( config=memory_config, user_id=npc_name, enable_working=True, # 启用工作记忆（短期） enable_episodic=True, # 启用情景记忆（长期） enable_semantic=False, # 不需要语义记忆 enable_perceptual=False # 不需要感知记忆 )

参数调整建议（来自记忆系统指南）：

记忆 API 与测试

• POST /chat对话自动读写记忆；GET /npcs/张三/memories?limit=10查看记忆；DELETE /npcs/张三/memories?memory_type=working清空指定类型记忆（不传memory_type则清空全部）。
• 测试方法：运行python test_memory.py；或通过 Swagger 文档连续对话后查看记忆列表；或在 Godot 中与 NPC 多次对话观察其是否"记住"之前的内容。

调试技巧

• 在chat()中打印检索到N条相关记忆、对话已保存到NPC的记忆中；
• 直接查 SQLite：sqlite3 memory_data/张三/memory.db后SELECT * FROM memories;（仓库中memory_data/下实际生成的文件名为memory.db，各 NPC 目录相互独立）；
• 排查"记不住"问题：检查日志中是否有"记忆系统已初始化"、memory_data目录是否存在、是否被遗忘机制清除（可降低importance_threshold）。

好感度系统：NPC 的情绪反馈

好感度系统让 NPC 能根据玩家对话内容自动调整亲疏态度，并实时影响对话风格。详见 AFFINITY_SYSTEM_GUIDE.md。

核心功能

1. 自动情感分析：使用独立的 LLM Agent（AffinityAnalyzer）分析对话——判断玩家态度（友好/中立/不友好）、对话内容（积极/中立/消极）、互动质量（深入/一般/敷衍）、情感倾向（赞美/批评/中性）；
2. 好感度动态调整：友好对话 +1~+10，批评对话 -3~-15，数值限定在 0-100；
3. 关系等级系统（get_affinity_level，见 relationship_manager.py）：

4. 对话风格调整：好感度等级对应的修饰词（get_affinity_modifier）被注入 NPC 的对话上下文，实现"高好感度更热情、低好感度更冷淡"的实时风格切换。

好感度变化规则

情感分析提示词中内置的变化规则：

技术实现：情感分析全流程

RelationshipManager.analyze_and_update_affinity的执行链路（relationship_manager.py）：

玩家消息 + NPC 回复 ↓ 构建分析提示（玩家/张三 两轮对话文本） ↓ 调用 analyzer_agent.run(prompt) ↓ _parse_analysis 解析 LLM 的 JSON 响应 ↓ should_change=true 时： new_affinity = clamp(当前好感度 + change_amount, 0, 100) 记录 old_level / new_level，返回分析结果

值得学习的是_parse_analysis的三层容错解析策略（relationship_manager.py）：

1. 先尝试json.loads直接解析完整 JSON；
2. 失败则截取首个{到末个}之间的子串再解析；
3. 再失败则用正则表达式分别提取should_change、change_amount、reason、sentiment四个字段；
4. 全部失败则返回默认值（不改变好感度）并打印警告。

这种"直接解析 → 提取 JSON 片段 → 正则兜底"的层级策略，对任何调用 LLM 输出结构化 JSON 的生产代码都有直接借鉴意义。

好感度 API 与测试

• GET /npcs/张三/affinity?player_id=player返回{affinity, level, modifier}；
• GET /affinities?player_id=player返回所有 NPC 好感度；
• PUT /npcs/张三/affinity?affinity=80&player_id=player手动设置好感度（测试用），参数范围 0-100，越界返回 400；
• 测试脚本python test_affinity.py覆盖：基本功能、提升/降低、等级变化、对话风格调整、渐进提升。

调优建议

想调整敏感度，修改relationship_manager.py中的情感分析提示词：更敏感可扩大变化量范围（如 -20 到 +15）；更保守可缩小（如 -5 到 +5）；更细腻可增加分析维度。如果好感度长期不变，优先检查日志中的情感分析结果与 LLM JSON 解析是否成功。

对话日志系统：全流程可视化

日志系统把所有对话信息同时输出到控制台与按日期命名的文件，便于学习者观察"记忆检索 → 回复生成 → 好感度变化 → 记忆保存"的完整链路。详见 DIALOGUE_LOG_GUIDE.md。

自动记录的信息

每次对话自动记录：对话开始/结束、玩家消息、当前好感度与关系等级、检索到的相关记忆、NPC 回复内容、好感度变化分析、关系等级变化、记忆保存确认。

日志查看工具

日志格式示例

14:30:25 - ============================================================ 14:30:25 - 💬 对话开始: 张三 <-> 玩家 14:30:25 - ============================================================ 14:30:25 - 📝 玩家消息: 你好,很高兴认识你! 14:30:25 - 💖 当前好感度: 50.0/100 (友好) 14:30:25 - 🧠 检索到0条相关记忆 14:30:26 - 🤖 正在生成回复... 14:30:28 - 💬 张三回复: 你好!我也很高兴认识你。我是Python工程师张三,最近在研究多智能体系统。 14:30:28 - 📊 正在分析好感度变化... 14:30:30 - 📈 好感度变化: 50.0 -> 56.0 (+6.0) 14:30:30 - 原因: 友好问候 14:30:30 - 情感: positive 14:30:30 - 💾 对话已保存到张三的记忆中 14:30:30 - ============================================================ 14:30:30 - ✅ 对话完成

技术实现

logger.py使用 Python 标准库logging：创建名为dialogue的 logger，同时挂载FileHandler（写文件，utf-8 编码）与StreamHandler（输出控制台），实现双路输出。agents.py的chat()方法通过log_dialogue_start、log_affinity、log_memory_retrieval、log_generating_response、log_npc_response、log_analyzing_affinity、log_affinity_change、log_memory_saved、log_dialogue_end等函数在流程各节点埋点，把整个对话生命周期"录制"下来。

说明：日志按日期分类，每次对话约 0.5-1 KB，一天通常不超过 1 MB，磁盘占用很小。

NPC 自主行为：批量对话生成与状态管理

即使玩家不与 NPC 交互，NPC 也会像真实同事一样"自言自语"：写代码、开评审会、喝咖啡，并在头顶气泡中展示。这套自主行为由state_manager.py+batch_generator.py协作完成。

批量生成：一次调用生成三个 NPC 的状态

backend/README.md 说明了批量策略的成本优势（按 30 秒更新一次估算）：

• 传统方式：3 个 NPC × 每 30 秒各调一次 = 6 次 API 调用/分钟，每小时 360 次；
• 批量方式：1 次批量调用/30 秒 = 2 次 API 调用/分钟，每小时 120 次，成本降低约 66%。

工作流程

1. 定时器触发（默认30秒） ↓ 2. 批量生成器构建提示词（含场景与3个NPC信息） ↓ 3. 一次 LLM 调用生成所有 NPC 对话（JSON） ↓ 4. 解析 JSON 响应（容错提取） ↓ 5. 更新状态管理器缓存（current_dialogues） ↓ 6. Godot 客户端定时 GET /npcs/status 获取

源码级细节

• 场景推断：batch_generator.py的_get_current_context()按当前小时自动推断场景（清晨/上午/午餐/下午/傍晚/夜晚），并注入提示词；
• JSON 容错解析：_parse_response先直接解析，失败则截取首尾大括号再解析，并校验三个 NPC 键是否齐全；
• 预设降级：LLM 不可用时使用preset_dialogues（morning/noon/afternoon/evening 四套预设台词）；
• 状态缓存：state_manager.py的get_current_state()返回{dialogues, last_update, next_update_in}，其中next_update_in为距下次更新的倒计时秒数；
• 更新频率调优：修改config.py的NPC_UPDATE_INTERVAL——开发测试 10 秒、正式运行 30-60 秒、低成本模式 120 秒。

Godot 客户端接入

Godot 端通过 scripts/api_client.gd 与后端通信，这是一个Node脚本，封装了三个HTTPRequest节点：

代码要点：

• 通过JSON.stringify序列化请求体，携带Content-Type: application/json头；
• 回调中先检查response_code != 200并发出错误信号，再解析 JSON 并emit对应信号，UI 层通过连接这些信号更新对话框与 NPC 气泡；
• 状态请求做了"请求进行中跳过本次"的防重入保护（检查HTTPClient.STATUS_DISCONNECTED），避免高频轮询堆积请求。

场景与脚本文件位于 helloagents-ai-town/scenes（main.tscn、npc.tscn、player.tscn、dialogue_ui.tscn）与 scripts（main.gd、npc.gd、player.gd、dialogue_ui.gd、config.gd）。后端已配置 CORS 中间件（CORS_ORIGINS，默认["*"]），支持 Godot HTML5 导出时的跨域访问。

常见问题排查

后端启动失败？依次检查：Python 版本是否 ≥ 3.10、是否激活虚拟环境、依赖是否安装完整（pip install -r requirements.txt）、.env是否配置正确；若出现LLM 初始化失败，确认LLM_API_KEY已设置。

Godot 无法打开项目？确认 Godot 版本 ≥ 4.2、project.godot文件存在、选择了正确的导入目录（helloagents-ai-town工程目录）。

游戏运行但无法对话？检查后端服务是否在运行、后端地址是否正确（默认http://localhost:8000）、查看 Godot 控制台错误信息。

NPC 记不住对话 / 好感度不变化？参见前文记忆系统与好感度系统的调试技巧：检查日志中的"记忆系统已初始化"与情感分析输出、确认memory_data目录存在、必要时降低importance_threshold或调整情感分析提示词。

对话无响应？后端会自动降级到预设对话/模拟模式（日志提示"将使用预设对话模式"），基础功能不受影响，配置 API 密钥后即可恢复真实 AI 对话。

教学价值与扩展方向

本项目是《Hello-agents》第 15 章的配套案例，其教学价值在于把教材中的理论概念落到可运行的游戏项目上：

1. MemoryManager 实战：初始化记忆管理器、配置工作/情景记忆、添加与检索记忆；
2. 记忆检索策略：工作记忆快速检索、情景记忆语义检索、混合检索结合时间与相关性；
3. 双存储机制：SQLite 权威存储 + 向量索引语义检索，保证数据一致性与检索能力；
4. 记忆遗忘机制：基于重要性的自动遗忘、基于时间的 TTL 过期、容量限制的优先级淘汰；
5. LLM 情感分析：设计情感分析提示词、约束 JSON 输出、三级容错解析；
6. 多系统协同：好感度 ↔ 记忆 ↔ 日志 ↔ 状态管理的数据联动设计；
7. 成本工程：批量生成策略显著降低 LLM API 调用次数。

从源码结构看，项目预留了清晰的扩展点（backend/README.md 的开发建议）：在agents.py的NPC_ROLES中添加配置即可新增 NPC（同时需在batch_generator.py的preset_dialogues中补充预设台词）；修改create_system_prompt可自定义对话风格；修改batch_generator.py的_build_batch_prompt可调整批量生成提示词；在 Godot 中可进一步实现好感度 UI 显示与更多基于好感度的游戏机制。

本项目遵循 CC BY-NC-SA 4.0 许可证发布，后端部分遵循 HelloAgents 项目的开源协议。现在，启动后端、按下 F5，走进 Datawhale 办公室，和三位各有性格的 AI 同事聊聊吧。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents