企业官网建设流程全解析

React Doctor架构深拆：Effect v4诊断引擎、oxlint插件与多Worker并行扫描设计

【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor

React 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/ 下：

这种分层让"规则引擎（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 里干。

四路 Worker

packages/core/src/ 下能找到四条 Worker 通道，各自独立进程、互不阻塞：

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-doctor@latest

也可以传文件路径只扫指定文件（CI 中配合 diff 使用）：

npx react-doctor@latest src/a.tsx src/b.tsx

CI 集成一条命令完成，只报告本次 PR 引入的问题而不翻旧账：

npx react-doctor@latest ci install

想给 AI 编码助手装"技能"让它学会修这些问题：

npx react-doctor@latest 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.md
• AI 技能定义：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