编写或审查 ReactLynx 双线程代码时遵循的最佳实践

在编写、审查或重构 ReactLynx 组件与组件库时，按双线程运行时规则检查副作用、生命周期、事件、主线程脚本、代码分割与性能。

适用场景

解决思路

1. 先分类任务模式：writing（写新代码或给最佳实践建议）、review（检查/审计/解释/验证现有代码）、refactor（修复或重写现有代码）；若用户未明说则从措辞推断，未检查代码前优先 review 再 refactor。
2. 在仓库中改动前先搜索：rg "lynx.getJSModule|NativeModules|useLayoutEffect|main-thread:|runOnMainThread|runOnBackground|lazy\(|Suspense|background only|globalPropsMode|__globalProps|jsx|exports" <target>，并阅读附近的组件、自定义 hooks、转发事件处理器的自定义组件、Rspeedy 配置和性能相关代码。
3. 有源码时运行辅助扫描器（非完整解析器，不能替代人工审查）：node -e "import fs from 'fs'; import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs'; const input = '<sourceCodeOrFilePath>'; const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input; const workflow = new ReactLynxWorkflow('review'); const summary = workflow.reviewCode(sourceCode); console.log(formatScanReport(summary));"
4. 结合扫描结果做人工检查：双线程边界——render 代码可能跑在主线程，副作用和原生 API 必须 background-only。
5. 检查 background-only 传播：仅被 background-only 代码调用的代码是 background-only，但自定义 prop 和自定义 hook 边界通常需要显式 'background only' 指令。
6. 检查生命周期：不支持 useLayoutEffect；后台副作用用 useEffect，布局读取用主线程布局事件/refs。
7. 检查事件：普通 bind*/catch* 处理器运行在后台线程；main-thread:* 处理器需要 'main thread' 且有更严格限制。
8. 检查 MTS：捕获值必须可 JSON 序列化，捕获变量不可修改，不支持嵌套主线程函数，跨线程调用必须用 runOnMainThread() 或 runOnBackground()。
9. 检查共享模块：仅在共享代码（而非共享状态）时用 with { runtime: 'shared' } 导入辅助函数。
10. 检查组件库：发布类型擦除的 dist ESM，在含 JSX 的 .jsx 文件中保留作者书写的 JSX 并配套声明；导出构建实际产出的 .js 或 .jsx 入口；仅通过显式 source 字段或受支持的 condition 暴露 TS/TSX 源码；检查 Rslib、TypeScript、Babel、SWC 输出是 classic、automatic 还是 custom-factory JSX 降级；按 @lynx-js/react peer 范围对待有意的 React.createElement，不要假定所有调用都不兼容。
11. 检查 lynx.__globalProps：由宿主注入的跨页面/全局数据，通过 updateGlobalProps 更新。
12. 检查 globalPropsMode：'reactive' 会触发根 forceUpdate；'event' 需要配合 useGlobalPropsChanged 显式更新；迁移到 'event' 时扫描直接读取 lynx.__globalProps 的地方，因为根 forceUpdate 不再生效。
13. 检查代码分割：lazy 组件需要 default 导出、Suspense、CSS scope 感知，以及重要边界的错误处理。
14. 检查性能分析：优化前先用 trace 事件和可读的 displayName 定位热点 render/diff/update 路径。
15. refactor 模式安全流程：1) 先报告当前发现；2) 说明哪些修复是机械性的、哪些需要人工设计判断；3) 只做范围受限的改动；4) 编辑后重跑辅助扫描器或包测试。
16. 自动修复仅作建议使用：当前 auto-fixes 针对 detect-background-only 诊断设计，应用前需审查；可用 node -e "import fs from 'fs'; import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs'; const input = '<sourceCodeOrFilePath>'; const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input; const workflow = new ReactLynxWorkflow('refactor'); workflow.reviewCode(sourceCode); const plan = workflow.generateFixPlan(); if (plan) { console.log(formatFixPlan(plan)); }"
17. 按规则清单逐项应用：detect-background-only（CRITICAL，lynx.getJSModule、NativeModules、'background only'、自定义事件/hook 边界）、avoid-use-layout-effect（MEDIUM，生命周期与布局读取）、proper-event-handlers（MEDIUM，bindtap、catchtap、传播、dataset、自定义 prop 处理器）、main-thread-scripts-guide（MEDIUM，main-thread:*、useMainThreadRef、跨线程调用、共享模块）、component-library-packaging（HIGH，组件库导出、类型擦除 ESM、保留 JSX、Rslib、tsc）、global-props-mode（MEDIUM，globalPropsMode 配置、直接读取 lynx.__globalProps、useGlobalPropsChanged 迁移）、code-splitting（MEDIUM，lazy、Suspense、独立 lazy bundle、CSS bundle scope）、performance-profiling（MEDIUM，ReactLynx trace 事件、flow ID、displayName）、hoist-static-jsx（LOW，静态 JSX 与 render 开销）。

适用边界 · 注意事项

• 不适用于不含 ReactLynx JSX 的原生 Lynx Element PAPI（应使用 vanilla-lynx）。
• 不适用于通过 DevTool/CDP 调试运行中的应用（应使用 lynx-devtool）。
• 不适用于 Rspeedy/tsconfig 配置（应使用 lynx-typescript）。