---
name: upgrade-packages
description: 调研 package.json 所有依赖的最新版本，交叉验证版本差异，给出可升级到最新版的结论
---

帮我调研当前项目所有依赖的最新版本，深入对比每个库「已安装版本」和「最新版本」之间的内容差异，**交叉验证**后给出结论：哪些库可以安全升级到最新版。

这是一次**调研 + 报告**任务，默认**不要**修改 [package.json](../../../package.json) 或执行安装命令。除非我明确要求，否则只产出结论，不动代码。

## 工作流

### 1. 盘点依赖
- 读取 [package.json](../../../package.json)，列出全部 `dependencies` 和 `devDependencies`。
- 在终端运行 `pnpm outdated`（项目用 pnpm，不要用 npm/yarn）拿到「Current / Wanted / Latest」三列。
- 如果我在参数里指定了具体库名，只处理这些库；否则处理全部有可升级版本的库。
- 已经是最新版的库直接跳过，不必逐个写说明。
- 不要更新typescript版本。

### 2. 逐库深入调研
对每个「有更新」的库，调研已安装版本 → 最新版本之间发生了什么：
- 优先官方渠道：GitHub Releases / `CHANGELOG.md` / 官方迁移指南 / npm 页面。
- 判断版本跳变性质：patch / minor / major（遵循 semver），跨越多个大版本时要把中间每个 major 的破坏性变更都覆盖到，不能只看最新一版。
- 重点提取：**breaking changes、废弃 API、需要手动迁移的步骤、对等依赖（peerDependencies）要求**。
- 特例 @earendil-works/pi-agent-core / pi-ai：变更日志在 pi monorepo 仓库内，**不在 npm release notes**——看 `packages/ai/CHANGELOG.md` 和 `packages/agent/CHANGELOG.md`（github.com/earendil-works/pi）。二者须锁步升到同一版本；深入调研这两个包时优先使用项目的 `upgrade-pi` workflow。

### 3. 交叉验证（必做）
每个结论至少要有两类独立来源相互印证，避免只信单一页面：
- 来源交叉：GitHub Releases 与 CHANGELOG/官方文档说法是否一致。
- 代码交叉：用代码搜索确认本项目**实际怎么用这个库**（用到的 API、入口、是否只是间接依赖），据此评估破坏性变更对本项目的**真实影响**——别人眼里的 breaking 在我们这儿可能根本没用到。
- 生态交叉：注意 React 19、WXT、Tailwind v4 等关键依赖的 peer 兼容要求，别让单个升级破坏整体。特别地，`typebox` 与 pi（pi-ai / pi-agent-core）内部捆绑的 typebox 必须同版本——本项目精确 pin `typebox`（无 `^`）就是为此，**不要单独升 typebox**，它只能跟随 pi 一起动；升级前后都去 [pnpm-lock.yaml](../../../pnpm-lock.yaml) 核对 pi 解析的 typebox 版本。
- 遇到来源互相矛盾或信息不足，**如实标注「未确认」**，不要猜。

### 4. 分类结论
把每个库归入下面四类之一，并给出一句话理由：
- ✅ **可安全升级**——patch/minor，无破坏性变更，本项目用法不受影响。
- ⚠️ **可升级但需注意**——有废弃项或行为变化，需小改或回归验证。
- ⛔ **破坏性升级**——major 跨越且本项目用到了受影响 API，需要改代码/迁移。
- ❓ **暂不建议 / 待确认**——信息不足、peer 冲突，或收益不明。

## 输出格式

先给一张总览表：

| 库 | 已安装 | 最新 | 跳变 | 结论 | 一句话理由 |
|----|--------|------|------|------|-----------|

再按「需要注意」「破坏性」「待确认」分组展开细节（✅ 可安全升级的库列在表里即可，不必逐个展开）。每个展开项写明：关键变更、对本项目的真实影响、升级要做的事、来源链接。

最后用一段话给出整体建议：这一轮优先升哪些、哪些先放着、有没有需要分批进行的。

调研中如果发现某个库的判断把握不大，直接告诉我「这个我没法确认」，并说明卡在哪里——不要给出没有依据的结论。