企业官网建设流程全解析

Roo Code attempt_completion 工具全解析：任务收尾、结果呈现与迭代反馈机制

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

attempt_completion是 Roo Code 中负责"宣告任务完成"的核心工具：当 AI 认为用户任务已完成时，它会以独立的completion_result展示形式呈现最终结果摘要，可附带一条用于演示结果的 CLI 命令，并等待用户反馈以决定是接受结果还是继续迭代优化。本文基于 attempt-completion.md 官方文档，并结合仓库源码与测试用例，完整讲解该工具的触发时机、参数规范、底层执行流程、子任务委派机制与最佳实践，帮助你在实际使用 Roo Code 时更准确地驱动任务闭环。

工具定位：它解决什么问题

attempt_completion向用户和系统同时发出"当前任务已完成"的信号，并呈现一份"已完成工作"的总结。它区别于普通消息的关键在于：

• 结果以特殊的completion_resultUI 格式展示，与常规对话消息在视觉上显著区分；
• 可附带一条命令，通过真实执行来"演示"结果；
• 呈现结果后会主动等待用户反馈，形成"完成 → 反馈 → 再优化"的迭代闭环，而不是草率结束对话；
• 在大型工作流中作为清晰的检查点（checkpoint），也支持子任务完成后的父任务续跑。

从系统提示（system prompt）的角度看，Roo Code 被明确要求"完成任务后必须调用该工具"。objective.ts 中写明："Once you've completed the user's task, you must use the attempt_completion tool to present the result of the task to the user"；responses.ts 同样指出完成用户任务时应使用attempt_completion。

参数说明

该工具仅接受两个参数：

在源码层面，参数以严格的类型约束定义。工具实现 AttemptCompletionTool.ts 中interface AttemptCompletionParams仅包含result: string与command?: string；面向模型的工具声明 native-tools/attempt_completion.ts 采用strict: true的 OpenAI function calling 格式，required: ["result"]，result的语义被定义为 "Final result message to deliver to the user once the task is complete"（任务完成时交付给用户的最终结果消息）。

值得注意的细节：官方原生工具声明中只向模型暴露了result一个参数（command不参与模型端参数校验），而工具实际执行时通过 AttemptCompletionTool.handlePartial 兼容了command参数——若模型同时输出result与command，会先呈现完成结果，再以command询问（task.ask("command", ...)）请求用户批准执行。

何时触发该工具

根据官方文档，以下场景是它的典型触发时机：

• Roo 认为用户的请求任务已经完成；
• 需要总结做了哪些改动或改进；
• 需要借助一条命令的执行来演示当前成果；
• 为用户的"验收反馈"提供一个检查点；
• 从一个工作阶段过渡到可能的后续优化。

简而言之：它不是"进行中"的汇报工具，而是任务收尾的信号灯。文档明确强调，它不能用于部分完成或进度更新——那是update_todo_list等工具的职责。

底层执行流程拆解

结合 AttemptCompletionTool.ts 的实现，工具调用后的实际流程如下。

1. 前置安全检查（指南 + 硬性校验）

文档指出，"确认之前的工具调用都成功后再调用本工具"是一项最佳实践而非程序强制（guideline, not enforced）。系统提示的描述文本同样强调："This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful"，否则可能导致"代码损坏和系统故障"。

但源码中存在两处硬性校验，这是文档之外的实现事实：

• 本轮工具失败检查：if (task.didToolFailInCurrentTurn)时直接报错并返回，提示信息为 i18n 文案errors.attempt_completion_tool_failed（见 AttemptCompletionTool.ts）。这意味着当前轮次只要有过失败的工具调用，attempt_completion会被拒绝执行。
• 未完成 Todo 拦截（可选配置）：通过 VS Code 配置项preventCompletionWithOpenTodos（默认false）控制。开启后，若task.todoList中存在状态非completed的条目，工具会拒绝完成任务，并增加consecutiveMistakeCount、记录工具错误（见 AttemptCompletionTool.ts）。

对应测试 attemptCompletionTool.spec.ts 覆盖了"无 todo 列表允许完成""存在未完成 todo 且开启配置时阻止完成""本轮有工具失败时拒绝完成"等分支，验证了这些拦截逻辑。

2. 结果呈现

校验通过后：

• 若result为空，会触发缺失参数错误（consecutiveMistakeCount++并记录错误，见 AttemptCompletionTool.ts）；
• 正常路径下执行task.say("completion_result", result, undefined, false)，以completion_result这一特殊消息类型向用户展示结果（AttemptCompletionTool.ts）。

文档提及结果文本会通过removeClosingTag函数剥离 XML 闭合标签——这是 XML 风格工具调用解析中的内部处理步骤：由于attempt_completion以<result>...</result>包裹内容，剥离闭合标签可避免结果文本携带多余的 XML 片段，确保呈现干净、可扫描的总结文字。

3. 命令执行（若提供 command）

• 命令需先获得用户批准（approval）才执行；
• 批准后通过系统的命令执行能力运行，并把输出展示给用户；
• 工具对命令数量有限制：只能附带一条命令，无法同时给出多个命令选项。

4. 反馈收集与迭代

• 系统通过task.ask("completion_result", "", false)等待用户对完成结果的反馈（AttemptCompletionTool.ts）；
• 若用户点击"是"（yesButtonClicked），任务正式标记为完成，触发TaskCompleted事件；
• 若用户输入反馈文本，系统会以user_feedback消息回显，并将反馈以<user_message>...</user_message>包装后作为工具结果推送给模型（AttemptCompletionTool.ts），使 AI 能够针对反馈继续工作——这正是"迭代改进循环"的源码实现：对话并未因attempt_completion而终止。

5. 任务完成与续跑

• 任务在系统中标记为完成；
• 捕获该任务的遥测（telemetry）数据；
• 任务完成时，emitTaskCompleted会先强制更新最终的 token 用量统计（task.emitFinalTokenUsageUpdate()），再发出RooCodeEventName.TaskCompleted事件，附带 token 用量与工具使用统计（AttemptCompletionTool.ts）。

子任务场景：委派与父任务续跑

attempt_completion在子任务（subtask）中拥有独特的委派逻辑（见 AttemptCompletionTool.ts）：

• 通过task.parentTaskId判断当前是否为委派产生的子任务；
• 查询子任务在历史记录中的状态，避免从历史恢复会话时重复向父任务注入 tool_result；
• 状态为active时进入委派流程：询问用户是否"完成子任务并恢复父任务"（askFinishSubTaskApproval）；
  • 批准后调用provider.reopenParentFromDelegation，把父任务从委派状态恢复，并携带子任务的完成摘要（completionResultSummary）；
  • 拒绝则推送toolDenied结果；
  • 返回"continue"时回落到常规完成询问流程；
• 状态异常（如undefined或"delegated"）会记录错误日志并跳过委派，防止数据损坏。

这使 Roo Code 能够支持复杂的嵌套工作流：子任务完成 → 总结 → 恢复父任务上下文 → 父任务继续，全程保持上下文连续。

可用范围：所有模式的"常备工具"

attempt_completion属于ALWAYS_AVAILABLE_TOOLS常量，在任何模式下都可用。该常量定义于 tools.ts：

export const ALWAYS_AVAILABLE_TOOLS: ToolName[] = [ "ask_followup_question", "attempt_completion", "switch_mode", "new_task", "update_todo_list", "run_slash_command", "skill", ] as const

在 modes.ts 中，每个模式的工具集合都会把ALWAYS_AVAILABLE_TOOLS全部并入，即无论 Code、Architect、Ask 还是自定义模式，attempt_completion始终在场。需要说明的例外是：工具校验 validateToolUse.ts 中，"requirements"（如自定义模式显式禁用某工具）的优先级高于常备工具列表——测试 validateToolUse.spec.ts 验证了这一行为。此外，在流式解析层面，NativeToolCallParser.ts 会在参数累积过程中即时提取result，让 UI 能边生成边呈现完成内容。

result 书写规范

官方文档给出如下写作指引：

• 清晰传达"完成了什么"；
• 简洁但完整；
• 聚焦交付给用户的价值；
• 避免不必要的客套话或填充文字；
• 保持专业、直截了当的语气；
• 使用易于快速扫读的结构化表达；
• 让用户知道可以提出反馈以进一步优化。

两点硬性提醒：

1. 不要以提问或邀请继续对话的方式结尾。系统提示规则 rules.ts 明确要求："NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user"——结果应以"最终交付"的口吻收束；
2. 系统会自动通过removeClosingTag剥离结果文本中的 XML 闭合标签，因此在 result 中不需要、也不应该手动编写 XML 标签。

command 选择规范

附带演示命令时遵循以下原则：

• 选择能"可视化展示结果"的命令，优先让用户看到创建或修改了什么；
• 推荐示例：
  • open index.html—— 打开生成的网页；
  • npm start—— 启动开发服务器；
  • python app.py—— 运行生成的应用程序；
• 避免仅输出文本的命令（如echo、cat）；
• 记住命令执行前需要用户批准；
• 确保命令在用户的操作系统上有效。

反馈与 UI 呈现：迭代闭环

attempt_completion拥有独特的反馈机制：

• 结果以独立的completion_resultUI 格式呈现，与普通消息不同，用户一眼即可识别"任务收尾点"；
• 系统在展示结果后等待用户反馈；
• 反馈被处理后返回给 Roo，驱动进一步优化——这创造了一个迭代改进循环，而非简单结束对话；
• UI 中包含专门的反馈交互元素；
• 结果作为对话流中清晰的检查点，保持结构化的对话节奏。

典型应用场景示例：

• 建站：Roo 交付网站后用open index.html展示，用户反馈后继续优化设计；
• 实现功能：Roo 总结改动及其影响，用户要求补充测试覆盖，Roo 继续任务；
• 修复 Bug：Roo 说明修复了什么、如何解决根因，用户确认修复生效；
• 搭建环境：Roo 确认各组件已安装，用户要求额外配置后继续；
• 数据处理脚本：Roo 总结脚本功能，用户建议性能优化，Roo 继续调优代码。

完整使用示例

以下三个示例分别覆盖"纯结果总结""结果 + 演示命令""脚本任务 + 执行演示"三种典型形态，均可在实际提示中直接套用。

示例一：仅结果总结

<attempt_completion> <result> I've updated the CSS for the navigation bar to match the design mockup. The changes include: 1. Updated color scheme to use the new brand colors 2. Added responsive behavior for mobile devices 3. Fixed the alignment issues in the dropdown menus </result> </attempt_completion>

示例二：结果 + 演示命令

<attempt_completion> <result> I've created a simple React application with the following features: 1. A responsive landing page with the requested hero section 2. A working contact form with validation 3. Navigation between all three requested pages 4. Styling that matches the provided design mockup </result> <command>npm start</command> </attempt_completion>

示例三：Python 脚本任务 + 执行演示

<attempt_completion> <result> I've created a data processing script that: 1. Reads the CSV files from the data directory 2. Cleans and normalizes the data as requested 3. Generates the summary statistics in JSON format 4. Outputs the processed data to the output directory </result> <command>python process_data.py</command> </attempt_completion>

限制与注意事项

• 上一工具成功确认是指导原则而非强制校验（不过源码中有didToolFailInCurrentTurn硬拦截，见上文"前置安全检查"）；
• 只能附带一条演示命令，无法呈现多个命令选项；
• 命令执行必须经用户批准；
• 只能演示"可以通过 CLI 命令展示"的结果类型；
• 不能用于部分完成或进度更新场景；
• 结果文本中的 XML 闭合标签会被内部处理剥离；
• 开启preventCompletionWithOpenTodos配置后，存在未完成 Todo 的任务将无法完成。

源码与测试索引

若想深入理解该工具的实现细节，推荐阅读以下仓库文件：

• 工具实现：AttemptCompletionTool.ts（含参数校验、Todo 拦截、委派流程、事件发射）
• 工具声明与常量：tools.ts（AttemptCompletionToolUse接口）、tools.ts（ALWAYS_AVAILABLE_TOOLS）
• 模型端工具描述：native-tools/attempt_completion.ts
• 系统提示约束：rules.ts、objective.ts、responses.ts
• 流式参数解析：NativeToolCallParser.ts（attempt_completion的 partial/nativeArgs 提取）
• 模式可用性：modes.ts、validateToolUse.ts
• 单元测试：attemptCompletionTool.spec.ts、validateToolUse.spec.ts

把握住"结果要终态、内容要可扫读、命令要能演示、反馈要接得住"这四条主线，attempt_completion就能成为你驾驭 Roo Code 完成-验收-迭代闭环的关键枢纽。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code