update-packages

更新软件包

操作模式

运行任何更新命令前，先确定操作模式：

• 使用建议模式仅进行分析、报告并提出更改建议。不要创建分支。
• 使用执行模式应用版本更改。编辑第一个软件包前，先创建一个全新的更新分支。

参考资料

执行期间请使用以下参考资料：

• references/package-groups.md — 必须一并更新的软件包组
• references/feature-adoption-tiers.md — T0-T3 采用等级标准
• references/report-formats.md — 发布报告和“What's New”输出格式
• references/testing-matrix.md — 不同更新类型所需的测试
• references/runtime-checklists.md — Bun 和 Playwright 检查清单；更新 Effect 或编译器时，请阅读 Effect Updates 部分；升级 SDK 时，请阅读 SDK Updates 部分

步骤 0：准备会话（仅限执行模式）

更新技能，并在修改软件包前创建专用分支。

# Update all skills from skills-lock.json (reads sources + skill names from lock)
bun run .agents/skills/update-packages/references/skills-update-local.ts

# Dry run to see what would be executed
bun run .agents/skills/update-packages/references/skills-update-local.ts --dry-run

# Create a fresh branch
git checkout -b chore/update-packages-$(date +%y%m%d-%H%M)

应用以下规则：

• 先更新技能。
• 为执行工作创建一个新的更新分支。
• 不要重复使用之前的更新分支。
• 所有更新提交都放在执行分支上。

更新策略

按软件包组执行的流程

阅读 references/package-groups.md。每个组都要先完成步骤 1-4，再继续处理下一个组。

步骤 1 — 确定版本和发布说明

运行以下三项报告：

bun run .agents/skills/update-packages/references/check-outdated.ts
bun run .agents/skills/update-packages/references/check-outdated.ts --changelog
bun run .agents/skills/update-packages/references/report.ts --json

将生成的 JSON 文件用作会话数据：

脚本标志	保存至
--json	.agents/skills/update-packages/references/outdated.json
--changelog	.agents/skills/update-packages/references/outdated-changelog.json
report.ts --json	.agents/skills/update-packages/references/runtime-report.json

分析前处理过期的报告文件：

• 在会话开始时重新生成全部三份报告。
• 如果旧报告文件包含先前运行或分支的数据，请先删除。
• 将已保存的 JSON 文件视为可丢弃的本地文件。不要提交它们。

集中处理 catalog 软件包：

• 在根目录的 package.json 中，通过 catalog 和 catalogs 查找 catalog 版本。
• 必要时手动检查最新版本（npm view <package> version）。
• 遵守仓库在 bunfig.toml 中规定的 Bun 安装策略，尤其是 minimumReleaseAge 及相关排除项。
• 不要使用 bun install --minimum-release-age 0 之类的标志绕过 Bun 的时限门槛，除非用户明确要求这样做。
• 为整个软件包组选择符合 minimumReleaseAge 要求的最新兼容版本。如果某个请求的版本似乎受到阻止，请先用 bun install <package>@<version> --dry-run --no-save 重现该情况，再记录拒绝原因；随后使用最新的合规版本。
• 手动更新 catalog 条目，然后运行普通的 bun install。

步骤 2 — 并行更新并采用功能

轨道 A：应用更新	轨道 B：采用发行说明中的功能
通过 bun upgrade 或编辑 catalog 应用版本升级	阅读 outdated-changelog.json——每个条目都包含完整发行说明的 releases[]
如果 catalog 有变更，则运行 bun install（遵守 bunfig.toml 中的 minimum-release-age 策略）	按层级对每项新功能进行分类（参见 references/feature-adoption-tiers.md）
	T0/T1：实施配置级变更（目标文件位于 configFiles[] 中），并通过 bun run check 验证
	T2：生成具体差异，并纳入报告
	在代码库中搜索对已变更、已弃用或新增 API 的使用情况

对于 SDK 升级，请遵循 references/runtime-checklists.md 中的 SDK 更新检查清单。

如有条件，请将发行说明调研委派给子 Agent／资料调研员。如果无法委派，则由主 Agent 按相同标准依次处理各软件包组。

采用 references/feature-adoption-tiers.md 中的 T0-T3 标准。

步骤 3 — 检查并修复

运行 references/testing-matrix.md 中要求的测试。
至少运行 bun run check。
结合 outdated-changelog.json 中的发行说明上下文修复失败。

步骤 4 — 提交软件包组

版本升级和功能采用应分别提交：

• chore: update <package> to vX.Y.Z — 仅升级版本
• feat: adopt <package> vX.Y improvements (<feature list>) — 采用新功能所需的配置／代码变更

更新期间发现的行为或安全修复，应放在与依赖升级不同的 PR 中。

内部库发行版本

将对等依赖固定到完全兼容的系列版本。对等依赖范围不得从预发行版本开始。发布前，应将该库安装到干净的使用方项目中，针对每个受支持的系列版本和包管理器进行验证，然后确认锁文件中每个系列软件包都只有一个副本。

发行说明报告

使用 references/report-formats.md 生成发行报告。
使用子 Agent 时，要求每个子 Agent 搜索对已变更、已弃用或新增 API 的使用情况。
依次处理时，直接执行相同的搜索。

新功能摘要

使用 references/report-formats.md 生成“新功能”摘要。
以 outdated-changelog.json 作为主要来源。
仅在需要时才让资料调研员获取缺失的发行说明。

特殊情况

遵循 references/runtime-checklists.md 中的 Bun 和 Playwright 检查清单。对于 Effect 或编译器更新，请遵循其中的 Effect 更新部分。对于 SDK 升级，请遵循其中的 SDK 更新部分。

部署后，检查每个项目和环境的 Sentry 是否出现新问题。请求 / 和存活检查路由；仅存活检查响应成功并不能验证服务器渲染。

测试要求

使用 references/testing-matrix.md 选择必需的测试。

防护措施

• 不要更新使用 workspace:* 的软件包。
• 不要跳过 @typescript/native-preview 更新。
• 不要使用 bun outdated；请改用 check-outdated.ts。
• 除非用户明确要求，否则不得绕过 Bun 的 minimumReleaseAge 策略。
• 如果 bun install 因 minimumReleaseAge 失败，请将请求的软件包版本降级到符合策略的最新版本，然后使用普通的 bun install 重试。
• 如果安装失败，请运行 bun clean:packages，然后运行 bun install。

完成标准

• 确认 check-outdated.ts 显示没有剩余的直接依赖更新。
• 确认 bun run check 通过。
• 确认 references/testing-matrix.md 要求的所有测试均通过。