功能总览

Visual Worktree 的核心模型是：源项目仍保留在原来的仓库目录，需求开发发生在 worktreesRoot/{任务名}/{项目名} 下的 worktree 中。应用把 Git 状态、任务进度、环境检查、链接和桌面快捷操作合到一个本地工作台里。

源码仓库：imberZsk/visual-worktree

任务化 Worktree

Worktree 视图按任务聚合多个仓库。一个需求涉及几个项目，就在同一个任务目录下创建几个 worktree。

这个视图重点解决三个问题：

• 一眼看到某个需求包含哪些仓库。
• 看到每个 worktree 的分支、路径和未提交变更。
• 直接打开 VSCode、终端、Finder、GitLab、复制路径或删除 worktree。

推荐目录结构：

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

创建 Worktree

点击「创建 Worktree」后，输入任务名、选择项目、确认分支名即可批量创建。

创建过程会做这些保护：

• 基于配置里的主分支候选创建新分支，默认支持 main 和 master。
• 跳过 Git hooks，减少 husky 等 hook 因依赖未安装导致创建失败。
• Node 项目可复用源项目 node_modules 软链接，避免重复安装依赖。
• 目标已是合法 worktree 时可复用，不会重复创建。

项目扫描

项目视图扫描源项目根目录下的一级 Git 仓库，并展示当前分支、主分支状态、未提交变更、ahead/behind、远程跟踪分支、fetch 失败状态和关联 worktree。

适合用在两个场景：

• 创建任务前，确认源仓库是否干净。
• 任务收尾后，检查哪些仓库还停在需求分支或有未提交变更。

你可以选择是否自动 fetch。关闭时刷新更快；打开后 behind 判断更准确，但会受网络、VPN 和 SSH 鉴权影响。

批量操作

项目表格支持多选后批量处理。常用动作包括批量切回主分支、批量拉取更新、批量暂存变更。

批量操作逐项执行，并展示进度。单个项目失败不会阻断后续项目，适合一次整理多个仓库的工作区。

建议在这些时机使用：

• 开发前：把相关仓库批量切到主分支并拉取最新代码。
• 提测前：检查是否还有不该存在的本地改动。
• 发布后：把源项目批量恢复到主分支。

任务链接、状态和卡点

每个任务可以维护状态、外部链接和卡点备注。常见链接包括 Jira、需求文档、设计稿、测试用例、发布单和排查文档。

任务状态用于快速判断阶段，内置状态包括未开始、开发中、自测中、待提测、测试中、待发布和已发布。卡点备注适合记录“正在等谁确认”“缺哪个接口”“下一步做什么”。

这些数据都跟随任务保存到本地，不需要把上下文散落在聊天记录、浏览器收藏和临时文本里。

需求流程

流程入口会打开当前任务的步骤面板。步骤可以打勾，也可以配置命令并在任务目录下执行。

流程步骤统一采用 {key,label,command} 模型。command 为空时是普通检查项；不为空时会出现「执行」按钮。命令支持 {path}、{task}、{branch} 等占位符，并会用 shell 引号保护路径和任务名，避免空格、中文、& 等字符拆坏命令。

适合配置成团队真实流程：

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

环境健康检查

环境检查会按任务目录识别项目，并检查依赖、端口、服务连通性和 Git 状态。

检查结果会汇总到任务行上，方便在列表里看到“环境正常”或“存在环境问题”。点开后可以看到每个项目的具体原因和修复建议。

典型检查包括：

• 依赖是否安装，例如 node_modules 是否缺失。
• 开发端口是否可用。
• 声明的外部服务是否存在问题。
• 当前 worktree 是否有未提交改动。

看板视图

看板视图按任务状态分列展示，适合在任务较多时巡检整体分布。

每张卡片会展示任务名、流程进度、卡点和风险标签。它不替代任务详情页，而是用来回答：“哪些任务还没启动？哪些正在推进？哪些已经完成？”

历史任务和清理

任务删除后会写入历史记录，保留任务名、任务状态、需求链接和归档工作文档路径。

历史任务适合解决收尾后的两个问题：

• worktree 目录可以删除，磁盘不继续堆积。
• 后续要找需求链接或工作文档时，还有入口。

清理建议会扫描可安全删除的 worktree，帮助你找出已经回到主分支或不再需要的任务目录。失效 worktree 可以执行 prune 清理。

设置项

设置页集中管理路径、工具、流程、展示和 CI/CD 等配置。

常用设置包括：

• 源项目根目录和 Worktree 根目录。
• 主分支候选，例如 main、master。
• 忽略项目列表和是否自动 fetch。
• VSCode、终端应用、GitLab/CI 链接规则。
• 工作文档模板、流程步骤、环境检查角色。
• 任务标题徽标显示项。

桌面集成

Visual Worktree 是 Electron 桌面应用。渲染层负责界面，主进程负责 IPC 转发和系统能力。它可以调用系统 Git、Finder、VSCode、终端、剪贴板和外部浏览器。

终端支持 macOS Terminal、iTerm2 和 Ghostty。VSCode 默认用新窗口打开，避免替换当前正在看的编辑器窗口。

本地优先

应用默认把配置、任务状态、任务链接、流程进度、卡点、环境检查缓存、历史任务和流程输出保存到：

~/.visualWorktree

仓库内容、任务路径和状态不会上传到远端服务。Visual Worktree 读取本地 Git 状态并组织本地工作流，适合放在内部研发场景里使用。