| name | upgrade-dependencies |
| description | Code Manager 仓库 pnpm/Cargo 依赖升级技能。依赖巡检、单包升级、Tauri 栈对齐、安全补丁修复、评估 Vite/TypeScript/Rust 主版本 breaking change，或复盘升级失败（构建/测试挂、锁文件漂移、版本回滚），只要涉及 package.json、Cargo.toml、lock 文件或要跑 pnpm audit/cargo update，都使用本技能。 |
Upgrade Dependencies
为 Code Manager 仓库执行依赖检查、升级规划、分批实施和复盘。事实源永远是当前命令输出——本文档列出的历史版本号会过时，不能当作未来升级的依据。
工作流速览
- 前置检查：工作区状态 + 工具链版本 + 命中规则。
- 抓事实：用当前命令输出，不读历史版本数字。
- 拆批：按"安全→Tauri→前端→breaking"四批，每批独立验证、独立回滚。
- 逐批实施 + 验证：跑对应验证矩阵。
- 收口：汇报实际改动、未尽项、风险。
方向偏离（lockfile 漂移、跨批升级、build 红）→ 停下重新规划，不要硬扛。
前置检查
读 CLAUDE.md 后，按改动范围读对应规则：
| 改动范围 | 必读规则 |
|---|
package.json、vite.config.ts、vitest.config.ts、tsconfig*.json | .claude/rules/frontend-ui.md |
src-tauri/Cargo.toml、Cargo.lock、Rust schema 测试 | .claude/rules/tauri-backend.md |
| Memory / Skills schema、契约测试 | .claude/rules/memory-and-skills.md |
环境快照（事后排查依赖）：
git status --short
pnpm --version
node --version
rustc --version
工作区已有无关 tracked 改动时叠加变更，不顺手回退或格式化——那可能是另一条工作线。
事实源
依赖结论只能来自当前输出，不能引用本文档下方"已知陷阱"里的版本号：
pnpm outdated --format json
pnpm audit --json
cd src-tauri && cargo update --dry-run --locked --verbose
深挖单个包时：
pnpm view <package>@<version>
cd src-tauri && cargo info <crate>
cd src-tauri && cargo tree -i <crate>@<version>
为什么强调当前输出：上游随时可能发新版本或撤回（yank）某版本；照抄旧记忆推进升级会让 lockfile 与 registry 实际状态错位，后续 CI 才暴露。
环境限制识别：sandbox 下 pnpm install / pnpm audit 网络可能失败；make build 的 DMG bundling 可能因 hdiutil 挂载权限挂——这些是环境问题，需要按权限流程提权重跑，不要为了绕过它们弱化测试、删除 audit 项或手改 lockfile。
分批策略
默认 4 批，按风险递增；除非用户明确要求合并，否则不合并。每批独立提交，便于定位和回滚。
Batch A — 安全与低风险前端补丁
先治 pnpm audit 中 moderate/high/critical 漏洞，附带前端 patch/minor 工具包。
- 为什么先做：风险面最小、价值最高，独立验证和回滚都容易，能尽快减小安全暴露窗口。
- 保持 pin 风格：原本精确 pin 的依赖继续精确 pin，只换版本值——下游 resolver 假设依赖于此，乱改 caret/tilde 会扩散到 lockfile 树。
Batch B — Tauri 2.x 栈对齐
JS 侧 @tauri-apps/* 与 Rust 侧 tauri*、所有 tauri-plugin-* 同步升级。
- 为什么打包：Tauri 是双语栈，JS 与 Rust 必须语义版本对齐，否则会出现 invoke 协议错配或 plugin schema 不一致——而且这种错位通常运行时才暴露。
- JS 插件精确 pin 时，Rust 插件同步 pin 到匹配版本。
Batch C — 前端 UI/表单库小版本
CodeMirror、UIW、React Hook Form、Zod、Tailwind v4、Recharts、date-fns、@pierre/diffs|trees 等。
- 为什么单独：这些库改 UI 行为或类型签名的概率高，需要前端测试 + 真实构建 + 视觉核验；混入 Tauri 批会让回滚粒度过粗，问题难定位。
Batch D — breaking / 主版本
Vite、TypeScript、pnpm、Rust 主版本依赖逐项独立评估。
- 为什么逐项：每个主版本都自带迁移指南，必须先读 release notes/migration guide 再动手；混批后"到底是哪个升级炸了"无法定位。
- 每个主版本独立提交或独立工作段，先跑局部测试，再跑全量门禁。
执行约束
- 不手动编辑
pnpm-lock.yaml / Cargo.lock——lock 文件由 resolver 生成，手改会引入实际不存在的版本组合。用 CI=true pnpm install、CI=true pnpm install --no-frozen-lockfile、cargo update 等命令生成。
- 不顺手改 UI 文案、Tauri command/capability、产品行为——升级只动版本号；编译/类型/测试挂时按最小必要修改适配，不顺道做产品改进。
- 不把
sqlx 单独升到 0.9——tauri-plugin-sql 当前主版本仍绑定 sqlx 0.8，两者共享 SqlitePool 类型，主版本错配会运行时崩溃。等 plugin 跟上或先解耦池类型。
- 不把工具链主版本混入安全批——Vite/TypeScript/pnpm 主版本属于 Batch D，混入会让"安全修复 PR"丧失快速合并和快速回滚的属性。
pnpm install 强制 CI=true——pnpm 11 在无 TTY 场景重建 node_modules 会等待交互输入而挂住，CI=true 关闭交互。
验证矩阵
按改动范围选最小充分集；没有本次会话的新鲜命令输出，不声称通过。
| 改动范围 | 验证命令 |
|---|
| 前端依赖 | pnpm audit --json、make lint-frontend、make build-frontend、make test-frontend |
| Rust 依赖 | make fmt-rust-check、make check、make lint-rust、make test-rust |
| Schemars / schema 契约 | cd src-tauri && cargo test schema_tests、make test-rust、make build-frontend |
| 跨语言收口 | make verify、make build、git diff --check、git status --short |
make verify 是本地全门禁；时间允许，每批结束都跑一次。
已知陷阱（截至 2026-05-24，使用前重新验证）
下列是过往升级踩过的具体事实。版本号会过时，再次升级前必须用"事实源"小节的命令重新查询。 若历史与当前输出冲突，信任当前输出并就地更新或删除条目。
pnpm@11.x 在本仓库可用（安装命令见"执行约束"）。- Vite 8 +
@vitejs/plugin-react 6 + TypeScript 6 可通过本仓库门禁；TS6 下需显式 Node types，并移除已弃用的 baseUrl，仅保留 paths alias。
schemars 1.x 弃用了 RootSchema.schema.object 访问路径；schema 契约测试改为 serde_json::to_value(schema_for!(...)) 后读取 properties / required。reqwest 0.13 使用 default-features = false 时，Rustls feature 是 rustls，不是旧的 rustls-tls。sqlx 0.8.x 仍与 tauri-plugin-sql 2.4.0 绑定（见"执行约束"）。
输出格式
按阶段输出对应结构。
规划阶段：
## 升级计划
事实源（当前命令输出）：
- pnpm outdated: <候选包数>
- pnpm audit: <漏洞数 by severity>
- cargo update --dry-run: <候选 crate 数>
Batch A — 安全/低风险：
- <pkg> <old> -> <new> (原因: CVE-XXXX / patch / ...)
Batch B — Tauri 栈：...
Batch C — 前端 UI：...
Batch D — breaking：
- <pkg> <old> -> <new> 风险：<点> 延后原因：<点>
每批验证命令：参考"验证矩阵"对应行
实施阶段（每批结束汇报）：
## Batch X 实施结果
改动文件：package.json / Cargo.toml / lock
版本变化：<pkg> <old> -> <new>
命令结果：<命令> -> <pass/fail，关键输出>
未完成 / 延后：<条目 + 原因>
复盘阶段：
- 漏洞修复状态（before/after by severity）
- 主版本风险与延后理由
- 锁文件是否完全由工具生成（绝无手改）
- 下次升级前需要先解决的耦合（如 sqlx/tauri-plugin-sql）
