如何在Flutter开发中运用各种技能：开发者手册

技能的工作原理：渐进式展示

技能背后的实现机制非常简洁高效。代理并不会一开始就将所有指令都加载到上下文窗口中，而是先读取元数据，只有当真正需要执行某项任务时，才会加载详细的指令内容。

Flutter 的文档将这种机制称为“渐进式展示”，这与 Flutter 本身所采用的延迟加载机制类似。

这种设计有效地解决了一个实际问题：AI 代理的上下文窗口容量是有限的。如果每个技能在每次执行任务时都会加载全部内容，那么代理就会浪费大量的资源来处理无关信息。例如，在要求代理编写单元测试时，导航技能并不需要被加载到上下文中；而在设置路由规则时，测试技能也同样不需要被加载。

逐步披露信息的方式有助于让智能体始终保持对相关信息的关注。首先，智能体会为所有可用的技能生成简洁的元数据索引。当有任务出现时，它会利用这些元数据来确定哪些技能与当前任务相关，并仅加载这些技能的完整使用说明，而不会加载不相关的技能。这样一来，既能减少不必要的信息占用，又能确保智能体获得完成任务所需的详细指导。

这种逐步披露信息的机制意味着，你在项目中可以使用很多技能，而无需担心信息量会过度膨胀。拥有二十个技能并不会使开发成本增加二十倍；对于任何具体的任务来说，系统只会加载其中相关的那部分技能内容。

技能文件的构成结构

每种技能都遵循特定的结构格式。深入理解这一结构是编写有效技能描述的前提条件。

---
name: 技能名称（采用驼峰命名法）
description: 一份清晰、具体的描述，需要回答以下问题：这项技能涵盖哪些内容？在什么情况下应该使用它？哪些关键词表明当前任务需要这项技能？智能体在判断某项技能是否相关时，只会读取这一部分描述。
aliases: [其他名称]
sources: [聊天记录、代码]
---

# 技能标题

简要说明这项技能的作用及其存在的必要性。

## 第一主要章节

包含具体且可操作的规则内容。

## 第二主要章节

提供更多的规则、示例以及反例。

## 代码示例

通过具体的代码来展示相关模式。

前言部分的详细构成

---
name: Flutter文件组织结构
description: 用于组织和划分Flutter/Dart文件，同时确保StatefulWidget与State之间的关系得到保持。适用于创建、重构、拆分或重新组织Dart文件及类时。无论是在新建屏幕、组件、模型还是Bloc文件时，还是在修改现有文件的结构时，都可以使用这一规则。
aliases: [flutter-files, dart-organization]
sources: [聊天记录、代码]
---

name是项目中标识这项技能的唯一名称。它遵循驼峰命名法（用连字符连接小写字母），并且通常以所对应的开发平台或领域作为前缀（例如flutter-、dart-等）。智能体在进行分析时会使用这个名称来引用相应的技能，而CLI工具在管理技能时也会依赖这一名称。

description是整个文件中最为重要的字段。在智能体进行初步索引时，它会是唯一被读取的部分。如果描述写得不好，那么即使技能内容编写得非常详尽，也不会被加载出来。描述应该回答三个问题：这项技能涵盖哪些功能？在什么情况下应该使用它？有哪些具体的关键词或短语能够表明这项技能与当前任务相关？从示例中可以看出，描述中包含了“适用于创建、重构、拆分或重新组织文件时”这样的表述，同时还列出了各种文件类型；这些信息都是帮助智能体将任务需求与相应技能匹配起来的关键线索。

aliases为该技能提供了替代名称，代理可以使用这些名称来引用它。这些替代名称是可选的，但在某些情况下，当同一技能在不同场景下可能有不同的称呼时，它们会非常有用。

sources指明了这一技能的来源。对于自定义团队技能而言，其来源通常为[chat]；而对于来自第三方包作者的技能，其来源可能包括[package]等。

技能内容的结构

技能内容的编写采用纯Markdown格式，并遵循特定的结构规范，这样代理在阅读时就能更有效地理解其中的内容：

# 标题部分 (h1)
简要介绍该技能的背景信息。它解决了什么问题？为什么会被设计出来？
这部分内容应控制在三句话以内。

## 核心规则 (h2部分)
以编号或列表的形式列出具体且可验证的规则。
每条规则都应当能够被独立执行。

## 具体子领域指南 (h2部分)
针对技能的某个特定子领域提供更详细的指导。
先说明错误的操作方式，再展示正确的做法。

代理通过标题结构来理解技能的内容组织方式。清晰明确的##标题能够帮助代理在更大的任务框架中找到与当前子任务相关的具体内容。

安装官方Flutter和Dart技能

Flutter和Dart团队维护着官方技能仓库，其中积累了多年来关于这些技术生态系统中最佳实践的知识。这些仓库就是你开始学习的起点。

安装Flutter技能

npx skills add flutter/agent-plugins --skill '*' --agent universal --yes

npx skills add命令通过npm运行skills命令行工具，无需进行永久性安装。flutter/agent-plugins是指Flutter团队维护官方Flutter技能的GitHub仓库路径。--skill '*'是一个通配符，它会从仓库中安装所有可用的技能，而不会只选择特定的几个。选项会将这些技能放置在.agents/skills/目录中，这是所有兼容代理都会查找的默认位置。--yes选项会跳过交互式确认提示，因此可以将这个命令添加到项目配置脚本或Makefile中。

运行这条命令后，你的项目将获得以下技能：响应式布局功能、使用GoRouter实现的声明式路由系统、使用json_serializable进行的JSON序列化处理、集成测试设置工具、组件预览功能、组件测试工具，以及遵循BLoC和Clean Architecture原则的架构最佳实践、Bloc状态管理机制、Bloc表单设计等。

安装Dart相关技能

npx skills add dart-lang/skills --skill '*' --agent universal --yes

Dart团队维护了一套专门针对Dart语言本身的技能工具，这些工具与Flutter的组件系统无关。对于Flutter应用程序以及纯Dart项目来说，这些技能都非常有用——无论是CLI工具、后端服务还是其他包文件。

官方提供的Dart技能工具包括：单元测试生成、静态分析配置、包依赖管理、模式匹配与密封类处理、CLI应用程序的开发、测试覆盖率的收集与分析、利用LSP修复运行时错误、使用Mockito生成模拟对象、通过ffigen进行FFI绑定、为C/C++集成准备原生资源、优化Dart程序的内存使用，以及将旧的测试断言方式迁移到现代的package:checks标准。

一次性安装两者

npx skills add flutter/agent-plugins dart-lang/skills --skill '*' --agent universal --yes

如果在一条命令中同时列出这两个仓库的名称，系统会一次性将它们全部安装完毕，并完成依赖关系的解析过程，这样比分别执行两条命令要快一些。对于新创建的Flutter项目来说，这种安装方式是推荐的做法。

通过pubspec依赖关系来安装技能

技能工具生态系统最强大的特点之一就是：包开发者可以将这些技能工具与他们的软件包一起发布。作为Dart包提供的skills CLI工具能够自动检测并安装你项目中所有依赖包中包含的技能工具：

dart pub global activate skills
skills get

dart pub global activate skills这条命令会将skills CLI工具全局安装在你的机器上。skills get则会读取你的pubspec.yaml文件和pubspec.lock文件，找出所有依赖包中包含skills/目录的包，并自动将这些技能工具安装到你项目的.agents/skills/目录中。

当你向项目中添加一个新的包并运行skills get命令时，系统会立即根据该包开发者提供的说明来指导你如何正确使用这个包。这种设计方式从根本上改变了以往的情况：不再是系统去猜测包的功能，而是包开发者直接为系统提供了正确的使用方法。

# 每当依赖关系发生变化时，及时更新技能工具
flutter pub get
skills get

运行flutter pub get命令可以更新你的项目依赖关系，而紧接着运行skills get命令则能确保技能工具与新的依赖关系保持一致。养成这种两步操作的习惯，就能保证你的系统始终使用的是与当前依赖关系相匹配的最新技能工具。

验证已安装的技能工具

ls -la .agents/skills/

ls -la .agents/skills/ 命令会列出所有已安装的技能文件及其详细信息。你会看到每个已安装的技能都会对应一个以 .md 为扩展名的文件。-la 参数会显示隐藏文件以及包括文件大小和修改日期在内的详细信息。

安装完成后，测试你的智能体是否能够识别这些技能：

我安装的这些技能中，哪些可以帮助我创建一个新的功能界面？

智能体会列出与这个任务相关的技能，从而确认这些技能已经被正确加载并索引到了系统中。每当你向项目中添加新的技能时，这个测试都是非常有用的。

在 Claude Code 中使用技能

Claude Code 是 Anthropic 开发的一款智能编码助手，可以在终端中运行。它是非常强大的工具，特别适合处理复杂的多步骤 Flutter 开发任务，并且对技能标准也提供了很好的支持。

为 Claude Code 安装 Flutter 插件

推荐的做法是安装完整的 Flutter 插件，因为该插件会将技能与 MCP 服务器配置捆绑在一起：

claude mcp add flutter-mcp -- dart pub global run dart_mcp_server
npx skills add flutter/agent-plugins --skill '*' --agent claude-code --yes
npx skills add dart-lang/skills --skill '*' --agent claude-code --yes

claude mcp add flutter-mcp 命令会将 Dart MCP 服务器注册到 Claude Code 中。MCP 服务器可以让 Claude Code 直接访问 Flutter 的文档、pub.dev 上的包信息以及 Dart 开发工具，而无需进行网络搜索。--agent claude-code 参数确保技能会被存储在 Claude Code 专用的目录中（如果该目录与通用的 .agents/skills/ 目录不同的话）；不过 Claude Code 也会从通用目录中读取技能信息。

Claude Code 的技能目录结构

Claude Code 会自动从 .agents/skills/ 目录中读取技能信息。如果你希望将 Claude 特有的技能与通用技能分开存储，也可以将其保存在 .claude/skills/ 目录中。

your_project/
  .agents/
    skills/
      flutter-file-organization.md    <- 通用目录，适用于所有场景
      flutter-bloc-state-management.md
  .claude/
    skills/
      claude-specific-workflow.md     <- 仅适用于 Claude Code
    CLAUDE.md                         <- Claude Code 的规则文件

Claude Code 的规则与技能

Claude Code 会使用位于项目根目录下的 CLAUDE.md 文件作为规则文件：这些规则是适用于整个项目的通用指令，无论执行什么任务，这些规则都会被正确应用。

# CLAUDE.md 示例

这是一个名为 Kopa 的 Flutter 应用程序，它是一种个人预算管理工具。

## 技术架构
- Flutter 3.47，搭配 Dart 3.10
- 状态管理：flutter_bloc ^9.0.0
- 导航系统：go_router ^14.0.0
- 数据层：使用 firebase_ai ^2.0.0来实现人工智能功能
- 序列化：采用 freezed 和 json_serializable
- 测试工具：bloc_test、mocktail

## 包名
com.example.kopa

## 最低运行要求
Android API 24，iOS 15

## 项目结构
采用以功能为导向的设计架构。具体结构详情可参考“flutter-feature-architecture”相关内容。

CLAUDE.md 文件中记录了项目中一些不会随任务变化而改变的信息，例如应用程序名称、所使用的包、SDK版本以及最低平台要求。而“技能”部分则介绍了如何使用这些包以及如何正确组织代码的相关知识。

在 Claude 代码会话中使用技能

一旦安装了所需的技能，Claude Code 会自动使用它们，无需手动调用。例如，当你提出如下请求时：

创建一个使用 Bloc 状态管理、从 Firestore 获取数据的用户资料功能模块，并设计一个能够显示加载状态、数据内容以及错误信息的界面。

Claude Code 会检测到这个请求涉及多个技能领域（功能架构设计、Bloc 状态管理、文件组织结构，可能还包括主题设置和错误处理），然后加载相应的技能文件，并生成符合你们团队编码规范的代码。

你也可以明确指定需要使用的技能：

利用“flutter-bloc-state-management”技能来实现购物车功能模块中的 CartBloc 逻辑。

通过明确指定技能名称，可以确保 Claude Code 一定会加载该技能，而不会自动选择其他替代方案。

结合 Antigravity 使用技能

Antigravity 是谷歌开发的人工智能编码助手，它与 Flutter 生态系统深度集成，并由 Flutter 团队共同开发。Antigravity 对代理技能提供了全面的支持，也是经过官方 Flutter 技能测试最为完善的辅助工具之一。

安装 Antigravity 的 Flutter 插件

为 Antigravity 手动安装技能
如果您更喜欢手动安装，或者需要添加自定义的团队技能，可以按照以下步骤操作：
npx skills add flutter/agent-plugins --skill '*' --agent antigravity --yes
npx skills add dart-lang/skills --skill '*' --agent antigravity --yes

--agent antigravity这个选项指定了Antigravity专用的技能目录；不过Antigravity也会从通用的.agents/skills/目录中读取技能信息。
使用技能构建Antigravity工作流程
Antigravity支持“工作流程”，这种预定义的任务序列能够引用各种技能。您可以为常见的团队任务创建相应的工作流程：
# .antigravity/workflows/new-feature.md

## 创建新的功能开发工作流程

需要使用的技能：flutter-feature-architecture、flutter-bloc-state-management、flutter-testing、flutter-file-organization

步骤：
1. 创建相应的项目文件夹结构。
2> 使用Freezed框架构建领域模型。
3> 设计并实现仓库接口。
4> 创建包含事件和状态的Bloc组件。
5> 设计屏幕界面对应的Widget组件。
6> 提取可重用的组件代码。
7> 为仓库编写单元测试用例。
8> 为Bloc组件编写`bloc_test`测试用例。
9> 为屏幕界面编写相应的测试用例。
使用技能来构建工作流程，能够确保代理在执行多步骤任务时始终遵循正确的操作规范。如果没有这种明确的关联机制，代理可能会在第一步中使用文件组织相关的技能，但在后续步骤中忽略测试相关的技能。
在OpenAI Codex中使用技能
OpenAI Codex是一款基于终端的智能编码辅助工具，其功能与Claude Code类似。它可以在您的终端环境中运行，并针对您的代码库执行多步骤任务。
为Codex安装所需技能
npx skills add flutter/agent-plugins --skill '*' --agent codex --yes
npx skills add dart-lang/skills --skill '*' --agent codex --yes

--agent codex这个选项指定了Codex专用的技能目录。不过Codex也会从通用的.agents/skills/目录中读取技能信息，因此--agent universal选项也同样适用。
Codex规则文件
与Claude Code的CLAUDE.md文件类似，Codex也会从项目根目录下的AGENTS.md文件中读取配置信息。您需要将这个文件与相关的技能配置一起进行设置：
# AGENTS.md

Flutter项目：Kopa预算管理应用
所使用的技术栈：flutter_bloc、go-router、firebase_ai、freezed
开发架构：以功能为导向，采用清晰的设计结构
测试框架：bloc_test + mocktail
AGENTS.md是整个项目共用的配置文件，Codex会在执行每项任务时都会读取这个文件。请保持文件内容简短，一般5到15行即可，主要说明项目中最重要的信息。详细的操作规范应该放在具体的技能配置文件中，而不是AGENTS.md里，因为技能配置文件是按需加载的，而AGENTS.md文件则会在整个项目启动时就被一次性读取完毕。
关于Codex插件的安装说明
目前，Codex插件无法自动合并规则文件。这意味着，从flutter/agent-plugins安装Flutter插件后，虽然相关技能会被添加进来，但系统不会自动生成AGENTS.md文件。
在完成插件安装后，需要手动创建这个文件。Flutter官方文档提供了适用于Flutter项目的AGENTS.md文件模板。
如何在Cursor中使用这些技能
Cursor是一款基于VS Code开发的人工智能代码编辑器。它将代理功能直接整合到了编辑体验中，并通过其规则系统以及通用的.agents/skills/目录来支持各种技能。
如何在Cursor中安装这些技能
npx skills add flutter/agent-plugins --skill '*' --agent cursor --yes
npx skills add dart-lang/skills --skill '*' --agent cursor --yes

Cursor会从.agents/skills/目录中读取相关技能信息。添加--agent cursor参数可以确保这些技能能够被Cursor的正确识别和加载。
Cursor与规则文件的集成
Cursor会使用.cursorrules目录（在较新版本中则是.cursor/rules/目录）来存储针对整个项目的规则设置，这与Claude Code中的CLAUDE.md文件的作用类似。
# .cursor/rules/flutter.mdc

---
description: 适用于所有Dart文件的Flutter项目规则
globs: ["**/*.dart", "pubspec.yaml"]
alwaysApply: true
---

这是一个使用flutter_bloc、go_router和freezed框架的Flutter项目。
所有的状态管理都采用了Bloc模式。
文件夹结构清晰，以功能为导向进行设计。
具体规则细节请参见 `.agents/skills/` 目录。
globs: ["**/*.dart"]这一设置确保只有在对Dart文件进行编辑时才会应用这些规则，从而避免在编辑Markdown文件或配置YAML文件时加载不必要的Flutter规则。alwaysApply: true则保证了每当相关文件被打开时，这些规则都会被自动执行。
在规则描述中引用.agents/skills/目录是有意为之的——这样可以让代理直接从该目录中获取所需的技能实现细节，而无需让规则文件变得过于冗长。
如何在Cursor中结合Composer、Chat和技能使用
在Cursor的Composer多文件编辑模式下，描述任务时相关技能会自动被加载；而在Cursor的Chat内嵌助手中，则可能需要更明确地指定所需技能：
@flutter-file-organization 创建一个新的PostCard组件
该组件是从帖子列表界面提取出来的
在Cursor的Chat功能中，@前缀可以在某些配置下根据技能名称来直接调用相应技能；而在其他情况下，只要详细描述任务内容，代理就能自动加载相应的技能。
在其他代理中使用技能
GitHub Copilot CLI
当以代理模式运行时，GitHub Copilot CLI支持通用的.agents/skills/目录（例如执行gh copilot explain和gh copilot suggest命令）：
npx skills add flutter/agent-plugins --skill '*' --agent copilot --yes

根据skills CLI的文档说明，使用skills get命令时，GitHub Copilot并不会被自动检测到；因为.github/目录通常还有其他用途。因此，在为Copilot安装技能时，务必使用明确的--agent copilot参数。
Gemini CLI
Google的Gemini CLI也支持通用的技能目录：
npx skills add flutter/agent-plugins --skill '*' --agent gemini --yes

通用安装方式
如果你希望一次性安装所有适用于各种代理的技能，可以执行以下命令：
npx skills add flutter/agent-plugins --skill '*' --agent universal --yes
npx skills add dart-lang/skills --skill '*' --agent universal --yes

使用universal代理选项时，技能会被保存在.agents/skills/目录中，所有兼容的代理都会自动识别这些技能。对于那些需要同时使用多种代理或希望不受代理类型限制的团队来说，这种设置是推荐的默认方案。
验证技能识别功能
无论你使用的是哪种代理，都可以通过向该代理提出一个自然语言问题来验证其是否能够正确识别这些技能：
请总结一下您为当前项目准备的这些技能所具备的功能。
如果代理配置正确，它会列出已安装的技能及其描述，从而证明技能识别功能是正常的。如果代理提示它没有找到任何技能，或者无法识别这些技能，请检查以下内容：

项目根目录下是否存在.agents/skills/目录
该目录中是否包含含有有效YAML格式前置内容的.md文件
所使用的代理是否支持通用的技能识别规范

官方Flutter技能介绍：深入解析
官方的Flutter技能仓库（flutter/agent-plugins）中收录了一组技能，这些技能体现了Flutter团队在常见开发模式上的最佳实践。了解每项技能的具体功能，有助于你决定应该安装哪些技能，哪些技能需要自定义，以及哪些技能可以通过自己开发的代码来补充。
flutter-responsive-layout
这项技能教会代理如何构建能够在移动设备、平板电脑和桌面电脑上正确显示的布局。它涵盖了AdaptiveScaffold、LayoutBuilder、MediaQuery、Breakpoints等概念，以及Flutter自适应框架推荐的处理不同屏幕尺寸的方法。
如果没有这项技能，开发人员构建出的布局在某一种设备上看起来很正常，但在其他设备上就会出问题。而掌握了这项技能后，开发人员就能从第一行代码开始就实现响应式布局设计，他们会使用Flutter特有的工具来进行开发，而不是依赖硬编码的像素阈值。
flutter-declarative-routing
这项技能会教授如何配置GoRouter、定义路由规则、实现嵌套导航功能、处理认证过程中的重定向逻辑、配置深度链接，以及如何在不同路由之间传递类型化的参数。
如果没有这项技能，开发人员即使在使用GoRouter的代码库中，也常常会使用Navigator.push这种方法；他们还经常搞错深度链接的实现方式，并且难以掌握GoRouter所要求的类型化参数传递机制。
flutter-json-serialization
这项技能会教授如何使用json_serializable和freezed这些工具：如何添加注释、运行build_runner命令、创建fromJson/toJson方法、处理可空字段，以及如何使用@JsonKey来实现字段名称与序列化数据之间的映射。
如果没有这项技能，开发人员就不得不手动编写序列化代码，或者在整个数据层中使用Map这种数据结构，这样一来，当字段名称发生变化时，代码就会出现故障。
flutter-add-widget-test
这项技能会教授如何使用testWidgets、WidgetTester这些工具，以及各种测试策略（如pump、pumpAndSettle、pumpWidget），如何查找特定的 widgets（通过find.text、find.byType、find.byKey等方法），如何模拟用户手势，以及如何为Widgets构建简洁但功能完备的测试环境。
flutter-add-integration-test
这项技能会教授如何在设备上、网页浏览器中或Firebase Test Lab环境中设置并运行端到端的集成测试。它涵盖了测试环境的配置、IntegrationTestWidgetsFlutterBinding的使用方法、应用程序的启动顺序，以及如何在测试过程中与已经运行的应用程序进行交互。

flutter-bloc
这项技能会全面讲解Bloc开发模式：如何定义事件、状态以及Bloc类，如何为Bloc提供BlocProvider，如何使用BlocBuilder、BlocListener和BlocConsumer来使用Bloc对象，以及如何使用bloc_test工具来进行测试。

flutter-apply-architecture-best-practices
这项技能会帮助开发人员按照Flutter官方推荐的BLoC模式来遵循“清晰架构”原则（包括数据层、业务逻辑层和用户界面层的划分），它会明确各层次之间的边界、依赖关系规则，以及代码仓库的构建方式。
flutter-add-widget-preview

这项技能会介绍Flutter 3.47版本中引入的Widget预览功能，包括如何使用@Preview注释、如何搭建预览环境，以及如何为复杂的Widgets编写有用的预览代码。
官方Dart技能详解
Dart团队的官方技能仓库（dart-lang/skills）主要涉及Dart语言本身，而非Flutter的组件系统。这些技能适用于任何Dart代码：包括Flutter应用程序逻辑、Dart命令行工具、Dart后端服务以及各种Dart包。
dart-add-unit-test
这是最基础的Dart技能，也是具有最直接实用价值的技能。它教会开发人员如何为任何Dart类编写正确的单元测试，具体内容包括：

设置test/目录，使其结构与lib/目录相同

使用描述性名称来编写group和test块

利用setUp和tearDown进行测试生命周期管理

正确使用expect及相应的匹配器


通过mocktail模拟依赖关系


使用expectLater及流式匹配器来测试异步代码



如果没有掌握这项技能，开发人员编写的测试可能会检测错误的内容，使用错误的断言方式，而且测试文件的结构也会与源代码结构不一致。而掌握了这项技能后，开发人员从第一次开始就能编写符合package:test规范的测试代码。
# dart-add-unit-test的主要内容

## 测试文件的存放位置
test/features/profile/data/profile_repository_test.dart
mirrors
libfeatures/profile/data/profile_repository.dart

## 测试用例的命名规则
```
group('ProfileRepository', () {
  group('getProfile', () {
    test('当API调用成功时，该方法应返回ProfileLoaded', () async {
      // ...
    });

    test('当连接失败时，该方法应返回NetworkFailure', () async {
      // ...
    });
  });
});
```

## 异步代码的测试方法
```
await expectLater(
  repository.getProfile('user123'),
  completion(isA<Right<AppFailure, UserProfile>>>()),
);
```

dart-run-static-analysis
这项技能教会开发人员如何使用Dart的静态分析工具：配置analysis_options.yaml文件，运行dart analyze命令，应用dart fix --apply命令，理解代码检查规则，正确处理误报情况，并强制执行严格的类型检查。

# dart-run-static-analysis涵盖的内容

## configuration文件analysis_options.yaml的配置方法
include: packageflutter_lints/flutter.yaml

analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  exclude:
    - '**/*.g.dart'
    - '**/*.freezed.dart'

linter:
  rules:
    avoid_print: true
    prefer_final_fields: true
    require_trailing_commas: true

## 如何正确处理误报
// ignore: avoid_print  <- 仅针对单行代码中的误报
// ignore_for_file: type=lint  <- 仅针对生成的测试文件中的误报
正确配置`analysis_options.yaml`是那些经常需要人工操作却容易出错的环节之一：人们可能会启用错误的规则，忘记排除生成的文件，或者过于宽泛地抑制诊断信息。掌握这项技能就能确保配置从一开始就是正确的。
dart-tooling
这项技能教会人们如何解决`pubspec.yaml`中包版本冲突的问题，如何正确使用依赖项覆盖规则，了解直接依赖与传递依赖之间的区别，以及如何通过阅读`pubspec.lock`文件来诊断版本匹配问题。
在包依赖管理方面，很多人常常会错误地判断包的版本，或者以掩盖实际冲突的方式设置`dependency_overrides`。掌握这项技能就能避免这些错误行为。
dart-use-pattern-matching
这项技能是Dart开发中极具价值的能力之一，因为Dart 3引入的密封类和模式匹配机制代表了一种全新的编程范式，而在Dart 3发布之前接受培训的开发者往往无法熟练运用这些技术。这项技能具体包括以下内容：

如何对密封类使用穷举式的switch表达式

如何在switch语句中运用解构模式

如何使用`when`关键字编写保护性代码

什么是记录模式

列表和映射模式的应用方法

如何在模式中正确使用通配符`_


// 使用dart-use-pattern-matching后代码示例

// 之前：传统的基于枚举的switch语句
switch (state) {
  case AppStateLoading:
    return CircularProgressIndicator();
  caseAppStateLoaded:
    return ContentWidget(data: data);
  default:
    return ErrorWidget();
}

// 现在：使用模式匹配的switch表达式（符合Dart 3的风格）
return switch (state) {
  AppStateLoading() => const CircularProgress(),
  AppStateLoaded(:final data) => ContentWidget(data: data),
 AppStateError(:final message) => ErrorWidget(message: message),
};

其中`AppStateLoaded(:final data)`这种解构模式是典型的Dart 3风格，代码结构也非常简洁。但那些没有掌握这项技能的开发者很少会使用它，因为旧版本的培训资料中并没有涉及这一内容。
dart-collect-coverage
这项技能教会人们如何收集测试覆盖率数据、生成LCOV报告和HTML报告，以及如何从覆盖率报告中过滤掉那些无法被有效测试的生成代码文件（如`*.g.dart`和`*.freezed.dart`），从而确保统计结果能够真实反映程序的实际覆盖情况。
dart-generate-test-mocks
这项技能介绍了如何使用`mockito`和`build_runner`工具，从接口和抽象类生成类型安全的测试模拟对象。它包括添加相应的注解、运行`dart run buildrunner build`命令，以及如何在测试中利用这些生成的模拟对象。
dart-fix-runtime-errors
这是一项程序性技能：它教会开发人员如何使用LSP（语言服务器协议）来获取当前的堆栈跟踪信息，定位出出现故障的代码行，应用相应的修复措施，并通过热重载来验证问题是否已经得到解决。对于在运行中的Flutter应用程序来说，这种处理方式才是纠正运行时错误的正确途径，而不是盲目猜测问题的原因。
dart-genkit
这项技能教授人们如何使用Genkit Dart SDK来构建基于人工智能的工作流程和开发工具。对于那些需要为Flutter应用程序添加人工智能功能的开发者来说，这一技能尤其具有实用性，它涵盖了流程定义、工具调用、模型选择以及数据流处理等相关内容。
dart-migrate-to-checks-package
这项技能指导人们如何将旧的package:matcher断言风格迁移到新的package:checks风格。新风格能够生成更清晰的错误信息，同时也更具可组合性。
// 旧风格 (package:matcher)
expect(result, isA>());
expect(result.getOrElse(() => null?).name, equals('Ade');

// 新风格 (package:checks)
check(result).isA>();
check(resultgetOrElse(() => null?).name).equals('Ade');

dart-memory
这项技能教授人们如何防止Flutter和Dart应用程序中出现内存泄漏现象，以及如何减轻垃圾收集带来的压力。它涵盖了StreamController的释放机制、AnimationController的处理方法、那些会阻碍垃圾收集发生的代码结构，同时还介绍了如何利用DevTools来识别内存相关的问题。
dart-build-cli-app
对于那些同时需要编写Dart命令行工具、后端脚本或进行部署自动化操作的Flutter开发者来说，这项技能会讲解入口文件的结构设计、如何使用package:args来解析命令参数、退出码的处理方法、子进程的管理技巧，以及跨平台脚本的开发规范。
dart-logic-patterns
这项技能涵盖了算法、数据结构，以及专门适用于Dart语言的业务逻辑组织模式：包括如何正确使用Iterable类中的各种方法，在不同场景下选择合适的List、Set或Map数据结构，实现高效的搜索和排序操作，以及如何高效地利用Dart提供的集合字面量。

Flutter文件组织技能：全面讲解
文件组织技能是所有Flutter开发者都应该掌握的一项基础能力，同时也是了解技能结构应该如何构建的绝佳范例。仔细学习这一技能，就能领悟到任何高效技能背后所蕴含的原则。
---
name: flutter-file-organization
description: 在维护EstadofulWidget与State之间的关联关系的同时，对Flutter/Dart文件进行合理的组织和拆分。适用于创建、重构、拆分或重新整理Dart文件及类的场景。
---

# Flutter文件组织规则

在创建、拆分、重构或重新整理Flutter/Dart文件时，请遵循以下规则。

## 核心规则

1. 在修改文件之前，先仔细检查其内容。
2> 明确所有类、枚举类型、扩展模块、混合组件、类型定义以及顶层声明的内容。
3> 在进行拆分操作之前，先确定这些声明之间的依赖关系。
4> 将每一个独立的主体类保存在单独的文件中。
5> 将紧密关联的声明视为一个整体，将它们放在一起处理。
6> 绝不要将`EstadofulWidget`与其对应的`State`类分开。
7> 在移动声明的位置后，及时更新所有的导入语句和引用关系。
8> 避免创建不必要的私有辅助类或方法。
9> 确保文件组织方式不会改变应用程序的功能。
10> 对修改后的Dart文件运行`dart format`命令进行格式化处理。
11> 运行项目的分析工具并执行相关的测试用例。
规则1（“在修改文件之前先检查其内容”）能够有效避免一种最为常见且代价高昂的错误：在不阅读文件内容的情况下就对其结构进行假设。
如果代理程序跳过了这一检查步骤，就可能会重复声明某些元素、破坏代码之间的依赖关系，或者引发与现有代码的命名冲突。将这一检查列为首要规则，可以确保代理程序始终能够基于当前文件的完整结构来执行后续操作。
规则2和规则3（“识别所有类”以及“确定各类之间的关系”）属于必须执行的预处理步骤。在代理程序开始处理文件的任何内容之前，它必须先弄清楚文件中存在哪些元素，以及这些元素之间是如何相互关联的。
这其实就相当于在代码重构过程中遵循“三思而后行”的原则，这样就能有效避免那些会破坏现有功能的重构操作。
规则6（“永远不要将 StatefulWidget类与其对应的State类分开”）体现了Flutter特有的编译规则。对于那些对Dart语言非常熟悉但并不了解Flutter框架的开发者来说，他们可能会误以为可以将某个文件中的所有类分别提取到不同的文件中，但实际上这样做会导致编译错误——因为 `_ProfilePageState` 类是通过 `widget` 属性引用 `ProfilePage` 组件的，而 `widget` 的类型是由 `State` 这个类型定义的，这两个类共同构成了一个不可分割的编译单元。因此，这一规则能够有效避免那些仅凭一般Dart知识就无法发现的编译错误。
规则10和规则11（“运行dart format命令”以及“执行项目的分析工具”）则确保了任务能够顺利完成。如果没有这些规则，代理程序在生成文件后会直接报告任务完成，但这样就会留下格式不一致的问题或分析工具提示的错误，需要用户后来再去发现并处理；而有了这些规则，代理程序会在报告完成之前先运行这两个工具，从而及时发现问题并进行修复。
## 组件提取规则

不要通过编写私有的 `_build...()` 方法来构建复杂的UI组件。

例如，不要这样做：

```
Widget _buildUserCard() {
  return Container(
    ...
  );
}
```

正确的做法应该是将这样的代码提取到一个公开的类中，并将其放在 `widgets` 或 `components` 文件夹中。
“组件提取规则”明确指出了应该避免的行为，详细解释了哪些做法是不被允许的，并通过具体的代码示例来消除任何可能产生的歧义，同时也告诉开发者应该如何正确地实现相同的功能。
在训练数据中，使用 `_build...()` 这种编写方式非常普遍（因为教程为了简化讲解常常会采用这种方式），因此如果只是简单地说“避免使用这种写法”，而没有给出具体的例子，就很难让开发者真正改掉这个习惯。而通过展示具体的错误代码示例，并将其与正确的实现方法进行对比，才能使这条规则变得清晰易懂。
## UI元素提取规则

不要将大量的UI元素放在同一个组件中。

在合适的情况下，应该将这些逻辑上相关的元素提取出来，制成可重用的组件。

例如：

- 头部导航栏
- 统计信息展示区
- 过滤栏
- 搜索框
- 列表显示
- 表格行
- 按钮
- 空状态界面
- 加载提示界面
- 表单元素
- 对话框内容

相比编写庞大的构建方法，使用小型、可重用的组件会更加高效。
“组件提取”部分中列出的示例都是基于实际经验总结得来的。这些就是在实际开发的Flutter应用程序中，会出现在屏幕部件内部的UI元素。阅读这份列表的智能体在检查代码时能够识别出这些模式，并知道应该如何提取它们。
如果没有这份列表，“提取逻辑组件”这个要求就过于模糊，无法确保智能体会做出正确的操作：智能体必须明确知道什么才算作“逻辑组件”。
## 代码注释

不要编写代码注释。

这条规则适用于所有地方和所有层次。
关于代码注释的规定之所以如此简洁，是因为它具有绝对性。“适用于所有地方和所有层次”这一表述也是经过深思熟虑后确定的。如果没有这种范围限定，智能体可能会误以为这条规则仅适用于当前文件的组织结构相关操作，从而在创建或修改其他文件时继续添加注释。明确的范围界定消除了歧义，使这条规则的意图在各种情况下都能被清晰理解。
编写自己的技能：完整指南
官方提供的技能模板是你的基础，但最有价值的技能往往是你自己编写的那些内容——它们体现了你自己在项目中总结出的具体模式、经验教训以及所遵循的标准。
编写技能所需的正确心态
为智能体编写技能与为人类编写文档是不同的。人类的文档依赖于共同的背景知识、隐含的理解能力以及提问的能力，而为智能体编写的技能必须表述得清晰明确、精确无误，并且不能假设读者已经掌握了技能文件中未包含的任何知识。
最优秀的技能来源于你对自己代码库的实际操作经验。记录下每次你手动修改由AI生成的代码的情况吧——每一次这样的修改其实都构成了一个技能规则。当你向新团队成员解释某种编程规范时，这种解释本身也属于技能内容；如果你在代码审查中连续三次遇到同样的错误，那么这个错误就需要被归纳为一种技能规则。
在编写任何规则之前，先问问自己：“如果一个不了解我的代码库的智能体看到这条规则，它知道该怎么做吗？”如果答案是否定的，那么这条规则就应该被纳入某个技能体系中。
描述：最重要的二十个字
描述字段起着至关重要的作用。请在完成技能内容的编写后再来填写描述部分，这样它才能准确反映该技能的实际覆盖范围。一个好的描述应该满足这样的标准：如果智能体只阅读描述内容，就能判断这个技能是否适用于某项任务。
# 不佳的描述：过于模糊，没有明确的触发条件
description: 如何在Flutter应用程序中处理状态管理。

# 更好的描述：具体明确，包含多个触发条件，范围界定清晰
description: 在Flutter应用程序中使用flutter_bloc来实现状态管理。
适用于以下场景：为屏幕添加状态管理功能、开发需要加载或显示错误状态的新增功能、从API获取数据、处理会改变用户界面状态的用户交互操作，或者实现BlocProvider、BlocBuilder、BlocListener或BlocConsumer等组件。
当你在某项任务中看到与“bloc”、“cubit”、“state”、“event”或“stream”相关的内容时，就可以参考这条描述。
第二种描述方式在几个方面更具优势。它列举了一些具体的触发场景（例如“创建那些会引发加载问题或出现错误的状态的新功能”），这些场景比笼统的“处理状态”更有可能与实际的任务描述相匹配。它还提到了相关包的API接口（如BlocProvider、BlocBuilder），因为这些信息很可能会出现在任务描述中。此外，它还列出了一些具有指示意义的关键词汇（如bloc、cubit、state和event）。
改变智能体行为的规则编写技巧
并非所有的规则都同样重要。那些只是要求智能体继续执行它原本已经在做的操作的规则，其实并无实际意义；而那些能够改变智能体行为方式的规则才真正具有价值。要想编写出能够改变智能体行为的规则，首先需要通过观察来分析问题：智能体究竟产生了哪些错误结果，以及哪条规则本可以防止这些错误的发生？
## 有效的规则与无效的规则

**无效的规则**（智能体本来就在尝试遵守这些规则）：
- 编写清晰、易读的代码。
- 遵循Flutter的最佳实践。
- 使用适当的状态管理机制。
- 保持代码库的可维护性。

**有效的规则**（这些规则能够改变智能体的具体行为）：
- 将任何长度超过30行的组件构建代码提取出来，放入`widgets/`目录下的单独类中。
- 在拥有对应BlocBuilder的组件内部，绝对不要调用`setState`方法。
- 将Bloc事件的名字命名为过去式动词，例如`ProfileLoadRequested`而不是`LoadProfile`。
- 将所有的Bloc相关文件（包括`.bloc`、`.event`和`.state`文件）放在功能模块内的`bloc/`子目录中。
- 使用`sealed`关键字来定义状态类，例如`sealed class ProfileState {}`。
- 在每个组件的构造函数中都必须指定`super.key`，例如`const MyWidget({super.key})`。
- 在任何异步方法中调用`setState`之前，必须先检查组件是否已经成功挂载。
需要注意的是，有效的规则通常会包含具体的数字（如30行代码）、特定的文件夹名称（如`widgets/`、`bloc/`）、明确的命名规范以及具体的代码结构。而像“编写清晰易懂的代码”这样的笼统要求，智能体本来就会尝试去遵守；而像“将Bloc事件的名字命名为过去式动词，并给出具体示例”这样的具体规则，才能真正改变智能体的行为结果。
反例模式
对于那些针对训练数据中常见模式的规则来说，仅仅通过文字描述这些规则是远远不够的；将错误的操作方式与正确的操作方式进行对比展示，会显得更加有效。因为在训练过程中，智能体已经见过成千上万的错误操作案例，单纯的文字说明可能无法改变它的行为习惯；而视觉上的对比则能让人清楚地理解规则的意图。
## 错误状态的命名规则

不要仅在错误状态的名字后面加上“Error”这个词。

不要这样做：

```
final class ProfileError extends ProfileState {
  const ProfileError();
}

应该包含错误的上下文信息：
final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}
在错误信息中包含操作名称（如Load），能够使错误信息明确对应于具体哪项操作出现了问题。当一个Bloc负责处理多个可能独立出错的操作时，这一点尤为重要。ProfileLoadFailure与ProfileUpdateFailure这样的错误代码具有明确的含义，而ProfileError与ProfileError2则不能这样区分。
反例后面的解释部分（“在错误信息中包含操作名称……”）将规则与其背后的原因联系起来，这有助于代理在特殊情况下正确应用这些规则，而不仅仅是机械地遵守规则的文字表述。
每个团队都应掌握的Flutter必备技能
根据AI代理在处理Flutter代码时最常出现错误的环节，以下是每个Flutter开发团队都应该掌握的必备技能。这些技能都已完整列出，你可以根据自己的实际需求进行调整使用。
Bloc状态管理技能
---
name: flutter-bloc-state-management
description: 使用flutter_bloc来实现状态管理。适用于创建新功能、为界面添加状态信息、从API获取数据、处理会导致加载或错误状态的用户交互操作，以及使用BlocProvider、BlocBuilder、BlocListener、BlocConsumer等组件进行状态管理，或者执行任何涉及状态转换的任务。
---

# Flutter Bloc状态管理

这个项目完全采用flutter_bloc来进行状态管理。除非有明确指示，否则禁止使用setState、ChangeNotifier、Provider或Riverpod等组件。

## 文件结构

任何需要状态管理的功能模块，都会在bloc/子目录下包含三个Bloc文件：
lib/
  features/
    profile/
      bloc/
        profile_bloc.dart      <- Bloc类及相应的处理方法
        profile_event.dart     <- 所有事件都被定义为密封类
        profile_state.dart     所有状态也被定义为密封类
      screens/
        profile_screen.dart
      widgets/
        profile_card.dart
      profile.dart              用于导出相关代码

密封类
为了实现对各种情况的全面处理，Dart允许使用密封类来定义事件和状态：
// profile_event.dart
sealed class ProfileEvent {}

final class ProfileLoadRequested extends ProfileEvent {
  const ProfileLoadRequested({required this.userId});
  final String userId;
}

final class ProfileUsernameUpdated extends ProfileEvent {
  const ProfileUsernameUpdated({required this.newUsername});
  final String newUsername;
}

// profile_state.dart
sealed class ProfileState {}

final class ProfileInitial extends ProfileState {}

final class ProfileLoading extends ProfileState {}

final class ProfileLoaded extends ProfileState {
  const ProfileLoaded({required this.profile});
  final UserProfile profile;
}

final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}
sealed class能够确保状态层次结构是完备的：Dart编译器可以验证switch语句中确实涵盖了所有可能的状态。而对于具体实现来说，final class能够防止出现意外的子类化行为。所有的状态和事件都是final且sealed的。

命名规范
Bloc类应该使用功能名称后加上Bloc作为后缀，例如ProfileBloc、AuthBloc或CartBloc。事件的名字则应采用过去分词形式的动词短语加上功能名称和Event后缀，比如ProfileLoadRequested或AuthLoginAttempted。状态的名字则应由功能名称再加上描述性的名词或形容词构成，例如ProfileInitial、ProfileLoading、ProfileLoaded或ProfileLoadFailure。
不要将事件命名为命令式名称（例如不要用LoadProfile，而应该使用ProfileLoadRequested）。错误状态也不应简单地称为ProfileError，而应该包含具体的操作信息，比如ProfileLoadFailure、ProfileUpdateFailure。
Block类
// profileBloc.dart
class ProfileBloc extends Bloc {
  final ProfileRepository _repository;

  ProfileBloc({required ProfileRepository repository})
      : _repository = repository,
        super(ProfileInitial()) {
    on(_onProfileLoadRequested);
    on(_onProfileUsernameUpdated);
  }

  Future _onProfileLoadRequested(
    ProfileLoadRequested event,
    Emitter emit,
  ) async {
    emit(ProfileLoading());

    final result = await _repository.getProfile(event.userId);

    result.fold(
      (failure) => emit PROFILE_LOAD_FAILURE(message: _mapFailure(failure)),
      (profile) => emit PROFILELoaded(profile: profile),
    );
  }

  String _mapFailure(AppFailure failure) => switch (failure) {
    NetworkFailure(:final message) => message,
    ServerFailure(:final message) => message,
    NotFoundFailure() => '未找到该资料',
    UnauthorizedFailure() => '请重新登录',
    _ => '发生了意外错误',
  };
}

每个事件处理方法都是一个以_on加上事件类名命名的私有方法。这种命名规则在所有的Bloc类中都是一致的。在异步操作开始之前，所有处理方法都会先发出“加载中”的状态信号；操作完成后，则会根据结果发出成功或失败的状态信号。没有任何处理方法会直接返回数据，所有的信息传递都是通过这些状态信号来完成的。
组件集成
class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key, required this.userId});
  final String userId;

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => ProfileBloc(
        repository: context.read(),
      )..add(ProfileLoadRequested(userId: userId)),
      child: BlocConsumer(
        listener: (context, state) {
          if (state is ProfileLoadFailure) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text(state.message)),
            );
          }
        },
        builder: (context, state) => switch (state) {
          ProfileInitial() => const SizedBox.shrink(),
          ProfileLoading() => const Center(child: CircularProgressIndicator()),
          ProfileLoaded(:final profile) => ProfileContent(profile: profile),
          ProfileLoadFailure(:final message) => ProfileErrorView(message: message),
        },
      ),
    );
  }
}
BlocConsumer结合了监听器（副作用）和构建器（用户界面）。对于那些被定义为“密封状态”的情况，switch表达式的覆盖范围是完备的：编译器会确保每种状态都对应着相应的用户界面。
禁止使用的模式
不要在任何拥有相应Bloc的小部件中使用setState方法。在initState方法内部，不要直接调用context.read().add(event)，而应该先使用addPostFrameCallback来延迟执行该操作。在进行await操作后，在没有检查mounted属性的情况下，也不要直接访问BuildContext。另外，不要在StatelessWidget.build方法内部创建Bloc对象（因为每次重新构建组件时，这个Bloc都会被重新创建）。

特性架构技能
---
名称：flutter-feature-architecture
描述：使用包含存储层、服务层和展示层的清晰架构来组织Flutter应用程序中的各个特性。适用于创建新特性、添加屏幕界面、实现数据获取功能、整理现有代码，或者确定新文件应存放在哪个目录中等涉及文件夹结构、层次划分或项目目录管理的任务。
---

# Flutter特性架构

这个项目采用了以特性为优先级的文件夹结构，并遵循清晰的架构设计原则。
顶层结构
lib/
  core/
    constants/     <- 全局常量，与特定特性无关
    errors/         <- AppFailure密封类层次结构
    extensions/     
    theme/          主题相关扩展、颜色代码及排版设置
    utils/          纯工具函数
  features/
    auth/
    profile/
    home/
    settings/
  shared/
    widgets/        在3个以上特性中共同使用的组件
    models/         多个特性之间共享的模型
    services/       被多个特性所使用的服务
  app.dart          MainApplication设置文件
  main.dart         程序入口点文件

特性文件夹结构
每个特性都遵循这样的内部结构：
features/
  profile/
    bloc/
      profileBloc.dart
      profile_event.dart
      profile_state.dart
    data/
      profile_repository.dart          接口层
      profile_repository_impl.dart     实现层
      profile_remote_data_source.dart
      profile_local_data_source.dart
    domain/
      profile_model.dart                冻结后的领域模型
    screens/
      profile_screen.dart
      edit_profile.screen.dart
    widgets/
      profile_card.dart
      profile_header.dart
      profile_stats_row.dart
    profile.dart                         最终输出的文件

层次依赖规则
<展示层（包括屏幕界面及各种组件）仅依赖于“Bloc”模型与相应的领域模型。而“Bloc”模型本身仅依赖于仓库接口，与其实现细节无关；仓库的实现方式则取决于所使用的数据源，而这些数据源往往需要借助外部库来实现，例如Firebase、HTTP或SharedPreferences等。>
切勿以错误的方向在不同的层之间导入数据。数据层永远不会从展示层导入数据；而领域层则不会从项目中的任何其他部分导入数据。
桶文件导出规则
每个功能模块都会对应一个桶文件，该文件仅用于导出该功能模块的公共API接口：
// features/profile/profile.dart
export 'domain/profile_model.dart';
export 'screens/profile_screen.dart';
export 'screens/edit_profile_screen.dart';
export 'bloc/profile_bloc.dart';
export 'bloc/profile_event.dart';
export 'bloc/profile_state.dart';

内部实现文件（如数据源代码、仓库实现逻辑等）不会被导出。使用这些文件的代码应该直接导入package:myapp/features/profile/profile.dart，而绝不应该使用嵌套的路径来导入。
核心文件夹规则
只有当一个文件被三个或更多的功能模块所使用时，它才应该被放在core/文件夹中；如果只有一个或两个功能模块使用了该文件，那么它就应该被放在这些功能模块对应的文件夹里。切勿仅仅根据文件未来可能被使用的场景就提前将其移放到core/文件夹中。
错误处理技巧
---
name: flutter-error-handling
description: 使用类型化的AppFailure类以及Either返回类型来实现错误处理。
适用于处理API调用、仓库方法产生的错误、Bloc模块中的错误状态，以及在数据源中捕获异常、显示错误提示界面、实现try-catch语句等涉及错误处理的各种场景。
---

# Flutter错误处理

该项目采用了一种类型化的错误处理机制。原始异常不会跨越不同的层进行传播。
AppFailure错误层次结构
// core/errors/app_failure.dart
sealed class AppFailure {
  const AppFailure();
}

final class NetworkFailure extends AppFailure {
  const NetworkFailure({required this.message});
  final String message;
}

final class ServerFailure extends AppFailure {
  const ServerFailure({required this.statusCode, required this.message});
  final int statusCode;
  final String message;
}

final class CacheFailure extends AppFailure {
  const CacheFailure({required this.message});
  final String message;
}

final class NotFoundFailure extends AppFailure {
  constNotFoundFailure();
}

final class UnauthorizedFailure extends AppFailure {
  const UnauthorizedFailure();
}

final class ValidationFailure extends AppFailure {
  const ValidationFailure({required this.field, required this.message});
  final String field;
  final String message;
}

sealed class AppFailure这一设计确保了错误处理层次的完整性。新的错误类型总是以final class的形式作为子类被添加进来；编译器会强制要求，针对AppFailure类型的switch语句必须能够覆盖所有可能的子类型。
仓库方法的返回类型
`fpdart`包中的仓库方法会返回`Either`类型的结果：
abstract class ProfileRepository {
  Future>> getProfile(String userId);
  Future>> updateUsername(String userId, String username);
}

返回`Either`类型可以明确表示可能发生失败的情况，而且这种失败会在类型层面就被体现出来。使用该仓库功能的代码开发者无法忽视这种失败的可能性，因为返回类型强制他们必须处理这两种情况。
数据源异常处理
数据源是唯一会使用`try-catch`结构的层。它们会捕获原始异常，并将其转换为`AppFailure`对象：
class ProfileRemoteDataSource {
  Future> getProfile(String userId) async {
    try {
      final doc = await _firestore.collection('users').doc(userId).get();

      if (!doc.exists) return left(const NotFoundFailure());

      return right(UserProfileDto.fromJson(doc.data()!));
    } on FirebaseException catch (e) {
      return switch (e.code) {
        'permission-denied' => left(const UnauthorizedFailure()),
        'unavailable' => left(NetworkFailure(message: e.message ?? '网络错误')),
        _ => left(ServerFailure(statusCode: 0, message: e.message ?? '服务器错误')),
      };
    } catch (e) {
      return left(NetworkFailure(message: e.toString()));
    }
  }
}

禁止使用的模式
不要在Bloc、仓库代码或展示层代码中使用`try-catch`结构。也不要从仓库方法中抛出异常。在状态类中，不要使用`String`类型作为错误信息；应该使用有类型的错误对象。不要将原始的异常信息直接传递给用户界面，在Bloc中应将异常情况转换为更易于用户理解的提示信息。
主题设计技巧
---
name: flutter-theming
description: 使用项目中的主题扩展系统来设置颜色、字体样式、间距以及视觉效果。在任何涉及颜色、文本样式、内边距、外边距、边框半径、阴影或UI组件外观的代码中，都应使用这一系统。当遇到与样式设计、颜色选择、字体格式、间距调整或视觉布局相关的问题时，也请使用这一方法。
---

# Flutter主题设计

该项目完全依赖主题扩展系统来进行所有视觉效果的设置。在代码库的任何地方都不允许使用硬编码的视觉参数值。
颜色访问方式
// 不要这样做
color: const Color(0xFF6750A4)
color: Colors.deepPurple
backgroundColor: Theme.of(context).colorScheme.primary

// 应该这样做
color: context.appColors(primary)
backgroundColor: context.appColors.surface

// 不要这样做：
padding: const EdgeInsets.all(16);
margin: const EdgeInsets_symmetric(horizontal: 24, vertical: 8);

// 而应该这样做：
padding: const EdgeInsets.all(AppSpacing.md);
margin: const EdgeInsets_symmetric(
  horizontal: AppSpacing.lg,
  vertical: AppSpacing.sm,
);

// 不要这样做：
style: constTextStyle(fontSize: 16, fontWeight: FontWeight.w600);

// 而应该这样做：
style: context.appTypography.bodyMedium;
style: context.app Typography.headlineLarge.copyWith(
  color: context.appColors.textPrimary,
);

// 不要这样做：
borderRadius: BorderRadius.circular(8);

// 而应该这样做：
borderRadius: BorderRadiusCircular(AppRadius.sm);

---
name: flutter-navigation
description: 使用 GoRouter 实现导航功能。适用于添加路由、在屏幕间切换、处理深度链接、设置路由守卫或重定向规则、处理需要身份验证的路由，以及处理嵌套导航或壳层导航等涉及导航的各种场景。
---

# Flutter Navigation

该项目使用 GoRouter 进行所有导航操作。请不要使用 Navigator.push、Navigator.pushNamed、Navigator.pop（这些方法必须通过 GoRouter 来调用），也不得使用任何绕过 GoRouter 的 Navigator API。

abstract class Routes {
  static const splash = '';
  static const login = '/auth/login';
  static const register = '/auth/register';
  static const home = '/home';
  static const profile = '/home/profile/:userId';
  static const editProfile = '/home/profile/:userId/edit';
  static const settings = '/settings';
}

// 替换当前位置（无法通过返回按钮回到上一个页面）
context.go(Routes.home);

// 将当前页面推到顶部栈帧（返回按钮会回到上一个页面）
context.push(Routes.profile.replaceAll(':userId', userId));

// 从栈顶弹出当前页面
context.pop();

// 带结果从栈顶弹出当前页面
context.pop(result);

final router = GoRouter(
  initialLocation: Routes.splash,
  redirect: _redirectLogic,
  routes: [
    GoRoute(
      path: Routes.home,
      pageBuilder: (context, state) => NoTransitionPage(
        child: const HomeScreen(),
      ),
    ),
    GoRoute(
      path: Routes.profile,
      builder: (context, state) {
        final userId = state.pathParameters['userId']!;
        return ProfileScreen(userId: userId);
      },
    ),
  ],
);

---
name: dart-models-freezed
description: 使用freezed包结合json_serializable创建不可变的数据模型。在创建新的数据模型、数据传输对象、请求或响应对象、值对象，或是任何用于表示结构化数据的Dart类时，都可以使用这种方法。它特别适用于处理JSON解析、API响应映射以及定义数据结构等场景。
---

# 使用freezed构建Dart模型

所有数据模型都会利用freezed包来实现不可变性并自动生成代码。

import 'package:freezed.annotation/freezed_annotation.dart';

part 'user_profile.freezed.dart';
part 'user_profile.g.dart';

@freezed
class UserProfile with _$UserProfile {
  const factoryUserProfile({
    required String id,
    required String name,
    required String email,
    String? avatarUrl,
    @Default(false) bool isVerified,
    required DateTime createdAt,
  }) = _UserProfile;

  factory UserProfile.fromJson(Map<String, dynamic> json) =>
      _$UserProfileFromJson(json);
}

dart run build_runner build --delete-conflicting-outputs

---
名称：Dart 模式匹配技巧
描述：使用 Dart 3 的模式匹配、switch 表达式以及密封类层次结构，来实现对控制流程的精确控制。这种技术适用于处理密封类、枚举类型、区分性联合体、基于类型的条件逻辑，或者任何可以用 switch 表达式替代的逻辑结构。在重构 if-else 语句链、处理多种子类型，或实现根据类型进行分支的业务逻辑时，这种技巧也非常有用。
---

# Dart 模式匹配

对于所有涉及类型判断、密封类层次结构或数据结构分解的控制流程，都应使用 Dart 3 的模式匹配功能。

// 不要这样做（传统的 switch 语句属于命令式编程风格）
switch (state) {
  case ProfileLoading():
    return const CircularProgressIndicator();
  case ProfileLoaded():
    return ProfileContent(profile: state.profile);
  case ProfileLoadFailure():
    return ErrorView(message: state.message);
  default:
    return const SizedBox.shrink();
}

// 应该这样做（switch 表达式属于函数式编程风格，适用于构建方法中）
return switch (state) {
  ProfileInitial() => const SizedBox.shrink(),
  ProfileLoading() => const CircularProgressIndicator(),
  ProfileLoaded(:final profile) => ProfileContent(profile: profile),
  ProfileLoadFailure(:final message) => ErrorView(message: message),
};

// 在模式中直接访问字段
case ProfileLoaded(:final profile) => ProfileContent(profile: profile),
// 等价于：
case ProfileLoaded() => ProfileContent(profile: state.profile),

return switch (state) {
  ProfileLoaded(:final profile) when profile.isVerified => VerifiedProfileView(profile: profile),
  ProfileLoaded(:final profile) => UnverifiedProfileView(profile: profile),
  _ => const LoadingView(),
};

// 对记录类型进行匹配
final (name, age) = getUserInfo();

// 在switch表达式中使用
final description = switch ((user.name, user.isAdmin)) {
  (final name, true) => '$name (Admin)',
  (final name, false) => name,
};

// 不要这样做
String label;
if (priority == Priority.high) {
  label = 'Urgent';
} else if (priority == Priority.medium) {
  label = 'Normal';
} else {
  label = 'Low';
}

// 应该这样做
final label = switch (priority) {
  Priority_high => 'Urgent',
  Priority.medium => 'Normal',
  Priority.low => 'Low',
};

---
name: dart-testing-conventions
description: 遵循package:test提供的规范来编写Dart单元测试，包括使用mocktail进行模拟测试、为测试用例和测试组指定描述性名称，以及采用正确的异步测试模式。无论是在编写新的测试文件、为现有文件添加测试用例、对依赖项进行模拟测试、测试异步函数，还是验证错误处理行为时，都应遵循这些规范。
---

# Dart测试规范

import 'packageflutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:myapp/features/profile/data/profile_repository_impl.dart';
import 'package:myapp/core/errors/app_failure.dart';

class MockProfileRemoteDataSource extends Mock
    implements ProfileRemoteDataSource {}

class MockProfileLocalDataSource extends Mock
    implements ProfileLocalDataSource {}

void main() {
  late MockProfileRemoteDataSource mockRemote;
  late MockProfileLocalDataSource mockLocal;
  late ProfileRepositoryImpl repository;

  setUp(() {
    mockRemote = MockProfileRemoteDataSource();
    mockLocal = MockProfileLocalDataSource();
    repository = ProfileRepositoryImpl(
      remote: mockRemote,
      local: mockLocal,
    );
  });

  group('ProfileRepositoryImpl', () {
    group('getProfile', () {
      test(
        '当远程数据源正常工作时，该方法应返回正确的结果',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => right(fakeProfileDto));

          final result = await repository.getProfile('user123');

          expect(result.isRight(), isTrue);
          expect(result.getOrElse(() => null)?.id, equals('user123'));
        },
      );

      test(
        '当远程数据源出现网络错误时，该方法应返回错误信息',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => left(NetworkFailure(message: '没有互联网连接');

          final result = await repository.getProfile('user123');

          expect(result.isLeft(), isTrue);
          expect(result.fold((f) => f, (_) => null), isA());
        },
      );
    });
  });
}

 setUpAll(() {
  registerFallbackValue(const ProfileLoadRequested(userId: ''));
  registerFallbackValue(left < AppFailure, UserProfile > (const NotFoundFailure()));
});

---
name: flutter-performance
description: 遵循Flutter的性能最佳实践，包括使用const小部件、有选择地重新构建组件、实现延迟加载机制，以及正确使用键值对。这些技巧适用于优化屏幕显示效果、处理列表数据、添加动画效果、处理图像相关操作，或任何与渲染性能、帧率或内存使用量相关的场景。
---

# Flutter性能优化

// 不正确的写法
class UserAvatar extends StatelessWidget {
  UserAvatar({super.key, required this.url}); // 缺少const关键字
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(  // 应该使用const关键字
      backgroundImage: NetworkImage(url),
    );
  }
}

// 正确的写法
class UserAvatar extends StatelessWidget {
  const UserAvatar({super.key, required this.url});
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(
      backgroundImage: NetworkImage(url),
    );
  }
}

// 对于长度可变的列表，请勿采用这种方式
ListView(
  children: items.map((item) => ItemCard(item: item)).ToList(),
)

// 正确的做法是这样写
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemCard(item: items[index]),
)

// 这种做法是错误的（任何状态变化都会导致整个子树被重新构建）
BlocBuilder〈CartBloc, CartState〉(
  builder: (context, state) => CartBadge(count: state is CartLoaded ? state.itemCount : 0),
)

// 正确的做法是这样写（只有当项目数量发生变化时才会重新构建）
BlocSelector〈CartBloc, CartState, int〉(
  selector: (state) => state is CartLoaded ? state.itemCount : 0,
  builder: (context, count) => CartBadge(count: count),
)

---
name: flutter-accessibility
description: 实现包括语义标签、焦点管理、对比度要求以及屏幕阅读器支持在内的无障碍功能。在创建交互式部件、图像、图标、表单字段或任何需要让残障人士能够使用的元素时，都应运用这些技术。在处理Semantics、ExcludeSemantics、Focus或FocusNode相关逻辑时，也需要参考这些内容。
---

# Flutter无障碍功能开发

TextFormField(
  decoration: const InputDecoration(
    labelText: '电子邮件地址',    // 屏幕阅读器会读取这一标签
    hintText: 'name@example.com', // 仅在字段为空时显示
  ),
)

SizedBox(
  width: 48,
  height: 48,
  child: IconButton(
    iconSize: 20,
    onPressed: _onClose,
    icon: const Icon'icon.close),
  ),
)

## 与上下文相关的规则

当某个组件发起网络请求时：
- 在请求执行期间，禁用所有交互式元素
- 根据当前的UI界面显示相应的加载指示器
- 使用用户能够理解的错误信息来处理错误
- 当请求完成时（无论结果是成功还是失败），重新启用所有交互式元素

当一个Bloc同时处理多个独立的操作时：
- 为每个操作创建单独的错误状态（而不是使用统一的Error状态）
- 每个错误状态的名称应与该操作相对应：例如ProfileLoadFailure、ProfileUpdateFailure

在创建用于ListView中的组件时：
- 必须为该组件提供一个键值对
- 在可能的情况下，使用const构造函数来定义组件
- 如果列表中的项目数量可能超过50个，可以考虑在列表层使用ListView.builder

## 相关技能

当使用该技能的规则提取组件时，还需应用
flutter-file-organization技能来确定正确的文件位置。

如果提取出的组件需要状态管理，应使用
flutter-bloc-state-management技能来判断它是否需要独立的Bloc状态管理结构。

在为使用该技能编写的代码编写测试时，需遵循
dart-testing-conventions规范来命名和组织测试用例。

Future _onSubmit() async {
  final result = await _repository.save(formData);

  // 错误做法：如果在等待操作期间组件被卸载，那么上下文信息可能会失效
  ScaffoldMessenger.of(context).showSnackBar(...);

  // 正确做法：先检查组件是否已挂载
  if (!mounted) return;
  ScaffoldMessenger.of(context).showSnackBar(...);
}

# 全局安装Dart skills命令行工具
dart pub global activate skills

# 安装项目中所有包含skills功能的包
skills get

my_design_system/
  lib/
    src/
      components/
    my_design_system.dart
  skills/
    my-design-system-components.md    <- 教导智能体如何使用你的组件
    my-design-system-theming.md       <- 教导智能体如何使用你的主题系统
  pubspec.yaml
  README.md

---
name: my-design-system-components
description: 使用MyDesignSystem组件库来创建UI元素。无论是需要按钮、卡片、表单字段、导航元素，还是任何视觉组件，都可以使用这个库。只要存在相应的设计系统组件，就应该优先使用它们，而不是原始的Material或Cupertino部件。
---

# MyDesignSystem组件的使用方法

只要有可替代的MyDesignSystem组件，就永远不要使用原始的Flutter部件。

## 可用的组件

DsButton可以替代ElevatedButton、TextButton和OutlineButton；
DsCard可以替代Card；
DsTextField可以替代FormField；
DsAvatar可以替代CircleAvatar；
DsChip可以替代Chip；
DsBottomSheet可以替代>ShowModalBottomSheet。

## DsButton的使用方法

`DsButton.variant`支持`primary`、`secondary`、`destructive`和`ghost`这几种样式。在加载组件时，可以传递`isLoading: true`参数来显示按钮的加载状态。

# .agents/skills/README.md (并非真正的技能文件，而是一个索引)

## Flutter相关技能
flutter-feature-architecture      -- Feature文件夹的结构及层次规则
flutter-bloc-state-management     -- Bloc事件、状态及组件集成方式
flutter-file-organization         -- 文件的划分、提取及命名规则
flutter-error-handling            -- 错误处理机制及返回类型
flutter-navigation                -- GoRouter路由配置、导航方法及深度链接处理
flutter-theming                   -- 设计元素、颜色设置及间距常量
flutter-testing                   -- 组件测试、Bloc相关测试及测试命名规范
flutter-accessibility             -- 语义标签、焦点设置及触摸交互功能
flutter-performance               -- 性能优化相关的组件与重建策略、列表处理技巧

## Dart相关技能
dart-models-freezed               -- 冻结模型、可序列化为JSON的数据结构、数据传输对象
dart-testing-conventions          -- 测试相关的规范、mocktail模拟框架、异步测试方法
dart-pattern-matching-idiomatic   -- Switch表达式、密封类及解构操作
dart-run-static-analysis          -- 静态分析工具及配置文件

# 描述中缺乏触发词的例子
description: 如何在Flutter项目中设置导航功能。

# 描述中包含丰富触发词的例子
description: 在Flutter应用中使用GoRouter来实现导航功能。适用于添加路由、在不同界面之间切换、配置深度链接、处理认证重定向、设置嵌套导航结构，或任何与Navigator、route、path、deep link、URL、back button或go_router包相关的操作。

# 这些规则并不会带来任何变化：因为代理程序本来就在努力遵循这些原则
- 编写清晰、易于维护的代码。
- 遵循Flutter的最佳实践。
- 选择合适的状态管理方案。
- 以逻辑清晰的方式组织文件结构。

# 这些规则会直接影响具体的行为：因为代理程序之前采取的是其他做法
- 将所有提取出来的组件类放在其所属功能文件夹的`widgets/`子目录中。
- 将`BlocEvent`的子类命名为过去式动词短语，例如`ProfileLoadRequested`而不是`LoadProfile`。
- 绝不要使用`Navigator.push()`；应使用`context.go()`或`GoRouter`中的`context.push()`方法。
- 除非某个组件构造函数的参数有默认值，否则都应将其标记为“必填项”。