发布 v0.0.1 首个 MVP：清理历史预发布、收敛版本与发布管线、重写发布说明/CHANGELOG/README

.github/workflows/ci.yml

@@ -83,6 +83,8 @@ jobs:
     permissions:
       contents: write
     steps:
+      # 检出仓库：使 body_path 指向的 Release Note 文件可见
+      - uses: actions/checkout@v4
       - uses: actions/download-artifact@v4
         with:
           name: vsix
@@ -91,7 +93,8 @@ 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 触发；OpenVSX 默认发布，VS Code Marketplace 由 ENABLE_MARKETPLACE_PUBLISH 变量门控（默认关闭）；生产环境审批门
@@ -122,7 +125,10 @@ jobs:
           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

README.md

@@ -7,76 +7,114 @@
 <p align="center">在 VS Code 上完整复刻 IntelliJ IDEA 的 <b>Git 工具窗口</b> 与 <b>Commit 提交窗口</b>，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。</p>
 
 <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>
 
 ## 为什么需要 Hyper Git
 
-IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit / Shelf / Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是开发者高频依赖的工作流。迁移到 VS Code 后，原生 Source Control 视图**缺少**：多 changelist、忠实的 Commit 窗口、提交前检查流水线、Shelf/行级提交等能力。Hyper Git 旨在 1:1 补齐这一体验。
+IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit / Shelf / Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是开发者高频依赖的工作流。迁移到 VS Code 后，原生 Source Control 视图**缺少**：多 Changelist、忠实的 Commit 窗口、提交前检查流水线、Shelf、行级提交、可视化提交图等能力。Hyper Git 旨在 1:1 补齐这一体验，并与原生 Source Control 平行共存、零冲突。
 
-## 架构（路径 B：消费 + 自绘）
+## 核心能力（v0.0.1）
+
+- **多 Changelist Changes 视图**：将改动分组到命名列表，设活动列表为提交目标，新建/重命名/删除/移动，`workspaceState` 持久化（重启恢复）；状态色复用 `gitDecoration.*` 主题色。
+- **Commit 提交窗口**：自绘 IDEA 风格面板 + 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。
+> 规模：**7 视图 / ~92 命令 / 3 配置项**，覆盖 IDEA Git 工具窗口主线工作流。完整发布说明见 [Release Note v0.0.1](./docs/releases/v0.0.1.md)。
 
-## 功能（v0.0.1-rc.1）
+## 架构（路径 B：消费 + 自绘）
 
-- **多 changelist Changes 视图**：active 列表、新建/删除/重命名/移动，`workspaceState` 持久化（重启恢复）；文件状态色复用 `gitDecoration.*` 主题色。
-- **Commit 提交窗口**：多行编辑器 + Conventional Commits 实时校验 + Amend / Signed-off-by / 跳过 Git hooks + Commit / Commit and Push；勾选集为提交权威范围；最近消息复用。
-- **Log 提交历史**：按作者/路径过滤、清除过滤、复制 commit hash、显示文件历史。
-- **Branches**：本地/远程分组、活动分支高亮；新建/检出/删除/合并/变基（rebase）；**多选批量**（Ctrl/Cmd/Shift 框选后批量删除分支/标签、复制引用、收藏）。
-- **Stash**：create / apply / pop / drop（作用于 stash@{0} 最新）。
-- **其他**：Discard 改动、Pull / Push / Fetch、Blame、Diff（HEAD ↔ Working）。
+- **消费** 内置 `vscode.git` 导出的稳定 `Repository` API 作为 git 底座，不重造 git 状态机。
+- **受控 CLI 通道**：稳定 API 未覆盖的能力（cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash 列表 / graph 拓扑 / shelf 等）经 `GitRepositoryService.execGit` 复用同一 git 二进制（`api.git.path`）实现。
+- **自绘视图** 承载 IDEA 风格 UI；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。
+- **AI 接缝**：预留 `ILlmProvider` / `IPreCommitInspector` 等 5 个接口（对齐 IDEA `CheckinHandler` 生命周期），实现延后至 M5。
+
+```mermaid
+flowchart TB
+  subgraph VSC["VS Code 宿主"]
+    direction LR
+    GitExt["内置 vscode.git 扩展<br/>稳定 Repository API"]
+    GitBin["git 二进制<br/>api.git.path"]
+  end
+
+  subgraph HG["Hyper Git（路径 B）"]
+    direction TB
+    UI["UI 层 · 自绘视图<br/>Changes · Commit · Log(DAG) · Branches<br/>Stash · Shelf · Worktrees"]
+    ADP["Adapter 层 · 唯一接触 vscode API<br/>GitRepositoryService · ChangelistRegistry<br/>TreeProviders · Webviews"]
+    ENG["Engine 层 · 纯逻辑 · 零 vscode 依赖 · 可单测<br/>graph-layout · hunk-parser · diff3<br/>conventional-linter · for-each-ref ..."]
+    AGT["Agent 接缝 · M5 预留<br/>ILlmProvider · IPreCommitInspector ..."]
+  end
+
+  UI --> ADP
+  ADP --> ENG
+  AGT -. 接口注入 .-> ENG
+  ADP -->|稳定 API| GitExt
+  ADP -->|受控 CLI| GitBin
+
+  classDef host fill:#1f3a5f,stroke:#5b9bd5,color:#e8f0fe;
+  classDef ui fill:#3d2f5f,stroke:#a479e2,color:#f3ecff;
+  classDef adp fill:#1f4d3f,stroke:#43d692,color:#e6fff4;
+  classDef eng fill:#5f4a1f,stroke:#e0a93f,color:#fff6e0;
+  classDef agt fill:#4d2230,stroke:#f691b2,color:#ffe9f0;
+  class GitExt,GitBin host;
+  class UI ui;
+  class ADP adp;
+  class ENG eng;
+  class AGT agt;
+```
 
 ## 安装
 
-- **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-0.0.1.vsix` → 命令面板 `Extensions: Install from VSIX`。
+- **OpenVSX**（Cursor / Windsurf / Gitpod / VSCodium）：搜索 `Hyper Git`。
+- **VS Code Marketplace**：搜索 `Hyper 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（IDEA「Include Selected Lines」）。
 - 目录 / 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-边界)）。
+| 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，218 例）
 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)。图标字形改编自 [Tabler Icons](https://github.com/tabler/tabler-icons)（MIT）。

docs/.agents/knowledge-map.md

@@ -20,6 +20,7 @@
 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。
 - [IDEA 功能复刻矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**）。
 - [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。
+- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.1](../releases/v0.0.1.md)）。
 
 ## 架构分层（src/）
 > 依赖方向单向：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI。

docs/README.md

@@ -7,6 +7,9 @@
 - [工程实施方案](./architecture/engineering-plan.md) — 全链路调研结论 + 路径 B 架构 + M0-M5 里程碑路线图 + 风险与验证（**开发蓝图**）。
 - [IDEA 功能复刻矩阵](./requirements/idea-feature-matrix.md) — 56 个原子功能点 / 8 组 + CheckinHandler 生命周期（**验收基线**）。
 
+## 发布说明
+- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.1 首个 MVP](./releases/v0.0.1.md)。
+
 ## 调研报告（循证依据）
 - [02 · VS Code SCM API 与 vscode.git 集成路径](./research/02-vscode-scm-integration.md) — 路径 B 决策依据、SCM 稳定/proposed API 边界、changelist 模型映射。
 - [03 · VS Code 扩展工程蓝图](./research/03-extension-blueprint.md) — 技术栈决策、工程骨架、IDEA→VS Code UI 表面映射表。
@@ -15,4 +18,4 @@
 
 ## 协作与规范
 - [AGENTS.md](../AGENTS.md) — 协作协议与工程行为准则。
-- [知识索引](../.agents/knowledge-map.md) · [Issue 记录](../.agents/issue.md) · [引用规范 IEEE](../.agents/reference-specifications.md)。
+- [知识索引](./.agents/knowledge-map.md) · [Issue 记录](./.agents/issue.md) · [引用规范 IEEE](./.agents/reference-specifications.md)。

docs/releases/README.md

@@ -0,0 +1,17 @@
+# 发布说明（Release Notes）
+
+> 各正式版本的发布说明，面向用户、覆盖该版本的全部特性。
+
+本目录是 GitHub Release 正文的**单一事实源**：CI 在推送 `v*` 标签时，由 `github-release` job 经 `body_path: docs/releases/${tag}.md` 取对应文件作为 Release 正文（详见 [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)）。因此**每个 `v*` 标签都必须先有同名 Release Note 文件**，否则发布会失败——这是有意的发布纪律闸门。
+
+## 版本索引
+
+| 版本 | 说明 | 日期 |
+|---|---|---|
+| [v0.0.1](./v0.0.1.md) | 首个 MVP 正式版 | 2026-06-30 |
+
+## 相关文档
+
+- [CHANGELOG](../../CHANGELOG.md) — 工程视角的逐版本变更记录（Added / Changed / Fixed）。
+- [README](../../README.md) — 项目说明、能力总览与开发指南。
+- [文档中心](../README.md) — 全部文档与调研资产索引。