AI 桌游对战平台项目说明书

1. 项目概述

AI 桌游对战平台是一个让真人与多个 AI 共同参与隐藏身份桌游的 Web 系统。项目以既有的 AI 阿瓦隆能力为基础，进一步接入完整的 AI 狼人杀模式：玩家可选择不同人数的对局，进入昼夜交替、私密行动、公开发言、投票放逐与胜负结算构成的完整游戏流程。

系统的核心目标不是让大模型直接“编故事”，而是把桌游规则、信息边界和 AI 策略拆开处理：规则引擎决定什么能做，智能体只在自己可见的信息范围内给出行动与发言，服务端再把脱敏后的视图返回给不同身份的玩家。

2. 功能范围

平台包含两类游戏模式。

• AI 阿瓦隆：支持 5 至 10 人、组队与任务投票、刺杀阶段及可选的湖中仙女机制。
• AI 狼人杀：支持 6、8、10、12 人配置；12 人默认采用“预言家、女巫、猎人、白痴”的标准板子，覆盖守卫、狼人夜聊与刀人、查验、用药、警长竞选、顺序发言、放逐、PK、遗言、警徽移交与角色结算。

前端提供模式选择、圆桌座位、阶段提示、操作面板、公开议事记录与夜间氛围界面。真人玩家可提交行动或查看最新局面，AI 玩家则由后端协调器在合法时机自动推进。

3. 系统架构

平台采用 React 前端与 FastAPI 后端分离的架构。SQLite 承载对局、玩家和事件日志等基础数据，ChromaDB 用于智能体的检索式记忆；模型调用经由统一网关路由到聊天或推理模型。

系统链路可以概括为：

玩家操作 / AI 触发 → FastAPI 路由与对局服务 → 对应游戏规则引擎 → 智能体上下文与模型决策 → 规则校验与状态写入 → 按视角脱敏的 DTO → React 页面更新

其中，game_mode 将阿瓦隆与狼人杀纳入共享的对局、日志和接口生命周期；具体规则则分别封装在各自的领域模块中。这样既保留原有阿瓦隆能力，也避免将两种桌游的阶段和权限硬编码到同一套流程里。

4. 狼人杀规则与状态控制

狼人杀模块以确定性领域引擎为唯一状态来源。引擎保存当前昼夜阶段、可行动座位、发言顺序、候选人、警长、投票资格、死亡与遗言状态等事实，并负责校验每一次行动的时机、身份权限和目标合法性。

夜晚依次处理守卫、狼人私聊和袭击、预言家查验、女巫行动；白天依次处理警长竞选、发言、投票、平票 PK、放逐和遗言。警长票权、警徽流转、猎人开枪、白痴翻牌免疫、自爆与弃票等特殊规则也由引擎统一结算，而非交给提示词临场判断。

这种设计保证了 AI 输出即使不完整或不合规，也不会直接破坏局面。系统只接受通过规则校验的结构化动作，失败时回退到引擎枚举出的中性合法动作。

5. AI 决策与策略能力

每位 AI 仅能读取符合自身身份的可见信息：普通好人只见公开事件，狼人额外可见同伴与夜间协作信息，预言家和女巫仅见各自的私密结果。智能体在此基础上组合公开编年史、角色私有记忆、阵营记忆、信念快照与策略卡，形成当前局势分析。

策略模块不再替 AI 强行选定动作，而是输出可解释的建议，例如施压摇摆位、建立共识、对跳、深水潜伏或牺牲队友。模型可以采纳、修改或拒绝建议；其输出必须先形成 ACTION JSON，再经过解析与规则校验。已接受的决策才会原子化写入记忆和信念，避免无效重试污染后续推理。

系统还为发言提供事实校验、长度预算和质量评估。质量指标只作为建议与复盘数据，不越过规则层替代玩家决策。

6. 视图隔离与可观测性

服务端按玩家视角构建 DTO：玩家页面不会泄露其他人的角色、狼人同伴、查验结果、女巫私密目标或策略诊断；观战与调试视图才可查看完整角色、置信矩阵、策略建议和质量指标。

为验证多智能体对局的稳定性，项目加入种子化模拟、结构化事件记录和恢复后记忆读取等机制。它们用于检查 AI 行动是否始终合法、对局能否持续推进、重启后状态是否连续，以及不同角色是否在可见信息边界内作出差异化判断。

7. 当前完成情况

项目已归档。主线已具备阿瓦隆与狼人杀双模式、完整狼人杀昼夜与警长流程、可见性隔离、策略建议层、持久化记忆、策略诊断和深度模拟能力；前后端构建与规则测试已在开发阶段完成验证。后续如继续迭代，可围绕更多板子配置、真人多人房间和复盘数据可视化扩展。