Agent 速成笔记 · 第 15 章构建赛博小镇

源：Datawhale《Hello-Agents》第 15 章｜定位：实战案例｜一句话：把 LLM 智能体塞进一个 2D 游戏世界，让 NPC 有性格、有记忆、有关系，并且跑得起、付得起。

0. 一章速览（30 秒）

一句话：赛博小镇 = 游戏引擎（Godot）+ 后端服务（FastAPI）+ 智能体框架（HelloAgents）三层分离；每个 NPC 是一个独立的 SimpleAgent 实例，靠「人设提示词 + 双层记忆 + 好感度」三件套，产出可自然语言交互、记得住你、态度会变的虚拟同事。
本章解决什么问题：传统 NPC 只能念预设台词或走对话树；本章演示如何把「自然语言对话 + 记忆 + 关系量化」工程化落地，并用批量生成把 LLM 调用成本压到原来的 1/3。
必须记住的 5 个点：
- 一个 NPC 一个 Agent 实例：人格由系统提示词定义，位置/忙闲由后端状态管理器定义，两者解耦。
- 记忆分两层：WorkingMemory 管连贯（容量 10 条、TTL 120 分钟），EpisodicMemory 管回忆（SQLite + Qdrant 语义检索，召回 top_k=3）。
- 好感度是 0-100 的连续值，五级映射；涨跌由 LLM 做情感分析打分（友好 +5、中立 +2、不友好 -3），并把当前等级写回 NPC 的系统提示词。
- 成本优化的核心手法是混合模式：N 个 NPC 的背景闲话合并成 1 次 LLM 调用（要求 JSON 输出），玩家真正发起对话时才走该 NPC 的专属 Agent。
- 前后端边界必须切干净：Godot 管感知与表现（Area2D 检测靠近、气泡显示、四方向动画），后端管决策（记忆检索 + LLM 生成 + 好感度结算）。

1. 项目目标与总体架构（15.1）

1.1 结合点：Agent 补上游戏 NPC 缺的那块

是什么：赛博小镇把「智能体技术」与「游戏引擎」结合，造一个有生命力的 AI 小镇。玩家用 WASD 在一个 2D 像素风 Datawhale 办公室场景里走动，走到 NPC 附近按 E 键，就能用自然语言跟 NPC 聊天。
和传统 NPC 的差别：传统 NPC 的台词是编剧写死的，就算对话树做得再复杂也是有限分支。本章的 NPC 能理解玩家的任意输入，记得上次聊了什么，并且对玩家的态度会随互动变化。
为什么值得做：同一套机制可直接迁移到教育游戏（NPC 扮演历史人物、科学家做互动式教学）、虚拟办公室（NPC 扮演同事、导师）以及情感陪伴/心理健康场景；最直接的用法是给传统游戏加 AI NPC。
本章的五个核心功能：智能 NPC 对话系统、记忆系统（短期 + 长期）、好感度系统、游戏化交互（2D 像素办公室自由移动）、实时日志系统。

1.2 四层分离架构

层	技术	职责
前端层	Godot 4.5	游戏渲染、玩家控制、NPC 显示、对话 UI
后端层	FastAPI	API 路由、NPC 状态管理、对话处理、日志记录
智能体层	HelloAgents	NPC 智能、记忆管理、好感度计算
外部服务层	LLM API / Qdrant / SQLite	推理能力、向量存储、数据持久化

怎么运作：每个 NPC 在后端就是一个 SimpleAgent 实例，拥有独立的记忆与状态；Godot 只负责"画面上的那个人"和"玩家的输入"，所有智能都在后端。
工程要点：这种分层让游戏逻辑与 AI 逻辑可以独立开发和测试，互相不牵连。后端侧文件按职责切分——main.py（FastAPI 入口）、agents.py（NPC Agent 系统）、relationship_manager.py（好感度）、state_manager.py（状态）、logger.py（日志）、models.py（数据模型）；游戏侧 scenes/ 下放 main/player/npc/dialogue_ui 四个 .tscn，scripts/ 下放同名 .gd 脚本外加 api_client.gd 与 config.gd。
环境基线（原文口径）：Godot 4.2 或更高版本、Python 3.10 或更高版本、一个 LLM API 密钥（OpenAI / DeepSeek / 智谱等）。

1.3 一次交互的完整数据流

这是全章最该背下来的一条链路，它把"游戏"和"Agent"缝在了一起：玩家按 E 键 → Godot 通过 HTTP API 把对话请求发给 FastAPI 后端 → 后端调用该 NPC 的 SimpleAgent → Agent 从记忆系统检索相关历史（短期 + 长期）→ Agent 调用 LLM 生成回复 → 后端更新 NPC 状态与好感度、写日志 → 回复返回 Godot 并更新 UI，完成一次交互循环。

关键理解：这段往返就是一个完整的"感知→决策→行动"周期，只是"感知"发生在游戏引擎里（Area2D + 按键事件），"决策"发生在后端（记忆检索 + LLM），"行动"体现为 UI 文本加状态值变化。第 2 章的最小 Agent 循环在这里被拆成了跨进程的两半。

2. NPC 智能体系统（15.2）

2.1 一 NPC 一 Agent：SimpleAgent 的复用

是什么：每个 NPC 都是一个独立的 SimpleAgent 实例。SimpleAgent 是 HelloAgents 的轻量级实现，封装了 LLM 调用、消息管理和工具调用，第 7 章已经学过——它的核心就是一个对话循环：收消息 → 调 LLM → 返回结果。
怎么运作：第 7 章的 SimpleAgent 是"一个通用助手"，本章把它实例化多份并注入不同的人格。创建过程分四步：定义 NPC 基本信息（ID、名称、职业、性格）→ 用这些信息拼系统提示词 → 创建 LLM 实例 → 创建记忆管理器并挂到 Agent 上。

def create_npc_agent(npc_id: str, name: str, role: str, personality: str):
    system_prompt = f"""你是{name},一位{role}。
你的性格特点:{personality}

你在Datawhale办公室工作,与同事们一起推动开源社区的发展。
请根据你的角色和性格,自然地与玩家对话。
记住你们之前的对话内容,保持对话的连贯性。"""

    memory_manager = MemoryManager(
        working_memory=WorkingMemory(capacity=10, ttl_minutes=120),
        episodic_memory=EpisodicMemory(
            db_path=f"memory_data/{npc_id}_episodic.db",
            collection_name=f"{npc_id}_memories"
        )
    )
    return SimpleAgent(name=name, llm=HelloAgentsLLM(),
                       system_prompt=system_prompt,
                       memory_manager=memory_manager)

这段在干什么：把「人格」编码成提示词，把「记性」编码成记忆管理器，其余全部复用框架能力——这就是"多 Agent 人格化"最省力的实现路径。

工程要点：长期记忆的库和集合是按 npc_id 分开的（{npc_id}_episodic.db / {npc_id}_memories）。如果所有 NPC 共用一个 collection，张三会检索到李四的私聊记录，人设立刻崩塌。

2.2 角色设定与 Prompt 设计（人设卡）

三个 NPC 都是"同一办公室的同事"，但职业与性格刻意拉开差异，这样玩家按兴趣选择互动对象时能感受到明显区别：

NPC	职业	性格设定	能提供什么
张三	Python 工程师	严谨、专业、喜欢分享技术知识；说话直接，注重代码质量	编程技巧与最佳实践
李四	产品经理	外向、善于沟通、注重用户体验；喜欢从用户角度思考，常问"为什么"	产品设计讨论
王五	UI 设计师	温和、富有创意、审美独特；注重视觉呈现	设计理念与灵感

人设卡的数据结构：{"npc_id", "name", "role", "personality"} 四个字段就是全部，可直接写成代码常量。批量生成用的 NPC_ROLES 在此基础上扩展出 title、location、activity（描述"在哪儿、在干什么"）。
工程要点：人设不要写成纯形容词堆砌，要带行为倾向（"说话直接"、"经常会问为什么"、"经常会分享设计灵感"）——这些才是 LLM 能转换成具体说话的指令。

2.3 双层记忆系统的接入

是什么：短期记忆（WorkingMemory）存最近对话，容量有限、随时间自动清理；长期记忆（EpisodicMemory）存全部对话历史，用向量数据库做语义检索。
为什么需要两层：只靠短期记忆，NPC 会"只顾眼前"（玩家问"它是什么颜色的？"，得从最近几轮里解析"它"指什么）；只靠长期记忆，NPC 会"记得住但接不上话"（语义检索返回的是相似片段，不是紧邻上下文）。两层合起来才既有连贯性又有长程回忆。
怎么运作（这是全章最值得抄的一段流程）：

def process_dialogue(agent, player_message):
    recent_messages    = agent.memory_manager.working_memory.get_recent_messages(5)
    relevant_memories  = agent.memory_manager.episodic_memory.search(
        query=player_message, top_k=3)
    context = {"recent": recent_messages, "relevant": relevant_memories}
    reply = agent.run(player_message, context=context)
    agent.memory_manager.add_interaction(player_message, reply)
    return reply

这段在干什么：检索 → 组上下文 → 生成 → 回写。注意顺序上的两个细节：检索用的是玩家这句话本身当 query；生成之后必须把这一轮对话写回记忆，否则下次就"忘了刚才"。

工程要点：recent=5 与 top_k=3 是典型的"上下文预算"控制。记忆不是越多越好——塞得越满，越贵、越慢、越容易被无关历史带偏。

2.4 批量对话生成：把 N 次 LLM 调用压成 1 次

要解决什么问题：多个玩家同时跟不同 NPC 对话时，后端要并发处理多个 LLM 请求。每个请求单独调 API 不只加成本，还可能因并发限流导致失败或延迟。
核心思想：把多个 NPC 的对话请求合并成一次 LLM 调用，让 LLM 一次性生成所有 NPC 的回复。原文的类比很准确——像餐厅的"预制菜"，提前批量备好，需要时直接取。
怎么运作：构建一个特殊提示词，明确要求 LLM 按 JSON 格式一次性返回所有 NPC 的对话，一次 API 调用拿到全部回复，成本降低到原来的 1/3，延迟也大幅减少。

【场景】{context}          # 如"上午工作时间""午餐时间"，为空时按当前时间推断
【NPC信息】
- 张三(Python工程师): 在{location}{activity},性格{personality}
- 李四(产品经理): ...
- 王五(UI设计师): ...

【生成要求】
1. 每个NPC生成1句话(20-40字)
2. 内容要符合角色设定、当前活动和场景氛围
3. 可以是自言自语、工作状态描述、或简单的思考
4. 要自然真实,像真实的办公室同事
5. 必须严格按照JSON格式返回
【输出格式】{"张三": "...", "李四": "...", "王五": "..."}
请生成(只返回JSON,不要其他内容):

这段在干什么：用约束 + 示例 + 强制 JSON 三件事，把"3 个 Agent 各说一句话"降维成"1 次结构化生成"。示例输出（原文给的）长这样：{"张三": "这个bug真是见鬼了,已经调试两小时了...", "李四": "嗯,这个功能的优先级需要重新评估一下。", "王五": "这杯咖啡的拉花真不错,灵感来了!"}。

额外收益（很重要）：所有 NPC 的对话在同一个上下文里生成，因此彼此之间天然有因果关联——张三在调 bug，李四就可能说要去帮忙看看；王五在设计界面，张三就可能说等会儿去看看设计稿。整个办公室的氛围因此变得真实、连贯。这是"批量"这个动作的副产品，也是让世界显得活着的关键。
限制：批量生成适合"背景对话/自言自语"，不适合玩家发起的直接互动——那会牺牲个性化和准确性。适用场景为：NPC 背景对话、定时状态更新、按时间变化的场景氛围、高并发下降低 API 调用次数。

2.5 混合模式：批量生成 + 即时响应

怎么运作：系统在后台定期运行批量生成，为所有 NPC 生成当前场景的"背景对话"并缓存；玩家靠近但未发起交互时，NPC 头顶显示这些背景话（"正在调试代码…"、"在看产品文档…"），让 NPC 看起来是活的而不是静止的模型。一旦玩家按 E 发起交互，立刻切到即时响应模式：调用该 NPC 的专属 Agent，结合玩家消息、历史记忆、好感度生成个性化回复。
代码骨架：

@app.post("/dialogue")           # 即时响应：不用批量生成
async def dialogue(request: DialogueRequest):
    agent = npc_agents.get(request.npc_id)
    if not agent:
        raise HTTPException(status_code=404, detail="NPC not found")
    reply = agent.run(request.player_message)
    affinity_change = relationship_manager.update_affinity(
        npc_id, player_name, request.player_message, reply)
    return {"npc_reply": reply,
            "affinity_score": affinity_change["score"],
            "affinity_level": affinity_change["level"]}

async def background_dialogue_update():   # 后台任务:每5分钟一次
    while True:
        dialogues = get_batch_generator().generate_batch_dialogues()
        for npc_name, dialogue in dialogues.items():
            state_manager.update_npc_background_dialogue(npc_name, dialogue)
        await asyncio.sleep(300)

这段在干什么：同一条后端进程里跑两条节奏完全不同的链路——慢链路（每 5 分钟批量刷新全世界氛围）和快链路（玩家来一句话就立刻响应一句）。

四个收益：降成本（一次调用覆盖所有 NPC）、保质量（交互回复个性化）、提体验（NPC 始终有话可说）、可调节（能按服务器负载动态调整批量频率）。

维度	批量生成	即时响应
触发方式	后台定时（每 5 分钟）	玩家按 E 发起
覆盖范围	全部 NPC 一次生成	单个 NPC
单次 LLM 调用	1 次	1 次
适用内容	背景对话、场景氛围	个性化交互回复

3. 好感度：把社交关系变成可计算的量（15.3）

3.1 五级关系与阈值

是什么：好感度是 NPC 对玩家的量化态度，0-100 分，分五级。

等级	分数区间	行为表现
陌生	0-20	礼貌但保持距离，回复简短，不主动分享个人信息
熟悉	21-40	开始记住玩家，回复自然，偶尔分享工作相关信息
友好	41-60	当玩家是朋友，回复更详细，主动询问玩家情况
亲密	61-80	非常信任，愿意分享私人话题，提供帮助和建议
挚友	81-100	当玩家是最好的朋友，无话不谈，分享内心想法

为什么重要：量化之后关系才能被"玩法"消费。比如只有达到一定好感度，NPC 才会分享特殊信息或提供特殊任务。玩家刚进游戏时所有 NPC 都是陌生态度，随互动升级回复越来越亲切详细。
工程要点：等级带宽 20 分、单次互动最多 +5（见下），意味着从陌生爬到挚友至少要二十来次有效友好互动——这个"节奏感"是刻意设计的。

3.2 用 LLM 做情感分析打分

设计原则：不能让每次对话都加固定分，那样系统显得机械不真实。好的好感度系统要能识别玩家的态度并动态调整——本章方案是让 LLM 判断玩家态度是友好/中立/不友好，再据此调分，玩家不需要刻意选选项。
关键机制：

def analyze_sentiment(self, player_message, npc_reply) -> int:
    prompt = f"""分析以下对话中玩家的态度:
玩家: {player_message}
NPC: {npc_reply}

请判断玩家的态度是:
1. 友好(+5分): 礼貌、热情、表示感谢或赞同
2. 中立(+2分): 普通的询问或陈述
3. 不友好(-3分): 粗鲁、冷漠、批评或否定

只返回数字,不要其他内容。"""
    response = self.llm.think([{"role": "user", "content": prompt}])
    try:
        return max(-3, min(5, int(response.strip())))
    except:
        return 2   # 解析失败默认中立

这段在干什么：把"关系涨跌"从手写规则变成一次廉价的 LLM 分类调用，并用 max/min 夹逼 + try/except 兜底把不可靠输出挡在系统外。注意 prompt 里连 NPC 的回复一起给了——判断玩家态度需要参照 NPC 说了什么。结算公式是 new_score = clamp(current_score + score_change, 0, 100)，同时互动次数加一。

数据结构：好感度以 f"{npc_id}_{player_name}" 为 key 存字典，值为 {"score", "level", "interaction_count"}，新玩家初始 score=0, level="陌生"。同一次结算还顺手加了互动次数——这是后续做统计和任务门槛的现成数据。

3.3 好感度反向影响对话

怎么运作：好感度如果只是一个数字就白算了，必须真正影响 NPC 行为。做法是动态调整系统提示词：按当前等级追加一段关系描述。

等级	注入提示词的关系指令
陌生	保持礼貌但不要过于热情，回复简短专业
熟悉	可以进行正常交流，回复自然友好
友好	当作朋友，愿意分享更多信息，回复详细热情
亲密	非常信任，可分享私人话题，回复充满关心
挚友	当作最好的朋友，无话不谈，回复亲切真诚

代码骨架：create_npc_agent_with_affinity(npc_id, name, role, personality, affinity_level) 把 当前与玩家的关系:{affinity_level} 和对应的关系指令拼进提示词，再创建 SimpleAgent。
工程要点（易错）：因为 Agent 的提示词在创建时固化，所以好感度等级一变，必须重新取一次 Agent——对话路由里写的是 agent_manager.get_agent(request.npc_id, affinity_info["level"])。若一直复用旧实例，玩家永远看不到态度变化。

4. 后端服务实现（15.4）

4.1 FastAPI 结构与 API 设计

是什么：后端用 FastAPI 构建，模块化拆分——main.py 是入口，NPCAgentManager（Agent 池）、RelationshipManager（好感度）、StateManager（状态）、DialogueLogger（日志）四个管理器在模块级初始化，启动事件（@app.on_event("startup")）里再初始化 NPC Agent 与状态。
必备基础设施：CORS 中间件。Godot 是独立进程发 HTTP 请求，不加跨域配置前端拿不到数据。

方法	路径	作用
GET	`/`	健康检查，返回运行状态与 NPC 数量
GET	`/npcs/status`	获取全部 NPC 状态
GET	`/npcs/{npc_id}/status`	获取单个 NPC 状态
POST	`/dialogue`	玩家与 NPC 对话（核心接口）
GET	`/affinity/{npc_id}/{player_name}`	查询玩家与 NPC 的好感度

/dialogue 的九步流程（背下来）：① 校验 NPC 是否存在（不存在返回 404）→ ② 检查 NPC 是否忙碌（忙碌返回 409）→ ③ 标记为忙碌 → ④ 取当前好感度 → ⑤ 按好感度等级取 Agent 并生成回复 → ⑥ 更新好感度 → ⑦ 写日志 → ⑧ 返回 DialogueResponse(npc_reply, affinity_level, affinity_score) → ⑨ finally 中释放忙碌标记。
工程要点：第 ③ 和第 ⑨ 步必须配对放在 try/finally 里。生成回复会抛异常（网络、限流、解析失败），但忙碌标记一定要被释放，否则这个 NPC 会被永久锁死，再也聊不了。

4.2 状态管理：并发互斥

是什么：StateManager 用字典跟踪每个 NPC 的位置、is_busy、current_action、last_interaction。三个 NPC 的初始位置是硬编码的左上角坐标系：张三 (300, 200)、李四 (500, 200)、王五 (700, 200)，初始 current_action="idle"。
为什么需要：防止并发问题——避免同一个 NPC 同时与多个玩家对话。set_npc_busy(npc_id, True) 时顺带写入 last_interaction 时间戳，这为"NPC 空了多久"这类后续逻辑留了钩子。
工程要点：互斥的粒度是整个 NPC，所以第二个玩家在第一个玩家撤回消息之前会收到 409。这是个刻意的取舍——NPC 只有一个"大脑"，同时处理两条对话流会让记忆和好感度串味。

4.3 日志系统：AI 应用的可观测性

是什么：DialogueLogger 实现双输出——控制台（方便实时盯）+ 文件（保存历史），文件按天命名 logs/dialogue_YYYY-MM-DD.log。
记录什么：日志含好感度变化量（+2.0、+3.0 等）、变化原因（友好问候、正常交流等）与情感分析结果（positive、neutral），以及当前好感度值、检索到的相关记忆、NPC 回复。前端界面不显示数值，但后端可完整追踪关系发展，也为将来加好感度 UI 备好了数据。
工程要点：LLM 应用最难的是"为什么它这么说"。日志是唯一能把「输入 → 检索到的记忆 → 输出 → 状态变化」串成一条线的东西，成本极低但价值极高。

4.4 Godot 的节点与场景：游戏侧的世界模型

节点（Node）：Godot 最基本的构建块，每种节点只做一件事——Sprite2D 显示图片、AudioStreamPlayer 播放音频、CharacterBody2D 处理角色物理移动。节点间形成父子树：移动/隐藏父节点会同步影响所有子节点。
场景（Scene）：一组节点保存成 .tscn 文件，相当于"预制件"。场景可实例化，也可在一个场景里实例化另一个场景形成嵌套；修改源头场景会自动影响所有实例——这就是"三个 NPC 共用一个模板"的技术基础。
一个最小场景结构示例：

Player (CharacterBody2D)   ← 根节点，负责物理移动
├─ AnimatedSprite2D        ← 子节点，显示角色动画
├─ CollisionShape2D        ← 子节点，定义碰撞形状
└─ Camera2D                ← 子节点，摄像机跟随玩家

工程要点：这就是游戏世界的"世界模型"——地图不是一张数据表，而是一棵可复用的节点树。想给所有 NPC 加一个头顶气泡，只改 NPC.tscn，三个实例全部自动获得。

5. 游戏场景构建与 NPC 行为（15.5）

5.1 为什么选 Godot

2D 优先：赛博小镇是俯视角 2D 像素游戏，Godot 提供 TileMap、AnimatedSprite2D、CharacterBody2D 等专为 2D 设计的节点，开发效率高于 Unity。
开源免费：MIT 许可证，无版权费用与收入分成，可自由修改引擎源码、可商业化（原文特意对比了 Unity 2024 年运行时费用政策引发的争议）。
学习成本低、集成简单：GDScript 是类 Python 的动态类型语言，已会 Python 的人几小时就能上手；内置 HTTPRequest 节点让前后端通信很直接。
局限：3D 能力相比 Unreal、Unity 仍有差距，做大型 3D 游戏需另选引擎；2D 游戏、独立游戏、教学项目则非常合适。

5.2 四个核心场景与实例化

场景	根节点	关键子节点
Main	Node2D	Background(Sprite2D)、Player 实例、NPCs（下挂三个 NPC 实例）、DialogueUI 实例、Walls、AudioStreamPlayer
Player	CharacterBody2D	AnimatedSprite2D、CollisionShape2D、Camera2D、InteractSound、RunningSound
NPC	CharacterBody2D	CollisionShape2D、AnimatedSprite2D、InteractionArea(Area2D > CollisionShape2D)、NameLabel、DialogueLabel
DialogueUI	CanvasLayer	Panel（下挂 NPCName、NPCTitle、DialogueText、PlayerInput、SendButton、CloseButton）

实例化怎么用：在 Main 场景中三次实例化 NPC.tscn，分别命名为 NPC_Zhang、NPC_Li、NPC_Wang。每个副本有自己的位置和状态，但共享同一套节点结构；差异通过脚本导出参数（@export npc_name / npc_title / sprite_frames）注入。
三个优势：每个场景可单独测试；NPC 改一处影响全部；场景之间靠信号通信，耦合度低。
工程要点：Main 场景里 Player、NPC_Zhang、NPC_Li、NPC_Wang、DialogueUI 都是场景实例而不是普通节点——这是判断一个人是否真懂 Godot 组织方式的分界线。

5.3 玩家控制

场景与状态：speed = 200.0；nearby_npc 记录当前可交互对象；is_interacting 为真时禁用移动。
_ready() 里最关键的一行：add_to_group("player")——NPC 的交互区域靠这个组名识别玩家，不加就永远触发不了交互。
移动与动画：_physics_process 用 Input.get_vector("ui_left","ui_right","ui_up","ui_down") 拿输入方向，乘速度、move_and_slide() 移动；再按主方向选择 walk_up/down/left/right 四方向动画，资源缺失时退化为 walk 动画并通过 flip_h 翻转左右。
交互：_input 里监听 KEY_E 或 KEY_ENTER（且 not event.echo，避免长按重复触发），有 nearby_npc 时播放交互音效，并 get_tree().call_group("dialogue_system", "start_dialogue", nearby_npc.npc_name) 通知对话系统。
音效：走路音效用 is_playing_running_sound 标志位做"只在开始移动时播放一次"，避免每帧重复触发。

5.4 NPC 行为：巡逻 + 交互 + 气泡

三件事：在场景中随机巡逻、响应玩家交互、显示对话气泡。

参数	默认值	含义
move_speed	50.0	NPC 移动速度（远低于玩家的 200）
wander_range	200.0	以出生点为圆心的巡逻半径
wander_interval_min / max	3.0 / 8.0	两次选点的间隔区间（秒），随机取值
到达判定	distance < 10	距目标小于 10 像素即视为到达，停下播 idle
气泡隐藏	10.0 秒	`update_dialogue()` 后延时自动隐藏

怎么运作：_ready() 里记录 spawn_position，初始化巡逻计时器；_physics_process 每帧递减 wander_timer，归零就 choose_new_wander_target()（在出生点附近随机取点）并重掷计时器；正在巡逻时朝目标归一化方向移动，到达即停。
交互检测：InteractionArea（Area2D）的 body_entered / body_exited 信号里判断 body.is_in_group("player")，进入时调 player.set_nearby_npc(self)，离开时置回 null。
交互时冻结：set_interacting(true) 后 NPC 立即 velocity = Vector2.ZERO 并播 idle 动画；对话结束置回 false，恢复巡逻。
气泡来源：主场景定时调用 NPC 的 update_dialogue() 更新气泡文本——内容是后端批量生成的 NPC 自主对话。
工程要点：注意"随机巡逻 + 定时气泡 + 交互冻结"三件事都在客户端完成，一次 LLM 都不调。把"低成本的存在感"与"高成本的智能"分开，是这个架构能跑起来的关键。

6. 前后端通信（15.6）

6.1 API 客户端封装

是什么：api_client.gd 把三个后端接口（对话、NPC 状态、NPC 列表）封装起来，设为 AutoLoad 单例，其他脚本通过 /root/APIClient 直接取用。
怎么运作：用 Godot 的 HTTPRequest 节点发请求。它是异步节点，发送后不阻塞游戏，通过 request_completed 信号通知结果；再往上转成自定义信号广播给业务脚本：

signal chat_response_received(npc_name: String, message: String)
signal chat_error(error_message: String)
signal npc_status_received(dialogues: Dictionary)
signal npc_list_received(npcs: Array)

设计要点：
- 每个 API 一个独立 HTTPRequest 节点（http_chat / http_status / http_npcs），这样可同时发多个请求而不互相干扰。
- 用信号而非 await 通知结果，好处是多个脚本可以同时监听同一个响应。
- 状态轮询前先检查 http_status.get_http_client_status() != HTTPClient.STATUS_DISCONNECTED，正在处理中就跳过——一个简单有效的防重入。

6.2 对话 UI

结构：DialogueUI 是 CanvasLayer，保证始终显示在画面最上层、不被游戏对象遮挡；Panel 锚定屏幕底部，内部 6 个元素：NPCName、NPCTitle、DialogueText（RichTextLabel，支持颜色/粗体等富文本）、PlayerInput（LineEdit）、SendButton、CloseButton。
交互状态联动（重点）：show_dialogue() 时通过 get_tree().get_first_node_in_group("player") 找到玩家并调 set_interacting(true) 禁用移动；hide_dialogue() 时置回 false 恢复移动。不开对话就满地图跑会错过 NPC 的下一句话。
防重复发送：发送后立刻 input_field.editable = false + send_button.disabled = true，收到回复后再恢复并 grab_focus()。LLM 响应有秒级延迟，这道锁是必需的。
渲染回复：用 append_text 追加带颜色的文本（玩家消息青色、NPC 回复黄色），按 current_npc_name 过滤信号，避免 A 的回复显示在 B 的对话框里。

6.3 主场景整合

职责：协调玩家控制、NPC 交互、对话 UI 和 NPC 状态更新。
怎么运作：_ready() 里连上 api_client.npc_status_received 信号并立即拉一次状态；_process(delta) 累加 status_update_timer，达到 Config.NPC_STATUS_UPDATE_INTERVAL（默认 30 秒）就再拉一次；收到状态后遍历字典，按名字匹配节点（match 张三/李四/王五）并调 update_dialogue()。
效果：即使玩家不跟任何 NPC 交互，也能看到 NPC 头顶不断刷新他们之间的自主对话。
工程要点：新增一个 NPC 只需加一个场景实例、在 match 里加一个分支、后端加一份配置。注意两个刷新节奏是错位的——前端 30 秒轮询、后端 5 分钟一次批量生成，所以同一段背景对话会被重复取到几次，这属于省成本的预期代价。

7. 工程实践要点（跨节综合）

7.1 感知—决策—行动循环在游戏世界里的落地

环节	发生位置	具体实现
感知	Godot	Area2D 的 `body_entered`/`body_exited` 判定靠近；按 E 采集玩家自然语言输入
决策	FastAPI + HelloAgents	按好感度等级取 Agent → 检索短期/长期记忆 → LLM 生成回复 + 情感分析打分
行动	FastAPI + Godot	返回回复与好感度；置 `is_busy`；写日志；UI `append_text` 显示
观察回灌	记忆系统	`add_interaction(player_message, reply)` 把这一轮写回记忆，成为下一轮的观察

关键差异：第 2 章的最小 Agent 循环里，"感知-决策-行动"都在一个进程内的 while 循环里；游戏场景中它被拆成跨进程的一次 HTTP 往返，循环的延续性由记忆系统而不是上下文数组来保证。
"世界心跳"：除了玩家触发的快循环，还有一条由 background_dialogue_update 驱动的慢循环（每 300 秒），它让世界在没人交互时也在推进。

7.2 时间推进与并发调度

三层时间尺度：NPC 巡逻/动画按帧（_physics_process）；玩家状态轮询 30 秒；世界背景对话 5 分钟。不同事物给不同频率，是控制成本与真实感的核心手段。
并发控制手段：is_busy 互斥 + HTTP 409 拒绝并发对话；try/finally 保证标记释放；asyncio.sleep(300) 让后台任务与请求处理在同一事件循环中共存而不阻塞；每个 API 独立 HTTPRequest 节点 + 状态检查防重入。
易错点：后台任务必须用 try/except 包住整轮逻辑（失败只打印错误、不退出循环），否则一次 LLM 抖动就会让"世界心跳"永久停跳。

7.3 LLM 成本与性能优化清单

批量合并：N 个 NPC 的背景对话合并成 1 次调用、要求 JSON 输出，成本降到 1/3。
动静分离：静态氛围（巡逻、动画、气泡）零 LLM 调用；只有玩家交互才烧 Token。
缓存：批量生成的背景对话缓存起来复用 5 分钟。
检索预算：短期记忆取 5 条、长期记忆召回 3 条、短期容量 10 条 / TTL 120 分钟——都在限制进 Prompt 的 Token 量。
降级与兜底：情感分析解析失败返回 2（中立），不让异常打断主流程。
可调频率：批量生成频率可根据服务器负载动态调整。

7.4 记忆与状态持久化现状

数据	存放位置	是否持久
长期对话记忆	`memory_data/{npc_id}_episodic.db` + Qdrant collection	是
短期对话记忆	WorkingMemory	否（TTL 120 分钟）
好感度	`RelationshipManager.affinity_data` 字典	否（进程内）
NPC 位置/忙闲	`StateManager.npc_states` 字典	否（进程内）
对话日志	`logs/dialogue_YYYY-MM-DD.log`	是（文本）

工程要点：好感度与 NPC 状态目前都在内存里，进程重启即丢失。原文把"用数据库持久化玩家数据和 NPC 状态"列进了扩展方向，这是从 Demo 走向可用产品的第一步。

7.5 让世界显得"活着"的调参旋钮

跨 NPC 的关联性：批量生成时所有 NPC 在同一上下文里说话，天然产生因果引用（他说在调 bug，另一个就接要去看看）。想要更强的联动感，就在提示词里强化"NPC 之间可以互相提及"。
存在感：wander_range（巡逻半径）、wander_interval_min/max（选点间隔）、气泡显示时长（10 秒）共同决定 NPC 看起来"忙不忙、有没有事在做"。
关系推进速度：单次 ±3~+5 的涨跌幅配 20 分一个等级带宽，决定爬到"挚友"要聊多少轮。想加快节奏就放大涨跌幅或收窄等级带宽。
观察手段：日志就是你的仪表盘——好感度变化量、变化原因、情感判定都落盘，调参时看日志比看游戏画面有效得多。

7.6 可迁移到其他模拟场景的方法

可迁移的是骨架，不是剧情：四层分离架构 + 一实体一 Agent + 双层记忆 + 数值化关系 + 动静分离的成本策略，这套骨架与"办公室"无关，原文直接点明可应用到其他需要大量 AI 调用的场景。
换场景要换什么：换人设卡（role / personality / location / activity）、换场景与地图节点树、换关系维度的语义。教育场景让 NPC 扮演历史人物、科学家做互动式教学；虚拟办公室让 NPC 扮演同事、导师；陪伴场景让 NPC 做情感交流。
继续扩展的方向（原文列出）：多人在线（WebSocket + 数据库持久化，NPC 对每个玩家保持独立好感度）、任务系统（好感度达标解锁特殊任务与奖励）、NPC 之间的互动（后台自动进行，玩家可围观）、情感系统、动态事件系统（团队会议、生日派对、突发任务）、更大的世界（咖啡厅、图书馆、公园等多场景）、个性化学习（记住玩家偏好与作息）。
绕不开的三个挑战：成本、延迟、内容可控性。原文对未来的判断是：推理会更快、成本会更低，本地化小型 LLM 也在发展，未来可能直接在玩家设备上运行、无需网络请求。

8. 高频考点 & 易错点速查

四层架构的每一层职责必须能对上号：前端 Godot / 后端 FastAPI / 智能体 HelloAgents / 外部 LLM+Qdrant+SQLite。
一 NPC 一 Agent 一独立向量库：长期记忆按 npc_id 分库分集，共用会导致人设串味。
短期记忆的两个参数：容量 10 条、TTL 120 分钟；它的作用是维持对话连贯（指代消解），不是长程回忆。
记忆检索的两个数字：最近 5 条 + 长期召回 top_k=3。这是上下文预算，不是越多越好。
批量生成的两个前提：一次调用覆盖全部 NPC；强制 JSON 输出。收益是成本降到 1/3，副作用是 NPC 对话自带关联性。
批量生成的禁区：不能用于玩家发起的对话，必须走该 NPC 的专属 Agent 以保个性化与准确性。
好感度的三段式：LLM 情感分析打分（友好 +5 / 中立 +2 / 不友好 -3，夹逼到 [-3,5]）→ clamp(0,100) 累加 → 按分数映射五级（每 20 分一级）。解析失败默认返回 2。
好感度影响对话的唯一通道是提示词：等级变了必须重新 get_agent(npc_id, level)，复用旧实例等于白算。
/dialogue 的并发语义：先查存在（404）再查忙闲（409），标记忙碌与释放忙碌必须 try/finally 配对，否则 NPC 被锁死。
前端启动时注册组名：玩家必须 add_to_group("player")，NPC 必须 add_to_group("npcs")，Area2D 靠组名识别，漏了就完全无法交互。
三个时间尺度别记混：NPC 巡逻按帧、前端状态轮询 30 秒、后端批量生成 5 分钟。两者错位导致同一段背景对话会被重复取到，属预期行为。
Godot 里"场景"≠"节点"：Main 里的 Player 与三个 NPC 都是场景实例，改源 .tscn 影响全部实例——这正是三个 NPC 能共用一个模板的原因。
异步通信靠信号不靠阻塞：每个 API 一个独立 HTTPRequest 节点；等待回复期间锁住输入框与发送按钮，防重复发送。
持久化的现状与缺口：记忆与日志落盘，好感度和 NPC 状态在内存中，重启即失——扩展方向里明确要用数据库补齐。
日志是 AI 应用的生命线：它记录输入、检索到的记忆、回复、好感度增量和情感判定，是调试与调参的唯一依据。

9. 与前后章节的衔接

本章站在第 7 章讲过的 SimpleAgent 之上，把那个"单进程对话循环"实例化成多个有身份、有记忆的 NPC；同时把第 2 章的最小 Agent 循环拆成跨进程的感知-决策-行动往返，用记忆系统取代上下文数组来维持循环的延续性。好感度与批量生成这两套机制，本质上是"多 Agent 之间没有直接通信、只有与环境的交互"时，用数值和共享上下文间接塑造群体行为的工程手法。本章的输出是一套完整可运行的"智能体 + 世界"骨架；接下来的毕业设计章节将转向用单智能体与多智能体构造通用智能体，那才是自由创作的开始。

10. 课后练习

在线试卷：https://md-quiz-online.app.workbuddy.host/

posted @ 2026-09-28 17:11 测试小罡阅读(14) 评论(0) 收藏举报

刷新页面返回顶部

小罡测试笔记

Agent 速成笔记 · 第 15 章 构建赛博小镇

Agent 速成笔记 · 第 15 章 构建赛博小镇

0. 一章速览（30 秒）

1. 项目目标与总体架构（15.1）

1.1 结合点：Agent 补上游戏 NPC 缺的那块

1.2 四层分离架构

1.3 一次交互的完整数据流

2. NPC 智能体系统（15.2）

2.1 一 NPC 一 Agent：SimpleAgent 的复用

2.2 角色设定与 Prompt 设计（人设卡）

2.3 双层记忆系统的接入

2.4 批量对话生成：把 N 次 LLM 调用压成 1 次

2.5 混合模式：批量生成 + 即时响应

3. 好感度：把社交关系变成可计算的量（15.3）

3.1 五级关系与阈值

3.2 用 LLM 做情感分析打分

3.3 好感度反向影响对话

4. 后端服务实现（15.4）

4.1 FastAPI 结构与 API 设计

4.2 状态管理：并发互斥

4.3 日志系统：AI 应用的可观测性

4.4 Godot 的节点与场景：游戏侧的世界模型

5. 游戏场景构建与 NPC 行为（15.5）

5.1 为什么选 Godot

5.2 四个核心场景与实例化

5.3 玩家控制

5.4 NPC 行为：巡逻 + 交互 + 气泡

6. 前后端通信（15.6）

6.1 API 客户端封装

6.2 对话 UI

6.3 主场景整合

7. 工程实践要点（跨节综合）

7.1 感知—决策—行动循环在游戏世界里的落地

7.2 时间推进与并发调度

7.3 LLM 成本与性能优化清单

7.4 记忆与状态持久化现状

7.5 让世界显得"活着"的调参旋钮

7.6 可迁移到其他模拟场景的方法

8. 高频考点 & 易错点速查

9. 与前后章节的衔接

10. 课后练习

公告

Agent 速成笔记 · 第 15 章构建赛博小镇

Agent 速成笔记 · 第 15 章构建赛博小镇