Roo Code 教程

1- 🧭 Roo Code 解锁 VS Code 中的 AI 编程超能力

1.1- 欢迎来到 Roo Code 的世界：你的 VS Code 智能副驾

想象一下，在你的 VS Code 编辑器里，并肩坐着一位经验丰富、不知疲倦的 AI 编程伙伴，它能理解你的想法，帮你写代码、查 Bug、做设计，还能 7x24 小时随时待命。这就是 Roo Code！

Roo Code (曾用名 Roo Cline) 不是一个孤立的应用程序，而是一款深度集成在 Visual Studio Code (VS Code) 中的强大AI 编程助手 (AI Coding Assistant) 扩展插件。它致力于将先进的 AI 能力无缝融入你的日常开发流程。

  • 💡 核心亮点:
    • 🔸 🤖 自然语言驱动: 用中文或英文直接与 AI 对话，下达指令。
    • 🔸 📂 无缝文件交互: 直接读取、理解、修改你工作区中的代码文件和项目文档。
    • 🔸 ⚡ 强大终端控制: 授权后可代你执行终端命令（如编译、测试、部署）。
    • 🔸 🧠 多模型支持: 灵活接入业界主流 AI 大模型 (OpenAI GPT 系列, Anthropic Claude 系列, Google Gemini, DeepSeek, 以及通过 OpenRouter 访问的众多模型)，甚至包括本地部署的模型 (通过 Ollama/LM Studio)。
    • 🔸 🎭 场景化模式: 内置多种 AI " 角色 "（如编码专家、架构师、知识问答助手），适应不同开发任务。
    • 🔸 🔧 高度可定制: 允许你创建具有特定 " 个性 "、技能和工具权限的自定义 AI 模式。
    • 🔸 🔗 智能上下文感知: 通过简单的 @ 符号，轻松将文件、代码片段、终端问题等关键上下文喂给 AI，让沟通更精准高效。

1.2- 安装 Roo Code：三步到位

在开始之前，请确保你已经安装了 VS Code (建议 1.85 或更高版本)。

1.2.1- 打开 VS Code 扩展市场

  • 🔹 在 VS Code 左侧边栏，点击像四个方块（其中一个分离）的 扩展 图标。

1.2.2- 搜索并识别

  • 🔹 在顶部的搜索框中输入 Roo Code。
  • 🔹 在搜索结果列表中，找到那个带着醒目 火箭图标 🚀 的 “Roo Code” 扩展。

1.2.3- 点击安装 (Install)

  • 🔹 在该扩展条目旁边，点击蓝色的 Install 按钮。
  • 🔹 安装过程通常很快。完成后按钮会变为 “Uninstall”。

1.2.4- 验证安装

  • 🔹 安装成功后，检查 VS Code 左侧的活动栏（最左边的图标栏），是否出现了一个新的火箭图标 🚀。
  • 🔹 点击这个火箭图标，应该会打开 Roo Code 的主侧边栏面板。

1.3- 配置核心：连接 AI 大脑 (API Key 设置)

这是让 Roo Code 真正开始工作的关键一步！ Roo Code 本身不包含 AI 模型，它需要通过 API Key 连接到外部或本地的 AI 大模型服务。

1.3.1- 获取你的钥匙 (API Keys)

你需要至少一个 AI 模型的 API Key。选择哪个取决于你的需求（性能、成本、数据隐私）：

1.3.2- 🤔 选择来源

  • ☁️ 云服务商:

    • 🔹 OpenAI: 提供强大的 GPT 系列模型 (如 GPT-4o, GPT-3.5-turbo)。
    • 🔹 Anthropic: 提供 Claude 系列模型 (如 Claude 3 Opus/Sonnet/Haiku)，以长文本和严谨性著称。
    • 🔹 Google: 提供 Gemini 系列模型。
    • 🔹 DeepSeek: (推荐尝试) 通常提供高性价比的编码和通用模型。

  • 🔗 聚合服务:

    • 🔹 OpenRouter: (强烈推荐) 注册一个账号，获取一个 API Key，就能通过 Roo Code 访问来自多家供应商的众多模型。方便对比、切换，更容易找到性价比最高的模型。

  • 💻 本地部署:

    • 🔹 Ollama / LM Studio: 在你自己的电脑上运行 AI 模型 (如 DeepSeek Coder, Llama 3, Qwen)。优势：完全免费、代码绝对私密、可离线使用。

  • ⚙️ 操作: 请访问你选择的服务商官网，注册账号并按指引创建 API Key。妥善保管好你的 Key。

1.3.3- 在 Roo Code 中添加配置

1.3.3.1- 🔸 找到设置入口

  • 🔹 打开 Roo Code 面板 (点击左侧活动栏的火箭图标 🚀)。
  • 🔹 在面板内寻找 设置 入口，通常是一个 齿轮图标 ⚙️，或者在聊天输入框附近有明确的 “Settings” 或 “Configure” 按钮。

1.3.3.2- ➕ 添加 API Provider (提供商)

  • 🔹 进入设置界面后，找到 “API Providers” 或 “Models” 或类似的配置区域。
  • 🔹 点击 “Add Provider” 或一个 “+” 加号按钮。
  • 🔹 从下拉列表中选择你要添加的服务商 (例如 DeepSeek, OpenRouter, Ollama)。

1.3.3.3- 🔸 填写配置信息 (以 OpenRouter 为例)

  • 🔹 Provider: 选择 OpenRouter。
  • 🔹 API Key: 粘贴你从 OpenRouter 获取的 API Key。
  • 🔹 Base URL: 通常保持默认 https://openrouter.ai/api/v1 即可，除非你有特殊的代理设置。
  • 🔹 Model: (可选) 你可以在这里指定一个默认使用的模型名称 (如 openai/gpt-4o)，但更推荐之后在具体的 “Mode” 设置中指定。

1.3.3.4- 🔁 重复添加

你可以按照这个步骤添加多个 Provider，比如同时配置 OpenRouter 和一个本地的 Ollama。

1.3.4- 为模式分配 " 大脑 " (指定模型)

Roo Code 的精髓在于其 多模式 (Modes) 设计。你可以为不同的工作模式（场景）指定不同的 AI 模型和配置，实现最佳效果和成本控制。

1.3.4.1- 🔸 配置策略考量

  • 🔹 日常编码 (Code Mode): 可选用 性价比高 的模型，如 deepseek-coder (通过 DeepSeek Provider 或 OpenRouter)。
  • 🔹 复杂架构设计 (Architect Mode): 可能需要 能力更强 的模型，如 openai/gpt-4o 或 anthropic/claude-3-opus (通过 OpenRouter)。
  • 🔹 知识问答 (Ask Mode): 选择 平衡性好 的模型，如 anthropic/claude-3-sonnet 或 google/gemini-pro (通过 OpenRouter)。
  • 🔹 私密或离线工作 (Custom Mode 或修改默认): 配置使用你本地部署的 Ollama 模型。

1.3.4.2- 🔸 操作方法

  • 🔹 在 Roo Code 的设置中，找到 “Modes” 管理部分。

  • 🔹 为每一个模式 (Code, Architect, Ask, 以及你自定义的模式) 选择它应该使用的 API Provider 和具体的 Model Name。

    Mode Provider Model Name Example Recommended Use Case
    Code Mode DeepSeek deepseek-coder Coding, Bug Fixing, Refactoring
    Architect Mode OpenRouter anthropic/claude-3-opus System Design, Tech Choices
    Ask Mode OpenRouter google/gemini-pro Q&A, Research, Code Explanation
    Local Coder Ollama deepseek-coder:6.7b-instruct Private Code Tasks, Offline Use

1.4- 界面导览与核心交互

熟悉 Roo Code 的工作界面和交互方式是高效使用的基础。

1.4.1- Roo Code 工作区概览

1️⃣ 模式切换器 (Mode Selector): 通常在输入框上方或旁边，显示当前激活的模式 (如 “Code”)。点击它可以切换 AI 的角色 (如切换到 “Architect”, “Ask” 或你自定义的模式)。
2️⃣ 聊天历史区 (Chat History): 显示你与当前模式 AI 的完整对话记录。
3️⃣ 指令输入框 (Input Box): 你在这里输入文字指令、问题或代码片段。
4️⃣ @ 上下文引用 (Context Mention): 输入框旁边可能有 @ 按钮，或直接在输入框输入 @ 即可触发，用于快速添加文件、文件夹、选中代码、终端问题等上下文信息。这是提高 AI 理解精度的利器！
5️⃣ 发送/运行按钮 (Send/Run): 点击此按钮提交你的输入给 AI 处理。
6️⃣ 配置/设置入口 (Settings): 通常是一个齿轮 ⚙️ 图标，点击进入 Roo Code 的详细配置页面。

1.4.2- 基础对话交互

  • 🔹 就像和人聊天一样，在输入框 ③ 中输入你的需求。

    帮我写一个 Javascript 函数，它可以接收一个数组，并返回数组中所有数字的总和。

  • 🔹 点击发送按钮 ⑤。

  • 🔹 Roo Code (使用当前模式配置的模型) 会在聊天历史区 ② 生成回复，通常包含代码块、解释说明。

1.4.3- 强大的上下文引用 (@) 实战

这是 Roo Code 的核心优势之一，让 AI 精准聚焦于你关心的内容。

1.4.3.1- 🔸 引用项目文件

  • 💬 指令: 请检查 @src/utils/validation.js 文件中的 'isValidEmail' 函数是否存在潜在的逻辑漏洞，并提供改进建议。
  • ✨ 效果: Roo Code 会读取并分析 validation.js 文件内容，然后针对性地回答。

1.4.3.2- 🔸 引用编辑器中选中的代码

  • ⚙️ 操作: 先在 VS Code 编辑器中选中一段你想让 AI 处理的代码。
  • 💬 指令: 请将 @selection 这段代码从 Promise 语法重构为 async/await 语法。
  • ✨ 效果: Roo Code 只会处理你选中的那部分代码。

1.4.3.3- 🔸 引用终端问题

  • 🖥️ 场景: 你的终端输出了错误信息。
  • 💬 指令: 分析一下 @terminal 中出现的这个 'ModuleNotFound' 错误，我应该如何解决？
  • ✨ 效果: Roo Code 会结合错误信息和可能的项目上下文给出解决方案。

1.4.4- 执行终端命令 (需授权)

  • 🚦 前提: 需要在 Roo Code 的设置中，明确启用 “Terminal Access” 或类似权限。
  • 💬 指令示例: 帮我执行 'git status' 命令，看看当前工作区的状态。
  • 🛡️ 安全确认: 默认情况下，Roo Code 在执行命令前会弹窗请求你的确认 (可以配置为自动批准，但不推荐用于高风险命令)。
    🎬 [模拟动图描述: 用户输入执行 \git status` 的指令后，弹出一个包含命令内容和 " 批准 “/” 拒绝 " 按钮的确认对话框]`
  • ✅ 执行: 确认后，Roo Code 会在 VS Code 的集成终端中运行该命令，并将结果反馈给你。

1.4.5- 智能文件修改 (需审查)

  • 💬 指令示例: 请在 @./config/settings.json 文件中，添加一个新的键值对 "theme": "dark"。
  • 👀 预览差异 (Diff): Roo Code 不会直接修改文件，而是会生成修改建议，并以清晰的 Diff (差异对比) 格式展示给你看，明确标出哪些行被添加、删除或修改。
  • 👍 应用修改: 如果你确认无误，可以点击 “Accept” (接受) 或类似的按钮，Roo Code 才会真正将修改写入到文件中。务必仔细审查 Diff！

1.5- 切换 AI 角色：精通不同场景 (Modes)

灵活运用 Roo Code 内置的不同模式，可以让 AI 发挥最大效能。

1.5.1- Code Mode (编码能手 - 默认模式)

  • 🎯 核心职责: 编写、补全、解释、调试、重构代码；根据注释生成代码；执行文件操作和基础终端命令。
  • ❓ 何时使用:
    • 🔹 日常编码任务，如实现函数、类。
    • 🔹 快速修复编译器错误或运行时 Bug。
    • 🔹 将代码从一种语言翻译到另一种语言。
    • 🔹 优化一小段代码的性能或可读性。
  • 📝 示例: "为这个 Python 函数 @utils.py::calculate_average 添加详细的 docstring 文档说明。"

1.5.2- Architect Mode (架构大师)

  • 🎯 核心职责: 高层次系统设计、技术选型分析、API 接口规划、数据库模式设计、绘制架构图（提供概念描述或 Mermaid/PlantUML 脚本）、分析性能瓶颈、对比不同技术方案。通常不直接编写大量实现代码。
  • ❓ 何时使用:
    • 🔹 项目启动阶段的技术规划。
    • 🔹 需要设计复杂系统或模块时。
    • 🔹 评估引入新技术或框架的利弊。
    • 🔹 梳理现有系统的架构。
  • 📝 示例: "我正在构建一个社交媒体应用，需要支持动态消息流、用户关注和实时通知。请为后端设计一个可扩展的微服务架构，并推荐关键的技术选型（如数据库、消息队列）。"

1.5.3- Ask Mode (知识专家)

  • 🎯 核心职责: 解答关于编程语言特性、框架用法、算法原理、设计模式、项目代码逻辑等方面的问题；进行技术调研和信息检索。
  • ❓ 何时使用:
    • 🔹 学习和理解新的技术概念。
    • 🔹 需要深入了解项目中某段不熟悉的代码时。
    • 🔹 查找特定库或 API 的用法示例。
    • 🔹 比较不同算法或数据结构的优劣。
  • 📝 示例: "请解释一下 @src/core/event_bus.ts 文件中实现的发布-订阅模式是如何工作的，以及它相比直接调用的优势是什么？"

1.6- 🚀 进阶玩法：打造你的专属 AI 助手

掌握 Roo Code 的高级功能，让它成为你独一无二的开发利器。

1.6.1- 自定义模式 (Custom Modes)

  • 💎 价值所在: 不满足于预设模式？你可以创建具有特定 " 人设 "、专长和工具权限的 AI 助手。想象一下拥有一个专门的 " 测试用例生成器 “、” 代码风格警察 "、"API 文档撰写师 " 或 " 安全漏洞扫描员 "！
  • 🛠️ 创建方法:
    • 1️⃣ 进入 Roo Code 设置中的 “Modes” 管理界面。
    • 2️⃣ 点击 “Create New Mode” 或类似按钮。
    • 3️⃣ 关键配置:
      • 🔹 Name: 给模式起个清晰的名字 (如 “UnitTest Writer”)。
      • 🔹 Role/Persona (System Prompt): 这是核心！用详细的自然语言描述这个模式的角色、目标、行为准则和专业领域。例如：" 你是一个专注于 Go 语言的单元测试专家。你的任务是根据用户提供的 Go 函数代码 (@selection 或 @file)，为其编写全面、有效的单元测试用例，遵循标准的 Go 测试实践。"
      • 🔹 Tools: 精确控制该模式可以使用的工具（如是否允许读写文件、执行终端命令）。
      • 🔹 Model Configuration: 为这个特殊模式单独选择最适合的 AI 模型和 Provider。
    • 4️⃣ 保存后，你的新模式就会出现在模式切换器中。

1.6.2- 拥抱本地模型 (Ollama / LM Studio)

  • 💡 核心优势:
    • 🔒 数据绝对隐私: 所有代码和交互都在你的本地机器上处理，永远不会发送到外部服务器。对处理敏感代码或有合规要求的场景至关重要。
    • 💰 零 API 成本: 不再担心按 Token 计费，本地运行完全免费。
    • 🔌 离线可用: 即使没有网络连接，只要本地模型服务在运行，Roo Code 就能工作。
  • ⚙️ 设置步骤:
    • 1️⃣ 确保你已在本地安装并运行了 Ollama 或 LM Studio，并下载了所需的模型 (如 ollama run deepseek-coder)。
    • 2️⃣ 在 Roo Code 的 API Provider 配置中，添加一个新的 Provider，类型选择 Ollama 或 OpenAI Compatible。
    • 3️⃣ Base URL: 填入你本地服务的地址 (Ollama 默认是 http://localhost:11434/v1)。
    • 4️⃣ API Key: 通常随便填 (如 ollama 或 unused)。
    • 5️⃣ Model Name: 填入你在本地运行的具体模型名称 (如 deepseek-coder:6.7b-instruct)。
    • 6️⃣ 最后，在你希望使用本地模型的模式（可以是默认模式或自定义模式）中，选择这个配置好的本地 Provider 和模型。

1.6.3- 探索 MCP (Model Context Protocol)

  • 🔮 未来潜力: 这是一项更高级的协议，允许 Roo Code 通过对话交互动态地学习和集成新的工具 (Tools)。想象一下，你可以教 Roo Code 如何查询你的 Jira 项目、如何触发 CI/CD 流水线、如何与你的内部数据库交互，实现更复杂的自动化工作流。这通常需要一定的开发或配置知识，具体请参考 Roo Code 的官方文档。

1.7- ✨ 高效使用 Roo Code 的黄金法则

遵循这些技巧，让 Roo Code 成为你真正的得力助手：

  • 🎯 指令清晰，上下文充分: AI 不是读心者。你的指令越具体、越明确，使用 @ 提供的相关上下文越多，得到的结果就越符合预期。
  • 🔁 迭代沟通，逐步优化: 很少有复杂任务能一次完美完成。将 AI 的初步回复视为草稿，通过追问、要求修改、提供更多信息来逐步打磨，最终达到目标。
  • 🎭 模式对口，事半功倍: 花点时间思考当前任务最适合哪个模式（或自定义模式），选对角色能极大提高效率和产出质量。
  • 🧪 尝试不同模型: 如果对结果不满意，或者想在成本和性能间找到平衡，不妨切换到不同的 AI 模型试试看 (尤其是在使用 OpenRouter 时非常方便)。
  • ✅ 永远审查，保持警惕: AI 是强大的助手，但不是绝对权威。 它生成的信息或代码可能存在错误、过时或不安全。务必仔细审查 AI 的输出，特别是涉及代码修改、命令执行或重要决策时，最终责任在你。
  • 🚶 从小处着手，逐步深入: 如果你是新手，先从让 Roo Code 帮你完成一些简单、明确的小任务开始（如解释一段代码、写个小函数），熟悉其交互方式和能力边界后，再逐步尝试更复杂的任务。

1.8- ❓ 常见问题与排查 (Troubleshooting)

遇到问题时，可以尝试以下排查步骤：

1.8.1- API Key 错误 / 无效 / 额度不足

  • 🔹 仔细核对 API Key 是否完整复制粘贴，没有多余的空格或字符。
  • 🔹 登录对应的 AI 服务商平台，检查 Key 是否依然有效，账户是否有足够的余额或调用额度。
  • 🔹 确认 Roo Code 中配置的 Base URL 是否正确，特别是使用代理或本地模型时。

1.8.2- 连接失败 / AI 无响应

  • 🔹 检查你的网络连接是否正常。
  • 🔹 如果使用本地模型，确认 Ollama 或 LM Studio 服务是否已在后台成功启动并运行。
  • 🔹 尝试重启 VS Code。
  • 🔹 检查 VS Code 和 Roo Code 扩展是否是最新版本，有时更新能解决兼容性问题。

1.8.3- AI 回复质量不佳 / 不符合预期

  • ✍️ 优化提示词 (Prompt Engineering): 这是最常见的提升方法。尝试让你的指令更具体、提供更详细的背景信息和约束条件，明确告知 AI 你期望的输出格式。
  • 🔄 切换模型: 尝试更换一个能力更强或更适合当前任务的 AI 模型。
  • 🎭 选择合适的模式: 确认当前使用的模式是否与任务匹配。
  • 📄 提供示例: 如果可能，给 AI 一个你期望输出的简单示例 (Few-shot prompting)。

1.8.4- 文件修改/终端命令未执行

  • 🔹 检查是否在 Roo Code 设置中授予了相应的文件写入或终端访问权限。
  • 🔹 注意是否错过了执行前的确认弹窗。

1.9- 📚 结语与资源

Roo Code 是一个充满潜力的 AI 编程工具，它将持续进化。通过学习和实践，它可以显著提升你的开发效率、代码质量和学习速度。

现在，就去你的 VS Code 中，开始探索和释放 Roo Code 的强大潜力吧！