Git 与工作树

git 页面、在任意窗格切换分支,以及让智能体互不干扰的每会话工作树。

git 页面#

⇧⌘G 打开一个类似 GitHub Desktop 的页面:

  • 切换仓库与分支。
  • fetch(⇧⌘T)、pull、push(⌘P)、刷新(⌘R)。
  • 逐文件查看差异,暂存你选中的内容并提交(⌘↩)。
  • 浏览历史,合并分支。

Agentty 使用的是你自己的 git,连同你的配置与凭据。所有命令都以非交互方式运行,因此不会卡在你看不见的提示上 —— 如果某次 push 需要凭据助手无法提供的信息,它会带着错误信息失败,而不是一直悬着。当 git 自己无法登录 GitHub(git@github.com: 远程的 SSH 密钥被拒绝——这台电脑的密钥没有登记——或 https://github.com/ 远程没有保存的凭据)而 GitHub CLI 已登录(设置 → 集成 → GitHub)时,Fetch、Pull 和 Push 会用 gh 的登录通过 HTTPS 再试一次。远程地址和你的 git 配置保持不变。

从窗格直接操作#

点击任意窗格标题中的分支名,就能在不离开终端的情况下切换分支、pull、push 或复制名称。

右键点击列表中的分支可使用更多操作:切换到此分支、重命名…、从此处新建分支…、复制名称和删除分支。含有尚未合并到任何地方的提交的分支,要再确认一次才会删除,对话框也可以同时删除它的远程副本(同时删除服务器上的 …);在服务器(远程)上删除会在确认后为所有人删除远程分支。Git 一次只能在一个文件夹中打开同一分支:当切换因另一个文件夹正在使用该分支而被拒绝时,Agentty 会提供打开那个文件夹,而不是静默失败。

用 AI 解决#

当合并因冲突而停止、分支与上游分支已分叉而无法 pull,或仍有待解决的冲突时,提示中会出现用 AI 解决。它会在仓库中打开 Claude Code;没有的话打开 Codex 或已安装的其他智能体,并附上处理冲突的说明。没有安装任何智能体时,只会在仓库中打开一个终端。已有合并在进行时,不会再开始另一个合并。

每个会话一个工作树#

当你在已有会话正在工作的项目中再开一个 AI 会话时,Agentty 会询问它从哪里开始:新建工作树 会在从项目默认分支切出的新分支的独立 git 工作树中启动,两个智能体不会改到同一批文件;打开现有工作树 则只在同一个工作树中开始新会话,适合想让两个会话一起查看或处理同一分支的时候。在终端里直接输入 claude 或 codex 也会出现同样的询问。

  • 工作树位于 ~/.agentty/worktrees/ 下,分支名为 agentty/<名称>。
  • 若你希望所有会话都在同一个文件夹,可在设置 → 常规中关闭。

工作原理#

Agentty 以新分支 agentty/<名称> 执行 git worktree add,基准是项目的默认分支,而不是项目文件夹当前检出的分支 —— 这样一个会话就不会建立在另一个会话尚未合并的工作之上。

工作树创建在项目之外的 ~/.agentty/worktrees/<项目>-<路径哈希>/<名称>/。不放进项目文件夹很重要:如果代码副本在里面,所有搜索、文件监视和构建都会一并遍历那份副本。

Agentty 只会删除该目录下的工作树。你自己创建的工作树只会被列出,不会被动。

文件面板#

⌥⌘B 把项目树停靠在终端旁。它还会列出项目的每一个工作树、谁在其中工作以及那里改了什么。

点击某个工作树即可查看其中的文件;若已有会话在其中工作,还会跳转到那个终端。

其余操作在右键菜单里:跳转到正在工作的终端、打开新终端、在文件管理器中显示该文件夹、复制路径,或删除该工作树。被手动删掉文件夹的工作树,也可以从同一菜单中清理。

删除会先询问。对话框会写明分支名,以及随之消失的内容:工作树及其文件夹;若选择的是删除工作树和分支,还包括本地分支。如果该分支曾被推送,对话框会一并询问是否删除远程上的分支——该选项默认关闭,且只有本地分支确实被删除后,远程分支才会被删除。无论哪种方式,是否安全都由 git 判断:有未提交更改的工作树会保留,含有别处没有的提交的分支也会保留。

仍有标签页在其中工作的工作树不会被删除:菜单中根本不会出现删除项,用其他方式删除也只会如实说明,而不会询问。请先关闭该标签页。

面板中的工作树列表#

工作树区域列出该窗格所在仓库的工作树。在包含多个项目的文件夹(例如主目录)中,它会列出其下所有有工作树的项目:按项目分组,每组可折叠,最近工作过的项目排在最前,组内先是项目文件夹,再是按时间从新到旧的工作树。每一行都会显示该工作树最后一次工作的时间(最后一次提交或最新的未提交更改)。只有面板打开时才会扫描这些文件夹,该区域可拖动调整大小,刷新按钮会重新扫描。

有工作树时,文件按钮会变成紫色并显示数量。

双击工作树,或右键选择在此终端中打开,即可用当前 shell 继续在那里工作(会先询问)。清理并回到项目文件夹会删除该工作树并让终端回到项目:分支已合并且没有未提交内容时立即执行,否则对话框会准确说明将丢失什么。只要有智能体、忙碌的 shell 或其他窗格正在该工作树中工作,就会被拒绝。

如果 shell 所在的工作树文件夹被删除,它会回到项目文件夹,而不是停在已不存在的文件夹里。

删除时会保留什么#

只有默认分支已包含某分支的全部提交时,该分支才会随工作树一起删除。含有默认分支中没有的提交的分支会保留——即使已经推送过——监控中的工作树管理页面也是如此。被忽略的构建文件夹(build/、out/、dist/、.cache/、coverage/)按其中的文件来判断:里面有文件就会先询问,而 target/、node_modules/ 之类仍照旧直接删除。

并行任务#

让智能体自己拆分工作即可 —— “并行做 A、B、C”。它会向 Agentty 提出请求,你确认一次,每个任务就在各自的分屏窗格和独立工作树中开始。

每一次这样的请求都要你确认;智能体无法自行开启窗格。

文件编辑器#

在文件面板中点击文件,它会在终端旁打开:常见语言的语法高亮、成对输入的括号和引号(匹配的括号会框出)、用 ⌘/ 注释行、用 ⌥↑ / ⌥↓ 移动行、撤销与重做、⌘S 保存,以及用你已安装的格式化工具(Prettier、google-java-format、ktlint、rustfmt、gofmt、Black)整理的 ⇧⌥F,没有时由语言服务器整理。在 设置 → 项目 → 文件编辑器 中开启 保存时格式化文件 后,⌘S 会先格式化再保存。

图片(PNG、JPEG、GIF、WebP)会缩小到合适大小,以预览方式打开。智能体改动过的文件会自动重新加载。右键点击文件标签页打开的菜单(还可关闭其他文件、复制路径、在文件管理器中显示)中的 在编辑器中打开 会把文件交给 VS Code、Cursor 或系统编辑器。文件只会被读写,绝不会被执行。 在 git 仓库中,自上次提交以来改动的行会在行号栏中标出:新增为绿色,修改为蓝色,删除处为红色标记。 点击标记可查看提交时的行,按 还原 即可恢复。 浏览较长的类或函数内部时,其首行会固定在视图顶部(粘性滚动)。 在终端中 ⌘-点击 路径即可在此打开;如果输出中带有行号和列号(如编译器或智能体写出的 src/app.ts:42:7),会直接跳到该位置。

表格与文档#

CSV 和 TSV 文件以表格打开。双击单元格、按 Enter 或直接开始输入即可编辑;拖动选择一个区域,可以按电子表格使用的格式复制和粘贴。⌘F 筛选行,列标题上的箭头按该列排序(再点一次反向,第三次恢复文件原来的顺序);两者都只改变显示的内容。拖动标题边缘调整列宽。右键可以插入或删除行和列。分隔符会自动识别,也可以更改;可以选择第一行是否作为标题,工具栏可以切换回纯文本。保存时只改写你修改过的单元格,因此撤销和智能体的修改与普通文本文件一样。

Excel 工作簿(.xlsx、.xlsm)以同样方式打开,每个工作表一个标签。单元格编辑、粘贴和新行会保存到工作簿中,并保留每个单元格的格式;Excel 打开文件时会重新计算公式。含有共享公式或数组公式的单元格不能在这里修改,为避免破坏公式中的引用,工作簿中不能插入或删除行和列。.xls、.xlsb 和 .ods 以只读方式显示。

Word 文档(.docx)显示为带有标题、粗体和斜体、列表和表格的页面。点击段落即可编辑:Enter 开始下一段,⇧Enter 换行,⌘S 保存。只有你修改过的段落会被改写;含有图片、链接、域或修订的段落只显示,不能编辑。

也可以从访达用 Agentty 打开这些文件。第一次打开默认由其他应用打开的文件时,会出现一个栏询问是否让 Agentty 成为这类文件的默认应用;设置 → 系统 中也可以按类型选择。

在代码中跳转#

适用于 Kotlin、Java、JavaScript、TypeScript、Python、HTML、CSS(含 Tailwind)、Rust 和 Go:

⌘P按名称转到文件。输入 @ 查看本文件的符号,# 查看项目的符号,: 转到某一行,% 搜索项目文件中的文本
⇧⌘F在项目的所有文件中搜索文本(即上面输入框的 %),以所选内容或光标处的名称开始。输入大写字母后区分大小写;有未保存更改的文件按屏幕上的内容搜索
F12 或 ⌘-点击转到光标下名称的定义(按住 ⌘ 悬停在名称上可直接预览定义)。在 import 路径上则打开该文件;在定义本身上则列出它的用法
⇧F12 或 ⌥F7项目中使用该名称的所有位置
⌘F12转到实现:实现接口的类、重写方法的位置(需要语言服务器)
F8 / ⇧F8转到文件中的下一个 / 上一个问题,并显示其消息
⌃Space自动补全(输入名称或在 . 之后也会自动打开;按 ↩ 或 ⇥ 插入,Esc 关闭)
补全后的 ⇥跳到下一个待填位置(参数、属性值),最后跳到末尾
输入 Emmet 缩写(ul>li.item*3)后按 ↩在 HTML 和 .tsx、.jsx 文件的标记中作为第一个补全出现,展开为标签(JSX 中为 className);⇥ 依次跳到空位
F2在所有使用处重命名光标下的名称(没有语言服务器时仅限此文件)
⇧⌥O整理 import:排序并删除未使用的(需要语言服务器)
⌘.语言服务器在此处提供的快速修复和重构(行号栏中的灯泡表示该行有可用修复)
⇧⌘O / ⌥⌘O / ⌃G本文件的符号 / 项目的符号 / 某一行
⌃- / ⌃⇧-在跳转过的位置之间后退、前进

定义按名称在项目文件中查找(遵循 .gitignore,跳过依赖和构建文件夹),无需安装任何东西。同一名称在多处定义时,全部列出,最近的排在前面。

安装了该语言的语言服务器时,编辑器会改为询问它:直接跳到正确的定义,只列出真正的用法,按住 ⌘ 悬停在名称上时还会显示其类型或签名。打开该语言的文件时,语言服务器会从文件所属项目的文件夹(Cargo.toml、go.mod、package.json、pyproject.toml 或 Gradle、Maven 构建所在处)自动启动,因此大型仓库中子文件夹里的项目也能正确读取:

语言语言服务器(需在 PATH 中)
Rustrust-analyzer(rustup component add rust-analyzer)
Gogopls
TypeScript、JavaScript项目或你安装的 TypeScript 7(tsc),或 typescript-language-server
Pythonpyright(pyright-langserver)、basedpyright 或 pylsp
Javajdtls
KotlinJetBrains 的 kotlin-lsp(brew install JetBrains/utils/kotlin-lsp)
CSS, SCSS, Less, HTML, JSONvscode-css-language-server、vscode-html-language-server、vscode-json-language-server(npm install -g vscode-langservers-extracted)

语言服务器仍在读取大型项目,或没有找到结果时,编辑器会像上面那样按名称查找。rust-analyzer 在关闭构建脚本和过程宏的情况下运行,因此打开项目不会运行其中的代码;语言服务器不会以运行项目自身代码的方式启动:只有当项目的 TypeScript 是你用包管理器安装的(git 不跟踪 node_modules)时才会使用它;jdtls 启动时关闭 Gradle 导入,并且只有在该项目的状态栏中点击 读取构建 后才读取 Maven 项目的构建(读取构建会运行 pom.xml 指定的插件和扩展;在此之前只读取文件本身的内容并显示语法错误;已允许的项目可在 设置 → 项目 → 语言服务器 中全部取消);kotlin-lsp 通过运行 Gradle 或 Maven 构建来读取项目,因此只有在该项目中点击 读取构建 后才会启动(没有构建文件的文件夹不会读取)。

语言服务器还会在你输入时报告问题:错误显示红色波浪线,警告为黄色,提示为蓝色,行号和滚动条上的标记也使用相同颜色;指针停留在上面会显示消息。 错误和警告的消息也会显示在该行末尾(可在 设置 → 项目 → 文件编辑器 中关闭)。 文件标签的名称会显示为其中最严重的错误或警告的颜色。状态栏会显示该文件的错误和警告数量,按 F8 可转到下一个问题。rust-analyzer 不会构建项目(cargo check 保持关闭),只报告它能直接发现的问题。 当语言服务器能修复某个问题时(例如 Add import from "./bad"),光标所在行的行号栏会出现灯泡,消息下方也会列出修复。按 ⌘. 可列出光标或所选内容可用的全部修复和重构。语言服务器报告名称未知时(undefined: Totl、Cannot find name 'onlyInStok'),还会列出文件和项目中拼写最接近的名称,例如 改为 'Total',无需 AI 即可直接修正。修复会一次性修改已打开的文件,按一次 ⌘Z 即可撤销;未打开的文件会直接保存修改。 点击问题消息下方以及 ⌘. 列表末尾的 用 AI 修复,会把问题所在位置和语言服务器的消息交给已连接的会话。 点击状态栏错误数量旁的闪光图标,会把所有已打开文件中的错误一次性交给它。 输入时,语言服务器的补全列表会显示在光标下方,选择其他文件中的名称时会一并添加其 import;没有语言服务器时则提供文件中的单词。 输入函数调用时,行的上方会显示其签名,并突出显示正在输入的参数。 将指针在名称上停留片刻会显示其类型或签名;点击状态栏中的错误数量,会连同代码列出所有已打开文件中的问题。

编辑器底部的状态栏会显示当前文件的语言服务器。未安装时显示 安装 …:点击后会在新的终端标签页中运行该语言服务器的官方安装命令(rustup、go install、npm 或 Homebrew);若这台电脑缺少该命令所需的工具,则打开其官方页面。设置 → 项目 → 语言服务器 列出全部语言服务器,并可逐个开启或关闭(关闭后立即停止)。在 Agentty 运行期间安装的语言服务器会自动接管。语言服务器在这台电脑上运行,代码不会发送到任何地方。

在代码旁与智能体一起工作#

点击编辑器栏中的 连接会话,智能体的终端会出现在代码右侧(拖动边缘调整宽度)。默认是当前标签页的智能体,也可以在该栏中选择其他会话。会话在等待你批准权限或回答问题时,栏中的标签会提示,点击即可查看。

  • 选中代码 后会出现 让 AI 修改、复制、转到定义、查找用法 小栏。在 让 AI 修改(或 ⌘K)中写下的指令,会连同文件和所选行范围一起发送给已连接的会话。
  • 在 diff 中同样可以。 在已更改文件的 diff(文件面板的更改标签)和 AgentGit 中,拖动即可选择代码,行号和 +、- 不会被选中。选择结束处会出现复制(或 ⌘C)和让 AI 修改(或 ⌘K)。⌘A 选择整个 diff,双击选择单词,三击选择一行。从已更改文件的 diff 发出指令时,会话会显示在旁边,智能体更改文件后 diff 也会随之更新。已删除的行不在文件中,提交中的行也可能不在,因此这些行的内容会随指令一起发送。
  • 看到智能体在工作。 智能体修改文件时,改动的行会亮起再渐隐,光标处显示智能体的名称(Claude-3f9a)。Claude Code 还会在写入前显示位置。多个会话可以同时工作,每个会话都有自己的光标和栏中的标签,点击标签即可跳到那个文件的那个位置。
  • 跟随(栏中的眼睛图标)开启后,智能体将要修改的文件会在该位置显示到前面(未打开则打开)。它不会抢走键盘焦点,你输入时会等待,终端在前面时什么也不做。在可见范围上方或下方工作的智能体会固定显示在相应边缘,点击即可滚动过去。
  • 让 AI 修改 的行会一直标记,直到智能体改动它们。⌥↩ 只发送问题(告诉智能体不要修改文件)。
  • 审阅智能体的改动。 智能体在已打开文件中的每处改动,都会在行号栏留下智能体颜色的竖条,并在文件标签上显示圆点。底部栏可逐一查看改动:撤销(恢复到智能体改动之前并保存,可用 ⌘Z 撤回)、保留(清除标记)、全部保留。对比 会同时显示改动前和现在的行,栏中的 N 处改动 会连同代码列出所有已打开文件中的改动,⌥F5 / ⇧⌥F5 跳到下一处或上一处改动。智能体再次修改同一行时会合并为一处改动。
  • 你的编辑是安全的。 智能体写入你有未保存编辑的文件时,若改动在不同的行会自动合并,只有改到同一行时才会询问。智能体在上方插入行时,光标和视图仍停留在你正在看的代码上。
  • 代码上方的栏显示光标所在位置(ApiClient › save),点击即可跳转。在定义或用法列表中,所选位置附近的代码会显示在旁边。