用 osFoundry Maestro 在改动代码前先看计划并追溯每一步操作

Maestro 是 osFoundry 桌面应用里功能最全的 AI 对话界面。它和普通聊天最大的区别不在于回答质量，而在于回答旁边会留下一条可追溯的作业路径：取过哪些文件列表、grep 了什么、读了哪个文件、改了哪一行、跑了哪条命令，每一个动作都以带耗时的行形式排在对话里，点开就能看到传给工具的输入和返回的输出。它还能直接以本地文件夹为工作对象，文件改动以建议形式送达，必要时可以先出计划、停下来等你批准再动手。

这篇教程面向三类读者：想在下周合并按钮按下之前先读懂改动计划的个人开发者；刚进团队、知道业务逻辑却不知道代码写在哪里的新成员；以及需要在工程师仓库里改文案、但不想误碰其他文件的非工程角色。下面按准备工作、操作步骤、完整示例、注意事项的顺序讲清楚怎么把它用起来。

准备工作

安装桌面应用

Maestro 不是网页版功能，它内置于 osFoundry 的桌面应用中，需要先安装桌面客户端。安装完成后，在左侧边栏找到「Maestro」入口，点击进入。浏览器里的通用对话产品没有这套作业日志和刹车机制，所以不要指望在网页端复现下面的流程。

准备一个可用的工作文件夹

Maestro 以本地文件夹为工作对象。开始之前先确认：

• 你要操作的代码或文档已经完整克隆到本地，而不是只下载了部分文件；
• 该文件夹是一个 Git 仓库，或者至少你清楚哪些文件允许被改动；
• 如果涉及依赖安装与测试命令，本地环境已经能独立跑通这些命令，避免把环境问题误判成模型问题。

认识界面上的几个区域

第一次进入 Maestro 时，先把下面几处认全，后面的步骤都会用到：

• 上方的界面标签：Maestro、Model chat、Multi chat、Research、Wiki、Code 并排在同一屏。只有 Maestro 标签能用上全部工具。
• 对话上方的详情标签：聊天、来源、文件、变更历史、工具、流水线、日志。它们是同一次执行的不同视角——来源记录答案的依据，变更历史记录这次对话写过哪些文件，日志记录每个步骤以及每次请求的成本。
• 对话中的作业步骤：每个工具调用一行，点开可见输入与输出。
• 输入框上方的工具条：沙箱开关、计划（开/关）、工具、目标。
• 输入框下方的选择项：文件夹、项目、仓库、Router、模型。
• 右侧预览区：文件、差异、网页在对话旁边打开，不会遮住对话。

确认审批模式的默认值

输入框下方有「审批模式」设置，共四个选项，含义差别很大，动手前务必确认当前选的是哪一个：

如果只是问「这段逻辑写在哪」，保持默认的自动批准即可，因为这类任务不会写文件。

操作步骤

第一步：用计划模式先拿到改动方案

计划模式解决的是「改完再回头追差异」太被动的问题。开启方式是在输入框上方的工具条里按下「计划」，使其处于开启状态，然后正常描述需求，例如：

在设置页面里加一个账号删除按钮

发送后会发生两件事。第一，代理会读取若干文件（示例场景中读了 6 个），但不会做任何修改。这不是靠提示词里写「先别动」实现的，而是应用本身在计划模式期间拒绝执行写文件类工具和命令执行类工具——读文件、搜索、看网页可以，编辑与执行要等你批准计划之后才放行。第二，你会收到一张标注「等待批准」的计划卡片，卡片右上角有「批准」和「取消」两个按钮。

计划卡片里通常包含：将要修改的文件清单（示例中为 4 个）、明确声明不会触碰的目录（示例中声明不碰 src/billing/，支付记录保留在 Stripe 一侧）、以及一句「目前尚未做任何修改」。

注意一个容易忽略的细节：计划送达时，计划模式会自动关闭。也就是说它只对这一次请求生效，不会一直挂着。

第二步：审阅并批准或取消

读计划时重点看三件事：改动文件的数量是否符合预期、有没有声明不碰的敏感目录、计划里描述的行为是否与你的需求一致。

• 认可内容，按「批准」。此时才会真正编辑那 4 个文件，并执行类似 npm test -- account 的测试命令，测试通过的结果会以 EDIT、TERMINAL 类型的行留在对话里。
• 不认可，按「取消」。文件夹保持原样，你手上留下的是事先对齐过的改动范围和一份「代理看了什么、执行了什么」的记录。

第三步：在陌生代码库里按语义定位实现

刚加入团队时，规格说明看得懂，代码位置却找不到。典型陷阱是：想找「登录多次失败后锁定」的处理，但代码里根本没有出现 lock 这个词，字符串搜索自然搜不到。

解决办法分两段：

1. 先建索引（只需一次）：在「索引」界面把项目文件夹加进去，让它支持按语义检索。
2. 再提问：在该文件夹为对象的 Maestro 对话里直接问，例如「登录失败后锁定的处理在哪里？」

看作业步骤就能知道它是怎么找到的：文件夹检索命中 2 条，随后 READ 了 throttle.ts。答案会指向 src/auth/throttle.ts（第 1–46 行）与 src/routes/session.ts（第 22–61 行），并说明代码里并没有出现「锁定」这个词，实际逻辑是失败 5 次后设置 15 分钟冷却，并在校验密码之前返回 429。

因为答案带文件路径和行号，而且读过哪些文件在步骤行里可见，你可以直接在右侧预览里打开同一处自己核对，不必全盘相信摘要。这类任务不写文件，审批模式保持默认即可。

第四步：在工程师的仓库里只改文案

市场同事写落地页文案，页面本身却在工程师的 React 仓库里，既要对齐 docs/ 下的语气指南，又不能被自动提交。做法如下：

1. 打开输入框下方的「审批模式」，选择「允许与批准」，让每次工具调用前都先问你。
2. 打开沙箱开关。开启后写入不会直接落到工作文件夹，而是放在分支一侧。
3. 提出需求，例如「按文档和语气指南写落地页文案」。

Maestro 会先读 docs/tone.md，检索来源，然后提出对 src/Launch.tsx 的修改。差异会在预览区打开，你确认后接受，再用「导出到分支」交给工程师评审。文案依据哪份指南，会留在「来源」标签里，评审的人也能顺着依据核对。

第五步：撤销某一轮的改动

如果某一轮的修改不想要了，在对话里输入 /rewind，即可把该轮改动过的文件恢复原状。这比手动逐个还原文件更省事，尤其在多轮迭代之后。

一个完整示例

下面把「先看计划再动手」这条主线从头到尾走一遍，场景是给设置页面加账号删除按钮。

前置状态：桌面应用已安装，仓库已克隆到本地，审批模式为默认的自动批准，尚未开启计划。

第 1 步：在输入框上方工具条按下「计划」，确认其处于开启状态。

第 2 步：输入并发送需求。

在设置页面里加一个账号删除按钮

第 3 步：观察作业步骤。你会看到类似这样的行序列：列出 src/ 目录（38 个文件）、grep deleteUser 命中 0 条、READ account.ts、READ users.ts。此时文件系统没有任何变化，因为写文件与执行命令的工具在计划模式期间被应用拒绝。

第 4 步：收到「等待批准」的计划卡片，核对三项内容——待改文件 4 个、不触碰 src/billing/、尚未做任何修改。同时注意计划模式已自动关闭。

第 5 步：按「批准」。此时才发生实际编辑，随后执行 npm test -- account，3 项测试通过。编辑与终端执行分别以 EDIT、TERMINAL 行记录在对话中，点开可看具体输入输出。

第 6 步：在右侧预览区打开差异逐行确认。若发现某一轮改得不合适，在对话里输入 /rewind 回退该轮。

如果第 4 步时你判断方案不对，直接按「取消」，文件夹保持原样，流程到此结束——这也是计划模式的价值所在：错误在动手之前就被拦下。

注意事项

计划按钮与「先出计划」不是一回事

这两个名字很像，作用范围完全不同。输入框上方的「计划」按钮是针对下一次请求的一次性开关，调研并给出计划后就停下。审批模式里的「先出计划」则是这个对话处理工具调用的一条长期规则，是四个审批选项之一。混用会导致预期错位：以为设了审批模式就只影响一轮，或者以为按了计划按钮就长期生效。

计划模式是应用层拦截，不是提示词约束

计划开启期间，不在只读清单里的工具会被应用侧直接拒绝执行。读、搜索、看网页可用，编辑与命令执行不可用。这比在提示词里加一句「先别改」可靠得多，但也意味着你不能指望在计划模式里顺手跑个命令验证环境。

计划送达后模式自动关闭

批准或取消之后，如果还想让下一轮也先出计划，需要重新按下计划按钮，或者改用审批模式里的「先出计划」。

作业步骤太长时的显示切换

步骤多的时候阅读负担不小。可以在「过程详情」设置里在「完整」与「紧凑」之间切换。改变的只是显示方式，执行内容不受影响。

模型选择与可追溯性

默认情况下由 Router 逐轮选择模型，具体哪个模型在干活会出现在作业步骤里。你也可以在输入框处切换模型类型（云端、本地、自托管）；如果希望整段对话固定在一个模型上，改用侧边栏的普通聊天。

与其他几种对话方式的分工

同一屏里还有更轻量的入口，用错会浪费时间和成本：

后续环节的衔接

Maestro 之后的工作可以接到应用的其他功能上：需要带依据的报告用 Research；要在独立分支上跑编码代理用 Code；让文件夹支持语义检索用索引（即第三步用到的功能）；汇总沙箱里的改动用「版本 → 合并站」。

易变信息以官网为准

本文涉及的功能入口、审批模式选项、界面标签名称等，可能随版本更新调整；价格、配额、可用模型等易变信息请以 osFoundry 官网当前公布的内容为准。安装包请从官方下载页面获取，不要使用来源不明的分发渠道。