这篇文章不只介绍功能，而是按第一次使用的顺序走一遍。你可以照着截图完成配置、创建第一个跨仓库任务，并知道每个页面应该重点看什么。

源码仓库：imberZsk/visual-worktree

0. 先准备两个目录​

Visual Worktree 的目录模型很简单：源项目放一处，任务 worktree 放另一处。

~/work/projects/
  frontend-shell/
  api-gateway/
  miniapp-client/

~/work/worktrees/
  FEAT-231 多端结算页联调/
    frontend-shell/
    api-gateway/
    miniapp-client/

源项目目录是你平时维护的本地 Git 仓库集合；worktree 根目录是 Visual Worktree 按任务创建临时工作区的地方。推荐把两者分开，这样主工作区保持干净，需求开发都落在任务目录里。

1. 配置源项目和 Worktree 根目录​

打开右上角「设置」，先填两个必需路径：

• 源项目根目录：存放多个 Git 仓库的目录。
• Worktree 根目录：按任务生成 worktree 的目录。

这里还可以顺手检查主分支名。默认支持 main 和 master，后续批量切回主分支时，应用会自动选择仓库真实存在的那个主分支。

实用建议：

• 源项目目录只放一级仓库，扫描会更清楚。
• 忽略不常用仓库，避免项目列表太吵。
• 日常可以先关闭自动 fetch，刷新会更快；需要精确 behind 状态时再打开。

2. 创建一个跨仓库任务​

回到 Worktree 视图，点击右上角「创建 Worktree」。输入任务名，选择这个需求涉及的项目，应用会在 worktreesRoot/{任务名}/{项目名} 下创建对应 worktree。

这个操作适合在需求刚开始时做。比如 FEAT-231 多端结算页联调 同时涉及 api-gateway、frontend-shell、miniapp-client，创建后每个项目都有独立分支和独立工作区。

创建时可以关注三件事：

• 任务名最好和 Jira、需求单或发布单一致，后面查历史更方便。
• 分支名可以按团队规范填写，例如 feat/settlement-panel。
• Node 项目可以复用源项目的 node_modules 软链接，减少重复安装依赖。

3. 在任务视图里看全局状态​

创建完成后，任务会在 Worktree 视图里按任务聚合。展开任务，可以看到这个需求下每个仓库的分支、路径、未提交变更和快捷操作。

这张图里最值得看的不是某一个项目，而是一整个任务的状态：

• 3 项目 表示这个需求包含 3 个仓库。
• 开发中 是任务当前阶段，可以手动调整。
• 需求链接、Jira 链接会跟着任务展示，回到任务时不用翻聊天记录。
• 1 个环境问题 会提示这个任务目录还没完全准备好。
• 每个项目行右侧可以快速打开编辑器、终端、Finder、复制路径或删除 worktree。

如果你每天要切多个需求，这个视图就是主入口。它回答的是：“这个需求现在牵涉哪些仓库？有没有改动？下一步该处理什么？”

4. 切到项目视图，先把仓库状态扫干净​

项目视图看的是源项目目录里的所有仓库。它适合在创建任务前后确认本地状态：哪些仓库不在主分支、哪些有未提交变更、哪些落后远端。

顶部统计卡片会把关键风险提出来：

• 非主分支：说明仓库还停在需求分支或临时分支。
• 有未提交变更：切分支或删除 worktree 前要小心。
• 可拉取更新：说明本地落后远端，需要 pull。

表格里的「操作」按钮是高频入口。你可以直接打开详情、Finder、VSCode、GitLab、终端，也可以复制路径或置顶项目。对多仓库项目来说，这比在终端里不断 cd 要省很多上下文切换。

5. 多选项目后做批量操作​

当你要整理一批仓库时，先在项目表格里勾选项目，再点「批量操作」。常用动作包括批量切到主分支、批量拉取更新、批量暂存变更。

这一步的价值在收尾阶段尤其明显。比如需求开发结束后，你可以：

• 勾选相关源项目。
• 批量切回 main 或 master。
• 批量拉取远端更新。
• 对临时改动做批量 stash。

批量操作是逐项执行的，单个项目失败不会让整批直接中断。遇到失败时，先点项目详情看错误，再单独处理那个仓库。

6. 用流程步骤管理需求推进​

任务行里的「流程」按钮会打开当前任务的步骤面板。每一步都可以打勾；带命令的步骤还可以直接执行，例如跑测试、构建或自定义脚本。

推荐把流程配置成团队真实会做的动作，而不是写得太理想化。比如：

• 确认需求范围
• 创建多仓库 worktree
• 开发与联调
• 自测与截图
• 发布前检查

这样做的好处是，任务不再只是一堆目录。你能看到它推进到哪一步、还差什么、哪些步骤可以自动执行。对跨仓库需求来说，这比只看 Git 状态更接近真实工作流。

7. 运行环境检查，先发现跑不起来的问题​

点击任务上的环境提示，可以看到环境检查详情。它会按项目列出依赖、端口、外部服务和 Git 状态。

这张图里，frontend-shell 提示 node_modules 未安装，并给出修复建议 运行 pnpm install。同一个面板里还可以看到端口是否可用、服务是否缺失、是否存在未提交改动。

环境检查适合放在两个时机：

• 刚创建 worktree 后：确认依赖、端口、服务是否可用。
• 提测或交接前：确认任务目录不是只有你本机能跑。

8. 用看板做任务巡检​

当任务多起来后，列表不一定好扫。看板视图会按状态把任务放到不同列里，适合每天早上看一眼当前有哪些需求待启动、进行中、已完成。

看板卡片会保留任务名、进度、卡点和风险标签。比如图里的任务进度是 40%，流程完成 2/5，同时还有 有变更 3 的提示。它适合回答：“现在团队或个人手上哪些需求还在推进？哪个卡住了？”

9. 清理后从历史任务找回上下文​

任务完成后，可以清理 worktree 并归档工作文档。清理过的任务会进入「历史任务」，保留任务名、状态、链接和归档路径。

历史任务不是为了让你继续堆积旧目录，而是为了安全收尾：

• 任务目录可以删掉，磁盘空间回收。
• Jira、发布单、工作文档路径还能找回来。
• 后续有人问“上次那个修复在哪”，不需要靠记忆检索。

一条推荐的日常路径​

如果你刚开始用 Visual Worktree，可以先按这条路径跑：

1. 设置源项目根目录和 Worktree 根目录。
2. 创建一个任务，选择本次需求涉及的多个仓库。
3. 展开任务，确认每个 worktree 分支和路径。
4. 在项目视图里扫一遍仓库状态。
5. 开发中用任务流程记录进度和可执行命令。
6. 提测前跑环境检查，把依赖、端口、Git 状态问题处理掉。
7. 任务多时用看板巡检状态和卡点。
8. 发布后归档文档并清理 worktree，再从历史任务保留上下文。

Visual Worktree 不替代 Git，也不替代你的代码编辑器。它更像一个本地任务工作台：Git 继续负责版本控制，VSCode/终端继续负责开发，Visual Worktree 负责把跨仓库需求的状态、路径、流程和风险放到同一个地方。

更多完整能力可以继续看：功能总览。首次运行和开发命令见：快速开始。