react-dropzone 仓库 AI 协作指南（AGENTS.md）全解析：oxc 工具链、CI 流程与发布规范

react-dropzone 仓库 AI 协作指南AGENTS.md全解析oxc 工具链、CI 流程与发布规范【免费下载链接】react-dropzoneSimple HTML5 drag-drop zone with React.js.项目地址: https://gitcode.com/gh_mirrors/re/react-dropzone本文以 react-dropzone 仓库的 AGENTS.md 为骨架系统讲解这个 TypeScript 编写的 HTML5 拖拽上传库Dropzone组件 useDropzonehook为 AI 编码 Agent 与人类贡献者制定的协作约定从 oxc 系工具链oxlint / oxfmt / tsdown / Vitest、本地 CI 六步流水线、prek git hooks、Conventional Commits 语义化发布到测试分层与 Vocs 文档站点的构建与冒烟测试。读完你不仅能看懂这个仓库的每一行配置还能照搬这套轻量、无 Babel/ESLint/Prettier 的现代前端工程化实践到自己的项目。仓库定位一个极简、发布到 npm 的 React 拖拽上传库AGENTS.md 开篇即明确了仓库边界react-dropzone是一个小型、已发布到 npm 的 TypeScript 库对外只暴露两个 API——默认导出的DropzoneReact 组件和useDropzonehook。这一点可以从 package.json 的描述与 src/index.tsx 的导出结构得到印证。它唯一的运行时依赖只有两个姊妹包attr-accept负责 MIME 类型 / 文件扩展名的匹配校验file-selector负责从拖拽drag、粘贴paste以及 File System Access API 事件中提取文件。这一点在 package.json 中白纸黑字dependencies仅有这两项其余全部是开发依赖。AGENTS.md 因此给出了两条硬性约定新增任何第三个运行时依赖之前必须三思如果遇到文件提取file extraction层面的 bug优先去file-selector上游修复而不是在本地打补丁。这保证了库的体积与依赖面始终可控。此外sideEffects: falsepackage.json与exports字段package.json表明它支持 tree-shaking 与 ESM/CJS 双格式导入构建产物由dist/index.jsESM、dist/index.cjsCJS和dist/index.d.ts类型声明三件套组成。工具链全面拥抱 Rust 系 oxc 栈零 Babel/ESLint/Prettier/Rollup这是 AGENTS.md 中最具辨识度的一段工程决策。仓库明确声明There is no Babel, ESLint, Prettier, or Rollup; do not reintroduce them.当前工具链全景如下均可在 package.json 的 devDependencies 中核实版本职责工具类型Lintoxlintoxc 官方 linter含--type-aware类型感知模式Rust格式化oxfmtoxc 官方 formatterRust构建 类型声明tsdownRolldown oxcdts由 oxcisolatedDeclarations从源码直接生成Rust 内核单元测试Vitestjsdom 环境JS类型检查tsc --noEmit含独立类型测试项目TypeScript文档站点Vocs wakuReact 静态站点生成JS端到端冒烟Playwrightheadless ChromiumJS其中构建配置值得展开tsdown.config.ts以src/index.tsx为唯一入口输出esm与cjs两种格式target为es2020浏览器构建目标并开启sourcemap。类型声明通过dts: {tsconfig: ./tsconfig.build.json}生成——这个 build-only 的 tsconfig 排除了 spec 测试文件确保不会为测试代码生成声明文件。由于包声明了type: moduletsdown 配合fixedExtension: false输出.jsESM与.cjsCJS与 package.json 的exports映射一一对应outputOptions.exports: named则明确 CJS 互操作方式require(react-dropzone).default取组件。本地 CI六步流水线绿了才能提审AGENTS.md 的 Workflow 章节给出了强制性的本地校验序列这也是整个仓库质量守门的核心npm run type-check # tsc --noEmit, plus the type-tests project npm run lint # oxlint npm run lint:type-aware # oxlint --type-aware npm run format:check # oxfmt --check npm run build # tsdown - dist/ npm run test:cov # vitest with coverage对照 package.json 的 scripts 可以发现一个值得注意的细节type-check实际执行的是tsc --noEmit tsc --noEmit -p tsconfig.type-tests.json——先检查主源码再检查类型测试项目两个tsc串联。而pretest:cov钩子会自动先跑type-check lint format:check即npm run test:cov一条命令实际上触发了类型检查、lint、格式校验与带覆盖率的测试四件事这正是 AGENTS.md 强调必须跑完才能声称通过的原因。AGENTS.md 还强调了三项协作原则实现前先对齐设计非平凡改动必须预先达成共识、一次提交只含一个变更单元绝不混入无关改动、先读代码再回答、先跑命令再断言。prek git hooks自动格式化与提交信息校验的最后一环除本地 CI 外npm install会通过prepare脚本安装 prek git hooks见 package.json。这些 hooks 会自动对暂存代码执行oxfmt与oxlint并校验提交信息格式。但 AGENTS.md 特别划清了边界hooks不会运行 type-check、build 或测试hooks不会格式化 Markdown 文档因此编辑docs/下的 Markdown 后必须手动执行npm run format否则 CI 的format:check会失败。也就是说prek hooks 是快速反馈层本地 CI 六步才是最终裁决层两者职责互补而非替代。写作规范ASCII-only、注释只解释 why、格式化交给 oxfmtAGENTS.md 对代码与文档写作提出了具体到字符的约束简洁直接拒绝废话解释非显而易见的部分不叙述显而易见的部分ASCII only禁止 em-dash--也不行一律写-箭头用-而非箭头字形不等号用!而非 ≠ 字形注释解释 why不解释 what任何复述代码的注释一律删除格式化不是品味问题一律执行npm run format而非手排。格式化风格由仓库根目录的 .oxfmtrc.json 定义该文件同时是 oxfmt 的配置 schema双引号、两空格缩进、分号、无尾逗号trailingComma: none、括号内无空格bracketSpacing: false、箭头函数参数尽量省略括号arrowParens: avoid、打印宽度 120 列并排除了node_modules、dist、site、coverage等生成目录。换句话说这个仓库没有风格争议oxfmt 就是唯一标准。提交规范Conventional Commits 驱动语义化发布提交规范与发布机制深度绑定这是理解整个仓库版本管理的关键。规则如下采用 Conventional Commits主题行用现在时、祈使句写feat: expose drag file rejections不写added或adds发布语义feat:/fix:/perf:会触发一次 releasefeat!:或带BREAKING CHANGE:footer 会触发 major 版本chore:/ci:/docs:/test:/refactor:/style:/build:不会触发发布——选择类型时必须想清楚这个后果正文尽量精简或省略好的主题行加 diff 通常足够只有代码无法呈现的内容why、权衡、非显而易见的后果才值得写进正文绝不复述改动AI 辅助披露使用Assisted-by: Claude:claude-opus-4-8这样的 trailer 声明 AI 参与禁止使用Co-Authored-By也不得添加人类的Signed-off-by。配套的 .releaserc.json 展示了发布流水线branches为master插件链依次是 commit-analyzer、release-notes-generator、changelog、semantic-release/npm开启provenance: true的 npm 来源证明与semantic-release/github把*.tgz作为发布资产。这也解释了 package.json 中版本号恒为0.0.0-development的原因——发布时由 semantic-release 动态设置永远不要手动改版本号。测试体系单测、类型测试、e2e 三层防线AGENTS.md 把测试清晰地分为三层对应三个目录1. 单元测试src/**/*.spec.{ts,tsx}Vitest jsdom测试文件与源码同目录存放运行环境由 vitest.config.ts 配置environment: jsdom、globals: true、setupFiles: [./test-setup.js]。test-setup.js引入testing-library/jest-dom/vitest的 jest-dom 匹配器并刻意把globalThis.isSecureContext定义为true——注释说明这是为了让测试覆盖 File System Access API 相关的安全上下文分支。测试写法上的硬性约定用testing-library/react的render/renderHook渲染用 jest-dom 匹配器断言用fireEvent驱动真实 DOM 事件并用file-selector的fromEvent构造拖拽数据。能用真实事件解决的场景绝不引入 mock 库——这保证了测试尽量贴近真实浏览器行为。2. 类型测试type-tests/*.tsxtsc -p tsconfig.type-tests.json类型测试是 react-dropzone 的特色每当公开类型public types发生变化都必须新增/更新类型测试type-tests 目录下已有 accept、events、validator、plugin、refs 等用例用tsc编译来钉死哪些写法应该通过、哪些应该被拒绝。这部分包含在npm run type-check里是公共 API 兼容性的隐形护栏。3. 端到端冒烟e2e/*.e2e.tsPlaywright注意 AGENTS.md 的定位说明e2e 测试的是文档站点的水合hydration不是库本身。e2e/docs-smoke.e2e.ts 对/、/guide/getting-started、/examples/basic三条路由加载 headless Chromium断言两条信号页面没有任何未捕获异常pageerror且主内容区#vocs-content可见且非空——后者用于兜底白屏场景。最后还有一条硬指标覆盖率不得下降npm run test:cov用 v8 provider 统计src/**。代码约定单一入口导出公开 APIAGENTS.md 的 Code conventions 章节明确了结构约束源码是带 JSX 的 TypeScriptsrc/index.tsx共享辅助函数放在src/utils其中 src/utils/index.ts 有配套单测 src/utils/index.spec.ts对外 API 恰好等于src/index.tsx重新导出的内容默认导出Dropzone组件、useDropzonehook 及其类型DropzoneProps、DropzoneOptions、DropzoneState、FileRejection、DropEvent等。任何公开改动都必须同步更新 README 的用法示例必须遵守 React Hooks 规则由 oxlint 的react插件强制但react-hooks/exhaustive-deps被有意关闭因此 effect 依赖数组要靠开发者手工保持诚实。构建与发布tsdown 产物、files 白名单与 semantic-release构建管线在 AGENTS.md 中描述得很完整结合 tsdown.config.ts 可还原全貌npm run build把src/index.tsx打包进dist/ESM.js、CJS.cjs与由 oxcisolatedDeclarations基于tsconfig.build.json从源码生成.d.tsdist/是生成目录严禁手工编辑实际发布到 npm 的内容由 package.json 的files白名单决定dist和src排除所有*.spec.*测试文件保持该列表准确即可控制包体积发布由 semantic-release 从提交历史自动完成仓库版本恒为0.0.0-development绝不手动 bump运行环境约束Node 22engines浏览器构建目标es2020。文档站点Vocs waku静态渲染到 Netlify文档体系是仓库的另一大工程块文档用 MDX 编写在docs/下见 docs 的 guide 与 examples 系列站点由 vocs.config.ts 配置srcDir: docs、outDir: site、renderStrategy: static输出静态 HTML顶部导航与侧边栏在此定义npm run docs:build生成静态 HTML 到site/gitignorednetlify.toml 指定构建命令与发布目录由 Netlify 部署到生产站点waku 必须锁定版本Vocs 运行在 waku 之上而 waku 的unstable_*路由 API 在 beta 版本之间会破坏性变更。AGENTS.md 明确警告 waku 已被固定并在 Dependabot 中忽略到 Vocs 支持的版本package.json 中waku: 1.0.0-beta.8擅自升级可能导致站点白屏仓库 issue #1512 的真实事故。解除锁定前必须重跑文档冒烟测试。这也解释了为什么 e2e 冒烟测试存在docs-e2eCI 任务在每个 PR 上运行docs-monitor.yml定时对生产环境运行专门拦截依赖升级导致水合崩溃但 HTTP 探测一切正常这类故障。CI 工作流最小化、单一职责、信任 CI 的自动合并最后是 CI 层约定GitHub Actions 位于.github/workflows工作流名、作业名、命名步骤一律用 Sentence case与现有文件保持一致Dependabot 把 patch/minor 升级分组并在 CI 全绿时自动合并 patch 升级。自动合并信任 CI所以任何必须拦截依赖升级的检查都必须跑在 CI 里——这正是文档冒烟测试存在的根本原因保持工作流最小化、聚焦单一目的优先使用内置GITHUB_TOKEN而非个人访问令牌。小结这套指南给我们的启发react-dropzone 的 AGENTS.md 是一份小而全的仓库协作契约值得借鉴的工程实践可以归纳为三点工具链极简用 Rust 系 oxc 栈oxlint oxfmt tsdown彻底取代 Babel/ESLint/Prettier/Rolluplint、format、build 全程由单一生态覆盖格式争议归零质量门禁分层prek hooks 管暂存文件的格式与提交信息本地 CI 六步管类型/质量/构建/测试Playwright 冒烟测试专管文档站点水合三层各司其职提交即发布Conventional Commits 与 semantic-release 深度绑定提交类型直接决定版本号走向配合files白名单与0.0.0-development版本策略发布全流程零手工干预。如果你正为 React 组件库项目设计工程规范这份 AGENTS.md 连同 package.json、tsdown.config.ts、vitest.config.ts、vocs.config.ts、.releaserc.json 构成了一个可直接对照落地的最小闭环模板。【免费下载链接】react-dropzoneSimple HTML5 drag-drop zone with React.js.项目地址: https://gitcode.com/gh_mirrors/re/react-dropzone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考