VS Code极简AI编排框架rooroo：构建你的专属AI开发团队

1. 项目概述：一个为VS Code设计的极简AI编排框架

如果你和我一样，每天都在VS Code里和各种代码、文档、需求搏斗，那你肯定也幻想过能有一个得力的“AI副驾”团队。不是那种只会单打独斗的聊天机器人，而是一个分工明确、配合默契的专家小组：一个负责拆解复杂需求的“军师”，一个埋头写代码的“工匠”，一个能洞察数据的“分析师”，还有一个能把一切讲清楚的“文档官”。更重要的是，这个团队得听从一个“总指挥”的调度，有条不紊地把你的想法变成现实。这就是rooroo（如如）想做的事——它不是一个功能庞杂的“全家桶”，而是一个极简主义的AI编排框架，专门为VS Code环境下的软件开发工作流量身打造。

rooroo的核心哲学很有意思，它借用了佛教哲学中的“如如”（Thusness）概念，意指事物本然、一贯的实相。这映射到框架设计上，就是一种“极简与专注”的理念：每个AI智能体（Agent）都有其清晰、单一、本质的职责，就像瑞士军刀里的每个工具，各司其职，组合起来却能应对复杂场景。它不追求大而全，而是强调通过清晰的流程、高效的沟通和专业的协作，让AI真正融入你的开发节奏，成为一种“ vibe coding ”——一种直觉、流畅的编码体验。

简单来说，rooroo为你构建了一个运行在VS Code内部的微型AI团队。你通过“领航员”（Navigator）这个总指挥来下达指令，它会根据任务的复杂性，决定是直接派某个专家（如开发者、分析员）上场，还是先请“规划师”（Planner）来制定一份详细的作战计划（分解为子任务）。所有任务、沟通、产出物都被结构化管理在项目根目录的.rooroo/文件夹下，整个过程透明、可追溯、可干预。它特别适合那些需要多步骤、多角度协作的软件开发任务，比如从一个模糊的产品想法开始，逐步完成需求分析、技术方案设计、代码实现、测试乃至文档编写的全过程。

2. 核心设计理念与架构拆解

2.1 “如如”哲学下的极简主义设计

为什么叫“极简主义”？在AI工具泛滥的今天，很多框架试图用一个模型解决所有问题，或者提供成百上千个配置参数，让人望而生畏。rooroo反其道而行之，它的“极简”体现在三个方面：

第一，角色极度专业化。框架内置的六个智能体（Navigator, Planner, Developer, Analyzer, Documenter, Idea Sparker）各有明确的边界。Navigator只做调度和通信，绝不写一行代码；Developer只关心如何实现需求，不参与任务规划。这种设计避免了“万能模型”带来的指令混淆和效果不可控问题。在实际使用中，我发现这大大提升了任务执行的准确率。例如，当你让Developer修复一个Bug时，它收到的context.md文件里已经包含了Planner或Navigator分析好的问题根因和修改范围，Developer就能心无旁骛地聚焦于编码，而不会去猜测“用户到底想要什么”。

第二，上下文传递的“链接优先”原则。这是rooroo提升效率并控制成本的关键设计。传统AI协作中，经常需要把大量代码或文档内容塞进提示词（Prompt），导致令牌（Token）消耗巨大、速度变慢且可能触及上下文长度限制。rooroo规定，在给专家智能体准备的context.md任务简报中，优先使用文件路径链接，而非直接嵌入内容。例如，简报里会写“请参考./src/utils/validator.js的第20-45行”，而不是把那几十行代码全贴进来。智能体被训练成会主动去“点击”（即读取）这些链接来获取必要信息。这就像给AI发了一份带有超链接的文档，而不是一份把所有附件都打印出来的纸质报告，既节省了通信开销，又保持了信息的结构化。

第三，清晰、一致的数据流与工作空间约定。所有操作都围绕项目根目录进行，使用相对路径。任务有统一的ROO#前缀ID，输出有固定的.rooroo/tasks/TASK_ID/目录存放，状态通过queue.jsonl和activity.jsonl来管理。这种强约定减少了歧义，使得整个系统的行为可预测、可调试。作为开发者，你永远知道该去哪里找任务列表、看执行日志、检查产出物。

2.2 智能体团队：各司其职的专家小组

理解每个智能体的定位和配置建议，是高效使用rooroo的前提。这里需要特别关注LLM（大语言模型）的选型策略，因为它直接关系到效果和成本。

• 🧭 Rooroo Navigator（领航员）：你的主要交互对象和系统大脑。它负责理解你的初始指令，进行任务分类（Triage），管理任务队列，调用其他专家，并处理专家的反馈。由于它的工作主要是流程控制和简短对话，对“智能”要求相对较低，但对响应速度要求高。因此，官方推荐使用⚡ 快速/廉价模型（例如GPT-3.5-Turbo，Claude Haiku等）。这能保证交互的流畅性，同时显著降低成本。

  注意：Navigator是整个系统的“调度中心”，它的稳定性至关重要。务必为其配置一个可靠的、低延迟的API端点。

• 🗓️ Rooroo Planner（规划师）：复杂任务的拆解大师。当你提出一个像“为我们的应用添加用户社交功能”这样模糊而庞大的目标时，Navigator会将它交给Planner。Planner需要理解全局，进行需求分析，并将其分解为一系列具体的、可执行的子任务，例如“设计数据库关系模型”、“实现关注/取关API”、“开发用户个人主页UI组件”。这个工作需要强大的逻辑推理和架构设计能力，因此官方推荐使用🧠 智能/昂贵模型（例如GPT-4，Claude Opus等）。虽然单次调用成本高，但它的一次成功规划可以避免后续多个子任务因方向错误而返工，总体上更划算。

• 🧑‍💻 Rooroo Developer（开发者）：代码执行者。它接收具体的编码任务简报（如“在src/api/friendship.py中实现POST /api/follow/{user_id}接口”），并产出代码文件、补丁或修改现有项目文件。模型选择取决于任务难度：简单的CRUD操作可以用快速模型；涉及复杂算法或新框架学习时，可能需要智能模型。你可以为它配置一个自定义或混合模型策略。

• 📊 Rooroo Analyzer（分析员） & ✍️ Rooroo Documenter（文档员）：这两个角色通常处理的是信息提取、总结和重组工作。Analyzer可能分析日志文件、用户数据；Documenter根据代码生成API文档或更新README。它们对创造性的要求低于Planner，但对准确性和归纳能力有要求。通常，⚡ 快速/廉价模型就能胜任，性价比最高。

• 💡 Rooroo Idea Sparker（灵感激发者）：这是一个战略前瞻协调员。它不直接执行任务，而是在项目早期，当你只有一个模糊概念时，引导你进行结构化思考。它会通过一系列提问，帮你厘清问题背景、核心目标、潜在解决方案和权衡利弊，最终产出一份详细的“移交文档”。这份文档存储在.rooroo/brainstorming/下，可以作为后续交给Planner进行详细规划的完美输入。由于其需要深度思考和发散联想，同样推荐使用🧠 智能/昂贵模型。

成本平衡心得：我的经验是，采用“两头重，中间轻”的模型配置策略。即在“思考类”任务（Planner, Idea Sparker）上投入好的模型，在“执行类”和“调度类”任务（Developer, Analyzer, Documenter, Navigator）上使用经济型模型。这样能在保证决策质量的同时，有效控制整体token消耗。

2.3 核心工作流与数据文件解析

rooroo的工作流是一个清晰的闭环，理解这个流程，就能理解整个框架是如何运转的。我们可以将其分为几个核心阶段，并对应到具体的文件操作上。

阶段一：任务接收与分类

1. 你在VS Code中选中Rooroo Navigator，输入：“我们需要优化首页的加载速度。”
2. Navigator收到指令后，开始“分类”。它会判断这是一个“复杂/不确定任务”（涉及性能分析、方案选型、具体修改），因此决定启动Planner。
3. Navigator在.rooroo/tasks/下创建一个新的任务目录，例如ROO#PLAN_20241001120000_optimize_homepage，并在其中生成一个给Planner的context.md文件，简要说明了你的原始需求。
4. Navigator将这个规划任务写入.rooroo/queue.jsonl队列文件。

.rooroo/queue.jsonl文件详解： 这是一个JSON Lines格式的文件，每一行都是一个独立的JSON对象，代表一个待处理任务。它的结构至关重要：

{"taskId": "ROO#PLAN_20241001120000_optimize_homepage", "suggested_mode": "rooroo-planner", "context_file_path": ".rooroo/tasks/ROO#PLAN_20241001120000_optimize_homepage/context.md", "goal_for_expert": "Decompose the goal 'optimize homepage loading speed' into actionable sub-tasks for the Developer or Analyzer."}

• taskId: 唯一任务标识符，以ROO#开头，包含时间戳和描述。
• suggested_mode: 建议执行此任务的专家模式。
• context_file_path: 该任务详细简报的Markdown文件路径。
• goal_for_expert: 给执行专家的最终目标描述。

阶段二：任务规划与分解

1. Navigator检查队列，发现有待处理任务，于是调用Rooroo Planner，并将对应的context.md提供给它。
2. Planner开始工作。它可能会要求读取项目中的相关文件（如首页组件代码、打包配置文件、网络请求模块等），进行分析。
3. Planner最终产出：一份详细的规划。它会在.rooroo/plans/目录下可能生成一份概览文档，同时，它会创建一系列子任务。
4. 对于每个子任务（例如“分析当前资源打包大小”、“实现图片懒加载组件”、“优化首屏API调用链”），Planner会：
   • 生成一个子任务ID，如ROO#SUB_optimize_homepage_S001。
   • 在.rooroo/tasks/下创建对应的子任务目录。
   • 在该目录中生成一个给执行专家（可能是Analyzer或Developer）的context.md文件。这个文件是精华所在，它包含了具体指令、相关文件链接、验收标准等。
   • 将这些子任务对象，依次追加写入queue.jsonl文件。

context.md文件示例：

# 任务简报：分析当前首页资源打包大小 **任务ID:** ROO#SUB_optimize_homepage_S001 **执行专家:** rooroo-analyzer **目标:** 生成一份报告，量化当前首页加载的主要资源（JS, CSS, 图片）的体积，并识别出最大的几个依赖包。 ## 相关文件 - 构建配置: `./webpack.config.js` - 打包分析报告: `./dist/report.html` (如果存在) - 入口文件: `./src/pages/Home/index.jsx` ## 具体步骤 1. 检查或运行构建命令，生成带有分析功能的构建报告。 2. 分析报告，列出所有大于100KB的Chunk。 3. 特别关注来自 `node_modules` 的第三方依赖。 4. 将分析结果总结为Markdown报告，包含表格和数据。 ## 输出要求 - 报告保存为 `bundle_analysis.md` 于本任务目录下。 - 报告中需包含建议的优化方向（如：可否代码分割、有无更小的替代库）。

实操心得：一个高质量的context.md是任务成功的关键。务必遵循“链接优先”原则，清晰地列出步骤和期望的输出格式。模糊的指令会导致AI反复询问或产出不如预期的结果。

阶段三：任务执行与反馈

1. Navigator再次检查队列，现在里面是Planner创建的几个子任务。它取出第一个子任务（例如给Analyzer的），调用对应的Rooroo Analyzer，并传递子任务的context.md。
2. Analyzer执行分析，它遵循简报，读取链接的文件，运行命令，最终将分析报告bundle_analysis.md保存到自己的任务目录.rooroo/tasks/ROO#SUB_optimize_homepage_S001/下。
3. 执行完毕后，Analyzer不会直接跟你说话，而是向Navigator返回一个结构化的JSON输出信封。

JSON输出信封：

{ "status": "Done", "message": "已完成首页资源打包分析，报告已保存。发现主要体积来自未按需加载的UI组件库。", "artifacts": ["bundle_analysis.md"] }

状态可以是Done、Failed或NeedsClarification。如果是NeedsClarification，Navigator会将其中的问题转达给你，等你回复后再转发给专家。

阶段四：状态处理与循环

1. Navigator收到Done的信封后，会做三件事：
   • 记录日志：将一个事件记录到.rooroo/logs/activity.jsonl。
   • 更新队列：将当前这个已完成的任务从queue.jsonl中移除（或标记为完成）。
   • 通知用户：在VS Code里告诉你“Analyzer任务已完成”。
2. 然后，Navigator自动检查队列是否还有任务。如果有，就回到阶段三，执行下一个任务；如果没有，则通知你所有计划任务已完成，并等待你的下一步指令。

.rooroo/logs/activity.jsonl文件详解： 这也是一个JSON Lines格式的日志文件，用于审计和调试。所有关键操作都会被记录。

{"timestamp": "2024-10-01T12:05:30Z", "agent_slug": "rooroo-navigator", "severity": "INFO", "task_id": "ROO#SUB_optimize_homepage_S001", "event_type": "EXPERT_REPORT_PROCESSED", "details": {"report_status": "Done", "next_action": "Task removed from queue."}}

通过这个日志，你可以清晰地看到整个任务的流转过程：何时被创建、派发给谁、执行结果如何。当出现问题时，这是第一手的排查资料。

3. 从零开始：环境配置与核心工作流实操

3.1 环境准备与Roo Code扩展安装

rooroo的运行依赖于VS Code及其扩展Roo Code。因此，第一步是搭建好这个基础环境。

1. 安装VS Code：确保你使用的是较新版本的Visual Studio Code（建议2023年6月以后的版本）。
2. 安装Roo Code扩展：
   • 打开VS Code，进入扩展市场（Ctrl+Shift+X）。
   • 搜索“Roo Code”，找到由“RooVeterinaryInc”发布的扩展。
   • 点击安装。这个扩展提供了与rooroo框架交互的界面和底层通信能力。
3. 配置LLM模型（关键步骤）：rooroo本身不绑定特定模型，它通过Roo Code扩展来调用你配置的AI服务。你需要准备一个或多个LLM API的访问权限（如OpenAI GPT, Anthropic Claude, 或本地部署的Ollama等）。
   • 在VS Code中，按下Ctrl+Shift+P打开命令面板，输入“Roo Code: Settings”并打开设置。
   • 在设置界面，你需要配置“Models”。这里你可以添加多个模型终端，并为每个rooroo智能体分配不同的模型。这正是实现前面提到的成本平衡策略的地方。
   • 配置示例：
     • 添加一个终端，命名为gpt-4-turbo，配置好OpenAI的API密钥和基础URL（如果你使用Azure OpenAI或第三方代理，此处需相应修改）。
     • 添加另一个终端，命名为claude-3-haiku，配置好Anthropic的API密钥。
     • 在“Agent Model Assignments”部分，进行如下映射：
       • rooroo-planner->gpt-4-turbo
       • rooroo-idea-sparker->gpt-4-turbo
       • rooroo-navigator->claude-3-haiku
       • rooroo-developer->claude-3-haiku(或根据任务难度动态选择)
       • rooroo-analyzer->claude-3-haiku
       • rooroo-documenter->claude-3-haiku

3.2 初始化项目与首次任务实战

假设我们有一个简单的Node.js后端项目，现在想为其添加一个“健康检查”API端点。让我们用rooroo来完成。

第一步：项目初始化与.roomodes文件加载

1. 在VS Code中打开你的项目根目录。
2. 你需要一个.roomodes文件来告诉Roo Code/rooroo本项目的一些基础配置。这个文件可以是YAML或JSON格式。
   • 对于Roo Code v3.18.0及以上版本，推荐使用更易读的YAML格式。在项目根目录创建.roomodes文件：

     # .roomodes version: 1 agents: rooroo-navigator: enabled: true rooroo-planner: enabled: true rooroo-developer: enabled: true rooroo-analyzer: enabled: true rooroo-documenter: enabled: true rooroo-idea-sparker: enabled: true # 可以在这里为特定agent添加自定义指令，但更推荐使用 .roo/rules/ 目录

   • 对于v3.18.0之前的版本，必须使用JSON格式，例如创建.roomodes.json文件，内容与上述YAML对应。
3. 创建好.roomodes文件后，必须完全重启（Reload）VS Code窗口，以确保Roo Code扩展正确加载并识别该配置。

第二步：启动Navigator并下达首个指令

1. 重启后，在VS Code侧边栏找到Roo Code的活动栏图标（通常是一个袋鼠或类似标志），点击它。
2. 在出现的聊天界面中，你应该能看到一个模式选择器。从下拉菜单中选择“🧭 Rooroo Navigator”。
3. 现在，你可以像跟一个项目经理对话一样，输入你的需求。我们输入：

   “为我们的Node.js后端项目添加一个健康检查端点/api/health，它应该返回服务状态、当前时间戳和数据库连接状态（假设我们使用Mongoose）。请规划并实现它。”

第三步：观察Navigator的分类与Planner的介入

1. Navigator收到这个请求。它会判断：这是一个明确的开发任务，但涉及路由创建、数据库状态检查等多个步骤，属于“复杂/不确定任务”。因此，它会启动Planner。
2. 你会在聊天窗口看到Navigator的回复：“这是一个涉及多个步骤的任务，我将请Planner来为您分解。请稍候...”
3. 同时，在你的项目根目录下，会自动生成.rooroo/文件夹。进去查看，你会发现：
   • logs/activity.jsonl里已经多了几条日志，记录了Navigator启动和调用Planner的事件。
   • tasks/目录下多了一个以ROO#PLAN_开头的文件夹，里面有一个context.md，内容是你的原始需求。
   • queue.jsonl文件被创建，里面写入了一条规划任务。

第四步：审查Planner的分解结果

1. 稍等片刻（时间取决于你的Planner模型速度），Planner会完成工作。Navigator会通知你：“Planner已生成执行计划，并创建了3个子任务。”
2. 此时，查看queue.jsonl，你会发现原来的规划任务已被移除，取而代之的是三条新的子任务记录，例如：

   {"taskId": "ROO#SUB_add_health_api_S001", "suggested_mode": "rooroo-developer", "context_file_path": ".rooroo/tasks/ROO#SUB_add_health_api_S001/context.md", "goal_for_expert": "Create a new route file for /api/health endpoint in the existing Express.js application structure."} {"taskId": "ROO#SUB_add_health_api_S002", "suggested_mode": "rooroo-developer", "context_file_path": ".rooroo/tasks/ROO#SUB_add_health_api_S002/context.md", "goal_for_expert": "Implement the health check logic in the route handler, including service uptime and a simple database connectivity check using Mongoose."} {"taskId": "ROO#SUB_add_health_api_S003", "suggested_mode": "rooroo-documenter", "context_file_path": ".rooroo/tasks/ROO#SUB_add_health_api_S003/context.md", "goal_for_expert": "Update the project's API documentation (e.g., README or a dedicated API docs file) to include the new /api/health endpoint."}

3. 分别打开这三个子任务目录下的context.md文件，你会看到Planner为你生成的、极其详细的任务说明书。例如，给第一个Developer任务的context.md可能会包含：
   • 目标：在src/routes/目录下创建health.js文件。
   • 参考现有结构：链接到src/routes/index.js和src/app.js，说明如何注册路由。
   • 具体要求：端点为GET方法，路径是/api/health。
   • 输出：创建的文件路径。

第五步：任务自动执行与监控

1. 由于队列非空，Navigator会自动开始处理。它会依次取出子任务，调用对应的Developer或Documenter。
2. 你可以在VS Code的聊天窗口看到实时进度：“正在执行任务：创建健康检查路由文件...”、“任务S001完成。”、“正在执行任务：实现健康检查逻辑...”
3. 同时，你可以打开logs/activity.jsonl文件，像看流水线日志一样观察每个步骤的状态。
4. 执行过程中，如果Developer遇到模糊点（比如它不确定数据库连接状态检查的具体方法），它会在JSON信封中返回NeedsClarification状态，并通过Navigator向你提问。你回答后，Navigator会将你的回答补充到context.md中，并让Developer继续。

第六步：验收成果

1. 当所有子任务状态都变为Done，队列清空后，Navigator会通知你所有任务已完成。
2. 现在，检查你的项目：
   • src/routes/health.js文件应该已经创建，里面包含了基本的Express路由。
   • 主应用文件（如app.js或index.js）可能已被修改，引入了新的路由。
   • .rooroo/tasks/ROO#SUB_add_health_api_S003/目录下，应该有一份更新后的API文档。
   • 整个.rooroo/目录完整记录了这次任务从规划到执行的全过程，包括所有的上下文和产出物。

通过这个完整的流程，你可以直观地感受到rooroo如何将一个模糊的需求，通过结构化的协作，转化为具体的代码和文档。它把“人指挥AI”变成了“人指挥一个AI团队”，而你作为“产品负责人”，只需要关注最高层的目标输入和关键节点的决策。

4. 高级特性与深度定制指南

4.1 利用.roo/rules/目录定制智能体行为

rooroo的默认行为已经足够智能，但每个团队或项目都有自己独特的编码规范、技术栈偏好或流程要求。.roo/rules/目录就是为了深度定制而生的。你可以在这里放置Markdown文件，为特定智能体或所有智能体提供额外的、项目级的指令。

工作原理：当某个Rooroo智能体被调用时，除了它自身的基础指令和当前任务的context.md，它还会自动读取.roo/rules/目录下所有相关的规则文件，并将这些规则作为系统提示词的一部分。这让你能“塑造”AI的行为，使其更贴合你的项目。

创建规则文件：

1. 在项目根目录下创建.roo/rules/文件夹（注意是.roo，不是.rooroo）。
2. 在rules/目录下创建Markdown文件。文件名有约定：
   • 01-general.md: 适用于所有智能体的通用规则。
   • 02-for-developer.md: 仅适用于Rooroo Developer的规则。
   • 03-for-documenter.md: 仅适用于Rooroo Documenter的规则。
   • 以此类推。数字前缀用于控制加载顺序（如果需要的话）。

规则文件内容示例 (02-for-developer.md)：

# 本项目开发者专用规则 ## 代码风格 - 使用 **ESLint** 配置（见 `.eslintrc.js`）和 **Prettier** 配置（见 `.prettierrc`）。生成或修改的代码必须通过 lint 检查。 - 使用 **箭头函数** 替代 `function` 关键字，除非是类方法或构造函数。 - 使用 **async/await** 处理所有异步操作，避免 `.then()` 链。 - 导入模块时，使用 **绝对路径别名** `@/`，它指向 `src/` 目录。 ## 项目结构约定 - 新的React组件请放在 `src/components/` 下，并遵循 `PascalCase` 命名。 - API路由控制器放在 `src/controllers/`，服务层放在 `src/services/`。 - 工具函数放在 `src/utils/`。 ## 安全与最佳实践 - 所有用户输入必须经过验证。参考 `src/middlewares/validator.js` 中的Joi模式。 - 数据库查询必须使用参数化查询或ORM方法，禁止字符串拼接。 - 在返回JSON响应时，统一使用 `src/utils/responseHelper.js` 中的 `success` 和 `error` 函数。 ## 测试 - 为新功能编写单元测试，放在 `__tests__/` 目录下。 - 如果修改了现有功能，请确保相关测试仍然通过。

有了这个规则文件，你的Rooroo Developer在编写代码时，就会自动遵循项目的代码规范、目录结构和安全要求，产出的代码几乎可以立即融入现有代码库，大大减少了后续的人工调整工作。

注意事项：规则文件不宜过长或过于复杂。应聚焦于最重要、最通用的约束。过于细致的规则可能会限制AI的创造力或导致提示词过长。建议从最关键的几条规则开始，逐步迭代。

4.2 工作流扩展：与Idea Sparker进行战略构思

对于更前期的、探索性的工作，rooroo提供了Rooroo Idea Sparker。它不是一个执行者，而是一个“引导式思考伙伴”。当你只有一个模糊的想法时，可以主动召唤它。

使用场景：比如，你正在考虑“是否应该为我们的应用引入WebSocket实现实时通知功能？”

操作流程：

1. 在Roo Code聊天界面，手动选择模式为“💡 Rooroo Idea Sparker”。
2. 输入你的初步想法：“评估为我们的用户仪表盘添加实时通知功能的可行性与方案。”
3. Idea Sparker会启动一个交互式会话。它会向你提出一系列结构化的问题，例如：
   • “当前用户通知是通过什么方式实现的？存在哪些痛点？”
   • “你期望的实时通知有哪些具体场景（如新消息、系统警报、状态更新）？”
   • “预计的并发用户数是多少？这对后端架构有什么影响？”
   • “在技术选型上，你更倾向于自建WebSocket服务，还是使用第三方PaaS（如Pusher, Ably）？”
4. 你回答这些问题，与Idea Sparker进行多轮对话。它会帮你梳理利弊，比较方案。
5. 最终，Idea Sparker会生成一份结构化的Handoff Document（移交文档），保存在.rooroo/brainstorming/目录下。这份文档可能包含：
   • 问题定义：清晰描述要解决的问题。
   • 目标与成功标准：项目成功的衡量指标。
   • 评估的方案：方案A（自建WebSocket），方案B（使用Pusher），方案C（使用Server-Sent Events）。
   • 利弊分析表：从成本、复杂度、维护性、性能等维度对比。
   • 推荐方案与理由：基于以上分析给出建议。
   • 后续行动步骤：如果采纳推荐方案，下一步可以交给Planner分解的具体任务清单。
6. 这份Handoff Document本身就是一个极其完善的context.md。你可以直接将其内容（或链接）交给Navigator，说：“请基于.rooroo/brainstorming/brainstorm_summary_ROO#IDEA_xxx.md中的推荐方案，进行详细规划和实施。” Navigator会理解这是一个已经过深度思考的需求，从而更高效地启动后续流程。

这个功能将rooroo从“任务执行框架”提升到了“创意与决策辅助框架”，覆盖了软件开发生命周期中更早的阶段。

4.3 故障排查与效能优化实战记录

即使设计再精良，在实际使用中也会遇到各种问题。以下是我在深度使用rooroo过程中遇到的一些典型情况及解决方法。

问题一：任务卡住，队列不再推进。

• 现象：Navigator显示“正在执行任务...”，但长时间没有进展，queue.jsonl里的任务也没有被移除。
• 排查步骤：
  1. 首先检查日志：打开.rooroo/logs/activity.jsonl，查看最后几条记录。如果看到"severity": "ERROR"的记录，里面通常会有错误信息。常见错误有：API调用失败（网络、密钥问题）、模型上下文长度超限、智能体输出不符合JSON信封格式导致解析失败。
  2. 检查专家输出：进入卡住任务对应的目录，查看是否有新文件生成。有时智能体已经产出了文件，但在返回JSON信封时格式错误，导致Navigator无法识别为完成。
  3. 手动检查context.md：可能是context.md中的指令过于模糊，或者链接的文件不存在，导致智能体陷入困惑，一直在“思考”而不输出。
• 解决方案：
  • 如果是API错误，检查Roo Code中的模型配置和网络连接。
  • 如果是上下文超限，优化context.md，更多地使用链接，减少直接嵌入大段代码。
  • 如果是输出格式错误，这是一个框架或模型兼容性问题。你可以尝试在.roo/rules/中为该智能体添加一条强规则，强调“你必须严格按照指定的JSON信封格式回复，只输出这个JSON对象，不要有任何其他文字。”
  • 最直接的解决方法是：手动干预。你可以直接删除queue.jsonl中卡住的任务行，然后通过Navigator重新下达一个更清晰的指令。

问题二：智能体产出的代码或文档质量不符合预期。

• 现象：任务执行完了，但生成的代码有bug，或者文档不完整。
• 原因分析：
  1. context.md质量不高：指令不够具体，缺少边界条件或验收标准。
  2. 模型能力不足：为执行类任务分配了过于廉价的模型，导致其无法理解复杂要求。
  3. 缺少项目上下文：虽然用了链接，但链接指向的文件本身未能提供足够信息（比如代码结构非常复杂）。
• 优化策略：
  • 提升context.md编写技巧：这是最重要的。学习编写“机器可读”的清晰指令。使用明确的步骤列表、输入输出示例、以及“不要做什么”的负面清单。例如，与其说“实现一个函数”，不如说“实现一个名为validateEmail的函数，它接收一个字符串参数，返回布尔值，需用正则表达式验证常见邮箱格式，参考src/utils/validatePhone.js的写法”。
  • 迭代式精炼：不要期望一次成功。把第一次产出当作初稿。如果代码有bug，不要直接自己改。可以新建一个任务给Developer或Analyzer，context.md里写：“请审查.rooroo/tasks/ROO#XXX/feature.js中的validateEmail函数，它未能通过__tests__/email.test.js中的测试用例1和3。请分析原因并修复。” 这样既解决了问题，又留下了审计轨迹。
  • 善用Analyzer进行代码审查：在重要的开发子任务后，可以插入一个由Analyzer执行的“代码审查”任务。让它基于项目的编码规范和质量要求，检查刚生成的代码。

问题三：如何管理复杂项目的.rooroo目录，避免混乱？

• 挑战：长期使用后，.rooroo/tasks/目录下会有大量以ROO#开头的文件夹，查找历史任务不便。
• 管理建议：
  • 定期归档：对于已完结且不再需要频繁参考的大型项目或史诗级任务，可以将其整个任务目录（如ROO#PLAN_xxx及其所有子任务ROO#SUB_xxx）压缩备份，然后从工作区中移除。.rooroo/queue.jsonl和logs/activity.jsonl可以定期清理旧条目（注意备份）。
  • 利用IDE搜索：VS Code的全局搜索（Ctrl+Shift+F）可以轻松搜索.rooroo目录下的所有context.md文件内容。通过搜索关键词来定位相关任务。
  • 约定任务ID命名：虽然框架自动生成ID，但你可以在给Navigator的初始指令中，加入一些有意义的标识。例如：“（项目代号：Phoenix）重构用户认证模块”。Planner在创建子任务时，可能会将这个代号带入任务ID或context.md，便于后续筛选。

效能优化技巧：

1. 批量处理相似小任务：如果有多个类似的简单任务（例如为十个实体生成CRUD API），不要分别给Navigator下十次指令。可以一次性告诉Planner：“请为以下十个资源模型：User, Product, Order... 分别生成标准的CRUD路由、控制器和Service层代码。” Planner会生成十个结构类似的子任务，然后由Developer批量执行，效率更高。
2. 预设常用任务模板：在.roo/rules/目录下，可以为Planner创建一些“任务模板”提示。例如，一个“生成React组件”的模板，里面包含了创建文件、编写函数组件、定义PropTypes、编写基础样式等标准步骤。这样Planner在分解类似任务时，能产出更一致、更高质量的context.md。
3. 监控成本：密切关注你的LLM API消费情况。rooroo的日志不记录token消耗，你需要通过API提供商的控制台来监控。如果发现Planner或Idea Sparker（使用贵模型）的调用过于频繁，可以反思是否有些简单分解或讨论可以由人来完成，或者优化你的提问方式，使其更精准，减少AI的“思考”负担。

rooroo不是一个点一下按钮就完成所有事情的魔法黑盒，而是一个需要你精心设计和引导的协作系统。你投入的“引导成本”（编写清晰的指令、制定合理的规则、设计高效的工作流）越多，它回报给你的“自动化收益”就越大。它最适合那些重复性高、模式固定、但又需要一定创造性和判断力的开发任务，将你从繁琐的“怎么做”中解放出来，让你更专注于“做什么”和“为什么”。