From a127cd99565b88e7ee2480a2ad749451aed83fd2 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Tue, 30 Jun 2026 11:20:04 +0800 Subject: [PATCH 1/2] =?UTF-8?q?chore(Release):=20=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E6=94=B6=E6=95=9B=E8=87=B3=200.0.1=20=E5=B9=B6=E5=AF=B9?= =?UTF-8?q?=E9=BD=90=E5=8F=91=E5=B8=83=E7=AE=A1=E7=BA=BF;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 清理历史预发布（删除 rc.1–rc.4 标签与 rc.1/rc.4 两个 GitHub Release）后，将首个 MVP 正式版收敛为单一 v0.0.1： - package.json: version 0.0.4 → 0.0.1。 - ci.yml(github-release): 新增 actions/checkout，并将 generate_release_notes 改为 body_path: docs/releases/${tag}.md——Release 正文取自版本控制的 Release Note（单一事实源、版本留痕、CI 与具体版本解耦）。 - ci.yml(publish): OpenVSX 发布步骤加 continue-on-error——历史 0.0.1–0.0.4 已占用且不可覆盖，隔离该步报错以保 GitHub Release + .vsix 正常产出、首发 workflow 不标红。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- .github/workflows/ci.yml | 8 +++++++- package.json | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5fabf58..23c8c33 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/package.json b/package.json index b2249ef..8091f85 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "displayName": "Hyper Git", "icon": "media/icon.png", "description": "在 VS Code 上完整复刻 IntelliJ IDEA 的 Git 工具窗口与 Commit 提交窗口，并为未来 AI Agent 自主代理预留架构接缝。", - "version": "0.0.4", + "version": "0.0.1", "publisher": "threefish-ai", "license": "MIT", "preview": true, From 2e39a9307e34356c4a83d0f63304a4f7ed60caad Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Tue, 30 Jun 2026 11:20:15 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(Release):=20=E9=87=8D=E5=86=99=20v0.0.?= =?UTF-8?q?1=20=E5=8F=91=E5=B8=83=E8=AF=B4=E6=98=8E=E3=80=81CHANGELOG=20?= =?UTF-8?q?=E4=B8=8E=20README;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 面向用户与开发者重写三份文档，特性与 package.json contributes 逐项对齐实证（7 视图 / 92 命令 / 3 配置项 / 218 单测）： - docs/releases/v0.0.1.md（新增）: 首个 MVP 正式版 Release Note，覆盖全部真实特性，作为 GitHub Release 正文单一事实源；docs/releases/README.md 为发布说明索引。 - CHANGELOG.md: 删除 [Unreleased] 与 rc.1–rc.4 多段，收敛为单一 [0.0.1] 正式版条目（按域分组、去重）。 - README.md: 能力总览升级为 v0.0.1 全量，据实校准已过时的「cherry-pick/revert/reset/分支重命名不可用」表述（均已经 execGit CLI 通道实现），新增路径 B Mermaid 架构图，补开发者构建/测试/文档导航。 - docs/README.md & knowledge-map.md: 登记 docs/releases/；修正失效的 .agents 相对链接。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- CHANGELOG.md | 212 ++++++++-------------------------- README.md | 108 +++++++++++------ docs/.agents/knowledge-map.md | 1 + docs/README.md | 5 +- docs/releases/README.md | 17 +++ docs/releases/v0.0.1.md | 96 +++++++++++++++ 6 files changed, 238 insertions(+), 201 deletions(-) create mode 100644 docs/releases/README.md create mode 100644 docs/releases/v0.0.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 058f5cc..8838f9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,185 +2,67 @@ 本项目的所有重要变更均记录于此文件。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。 -## [Unreleased] +> 面向用户的发布说明（含完整特性叙述与安装指引）见 [`docs/releases/`](./docs/releases/README.md)。 -### Added - -- **Log 视图升级为 IDEA 风格提交图（Graph DAG）**：`hyperGit.log` 由原生 TreeView（`log-tree.ts`）迁移为 Webview，基于 commit 父子关系**自计算 DAG lane 布局**，完整复刻 IntelliJ IDEA Git Log 的彩色泳道 / 节点 / 分叉·合并连线 / HEAD·分支·标签标签——不再依赖 `git log --graph` 的粗糙 ASCII（lane 由 git 分配、不可控、随列号抖动着色）。新增纯逻辑引擎 `engine/log/graph-layout.ts`（单遍增量 lane 状态机，nil-slot 复用保证分支「直顺」；`graph-color.ts` 沿首父链继承 + 相邻 lane 异色；覆盖 octopus 合并 / 多 root / 收敛 / 截断 dangling 边）、`log-line.ts`（NUL/RS 解析）与 `log-query.ts`（`--topo-order` 保拓扑序；author/grep/path 服务端 + mergeMode/date/regex 客户端复用 `applyClientFilters`），单测 29 例全覆盖。Webview 端虚拟化「每行内联 SVG + 文本列」渲染、主题调色板（`--vscode-` 令牌 + hex 回退）、All/Current 范围切换、滚动增量加载、↑↓ 键导航、选中提交内联展示变更文件（点击打开 diff）、右键 per-commit 操作菜单（复用既有 9 个命令）。移除独立的 `showGraph` 面板与 `graph-parser`（单一事实源去重）；新增 `LogFilterControl` 接口使 4 个命令注册器零行为改动完成迁移。 -- **Branches 视图多选 + 批量操作**：`hyperGit.branches` 由 `registerTreeDataProvider` 改用 `createTreeView({ canSelectMany: true })`，支持 Ctrl/Cmd/Shift 框选多个分支/标签。批量命令作用于整个选区：**删除分支**（一次 `git branch --merged` 分类已合并/未合并，单条确认弹窗诚实分栏呈现强制删除风险，逐个删除并汇总成功/失败）、**删除标签**、**复制引用**（按行连接）、**收藏切换**。仅单目标语义的操作（检出/合并/变基/重命名/比较）经 `!listMultiSelection` 在多选时从右键菜单隐藏，且因仅读「右键点击项」而始终安全。新增纯逻辑 `engine/ref/selection.collectBranchRefs`（选区归一化 + 「点击在选区之外」手势优先）与 `engine/ref/cleanup` 的 `partitionByMerged`/`formatBranchDeleteConfirm`/`truncateNames`，单测全覆盖。 - -### Changed - -- **品牌图标统一**：将活动栏图标（`media/hyper-git-icon.svg`）、Marketplace 市场徽标（`media/icon.png`）与 README 头图统一为辨识度更高的「Git Pull Request」造型（字形改编自 Tabler Icons，MIT）；市场徽标基于新字形重新栅格化为 256×256 RGBA 蓝→紫渐变图，设计源沉淀至 `media-src/icon.svg`；README 头部重构为居中布局（徽标 + 标题 + 一句话定位 + License 徽章）。 - -### Fixed - -- **Log Graph 文字与节点间留白**：原实现每行 Graph SVG 宽度取「已加载全部提交」的全局 `maxLanes`，分支型仓库中仅用 1–2 条 lane 的行仍预留整宽，导致节点与文字间大片留白。改为按「本行实际绘制的最右列」自适应行宽，文字随即向左贴近本行 Graph（lane x 坐标仍全局一致，竖线跨行衔接不变），对齐 IDEA「文字紧随 Graph」观感。 - -## [0.0.1-rc.4] - 2026-06-29 — 第四个预发布候选 - -> 修复用户截图反馈的两处工具窗口缺陷：活动栏图标缺失「未提交文件数」角标、Branches「Push」对无上游分支失败。 -> -> 版本号遵循 VS Code Marketplace 约定（`major.minor.patch` = `0.0.4`），预发布语义由 `--pre-release` 标记 + git tag `v0.0.1-rc.4` 体现。 - -### Fixed - -- **活动栏未提交角标（#17）**：`hyperGit.changes` 原经 `registerTreeDataProvider` 注册，仅得 `Disposable` 无法承载 `.badge`；改用 `createTreeView` 获取 `TreeView` 句柄并新增 `updateChangesBadge()`，计数复用 `GitRepositoryService.getChanges()`（index+工作区+未跟踪去重），接入既有 `refreshAll` 防抖链路与首帧保险，计数为 0 时清空。活动栏容器图标角标为容器内各视图 `badge.value` 之和，故 Hyper Git 图标自此实时显示未提交文件数，对齐原生 SCM。 -- **Branches Push 对无上游分支失败（#17）**：`hyperGit.push` 原以零参数调 `repo.push()`，当前分支无上游时 `git push`（`push.default=simple`）必然失败，vscode.git 包装为 `GitError`、其 `.message` 恰为通用串「Failed to execute git」而真实 stderr 被吞没。改为以 `HEAD.upstream` 是否存在分流：有上游沿用 `repo.push()`；无上游则选定 remote（单 remote 直用、多 remote 弹选）并以 `repo.push(remote, branch, true)` 建立 `-u` 追踪。同时增强 `errMsg` 优先暴露 `GitError.stderr`，使「无上游」「non-fast-forward」等失败可读（push/pull/fetch 等同享）。 - -## [0.0.1-rc.3] - 2026-06-29 — 第三个预发布候选 - -> 包含 rc.2 后的全部 Parity Recovery（Batch 5-12），完成 IDEA Git 工具窗口全量对齐；并修复发布流水线，使 GitHub Release 自此自动附带「可本地安装的 `.vsix`」资产。 -> -> 版本号遵循 VS Code Marketplace 约定（`major.minor.patch` = `0.0.3`），预发布语义由 `--pre-release` 标记 + git tag `v0.0.1-rc.3` 体现。 - -### CI / 发布 - -- **GitHub Release 自动附带 `.vsix`**：CI 新增独立 `github-release` job（`softprops/action-gh-release`），对每个 `v*` tag 复用 `package` job 产出的 vsix artifact，自动创建 Release（`*rc*` tag 自动标记 prerelease）并上传 `.vsix` 资产，用户可直接「`Extensions: Install from VSIX`」本地安装。该 job 与市场 `publish` 解耦（`needs: package`、不挂 `production` 环境），即便市场发布待审批/失败亦不影响 Release 资产产出；`fail_on_unmatched_files` 杜绝「空资产 Release」。 - -### Added — Parity Recovery（Batch 5-12，IDEA 全量对齐） - -> 基于「IDEA Git 功能复刻全量对齐」评审（用户截图反馈 Branches 空白/工具栏缺失），经 3 路代码审计确认「功能多数已实现但被视图 bug + 工具栏未浮现掩盖」，本批次先解除可见痛感再全量补齐。共新增 **13 个 engine 纯逻辑模块 + 21 个命令**，单测 64 → 166。 - -- **Branches 视图渲染修复（Batch5）**：`engine/ref/for-each-ref`（NUL 分隔 + upstream/HEAD/ahead-behind track）+ async getChildren + `repo.state.refs` 为空时 `git for-each-ref` CLI 兜底 + 首帧刷新（修复初始 `_onDidChange.fire` 早于订阅挂载而丢失的根因）。 -- **工具栏 Action 组补齐 + 命令 bug（Batch5）**：Changes 加 fetch/pull/push/commit；Branches 加 fetch；Log 加 cherry-pick/revert/reset；cherry-pick/revert 成功后刷新；resetHead 重写（修 `HEAD~0` 致 mixed/keep 失效）；branchDelete 加 `--merged` 检查；merge/rebase 加确认。 -- **冲突兜底引导（Batch5）**：`engine/git-state/conflict-detector` + `adapter/conflict-ui`；merge/rebase/pull/cherry-pick/revert/stash-pop/unshelve 失败检测冲突弹「解决/中止」。 -- **Branches 对齐 IDEA（Batch6）**：Favorites/Local/Remote/Tags 四段分组 + ahead/behind/upstream 展示 + `engine/ref/favorites`/`cleanup`（提取复用）+ toggleFavorite/checkoutAsNew/compareWithCurrent/tagCreate/tagDelete/tagCheckout。 -- **交互式 Rebase webview 1:1 复刻（Batch7）**：补 reword/edit + 拖拽重排序；reword 经 `process.execPath` 跑 Node editor helper + state 文件非交互写入新 message（已功能性验证）；`engine/rebase/todo`。 -- **Log 提交详情面板 + 高级过滤（Batch8）**：commit 展开显示变更文件（`engine/log/commit-files`）+ 单文件 diff（commit^ vs commit）+ `engine/log/log-filter`（合并模式/日期/正则）+ per-commit 操作（resetToHere/createBranchFromCommit/createTagFromCommit/showContainingBranches）。 -- **真实 SVG 提交拓扑图（Batch9）**：解析 `git log --graph` 字符粒度渲染（`*` 圆点可点击 / `|` 竖线 / `/ \` 斜线，多色 lane）+ 实时刷新 + 节点点击 QuickPick；`engine/log/graph-parser`。 -- **Push/Update/Merge 对话框（Batch10）**：force/force-with-lease/push tags、pull --rebase/--no-rebase、merge ff-only/no-ff/squash + message；fetch --prune；`engine/commit/trailer`（Co-authored-by）。 -- **自绘 3-way Merge Editor（Batch11）**：自实现 `engine/merge/diff3`（基于 LCS，双方同改动自动消解）+ WebviewPanel 三栏（OURS/RESULT 可编辑/THEIRS）+ Accept 按钮 + 写回 `git add`；handleGitConflict「解决冲突」直接调起。 -- **Phase 4/5 收尾（Batch12）**：Stash 高级（keep-index/clear/branch）、Patch create/apply、Reflog 视图、编辑器内 Blame 行内注解（`engine/blame/blame-parser` + `adapter/editor/blame-annotation`）。 - -### 架构与质量 -- 新增 engine 模块（零 vscode 依赖、可单测）：`ref/{for-each-ref,favorites,cleanup}`、`rebase/todo`、`log/{log-filter,commit-files,graph-parser}`、`merge/diff3`、`commit/trailer`、`git-state/conflict-detector`、`blame/blame-parser`。 -- 命令 56 → 77；单测 64 → 166（+21 文件）；集成 3/3；lint/类型/构建全程 GREEN。 -- 关键算法（reword helper / graph 解析 / diff3 / blame 解析）均做真实 git 数据功能性验证。 -- git 底座：稳定 API 能做的用 `Repository.*`；缺口用 `GitRepositoryService.execGit`（复用 `api.git.path` 同一二进制）。 - -### 待补（后续） -- Commit webview 的 Co-authored-by / author 覆盖（`--author`）/ undo-last-commit 按钮 UI 接线（engine trailer 已就绪）。 -- Partial 多文件选择 UX、行级 split chunks（IDEA "Include Selected Lines"）。 -- 目录/folder diff（虚拟文档）、Submodules 管理。 -- M5 AI Agent（5 个接缝已预埋 Null 实现，本轮未启动）。 +## [0.0.1] - 2026-06-30 — 首个 MVP 正式版 +首个对外正式版本，在 VS Code 上完整复刻 IntelliJ IDEA 的 Git 工具窗口与 Commit 提交窗口。采用**路径 B**（消费 `vscode.git` 稳定 `Repository` API 为底座；稳定 API 未覆盖的能力经 `GitRepositoryService.execGit` 复用同一 git 二进制 `api.git.path` 的受控 CLI 通道实现），与原生 Source Control 平行共存、零冲突。规模：**7 视图 / ~92 命令 / 3 配置项**，**218 单元测试** + 集成测试，CI 三平台矩阵全程 GREEN。完整特性见 [Release Note v0.0.1](./docs/releases/v0.0.1.md)。 +### Added -## [0.0.1-rc.2] - 2026-06-28 — 第二个预发布候选 - -包含 rc.1 后的全部 Parity Recovery（Batch 1-4 + Editor Inline Commit），大幅补齐 IDEA Git 功能复刻。 - -### 核心新增（自 rc.1） -- **Editor Inline Commit**（#13）：CodeLens「✓ 提交此 Hunk」→ 仅暂存该 hunk → 提交。 -- **Cherry-pick / Revert / Reset / Branch rename / Compare / Ignore / Reword**（经 `api.git.path` CLI 通道）。 -- **Git 提交图**（Webview `git log --graph` 着色拓扑）+ **Console**（git 命令输出面板）。 -- **partial/hunk 级提交**（hunk 解析引擎 + 选择暂存 + 光标处暂存）+ undo/drop/fixup + cleanup branches + 3-way diff。 -- **忠实 Shelf**（patch 存储 + unshelve 三方合并）+ **交互式 Rebase UI**（pick/squash/fixup/drop Webview）+ **Move Hunk to Changelist**（#25）。 -- **Stash 多栈列表** + Discard + Pull/Push/Fetch + PNG 图标 + Dependabot。 - -### Added — Parity Batch 4（忠实 Shelf + 交互式 Rebase + Line→CL，0.0.6） - -- **忠实 Shelf**（IDEA patch-based，#27-28）：Shelve（`git diff` → patch 存扩展存储 → `git checkout --` 移除工作区）+ Unshelve silently / with 3-way merge + Delete + Shelf TreeView。与 Stash 独立并存。 -- **交互式 Rebase UI**（Webview，#44）：commit 列表 + pick/squash/fixup/drop 动作 → 非交互 rebase（`GIT_SEQUENCE_EDITOR=cp ` + `GIT_EDITOR=:`）。 -- **Move Hunk to Changelist**（#25）：编辑器内光标处 hunk → QuickPick changelist → ChangelistRegistry 持久化 hunk→CL 归属。 - -### Added — Editor Inline Commit（#13，0.0.5） - -> IDEA editor inline commit 的 VS Code 等价（补齐最后一块主要拼图）。 - -- **行内提交 CodeLens**：编辑器中每个未暂存 hunk 上方渲染可点击 CodeLens「✓ 提交此 Hunk (+N -M)」→ 仅暂存该 hunk（patch 重建 + `git apply --cached`）→ 输入 message → `git commit`。 -- 新增 `engine/diff/editor-mapping`（hunk → 编辑器行区域映射，纯逻辑 + 5 单测）；gutter 行标记（绿/红/蓝）由原生 git quickDiff 提供。 -- 其他已暂存内容会一并提交时给出二次确认提示。 - -### Added — Parity Batch 3（partial commit + 高级操作，0.0.4） - -- **partial / 行级提交**（IDEA PartialChangesUtil 等价）：`engine/diff/hunk-parser`（unified diff 解析，7 单测）+ hunk 选择暂存/取消暂存（QuickPick 勾选）+ 光标处 hunk 暂存——经 patch 重建 + `git apply --cached`。 -- **undo commit**（soft reset，保留改动到暂存区）、**drop commit**（`git rebase --onto`，重写历史二次确认）、**fixup**（autosquash rebase，经 env 注入 `GIT_SEQUENCE_EDITOR`）。 -- **cleanup branches**（`git branch --merged` 批量删除）、**copy branch ref**、**3-way diff 概览**（HEAD↔Staged↔Working）。 -- `execGit` 支持 env 注入（为 autosquash 等 rebase 自动化铺路）。 - -### Added — Parity Batch 2（UI 丰富度，0.0.3） - -- **Git 提交图（WebviewPanel）**：`git log --graph --oneline --decorate --all`（CLI）获取拓扑，语义着色渲染（graph 连线 / refs / hash）——补齐 IDEA Log 提交图的可视化拓扑。命令面板 + Log 视图标题按钮。 -- **Console**：Hyper Git Console（OutputChannel）记录所有 `execGit` 命令与输出（对齐 IDEA Console 标签页）。 - -### Added — Parity Batch 1（CLI 功能补齐，0.0.2） - -> 关键转向：引入 `GitRepositoryService.execGit`（复用 vscode.git 的同一 git 二进制 `api.git.path`），补齐稳定 API 未暴露的操作——修正此前"API 限制延后"的过度自我设限。 - -- Cherry-pick（Log 右键）、Revert commit（Log 右键）——经 `git cherry-pick` / `git revert`。 -- Reset HEAD（soft/mixed/hard/keep，命令面板，hard 二次确认）。 -- 分支重命名（Branches 右键 `git branch -m`）、比较分支（`git diff --stat a...b`）。 -- Ignore（写 .gitignore）、改写最新提交（amend）。 -- **Stash 多栈列表**：用 `git stash list`（CLI）修复——apply/pop/drop 按真实 `stash@{n}` 索引（此前 `log({refNames:['stash']})` 仅返回最新 stash 内部提交、语义错误，已弃用）。 - -## [0.0.1-rc.1] - 2026-06-27 — 首发候选（Pre-release） - -首个公开预发布候选，整合 M0-M4 里程碑交付 + 两轮独立 code review 修复。 -版本号遵循 VS Code Marketplace 约定（仅 `major.minor.patch` = `0.0.1`），预发布语义由 `--pre-release` 标记 + git tag `v0.0.1-rc.1` 体现。 - -**核心能力**：多 changelist Changes 视图、Commit 提交窗口（Conventional Commits 校验 + Amend/sign-off/skipHooks + Checkin hook 链）、Log/Branches/Blame/Show History、Stash（create/apply/pop/drop）、Discard 改动、Pull/Push/Fetch。架构路径 B（消费 vscode.git 稳定 API），5 个 AI 接缝已预埋（M5 实现）。 - -**已知限制**（vscode.git 稳定 API 边界）：cherry-pick / revert / reset / 分支重命名 / 行级 hunk 暂存 / 多 stash 列表枚举 / Author 覆盖暂不可用，详见 [实施状态 §3](./docs/milestones/implementation-status.md#3-api-限制汇总vscodegit-稳定-api-边界)。 +#### 变更与 Changelist +- 按 Changelist 分组的 Changes 树视图：新建 / 重命名 / 删除 / 设活动列表 / 跨列表移动文件，`workspaceState` 持久化（重启恢复）；文件状态色复用 `gitDecoration.*` 主题色；单击打开原生 Diff（HEAD ↔ Working）。 +- 文件级操作：丢弃改动、加入 `.gitignore`、显示文件历史。 -### Added — M4 Stash/Shelf（0.5.0） +#### Commit 提交窗口 +- 自绘 IDEA 风格提交面板（WebviewView）：活动 Changelist 文件勾选 + 多行消息编辑器 + Amend / Signed-off-by / 跳过 Git Hooks + **提交** / **提交并推送**；勾选集即提交权威范围（对齐 IDEA「提交该集合」）；最近消息一键复用。 +- Conventional Commits 实时校验（可配置）+ 内置 `ConventionalCommitCheck` Checkin Hook；`CommitPipeline` 责任链对齐 IDEA `CheckinHandler`（校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 -- **Stash 视图**：`StashTreeProvider` 经 `Repository.log({ refNames: ['stash'] })` 枚举 stash（API 不暴露 `git stash list`，以此近似）。 -- **Stash 操作**：`createStash` / `applyStash` / `popStash` / `dropStash`（经 vscode.git 稳定 API），配视图标题按钮与右键菜单 + viewsWelcome。 -- **Shelf（MVP）**：以 stash 近似 IDEA shelve（工程方案 §4 P2 约定）；忠实 patch Shelf 受 API 限制延后。 -- **API 限制（文档化延后）**：行级 partial commit（vscode.git `add` 仅整文件，无 hunk 暂存）、忠实 patch Shelf、Staging Area 模式开关、cherry-pick/revert/reset/分支重命名——均无稳定 API 对应，未来可经 git CLI 兜底或 proposed API 评估。 +#### Log 提交图与历史 +- IDEA 风格 **Graph DAG** webview：基于父子关系自计算 lane 布局，彩色泳道 / 节点 / 分叉·合并连线 / HEAD·分支·标签徽标，`--topo-order` 保拓扑序，行宽随实际 lane 自适应；虚拟化滚动增量加载、↑↓ 键导航；选中提交内联展开变更文件并打开单文件 Diff。 +- **7 个可组合过滤器**：作者、路径、message（grep）、message（正则）、合并模式、日期、一键清除；复制 commit hash、刷新。 +- per-commit 操作：Reset 到此（soft/mixed/hard/keep）、从此新建分支 / 标签、查看包含此提交的分支、Cherry-Pick、Revert。 -### Added — M3 Log/Branches/Diff·Blame（0.4.0） +#### Branches 与 Tags +- 四段分组（收藏 / 本地 / 远程 / 标签）+ ahead·behind·upstream 跟踪展示；新建 / 检出 / 删除 / 重命名 / 合并 / 变基 / 从选中新建并检出；收藏切换、与当前分支比较、任意两分支比较、复制引用、清理已合并分支。 +- **多选批量操作**：`createTreeView({ canSelectMany: true })` 支持框选，批量删除分支/标签、批量复制引用、批量收藏；删除前 `git branch --merged` 分类已合并/未合并并诚实分栏确认强制删除风险；仅单目标语义的操作经 `!listMultiSelection` 在多选时隐藏。 +- 标签：新建（轻量/附注）、删除（多选）、检出（detached HEAD）。 -- **Log TreeView**：消费 `Repository.log()`，按 author/path 过滤（清除过滤）、复制 commit hash、显示文件历史。完整提交图（SVG 拓扑连线）作为后续增强（M3.x）。 -- **Branches TreeView**：消费 `Repository.state.refs`（Local/Remote 分组），活动分支高亮；支持新建/检出/删除/合并/变基（rebase）。 -- **Blame**：`Show Blame` 命令对当前文件执行 `repo.blame` 并以只读文档展示。 -- **Show History**：从 Changes 文件右键跳转 Log 并按该文件路径过滤。 -- **API 限制（文档化延后）**：vscode.git 稳定 API 不含 cherry-pick / revert / reset / 分支重命名，这些 IDEA 功能暂不可用（未来可 CLI 兜底）。 +#### Stash 与 Shelf +- Stash：创建、保留已暂存创建、应用、Pop、删除、从 Stash 创建分支、清空全部，按真实 `stash@{n}` 索引操作。 +- Shelf（IDEA 忠实复刻，基于 patch、独立于 git stash）：Shelve 暂存、静默 Unshelve、带 3-way 合并 Unshelve、删除；独立 TreeView。 -### Fixed — M0/M1/M2 审查修复（0.3.1） +#### 远程与冲突 +- Pull / Push / Fetch（无上游分支自动选定 remote 并建立 `-u` 跟踪；`GitError.stderr` 优先暴露使失败可读）。 +- 对话框：**Push…**（normal / force-with-lease / force + 推送标签）、**Update Project…**（merge / rebase）、**Merge…**（ff-only / no-ff / squash + 自定义消息）。 +- 冲突兜底引导：merge/rebase/pull/cherry-pick/revert/stash-pop/unshelve 失败时检测冲突并弹「解决/中止」；自绘 **3-way Merge Editor**（OURS / RESULT 可编辑 / THEIRS + 写回 `git add`）；冲突文件「采用 Ours / Theirs」。 -经 3 路独立 code review（正确性 / 架构 / 完整性）交叉复核后修复： +#### 历史编辑与高级操作 +- Cherry-Pick、Revert、Reset HEAD（soft/mixed/hard/keep）、交互式 Rebase（webview：pick/squash/fixup/drop + reword + 拖拽重排，经 `GIT_SEQUENCE_EDITOR` 非交互写入）、撤销最近提交（soft）、删除提交（rebase）、Fixup（autosquash）、改写最新提交信息。 -- **GitRepositoryService**：仓库切换时 `onDidChange` 订阅累积泄漏 → 改用单 `repoSub`，切换/卸载时 dispose。 -- **pickRepository**：`startsWith` 误匹配（无路径边界）→ 改用 `api.getRepository(folder.uri)` 精确匹配。 -- **getChanges**：缺失 `indexChanges`（已暂存文件不可见）→ 合并 index/working/untracked 按相对路径去重（index 优先）。 -- **commit 语义**：未勾选的已暂存文件先 `restore --staged`，让勾选集成为提交权威范围（对齐 IDEA「提交该集合」）。 -- **push 失败**：commit 成功后 push 失败误报「提交失败」→ 返回 `ok:true` + `warning`。 -- **extension.ts**：三个 `onDidChange` 订阅入 `subscriptions`（修复卸载泄漏）。 -- **refresh**：`await repo.status()` 后再刷新（避免陈旧数据）。 -- **conventional-linter**：Windows `\r\n` 行尾 + 中文/Unicode scope 支持。 -- **commit-webview**：`onDidReceiveMessage` 绑定 `view.onDidDispose`（修复重载泄漏）；nonce 改用 `crypto.randomBytes`；选中态 `setState` 持久化。 -- **changes-tree**：tooltip 显示状态全称（Modified 而非 M）；清理 `CommitFileItem` 冗余 `status/statusName` 字段。 -- **测试补齐**：`ConventionalCommitCheck`、`CommitService.executeCommit`（mock Repository，覆盖 CC 阻断/无文件/amend 透传/unstage/push 警告）、`git-status-map` 全量、`amend` 真实集成。 +#### 编辑器内能力 +- 行内提交：每个未暂存 Hunk 上方渲染 CodeLens「提交此 Hunk」→ patch 重建 + `git apply --cached` 仅暂存该 Hunk → 提交（含他处已暂存内容的二次确认）。 +- 部分暂存 / 取消暂存、光标处暂存、Hunk 归属 Changelist（持久化 hunk→CL 映射）。 +- Blame 行内注解：逐行作者 / 日期 / hash 显示于编辑器内，悬浮展示提交详情，文档编辑时自动清除。 -### Added — M2 Commit 提交窗口（0.3.0） +#### Worktrees +- 全生命周期管理：新建（新分支 / 检出已有 / detached）、在新窗口打开、锁定 / 解锁、移动、复制路径、删除（安全 / 强制）、清理失效 Worktree、刷新。 -- Commit 提交窗口（WebviewView 自绘 IDEA 风格）：活动 changelist 文件勾选 + 多行 Commit Message 编辑器 + Amend / Signed-off-by / 跳过 Git hooks 选项 + Commit / Commit and Push 按钮。 -- Conventional Commits 实时校验：`engine/commit/conventional-linter` 纯函数 + webview 指示器（ok/warning/error）+ 内置 `ConventionalCommitCheck` Checkin hook（pipeline 内阻断不合规提交）。 -- `CommitPipeline` 责任链接入提交流程（对齐 IDEA `CheckinHandler`：校验 → stage → hook 链 → commit → 可选 push）。 -- AI 接缝 5 接口 + Null 实现注入 CommitService（`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`），M5 替换为真实实现。 -- 最近提交消息复用（`workspaceState` 持久化，webview 一键填入）。 -- 真实 git 提交闭环集成测试（fixture 仓库 + `vscode.git` add/commit + git log 校验）。 +#### 工具与配置 +- 导出 / 应用 Patch、查看 Reflog、3-way Diff 概览（HEAD ↔ Staged ↔ Working）、Console 命令输出面板。 +- 配置项：`hyperGit.commit.template`、`hyperGit.commit.conventional`、`hyperGit.ai.enabled`（M5 预留，暂不生效）。 -### Added — M1 Git Adapter + 多 changelist Changes（0.2.0） +#### 架构与质量 +- 正交分层：`engine/`（纯逻辑，零 vscode 依赖、Vitest 可测）、`adapter/`（唯一接触 vscode API）、`agent/`（AI 接缝）、`ui/`、`shared/protocol.ts`（Webview ↔ Host 契约单一事实源）、`infra/`。 +- AI 接缝预埋 5 接口 + Null 实现（`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`），对齐 IDEA `CheckinHandler` 生命周期，M5 替换为真实实现。 +- 品牌图标统一为「Git Pull Request」造型（活动栏 SVG + Marketplace 徽标 + README 头图，字形改编自 Tabler Icons，MIT）；活动栏图标实时显示未提交文件数角标。 +- CI 流水线：lint → 类型 → 构建 → 三平台测试矩阵（Ubuntu/macOS/Windows，Linux 经 xvfb）→ 打包 vsix；`v*` 标签触发 GitHub Release（附带可本地安装的 `.vsix`，正文取自 `docs/releases/`）+ OpenVSX 发布；VS Code Marketplace 由 `ENABLE_MARKETPLACE_PUBLISH` 变量门控。 -- Git Adapter：`GitRepositoryService` 封装内置 vscode.git 稳定 `Repository` API（读取 workingTreeChanges/untrackedChanges、状态变更事件、diff/toGitUri 委托）。 -- 多 changelist：`ChangelistRegistry`（active 列表、新建/重命名/删除/移动 + `workspaceState` 持久化，重启恢复）+ 引擎纯分组逻辑 `groupByChangelist`。 -- Changes TreeView：changelist 一级节点 + 文件叶子，状态色复用 `gitDecoration.*` 主题色（ThemeIcon + ThemeColor），文件单击打开原生 `vscode.diff`。 -- 命令：`refresh` / `newChangelist` / `setActiveChangelist` / `renameChangelist` / `deleteChangelist` / `moveChangelist` / `openDiff`，配视图标题与右键菜单（`viewItem` 上下文键）。 -- 测试：新增 `changelist-grouper`（5）+ `git-status-map`（9）单元测试；集成测试覆盖全部 M1 命令注册。 -- 工程修复：eslint flat config 忽略 `.vscode-test/**`（规避本地 test-electron 下载的 VS Code 导致 lint OOM）。 +### 已知限制 -### Added — M0 脚手架 + CI +- 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 实现，本版未启动）。 -- 初始化 pnpm + esbuild + TypeScript（strict）工程骨架，对齐官方 `esbuild-sample`。 -- 正交分层目录：`engine/`（纯逻辑，零 vscode 依赖）、`adapter/`、`agent/`（AI 接缝预留）、`ui/`、`shared/`、`infra/`。 -- 质量基础设施：ESLint 9 flat config + typescript-eslint + @stylistic、Prettier、Vitest（engine 单测）、@vscode/test-electron + Mocha（集成测试）。 -- 工程约束：`.npmrc`（`node-linker=hoisted` 规避 vsce/pnpm hoisting）、`.vscodeignore`、`engines.vscode ^1.85.0` 与 `@types/vscode 1.85.0` 严格对齐。 -- 扩展贡献点：活动栏视图容器 `hyper-git` + `hyperGit.changes` 树视图（M0 占位，M1 接入真实 changelist）+ `hyperGit.showVersion` 命令 + 配置项（commit 模板 / Conventional Commits 开关 / AI 开关预留）。 -- 引擎层纯逻辑：`engine/scm-mapping`（FileStatus → gitDecoration.* 主题色映射）、`engine/commit/pipeline`（Checkin hook 责任链，对齐 IDEA `CheckinHandler.ReturnResult`）。 -- AI 接缝接口 + Null 实现：`agent/llm-provider.ts`（`ILlmProvider`）、`agent/pre-commit.ts`（`IPreCommitInspector`）。 -- Webview ↔ Host 消息契约单一事实源：`shared/protocol.ts`。 -- CI 流水线 `.github/workflows/ci.yml`：lint → build → test 矩阵（ubuntu/mac/win + Linux xvfb）→ package vsix → artifact；`tag v*` → 双市场发布（Marketplace + OpenVSX）。 +[0.0.1]: https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.1 diff --git a/README.md b/README.md index c28b974..11931fc 100644 --- a/README.md +++ b/README.md @@ -7,61 +7,97 @@

在 VS Code 上完整复刻 IntelliJ IDEA 的 Git 工具窗口 与 Commit 提交窗口，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。

+ CI License: MIT + VS Code >= 1.85

## 为什么需要 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 扩展
稳定 Repository API"] + GitBin["git 二进制
api.git.path"] + end + + subgraph HG["Hyper Git（路径 B）"] + direction TB + UI["UI 层 · 自绘视图
Changes · Commit · Log(DAG) · Branches
Stash · Shelf · Worktrees"] + ADP["Adapter 层 · 唯一接触 vscode API
GitRepositoryService · ChangelistRegistry
TreeProviders · Webviews"] + ENG["Engine 层 · 纯逻辑 · 零 vscode 依赖 · 可单测
graph-layout · hunk-parser · diff3
conventional-linter · for-each-ref ..."] + AGT["Agent 接缝 · M5 预留
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（接缝已预留，实现待启动） | ⏳ | ## 开发 @@ -69,14 +105,16 @@ IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit / Shelf / Stash` 标 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）。 diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md index 00aff2a..91ece86 100644 --- a/docs/.agents/knowledge-map.md +++ b/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。 diff --git a/docs/README.md b/docs/README.md index 4f7e7b0..350ff66 100644 --- a/docs/README.md +++ b/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)。 diff --git a/docs/releases/README.md b/docs/releases/README.md new file mode 100644 index 0000000..51dbd46 --- /dev/null +++ b/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) — 全部文档与调研资产索引。 diff --git a/docs/releases/v0.0.1.md b/docs/releases/v0.0.1.md new file mode 100644 index 0000000..59f7e13 --- /dev/null +++ b/docs/releases/v0.0.1.md @@ -0,0 +1,96 @@ +# Hyper Git v0.0.1 — 首个 MVP 正式版 + +> 在 VS Code 上完整复刻 IntelliJ IDEA 的 **Git 工具窗口** 与 **Commit 提交窗口**，并为未来 AI Agent 自主代理预留架构接缝。 + +这是 Hyper Git 的首个对外正式版本。它把 IDEA 里那套被开发者高频依赖、迁移到 VS Code 后却长期缺失的 Git 工作流——多 Changelist 变更组织、忠实的提交窗口、可视化提交图、Shelf、行级提交——一次性补齐，并与原生 Source Control 平行共存、零冲突。 + +--- + +## ✨ 亮点速览 + +- **多 Changelist 变更组织**：像 IDEA 一样把工作区改动分组到命名列表，设活动列表为提交目标，重启自动恢复。 +- **IDEA 风格 Commit 窗口**：自绘提交面板，Conventional Commits 实时校验，Amend / Sign-off / 跳过 Hook，提交或提交并推送。 +- **IDEA 风格提交图（自绘 DAG）**：彩色泳道、分叉·合并连线、HEAD/分支/标签徽标，虚拟滚动增量加载，告别 `git log --graph` 的粗糙 ASCII。 +- **Branches 多选批量操作**：框选多个分支/标签，一次性删除、复制引用、收藏；已合并/未合并诚实分栏确认。 +- **忠实 Shelf + 全量 Worktree**：基于 patch 的 Shelf（独立于 stash）与 Worktree 全生命周期管理（新建/打开/锁定/移动/删除）。 +- **行级与 Hunk 提交**：编辑器内 CodeLens「提交此 Hunk」、部分暂存、光标处暂存、Hunk 归属 Changelist。 +- **3-way Merge Editor**：自绘三栏冲突编辑器（OURS / RESULT / THEIRS），冲突时一键调起。 + +--- + +## 🧩 完整能力 + +### 变更与 Changelist +按 Changelist 分组的 Changes 树（状态色复用 `gitDecoration.*` 主题色）；新建 / 重命名 / 删除 / 设活动 / 跨列表移动文件，`workspaceState` 持久化；单击打开原生 Diff（HEAD ↔ Working）；丢弃改动、加入 `.gitignore`、显示文件历史。 + +### Commit 提交窗口 +多行消息编辑器 + Conventional Commits 实时校验（可配置开关）；Amend、Signed-off-by、跳过 Git Hooks；勾选集即提交权威范围（对齐 IDEA「提交该集合」）；最近消息一键复用；**提交** 与 **提交并推送** 双动作；提交流水线对齐 IDEA `CheckinHandler`（校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 + +### Log 提交图与历史 +自绘 **Graph DAG** webview（彩色泳道 / 节点 / 连线 / 引用徽标，拓扑保序，虚拟化滚动，↑↓ 键导航）；选中提交内联展开变更文件并打开单文件 Diff；**7 个可组合过滤器**——作者、路径、message（grep）、message（正则）、合并模式、日期、一键清除；per-commit 操作——复制 hash、Reset 到此、从此新建分支/标签、查看包含此提交的分支、Cherry-Pick、Revert。 + +### Branches 分支管理 +四段分组（收藏 / 本地 / 远程 / 标签）+ ahead·behind·upstream 跟踪展示；新建 / 检出 / 删除 / 重命名 / 合并 / 变基 / 从选中新建并检出；收藏切换、与当前分支比较、任意两分支比较、复制引用、清理已合并分支；**多选批量**：批量删除分支/标签、批量复制引用、批量收藏（已合并/未合并风险诚实分栏确认）。 + +### 标签 Tags +新建（轻量/附注）、删除（支持多选）、检出（进入 detached HEAD）、从提交新建标签。 + +### Stash 与 Shelf +**Stash**：创建、保留已暂存创建、应用、Pop、删除、从 Stash 创建分支、清空全部，按真实 `stash@{n}` 索引操作。**Shelf**（IDEA 忠实复刻，基于 patch、独立于 git stash）：Shelve 暂存、静默 Unshelve、带 3-way 合并 Unshelve、删除。 + +### 远程操作 +Pull / Push / Fetch（无上游分支自动建立 `-u` 跟踪）；**Push…**（normal / force-with-lease / force + 推送标签）、**Update Project…**（merge / rebase）、**Merge…**（ff-only / no-ff / squash + 自定义消息）三类对话框；冲突兜底引导与 **3-way Merge Editor**，以及冲突文件「采用 Ours / Theirs」。 + +### 历史编辑与高级操作 +Cherry-Pick、Revert、Reset HEAD（soft / mixed / hard / keep）、交互式 Rebase（webview：pick/squash/fixup/drop + reword + 拖拽重排）、撤销最近提交（soft）、删除提交（rebase）、Fixup（autosquash）、改写最新提交信息。 + +### 编辑器内能力 +**行内提交**（每个未暂存 Hunk 上方 CodeLens「提交此 Hunk」）；部分暂存 / 取消暂存、光标处暂存、Hunk 归属 Changelist；**Blame 行内注解**（逐行作者/日期/hash + 悬浮详情）。 + +### 工具 +导出 / 应用 Patch、查看 Reflog、3-way Diff 概览（HEAD ↔ Staged ↔ Working）、Console 命令输出面板。 + +### 配置项 +`hyperGit.commit.template`（提交模板）、`hyperGit.commit.conventional`（CC 校验开关）、`hyperGit.ai.enabled`（AI 能力开关，M5 预留）。 + +> 规模实证：**7 个视图 / ~92 个命令 / 3 个配置项**，覆盖 IDEA Git 工具窗口主线工作流。 + +--- + +## 🏗️ 架构 + +采用 **路径 B（消费 + 自绘）**，与原生 Source Control 平行共存、零冲突： + +- **消费** 内置 `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 接缝**：预埋 5 个接口（`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`，对齐 IDEA `CheckinHandler` 生命周期），M5 替换为真实实现，本版未启动。 + +质量基线：**218 个单元测试**（engine 纯逻辑）+ 集成测试（`@vscode/test-electron` + fixture 仓库），CI 三平台（Ubuntu / macOS / Windows）矩阵校验，lint / 类型 / 构建全程 GREEN。 + +--- + +## 📦 安装 + +- **手动安装（当前推荐）**：从 [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 工作区。 + +--- + +## ⚠️ 已知限制 + +- 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 实现，本版未启动。 + +--- + +## 🙏 致谢与许可 + +图标字形改编自 [Tabler Icons](https://github.com/tabler/tabler-icons)（MIT）。完整工程变更见 [CHANGELOG](https://github.com/ThreeFish-AI/hyper-git/blob/master/CHANGELOG.md)。 + +许可证：[MIT](https://github.com/ThreeFish-AI/hyper-git/blob/master/LICENSE)。