feat(multi-repo): 多根工作区仓库切换（Graph 选择器 + 全局活跃仓库级联，issue #107）

CHANGELOG.md

@@ -8,14 +8,19 @@
 
 ### Added
 
-- **Agentic Git 偏好配置（Agentic Git 预置）**：新增 `hyperGit.agent.*` 四项配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① `hyperGit.agent.baseBranch`（创建 PR 的基线分支，留空=仓库默认分支）；②③④ `commitPreferences` / `createPrPreferences` / `reviewPreferences`（分别为点击 **Commit / Create PR / Review** 时发送给 agent 的自定义指令，均以 `editPresentation: "multilineText"` 多行文本域承载、**内置默认模板**）。其中 **Commit 模板由中文提交规约译为专业英文**（规约规定提交信息用中文，故示例与签名块原样保留）；Create PR / Review 模板**逐字内置**（含 `${TARGET_BRANCH}` / `#{pr_number}` 等占位符）。采用**原生设置**承载（零新增 Webview / 命令 / TS / 测试），默认值内联于 [`package.json`](./package.json)。**仅落地配置与内置默认**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。README 指标行同步 `7 → 11 配置项`。完整叙述见 [Agentic Git 偏好配置](./docs/features/agentic-git-preferences.md)。
-- **Claude Code 配置（Agentic Git 预置）**：新增两项与 Claude Code 相关的配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① 设置项 `hyperGit.claudeCode.executablePath`（Claude Code CLI 可执行路径，**留空=从 `PATH` 自动探测 `claude`**；描述内嵌 `command:` 链接就地提供「浏览 / 打开 Claude 设置」）；② 命令 `hyperGit.setClaudeCodePath`（QuickPick：Browse 文件选择器写回 / **Use system Claude Code** 清空覆盖）与 `hyperGit.openClaudeSettings`（打开 `~/.claude/settings.json`，缺失时经确认创建 `{}`）。采用**原生设置 + 命令**承载（零新增 Webview 面板），路径解析下沉纯函数 [`engine/agent/claude-path.ts`](./src/engine/agent/claude-path.ts)（Vitest 可测），命令实现见 [`adapter/claude-commands.ts`](./src/adapter/claude-commands.ts)。**仅落地配置与快捷入口**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。同步校正 README 指标行（`6 视图 · 101 命令 · 7 配置项 · 372 单元测试`，此前 `97 命令 / 324 测试` 已滞后 HEAD）。完整叙述见 [Claude Code 配置](./docs/features/claude-code-config.md)。
-- **Branches 视图按 `/` 前缀分组为文件夹树**：Local / Remote / Tags 三段支持在**平铺**与**按 `/` 前缀分组的可折叠文件夹树**间切换——共享前缀的分支收拢到以前缀命名的文件夹下、叶子仅显示末段后缀（如 `bak/2025`、`bak/master-2025-07` → 📁`bak` → `2025` / `master-2025-07`；远程整体收拢为 `origin` 文件夹并内嵌 `feature`）。新增纯逻辑引擎 [`buildRefTree`](./src/engine/ref/ref-tree.ts)（复用「变更文件目录树」`buildFileTree` 的 trie 构建 + compact 折叠范式；叶子携完整 `RawRef`、命令定位不受影响；分支感知排序：当前 HEAD → 收藏 → 同档文件夹优先、名称数字感知升序），并**隐藏 `origin/HEAD` 符号引用**（对齐主流 Git UI，消除 `origin` 叶子与 `origin` 文件夹同名冲突）。工具栏提供「平铺 ⇄ 树」切换（`hyperGit.branchesGroupByPrefix` / `hyperGit.branchesFlatten`，context key 驱动按钮互斥），偏好按仓库持久化于 `workspaceState`（默认树形），文件夹默认展开、展开态跨刷新稳定。文件夹节点用独立 `contextValue` 且不登记任何右键命令，checkout / delete / rename / merge / rebase / compare / favorite 与多选批量均零改动、零破坏。完整叙述见 [分支前缀分组树](./docs/features/branch-tree-group-by-prefix.md)。
+- **多根工作区仓库切换（issue #107）**：多根工作区含多个 Git 仓库时，Graph 工具栏仓库名升级为**可切换按钮**（对标 Git Graph；单仓库退化为纯文本，多数用户零感知），Command Palette 亦可经 `Hyper Git: Select Repository…` 直达。切换**全局活跃仓库**——Graph / Branches / Commit（changelist）/ Stash / Shelf / Worktrees / 未提交角标七视图级联跟随，活跃仓库持久化于 `workspaceState`（`hyperGit.activeRepoRoot`，重开窗口回到上次操作的仓库）。**按仓库隔离记忆**：changelist 分配 / 分支收藏 / 分支分组偏好（`setRepoRoot` 重绑 + context key 同步）、Shelf 存储（`shelves/<basename>.<sha1[:8]>/` 随活跃仓库动态求值，旧平铺数据一次性安全迁移：仅 rename、零删除零覆盖）、最近提交消息（per-repo key，旧全局 key 回落一次）、Graph/Commit webview 视图状态（scope/选中/勾选集等 v2 `byRepo` 分区）。选取逻辑下沉纯函数 [`engine/git-state/repo-selection.ts`](./src/engine/git-state/repo-selection.ts)（持久化恢复 → folder0 匹配 → 首个仓库三级优先），**三重顺序不变量**保证 rebind 先于视图刷新；Blame 注解切库自清理；顺带修复激活竞态（repo 发现晚于 activate 时 memento key 落占位根）。集成测试新增 multi-root 双仓库 fixture 套件（`tests/suite/multi-root.test.js`，`activate()` 导出 `{ service }` 程序化接缝）。完整叙述见 [多根工作区仓库切换](./docs/features/multi-root-repo-selection.md)。
 
 ### Changed
 
+- **`@vscode/test-electron` 升级 3.0.0 → 3.1.0**：VS Code 1.110 起将 macOS 主二进制 `Electron` 更名为 `Code`（兼容符号链接于 2026-07 移除，microsoft/vscode#326502），3.0.0 启动 1.110+ 版本即 `spawn .../MacOS/Electron ENOENT` 崩溃；3.1.0 按 `Info.plist → CFBundleExecutable` 三级解析修复（microsoft/vscode-test#348）。此前 dependabot [PR #102](https://github.com/ThreeFish-AI/hyper-git/pull/102) 因 supply-chain 发布冷静期被 CI 拦截，现窗口已过正式合入。
 - **面板视图默认布局调整（显隐与顺序）**：`package.json` `contributes.views` 声明式微调六视图默认态——**Stash / Shelf** 由 `collapsed` 改为 `visibility:"hidden"`（VS Code schema 中 `hidden` 映射 `hideByDefault`：默认不出现在容器内，仍可经视图标题右键菜单勾选恢复）；**Commit / Worktrees** 由 `visible` 改为 `collapsed`（显示但默认折叠、点击标题即展开）；**Branches / Graph** 保持 `visible`；容器内声明顺序调整为 **Commit · Branches · Graph · Worktrees**（Stash · Shelf 隐藏排其后）。`initialSize` 权重不变，`src/` 零改动，命令 / 协议 / 菜单 / `viewsWelcome` / 交互零破坏。新增 [`tests/unit/views-layout.test.ts`](./tests/unit/views-layout.test.ts) 声明式护栏锁定顺序与各视图 `visibility`。**平台约束**：`visibility` 仅影响全新安装 / 干净 profile 的初始态——老用户升级后需命令面板「View: Reset View Locations」或右键容器页签「Reset Location」方采用新默认（同 [issue #12](./docs/.agents/issue.md) / [#13](./docs/.agents/issue.md) 平台行为）。决策详见 [issue #16](./docs/.agents/issue.md)。
 
+### Added（既有未发布条目）
+
+- **Agentic Git 偏好配置（Agentic Git 预置）**：新增 `hyperGit.agent.*` 四项配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① `hyperGit.agent.baseBranch`（创建 PR 的基线分支，留空=仓库默认分支）；②③④ `commitPreferences` / `createPrPreferences` / `reviewPreferences`（分别为点击 **Commit / Create PR / Review** 时发送给 agent 的自定义指令，均以 `editPresentation: "multilineText"` 多行文本域承载、**内置默认模板**）。其中 **Commit 模板由中文提交规约译为专业英文**（规约规定提交信息用中文，故示例与签名块原样保留）；Create PR / Review 模板**逐字内置**（含 `${TARGET_BRANCH}` / `#{pr_number}` 等占位符）。采用**原生设置**承载（零新增 Webview / 命令 / TS / 测试），默认值内联于 [`package.json`](./package.json)。**仅落地配置与内置默认**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。README 指标行同步 `7 → 11 配置项`。完整叙述见 [Agentic Git 偏好配置](./docs/features/agentic-git-preferences.md)。
+- **Claude Code 配置（Agentic Git 预置）**：新增两项与 Claude Code 相关的配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① 设置项 `hyperGit.claudeCode.executablePath`（Claude Code CLI 可执行路径，**留空=从 `PATH` 自动探测 `claude`**；描述内嵌 `command:` 链接就地提供「浏览 / 打开 Claude 设置」）；② 命令 `hyperGit.setClaudeCodePath`（QuickPick：Browse 文件选择器写回 / **Use system Claude Code** 清空覆盖）与 `hyperGit.openClaudeSettings`（打开 `~/.claude/settings.json`，缺失时经确认创建 `{}`）。采用**原生设置 + 命令**承载（零新增 Webview 面板），路径解析下沉纯函数 [`engine/agent/claude-path.ts`](./src/engine/agent/claude-path.ts)（Vitest 可测），命令实现见 [`adapter/claude-commands.ts`](./src/adapter/claude-commands.ts)。**仅落地配置与快捷入口**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。同步校正 README 指标行（`6 视图 · 101 命令 · 7 配置项 · 372 单元测试`，此前 `97 命令 / 324 测试` 已滞后 HEAD）。完整叙述见 [Claude Code 配置](./docs/features/claude-code-config.md)。
+- **Branches 视图按 `/` 前缀分组为文件夹树**：Local / Remote / Tags 三段支持在**平铺**与**按 `/` 前缀分组的可折叠文件夹树**间切换——共享前缀的分支收拢到以前缀命名的文件夹下、叶子仅显示末段后缀（如 `bak/2025`、`bak/master-2025-07` → 📁`bak` → `2025` / `master-2025-07`；远程整体收拢为 `origin` 文件夹并内嵌 `feature`）。新增纯逻辑引擎 [`buildRefTree`](./src/engine/ref/ref-tree.ts)（复用「变更文件目录树」`buildFileTree` 的 trie 构建 + compact 折叠范式；叶子携完整 `RawRef`、命令定位不受影响；分支感知排序：当前 HEAD → 收藏 → 同档文件夹优先、名称数字感知升序），并**隐藏 `origin/HEAD` 符号引用**（对齐主流 Git UI，消除 `origin` 叶子与 `origin` 文件夹同名冲突）。工具栏提供「平铺 ⇄ 树」切换（`hyperGit.branchesGroupByPrefix` / `hyperGit.branchesFlatten`，context key 驱动按钮互斥），偏好按仓库持久化于 `workspaceState`（默认树形），文件夹默认展开、展开态跨刷新稳定。文件夹节点用独立 `contextValue` 且不登记任何右键命令，checkout / delete / rename / merge / rebase / compare / favorite 与多选批量均零改动、零破坏。完整叙述见 [分支前缀分组树](./docs/features/branch-tree-group-by-prefix.md)。
+
 ## [0.0.14] - 2026-07-06 — 修复 GRAPH 视图提交记录时间倒序
 
 修复 GRAPH 视图「All」范围下提交记录未按时间倒序排列的问题——取数参数由 `--topo-order` 改为 `--author-date-order`，令跨分支提交按作者日期正确交错、消除「日期回跳」。纯取数排序修复，不改数据协议、布局算法与任何视图交互。完整用户视角叙述见 [Release Note v0.0.14](./docs/releases/v0.0.14.md)。

README.md

@@ -16,7 +16,7 @@
   <b>English</b> · <a href="./docs/i18n/zh-CN/README.md">简体中文</a>
 </p>
 
-<p align="center"><sub>6 views · 101 commands · 11 settings · 375 unit tests</sub></p>
+<p align="center"><sub>6 views · 102 commands · 11 settings · 403 unit tests</sub></p>
 
 ## Features
 
@@ -25,6 +25,7 @@
 </p>
 
 - **Multi-Changelist Changes view**: group edits into named lists, mark one as the active commit target, create / rename / delete / move lists, persisted in `workspaceState` (restored across restarts); status colors reuse the `gitDecoration.*` theme tokens.
+- **Multi-root repository switching**: in multi-root workspaces with several Git repositories, the Graph toolbar's repository name becomes a clickable switcher (Git Graph-style) plus a `Select Repository…` command; one switch updates the active repository across all views (Graph / Branches / Commit / Stash / Shelf / Worktrees / badge), with changelists, branch favorites, grouping preferences, shelves, and recent messages remembered per repository, and the last active repository restored across restarts.
 - **Commit panel**: a hand-built commit view with real-time Conventional Commits validation, Amend / Sign-off / skip hooks, and Commit / Commit & Push; the checkbox selection is the authoritative commit scope, and recent messages are reusable.
 - **Log commit graph (hand-rendered DAG)**: colored swimlanes, branch/merge edges, HEAD/branch/tag badges, virtualized incremental loading; 7 composable filters (author / path / grep / regex / merge-mode / date / clear); per-commit actions (Reset, new branch·tag, Cherry-Pick, Revert, list containing branches).
 - **Branches management**: favorites / local / remote / tags grouped into four sections with ahead·behind·upstream tracking; **prefix folder grouping** (flat ⇄ tree toggle) that collapses `/`-shared branches under their common prefix, showing only the suffix; create / checkout / delete / rename / merge / rebase / compare / favorite; **multi-select batch** delete, copy ref, and favorite (with an honest merged/unmerged split confirmation).
@@ -78,7 +79,7 @@ See the [Engineering Plan](./docs/architecture/engineering-plan.md), the [Implem
 pnpm install                  # install dependencies
 pnpm run compile              # type-check + lint + build
 pnpm run watch                # watch build (press F5 to launch the Extension Host debugger)
-pnpm run test:unit            # unit tests (pure engine logic, Vitest, 375 cases)
+pnpm run test:unit            # unit tests (pure engine logic, Vitest, 403 cases)
 pnpm run test:integration     # integration tests (@vscode/test-electron)
 pnpm run package              # production build
 pnpm dlx @vscode/vsce package # package the .vsix

docs/.agents/issue.md

@@ -140,3 +140,11 @@
 - **同类问题影响**：所有以 `contributes.views` 声明默认布局的 VS Code 扩展；凡将「默认隐藏但可恢复」误用 `when:false`（致用户无法启用）或反向混淆的实现；以及把「仅初始态生效」误当「持久强制」而困惑于老用户升级后不生效的排障。
 
 
+
+## #107 多根工作区无法切换 Git 仓库（Graph 等全部视图锁定单一仓库）
+
+- **表因**：多根工作区（multi-root）含多个 Git 仓库时，Graph 面板恒只显示其中一个仓库（`workspaceFolders[0]` 匹配或 `repositories[0]`），无任何切换入口；Git Graph / GitLens 等均有仓库选择器。
+- **根因**：扩展的活跃仓库模型是**单仓库假设**——① `GitRepositoryService.pickRepository()` 只按「首个 folder → 首个仓库」两级选取，无手动切换 API；② 4 处**构造期冻结**的按 repoRoot 键控持久化状态（`ChangelistRegistry` / `BranchFavorites` / `BranchesTreeProvider.groupingKey` / `ShelfService` 目录）不随仓库变化，即使切了活跃仓库，changelist 分配与收藏仍指向旧仓库、Shelf 会跨库误 apply；③ Blame 注解、Graph host 级 filter、webview 持久化状态等均无切库清理/隔离。
+- **处理方式**：落地全局活跃仓库切换（Git Graph 模式）——① 选取逻辑下沉纯函数 `engine/git-state/repo-selection.ts`（三级优先：持久化恢复 → folder0 匹配 → 首个仓库，路径归一化跨平台稳定），`GitRepositoryService` 新增 `selectRepository`/`listRepositories`/`onDidChangeRepository`，活跃仓库持久化 `hyperGit.activeRepoRoot`；② **三重顺序不变量**保证 rebind 先于刷新：`applyRepository` 内先 fire 切换事件（同步 rebind：registry/favorites/branchesTree.setRepoRoot + context key 同步 + blame 清理 + filter 清空）后 fire onDidChange（防抖刷新），且 rebind 订阅先于 `refreshAll` 注册；③ Shelf 目录随 `service.repoRoot` 动态求值（`shelves/<basename>.<sha1[:8]>/`）+ 旧平铺数据一次性安全迁移（仅 rename、目标存在即跳过、失败可重试）；④ Graph 工具栏仓库名升级可点击按钮（单仓库退化纯文本）+ `hyperGit.selectRepository` palette 命令（带参=程序化切换接缝，`activate()` 导出 `{ service }` 供集成测试）；⑤ webview 视图状态（scope/选中/勾选集等）v2 `byRepo` 分区 + 最近提交消息 per-repo key（旧 key 回落一次平滑迁移）。集成测试新增 multi-root 双仓库 fixture 套件（`tests/suite/multi-root.test.js`）。
+- **后续防范**：① **新增组件若构造期快照 repoRoot（拼 memento key / 存储目录），必须订阅 `service.onDidChangeRepository` 重绑**——可用 `grep -rn 'repoRoot' src/adapter/ | grep -v 'service.repoRoot'` 扫描快照点；② 集成测试需 UI 交互时，优先给命令 handler 加可选参数（无参=QuickPick，带参=程序化）+ `activate()` 导出接缝，勿依赖无法自动化的原生弹窗；③ 顺带修复了既有激活竞态（repo 发现晚于 activate 时 memento key 落 workspaceRoot 占位），rebind 事件会纠正——但根治应在「窗口内无写入路径」前提下依赖该纠正，勿在激活早期引入持久化写入。
+- **同类问题影响**：所有围绕「单一活跃仓库」装配的 VS Code Git 扩展；凡按 repoRoot 构造 workspaceState/globalStorage 键或存储目录、却不在仓库集合变化时重绑的实现；以及 macOS 上 VS Code ≥ 1.110 主二进制 `Electron`→`Code` 更名导致 `@vscode/test-electron` 旧版 ENOENT 的集成测试环境（升 3.1.0 解决，见 PR #102）。

docs/.agents/knowledge-map.md

@@ -24,6 +24,7 @@
 - [Log 提交悬浮详情](../docs/features/log-commit-tooltip.md) — 悬停提交行浮层展示 分支/标签/HEAD/完整消息/作者·提交者/时间/SHA；复用 CI 浮层范式、与其互斥。
 - [Claude Code 配置](../docs/features/claude-code-config.md) — Agentic Git 预置：`hyperGit.claudeCode.executablePath` 设置 + `~/.claude/settings.json` 快捷入口（原生设置 + 命令；纯路径逻辑沉淀 `engine/agent/`）。
 - [Agentic Git 偏好配置](../docs/features/agentic-git-preferences.md) — Agentic Git 预置：`hyperGit.agent.*` 四项（baseBranch + commit/createPr/review Preferences；多行文本域 + 内置默认模板，Commit 模板中文规约已英译）。
+- [多根工作区仓库切换](../docs/features/multi-root-repo-selection.md) — Graph 工具栏仓库名按钮 + `hyperGit.selectRepository` 切换全局活跃仓库：七视图级联跟随、changelist/收藏/Shelf/最近消息按仓库隔离、三重顺序不变量与安全迁移。
 - [实施状态总览](../docs/milestones/implementation-status.md) — M0-M5 交付记录 + API 限制 + M5 AI 设计 + 验证/发布（**实施看板**）。
 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。
 - [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。