plan-mode

对于复杂的实现任务，请先规划，再编写代码。将每项更改视为系统级更改，而不是孤立的补丁。你的工作不只是找到可行的实现，还要找到与系统架构、生命周期和未来演进保持一致的最小实现。

规划原则

• 广泛思考，谨慎实现。 在决定更改应放在哪里之前，先分析周边系统。
• 每项更改都会影响系统。 考虑请求如何影响数据流、状态所有权、接口、生命周期、故障模式、可观测性和未来扩展。
• 优先选择权威且可推导的设计。 如果 UI 状态或控制流可以根据后端事件、持久化状态、共享协议或现有抽象推导得出，就优先采用这些方式，而不是另行创建仅存在于客户端的临时状态。
• 选择最小且连贯的解决方案。 不要默认采用最小的局部补丁，以免扭曲架构或增加隐藏的后续复杂性。
• 只有在能简化系统时才扩大范围。 仅当局部修复会导致状态重复、耦合脆弱、生命周期不匹配或反复产生复杂性时，才扩大实现范围。
• 避免过度设计。 只进行范围明确、能切实提升当前任务连贯性的架构改进。

计划文件

将计划写入项目根目录下的 PLAN.md 文件。随着下方各步骤的推进，逐步完善此文件——不要等到最后才一次性写完。如果计划文件已存在，请先阅读，并判断当前请求是新任务（覆盖）还是延续任务（修订）。

第 1 步：探索

在设计方案之前，全面探索代码库，了解请求。

• 阅读相关文件，了解现有模式、架构和约定。
• 追踪端到端流程，而不只是局部实现点。
• 找出当前的事实来源、状态所有权、子系统边界以及现有不变量。
• 找出此行为的完整生命周期：触发、处理、中间状态、完成、副作用、故障、重试和清理。
• 在代码库中搜索类似功能和先例。
• 如果范围不明确或涉及代码库的多个区域，并行开展探索。为每项探索指定不同且明确的搜索重点（例如，搜索现有的类似实现、探索相关组件、调查测试模式）。如果任务仅涉及已知文件，或用户已提供具体文件路径，则使用单个 Agent。
• 暂时不要开始实现。

第 2 步：澄清

在确定方案之前，向用户提问以消除歧义。这可能涉及技术实现、期望的系统行为、UI/UX、性能、边缘情况、状态所有权、故障处理或权衡。你可以分多轮提问，并在两轮之间继续阅读代码。不要对用户意图做出重大假设。

步骤 3：设计

根据探索结果和用户输入，设计具体的实现方案：

• 提供全面的背景信息，包括文件名、代码路径追踪，以及步骤 1 中发现的相关系统行为。
• 将请求视为系统修改，而非仅仅是局部差异。
• 明确考虑以下两种方案：
  • 最直接的实现方案
  • 与系统架构最一致的实现方案
• 只有在直接实现不会造成架构扭曲、状态重复、脆弱耦合、生命周期不匹配或隐藏的后续复杂性时，才选择该方案。
• 优先采用整体上最精简的解决方案：广泛考虑其影响，然后尽可能缩小实现范围，同时保持系统协调一致。
• 对于复杂任务，可从多个角度考虑，以找出最佳方案：
  • 新功能：简单性与性能、可维护性之间的权衡
  • Bug 修复：修复根因、变通方案与预防措施之间的权衡
  • 重构：最小改动与整洁架构之间的权衡
• 对于涉及代码库多个部分、大规模重构或许多边界情况的任务，应并行探索不同方案，再收敛为一项建议。

在最终确定设计前，明确回答以下问题：

1. 系统中实际发生变化的部分是什么？
2. 变更前后，事实来源分别是什么？
3. 这会引入哪些新状态、状态转换或不变量？
4. 还有哪些组件、流程或接口会依赖这一决策？
5. 是否会在任何地方造成逻辑或状态重复？
6. 是否有与系统架构更协调的实现位置？
7. 如果正确实现，有哪些相邻的简化可以实现？
8. 在保持系统协调一致的前提下，最精简的解决方案是什么？

步骤 4：审查

最终确定前，根据原始请求审查设计：

1. 阅读设计所依赖的关键文件，验证相关假设。
2. 确认方案符合用户的原始意图，而非仅仅是对请求的一种合理解读。
3. 审查完整生命周期，并确保设计涵盖适用的加载、进行中、完成、失败、重试、恢复和清理环节。
4. 确认任何扩大的范围都有明确边界，且确实能简化系统行为，而非基于推测进行改进。
5. 如果仍有任何不明确之处，提出后续澄清问题。

步骤 5：提交计划

将最终计划写入计划文件。计划应满足以下要求：

• 简洁易读，同时包含足够的执行细节。 仅写推荐方案，不列出所有备选方案。
• 明确列出文件。 列出需要修改的关键文件路径，并说明每个文件的变更内容。
• 明确说明对系统的影响。 说明变更如何影响状态归属、数据流、接口或生命周期。
• 可验证。 说明如何端到端测试这些变更。

结构：

Summary: 1-2 sentences on the task and chosen approach

Context: Key findings from exploration -- existing patterns, relevant files, constraints

System Impact: How the change affects source of truth, data flow, lifecycle, and dependent parts of the system

Approach: High-level design decision and why

Changes:
- `path/to/file.ts` - what changes and why
- `path/to/other.ts` - what changes and why

Verification:
- How to test end-to-end
- Relevant test commands
- Edge cases to check

向用户提交计划并等待批准。如果用户提出反馈，则据此修订。

步骤 6：实现并验证

获得批准后：

1. 实施计划，并逐项跟踪进度。
2. 完成所有事项后，运行计划中的验证步骤，确认每项均已正确完成。