Skip to content

Commit c211365

Browse files
committed
docs: 文档口径同步为 VS Code Marketplace 单市场(移除 OpenVSX 记述);
- 前瞻策略文档改为单市场口径:文档中心与调研索引(docs/README、research/README)、工程蓝图(engineering-plan)、实施状态(implementation-status); - 循证报告 04-publishing-cicd 加「决策更新(2026-07-04)」注记:保留 §2 双市场分析为当时循证背景(已被决策取代),§2.3 决策改为 Marketplace 单市场,「下一步」action item 改为创建 Marketplace publisher; - 历史发布说明(v0.0.6 / v0.0.9 / v0.0.10-rc.1 / rc.2)最小订正:移除从未成立的 OpenVSX 安装指引;修正 rc.2「走通三渠道」失实表述(OpenVSX 实际因令牌无效未发布)为两渠道; - 与已移除 OpenVSX 的 ci.yml 及 README 双语保持一致。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
1 parent a09a816 commit c211365

9 files changed

Lines changed: 29 additions & 31 deletions

File tree

docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
## 调研报告(循证依据)
1717
- [02 · VS Code SCM API 与 vscode.git 集成路径](./research/02-vscode-scm-integration.md) — 路径 B 决策依据、SCM 稳定/proposed API 边界、changelist 模型映射。
1818
- [03 · VS Code 扩展工程蓝图](./research/03-extension-blueprint.md) — 技术栈决策、工程骨架、IDEA→VS Code UI 表面映射表。
19-
- [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md)双市场(Marketplace + OpenVSX)、CI 矩阵、版本治理、安全。
19+
- [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md)VS Code Marketplace 发布、CI 矩阵、版本治理、安全。
2020
- [05 · AI Agent 架构预留](./research/05-ai-agent-seams.md) — AI 接缝(ILlmProvider 等)+ 借鉴 JetBrains CheckinHandler 责任链设计 + 渐进式引入路线。
2121

2222
## 协作与规范

docs/architecture/engineering-plan.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Hyper Git — VS Code 扩展工程实施方案
22

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

@@ -28,7 +28,7 @@
2828
| **Commit 编辑器** | WebviewView 自绘(多行 / 模板 / Conventional Commits 校验 / Amend / Author / sign-off) | 原生 `SourceControlInputBox``value` 字段,Provider 已删除 |
2929
| **Log 提交图** | Webview 自绘 SVG graph + 消费 `Repository.log()` | `scmHistoryProvider` 为 proposed,上架不可用 |
3030
| **Diff 预览** | 复用 `vscode.diff` + `api.toGitUri(uri,'HEAD')`(零成本) | Track2 §5.5 |
31-
| **发布** | 双市场(Marketplace + OpenVSX) | Cursor/Windsurf 走 OpenVSX;AI 受众主战场 |
31+
| **发布** | VS Code Marketplace 单市场 | 官方市场为唯一渠道;每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装 |
3232
| **AI** | 现仅定义接缝 + Null 实现,实现延后 M5 | YAGNI + 借鉴 JetBrains `CheckinHandler` 责任链语义 |
3333

3434
**架构总览(Mermaid,深色模式高对比)**
@@ -148,10 +148,10 @@ hyper-git/
148148
| `api.toGitUri(uri, ref)` | 构造任意 ref 版本的资源 Uri(diff 原始端) | 同上 |
149149
| `vscode.commands.executeCommand('vscode.diff', left, right, title)` | 文件 diff 预览(零成本,不自绘 diff) | VS Code 稳定 API |
150150
| `ThemeColor('gitDecoration.modifiedResourceForeground')`| 文件状态色(深色模式一致) | 复用原生 token |
151-
| `@vscode/vsce` / `ovsx` | 打包 / 发布 | 官方工具 |
151+
| `@vscode/vsce` | 打包 / 发布 | 官方工具 |
152152
| `@vscode/test-electron` | 集成测试 | 官方唯一推荐 |
153153
| `esbuild-sample` 模板 | 工程骨架零点(`esbuild.js` + scripts) | microsoft/vscode-extension-samples |
154-
| `HaaLeo/publish-vs-code-extension` Action | 一键双市场发布 | GitHub Marketplace |
154+
| `HaaLeo/publish-vs-code-extension` Action | Marketplace 发布 | GitHub Marketplace |
155155

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

@@ -230,9 +230,9 @@ hyper-git/
230230

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

233-
- **发布渠道**双市场(Marketplace + OpenVSX)。**立即**`ovsx create-namespace <publisher>`**claim ownership**(OpenVSX namespace 默认非排他,防抢注)
233+
- **发布渠道**VS Code Marketplace 单市场(`vsce publish``ENABLE_MARKETPLACE_PUBLISH` 变量门控,`rc` tag 走 `--pre-release` 预发布通道);每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装
234234
- **publisher / 扩展 id**:扩展显示名 **Hyper Git**,id `hyper-git`;publisher 建议与 git owner 一致取 `threefish-ai`**待你最终确认 publisher id**,创建后不可改)。
235-
- **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 跑全矩阵(控成本)。
235+
- **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 跑全矩阵(控成本)。
236236
- **版本治理**:Marketplace 版本不可撤销 → **快速补丁版本为唯一回滚范式**;pre-release 用奇数 minor 吸收 M5 AI 等高风险特性;CHANGELOG 用 Keep a Changelog 格式。
237237
- **安全**:PAT 短过期(90d) + 最小 scope + 仅存 GitHub encrypted secret;action pin 到完整 commit SHA;启用 Dependabot + CodeQL + `pnpm audit`;AI/遥测默认关闭。
238238
- **engines.vscode**:M0-M4 锁 `^1.85.0``@types/vscode:1.85.0` 严格对齐,让 tsc 拦截越界 API);M5 评估上调以支持 LM/Chat API。
@@ -268,7 +268,7 @@ hyper-git/
268268

269269
1. **建工作分支**(基于 `origin/feature/1.x.x`),创建 `package.json` + esbuild 骨架(复制官方 `esbuild-sample`),落地 M0。
270270
2. **PoC 验证两个关键风险点**:(a) `extensionDependencies:["vscode.git"]` + `getAPI(1)` 拿到 `Repository``workingTreeChanges`;(b) WebviewView Commit 编辑器 `postMessage → Repository.commit()`。两项跑通即消除主要技术不确定性。
271-
3. **并行**`ovsx create-namespace` + claim ownership(防抢注);将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线,并同步 `.agents/knowledge-map.md` 索引。
271+
3. **并行**:将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线,并同步 `.agents/knowledge-map.md` 索引。
272272
4. **提交规范**:按用户偏好,commit 用 `/commit` 命令;PR 基线为 `origin/feature/1.x.x`,不直接推 master。
273273

274274
---
@@ -289,4 +289,4 @@ hyper-git/
289289
- 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)
290290

291291
**发布生态**
292-
- [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)
292+
- [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)

docs/milestones/implementation-status.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
| 里程碑 | 版本 | PR | 交付 | 验收 |
2222
|---|---|---|---|---|
23-
| 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 全绿 |
23+
| 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 全绿 |
2424
| 调研资产持久化 || [#2](https://github.com/ThreeFish-AI/hyper-git/pull/2) | docs/(IDEA 56 功能矩阵、工程方案、四路调研报告) ||
2525
| M1 Git Adapter+多 changelist | 0.2.0 | [#3](https://github.com/ThreeFish-AI/hyper-git/pull/3) | GitRepositoryService、ChangelistRegistry(CRUD+持久化)、Changes TreeView(状态色+diff) | 集成:真实仓库变更渲染 |
2626
| 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 提交闭环 |
@@ -100,10 +100,10 @@
100100

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

105105
## 7. 发布状态
106106

107-
- **当前版本**:0.0.6(首个 MVP 正式版,对外首发;以「Hyper Git - Agentic Git」之名上架 Marketplace / OpenVSX)。
107+
- **当前版本**:0.0.6(首个 MVP 正式版,对外首发;以「Hyper Git - Agentic Git」之名上架 Marketplace)。
108108
- **首发历程**:经若干内部迭代与 `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 体现。
109-
- **发布前置**:publisher 账号(`threefish-ai`)、VSCE_PAT / OVSX_PAT secrets、PNG 图标。
109+
- **发布前置**:publisher 账号(`ThreeFish-AI`)、VSCE_PAT secret、PNG 图标。

docs/releases/v0.0.10-rc.1.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> **预发布(Release Candidate)**,面向下一正式版 `0.0.10`。本版在 [v0.0.9](./v0.0.9.md) 基础上把提交图视图更名为 **Graph** 并逐像素对齐 VS Code 官方 Source Control GRAPH 视图,修复两处交互缺陷(悬浮浮层被侧边栏 iframe 裁剪、活动栏未提交数角标更新不及时),并完成 README 真实性校准与中英双语重构。
44
5-
> 本版同时是 **VS Code Marketplace 发布链路打通**的验证版:首次以官方预发布模型(`vsce publish --pre-release`)将扩展推送至 Marketplace 预发布通道,与 OpenVSX、GitHub Release 三渠道并发发布。
5+
> 本版同时是 **VS Code Marketplace 发布链路打通**的验证版:首次以官方预发布模型(`vsce publish --pre-release`)将扩展推送至 Marketplace 预发布通道与 GitHub Release。(注:OpenVSX 渠道后续已移除,收敛为 VS Code Marketplace 单市场。)
66
77
---
88

@@ -57,7 +57,6 @@
5757
## 📦 安装
5858

5959
- **VS Code Marketplace(预发布通道)**:搜索 `Hyper Git - Agentic Git`,在扩展页选择「Switch to Pre-Release Version」安装本 RC。
60-
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
6160
- **手动**:从 [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`
6261

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

docs/releases/v0.0.10-rc.2.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

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

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

11-
- **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 行为不变。
11+
- **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 行为不变。
1212

1313
---
1414

@@ -63,7 +63,6 @@
6363
## 📦 安装
6464

6565
- **VS Code Marketplace(预发布通道)**:搜索 `Hyper Git - Agentic Git`,在扩展页选择「Switch to Pre-Release Version」安装本 RC。
66-
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
6766
- **手动**:从 [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`
6867

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

docs/releases/v0.0.6.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> 为 VS Code 带来统一的 **Git 变更管理****提交工作流**,并为未来 AI Agent 自主代理预留架构接缝。
44
5-
这是本扩展的**首个对外正式版本**,在 VS Code Marketplace / OpenVSX 上以 **「Hyper Git - Agentic Git」** 之名发布。它把开发者高频依赖、却在 VS Code 原生 Source Control 中长期缺失的 Git 工作流**一次性补齐**:多 Changelist 变更组织、自绘提交面板、可视化提交图、Shelf、行级提交,并与原生 Source Control **平行共存、零冲突**
5+
这是本扩展的**首个对外正式版本**,在 VS Code Marketplace 上以 **「Hyper Git - Agentic Git」** 之名发布。它把开发者高频依赖、却在 VS Code 原生 Source Control 中长期缺失的 Git 工作流**一次性补齐**:多 Changelist 变更组织、自绘提交面板、可视化提交图、Shelf、行级提交,并与原生 Source Control **平行共存、零冲突**
66

77
---
88

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

8585
- **手动安装(当前推荐)**:从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `hyper-git-agentic-git-0.0.6.vsix` → 命令面板执行 `Extensions: Install from VSIX`
86-
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git`
8786
- **VS Code Marketplace**:搜索 `Hyper Git - Agentic Git`(发布上线后可用)。
8887

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

docs/releases/v0.0.9.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,7 @@ Commit 视图活动 Changelist 文件列表、Log 视图选中提交的「Change
8484

8585
## 📦 安装
8686

87-
- **VS Code Marketplace**:由 CI `ENABLE_MARKETPLACE_PUBLISH` 变量门控(默认关闭);未开启时以下渠道均可安装。
88-
- **OpenVSX**(Cursor / Windsurf / Gitpod / VSCodium):搜索 `Hyper Git - Agentic Git` 安装。
87+
- **VS Code Marketplace**:由 CI `ENABLE_MARKETPLACE_PUBLISH` 变量门控(默认关闭);未开启时可用以下方式安装。
8988
- **手动**:从 [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`
9089

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

0 commit comments

Comments
 (0)