AI 阿瓦隆对战平台项目说明书

1. 项目目标

项目实现一套可本地运行的 AI 阿瓦隆对战平台，支持真人与 AI 共同参与标准阿瓦隆流程。系统目标不是复刻简单的投票流程，而是同时保证三件事：规则由程序严格执行、AI 能基于历史形成连续策略、玩家不能通过前端接口获得隐藏身份。

当前交付以 6 人标准局为主要玩法；规则配置已抽象为数据模型，可容纳 6—10 人的官方配置，并为新增角色或接入其他阵营推理游戏预留扩展边界。

2. 功能范围

• 完整阶段流转：讨论、组队、组队投票、任务、刺杀与胜负结算。
• 真人玩家与多名 AI 共同对局，AI 讨论按顺序调度以继承上下文。
• 角色视野、任务人数、失败票阈值、连续否决和非法动作由规则引擎统一校验。
• AI 在发言、投票、组队、任务与刺杀等场景完成不同粒度的决策。
• 玩家视角仅获得必要公开信息；独立上帝视角可查看完整角色、推理过程、信任矩阵和模型统计。
• 前端提供圆桌布局、议事录、阶段操作面板、软倒计时、断连提示、新手引导与结算复盘。

3. 后端架构

后端按 core、agent、llm、api 与基础设施模块分层。

core 是不依赖 FastAPI、数据库或模型 SDK 的纯领域层。GameConfig 管理人数、角色组合、任务人数和失败票阈值；RoleRegistry 将角色能力、阵营和视野数据化；PhaseHandler 组织各阶段准入、校验与推进；AvalonEngine 只负责状态机、规则拒绝与胜负判定。该设计使“好人投失败票”“刺客刺杀坏人”“队伍人数错误”等非法操作在引擎层被拒绝，而不是依赖页面限制。

api 层以薄路由承接 HTTP 请求，由对局服务统一管理创建、重置、删除和 AI 调度。返回前通过视角 DTO 过滤角色身份和任务失败票等隐藏数据；上帝视角使用独立端点，避免把完整状态先发送到浏览器再由前端隐藏。

SQLite 与 SQLAlchemy 保存对局和信念快照等可恢复状态，Pydantic 负责请求与响应约束。

4. Agent 决策闭环

每名 AI 在单局内拥有按 game_id + seat 维持的 AgentRuntime，而不是每次行动临时实例化。它的决策闭环如下：

游戏事件
↓
工作记忆记录本轮发言、投票与任务上下文
↓
读取信念快照与 Chroma 情节记忆
↓
检索角色、阶段和局势匹配的 RAG 策略
↓
构造人设、上下文、任务三层 Prompt
↓
LLM Gateway 调用模型
↓
解析五段式推理或 ACTION JSON
↓
规则引擎验证动作并推进对局
↓
任务结果揭晓后更新信任、阵营猜测与梅林概率，并写入轮次摘要

系统使用双模型路由：讨论发言走偏高温的 chat 通道，投票、组队、任务和刺杀等硬决策走低温 reasoner 通道。网关集中处理模型配置、重试、退避、降级与 token 统计；若模型不可用或输出无法解析，则根据当前信念快照执行启发式兜底，保证对局不会因模型故障停止。

5. 前端与交互

前端采用 React、TypeScript 和 Zustand。gameStore 管理对局状态、会话恢复、动作提交和轮询：讨论阶段或存在流式发言时采用更短间隔，其他阶段采用常规间隔；连续请求失败后展示断连提示。

界面围绕中世纪圆桌主题设计，包含按人数自适应的座位布局、逐字渲染的 AI 发言、按阶段显示的控制面板、任务轨道历史信息与复盘页面。复盘页提供逐轮队伍、投票、任务结果与身份揭晓，用于还原完整对局。

6. 质量与边界

项目以规则正确性和信息边界为优先级。后端测试覆盖领域规则、非法路径、Agent 运行时、API 与 LLM 网关；前端使用 TypeScript 构建校验。当前项目不以移动端适配和 WebSocket 实时推送为交付目标，采用轮询以降低复杂度；完整玩法聚焦阿瓦隆，插件化扩展只保留架构接口，不宣称已交付其他游戏。