angular-migration

angular-migration 技能概览

angular-migration 实际能帮你解决什么问题

angular-migration 技能适合正在把现有 AngularJS 1.x 代码库迁移到现代 Angular 的团队，尤其是在“整库重写”风险过高的情况下。它的核心价值不只是“转换语法”，而是帮助你选定合适的迁移路径、在必要时搭建混合应用结构，并处理那些最容易卡住项目的衔接点：比如把 directives 改造成 components、把 AngularJS services 迁到 Angular DI，以及按路由逐步替换旧功能。

谁适合使用 angular-migration 技能

这个技能最适合已经拥有真实 AngularJS 应用、并且需要一条可执行迁移路径的前端工程师、技术负责人和迁移项目 owner。尤其当你需要解决以下问题时，它会很有用：

• 在 big-bang、hybrid 或 vertical-slice 迁移之间做选择
• 在迁移过程中持续发布新版本
• 将旧的 directives/controllers 重写为 Angular components 和 services
• 分阶段、安全地推进 routing 和 dependency injection 的改造

最适合使用 angular-migration 的迁移场景

当你的应用背着比较重的历史包袱时，就很适合使用 angular-migration：

• AngularJS 代码库规模较大，而且还在持续发布
• 存在共享 services 和 directives，无法一次性全部替换
• 过渡期内需要同时运行 AngularJS + Angular 的 hybrid runtime
• 你需要的是按功能分层的迁移规划，而不是抽象的框架建议

如果你只是要新建一个全新的 Angular 应用，那这个技能大概率有点大材小用。

为什么它比普通迁移 Prompt 更有用

一般的迁移 prompt 往往会直接跳到代码转换这一步。angular-migration 更适合解决真正难的部分：如何安排迁移顺序、如何启动 hybrid 模式、以及如何把旧 AngularJS 概念映射到 Angular 对应能力，同时又不打断现有交付流程。对大多数团队来说，这些才是真正阻碍落地的地方。

安装前你需要知道什么

这个技能的仓库很轻量：主要内容都在 SKILL.md，没有额外脚本、参考资料或辅助资源。好处是你可以很快看懂它的范围；但这也意味着它提供的是方法、模式和示例，而不是自动化工具。若你需要的是迁移决策支持和结构化思路，它值得安装；如果你想要的是开箱即用的 codemod，它并不适合。

如何使用 angular-migration 技能

angular-migration 技能的安装方式

按你常用的 Skills 工作流，把 angular-migration 安装到 agent 环境中即可。常见方式如下：

npx skills add https://github.com/wshobson/agents --skill angular-migration

由于这个技能本质上就是一个 SKILL.md 文件，安装的意义主要是让这些迁移指导能够在你的 agent 工作流里被直接调用，而不是拉取某种可执行工具。

先读这个文件

先看：

• SKILL.md

这个文件就是核心内容所在：包括何时使用该技能、迁移策略、hybrid 搭建方式，以及代码示例。因为这里没有额外的规则目录或资源目录，所以完整读一遍是现实可行的，而且在真正依赖它之前，值得先通读一遍。

这个技能需要你提供哪些输入

如果你提供的是具体仓库事实，而不是泛泛地要一个迁移方案，angular-migration 技能的效果会好很多。比较有用的输入包括：

• 当前 AngularJS 版本和应用规模
• 迁移期间是否必须持续发版
• 目前使用的 routing library
• 主要的 directive 模式
• DI/service 的使用模式
• build tooling 和测试现状
• 是否接受 hybrid runtime
• 目标 Angular 版本和迁移时间线

如果缺少这些信息，输出通常会停留在“大型应用建议选 hybrid”这种层面——这话没错，但不足以支撑实际决策。

如何把模糊目标改写成高质量 Prompt

弱 prompt：

• “Help migrate my AngularJS app to Angular.”

更强的 prompt：

• “Use the angular-migration skill to recommend a migration strategy for a 70k-line AngularJS 1.6 app with ui-router, 120 directives, and weekly releases. We need to keep shipping, can tolerate a hybrid app for 6 months, and want a phased route migration. Propose strategy, sequencing, first feature slice, DI conversion approach, and top technical risks.”

之所以这样效果更好，是因为这个技能最擅长的是规划迁移形态，而不是替你猜测约束条件。

一套实用的 angular-migration 使用流程

一套比较稳妥的 angular-migration usage 流程通常是：

1. 先判断应用类型：适合小规模重写，还是更适合 hybrid
2. 明确只选一种主策略：big bang、incremental hybrid，或 vertical slice
3. 划定迁移单元：routes、features、directives、services
4. 定义 AngularJS 与 Angular 之间需要哪些互操作能力
5. 先迁移一个范围足够窄的 feature
6. 验证 bootstrapping、DI 和 routing 的衔接是否稳定
7. 用一份稳定的迁移 checklist 重复推进后续部分

这样可以避免一个常见错误：过早把“策略讨论”和“底层代码重写”混在一起。

如何选迁移策略，才不会一开始就走偏

仓库重点强调了三种策略：

• Big Bang：更适合较小的应用，或者能够现实地并行重写的场景
• Incremental / Hybrid：更适合体量较大、且必须持续交付的应用
• Vertical Slice：更适合功能边界清晰、可以按端到端 feature 替换的场景

对大多数真实的历史遗留应用来说，hybrid 或 vertical-slice 往往才是更实际的答案。只有当业务和运维风险低于长期双栈共存带来的复杂度时，才值得考虑 big bang。

用 angular-migration 规划 hybrid 应用

angular-migration for Frontend Development 中最有价值的部分之一，就是 hybrid 规划。如果你打算使用 @angular/upgrade/static，可以让这个技能帮你梳理：

• bootstrap 顺序
• AngularJS/Angular 共存的边界
• downgraded/upgraded components 和 services
• 哪些共享依赖应该优先迁移
• 如何让 feature 团队在双栈共存阶段不中断开发

这恰恰是普通 prompt 最容易变得模糊甚至不安全的地方。

关于 directive、component 和 DI 转换的提问方式

你可以让这个技能处理更有针对性的转换，而不只是整库迁移计划。比较好的提问方式包括：

• “Map this AngularJS directive with isolate scope and link function into an Angular component design.”
• “Convert this AngularJS service registration pattern into Angular DI with provider scope guidance.”
• “Explain which controllers should become smart container components versus plain services.”

这种更聚焦的问题，通常比“把所有东西都转掉”更能产出可落地的结果。

routing 迁移建议怎么用

很多迁移方案最后都是在 routing 上失控。你可以用这个技能重点分析：

• 应该按 route 迁，还是按 feature 迁
• AngularJS router state 如何映射到 Angular routing
• 在 hybrid 模式下，如何隔离新旧 route 的归属
• guards、resolvers 和 data fetching 模式应该何时迁移

如果你的应用里有复杂的嵌套 states，记得在 prompt 里明确写出来。

用什么顺序读仓库，能最快判断值不值得装

如果你在评估 angular-migration install 是否值得，可以按这个顺序检查：

1. 看 SKILL.md 的 frontmatter，确认精确 scope
2. 看策略相关标题，确认是否覆盖你的迁移模式
3. 看 hybrid app 示例，判断是否和 UpgradeModule 相关
4. 看 directive、DI 和 routing 的转换部分，判断是否贴合你的场景

因为内容集中在一个文件里，所以这个技能很适合快速评估。

提升输出质量的实用技巧

想让 angular-migration 技能给出更有用的结果，可以这样做：

• 直接贴一个有代表性的 AngularJS directive 或 service，而不是玩具示例
• 说明发版约束和团队产能
• 重点问迁移顺序，而不只是最终架构
• 让它比较两种迁移路径的 tradeoff
• 让模型先标出高风险 legacy 模式，再提出代码改造建议

这样得到的内容，才更接近真实仓库评审里能直接拿来用的输出。

angular-migration 技能 FAQ

angular-migration 适合新手吗？

适合，但更偏向“有引导的规划”，而不是“无脑代劳式迁移”。新手可以借它理解不同策略选项和概念映射，但你仍然需要具备足够的 AngularJS 和 Angular 基础，去判断建议的架构和代码改造是否靠谱。

什么情况下不该用 angular-migration 技能？

以下情况建议跳过 angular-migration：

• 项目已经是现代 Angular
• 你只是要做 Angular 的版本升级
• 你需要自动化 code mods
• 应用规模非常小，重建显然比分阶段迁移规划更便宜

这个技能专门面向的是 AngularJS 到 Angular 的迁移过程。

angular-migration 技能能代替阅读 Angular 文档吗？

不能。它能显著缩短规划和概念转换的时间，尤其是在 hybrid 架构和分阶段迁移上。但涉及具体 API、版本兼容性和实现细节时，你仍然需要查 Angular 和 ngUpgrade 官方文档。

它比普通 LLM prompt 更好吗？

通常是的，前提是你的问题核心在于迁移结构，而不是一次性的代码翻译。angular-migration guide 给 agent 提供的是一个有边界的思考框架：如何选策略、如何搭 hybrid、如何做 component 转换、如何升级 DI、以及如何迁 routing。这样能显著减少泛泛而谈的建议，让输出更贴近真实迁移工作。

大型企业应用可以用 angular-migration 吗？

可以，而且这正是它最擅长的场景之一。大型应用通常更能从它对 incremental 和 hybrid 路线的强调中受益。只是你需要在 prompt 中明确组织层面的现实约束，比如发版节奏、共享库、团队边界和风险承受能力。

这个技能自带自动化或脚本吗？

不带。根据仓库结构来看，这里没有附带脚本、参考文件或辅助资源。它的价值在于迁移框架和示例，而不是可执行工具链。

如何提升 angular-migration 技能的使用效果

给技能提供架构事实，而不只是目标

想提升 angular-migration 输出质量，最快的方法就是提供真实系统形态，而不是只说目标。比如：

• module 数量
• route map
• directive 类型
• 共享 services
• 测试覆盖率
• build 约束
• 浏览器支持要求

只有知道哪些部分耦合得最紧，技能才能给出可信的迁移顺序建议。

明确要求输出采用迁移计划格式

如果你在提问时直接要求固定结构，结果通常会更好，比如：

• 推荐策略
• 为什么不选另外两种
• 前 3 个迁移 slices
• hybrid app 的前置要求
• DI 和 routing 改造点
• rollback 风险
• 每个 slice 的完成定义

这样更方便你拿去和工程团队或干系人一起评审。

常见失败模式：先要代码，再谈策略

一个很常见的错误，是在还没确定迁移边界之前，就先要求重写 component。这样往往会得到“看起来不错、实际上用不了”的输出。正确做法是先用 angular-migration 技能确定迁移顺序，再针对某个已选定的 slice 请求代码转换。

常见失败模式：把关键约束藏起来

如果你没有写明“必须每周发版”或“不能冻结产品开发”这类约束，技能很可能会给出更整洁、但现实中不可执行的方案。更好的 prompt 应该明确暴露：

• 交付压力
• 团队规模
• 可接受的 hybrid 持续时间
• 允许的 breaking changes
• 测试成熟度

这些信息会实质性地改变最终建议。

用前后对照示例提升 angular-migration 的效果

如果你是在请求具体转换帮助，最好同时提供：

• 当前 AngularJS 代码
• 期望的 Angular 风格或目标版本
• 你们本地的代码约定
• hybrid 模式下的兼容性要求

这样技能更容易保留原有意图，而不是生成一段“教科书式但不适合你仓库”的 Angular 代码。

第一轮输出后继续迭代

把第一版回答视为迁移框架，而不是最终方案。然后继续用后续问题细化，例如：

• “Revise for a 3-team setup with shared libraries.”
• “Change the recommendation if we cannot use ngUpgrade.”
• “Break the first feature slice into weekly milestones.”
• “Show the service migration risks before component migration.”

通常，正是通过这种追问，你才能把一个“还不错的方案”打磨成真正适配仓库的迁移计划。

如果输出太泛，优先改进哪些输入

如果你觉得 angular-migration skill 给出的内容还是太宽泛，可以按这个顺序补充输入：

1. 应用规模和发版模式
2. 已选定或初步倾向的迁移策略
3. 一个真实的 feature slice
4. 一个真实的 directive/service 示例
5. routing 和 DI 约束

按照这个顺序补充上下文，通常就足以让技能从泛化迁移建议，切换到更接近实际前端交付的操作性指导。