bloc-signals

用途

该技能用于处理使用 bloc_signals、bloc_signals_flutter 或 bloc_signals_otel 的 Dart 与 Flutter 代码，任务类型包括实现、审查、测试和调试。适用对象是 BlocSignalBase、BlocSignal、CubitSignal 等类型相关的工作。

BlocSignal 本身较新，API 可能在不同版本之间变化。资料要求：在修改代码前，先检查消费项目的 pubspec.yaml、lockfile、import 语句以及已安装的包源码。只有当项目跟随其当前分支，或任务本身针对该仓库时，才使用该仓库资料。

不应从 package:bloc、package:flutter_bloc 或 Riverpod 推断 API 对等性。BlocSignal 使用 signals，没有 state stream，也没有 provider 依赖图，并未实现源包的全部生命周期、谓词或 widget API。

主题文档路由

资料列出多个主题文件：decision_matrix.md（比较原生 Signals、CubitSignal、BlocSignal、Hydrate 与 Replay 的架构决策准则）、core.md（事件分发、相等性、错误、闭包、观察者与响应式所有权）、flutter.md（providers、builders、listeners、multi-listeners、consumers、selectors、context 扩展、无限滚动分页方案、flutter_hooks 集成、widget 所有权与派生 UI 状态）、testing.md（同步断言、确定性异步测试、zones 与 widget 测试）、migration.md（替换 bloc、flutter_bloc、bloc_concurrency、hydrated_bloc、replay_bloc 或 bloc_test 前阅读）、migration_bridge.md（Stream 与 Listenable 互操作桥）、riverpod_migration.md（替换 Riverpod providers、consumers、families、scopes 或生成声明前阅读）、interoperability.md（跨 BLoC、Riverpod 与 Provider 生态的通用状态桥）、hydration.md（持久化状态存储 bloc_signals_hydrate）、replay.md（撤销与重做状态追踪 bloc_signals_replay）、jaspr.md（Jaspr web component 集成 bloc_signals_jaspr）、devtools.md（VM Service RPC 扩展与 DevTools UI bloc_signals_devtools）、lint.md（分析规则与 IDE 诊断 bloc_signals_lint）、otel.md（OtelBlocSignalObserver、span 完成缺口与遥测数据选择）。资料要求只加载任务所需的引用。

工作流

确认确切的包版本与目标平台。
在修改前追踪当前的事件、状态、所有权与销毁路径。
对计划使用的每个类型或成员，检查已安装的公共 API。
做最小的连贯改动，保持现有用户行为。
格式化改动的 Dart 文件，运行范围内分析与最近的测试。
报告检查过的版本、运行的检查项，以及仍然不支持的源行为。

需要保持的约定

BlocSignalBase<State> 拥有状态与生命周期。公开方法用 CubitSignal<State>，事件分发用 BlocSignal<Event, State>。当类已继承现有父类（如 ChangeNotifier、TextEditingController 或 BaseRepository）时，使用 CubitSignalMixin<State> 或 BlocSignalMixin<Event, State>，并在构造函数中调用 initCubitSignal(initialState: ...)。

构造函数要求具名参数 initialState:，例如 super(initialState: initial)，而不是位置参数 super(initial)。

在方法或处理函数内读取原始 StateType 值，使用 value（推荐的现代 getter）或 stateValue（为向后兼容保留的永久别名），例如 emit(value + 1)。state 返回 ReadonlySignal<StateType>，用于响应式 signal 订阅。

emit 同步改变状态，并跳过与当前状态相等的值。

BlocSignal.add 返回 void。同步处理函数在它返回前完成。异步处理函数的 future 会被观察错误，但不会被 close 返回或取消。

on<E> 注册是运行时路由。重复的完全相同的类型会抛出 StateError；注册不提供 sealed class 的穷尽性检查。onEvent 覆盖必须调用 super.onEvent。

close 返回 Future<void>，销毁通过 createEffect 注册的 effect，并销毁内部 model。关闭后新事件会被丢弃。关闭后的 emit 在 debug 模式下断言，在 release 模式下返回且不更新状态。

不相等的状态转换在状态变更前运行。onChange 在变更后运行。两个本地钩子都需要 super；相等的 emit 不运行任何钩子。

BlocSignalProvider(create:) 默认惰性，拥有并关闭其 bloc。使用 lazy: false 可急切创建。BlocSignalProvider.value 不拥有其 bloc。BlocSignalProvider 与 BlocSignalListener 都支持可选 child 参数（Flutter 中默认为 const SizedBox.shrink()，Jaspr 中为 const _NullComponent()），从而在 MultiBlocSignalProvider 或 MultiBlocSignalListener 内无需占位 child 参数。

context.watch<T>() 追踪 provider 替换，而非状态变化。要因状态重建，应使用 BlocSignalBuilder 或某个 signals widget。

BlocSignalListener 会抑制其初始 effect 运行，并支持 listenWhen(previous, current)。它只把当前状态传给 listener 回调。

全局 BlocSignalObserver 是单一槽位。安装遥测观察者可能替换现有 logger，除非应用将它们组合。

BlocSignalBase 覆盖 toString() 输出 $runtimeType($stateValue)，让所有 CubitSignal 与 BlocSignal 子类都能直接获得诊断可见性。

计算属性优先使用带类型推断的内联 late final 字段声明（例如 late final itemCount = computed(() => stateValue.items.length);），而不是未初始化字段加构造函数体赋值。

在重负载下保障 Flutter 的 16.6ms/8.3ms 帧预算：使用 Isolate.run 做 CPU 计算，用 batch() 做多 signal 变更，以及通过 Stopwatch + Future.pause()（Dart 3.13+）或 Future<void>.delayed(Duration.zero)（Dart 3.5）做协作式时间切片。绝不要用事件循环延迟来等待状态转换稳定。绝不要在 Flutter build 方法中创建 effect 或 computed。保持其所有者与销毁路径明确。

限制

资料未提供收费、价格、平台、效果或官方外部文档链接等事实。以上内容均以资料中的说明为准，未展开的部分（如各主题文档的具体内容）暂未提供。

技能介绍

用途

相关 Signals 技能

主题文档路由

工作流

需要保持的约定

限制