diff --git a/.agents/issue.md b/.agents/issue.md index fd601c3..fb02135 100644 --- a/.agents/issue.md +++ b/.agents/issue.md @@ -21,3 +21,20 @@ - **处理方式**：删除 package.json 的 `pnpm` 字段；在 `pnpm-workspace.yaml` 写入 `allowBuilds: { esbuild: true, '@vscode/vsce-sign': true, keytar: true }` 后重新 `pnpm install`，三个 postinstall 正常执行。 - **后续防范**：pnpm 项目一律在 `pnpm-workspace.yaml` 管理构建脚本审批；新增含原生二进制的依赖时，需在此文件追加放行；CI 首次 `pnpm install` 后确认无 `ERR_PNPM_IGNORED_BUILDS`。 - **同类问题影响**：所有 pnpm 11 工程；凡依赖 esbuild / keytar / @vscode/vsce-sign / prebuild-install 类原生模块的扩展。 + +## #3 pnpm 11.9 要求 Node ≥ 22.13（CI 用 Node 20 崩溃） + +- **表因**：CI `Lint & Build` job 10s 内失败，日志 `Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:sqlite`，并告警 `This version of pnpm requires at least Node.js v22.13`。本地不暴露（本地用 Node 24）。 +- **根因**：pnpm 11.9 内部使用 Node 22.13+ 才有的 `node:sqlite` 内置模块；CI 工作流配置 `node-version: 20`，pnpm 启动即崩。 +- **处理方式**：CI 所有 job 的 `setup-node` 由 `node-version: 20` 升至 `node-version: 22`。 +- **后续防范**：pnpm ≥ 11 工程的 Node 基线须 ≥ 22.13；`engines.node`/CI/本地三者对齐（建议 22 LTS 或 24）；升级 pnpm 前查其 Node 版本要求（https://r.pnpm.io/comp）。 +- **同类问题影响**：所有 pnpm 11+ 的 CI/本地环境；node:sqlite 依赖的其他工具链。 + +## #4 CI 集成测试 job 缺失扩展构建步骤 + +- **表因**：CI `Test` job 集成测试报 `Activating extension 'threefish-ai.hyper-git' failed: Cannot find module '.../dist/extension.js'`；本地却通过。 +- **根因**：`test` job 仅跑 `test:unit` + `test:integration`，未执行 `node esbuild.js` 构建 `dist/extension.js`；test-electron 启动真实 VS Code 加载扩展（`main: ./dist/extension.js`）时找不到入口。本地因先前 `pnpm run package` 残留 dist/ 而误判通过。 +- **处理方式**：`test` job 在 `pnpm install` 后、测试前增加 `node esbuild.js`（或 `pnpm run compile`）构建 dist/。 +- **后续防范**：凡含 `@vscode/test-electron` 集成测试的 CI job，必须在测试前显式构建扩展产物；本地验证集成测试后清理 dist/ 以暴露该依赖；`.gitignore` 排除 dist/ 时注意 CI 需重建。 +- **同类问题影响**：所有 VS Code 扩展的 test-electron CI job；本地"能跑"但 CI 失败的构建产物缺失类问题。 + diff --git a/.agents/knowledge-map.md b/.agents/knowledge-map.md index ac318e3..6ada661 100644 --- a/.agents/knowledge-map.md +++ b/.agents/knowledge-map.md @@ -14,6 +14,12 @@ - [引用规范 IEEE](./reference-specifications.md) — 文献引用格式与上标锚定。 - [浏览器验证协议](./browser-validation.md) — OAuth/SSO 红线与 E2E 验证协议。 +## 项目文档（docs/） +- [文档中心](../docs/README.md) — 文档与调研资产总索引。 +- [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。 +- [IDEA 功能复刻矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**）。 +- [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。 + ## 架构分层（src/） > 依赖方向单向：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..30ccde1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Hyper Git 文档中心 + +> 项目文档与调研资产索引。所有决策均循证（附 GitHub 源码路径 / 官方文档 URL）。 + +## 工程方案与需求基线（高频引用） +- [工程实施方案](./architecture/engineering-plan.md) — 全链路调研结论 + 路径 B 架构 + M0-M5 里程碑路线图 + 风险与验证（**开发蓝图**）。 +- [IDEA 功能复刻矩阵](./requirements/idea-feature-matrix.md) — 56 个原子功能点 / 8 组 + CheckinHandler 生命周期（**验收基线**）。 + +## 调研报告（循证依据） +- [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 对齐 + 渐进式引入路线。 + +## 协作与规范 +- [AGENTS.md](../AGENTS.md) — 协作协议与工程行为准则。 +- [知识索引](../.agents/knowledge-map.md) · [Issue 记录](../.agents/issue.md) · [引用规范 IEEE](../.agents/reference-specifications.md)。 diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md new file mode 100644 index 0000000..61c8683 --- /dev/null +++ b/docs/architecture/engineering-plan.md @@ -0,0 +1,292 @@ +# Hyper Git — VS Code 扩展工程实施方案 + +> 复刻 IntelliJ IDEA 社区版「Git 工具窗口 + Commit 提交窗口」全功能，并为未来 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（提交信息生成 / 提交前代码审查 / 变更语义分组 / 冲突解决）。 + +**当前状态**：仓库为全新 greenfield 工程（仅有 `.agents/` 文档脚手架与 AGENTS.md 协议，无源码 / 无 package.json / 无 README）。本方案从零搭建。 + +**循证基线**（已读源码 / 官方文档交叉验证）： +- IDEA 侧：56 个原子功能点 / 8 组 + `CheckinHandler` 11 个 hook 生命周期（`git4idea` + `vcs-api/vcs-impl` 源码）。 +- VS Code 侧：`vscode.git` 导出的稳定 `Repository` API（`extensions/git/src/api/git.d.ts` 已逐行复核）；`scmHistoryProvider`/`scmMultiDiffSource` 仍是 proposed API（上架禁用）；`SourceControlInputBoxValueProvider` 已删除。 +- IDEA 多 changelist 模型（active 概念 + 跨列表行级归属 `PartialLocalLineStatusTracker`）**无法**用原生 SCM group 1:1 表达 → 必须自建 changelist registry。 + +--- + +## 1. 核心架构决策（路径 B） + +| 决策项 | 结论 | 循证依据 | +|---|---|---| +| **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 无法表达 | +| **视图容器** | 活动栏新建独立视图容器 `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` 语义 | + +**架构总览（Mermaid，深色模式高对比）**： + +```mermaid +flowchart TB + subgraph UI["UI 层 (自绘, adapter/ui)"] + direction LR + V1["Changes
TreeView"] + V2["Commit
WebviewView"] + V3["Log
Webview graph"] + V4["Branches/Shelf/Stash
TreeView"] + end + subgraph Adapter["Adapter 层 (唯一接触 vscode API)"] + GA["GitRepositoryAdapter
封装 vscode.git Repository"] + CR["ChangelistRegistry
(active/分组/持久化)"] + WV["WebviewHost
postMessage 协议"] + DI["DiffContentProvider
自定义 scheme"] + end + subgraph Engine["Engine 层 (纯逻辑, 零 vscode 依赖, 可单测)"] + M["领域模型
FileChange/Changelist/Commit/Branch/Stash"] + DF["Diff/行级 patch
(partial commit 基础)"] + CK["CommitPipeline
(Checkin hook 责任链)"] + SM["Status 色映射
M/A/D/U/R/C"] + end + subgraph Agent["Agent 层 (AI 接缝, 预留)"] + LLM["ILlmProvider"] + AI1["ICommitMessageProvider"] + AI2["IPreCommitInspector"] + AI3["IChangelistGrouper"] + AI4["IConflictResolver"] + end + VSCodeGIT[("vscode.git
内置 Repository API")] + NATIVE[("原生 Source Control 视图
不动, 共存")] + + UI --> Adapter + Adapter --> Engine + Agent -. 读领域模型 / 注入 hook .-> Engine + Agent -. 读 .-> Adapter + Adapter --> VSCodeGIT + NATIVE -. 平行存在 .-> VSCodeGIT + + classDef ui fill:#1f6feb,stroke:#4dabf7,stroke-width:2px,color:#fff + classDef ad fill:#7c3aed,stroke:#c4b5fd,stroke-width:2px,color:#fff + classDef eg fill:#0f766e,stroke:#5eead4,stroke-width:2px,color:#fff + classDef ag fill:#b45309,stroke:#fcd34d,stroke-width:2px,color:#fff + classDef ext fill:#444654,stroke:#8b8fa3,stroke-width:2px,color:#fff + class V1,V2,V3,V4 ui + class GA,CR,WV,DI ad + class M,DF,CK,SM eg + class LLM,AI1,AI2,AI3,AI4 ag + class VSCodeGIT,NATIVE ext +``` + +**依赖方向（单向，正交）**：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI；`Engine` 零依赖 `vscode`（可被 Vitest 与未来 CLI 双复用，是项目核心 IP）。 + +--- + +## 2. 模块正交分解（工程骨架） + +``` +hyper-git/ +├── package.json # Manifest + contributes（viewsContainers/views/commands/menus/configuration/keybindings） +├── esbuild.js # 沿用官方 esbuild-sample（CJS, external:['vscode']） +├── tsconfig.json # strict; @types/vscode 与 engines.vscode 最低版本对齐 +├── eslint.config.mjs # flat config + typescript-eslint +├── .prettierrc +├── .npmrc # node-linker=hoisted（规避 vsce/pnpm hoisting） +├── .vscodeignore # 排除 src/tests/*.config +├── .github/workflows/ci.yml # lint→build→test 矩阵→package→publish +├── media/ # 图标 SVG + webview 前端产物（commit-view/log-graph） +└── src/ + ├── extension.ts # 唯一入口：activate/deactivate，仅装配（DI 注册） + ├── engine/ # 【引擎层】纯领域逻辑，零 vscode 依赖 + │ ├── model/ # FileChange / Changelist / Commit / Branch / StashEntry / ConflictHunk + │ ├── diff/ # diff 解析 + 行级 patch（partial commit 基础） + │ ├── commit/ # CommitPipeline（Checkin hook 责任链，仿 IDEA 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…） + │ ├── changelist-registry.ts # ChangelistRegistry：active 列表/分组/移动/持久化(workspaceState) + │ ├── tree/ # TreeDataProvider：Changes / Branches / Shelf / Stash + │ ├── webview/ # WebviewView 宿主：Commit 窗口 + Log 图（postMessage 协议） + │ ├── diff/ # TextDocumentContentProvider：自定义 scheme 提供任意 ref 版本 + │ ├── commands/ # command 注册分发 + menu when-clause 上下文键 + │ └── storage/ # globalState/workspaceState/SecretStorage 封装 + ├── agent/ # 【代理层】AI 接缝（预留，Null 实现） + │ ├── llm-provider.ts # ILlmProvider（模型来源抽象：vscodeLM/byok/openaiCompatible） + │ ├── commit-message.ts # ICommitMessageProvider（生成 + Conventional Commits 校验） + │ ├── pre-commit.ts # IPreCommitInspector（对齐 IDEA beforeCheckin/CommitCheck） + │ ├── grouper.ts # IChangelistGrouper（语义分组） + │ ├── conflict.ts # IConflictResolver（三方合并建议） + │ └── chat-tools.ts # IChatToolRegistrar（M5 暴露 git 能力给 Agent） + ├── ui/ # 【UI 层】webview 前端（独立 esbuild iife bundle → media/） + │ ├── commit-view/ # Commit 窗口前端（多行编辑器 + 模板/校验/Amend/Author） + │ ├── log-graph/ # Log 图渲染（SVG graph + 过滤） + │ └── shared/ # 共享组件 + ├── shared/ + │ └── protocol.ts # 【单一事实源】webview↔host 消息类型契约（前后端共引） + └── infra/ # 日志（OutputChannel）/ 错误处理 / 事件总线 / 配置读取 +└── tests/ + ├── unit/ # Vitest：engine/* 与 diff/scm-mapping 纯逻辑（无 vscode 依赖） + ├── integration/ # @vscode/test-electron + Mocha：adapter/* 适配层 + └── fixtures/ # 最小化 git 仓库 fixture +``` + +**职责边界**：`engine/` 零依赖 `vscode`（Vitest 可测、未来 CLI 可复用）；`adapter/` 是唯一接触 `vscode` API 的层；`agent/` 依赖 `engine/` 但不依赖 `adapter/`；`shared/protocol.ts` 是 webview↔host 消息类型唯一来源，杜绝 Split-Brain。 + +--- + +## 3. 关键复用点（Reuse-Driven，拒绝重复造轮子） + +| 复用对象 | 用途 | 来源 | +|---|---|---| +| `vscode.git` → `Repository` | 所有 git 操作（commit/add/revert/clean/restore/diff*/blame/log/createBranch/merge/rebase/createStash/applyStash/popStash/dropStash/fetch/pull/push/checkout） | `extensions/git/src/api/git.d.ts`（已逐行复核） | +| `Repository.state.{indexChanges,workingTreeChanges,untrackedChanges,mergeChanges}` + `Status` 枚举 | 变更数据单一事实源 | 同上 | +| `api.toGitUri(uri, ref)` | 构造任意 ref 版本的资源 Uri（diff 原始端） | 同上 | +| `vscode.commands.executeCommand('vscode.diff', left, right, title)` | 文件 diff 预览（零成本，不自绘 diff） | VS Code 稳定 API | +| `ThemeColor('gitDecoration.modifiedResourceForeground')` 等 | 文件状态色（深色模式一致） | 复用原生 token | +| `@vscode/vsce` / `ovsx` | 打包 / 发布 | 官方工具 | +| `@vscode/test-electron` | 集成测试 | 官方唯一推荐 | +| `esbuild-sample` 模板 | 工程骨架零点（`esbuild.js` + scripts） | microsoft/vscode-extension-samples | +| `HaaLeo/publish-vs-code-extension` Action | 一键双市场发布 | GitHub Marketplace | + +**消费 `vscode.git` API 的声明**：`package.json` 加 `"extensionDependencies": ["vscode.git"]`；TS 类型复制 `git.d.ts` 入仓；运行时 `getExtension('vscode.git').activate().getAPI(1)`。 + +--- + +## 4. IDEA 功能复刻优先级矩阵 + +> 基于 Track1 的 56 功能点，按价值×依赖×难度分入 P0(MVP)/P1(核心对齐)/P2(高级对齐)/P3(AI 增强)。完整 56 项明细见 [IDEA 功能复刻矩阵](../requirements/idea-feature-matrix.md)（后续验收的需求基线）。 + +| 优先级 | 功能域 | 代表功能（来源 Track1 编号） | +|---|---|---| +| **P0 MVP** | Commit 窗口核心 | 统一窗口容器(#1)、Commit Message 多行编辑(#2 模板/#3 历史)、Commit / Commit and Push(#7)、Amend(#5)、Author/sign-off/skip-hooks(#6/#8/#9)、选择性勾选文件提交(#22)、本地 vs HEAD diff(#35)、Rollback/Discard(#51)、文件状态色 | +| **P0 MVP** | Local Changes | 多 changelist(#15)、active changelist(#16)、新建/删除/重命名(#17-19)、Move changes(#20) | +| **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 高级** | 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 近似 | +| **P3 AI 增强** | （M5，接缝现已埋） | AI 提交信息生成、AI 提交前审查、AI 语义分组、AI 冲突解决、AI release notes、Chat Tools 暴露 git 能力 | + +--- + +## 5. 里程碑路线图 + +> 每个 M：交付物 / 验收标准 / 依赖。版本号遵循 Marketplace 偶数 minor=release、奇数 minor=pre-release 约定（如 `0.2.x` release / `0.3.x` pre-release）。 + +**M0 — 脚手架 + CI（0.1.0 pre-release）** +- 交付：pnpm 工程、esbuild、tsconfig、ESLint9、Vitest、`@vscode/test-electron`、`.github/workflows/ci.yml`（lint→build→test 矩阵 ubuntu/mac/win + xvfb→package vsix→artifact）、`.vscodeignore`、README 骨架、`shared/protocol.ts`。 +- 验收：`pnpm test`（单测+集成）< 3min 全绿；CI 三平台通过；`vsce package` 产 vsix。 +- 依赖：无。 + +**M1 — Git Adapter + Changes TreeView（0.2.0）** +- 交付：`GitRepositoryAdapter`（封装 `vscode.git` API）、`ChangelistRegistry`（active/分组/移动/`workspaceState` 持久化）、Changes TreeView（changelist 一级节点 + 文件叶子 + 状态色 `gitDecoration.*`）、文件单击触发 `vscode.diff` + `toGitUri('HEAD')`。 +- 验收：能读取真实仓库 `workingTreeChanges` 并渲染 changelist 树；新建/移动/删除 changelist 持久化重启仍在；单击文件弹出原生 diff。 +- 依赖：M0。 + +**M2 — Commit 提交窗口（0.3.x pre-release）** +- 交付：Commit WebviewView（多行编辑器 + 模板注入 + 历史选填 + Conventional Commits 实时校验 linter + Amend + Author + sign-off + skip-hooks 开关）、底部 Commit / Commit and Push 按钮、`CommitPipeline`（Checkin hook 责任链骨架，Null hooks）、AI 接缝 5 个接口 + Null 实现（`ILlmProvider`/`ICommitMessageProvider`/`IPreCommitInspector`/`IChangelistGrouper`/`IConflictResolver`）、`includedChangesChanged` 等价事件。 +- 验收：勾选文件→填 message→Commit 落库（调 `Repository.commit`）；Commit and Push 成功；Amend 修正上一提交；CC 不合规时有提示；hook 链可注入并阻断（用内置非 AI 检查如 TODO 验证）。 +- 依赖：M1。 + +**M3 — Log 图 + Branches + Diff/Blame（0.4.0）** +- 交付：Log Webview（SVG graph + 按作者/路径/日期过滤，消费 `Repository.log`）、cherry-pick/revert from log、Branches TreeView（create/checkout/delete/rename/compare/merge/rebase）、Annotate(blame)、Show History、Reset 对话框（soft/mixed/hard/keep）。 +- 验收：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 模式开关。 +- 验收：shelve/unshelve with conflict 可解；单文件部分行可单独提交。 +- 依赖：M2、M3。 + +**M5 — AI Agent（实现接缝，0.7.x pre-release）** +- 交付：`ILlmProvider` 三实现（vscodeLM / byok-Ollama / openaiCompatible，配置驱动）、AI 提交信息生成（流式 + CC 校验）、AI 提交前代码审查（挂 `IPreCommitInspector`，可阻断）、AI 语义分组、AI 冲突解决（用户逐块确认）、`@hyper-git` Chat Participant + `languageModelTools`（`hyper_get_staged_diff`/`hyper_git_blame` 等暴露给任意 Agent）。 +- 验收：opt-in 开关启用后 ✨ 按钮出现；AI 审查能阻断不良提交；Chat 工具可被 Copilot Agent 调用。 +- 依赖：M2-M4。注：M5 起需 `engines.vscode` 评估上调（LM/Chat API 稳定版本要求）。 + +--- + +## 6. AI 集成架构预留点（现建接缝，M5 实现） + +> 对齐 IDEA `CheckinHandler` 生命周期（Track1 D 节：`beforeCheckin`/`CommitCheck.runCheck`/`includedChangesChanged`/`checkinSuccessful`/`checkinFailed`）。**只定义契约 + Null 实现，不引入 Copilot 依赖**（未启用 AI 用户零负担）。 + +| 接缝（Agent 层） | 对齐 IDEA | 为何现在抽 | +|---|---|---| +| `ILlmProvider`（模型来源抽象） | — | **最关键**：未来切换 vscodeLM/byok/自带 key 的命脉；晚抽则所有 AI 调用散落、迁移成本爆炸 | +| `ICommitMessageProvider` | （IDEA 无内置，插件有） | 提交信息是 commit 流水线核心产物，留接缝让"无 AI→LM→自带 key"平滑切换 | +| `IPreCommitInspector` | `beforeCheckin`/`CommitCheck.runCheck`（返回 COMMIT/CANCEL/DEFER，对齐 `ReturnResult`） | 复用 IDEA 20+ 年验证的 hook 闸门机制；AI 审查最佳挂载点 | +| `IChangelistGrouper` | （IDEA 无内置） | 写回 changelist 模型（回写工作流，差异化于内置 Copilot） | +| `IConflictResolver` | （IDEA 无内置） | 必须 `prepareInvocation` 用户确认（VS Code 工具确认机制，安全红线） | + +**Commit 流水线 hook 注入点**（M2 即建责任链，默认 Null hooks）： +`staged diff → [Hook A: 提交信息生成] → message 定稿 → [Hook B: 提交前检查链=beforeCheckin] → [Hook C: 分组校验] → commit → [Hook D: checkinSuccessful] → push → [Hook E: checkinFailed→Hook F: 冲突解决]` + +--- + +## 7. CI/CD 与发布策略 + +- **发布渠道**：双市场（Marketplace + OpenVSX）。**立即**：`ovsx create-namespace ` 并 **claim ownership**（OpenVSX namespace 默认非排他，防抢注）。 +- **publisher / 扩展 id**：扩展显示名 **Hyper Git**，id `hyper-git`；publisher 建议与 git owner 一致取 `threefish-ai`（**待你最终确认 publisher id**，创建后不可改）。 +- **CI 流水线**（`.github/workflows/ci.yml`）：`push/PR → lint→build→test 矩阵(ubuntu/mac/win, Linux 用 xvfb-run -a) → package vsix(Linux 打包保 POSIX 位) → upload artifact`；`tag v* → publish(vsce + ovsx, environment:production 审批门, PAT as secret)`。PR 仅跑 ubuntu 单格快门，main/tag 跑全矩阵（控成本）。 +- **版本治理**：Marketplace 版本不可撤销 → **快速补丁版本为唯一回滚范式**；pre-release 用奇数 minor 吸收 M5 AI 等高风险特性；CHANGELOG 用 Keep a Changelog 格式。 +- **安全**：PAT 短过期(90d) + 最小 scope + 仅存 GitHub encrypted secret；action pin 到完整 commit SHA；启用 Dependabot + CodeQL + `pnpm audit`；AI/遥测默认关闭。 +- **engines.vscode**：M0-M4 锁 `^1.85.0`（`@types/vscode:1.85.0` 严格对齐，让 tsc 拦截越界 API）；M5 评估上调以支持 LM/Chat API。 + +--- + +## 8. 关键风险与规避 + +| 风险 | 规避 | +|---|---| +| changelist 模型无法用原生 SCM group 表达 | 自建 `ChangelistRegistry`（已定为路径 B 核心）；`workspaceState` 持久化 | +| Webview 性能/内存（Log 图 + Commit 窗口） | Log 数据虚拟滚动 + 增量 postMessage；`retainContextWhenHidden` 按视图区分；graph 用轻量 SVG | +| `vscode.git` API 跨版本兼容 | `getAPI(1)` 锁主版本；Adapter 层防御性可选链 | +| 与原生 Source Control 视图双胞胎冲突 | 不注册竞争 SCM Provider；独立视图容器；原生视图平行共存 | +| 版本不可撤销误发 | CI 三平台门 + pre-release 通道 + 快速补丁回滚演练（tag→发布 < 10min） | +| PAT 泄露供应链攻击 | secret 隔离 + 短过期 + 优先 Entra OIDC 联邦（待核实 GA）+ SHA pin | +| 行级 partial commit 过早抽象 | 列入 M4（P2），MVP 仅文件级勾选提交 | +| AI 接缝过早抽象（YAGNI 反例风险） | 只定义接口 + Null 实现，零 AI 依赖，不写 AI 逻辑 | + +--- + +## 9. 验证方案（端到端） + +- **单元测试（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 对齐）。 +- **发布前自证**：Diff 分析、测试覆盖、三平台 CI 绿、`.vsix` 在干净 VS Code + Cursor 实机安装回归。 + +--- + +## 10. 立即下一步（Next Best Action） + +1. **建工作分支**（基于 `origin/feature/1.x.x`），创建 `package.json` + esbuild 骨架（复制官方 `esbuild-sample`），落地 M0。 +2. **PoC 验证两个关键风险点**：(a) `extensionDependencies:["vscode.git"]` + `getAPI(1)` 拿到 `Repository` 读 `workingTreeChanges`；(b) WebviewView Commit 编辑器 `postMessage → Repository.commit()`。两项跑通即消除主要技术不确定性。 +3. **并行**：`ovsx create-namespace` + claim ownership（防抢注）；将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线，并同步 `.agents/knowledge-map.md` 索引。 +4. **提交规范**：按用户偏好，commit 用 `/commit` 命令；PR 基线为 `origin/feature/1.x.x`，不直接推 master。 + +--- + +## 附录：调研来源（关键，IEEE 可溯源） + +**IDEA 源码（JetBrains/intellij-community）** +- `platform/vcs-api/src/com/intellij/openapi/vcs/checkin/CheckinHandler.java`（11 hook 生命周期） +- `plugins/git4idea/src/git4idea/checkin/GitCheckinEnvironment.kt`（commit + partial + amend） +- `platform/vcs-impl/.../impl/PartialChangesUtil.kt`（行级提交） +- `platform/vcs-api/.../changes/ChangeListManager.java`（changelist API 契约） +- `platform/vcs-impl/.../changes/shelf/ShelveChangesManager.java`（Shelf） + +**VS Code 源码/文档（microsoft/vscode + code.visualstudio.com）** +- `extensions/git/src/api/git.d.ts`（Repository 全签名，已逐行复核） +- [Source Control API](https://code.visualstudio.com/api/extension-guides/scm-provider)、[Webview API](https://code.visualstudio.com/api/extension-guides/webview)、[Bundling](https://code.visualstudio.com/api/working-with-extensions/bundling-extension)、[Testing](https://code.visualstudio.com/api/working-with-extensions/testing-extension)、[Publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)、[Continuous Integration](https://code.visualstudio.com/api/working-with-extensions/continuous-integration) +- proposed API 状态：[#185269 scmHistoryProvider](https://github.com/microsoft/vscode/issues/185269)、[#195474/#199778 InputBoxValueProvider 已删](https://github.com/microsoft/vscode/issues/195474)、[#179000 multi-diff](https://github.com/microsoft/vscode/issues/179000) +- AI 机制：[Language Model API](https://code.visualstudio.com/api/extension-guides/ai/language-model)、[Chat](https://code.visualstudio.com/api/extension-guides/ai/chat)、[Tools](https://code.visualstudio.com/api/extension-guides/ai/tools)、[BYOK Provider](https://code.visualstudio.com/api/extension-guides/ai/language-model-chat-provider) + +**发布生态** +- [eclipse/openvsx cli](https://github.com/eclipse/openvsx/blob/master/cli/README.md)、[Cursor 使用 OpenVSX](https://forum.cursor.com/t/cursor-marketplace-installs-offers-outdated-version-of-open-vsx-extension-despite-latest-version-being-available-upstream/159718)、[HaaLeo/publish-vs-code-extension](https://github.com/marketplace/actions/publish-vs-code-extension) diff --git a/docs/requirements/idea-feature-matrix.md b/docs/requirements/idea-feature-matrix.md new file mode 100644 index 0000000..462b269 --- /dev/null +++ b/docs/requirements/idea-feature-matrix.md @@ -0,0 +1,215 @@ +# IntelliJ IDEA 社区版 Git/Commit 模块 调研报告 + +> 调研目标：产出 IDEA「Git 工具窗口 + Commit 提交窗口」的【完整功能清单 + 关键源码锚点】，作为 VS Code 插件复刻的需求规约（Spec）基线。 +> 仓库：[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 + +--- + +## A. 模块地图（源码模块职责 + 代表类） + +### git4idea 插件层（`plugins/git4idea/src/git4idea/`） + +| 模块 | 一句话职责 | 代表类/文件路径 | +|---|---|---| +| `checkin/` | 提交（commit）流水线：环境实现、handler 工厂、Amend、staging area 管理、commit 后转换器、push-after-commit | `GitCheckinEnvironment.kt`、`GitCheckinHandlerFactory.kt`、`GitAmendCommitService.kt`、`GitRepositoryCommitter.kt`、`GitStagingAreaStateManager.kt`、`GitCommitAndPushExecutor.kt`、`GitPushAfterCommitDialog.java`、`GitPostCommitChangeConverter.kt` | +| `commit/` | Git 提交数据模型与提交信息辅助：commit message 提供器、最近提交、签名（GPG）、合并提交信息策略 | `GitTemplateCommitMessageProvider.kt`、`GitRecentCommitsProvider.kt`、`GitCommitCompletionContributor.kt`、`signing/GpgAgentConfigurator.kt`、`signature/GitCommitSignature.kt`、`GitStagingAreaCommitMode.kt` | +| `changes/` | 变更检测与历史：committed change list、文件历史、outgoing 变更、changes 视图刷新 | `GitCommittedChangeList.java`、`GitCommittedChangeListProvider.java`、`GitFileHistory.kt`、`GitOutgoingChangesProvider.java`、`GitChangesViewRefresher.java` | +| `stash/` | Git stash 操作（push/apply/pop/drop/keep index）+ stash UI 与缓存 | `GitStashUtils.kt`（`GitStashOperations`、`loadStashStack`、`createStashHandler`）、`GitStashContentProvider.kt`、`GitStashDialog.kt`、`GitStashChangesSaver.java`、`GitStashCache.kt` | +| `branch/` | 分支操作（create/checkout/delete/rename/merge/compare）+ branches popup/dashboard | `GitBranchWorker.java`、`GitBrancherImpl.java`、`GitCheckoutOperation.java`、`GitMergeOperation.java`、`GitCreateBranchOperation.kt`、`GitCompareBranchesUi.kt`、`ui/dashboard/BranchesDashboardTreeController.kt` | +| `rebase/` | rebase（含 interactive、auto-squash、fixup、reword）+ rebase 编辑器 + 续接/中止 | `GitRebaser.java`、`GitInteractiveRebaseAction.kt`、`GitAutoSquashCommitAction.kt`、`GitRebaseProcess.java`、`interactive/GitInteractiveRebaseUsingLog.kt`、`GitRewordService.kt` | +| `rollback/` | 回滚/撤销（revert、reset、unversioned→rollback） | `GitRollbackEnvironment.java` | +| `actions/` | 顶层 Git Action 入口（branches、rebase、fetch、push-up-to-commit、working trees 等） | `GitBranchesComboBoxAction.java`、`GitRebase.java`、`GitFetch.java`、`GitPushUpToCommitAction.kt`、`actions/branch/*`、`actions/workingTree/*` | +| `ui/` | Git UI（reset 对话框、tag、stash、branches widget、merge-rebase widget、branch dashboard） | `GitResetDialog.java`、`GitTagDialog.java`、`branch/GitBranchWidget.kt`、`toolbar/GitMergeRebaseWidget.kt` | +| `push/`、`pull/`、`fetch/`、`merge/`、`cherrypick/`、`reset/`、`revert/` | 对应的 Git 命令流水线与对话框（详见各子目录） | `push/GitPushUtil.kt`、`cherrypick/GitCherryPickAction.kt`、`revert/`（commit-level revert from log） | +| `annotate/`、`diff/`、`history/` | blame 注解、diff 对比、历史浏览 | `annotate/GitAnnotationProvider.kt`、`diff/`、`history/GitHistoryUtils.kt` | +| `index/`、`status/` | staging area（index）操作与 status 计算 | `index/GitIndexUtil.kt`、`index/GitFileStatusWorker.kt` | +| `ignore/`、`vfs/`、`util/`、`console/`、`conflicts/` | gitignore、VFS 集成、工具函数、控制台、冲突解决 | `ignore/`、`conflicts/GitConflictsUtil.kt` | + +### 平台层（`platform/`） + +| 模块 | 一句话职责 | 代表类/文件路径 | +|---|---|---| +| `vcs-api/`（变更/提交抽象） | VCS 抽象接口：ChangeListManager、CheckinHandler、CheckinEnvironment、CommitExecutor、CommitMessageProvider、RollbackEnvironment、ChangeProvider | `changes/ChangeListManager.java`、`changes/LocalChangeList`（接口）、`checkin/CheckinHandler.java`、`checkin/CheckinEnvironment`、`changes/CommitExecutor.java`、`changes/ui/CommitMessageProvider.java` | +| `vcs-impl/`（实现） | CLM 实现、commit 对话框、shelf（shelve/unshelve）、partial changes、checkin handler 管理器、committed changes 浏览 | `changes/ChangeListManagerImpl.java`、`changes/ChangeListWorker.java`、`changes/ui/CommitChangeListDialog.java`、`changes/shelf/ShelveChangesManager.java`、`changes/shelf/ShelvedChangesViewManager.java`、`impl/PartialChangesUtil.kt`、`impl/CheckinHandlersManagerImpl.kt`、`impl/LineStatusTrackerManager.kt`、`changes/local/*`（ChangeListCommand 体系：AddList/EditName/MoveChanges/RemoveList/SetDefault） | +| `vcs-log/` | Git Log 图（graph）、过滤、搜索、cherry-pick/revert 入口 | `platform/vcs-log/`（VcsLog UI 与数据模型） | +| `dvcs-api/` | 分布式 VCS 抽象（branch、repository、working tree 通用逻辑） | `platform/dvcs-api/` | + +--- + +## B. 功能全量矩阵（≥30 原子功能点，8 组） + +> 说明：「源码锚点」优先给关键类路径；「VS Code 原生对应物」对照 VS Code 内置 SCM/Git。 + +### 组 1：Commit 窗口（Commit / Shelf / Stash 标签页 + 提交流水线） + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层 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） | +| 3 | 提交信息历史与补全 | 点击历史按钮选最近提交信息；commit message 关键字补全 | 提交信息区历史按钮 / 输入触发补全 | `RecentCommitsProvider` + IDEA completion 体系 | `commit/GitRecentCommitsProvider.kt`、`GitCommitCompletionContributor.kt` | 中 | 无原生 | +| 4 | Conventional Commits 校验 | **IDEA 无内置 Conventional Commits 强校验**；仅支持 commit message 规则（wrap/reformat）与 quick-fix；需第三方插件 | 设置 `Version Control \| Commit` + quick-fix | commit message 重排（`CodeStyle`），无语义校验 | 「待核实」官方未提供 CC 校验类；参考 WebSearch 结论（需第三方） | 低（IDEA 本身无） | 无原生（需插件） | +| 5 | Amend last commit（修正上一提交） | 勾选 Amend，新改动并入上一次提交；可选指定被修正的提交 | Commit 窗口 Amend 复选框 + 下拉选择提交 | `git commit --amend`；`CommitToAmend`（Last/Specific） | `checkin/GitAmendCommitService.kt`、`GitAmendSpecificCommitSquasher.kt`；`GitCheckinEnvironment.isAmendCommitSupported/getAmendCommitDetails` | 中 | 无原生（git lens 等插件） | +| 6 | Author 覆盖 | 指定本次提交作者（name+email） | 高级选项 `Author` | `git commit --author=` | `checkin/GitCheckinEnvironment`（`myNextCommitAuthor` / `CommitContext.commitAuthor`）、`GitRepositoryCommitter` | 低 | 无原生 | +| 7 | Commit / Commit and Push | `Commit`（Ctrl+K）或 `Commit and Push`（Ctrl+Alt+K） | 按钮 / 快捷键 | commit 后可选 push；`CommitExecutor` + `GitCommitAndPushExecutor` | `checkin/GitCommitAndPushExecutor.kt`、`GitPushAfterCommitDialog.java`；`GitCheckinEnvironment.doCommit`（`commitContext.isPushAfterCommit`） | 中 | 是（Commit & Push 按钮，VS Code 1.69+） | +| 8 | Sign-off 提交 | 勾选自动追加 `Signed-off-by` | 高级选项 | `git commit -s` | `checkin/GitRepositoryCommitter`（`myNextCommitSignOff` / `commitContext.isSignOffCommit`） | 低 | 无原生 | +| 9 | Skip Git hooks（本次） | 勾选跳过本次 hook | 高级选项 `Run Git hooks` 取消 | `git commit --no-verify` | `checkin/GitSkipHooksCommitHandlerFactory.kt`、`GitCheckinEnvironment`（`myNextCommitSkipHook`） | 低 | 无原生 | +| 10 | 提交前 Inspection / 代码检查 | 勾选 Reformat/Rearrange/Optimize imports/Cleanup/Update copyright/Check TODO/Analyze code/Run Configuration 作为提交检查 | 高级选项 `Commit Checks` / `Advanced Commit Checks` | `CheckinHandler` + `CodeAnalysisBeforeCheckinHandler` + 平台 inspection/checkin factory（EP `com.intellij.checkinHandlerFactory`） | `vcs-api/.../checkin/CheckinHandler.java`；平台各 `BeforeCheckinHandler`；git4idea 自带 `GitCRLF/LargeFile/UserName/DetachedRoot/FileName CheckinHandler`（见 `GitCheckinHandlerFactory.kt`） | 高 | 无原生 | +| 11 | Commit Checks 执行顺序 | EARLY/LATE 排序，失败可阻断或后置 | 自动 | `CommitCheck.ExecutionOrder` | `checkin/GitCheckinHandlerFactory.kt`（各 handler 的 `getExecutionOrder()`） | 中 | 无 | +| 12 | CRLF / 大文件 / 用户名 / detached HEAD / 坏文件名 预检 | 提交前提示 CRLF、大文件、未设 user.name、detached HEAD、Windows 非法文件名 | 自动弹窗 | 各 `GitCheckinHandler`（`runGitCheck` 返回 `CommitProblem`） | `GitCRLFCheckinHandlerFactory`、`GitLargeFileCheckinHandlerFactory`、`GitUserNameCheckinHandlerFactory`、`GitDetachedRootCheckinHandlerFactory`、`GitFileNameCheckinHandlerFactory`（同 `GitCheckinHandlerFactory.kt`） | 中 | 无 | +| 13 | Editor 内联提交（gutter marker） | 点 gutter 变更标记 → 写 message → 提交单处改动 | gutter 变更标记工具栏 | `LineStatusTracker` + inline commit | `vcs-impl/.../impl/LineStatusTrackerManager.kt`；官方文档「Commit selected changes from the editor」 | 中 | 无原生 | +| 14 | After Commit 上传文件 | 提交后上传到部署服务器 | 高级选项 `After Commit` | 部署插件 EP | 平台 Deployment 集成（git4idea 不负责） | 低 | 无 | + +### 组 2：Local Changes 变更列表（多 changelist 模型） + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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 概念） | +| 17 | 新建 changelist | `+` 新建命名列表 | `+` 按钮 / 右键 New Changelist | `ChangeListModification`；命令 `AddList` | `vcs-impl/.../changes/ui/NewChangelistDialog.java`、`NewEditChangelistPanel.kt`；`changes/local/AddList.java` | 低 | **无**（git stash/resource group 替代） | +| 18 | 删除 changelist | 删除空列表（自动清理选项） | 右键 Delete | `scheduleAutomaticEmptyChangeListDeletion`；命令 `RemoveList` | `ChangeListManager.scheduleAutomaticEmptyChangeListDeletion`；`changes/local/RemoveList.java`；设置 `REMOVE_EMPTY_INACTIVE_CHANGELISTS` | 低 | 无 | +| 19 | 重命名 changelist | 右键 Edit → 改名/改注释 | 右键 Edit Changelist | 命令 `EditName`/`EditComment` | `vcs-impl/.../changes/ui/EditChangelistDialog.java`；`changes/local/EditName.java`、`EditComment.java` | 低 | 无 | +| 20 | Move changes between changelists | `⌘⇧M`/`Alt+Shift+M` 或拖拽移动变更到其他列表 | 快捷键 / 右键 Move to Another Changelist / 拖拽 | `ChangeListModification.moveChanges`；命令 `MoveChanges` | `changes/local/MoveChanges.java`；`vcs-impl/.../changes/ui/ChangeListChooser.java` | 中 | **无** | +| 21 | Changelist 自动绑定分支 | （IDEA Git 无原生 changelist↔branch 自动绑定；**任务上下文（Tasks）** 可关联 changelist 与 branch） | 任务切换 | `ActiveChangeListTracker`；任务管理器 | `vcs-impl/.../impl/ActiveChangeListTracker.kt`；任务上下文集成「待核实」具体绑定类 | 中 | 无 | + +### 组 3：Partial / Selective / 按行（line-level）提交 + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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） | +| 24 | 按行（line）提交 | 右键行 → Split Chunks & Include Selected Lines | gutter 复选 / 右键 | `LineStatusTracker` 行级 exclusion | `PartialChangesUtil.convertExclusionState`；官方文档「Split Chunks and Include Selected Lines into Commit」 | **高** | 部分（Staged/Unstaged 选择行） | +| 25 | Move Lines to Another Changelist | 编辑时把行级改动划入不同 changelist | gutter marker → 选 changelist | 行级 `ChangeListChange` + `PartialLocalLineStatusTracker` | `PartialChangesUtil`、`ChangeListChange`；官方文档「Put changes into different changelists」 | **高** | **无** | +| 26 | Git Staging Area 模式 | 设置启用 → changelist 切换为 index 暂存模型 | 设置 `Enable staging area` | `GitStagingAreaStateManager` + index | `checkin/GitStagingAreaStateManager.kt`、`GitIndexInfoStagingAreaStateManager.kt`、`GitResetAddStagingAreaStateManager.kt`；`commit/GitStagingAreaCommitMode.kt` | 中 | 是（VS Code 原生 index 模型） | + +### 组 4：Shelf 与 Stash + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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` | 中 | 无 | +| 29 | Stash changes（git native） | `git stash push`（可选 `--keep-index`、message、指定文件 pathspec） | 右键 Git \| Stash Changes | `git stash push [--keep-index] [--message] [-- pathspec]` | `stash/GitStashUtils.kt`（`createStashHandler`/`runStashInBackground`）；`ui/GitStashDialog.kt`、`GitStashContentProvider.kt` | 中 | 是（命令式，无原生 UI） | +| 30 | Apply / Pop / Drop / Clear stash | Apply 保留 / Pop 移除 / Drop 单个 / Clear 全部；可选 Reinstate Index（`--index`）；Unstash as new branch | Stash tab 按钮 / 右键 | `git stash apply\|pop\|drop\|branch` | `stash/GitStashUtils.kt`（`GitStashOperations.dropStashWithConfirmation`/`clearStashesWithConfirmation`/`unstash`/`createUnstashHandler`） | 中 | 部分（命令式） | +| 31 | Combine Stash & Shelf tab | 合并两个标签页 | 设置 `Combine stashes and shelves in one tab` | UI 合并 | `stash/ui/GitStashContentProvider.kt`、`shelf/ShelvedChangesViewManager.java` | 低 | 无 | +| 32 | Import external patches 为 shelf | 导入 patch 作为 shelf 再 unshelve | Shelf 右键 Import Patches | patch 解析 + shelf | `shelf/ImportIntoShelfAction.java` | 低 | 无 | +| 33 | Shelve base revision（DCVS） | 自动保存 base revision 以支持 3-way merge | 设置 `Shelve base revisions` | base revision 存储 | `shelf/ShelveChangesManager`（配置项） | 低 | 无 | +| 34 | Save to Shelf（不重置本地） | 复制改动到 shelf 但保留本地 | `Ctrl+Shift+A` Save to Shelf | patch 复制 | `shelf/ShelveChangesAction.kt`（相关 action） | 低 | 无 | + +### 组 5：Diff（对比） + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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`） | 中 | 部分 | +| 37 | Annotate（blame） | 编辑器/gutter 显示逐行作者/提交 | Annotate | `GitAnnotationProvider` | `annotate/GitAnnotationProvider.kt`；`actions/GitToggleAnnotationOptionsActionProvider.java` | 中 | 是（GitLens 等；VS Code 1.90+ 实验内置） | +| 38 | Show History for selection | 选中代码/文件的历史 | 右键 Show History / Git History | `GitFileHistory`/`GitHistoryUtils` | `changes/GitFileHistory.kt`、`MutableLinearGitFileHistory.kt`；`history/GitHistoryUtils.kt` | 中 | 是（文件历史） | + +### 组 6：Log 提交图 + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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 过滤） | +| 41 | Cherry-pick from log | 右键提交 → Cherry-Pick 到当前分支 | 右键 Cherry-Pick | `git cherry-pick` | `cherrypick/GitCherryPickAction.kt`；`branch/CherryPickedCommitsHighlighter.kt` | 中 | 无原生 | +| 42 | Revert commit from log | 右键提交 → Revert Commit（生成反向提交） | 右键 Revert Commit | `git revert` | `revert/`（commit-level）；`actions/GitRevertResolvedAction.kt` | 中 | 无原生 | +| 43 | Undo Commit / Push All up to Here / Drop（rebase） | 撤销最近提交 / 推送到某提交 / rebase 删除 | 右键 / Log action | soft reset / `git push ` / interactive rebase | `actions/GitPushUpToCommitAction.kt`；`rebase/`（interactive） | 中 | 无原生 | +| 44 | Reword / Squash / Fixup（from log，interactive rebase） | 在 log 内改写提交 | 右键 + interactive rebase | interactive rebase | `rebase/GitRewordAction.kt`、`GitAutoSquashCommitAction.kt`、`GitCommitSquashBySubjectAction.kt`、`interactive/GitInteractiveRebaseUsingLog.kt` | 高 | 无原生 | + +### 组 7：Branches + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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` | 低 | 部分 | +| 47 | Compare branches | 对比两分支文件差异 | 右键 Compare | `GitCompareBranchesUi` + diff fs | `branch/GitCompareBranchesUi.kt`、`GitCompareBranchesFilesManager.java`、`GitCompareBranchesVirtualFileSystem.kt` | 中 | 无原生 | +| 48 | Merge / Rebase / Pull / Push / Fetch（分支级） | 在分支上执行 merge/rebase/update/push/fetch | 分支右键菜单 | 各 operation worker | `branch/GitMergeOperation.java`、`GitBranchWorker.java`；`rebase/GitRebaser.java`；`actions/branch/GitPullBranchAction.kt`、`GitPushBranchAction.kt`、`GitRebaseBranchAction.kt`、`GitUpdateSelectedBranchAction.kt`；`actions/GitFetch.java` | 中 | 是（命令式） | +| 49 | Branches Dashboard / Popup | 分支树状仪表盘 + popup 选择器 | Git 工具窗口 Branches pane | `BranchesDashboardTree*` + popup | `ui/branch/dashboard/BranchesDashboardTreeController.kt`、`BranchesTree.kt`；`ui/branch/GitBranchWidget.kt`、`popup/GitBranchesTreePopupOnBackend.kt` | 中 | 部分（VS Code status bar） | +| 50 | Cleanup branches / Find merged | 清理已合并分支、查找合并的本地分支 | Cleanup action | `git branch --merged` | `ui/branch/cleanup/CleanupBranchesAction.kt`、`branch/FindMergedLocalBranchesAction.kt` | 低 | 无 | + +### 组 8：右键 / 内联操作 + +| # | 功能名 | 用户可见行为 | 触发入口 | 底层机制 | 源码锚点 | 复刻难度 | 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` | 低 | 无原生（命令式） | +| 53 | Ignore | 加入 .gitignore | 右键 Add to .gitignore | `ignore/` + `.gitignore` 写入 | `ignore/`（GitIgnore 集成） | 低 | 是 | +| 54 | Compare / Show Diff | 对比改动 | 右键 Show Diff | `diff/` | `git4idea/diff/`；`ChangesBrowserBase`（diff producer） | 中 | 是 | +| 55 | Jump to Source | 跳到源码 | 右键 Jump to Source / `F4` | 编辑器导航 | `vcs-impl/.../changes/ui/EditSourceForDialogAction.java` | 低 | 是 | +| 56 | Copy revision | 复制 commit hash / 修订号 | 右键 Copy Revision / Copy Hash | 剪贴板 | `branch/GitRefDialog` 等（参考 Log 右键 Copy Hash） | 低 | 部分 | + +--- + +## C. IDEA「多 changelist」模型 vs VS Code SCM「group」模型 差异要点 + +| 维度 | IDEA 多 changelist | VS Code SCM group | +|---|---|---| +| 核心抽象 | `LocalChangeList`（命名、有 id、有 comment、可设 active）+ `Change` 可属于多个列表（同一文件不同 chunk 跨列表，`ChangeListChange` + `PartialLocalLineStatusTracker`） | `SourceControlResourceGroup`（按 type/自定义 label 分组，无「active」概念，无跨组同文件 chunk） | +| 数据来源 | 平台 `ChangeListManager` 统一管理（含本地 changelist 持久化、`ChangeListListener` 事件） | 扩展点 `scm.ResourceGroups`（插件自行维护） | +| Active 概念 | 有「active changelist」：新改动默认落入；`getDefaultChangeList`/`setDefaultChangeList` | 无；新改动归属由插件决定（通常单组 Staged/Changes） | +| 行级跨列表 | 支持（`PartialChangesUtil`/`PartialLocalLineStatusTracker`：同一文件不同行属于不同 changelist） | 不支持原生；git staging 可部分行 stage，但无「命名列表」归属 | +| 持久化 | `ChangeListManagerSerialization` 持久化 changelist 定义 | 插件自定义状态 | +| 与 git index 关系 | 默认「changelist 即待提交集」（非 staging 模型）；可选切换为 Staging Area 模式（`GitStagingAreaCommitMode`） | 默认即 staging 模型（Changes/ Staged） | +| 提交范围 | 提交所选 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 最大的差异与复刻难点。 + +--- + +## D. IDEA Checkin 流水线（CheckinHandler 生命周期）hook 点清单 + +> 来源：`platform/vcs-api/src/com/intellij/openapi/vcs/checkin/CheckinHandler.java`（完整源码已读）。 +> 注册：通过 `BaseCheckinHandlerFactory`/`VcsCheckinHandlerFactory`（EP `com.intellij.checkinHandlerFactory` 全局 + `com.intellij.vcs.checkinHandlerFactory` VCS 专属），由 `CheckinHandlersManagerImpl`（`platform/vcs-impl/.../impl/CheckinHandlersManagerImpl.kt`）聚合。 +> 现代 IDEA 推荐实现 `CommitCheck`（suspend 协程，返回 `CommitProblem`）替代旧 `beforeCheckin`。git4idea 的 `GitCheckinHandler` 抽象类同时实现 `CheckinHandler` + `CommitCheck`。 + +| Hook 点 | 方法签名 | 触发时机 | 返回/语义 | AI 接入价值 | +|---|---|---|---|---| +| Before-Commit 配置面板（Before Commit 组） | `RefreshableOnComponent getBeforeCheckinConfigurationPanel()` | 构建 commit 窗口选项面板 | 注入复选框（如 Reformat/Optimize imports/Check TODO） | 高：注入「AI review before commit」开关 | +| 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 执行顺序 | `CommitCheck.ExecutionOrder getExecutionOrder()` | 排序多个 CommitCheck | `EARLY`/`DEFAULT`/`LATE` | 中：控制 AI 检查与其他检查顺序 | +| CommitCheck 启用开关 | `boolean isEnabled()` | 决定是否运行 | 布尔 | 中 | +| **Successful 回调** | `void checkinSuccessful()`（`@RequiresEdt`） | 提交成功后 | 通知/后续动作 | 高：AI 提交摘要、自动生成 PR 描述 | +| **Failed 回调** | `void checkinFailed(List)` | 提交失败后 | 异常列表 | 中：AI 诊断失败原因 | +| **变更勾选变更通知** | `void includedChangesChanged()` | 用户勾选/取消变更时 | 实时感知提交范围 | **高**：AI 实时根据勾选范围动态生成 commit message | +| Executor 过滤 | `boolean acceptExecutor(CommitExecutor)` | 决定本 handler 是否对某 executor 生效 | 默认对非 `LocalCommitExecutor` 生效（即 shelf/create patch 不跑该检查） | 中：区分 commit vs shelf vs push | +| CommitProblem 模态解决 | `CommitProblem.showModalSolution(project, commitInfo)` | 检查发现问题时弹模态方案 | `ReturnResult` | 中：AI 给出修复建议弹窗 | + +> **CommitContext 关键字段**（贯穿整个流水线，承载 commit 选项）：`commitToAmend`、`isSkipHooks`、`commitAuthor`、`commitAuthorDate`、`isSignOffCommit`、`isPushAfterCommit`、`isCommitRenamesSeparately`、`commitWithoutChangesRoots`。源码：`GitCheckinEnvironment.updateState()` / `doCommit()`。 +> +> **AI 接入建议**：实现一个 `CommitCheck`（EARLY 顺序）挂载 AI 审查 + 实现 `includedChangesChanged()` 动态生成 commit message + 实现 `checkinSuccessful()` 触发 AI 后处理，可完整复用 IDEA 提交流水线的「设计-实现-验证」闭环，无需重写 commit 引擎。 + +--- + +## E. 关键事实来源（循证索引） + +### 源码（GitHub master） +- 提交 handler 生命周期：[`platform/vcs-api/.../checkin/CheckinHandler.java`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/checkin/CheckinHandler.java) +- git4idea 提交环境与 Amend：[`plugins/git4idea/.../checkin/GitCheckinEnvironment.kt`](https://github.com/JetBrains/intellij-community/blob/master/plugins/git4idea/src/git4idea/checkin/GitCheckinEnvironment.kt)、[`GitCheckinHandlerFactory.kt`](https://github.com/JetBrains/intellij-community/blob/master/plugins/git4idea/src/git4idea/checkin/GitCheckinHandlerFactory.kt) +- ChangeListManager 抽象：[`platform/vcs-api/.../changes/ChangeListManager.java`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeListManager.java) +- Partial changes 工具：[`platform/vcs-impl/.../impl/PartialChangesUtil.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-impl/src/com/intellij/openapi/vcs/impl/PartialChangesUtil.kt) +- Shelf 管理：[`platform/vcs-impl/.../changes/shelf/ShelveChangesManager.java`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-impl/src/com/intellij/openapi/vcs/changes/shelf/ShelveChangesManager.java) +- Stash 操作：[`plugins/git4idea/.../stash/GitStashUtils.kt`](https://github.com/JetBrains/intellij-community/blob/master/plugins/git4idea/src/git4idea/stash/GitStashUtils.kt) +- Checkin handler 聚合：[`platform/vcs-impl/.../impl/CheckinHandlersManagerImpl.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-impl/src/com/intellij/openapi/vcs/impl/CheckinHandlersManagerImpl.kt) +- Commit message 提供器 EP：[`platform/vcs-api/.../changes/ui/CommitMessageProvider.java`](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ui/CommitMessageProvider.java) +- changelist 命令体系：`platform/vcs-impl/.../changes/local/{AddList,EditName,EditComment,MoveChanges,RemoveList,SetDefault,SetReadOnly}.java` + +### 官方文档（jetbrains.com/help/idea 2026.1） +- [Commit and push changes to Git repository](https://www.jetbrains.com/help/idea/commit-and-push-changes.html)（commit 窗口、amend、author、commit checks、partial commit、staging area、push） +- [Shelve or stash changes](https://www.jetbrains.com/help/idea/shelving-and-unshelving-changes.html)（shelve/unshelve silently/with conflict、stash apply/pop/drop/keep index、combine tabs） +- [Group changes into changelists](https://www.jetbrains.com/help/idea/managing-changelists.html)（active/create/move/delete/rename changelist） +- [Log Tab](https://www.jetbrains.com/help/idea/log-tab.html)（graph/filter/cherry-pick/revert） +- [Manage Git branches](https://www.jetbrains.com/help/idea/manage-branches.html)（create/checkout/delete/rename/compare/merge/rebase） +- [Edit Git project history](https://www.jetbrains.com/help/idea/edit-project-history.html)（amend 历史、reword/squash/fixup） +- [Investigate changes in Git repository](https://www.jetbrains.com/help/idea/investigate-changes.html)（history/annotate） + +--- + +## 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。 +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 new file mode 100644 index 0000000..cf738cd --- /dev/null +++ b/docs/research/02-vscode-scm-integration.md @@ -0,0 +1,404 @@ +# Track2 调研报告:VS Code SCM API 与 vscode.git 导出 API 集成路径 + +> 调研对象:在 VS Code 中复刻 IDEA 风格 Git 工具窗口(多 changelist + 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;存疑项标注「待核实」。 + +--- + +## 0. 核心结论(执行摘要) + +| 决策项 | 结论 | +|---|---| +| **推荐路径** | **路径 B(纯消费 vscode.git 导出 API + 自建 TreeView/WebviewView 渲染 IDEA 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()` | +| **git 操作底座** | 全部复用 vscode.git 导出的 `API`(`commit/add/revert/diff/blame/log/stash/branch/merge/rebase`),不自调 git CLI(循证:GitHub PR 扩展即此模式) | + +**一句话理由**:VS Code 原生 SCM API 的设计哲学是「provider 负责填数据 + 框架负责渲染统一 UI」,与 IDEA「插件完全自绘工具窗口」相反。强行注册独立 SCM Provider(A/C)会与原生 git 视图**双胞胎冲突**,且无法表达 IDEA 的多 changelist + Commit 对话框这种「自绘」需求;而纯消费 git API + 自绘视图(B)既能拿到稳定的 git 能力,又拥有 100% 的 UI 自由度,与原生视图零冲突,符合「复用驱动 + 正交分解」。 + +--- + +## 1. SCM API 能力地图(稳定 API) + +> 来源:[官方 SCM provider 指南](https://code.visualstudio.com/api/extension-guides/scm-provider)、[VS Code API 参考](https://code.visualstudio.com/api/references/vscode-api)、`src/vscode-dts/vscode.d.ts`。下列为**稳定(public/stable)**能力,proposed 项单列。 + +### 1.1 SourceControl(顶层 provider 句柄) + +由 `vscode.scm.createSourceControl(id, label, rootUri?)` 创建。稳定字段(来源:[vscode.d.ts](https://github.com/microsoft/vscode/blob/main/src/vscode-dts/vscode.d.ts) `export interface SourceControl`): + +| 成员 | 类型 | 能力 | IDEA 对应 | +|---|---|---|---| +| `id` / `label` | `readonly string` | provider 标识与显示名 | — | +| `rootUri` | `readonly Uri \| undefined` | 仓库根 | 仓库根 | +| `inputBox` | `SourceControlInputBox` | **唯一的**提交消息输入框 | Commit Message 区 | +| `count` | `number \| undefined` | 在 provider 标题上显示的徽标数字 | Changes 计数 | +| `commitTemplate` | `string \| undefined` | 预填入 inputBox 的模板 | Commit Message Template | +| `acceptInputCommand` | `Command \| undefined` | 用户按 Ctrl/Cmd+Enter 提交时触发的命令 | Commit 按钮 | +| `statusBarCommands` | `Command[]` | 状态栏下拉命令 | — | +| `quickDiffProvider` | `QuickDiffProvider \| undefined` | 提供 gutter quick diff | 编辑器内联 diff 标记 | +| `createResourceGroup(id, label)` | → `SourceControlResourceGroup` | 创建分组 | changelist 雏形 | +| `selected` | `readonly boolean` | 是否为当前选中的 provider | active 仓库 | + +**硬限制**: +- **每个 SourceControl 只有一个 `inputBox`**(单 Commit Message),无法表达「多 changelist 各自有独立 message」(IDEA 的 Default changelist 才有 message,其他可独立)。来源:[官方指南 SCM Input Box 段](https://code.visualstudio.com/api/extension-guides/scm-provider#scm-input-box)。 +- `SourceControl.contextValue`(用于 `when` 子句精细控制菜单)是 **proposed API**(`scmProviderOptions`,issue [#254910](https://github.com/microsoft/vscode/issues/254910))。来源:[vscode.proposed.scmProviderOptions.d.ts](https://github.com/microsoft/vscode/blob/main/src/vscode-dts/vscode.proposed.scmProviderOptions.d.ts)。 + +### 1.2 SourceControlResourceGroup(分组 = changelist 的近似) + +``` +createResourceGroup(id, label) → { id, label, resourceStates, hideWhenEmpty, ... dispose() } +``` + +- `resourceStates: SourceControlResourceState[]` — 你**全量覆盖**这个数组来更新分组内容(push 模型,非增量)。 +- `hideWhenEmpty: boolean` — 空分组自动隐藏。 +- 分组在视图里**默认可折叠**(VS Code 1.18+ SCM 视图即树状)。来源:[官方指南 Source Control Model 段](https://code.visualstudio.com/api/extension-guides/scm-provider#source-control-model)。 + +**能否多 group 折叠?** 能。一个 SourceControl 下 `createResourceGroup` 可调用多次,每个 group 独立折叠。git 扩展自己就建了 `merge` / `index` / `workingTree` / `untracked` 四个 group。来源:`extensions/git/src/repository.ts`(git.d.ts 的 `RepositoryState` 暴露了 `mergeChanges/indexChanges/workingTreeChanges/untrackedChanges`,对应这四个 group)。 + +**changelist 表达力的硬限制**: +- group 是「只读展示容器」,**没有 group 级别的 commit message、没有 group 级别的 active 概念**。IDEA 的 active changelist(active 时新增文件自动落入)在原生 SCM 里无对应物。 +- group 之间**无法跨 group 拖拽移动文件**(move changes)——SCM 视图不支持跨 group DnD,只能靠 `scm/resourceState/context` 菜单命令实现。 + +### 1.3 SourceControlResourceState(单个文件条目) + +稳定字段(来源:[官方指南](https://code.visualstudio.com/api/extension-guides/scm-provider#source-control-view) + [Haxe externs 镜像](https://vshaxe.github.io/vscode-extern/vscode/SourceControlResourceState.html)): + +| 成员 | 能力 | +|---|---| +| `resourceUri: Uri` | 文件路径(渲染主标签) | +| `command?: Command` | **单击**该文件时的命令(通常打开 diff) | +| `decorations?: SourceControlResourceDecorations` | 状态色/图标/删除线等 | +| `multiDiffEditorOriginalUri?` / `multiDiffEditorModifiedUri?` | 接入 multi-diff 编辑器(proposed `scmMultiDiffSource`,见下) | + +### 1.4 SourceControlResourceDecorations(状态色 M/A/D/U...) + +稳定字段(来源:[Haxe externs](https://vshaxe.github.io/vscode-extern/vscode/SourceControlResourceDecorations.html) + 官方指南): + +| 成员 | 对应 IDEA 状态色 | +|---|---| +| `strikeThrough?: boolean` | 删除(D) | +| `faded?: boolean` | 未跟踪/弱化(U) | +| `tooltip?: string` | 悬停提示 | +| `letter?: string` | 单字母角标(M/A/D/R/C/U) | +| `color?: ThemeColor` | 状态色(如 `gitDecoration.modifiedResourceForeground`) | +| `iconPath?: string \| Uri \| {light, dark}` | 自定义图标 | +| `source?: string` | 来源标注 | + +> IDEA 的 M/A/D/U/Renamed/Copied 完全可由 `letter` + `color` 组合复刻(git 扩展就是这么做的,见其 `Resource` 类的 decorations 计算)。 + +### 1.5 QuickDiff(编辑器 gutter 内联 diff) + +``` +quickDiffProvider?: QuickDiffProvider // provideOriginalResource(uri) → 原始资源 Uri +``` +配合 `registerTextDocumentContentProvider` 提供原始内容。来源:[官方指南 Quick Diff 段](https://code.visualstudio.com/api/extension-guides/scm-provider#quick-diff)。能力完备,可直接复用。 + +### 1.6 SourceControlInputBox(提交消息框)— 关键硬限制 + +**稳定字段仅有**:`value: string`、`visible: boolean`、`placeholder: string`。来源:[官方指南 SCM Input Box](https://code.visualstudio.com/api/extension-guides/scm-provider#scm-input-box) + WebSearch 交叉确认。 + +**致命限制(循证)**:曾用于「按 provider 动态提供 inputBox 值/校验」的 `SourceControlInputBoxValueProvider` 提案,**已被官方删除**(PR [microsoft/vscode#199778](https://github.com/microsoft/vscode/issues/199778),issue [#195474](https://github.com/microsoft/vscode/issues/195474) 标题由 `SourceControlInputBoxValueProvider API proposal` 改为 `scm/inputBox menu contribution`)。结论:**无法在原生 inputBox 上做 Conventional Commits 实时校验、无法嵌多行模板编辑器、无法加自定义按钮**。 + +> 这一硬限制直接决定了:IDEA 的 Commit Message 多行编辑区(模板/校验/Amend/Author)无法落在原生 inputBox 上 → 必须自建 WebviewView(见第 5 节)。 + +### 1.7 SCM 菜单贡献点(自定义二级菜单/inline 按钮) + +来源:[官方指南](https://code.visualstudio.com/api/extension-guides/scm-provider#source-control-view)。**全部稳定**,且能力足够复刻 IDEA 文件右键菜单: + +| 菜单 id | 作用位置 | 可放 `inline`(行内按钮) | +|---|---|---| +| `scm/title` | provider 标题栏 | ✅ navigation 组行内 | +| `scm/resourceGroup/context` | **分组(changelist)右键** | ✅ | +| `scm/resourceState/context` | **文件右键** | ✅ | +| `scm/resourceFolder/context` | 文件夹节点右键 | ✅ | +| `scm/repository` | Repositories 视图每项 | ✅ | +| `scm/sourceControl` | Repositories 视图右键 | ❌ | +| `scm/change/title` | 内联 diff 编辑器标题栏 | ❌ | + +`when` 子句可用 `scmProvider` / `scmResourceGroup` context key 精细控制。来源:官方指南示例 `when: "scmProvider == git && scmResourceGroup == merge"`。 + +> 结论:**每个文件的二级菜单、行内 inline 按钮、分组级菜单都能自定义**——这部分原生 SCM 完全够用。 + +### 1.8 提交图(SourceControlHistoryItem)— proposed,不可稳定复用 + +`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**。 + +### 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。 + +--- + +## 2. vscode.git 扩展导出 API(已读源码确认) + +> 来源:`extensions/git/src/api/git.d.ts`(完整签名)+ `extensions/git/src/api/api1.ts`(实现)。两文件已逐行读取,下述为源码直接摘录的事实。 + +### 2.1 版本机制与稳定性 + +```ts +export interface GitExtension { + readonly enabled: boolean; + readonly onDidChangeEnablement: Event; + getAPI(version: 1): API; // 唯一版本入口,version 必须传字面量 1 +} +``` +来源:[git.d.ts `GitExtension`](https://github.com/microsoft/vscode/blob/main/extensions/git/src/api/git.d.ts)。 + +- **版本机制**:`getAPI(1)` 是唯一导出形态,以字面量 `1` 锁定主版本;若 git 扩展 disabled 会抛错,需监听 `onDidChangeEnablement`。 +- **稳定性**:**这是稳定公开的扩展导出 API**,不是 proposed。第三方扩展经 Marketplace 发布无需特批。来源:官方 [extensions/git/README.md](https://github.com/microsoft/vscode/blob/main/extensions/git/README.md) 明示「The Git extension exposes an API, reachable by any other extension」。 +- **untrusted workspace**:git 扩展在 untrusted workspace 下功能受限(`supportUntrusted: false`),消费方需在 trusted 环境使用。来源:git 扩展 package.json(待核实具体 policy 字段,行为可观察)。 + +### 2.2 消费声明方式(循证:GitHub PR 扩展即此模式) + +**package.json**: +```json +{ "extensionDependencies": ["vscode.git"] } +``` +> `extensionDependencies` 声明运行时依赖,保证激活顺序与可用性。来源:[Extension Manifest 参考](https://code.visualstudio.com/api/references/extension-manifest)。**注意**:不需要 `enabledApiProposals`,因为这不是 proposed API。 + +**TypeScript 类型**:官方要求「把 `extensions/git/src/api/git.d.ts` 复制进你的扩展源码」。来源:官方 git README。 + +**运行时获取**(标准模式,来源:[Stack Overflow 官方回答](https://stackoverflow.com/questions/59442180/vs-code-git-extension-api) + [dev.to 实操](https://dev.to/bwfiq/live-syncing-to-a-git-repository-with-a-vs-code-extension-3p8m)): +```ts +const gitExt = vscode.extensions.getExtension('vscode.git')!; +await gitExt.activate(); // 防御性激活 +const api = gitExt.exports.getAPI(1); // → API +``` + +### 2.3 `API` 表面能力(源码确认) + +来源:[git.d.ts `API`](https://github.com/microsoft/vscode/blob/main/extensions/git/src/api/git.d.ts) + api1.ts 实现。 + +| 能力 | API | 备注 | +|---|---|---| +| 仓库发现 | `api.repositories: Repository[]`、`onDidOpenRepository`、`onDidCloseRepository`、`getRepository(uri)`、`getRepositoryRoot(uri)` | 多仓库支持完备 | +| 状态生命周期 | `api.state: 'uninitialized'\|'initialized'` + `onDidChangeState` | 初始化前 `repositories` 为空 | +| 发布事件 | `onDidPublish` | Commit & Push 完成回调 | + +### 2.4 `Repository` 能力(源码逐项确认)— 这是最关键的能力底座 + +来源:[git.d.ts `Repository`](https://github.com/microsoft/vscode/blob/main/extensions/git/src/api/git.d.ts)。 + +| IDEA 功能域 | Repository 方法 | 覆盖度 | +|---|---|---| +| **变更模型** | `state.indexChanges` / `workingTreeChanges` / `mergeChanges` / `untrackedChanges` + `Status` 枚举(INDEX_MODIFIED/ADDED/DELETED/RENAMED/COPIED + MODIFIED/DELETED/UNTRACKED/IGNORED/INTENT_TO_ADD/INTENT_TO_RENAME/TYPE_CHANGED + 冲突 7 种 ADDED_BY_US...BOTH_MODIFIED) | ✅ 完全覆盖 IDEA 的 M/A/D/U/Renamed/Copied + 冲突 | +| **stage/unstage** | `add(paths)`、`revert(paths)`(unstage,IDEA 语义)、`clean(paths)`、`restore(paths, {staged, ref})` | ✅ | +| **commit** | `commit(message, opts?: {all, amend, signoff, signCommit, empty, noVerify, useEditor})` | ✅ 含 amend/signoff/no-verify | +| **diff** | `diffWithHEAD`、`diffWith(ref)`、`diffIndexWithHEAD`、`diffBetween(ref1,ref2)`、`diffBetweenPatch`、`diffBetweenWithStats` | ✅ 覆盖与分支/HEAD/本地比较 | +| **blame** | `blame(path)` → string | ✅ Show History/Annotate | +| **log** | `log(opts?: {maxEntries, path, range, author, grep, refNames, sortByAuthorDate, shortStats})` → `Commit[]` | ✅ 含按作者/路径/消息过滤,Commit 带 hash/message/parents/authorDate/authorName/shortStat | +| **branch** | `createBranch(name, checkout, ref?)`、`deleteBranch`、`getBranch`、`getBranches(query)`、`setBranchUpstream` | ✅ 创建/检出/删除/重命名(重命名无直接 API,待核实)/比较 | +| **merge/rebase** | `merge(ref)`、`mergeAbort()`、`rebase(branch)` | ✅ | +| **stash** | `createStash({message, includeUntracked, staged})`、`applyStash(index)`、`popStash(index)`、`dropStash(index)` | ✅ stash/apply/drop(pop=apply+drop) | +| **tag** | `tag(name, message, ref?)`、`deleteTag` | ✅ | +| **fetch/pull/push** | `fetch(options)`、`pull(unshallow?)`、`push(remote, branch, setUpstream, force)` + `ForcePushMode` 枚举 | ✅ push 含 force-with-lease | +| **checkout** | `checkout(treeish)` | ✅ | +| **commit 对象** | `getCommit(ref)`、`show(ref, path)`、`buffer(ref, path)`、`getObjectDetails` | ✅ | +| **worktree** | `createWorktree`、`deleteWorktree` | ✅ | +| **migrateChanges** | `migrateChanges(sourceRepoPath, {confirmation, deleteFromSource, untracked})` | ⚠️ 源码有,IDEA 对应「Move Changes to Another Changelist/Repo」语义待核实 | + +**事件**:`onDidCommit`、`onDidCheckout`、`state.onDidChange`(状态变更)、`ui.onDidChangeSelection`(provider 选中变化)。来源:git.d.ts `Repository` / `RepositoryState` / `RepositoryUIState`。 + +**InputBox 桥接**:`repository.inputBox`(只暴露 `value` get/set)是原生 `SourceControlInputBox` 的薄包装。来源:api1.ts `ApiInputBox`: +```ts +class ApiInputBox implements InputBox { + #inputBox: SourceControlInputBox; + set value(v) { this.#inputBox.value = v; } + get value() { return this.#inputBox.value; } +} +``` +即:**通过 git API 只能读写原生 inputBox 的 value,无法增强其 UI**——再次印证须自建 Commit 编辑器。 + +### 2.5 可注册的扩展点(API.register*) + +git API 还允许第三方**注入**能力而非仅消费:`registerPostCommitCommandsProvider`、`registerBranchProtectionProvider`、`registerCredentialsProvider`、`registerRemoteSourceProvider`、`registerPushErrorHandler`、`registerSourceControlHistoryItemDetailsProvider`(提交图 hover/头像/链接增强,注意这是「增强原生 Graph」而非「自建 Graph」)。来源:git.d.ts `API`。 + +--- + +## 3. 集成路径对比(决策表) + +| 维度 | A. 注册独立 SCM Provider(包装 git CLI) | **B. 纯消费 vscode.git API + 自建 TreeView/WebviewView(推荐)** | C. 注册 SCM Provider + 复用 vscode.git 数据源 | +|---|---|---|---| +| **git 操作实现** | 自调 `child_process` git(或包装 `git.path`) | **全部复用 `api.getAPI(1)` 的 Repository 方法** | 复用 git API 读数据,但 stage/commit 走自己的 SourceControl | +| **与原生 Source Control 视图关系** | **双胞胎冲突**:活动栏会出现两个 Git provider,用户混淆;`extensionDependencies: ["vscode.git"]` 后两者并存 | **零冲突**:原生 git 视图照常,我们的 UI 在**独立视图容器**(Secondary Side Bar) | 双胞胎冲突(同 A) | +| **多 changelist 表达** | 多 `SourceControlResourceGroup` 近似(语义有损:无 group 级 message/active) | **自建 TreeView,每个 changelist 一个根节点**,可挂独立 message/active 标记,语义无损 | 同 A,有损 | +| **Commit 窗口(模板/校验/Amend/Author)** | 受限于原生 inputBox(单行,无校验,Provider 已删)→ **无法实现** | **自建 WebviewView 编辑器,100% 自由**(多行/模板/Conventional Commits 校验/Amend/Author) | 同 A,无法实现 | +| **Log 提交图** | 原生 Graph 是 proposed,不可稳定用 → 仍需自建 | 自建 TreeView + `Repository.log()`(稳定) | 自建(同 B) | +| **文件右键菜单/状态色** | 原生 SCM 菜单贡献点(强) | 自建 TreeView 的 `view/item/context`(同样强,且更可控) | 原生 SCM 菜单(强) | +| **性能** | 自管 git 进程,需自行处理状态轮询/缓存 | **复用 git 扩展已优化的状态机**(增量 status、diff 缓存、操作队列),性能最优 | 双重状态管理,冗余 | +| **迁移/维护成本** | 高:重写 git 状态机、diff 解析、错误码映射 | **中:需自绘 UI,但 git 逻辑全复用** | 最高:既要管 SCM provider 契约又要桥接 git API | +| **与 AI Agent 未来扩展(提交信息生成/审查)耦合度** | 自管状态,AI 集成需额外适配 | **天然契合**:AI 可直接读 `Repository.state.*Changes` + 调 `commit()` | 冗余 | +| **循证先例** | SVN 扩展(非 git 场景才合理) | **GitLens、vscode-pull-request-github 均为消费 git API 模式** | 无知名先例 | + +### 推荐路径:B(纯消费 vscode.git API + 自建视图) + +**理由(对应 AGENTS.md 准则)**: + +1. **复用驱动(拿来主义)**:git 状态机、diff/blame/log/stash/branch/merge/rebase 全部已由 vscode.git 团队(Lszomoru 等)实现并优化,重造=重复造轮子,违背「Compose over Reinvent」。GitHub 官方的 PR 扩展(microsoft/vscode-pull-request-github)即采用此模式,源码含 `gitExtensionIntegration.ts`。来源:[vscode-pull-request-github 仓库](https://github.com/microsoft/vscode-pull-request-github)。 + +2. **正交分解(Engine/Adapter/Agent/UI 分层)**: + - **Engine**:vscode.git API(不可变底座) + - **Adapter**:我们封装一层 `GitRepositoryAdapter`,把 `Repository` 适配成领域模型(Changelist/FileChange) + - **UI**:自建 TreeView(changes)+ WebviewView(commit dialog)+ TreeView(log/branches/stash) + - **Agent**(未来):AI 层只依赖 Adapter 的领域模型,不碰 vscode API + +3. **单一事实源**:git 真实状态只在 vscode.git 维护一份,我们的 Adapter 是只读视图 + 委托写操作,杜绝 Split-Brain(若走 A/C,两套状态会断裂)。 + +4. **系统完整性(涟漪效应预判)**:路径 A/C 会与原生 git 视图产生「谁是 source of truth」的竞争(用户在原生视图 stage,我们的视图不同步);路径 B 不接管原生视图,只做增量 UI,涟漪最小。 + +5. **规避 proposed API 陷阱**:B 不依赖任何 proposed API(scmHistoryProvider/scmMultiDiffSource/scmProviderOptions/scmInputBoxValueProvider 全避开),可在 Marketplace 无障碍发布。 + +--- + +## 4. changelist 模型映射方案(路径 B 下的落地) + +### 4.1 概念映射 + +| IDEA 概念 | VS Code 落地(路径 B) | 实现 | +|---|---|---| +| Changelist(多组) | 自建 TreeView 的**一级节点** | `vscode.window.createTreeView('sofia.changes', {...})`,每个 changelist 一个 `TreeItem`(collapsible) | +| Active changelist | 一级节点带 `description=active` + 图标徽标;新增文件默认归入此节点 | Adapter 维护 `activeChangelistId`,TreeView 高亮 | +| Changelist 内文件 | 一级节点下的**叶子节点** | `TreeItem` with `resourceUri` + `iconPath`(状态色)+ `description`(M/A/D) | +| 文件状态色 M/A/D/U/R/C | 叶子节点的 `iconPath`(ThemeIcon + ThemeColor)或 `description` 文字 | 复用 git 扩展同款 `gitDecoration.*Foreground` ThemeColor | +| Move changes(跨 changelist 移文件) | 叶子节点右键 `Move to Changelist...` 命令 | Adapter 维护内存 changelist→files 映射;stage/commit 时按 changelist 过滤 `add(paths)` | + +### 4.2 与 git 的语义桥接(关键设计) + +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」。 +- **Default changelist**:即 active changelist,未显式分配的变更自动落入。 + +> 注意:此设计下,changelist 是**纯客户端逻辑分组**,不写 git 元数据(IDEA 的 changelist 也仅存于 `.idea/workspace.xml`,同理)。这与 git 的 stage 是两套正交机制,需在 UI 上明确区分(可提供「stage = 临时索引」「changelist = 持久分组」的认知锚点)。 + +### 4.3 备选(若要借用原生 SCM 视图) + +放弃 TreeView,改为**注册一个自己的 SourceControl + 每个 changelist 一个 ResourceGroup**。代价:无 group 级 message、无 active 概念、与原生 git 视图双胞胎。**不推荐**,仅作为「快速 MVP」降级方案。 + +--- + +## 5. Commit 窗口 UI 落地(路径 B 下的落地) + +### 5.1 容器选择:Secondary Side Bar 的 WebviewView + 自定义视图容器 + +**package.json 贡献**(来源:[viewsContainers 贡献点](https://code.visualstudio.com/api/references/contribution-points#contributes.viewsContainers)): +```json +{ + "contributes": { + "viewsContainers": { + "activitybar": [{ "id": "sofia-git", "title": "SOFIA Git", "icon": "..." }] + }, + "views": { + "sofia-git": [ + { "id": "sofia.changes", "name": "Changes", "type": "tree" }, + { "id": "sofia.commit", "name": "Commit", "type": "webview" }, + { "id": "sofia.log", "name": "Log", "type": "tree" }, + { "id": "sofia.shelf", "name": "Shelf", "type": "tree" }, + { "id": "sofia.stash", "name": "Stash", "type": "tree" } + ] + } + } +} +``` + +> 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 表达 + +两种实现,择一: + +- **方案 1(推荐):平铺视图节点**。上图 `sofia-git` 容器下并列 Changes/Commit/Log/Shelf/Stash 五个 view,用户点击切换(等价标签页)。 +- **方案 2:单 WebviewView 内自绘 Tabs**。一个 `sofia.main` webview 内用前端框架渲染 IDEA 风格 Tab 栏 + 各面板内容。自由度最高但失去原生 a11y/快捷键集成。 + +### 5.3 Commit Message 编辑器(替代原生 inputBox) + +- 用 `WebviewView` 渲染一个**多行 Monaco-like 编辑器**(可用 `