企业官网建设流程全解析

claude-task-master VS Code 扩展开发指南：三文件打包体系、构建流程与自动化发布实战

【免费下载链接】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 仓库中 VS Code 扩展（TaskMaster Kanban）的工程化实践：它如何通过package.json、package.publish.json、package.mjs构成的三文件打包体系，在开发与发布之间建立干净隔离，从而规避vsce package的依赖冲突问题。读完本文，你将掌握该扩展的本地开发、热重载调试、生产打包、版本同步、Changesets 自动化发布与故障排查的完整闭环，并理解其背后的源码实现细节。

为什么需要"三文件打包体系"

VS Code 扩展发布到 Marketplace 时，官方工具vsce package会读取package.json中的dependencies与devDependencies进行依赖校验。如果发布包中残留了仅为本地构建服务的开发依赖，vsce package就会因"缺少依赖"而失败，或者把无关文件一并打入 VSIX。

本仓库的扩展位于 apps/extension，其目录结构采用一套刻意设计的布局来规避该问题：

apps/extension/ ├── package.json # 开发配置（含全部构建工具与脚本） ├── package.publish.json # 干净的发布配置（无 devDependencies） ├── package.mjs # 打包构建脚本 ├── .vscodeignore # 从扩展包中排除的文件清单 └── vsix-build/ # 生成的干净发布目录

这一设计的核心思想是：开发与发布使用两套独立的 manifest，由package.mjs在打包时负责组装与版本同步。下面逐一拆解三个文件的分工。

文件职责剖析：开发配置、发布配置与构建脚本

package.json：面向本地开发的完整环境

apps/extension/package.json 承担开发期的一切工作：

• 携带全部devDependencies：包括esbuild（构建器）、@vscode/vsce（打包工具）、react/react-dom/tailwindcss（webview 前端栈）、@modelcontextprotocol/sdk（MCP 客户端）、typescript等；
• 提供开发脚本：build、watch、lint、typecheck、package等，具体见下文"开发工作流"；
• 开发期包名："name": "extension"，"private": true，不会被误发布；
• 注册 VS Code 贡献点：activitybar 视图容器taskmaster、webview 视图taskmaster.welcome、命令tm.showKanbanBoard/tm.checkConnection/tm.reconnect/tm.openSettings，以及完整的taskmaster.*配置项（MCP 连接、UI 显示、性能与调试四大类）。

这里有一个值得注意的细节：开发版 package.json 中taskmaster.mcp.command的默认值是"node"、args为空数组，意指向内置的 bundled MCP server；而发布版 package.publish.json 中默认值是"npx"、args为["-y", "task-master-ai"]，指向远程安装的 npm 包。这是两套配置"各司其职"的典型体现。

package.publish.json：面向 Marketplace 的干净分发版

apps/extension/package.publish.json 是最终进入 VSIX 的 manifest：

• 不包含任何devDependencies，从根本上避免vsce package的依赖解析冲突；
• 携带发布元数据：keywords（kanban、task management、mcp、model context protocol 等 30 余个检索词）、repository、categories（AI、Visualization、Education、Other）；
• 激活事件与入口：activationEvents为["onStartupFinished", "workspaceContains:.taskmaster/**"]，main指向./dist/extension.js——这与ConfigService读取工作区.taskmaster/config.json的行为相呼应（见 apps/extension/src/services/config-service.ts）；
• VS Code 引擎约束：engines.vscode为^1.93.0。

package.mjs：打包编排脚本

apps/extension/package.mjs 是连接开发与发布的枢纽，其执行流程与文档描述一致，并额外包含一个关键细节——RC 版本号的 Marketplace 转换：

1. 依次执行npm run build:js与npm run build:css完成构建；
2. 清空并重建vsix-build/目录；
3. 从dist/仅拷贝extension.js、index.js、index.css、sidebar.js（显式排除.map源映射文件），再补充README.md、CHANGELOG.md、AGENTS.md、LICENSE、.vscodeignore与assets/；
4. 版本同步：若开发版版本号形如0.26.0-rc.0，则按rc.N递增 patch 得到唯一版本（如0.26.0-rc.1→0.26.1），这是因为 VS Code Marketplace 不允许重复版本号，RC 迭代必须映射为递增的正式版本；随后把最终版本写回package.publish.json并拷贝为vsix-build/package.json；
5. 输出提示：cd vsix-build && npx vsce package --no-dependencies。

从构建器一侧看，apps/extension/esbuild.js 使用 esbuild 的 context 并发构建三个入口：扩展主进程（src/extension.ts，CJS、external: ['vscode']）、webview（src/webview/index.tsx，IIFE、jsx: 'automatic'）与 sidebar（src/webview/sidebar.tsx）；生产模式下会drop: ['debugger']并以pure剔除console.log/debug/trace，同时把react/react-dom别名解析到 monorepo 根node_modules，避免 webview 内出现多份 React 实例。

本地开发工作流：从安装依赖到 F5 调试

常用命令

在 apps/extension/package.json 的scripts中定义了完整的开发命令集：

# 安装依赖（在仓库根目录执行 npm install 后进入 apps/extension） npm install # 开发模式：JavaScript 与 CSS 同时热重载监听 npm run watch # 仅构建 JavaScript（esbuild，见 esbuild.js） npm run build:js # 仅构建 CSS（Tailwind CLI 压缩 dist/index.css） npm run build:css # 完整生产构建（build:js + build:css） npm run build # 类型检查（tsc --noEmit，tsconfig.json） npm run typecheck # Lint 检查 npm run lint

在 VS Code 中调试

1. 在 VS Code 中打开该扩展目录，按F5启动 Extension Development Host（扩展开发宿主窗口）；
2. 在宿主窗口中验证扩展功能：命令面板运行TaskMaster: Show Board打开 Kanban 面板，TaskMaster: Check Connection检查 MCP 连接；
3. 修改代码后使用Developer: Reload Window重载宿主窗口即可生效（watch模式下构建产物会自动更新）。

从源码看，扩展激活入口 apps/extension/src/extension.ts 的activate按序完成：初始化ExtensionLogger（注释明确指出其作用之一是避免 MCP stdio 冲突）、创建EventEmitter、初始化MCPClientManager（配置来自createMCPConfigFromSettings()，即读取taskmaster.*设置项）、TaskMasterApi、带缓存的TaskRepository、TerminalManager（用于在终端启动任务）、ConfigService，再通过策略模式创建PollingService——当 webview 打开时开始轮询、全部关闭时停止。这些服务分层为开发调试提供了清晰的观测边界。

生产打包：从构建产物到 VSIX

标准两步流程

# 第 1 步：构建干净发布目录 npm run package # 即 node ./package.mjs # 第 2 步：进入 vsix-build 生成 VSIX cd vsix-build npx vsce package --no-dependencies

npm run package生成vsix-build/干净目录，其中package.json已由package.publish.json替换；--no-dependencies告知vsce不执行依赖解析，直接打包，从而绕开依赖冲突。

一条命令完成

npm run package && cd vsix-build && npx vsce package --no-dependencies

生成的 VSIX 文件名遵循task-master-<version>.vsix模式（如task-master-0.26.0.vsix，实际版本以 apps/extension/package.json 与 CHANGELOG.md 为准）。

注意：原文档示例中的taskr-kanban-1.0.1.vsix与"taskr"包名属于早期规划；当前仓库实际使用的包名为extension（开发）与task-master-hamster（发布），发布版publisher为Hamster，版本当前为0.26.0（详见 package.publish.json）。所有命令以仓库实际内容为准。

保持双 manifest 同步：哪些字段必须一致，哪些必须不同

由于开发与发布各持一份 manifest，元数据更新时极易"漏改一处"，导致"本地正常、打包后行为异常"。

必须严格一致的字段

{ "version": "0.26.0", // ⚠️ 必须一致 "publisher": "Hamster", // ⚠️ 必须一致 "displayName": "TaskMaster", // ⚠️ 必须一致 "description": "A visual Kanban board interface for TaskMaster projects in VS Code", "engines": { "vscode": "^1.93.0" }, // ⚠️ 必须一致 "categories": ["AI", "Visualization", "Education", "Other"], // ⚠️ 必须一致 "activationEvents": ["onStartupFinished", "workspaceContains:.taskmaster/**"], // ⚠️ 必须一致 "main": "./dist/extension.js", // ⚠️ 必须一致 "contributes": { ... } // ⚠️ 必须完全一致 }

好消息是：版本号不必再手工同步。package.mjs在每次打包时会把开发版版本号（含 RC 转换后的结果）自动写回package.publish.json并打印日志：

- Version sync needed: 0.25.3 → 0.26.0 - Updated package.publish.json version to 0.26.0

但engines、activationEvents、contributes等结构字段仍需在编辑时保持两侧一致。

刻意不同的字段

// package.json（开发版） { "name": "extension", // ✅ 简短开发名，private: true "devDependencies": { ... }, // ✅ 仅存在于开发版 "scripts": { ... } // ✅ 构建脚本仅存在于开发版 } // package.publish.json（发布版） { "name": "task-master-hamster", // ✅ Marketplace 包名 "keywords": [...], // ✅ 仅发布版包含 "repository": "...", // ✅ 仅发布版包含 // 无 devDependencies // ✅ 发布版保持干净 // 无 build scripts // ✅ 打包无需脚本 }

此外，MCP 相关默认值也可不同（开发版用内置 server，发布版默认npx -y task-master-ai），这一点在前文已说明。

自动化发布：Changesets 驱动版本管理与持续发布

创建 Changeset 的规范流程

每次改动扩展代码后，必须记录变更：

1. 完成代码修改；
2. 在仓库根目录执行npx changeset add；
3. 按提示选择扩展包（对应task-master-hamster/ 历史文档中的taskr-kanban）；
4. 选择版本递增类型：
   • patch：Bug 修复、小更新；
   • minor：向后兼容的新功能；
   • major：破坏性变更；
5. 编写面向用户的变更摘要。

自动化发布流水线

根据 apps/extension/docs/extension-CI-setup.md 的描述，仓库包含两条核心流水线：

1. extension-ci.yml：在推送到main/next分支或发起 PR 时触发（仅当扩展文件有变更），执行 lint、typecheck、npm run build、npm run package、运行 VS Code 测试框架、创建测试用 VSIX 验证打包链路并上传产物；
2. version.yml（版本发布）：推送到main后检测.changeset/中的变更文件，生成 "Version Packages" PR（更新版本号与 CHANGELOG）；当该 PR 被合并时，自动完成构建打包、创建 git tag、发布到 VS Code Marketplace 与 Open VSX Registry、更新包版本与 CHANGELOG。

发布动作由scripts/release.sh承担：使用三文件打包体系构建扩展、生成 VSIX，并在设置了相应密钥时分别发布到 VS Code Marketplace（VSCE_PAT）与 Open VSX Registry（OVSX_PAT），最后为扩展版本创建 git tag。

所需 Secrets

手动发布

# 在仓库根目录执行 ./scripts/release.sh

独立打标签策略

扩展与主包使用互不冲突的独立标签体系，使 monorepo 中两个包的版本可以各自演进：

• 扩展标签：task-master-hamster@0.26.0这类格式（历史文档中记为taskr-kanban@x.y.z）；
• 主包标签：task-master-ai@x.y.z。

故障排查手册

依赖冲突

• 症状：vsce package报缺少依赖。
• 解法：始终通过三文件体系打包，绝不要在仓库根目录（或开发版package.json所在目录）直接执行vsce package；应使用npm run package生成vsix-build/后，在vsix-build/内执行npx vsce package --no-dependencies。

构建失败

• 症状：构建后扩展不工作。
• 排查项：
  1. 所有产物均已拷贝到vsix-build/dist/（extension.js、index.js、index.css、sidebar.js，不含.map）；
  2. package.publish.json的main字段正确指向./dist/extension.js；
  3. 当前 VS Code 版本满足engines.vscode（^1.93.0）约束；
  4. 若使用npm run package，留意日志中是否有 "Version sync needed" 提示。

同步不一致

• 症状：本地一切正常，打包后行为异常。
• 排查项：核对package.json与package.publish.json的关键字段（engines、activationEvents、contributes、main）是否完全一致；contributes中命令 ID、视图 ID 不一致会导致命令无法注册。

Changeset 未触发版本工作流

• 排查项：
  1. .changeset/目录下存在变更文件；
  2. changeset 中的包名与package.publish.json的name匹配；
  3. 变更已推送到main分支。

发布失败

• 排查项：
  1. 仓库 Secrets 中已设置VSCE_PAT/OVSX_PAT；
  2. package.publish.json的repositoryURL 正确；
  3. 完整构建（npm run build→npm run package→vsce package）能成功跑通。

版本发布清单

手动发布

1. 执行npx changeset add创建变更记录；
2. 同步更新package.json与package.publish.json的关键字段（版本号可由package.mjs自动同步）；
3. 在 VS Code 中按F5本地验证；
4. 提交并推送，触发自动化工作流。

自动化发布（推荐）

1. 执行npx changeset add；
2. 推送到功能分支并创建 PR；
3. 合并 PR——触发 "Version Packages" PR 的创建；
4. 审查并合并版本 PR——触发自动构建、打包与发布。

这套体系的价值总结

• 规避依赖冲突：发布包中不携带任何开发依赖，vsce package --no-dependencies不再报错；
• 分发干净：VSIX 仅含运行必需文件（dist 产物、manifest、README/CHANGELOG/LICENSE、assets）；
• 打包更快：省去vsce的依赖解析步骤；
• 可维护：开发配置与发布配置职责边界清晰，且package.mjs自动完成版本同步；
• 可靠：从 CI 构建、测试 VSIX 验证到发布，全链路一致且可复现；
• 自动化：Changesets 统一管理版本号、CHANGELOG 与双平台发布；
• 可追溯：每次发布都有清晰的 CHANGELOG 条目与独立 git tag（参考 apps/extension/CHANGELOG.md 的 0.x 版本历史）。

实践要点：任何扩展改动都先npx changeset add，再推送代码以触发自动化发布；遇到打包问题优先检查是否绕过了三文件体系直接执行了vsce package。

【免费下载链接】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