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 更新检查清单

步骤 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）。
• 手动更新 catalog 条目，然后运行 bun install。

步骤 2 — 并行执行更新和功能采纳

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

条件允许时，将发行说明调研工作委派给子 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>) — 新功能带来的配置／代码更改

发行说明报告

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

新功能摘要

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

特殊情况

应用 references/runtime-checklists.md 中的 Bun 和 Playwright 更新检查清单。

测试要求

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

防护措施

• 不要更新使用 workspace:* 的软件包。
• 不要跳过 @typescript/native-preview 更新。
• 不要使用 bun outdated；请使用 check-outdated.ts。
• 如果安装失败，请先运行 bun clean:packages，然后运行 bun install。

完成标准

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