用 osFoundry Code 并行运行多个 AI 代理并安全合并分支

osFoundry 是一个桌面应用，把聊天、代理、文件和各类工具收在同一个窗口里。围绕代码，它提供了三个职责不同的界面：Code 让多个 AI 代理在同一个仓库上并行执行任务，每次执行都有专属的 Git 分支和 worktree，差异确认、测试、整合合并预览都走完之后，由你自己决定要不要合并；IDE 用来打开本地文件夹自己写代码，左侧是资源管理器与源代码管理，中间是标签页，下方是终端、输出、问题、测试面板，右侧是能结合当前打开文件作答的助手；Wiki 读取本地仓库，写出带 path:line 出处的文档页面，被引用的代码改动后页面会被打上标记。

可以这样理解三者的定位：IDE 接近「带 Git 面板的 VS Code」，Code 接近「写手全是 AI 代理的拉取请求列表」，区别在于这些分支一步都没有离开你的电脑。Code 与 Wiki 和 Maestro、Model chat、Multi chat、Research 排在同一个标签序列里，IDE 则是侧边栏中的独立条目。

这篇教程面向两类读者：一是想同时把多个互不干扰的任务交给代理、又不想让它们直接动自己工作目录的独立开发者；二是需要在提交前看清 AI 到底改了哪几行、为什么改的团队成员。下面按准备、操作、完整示例的顺序展开，最后列出素材中提到的限制与常见坑。

准备工作

安装桌面应用

Code、IDE、Wiki 三个界面都依赖本地文件夹、Git worktree、shell 和语言服务器，因此必须在 osFoundry 的桌面应用中运行，网页端无法替代。安装包从 osFoundry 的下载页面获取，素材中说明该应用可免费下载；具体版本、系统要求与授权条款请以官网当前信息为准。

准备一个 Git 仓库

Code 的每次执行都会切出独立分支和 worktree，所以目标目录必须是一个 Git 仓库，并且当前分支处于可正常提交的状态。开始之前建议先把手上的改动提交或暂存，避免自己的未提交内容与代理的写入混在一起。

确认测试命令

Code 的合并流程依赖测试结果。默认设置是「要合并分支，测试必须通过」，这个开关可以在设置里修改。因此在动手之前，先确认仓库里存在可用的测试命令，并且它能在干净的 worktree 中跑通——测试是在该次执行专属的 worktree 里运行的，不会污染你自己的检出目录。

了解三个界面的入口

Code：与 Maestro、Model chat、Multi chat、Research 同一排标签。
Wiki：同样在这一排标签中。
IDE：侧边栏里的独立条目，从那里打开项目文件夹。

操作步骤

第一步：在 Code 中发起一次执行

进入 Code 界面，点击「新建执行」，用一行文字写清任务，然后选择要使用的代理。提交之后，应用会为这次执行单独切出一个 Git 分支和一个工作文件夹（worktree）。

这一步的关键在于隔离：如果在同一个文件夹里同时跑多个代理，工作树很容易被搅乱，而 Code 从一开始就把 AI 的工作区隔开，代理碰不到你正在编辑的目录。任务描述尽量写成一句可验收的话，例如「修正金额的取整逻辑」「新增折扣码」「为价格显示补充测试」，这样后续在轨道上区分执行会更直观。

第二步：读懂 Code 界面的五个区域

Code 的主界面可以拆成五块，理解它们各自回答什么问题，后面的操作会顺很多：

轨道顶部的横条：在打开差异之前就告诉你多个代理是否在同一文件上产生了分歧。例如三个执行都改到了 src/cart.js，这里会直接提示。
执行轨道：一行一个执行，显示任务名、新增与删除的行数、耗时和分支名。执行按「待审阅」「需确认」「已折叠的历史」等分组排列，分组依据是「你接下来该做什么」。
中间的对话区：点开某个执行，可以看到你交给代理的指令，以及它在作业过程中说了什么。
右侧面板：包含「变更」「文件」「提交」「审阅」「PR」几个标签，用来查看该执行真实的差异。未提交的改动排在前面，已提交到分支的内容排在后面。
右下角的合并区：选中已完成的执行后，测试和整合合并预览都在这里进行。

第三步：用「一起审阅」横向比对多个执行

当横条提示存在分歧时，勾选相关的几个执行，点击「一起审阅」，就能把它们并排放在一起看。合并区会显示「冲突未确认」「未测试」这类状态——它不会先给你一个绿色的通过标记，而是如实说明「还不知道」。这正是需要你介入的位置。

在下方，冲突文件（例如 src/cart.js）会被打上「冲突」标签，并按分支列出各自的改动片段（hunk）。到这里就能看出，取整修正和折扣码这两个任务都改写了 total()。

第四步：逐个执行运行测试

对每个执行分别点击「测试」。测试在该执行专属的 worktree 中运行，你自己的检出目录保持干净。默认配置下，分支必须通过测试才能合并，这个约束可以在设置中调整。

需要注意，逐个通过并不等于组合起来也能通过。三个执行各自绿灯，只能说明每个改动单独成立，不能说明它们叠加之后仍然正确。所以下一步不能省。

第五步：预览整合合并

点击「整合合并预览」，应用会在一个一次性副本里先试一遍合并，然后返回结果，例如「2 项可以顺利合并，1 项冲突」。只有在你确认合并那些没有问题的分支时，你自己的分支才会真正发生变化。

发生冲突的分支会原样保留，你可以让代理在它的基础上重新修改，也可以换一种方式处理：如果不想按分支整体合并，而是想「各取所长」，可以使用「组合到分支」，逐个挑选改动片段，生成一个新分支。

第六步：在 IDE 中核对 AI 的写入

从侧边栏进入 IDE，打开项目文件夹。界面布局是：左侧资源管理器与源代码管理，中间标签页，下方终端、输出、问题、测试，右侧助手。助手可以从全设备可用的同步聊天开始，也可以使用只留在本机的本地聊天。

源代码管理里，被 AI 最后写入的文件会带一个小机器人标记，下面一行显示模型名和改动理由。点击「审阅」，会打开与「该次写入之前保存的副本」的对比差异，因此你看到的只有这一次改动，而不是整个分支的累积差异。

素材中的示例很能说明问题：某次改动把超时从 30 秒缩短到 3 秒，而紧邻的注释写着「大图片上传需要 20 秒以上」。这类问题在提交前发现，和提交后再返工，代价完全不同。

如果代理写入的文件正好有你未保存的编辑，应用不会默默替你选一边，而是询问你要「保留自己的内容」还是「使用磁盘上的版本」。

第七步：用代码图判断改动影响面

要修改一个公共函数（例如 formatPrice）的规格时，先右键该函数，选择「显示代码图」，可以看到调用方与被调用方的清单。实心点表示从代码中直接读到的调用，空心点表示推断结果，空心点建议自己再确认一遍。

「改动的影响」会继续向上追溯调用方的调用方，示例中显示为「15 个符号、14 个文件、3 个测试」。点击某一行可以跳到对应位置，也可以用「发送到聊天」把整张图交给助手。

第八步：用 Wiki 从代码生成文档

Wiki 面向的是「不打算改代码、但需要理解代码」的人，例如新加入的成员，或经常被问规格的支持人员。设计文档长期不更新而失效是常见问题，Wiki 以代码为起点写页面，正面处理这个问题。

在 Wiki 中选择「打开文件夹」，或选择「克隆公开仓库」（支持 https:// 与 git@ 形式的 URL），应用会在本地读取项目结构。在向项目写入任何内容之前，它一定会先征求确认，并直接显示将要创建的文件夹路径；选择「现在不做」则什么都不会写入。

同意之后，用「生成页面」批量生成，或用「创建页面」指定一个主题单独生成。设置里有两个维度可选：每页交给模型多少源码（深度：快速、标准、深度），以及验证多少描述（验证：关闭、抽样、全部）。素材提到，选择「全部」时费用大约是两倍；生成前会显示费用，可以先看估算再决定是否继续。价格与计费方式请以官网当前信息为准。

每个页面都带 path:line 出处，点击即可在 IDE 中打开对应行。一个月后，如果轨道上的页面出现「本页引用的文件在页面创建后被修改过」的标记，那就是重新生成之后再读的信号。零散的问题可以在页面旁边的聊天里问，回答同样带该项目的 path:line；也可以用自然语言直接要求写页面，例如「写一页关于重试策略的说明」。

页面本身就是仓库里的 Markdown 文件，因此可以和代码走同一个拉取请求来审阅。

第九步：把执行交给团队

当 Code 中的执行准备就绪，点击「创建 PR」，即可为该分支打开拉取请求。三个界面之间也可以互相跳转：点击 Wiki 的出处会跳到 IDE 的对应行，IDE 里的「此文件夹的 Wiki」可以回到 Wiki。IDE 的助手与 Wiki 页面旁的聊天都基于 Maestro，使用方式与其他 Maestro 聊天一致。如果希望按语义而不是精确词去搜代码，可以先在索引界面建立本地搜索索引，Maestro 会用它来查找。

一个完整示例

下面把前面的步骤串成一个可复现的最小流程。场景是一个小型电商站点，需要同时处理三件事：修正金额取整、新增折扣码、为价格显示补充测试。

准备：确认仓库干净，测试命令可用，安装并打开 osFoundry 桌面应用。
发起三个执行：在 Code 中点击「新建执行」三次，分别填写「修正金额取整逻辑」「新增折扣码」「为价格显示补充测试」，每次选择一个代理。三次执行各自获得独立分支与 worktree。
等待完成：三个执行都返回「已完成」。此时不要急着合并，先看轨道顶部横条——它提示三个执行在 src/cart.js 上存在分歧。
一起审阅：勾选三个执行，点击「一起审阅」。合并区显示「冲突未确认」「未测试」。下方 src/cart.js 被打上「冲突」标签，按分支列出改动片段，可以看到取整修正与折扣码都改写了 total()。
逐个测试：对每个执行点击「测试」，三次都在各自的 worktree 中运行，全部通过。记住这只证明单独成立。
预览整合：点击「整合合并预览」，返回「2 项可以顺利合并，1 项冲突」。确认合并这两项之后，你的分支才第一次发生变化；冲突的折扣码分支原样保留。
处理冲突：让代理在保留的分支上重新修改，或者使用「组合到分支」，从各分支中逐个挑选改动片段，生成一个新分支。
IDE 复核：在 IDE 中打开项目，源代码管理里带机器人标记的文件逐个点「审阅」，只看该次写入的差异。若发现某处把超时从 30 秒改成 3 秒而注释说明上传需要 20 秒以上，就在提交前退回修改。
影响面检查：右键 formatPrice，选择「显示代码图」，查看调用方清单与「改动的影响」统计，必要时用「发送到聊天」把图交给助手讨论。
出 PR：确认无误后，在 Code 中对相应执行点击「创建 PR」。

如果这个仓库还需要给新成员看，就在 Wiki 中打开同一文件夹，先确认写入路径，再选择「生成页面」。深度选标准、验证选抽样，先看费用估算再生成。生成后逐页检查 path:line 出处是否指向你预期的代码。

注意事项

必须使用桌面应用：Code、IDE、Wiki 依赖本地文件夹、Git worktree、shell 与语言服务器，网页端无法完成这些操作。
代理不会自行合并：每次执行都在专属分支与文件夹中运行，只有你按下合并，自己的分支才会改变。默认设置下，只有通过测试的分支才能合并，该约束可在设置中修改。
逐个通过不等于组合通过：每个执行单独测试通过，不能推出叠加后仍然正确，整合合并预览这一步不能跳过。
冲突分支不会消失：冲突的分支会保留，可以在此基础上让代理重做，或用「组合到分支」挑选改动片段。
应用中断后的状态：长时间作业中如果应用停止，该执行不会被一直挂在「运行中」，而是回到「中断」状态，并显示分支已保留。
未保存编辑的冲突：代理写入你正在编辑且未保存的文件时，应用会询问保留自己的内容还是使用磁盘上的版本，不会静默选择。
推断结果需人工确认：代码图中的空心点属于推断，实心点才是从代码直接读到的调用，空心部分建议自己核对。
Wiki 不是团队协作文档工具：它从代码仓库出发、带文件与行号出处写文档，并在代码变化后给页面打标记，适合架构概览与上手资料，不适合当作通用的团队知识库。
Wiki 写入前有确认：向项目写入任何内容前都会显示将要创建的文件夹路径，选择「现在不做」则不会写入。
Wiki 的费用与验证强度相关：验证选「全部」时费用约为两倍，生成前会显示估算；具体价格与计费规则请以官网当前信息为准。
页面会过期：页面引用的文件在创建后被修改时会出现标记，此时应重新生成再阅读。
克隆公开仓库的 URL 形式：支持 https:// 与 git@ 两种写法。