React Doctor架构深拆Effect v4诊断引擎、oxlint插件与多Worker并行扫描设计【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctorReact Doctor 是一个专门诊断 React 代码质量的多 Worker 并行扫描工具它能自动检测状态与副作用、性能、架构、安全、可访问性等六大类问题。本文将从 React Doctor 架构入手拆解它的 Effect v4 诊断引擎、oxlint 规则插件与多 Worker 并行扫描设计帮你理解一个确定性扫描器是如何做到又快又稳的。React Doctor 是做什么的先说结论你的 AI Agent 写出的 React 代码可能有坑React Doctor 专门抓这些坑它会对你的代码库做确定性扫描同样的代码永远给出同样的结果覆盖以下维度状态与副作用useEffect滥用、派生状态、Effect 内发请求⚡性能不必要的重渲染、列表渲染陷阱️架构过度复杂的 React 函数、重复的 JSX 子树适合组件化的候选安全危险 HTML 注入等♿可访问性语义化与关联控件可维护性死代码、重复 JSX它横跨各种 React 框架Next.js、Vite、Astro、TanStack、React Native、Expo 都能扫。Monorepo 全景6 个包各司其职React Doctor 采用 pnpm monorepo 组织核心包都在 packages/ 下包职责源码位置react-doctorCLI 与终端 UIInk 渲染packages/react-doctor/src/react-doctor/core诊断引擎被其他包复用packages/core/src/react-doctor/api对外诊断 API 封装packages/api/src/diagnose.tsoxlint-plugin-react-doctor核心规则插件2900 文件packages/oxlint-plugin-react-doctor/src/eslint-plugin-react-doctorESLint 兼容层packages/eslint-plugin-react-doctor/src/index.tsfuzz / evals模糊测试与真实仓库评测packages/fuzz/src/这种分层让规则引擎oxlint 插件→ 诊断引擎core→ 交互层CLI各管一层新人读代码时从下往上看最清晰。Effect v4 诊断引擎把副作用关进笼子打开 packages/core/package.json 可以看到引擎依赖effect: 4.0.0-beta.102——这是项目整个诊断流程的骨架。诊断入口是 run-inspect.ts它一次性引入了 Effect 生态的核心原语Effect把可能失败、有副作用的操作建模为可组合的值Fiber运行在并发执行单元上天然支持超时与取消Stream诊断结果以流的方式产出边扫边报告Ref / Filter / Option线程安全的共享状态与空值处理为什么这么设计因为一次完整扫描涉及读文件、跑 git、启动子进程、写缓存等大量副作用。用 Effect 之后services/ 目录下的linter.ts、git.ts、files.ts、score.ts等服务都变成可注入、可测试、可超时的组件。引擎还为每个阶段设置了独立超时LintPhaseTimeoutMs、DeadCodePhaseTimeoutMs等任何一阶段卡死都不会拖垮整次扫描——这就是确定性的另一层含义行为可预期故障可隔离。oxlint 插件规则引擎的心脏真正的找问题能力来自 packages/oxlint-plugin-react-doctor/这是整个仓库最大的包约 2900 个源码文件。规则按领域分目录规则代码在 plugin/rules/ 下按问题域拆成 30 个目录performance/ 性能规则 state-and-effects/ 状态与副作用 security/ 安全规则 a11y/ 可访问性 architecture/ 架构规则 nextjs/ tanstack-query/ mobx/ jotai/ ...三层注册表core-rule-registry.ts核心规则注册表附 core-rule-registry-data.json 数据rule-registry.ts完整规则目录CLIrules命令就靠它生成规则清单security-scan-rule-registry.ts安全扫描专属规则插件本体 react-doctor-plugin.ts 还实现了一个重置钩子reset hook保证每次扫描间插件内部缓存干净这也是扫描结果可复现的关键。多 Worker 并行扫描设计这是架构中最精彩的部分主线程只负责调度脏活全在 Worker 里干。四路 Workerpackages/core/src/ 下能找到四条 Worker 通道各自独立进程、互不阻塞Worker文件干什么oxlintstart-oxlint-worker.ts批量执行规则扫描重复 JSXstart-duplicate-jsx-worker.ts检测可组合的重复 JSX 子树项目分析start-project-analysis-worker.ts死代码、依赖解析React Compilerstart-react-compiler-detection-worker.ts检测 React Compiler 配置oxlint Worker 的任务-标记协议看 start-oxlint-worker.ts 中的消息协议主线程通过标准 I/O 给 Worker 发三种消息job一批待扫描文件 工作目录probes让热Worker 顺路做依赖探测它已持有规则插件和文件系统记忆10 个 Worker 并行收集时主线程完全空闲ready/unavailable启动握手filesystemCacheEpoch文件系统缓存纪元是精妙之处一次扫描内文件系统视为冻结插件缓存在 Job 之间存活纪元一变缓存立刻丢弃。这样既避免了反复 stat 文件又保证了跨批次的一致性。批次调度与 OOM 自救spawn-batches.ts 负责把文件切批、控制并发、启动子进程配套测试覆盖了级联限制、OOM 救援、串行降级等极端场景见 spawn-batches-oom-rescue.test.ts。Worker 槽位由 create-worker-slots.ts 统一创建并发数还会根据机器 CPU 与内存自适应见 resolve-scan-concurrency.test.ts。加上文件级缓存file-lint-cache.ts与侧边缓存sidecar-lint-cache.ts二次扫描只会对变化的文件重新跑规则——CI 场景下提速非常可观。快速上手验证架构效果在任意 React 项目根目录执行一条命令即可体验npx react-doctorlatest也可以传文件路径只扫指定文件CI 中配合 diff 使用npx react-doctorlatest src/a.tsx src/b.tsxCI 集成一条命令完成只报告本次 PR 引入的问题而不翻旧账npx react-doctorlatest ci install想给 AI 编码助手装技能让它学会修这些问题npx react-doctorlatest install扫描结果支持 JSON 输出--format json格式说明见 docs/json-report.md。延伸阅读关键文件导航想继续深挖推荐按这个顺序读诊断主流程run-inspect.ts评分计算calculate-score.ts诊断类型定义types/diagnostic.ts规则编写指南docs/HOW_TO_WRITE_A_RULE.md规则候选清单docs/rule-candidates-backlog.mdAI 技能定义skills/react-doctor/SKILL.md总结React Doctor 的架构可以概括为三层oxlint 插件管规则按领域组织、三层注册表、可重置保证确定性Effect v4 管流程副作用可控、阶段超时隔离、结果流式产出多 Worker 管并发四路 Worker 独立进程、批次调度、OOM 自救、纪元化缓存。三者叠加才实现了大仓库扫得快、结果永远一致这个看似矛盾的目标 【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 19:12:03 · 阅读 1.2k React Doctor架构深拆：Effect v4诊断引擎、oxlint插件与多Worker并行扫描设计
React Doctor架构深拆Effect v4诊断引擎、oxlint插件与多Worker并行扫描设计【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctorReact Doctor 是一个专门诊断 React 代码质量的多 Worker 并行扫描工具它能自动检测状态与副作用、性能、架构、安全、可访问性等六大类问题。本文将从 React Doctor 架构入手拆解它的 Effect v4 诊断引擎、oxlint 规则插件与多 Worker 并行扫描设计帮你理解一个确定性扫描器是如何做到又快又稳的。React Doctor 是做什么的先说结论你的 AI Agent 写出的 React 代码可能有坑React Doctor 专门抓这些坑它会对你的代码库做确定性扫描同样的代码永远给出同样的结果覆盖以下维度状态与副作用useEffect滥用、派生状态、Effect 内发请求⚡性能不必要的重渲染、列表渲染陷阱️架构过度复杂的 React 函数、重复的 JSX 子树适合组件化的候选安全危险 HTML 注入等♿可访问性语义化与关联控件可维护性死代码、重复 JSX它横跨各种 React 框架Next.js、Vite、Astro、TanStack、React Native、Expo 都能扫。Monorepo 全景6 个包各司其职React Doctor 采用 pnpm monorepo 组织核心包都在 packages/ 下包职责源码位置react-doctorCLI 与终端 UIInk 渲染packages/react-doctor/src/react-doctor/core诊断引擎被其他包复用packages/core/src/react-doctor/api对外诊断 API 封装packages/api/src/diagnose.tsoxlint-plugin-react-doctor核心规则插件2900 文件packages/oxlint-plugin-react-doctor/src/eslint-plugin-react-doctorESLint 兼容层packages/eslint-plugin-react-doctor/src/index.tsfuzz / evals模糊测试与真实仓库评测packages/fuzz/src/这种分层让规则引擎oxlint 插件→ 诊断引擎core→ 交互层CLI各管一层新人读代码时从下往上看最清晰。Effect v4 诊断引擎把副作用关进笼子打开 packages/core/package.json 可以看到引擎依赖effect: 4.0.0-beta.102——这是项目整个诊断流程的骨架。诊断入口是 run-inspect.ts它一次性引入了 Effect 生态的核心原语Effect把可能失败、有副作用的操作建模为可组合的值Fiber运行在并发执行单元上天然支持超时与取消Stream诊断结果以流的方式产出边扫边报告Ref / Filter / Option线程安全的共享状态与空值处理为什么这么设计因为一次完整扫描涉及读文件、跑 git、启动子进程、写缓存等大量副作用。用 Effect 之后services/ 目录下的linter.ts、git.ts、files.ts、score.ts等服务都变成可注入、可测试、可超时的组件。引擎还为每个阶段设置了独立超时LintPhaseTimeoutMs、DeadCodePhaseTimeoutMs等任何一阶段卡死都不会拖垮整次扫描——这就是确定性的另一层含义行为可预期故障可隔离。oxlint 插件规则引擎的心脏真正的找问题能力来自 packages/oxlint-plugin-react-doctor/这是整个仓库最大的包约 2900 个源码文件。规则按领域分目录规则代码在 plugin/rules/ 下按问题域拆成 30 个目录performance/ 性能规则 state-and-effects/ 状态与副作用 security/ 安全规则 a11y/ 可访问性 architecture/ 架构规则 nextjs/ tanstack-query/ mobx/ jotai/ ...三层注册表core-rule-registry.ts核心规则注册表附 core-rule-registry-data.json 数据rule-registry.ts完整规则目录CLIrules命令就靠它生成规则清单security-scan-rule-registry.ts安全扫描专属规则插件本体 react-doctor-plugin.ts 还实现了一个重置钩子reset hook保证每次扫描间插件内部缓存干净这也是扫描结果可复现的关键。多 Worker 并行扫描设计这是架构中最精彩的部分主线程只负责调度脏活全在 Worker 里干。四路 Workerpackages/core/src/ 下能找到四条 Worker 通道各自独立进程、互不阻塞Worker文件干什么oxlintstart-oxlint-worker.ts批量执行规则扫描重复 JSXstart-duplicate-jsx-worker.ts检测可组合的重复 JSX 子树项目分析start-project-analysis-worker.ts死代码、依赖解析React Compilerstart-react-compiler-detection-worker.ts检测 React Compiler 配置oxlint Worker 的任务-标记协议看 start-oxlint-worker.ts 中的消息协议主线程通过标准 I/O 给 Worker 发三种消息job一批待扫描文件 工作目录probes让热Worker 顺路做依赖探测它已持有规则插件和文件系统记忆10 个 Worker 并行收集时主线程完全空闲ready/unavailable启动握手filesystemCacheEpoch文件系统缓存纪元是精妙之处一次扫描内文件系统视为冻结插件缓存在 Job 之间存活纪元一变缓存立刻丢弃。这样既避免了反复 stat 文件又保证了跨批次的一致性。批次调度与 OOM 自救spawn-batches.ts 负责把文件切批、控制并发、启动子进程配套测试覆盖了级联限制、OOM 救援、串行降级等极端场景见 spawn-batches-oom-rescue.test.ts。Worker 槽位由 create-worker-slots.ts 统一创建并发数还会根据机器 CPU 与内存自适应见 resolve-scan-concurrency.test.ts。加上文件级缓存file-lint-cache.ts与侧边缓存sidecar-lint-cache.ts二次扫描只会对变化的文件重新跑规则——CI 场景下提速非常可观。快速上手验证架构效果在任意 React 项目根目录执行一条命令即可体验npx react-doctorlatest也可以传文件路径只扫指定文件CI 中配合 diff 使用npx react-doctorlatest src/a.tsx src/b.tsxCI 集成一条命令完成只报告本次 PR 引入的问题而不翻旧账npx react-doctorlatest ci install想给 AI 编码助手装技能让它学会修这些问题npx react-doctorlatest install扫描结果支持 JSON 输出--format json格式说明见 docs/json-report.md。延伸阅读关键文件导航想继续深挖推荐按这个顺序读诊断主流程run-inspect.ts评分计算calculate-score.ts诊断类型定义types/diagnostic.ts规则编写指南docs/HOW_TO_WRITE_A_RULE.md规则候选清单docs/rule-candidates-backlog.mdAI 技能定义skills/react-doctor/SKILL.md总结React Doctor 的架构可以概括为三层oxlint 插件管规则按领域组织、三层注册表、可重置保证确定性Effect v4 管流程副作用可控、阶段超时隔离、结果流式产出多 Worker 管并发四路 Worker 独立进程、批次调度、OOM 自救、纪元化缓存。三者叠加才实现了大仓库扫得快、结果永远一致这个看似矛盾的目标 【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考