---
url: /wave-agent/specs/multi-agent/plan-subagent.md
description: 内置 Plan 子代理，只读探索代码库，输出多视角实现方案与关键文件
---

# 功能规格说明：Plan 子 Agent 支持

**创建日期**：2026-02-12

## 用户场景与测试 *（必填）*

### 用户故事：使用内置 Plan 子 agent 的计划模式（优先级：P1）

当用户进入计划模式时，他们可以生成内置的 Plan 子 agent 来探索代码库并设计实现方案。Plan 子 agent 充当软件架构师，基于彻底的代码探索提供详细的实现计划。

**为什么是这个优先级**：核心功能，通过提供专门设计实现策略而不做任何代码更改的 agent 来启用计划模式工作流。

**独立测试**：可以通过进入计划模式、生成带有需求的 Plan 子 agent，并验证子 agent 探索代码库并返回详细实现计划而不修改任何文件来进行完整测试。

**验收场景**：

1. **假设**用户处于计划模式，**当**用户生成带有实现需求的 Plan 子 agent 时，**则**子 agent 探索相关代码并返回包含关键文件识别的详细计划
2. **假设** Plan 子 agent 正在探索代码库，**当**子 agent 尝试编辑或创建文件时，**则**操作被阻止并返回错误
3. **假设**生成了多个具有不同视角的 Plan 子 agent，**当**它们完成工作时，**则**每个都基于其分配的视角（例如，简洁性 vs 性能）返回计划

***

### 用户故事：只读工具限制（优先级：P1）

Plan 子 agent 严格限制为只读操作，确保它们可以探索和分析代码但不能在计划阶段进行任何修改。

**为什么是这个优先级**：对于维护计划模式的完整性至关重要，防止在设计阶段意外更改代码。

**独立测试**：可以通过尝试各种文件修改操作（Write、Edit、有副作用的 Bash 命令）并验证全部被阻止来进行测试。

**验收场景**：

1. **假设** Plan 子 agent 正在运行，**当**子 agent 尝试使用 Write 工具时，**则**工具不可用且操作失败
2. **假设** Plan 子 agent 正在运行，**当**子 agent 尝试使用 Edit 工具时，**则**工具不可用且操作失败
3. **假设** Plan 子 agent 正在运行，**当**子 agent 尝试 bash 命令如 mkdir、touch 或 rm 时，**则**系统提供清晰的指导，说明只允许只读 bash 操作

***

### 用户故事：工具面按黑名单收敛并跳过项目记忆（优先级：P2）

作为用户，我希望 Plan 和 Claude Code 的 Plan 子代理一样：除了「会改文件」的那几个工具之外都能用（`WebFetch`、`WebSearch`、`Skill`、`LSP`…），并且不必携带主会话的 `AGENTS.md` 才能做只读研究。

**为什么是这个优先级**：白名单只能加不能减——新工具（如网页抓取）永远进不了 Plan 的工具池，而规划常常需要读在线文档；项目记忆对一次性的只读研究是纯粹的成本。

**独立测试**：派一个需要读网页的规划任务，验证 Plan 能调用 `WebFetch` 拿到内容；同时验证它的首条消息里没有 `AGENTS.md`、工具列表里没有 `Write`/`Edit`。

**验收场景**：

1. **假设** Plan 子代理启动，**当** 模型看到工具列表，**则** 采用黑名单式限制（`Agent`、`Artifact`、`ExitPlanMode`、`Edit`、`Write` 以及恒定拒绝的 Task 工具不可用），`WebFetch`/`WebSearch`/`Skill`/`LSP`/`Bash` 均可用。
2. **假设** Plan 子代理启动，**当** 它发出第一次请求，**则** 不注入项目 `AGENTS.md` 与 `.wave/rules` 的无条件规则（定义文件带 `omitAgentsMd: true`）。
3. **假设** 用户自定义了同名 `Plan` 子代理，**当** 它被派发，**则** 遵守用户自己的定义（白名单/黑名单与 `omitAgentsMd` 都以用户文件为准），内置行为不覆盖用户文件。

***

### 用户故事：多规划视角（优先级：P2）

用户可以生成多个具有不同视角的 Plan 子 agent，为复杂任务探索各种实现方案。

**为什么是这个优先级**：通过考虑多种架构方案和权衡来实现对复杂问题的彻底分析。

**独立测试**：可以通过生成多个具有不同视角提示的 Plan 子 agent，并验证每个都基于其分配的重点生成不同的计划来进行测试。

**验收场景**：

1. **假设**有一个复杂的重构任务，**当**用户生成具有"简洁性"和"性能"视角的 Plan 子 agent 时，**则**每个子 agent 生成与其分配视角一致的计划
2. **假设**多个 Plan 子 agent 正在运行，**当**它们探索同一代码库时，**则**它们的探索互不干扰

***

### 用户故事：关键文件识别（优先级：P2）

Plan 子 agent 识别并列出实现其提议计划最关键的 3-5 个文件，帮助用户理解将在何处进行更改。

**为什么是这个优先级**：为实现阶段提供清晰指导，并帮助用户评估提议更改的范围和影响。

**独立测试**：可以通过验证 Plan 子 agent 输出包含"Critical Files for Implementation"部分及文件路径和简要说明来进行测试。

**验收场景**：

1. **假设** Plan 子 agent 完成探索，**当**它生成计划时，**则**输出包含 3-5 个关键文件及其路径和原因
2. **假设**关键文件已被识别，**当**用户审查计划时，**则**文件路径准确且原因解释了其重要性

***

### 边界情况

* 当 Plan 子 agent 遇到因权限无法读取的文件时会发生什么？
* Plan 子 agent 如何处理非常大的代码库（探索可能耗时）？
* 当 Plan 子 agent 引用的文件在计划期间被移动或删除时会发生什么？
* 系统如何处理多个 Plan 子 agent 同时尝试探索相同文件？
* 当 Plan 子 agent 系统提示太大超出 token 限制时会发生什么？