一个技能包解决 AI 编程助手的 Flutter 迁移知识盲区

用 dart-sdk-skills一个开源的技能库，为Dart和Flutter SDK提供版本化的Agent Skill，使AI编码代理能够获取精确的迁移规则和操作手册。 给 AI 编程助手补课，一条命令迁移 Flutter 拆分包

核心洞察

先说结论：这次 Flutter 拆分包的迁移，麻烦全在 AI 的知识截止日期上。dart-sdk-skills 把官方 fix 规则和迁移手册打包成技能，等于给模型补上了没学过的课。我比较好奇这个仓库能跟多久，Flutter 版本一多，维护压力可不小。

Flutter 框架最近经历了一次大的架构调整：Material Design 和 Cupertino 库从核心 SDK 里拆了出来，变成独立的 pub 包，也就是 material_uiFlutter官方独立的Material Design组件库包，版本^1.1.0，规范入口为package:material_ui/material_ui.dart。 和 cupertino_uiFlutter官方独立的Cupertino（iOS风格）组件库包，版本^1.0.1，规范入口为package:cupertino_ui/cupertino_ui.dart。。

拆分带来的好处是独立的发布周期、更轻的核心框架，还有真正的 headless UI 开发。代价也摆在眼前：所有现有 Flutter 应用都要经历一轮大迁移。

如果你平时用 Claude Code、Google Antigravity、Cursor、GitHub Copilot 或 Cline 这类 AI 编程助手，多半已经撞上过同一堵墙：模型的知识有截止日期。大多数模型还在生成 package:flutter/material.dart 这种老式导入，拆分包迁移该怎么做，它们完全不知道。

这篇文章要聊的开源仓库 dart-sdk-skills，正好解决这个问题。它把迁移所需的知识和执行手册直接塞给 AI agent，让整个迁移在一个提示词里自动完成。

核心结论

1. Flutter 已将 Material Design 和 Cupertino 组件从核心 SDK 拆分为独立 pub 包：material_ui（^1.1.0）和 cupertino_ui（^1.0.1），规范入口分别为 package:material_ui/material_ui.dart 和 package:cupertino_ui/cupertino_ui.dart。

2. dart-sdk-skills 是一个按 Flutter/Dart 版本整理的 Agent Skill一种基于SKILL.md规范的知识打包方式，使AI代理能够渐进式地获取精确的规则、API矩阵和升级操作手册。 技能仓库，基于 SKILL.md 规范构建，专门解决 AI 编程助手因知识截止日期而不会迁移拆分包的问题。

3. 迁移流程的核心是使用 Dart 内置修复命令 dart fix --apply --code=migrate_design_widgets，同时项目需满足最低版本约束：Flutter >=3.44.0、Dart ^3.12.0。

4. 未安装该技能的 AI 助手通常会犯三类典型错误：凭空编造不存在的导入路径或包名、不知道 Dart 分析器内置数据驱动的自动修复规则、遗漏 GlobalMaterialLocalizations 等本地化委托的破坏性变更。

架构调整：为什么拆分包？

以前，Flutter 把所有 Material Design 和 Cupertino 组件都直接塞进核心 flutter SDK。一开始确实省事，问题也攒下不少：

1. 发布周期耦合。想更新一个 Material 按钮样式，得等整个框架发版。
2. 框架体积膨胀。做企业定制设计系统的应用，被迫打包几百个用不到的 Material 和 Cupertino 类。
3. 设计系统互相打架。混用两套平台风格时，依赖关系经常缠成一团。

新版解耦架构大概是这个样子：

旧版 Flutter（单体结构）
├── package:flutter/material.dart
├── package:flutter/cupertino.dart
└── package:flutter/widgets.dart

新版（解耦结构）
├── package:material_ui
├── package:cupertino_ui
└── Flutter 核心 SDK（package:flutter/widgets.dart）

两套设计系统现在由 Flutter 官方团队在 pub.dev 独立维护：

• material_ui（^1.1.0）：规范入口 package:material_ui/material_ui.dart
• cupertino_ui（^1.0.1）：规范入口 package:cupertino_ui/cupertino_ui.dart

AI 编码助手为何搞不定这次迁移

你直接跟一个没装技能的 AI agent 说："把我的应用迁移到新的 Flutter 拆分设计包。"

它通常会卡在几个地方：

• 凭空编造不存在的导入路径或包名。
• 不知道 Dart 分析器里已经内置了数据驱动的自动修复规则。
• 漏掉本地化委托（GlobalMaterialLocalizations）的破坏性变更。

Agent Skills 就是来填这个坑的。

dart-sdk-skills 是什么？

dart-sdk-skills 是一个按版本整理的 Dart 和 Flutter SDK 技能仓库，基于开放的 Agent Skill 规范（SKILL.md）构建。它把精确的规则、API 对照表和升级操作手册，按版本一层层喂给 AI。

安装 dart-sdk-skills，几秒钟的事

装到全局还是某个项目里都行，看你习惯用哪个工具。

通用安装（Node / npx skills）

# 全局安装，所有 AI agent 都能用
npx skills add RandalSchwartz/dart-sdk-skills -g

Dart Skills 命令行

skills add https://github.com/RandalSchwartz/dart-sdk-skills --global --all

Google Antigravity / 手动软链接

git clone https://github.com/RandalSchwartz/dart-sdk-skills.git ~/Projects/Dart/dart-sdk-skills
ln -s ~/Projects/Dart/dart-sdk-skills/skills/flutter-sdk-changelog ~/.gemini/config/skills/flutter-sdk-changelog

迁移流程：让 AI 去干活

装好之后，agent 会自动识别拆分包相关的请求。你只需要说一句：

"把项目迁移到新的 Material 和 Cupertino 拆分包。"

agent 会根据技能手册跑完一整条流水线。

1. 自动分析与数据驱动转换

agent 会调用 Dart 自带的修复工具：

dart fix --apply --code=migrate_design_widgets

这一步会更新引用，并应用 material_ui/lib/fix_data/ 里发布的数据驱动转换规则。

2. 依赖配置（pubspec.yaml）

agent 会确认项目的最低 SDK 约束满足要求（Flutter >=3.44.0，Dart ^3.12.0）：

dependencies:
  flutter:
    sdk: flutter
  # 独立设计系统
  material_ui: ^1.1.0
  cupertino_ui: ^1.0.1

3. 规范导入重写

agent 会把所有 Dart 文件里的单体导入替换成新的规范入口：

// 旧：单体导入
import 'package:flutter/material.dart';
import 'package:flutter/cupertino.dart';

// 新：独立包导入
import 'package:material_ui/material_ui.dart';
import 'package:cupertino_ui/cupertino_ui.dart';

4. 本地化委托绑定

material_ui.dart 和 cupertino_ui.dart 各自导出了对应的全局本地化委托，不需要再手动补胶水代码：

import 'package:flutter/widgets.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:material_ui/material_ui.dart';
import 'package:cupertino_ui/cupertino_ui.dart';

Widget buildApp() {
  return MaterialApp(
    localizationsDelegates: const [
      GlobalMaterialLocalizations.delegate,
      GlobalCupertinoLocalizations.delegate,
      GlobalWidgetsLocalizations.delegate,
    ],
    supportedLocales: const [
      Locale('en', 'US'),
      Locale('es', 'ES'),
    ],
    home: const HomeScreen(),
  );
}

5. 自动验证与质量门禁

最后 agent 会跑静态分析和测试，确认没有符号冲突或未解决的导入：

dart analyze --fatal-infos
dart test

彩蛋：构建纯 headless 应用

这次拆分还有一个额外好处：使用自研企业设计系统的 Flutter 应用，可以完全不用引入 material_ui 和 cupertino_ui。

直接基于 package:flutter/widgets.dart 搭 UI 层，体积更小，干干净净，一点设计系统的冗余都没有：

import 'package:flutter/widgets.dart';

class BrandButton extends StatelessWidget {
  final Widget child;
  final VoidCallback onTap;

  const BrandButton({
    super.key,
    required this.child,
    required this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Container(
        padding: const EdgeInsets.symmetric(horizontal: 20.0, vertical: 12.0),
        decoration: BoxDecoration(
          color: const Color(0xFF1E88E5),
          borderRadius: BorderRadius.circular(10.0),
        ),
        child: child,
      ),
    );
  }
}

现在就开始

拆分包架构是 Flutter 在可扩展性和模块化上的一个关键节点。给 AI 工作流配上 dart-sdk-skills，原本枯燥的手工重构就变成了一条命令的事。

• GitHub 仓库：github.com/RandalSchwartz/dart-sdk-skills
• material_ui 在 Pub：pub.dev/packages/material_ui
• cupertino_ui 在 Pub：pub.dev/packages/cupertino_ui

行了，让 agent 去干活吧。

常见问题（FAQ）

Flutter 拆分包迁移中 AI 编程助手为什么总出错？

因为模型知识截止日期早，不了解新包结构。dart-sdk-skills 提供官方 fix 规则和迁移手册，让 AI 掌握准确迁移知识。

dart-sdk-skills 安装后怎样自动迁移 Flutter 拆分包？

安装后，AI agent 会自动运行 dart fixDart工具链提供的自动修复命令，用于应用数据分析转换规则（如migrate_design_widgets）进行代码迁移。 --apply --code=migrate_design_widgets，更新导入并配置 material_ui 和 cupertino_ui 依赖。

dart-sdk-skills 迁移后还需要手动处理本地化委托吗？

不需要。material_ui.dart 和 cupertino_ui.dart 已导出全局本地化委托，只需在 MaterialApp 中配置 delegates 即可。