ThreeFish-AI · ThreeFish-AI · Jul 2, 2026 · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,8 +16,8 @@ jobs:
     name: Lint & Build
     runs-on: ubuntu-latest
     steps:
-      - uses: pnpm/action-setup@v6
       - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 22
@@ -37,8 +37,8 @@ jobs:
         os: ${{ (github.event_name == 'pull_request') && fromJson('["ubuntu-latest"]') || fromJson('["ubuntu-latest", "macos-latest", "windows-latest"]') }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: pnpm/action-setup@v6
       - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 22
@@ -60,8 +60,8 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: pnpm/action-setup@v6
       - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 22
@@ -83,6 +83,8 @@ jobs:
     permissions:
       contents: write
     steps:
+      # 检出仓库：使 body_path 指向的 Release Note 文件可见
+      - uses: actions/checkout@v4
       - uses: actions/download-artifact@v8
         with:
           name: vsix
@@ -91,19 +93,20 @@ jobs:
         with:
           files: '*.vsix'
           prerelease: ${{ contains(github.ref_name, 'rc') }}
-          generate_release_notes: true
+          # Release 正文取自版本控制的 Release Note（单一事实源，按 tag 名取对应文件）
+          body_path: docs/releases/${{ github.ref_name }}.md
           fail_on_unmatched_files: true
 
-  # 发布：仅 tag 触发，双市场（Marketplace + OpenVSX），生产环境审批门
+  # 发布：仅 tag 触发；OpenVSX 默认发布，VS Code Marketplace 由 ENABLE_MARKETPLACE_PUBLISH 变量门控（默认关闭）；生产环境审批门
   publish:
     name: Publish
     needs: package
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     environment: production
     steps:
-      - uses: pnpm/action-setup@v6
       - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 22
@@ -112,13 +115,20 @@ jobs:
       - uses: actions/download-artifact@v8
         with:
           name: vsix
+      # VS Code Marketplace 发布：默认关闭（未配置 VSCE_PAT）。
+      # 配好 VSCE_PAT 后，在仓库 Settings → Secrets and variables → Actions → Variables
+      # 新增 ENABLE_MARKETPLACE_PUBLISH=true 即恢复，无需改代码或发 PR。
       - name: 发布到 VS Code Marketplace
+        if: ${{ vars.ENABLE_MARKETPLACE_PUBLISH == 'true' }}
         run: |
           PRE_FLAG=$([[ "${GITHUB_REF_NAME}" == *rc* ]] && echo "--pre-release" || echo "")
           pnpm dlx @vscode/vsce publish --packagePath *.vsix $PRE_FLAG
         env:
           VSCE_PAT: ${{ secrets.VSCE_PAT }}
+      # OpenVSX 不支持覆盖已存在版本：若该版本号已发布则此步报错。
+      # 以 continue-on-error 隔离——不阻断 GitHub Release 产出，亦不让首发 workflow 标红。
       - name: 发布到 OpenVSX（覆盖 Cursor / Windsurf 等 AI IDE）
+        continue-on-error: true
         run: |
           PRE_FLAG=$([[ "${GITHUB_REF_NAME}" == *rc* ]] && echo "--pre-release" || echo "")
           pnpm dlx ovsx publish *.vsix $PRE_FLAG

diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,7 @@ out/
 
 # VS Code Test 临时
 .vscode-test/
+.idea/
 
 # 临时产物（执行计划等，一律收敛至此并即时清理）
 .temp/

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -1,76 +1,84 @@
-# Hyper Git
+<p align="center">
+  <img src="media/icon.png" alt="Hyper Git" width="112" height="112" />
+</p>
 
-> 在 VS Code 上完整复刻 IntelliJ IDEA 的 **Git 工具窗口** 与 **Commit 提交窗口**，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。
+<h1 align="center">Hyper Git</h1>
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+<p align="center">为 VS Code 带来统一的 <b>Git 变更管理</b> 与 <b>提交工作流</b>——多变更分组、自绘提交面板、可视化提交图、Shelf、行级提交，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。</p>
 
-## 为什么需要 Hyper Git
+<p align="center">
+  <a href="https://github.com/ThreeFish-AI/hyper-git/actions/workflows/ci.yml"><img src="https://github.com/ThreeFish-AI/hyper-git/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/ThreeFish-AI/hyper-git/blob/HEAD/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/VS%20Code-%E2%89%A5%201.85-007ACC.svg" alt="VS Code >= 1.85" />
+</p>
 
-IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit / Shelf / Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是开发者高频依赖的工作流。迁移到 VS Code 后，原生 Source Control 视图**缺少**：多 changelist、忠实的 Commit 窗口、提交前检查流水线、Shelf/行级提交等能力。Hyper Git 旨在 1:1 补齐这一体验。
+## 核心能力
 
-## 架构（路径 B：消费 + 自绘）
+- **多 Changelist Changes 视图**：将改动分组到命名列表，设活动列表为提交目标，新建/重命名/删除/移动，`workspaceState` 持久化（重启恢复）；状态色复用 `gitDecoration.*` 主题色。
+- **Commit 提交窗口**：自绘提交面板 + Conventional Commits 实时校验 + Amend / Sign-off / 跳过 Hook + 提交 / 提交并推送；勾选集即提交权威范围；最近消息复用。
+- **Log 提交图（自绘 DAG）**：彩色泳道、分叉·合并连线、HEAD/分支/标签徽标，虚拟滚动增量加载；7 个可组合过滤器（作者/路径/grep/正则/合并模式/日期/清除）；per-commit 操作（Reset、新建分支·标签、Cherry-Pick、Revert、查看包含分支）。
+- **Branches 分支管理**：收藏/本地/远程/标签四段分组 + ahead·behind·upstream 跟踪；新建/检出/删除/重命名/合并/变基/比较/收藏；**多选批量**删除、复制引用、收藏（已合并/未合并诚实分栏确认）。
+- **Stash & Shelf**：Stash 全操作（含 keep-index / clear / 从 Stash 建分支）；独立 **Shelf**（基于 patch、独立于 stash，含 3-way 合并 Unshelve）。
+- **Worktrees**：全生命周期管理——新建（新分支/检出/detached）、在新窗口打开、锁定/解锁、移动、删除、清理失效。
+- **行级与 Hunk 提交**：编辑器内 CodeLens「提交此 Hunk」、部分暂存/取消暂存、光标处暂存、Hunk 归属 Changelist。
+- **远程与冲突**：Pull/Push/Fetch + Push…/Update…/Merge… 对话框（force-with-lease / rebase / squash 等）+ 自绘 **3-way Merge Editor** 与冲突兜底引导。
+- **历史编辑**：Cherry-Pick、Revert、Reset、交互式 Rebase、Undo/Drop/Fixup/Reword。
+- **其他**：Blame 行内注解、Patch 导出/应用、Reflog、3-way Diff 概览、Discard、Diff（HEAD ↔ Working）。
 
-- **消费** 内置 `vscode.git` 扩展导出的稳定 `Repository` API 作为 git 操作底座（不重造 git 状态机）。
-- **自建** changelist registry（IDEA 的 active 列表 / 跨列表行级归属无法用原生 SCM group 表达）。
-- **自绘** 独立视图容器承载 IDEA 风格 UI，与原生 Source Control 视图零冲突、平行共存。
-- **AI**：现仅预留接口接缝（`ILlmProvider` / `IPreCommitInspector` 等，对齐 IDEA `CheckinHandler` 生命周期），实现延后至 M5。
+## 架构（路径 B：消费 + 自绘）
 
-## 功能（v0.0.1-rc.1）
+- **消费** 内置 `vscode.git` 导出的稳定 `Repository` API 作为 git 底座，不重造 git 状态机。
+- **受控 CLI 通道**：稳定 API 未覆盖的能力（cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash 列表 / graph 拓扑 / shelf 等）经 `GitRepositoryService.execGit` 复用同一 git 二进制（`api.git.path`）实现。
+- **自绘视图** 承载完整的变更管理 UI；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。
+- **AI 接缝**：预留 `ILlmProvider` / `IPreCommitInspector` 等 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），实现延后至 M5。
 
-- **多 changelist Changes 视图**：active 列表、新建/删除/重命名/移动，`workspaceState` 持久化（重启恢复）；文件状态色复用 `gitDecoration.*` 主题色。
-- **Commit 提交窗口**：多行编辑器 + Conventional Commits 实时校验 + Amend / Signed-off-by / 跳过 Git hooks + Commit / Commit and Push；勾选集为提交权威范围；最近消息复用。
-- **Log 提交历史**：按作者/路径过滤、清除过滤、复制 commit hash、显示文件历史。
-- **Branches**：本地/远程分组、活动分支高亮；新建/检出/删除/合并/变基（rebase）。
-- **Stash**：create / apply / pop / drop（作用于 stash@{0} 最新）。
-- **其他**：Discard 改动、Pull / Push / Fetch、Blame、Diff（HEAD ↔ Working）。
+<p align="center">
+  <img src="media/framework.png" alt="Framework"/>
+</p>
 
 ## 安装
 
-- **VS Code Marketplace**：搜索 `Hyper Git`（发布后）。
-- **OpenVSX**（Cursor / Windsurf / Gitpod / VSCodium）：同 `Hyper Git`。
-- **手动**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `.vsix`（形如 `hyper-git-0.0.4.vsix`）→ 命令面板 `Extensions: Install from VSIX`。
-- **要求**：VS Code ≥ 1.85.0 + 启用内置 Git 扩展（`vscode.git`，默认随附）。
+- **手动（当前推荐）**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `hyper-git-agentic-git-x.x.x.vsix` → 命令面板 `Extensions: Install from VSIX`。
+- **OpenVSX**（Cursor / Windsurf / Gitpod / VSCodium）：搜索 `Hyper Git - Agentic Git`。
+- **VS Code Marketplace**：搜索 `Hyper Git - Agentic Git`（发布上线后可用）。
+- **要求**：VS Code ≥ 1.85.0 + 启用内置 Git 扩展（`vscode.git`，默认随附）。仅支持本地 git 仓库，不支持虚拟 / Web 工作区。
 
 ## 已知限制
 
-> vscode.git 稳定 API 不含 cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash list / graph topology / shelf / author 覆盖等；**这些均已通过 `GitRepositoryService.execGit`（复用 `api.git.path` 同一 git 二进制）的受控 CLI 通道实现**（Batch 5-12 全量对齐，详见 [CHANGELOG](./CHANGELOG.md) [Unreleased]）。
-
-当前仍待补：
-
-- Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ undo-last-commit **按钮 UI 接线**（engine `trailer` 已就绪，仅缺 webview 交互）。
-- Partial 多文件选择 UX、行级 split chunks（IDEA "Include Selected Lines"）。
+- Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ 撤销最近提交的**按钮 UI 接线**（engine `trailer` 已就绪，仅缺 webview 交互）。
+- Partial 多文件选择 UX、行级 split chunks（按选定行拆分提交）。
 - 目录 / folder diff（虚拟文档）、Submodules 管理。
-- M5 AI Agent（5 个接缝已预埋 Null 实现，本轮未启动）。
+- M5 AI Agent（5 个接缝已预埋 Null 实现，本版未启动）。
 
-详见[工程实施方案](./docs/architecture/engineering-plan.md)、[实施状态总览](./docs/milestones/implementation-status.md)与[知识索引](./.agents/knowledge-map.md)。
+详见[工程实施方案](./docs/architecture/engineering-plan.md)、[实施状态总览](./docs/milestones/implementation-status.md)与[知识索引](./docs/.agents/knowledge-map.md)。
 
 ## 路线图
 
-| 里程碑 | 主题 | 状态 |
-|---|---|---|
-| M0 | 脚手架 + CI | ✅ |
-| M1 | Git Adapter + Changes TreeView（多 changelist） | ✅ |
-| M2 | Commit 提交窗口（模板 / Amend / CC 校验 / hook 链） | ✅ |
-| M3 | Log + Branches + Diff/Blame | ✅ |
-| M4 | Stash / Shelf MVP | ✅ |
-| M5 | AI Agent（实现接缝） | ⏳ 留存设计，暂不实施 |
-
-> ⚠️ vscode.git 稳定 API 不含 cherry-pick / revert / reset / 分支重命名 / 行级 hunk 暂存；这些 IDEA 功能暂不可用（详见[实施状态 §3](./docs/milestones/implementation-status.md#3-api-限制汇总vscodegit-稳定-api-边界)）。
+| 里程碑 | 主题                                                | 状态 |
+| ------ | --------------------------------------------------- | ---- |
+| M0     | 脚手架 + CI                                         | ✅    |
+| M1     | Git Adapter + Changes TreeView（多 Changelist）     | ✅    |
+| M2     | Commit 提交窗口（模板 / Amend / CC 校验 / Hook 链） | ✅    |
+| M3     | Log（Graph DAG） + Branches + Diff/Blame            | ✅    |
+| M4     | Stash / Shelf / 行级提交 / Worktrees                | ✅    |
+| M5     | AI Agent（接缝已预留，实现待启动）                  | ⏳    |
 
 ## 开发
 
 ```bash
 pnpm install                  # 安装依赖
 pnpm run compile              # 类型检查 + lint + 构建
 pnpm run watch                # 监听构建（F5 启动 Extension Host 调试）
-pnpm run test:unit            # 单元测试（engine 纯逻辑，Vitest）
+pnpm run test:unit            # 单元测试（engine 纯逻辑，Vitest，280 例）
 pnpm run test:integration     # 集成测试（@vscode/test-electron）
 pnpm run package              # 生产构建
 pnpm dlx @vscode/vsce package # 打包 .vsix
 ```
 
-> 包管理与脚本统一使用 `pnpm`（遵循 [AGENTS.md](./AGENTS.md) 工程规范）。
+- **分层**：`engine/`（纯逻辑）→ `adapter/`（唯一接触 vscode API）→ `ui/`；`agent/` 以接口注入 `engine`，不反向依赖 UI；`shared/protocol.ts` 为 Webview ↔ Host 契约单一事实源。
+- **发布**：`v*` 标签触发 CI 产出 GitHub Release（附 `.vsix`，正文取自 [`docs/releases/`](./docs/releases/README.md)）+ OpenVSX；VS Code Marketplace 由 `ENABLE_MARKETPLACE_PUBLISH` 变量门控。
+- 包管理与脚本统一使用 `pnpm`（遵循 [AGENTS.md](./AGENTS.md) 工程规范）。完整文档见[文档中心](./docs/README.md)。
 
 ## 许可证
 
-[MIT](./LICENSE)
+[MIT](./LICENSE)。
diff --git a/.agents/browser-validation.md → docs/.agents/browser-validation.md b/.agents/browser-validation.md → docs/.agents/browser-validation.md
diff --git a/.agents/issue.md → docs/.agents/issue.md b/.agents/issue.md → docs/.agents/issue.md
@@ -62,4 +62,20 @@
 - **后续防范**：该 job 与市场 `publish` **解耦**（不 `needs: publish`、不挂 `environment: production`），保证「Release 带 `.vsix`」不被市场审批门/密钥缺失阻塞；「仅出 Release、暂不发市场」时不审批 production 即可，无需改 publish job；最小权限仅本 job 提权 `contents: write`。
 - **同类问题影响**：所有「CI 只上传 artifact + 发市场、却在 README 承诺 Release 手动下载」的 VS Code 扩展；artifact ≠ Release 资产，二者可见性/留存期差异易被忽视。
 
+## #8 Branches 视图无法多选（批量删除等批量操作缺失）
+
+- **表因**：用户截图反馈 Branches 视图中一组功能/工作分支无法框选多个、无法批量删除。
+- **根因**：`hyperGit.branches` 经 `vscode.window.registerTreeDataProvider` 注册——该 API **不支持** `canSelectMany`，故视图天然单选；所有分支命令处理器亦只接收单个 `BranchNode`。多选能力（`canSelectMany: true`）仅 `createTreeView` 的 `TreeViewOptions` 支持。
+- **处理方式**：改用 `createTreeView('hyperGit.branches', { treeDataProvider, canSelectMany: true })`（句柄入 subscriptions）。批量命令处理器签名扩展为 `(clickedNode, selectedNodes[])`——VS Code 多选树的 `view/item/context` 命令第 2 实参即完整选区数组。新增纯逻辑 `engine/ref/selection.collectBranchRefs`（谓词过滤 + shortName 去重 + 「点击在选区之外则以点击项为准」）与 `engine/ref/cleanup.partitionByMerged`/`formatBranchDeleteConfirm`，使 `branchDelete`/`tagDelete`/`copyBranchRef`/`toggleFavorite` 批量化（删除仅一次 `git branch --merged` 分类、汇总成功/失败、末尾单次刷新）。`package.json` 对仅单目标命令（检出/合并/变基/重命名/比较等）追加 `&& !listMultiSelection` 在多选时隐藏。
+- **后续防范**：① 需要承载 `.badge` 或 `canSelectMany` 等 `TreeViewOptions` 能力的视图，一律用 `createTreeView` 而非 `registerTreeDataProvider`（本仓 `hyperGit.changes` 已有先例）。② 多选命令正确性**只依赖处理器读取实参**（`clickedNode` + `selectedNodes[]`），不得依赖 `listMultiSelection` 上下文键——其对**自定义贡献视图**的可靠性无法确证，仅作菜单整洁的视觉优化；单目标命令因只读 `clickedNode` 即便该键失效仍安全。③ 「右键点击选区之外」须以点击项为准（手势目标优先），由归一化助手统一兜底。
+- **同类问题影响**：所有以 `registerTreeDataProvider` 注册却后续需要多选/角标的自定义 TreeView；以及误把单目标命令在多选下直接作用于「点击项」造成的隐性误操作。
+
+## #9 LOG 视图残留「已删分支」提交（实为工具注入的内部引用污染 `git log --all`）
+
+- **表因**：用户截图反馈 LOG 的 All 范围下，一批本应随分支删除而消失的提交仍以游离泳道残留；运行「清理已删远程分支」（#44，`git fetch --prune`）后**依旧存在**。
+- **根因**：`engine/log/log-query.ts` 的 `buildLogArgs` 对 `all`/`checkpointer` 范围下 `git log --all`。`--all` 遍历 `refs/` 下**全部**引用，不止 heads/remotes/tags——还包括宿主工具（如 Conductor）注入的 `refs/conductor-checkpoints/*`（会话快照）、`refs/conductor-archive-heads/*`（已删/被取代分支头的归档）。这些归档头让**真实的游离提交**（被 amend/rebase 取代、或分支删除后仅靠归档存活者）仍可达，画成游离泳道。而既有的客户端 `CHECKPOINT_SUBJECT_RE=/^checkpoint:/i` 过滤**只能拦住 checkpoint 元数据提交本身**，拦不住作为其祖先的游离业务提交——故泄漏。`git fetch --prune` 仅清理 `refs/remotes/*`，对上述非远端跟踪引用**完全无效**，这正是「prune 后依旧存在」的根因。实证：本仓 `--all` 取 241 提交、`--branches --tags --remotes` 仅 70；refs 命名空间 135 conductor-checkpoints + 17 conductor-archive-heads，远多于 3 heads/3 remotes/2 tags。
+- **处理方式**：`all` 范围由 `--all` 改为 `--branches --tags --remotes`（仅三大标准命名空间，排除一切工具注入的内部引用），根治游离泳道；`checkpointer` 范围**保留 `--all`**——该 Tab 的职责即「原始完整视图，含内部 checkpoint 快照」，需触达 `refs/conductor-checkpoints/*`。客户端 `keepCheckpoint` 过滤作为双保险保留。更新 `tests/unit/log-query.test.ts` 断言（`all` 含三件套、不含 `--all`；`checkpointer` 含 `--all`、不叠三件套）作回归护栏。
+- **后续防范**：① 「全分支视图」语义应映射到 `--branches --tags --remotes` 而非 `--all`——`--all` 是「全部引用」而非「全部分支」，二者差异恰是工具注入引用的污染面。② 客户端按提交 message 正则过滤是**漏的抽象**（拦不住作为祖先被带入的游离提交）；根治应在 ref 选取层（服务端参数）而非 subject 过滤层。③ **诊断 git 引用类问题时务必先 `git for-each-ref` 列出全部命名空间**——本案最初误判为「远端已删、本地未 prune」（#44 与一度推进的 prune-on-fetch 方案均为此误判），直到列出 refs 才发现真凶是 conductor-* 引用；「prune 无效」本身就是关键反证，应据其反向收敛而非强行加 prune。④ 修正「错漏逻辑」前先用 `git log --all` vs `--branches --tags --remotes` 的差集实证根因，避免再次基于关键字匹配机械式修改。
+- **同类问题影响**：所有在带「工具注入内部引用」环境（IDE/Agent checkpoint、`refs/stash`、`refs/replace/*`、`refs/notes/*` 等）下展示 `git log --all` 图的 Git GUI；凡把「范围 = 引用集合」与「范围 = message 过滤」混为一谈的实现均可能漏过游离提交。
+
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,6 +9,7 @@ out/ @@
     # VS Code Test 临时
     .vscode-test/
+    .idea/
     # 临时产物（执行计划等，一律收敛至此并即时清理）
     .temp/
@@ Expand Down @@