CodeWave IDE

Appearance

功能规格说明：子代理支持 ​

创建日期：2024-12-19

用户场景与测试 （必填） ​

用户故事：加载和解析用户创建的子代理（优先级：P1） ​

作为开发者，我希望 Wave Agent SDK 自动发现和加载我手动创建的子代理配置文件，以便我可以使用具有领域专业知识和适当工具访问权限的专门 AI 助手。

为什么是这个优先级：这是子代理系统的基础 - SDK 必须能够在任何委托发生之前发现、加载和解析用户创建的子代理配置。SDK 专注于读取能力，而用户通过首选编辑器管理创建。

独立测试：可以通过在正确位置手动创建带有有效 YAML frontmatter 的子代理配置文件并验证它可以被 SDK 发现、加载和解析来完整测试。

验收场景：

  1. 假设 我在 .wave/agents/ 中手动创建了带有有效 YAML frontmatter 的 markdown 文件，当 SDK 扫描子代理，则 子代理被发现并可用于使用
  2. 假设 我在 ~/.wave/agents/ 中有一个用户级子代理，当 SDK 加载配置，则 该子代理在所有项目中可用
  3. 假设 我有同名的项目和用户子代理，当 SDK 加载配置，则 项目级子代理优先
  4. 假设 我手动配置了带有特定工具的子代理，当 子代理被调用，则 它只能访问这些指定的工具
  5. 假设 我手动配置了带有特定模型的子代理，当 子代理被调用，则 它使用指定模型进行响应
  6. 假设 子代理的 frontmatter 用 YAML 块标量写多行值（>／>-／|／|- 等），当 SDK 加载配置，则 description／model 等字段必须是折叠／保留后的真实文本（不含 >、|、- 这类指示符），续行不得被解析成独立的 frontmatter 键；子代理列表与自动委托判据看到的描述都是解析后的结果

用户故事：自动任务委托（优先级：P2） ​

作为用户，我希望 Wave Agent 自动识别任务何时匹配子代理的专业领域并适当委托，这样我无需手动指定使用哪个子代理就能获得专业帮助。

为什么是这个优先级：这提供了使子代理真正有用的智能自动化 - 用户不必为每个任务手动管理使用哪个子代理。

独立测试：可以通过为子代理配置清晰的专业描述并发出匹配这些描述的任务，然后验证自动委托发生来测试。

验收场景：

  1. 假设 我配置了 test-runner 子代理，当 我要求"修复失败的测试"，则 任务自动委托给 test-runner 子代理
  2. 假设 我有多个具有不同专业领域的子代理，当 我描述一个任务，则 根据任务描述和子代理描述选择最合适的子代理
  3. 假设 我有一个描述中包含 "PROACTIVELY" 的子代理，当 提到任何相关任务，则 系统优先委托给该子代理
  4. 假设 没有子代理匹配我的任务描述，当 我请求帮助，则 主代理直接处理任务

用户故事：显式子代理调用（优先级：P3） ​

作为用户，我希望为任务显式请求特定子代理，以便在需要时完全控制哪个专业代理处理我的请求。

为什么是这个优先级：虽然自动委托很方便，但用户有时需要直接控制使用哪个子代理，特别是对于复杂场景或当他们知道特定子代理最适合时。

独立测试：可以通过在请求中按名称提及特定子代理并验证命名的子代理处理任务来测试。

验收场景：

  1. 假设 我有多个已配置的子代理，当 我说"使用 code-reviewer 子代理查看我的更改"，则 code-reviewer 子代理专门处理请求
  2. 假设 我提及了一个不存在的子代理，当 我发出请求，则 我收到列出可用子代理的错误消息
  3. 假设 我显式调用了子代理，当 任务完成，则 我可以在响应中看到哪个子代理处理了请求

用户故事：子代理上下文隔离（优先级：P2） ​

作为用户，我希望每个子代理维护与主对话分离的独立上下文窗口，以便专业代理可以专注于其特定任务而不受不相关对话历史的影响。

为什么是这个优先级：上下文隔离对子代理的有效性至关重要 - 它防止子代理被不相关的对话历史混淆，并允许它们保持对专业领域的专注。

独立测试：可以通过进行长对话，然后委托给子代理并验证它不引用不相关的先前对话元素来测试。

验收场景：

  1. 假设 我与主代理有长对话，当 我将任务委托给子代理，则 子代理仅使用其任务的相关上下文运行
  2. 假设 我按顺序使用多个子代理，当 每个子代理运行，则 它们不互相干扰上下文
  3. 假设 子代理完成任务，当 控制权返回主代理，则 主代理可以访问子代理的结果但维护自己的上下文

用户故事：子代理活动显示（优先级：P2） ​

作为用户，我希望在主对话流中看到子代理活动的反映，以便我无需单独的消息历史视图就能追踪它们的进度。

为什么是这个优先级：清晰的子代理活动反馈对用户理解和调试至关重要。用户需要实时了解子代理正在运行什么工具。

独立测试：可以通过触发子代理并验证 Agent 工具块的 short result 动态更新工具名称和 token 使用情况来测试。

验收场景：

  1. 假设 子代理被触发，当 它处理任务，则 Agent 工具块在其 shortResult 中显示实时更新
  2. 假设 子代理正在运行工具，当 我查看消息列表，则 我在 Agent 工具块的 shortResult 中看到最近执行的子代理工具
  3. 假设 子代理任务完成，当 任务结束，则 最终文本结果作为工具输出返回并显示在主对话中
  4. 假设 子代理任务完成，当 我查看工具块，则 我看到任务完成摘要，包括使用的总 token 和执行的工具

边界情况 ​

  • 子代理配置文件的 YAML frontmatter 无效时会怎样？
  • 系统如何处理循环委托（子代理尝试委托回主代理或另一个子代理）？
  • 子代理配置了不存在的工具时会怎样？
  • 当项目和用户目录都包含同名代理时系统如何表现？
  • 子代理指定的模型不可用或无效时会怎样？
  • 系统如何处理存在但没有内容或缺少必需字段的子代理文件？
  • 用户请求的子代理存在但缺少访问所需工具的权限时会怎样？
  • 子代理尝试访问 Task 管理工具（TaskCreate/TaskGet/TaskUpdate/TaskList）时会怎样？→ 系统必须拒绝：这些工具不注册到子代理的 ToolManager，子代理无法调用，防止其修改主代理的共享任务列表。

子代理生命周期（2025-01-10 添加） ​

此功能为子代理提供细粒度消息回调并确保严格的生命周期管理。

关键变更 ​

  1. SubagentManagerCallbacks 接口：子代理事件的新接口：

    • onSubagentUserMessageAdded
    • onSubagentAssistantMessageAdded
    • onSubagentAssistantContentUpdated
    • onSubagentToolBlockUpdated
    • onSubagentMessagesChange

  2. 重构的 SubagentManager：

    • 使用 callbacks: SubagentManagerCallbacks 转发事件
    • 通过 cleanupInstance(subagentId) 确保子代理实例清理

  3. 移除持久子代理 UI 状态：

    • SubagentBlock 组件及其关联的 subagentMessages 上下文状态从 CLI 中移除
    • 活动现在通过 Agent 工具块的 shortResult 报告

澄清 ​

2024-12-19 会议 ​

  • 问：子代理触发时，子代理消息块是否应在主对话流中内联显示？ → 答：否，它在主对话流中表示为 Agent 工具块
  • 问：当子代理产生错误或未能完成任务时系统应如何处理任务委托？ → 答：返回错误消息给主代理。子代理是工具调用，因此可以返回成功内容或错误消息
  • 问：区分子代理活动的视觉指示器应该是什么？ → 答：Agent 工具块的 shortResult 动态更新工具执行和 token 使用信息
  • 问：Wave Agent SDK 是否应提供创建子代理配置文件的功能？ → 答：否，SDK 仅读取/加载/解析用户创建的子代理文件