用途：在 Flutter 项目中实现基于 Riverpod 3.x 的响应式状态管理，适用于定义 provider、构建 AsyncNotifier 以及覆盖 provider 进行测试等场景。
主要能力与约定：目标版本为 Riverpod 3.x；Notifier/AsyncNotifier 的代码生成接口与 2.x 一致，3.x 新增自动重试与退避、离线暂停/恢复，因此不要手写框架已提供的重试逻辑。推荐目录结构为 lib/providers 存放全局 provider 与服务，功能模块下设 providers 与 models（@freezed 领域模型）。
使用方式：所有 provider 使用 @riverpod 注解，优先代码生成，避免手写 Provider；状态模型用 Freezed 保证不可变。UI 使用 ConsumerWidget 配合 ref.watch() 与 AsyncValue.when() 响应变化。ref.watch() 在 build() 内使用以触发重建；ref.listen() 在 build() 内处理导航、弹窗等副作用，禁止在 provider 初始化中使用；ref.read() 仅用于 onPressed 等回调。测试时通过 ProviderScope(overrides: [provider.overrideWithValue(Mock())]) 覆盖 provider。建议启用 riverpod_lint 与 custom_lint 做循环依赖检测。
限制与反模式：provider 初始化中不得放副作用；Notifier 中不得传入 BuildContext；provider 应保持全局，避免动态创建局部实例。相关主题包括 flutter-layer-based-clean-architecture、flutter-dependency-injection、flutter-testing。具体实现示例与完整代码未在资料中提供。