Task Master VS Code 扩展的 CI/CD 发布流水线：基于 Changesets 的自动化版本管理与双注册表发布

Task Master VS Code 扩展的 CI/CD 发布流水线基于 Changesets 的自动化版本管理与双注册表发布【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master本篇文章以 claude-task-master 仓库中 extension-CI-setup.md 为骨架系统讲解 Task Mastertaskr / Taskmaster AIVS Code 扩展的持续集成与持续发布方案从extension-ci.yml的代码质量门禁到基于 Changesets 的版本自动管理与extension-release.yml的双注册表发布。读者读完可以完整复现这套「改代码 → 建 changeset → 合并 → 自动打版本 → 自动发布」的工程化流程并理解 3 文件打包系统package.json/package.publish.json/package.mjs在其中的关键作用。一、流水线总览两道关卡各司其职Task Master 扩展的 CI/CD 由两个 GitHub Actions 工作流构成分工明确CI 负责「改得对不对」Release 负责「发得顺不顺」。1. Extension CIextension-ci.yml——持续集成门禁实际工作流位于 .github/workflows/extension-ci.yml触发条件与文档描述一致Push 到main或next分支且仅当扩展相关文件发生变化时paths过滤apps/extension/**与工作流自身Pull Request 指向main或next同样带路径过滤。该工作流包含三个 Jobsetup→typecheck/build职责链如下阶段具体步骤对应本地命令环境准备actions/checkoutv4fetch-depth: 0 Node 20 node_modules缓存key 基于package-lock.json哈希缓存未命中时回退npm cinpm ci类型检查在apps/extension下执行 TypeScript 编译检查npm run typecheck构建使用 esbuild 与 Tailwind 产出dist/产物npm run build打包生成vsix-build/干净目录并同步版本npm run package内容校验检查vsix-build/、vsix-build/dist/目录结构与package.json是否存在见工作流Verify Package Contents步骤试打包在vsix-build/内执行npx vsce package --no-dependencies验证 VSIX 可正常产出npx vsce package --no-dependencies产物上传用actions/upload-artifactv4上传*.vsix与dist/保留 30 天—从源码结构看CI 的关键设计是「在 CI 中完整复刻一次发布前置动作」先npm run build再npm run package最后真正执行一次vsce package这样任何打包配置错误如package.publish.json缺字段、图标路径缺失都会在 PR 阶段暴露而不是等到发布时才发现。2. Extension Releaseextension-release.yml——发布执行文档中描述的version.ymlpush 到main后检测 changeset 并创建 Version Packages PR在当前仓库中对应为extension-release.yml实际位于 .github/workflows/extension-release.yml。需要指出当前仓库代码中的触发方式与文档描述存在差异——实际工作流由Git tagextension*触发而非 push 到main它也没有创建 Version Packages PR 的步骤版本提升与 tag 创建由仓库根package.json中的changeset脚本链见下文「版本管理」一节负责。extension-release.yml的执行流程监听extension*tag 推送on.push.tags设置concurrency防止并发发布冲突permissions.contents: write在extension-release环境上依次执行npm ci→npm run typecheck→npm run build→npm run package在vsix-build/内创建 VSIX 并定位文件名发布到 VS Code Marketplacenpx vsce publish --packagePath vsix使用 secretVSCE_PAT发布到 Open VSX Registry全局安装ovsx后ovsx publish vsix使用 secretOVSX_PAT上传发布产物保留 90 天notify-successJob 在成功后打印发布摘要Marketplace / Open VSX / GitHub release。二、Changeset 工作流如何为扩展打一个「发布凭证」Changesetschangesets/cli是本方案的核心每次代码变更附带一个描述文件changeset合并后由工具自动汇总出版本与 CHANGELOG。根目录 package.json 中已经内置了相关脚本scripts: { changeset: changeset, changeset:validate: node .github/scripts/validate-changesets.mjs, version: changeset version node ./.github/scripts/sync-manifest-version.mjs npm i --package-lock-only, publish-packages: turbo run build lint test changeset version changeset publish }创建变更的标准动作当修改扩展代码时按以下步骤操作文档原文流程与仓库脚本完全对应# 1. 从仓库根目录创建 changeset npx changeset add选择包提示时选择扩展包。注意文档中提到的包名taskr-kanban是历史命名当前仓库apps/extension/package.publish.json中的发布名为task-master-hamsterapps/extension目录下的package.json名为extension为私有开发包。创建 changeset 时请以实际出现的包名为准。选择版本类型patchBug 修复、小改动minor向后兼容的新功能major破坏性变更。撰写摘要面向用户描述变更内容。将 changeset 文件与代码改动一起提交推送到功能分支并创建 PR。自动发布流程期望闭环带 changeset 的 PR 合入main版本工作流检测到 changeset汇总生成版本变更Version PR人工评审并合并 Version PR触发自动发布构建扩展 → 创建并测试 VSIX → 发布到两个注册表 → 打 git tag → 自动更新 CHANGELOG。事实说明当前仓库中未发现.changeset/目录find 结果为空说明 changeset 文件属于按需生成、随 PR 提交的临时产物而「Version PR」环节在当前extension-release.yml中由 tag 触发替代。若你希望完全复刻文档中的 Version PR 流程需要自行补充基于changeset version的 PR 创建工作流如 changesets action并让version脚本产出版本提交后推送extensionversiontag。三、所需 Secrets发布的两个「钥匙」自动化发布依赖三个 GitHub repository secretVSCE_PATVS Code Marketplace 个人访问令牌登录 Azure DevOpsMicrosoft 账号创建 Personal Access TokenName如 VS Code Extension PublishingOrganizationAll accessible organizationsExpiration自定义建议 1 年注意到期前更换Scopes自定义定义 →Marketplace→Manage复制令牌并添加到仓库 Secrets名为VSCE_PAT。在 extension-release.yml 中它被注入vsce publish步骤的VSCE_PAT环境变量。OVSX_PATOpen VSX Registry 访问令牌登录 Open VSX Registry用 GitHub 账号进入 User Settings 的 Tokens 页面创建新 Access TokenDescription 任意Scopes 保持默认全量权限复制并添加到仓库 Secrets名为OVSX_PAT。该令牌供ovsx publish使用。GITHUB_TOKEN自动提供GitHub Actions 自动注入无需配置用于 checkout 与产物上传等常规操作。四、版本管理关键字段同步的「自动」与「手动」Changeset 驱动的版本机制无需手动改版本号changeset version依据 changeset 类型patch/minor/major自动提升语义化版本CHANGELOG 自动生成版本脚本会汇总各 changeset 描述Git tagging 由自动化完成配合 tag 触发的工作流extension*实现发布冲突预防扩展与主包task-master-ai版本相互独立各自演进。Critical Fields Sync只有一个字段自动同步文档明确强调打包系统在package.json开发用与package.publish.json发布用之间只有version是自动同步的其余字段必须人工保持一致{ version: 1.0.2, // ✅ AUTO-SYNCED由 package.mjs 自动同步 publisher: Hamster, // ⚠️ 必须人工一致 displayName: Taskmaster AI, // ⚠️ 必须人工一致 description: ..., // ⚠️ 必须人工一致 engines: { vscode: ^1.93.0 }, // ⚠️ 必须人工一致 categories: [...], // ⚠️ 必须人工一致 contributes: { ... } // ⚠️ 必须人工一致 }对照当前仓库 apps/extension/package.publish.jsonversion为0.25.3engines.vscode为^1.93.0publisher为Hamster——这些是发布包真正生效的字段开发侧 apps/extension/package.json 则额外包含构建脚本与开发依赖esbuild、Tailwind、React 19、vscode/vsce等。五、监控构建与发布状态CI 状态解读绿色 ✅扩展构建与测试全部通过红色 ❌构建/测试失败需检查 Actions 日志黄色 部分成功部分 Job 存在告警。发布状态解读Version PR Created检测到 changeset评审合并后即可发布No Version PR无 changeset无待发布内容Version PR Merged / Tag Pushed触发自动发布流程当前仓库为extension*tag 推送。失败排查速查Published 扩展已上线 VS Code Marketplace 与 Open VSXSkipped ℹ️无 changeset 或无新 tag无需发布Failed ❌多为 Secrets 缺失或构建问题见下一节。ArtifactsCI 工作流测试结果、构建产物与 VSIX 包保留 30 天Release 工作流最终 VSIX 与dist/保留 90 天可直接下载安装验证。六、3 文件打包系统CI 背后的工程基石文档强调「CI 工作流遵循 3 文件打包系统」其落地实现就是 apps/extension/package.mjs。该脚本是npm run package的执行体理解它才能真正看懂 CI 的每一步文件角色package.json开发期使用依赖、脚本、调试配置package.publish.json发布期使用干净的 Marketplace 元数据name、displayName、contributes、keywords 等package.mjs构建脚本组装vsix-build/干净目录并同步版本.changeset/版本管理跨包自动维护版本与 CHANGELOGpackage.mjs 的核心逻辑从源码结构看先构建依次执行npm run build:js与npm run build:css对应 apps/extension/package.json 中的 esbuild 与 Tailwind 命令清空并重建vsix-build/fs.emptyDirSync保证发布目录无历史残留只复制必要产物从dist/仅复制extension.js、index.js、index.css、sidebar.js显式排除.mapsource map 文件避免泄露源码映射复制附加文件README.md、CHANGELOG.md、AGENTS.md存在才复制版本同步读取开发版package.json的version写入发布包。亮点是 RC 版本转换逻辑若版本形如1.0.0-rc.3会自动映射为1.0.3将 RC 序号累加到 patch 位以规避 VS Code Marketplace 对预发布版本号的限制并回写package.publish.json保持同步组装最终package.json将同步后的package.publish.json复制为vsix-build/package.json搬运收尾文件.vscodeignore、LICENSE、assets/目录输出打包指引提示在vsix-build/内执行npx vsce package --no-dependencies产物形如vsix-build/task-master-version.vsix。这也解释了 Troubleshooting 中「Packaging Failures」的检查项vsix-build结构不对、package.publish.json缺repository字段都会在 CI 的Verify Package Contents与试打包步骤中暴露。七、故障排查清单Troubleshooting现象检查项解决方向没有生成 Version PR.changeset/下是否有 changeset 文件包名引用是否正确改动是否推送到mainnpx changeset add重新创建Version PR 不发布PR 是否真正 merged而非仅关闭VSCE_PAT/OVSX_PAT是否已配置工作流日志有无构建失败重跑工作流或修正 SecretVSCE_PATis not setSecret 是否添加令牌是否过期是否有 Marketplace → Manage 权限重新生成令牌并更新 SecretOVSX_PATis not setSecret 是否添加令牌是否过期是否用 GitHub 账号登录 Open VSX重新生成令牌并更新 Secret构建失败本地能否编译cd apps/extension npm run build测试是否通过npm run testTypeScript 检查npm run typecheck修复代码后在本地复现打包失败本地npm run package是否干净产出vsix-build结构是否正确package.publish.json的repository字段是否齐全修正元数据后重跑Changeset 问题包名是否引用正确当前为task-master-hamsterMarkdown 格式是否规范是否与既有 changeset 冲突修正后重新提交八、双注册表发布一次构建覆盖全编辑器生态发布流水线会同时将扩展推送到两个注册表VS Code Marketplace面向官方 VS Code 用户使用VSCE_PATOpen VSX Registry面向Cursor、Windsurf、VSCodium、Gitpod、Eclipse Theia等兼容编辑器使用OVSX_PAT。由于两者共用同一个vsix-build产物一次vsce package产出 VSIX再分别vsce publish与ovsx publish因此版本一致、行为一致且任一注册表失败都不影响另一个两个步骤相互独立。九、这套自动化的收益总结✅自动化版本管理无需手动 bump 版本号✅自动生成 CHANGELOG发布说明准确、可追溯✅语义化版本强制通过 changeset 类型约束✅Git tagging 自动化为每次扩展发布留下可回滚的锚点✅版本冲突预防扩展版本与主包版本清晰隔离、独立演进✅可评审的发布流程版本变更以 PR 形式接受人工把关✅可回滚能力tag 与 CHANGELOG 完整记录每次发布出问题可快速 revert。延伸阅读关联文档extension-CI-setup.md、extension-development-guide.md工作流源码extension-ci.yml、extension-release.yml打包实现package.mjs、package.json、package.publish.json扩展入口extension.ts、index.ts【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考