一、用途 package-upgrade 用于前端项目的 npm 依赖升级前期分析。当你需要评估过期依赖、潜在破坏性变更,或制定分阶段升级计划时,可以调用该技能。它明确声明自身只做分析:不实施升级,调研结果也不构成修改依赖的授权。
二、主要能力
- 依赖盘点:查找工作区内的全部 package.json,包括根目录、apps/* 与 libs/*,记录框架版本、依赖与开发依赖,并按框架、UI、构建工具、测试、工具类等类别整理,汇总成主依赖清单。
- 使用情况分析:对每个依赖统计使用它的项目、导入文件数量、主要使用区域、相关配置文件,并据此标注升级风险等级。
- 版本与变更调研:以每 10 个依赖为一批,检索 npm 上的最新稳定版本、发布时间、下载量,以及迁移指南、破坏性变更和 CHANGELOG,并检查 peerDependencies 与生态兼容性。仅使用 npm、GitHub、官方文档等官方来源。
- 风险评估与排序:按落后主版本数量、是否为核心框架包、破坏性变更规模划分 Critical、High、Medium、Low 四级;升级顺序建议为基础设施(Node.js、TypeScript)、框架包、框架扩展、第三方库、开发工具。
- 报告生成:报告写入 tmp/reports/package-upgrade/ 目录,结构包含执行摘要、按项目划分的依赖清单、版本差距分析、破坏性变更目录、迁移复杂度评估、生态兼容性分析、分阶段升级策略、详细迁移指南、测试策略、回滚计划、时间与资源估算及附录。分析过程文件写入 tmp/analysis/frontend-package-upgrade-analysis.md。
- 审批与置信度声明:报告完成后需用户明确批准才继续;结束前声明整体置信度(High 90-100%、Medium 70-89%、Low 低于 70%),低于 90% 时请求用户核实特定依赖。
三、使用方式 在支持的运行环境中调用该技能,按其工作流依次执行六个阶段:依赖盘点、网络调研、风险评估与优先级、报告生成、审批门槛、置信度声明。技能要求执行前先用待办跟踪把工作拆成小任务,并要求每条结论引用 file:line 证据;行动门槛为置信度 80% 以上,低于 60% 不应给出建议,证据不足本身也是合法输出。文中还说明 Codex 兼容方式:通过加载已注册的 .agents/skills/<name>/SKILL.md 执行,无需单独的 Skill 工具或 Claude 模式切换。
四、适用场景 适合中大型前端单体或 monorepo 的依赖升级前期评估、跨多个主版本的迁移规划、需要向团队提交升级方案与工作量估算的场合。
五、限制 不执行实际升级或改依赖;仅针对 npm 生态前端依赖;调研依赖网络检索,结果需以官方来源为准;置信度不足时需人工核实;具体支持的宿主环境细节以源资料为准。