Roo Code 自然语言请求指南：如何高效地向 AI 编程助手描述需求
【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code
Roo Code 是一套运行在你代码编辑器中的 AI 编程助手，它被设计为理解自然语言：你不需要学习任何特殊命令或语法，直接用平实的英语（或其他自然语言）描述你的需求，就像和一位人类开发者对话一样。本篇指南将系统讲解向 Roo Code 提出请求的核心策略、完整示例与常见误区，并结合仓库源码剖析请求背后的解析机制（尤其是@上下文提及系统），帮助你写出信息密度更高、执行结果更准确的任务指令。
为什么可以直接"说人话"
Roo Code 的交互入口是一个普通文本输入框，它会把你的请求与当前工作区的代码、诊断信息、终端输出等上下文一起封装成消息，交给底层大语言模型处理。因此，请求的质量直接决定了执行的质量——一条模糊的指令与一条精确的指令，产出的结果可能天差地别。
从源码看，你的请求并不会被"原样"直接送入模型，而是先经过一层提及（mention）解析系统处理。src/core/mentions/processUserContentMentions.ts 是这一流程的入口：它会扫描用户内容中的@提及、/斜杠命令等标记，将文件内容、目录内容、诊断信息、终端输出等以独立内容块的形式拼接到请求中，再连同用户的原始文本一起发给模型。这意味着，你写在请求里的每个@引用，都会被真实地展开成模型可读的代码上下文——这也正是"用自然语言 + 上下文引用"比"空口描述"更可靠的根本原因。
有效请求策略
原文档总结的四大策略是所有高质量请求的基石：
| 策略 | 具体做法 |
|---|---|
| Be specific（具体明确） | 明确说出要 Roo Code 做什么，避免含糊不清。例如用"修复calculateTotal中导致返回结果错误的问题"代替"修复代码" |
| Provide context（提供上下文） | 使用@上下文提及 引用文件与代码，把相关内容直接带进对话 |
| Break down tasks（拆解任务） | 将复杂任务拆分为若干个更小、可管理的步骤逐一提交 |
| Include examples（附带示例） | 当你需要特定的格式或代码风格时，提供示例代码作为参照 |
这四条策略在仓库中都有对应的实现支撑。例如"提供上下文"背后是完整的提及解析管线：parseMentions（src/core/mentions/index.ts）会通过正则逐一识别请求文本中的提及，再调用getFileOrFolderContentWithMetadata读取文件/目录内容，最终由formatFileReadResult（src/core/mentions/index.ts）将内容格式化成像read_file工具输出那样的块——带上文件路径、行号范围与截断提示，让模型明确"该文件已被读取"，从而做出更精准的判断。
请求解析机制：@提及在底层如何工作
理解@提及的底层实现，能帮助你写出更有效的请求。提及解析的关键逻辑集中在 src/core/mentions/index.ts 与 src/shared/context-mentions.ts 中：
- 匹配规则：
mentionRegex（src/shared/context-mentions.ts）规定@必须出现在行首或空白之后，且不能被反斜杠转义，从而避免粘贴日志时误触发；它支持以/开头的文件/目录路径、带协议头的 URL、7–40 位十六进制 Git 提交哈希，以及problems、git-changes、terminal三个关键字。文件路径中的空格需要用\转义（例如@/path/to/file\ with\ spaces.txt），解析时再由unescapeSpaces还原。 - 内容替换：
parseMentions的第二遍扫描（src/core/mentions/index.ts）会把提及替换为干净的引用文本，例如文件路径被替换为带引号的路径、@problems被替换为Workspace Problems (see below for diagnostics)，同时把真正的载荷追加为独立内容块。 - 块类型分发：文件/目录内容来自文件系统读取；
problems通过diagnosticsToProblemsString汇总 VS Code 问题面板的诊断；git-changes通过getWorkingState获取未提交改动；提交哈希通过getCommitInfo拉取提交信息；terminal通过getLatestTerminalOutput捕获最近的终端输出（见 src/core/mentions/index.ts）。 .rooignore校验：读取文件时会经过rooIgnoreController.validateAccess检查（src/core/mentions/index.ts），被忽略的文件会返回说明而非内容。- 二进制与图片：二进制文件不会以文本形式混入上下文（src/core/mentions/index.ts），图片提及则由独立的图像附件流程处理，前提是模型支持视觉能力。
processUserContentMentions（src/core/mentions/processUserContentMentions.ts）则负责把这套解析结果装配进最终的消息块：用户的原始文本、文件内容块、斜杠命令帮助依次排列，并捕获第一个斜杠命令携带的模式（mode）切换指令。整个过程对用户是透明的——你在输入框里写下的自然语言请求，经过这一层"隐形增强"后才成为模型看到的完整上下文。
示例请求：从复制到理解
原文档给出了六个可直接使用的请求示例，下面逐个展开说明它们运用了哪些策略：
新建文件并实现函数
create a new file named `utils.py` and add a function called `add` that takes two numbers as arguments and returns their sum这条请求同时具备"具体明确"（文件名、函数名、参数与返回值都交代清楚）与"单一任务"（只做一件事）两个特征，是典型的高质量指令。
结合文件引用修改代码
in the file @src/components/Button.tsx, change the color of the button to blue文件引用@会把Button.tsx的完整内容（含行号）注入上下文，Roo Code 无需猜测"哪个按钮"，直接定位目标组件即可修改。
全局查找替换
find all instances of the variable `oldValue` in @/src/App.js and replace them with `newValue`注意这里的@/src/App.js以/开头、指向工作区根目录，这是文件提及的标准写法（详见 上下文提及 中的格式说明）。
执行终端命令
run the command `npm install` in the terminal这类指令会触发执行命令类工具，把具体的命令行参数写清楚能显著减少来回确认的次数。
解释代码
explain the function `calculateTotal` in @/src/utils.ts文件提及提供源码、自然语言指定目标符号，两者配合让"解释类"请求也能得到精确回答。
结合诊断信息修复问题
@problems address all detected problems@problems会把 VS Code 问题面板中的错误与警告（含文件路径、行号与诊断消息）作为结构化上下文追加进请求（src/core/mentions/index.ts），Roo Code 无需你手动复制报错即可直接修复，详见 诊断集成。
原始文档配图（输入请求的真实交互演示）位于 apps/docs/static/img/typing-your-requests/naturally.gif。
常见误区：不该怎么做
原文档用一组对照表总结了新手最常犯的五类错误，值得反复对照自查：
| 不要这样做（DON'T） | 应该这样做（DO） |
|---|---|
| 含糊的请求（Vague requests） | 精确说明需要完成什么 |
| 默认对方了解上下文（Assuming context） | 显式引用文件和函数 |
| 堆砌过多技术黑话（Excessive technical jargon） | 使用清晰直白的语言 |
| 一次提交多个无关任务（Multiple unrelated tasks） | 一次聚焦一个请求 |
| 不确认就继续（Proceeding without confirmation） | 检查代码确保完整正确 |
其中"默认对方了解上下文"是最常见的效率杀手。Roo Code 并不会自动阅读你整个项目，它只能看到请求中被显式引用的内容。参考上面的解析机制可以理解：文件内容只有在被@提及或由工具主动读取后才会进入上下文。因此，与其说"修复那个报错的组件"，不如说"修复 @/src/components/Button.tsx 里的类型错误"。
此外，提示词工程指南 还补充了两条与本节互补的进阶建议：一是尽量在提示中指定输出格式（如 JSON、Markdown）；二是如果初次结果不理想，不要放弃——迭代修改提示词是正常且高效的工作方式。
进阶技巧：从"请求"到"工作流"
当你掌握了基础请求写法后，可以组合使用更高级的上下文能力，把单条请求升级为完整工作流：
- 目录提及：
@/src/components/（注意结尾斜杠，用于与文件提及区分）会一次性带入目录内全部非二进制文本文件的内容，适合"分析这一整个目录的代码"类请求；但需留意上下文窗口限制，目录过大时优先改为引用其中关键文件。 - Git 提及：
@a1b2c3d引用具体提交（提供提交信息、作者、日期与完整 diff），@git-changes展示未提交的改动（git status与 diff），适合代码审查与提交信息建议；二者都依赖 Git 命令，因此会遵循.gitignore。 - 终端提及：
@terminal捕获最近一次命令及其完整输出（保留终端状态、不清理终端），非常适合调试构建失败或分析命令输出。 - URL 提及：
@https://example.com通过无头浏览器抓取网页并清洗为可读的 Markdown，适合让 Roo Code 参考外部文档或页面。 - 斜杠命令：以
/开头（而非@），例如/test、/init，执行预定义工作流；当命令绑定了目标模式时，还会触发模式切换。完整清单见 斜杠命令。 - "先想后做"四步法：分析（分析现状与问题）→ 计划（列出实施步骤）→ 执行（逐步实现）→ 复核（每步确认），把复杂任务拆成一轮轮聚焦的请求，与"拆解任务"策略一脉相承。
小结
向 Roo Code 提请求的核心就一句话：像给一位认真但不知情的同事布置任务一样，把"做什么、在哪里做、做到什么程度"说清楚，并用@把相关文件、诊断、终端与 Git 上下文直接带进对话。把握"具体明确、提供上下文、拆解任务、附带示例"四条策略，避开"含糊、臆断、堆术语、多任务混杂"四类误区，再配合目录、Git、终端、URL 与斜杠命令等扩展提及能力，你就能把 Roo Code 从"能跑的助手"调教成"一次到位"的 AI 开发搭档。若想进一步深挖请求的底层解析逻辑，可继续阅读 src/core/mentions/index.ts 与 src/core/mentions/processUserContentMentions.ts 的完整实现。
【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
