企业官网建设流程全解析

React Doctor 贡献者指南：代码规范、测试命令与 GitHub Action 发布流程完全讲解

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

React Doctor 是一款专为 React 项目打造的确定性代码体检工具，能够扫描状态与副作用、性能、安全、可访问性与可维护性问题，并给代码打出 0–100 的健康分。本文将作为 React Doctor 贡献者指南，完整讲解其代码规范、常用测试命令、Changesets 发布流程，以及 GitHub Action 独立版本化与打 tag 的发布流程，帮助新手贡献者快速上手。

快速了解项目：你将要改动的代码库

React Doctor 的核心卖点是"确定性扫描"——同一段代码每次扫描结果一致，因此它非常适合被集成到 CI 与编码 Agent 中。项目采用pnpm workspace + Turbo管理的 monorepo 结构，主要包如下：

完整目录职责说明见 AGENTS.md，它是贡献者必读的"包布局地图"。核心编排器（诊断流水线的"心脏"）位于 run-inspect.ts。

环境准备与安装命令

1. 使用git clone https://gitcode.com/GitHub_Trending/re/react-doctor克隆仓库并进入目录
2. 确认 Node.js 版本满足要求（^20.19.0 || >=22.13.0），包管理器为pnpm >= 8，版本约束声明在 package.json
3. 项目约定使用@antfu/ni封装命令：ni安装依赖、nr SCRIPT_NAME运行脚本、nun卸载，详见 AGENTS.md

核心代码规范：动手前必须知道的 8 条铁律

项目的编码风格写在 AGENTS.md 的 General Rules 一节中，贡献者（包括 AI 助手）都必须遵守：

• 命名与组织：文件名一律 kebab-case；变量名要有描述性，避免x、moved这类缩写，优先didPositionChange
• TypeScript：优先使用interface而非type；类型放在全局作用域；尽量避免as断言
• 函数：使用箭头函数而非function声明；魔法数字必须放进constants.ts，用SCREAMING_SNAKE_CASE并带单位后缀（如_MS、_PX）
• 工具函数：小而专注的 utility 放进utils/，一个文件一个工具函数
• 注释：几乎不写注释；确属 hack 的代码必须加// HACK: 原因前缀
• 去重：新增工具函数前先搜索现有符号（项目用truffler做模糊符号检索），任务结束后再搜一遍，删除被取代的旧代码

Effect v4 运行时约定

核心引擎基于effect@4.0.0-beta.102，几条硬性约定值得提前了解：

• 每个 Effect 模块单独导入：import * as Effect from "effect/Effect"，禁止伞形导入
• 所有可失败服务统一抛出ReactDoctorError（Schema.TaggedErrorClass叶子 + 联合类型）
• Effect.gen内部严禁try/catch，同步抛错要用Effect.try包裹
• 测试层命名有固定词汇表：layerNode、layerOf、layerInMemory、layerCapture、layerNoop

完整约定见 AGENTS.md。

测试命令一览：提交前的检查清单

测试框架是vite-plus/test（vitest 封装），测试与源码同包存放：packages/core/tests/（服务与编排测试）、packages/react-doctor/tests/（CLI 与端到端测试）。

提交前必须依次运行（来自 AGENTS.md）：

pnpm test # 运行全部包的测试 pnpm lint # 代码检查 pnpm typecheck # 类型检查 pnpm format # 格式化（仅校验用 pnpm format:check） pnpm smoke:json-report # 校验构建产物的 JSON 报告是否符合 schema

其他常用命令（脚本定义在 package.json）：

CI 中这些检查如何执行？测试矩阵覆盖 Ubuntu / Windows / macOS 与 Node 20–26，Windows 与 Node 20 腿串行执行；格式化检查、CLI 冒烟、JSON 报告 schema 校验只在 Ubuntu + Node 22 腿跑一次，详见 ci.yml。任务依赖与缓存配置在 turbo.json。

发布流程：Changesets 驱动的 npm 版本化

npm 包发布完全由Changesets托管，工作流在 publish.yml：

1. 在 PR 中执行pnpm changeset添加版本变更（贡献者默认只加patch级 Changeset，minor/major 需维护者明确要求）
2. 合并到main后，publish.yml 中的changesets/action自动创建 "chore: version packages" 版本 PR；合并后执行pnpm release
3. release脚本（package.json）依次执行：构建 → 依赖审计 → 注入 Sentry source maps →changeset publish
4. 发布使用npm Trusted Publishing（OIDC），无需长期 npm token
5. 每次稳定发布后，publish-dev作业还会发布一个X.Y.Z-dev.<sha>快照版本，方便内部联调

⚠️发布授权红线（AGENTS.md）：合并任何触发发布的 PR、打 tag、推 tag 都必须获得维护者针对具体版本的明确确认——"通用放行"不构成发布授权。

GitHub Action 独立版本化：最容易被忽视的细节

React Doctor 仓库根部的 action.yml 是一个 composite GitHub Action，它与 npm 包版本完全独立，有自己的 tag 体系：

• npm 包 tag：react-doctor@X.Y.Z（无前缀，Changesets 在 CI 中创建）
• Action tag：带v前缀的语义化版本vX.Y.Z+ 浮动主版本指针vN（如v2），v前缀用于与包 tag 区分

哪些改动算 "Action 发布"？

改动了下列任一文件，就必须打新的 Action tag。该清单定义在 recommend-action-version-bump.mjs：

版本号如何递增？

由 recommend-action-version-bump.mjs 按 conventional commit 分类：feat(action)→minor；fix/refactor/chore/docs →patch；inputs/outputs 或运行时契约的破坏性变更 →major。

打 tag 的完整步骤

tag 为GPG 签名的附注 tag（tag.gpgsign=true），必须在本地显式带消息创建：

# 1. 在改动 Action 的合并提交上打新 tag git tag -a v2.2.3 <commit> -m "react-doctor action v2.2.3" # 2. 将浮动主版本指针 v2 移到同一提交 git tag -fa v2 <commit> -m "react-doctor action v2 (floating major -> v2.2.3)" # 3. 推送：普通推送 vX.Y.Z，仅浮动主版本指针需要 force git push origin v2.2.3 git push --force origin v2

另外两点最佳实践：

• 自动提醒：action-version-bump.yml 工作流会检测 PR 中是否触碰 Action 发布面，并在 PR 下评论推荐的版本号与打 tag 命令；设置仓库变量AUTO_BUMP_ACTION_TAG=true后合并时可自动完成
• 引用方式：文档中永远不要让消费方引用@main（存在供应链风险），推荐@<完整 commit SHA> # v2.2.2强 pin 或@vN浮动主版本

新手贡献者速查清单

1. git clone https://gitcode.com/GitHub_Trending/re/react-doctor后用ni安装依赖
2. 通读 AGENTS.md：包布局、Effect v4 约定、测试要求、发布红线
3. 写规则优先复用现有符号（truffler检索），一个utils/文件只放一个函数
4. 提交前跑完pnpm test && pnpm lint && pnpm typecheck && pnpm format
5. 用pnpm changeset添加 patch 级变更说明
6. 若触碰action.yml或四个发布脚本，记得走独立的vX.Y.Z+vN打 tag 流程

掌握以上规范与流程，你就可以顺畅地为 React Doctor 提交第一个 PR 了 🚀

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