CodeWave IDE

Appearance

功能规格说明：任务后台执行与管理 ​

创建日期：2026-02-09

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

用户故事：后台任务执行（优先级：P1） ​

作为用户，我希望能够在后台运行复杂或长时间运行的任务，以便在任务处理期间继续与 agent 交互。

为什么是这个优先级：这是实现非阻塞工作流的核心功能，对于处理耗时操作时的生产力至关重要。

独立测试：可以通过使用 run_in_background: true 启动任务并验证 agent 立即返回控制权并附带任务 ID，同时任务继续运行来进行测试。

验收场景：

  1. 假设有一个需要大量时间的任务，当我使用 run_in_background: true 执行它时，则我应立即收到唯一的任务 ID 和实时输出日志文件的路径，agent 应准备好接受下一个命令。
  2. 假设后台任务正在运行，当我检查系统状态时，则我应看到该任务被列为活动状态。
  3. 假设后台任务正在运行，当我读取提供的日志文件路径时，则我应看到任务的实时输出。

用户故事：任务输出获取（优先级：P1） ​

作为用户，我希望能够获取后台任务的输出（无论是在运行中还是完成后），以便查看我所请求操作的结果。

为什么是这个优先级：如果无法检查结果，后台任务就毫无用处。这提供了对后台操作的必要可见性。通过日志文件进行实时监控提供了更好的长时间运行任务体验。

独立测试：可以通过使用 Read 工具读取任务启动时提供的 outputPath 来进行测试。

验收场景：

  1. 假设后台任务已启动，当我使用 Read 工具访问 outputPath 文件时，则我应看到到目前为止生成的输出。
  2. 假设后台任务正在运行，当我读取提供的日志文件路径时，则我应看到任务的实时输出。

用户故事：任务终止（优先级：P2） ​

作为用户，我希望能够停止正在运行的后台任务，如果我意识到它不再需要或行为异常。

为什么是这个优先级：提供对系统资源的控制，并允许用户取消错误或失控的操作。

独立测试：可以通过对正在运行的任务使用 TaskStop 工具并验证任务被终止且其状态更新为已停止/已取消来进行测试。

验收场景：

  1. 假设有一个正在运行的后台任务，当我使用 TaskStop 并传入任务 ID 时，则任务应立即终止，我应收到确认信息。

用户故事：任务管理命令（优先级：P2） ​

作为用户，我希望在 CLI 中使用 /tasks 命令来列出和管理所有后台任务，以便有一个集中的地方来监控进度。

为什么是这个优先级：提供用户友好的任务管理界面，无需记住特定的任务 ID 或直接使用底层工具。

独立测试：可以在 CLI 中运行 /tasks 并验证它显示当前和最近任务的列表及其状态。

验收场景：

  1. 假设已启动了多个后台任务，当我运行 /tasks 时，则我应看到一个格式化列表，显示每个任务的任务 ID、类型、状态和启动时间。
  2. 假设遗留的 /bashes 命令曾经存在，当我尝试使用它时，则它应被移除或重定向到 /tasks 并附带弃用通知。

用户故事：前台工具后台化（优先级：P1） ​

作为在后台运行长时间 bash 命令或子 agent 任务的用户，我希望能够使用 Ctrl-B 将其移到后台，以便在不等待完成的情况下继续使用 CLI 处理其他任务。

为什么是这个优先级：这在最初在前台启动的长时间操作期间通过解除用户阻塞来提供即时价值。

独立测试：可以通过运行一个长 bash 命令（例如 sleep 60）、按 Ctrl-B 并验证 CLI 返回提示符而命令在后台继续运行来进行测试。

验收场景：

  1. 假设bash 或任务工具在前台运行，当用户看到提示 [Ctrl-B] Background 并按 Ctrl-B 时，则工具的前台执行结束，任务在后台继续运行。
  2. 假设工具已通过 Ctrl-B 后台化，当用户通过 /tasks 检查任务状态时，则该工具应作为后台任务可见。

用户故事：任务完成通知（优先级：P1） ​

作为用户，我希望在后台任务完成、失败或被终止时在聊天中自动收到通知，这样我不必手动检查就能知道结果。

为什么是这个优先级：如果没有自动通知，用户必须轮询任务状态或记得检查输出，这就违背了后台执行的目的。

独立测试：启动一个后台任务，等待其完成，并验证聊天中出现通知，显示任务状态和摘要。

验收场景：

  1. 假设后台任务正在运行，当任务成功完成时，则聊天中应出现带有绿色指示器和摘要消息的通知。
  2. 假设后台任务正在运行，当任务失败时，则聊天中应出现带有红色指示器和错误摘要的通知。
  3. 假设后台任务正在运行，当任务被用户终止时，则聊天中应出现带有黄色指示器和摘要的通知。
  4. 假设多个后台任务在 agent 空闲时完成，则所有通知应出现在聊天中。
  5. 假设后台任务在 agent 活跃响应时完成，则通知应被排队并在当前响应完成后显示。
  6. 假设队列中已有待处理用户消息，当后台任务通知同时入队时，则系统必须串行处理二者，不会并发触发两个 AI turn，不会出现两个并行的响应 stream。
  7. 假设主 Agent 并发启动 N（N≥3）个后台 subagent 并等待全部完成通知，当所有 subagent 完成时，则主 Agent 必须收到恰好 N 条完成通知（每个 taskId 恰好一次），且任何通知不得出现在兄弟 subagent 的会话 transcript 中、不得因此重新唤起兄弟 subagent 额外执行一轮。
  8. 假设并发后台 subagent 完成通知入队期间，当某个兄弟 subagent 的 AIManager 回合结束时，则该 subagent 不得从主 Agent 的 MessageQueue 排空（drainNotifications）任何通知；subagent 的通知排空只能作用于其自身容器的独立队列。
  9. 假设主 Agent 在 print 模式（wave -p）下等待后台 subagent 完成，当最后一个 subagent 完成且其通知已被主 Agent 消费、生成最终响应后，则print 模式才允许退出（exit 0）；不得因通知被错误消费者取走导致 hasPendingMessages/hasRunningBackgroundWork/isLoading 提前为假而提前退出。

用户故事：IDE 插件后台任务管理对话框（优先级：P2） ​

作为 IDE 插件（VS Code 扩展与 JetBrains 插件）用户，我希望能在 IDE 中通过 /tasks 命令弹出对话框查看和管理后台任务（shell / 子 agent / 工作流），与 CLI 的 /tasks 弹窗体验一致，以便集中监控后台运行的长时间任务、查看输出、必要时终止任务。

为什么是这个优先级：IDE 插件以 stdio 子进程方式运行 Agent，目前 AgentCallbacks.onBackgroundTasksChange 回调未通过 stdio 协议转发，IDE 完全无法感知后台任务（run_in_background、超时自动后台化的任务）。后台任务的结果当前仅在 CLI 可见；IDE 用户无法查看或管理这些任务，与 CLI 体验不一致。

独立测试：在 IDE 插件中输入 /tasks，验证弹出对话框列出后台任务（id、类型、状态、描述、运行时长）；选择某任务查看详情输出；点停止按钮终止运行中任务；任务状态变化时列表实时刷新。

验收场景：

  1. 假设有后台任务运行，当用户在 IDE 输入 /tasks 时，则弹出对话框列出所有后台任务（运行中/已完成/失败/已终止），每项显示 id、类型、状态、描述/命令、运行时长
  2. 假设用户在列表中选择某任务，当进入详情视图时，则显示该任务的 stdout/stderr 输出（末尾若干行）、退出码、日志文件路径
  3. 假设某任务正在运行，当用户点击停止按钮时，则任务被终止，列表中该任务状态更新为已终止
  4. 假设后台任务状态变化（启动/完成/失败/终止），当子进程发送 backgroundTasksChange 通知时，则对话框实时刷新列表
  5. 假设无后台任务，当用户输入 /tasks 时，则对话框显示空状态提示
  6. 假设IDE 与 CLI 行为需一致，则二者任务列表数据模型一致（基于同一 BackgroundTask 类型）
  7. 假设所选任务仍在运行，当其输出持续产生时，则详情视图周期性自动刷新并展示最新输出（运行中的 agent 任务其 stdout 在终态前为空，此时取该任务日志文件尾部的实时内容）；当任务进入终态时，则停止自动刷新并显示终态输出快照

边界情况 ​

  • 无效任务 ID：系统如何处理带有不存在 ID 的 TaskOutput 或 TaskStop 请求？（预期：显示任务未找到的错误消息）。
  • 任务已完成：当 TaskStop 被调用在已完成的任务上时会发生什么？（预期：显示任务已完成的提示消息）。
  • 输出获取超时：当 block: true 时，TaskOutput 如何处理超过指定超时的任务？（预期：返回日志文件的最后几行，并附带仍在运行的状态指示）。
  • 并发访问：来自同一后台任务的多个输出请求。
  • 任务日志文件不可读：运行中的任务其 outputPath 文件缺失或读取失败时如何处理？（预期：回退到内存中的 stdout/stderr，不向用户报错）。
  • 没有工具运行时按 Ctrl-B：系统应忽略该按键。
  • 直接用户 bash 命令（!command）：用户使用 ! 前缀直接启动的命令不得受 Ctrl-B 影响。
  • 超时自动后台化：当前台 Bash 命令超时时，进程被自动后台化而不是被终止（除非命令以 sleep 开头）。这保留了只需要更多时间的长时间运行工作。
  • 后台任务无超时：显式后台化的任务（run_in_background: true）忽略默认和显式超时，运行直到完成或手动停止。
  • 并发后台 subagent 通知错误路由：当多个后台 subagent 并发完成时，若 subagent 容器未持有独立 MessageQueue，其 AIManager 回合末会经由 Container.get() 的 parent 回退抽干主 Agent 队列，将兄弟任务完成通知注入自身会话并重新唤起自身回合（shouldRestart），同时主 Agent 因收不到该通知而提前退出。修复要求每个 subagent 容器注册独立 MessageQueue，且完成通知仅投递并消费于主 Agent 队列。