legend-state

Legend-State

使用此技能处理 Legend-State v3 相关工作，包括核心可观察对象、React 或 React Native 集成、持久化、远程同步和迁移。

工作流

1. 修改代码前检查项目：
   • 阅读本地 Agent 指南和附近的状态管理约定。
   • 检查确切的 @legendapp/state 版本和包管理器锁文件。
   • 确认运行环境：原生 TypeScript、React Web、React Native、Expo、SSR 或混合应用。
   • 梳理可观察对象的归属和生命周期：模块单例、请求作用域、Provider 作用域、组件局部或同步资源。
   • 清点 React 使用方式（useValue、observer、Memo、$React、控制流组件）、持久化插件、同步插件和已弃用的 API。
2. 使用 v3 API 前确认发布渠道。版本 3 仍为预发布版（beta 标签为 3.0.0-beta.48），而 npm latest 仍为 v2（2.1.15）；请使用 @beta 或精确版本安装。先查看 references/source-map.md，然后在版本相关时更新当前文档和包元数据。
3. 对于可观察对象的创建、读写、计算或链接状态、响应性、数组、事件、批处理和辅助工具，请使用 references/core-observables.md。
4. 对于 React、React Compiler 兼容性、细粒度渲染、React Native、钩子、控制流、上下文和追踪，请使用 references/react-integration.md。
5. 对于本地持久化、远程同步、CRUD、重试、转换、插件、同步状态和本地优先的可靠性，请使用 references/persistence-sync.md。
6. 对于 v2 迁移、beta 版本差异、架构、安全、性能、SSR、调试和测试，请使用 references/production-migration-testing.md。
7. 遵循已安装的类型声明和项目现有风格。不要把 v2 示例复制到 v3 代码中，也不要假设 v3 beta API 始终保持不变。

实施判断

• 在 React 中读取数据时，优先使用 useValue(observableOrSelector)。将 useSelector 和 use$ 视为迁移别名；不要依赖在 observer 中直接调用 .get()，这种模式与 React Compiler 指南冲突。
• 将 observer 作为可选的钩子数量优化手段，用于包含大量或有条件调用的 useValue 的组件，而非主要订阅 API。
• 通过可观察对象 API（如 set、assign、delete、数组方法以及 Map 或 Set 方法）进行修改。切勿修改 get() 或 peek() 返回的原始数据并期待收到通知。
• 仅在有意进行非跟踪读取时使用 peek()。只有在浅层键或集合跟踪确实是所需依赖时，才使用 get(true)。
• 除了异步或同步 getter 文档所述的数据加载行为外，计算、链接和同步 getter 都应保持纯函数。将副作用放在操作、observe、onChange 或显式的应用服务中。
• 优先使用范围较小的可观察节点和选择器。只有在将更新移到更小的 React 边界能带来显著帮助时，才使用 Memo、$React、For、Show 或 Switch。
• 将相关写操作批量处理。这对监听器频繁变动、React 重渲染和持久化写入放大都很重要。
• 需要在首次读取时惰性激活时，选择 synced(...)；需要让现有可观察对象立即开始同步时，选择 syncObservable(...)。
• 将持久化视为缓存和重试队列，而非授权机制或安全的机密存储。明确处理服务端授权、行级访问、校验和冲突策略。
• 对于异步持久化，若读取依赖已完成数据水合，应通过 syncState(state$).isPersistLoaded 设置门控。对于远程就绪状态，应依据 isLoaded、error 和待处理更改状态，而不是根据数据形态猜测。
• 明确建模登出、租户变更和身份验证门控。重置后，实时的 useValue 或其他观察器可能会重新激活惰性同步的可观察对象，除非选择器或同步配置设置了门控。

验证

使用仓库现有的检查。对于有实际意义的 Legend-State 工作，包含相关子集：

• 根据已安装的 v3 beta 声明和精确的子路径导入进行类型检查。
• 为可观察对象写入、计算依赖、关联 setter、批处理、清理、Map 或 Set 行为，以及原始数据修改错误编写单元测试。
• 编写 React 测试，覆盖渲染边界、useValue、observer、Memo、For、Show、Strict Mode 清理、Suspense，以及对 React Compiler 敏感的模式。
• 编写持久化测试，覆盖水合顺序、转换、迁移、重试元数据、乱序保存、重置和存储故障。
• 编写同步测试，覆盖创建、更新、删除、分页、实时订阅、重试、冲突或最后写入规则、身份验证门控，以及重启后的待处理更改。
• 编写浏览器或设备冒烟测试，覆盖离线编辑、重新加载、重新连接、写入失败、注销、租户切换和存储升级。
• 扫描迁移情况，检查 v2 持久化 API、旧版计算或代理辅助函数、useSelector 或 use$、渲染路径中的直接 .get()、旧版响应式组件导入，以及重命名后的返回值或回调行为。