企业官网建设流程全解析

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能

本指南围绕 mcp-use 仓库libraries/typescript/.changeset/README.md及配套的 CI 工作流，系统讲解 TypeScript 多包仓库如何使用 Changesets 完成版本管理与发布：包括创建 changeset 的正确姿势、main 分支稳定版与 canary 分支预发布两条自动化流水线、.changeset/config.json关键配置的含义，以及哪些命令必须交给 CI、哪些命令需要人工执行。读完本文，你将能独立为一个 mcp-use TypeScript 包提交合规的变更描述，并理解一次发布从 PR 合并到 npm 发布、Git tag 与 GitHub Release 创建的全过程。

为什么 mcp-use 需要 Changesets

mcp-use 的 TypeScript 侧是一个标准的多包（monorepo）工程，根目录位于 libraries/typescript，通过 pnpm-workspace.yaml 声明了packages/*及若干嵌套示例目录。仓库内同时存在多个需要独立发版的 npm 包，包括但不限于mcp-use、@mcp-use/client、@mcp-use/server、@mcp-use/agent、@mcp-use/cli、@mcp-use/inspector、@mcp-use/tunnel和脚手架create-mcp-use-app（可参见 package.json 中的workspaces配置与发布脚本）。

多包仓库面临两个核心问题：

1. 变更归属不明确：一次提交可能同时改动多个包，人工判断"这次该给谁升版本"容易出错；
2. 变更记录丢失：PR 合并后，changelog 往往靠事后补写，版本历史与代码变更脱节。

Changesets（@changesets/cli已在根devDependencies中声明）正是为解决这些问题而生的工具：它在提交代码时就记录"哪个包、哪种升级类型、改了什么"，版本号与 changelog 由工具统一计算生成，保证发布信息与代码变更强绑定。

协作铁律：所有 TypeScript 变更必须附带 changeset

在 mcp-use 仓库中，提交 changeset 不是可选项，而是强制要求。项目根目录的 CONTRIBUTING.md 明确写道：

All TypeScript changes require a changesetdescribing what changed. This is enforced in CI for PRs tomain.

即：任何改动 TypeScript 包的 PR，都必须同时提交一个描述变更的 changeset 文件，并且该要求在合并到main的 PR 上由 CI 强制校验（CI 检查清单中的 "Changeset verification (PRs to main only)" 即对应 ci.yml 中的相关步骤）。因此，创建 changeset 是每一位贡献者提交 TypeScript 代码前的必备动作。

快速上手：用pnpm changeset创建变更记录

在仓库根目录执行：

cd libraries/typescript pnpm changeset

命令会以交互式问答引导你完成三步：

1. 选择哪些包发生了变更（Select which packages have changes）；
2. 选择版本升级类型（Choose the version bump type）：major/minor/patch，对应语义化版本规则；
3. 编写变更摘要（Write a summary of the changes）：一段描述本次改动的文本。

完成后，工具会在libraries/typescript/.changeset/目录下生成一个类似tidy-melons-sing.md的 Markdown 文件，其内部结构为 YAML frontmatter 加正文摘要：

--- "@mcp-use/client": patch "mcp-use": minor --- 为客户端新增对某某传输协议的支持，并修正了连接超时时的错误提示。

frontmatter 中列出受影响的包名与对应的 bump 类型，正文则是会进入 changelog 的描述文本。

提交并推送 changeset 文件，与代码改动放在同一个提交中：

git add . git commit -m "feat: your feature description" git push

提示：建议遵守项目的 conventional commit 约定（见 CONTRIBUTING.md），例如feat(typescript): ...、fix(typescript): ...，便于维护者快速定位变更性质。

自动化发布：哪些命令不能手动执行

Changesets 的完整工作流包含两个阶段：收集变更（创建 changeset）与应用变更（版本计算 + 发布）。在 mcp-use 中，后一阶段被 GitHub Actions 完全接管：

• pnpm version：由 CI 自动处理，禁止手动执行（即版本号提升与 changelog 生成）；
• pnpm release：由 CI 自动处理，禁止手动执行（即发布到 npm）。

也就是说，贡献者的职责只到"创建 changeset 并推送"为止，之后的版本计算、CHANGELOG 更新、npm 发布全部交给流水线。

这与根 package.json 中脚本的设计一致——version和release脚本虽然存在，但被设计为仅供 CI 内部调用：version会执行自定义的 version-packages.mjs（内部通过spawnSync调用changeset二进制并处理 workspace 依赖传播），release则执行pnpm build && changeset publish。脚本可用，但不意味着应人工触发。

main 分支：稳定版发布流程

向main分支合入变更时，流程如下：

1. 贡献者执行pnpm changeset创建 changeset；
2. 通过 PR 推送到main；
3. CI 自动创建一份 "Version Packages" PR（该 PR 内会应用版本计算、更新各包 CHANGELOG.md 与 workspace 依赖元数据，并刷新 lockfile）；
4. 合并该 Version PR 后，流水线自动将稳定版发布到 npm，并附带打 Git tag、创建 GitHub Release。

canary 分支：预发布流程

canary 分支走预发布（prerelease）通道，用于在正式发版前验证新功能：

1. 同样先pnpm changeset创建变更记录；
2. 推送到canary分支；
3. CI 自动以x.y.z-canary.N形式发布预发布版本（pre.json与changeset pre enter canary机制由 typescript-release.yml 管理）。

流水线源码解读：一次发布在 CI 中经历了什么

真正的发布逻辑集中在 .github/workflows/typescript-release.yml。该工作流在main与canary两个分支上触发，并只关注libraries/typescript/**与工作流自身的变化。其关键步骤可以概括为一条清晰的链路：

1. 构建与自检：pnpm install --frozen-lockfile→pnpm build→pnpm verify:release-install（验证打包产物可被正常安装，防止"能编译但装不上"的问题）。
2. canary 分支进入预发布模式：若.changeset/pre.json不存在，则执行pnpm changeset pre enter canary并提交该文件。
3. 检查待发布 changesets：通过pnpm release-channel pending判断是否有待应用的变更，没有则直接跳过发布。
4. 生成并校验发布计划：pnpm release-channel prepare/preflight/validate结合changeset status输出，确保发布计划合法。
5. 应用版本：pnpm changeset version写入新版本号并更新 changelog，随后刷新 lockfile 并提交。
6. 发布：pnpm changeset publish使用 npm 的 trusted publishing（OIDC）机制，无需手动配置 npm token。
7. 验证与打标：pnpm release-channel verify校验已发布的版本与 dist-tag，随后pnpm changeset tag推送 Git tag。
8. 创建 GitHub Release：从各包 CHANGELOG.md 中提取对应版本段落作为 Release 正文，mcp-use主包在稳定发布时会被标记为latest。
9. 下游联动：main 稳定发布后还会生成部署标记（.railway-deploy-marker），供 Railway 等部署流水线消费；canary 分支会被强制 reset 回 main，保持预发布通道始终与最新稳定代码对齐。

从这条链路可以看出，mcp-use 的发布流水线在标准changeset version+changeset publish之外，还叠加了release-channel系列脚本（见 package.json 中的release-channel、version:check等命令）做发布计划的预演与校验，属于对 Changesets 能力的工程化封装。

.changeset/config.json配置逐项解读

mcp-use 的 changeset 配置 内容如下：

{ "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json", "changelog": "@changesets/cli/changelog", "commit": false, "fixed": [], "linked": [], "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": [], "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": { "onlyUpdatePeerDependentsWhenOutOfRange": true } }

各字段在 mcp-use 场景下的含义：

注意：baseBranch: main与 typescript-release.yml 中针对main、canary两个分支的分支逻辑共同构成完整发布模型——配置声明基准，工作流声明通道。

配套工程能力：dependabot 依赖升级的自动 changeset

多包仓库中依赖升级是最频繁的变更来源之一。为此仓库还提供了 .github/workflows/dependabot-changesets.yml：当 Dependabot 提交的 PR 修改了libraries/typescript/**/package.json时，该工作流会自动：

1. 分析 PR 相对origin/main的 diff，找出受影响且非private的公开包；
2. 解析依赖版本变化，生成形如"@mcp-use/client": patch的 changeset；
3. 将 changeset 提交并推送回 Dependabot 分支。

这一机制保证了"依赖升级必须带 changeset"的规则对机器人同样生效，从源头避免 CI 的 changeset 校验失败。该工作流同时支持workflow_dispatch手动触发（可指定 PR 号与force参数，用于强制重新生成）。

常见操作与排错

查看当前是否有待发布的 changeset / 版本状态

cd libraries/typescript pnpm version:check # 等价于 changeset status

如果输出提示存在未应用的 changeset，说明有变更记录待版本计算，等待 CI 的 Version PR 或 canary 发布即可。

我提交了代码但 CI 报 changeset 校验失败

说明改动涉及 TypeScript 包却未附带.changeset/*.md文件。回到 快速上手 一节，执行pnpm changeset生成记录后随代码一起提交。

PR 中意外提交了多个 changeset

.changeset/目录下允许存在多个.md文件，CI 会一次性消费全部待处理 changeset；若需要清理，删除多余的 changeset 文件并保持至少一个有效记录即可（不要手动改动版本号）。

小结

围绕libraries/typescript/.changeset/README.md约定，mcp-use 的 TypeScript 发布体系可以概括为三句话：

• 贡献者只负责一件事：为 TypeScript 变更创建并提交 changeset（pnpm changeset），这是 CI 强制要求的唯一人工环节；
• 版本与发布完全自动化：pnpm version/pnpm release由 typescript-release.yml 接管，main 出稳定版、canary 出-canary.N预发布版，并自动完成 changelog、Git tag、GitHub Release 与部署标记的全链路；
• 工具链在标准之上做了工程化增强：release-channel预演校验、verify-release-install安装自检、dependabot 自动 changeset 等机制，都是为了降低多包发布中的人为失误率。

这套流程同样适用于其他基于 Changesets 的多包 TypeScript 仓库——理解.changeset/config.json的语义、厘清"收集变更"与"应用变更"的职责边界，是驾驭任何 changesets 工程的第一步。

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能