启动提示词：

请按以下流程执行任务：

1. 
   

   先完整读取：

   
   
   
   
   • docs/agent-rules.md
   
   
   • docs/agent-plan.md
   
   
   • docs/agent-progress.md
   
   
   
   


2. 
   

   严格遵守 agent-rules.md 中的所有规则。

   
   


3. 
   

   以 agent-progress.md 中的「当前批次」为本轮范围，
   
   按 agent-plan.md 的卡片顺序，只执行该批次中状态为 TODO 的卡片。

   
   


4. 
   

   每完成一张卡片，按 rules.md 要求更新 plan.md 和 progress.md。

   
   

先输出本轮将执行的卡片列表，再开始执行。

以下是简化版的操作流程：

1. 先让 AI 根据需求生成卡片


2. 你确认批次和依赖


3. 把卡片粘到 agent-plan.md


4. 让 Agent 按 rules/progress/plan 执行


5. 每轮只做当前批次


6. 批次完成后停下


7. 你检查结果，再决定是否进入下一批

agent-rules（agent运行总则）

Agent 执行规则

本文件定义 Codex / Agent 执行任务时必须遵守的固定规则。

配套文件：

• docs/agent-plan.md：任务卡片（卡片状态以本文件为权威源）


• docs/agent-progress.md：运行时进度（不再镜像状态表，只记录会话与「不要重复做」）

---

基本原则

• 只执行 docs/agent-progress.md 中「当前批次」对应的任务。


• 按 docs/agent-plan.md 中的卡片顺序执行。


• 不要重新设计方案，不要提出替代方案。


• 不要重构无关代码。


• 不要改变接口、数据结构和现有业务逻辑。


• 不要删除现有功能。


• 不要引入第三方依赖，除非卡片明确要求。


• 如果代码结构与卡片描述不一致，做最小侵入式适配；适配范围超出卡片描述时标记 BLOCKED。


• 卡片状态以 docs/agent-plan.md 为权威源，docs/agent-progress.md 中不重复维护状态表。

---

启动协议

每次会话开始前必须按顺序完成：

1. 完整读取 docs/agent-rules.md、docs/agent-plan.md、docs/agent-progress.md。


2. 读取 docs/agent-progress.md 中「不要重复做」清单，避免在本轮重复已知失败或无效的尝试。


3. 以 docs/agent-progress.md 中「当前批次」为本轮范围，输出本轮将执行的卡片列表，再开始执行。


4. 在 docs/agent-progress.md 的「会话历史」末尾追加一个新的 ### 会话 YYYY-MM-DD HH:mm 块，本轮所有运行时记录写入该块；不修改历史会话块。

---

批次推进协议

• 当「当前批次」的所有卡片状态都为 DONE（或 BLOCKED 已被用户确认）时：
  
  
  
  1. 将 docs/agent-progress.md 中「当前批次」的值 +1；
  
  
  2. 在当前会话块中输出推进确认信息；
  
  
  3. 停止执行，等待用户决定是否继续下一批次；
  
  
  4. 不要自动开始下一批次的卡片。
  
  
  
  

---

卡片状态

每张卡片只能使用以下状态之一：

• TODO：未开始


• IN_PROGRESS：正在执行


• DONE：已完成


• BLOCKED：无法安全继续

---

卡片字段规范

每张卡片必须包含以下字段，缺字段视为卡片不合格，标记 BLOCKED 并提示用户补全。

头部（机读元数据）：

• 批次：数字


• 状态：TODO / IN_PROGRESS / DONE / BLOCKED


• 依赖：其他卡片 ID 或「无」


• 自检：可执行命令、「手动：…」描述，或「无」

正文（5 字段强制结构）：

• 问题定位：为什么要做、当前痛点


• 实施方案：具体步骤


• 涉及位置：会改动的文件/组件/接口


• 风险：可能的副作用、需要规避的情况


• 验收标准：可逐条勾选的 checkbox 列表

运行时：

• 执行记录：Agent 完成后填写（时间、实际改动文件、自检结果、风险回应）

---

每张卡片的执行流程

1. 阅读卡片所有字段，特别注意「风险」与「依赖」。


2. 在 docs/agent-plan.md 中将卡片状态改为 IN_PROGRESS。


3. 在「涉及位置」范围内做最小改动；超出该范围立即停止并标记 BLOCKED。


4. 执行卡片「自检」命令；填写为「无」时跳过自动校验，按验收标准做人工核对。


5. 通过验收后将卡片状态改为 DONE；未通过且无法在最小范围修复时改为 BLOCKED。


6. 在卡片「执行记录」中填写：时间、实际改动文件、自检结果、风险回应（已规避 / 已发生 / 不适用）。


7. 在当前会话块中追加该卡片的完成摘要。

---

自检定义

• 「自检」字段是该卡片唯一的自动化校验入口。


• 自检命令失败时，不要通过修改无关代码绕过；先尝试在「涉及位置」范围内修复，仍失败则标记 BLOCKED。


• 「自检」为「无」或「手动：…」时，必须在执行记录中描述人工验证步骤与结果。

---

停止条件

遇到以下任一情况立即停止并输出说明：

• 「当前批次」所有卡片完成（触发批次推进协议）；


• 卡片自检失败且无法在最小范围内修复；


• 需要修改接口、数据结构或核心业务逻辑，但卡片未明确要求；


• 卡片字段不合格、依赖卡片未完成、或「涉及位置」不存在。

---

输出要求

每次会话结束时必须输出：

• 本次完成 / BLOCKED 的卡片 ID；


• 实际修改的文件列表；


• 自检命令及结果（含手动验证摘要）；


• 阻塞原因（若有）；


• 下一步建议：继续下一张 TODO 卡片 / 触发批次推进 / 等待用户决策。

agent-progress（用于规范操作流程）

Agent 执行进度

本文件记录 Agent 运行时状态，用于多轮任务续接。

• 卡片状态以 docs/agent-plan.md 为权威源，本文件不再镜像状态表。


• 本文件维护三件事：当前批次指针、不要重复做清单、会话历史。

---

当前批次

1

当前批次的所有卡片 DONE 后，由 Agent 按「批次推进协议」将此值 +1，并停止等待用户确认。

---

不要重复做

Agent 启动时必读。记录已知失败、无效或被用户否决的尝试，避免在新会话中重复。

每条用一行简述，必要时附会话日期。

• 空。

---

会话历史

每次会话开始时，Agent 在本节末尾追加一个新的 ### 会话 YYYY-MM-DD HH:mm 块。

历史会话块只读，不修改。

会话模板（复制使用，不要修改本块）

### 会话 YYYY-MM-DD HH:mm



- 本轮范围：批次 N，卡片 X1 / X2

- 完成：

  - X1：DONE

  - X2：BLOCKED（原因：...）

- 修改文件：

  - path/to/a

  - path/to/b

- 自检：

  - X1：命令或手动步骤 → 结果

  - X2：...

- 风险回应：

  - X1：已规避 / 已发生 / 不适用

- 阻塞与待决：

  - （若有）

- 下一步：

  - 继续 X3 / 触发批次推进 / 等待用户决策

---

agent-plan(用于存放卡片)

Agent 任务计划

本文件是任务卡片清单，卡片状态以本文件为权威源。

• 
  

  执行规则见：docs/agent-rules.md

  
  


• 
  

  运行时进度见：docs/agent-progress.md

  
  

卡片字段规范见 docs/agent-rules.md 中「卡片字段规范」一节。

agent-card-template(用于生成卡片)

卡片生成指令

用途：让 AI 帮你写一张新的任务卡片时，复制下方 ===== 模板 ===== 之间的内容贴在需求前面，AI 会按规范输出可直接粘贴进 docs/agent-plan.md 的卡片。

字段规范的权威定义见 docs/agent-rules.md 中「卡片字段规范」一节。本模板与之保持一致。

---

使用步骤

1. 复制下方 ===== 模板 ===== 之间的全部内容。


2. 贴在你描述需求的消息开头，紧接着写出你的需求。


3. AI 输出卡片后，你只需确认两项：
   
   
   
   • 批次：数字由你定（AI 不知道你的批次排期）。
   
   
   • 依赖：如果 AI 标注了「待我确认 ID」，对照 docs/agent-plan.md 把 ID 补准或改为「无」。
   
   
   
   


4. 把卡片粘贴到 docs/agent-plan.md 末尾，用 --- 与上一张卡片分隔。


5. 当前阶段请先完成：
   
   
   
   1. 扫描项目结构；
   
   
   2. 找到主要入口文件、核心页面、状态管理、请求封装、渲染函数；
   
   
   
   

---

===== 模板 =====

请按以下格式输出任务卡片，所有字段必填，不要省略，不要解释，直接输出 Markdown：

## <ID> <标题>



- 批次：<数字；不确定时填「待确认」>

- 状态：TODO

- 依赖：<其他卡片 ID 列表 或「无」；如果你从需求中识别出语义依赖，列出来并标注「待我确认 ID」>

- 自检：<可执行命令 / 「手动：……」一句话 / 「无」；优先从验收标准中归纳出最小验证步骤>



### 问题定位

<为什么要做、当前痛点；尽量引用具体 文件:行号>



### 实施方案

<分步骤，每步可独立验证；不要重新设计，不要提替代方案>



### 涉及位置

<具体 文件:行号；区分「会改」与「只读引用」；明确不会改动的范围>



### 风险

<可能的副作用、要规避的情况、被打断的边界场景；列出对策>



### 验收标准

<可逐条勾选的 checkbox 列表；覆盖正常路径 + 异常路径 + 持久化 + 边界场景>



### 执行记录

（Agent 填写：完成时间 / 实际改动文件 / 自检结果 / 风险回应）

约束：

• 不要新增字段，不要删除字段。


• 不要在字段里写「TODO 待补」「视情况而定」之类的占位话术；信息不足时写「无」或直接问我。


• 「实施方案」和「涉及位置」必须引用具体文件路径，不接受「项目主文件」「相关组件」这类泛指。


• 「验收标准」每条必须是可观察的行为，不接受「代码质量好」「性能提升」这类不可验证的描述。

===== 模板结束 =====

---

卡片示例（最小完整版）

## A1 首屏加载反馈演示



- 批次：1

- 状态：TODO

- 依赖：无

- 自检：手动：浏览器打开 `index.html`，刷新页面观察加载反馈



### 问题定位

演示页面在数据加载期间无任何视觉反馈，用户会误以为页面卡死。



### 实施方案

1. 在 `index.html` 中定位数据加载相关代码段。

2. 请求开始时显示 loading 提示，结束（成功或失败）后隐藏。

3. 优先复用页面中已有的提示元素。



### 涉及位置

- `index.html`（前端单文件，定位数据加载相关脚本块）。

- 不修改 `server.js` 与数据库相关代码。



### 风险

- 不要把 loading 状态做成全局变量。

- 不要改变现有 fetch 接口和返回数据结构。

- 不要引入第三方 loading 库。



### 验收标准

- [ ] 触发数据加载时可见反馈；

- [ ] 加载完成后反馈消失；

- [ ] 加载失败时反馈也能正确退出；

- [ ] 未改动接口签名和返回数据结构。



### 执行记录

（Agent 填写：完成时间 / 实际改动文件 / 自检结果 / 风险回应）

至此，完成了所有文档准备，我们只需要将卡片完成，就可以用goal命令愉快的摸鱼了！！！

欢迎各位愿意尝试的佬欢迎提出优化建议和问题。