AI 代理驱动开发实战：用 TRAE 构建经典吃豆人游戏

本文作者：茉卷，TRAE 开发者用户

项目概述

BMAD-METHOD（Breakthrough Method for Agile AI-Driven Development）是一个通用 AI 代理框架，专注于代理式敏捷驱动开发（Agentic Agile Driven Development）。它通过 AI 代理协作，帮助用户在软件开发、娱乐、创意写作、商业策略、个人健康等领域实现高效转型，解决传统 AI 辅助工作流中规划不一致和上下文丢失的问题。本文展示了用 BMAD-METHOD™框架构建经典吃豆人游戏的过程。

核心目标与方法

采用两阶段方法：

1. 代理规划阶段： 分析师（Analyst）、产品经理（PM）和架构师（Architect）代理协作生成详细的产品需求文档（PRD）和架构文档，支持高级提示工程和人工干预优化。

2. 上下文工程开发阶段： Scrum Master 代理将规划转化为超详细开发故事（包含完整上下文、实现细节和架构指导），供开发代理（Dev）执行。 框架可扩展到非软件领域，通过专用 AI 代理实现。

关键组件

• 文档： docs/user-guide.md （完整工作流，包括 Web UI 规划和 IDE 开发循环）；docs/expansion-packs.md（扩展包指南，支持创意写作、商业策略等定制）。

• 团队文件： dist/teams/team-fullstack.txt（全栈团队配置，用于快速启动）。

安装与特点

• 安装： 使用 npx bmad-method install 一键部署（需 Node.js v20+），支持升级和扩展包。

• 版本： 稳定版 v4.x（npm 安装）；v6-alpha（2025 年 10 月中旬 beta 测试中，包含架构重构）。

• 工作流： Web UI 用于快速 ideation 和规划；IDE 循环支持 Scrum Master、Dev 和 QA 代理协作。强调人类干预和 #bmad-orchestrator 命令。

• 扩展性： 自然语言框架，适用于研究（代理工作流实验）和实际应用（跨领域 AI 开发）。

快速安装

运行环境：MacBook

npx bmad-method install
# OR
git pull
npm run install:bmad

输入一个完整路径，用来保存项目代码、文档。

选择安装 BMad Agile Core System 即可。

PRD 和文档选择 YES。

选择 TRAE（注意，按空格是选择，下图是没选中的状态）。

选择 TRAE， NO pre-build web bundles。

在安装的目录，可以看到 bmad-core 目录。

用 TRAE 打开刚才创建的项目目录，可以看到 .bmad-core 文件夹。

使用方法

BMAD 内置了很多有用的智能体，可以在 Agents 目录查看。

接下来我们通过一个例子来看下如何使用 BMad 方法来构建项目。

2.1 BMad 分析师 ：Mary

第一步，我们可以找到分析师 Mary， 帮助我们头脑风暴，分析项目。

注意：

• 这里通过 # 号选择文件 analyst.md

• 模型选择 GPT-5

Mary 是一个综合性分析师，她可以进行：市场研究、头脑风暴、竞争分析、项目简报创建、初始项目发现以及现有项目文档化。

bmad:analist #analyst.md #analyst.md

我们可以看到 Mary 上线了。

Mary 的功能菜单：

- 1.
*help --- 显示此菜单
- 2.
*brainstorm {topic} --- 带输出模板的结构化头脑风暴
- 3.
*create-competitor-analysis --- 生成竞争对手分析文档
- 4.
*create-project-brief --- 生成项目简报文档
- 5.
*perform-market-research --- 生成市场调研文档
- 6.
*research-prompt {topic} --- 创建深度研究提示语
- 7.
*elicit --- 运行交互式信息获取流程
- 8.
*doc-out --- 输出当前正在编辑的文档
- 9.
*yolo --- 切换"Yolo模式"（注：Yolo为俚语，常含"冒险、随性"之意，具体含义需结合场景）
- 10.
*exit --- 退出分析师角色

2.1.1 头脑风暴

这里我们先进行头脑风暴，假设我们想做一个经典的吃豆人游戏。

输入下面的指令：

*brainstorm  我想做一个： 经典吃豆人游戏

AI 开始引导我们进行头脑风暴～

第一轮头脑风暴问题确认：

- 1.
我们本次头脑风暴的主题是什么？（确认或细化：例如平台、玩法变体、风格等）
头脑风暴的主题是 做一个经典的吃豆人游戏。 做一个MVP。 
- 2.
有哪些约束或参数？（如平台/设备、技术栈、单人/多人、难度/节奏、时间/预算、目标受众等）
使用vite react 前端构建，单人本地游戏，有一个经典的关卡就行
- 3.
你的目标是"广泛探索"还是"聚焦某个方向的深挖"？
聚焦如何优雅的实现这个游戏。 
- 4.
是否需要生成结构化文档供后续参考？（默认：需要）
需要

生成了头脑风暴文档：brainstorming-session-results.md

Bmad 给出了 20 种对话方式，根据我们的问题，她也给出了推荐。我们使用 AI 推荐的 "4 第一性原理"开始与 AI 进行头脑风暴。

回答下面几个问题：

MVP：是 Minimum Viable Product（最小可行产品） 的缩写

引导问题（请逐条回答，以你的话输出要点）

- 功能（交互与行为）
  - 列出 MVP 必须具备的功能元素（例：吃豆人移动、幽灵追逐、豆子与能量豆、得分与生命、胜负条件）。请按"功能点：一句描述"的格式罗列。
  功能点如下：1个吃豆人，4个幽灵。吃豆人移动、幽灵追逐、豆子与能量豆、得分与生命、胜负条件
- 状态（数据与模式）
  - 列出关键状态变量（例：位置/方向/速度、关卡定时器、幽灵模式：散开/追逐/惊慌、分数与生命）。请按"状态变量：用途/取值范围"的格式罗列。
  关键状态变量：位置/方向/速度、关卡定时器、幽灵模式：散开/追逐/惊慌、分数与生命 （名字、取制范围你定，要合理） 
- 规则（约束与触发）
  - 列出核心规则（例：网格移动与碰撞、吃豆触发得分、能量豆触发幽灵惊慌计时、被幽灵碰撞扣命、清空豆子胜利）。请按"规则：条件→结果"的格式罗列。
  核心规则：吃豆人和幽灵 都按照网格移动。设定一个范围，所有角色在范围内移动，不能穿透墙壁和障碍物。可以吃能量豆，然后幽灵惊慌（需要惊慌一段时间）。被幽灵碰撞扣命、清空豆子胜利。 
  
实现选择（先做一个关键二选一）

- 移动模型你倾向于哪种？请选一个：
  - A) 基于"网格步进"的离散移动（简单、确定性强，适合 MVP）
  - B) 基于"像素插值"的连续移动（更顺滑，但实现复杂度更高）
  使用A，先做一个MVP

第二轮 头脑风暴问题确认：

回答下面几个问题：

第二轮头脑风暴后，brainstorming-session-results.md 会更新，后面给出全文。

下一步关键决策（请二选一，或给你自己的偏好）

- 渲染方式：
  - 1. 1.
       Canvas 2D （高效、易于网格和精灵渲染，适合游戏循环）
  - 1. 2.
       DOM + CSS Grid （实现更直观，React 组件化友好，但高频更新有性能压力）
       
 渲染方式使用  Canvas 2D 
- 状态管理：
  - A) React useReducer + useRef （最轻，便于纯函数式更新与逐帧循环）
  - B) 轻量外部 store（如 zustand ），将游戏状态与渲染解耦，减少不必要的 React 重渲染
我的建议：Canvas 2D + 轻量外部 store（B），让游戏引擎的逐帧更新独立于 React，使 UI 只在需要时同步。若你偏好更纯 React，可选 Canvas + useReducer。

状态管理 使用React useReducer + useRef 

推荐默认值（可直接确认或修改）

- grid ：R×C 建议 21×19 （更小巧的经典布局，便于 MVP）
- lives ：3
- frightenedRemaining ：8 秒
- pacmanSpeed ：1 单元/帧； ghostSpeed ：1 单元/帧（后续可做模式差异）
- score ：普通豆 +10，能量豆 +50，惊慌期吃幽灵 +200（链式可选先不做）
使用上面的默认值

第三轮头脑风暴问题确认：

回答下面几个问题：

第三轮头脑风暴后，brainstorming-session-results.md 会更新，后面给出全文。

继续第一性原理细化（请逐条选择/确认）

- 地图与网格
  - 1. 1.
       tileSize 建议 24px （Canvas上易配比），是否接受？ 使用 24px
  - 1. 2.
       地图存储： 二维数组 （0=空、1=墙、2=豆、3=能量豆），是否采用该编码？ 可以
  - 1. 3.
       入口/幽灵屋是否纳入 MVP？建议：先不做传送门，幽灵屋只作为初始出生点。 先不做传送门
       
- 游戏循环与节拍
  - 1. 1.
       tick 建议 120ms （每tick走一格），是否接受？ 接受
  - 1. 2.
       输入缓冲：保存 nextDir ，仅在到达交叉点且不撞墙时应用，是否采用？ 采用
- 碰撞与吃豆
  - 1. 1.
       碰撞检测基于格子占用，不做像素边界，是否确认？确认
  - 1. 2.
       吃豆逻辑：进入含豆格子即消失并加分；能量豆触发 frightenedRemaining=8s ，是否确认？确认
       
- 幽灵行为（MVP简化）
  - 1. 1.
       追逐：选择能使曼哈顿距离变小的方向，禁止立即反向；若无路则允许反向，是否确认？ 确认
  - 1. 2.
       散开：各幽灵固定目标角落（TL/TR/BL/BR），是否采用？ 采用
  - 1. 3.
       模式切换： scatter 20s → chase 40s 循环，能量豆期间强制 frightened ，是否采用？ 采用

头脑风暴开始收敛

直接回复 ： 开始。

AI 对头脑风暴过程进行总结，生成 brainstorming-session-results.md 文档。

头脑风暴结果：brainstorming-session-results.md

 # Brainstorming Session Results   
 
 **Session  Date:**  2025-10-21  
 **Facilitator:**  Business  Analyst  Mary  
 **Participant:**  You   
 ---  
 ## Executive Summary   
 **Topic:**  经典吃豆人游戏  MVP（Vite  +  React，单人，本地，经典一关）   
 **Session  Goals:**  聚焦如何优雅地实现该游戏的核心玩法与工程架构   
 **Techniques  Used:**  First  Principles  Thinking   
 **Total  Ideas  Generated:**  33   
 ### Key Themes Identified  
 -  网格步进与Canvas  2D天然契合，简化渲染与碰撞  
 -  useReducer+useRef有利于将逐帧循环与纯函数更新对齐  
 -  采用统一状态机管理幽灵模式与计时器   
 ---  
 ## Technique Sessions   
 >  本区将在会话过程中按所选技术逐步记录：   
 ### First Principles Thinking - 进行中  
 -  Description:  从第一性原理拆解：以"功能""状态""规则"为核心要素  
 -  Ideas Generated:   
 1 .  MVP功能：1个吃豆人、4个幽灵；吃豆人移动；幽灵追逐；豆子与能量豆；得分与生命；胜负条件   
 2 .  关键状态变量：
 -  pacmanPos:  行[0..R-1],  列[0..C-1]  
 -  pacmanDir:  up|down|left|right  
 -  pacmanSpeed:  cellsPerTick  ∈ { 1 }  
 -  ghosts[4]:  每个包含  pos、dir、speed、mode   
 -  ghostMode:  scatter|chase|frightened   
 -  levelTimer:  seconds  ≥  0   
 -  frightenedRemaining:  seconds  ∈ [ 0 ..10 ]  
 -  score:  int  ≥  0   
 -  lives:  int  ∈ [ 0 ..3 ] （初始3）  
 -  pelletsRemaining:  int  ≥  0   
 -  gameState:  running|win|lose   
 -  grid:  R×C  网格（R、C合理设定）   
 3 .  核心规则：   
 -  网格步进移动；不可穿透墙   
 -  吃普通豆得分；吃能量豆触发幽灵惊慌（计时）   
 -  惊慌期间与幽灵碰撞，吃掉幽灵加分；否则扣命  
 -  清空豆子胜利；生命为0失败 
 -  全角色在范围内活动，边界限制   
 4 .  移动模型：A)  网格步进（用于  MVP）   
 5 .  渲染方式：Canvas  2D   
 6 .  状态管理：React  useReducer  +  useRef   
 7 .  默认参数：grid  21 ×19；lives  3 ；frightenedRemaining  8s；速度1单元/帧；得分规则（豆+10、能量豆+50、惊慌期吃幽灵+200）   
 8 .  tileSize：24px   
 9 .  地图编码：二维数组  0 =空、1=墙、2=豆、3=能量豆   
 10 .  传送门：MVP不做；幽灵屋仅作为出生点   
 11 .  tick：120ms（每tick走一格）   
 12 .  输入缓冲：保存  nextDir，到达交叉点且不撞墙时应用   
 13 .  碰撞检测：基于格子占用，不做像素边界   
 14 .  吃豆：进入含豆格子即消失并加分；能量豆触发  frightenedRemaining=8s  
 15 .  幽灵追逐：选择使曼哈顿距离变小的方向；禁止立即反向，死路允许反向   
 16 .  幽灵散开：四个角落  TL/TR/BL/BR  为目标  
 17 .  模式切换：scatter  20s  →  chase  40s  循环；能量豆期间强制  frightened 
 -  Insights Discovered:  
 -  采用网格步进可大幅简化碰撞与AI路径决策 
 -  Canvas  2D对离散网格渲染友好，避免高频DOM重排 
 -  useReducer+useRef可将渲染与状态更新节拍对齐并减少重渲染 
 -  输入缓冲（nextDir）降低拐角错过，提升操控体验 
 -  二维数组地图编码便于关卡编辑与碰撞判断 
 -  基于曼哈顿距离的追逐与散开角落可抽象成策略接口，后续可替换  
 -  模式计时与  frightened  应与  tick  驱动统一管理，避免时间漂移  
 -  将"功能-状态-规则"映射到独立模块有利于清晰实现 
 -  惊慌计时器与幽灵模式切换需统一状态机驱动 
 -  Notable Connections:   
 -  状态机与渲染循环的tick对齐，便于  deterministic  行为  
 -  地图编码与  tileSize  共同决定绘制缩放与寻路粒度  
 -  nextDir  与交叉点检测耦合，需要预判路径可行性  
 -  模式切换与  frightenedRemaining  皆由同一计时器/状态机驱动 
 ---  
 ## 引擎架构（MVP）   
 -  模块划分  
 -  GameLoop：`setInterval`  驱动  120ms/tick；统一推进计时与状态机  
 -  Input：键盘方向键→`nextDir`  缓冲；到交叉点判定可拐再应用  
 -  StateMachine：幽灵模式  `scatter|chase|frightened`  与计时器（含强制  frightened）   
 -  Collision：墙体阻挡、吃豆/能量豆、吃豆人-幽灵碰撞
 -  AI：追逐（曼哈顿距离）、散开（角落目标）、惊慌（随机/避免反向）  
 -  Renderer(Canvas)：`tileSize=24`  绘制网格、豆子、角色；每tick刷新  
 -  TypeScript  接口草案 
 ```ts  
 type  Dir  =  'up'  |  'down'  |  'left'  |  'right'; 
 interface  Pos { r:  number;  c:  number; }  
 interface  Pacman {  
 pos:  Pos;   
 dir:  Dir;   
 nextDir:  Dir  |  null ;   
 speed:  number;  //  cells  per  tick  
 }  
 type  GhostMode  =  'scatter'  |  'chase'  |  'frightened';  
 interface  Ghost {  
 id:  number;   
 pos:  Pos;   
 dir:  Dir;   
 speed:  number;  
 mode:  GhostMode;   
 target?:  Pos;  
 }  
 interface  GameState {  
 grid:  number [][] ;  //  0  empty , 1  wall , 2  pellet , 3  power   
 pacman:  Pacman;   
 ghosts:  Ghost [] ;   
 score:  number;   
 lives:  number;   
 pelletsRemaining:  number;   
 levelTimerMs:  number;   
 frightenedRemainingMs:  number;   
 ghostModeTimerMs:  number;   
 game:  'running'  |  'win'  |  'lose';   
 tileSize:  number;  //  24   
 tickMs:  number;  //  120  
 } 
 ```   
 -  逐帧更新流程（120ms/tick）  
 ```ts 
 function  tick(state:  GameState):  GameState { 
 const  s1  =  applyInput(state);   
 const  s2  =  movePacman(s1);   
 const  s3  =  handlePelletAndScore(s2);   
 const  s4  =  updateModeTimers(s3);   
 const  s5  =  moveGhosts(s4);   
 const  s6  =  checkCollisions(s5);  
 return  checkWinLose(s6);  
 } 
 ```   
 -  关键函数原型  
 ```ts  
 function  canTurn(grid:  number[][],  pos:  Pos,  dir:  Dir):  boolean;  
 function  nextPos(pos:  Pos,  dir:  Dir):  Pos;  
 function  isWall(grid:  number[][],  pos:  Pos):  boolean;  
 function  moveEntity(pos:  Pos,  dir:  Dir,  grid:  number[][]):  Pos;  
 function  applyInput(state:  GameState):  GameState;  
 function  handlePelletAndScore(state:  GameState):  GameState;  
 function  updateModeTimers(state:  GameState):  GameState;  
 function  chooseGhostDir(ghost:  Ghost,  state:  GameState):  Dir;  
 function  moveGhosts(state:  GameState):  GameState;  
 function  checkCollisions(state:  GameState):  GameState;  
 function  checkWinLose(state:  GameState):  GameState; 
 function  render(ctx:  CanvasRenderingContext2D,  state:  GameState):  void;  
 ```   
 -  React  集成方式（useReducer  +  useRef）   
 -  `const [ state , dispatch ] =  useReducer(reducer,  initialState)`  
 -  `const  canvasRef  =  useRef<HTMLCanvasElement>(null)`   
 -  `useEffect(()  => { const  id  =  setInterval(()  =>  dispatch( { type:  'TICK' } ) , state.tickMs);  return  ()  =>  clearInterval(id); } , [ state.tickMs ] )`   
 -  `useEffect(()  => { const  ctx  =  canvasRef.current?.getContext('2d');  if  (ctx)  render(ctx , state); } , [ state ] )`   
 -  MVP  开发里程碑顺序   
 1 .  Canvas  网格渲染与静态地图   
 2 .  可控吃豆人移动  +  输入缓冲   
 3 .  豆子/能量豆消费与得分、统计剩余豆   
 4 .  幽灵基础移动（chase/scatter）与  frightened  计时  
 5 .  碰撞与胜负判断（扣命/游戏结束/胜利）   
 6 .  UI  文本与调试信息（分数、生命、模式）   
 ## Idea Categorization   
 ### Immediate Opportunities  
 1 .  Canvas  网格渲染与静态地图加载  
 2 .  可控吃豆人移动与输入缓冲  
 3 .  豆子/能量豆消费与得分  
 4 .  幽灵基础移动（chase/scatter）与  frightened  计时  
 5 .  胜负判断与  UI  提示   
 ### Future Innovations  
 1 .  路径规划优化（BFS/A*、交叉点优先、避开死路）  
 2 .  幽灵差异化速度与个性策略（Blinky/Pinky/Inky/Clyde  简化版） 
 3 .  传送门与地图装饰、粒子动画/吃豆人嘴部动画  
 4 .  声音与音乐、得分连击与奖励机制 
 5 .  多关卡支持与关卡编辑格式（JSON/CSV）  
 6 .  响应式/移动端按键适配与可访问性提示   
 ### Moonshots  
 1 .  在线多人或本地对战（吃豆人与幽灵角色切换）  
 2 .  关卡编辑器（所见即所得）与社区分享  
 3 .  AI  学习/强化幽灵策略，动态难度  
 4 .  关卡程序化生成与每日挑战  
 5 .  录像/回放与排行榜系统   
 ### Insights & Learnings  
 -  网格步进让碰撞与路径选择更确定，易于测试  
 -  Canvas  2D  渲染与离散  tick  同步，避免  DOM  高频重排  
 -  输入缓冲在交叉点应用显著提升操控手感  
 -  幽灵模式与计时最好用统一状态机驱动，减少分散逻辑  
 -  地图编码（0/1/2/3）与  tileSize  共同决定渲染与寻路粒度   
 ---  
 ## Action Planning   
 ### Top 3 Priority Ideas  
 1 )  Canvas  网格渲染与静态地图   
 -  Rationale:  奠定坐标系与视觉基础，所有逻辑依赖地图与绘制。   
 -  Next Steps:  初始化  Vite+React；实现  Canvas  组件；加载  21 ×19  地图并绘制墙/豆。   
 -  Resources:  无外部依赖；内置地图  JSON。   
 -  Timeline:  0.5  天。   
 2 )  吃豆人移动与输入缓冲（tick=120ms）   
 -  Rationale:  形成可交互核心循环，验证网格步进与转向规则。  
 -  Next Steps:  键盘监听→nextDir；交叉点判定可拐；移动与墙体阻挡；渲染位置。  
 -  Resources:  无外部依赖。   
 -  Timeline:  0.5  天。   
 3 )  幽灵基础AI与模式计时、碰撞  
 -  Rationale:  完成基本对抗玩法与难度框架。   
 -  Next Steps:  scatter/chase  切换计时器；frightened  强制；曼哈顿方向选择；   
 吃豆人-幽灵碰撞与扣命/重生；胜负判断。  
 -  Resources:  无外部依赖。   
 -  Timeline:  1  天。   
 ---  
 ## Reflection & Follow-up  
 -  What Worked Well:  第一性原理将功能-状态-规则清晰拆解；关键参数已定。  
 -  Areas for Further Exploration:  幽灵拐角选择的平局打破；地图设计与美术风格；      
 性能监测（tick  同步、渲染开销）；得分与奖励节奏。  
 -  Recommended Follow-up Techniques:  SCAMPER（趣味增强）、Morphological  Analysis（AI策略组合）、User  Story  Mapping（迭代计划）。  
 -  Questions That Emerged:  幽灵随机性阈值？胜负  UI  表达？移动端按键布局？  
 -  Next Session Planning:  进入开发冲刺第1里程碑（Canvas+地图）；随后第2里程碑（移动+输入），第3里程碑（幽灵与碰撞）。 

2.2 创建项目简报

输入下面的命令，开始生成项目简报：

 create-project-brief - 创建项目简报

AI 给出很多选项，我们可以根据实际需求选择。我这里选择：YOLO 模式，直接进入下一节。

模式选择

- 1. 1.
     交互模式（逐节协作完善，每节附方法选项）
- 1. 2.
     YOLO 模式（一次性生成完整草案，你再审阅与修订）
     请选择 1 或 2，并告知项目名（默认用"Pac-Man MVP"）与输出文件（默认 docs/brief.md ）
     
     
请选择 1-9 的一个选项进行本节的精炼或推进：

1. 1.
   进入下一节（Problem Statement）
2. 2.
   Critique and Refine（从分析师视角批判与修订）
3. 3.
   Analyze Logical Flow and Dependencies（检查结构与依赖）
4. 4.
   Assess Alignment with Overall Goals（核对与项目目标的一致性）
5. 5.
   Identify Potential Risks and Unforeseen Issues（识别可能风险与边界）
6. 6.
   Challenge from Critical Perspective（以"挑刺"视角缩减不必要范围）
7. 7.
   Tree of Thoughts Deep Dive（多路径推理深化本节内容）
8. 8.
   Agile Team Perspective Shift（PO/SM/Dev/QA多角色视角补充）
9. 9.
   Self-Consistency Validation（多版本对比选稳健措辞）

生成项目简报：brief.md

我们可以自行检查并修改brief.md。

 # Project Brief: Pac-Man MVP

**Project  Name:** Pac-Man MVP
**Date:** 2025-10-21
**Owner:** Business Analyst Mary (with You)

---

## Executive Summary
- Product Concept: 以 Vite + React + Canvas 2D 实现经典吃豆人本地单人 MVP，采用离散网格与统一 tick 状态机，强调优雅与可扩展的工程实现。
- Primary Problem: 提供一个最小而真实的吃豆人核心玩法实现，兼具教学与迭代性，避免常见"快速但杂乱"的示例代码。
- Target Market: 前端/游戏初学者、训练营/课程项目、热爱复古游戏的开发者、技术面试与作品集。
- Value Proposition: 简洁架构（`useReducer`+`useRef`、Canvas 渲染、统一幽灵模式状态机）达成确定性行为与清晰模块划分，利于扩展与维护。

Rationale
- Canvas + 网格降低渲染/碰撞复杂度，提升确定性与性能；第一性原理确保 MVP 范围清晰与工程落点明确。

---

## Problem Statement
- 当前很多小游戏示例代码为了快速可玩牺牲结构与可维护性；新手难以从中学习到清晰的工程实践。
- 需要一个结构优雅、模块边界清晰、可迭代的经典玩法 MVP，既可作为教学示例也可作为作品集展示。
- 期望核心玩法完整且确定性强，便于测试与后续扩展（路径规划、动画、音效、移动端适配等）。

---

## Proposed Solution
- 技术栈：`Vite + React (TypeScript) + Canvas 2D`；状态管理：`useReducer + useRef`；离散 `tick=120ms`。
- 核心设计：`tileSize=24px`，网格地图 `21×19`，二维数组编码（`0空/1墙/2豆/3能量豆`）。
- 幽灵模式状态机：`scatter 20s ↔ chase 40s`，能量豆触发 `frightened=8s` 强制模式。
- AI 简化：追逐选使曼哈顿距离变小的方向，禁止立即反向，死路允许反向；散开目标为四角。
- 碰撞与得分：进入含豆格子即消失并加分（豆+10、能量豆+50、惊慌期吃幽灵+200）；生命 3，清空豆子胜利，生命为 0 失败。

Rationale
- 以离散网格与统一状态机实现确定性和易测试；接口与模块划分面向后续增强（路径规划、差异化幽灵）。

---

## Target Users
### Primary User Segment: 前端/游戏开发初学者
- 目标：掌握 Canvas 网格渲染、游戏循环、状态管理、碰撞与简单 AI。
- 痛点：示例代码凌乱、不易扩展；难以理解系统性架构。

### Secondary User Segment: 教育机构/训练营与作品集打造者
- 目标：可教学/评估的示例项目；快速展示工程能力与代码质量。
- 痛点：课程示例缺少清晰结构与工程可读性；评估难以量化质量。

---

## Goals & Success Metrics
- Business Objectives
  - 在 3-5 天内交付可玩的 MVP
  - 输出清晰代码结构与文档，便于教学/复用
  - 为后续 PRD 与迭代计划提供坚实基础
- User Success Metrics
  - 学习者可在 < 30 分钟内读懂主架构与循环
  - 90% 用户可在首局内完成通关或明确失败条件
- KPIs
  - 首次可玩（TTFP）≤ 1 天；关键路径 Bug（P1）= 0
  - 帧稳定性：Canvas 渲染在现代浏览器下无明显卡顿；tick 抖动 < 10ms（均值）

---

## MVP Scope
- Core Features (Must Have)
  - 经典一关静态地图（`21×19`，`tileSize=24px`） 需要放大，适应大屏幕。
  - 吃豆人：网格步进移动；输入缓冲 `nextDir`；墙体阻挡
  - 幽灵：简化追逐/散开；模式计时与 `frightened` 强制
  - 豆子/能量豆：吃豆加分与惊慌计时；统计剩余豆
  - 碰撞与胜负：生命扣减与重生；清空豆子胜利；生命用尽失败
  - 渲染：Canvas 2D 按 `tick=120ms` 刷新
- Out of Scope for MVP
  - 传送门、复杂路径规划、差异化幽灵个性
  - 多关卡、音效音乐、粒子/精细动画、美术主题化
  - 多人模式、数据持久化、排行榜与联网功能
- MVP Success Criteria
  - 在目标浏览器中稳定运行，核心玩法无高优 Bug
  - 完整演示移动/吃豆/幽灵模式/碰撞/胜负，代码结构清晰

---

## Post-MVP Vision
- Phase 2 Features
  - BFS/A* 路径规划与交叉点策略；音效/音乐；吃豆人/幽灵动画
  - 幽灵差异化速度与个性（Blinky/Pinky/Inky/Clyde 简化版）
- Long-term Vision
  - 多关卡与关卡编辑器；移动端适配与可访问性；排行榜与回放
- Expansion Opportunities
  - 社区分享关卡；程序化生成每日挑战；模组与皮肤支持

---

## Technical Considerations
- Platform Requirements
  - 目标平台：现代桌面浏览器（Chrome/Edge/Firefox/Safari）
  - 性能：离散 `tick=120ms`，Canvas 渲染与状态更新同步；网格步进简化碰撞
- Technology Preferences
  - 前端：`Vite + React (TypeScript)`；渲染：`Canvas 2D`
  - 状态：`useReducer + useRef`；无后端/数据库；本地单人
- Architecture Considerations
  - 单仓库，模块：GameLoop / Input / StateMachine / Collision / AI / Renderer
  - 集成：无外部 API；安全合规：N/A（本地离线）

---

## Constraints & Assumptions
- Constraints
  - Budget：N/A（内部学习/示例项目）
  - Timeline：MVP 3-5 天；首版演示 ≤ 1 天
  - Resources：1 开发者 + 1 分析师角色；不涉及后端
  - Technical：Canvas 2D；不做像素级碰撞；单人本地
- Key Assumptions
  - 单关卡即可展示核心玩法与工程结构
  - 用户设备为现代浏览器环境；分辨率适配桌面优先

---

## Risks & Open Questions
- Key Risks
  - 输入缓冲与交叉点判定细节影响操控手感
  - 幽灵拐角平局打破策略可能影响难度与公平性
  - 计时器与渲染同步造成边界行为（抖动/掉帧）
- Open Questions
  - 幽灵随机性阈值如何设定？胜负 UI 如何表达？
  - 是否需要移动端虚拟按键？何时引入音效？
- Areas Needing Further Research
  - 经典地图数据来源与授权；路径规划策略对比与测试

---

## Appendices
- A. Research Summary
  - 参考"First Principles"会话文档：功能/状态/规则与技术选型已确定
- B. Stakeholder Input
  - 来自用户与分析师协作的决策与偏好
- C. References
  - `docs/brainstorming-session-results.md`

---

## Next Steps
- Immediate Actions
  1. 初始化 `Vite + React` 项目与基础目录
  2. 创建 `Canvas` 组件并绘制静态地图（`21×19`）
  3. 输入缓冲与吃豆人移动（`tick=120ms`）
  4. 豆子/能量豆消费与得分、统计剩余豆
  5. 幽灵基础移动与模式计时、`frightened` 强制
  6. 碰撞与胜负判断；生命/重生逻辑
  7. UI 提示（分数/生命/模式）与调试信息
- PM Handoff
  - 本项目简报为 Pac-Man MVP 提供完整上下文。请进入 PRD 生成模式，逐节审阅与完善，提出必要澄清或优化建议，随后推进实现。

2.3 产品经理

重新打开一个对话，命令行输入：

注意： 通过 # 号选中 pm.md 文件

pm.md 是 Product Manager 智能体，John

#pm.md

召唤项目经理后，他让我们给出指令：

建议的下一步

- 请选择你希望如何创建 PRD：
  - 1. 1.
       交互模式：逐节推进并使用 1-9 选项精炼内容（符合模板工作流）
  - 1. 2.
       YOLO 模式：一次性生成完整草案，随后你再审阅与修订
  - 1. 3.
       查看 PM 可用命令清单
  - 1. 4.
       退出
       
       我的指令： 使用 YOLO 模式 生成 PRD
如果选择 1，我将从 "Goals and Background Context" 开始：

- Goals：根据 docs/brief.md 的目标与 MVP 成功标准预填要点
- Background：提炼简报的背景与问题陈述，避免与 Goals 重复
- Changelog：初始化变更表（Date/Version/Description/Author）
如果选择 2（YOLO），我会直接生成 docs/prd.md 的完整初稿，内容将基于：

- docs/brief.md 的 Executive Summary / MVP Scope / Technical Considerations / Risks
- 先给出 Functional/NFR 的编号条目、UI 目标的高层愿景、Technical Assumptions 的技术决策、合适的 Epic 列表与示例故事结构
请回复选项（1/2/3/4）。

AI 生成 prd.md 文档。

 # Pac-Man MVP --- Product Requirements Document (PRD)

**Project Name:** Pac-Man MVP  
**Date:** 2025-10-21  
**Owner:** PM Agent (with You)

---

## Goals & Background
### Goals
- 在 3--5 天内交付可玩的 MVP，并在 ≤1 天内达到首次可玩。
- 以简洁架构演示核心玩法：`useReducer + useRef`、Canvas 网格渲染、统一幽灵模式状态机。
- 确保行为确定性与可测试性：离散 `tick=120ms`，网格步进碰撞，模式计时一致。
- 输出可教学、可复用的代码与文档，支持后续迭代（路径规划、动画、音效、多关）。

### Background
Pac-Man MVP 旨在以现代前端栈（Vite + React + TS + Canvas 2D）重现经典吃豆人单人玩法，优先选择离散网格与统一状态机以降低复杂度并提升确定性。目标用户包括前端/游戏初学者与课程/作品集场景，强调清晰模块划分与工程可维护性。MVP 范围锁定单关卡、简化 AI 与碰撞/胜负判定，提供可扩展的基础。

### Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-10-21 | v0.1 | 初版 PRD（YOLO）基于简报生成 | PM Agent + You |

---

## Requirements
### Functional Requirements (FR)
1. Canvas 网格渲染：固定地图 `21×19`，`tileSize=24px`，二维数组编码（0 空、1 墙、2 豆、3 能量豆）。
2. 渲染要素：按编码绘制墙、豆子、能量豆；地图边界不可越界。
3. 游戏循环：离散 `tick=120ms`；每 tick 进行状态推进与 Canvas 重绘。
4. 吃豆人移动：网格步进（每 tick 一格）；不可穿墙；支持输入缓冲 `nextDir` 于交叉点生效。
5. 输入支持：键盘方向键（↑↓←→）与 WASD；同时处理按下与持续按压，避免抖动。
6. 豆子/能量豆：进入含豆格即移除并加分（豆 +10、能量豆 +50）；统计 `pelletsRemaining`。
7. 幽灵模式状态机：`scatter=20s ↔ chase=40s` 循环；能量豆触发 `frightened=8s`（覆盖其余模式）。
8. 幽灵移动（简化 AI）：在追逐模式选择使曼哈顿距离变小的方向；禁止立即反向；死路允许反向；散开目标为四角点。
9. 碰撞规则：正常模式碰撞吃豆人-1 生命并重生；`frightened` 下吃豆人可吃幽灵 +200 分，幽灵回巢重生。
10. 胜负判定：`pelletsRemaining=0` 则胜；`lives=0` 则败；重置/开始流程明确。
11. UI 叠层：显示分数、生命、当前模式（scatter/chase/frightened）与剩余豆，必要提示（开始/胜利/失败）。
12. 状态持久：运行期内以内存管理，不涉及存储；允许重新开始并清理状态。

### Non-Functional Requirements (NFR)
1. 性能稳定：在现代浏览器保持平均 `tick` 抖动 < 10ms；渲染无明显卡顿。
2. 兼容性：Chrome/Edge/Firefox/Safari 最新稳定版桌面环境；像素比适配（`devicePixelRatio`）。
3. 代码质量：TypeScript 强类型；模块边界清晰；无不必要依赖；易读易测。
4. 测试策略：对纯函数（如 `canTurn`、`nextPos`、碰撞判定、模式计时推进）提供单元测试；对核心循环提供轻量集成测试。
5. 可访问性（MVP）：键盘即可玩；高对比色与清晰提示；屏幕阅读器支持非必需。
6. 确定性：以离散 tick 驱动所有逻辑；避免基于实时毫秒漂移的隐性差异。
7. 安全与隐私：纯客户端、无外部数据；不采集用户信息。

---

## UI Goals
- UX 愿景：复古简洁风格，信息清晰优先于华丽；强调操控手感与反馈。
- 交互范式：网格步进 + 输入缓冲；开始/暂停/重开；胜负叠层提示。
- 核心视图：
  - 游戏主视图（Canvas）
  - HUD（分数/生命/模式/剩余豆）
  - Start/Win/Lose 叠层
- 可访问性：MVP 目标为"WCAG AA（部分达成）"。
- 品牌与风格：经典蓝墙、黄吃豆人、白豆点；色彩高对比与像素化轻风格。
- 目标设备与平台：桌面优先；分辨率自适配到固定网格。

---

## Technical Assumptions
- 仓库结构：Monorepo（单项目）。
- 服务架构：前端单体（Monolith），纯客户端，无后端服务。
- 测试要求：Unit + Integration。
- 其他假设：
  - 主循环以 `setInterval`/`requestAnimationFrame` 包装离散节拍；状态推进绑定 tick。
  - 地图静态载入于启动阶段；精简配置常量（`tileSize`、`tickMs`、网格尺寸）。
  - `GameLoop / Input / StateMachine / Collision / AI / Renderer` 明确分层与职责。

---

## Epic List
- Epic 1 --- 基础与 Canvas 渲染：初始化项目、绘制静态网格与地图要素。
- Epic 2 --- 吃豆人移动与吃豆：键盘输入缓冲、网格步进、豆/能量豆消费与计分。
- Epic 3 --- 幽灵模式与碰撞胜负：模式计时、追逐/散开/惊慌、碰撞与生命、胜负流转。

---

## Epic Details
### Epic 1 --- 基础与 Canvas 渲染
- Story 1.1：项目初始化与空白画布
  - 接受标准：
    1. 可运行 `Vite + React` 开发服务器，页面加载成功。
    2. 页面包含固定大小 Canvas，DPR 自适配。
    3. 基础目录与模块占位（loop/input/state/ai/render）建立。
- Story 1.2：静态网格与墙体绘制
  - 接受标准：
    1. 从二维数组编码加载 `21×19` 地图；`tileSize=24px`。
    2. 按编码绘制墙体；边界碰撞数据与渲染一致。
    3. 刷新周期与逻辑推进由统一 tick 驱动。
- Story 1.3：豆子与能量豆渲染
  - 接受标准：
    1. 正常豆与能量豆区分渲染样式。
    2. 初始统计 `pelletsRemaining` 与能量豆数量。
    3. 渲染层与 HUD 预留位置不遮挡主视图。

### Epic 2 --- 吃豆人移动与吃豆
- Story 2.1：输入缓冲与方向切换
  - 接受标准：
    1. 支持方向键与 WASD；按下即写入 `nextDir`。
    2. 在交叉点可切换为 `nextDir`；非交叉点不抖动不穿墙。
    3. 禁止立即反向穿墙；方向合法性函数可单测。
- Story 2.2：网格步进与位置更新
  - 接受标准：
    1. 每 tick 推进一格；越界与墙体阻挡正确。
    2. 位置状态与 Canvas 渲染同步，无跳帧错位。
    3. 具备调试显示（可选）：当前格坐标与方向。
- Story 2.3：吃豆与计分
  - 接受标准：
    1. 进入含豆格即移除并加分（豆 +10）。
    2. 能量豆触发 `frightened=8s` 并 +50 分；HUD 显示计时状态。
    3. `pelletsRemaining` 实时更新；所有豆清空判定胜利。

### Epic 3 --- 幽灵模式与碰撞胜负
- Story 3.1：模式状态机与计时
  - 接受标准：
    1. `scatter 20s ↔ chase 40s` 循环；`frightened=8s` 覆盖。
    2. 模式切换在 HUD 可见；计时精度与 tick 同步。
    3. 多幽灵共享统一模式管理，个体状态可扩展。
- Story 3.2：追逐/散开/惊慌移动
  - 接受标准：
    1. 追逐：选择使曼哈顿距离减小的方向；平局打破策略一致。
    2. 散开：各自角点目标；死路允许反向；禁止立即反向规则一致。
    3. 惊慌：随机/半随机游走，颜色或速度反馈（简化）。
- Story 3.3：碰撞、生命与胜负
  - 接受标准：
    1. 正常模式碰撞：吃豆人生命 -1，位置重置，幽灵可保持或重生（简化选择其一）。
    2. 惊慌期碰撞：吃豆人吃幽灵 +200 分，幽灵回巢重生；连吃计分可扩展（MVP 单次）。
    3. 胜负：豆清空胜利；生命为 0 失败；叠层提示与重开按钮可用。

---

## Checklist Results
- 需求一致性检查：通过（与简报一致）。
- 技术可行性评估：通过（栈与范围匹配）。
- 风险回顾与缓解：记录（输入缓冲与模式计时为重点）。

---

## Next Steps
- UX Expert Prompt：
  - 目标：基于 PRD 的 HUD 与叠层信息架构优化，确保信息密度、层级与反馈节奏合理；提供色彩与对比建议，定义键盘交互提示与空状态文案。
- Architect Prompt：
  - 目标：将 `GameLoop / Input / StateMachine / Collision / AI / Renderer` 细化为文件与函数清单；定义 `tickMs`、`tileSize`、地图载入、模式计时器与碰撞函数的接口；制定最小单元测试面。

---

## References
- `docs/brief.md`
- `docs/brainstorming-session-results.md`

产品经理输出项目文档

2.4 架构师

召唤架构师，通过 # 号选择文件 architect.md。

#architect.md

架构师会阅读文档，然后修改、生成相关文档。

生成架构相关文档

ui-architecture.md

 # Pac-Man MVP --- Frontend Architecture Document   **Project  Name:**  Pac-Man  MVP  **Date:**  2025-10-21  **Owner:**  Architect  (with  You)   ---  ## Template and Framework Selection  -  Starter:  `Vite  +  React  (TypeScript)`，纯前端单体，无后端/API。UI  以  Canvas  2D  为主，HUD  为  React  组件。  -  Design Drivers:  离散  `tick=120ms`、网格步进（`tileSize=24px`、`21×19`  地图）、统一幽灵模式状态机（scatter/chase/frightened）。  -  Not Using:  路由（MVP  单页）、外部  API、复杂动效库（后续可加）。  -  Rationale:  Vite  +  React  提供快速开发与良好  DX；TypeScript  强类型利于教学与维护；Canvas  2D  与离散  tick  保证确定性与性能。   ### Change Log  |  Date  |  Version  |  Description  |  Author  |  |------|---------|-------------|--------|  |  2025-10-21  |  v0.1  |  初版前端架构文档（YOLO）  |  Architect  +  You  |   ---  ## Frontend Tech Stack   ### Technology Stack Table  |  Category  |  Technology  |  Version  |  Purpose  |  Rationale  |  |----------|-----------|---------|---------|-----------|  |  Framework  |  React  |  18. x  |  UI  组件与  HUD  |  主流生态、TS  良好支持  |  |  Build  Tool  |  Vite  |  5. x  |  开发/构建  |  快速冷启动、优秀  DX  |  |  Language  |  TypeScript  |  5. x  |  强类型  |  教学友好、降低错误率  |  |  Rendering  |  Canvas  2D  |  N/A  |  游戏画面绘制  |  轻量、可控、性能稳定  |  |  State  Management  |  React  `useReducer`  +  `useRef`  |  N/A  |  核心循环与实体状态  |  简洁、确定性强  |  |  Testing  |  Vitest  +  React  Testing  Library  |  latest  |  单元/集成测试  |  轻量、与  Vite  集成  |  |  Styling  |  CSS  Modules  +  CSS  Vars  |  N/A  |  HUD  样式与主题  |  简单直观、易维护  |  |  Routing  |  N/A（可选  `react-router-dom`）  |  N/A  |  单页（MVP）  |  MVP  不需要复杂路由  |  |  Dev  Tools  |  ESLint  +  Prettier  |  latest  |  规范/格式化  |  保持一致风格  |   ---  ## Project Structure  ```  src/   app.tsx   main.tsx   constants.ts   types/   index.ts   data/   map.ts   systems/   loop.ts   input.ts   state.ts   collision.ts   ai.ts   render.ts   utils/   grid.ts   math.ts   ui/   Hud.tsx   Overlay.tsx   styles/   hud.module.css   theme.css  ```  -  `systems/`：游戏各子系统的纯逻辑模块（可单测）。  -  `ui/`：仅用于  HUD/叠层的  React  组件；不直接持有游戏状态，订阅只读片段。  -  `types/`：共享  TS  类型。  -  `data/`：静态地图与初始配置。  -  `constants.ts`：集中常量（`tickMs`、`tileSize`、尺寸等）。   ---  ## Component Standards  -  Component Style:  函数组件  +  TS  类型；无副作用渲染；状态通过  props  或  selector  派生。  -  Naming:  组件  `PascalCase`；文件  `PascalCase.tsx`；hooks  `useXxx.ts`；工具  `camelCase.ts`。   ### Component Template (React + TS)  ```tsx  import  React  from  'react';   type  HudProps  = {  score:  number;   lives:  number;   mode:  'scatter'  |  'chase'  |  'frightened';   pelletsRemaining:  number;  } ;   export  function  Hud({  score,  lives,  mode,  pelletsRemaining  }:  HudProps) {  return  (   <div  className="hud">   <span>Score: { score } </span>   <span>Lives: { lives } </span>   <span>Mode: { mode } </span>   <span>Pellets: { pelletsRemaining } </span>   </div>   );  } ```   ### Naming Conventions  -  目录：`systems`,  `ui`,  `types`,  `data`,  `utils`。  -  文件：`PascalCase.tsx`（组件）、`camelCase.ts`（工具/系统）。  -  类型：`TypeName`（接口/类型）、`EnumName`（枚举）。  -  常量：`SCATTER_MS`,  `CHASE_MS`,  `FRIGHTENED_MS`,  `TILE_SIZE`,  `TICK_MS`。   ---  ## State Management  -  Pattern:  `useReducer`  驱动  `GameState`；`useRef`  持有非渲染关键引用（Canvas  context、计时器、键盘订阅）。  -  规则：所有推进以  `tick`  为节拍；禁止直接在  UI  改写核心状态；系统函数纯逻辑。   ### Store Structure  ```  state/   index.ts   reducer.ts   selectors.ts   actions.ts  ```   ### State Template (TypeScript)  ```ts  //  types/index.ts  export  type  Dir  =  'up'  |  'down'  |  'left'  |  'right';  export  type  Tile  =  0  |  1  |  2  |  3 ;  //  空/墙/豆/能量豆  export  type  GhostMode  =  'scatter'  |  'chase'  |  'frightened';   export  interface  Pos { x:  number;  y:  number; } export  interface  Pacman { pos:  Pos;  dir:  Dir;  nextDir:  Dir  |  null ; } export  interface  Ghost { id:  string;  pos:  Pos;  dir:  Dir;  mode:  GhostMode; }  export  interface  GameState {  grid:  Tile [][] ;   score:  number;   lives:  number;   pelletsRemaining:  number;   tick:  number;   modeTimerMs:  number;  //  当前模式剩余毫秒   frightenedTimerMs:  number;  //  若>0则处于惊慌   pacman:  Pacman;   ghosts:  Ghost [] ;  }  //  state/actions.ts  export  type  Action  =   | { type:  'tick' }  | { type:  'setNextDir';  dir:  Dir }  | { type:  'restart' } ;   //  state/reducer.ts  export  function  reducer(state:  GameState,  action:  Action):  GameState {  switch  (action.type) {  case  'tick':   //  由  systems  下纯函数推进：移动/吃豆/计时/碰撞   return  state;  //  具体逻辑在  systems/*   case  'setNextDir':   return { ...state , pacman: { ...state.pacman , nextDir:  action.dir } } ;   case  'restart':   //  重置为初始状态   return  state;  //  具体由初始化函数提供   default:   return  state;  } } ```   ---  ## API Integration  -  MVP：不涉及外部  API；提供可扩展的服务模板以便后续引入。   ### Service Template (TypeScript)  ```ts  export  interface  HighScore { name:  string;  score:  number;  ts:  number; }  export  async  function  fetchHighScores():  Promise<HighScore[]> {  //  Placeholder:  后续可替换为真实  HTTP  客户端   return [] ;  } ```   ---  ## Routing  -  MVP  不需要路由；如后续引入：  ```ts  //  示例（React  Router）  import { createBrowserRouter } from  'react-router-dom';  export  const  router  =  createBrowserRouter([  { path:  '/' , element:  <App  /> } ,  { path:  '/about' , element:  <About  /> } ,  ]);  ```   ---  ## Styling Guidelines  -  Approach:  CSS  Modules  +  CSS  变量；HUD  使用模块化样式，Canvas  外观尽量简洁高对比。   ### Global Theme Variables  ```css  :root {  --color-bg:  #000;   --color-wall:  #0033cc;   --color-pacman:  #ffcc00;   --color-ghost:  #ff3366;   --color-pellet:  #ffffff;   --space-1:  4px;   --space-2:  8px;   --space-3:  12px;   --font-sans:  ui-sans-serif , system-ui , -apple-system , Segoe  UI , Roboto;  }  .hud {  color:  var(--color-pellet);   display:  grid;   grid-auto-flow:  column;   gap:  var(--space-2);  } ```   ---  ## Testing Requirements  -  Minimal:  纯函数单测（移动/可拐判定/碰撞/计时推进）、核心循环轻量集成测、HUD  渲染测试。   ### Component Test Template  ```ts  import { render , screen } from  '@testing-library/react';  import { Hud } from  './Hud';  import { describe , it , expect } from  'vitest';   describe('Hud',  ()  => {  it('renders  score  and  lives' , ()  => {  render(<Hud  score= { 100 } lives= { 3 } mode="scatter"  pelletsRemaining= { 200 } />);   expect(screen.getByText(/Score:  100 /)).toBeInTheDocument();   expect(screen.getByText(/Lives:  3 /)).toBeInTheDocument();  } );  } );  ```   ### Testing Best Practices  1 .  Unit：systems  下纯函数优先（可拐判定、下一格、碰撞）。  2 .  Integration：tick  推进与  HUD  同步渲染的最小路径。  3 .  E2E：关键用户流（开始→移动→吃豆→碰撞→胜负）。  4 .  覆盖率目标：≥  80 %。  5 .  Arrange-Act-Assert  结构化编写。  6 .  Mock  外部依赖（后续引入  API  时）。   ---  ## Environment Configuration  -  使用  `VITE_`  前缀：  ```  VITE_APP_TITLE=Pac-Man  MVP  VITE_TICK_MS=120  VITE_TILE_SIZE=24  VITE_MAP_ID=classic-21x19  ```  -  说明：若未提供  `.env`，使用  `constants.ts`  中的默认值。   ---  ## Frontend Developer Standards   ### Critical Coding Rules  -  所有逻辑推进以  `tick`  驱动；禁止在渲染期间改写核心状态。  -  `systems/*`  保持纯逻辑、无直接  DOM  操作；Canvas  渲染集中在  `render.ts`。  -  输入缓冲仅在交叉点应用；方向合法性检查为纯函数（可单测）。  -  禁止即时反向规则统一在  AI/移动逻辑中实现，保持一致性。  -  共享类型与常量集中在  `types/`  与  `constants.ts`，避免重复定义。   ### Quick Reference  -  Commands：`npm  run  dev`（启动）、`npm  run  build`（构建）、`npm  run  test`（测试）。  -  Imports：`systems/*`  仅依赖  `types`  与  `constants`；`ui/*`  经选择器读取只读状态。  -  File  Naming：组件  `PascalCase.tsx`，系统  `camelCase.ts`，选择器  `getXxx`。  -  Project  Patterns：离散  `tick`  →  `systems`  推进  →  `render`  绘制；HUD  通过  props  展示状态。   ---  ## Alignment  -  与  PRD  一致：模块划分、常量与  tick、地图与模式计时、测试范围。  -  引用：`docs/brief.md`、`docs/prd.md`。 

检查一下生成的架构文档，让 AI 继续补充

继续处理，可以问我问题 如果你不知道怎么行动

- Confirm tech versions.

- Proceed to Frontend UI Architecture (docs/ui-architecture.md) for component naming, file conventions, and state management details.

2.5 文档分片

2.5.1 PRD 分片

注意： 通过 # 号选择对应的文档。

#shard-doc.md 运行shard 命令处理 #prd.md

• 基于二级章节将大型文档拆分为多个小型文档

• 创建文件夹结构以整理分片后的文档

• 保持所有内容的完整性，包括代码块、图表和 Markdown 格式

该命令需要先安装一个工具，可以让 TRAE 先安装再运行。

运行后， PRD 文档被切分。

2.5.2 架构文档分片

输入下面的命令，使用 # 号选择文件 shard-doc.md 和 ui-architecture.md（不同项目，这个名词可能不同）。

#shard-doc.md 运行shard命令处理 #ui-architecture.md

生成一系列的 UI 架构文档。

2.6 创建用户故事

输入下面的命令：

# create-next-story.md

生成了 1.1.story.md 文档。

 # Story 1.1 --- 项目初始化与空白画布

Status: Draft
Epic: Epic 1 --- 基础与 Canvas 渲染
Owner: Dev

## Story Statement
初始化 `Vite + React (TypeScript)` 项目并建立基础目录结构；页面加载成功且包含一个固定尺寸的 Canvas（支持 DPR 自适配）；为核心子系统创建占位文件（loop/input/state/ai/render），为后续迭代提供稳定的渲染与组织基础。

## Acceptance Criteria (来自 PRD)
1. 可运行开发服务器（`npm run dev`），页面加载成功。[Source: prd/epic-details.md#epic-1-----基础与-canvas-渲染]
2. 页面包含固定大小 Canvas，DPR 自适配。[Source: prd/epic-details.md#epic-1-----基础与-canvas-渲染]
3. 基础目录与模块占位（`loop`/`input`/`state`/`ai`/`render`）建立。[Source: prd/epic-details.md#epic-1-----基础与-canvas-渲染]

## Dev Notes（架构上下文）
- 技术栈与工具：React 18、Vite 5、TypeScript 5、Vitest、CSS Modules。[Source: ui-architecture/frontend-tech-stack.md#technology-stack-table]
- 目录结构：`src/systems/*`（纯逻辑）、`src/ui/*`（HUD/叠层）、`src/data/map.ts`、`src/types`、`constants.ts`。[Source: ui-architecture/project-structure.md]
- 状态管理：`useReducer` 驱动 `GameState`；`useRef` 管理非渲染引用（context/timers/inputs）。[Source: ui-architecture/state-management.md]
- 渲染策略：Canvas 2D，逻辑推进与渲染分离；HUD 使用 React 组件。[Source: ui-architecture/template-and-framework-selection.md]
- 样式与主题：CSS 变量与模块化样式，用于 HUD 与基础布局。[Source: ui-architecture/styling-guidelines.md]
- 测试：纯函数单元测试优先，最小集成测试覆盖渲染路径；覆盖率目标 ≥ 80%。[Source: ui-architecture/testing-requirements.md]
- 环境配置：`VITE_TICK_MS`、`VITE_TILE_SIZE` 等，缺省值在 `constants.ts` 提供。[Source: ui-architecture/environment-configuration.md]

### Previous Story Insights
- 无（首个故事）。

### Data Models
- 无强制后端数据模型；地图数据使用二维数组编码。[Source: ui-architecture/project-structure.md]

### API Specifications
- MVP 不涉及外部 API。[Source: ui-architecture/api-integration.md]

### Component Specifications
- Canvas 渲染组件：负责创建并持有 `CanvasRenderingContext2D`；仅执行绘制，逻辑推进在 `systems/*`。[Source: ui-architecture/project-structure.md]
- HUD 组件：展示分数/生命/模式等（占位）。[Source: ui-architecture/component-standards.md#component-template-react-ts]

### File Locations（按项目结构）
- `src/main.tsx`：应用入口；挂载根组件。
- `src/app.tsx`：组合 Canvas 与 HUD。
- `src/constants.ts`：默认常量（`tickMs=120`、`tileSize=24`）。[Source: ui-architecture/template-and-framework-selection.md]
- `src/systems/loop.ts`：游戏循环占位（后续实现）。
- `src/systems/input.ts`：输入订阅占位（后续实现）。
- `src/systems/state.ts`：`GameState` 初始化与 reducer 框架（占位）。[Source: ui-architecture/state-management.md]
- `src/systems/render.ts`：Canvas 初始化与清屏/网格线占位（本故事可先空白）。
- `src/ui/Hud.tsx`：HUD 组件占位。
- `src/ui/styles/theme.css`：主题变量。

### Testing Requirements（本故事）
- 单测：`constants.ts` 默认值；`state` 初始化函数返回结构。
- 集成：渲染根组件，存在 Canvas 元素且尺寸正确；开发服务器可运行。
- 参考：[Source: ui-architecture/testing-requirements.md]

### Technical Constraints
- 离散 tick：`tick=120ms`；网格步进 `tileSize=24px`；地图尺寸 `21×19`（后续故事才绘制）。[Source: ui-architecture/template-and-framework-selection.md]

## Tasks / Subtasks
1. 初始化项目骨架（AC: 1）
   - 使用 Vite 创建 React + TS 项目结构（或在现有项目内添加 `src/*` 结构）。[Source: ui-architecture/project-structure.md]
   - 添加 `eslint`、`prettier` 基础配置（可选）。[Source: ui-architecture/frontend-tech-stack.md]
2. 创建基础目录与占位文件（AC: 3）
   - 新建 `src/systems/{loop,input,state,ai,render}.ts` 空文件并导出占位函数。[Source: ui-architecture/project-structure.md]
   - 新建 `src/ui/Hud.tsx` 与 `src/ui/styles/theme.css` 占位。[Source: ui-architecture/component-standards.md]
   - 新建 `src/constants.ts` 并提供默认常量；读取 `import.meta.env`。[Source: ui-architecture/environment-configuration.md]
3. 页面引导与 Canvas（AC: 2）
   - 在 `App` 中渲染固定尺寸 Canvas；根据 `window.devicePixelRatio` 进行 DPR 适配（像素缩放与实际大小一致）。[Source: ui-architecture/template-and-framework-selection.md]
   - 预留 `render.ts` 的 `initCanvas(ctx)` 与 `clear()` 占位方法。[Source: ui-architecture/project-structure.md]
4. 最小测试与运行（AC: 1,2,3）
   - 单元测试：`state` 初始化与 `constants` 默认值。[Source: ui-architecture/testing-requirements.md]
   - 轻量集成测试：渲染根组件存在 Canvas；尺寸断言。
   - 运行 `npm run dev` 验证页面加载与元素存在。

## Project Structure Notes
- 已与 UI 架构文档对齐使用 `src/systems/*` 与 `src/ui/*` 分层。核心配置中的 `architectureShardedLocation: docs/architecture` 与当前 UI 架构分片位于 `docs/ui-architecture/` 不一致；保持现状并在后续需要时统一迁移即可。

## Checklist Results
- Story Draft Checklist：已自检完整性（状态、AC、任务、架构引用）。
- Deviations：无。

## Next Steps
- 审阅并确认后进入开发执行；若需迁移到 `docs/architecture/`，请确认后我再统一更新引用与目录。

2.7 产品负责人核对

输入下面的指令（通过 # 号选择 po.md文档）。

#po.md

让产品负责人检查 故事文档。

AI 觉得可以开始实施了，咱们准备开始让 AI 写代码！

2.8 编写代码

输入下面的命令，指定故事文档，开始编写代码：

注意：用 # 号选择 1.1.story.md 文档 （之前生成的故事文档）。

 
*develop-story  开发  #1.1.story.md

项目创建时，需要通过 vite 脚手架，创建项目内容，终端中选择忽略并执行。

存在的文件都是文档，直接在目录中生成代码即可。

项目启动后（底部 5173 出现），点击右边的 跳过。

Vite react 项目脚手架建立成功，如图所示。AI 继续编码。

过程中会出现思考次数达到上限的提示，直接点击 继续。

运行期间，AI 会进行一些代码测试，可能需要用户手动在终端部分按 q 键退出 。

2.9 项目调优

2.9.1 第 1 版

第一版没有出现游戏界面，查看了一下发现 1.1.story.md的定义就是完成这个画布。

接下来需要生成完整的用户故事。

输入指令 （用#号选择文档）。

根据 #docs 中的prd 和 #ui-architecture 目录中的PRD文档和架构文档，补充 除了 #1.1.story.md 之外的其他所有用户故事

分析 PRD 和 架构文档发现：其他用户故事缺失。

这是由于在 2.6 环节，没有明确说明 【用户故事的范围】。

补全之后，故事文档都齐备了，打开 MAX 模式。

MAX 模式根据全部用户故事生成代码。

注意：用 # 号选择目录 stories。

*develop-story  根据 #stories 中的所有故事文档，开发

2.9.2 第 2 版

游戏界面没有吃豆人和幽灵，检查用户故事发现： 模型犯懒。

AI 只生成了基础系统，还没有实现角色显示和移动。推测这里没生成的原因是我们在 2.8 中没有明确约束软件完成度。

我们继续让 AI 实现功能。

界面上没有吃豆人，也没有 幽灵（幽灵自动追击吃豆人，用户可以通过wsad控制 吃豆人行进方向）。 检查一下 stories 目录中的 故事文档，这部分是缺失么？如果缺失，需要补充故事文档，然后生成对应代码。

2.9.3 第 3 版

AI 实现了部分功能，还有一些功能没有实现，继续要求它实现。

上图中，可以看到幽灵在动，但是动得太快了，我们让 AI 优化。

你需要继续实现：
- Story 2.2 - 网格步进与位置更新（让吃豆人真正移动起来）
- Story 2.3 - 吃豆与计分（实现游戏核心玩法）
- Story 3.x - 幽灵 AI 和碰撞系统

另外幽灵动得慢一些，符合游戏界的最佳实践设定

提出我们的要求，让 AI 优化。

2.9.4 第 4 版

可以吃豆，能量豆吃了幽灵会跑；吃幽灵后，幽灵不消失；幽灵动作太快，会闪现。

继续优化：

1. 调整幽灵的运动速度参数，将其移动速度降低至适宜水平，确保移动缓慢但保持游戏平衡性。优化运动轨迹算法和动画过渡效果，实现流畅自然的慢速移动表现，同时保持与游戏场景的协调性。

2. 实现能量豆的特殊效果机制：当吃豆人吃掉能量豆后，若与幽灵相遇，触发幽灵被吃掉（消失）的判定逻辑。需确保该状态持续到能量豆效果结束，并正确显示幽灵消失的动画效果。

2.9.5 第 5 版

基本可用效果视频。

结语

通过这个 BMAD-METHOD 的实战之旅，我们从一个简单的"经典吃豆人"idea 出发，历经头脑风暴、文档生成、用户故事拆解，到最终的代码迭代与优化，短短几步就构建出一个可玩的 MVP。

这个过程不仅仅是开发一个游戏，更是见证 AI 如何重塑工作流：它解决了传统开发中的痛点，让规划与执行无缝衔接，人类干预如点睛之笔般精准。TRAE 和 BMAD-METHOD™证明了，AI 代理不是取代开发者，而是成为你的"敏捷大脑"，让创意从 idea 瞬间落地。

相关资料

• BMAD-METHOD: Universal AI Agent Framework:

  github.com/bmad-code-o...

• B 站视频：

  www.bilibili.com/video/BV1o6...

• Youtube:

  www.youtube.com/watch?v=6Lt...