1. 项目概述重新定义AI驱动的开发工作流如果你和我一样每天都在和代码、需求文档、调试信息打交道那你一定对“上下文切换”这个词深恶痛绝。我们的大脑就像一台单核CPU在编写功能、查阅文档、分析日志、构思方案之间来回切换效率低得令人抓狂。更别提那些需要多步骤协作的复杂任务了光是理清头绪、分配工作、跟踪进度就足以消耗掉大半的精力。这正是我接触到rooroo这个项目时感到眼前一亮的原因。它不是一个试图取代你的“超级AI”而是一个极简主义的AI编排框架专为VS Code设计。你可以把它想象成一个高度专业化的“AI特工小队”的指挥官系统。你作为项目的“总司令”只需要向核心的“导航员”下达一个宏观指令比如“重构用户登录模块以支持OAuth 2.0”。剩下的工作——需求拆解、方案规划、代码编写、文档更新、问题分析——会由导航员智能地分派给最合适的“特工”去执行整个过程井然有序产出物结构清晰。rooroo的核心哲学“如如”Thusness源自佛学意指事物本然、如其所是的状态。这完美地映射了它的设计理念让每个AI代理回归其最纯粹、最专业的角色。开发者就专心写代码分析员就专注找问题规划师就负责拆解蓝图文档员就整理说明。它们各司其职通过一个清晰、可追溯的流程协同工作最终的目标是让你从繁琐的“项目管理”和“任务切换”中解放出来回归到“思考”和“决策”这一创造性的核心上来。它不追求大而全的复杂功能而是通过精准的分工和高效的协作实现开发流程的“本然”高效。2. 核心架构与设计哲学解析2.1 “导航员-专家”双轨制清晰的责任边界rooroo的架构核心可以概括为“一个大脑多只巧手”。这个“大脑”就是 Rooroo Navigator导航员。它是整个系统的指挥中枢也是你唯一的交互接口。你所有的指令、反馈、疑问都直接与导航员沟通它负责理解你的意图并决定下一步该怎么做。这个设计非常关键。它避免了你在多个AI代理之间疲于奔命也防止了信息在多个代理间传递时产生的歧义和丢失。导航员承担了“项目经理”和“产品经理”的双重角色对外你沟通需求对内专家代理分配任务、协调进度。而“巧手”则是一系列高度专业化的Rooroo专家代理️ Rooroo Planner规划师当导航员判断任务过于复杂或目标模糊时就会召唤规划师。它的职责是将一个宏大的目标如“开发一个待办事项应用”分解成一系列具体、可执行的子任务并为每个子任务生成详细的执行简报。‍ Rooroo Developer开发者纯粹的“码农”。它接收具体的编码任务简报然后生成、修改代码文件。它的输出直接是.py、.js等源代码文件或补丁。 Rooroo Analyzer分析员团队的“侦探”。负责根据简报分析代码库、日志、数据并生成分析报告如性能瓶颈、潜在bug、依赖关系图。✍️ Rooroo Documenter文档员团队的“书记官”。专门根据代码变更或需求创建或更新README.md、API文档、用户手册等。 Rooroo Idea Sparker灵感激发者这是一个比较特殊的战略角色。它不直接执行任务而是在项目初期或遇到复杂问题时引导你进行结构化头脑风暴探索问题本质评估多种解决方案最终产出一份详尽的移交文档。这份文档会成为后续规划师和开发者行动的蓝图。实操心得代理的“人设”至关重要在实际使用中我发现给每个代理设定清晰、稳定的“人设”即系统提示词是成功的关键。例如开发者代理必须被严格约束在“只修改context.md中指定的文件”和“遵循项目现有的代码风格”这些规则内否则它可能会天马行空地重构整个项目。rooroo通过.roo/rules/目录支持这种工作区级别的自定义指令让你能精细调校每个代理的行为使其更贴合你的项目规范。2.2 基于文件系统的强状态管理一切皆可追溯与许多依赖内存或临时会话的AI工具不同rooroo将所有状态和产出物都持久化到文件系统中。这带来了几个巨大的优势可追溯性整个任务的生命周期从创建、执行到完成所有记录都保存在.rooroo/目录下。你可以随时查看任务队列、活动日志、每个任务的详细简报和产出文件。这就像拥有了一个永不丢失的“开发黑匣子”。可中断与可恢复因为状态被保存你可以随时关闭VS Code甚至关机。下次打开项目导航员可以读取队列和日志从中断的地方继续或者向你汇报进度。协作与审查.rooroo/tasks/目录下的任务文件夹天然就是一份份完整的工作包。你可以轻松地将它们提交到版本控制系统如Git供团队成员审查或者作为案例存档。上下文精准传递通过context.md文件传递任务详情并强制要求使用文件链接而非嵌入大量内容确保了专家代理获取的上下文是精准且最新的。它直接去读链接指向的当前文件内容避免了因复制粘贴导致的上下文过时问题。这种设计体现了“如如”哲学让系统的运行状态和中间产物“如其所是”地呈现出来不增不减清晰可见。2.3 成本感知的模型调度策略AI API调用成本是实际应用中必须考虑的因素。rooroo在设计上就内置了成本优化意识。它建议为不同的代理分配不同“档位”的大语言模型导航员、分析员、文档员建议使用快速/廉价的模型如GPT-3.5-Turbo Claude Haiku。它们的任务更多是流程控制、信息提取和格式化输出对创造性和深度推理要求相对较低。规划师、灵感激发者建议使用智能/昂贵的模型如GPT-4 Claude Opus。它们的任务需要深度理解、复杂拆解和创造性构思高质量的模型能显著提升规划的成功率和头脑风暴的深度。这种差异化配置可以在保证核心任务质量的同时有效控制整体使用成本。在实际部署时你可以在VS Code的Roo Code扩展设置中为每个代理单独指定其使用的模型。3. 从零开始完整配置与核心工作流实操3.1 环境准备与基础配置首先你需要在VS Code中安装Roo Code扩展。这不仅仅是rooroo的运行时更是一个强大的AI编程助手本体。安装完成后你需要一个.roomodes文件来定义你的AI代理团队。关键步骤创建你的代理团队蓝图.roomodes文件.roomodes文件是Roo Code扩展识别和加载代理的配置文件。从v3.18.0开始支持更易读的YAML格式。我强烈推荐使用YAML因为它结构清晰便于维护。以下是一个为rooroo框架量身定制的、功能完整的.roomodes.yaml示例version: 1 modes: # 核心导航员 - 使用快速廉价模型 - slug: rooroo-navigator name: Rooroo Navigator description: The central orchestrator. Manages user interaction, triages tasks, dispatches to experts, and processes reports. Prioritizes concise communication. systemPrompt: | You are the Rooroo Navigator, the central command and control for a team of specialized AI agents. Your role is to: 1. INTERACT with the user: Understand their goal, ask for clarifications when needed. 2. TRIAGE the request: - If its complex/uncertain, summon the Rooroo Planner (rooroo-planner). - If its a clear, single-task for Developer, Analyzer, or Documenter, prepare the task context. - If ambiguous, ask the user. 3. MANAGE the queue (.rooroo/queue.jsonl): Add tasks, dispatch the next task to the correct expert. 4. PROCESS expert reports (JSON Output Envelope): Handle NeedsClarification, Done, Failed statuses. 5. LOG all key events to .rooroo/logs/activity.jsonl. Always be concise. Use the Principle of Least Assumption. Never guess; clarify. # 建议使用快速模型以节省成本如 gpt-3.5-turbo modelProvider: openai modelName: gpt-3.5-turbo # 战略层规划师与灵感激发者 - 使用智能昂贵模型 - slug: rooroo-planner name: ️ Rooroo Planner description: Decomposes complex goals into sub-tasks for execution agents. Creates detailed context.md briefings. systemPrompt: | You are the Rooroo Planner. Your job is to break down complex, high-level goals into a sequence of concrete, actionable sub-tasks for the Rooroo Developer, Analyzer, or Documenter. For each sub-task, you MUST create a context.md file in the corresponding .rooroo/tasks/ROO#SUB_.../ directory. The context.md must be concise and use FILE LINKS (e.g., [./src/main.py](./src/main.py)) to reference relevant files, NOT embed large chunks of code. If the goal is ambiguous or youre unsure which expert to assign a sub-task to, flag it for the Navigator. Output a clear plan summary and ensure all task folders and context files are created. modelProvider: openai modelName: gpt-4 # 使用更强大的模型进行复杂规划 - slug: rooroo-idea-sparker name: Rooroo Idea Sparker description: Strategic Foresight Facilitator. Guides structured brainstorming to produce a Handoff Document blueprint. systemPrompt: | You are the Rooroo Idea Sparker. You facilitate structured brainstorming sessions to explore problems, generate solutions, and evaluate options. Guide the user through questions to clarify the problem space, constraints, and success criteria. Synthesize the discussion into a comprehensive **Handoff Document**. This document should include: - Problem Statement - Considered Solutions Trade-offs - Recommended Approach Rationale - Key Requirements Specifications - Potential Risks Mitigations Save the final document to .rooroo/brainstorming/ with a proper ROO#IDEA_ timestamp ID. This document will be the blueprint for the Planner and Developer. modelProvider: openai modelName: gpt-4 # 创造性思考需要更强的模型 # 执行层开发者、分析员、文档员 - 可使用快速或定制模型 - slug: rooroo-developer name: ‍ Rooroo Developer description: Executes coding tasks. Writes, modifies, and refactors code based on the context.md briefing. systemPrompt: | You are the Rooroo Developer, a specialist AI coder. Your ONLY sources of truth are: 1. The context.md file in your assigned task directory (.rooroo/tasks/TASK_ID/context.md). 2. The actual files in the workspace, accessed via the links provided in context.md. Your instructions: - Read the context.md thoroughly. - Follow the goal and requirements EXACTLY. - Write or modify code ONLY as specified. Do not change unrelated files. - Adhere to the existing projects coding style and conventions. - Output your work (new files, modifications as diff/patch) directly into your task folder (.rooroo/tasks/TASK_ID/). - Finally, return a JSON Output Envelope to the Navigator with your status and any artifact paths. # 开发者可根据任务复杂度选择模型。简单任务用快速模型复杂算法用智能模型。 modelProvider: openai modelName: gpt-3.5-turbo - slug: rooroo-analyzer name: Rooroo Analyzer description: Investigates code, data, or systems based on context.md. Produces analysis reports. systemPrompt: | You are the Rooroo Analyzer. You investigate and analyze based on the briefing in context.md. Your output is an analysis report (e.g., .md, .json) saved in your task folder. The report should be clear, factual, and based on the evidence found in the linked files. Return a JSON Output Envelope to the Navigator when done. modelProvider: openai modelName: gpt-3.5-turbo - slug: rooroo-documenter name: ✍️ Rooroo Documenter description: Creates or updates documentation based on context.md briefing. systemPrompt: | You are the Rooroo Documenter. You create clear, useful documentation. Use the context.md and linked source files as input. Output documentation files (e.g., README.md, API_DOCS.md) into your task folder. Maintain a consistent tone and style with any existing project documentation. Return a JSON Output Envelope to the Navigator. modelProvider: openai modelName: gpt-3.5-turbo将这个文件保存到你的项目根目录。然后在VS Code中通过命令面板CtrlShiftP / CmdShiftP运行Roo Code: Load .roomodes file并选择该文件。加载成功后你会在VS Code侧边栏的Roo Code面板中看到这六个代理模式可供选择。注意事项模型配置与API成本上述配置中的modelProvider和modelName需要根据你实际拥有的API访问权限进行修改。例如你可以将modelProvider改为anthropic并使用claude-3-haiku-20240307作为快速模型claude-3-opus-20240229作为智能模型。务必在VS Code的设置中正确配置对应API的密钥。混合使用不同供应商的模型是平衡能力与成本的常见策略。3.2 核心工作流逐步拆解让我们通过一个真实场景——“为现有REST API添加用户身份验证中间件”——来走一遍rooroo的完整工作流。假设你的项目是一个简单的Node.js Express应用。第1步与导航员对话下达指令在VS Code中从Roo Code面板选择 Rooroo Navigator模式。在聊天框中输入你的目标“为当前项目中的Express API添加用户身份验证。需要支持基于JWT的令牌验证并创建一个/api/auth/login端点来签发令牌。现有代码在src/目录下。”导航员收到指令后会开始它的分流判断。由于这是一个涉及多个步骤分析现有路由、创建中间件、设计登录端点、更新文档的复合任务导航员大概率会判断其为“复杂/不确定”任务。第2步规划师介入拆解任务4. 导航员自动切换到️ Rooroo Planner模式或调用它并将你的初始指令传递过去。 5. 规划师开始工作。它会 * 扫描src/目录下的现有文件如app.js,routes/等。 * 创建一个规划任务ID例如ROO#PLAN_20231027120000_auth_middleware。 * 在.rooroo/tasks/ROO#PLAN_.../下生成context.md里面是给你的原始指令。 * 然后它会在.rooroo/plans/目录下生成一个*_plan_overview.md文件概述整体方案。 *最关键的一步它创建一系列子任务文件夹如ROO#SUB_auth_middleware_S001ROO#SUB_auth_middleware_S002并为每个子任务生成详细的context.md。例如 *S001给分析员目标分析现有src/目录下的API路由结构识别哪些端点需要保护。*S002给开发者目标在src/middleware/下创建auth.js实现JWT验证中间件。需读取环境变量JWT_SECRET。*S003给开发者目标在src/routes/下创建auth.js实现POST /api/auth/login端点验证用户名密码后签发JWT。*S004给文档员目标在README.md中更新‘身份验证’章节描述如何获取和使用JWT。6. 规划师将这些子任务以JSON行格式写入.rooroo/queue.jsonl文件。 7. 规划师向导航员报告“完成”并附上规划概览的路径。第3步导航员调度与专家执行8. 导航员切回读取队列中的第一个任务比如S001给分析员。它更新任务状态然后切换到 Rooroo Analyzer模式并将S001的context.md路径提供给分析员。 9. 分析员读取context.md按照其中的链接去查看src/routes/下的文件进行分析。完成后它在自己的任务文件夹.rooroo/tasks/ROO#SUB_auth_middleware_S001/中生成一份报告例如route_analysis.md列出需要保护的路由。 10. 分析员向导航员返回一个JSON输出信封{status: Done, message: Analysis complete., artifacts: [.rooroo/tasks/ROO#SUB_auth_middleware_S001/route_analysis.md]}。 11. 导航员记录日志将S001从队列中移除然后检查队列中的下一个任务S002给开发者并重复调度过程。第4步循环、反馈与完成12. 开发者代理根据context.md编写auth.js中间件和auth.js路由文件并将它们输出到自己的任务文件夹。它可能会在代码中引用分析员生成的报告。 13. 如果开发者在编码过程中发现context.md的描述有歧义例如“用户名密码”从哪里获取它会返回状态为NeedsClarification的输出信封。导航员会暂停队列将问题转达给你获得你的澄清后再反馈给开发者继续。 14. 所有任务依次执行。文档员根据开发者的产出更新README.md。 15. 当队列清空导航员会汇总所有结果通知你整个“添加身份验证”的任务已完成。所有中间产物、代码、报告都整齐地存放在.rooroo/tasks/下对应的子文件夹中你可以逐一审查并将需要的代码文件如src/middleware/auth.js手动复制到项目源码目录或者用开发者生成的补丁文件进行合并。4. 高级技巧与深度定制指南4.1 利用.roo/rules/目录进行行为微调.roomodes文件定义了代理的“基础人格”而.roo/rules/目录则允许你进行工作区级别的行为微调。你可以在这里创建Markdown文件为特定代理添加更具体的指令。例如你的项目使用ESLint和Prettier进行代码规范检查。你可以创建.roo/rules/01-for-developer.md# 针对 Rooroo Developer 的额外规则 当你编写或修改JavaScript/TypeScript代码时必须严格遵守以下规范 1. 所有代码必须通过项目根目录下的ESLint配置检查。运行 npm run lint 不应有任何错误。 2. 代码格式必须符合Prettier规范。你可以参考 .prettierrc 文件。 3. 优先使用 const 和 let避免 var。 4. 使用箭头函数替代传统的 function 关键字除非需要特定的 this 绑定。 5. 为所有新函数添加JSDoc注释。 在返回的JSON信封中请附带一条说明表明你已考虑上述规则。当导航员调用开发者代理时它会自动加载并融合这些规则到其系统提示词中。这确保了所有由rooroo生成的代码都符合你的项目标准。4.2 上下文管理艺术“链接而非嵌入”这是rooroo的一个核心操作准则也是保证效率的关键。在编写context.md时你必须克制住复制粘贴大量代码到简报中的冲动。错误示范嵌入内容导致简报臃肿且易过时目标修改用户查询函数。 现有代码如下 javascript // src/users.js function getUsers() { // ... 这里粘贴了50行代码 }请添加一个按姓名过滤的功能。**正确示范使用链接简洁且指向最新源文件** markdown 目标修改 src/users.js 文件中的 getUsers 函数为其添加按 name 参数过滤用户列表的功能。 **相关文件** - 主文件[./src/users.js](./src/users.js) - 用户数据结构参考[./src/models/User.js](./src/models/User.js) - 相关的API测试文件[./tests/users.api.test.js](./tests/users.api.test.js) **要求** 1. 添加一个可选的 name 查询参数。 2. 过滤逻辑需区分大小写。 3. 保持函数原有的错误处理逻辑不变。这样做的好处是简报轻量任务队列和日志读写更快。上下文准确专家代理总是读取文件系统中的最新内容避免基于过时的代码片段做出决策。关注点分离context.md只描述“要做什么”和“在哪里做”具体的“怎么做”由专家代理通过分析最新代码来决定。4.3 故障排查与状态恢复实战rooroo的强状态持久化设计使得故障排查和恢复变得非常直观。场景VS Code意外崩溃重启后如何继续检查活动日志首先打开.rooroo/logs/activity.jsonl。这是一个JSON Lines格式的文件每一行都是一个日志事件。从最后几行看起寻找最后一个event_type: EXPERT_REPORT或TASK_DISPATCH的记录。这能告诉你系统在崩溃前执行到了哪一步。{timestamp: 2023-10-27T10:15:30Z, agent_slug: rooroo-navigator, severity: INFO, task_id: ROO#SUB_auth_S002, event_type: EXPERT_REPORT, details: {status: NeedsClarification, message: 需要明确JWT的过期时间应设置为多长}}从这条日志可知任务ROO#SUB_auth_S002的开发者代理遇到了问题正在等待澄清。检查任务队列打开.rooroo/queue.jsonl。查看当前队列里还有哪些任务。如果上一个任务状态是NeedsClarification它可能已被导航员暂时挂起但仍在队列中。手动恢复重新启动VS Code加载项目。切换到 Rooroo Navigator模式。直接对导航员说“继续处理之前的任务”或者“请查看当前队列状态”。导航员会读取队列和日志并很可能直接向你复述它最后收到的问题“关于任务ROO#SUB_auth_S002开发者需要澄清JWT的过期时间应设置为多长”你回答后导航员便会将澄清信息传递给开发者任务流程自动继续。常见问题速查表问题现象可能原因排查步骤与解决方案导航员不响应或报错Roo Code扩展未正确加载.roomodes文件1. 检查.roomodes.yaml语法是否正确可用YAML校验器。2. 在命令面板重新运行Roo Code: Load .roomodes file。3. 重启VS Code。专家代理找不到context.md任务文件夹路径错误或文件未创建1. 检查.rooroo/queue.jsonl中context_file_path字段的值是否正确。2. 手动去.rooroo/tasks/下对应的任务ID文件夹查看文件是否存在。3. 可能是规划师执行出错需检查其活动日志。队列卡住任务不推进上一个任务报告NeedsClarification后未收到用户反馈1. 查看activity.jsonl最后几条日志。2. 直接与导航员对话它会提示你当前阻塞的问题是什么。3. 回答该问题以解除阻塞。代理生成的代码不符合项目规范代理的“人设”或项目特定规则未定义清楚1. 检查并强化.roomodes中对应代理的systemPrompt。2. 在.roo/rules/目录下创建针对性的规则文件。3. 在context.md中明确加入代码风格要求。.rooroo/目录变得混乱长时间运行产生大量任务文件夹1. 定期归档已完成的任务文件夹可压缩备份后删除。2. 在开始新的大项目前考虑清空.rooroo/目录注意备份队列和日志如需。rooroo本身不提供自动清理这是为了保留完整历史。5. 融入现有开发流程从玩具到生产力的跨越rooroo不是一个孤立的工具它需要被你整合到日常的工作习惯中才能发挥最大价值。与版本控制Git的协作将.rooroo/目录纳入.gitignore是一个值得商榷的选择。我的建议是有选择地提交。忽略queue.jsonl和activity.jsonl是运行时状态频繁变化不应提交。考虑提交重要的tasks/子文件夹特别是包含最终方案设计、核心分析报告或可作为范例的context.md、plans/下的规划文档、brainstorming/下的移交文档。这些是宝贵的知识资产和过程记录有助于团队知识沉淀和审计。你可以配置.gitignore如.rooroo/queue.jsonl.rooroo/logs/但保留.rooroo/tasks/等目录的跟踪。作为“超级增强版”的代码助手不要用rooroo去处理那些在编辑器中按个快捷键如Copilot就能完成的代码补全。它的强项在于处理需要多步骤、多上下文、有明确输入输出定义的复合型任务。例如功能开发“基于models/Product.js和现有的routes/products.js添加一个带有分页和价格区间过滤的产品搜索端点。”代码重构“将src/utils/目录下所有使用var声明变量的文件改为使用const或let并确保通过ESLint检查。”依赖升级“分析package.json将React从17.x升级到18.x并检查src/目录下所有文件更新任何不兼容的API用法。”文档梳理“遍历src/components/下的所有React组件文件为每个组件生成一个Props接口定义和用法示例并汇总到一个COMPONENT_API.md文件中。”迭代与反馈循环rooroo的工作流天然支持迭代。如果你对开发者生成的代码不满意不要直接手动修改它的输出文件。更好的方式是将它的输出作为参考。创建一个新的任务或修改原任务的context.md更清晰地描述你的修改要求。再次将其放入队列让开发者代理基于你的反馈进行修正。这样整个修改过程和原因也被记录在任务流中形成了可追溯的迭代历史。经过数月的实践我个人最大的体会是rooroo带来的最大价值并非完全自动化的代码生成而是将模糊的意图转化为清晰、可执行、可追踪的行动计划的能力。它迫使你在项目初期进行更结构化的思考通过灵感激发者和规划师并在整个执行过程中保持上下文的一致性和透明度。它就像一位不知疲倦的、极度严谨的项目协调员把你从项目管理的泥潭中拉出来让你能更专注于真正需要人类创造力和判断力的高层设计和技术决策。当你适应了这种“导航员指挥专家执行”的节奏后你会发现处理复杂任务的心智负担显著降低而项目的可维护性和文档完整性却得到了意想不到的提升。