Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
## 调研报告(循证依据)
- [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 矩阵、版本治理、安全。
- [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md) — VS Code Marketplace 发布、CI 矩阵、版本治理、安全。
- [05 · AI Agent 架构预留](./research/05-ai-agent-seams.md) — AI 接缝(ILlmProvider 等)+ 借鉴 JetBrains CheckinHandler 责任链设计 + 渐进式引入路线。

## 协作与规范
Expand Down
16 changes: 8 additions & 8 deletions docs/architecture/engineering-plan.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Hyper Git — VS Code 扩展工程实施方案

> 提供完整的「Git 变更管理 + Commit 提交工作流」(功能完备性参考 IntelliJ IDEA 等成熟实现),并为未来 AI Agent 自主代理预留架构接缝。
> 决策已与用户确认:**路径 B**(消费 `vscode.git` API + 自建 changelist registry + 独立视图容器)、扩展命名 **Hyper Git**、**双市场发布**、**AI 现仅预留接缝 + Null 实现、延后至 M5**。
> 决策已与用户确认:**路径 B**(消费 `vscode.git` API + 自建 changelist registry + 独立视图容器)、扩展命名 **Hyper Git**、**VS Code Marketplace 单市场发布**、**AI 现仅预留接缝 + Null 实现、延后至 M5**。

---

Expand All @@ -28,7 +28,7 @@
| **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 受众主战场 |
| **发布** | VS Code Marketplace 单市场 | 官方市场为唯一渠道;每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装 |
| **AI** | 现仅定义接缝 + Null 实现,实现延后 M5 | YAGNI + 借鉴 JetBrains `CheckinHandler` 责任链语义 |

**架构总览(Mermaid,深色模式高对比)**:
Expand Down Expand Up @@ -148,10 +148,10 @@ hyper-git/
| `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/vsce` | 打包 / 发布 | 官方工具 |
| `@vscode/test-electron` | 集成测试 | 官方唯一推荐 |
| `esbuild-sample` 模板 | 工程骨架零点(`esbuild.js` + scripts) | microsoft/vscode-extension-samples |
| `HaaLeo/publish-vs-code-extension` Action | 一键双市场发布 | GitHub Marketplace |
| `HaaLeo/publish-vs-code-extension` Action | Marketplace 发布 | GitHub Marketplace |

**消费 `vscode.git` API 的声明**:`package.json` 加 `"extensionDependencies": ["vscode.git"]`;TS 类型复制 `git.d.ts` 入仓;运行时 `getExtension<GitExtension>('vscode.git').activate().getAPI(1)`。

Expand Down Expand Up @@ -230,9 +230,9 @@ hyper-git/

## 7. CI/CD 与发布策略

- **发布渠道**:双市场(Marketplace + OpenVSX)。**立即**:`ovsx create-namespace <publisher>` 并 **claim ownership**(OpenVSX namespace 默认非排他,防抢注)
- **发布渠道**:VS Code Marketplace 单市场(`vsce publish`,`ENABLE_MARKETPLACE_PUBLISH` 变量门控,`rc` tag 走 `--pre-release` 预发布通道);每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装
- **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 跑全矩阵(控成本)。
- **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, environment:production 审批门, VSCE_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。
Expand Down Expand Up @@ -268,7 +268,7 @@ hyper-git/

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` 索引。
3. **并行**:将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线,并同步 `.agents/knowledge-map.md` 索引。
4. **提交规范**:按用户偏好,commit 用 `/commit` 命令;PR 基线为 `origin/feature/1.x.x`,不直接推 master。

---
Expand All @@ -289,4 +289,4 @@ hyper-git/
- 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)
- [Publishing Extensions(官方)](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)、[HaaLeo/publish-vs-code-extension](https://github.com/marketplace/actions/publish-vs-code-extension)
8 changes: 4 additions & 4 deletions docs/milestones/implementation-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@

| 里程碑 | 版本 | PR | 交付 | 验收 |
|---|---|---|---|---|
| M0 脚手架+CI | 0.1.0 | [#1](https://github.com/ThreeFish-AI/hyper-git/pull/1) | pnpm+esbuild+TS strict+ESLint9+Vitest+test-electron;正交分层骨架;CI 三平台矩阵+双市场发布;engine 纯逻辑 + AI 接缝预留 | check-types/lint/package/test 全绿 |
| M0 脚手架+CI | 0.1.0 | [#1](https://github.com/ThreeFish-AI/hyper-git/pull/1) | pnpm+esbuild+TS strict+ESLint9+Vitest+test-electron;正交分层骨架;CI 三平台矩阵+Marketplace 发布;engine 纯逻辑 + AI 接缝预留 | check-types/lint/package/test 全绿 |
| 调研资产持久化 | — | [#2](https://github.com/ThreeFish-AI/hyper-git/pull/2) | docs/(IDEA 56 功能矩阵、工程方案、四路调研报告) | — |
| M1 Git Adapter+多 changelist | 0.2.0 | [#3](https://github.com/ThreeFish-AI/hyper-git/pull/3) | GitRepositoryService、ChangelistRegistry(CRUD+持久化)、Changes TreeView(状态色+diff) | 集成:真实仓库变更渲染 |
| M2 Commit 窗口 | 0.3.0 | [#4](https://github.com/ThreeFish-AI/hyper-git/pull/4) | Commit WebviewView(勾选+多行编辑器+Amend/signoff/skipHooks+CC 实时校验)、CommitPipeline(Checkin hook 链)、5 AI 接缝 Null 注入 | 集成:真实 git 提交闭环 |
Expand Down Expand Up @@ -100,10 +100,10 @@

- **单元测试(Vitest,< 1s)**:engine/ 纯逻辑(scm-mapping、changelist-grouper、commit-pipeline、conventional-linter、git-status-map、conventional-check)+ CommitService.executeCommit(mock Repository,7 分支)。共 45 项。
- **集成测试(@vscode/test-electron)**:扩展激活 + 全部命令注册(M1-M4);真实 git 提交闭环(fixture 仓库 add+commit+git log 校验);amend 改写 HEAD。共 3 项。
- **CI(GitHub Actions)**:lint→build→test 矩阵(ubuntu/mac/win + Linux xvfb)→package vsix→artifact;`tag v*` → 双市场发布(Marketplace + OpenVSX,需 secrets)。
- **CI(GitHub Actions)**:lint→build→test 矩阵(ubuntu/mac/win + Linux xvfb)→package vsix→artifact;`tag v*` → Marketplace 发布(需 VSCE_PAT secret,`ENABLE_MARKETPLACE_PUBLISH` 门控)。

## 7. 发布状态

- **当前版本**:0.0.6(首个 MVP 正式版,对外首发;以「Hyper Git - Agentic Git」之名上架 Marketplace / OpenVSX)。
- **当前版本**:0.0.6(首个 MVP 正式版,对外首发;以「Hyper Git - Agentic Git」之名上架 Marketplace)。
- **首发历程**:经若干内部迭代与 `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 图标。
- **发布前置**:publisher 账号(`ThreeFish-AI`)、VSCE_PAT secret、PNG 图标。
3 changes: 1 addition & 2 deletions docs/releases/v0.0.10-rc.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> **预发布(Release Candidate)**,面向下一正式版 `0.0.10`。本版在 [v0.0.9](./v0.0.9.md) 基础上把提交图视图更名为 **Graph** 并逐像素对齐 VS Code 官方 Source Control GRAPH 视图,修复两处交互缺陷(悬浮浮层被侧边栏 iframe 裁剪、活动栏未提交数角标更新不及时),并完成 README 真实性校准与中英双语重构。

> 本版同时是 **VS Code Marketplace 发布链路打通**的验证版:首次以官方预发布模型(`vsce publish --pre-release`)将扩展推送至 Marketplace 预发布通道,与 OpenVSX、GitHub Release 三渠道并发发布。
> 本版同时是 **VS Code Marketplace 发布链路打通**的验证版:首次以官方预发布模型(`vsce publish --pre-release`)将扩展推送至 Marketplace 预发布通道与 GitHub Release。(注:OpenVSX 渠道后续已移除,收敛为 VS Code Marketplace 单市场。)

---

Expand Down Expand Up @@ -57,7 +57,6 @@
## 📦 安装

- **VS Code Marketplace(预发布通道)**:搜索 `Hyper Git - Agentic Git`,在扩展页选择「Switch to Pre-Release Version」安装本 RC。
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
- **手动**:从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.10-rc.1) 下载 `hyper-git-agentic-git-0.0.10.vsix` → 命令面板 `Extensions: Install from VSIX`。

**系统要求**:VS Code ≥ 1.85.0,且启用内置 Git 扩展(`vscode.git`,默认随附)。仅支持本地 git 仓库,不支持虚拟 / Web 工作区。
Expand Down
5 changes: 2 additions & 3 deletions docs/releases/v0.0.10-rc.2.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

> **预发布(Release Candidate)**,面向下一正式版 `0.0.10`。产品内容与 [v0.0.10-rc.1](./v0.0.10-rc.1.md) 一致——将提交图视图更名为 **Graph** 并对齐 VS Code 官方 Source Control GRAPH 视图,修复悬浮浮层被侧边栏 iframe 裁剪、活动栏未提交数角标更新不及时两处缺陷,并完成 README 真实性校准与中英双语重构。

> **为何是 rc.2**:rc.1 因发布流水线的**预发布打包缺陷**——`package` job 未以 `--pre-release` 打包,致 `publish` job 的 Marketplace 步骤报 `Cannot use '--pre-release' flag with a package that was not packaged as pre-release` 而失败、OpenVSX 步骤随之被跳过,最终仅 GitHub Release 成功。rc.2 修复该缺陷(打包端与发布端 `--pre-release` 对齐,同一枚预发布 VSIX 贯穿三渠道)后重新走通 **GitHub Release + VS Code Marketplace(预发布通道)+ OpenVSX** 三渠道。详见 [issue #11](../.agents/issue.md)。
> **为何是 rc.2**:rc.1 因发布流水线的**预发布打包缺陷**——`package` job 未以 `--pre-release` 打包,致 `publish` job 的 Marketplace 步骤报 `Cannot use '--pre-release' flag with a package that was not packaged as pre-release` 而失败、OpenVSX 步骤随之被跳过,最终仅 GitHub Release 成功。rc.2 修复该缺陷(打包端与发布端 `--pre-release` 对齐,同一枚预发布 VSIX 贯穿打包与发布)后重新走通 **GitHub Release + VS Code Marketplace(预发布通道)**。详见 [issue #11](../.agents/issue.md)。(注:OpenVSX 渠道后续已移除,收敛为 VS Code Marketplace 单市场。)

---

## 🔧 本次修复(rc.1 → rc.2)

- **CI `package` job 对 rc tag 以 `--pre-release` 打包**:VS Code 要求以预发布方式发布的 VSIX 必须在**打包时**即带 `--pre-release` 标记(写入 manifest),否则 `vsce publish --pre-release` 拒绝发布。`package` 步骤改为与 `publish` / OpenVSX 同款 `PRE_FLAG` 判定(tag 名含 `rc` 即追加 `--pre-release`),保证单一枚预发布 VSIX 贯穿三渠道、零重复打包;正式版 tag 与分支 / PR CI 行为不变。
- **CI `package` job 对 rc tag 以 `--pre-release` 打包**:VS Code 要求以预发布方式发布的 VSIX 必须在**打包时**即带 `--pre-release` 标记(写入 manifest),否则 `vsce publish --pre-release` 拒绝发布。`package` 步骤改为与 `publish` 同款 `PRE_FLAG` 判定(tag 名含 `rc` 即追加 `--pre-release`),保证单一枚预发布 VSIX 贯穿打包与发布、零重复打包;正式版 tag 与分支 / PR CI 行为不变。

---

Expand Down Expand Up @@ -63,7 +63,6 @@
## 📦 安装

- **VS Code Marketplace(预发布通道)**:搜索 `Hyper Git - Agentic Git`,在扩展页选择「Switch to Pre-Release Version」安装本 RC。
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
- **手动**:从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.10-rc.2) 下载 `hyper-git-agentic-git-0.0.10.vsix` → 命令面板 `Extensions: Install from VSIX`。

**系统要求**:VS Code ≥ 1.85.0,且启用内置 Git 扩展(`vscode.git`,默认随附)。仅支持本地 git 仓库,不支持虚拟 / Web 工作区。
Expand Down
3 changes: 1 addition & 2 deletions docs/releases/v0.0.6.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> 为 VS Code 带来统一的 **Git 变更管理** 与 **提交工作流**,并为未来 AI Agent 自主代理预留架构接缝。

这是本扩展的**首个对外正式版本**,在 VS Code Marketplace / OpenVSX 上以 **「Hyper Git - Agentic Git」** 之名发布。它把开发者高频依赖、却在 VS Code 原生 Source Control 中长期缺失的 Git 工作流**一次性补齐**:多 Changelist 变更组织、自绘提交面板、可视化提交图、Shelf、行级提交,并与原生 Source Control **平行共存、零冲突**。
这是本扩展的**首个对外正式版本**,在 VS Code Marketplace 上以 **「Hyper Git - Agentic Git」** 之名发布。它把开发者高频依赖、却在 VS Code 原生 Source Control 中长期缺失的 Git 工作流**一次性补齐**:多 Changelist 变更组织、自绘提交面板、可视化提交图、Shelf、行级提交,并与原生 Source Control **平行共存、零冲突**。

---

Expand Down Expand Up @@ -83,7 +83,6 @@ Cherry-Pick、Revert、Reset HEAD(soft / mixed / hard / keep)、交互式 Re
## 📦 安装

- **手动安装(当前推荐)**:从 [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 工作区。
Expand Down
3 changes: 1 addition & 2 deletions docs/releases/v0.0.9.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,7 @@ Commit 视图活动 Changelist 文件列表、Log 视图选中提交的「Change

## 📦 安装

- **VS Code Marketplace**:由 CI `ENABLE_MARKETPLACE_PUBLISH` 变量门控(默认关闭);未开启时以下渠道均可安装。
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
- **VS Code Marketplace**:由 CI `ENABLE_MARKETPLACE_PUBLISH` 变量门控(默认关闭);未开启时可用以下方式安装。
- **手动**:从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.9) 下载 `hyper-git-agentic-git-0.0.9.vsix` → 命令面板 `Extensions: Install from VSIX`。

**系统要求**:VS Code ≥ 1.85.0,且启用内置 Git 扩展(`vscode.git`,默认随附)。仅支持本地 git 仓库,不支持虚拟 / Web 工作区。
Expand Down
Loading