开发工具版本控制【免费下载链接】vscode-gitlensSupercharge Git inside VS Code and unlock untapped knowledge within each repository — Visualize code authorship at a glance via Git blame annotations and CodeLens, seamlessly navigate and explore Git repositories, gain valuable insights via rich visualizations and powerful comparison commands, and so much more项目地址https://gitcode.com/gh_mirrors/vs/vscode-gitlens点击查看免费下载本篇指南讲解 vscode-gitlens 仓库为 AI AgentClaude Code定制的一套 git worktree 开发隔离约定worktree 统一创建在主仓库的兄弟目录repo-name.worktrees/下通过「先git worktree add创建、再EnterWorktree({ path })切换」的两步流程完成隔离开发。读完本文你将掌握这套目录与分支命名规范、完整的创建/进入/退出命令序列以及为何不能使用EnterWorktree({ name })直接创建工作区的底层原因并能将同一套约定复用到其他大型 TypeScript 仓库的 Agent 开发流程中。为什么 GitLens 需要自定义 worktree 约定vscode-gitlens 是一个体量很大的 VS Code 扩展仓库包含packages/gitlens/*、gitkraken/*多包工作区与src/两个主要代码区域还有大量 webview 应用。对这样的仓库Agent 在实现功能分支时如果直接在主工作区改代码很容易污染正在进行的其他任务。因此该仓库在 AGENTS.md 的 Git Repository Guidelines 中明确了分支命名规则并通过.claude/skills/worktree/SKILL.md定义了一套专门面向 Agent 会话的 worktree 约定worktree 位于主仓库的兄弟目录repo-name.worktrees/即.claude/hooks/worktree.mts钩子围绕的布局不是EnterWorktree原生的默认位置目录在仓库之外天然不需要.gitignore处理也不会被 git 跟踪worktree 内分支按类型前缀组织便于按「功能/缺陷/技术债」快速定位。这套约定与产品端 GitLens 扩展的 worktree 能力相互呼应在 src/commands/git/worktree/create.ts 的确认步骤中推荐路径的规则同样是「选在仓库外则生成chosen-path/repo.worktrees/branch选在仓库内则提升为repo/../repo.worktrees/branch」可见repo-name.worktrees兄弟目录是该项目的统一心智模型。目录约定兄弟目录 类型分层 会话标识worktree 统一放在主仓库的同级目录中命名为repo-name.worktrees/内部按分支类型再分层vscode-gitlens/ # 主仓库primary worktree vscode-gitlens.worktrees/ # worktrees 根目录 ├── debt/ │ ├── library/ # 分支debt/library │ ├── librarysession-idagent-x/ # 从 debt/library 派生的 Agent worktree │ └── refactor-home/ # 分支debt/refactor-home ├── feature/ │ ├── ai-chat/ # 分支feature/ai-chat │ └── graph-actions/ # 分支feature/graph-actions └── bug/ └── graph-performance/ # 分支bug/graph-performance三个关键规则分支路径段直接映射为目录嵌套debt/library→debt/library/feature/ai-chat→feature/ai-chat/。这样从目录结构就能一眼看出对应的分支类型与分支名。Agent worktree 使用作为分隔符格式为branchsession-idagent-name。它作为父 worktree 的同级sibling存在而不是嵌套在父 worktree 内部session-id用于按对话会话分组方便追溯该 worktree 源自哪一次 Agent 会话。会话粒度隔离同一个父分支下可以并行存在多个 Agent worktree例如librarysession-aagent-1与librarysession-bagent-2互不干扰。该命名逻辑与 hook 的实现完全一致。在 .claude/hooks/worktree.mts 中路径拼接为const worktreesRoot join(repoRoot, .., ${repoName}.worktrees); const branchSegments branch.split(/); const lastSegment branchSegments.pop()!; const worktreeName ${lastSegment}${session_id}${name}; const targetPath join(worktreesRoot, ...branchSegments, worktreeName);即取当前分支的最后一层作为基准名前面各层作为目录层级最后附加session_idagent_name。分支命名规范SKILL.md 要求遵循 AGENTS.md 中的分支指南具体前缀如下类型前缀示例功能Featurefeature/feature/search-natural-language缺陷修复Bug fixbug/bug/graph-performance技术债Tech debtdebt/debt/library关联 Issue分支名内包含#Nfeature/#1234-search-natural-language要点分支一般从main切出需要堆叠stacking时也可以从另一个功能分支切出分支名要有描述性直接反映要解决的问题如果存在关联 issue把 issue 号写进分支名放在类型前缀之后、描述之前。创建并进入 worktree 的两步流程由于目录约定偏离EnterWorktree默认位置SKILL.md 规定流程必须拆成两步先创建、后进入。创建侧用标准 git 命令完成进入侧用EnterWorktree原语切换会话工作目录在 Bash 里单纯cd无法改变 Agent 会话的工作目录。# 1. 计算 worktrees 根目录 REPO_ROOT$(git rev-parse --path-formatabsolute --git-common-dir | sed s|/.git$||) REPO_NAME$(basename $REPO_ROOT) WORKTREES_ROOT$REPO_ROOT/../$REPO_NAME.worktrees # 2. 创建 worktree分支路径段映射为目录嵌套 git worktree add $WORKTREES_ROOT/type/name -b type/name # 3. 安装依赖pnpm 的全局 store 是热的这一步很快 pnpm install --dir $WORKTREES_ROOT/type/name随后用EnterWorktree原语切换进刚创建的路径EnterWorktree({ path: absolute path to $WORKTREES_ROOT/type/name })理解两点EnterWorktree要求传入绝对路径且该路径必须已存在于git worktree list输出中——这正是「先创建、后进入」顺序的根本原因切换完成后该会话后续的所有工具调用都将在 worktree 目录内执行主仓库保持干净。为什么禁止用 EnterWorktree({ name }) 创建SKILL.md 特别强调不要用EnterWorktree({ name })来创建 worktree。原因在文档中写得很清楚——在 git 仓库内调用时它会忽略自定义 hook把 worktree 放到.claude/worktrees/该目录未被 gitignore并且从origin/main切分支从而破坏项目的目录约定。对照 hook 配置可以验证这一点.claude/settings.json 中注册了WorktreeCreate事件钩子执行node .claude/hooks/worktree.mts create超时 60 秒。也就是说只有当创建动作经由该 hook 路径发生时才会落入repo.worktrees/兄弟目录约定。EnterWorktree({ name })走的不是这条路因此产物位置和分支来源都不符合约定。正确姿势永远是git worktree add创建 →EnterWorktree({ path })进入。离开 worktree任务完成或需要回到原仓库时调用ExitWorktreeExitWorktree({ action: keep })必须使用action: keep原因与创建路径对称ExitWorktree不会移除通过path进入的 worktree它只会清理自己用name创建的那类所以keep在这里是正确且无破坏性的选择worktree 与其分支保留在磁盘上之后如需清理用标准的git worktree remove手动移除即可若存在未提交改动可追加--force。这与 hook 的移除逻辑一致在 .claude/hooks/worktree.mts 中WorktreeRemove事件先尝试git worktree remove失败时捕获错误并用--force重试。Setup 注意事项SKILL.md 明确要求跳过测试基线验证skip test baseline verification。理由是该项目构建非常昂贵应在实现完成之后再统一验证而不是在 setup 阶段就为每个 worktree 跑一遍测试基线。这与 AGENTS.md 中把pnpm run build、pnpm run test、pnpm run check列为常规开发命令但并不要求在初始化阶段执行的定位一致——worktree 初始化只做pnpm install把耗时操作推迟到实现阶段。与默认 Superpowers Skill 的关键差异SKILL.md 在结尾总结了本项目约定与默认 Superpowers 工作流 skill 的四点差异可直接作为迁移清单维度本项目约定默认 Superpowers 行为worktree 位置仓库外部的兄弟目录repo.worktrees/仓库内部.gitignore验证不需要目录在仓库外需要验证创建方式先git worktree add再EnterWorktree({ path })用EnterWorktree({ name })创建测试基线跳过构建太慢不适合 setup 阶段通常先跑基线其中「创建方式」的差异是最容易踩坑的一点一旦用EnterWorktree({ name })创建就会绕过WorktreeCreatehook见 .claude/settings.json与 .claude/hooks/worktree.mts 中实现的branchsession-idagent-name命名与pnpm install自动依赖安装逻辑。配套 Hook 实现解析为了让约定落地仓库在 .claude/hooks/worktree.mts 中实现了WorktreeCreate/WorktreeRemove两个事件的钩子逻辑要点创建create读取标准输入中的 JSON 事件负载session_id、name、cwd等通过git rev-parse --path-formatabsolute --git-common-dir定位主仓库根目录并剥掉/ .git后缀得到repoRoot与repoName再取当前分支名git rev-parse --abbrev-ref HEAD拼出worktreesRoot/type/last-segmentsession-idagent-name路径mkdirSync预建父目录后执行git worktree add targetPath -b worktree-session-id-agent HEAD随后自动运行pnpm install最后把目标路径写到标准输出供 Agent 读取。移除remove先尝试git worktree remove path若因未提交改动失败捕获异常后改用--force重试。配置两个事件钩子在 .claude/settings.json 中注册创建超时 60 秒、移除超时 30 秒。这套 hook 与 SKILL.md 构成完整闭环skill 告诉 Agent「怎么建、建在哪」hook 保证「建出来的一定符合约定、依赖自动装好」。与其他技能文档的配合worktree 隔离是 GitLens 仓库 Agent 开发工作流的物理基础它与仓库内其他规范配合使用AGENTS.md 规定技能产物目标、计划、评审、实测记录统一放在主 worktreevscode-gitlens/.work/下一个被 gitignore 的.work/根目录里绝不要放进功能 worktree——因为.work/不跨 worktree 共享写进功能 worktree 的文档在其它任何地方都不可见docs/triage-dev-skills.md 给出了.work/下的具体布局triage/、dev/、reviews/、live/、design/等子目录及其写作者同一仓库下还维护了a11y-*、commit、review、investigate等一批技能见 .claude/skills/worktree 负责让这些技能的产出互不污染。简而言之worktree 约定解决「在哪干活」.work/约定解决「产出放哪」二者共同保证多个 Agent 会话可以并行推进互不干扰同时所有可追踪的中间产物仍集中在主仓库可访问的位置。赞分享开发工具版本控制【免费下载链接】vscode-gitlensSupercharge Git inside VS Code and unlock untapped knowledge within each repository — Visualize code authorship at a glance via Git blame annotations and CodeLens, seamlessly navigate and explore Git repositories, gain valuable insights via rich visualizations and powerful comparison commands, and so much more项目地址https://gitcode.com/gh_mirrors/vs/vscode-gitlens点击查看免费下载相关推荐qwen-code Worktree 功能端到端测试全解析从 EnterWorktree 工具到 Agent 隔离与过期清理qwen code Worktree 功能端到端测试全解析从 EnterWorktree 工具到 Agent 隔离与过期清理 导读 本文以 qwen code人工智能AI Agent代码智能体工具调用交互助手CLIQwenGitLens 仓库提交规范实战指南基于 .claude/skills/commit/SKILL.md 的 Agent 提交工作流GitLens 仓库提交规范实战指南基于 .claude/skills/commit/SKILL.md 的 Agent 提交工作流 导读 本文以 GitLe开发工具版本控制Homebrew/brew 仓库 Agent 协作规范验证工作流、Sorbet 类型约束与测试纪律Homebrew/brew 仓库 Agent 协作规范验证工作流、Sorbet 类型约束与测试纪律 Homebrew/brew 仓库的根目录文档 AGENTSCLI包管理器上一篇Primitive FTPd 安装与配置指南下一篇Taiga Backend 快速安装配置指南10分钟搭建项目管理平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考