diff --git a/CHANGELOG.md b/CHANGELOG.md index 8838f9b..eac3a13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,9 @@ > 面向用户的发布说明（含完整特性叙述与安装指引）见 [`docs/releases/`](./docs/releases/README.md)。 -## [0.0.1] - 2026-06-30 — 首个 MVP 正式版 +## [0.0.6] - 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)。 +首个对外正式版本，在 VS Code Marketplace / OpenVSX 上以 **「Hyper Git - Agentic Git」** 之名发布。为 VS Code 提供统一的 Git 变更管理与提交工作流（多变更分组、自绘提交面板、可视化提交图、Shelf、行级提交）。采用**路径 B**（消费 `vscode.git` 稳定 `Repository` API 为底座；稳定 API 未覆盖的能力经 `GitRepositoryService.execGit` 复用同一 git 二进制 `api.git.path` 的受控 CLI 通道实现），与原生 Source Control 平行共存、零冲突。规模：**7 视图 / 93 命令 / 6 配置项**，**280 单元测试** + 集成测试，CI 三平台矩阵全程 GREEN。完整特性见 [Release Note v0.0.6](./docs/releases/v0.0.6.md)。 ### Added @@ -15,11 +15,13 @@ - 文件级操作：丢弃改动、加入 `.gitignore`、显示文件历史。 #### Commit 提交窗口 -- 自绘 IDEA 风格提交面板（WebviewView）：活动 Changelist 文件勾选 + 多行消息编辑器 + Amend / Signed-off-by / 跳过 Git Hooks + **提交** / **提交并推送**；勾选集即提交权威范围（对齐 IDEA「提交该集合」）；最近消息一键复用。 -- Conventional Commits 实时校验（可配置）+ 内置 `ConventionalCommitCheck` Checkin Hook；`CommitPipeline` 责任链对齐 IDEA `CheckinHandler`（校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 +- 自绘提交面板（WebviewView）：活动 Changelist 文件勾选 + 多行消息编辑器 + Amend / Signed-off-by / 跳过 Git Hooks + **提交** / **提交并推送**；勾选集即提交权威范围（仅提交选中的文件集合）；最近消息一键复用。 +- Conventional Commits 实时校验（可配置）+ 内置 `ConventionalCommitCheck` Checkin Hook；`CommitPipeline` 责任链设计参考 JetBrains `CheckinHandler`（校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 #### Log 提交图与历史 -- IDEA 风格 **Graph DAG** webview：基于父子关系自计算 lane 布局，彩色泳道 / 节点 / 分叉·合并连线 / HEAD·分支·标签徽标，`--topo-order` 保拓扑序，行宽随实际 lane 自适应；虚拟化滚动增量加载、↑↓ 键导航；选中提交内联展开变更文件并打开单文件 Diff。 +- 自绘 **Graph DAG** webview：基于父子关系自计算 lane 布局，彩色泳道 / 节点 / 分叉·合并连线 / HEAD·分支·标签徽标，`--topo-order` 保拓扑序，行宽随实际 lane 自适应；虚拟化滚动增量加载、↑↓ 键导航；选中提交内联展开变更文件并打开单文件 Diff。 +- **提交图 × CI 状态**：每条提交行最右侧显示 GitHub CI 最终状态（绿勾/红叉/运行中），悬停 Tooltip 展示各项检查 + 未通过原因 + 跳转链接；复用 VS Code 内置 GitHub 认证（`vscode.authentication`，凭证不经 chat/日志/webview），仅取可见行懒加载、批量 GraphQL（≤100 oid）+ 限流冷却、终态缓存；非 GitHub 远程零图标零请求，支持 github.com 与 GitHub Enterprise；配置 `hyperGit.log.ci.{enabled,remote,provider}`。 +- **Checkpointer 过滤**：Log 视图新增 Checkpointer 选项，默认剔除 AI 编码工具产生的自动快照（checkpoint）提交，提交图更干净，可按需开启。 - **7 个可组合过滤器**：作者、路径、message（grep）、message（正则）、合并模式、日期、一键清除；复制 commit hash、刷新。 - per-commit 操作：Reset 到此（soft/mixed/hard/keep）、从此新建分支 / 标签、查看包含此提交的分支、Cherry-Pick、Revert。 @@ -30,7 +32,7 @@ #### Stash 与 Shelf - Stash：创建、保留已暂存创建、应用、Pop、删除、从 Stash 创建分支、清空全部，按真实 `stash@{n}` 索引操作。 -- Shelf（IDEA 忠实复刻，基于 patch、独立于 git stash）：Shelve 暂存、静默 Unshelve、带 3-way 合并 Unshelve、删除；独立 TreeView。 +- Shelf（基于 patch、独立于 git stash 的改动搁置机制）：Shelve 暂存、静默 Unshelve、带 3-way 合并 Unshelve、删除；独立 TreeView。 #### 远程与冲突 - Pull / Push / Fetch（无上游分支自动选定 remote 并建立 `-u` 跟踪；`GitError.stderr` 优先暴露使失败可读）。 @@ -50,19 +52,19 @@ #### 工具与配置 - 导出 / 应用 Patch、查看 Reflog、3-way Diff 概览（HEAD ↔ Staged ↔ Working）、Console 命令输出面板。 -- 配置项：`hyperGit.commit.template`、`hyperGit.commit.conventional`、`hyperGit.ai.enabled`（M5 预留，暂不生效）。 +- 配置项：`hyperGit.commit.template`、`hyperGit.commit.conventional`、`hyperGit.ai.enabled`（M5 预留，暂不生效）、`hyperGit.log.ci.{enabled,remote,provider}`（提交图 CI 状态）。 #### 架构与质量 - 正交分层：`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 替换为真实实现。 +- AI 接缝预埋 5 接口 + Null 实现（`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`），设计参考 JetBrains `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` 变量门控。 ### 已知限制 - Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ 撤销最近提交按钮 UI 接线（engine `trailer` 已就绪，仅缺 webview 交互）。 -- Partial 多文件选择 UX、行级 split chunks（IDEA「Include Selected Lines」）。 +- Partial 多文件选择 UX、行级 split chunks（按选定行拆分提交）。 - 目录 / folder diff（虚拟文档）、Submodules 管理。 - M5 AI Agent（5 个接缝已预埋 Null 实现，本版未启动）。 -[0.0.1]: https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.1 +[0.0.6]: https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.6 diff --git a/README.md b/README.md index 11931fc..080e18f 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

Hyper Git

-

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

+

为 VS Code 带来统一的 Git 变更管理 与 提交工作流——多变更分组、自绘提交面板、可视化提交图、Shelf、行级提交，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。

CI @@ -14,29 +14,29 @@ ## 为什么需要 Hyper Git -IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit / Shelf / Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是开发者高频依赖的工作流。迁移到 VS Code 后，原生 Source Control 视图**缺少**：多 Changelist、忠实的 Commit 窗口、提交前检查流水线、Shelf、行级提交、可视化提交图等能力。Hyper Git 旨在 1:1 补齐这一体验，并与原生 Source Control 平行共存、零冲突。 +在重度 Git 协作中，开发者高频依赖一套统一的变更管理工作流：把改动分组到命名列表、在专门的提交面板里逐项勾选并校验、用可视化提交图审阅历史、用 Shelf 临时搁置改动、按行/按 Hunk 精确提交。VS Code 原生 Source Control 视图在这些能力上**存在空缺**：没有多 Changelist、没有忠实的提交窗口、没有提交前检查流水线、没有 Shelf、没有行级提交、没有可视化提交图。Hyper Git **补齐这些能力**，并与原生 Source Control 平行共存、零冲突。 -## 核心能力（v0.0.1） +## 核心能力（v0.0.6） - **多 Changelist Changes 视图**：将改动分组到命名列表，设活动列表为提交目标，新建/重命名/删除/移动，`workspaceState` 持久化（重启恢复）；状态色复用 `gitDecoration.*` 主题色。 -- **Commit 提交窗口**：自绘 IDEA 风格面板 + Conventional Commits 实时校验 + Amend / Sign-off / 跳过 Hook + 提交 / 提交并推送；勾选集即提交权威范围；最近消息复用。 +- **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）。 +- **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）。 -> 规模：**7 视图 / ~92 命令 / 3 配置项**，覆盖 IDEA Git 工具窗口主线工作流。完整发布说明见 [Release Note v0.0.1](./docs/releases/v0.0.1.md)。 +> 规模：**7 视图 / 93 命令 / 6 配置项**，覆盖 Git 变更管理主线工作流。完整发布说明见 [Release Note v0.0.6](./docs/releases/v0.0.6.md)。 ## 架构（路径 B：消费 + 自绘） - **消费** 内置 `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。 +- **自绘视图** 承载完整的变更管理 UI；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。 +- **AI 接缝**：预留 `ILlmProvider` / `IPreCommitInspector` 等 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），实现延后至 M5。 ```mermaid flowchart TB @@ -74,15 +74,15 @@ flowchart TB ## 安装 -- **手动（当前推荐）**：从 [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`（发布上线后可用）。 +- **手动（当前推荐）**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `hyper-git-agentic-git-0.0.6.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 工作区。 ## 已知限制 - Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ 撤销最近提交的**按钮 UI 接线**（engine `trailer` 已就绪，仅缺 webview 交互）。 -- Partial 多文件选择 UX、行级 split chunks（IDEA「Include Selected Lines」）。 +- Partial 多文件选择 UX、行级 split chunks（按选定行拆分提交）。 - 目录 / folder diff（虚拟文档）、Submodules 管理。 - M5 AI Agent（5 个接缝已预埋 Null 实现，本版未启动）。 @@ -105,7 +105,7 @@ flowchart TB pnpm install # 安装依赖 pnpm run compile # 类型检查 + lint + 构建 pnpm run watch # 监听构建（F5 启动 Extension Host 调试） -pnpm run test:unit # 单元测试（engine 纯逻辑，Vitest，218 例） +pnpm run test:unit # 单元测试（engine 纯逻辑，Vitest，280 例） pnpm run test:integration # 集成测试（@vscode/test-electron） pnpm run package # 生产构建 pnpm dlx @vscode/vsce package # 打包 .vsix diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md index 735db45..dff7a5c 100644 --- a/docs/.agents/knowledge-map.md +++ b/docs/.agents/knowledge-map.md @@ -19,9 +19,9 @@ - [Log 视图 CI 状态](../docs/features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + Tooltip 明细）：认证、限流、懒加载、边界与配置。 - [实施状态总览](../docs/milestones/implementation-status.md) — M0-M5 交付记录 + API 限制 + M5 AI 设计 + 验证/发布（**实施看板**）。 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。 -- [IDEA 功能复刻矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**）。 +- [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。 - [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。 -- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.1](../releases/v0.0.1.md)）。 +- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.6](../releases/v0.0.6.md)）。 ## 架构分层（src/） > 依赖方向单向：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI。 diff --git a/docs/README.md b/docs/README.md index f4bc25c..b32bb9f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,19 +5,19 @@ ## 工程方案与需求基线（高频引用） - [实施状态总览（M0-M5）](./milestones/implementation-status.md) — 里程碑交付记录、P0/P1 达成矩阵、API 限制、M5 AI 设计、验证与发布状态（**实施看板**）。 - [工程实施方案](./architecture/engineering-plan.md) — 全链路调研结论 + 路径 B 架构 + M0-M5 里程碑路线图 + 风险与验证（**开发蓝图**）。 -- [IDEA 功能复刻矩阵](./requirements/idea-feature-matrix.md) — 56 个原子功能点 / 8 组 + CheckinHandler 生命周期（**验收基线**）。 +- [Git 功能完备性矩阵](./requirements/idea-feature-matrix.md) — 56 个原子功能点 / 8 组 + CheckinHandler 生命周期（**验收基线**）。 ## 功能文档 - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。 ## 发布说明 -- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.1 首个 MVP](./releases/v0.0.1.md)。 +- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.6 首个 MVP](./releases/v0.0.6.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 表面映射表。 - [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md) — 双市场（Marketplace + OpenVSX）、CI 矩阵、版本治理、安全。 -- [05 · AI Agent 架构预留](./research/05-ai-agent-seams.md) — AI 接缝（ILlmProvider 等）+ IDEA CheckinHandler 对齐 + 渐进式引入路线。 +- [05 · AI Agent 架构预留](./research/05-ai-agent-seams.md) — AI 接缝（ILlmProvider 等）+ 借鉴 JetBrains CheckinHandler 责任链设计 + 渐进式引入路线。 ## 协作与规范 - [AGENTS.md](../AGENTS.md) — 协作协议与工程行为准则。 diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md index 61c8683..a00565b 100644 --- a/docs/architecture/engineering-plan.md +++ b/docs/architecture/engineering-plan.md @@ -1,13 +1,13 @@ # Hyper Git — VS Code 扩展工程实施方案 -> 复刻 IntelliJ IDEA 社区版「Git 工具窗口 + Commit 提交窗口」全功能，并为未来 AI Agent 自主代理预留架构接缝。 +> 提供完整的「Git 变更管理 + Commit 提交工作流」（功能完备性参考 IntelliJ IDEA 等成熟实现），并为未来 AI Agent 自主代理预留架构接缝。 > 决策已与用户确认：**路径 B**（消费 `vscode.git` API + 自建 changelist registry + 独立视图容器）、扩展命名 **Hyper Git**、**双市场发布**、**AI 现仅预留接缝 + Null 实现、延后至 M5**。 --- ## 0. Context（背景与目标） -**为什么做**：IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit/Shelf/Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是 Java/全栈开发者高频依赖的工作流，但迁移到 VS Code 后只能用原生 Source Control 视图（无多 changelist、无忠实 Commit 窗口、无提交前检查流水线）。本项目目标是**在 VS Code 上 1:1 复刻该体验**，并在未来为 git 管理引入 AI Agent（提交信息生成 / 提交前代码审查 / 变更语义分组 / 冲突解决）。 +**为什么做**：IntelliJ IDEA 的统一 Git 工具窗口（顶部 `Commit/Shelf/Stash` 标签页 + Changes 变更树 + Commit Message 编辑区 + 提交前 Inspection）是 Java/全栈开发者高频依赖的工作流，但迁移到 VS Code 后只能用原生 Source Control 视图（无多 changelist、无独立 Commit 窗口、无提交前检查流水线）。本项目目标是**在 VS Code 上提供同等完备的 Git 变更管理与提交工作流**，并在未来为 git 管理引入 AI Agent（提交信息生成 / 提交前代码审查 / 变更语义分组 / 冲突解决）。 **当前状态**：仓库为全新 greenfield 工程（仅有 `.agents/` 文档脚手架与 AGENTS.md 协议，无源码 / 无 package.json / 无 README）。本方案从零搭建。 @@ -23,13 +23,13 @@ | 决策项 | 结论 | 循证依据 | |---|---|---| | **git 操作底座** | 消费内置 `vscode.git` 扩展导出的 `API`（`getAPI(1)` → `Repository`），**不自调 git CLI、不重造状态机** | `git.d.ts` 已暴露 commit/add/revert/diff/blame/log/stash/branch/merge/rebase 全套；GitHub PR 扩展即此模式 | -| **changelist 表达** | **自建 changelist registry**（仿 IDEA `ChangeListManager`），以 TreeView 渲染；**不**注册竞争性 SCM Provider | Track1：IDEA active 列表 + 跨列表行级归属，原生 SCM group 无法表达 | +| **changelist 表达** | **自建 changelist registry**（借鉴 JetBrains `ChangeListManager` 设计），以 TreeView 渲染；**不**注册竞争性 SCM Provider | Track1：IDEA active 列表 + 跨列表行级归属，原生 SCM group 无法表达 | | **视图容器** | 活动栏新建独立视图容器 `hyper-git`，承载 Changes/Commit/Log/Branches/Shelf/Stash；**不接管/不替代原生 Source Control 视图**（避免双胞胎冲突） | Track2：注册独立 SCM 会与原生 git 视图并列混淆 | | **Commit 编辑器** | WebviewView 自绘（多行 / 模板 / Conventional Commits 校验 / Amend / Author / sign-off） | 原生 `SourceControlInputBox` 仅 `value` 字段，Provider 已删除 | | **Log 提交图** | Webview 自绘 SVG graph + 消费 `Repository.log()` | `scmHistoryProvider` 为 proposed，上架不可用 | | **Diff 预览** | 复用 `vscode.diff` + `api.toGitUri(uri,'HEAD')`（零成本） | Track2 §5.5 | | **发布** | 双市场（Marketplace + OpenVSX） | Cursor/Windsurf 走 OpenVSX；AI 受众主战场 | -| **AI** | 现仅定义接缝 + Null 实现，实现延后 M5 | YAGNI + 复用 IDEA `CheckinHandler` 语义 | +| **AI** | 现仅定义接缝 + Null 实现，实现延后 M5 | YAGNI + 借鉴 JetBrains `CheckinHandler` 责任链语义 | **架构总览（Mermaid，深色模式高对比）**： @@ -105,7 +105,7 @@ hyper-git/ ├── engine/ # 【引擎层】纯领域逻辑，零 vscode 依赖 │ ├── model/ # FileChange / Changelist / Commit / Branch / StashEntry / ConflictHunk │ ├── diff/ # diff 解析 + 行级 patch（partial commit 基础） - │ ├── commit/ # CommitPipeline（Checkin hook 责任链，仿 IDEA CheckinHandler） + │ ├── commit/ # CommitPipeline（Checkin hook 责任链，借鉴 JetBrains CheckinHandler 设计） │ └── scm-mapping/ # Status(M/A/D/U/R/C) → decorations 映射（纯函数） ├── adapter/ # 【适配层】唯一接触 vscode API │ ├── git-repository.ts # GitRepositoryAdapter：封装 vscode.git Repository（add/commit/diff/log/stash/branch…） @@ -118,7 +118,7 @@ hyper-git/ ├── agent/ # 【代理层】AI 接缝（预留，Null 实现） │ ├── llm-provider.ts # ILlmProvider（模型来源抽象：vscodeLM/byok/openaiCompatible） │ ├── commit-message.ts # ICommitMessageProvider（生成 + Conventional Commits 校验） - │ ├── pre-commit.ts # IPreCommitInspector（对齐 IDEA beforeCheckin/CommitCheck） + │ ├── pre-commit.ts # IPreCommitInspector（借鉴 JetBrains beforeCheckin/CommitCheck 机制） │ ├── grouper.ts # IChangelistGrouper（语义分组） │ ├── conflict.ts # IConflictResolver（三方合并建议） │ └── chat-tools.ts # IChatToolRegistrar（M5 暴露 git 能力给 Agent） @@ -157,9 +157,9 @@ hyper-git/ --- -## 4. IDEA 功能复刻优先级矩阵 +## 4. 功能优先级矩阵 -> 基于 Track1 的 56 功能点，按价值×依赖×难度分入 P0(MVP)/P1(核心对齐)/P2(高级对齐)/P3(AI 增强)。完整 56 项明细见 [IDEA 功能复刻矩阵](../requirements/idea-feature-matrix.md)（后续验收的需求基线）。 +> 基于 Track1 的 56 功能点，按价值×依赖×难度分入 P0(MVP)/P1(核心功能)/P2(高级功能)/P3(AI 增强)。完整 56 项明细见 [功能矩阵](../requirements/idea-feature-matrix.md)（后续验收的需求基线）。 | 优先级 | 功能域 | 代表功能（来源 Track1 编号） | |---|---|---| @@ -168,9 +168,9 @@ hyper-git/ | **P1 核心** | Commit 检查流水线 | 提交前 Inspection 框架(#10，对接 VS Code Diagnostics)、Commit Checks 顺序闸门(#11)、CRLF/大文件预检(#12)、Conventional Commits 校验(#4，IDEA 无内置需自建 linter) | | **P1 核心** | Branches | 创建/检出/删除/重命名(#45/#46)、Merge/Rebase/Pull/Push/Fetch(#48)、Compare(#47) | | **P1 核心** | Stash + Diff | Stash apply/pop/drop(#29/#30)、Annotate(blame)(#37)、Show History(#38) | -| **P2 高级** | Partial / 行级提交 | 按代码块提交(#23)、按行提交(#24)、Move Lines to Changelist(#25)——最难，仿 `PartialChangesUtil` | +| **P2 高级** | Partial / 行级提交 | 按代码块提交(#23)、按行提交(#24)、Move Lines to Changelist(#25)——最难，参考 `PartialChangesUtil` 实现 | | **P2 高级** | Log 提交图 | graph 自绘(#39)、filter(#40)、cherry-pick/revert from log(#41/#42)、Undo Commit(#43) | -| **P2 高级** | Shelf | 忠实 shelve/unshelve with conflict(#27/#28，patch 存储+三方合并)；MVP 先用 stash 近似 | +| **P2 高级** | Shelf | 完整 shelve/unshelve with conflict(#27/#28，patch 存储+三方合并)；MVP 先用 stash 近似 | | **P3 AI 增强** | （M5，接缝现已埋） | AI 提交信息生成、AI 提交前审查、AI 语义分组、AI 冲突解决、AI release notes、Chat Tools 暴露 git 能力 | --- @@ -199,8 +199,8 @@ hyper-git/ - 验收：Log 图正确渲染拓扑；分支操作经真实 git 验证；blame 行级显示作者。 - 依赖：M1、M2。 -**M4 — Shelf + Partial/行级提交 + Stash UI（Parity 收口，0.6.0）** -- 交付：忠实 Shelf（patch 存储 + unshelve 三方合并）、行级 partial commit（仿 `PartialChangesUtil` + 行级 hunk staging）、Stash 完整 UI（apply/pop/drop/clear/keep-index）、Git Staging Area 模式开关。 +**M4 — Shelf + Partial/行级提交 + Stash UI（功能收口，0.6.0）** +- 交付：完整 Shelf（patch 存储 + unshelve 三方合并）、行级 partial commit（参考 `PartialChangesUtil` 实现 + 行级 hunk staging）、Stash 完整 UI（apply/pop/drop/clear/keep-index）、Git Staging Area 模式开关。 - 验收：shelve/unshelve with conflict 可解；单文件部分行可单独提交。 - 依赖：M2、M3。 @@ -213,13 +213,13 @@ hyper-git/ ## 6. AI 集成架构预留点（现建接缝，M5 实现） -> 对齐 IDEA `CheckinHandler` 生命周期（Track1 D 节：`beforeCheckin`/`CommitCheck.runCheck`/`includedChangesChanged`/`checkinSuccessful`/`checkinFailed`）。**只定义契约 + Null 实现，不引入 Copilot 依赖**（未启用 AI 用户零负担）。 +> 借鉴 JetBrains `CheckinHandler` 生命周期设计（Track1 D 节：`beforeCheckin`/`CommitCheck.runCheck`/`includedChangesChanged`/`checkinSuccessful`/`checkinFailed`）。**只定义契约 + Null 实现，不引入 Copilot 依赖**（未启用 AI 用户零负担）。 -| 接缝（Agent 层） | 对齐 IDEA | 为何现在抽 | +| 接缝（Agent 层） | 借鉴 JetBrains 机制 | 为何现在抽 | |---|---|---| | `ILlmProvider`（模型来源抽象） | — | **最关键**：未来切换 vscodeLM/byok/自带 key 的命脉；晚抽则所有 AI 调用散落、迁移成本爆炸 | | `ICommitMessageProvider` | （IDEA 无内置，插件有） | 提交信息是 commit 流水线核心产物，留接缝让"无 AI→LM→自带 key"平滑切换 | -| `IPreCommitInspector` | `beforeCheckin`/`CommitCheck.runCheck`（返回 COMMIT/CANCEL/DEFER，对齐 `ReturnResult`） | 复用 IDEA 20+ 年验证的 hook 闸门机制；AI 审查最佳挂载点 | +| `IPreCommitInspector` | `beforeCheckin`/`CommitCheck.runCheck`（返回 COMMIT/CANCEL/DEFER，参考 `ReturnResult`） | 借鉴 JetBrains 20+ 年验证的 hook 闸门机制设计；AI 审查最佳挂载点 | | `IChangelistGrouper` | （IDEA 无内置） | 写回 changelist 模型（回写工作流，差异化于内置 Copilot） | | `IConflictResolver` | （IDEA 无内置） | 必须 `prepareInvocation` 用户确认（VS Code 工具确认机制，安全红线） | @@ -259,7 +259,7 @@ hyper-git/ - **单元测试（Vitest，< 30s）**：`engine/model`、`engine/diff`（行级 patch）、`engine/scm-mapping`（Status→decorations）、`engine/commit`（hook 责任链顺序/阻断）、Conventional Commits linter 纯函数。 - **集成测试（@vscode/test-electron + Mocha，< 2min）**：`adapter/git-repository`（真实 fixture 仓库读 changes/commit/stash）、`adapter/changelist-registry`（持久化往返）、`adapter/webview`（postMessage 协议契约）、Commit 全链路（勾选→message→commit→验证 `git log`）。 - **手动回归清单**：多 changelist 新建/移动/删除/重启持久化；Amend；Commit and Push；Conventional Commits 拦截；Log 图过滤；分支 merge/rebase；shelve/unshelve with conflict；行级 partial commit。 -- **浏览器/编辑器验证**：按 AGENTS.md 浏览器验证协议——用户已认证 Chrome 主 profile 打开真实仓库，截图验证 UI 还原度（Commit 窗口 vs 图1/图2 对齐）。 +- **浏览器/编辑器验证**：按 AGENTS.md 浏览器验证协议——用户已认证 Chrome 主 profile 打开真实仓库，截图验证 Commit 窗口的 UI 渲染与交互完整性（对照设计参考图1/图2）。 - **发布前自证**：Diff 分析、测试覆盖、三平台 CI 绿、`.vsix` 在干净 VS Code + Cursor 实机安装回归。 --- diff --git a/docs/features/log-ci-status.md b/docs/features/log-ci-status.md index af25484..f976421 100644 --- a/docs/features/log-ci-status.md +++ b/docs/features/log-ci-status.md @@ -1,7 +1,7 @@ # Log 视图 CI 状态（GitHub Actions / Commit Status） -> 在 Log 视图（`hyperGit.log`，IDEA 风格提交图）每条提交上显示其 **CI 最终状态**：绿勾=通过、红叉=失败、 -> 运行中=黄色旋转；悬停图标以浮层 Tooltip 展示「各项检查 + 未通过原因 + 运行链接」，效果对标 IntelliJ IDEA / GitHub。 +> 在 Log 视图（`hyperGit.log`，可视化提交图）每条提交上显示其 **CI 最终状态**：绿勾=通过、红叉=失败、 +> 运行中=黄色旋转；悬停图标以浮层 Tooltip 展示「各项检查 + 未通过原因 + 运行链接」。 > 数据源为 GitHub（Checks API + Commit Status），按 origin 远程主机自动判定 github.com / GitHub Enterprise。 ## 数据流 diff --git a/docs/milestones/implementation-status.md b/docs/milestones/implementation-status.md index df0cdb1..d31d0df 100644 --- a/docs/milestones/implementation-status.md +++ b/docs/milestones/implementation-status.md @@ -2,16 +2,16 @@ > Hyper Git VS Code 扩展的里程碑实施记录、API 限制发现、功能达成矩阵与 M5 AI 设计（留存）。 > 本文档随里程碑推进即时更新；调研与原始方案见 [工程实施方案](../architecture/engineering-plan.md) 与 [调研报告](../research/README.md)。 -> 最后更新：2026-06-29（Parity Recovery Batch 5-12 全量对齐 IDEA 完成）。 +> 最后更新：2026-06-29（Parity Recovery Batch 5-12 全量功能对齐完成）。 > -> **⚠️ 重大更新（2026-06-29，Batch 5-12）**：经 IDEA Git 功能复刻评审，发现「功能多数已实现，但被 Branches 视图渲染 bug + 工具栏未浮现 + 命令 bug 掩盖」。本批 Recovery **先解除可见痛感，再全量补齐**：新增 13 个 engine 纯逻辑模块 + 21 个命令，单测 64 → 166、命令 56 → 77。**§3 所列 vscode.git 稳定 API 限制（cherry-pick/revert/reset/branch rename/hunk 暂存/stash list/graph topology/shelf/author 等）现均已通过 `GitRepositoryService.execGit`（复用 `api.git.path` 同一 git 二进制）受控 CLI 通道解决**。详见 [CHANGELOG](../../CHANGELOG.md) [Unreleased]。 -> AI M5 暂不启动（5 个接缝保留 Null 实现，本轮专注 IDE 对齐）。 +> **⚠️ 重大更新（2026-06-29，Batch 5-12）**：经 Git 功能完备性评审，发现「功能多数已实现，但被 Branches 视图渲染 bug + 工具栏未浮现 + 命令 bug 掩盖」。本批 Recovery **先解除可见痛感，再全量补齐**：新增 13 个 engine 纯逻辑模块 + 21 个命令，单测 64 → 166、命令 56 → 77。**§3 所列 vscode.git 稳定 API 限制（cherry-pick/revert/reset/branch rename/hunk 暂存/stash list/graph topology/shelf/author 等）现均已通过 `GitRepositoryService.execGit`（复用 `api.git.path` 同一 git 二进制）受控 CLI 通道解决**。详见 [CHANGELOG](../../CHANGELOG.md) [Unreleased]。 +> AI M5 暂不启动（5 个接缝保留 Null 实现，本轮专注功能完备性）。 --- ## 0. 概览 -- **架构**：路径 B —— 消费内置 `vscode.git` 稳定 `Repository` API + 自建 changelist registry + 独立视图容器自绘 IDEA 风格 UI，不接管原生 Source Control 视图。 +- **架构**：路径 B —— 消费内置 `vscode.git` 稳定 `Repository` API + 自建 changelist registry + 独立视图容器自绘 UI，不接管原生 Source Control 视图。 - **分层**：`engine/`（纯逻辑，零 vscode 依赖）/ `adapter/`（唯一接触 vscode API）/ `agent/`（AI 接缝）/ `shared/`（契约）/ `infra/`。 - **质量基线**：TypeScript strict + ESLint9 + Vitest（engine 单测）+ @vscode/test-electron（adapter 集成）+ esbuild + 三平台 CI（Linux xvfb）。 - **验证**：单测 45/45、集成 3/3（含真实 git 提交闭环 + amend）、`vsce package` 产 vsix。 @@ -27,7 +27,7 @@ | M0-M2 审查修复 | 0.3.1 | [#5](https://github.com/ThreeFish-AI/hyper-git/pull/5) | 11 类正确性修复（订阅泄漏/仓库选取/indexChanges/commit 语义/push 警告/linter 等）+ 16 项测试补齐 | 单测 45/45 + 集成 3/3 | | M3 Log/Branches/Blame | 0.4.0 | [#6](https://github.com/ThreeFish-AI/hyper-git/pull/6) | Log TreeView（过滤+copy hash+Show History）、Branches TreeView（create/checkout/delete/merge/rebase）、Blame | 命令注册集成 | | M4 Stash/Shelf | 0.5.0 | [#7](https://github.com/ThreeFish-AI/hyper-git/pull/7) | Stash 视图（log refnames 枚举）+ create/apply/pop/drop；Shelf MVP（stash 近似） | 命令注册集成 | -| **Parity Recovery Batch 5-7** | — | commit `00b5ba7`/`2105445`/`9699ee9` | Branches 渲染修复 + 工具栏 Action 组 + 冲突兜底；Branches 对齐 IDEA（Favorites/Tags/ahead-behind）；Rebase webview reword/edit/拖拽 1:1 复刻 | 单测 166/166 + 集成 3/3 | +| **Parity Recovery Batch 5-7** | — | commit `00b5ba7`/`2105445`/`9699ee9` | Branches 渲染修复 + 工具栏 Action 组 + 冲突兜底；Branches 视图增强（Favorites/Tags/ahead-behind）；Rebase webview 支持 reword/edit/拖拽交互式编排 | 单测 166/166 + 集成 3/3 | | **Parity Recovery Batch 8-9** | — | commit `efd888c`/`ed01883` | Log 提交详情面板 + 高级过滤 + per-commit 操作；真实 SVG 提交拓扑图（解析 git --graph 字符粒度渲染 + 可点击 + 实时刷新） | 同上 | | **Parity Recovery Batch 10-12** | — | commit `2274d8a`/`fcb6ffa`/`acdf53c` | Push/Update/Merge 对话框 + fetch prune + Co-authored-by trailer；自绘 3-way Merge Editor（自实现 diff3）；Stash 高级 + Patch + Reflog + Blame 行内注解 | 同上 | @@ -79,7 +79,7 @@ **5 个 AI 接缝**（agent/，依赖 engine 不依赖 adapter）： - `ILlmProvider`：模型来源抽象（vscodeLM / byok-Ollama / openaiCompatible）。**最关键**——未来切换模型来源的命脉。 - `ICommitMessageProvider`：AI 提交信息生成（staged diff + 团队规范 → 流式 CC 合规 message）。 -- `IPreCommitInspector`：提交前 AI 代码审查（对齐 IDEA `CheckinHandler.beforeCheckin`，可阻断）。 +- `IPreCommitInspector`：提交前 AI 代码审查（参考 JetBrains `CheckinHandler.beforeCheckin` 责任链设计，可阻断）。 - `IChangelistGrouper`：变更语义分组（回写 changelist）。 - `IConflictResolver`：冲突解决（用户逐块确认）。 @@ -104,6 +104,6 @@ ## 7. 发布状态 -- **当前版本**：0.5.0（preview，内部里程碑）。 -- **首发候选**：v0.0.1-rc.1（package 版本 `0.0.1` + `--pre-release` + git tag `v0.0.1-rc.1`）。Marketplace 仅支持 `major.minor.patch`，预发布语义由 `--pre-release` 标记 + tag 体现。 +- **当前版本**：0.0.6（首个 MVP 正式版，对外首发；以「Hyper Git - Agentic Git」之名上架 Marketplace / OpenVSX）。 +- **首发历程**：经若干内部迭代与 `v0.0.1-rc.*` 预发布打磨后，以 `v0.0.5` 完成内部首发；因 Marketplace 上「Hyper Git」名称被误删不可用，遂将扩展更名为 **Hyper Git - Agentic Git**（`package.json` `name=hyper-git-agentic-git`），以 `v0.0.6`（git tag `v0.0.6`）重新上架。Marketplace 仅支持 `major.minor.patch`，预发布语义由 `--pre-release` 标记 + tag 体现。 - **发布前置**：publisher 账号（`threefish-ai`）、VSCE_PAT / OVSX_PAT secrets、PNG 图标。 diff --git a/docs/releases/README.md b/docs/releases/README.md index 51dbd46..df9ac29 100644 --- a/docs/releases/README.md +++ b/docs/releases/README.md @@ -8,7 +8,7 @@ | 版本 | 说明 | 日期 | |---|---|---| -| [v0.0.1](./v0.0.1.md) | 首个 MVP 正式版 | 2026-06-30 | +| [v0.0.6](./v0.0.6.md) | 首个 MVP 正式版（以「Hyper Git - Agentic Git」之名上架） | 2026-06-30 | ## 相关文档 diff --git a/docs/releases/v0.0.1.md b/docs/releases/v0.0.6.md similarity index 54% rename from docs/releases/v0.0.1.md rename to docs/releases/v0.0.6.md index 59f7e13..801d835 100644 --- a/docs/releases/v0.0.1.md +++ b/docs/releases/v0.0.6.md @@ -1,18 +1,18 @@ -# Hyper Git v0.0.1 — 首个 MVP 正式版 +# Hyper Git - Agentic Git v0.0.6 — 首个 MVP 正式版 -> 在 VS Code 上完整复刻 IntelliJ IDEA 的 **Git 工具窗口** 与 **Commit 提交窗口**，并为未来 AI Agent 自主代理预留架构接缝。 +> 为 VS Code 带来统一的 **Git 变更管理** 与 **提交工作流**，并为未来 AI Agent 自主代理预留架构接缝。 -这是 Hyper Git 的首个对外正式版本。它把 IDEA 里那套被开发者高频依赖、迁移到 VS Code 后却长期缺失的 Git 工作流——多 Changelist 变更组织、忠实的提交窗口、可视化提交图、Shelf、行级提交——一次性补齐，并与原生 Source Control 平行共存、零冲突。 +这是本扩展的**首个对外正式版本**，在 VS Code Marketplace / OpenVSX 上以 **「Hyper Git - Agentic Git」** 之名发布。它把开发者高频依赖、却在 VS Code 原生 Source Control 中长期缺失的 Git 工作流**一次性补齐**：多 Changelist 变更组织、自绘提交面板、可视化提交图、Shelf、行级提交，并与原生 Source Control **平行共存、零冲突**。 --- ## ✨ 亮点速览 -- **多 Changelist 变更组织**：像 IDEA 一样把工作区改动分组到命名列表，设活动列表为提交目标，重启自动恢复。 -- **IDEA 风格 Commit 窗口**：自绘提交面板，Conventional Commits 实时校验，Amend / Sign-off / 跳过 Hook，提交或提交并推送。 -- **IDEA 风格提交图（自绘 DAG）**：彩色泳道、分叉·合并连线、HEAD/分支/标签徽标，虚拟滚动增量加载，告别 `git log --graph` 的粗糙 ASCII。 +- **多 Changelist 变更组织**：把工作区改动分组到命名列表，设活动列表为提交目标，重启自动恢复。 +- **自绘 Commit 提交面板**：勾选式提交面板，Conventional Commits 实时校验，Amend / Sign-off / 跳过 Hook，提交或提交并推送。 +- **可视化提交图（自绘 DAG）× CI 状态**：彩色泳道、分叉·合并连线、HEAD/分支/标签徽标；每条提交行右侧实时显示 **GitHub CI 最终状态**（绿勾/红叉/运行中），悬停查看各项检查、失败原因与跳转链接——告别 `git log --graph` 的粗糙 ASCII，也无需切到浏览器查构建结果。 - **Branches 多选批量操作**：框选多个分支/标签，一次性删除、复制引用、收藏；已合并/未合并诚实分栏确认。 -- **忠实 Shelf + 全量 Worktree**：基于 patch 的 Shelf（独立于 stash）与 Worktree 全生命周期管理（新建/打开/锁定/移动/删除）。 +- **独立 Shelf + 全量 Worktree**：基于 patch 的 Shelf（独立于 stash）与 Worktree 全生命周期管理（新建/打开/锁定/移动/删除）。 - **行级与 Hunk 提交**：编辑器内 CodeLens「提交此 Hunk」、部分暂存、光标处暂存、Hunk 归属 Changelist。 - **3-way Merge Editor**：自绘三栏冲突编辑器（OURS / RESULT / THEIRS），冲突时一键调起。 @@ -24,11 +24,20 @@ 按 Changelist 分组的 Changes 树（状态色复用 `gitDecoration.*` 主题色）；新建 / 重命名 / 删除 / 设活动 / 跨列表移动文件，`workspaceState` 持久化；单击打开原生 Diff（HEAD ↔ Working）；丢弃改动、加入 `.gitignore`、显示文件历史。 ### Commit 提交窗口 -多行消息编辑器 + Conventional Commits 实时校验（可配置开关）；Amend、Signed-off-by、跳过 Git Hooks；勾选集即提交权威范围（对齐 IDEA「提交该集合」）；最近消息一键复用；**提交** 与 **提交并推送** 双动作；提交流水线对齐 IDEA `CheckinHandler`（校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 +多行消息编辑器 + Conventional Commits 实时校验（可配置开关）；Amend、Signed-off-by、跳过 Git Hooks；勾选集即提交权威范围（仅提交选中的文件集合）；最近消息一键复用；**提交** 与 **提交并推送** 双动作；提交流水线采用责任链设计（参考 JetBrains `CheckinHandler`：校验 → 暂存 → Hook 链 → 提交 → 可选推送）。 ### Log 提交图与历史 自绘 **Graph DAG** webview（彩色泳道 / 节点 / 连线 / 引用徽标，拓扑保序，虚拟化滚动，↑↓ 键导航）；选中提交内联展开变更文件并打开单文件 Diff；**7 个可组合过滤器**——作者、路径、message（grep）、message（正则）、合并模式、日期、一键清除；per-commit 操作——复制 hash、Reset 到此、从此新建分支/标签、查看包含此提交的分支、Cherry-Pick、Revert。 +#### 提交图 × CI 状态（GitHub Actions / Commit Status） +每条提交行最右侧显示其 **CI 最终状态**：绿勾=通过、红叉=失败、运行中=黄色旋转。悬停图标以浮层 Tooltip 展示「各项检查 + 未通过原因 + 运行链接」，让你**在提交图里一眼看出哪次提交挂了 CI**，无需跳转浏览器。 +- 复用 **VS Code 内置 GitHub 认证**（`vscode.authentication`），凭证由编辑器托管，**绝不经过 chat / 日志 / webview**；范围 `repo`，静默优先、仅点击「登录 GitHub」时才触发原生授权。 +- **性能与限流**：仅取可见行懒加载（虚拟滚动 ~50 行）、批量 GraphQL（单次 ≤100 oid）+ 限流冷却；终态整会话缓存、pending 30s 刷新。 +- **零打扰降级**：非 GitHub 远程（GitLab 等）零图标零请求；未推送/无 CI 配置 → 不渲染图标；断网/限流不崩溃、建图正常。支持 github.com 与 GitHub Enterprise（按 origin 主机自动判定）。 + +#### Checkpointer 过滤 +Log 视图新增 **Checkpointer 选项**，**默认剔除** AI 编码工具产生的自动快照（checkpoint）提交，让提交图回归「人写的人类提交」，避免被海量自动提交淹没；可在过滤器面板按需开启查看。 + ### Branches 分支管理 四段分组（收藏 / 本地 / 远程 / 标签）+ ahead·behind·upstream 跟踪展示；新建 / 检出 / 删除 / 重命名 / 合并 / 变基 / 从选中新建并检出；收藏切换、与当前分支比较、任意两分支比较、复制引用、清理已合并分支；**多选批量**：批量删除分支/标签、批量复制引用、批量收藏（已合并/未合并风险诚实分栏确认）。 @@ -36,7 +45,7 @@ 新建（轻量/附注）、删除（支持多选）、检出（进入 detached HEAD）、从提交新建标签。 ### Stash 与 Shelf -**Stash**：创建、保留已暂存创建、应用、Pop、删除、从 Stash 创建分支、清空全部，按真实 `stash@{n}` 索引操作。**Shelf**（IDEA 忠实复刻，基于 patch、独立于 git stash）：Shelve 暂存、静默 Unshelve、带 3-way 合并 Unshelve、删除。 +**Stash**：创建、保留已暂存创建、应用、Pop、删除、从 Stash 创建分支、清空全部，按真实 `stash@{n}` 索引操作。**Shelf**（基于 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」。 @@ -51,9 +60,10 @@ Cherry-Pick、Revert、Reset HEAD（soft / mixed / hard / keep）、交互式 Re 导出 / 应用 Patch、查看 Reflog、3-way Diff 概览（HEAD ↔ Staged ↔ Working）、Console 命令输出面板。 ### 配置项 -`hyperGit.commit.template`（提交模板）、`hyperGit.commit.conventional`（CC 校验开关）、`hyperGit.ai.enabled`（AI 能力开关，M5 预留）。 +- `hyperGit.commit.template`（提交模板）、`hyperGit.commit.conventional`（CC 校验开关）、`hyperGit.ai.enabled`（AI 能力开关，M5 预留）。 +- `hyperGit.log.ci.enabled` / `hyperGit.log.ci.remote` / `hyperGit.log.ci.provider`（提交图 CI 状态：总开关 / 查询远程 / 提供者 auto·github.com·github-enterprise）。 -> 规模实证：**7 个视图 / ~92 个命令 / 3 个配置项**，覆盖 IDEA Git 工具窗口主线工作流。 +> 规模实证：**7 个视图 / 93 个命令 / 6 个配置项 / 280 个单元测试**，覆盖 Git 变更管理主线工作流。 --- @@ -63,18 +73,18 @@ Cherry-Pick、Revert、Reset HEAD（soft / mixed / hard / keep）、交互式 Re - **消费** 内置 `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 替换为真实实现，本版未启动。 +- **自绘视图** 承载完整的变更管理 UI；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。 +- **AI 接缝**：预埋 5 个接口（`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`，设计参考 JetBrains `CheckinHandler` 提交生命周期），M5 替换为真实实现，本版未启动。 -质量基线：**218 个单元测试**（engine 纯逻辑）+ 集成测试（`@vscode/test-electron` + fixture 仓库），CI 三平台（Ubuntu / macOS / Windows）矩阵校验，lint / 类型 / 构建全程 GREEN。 +质量基线：**280 个单元测试**（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`（发布上线后可用）。 +- **手动安装（当前推荐）**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `hyper-git-agentic-git-0.0.6.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 工作区。 @@ -83,7 +93,7 @@ Cherry-Pick、Revert、Reset HEAD（soft / mixed / hard / keep）、交互式 Re ## ⚠️ 已知限制 - Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ 撤销最近提交的**按钮 UI 接线**仍待补（engine `trailer` 已就绪，仅缺 webview 交互）。 -- Partial 多文件选择 UX、行级 split chunks（IDEA「Include Selected Lines」）。 +- Partial 多文件选择 UX、行级 split chunks（按选定行拆分提交）。 - 目录 / folder diff（虚拟文档）、Submodules 管理。 - M5 AI Agent：5 个接缝已预埋 Null 实现，本版未启动。 diff --git a/docs/requirements/idea-feature-matrix.md b/docs/requirements/idea-feature-matrix.md index 462b269..3d6fb94 100644 --- a/docs/requirements/idea-feature-matrix.md +++ b/docs/requirements/idea-feature-matrix.md @@ -1,6 +1,6 @@ # IntelliJ IDEA 社区版 Git/Commit 模块 调研报告 -> 调研目标：产出 IDEA「Git 工具窗口 + Commit 提交窗口」的【完整功能清单 + 关键源码锚点】，作为 VS Code 插件复刻的需求规约（Spec）基线。 +> 调研目标：产出 IDEA「Git 工具窗口 + Commit 提交窗口」的【完整功能清单 + 关键源码锚点】，作为本扩展 Git 变更管理与提交工作流的功能需求规约（Spec）基线（参考 IDEA 等成熟实现）。 > 仓库：[JetBrains/intellij-community](https://github.com/JetBrains/intellij-community)（master 分支，2025–2026 年版本） > 官方文档：[IntelliJ IDEA Help 2026.1](https://www.jetbrains.com/help/idea/) > 调研时间：2026-06-27 @@ -44,7 +44,7 @@ ### 组 1：Commit 窗口（Commit / Shelf / Stash 标签页 + 提交流水线） -| # | 功能名 | 用户可见行为 | 触发入口 | 底层 git/IDEA 机制 | 源码锚点（类路径） | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层 git/IDEA 机制 | 源码锚点（类路径） | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 1 | Commit 工具窗口（竖向，Alt+0） | 左侧竖向变更列表 + 提交信息区 + Diff 预览；非模态 | `Alt+0` / `Ctrl+K` | 平台 `CommitDialog/CommitToolWindow`，git4idea `GitCheckinEnvironment` | `vcs-impl/.../changes/ui/CommitChangeListDialog.java`、`DefaultCommitChangeListDialog.kt`；git4idea `checkin/GitCheckinEnvironment.kt` | 高 | 部分（SCM 面板，无竖向 commit 工具窗口形态） | | 2 | Commit Message 模板 | 默认填充 commit message（来自 `.git/COMMIT_TEMPLATE` / `commit.template` / merge message） | 打开 commit 窗口自动填充 | `git config commit.template`；EP `com.intellij.vcs.commitMessageProvider` | `commit/GitTemplateCommitMessageProvider.kt`；`vcs-api/.../changes/ui/CommitMessageProvider.java`；`checkin/GitCheckinEnvironment.getDefaultMessageFor`（merge message） | 低 | 无原生（需插件/git config） | @@ -63,7 +63,7 @@ ### 组 2：Local Changes 变更列表（多 changelist 模型） -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 15 | 多 changelist | 同时维护多个命名变更列表 | Commit 窗口左侧树 | `ChangeListManager` + `LocalChangeList` 模型 | `vcs-api/.../changes/ChangeListManager.java`、`LocalChangeList`（接口）；`vcs-impl/.../changes/ChangeListManagerImpl.java`、`ChangeListWorker.java` | 高 | **无**（VS Code SCM 仅多 group，非命名 changelist） | | 16 | Active changelist | 设置默认活动列表；新改动落入此列表 | `Ctrl+Space` / 右键 Set Active | `getDefaultChangeList/setDefaultChangeList`；命令 `SetDefault` | `ChangeListManager`；`changes/local/SetDefault.java` | 中 | **无**（无 active 概念） | @@ -75,7 +75,7 @@ ### 组 3：Partial / Selective / 按行（line-level）提交 -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 22 | 选择性勾选文件提交 | 勾选/取消文件，未勾选保留 | 复选框 | changelist 内子集提交 | `vcs-impl/.../changes/ui/CommitDialogChangesBrowser.java`；`GitCheckinEnvironment.commit(changes)` 接受子集 | 低 | 是（SCM 文件勾选） | | 23 | 按代码块（chunk）提交 | Diff 中勾选 chunk 提交，其余保留 | Diff 区勾选 | `PartialLocalLineStatusTracker` + `PartialCommitHelper` | `vcs-impl/.../impl/PartialChangesUtil.kt`（`getPartialTracker`/`processPartialChanges`）；`vcs-api/.../vcs/ex/PartialCommitHelper`；`GitCheckinEnvironment.addPartialChangesToIndex` | **高** | 部分（git staging + chunk staging，VS Code 1.70+ 支持 staging selected lines） | @@ -85,7 +85,7 @@ ### 组 4：Shelf 与 Stash -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 27 | Shelve changes（IDEA patch） | 暂存选定改动为 IDEA patch；可选择部分文件 | 右键 Shelve Changes / Shelve Silently（`Ctrl+Shift+H`） | `ShelveChangesManager`（patch 文件存储） | `vcs-impl/.../changes/shelf/ShelveChangesManager.java`、`ShelveChangesAction.kt`、`ShelveChangesCommitExecutor.java` | 中 | **无**（需 git stash 替代） | | 28 | Unshelve silently / with conflict | 还原 shelf；静默或弹冲突解决 | `Ctrl+Shift+U` / Unshelve Silently（`Ctrl+Alt+U`）/ 拖拽 | `ShelvedChangesViewManager` + 3-way merge（冲突） | `shelf/UnshelveWithDialogAction.java`、`ShelvedChangesViewManager.java`、`RestoreShelvedChange.java` | 中 | 无 | @@ -98,7 +98,7 @@ ### 组 5：Diff（对比） -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 35 | 与 HEAD/分支/本地对比 | Diff Viewer 对比本地 vs HEAD / 任意分支 / 本地版本 | Diff 按钮（`Ctrl+D`）/ Compare HEAD, Staged and Local | `DiffProvider`/`GitDiffProvider` | `git4idea/diff/`；`ui/GitShowDiffWithBranchPanel.kt`；`branch/GitCompareBranchesUi.kt` | 中 | 是（editor diff） | | 36 | Compare HEAD/Staged/Local 三方 | 三窗 Diff（repo / 中央可编辑 staging / local） | 右键 Compare HEAD, Staged and Local Versions | staging area interactive staging | 官方文档「Stage changes interactively」；`checkin/GitIndexUtil`（`listStaged`/`listTree`） | 中 | 部分 | @@ -107,7 +107,7 @@ ### 组 6：Log 提交图 -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 39 | 提交图（graph） | 分支拓扑图、彩色节点 | Git 工具窗口 Log tab（`Alt+9`） | `platform/vcs-log`（VcsLog data + UI） | `platform/vcs-log/`（`VcsLogUi`、graph 渲染）；git4idea `log/` | **高** | 无原生（需 GitGraph 等插件） | | 40 | Search / filter（author/path/date/branch/regex） | 按 author、path、date、branch、正则过滤 | Log toolbar 过滤 | VcsLog filter 体系 | `platform/vcs-log/`（filter providers）；官方文档 [Log Tab](https://www.jetbrains.com/help/idea/log-tab.html) | 中 | 部分（无原生图形 log 过滤） | @@ -118,7 +118,7 @@ ### 组 7：Branches -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 45 | Create / Checkout branch | 新建并检出 / 检出现有 / checkout-as-new | VCS widget / Branches pane | `git checkout -b/-` | `branch/GitCreateBranchOperation.kt`、`GitCheckoutOperation.java`、`GitCheckoutNewBranchOperation.java`；`actions/branch/GitCheckoutAsNewBranch.kt` | 低 | 是（命令面板） | | 46 | Delete / Rename branch | 删除本地/远程分支/标签、重命名 | 右键 Delete/Rename | `git branch -d/-D`/`-m`；`git push origin --delete` | `branch/GitDeleteBranchOperation.java`、`GitDeleteRemoteBranchOperation.java`、`GitRenameBranchOperation.java`、`GitDeleteTagOperation.java` | 低 | 部分 | @@ -129,7 +129,7 @@ ### 组 8：右键 / 内联操作 -| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | VS Code 原生 | +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 实现难度 | VS Code 原生 | |---|---|---|---|---|---|---|---| | 51 | Revert / Rollback | 回滚未提交改动（`RollbackEnvironment`） | 右键 Rollback / `RollbackChangesDialog` | `git checkout --` / reset | `rollback/GitRollbackEnvironment.java`；`vcs-impl/.../changes/ui/RollbackChangesDialog.kt`、`RollbackWorker.java` | 中 | 是（Discard Changes） | | 52 | Reset HEAD（mixed/soft/hard/keep） | Git Reset 对话框选择模式 | 右键 / `GitResetHead` action | `git reset --soft/--mixed/--hard/--keep` | `actions/GitResetHead.java`；`ui/GitResetDialog.java` | 低 | 无原生（命令式） | @@ -153,7 +153,7 @@ | 提交范围 | 提交所选 changelist（或其中勾选子集） | 提交整个 Staged group | | 自动绑定分支 | **无原生 changelist↔branch 自动绑定**；需 Tasks 上下文（`ActiveChangeListTracker`） | 无 | -> **复刻映射建议**：VS Code SCM 的 `ResourceGroup` 难以 1:1 表达「active + 跨文件行级归属」，建议在插件层自建「changelist registry」（仿 `ChangeListManager` + `ChangeListChange`），将 SCM group 作为渲染层，并通过 `LineStatusTracker`-like 行级 tracker 支撑 partial commit。这是 IDEA 模型对 VS Code 最大的差异与复刻难点。 +> **实现映射建议**：VS Code SCM 的 `ResourceGroup` 难以直接表达「active + 跨文件行级归属」，建议在插件层自建「changelist registry」（参考 `ChangeListManager` + `ChangeListChange` 设计），将 SCM group 作为渲染层，并通过 `LineStatusTracker`-like 行级 tracker 支撑 partial commit。这是 IDEA 模型与 VS Code 原生 SCM 模型最大的差异点与实现难点。 --- @@ -169,7 +169,7 @@ | Before-Commit 设置项（Settings 页） | `UnnamedConfigurable getBeforeCheckinSettings()` | `Settings \| VCS \| Commit` 配置页 | 持久化设置 | 中：AI 规则配置 | | After-Commit 配置面板 | `RefreshableOnComponent getAfterCheckinConfigurationPanel(Disposable)` | 构建 After Commit 选项面板 | 注入部署等选项 | 低 | | **Before check-in（核心闸门）** | `ReturnResult beforeCheckin(CommitExecutor, PairConsumer)` / `beforeCheckin()` | 提交按钮按下后、真正 commit 前 | `COMMIT`/`CANCEL`/`CLOSE_WINDOW` 可阻断提交 | **高**：AI 代码审查/质量闸门，可阻断不良提交 | -| **CommitCheck（现代协程闸门）** | `suspend CommitProblem? runCheck(CommitInfo)` / `runGitCheck(commitInfo, changes)` | beforeCheckin 的协程演进版；`commitInfo.isVcsCommit` 时执行 | 返回 `CommitProblem`（含 `showModalSolution`） | **高**：AI 异步审查最佳挂载点（仿 `GitCheckinHandler`） | +| **CommitCheck（现代协程闸门）** | `suspend CommitProblem? runCheck(CommitInfo)` / `runGitCheck(commitInfo, changes)` | beforeCheckin 的协程演进版；`commitInfo.isVcsCommit` 时执行 | 返回 `CommitProblem`（含 `showModalSolution`） | **高**：AI 异步审查最佳挂载点（参考 JetBrains `GitCheckinHandler` 设计） | | CommitCheck 执行顺序 | `CommitCheck.ExecutionOrder getExecutionOrder()` | 排序多个 CommitCheck | `EARLY`/`DEFAULT`/`LATE` | 中：控制 AI 检查与其他检查顺序 | | CommitCheck 启用开关 | `boolean isEnabled()` | 决定是否运行 | 布尔 | 中 | | **Successful 回调** | `void checkinSuccessful()`（`@RequiresEdt`） | 提交成功后 | 通知/后续动作 | 高：AI 提交摘要、自动生成 PR 描述 | @@ -180,7 +180,7 @@ > **CommitContext 关键字段**（贯穿整个流水线，承载 commit 选项）：`commitToAmend`、`isSkipHooks`、`commitAuthor`、`commitAuthorDate`、`isSignOffCommit`、`isPushAfterCommit`、`isCommitRenamesSeparately`、`commitWithoutChangesRoots`。源码：`GitCheckinEnvironment.updateState()` / `doCommit()`。 > -> **AI 接入建议**：实现一个 `CommitCheck`（EARLY 顺序）挂载 AI 审查 + 实现 `includedChangesChanged()` 动态生成 commit message + 实现 `checkinSuccessful()` 触发 AI 后处理，可完整复用 IDEA 提交流水线的「设计-实现-验证」闭环，无需重写 commit 引擎。 +> **AI 接入建议**：实现一个 `CommitCheck`（EARLY 顺序）挂载 AI 审查 + 实现 `includedChangesChanged()` 动态生成 commit message + 实现 `checkinSuccessful()` 触发 AI 后处理，可借鉴 JetBrains CheckinHandler 责任链的「设计-实现-验证」闭环，无需重写 commit 引擎。 --- @@ -209,7 +209,7 @@ --- ## F. 待核实 / 不确定项 -1. **LocalChangeList 接口/实现类的精确文件路径**：zread 多次返回「文件不存在」（API 类可能位于非直觉路径或为生成/移动类），但其方法语义已通过 `ChangeListManager.java`（大量引用）+ `PartialChangesUtil.kt`（`LocalChangeList` import）+ `ChangeListWorker.java`（实现侧）交叉证实存在。**建议**复刻阶段直接以 `ChangeListManager` API 为契约蓝本。 -2. **Conventional Commits 内置校验**：WebSearch 与文档检索均未发现 IDEA 内置 CC 强校验类；结论为「IDEA 无原生 CC 校验，依赖 commit message 规则/第三方插件」，需在复刻时自行实现 CC linter。 +1. **LocalChangeList 接口/实现类的精确文件路径**：zread 多次返回「文件不存在」（API 类可能位于非直觉路径或为生成/移动类），但其方法语义已通过 `ChangeListManager.java`（大量引用）+ `PartialChangesUtil.kt`（`LocalChangeList` import）+ `ChangeListWorker.java`（实现侧）交叉证实存在。**建议**实现阶段直接以 `ChangeListManager` API 为契约蓝本。 +2. **Conventional Commits 内置校验**：WebSearch 与文档检索均未发现 IDEA 内置 CC 强校验类；结论为「IDEA 无原生 CC 校验，依赖 commit message 规则/第三方插件」，需在实现时自行构建 CC linter。 3. **Changelist 自动绑定分支的具体类**：`ActiveChangeListTracker.kt` 存在，但「changelist↔branch」自动绑定疑似走 Tasks 上下文模块（非 git4idea），未定位到确切绑定类。 4. **分支级 Pull/Push/Fetch 的精确 action 类**：`actions/branch/GitPullBranchAction.kt` 等结构已确认存在，但内部委托链（→ `GitBranchWorker`/`GitFetch`）未逐行核实。 diff --git a/docs/research/02-vscode-scm-integration.md b/docs/research/02-vscode-scm-integration.md index cf738cd..851ce34 100644 --- a/docs/research/02-vscode-scm-integration.md +++ b/docs/research/02-vscode-scm-integration.md @@ -1,6 +1,6 @@ # Track2 调研报告:VS Code SCM API 与 vscode.git 导出 API 集成路径 -> 调研对象:在 VS Code 中复刻 IDEA 风格 Git 工具窗口(多 changelist + Commit 窗口)的最佳集成路径。 +> 调研对象:在 VS Code 中实现统一 Git 变更管理面板(多分组列表 + 自绘 Commit 提交面板)的最佳集成路径。 > 证据基线:microsoft/vscode 源码(`extensions/git/src/api/git.d.ts`、`api1.ts`、`vscode.d.ts`)、官方 SCM provider 指南、GitHub Issue 追踪记录、同类扩展(GitLens、vscode-pull-request-github)实践。 > 检索时间:2026 年 6 月。所有关键事实附 GitHub 文件路径或官方文档 URL;存疑项标注「待核实」。 @@ -10,7 +10,7 @@ | 决策项 | 结论 | |---|---| -| **推荐路径** | **路径 B(纯消费 vscode.git 导出 API + 自建 TreeView/WebviewView 渲染 IDEA UI),原生 Source Control 视图保持不动** | +| **推荐路径** | **路径 B(纯消费 vscode.git 导出 API + 自建 TreeView/WebviewView 渲染自绘 UI),原生 Source Control 视图保持不动** | | **changelist 模型** | VS Code SCM 是「分组(group)」模型,不是 IDEA 的「多 changelist」。多 changelist 用**自建 TreeView** 表达最忠实;若想借用原生视图,可用「每个 changelist 一个 `SourceControlResourceGroup`」近似但语义有损 | | **Commit 窗口 UI** | 放在 **Secondary Side Bar 的 WebviewView**(自建视图容器),自带 Commit/Shelf/Stash 标签页 + Commit Message 编辑器;**不依赖也不替代**原生 `SourceControlInputBox`(稳定字段太弱,且 `SourceControlInputBoxValueProvider` 已被官方删除) | | **提交图(Log)** | 原生 Source Control Graph 的 `scmHistoryProvider` **仍是 proposed API**(截至 2025-05 无 stable 时间表),不能稳定复用。Log 提交图须自建 TreeView + 消费 `Repository.log()` | @@ -86,7 +86,7 @@ createResourceGroup(id, label) → { id, label, resourceStates, hideWhenEmpty, . | `iconPath?: string \| Uri \| {light, dark}` | 自定义图标 | | `source?: string` | 来源标注 | -> IDEA 的 M/A/D/U/Renamed/Copied 完全可由 `letter` + `color` 组合复刻(git 扩展就是这么做的,见其 `Resource` 类的 decorations 计算)。 +> M/A/D/U/Renamed/Copied 等文件状态色完全可由 `letter` + `color` 组合实现(git 扩展就是这么做的,见其 `Resource` 类的 decorations 计算)。 ### 1.5 QuickDiff(编辑器 gutter 内联 diff) @@ -105,7 +105,7 @@ quickDiffProvider?: QuickDiffProvider // provideOriginalResource(uri) → 原 ### 1.7 SCM 菜单贡献点(自定义二级菜单/inline 按钮) -来源:[官方指南](https://code.visualstudio.com/api/extension-guides/scm-provider#source-control-view)。**全部稳定**,且能力足够复刻 IDEA 文件右键菜单: +来源:[官方指南](https://code.visualstudio.com/api/extension-guides/scm-provider#source-control-view)。**全部稳定**,且能力足够支撑文件右键菜单: | 菜单 id | 作用位置 | 可放 `inline`(行内按钮) | |---|---|---| @@ -125,11 +125,11 @@ quickDiffProvider?: QuickDiffProvider // provideOriginalResource(uri) → 原 `SourceControlHistoryItem` / `SourceControlHistoryItemChange` / `scmHistoryProvider` **至今仍是 proposed API**。VS Code 团队成员 lszomoru 2025-05-13 在 issue [#185269](https://github.com/microsoft/vscode/issues/185269) 明确:「计划 finalize 但无时间表」。定义文件:[vscode.proposed.scmHistoryProvider.d.ts](https://github.com/microsoft/vscode/blob/main/src/vscode-dts/vscode.proposed.scmHistoryProvider.d.ts)。 -> 第三方扩展在 Marketplace 发布时使用 proposed API 受限(需特批)。因此 **IDEA 的 Log 提交图不能依赖原生 Source Control Graph,必须自建 TreeView**。 +> 第三方扩展在 Marketplace 发布时使用 proposed API 受限(需特批)。因此 **Log 可视化提交图不能依赖原生 Source Control Graph,必须自建 TreeView**。 ### 1.9 Multi-Diff 编辑器 — proposed -`scmMultiDiffSource`(多文件并排 diff 审查)是 proposed,跟踪 issue [#179000](https://github.com/microsoft/vscode/issues/179000),`vscode.changes` 命令标注「experimental, subject to change」。IDEA 风格的「提交前多文件 diff 预览」短期须自建 Webview 或逐文件 diff。 +`scmMultiDiffSource`(多文件并排 diff 审查)是 proposed,跟踪 issue [#179000](https://github.com/microsoft/vscode/issues/179000),`vscode.changes` 命令标注「experimental, subject to change」。「提交前多文件 diff 预览」短期须自建 Webview 或逐文件 diff。 --- @@ -272,7 +272,7 @@ git 本身**没有 changelist** 概念,只有 stage(index)。IDEA 的 changelist - **物理层**:所有变更仍来自 `Repository.state.workingTreeChanges`(单一事实源)。 - **逻辑层**:Adapter 维护一个**本地 changelist 分配表**(`Map`),持久化到 workspace state(`context.workspaceState`)或 `.idea` 风格本地文件。 -- **提交语义**:「Commit 某 changelist」= `add(该 changelist 的 paths)` + `commit(msg)` + (可选)保留其余未 stage。这正向复刻 IDEA「selective commit」。 +- **提交语义**:「Commit 某 changelist」= `add(该 changelist 的 paths)` + `commit(msg)` + (可选)保留其余未 stage。这即对应「selective commit(选择性提交)」语义。 - **Default changelist**:即 active changelist,未显式分配的变更自动落入。 > 注意:此设计下,changelist 是**纯客户端逻辑分组**,不写 git 元数据(IDEA 的 changelist 也仅存于 `.idea/workspace.xml`,同理)。这与 git 的 stage 是两套正交机制,需在 UI 上明确区分(可提供「stage = 临时索引」「changelist = 持久分组」的认知锚点)。 @@ -309,17 +309,17 @@ git 本身**没有 changelist** 概念,只有 stage(index)。IDEA 的 changelist > GitLens 正是此模式:在 Source Control 活动栏挂自定义视图(来源:[gitkraken/vscode-gitlens issue #213](https://github.com/gitkraken/vscode-gitlens/issues/213) 讨论其视图置于 SCM 面板)。 -### 5.2 IDEA 顶部 Commit/Shelf/Stash 标签页 → VS Code 表达 +### 5.2 顶部 Commit/Shelf/Stash 标签页 → VS Code 表达 两种实现,择一: - **方案 1(推荐):平铺视图节点**。上图 `sofia-git` 容器下并列 Changes/Commit/Log/Shelf/Stash 五个 view,用户点击切换(等价标签页)。 -- **方案 2:单 WebviewView 内自绘 Tabs**。一个 `sofia.main` webview 内用前端框架渲染 IDEA 风格 Tab 栏 + 各面板内容。自由度最高但失去原生 a11y/快捷键集成。 +- **方案 2:单 WebviewView 内自绘 Tabs**。一个 `sofia.main` webview 内用前端框架渲染自绘 Tab 栏 + 各面板内容。自由度最高但失去原生 a11y/快捷键集成。 ### 5.3 Commit Message 编辑器(替代原生 inputBox) - 用 `WebviewView` 渲染一个**多行 Monaco-like 编辑器**(可用 `