Roo Code 是 VS Code 生态里一款开源的 AI 编程智能体插件，它把大模型直接接入你的编辑器，让”agent”读代码、改文件、跑命令、查报错一气呵成。相比只会补全代码片段的传统工具，Roo Code 更像一位能自主执行任务的搭档。本文用实战方式，带你从安装到自定义专属”模式（Mode）”，打造属于自己的 AI 编程智能体。
一、Roo Code 是什么
Roo Code 源自 Cline 的开源分叉（fork），采用 Apache-2.0 协议，完全免费且可自托管。它最大的特点是以”任务”为单位驱动 Agent：你用自然语言描述目标，它规划步骤、读写文件、执行终端命令，并在每一步向你确认或自动放行。如果你已经读过《AI 编程智能体实战》，会发现 Roo Code 正是把”智能体”概念落到了本地编辑器里。
它支持 OpenRouter、Anthropic、OpenAI 以及本地模型（如 Ollama），也兼容 MCP 工具协议，可以接入数据库、浏览器、文件系统等多种能力。
二、四种内置模式与自定义机制
Roo Code 用”模式”来约束 Agent 的行为边界，避免它越权乱改。内置四种模式：
| 模式 | 能力范围 | 典型用途 |
|---|---|---|
| Code | 读写文件、执行命令 | 实现功能、修复 Bug |
| Architect | 只读分析、输出方案 | 架构设计、代码评审 |
| Ask | 纯问答、不改动 | 概念解释、选型建议 |
| Debug | 读日志、定位根因 | 排查运行期错误 |
但真正让 Roo Code 与众不同的是自定义模式：你可以为团队沉淀一个”数据库迁移专家””安全审计员”或”单元测试生成器”，把领域知识写进指令，新人也能一键复用老手的经验。
三、快速安装与基础配置
在 VS Code 扩展市场搜索 Roo Code 安装即可。首次使用需在设置里配置模型与 API Key。Roo Code 的配置统一存放在 VS Code 的 settings.json 中，例如指定使用 OpenRouter 的某个模型：
{
"roo-cline.apiProvider": "openrouter",
"roo-cline.openRouterModelId": "anthropic/claude-3.5-sonnet",
"roo-cline.autoApprovalEnabled": true,
"roo-cline.alwaysAllowExecute": true,
"roo-cline.alwaysAllowRead": true,
"roo-cline.alwaysAllowWrite": false
}把写文件设为需确认、读文件和执行命令自动放行，是兼顾效率与安全的常见组合。关于 VS Code 本身的效率配置，可参考《VS Code 高效开发环境配置》。
四、自定义模式实战：数据库迁移专家
在项目根目录新建 .roomodes 文件，定义专属模式。下面这个例子让 Agent 在生成数据库迁移脚本时，强制遵循”先评估影响、再产出可回滚 SQL”的纪律：
{
"customModes": [
{
"slug": "db-migration",
"name": "数据库迁移专家",
"roleDefinition": "你是资深 DBA，擅长评估 schema 变更的影响范围，并产出兼容线上环境、可回滚的迁移 SQL。",
"customInstructions": "1. 先读取相关表结构与现有迁移文件；2. 使用在线 DDL 工具思路，避免锁表；3. 每份变更必须附回滚脚本；4. 不删除列，采用标记废弃+延迟清理。",
"groups": ["read", "edit", "command"]
}
]
}保存后，在 Roo Code 模式下拉框即可看到”数据库迁移专家”。切换到该模式后，你只需说”给 users 表加一列 last_login_ip 并补充索引”，它就会按你设定的规则产出迁移文件与回滚脚本，而不是随手写一条会锁表的 ALTER。
五、用 MCP 把工具能力接进来
Roo Code 支持 MCP（Model Context Protocol），可以把外部工具暴露给 Agent。本质上，这和我们聊过的《Function Calling 实战：让大模型调用你的 API》是同一思路——把”能力”封装成可被模型调用的接口。例如接入一个本地数据库 MCP，Agent 就能直接查询线上表结构来辅助迁移设计。
{
"mcpServers": {
"local-db": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/app.db"]
}
}
}六、一条真实工作流：用 Roo 重构认证模块
假设要把散落在各处的硬编码鉴权逻辑抽成统一中间件，可以这样驱动 Roo Code：
- 在 Architect 模式下让它扫描代码、输出重构方案与受影响文件清单；
- 确认方案后切到 Code 模式，让它分批实现中间件并补单元测试；
- 用 Debug 模式运行测试、读取失败日志，迭代修复；
- 最后在 Ask 模式让它写出变更说明与回滚要点。
这种”先用 Architect 规划、再 Code 执行、Debug 收尾”的节奏，既能控制改动范围，又保留了 Agent 的自主性。如果你想深入理解背后的 ReAct 循环原理，推荐阅读《从零手写 AI Agent：ReAct 智能体实战》。
七、权限与成本控制
Agent 会真实执行命令，因此权限边界必须想清楚。建议：
- 命令白名单：只自动放行
npm test、git status等安全命令，rm、git push --force一律人工确认； - 预算护栏：在设置里限制每轮最大请求数或 token，防止陷入循环；
- 沙箱隔离：把实验性改动放在容器或分支中，可结合《Docker Compose 实战》快速拉起隔离环境。
八、项目级 .roo 目录：把规则沉淀进仓库
自定义模式可以只存在于本机，但更有价值的是把它提交进代码仓库。Roo Code 会读取项目根目录下的 .roo/ 文件夹：其中 .roo/rules-*.md 是全局规则，每次对话都会自动注入上下文；.roo/modes/ 下可放置模式专属的系统提示。这样团队成员克隆仓库后，无需各自配置，就能获得一致的 Agent 行为——相当于把”团队规范”变成了机器可执行的约束。
例如 .roo/rules-style.md 写入”使用 2 空格缩进、禁止 any 类型、单个函数不超过 40 行”，Agent 在生成代码时会自觉遵守，能省去大量 review 返工。配合 Git 的版本管理，这些规则还能随项目演进持续迭代。
九、Roo Code 与同类工具怎么选
面对琳琅满目的 AI 编码工具，可按”自主程度”和”是否开源”两个维度快速定位：
| 工具 | 自主执行 | 开源 | 适合场景 |
|---|---|---|---|
| Roo Code | 高（可跑命令） | 是 | 需要可控、可定制的 Agent |
| Cline | 高 | 是 | Roo 的上游，功能相近 |
| Cursor | 中 | 否 | IDE 内联补全与聊天 |
| Aider | 高（终端） | 是 | 习惯命令行的开发者 |
| Copilot | 低（补全） | 否 | 轻量补全、快速上手 |
如果你追求”把经验固化成模式、且完全自托管不依赖厂商”，Roo Code 是当前最顺手的选择。它与前面提到的手写 ReAct Agent思路一脉相承，只是把编排权交给了你和团队。
十、总结
Roo Code 的价值不在于”又一个补全工具”，而在于把领域经验沉淀成可复用的模式。当你把团队的编码规范、迁移纪律、测试要求写进 .roomodes 和 .roo 指令文件，AI 编程智能体就从一个通用助手，变成了懂你项目的专属工程师。从今天的一个自定义模式开始，逐步搭建属于你和团队的 Agent 工作流吧。
