diff --git a/docs/README.md b/docs/README.md index b2cd4be..96d4196 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 责任链设计 + 渐进式引入路线。 ## 协作与规范 diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md index a00565b..5a9c28d 100644 --- a/docs/architecture/engineering-plan.md +++ b/docs/architecture/engineering-plan.md @@ -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**。 --- @@ -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，深色模式高对比）**： @@ -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('vscode.git').activate().getAPI(1)`。 @@ -230,9 +230,9 @@ hyper-git/ ## 7. CI/CD 与发布策略 -- **发布渠道**：双市场（Marketplace + OpenVSX）。**立即**：`ovsx create-namespace ` 并 **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。 @@ -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。 --- @@ -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) diff --git a/docs/milestones/implementation-status.md b/docs/milestones/implementation-status.md index d31d0df..6e889d7 100644 --- a/docs/milestones/implementation-status.md +++ b/docs/milestones/implementation-status.md @@ -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 提交闭环 | @@ -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 图标。 diff --git a/docs/releases/v0.0.10-rc.1.md b/docs/releases/v0.0.10-rc.1.md index f7cf1fd..cde28ce 100644 --- a/docs/releases/v0.0.10-rc.1.md +++ b/docs/releases/v0.0.10-rc.1.md @@ -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 单市场。） --- @@ -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 工作区。 diff --git a/docs/releases/v0.0.10-rc.2.md b/docs/releases/v0.0.10-rc.2.md index c0a4f16..55da067 100644 --- a/docs/releases/v0.0.10-rc.2.md +++ b/docs/releases/v0.0.10-rc.2.md @@ -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 行为不变。 --- @@ -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 工作区。 diff --git a/docs/releases/v0.0.6.md b/docs/releases/v0.0.6.md index 801d835..6800ec3 100644 --- a/docs/releases/v0.0.6.md +++ b/docs/releases/v0.0.6.md @@ -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 **平行共存、零冲突**。 --- @@ -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 工作区。 diff --git a/docs/releases/v0.0.9.md b/docs/releases/v0.0.9.md index 632db23..19f8304 100644 --- a/docs/releases/v0.0.9.md +++ b/docs/releases/v0.0.9.md @@ -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 工作区。 diff --git a/docs/research/04-publishing-cicd.md b/docs/research/04-publishing-cicd.md index 7ff51b5..5c3d03a 100644 --- a/docs/research/04-publishing-cicd.md +++ b/docs/research/04-publishing-cicd.md @@ -3,6 +3,8 @@ > 交付目标:把"提供统一 Git 变更管理与提交工作流"的 VS Code 扩展,从源码可靠、安全、自动化地交付到所有目标编辑器用户(原生 VS Code、Cursor、Windsurf、Gitpod、VSCodium/Code-OSS)。 > 所有事实论断均附 GitHub 路径或官方文档 URL;不确定项标注"待核实"。 +> **决策更新(2026-07-04)**:本项目已将发布策略由「双市场(Marketplace + OpenVSX)」**收敛为 VS Code Marketplace 单市场**——移除 CI 的 OpenVSX 发布步骤与 `OVSX_PAT` 依赖(实践中 OpenVSX 命名空间与凭证未落地,且为降低维护面)。下文 §1.2、§2、§3、§5 及「下一步」中一切涉及 OpenVSX / ovsx 的内容,均保留为当时的循证背景(已被本决策取代);当前发布口径以 **§2.3(已修订)** 为准。 + --- ## 1. 发布前置清单(Manifest + Publisher + 凭证) @@ -69,15 +71,15 @@ - **Cursor 使用 Open VSX registry,而非 VS Code Marketplace**。来源:[Cursor 论坛官方回复](https://forum.cursor.com/t/cursor-marketplace-installs-offers-outdated-version-of-open-vsx-extension-despite-latest-version-being-available-upstream/159718)、[安全研究 mazinahmed.net](https://mazinahmed.net/blog/publishing-malicious-vscode-extensions/)(明确指出 OpenVSX 驱动 Cursor/Windsurf/Kiro 等 AI IDE)、[devclass 报道](https://www.devclass.com/development/2025/04/08/vs-code-extension-marketplace-wars-cursor-users-hit-roadblocks/1629343)。 - 后果:**只**发 Marketplace 时,Cursor/Windsurf 用户**装不到**(除非手动 `.vsix`)。 -### 2.3 决策:**双市场同时发布** +### 2.3 决策(2026-07-04 修订):**VS Code Marketplace 单市场发布** -理由(契合本项目"未来引入 AI Agent 自主代理能力"的受众): -1. **AI 受众主战场在 OpenVSX**:Cursor/Windsurf 用户是 AI 提交/AI 代码审查的核心早期采用者,却只能从 OpenVSX 安装; -2. **Marketplace 是事实主流**:原生 VS Code 基数最大,pre-release/平台包/verified publisher 等特性更完善; -3. **边际成本低**:`ovsx` 与 `vsce` CLI 几乎同构,同一 VSIX 可直接 `ovsx publish`,CI 仅追加一个 step; -4. **抢注风险**:OpenVSX namespace 默认非排他,**务必 `create-namespace` 后立即 claim ownership**([cli/README.md](https://github.com/eclipse/openvsx/blob/master/cli/README.md))。 +> 原方案为「双市场同时发布」(理由见上 §2.1/§2.2 循证背景:AI 受众主战场在 OpenVSX、边际成本低)。实践中因 OpenVSX 命名空间与 `OVSX_PAT` 凭证未落地、且为收敛维护面,**修订为仅发布 VS Code Marketplace**。 -> 已有成熟 Action 一键双发:`HaaLeo/publish-vs-code-extension`(支持 vsce + ovsx,见 [GitHub Marketplace Action](https://github.com/marketplace/actions/publish-vs-code-extension))——符合 AGENTS.md"复用驱动,优先组合而非重复造轮子"。 +当前口径: +1. **单市场**:仅经 `vsce publish` 发布到 VS Code Marketplace(原生 VS Code 用户主战场;`rc` tag 走 `--pre-release` 预发布通道)。 +2. **兜底安装**:每个 `v*` tag 均产出 GitHub Release 并附 `.vsix`,Cursor/Windsurf/VSCodium 等用户可下载后 `Install from VSIX`。 +3. **凭证**:仅需 `VSCE_PAT`(Azure DevOps PAT,scope Marketplace → Manage);由仓库变量 `ENABLE_MARKETPLACE_PUBLISH` 门控。 +4. **未来若重启 OpenVSX**:需先在 open-vsx.org 创建并 claim `ThreeFish-AI` 命名空间、配置有效 `OVSX_PAT`,再于 `publish` job 增回 `ovsx publish` 步骤(§2.1/§2.2 背景分析仍适用)。 --- @@ -302,7 +304,7 @@ OpenVSX 删除策略相对宽松,但为双市场一致,统一遵循"出新版本 ## 下一步最佳行动建议(Next Best Action) 1. **先落地 §3.2 `ci.yml` 的 test+package+artifact 三 job**:验证 3 平台通过率与 `xvfb` 集成,暂不接 publish(零风险)。 -2. **同步创建 Publisher + OpenVSX namespace**:立即 `ovsx create-namespace` 并 **claim ownership**,防止命名空间抢注。 +2. **同步创建 Marketplace Publisher**:在 [Marketplace publisher 管理页](https://marketplace.visualstudio.com/manage/publishers/) 创建 publisher `ThreeFish-AI` 并配置 `VSCE_PAT`(Azure DevOps PAT,scope Marketplace → Manage)。 3. **PAT 治理决策点**:评估是否一步到位上 Entra 托管标识(消除 PAT),还是先用 secret + 短过期 PAT 过渡——决定 publish job 认证实现。 4. **pre-release 路线**:AI Agent 自主代理属高风险新特性,建议首版即建立 `odd minor` pre-release 通道(如 `0.3.x`)吸收早期 Cursor/Windsurf 反馈,稳定后升 `0.4.x` release。 diff --git a/docs/research/README.md b/docs/research/README.md index e1279ab..67f1243 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -9,7 +9,7 @@ | 01 | [Git 功能完备性矩阵](../requirements/idea-feature-matrix.md) | 56 功能点 / 8 组；多 changelist + 行级跨列表归属是 VS Code 原生模型与成熟实现的最大差异 | | 02 | [VS Code SCM 集成路径](./02-vscode-scm-integration.md) | **路径 B**：消费 vscode.git API + 自建 changelist registry + 自绘视图；scmHistoryProvider 等仍 proposed | | 03 | [扩展工程蓝图](./03-extension-blueprint.md) | TS+esbuild+Vitest+test-electron；engine/adapter/agent/ui 正交分层 | -| 04 | [发布 + CI/CD](./04-publishing-cicd.md) | 双市场（Cursor/Windsurf 走 OpenVSX）；CI 三平台 + xvfb；版本不可撤销 | +| 04 | [发布 + CI/CD](./04-publishing-cicd.md) | VS Code Marketplace 单市场；CI 三平台 + xvfb；版本不可撤销 | | 05 | [AI Agent 接缝](./05-ai-agent-seams.md) | ILlmProvider/IPreCommitInspector 现在抽（借鉴 JetBrains CheckinHandler 责任链设计），实现延后 M5 | > 综合方案见 [工程实施方案](../architecture/engineering-plan.md)。