企业官网建设流程全解析

Kilo 仓库 Changesets 变更管理指南：从 changeset 文件到 GitHub Release Notes 的完整工作流

【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode

导读

本文以 Kilo（开源仓库 GitHub_Trending/ki/kilocode）中的 .changeset/README.md 为骨架，系统讲解该仓库如何基于 Changesets 工具链管理「面向用户的变更」：包括 changeset 文件的编写规范、patch / minor / major版本语义、发布期消费流程，以及它们最终如何转化为 GitHub Release Notes 中的 changelog 条目。读完本文，你将掌握在 Kilo 这类多包 monorepo 中提交变更、跟踪版本、自动生成发布说明的完整实操方法，并能读懂仓库中 .changeset/config.json 与 script/publish.ts 背后的设计意图。

一、Changesets 是什么：Kilo 的变更跟踪机制

Changesets是一个面向 monorepo 的版本管理与发布工具。它的核心思路是：开发者在提交代码时，同时提交一份描述「这个 PR 对用户产生了什么影响」的小文件，发布时再由工具统一汇总，自动推导版本号、生成 changelog，并联动发布流程。

在 Kilo 仓库中，.changeset/目录承担了这一职责。从仓库实际内容看：

• .changeset/README.md 是开发者提交变更时的操作指南；
• .changeset/下存放着一系列待消费的 changeset 文件，例如agent-manager-home-guidance.md、claude-global-migration.md、caffeinate-cli.md等，每一个通常对应一次面向用户的改动；
• .changeset/config.json 是 Changesets 的配置文件，声明了 changelog 生成器、版本联动（fixed）策略、基线分支等关键选项；
• 发布流水线 .github/workflows/publish.yml 在发布时执行bunx changeset version消费这些文件。

换句话说，.changeset/README.md只是入口，真正的完整链路是「写 changeset → CI 校验 → 发布时版本归并 → 生成 changelog → 写入 GitHub Release Notes」。

二、如何添加一个 changeset：README 规范全解

2.1 原则：每个 PR 一个 changeset

原文明确规定：当做出面向用户的变更（user-facing change）时，优先每个 PR 提交一个简洁的 changeset，并在可能的情况下对相关变更进行分组。

这样做的收益是显而易见的：

• 每个 PR 的变更影响在合并时即可沉淀，避免发布前集中补记导致遗漏；
• 版本号推导与 changelog 生成可以逐条追溯，评审更清晰；
• 便于 Release Notes 按 PR 粒度呈现，用户能快速定位某条改动对应的代码。

2.2 推荐方式一：命令行生成

bunx changeset add

在 Kilo 仓库中，Bun 是默认运行时（仓库根目录存在 bunfig.toml 与 bun.lock，且 CI 使用 .github/actions/setup-bun 安装 Bun），因此使用bunx changeset add而非npx changeset add。执行后，工具会以交互方式询问：

1. 影响到了哪些包（本仓库主要是kilo-code与@kilocode/cli）；
2. 版本变更类型（patch / minor / major）；
3. changeset 摘要内容。

随后自动在.changeset/下生成一个随机的<slug>.md文件。

2.3 推荐方式二：手工创建文件

也可以直接在.changeset/<slug>.md下手写，格式为 YAML frontmatter + Markdown 正文：

--- "kilo-code": minor --- Short description of the change for the changelog.

各字段说明：

仓库内真实示例可参考 .changeset/claude-global-migration.md：

--- "@kilocode/cli": minor "kilo-code": minor --- Add an opt-in, one-time import of supported global Claude Code instructions, simple skills, and disabled MCP definitions into Kilo.

以及 .changeset/complete-release-notes.md：

--- "@kilocode/cli": patch --- Include CLI changes alongside VS Code changes in GitHub release notes.

可以看到，一个 PR 的改动可以同时影响多个包（例如同时升级 CLI 与主扩展），此时在 frontmatter 中按"包名": 版本类型的格式逐行列出即可。

2.4 版本类型语义：patch / minor / major

原文给出三条硬性规则，这也是 Semantic Versioning（语义化版本）在 Kilo 中的落地：

从.changeset/目录中的实际文件命名也能印证这套约定：fix-terminal-tab-close-resize.md、clear-empty-repository-worktree-error.md等对应 bug 修复（patch），而caffeinate-cli.md、claude-global-migration.md、session-goals.md等对应新功能（minor）。

三、配置层解读：config.json 与版本联动策略

.changeset/config.json 是理解该仓库发布策略的关键，逐项说明如下：

{ "$schema": "https://unpkg.com/@changesets/config@3.0.4/schema.json", "changelog": ["../script/changelog-github.cjs", { "repo": "Kilo-Org/kilocode" }], "commit": false, "fixed": [["kilo-code", "@kilocode/cli"]], "linked": [], "access": "restricted", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": [] }

• changelog：指定 changelog 生成器为仓库自研的 script/changelog-github.cjs，并传入repo: Kilo-Org/kilocode。该脚本包装了@changesets/changelog-github，额外逻辑是从 "Thanks @user!" 致谢行中剔除团队成员——它内置了一个团队成员名单（如kilo-code-bot、kilo-maintainer[bot]等），通过正则/ Thanks \[@([^\]]+)\]\([^)]+\)!/g匹配并移除，避免机器人或内部成员刷屏致谢，而外部贡献者的致谢得以保留。
• commit：false，即 changesets 消费时不自动生成 git commit（Kilo 的发布提交由publish.ts统一git commit -am "release: v${Script.version}"完成）。
• fixed：[["kilo-code", "@kilocode/cli"]]，这是最值得注意的配置。它声明主扩展包kilo-code（VS Code 扩展）与 CLI 包@kilocode/cli为固定版本联动组：只要其中一个需要 minor/major 升级，组内所有包都会同步升到同一版本，避免扩展与 CLI 版本漂移带来的兼容问题。
• linked：空数组，未启用独立的「linked」版本组。
• access：restricted，配合 npm 私有/受限发布策略。
• baseBranch：main，版本归并（changeset version）与发布均基于 main 分支。
• updateInternalDependencies：patch，当内部依赖包升级时，依赖方最低用patch级别跟随更新。
• ignore：空数组，没有包被排除在发布流程之外。

注："kilo-code"对应 packages/kilo-vscode（VS Code 扩展），"@kilocode/cli"对应 packages/opencode（Kilo 的 CLI，即仓库继承的上游 opencode 代码包）。

四、changeset 的消费时机：publish 流水线全流程

原文指出：「changeset 文件在发布时被消费——当publish.yml工作流运行时，会为 GitHub Release Notes 生成 changelog 条目」。让我们沿着 .github/workflows/publish.yml 还原这条真实链路。

4.1 版本计算阶段

publish工作流通过workflow_dispatch手动触发，输入参数包括bump（patch/minor/major）、可选version覆盖值，以及pre_release（是否作为预发布版，默认true）。随后执行：

./script/version.ts

script/version.ts 调用gh release create先创建一个草稿（draft）发布，并输出version、release（release 的 databaseId）、tag供下游 job 使用。

4.2 消费 changeset：bunx changeset version

关键逻辑位于 script/publish.ts 的开头（第 14～41 行）。代码注释明确指出：

「consume changesets on the publish runner so changelog changes are included in the release commit. Previously this ran in the version job on a separate runner whose workspace was discarded.」

即：changesets 的消费被特意移到发布 runner 上执行，这样生成的 changelog 变更能直接包含在 release commit 中。具体步骤：

1. bun install安装依赖；
2. 记录packages/kilo-vscode/CHANGELOG.md与packages/opencode/CHANGELOG.md的修改前内容；
3. 执行bunx changeset version——这一步会读取.changeset/*.md，按 frontmatter 中的版本类型归并，更新各包package.json的 version 字段，并向两个 CHANGELOG.md 追加新版本条目，随后删除已消费的 changeset 文件；
4. 由于 Changesets 推导的版本可能与 Kilo 统一的Script.version不一致，publish.ts 会对被修改的 changelog 做一次标题修正：content.replace(/^## .+$/m,## ${Script.version})，将版本标题统一为 Kilo 的正式版本号。

4.3 版本写入与发布提交

随后 publish.ts 遍历仓库所有package.json（排除 node_modules 与 dist），把"version"统一替换为Script.version；同时更新 packages/extensions/zed/extension.toml 中的版本号与下载链接；再执行git commit -am "release: v${Script.version}"、打 tagv${Script.version}，并通过「fetch → rebase → push --force-with-lease」带重试的策略安全推送（该策略用于应对 main 上并发合并导致的冲突）。

4.4 生成 GitHub Release Notes

发布提交推送成功后，publish.ts 调用自研的 script/kilocode/release-notes.ts 的publishNotes()：

1. 读取packages/kilo-vscode/CHANGELOG.md（VS Code 部分）与packages/opencode/CHANGELOG.md（CLI 部分）；
2. 用正则^##\s+(.+)$解析 changelog，按语义化版本号切分出各版本小节；
3. 通过buildReleaseNotes()将两个 changelog 组织为## VS Code与## CLI两个板块；预发布（prerelease）时只取当前版本正文，正式发布时还会回溯纳入「上一个稳定版之后的所有预发布版本」的变更，实现预发布累积；
4. 将最终文本写入临时文件，通过gh release edit填充之前创建的草稿 release 的 notes，并置--draft=false完成发布。

值得一提的细节：release-notes.ts的注释说明packages/opencode中继承的 changelog 实际承载的是 Kilo 的 CLI（@kilocode/cli）发布说明，因此在生成 Release Notes 时会合并 VS Code 与 CLI 两部分的变更——这正是 .changeset/complete-release-notes.md 所描述的「Include CLI changes alongside VS Code changes in GitHub release notes」在代码层的落点。

4.5 预发布通道

publish.yml支持pre_release输入，对应 npm 的rc通道与 VS Code marketplace 的预发布版本；script/version.ts对beta/rc通道创建--prerelease的草稿发布。而release-notes.ts中的pattern = /^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/则兼容了带预发布后缀的版本号解析。

五、CI 对 changeset 的校验与测试隔离

changesets 不只是发布期的概念，在开发阶段同样参与 CI。在 .github/workflows/test.yml 中可以看到路径过滤规则：

- '!.changeset/**'

即.changeset/目录下的变更（新增 changeset 文件、更新 README 等）不会触发测试工作流的全量跑测——因为 changeset 文件只影响发布元数据，不影响源码行为。这条规则体现了仓库对「文档/元数据变更」与「代码变更」的职责分离管理。

此外，仓库根目录的 CI 检查（如 script/check-md-table-padding.ts、script/check-forbidden-strings.ts 等）也会对 Markdown 文件做一致性校验，changeset 文件作为 Markdown 同样需要符合仓库的格式规范。

六、实战清单：给 Kilo 提交一个合规变更

综合以上机制，一次完整的「面向用户变更」提交流程为：

1. 定位变更影响面：确定改动影响kilo-code（VS Code 扩展）还是@kilocode/cli（CLI），或两者皆有；
2. 判定版本类型：bug 修复 →patch；新功能 →minor；破坏性变更 →major；
3. 创建 changeset：在仓库根目录运行bunx changeset add，按交互提示选择包与类型并填写摘要；或手动在.changeset/<slug>.md写入 frontmatter + 描述；
4. 保持简洁：一个 PR 一个 changeset，相关小改动尽量合并描述；
5. 随 PR 合入 main：changeset 文件随代码一起进入 main 分支，CI 不会因.changeset/变更触发全量测试；
6. 发布时自动消费：publish.yml手动触发后，script/publish.ts依次完成bunx changeset version（归并版本、追加 CHANGELOG、删除已消费文件）、统一版本号、提交打 tag、release-notes.ts生成并回填 GitHub Release Notes。

结语

从 .changeset/README.md 的简短规范出发，可以看到 Kilo 将其扩展为一套端到端闭环：开发者侧只需遵循「每 PR 一个 changeset + patch/minor/major 语义」这一简单约定；仓库侧则由 .changeset/config.json 的 fixed 联动策略保证kilo-code与@kilocode/cli版本同步，由 script/changelog-github.cjs 过滤团队成员致谢，最终由 .github/workflows/publish.yml → script/publish.ts → script/kilocode/release-notes.ts 完成版本归并与 Release Notes 的自动生成。理解这条链路，无论是贡献者提交变更，还是维护者排查发布问题，都能事半功倍。

【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode