React-Admin 项目架构与开发规范指南Agent 上下文文档深度解读【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-adminreact-admin 是一个基于 TypeScript、React 与 Material UI、面向 REST/GraphQL API 的单页应用前端框架由 Marmelab 维护专为 B2B 与后台管理系统设计。仓库根目录下的 Agents.md 是一份为 AI 编程助手Agent与人类协作者准备的项目上下文速查手册浓缩了该项目的设计哲学、反模式红线、代码库结构、依赖基线、测试要求与协作规范。读完本文你将理解 react-admin 为何采用 headless 核心 控制器/视图分离的架构掌握其核心开发约定与质量门槛并能在该仓库中快速定位模块、读懂测试结构与运行开发命令。一、这份文档是什么为 Agent 准备的仓库上下文Agents.md开篇即点明其定位它不是面向最终用户的框架文档而是面向 Agent 的上下文文件。它的价值在于让任何进入该仓库的 AI Agent 无需完整扫描数千个源文件即可快速建立起与维护者一致的心智模型从而在生成代码、定位问题、提交 PR 时遵循仓库既定惯例。值得注意的细节是仓库中的 CLAUDE.md 全文只有一行Agents.md——即通过引用指令将Agents.md作为唯一的项目上下文来源。这种单一事实源 引用的组织方式本身就是该仓库DRY不要重复知识原则的体现项目上下文只维护一份各工具入口统一引用避免多处维护导致信息漂移。全文围绕六个维度展开设计原则、反模式、代码库组织、包依赖、测试与文档要求、PR 规范与静态分析命令。下面逐层展开。二、设计原则从哲学到源码的验证2.1 SPA 优先的架构定位react-admin 被明确设计为单页应用SPA框架而不是服务端渲染或混合渲染优先的框架。这一点决定了其数据获取、路由与状态管理的整体形态应用启动时加载一次 Shell之后通过dataProvider以异步方式获取数据、通过 React Router 在客户端完成路由切换。仓库中 examples/simple、examples/demo 等示例应用均采用这种形态。2.2 向后兼容优先Backward compatibility over new features——避免破坏性变更是核心取舍准则。这意味着宁可暂缓引入新特性也不轻易改变既有 API 的行为。对 Agent 而言这条原则的实操含义是在修改任何被导出的 API 之前先检查其影响面优先以增量方式扩展而不是重写。2.3 最小 API 表面如果几行纯 React 就能实现就不要把它加进 core。这一原则直接控制着ra-core的膨胀速度。例如许多便捷组件实际上可以通过组合既有 hooks 与 MUI 组件在用户侧实现框架就不应提供专门的 API。对贡献者来说新增导出前应自问这个能力是否可以用现有 API 组合出来如果答案是肯定的它更可能属于用户代码而非框架核心。2.4 Provider 模式三大可替换适配器数据获取、认证、国际化被抽象在三个可替换的 provider 之后dataProvider统一所有数据读写getList、getOne、create、update、delete等authProvider统一登录、登出、权限检查login、logout、checkAuth、getPermissions等i18nProvider统一翻译与文案解析。这一模式在仓库结构中体现为独立成包的数据适配器族ra-data-*如ra-data-simple-rest、ra-data-fakerest、ra-data-json-server、ra-data-graphql、i18n 适配器族ra-i18n-*如ra-i18n-polyglot、ra-i18n-i18next以及翻译包ra-language-*如ra-language-english、ra-language-french。应用侧可以像插拔一样更换后端协议而不必改动业务组件——这正是 provider 模式的核心收益。2.5 Headless 核心逻辑与 UI 的刻意分离这是 react-admin 最具辨识度的架构决策逻辑全部放在ra-coreUI 渲染放在ra-ui-materialui且这种分离是刻意的intentional——绝不把逻辑耦合进 UI。从源码可以清晰看到这一分层packages/ra-core/src 下是auth、controller、core、dataProvider、form、i18n、routing、store、notification、inference、preferences等纯逻辑目录几乎不依赖任何具体 UI 库packages/ra-ui-materialui/src 下则是auth、button、detail、field、form、input、layout、list、theme等渲染层目录packages/react-admin/src/index.ts 是面向最终用户的主发行包它只做三件事export * from ./Admin、export * from ./defaultI18nProvider再聚合导出ra-core与ra-ui-materialui。换句话说一个不想要 Material UI 的用户完全可以只用ra-core自建 UI而 Material UI 层只是对核心逻辑的一套默认渲染实现。2.6 控制器/视图分离ra-core/src/controller/下的控制器如create/、edit/、list/、show/、saveContext/、field/、input/以 hooks 形式暴露业务逻辑ra-ui-materialui/src下的视图组件消费这些 hooks 完成渲染。典型链路是ListController/useListController提供数据与回调 →List视图组件渲染。这种分离让同一套逻辑可以被不同的 UI 皮肤复用也便于单元测试——直接对 controller hooks 做断言无需挂载 DOM。2.7 Context拉取而非推送Pull, dont push组件通过 context 自定义 hooks 向子孙暴露数据而不是层层 prop drilling。每一个会获取数据或定义回调的组件都会为它创建一个 context。这在ra-core中体现为大量的use*Contexthooks如useListContext、useEditContext、useShowContext、useRecordContext、useSaveContext对应文档见 docs 目录下的useListContext.md、useEditContext.md等。对使用者而言深层组件不再需要手动透传 props而是通过 hook 就近拉取数据对 Agent 而言新增需要跨层级共享的数据时正确做法是新增 context而不是增加 props 深度。2.8 使用内部useEvent()而非useCallbackAgents.md明确要求记忆化事件处理器使用内部useEvent而不是useCallback。其实现位于 packages/ra-core/src/util/useEvent.tsexport const useEvent Args extends unknown[], Return( fn: (...args: Args) Return ): ((...args: Args) Return) { const ref React.useRef(...args: Args) Return(() { throw new Error(Cannot call an event handler while rendering.); }); useLayoutEffect(() { ref.current fn; }); return useCallback((...args: Args) ref.current(...args), []); };从源码可以看出其设计巧思函数引用被存放在 ref 中每次渲染通过useLayoutEffect同步更新SSR 环境下退化为useEffect但对外暴露的永远是同一个useCallback引用。这样既保证了事件处理器引用稳定避免子组件无谓重渲染又始终能调用到最新闭包中的函数——解决useCallback依赖数组需要不断变化的痛点。该 hook 配有专门的单测 packages/ra-core/src/util/useEvent.spec.tsx并已在ra-core内部广泛使用。三、反模式红线这些写法不要在仓库中出现Agents.md列出的反模式清单本质上是设计原则的否定式表达Agent 在代码审查时应对照检查反模式理由禁用React.cloneElement()会破坏组合composition使组件树难以推理禁止检查 children违反 React 组合模式唯一例外是Datagrid因其需要反射子列配置不加纯 React 即可实现的功能保持 API 表面最小化不加多余的注释代码能自解释时不要写注释不留死代码信任前置条件不要防御前置代码已经排除的情况DRY 而非 DRY 过度巧合的相似代码不是重复只有当同一个决策或事实在多处表达时才去重。长得像但可以独立演进的代码应保持独立最后一条尤其值得注意——它是对DRY 强迫症的纠偏去重应以是否表达同一知识为准而非以代码是否相似为准。四、代码库组织Lerna 管理的一体化仓库Agents.md给出了仓库的顶层组织图结合实际目录可确认如下结构react-admin/ ├── packages/ # Lerna 管理的包 │ ├── ra-core/ # 核心逻辑、hooks、控制器 │ ├── ra-ui-materialui/ # Material UI 组件层 │ ├── react-admin/ # 主发行包 │ ├── ra-data-*/ # 数据提供器适配器 │ ├── ra-i18n-*/ # i18n provider │ └── ra-language-*/ # 翻译语言包 ├── examples/ # 示例应用 │ ├── simple/ # E2E 测试目标应用 │ ├── demo/ # 电商完整示例 │ ├── crm/ # CRM 应用 │ └── tutorial/ # 教程应用 ├── cypress/ # E2E 测试配置与用例 ├── docs/ # Jekyll 技术文档 ├── docs_headless/ # headless 组件的 Astro Starlight 文档 └── scripts/ # 构建/发布脚本仓库实际清单与之一一对应packages 下共 17 个包examples 下除上述四个应用外还有data-generator、no-code、ra-offlinescripts 下是release.sh、update-package-exports.ts、create-github-release.ts等工程脚本。Lerna 配置见 lerna.jsonpackages字段覆盖examples/data-generator、examples/simple与packages/*当前版本 5.15.3npmClient 为 yarnYarn 的 workspaces 配置见 package.json额外纳入cypress与docs_headless。五、依赖基线进入开发前的版本认知Agents.md明确了核心依赖的版本基线与 package.json 中声明相互印证核心React 18.3仓库声明^18.3.1、TypeScript 5.8^5.8.3、lodash 4.17、inflection 3.0路由React Router 6.28数据TanStack Query 5.90即 React Query表单React Hook Form 7.53UIMaterial UI 5.16测试与工程Jest 29.5、Testing Library、Storybook仓库声明^10.5.5、Cypress、Lerna^10.0.1、Prettier~3.2.5。包管理器为 Yarn 4.0.2见package.json的packageManager字段。workspaces将packages/*、examples/*、cypress、docs_headless统一纳入依赖管理。安装依赖在仓库根目录执行yarn installCI 下使用make install的冻结锁文件安装见 Makefile。六、测试要求所有改动必须带测试Agents.md规定 All changes must include tests并给出三层测试体系6.1 Stories每个组件都需要*.stories.tsx每个组件必须提供覆盖所有 props的 Storybook storiesmock 数据使用 FakeRestra-data-fakerest数据要真实可信——因为 stories 会用于截图与视觉回归测试。6.2 单元/集成测试*.spec.tsx复用 stories规范要求*.spec.tsx复用组件自己的 stories 作为测试用例storybook 的composeStories机制断言应面向用户可见输出文本、交互行为而不是实现细节或 HTML 属性——这是测试行为而非实现原则的体现。6.3 E2ECypress 保持精简E2E 测试刻意保持最小规模只覆盖关键用户路径目标应用固定为 examples/simple现有用例见 cypress/e2eauth.cy.js、create.cy.js、edit.cy.js、list.cy.js、show.cy.js、permissions.cy.js、mobile.cy.js、navigation.cy.js、customPages.cy.js、custom-forms.cy.js、tabs-with-routing.cy.js。Jest 配置位于 jest.config.jstestEnvironment为jsdom并通过moduleNameMapper将ra-*包名自动映射到各自src源码目录这正是测试跑在源码而非构建产物上的实现testTimeout设为 60 秒。七、文档要求每个 API 都必须有文档每个新特性或 API 变更都必须写文档并区分两套文档站点docsJekyll 站点每个组件或 hook 对应一个 Markdown 文件。每份文件必须包含描述、用法示例、props/参数列表必填项在前、其余按字母序、每个 prop 的详细用法、以及适用场景的 recipes。这也是该目录下存在useGetList.md、useCreate.md、Datagrid.md、SelectInput.md等大量单页文档的原因docs_headlessAstro Starlight 站点专门记录来自ra-core的 headless hooks 与组件。Agent 在新增或修改 API 时应同时检查是否需要在这两个站点补齐对应文档条目。八、Pull Request 规范Agents.md明确了协作流程的硬性约定目标分支新特性合入nextbug 修复与文档改动合入masterPR 标题以动词开头Add / Fix / Update / Remove如果改动只涉及文档或类型分别加[Doc]或[TypeScript]前缀提交信息遵循 Conventional Commits且重点说明为什么why而非做了什么whatfix: Prevent duplicate API calls in useGetList hook feat: Add support for custom row actions in Datagrid docs: Clarify dataProvider response format这条commit 要写 why的约定直接支撑了后续自动化生成 changelog 的流程见 scripts/update-changelog.ts 与 package.json 中changelog.labels对breaking change、feature、fix、Documentation、TypeScript的分类映射。九、静态分析与本地开发命令Agents.md给出的三个静态分析命令在 Makefile 中均有对应实现make lint # ESLint 检查对应 yarn lint覆盖 packages/examples/cypress 源码 make typecheck # TypeScript 类型检查对应 yarn typecheck通过 lerna run build 驱动 make prettier # Prettier 格式化对应 yarn prettierMakefile 还提供了完整的本地开发与测试入口例如make run-simple运行 simple 示例、make run-demo运行电商示例支持 REST/GraphQL 后端切换、make run-crm、make run-tutorial、make run-no-code、make run-offline构建与测试方面有make build逐包编译、make test 单元测试 lint E2E、make test-unit/make test-unit-watch/make test-e2e、make storybook与make build-storybook文档方面有make docJekyll 文档站点与make doc-headlessheadless 文档站点。十、给 Agent 的落地清单将上述规范归纳为一份可操作的 checklist便于 Agent 在 react-admin 仓库中完成任务时对照执行定位代码逻辑在ra-coreUI 在ra-ui-materialui主包在react-admin需要 provider 适配器时搜索ra-data-*/ra-i18n-*遵守架构红线不引入cloneElement、不检查 children除 Datagrid、不写死代码、不为可自解释代码加注释共享数据走 Context为需要跨层级暴露的数据创建 context并提供use*Contexthook事件处理器用useEvent参考 packages/ra-core/src/util/useEvent.ts 的实现模式改动必带测试新组件补*.stories.tsx与*.spec.tsx复用 stories、断言用户可见行为关键用户路径才补 Cypress 用例API 变更必更文档按 docs 的模板补齐组件/hook 文档页提交遵循规范特性走next、修复走master标题以动词开头commit 信息说明动机提交前跑静态分析make lint、make typecheck、make prettier三者通过后再提交。遵循这份上下文文档Agent 就能以与仓库维护者一致的方式工作产出风格统一、质量达标、易于被团队评审与维护的代码——这也正是Agents.md存在的全部意义让下一个进入仓库的智能体少走弯路。【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
React-Admin 项目架构与开发规范指南：Agent 上下文文档深度解读
React-Admin 项目架构与开发规范指南Agent 上下文文档深度解读【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-adminreact-admin 是一个基于 TypeScript、React 与 Material UI、面向 REST/GraphQL API 的单页应用前端框架由 Marmelab 维护专为 B2B 与后台管理系统设计。仓库根目录下的 Agents.md 是一份为 AI 编程助手Agent与人类协作者准备的项目上下文速查手册浓缩了该项目的设计哲学、反模式红线、代码库结构、依赖基线、测试要求与协作规范。读完本文你将理解 react-admin 为何采用 headless 核心 控制器/视图分离的架构掌握其核心开发约定与质量门槛并能在该仓库中快速定位模块、读懂测试结构与运行开发命令。一、这份文档是什么为 Agent 准备的仓库上下文Agents.md开篇即点明其定位它不是面向最终用户的框架文档而是面向 Agent 的上下文文件。它的价值在于让任何进入该仓库的 AI Agent 无需完整扫描数千个源文件即可快速建立起与维护者一致的心智模型从而在生成代码、定位问题、提交 PR 时遵循仓库既定惯例。值得注意的细节是仓库中的 CLAUDE.md 全文只有一行Agents.md——即通过引用指令将Agents.md作为唯一的项目上下文来源。这种单一事实源 引用的组织方式本身就是该仓库DRY不要重复知识原则的体现项目上下文只维护一份各工具入口统一引用避免多处维护导致信息漂移。全文围绕六个维度展开设计原则、反模式、代码库组织、包依赖、测试与文档要求、PR 规范与静态分析命令。下面逐层展开。二、设计原则从哲学到源码的验证2.1 SPA 优先的架构定位react-admin 被明确设计为单页应用SPA框架而不是服务端渲染或混合渲染优先的框架。这一点决定了其数据获取、路由与状态管理的整体形态应用启动时加载一次 Shell之后通过dataProvider以异步方式获取数据、通过 React Router 在客户端完成路由切换。仓库中 examples/simple、examples/demo 等示例应用均采用这种形态。2.2 向后兼容优先Backward compatibility over new features——避免破坏性变更是核心取舍准则。这意味着宁可暂缓引入新特性也不轻易改变既有 API 的行为。对 Agent 而言这条原则的实操含义是在修改任何被导出的 API 之前先检查其影响面优先以增量方式扩展而不是重写。2.3 最小 API 表面如果几行纯 React 就能实现就不要把它加进 core。这一原则直接控制着ra-core的膨胀速度。例如许多便捷组件实际上可以通过组合既有 hooks 与 MUI 组件在用户侧实现框架就不应提供专门的 API。对贡献者来说新增导出前应自问这个能力是否可以用现有 API 组合出来如果答案是肯定的它更可能属于用户代码而非框架核心。2.4 Provider 模式三大可替换适配器数据获取、认证、国际化被抽象在三个可替换的 provider 之后dataProvider统一所有数据读写getList、getOne、create、update、delete等authProvider统一登录、登出、权限检查login、logout、checkAuth、getPermissions等i18nProvider统一翻译与文案解析。这一模式在仓库结构中体现为独立成包的数据适配器族ra-data-*如ra-data-simple-rest、ra-data-fakerest、ra-data-json-server、ra-data-graphql、i18n 适配器族ra-i18n-*如ra-i18n-polyglot、ra-i18n-i18next以及翻译包ra-language-*如ra-language-english、ra-language-french。应用侧可以像插拔一样更换后端协议而不必改动业务组件——这正是 provider 模式的核心收益。2.5 Headless 核心逻辑与 UI 的刻意分离这是 react-admin 最具辨识度的架构决策逻辑全部放在ra-coreUI 渲染放在ra-ui-materialui且这种分离是刻意的intentional——绝不把逻辑耦合进 UI。从源码可以清晰看到这一分层packages/ra-core/src 下是auth、controller、core、dataProvider、form、i18n、routing、store、notification、inference、preferences等纯逻辑目录几乎不依赖任何具体 UI 库packages/ra-ui-materialui/src 下则是auth、button、detail、field、form、input、layout、list、theme等渲染层目录packages/react-admin/src/index.ts 是面向最终用户的主发行包它只做三件事export * from ./Admin、export * from ./defaultI18nProvider再聚合导出ra-core与ra-ui-materialui。换句话说一个不想要 Material UI 的用户完全可以只用ra-core自建 UI而 Material UI 层只是对核心逻辑的一套默认渲染实现。2.6 控制器/视图分离ra-core/src/controller/下的控制器如create/、edit/、list/、show/、saveContext/、field/、input/以 hooks 形式暴露业务逻辑ra-ui-materialui/src下的视图组件消费这些 hooks 完成渲染。典型链路是ListController/useListController提供数据与回调 →List视图组件渲染。这种分离让同一套逻辑可以被不同的 UI 皮肤复用也便于单元测试——直接对 controller hooks 做断言无需挂载 DOM。2.7 Context拉取而非推送Pull, dont push组件通过 context 自定义 hooks 向子孙暴露数据而不是层层 prop drilling。每一个会获取数据或定义回调的组件都会为它创建一个 context。这在ra-core中体现为大量的use*Contexthooks如useListContext、useEditContext、useShowContext、useRecordContext、useSaveContext对应文档见 docs 目录下的useListContext.md、useEditContext.md等。对使用者而言深层组件不再需要手动透传 props而是通过 hook 就近拉取数据对 Agent 而言新增需要跨层级共享的数据时正确做法是新增 context而不是增加 props 深度。2.8 使用内部useEvent()而非useCallbackAgents.md明确要求记忆化事件处理器使用内部useEvent而不是useCallback。其实现位于 packages/ra-core/src/util/useEvent.tsexport const useEvent Args extends unknown[], Return( fn: (...args: Args) Return ): ((...args: Args) Return) { const ref React.useRef(...args: Args) Return(() { throw new Error(Cannot call an event handler while rendering.); }); useLayoutEffect(() { ref.current fn; }); return useCallback((...args: Args) ref.current(...args), []); };从源码可以看出其设计巧思函数引用被存放在 ref 中每次渲染通过useLayoutEffect同步更新SSR 环境下退化为useEffect但对外暴露的永远是同一个useCallback引用。这样既保证了事件处理器引用稳定避免子组件无谓重渲染又始终能调用到最新闭包中的函数——解决useCallback依赖数组需要不断变化的痛点。该 hook 配有专门的单测 packages/ra-core/src/util/useEvent.spec.tsx并已在ra-core内部广泛使用。三、反模式红线这些写法不要在仓库中出现Agents.md列出的反模式清单本质上是设计原则的否定式表达Agent 在代码审查时应对照检查反模式理由禁用React.cloneElement()会破坏组合composition使组件树难以推理禁止检查 children违反 React 组合模式唯一例外是Datagrid因其需要反射子列配置不加纯 React 即可实现的功能保持 API 表面最小化不加多余的注释代码能自解释时不要写注释不留死代码信任前置条件不要防御前置代码已经排除的情况DRY 而非 DRY 过度巧合的相似代码不是重复只有当同一个决策或事实在多处表达时才去重。长得像但可以独立演进的代码应保持独立最后一条尤其值得注意——它是对DRY 强迫症的纠偏去重应以是否表达同一知识为准而非以代码是否相似为准。四、代码库组织Lerna 管理的一体化仓库Agents.md给出了仓库的顶层组织图结合实际目录可确认如下结构react-admin/ ├── packages/ # Lerna 管理的包 │ ├── ra-core/ # 核心逻辑、hooks、控制器 │ ├── ra-ui-materialui/ # Material UI 组件层 │ ├── react-admin/ # 主发行包 │ ├── ra-data-*/ # 数据提供器适配器 │ ├── ra-i18n-*/ # i18n provider │ └── ra-language-*/ # 翻译语言包 ├── examples/ # 示例应用 │ ├── simple/ # E2E 测试目标应用 │ ├── demo/ # 电商完整示例 │ ├── crm/ # CRM 应用 │ └── tutorial/ # 教程应用 ├── cypress/ # E2E 测试配置与用例 ├── docs/ # Jekyll 技术文档 ├── docs_headless/ # headless 组件的 Astro Starlight 文档 └── scripts/ # 构建/发布脚本仓库实际清单与之一一对应packages 下共 17 个包examples 下除上述四个应用外还有data-generator、no-code、ra-offlinescripts 下是release.sh、update-package-exports.ts、create-github-release.ts等工程脚本。Lerna 配置见 lerna.jsonpackages字段覆盖examples/data-generator、examples/simple与packages/*当前版本 5.15.3npmClient 为 yarnYarn 的 workspaces 配置见 package.json额外纳入cypress与docs_headless。五、依赖基线进入开发前的版本认知Agents.md明确了核心依赖的版本基线与 package.json 中声明相互印证核心React 18.3仓库声明^18.3.1、TypeScript 5.8^5.8.3、lodash 4.17、inflection 3.0路由React Router 6.28数据TanStack Query 5.90即 React Query表单React Hook Form 7.53UIMaterial UI 5.16测试与工程Jest 29.5、Testing Library、Storybook仓库声明^10.5.5、Cypress、Lerna^10.0.1、Prettier~3.2.5。包管理器为 Yarn 4.0.2见package.json的packageManager字段。workspaces将packages/*、examples/*、cypress、docs_headless统一纳入依赖管理。安装依赖在仓库根目录执行yarn installCI 下使用make install的冻结锁文件安装见 Makefile。六、测试要求所有改动必须带测试Agents.md规定 All changes must include tests并给出三层测试体系6.1 Stories每个组件都需要*.stories.tsx每个组件必须提供覆盖所有 props的 Storybook storiesmock 数据使用 FakeRestra-data-fakerest数据要真实可信——因为 stories 会用于截图与视觉回归测试。6.2 单元/集成测试*.spec.tsx复用 stories规范要求*.spec.tsx复用组件自己的 stories 作为测试用例storybook 的composeStories机制断言应面向用户可见输出文本、交互行为而不是实现细节或 HTML 属性——这是测试行为而非实现原则的体现。6.3 E2ECypress 保持精简E2E 测试刻意保持最小规模只覆盖关键用户路径目标应用固定为 examples/simple现有用例见 cypress/e2eauth.cy.js、create.cy.js、edit.cy.js、list.cy.js、show.cy.js、permissions.cy.js、mobile.cy.js、navigation.cy.js、customPages.cy.js、custom-forms.cy.js、tabs-with-routing.cy.js。Jest 配置位于 jest.config.jstestEnvironment为jsdom并通过moduleNameMapper将ra-*包名自动映射到各自src源码目录这正是测试跑在源码而非构建产物上的实现testTimeout设为 60 秒。七、文档要求每个 API 都必须有文档每个新特性或 API 变更都必须写文档并区分两套文档站点docsJekyll 站点每个组件或 hook 对应一个 Markdown 文件。每份文件必须包含描述、用法示例、props/参数列表必填项在前、其余按字母序、每个 prop 的详细用法、以及适用场景的 recipes。这也是该目录下存在useGetList.md、useCreate.md、Datagrid.md、SelectInput.md等大量单页文档的原因docs_headlessAstro Starlight 站点专门记录来自ra-core的 headless hooks 与组件。Agent 在新增或修改 API 时应同时检查是否需要在这两个站点补齐对应文档条目。八、Pull Request 规范Agents.md明确了协作流程的硬性约定目标分支新特性合入nextbug 修复与文档改动合入masterPR 标题以动词开头Add / Fix / Update / Remove如果改动只涉及文档或类型分别加[Doc]或[TypeScript]前缀提交信息遵循 Conventional Commits且重点说明为什么why而非做了什么whatfix: Prevent duplicate API calls in useGetList hook feat: Add support for custom row actions in Datagrid docs: Clarify dataProvider response format这条commit 要写 why的约定直接支撑了后续自动化生成 changelog 的流程见 scripts/update-changelog.ts 与 package.json 中changelog.labels对breaking change、feature、fix、Documentation、TypeScript的分类映射。九、静态分析与本地开发命令Agents.md给出的三个静态分析命令在 Makefile 中均有对应实现make lint # ESLint 检查对应 yarn lint覆盖 packages/examples/cypress 源码 make typecheck # TypeScript 类型检查对应 yarn typecheck通过 lerna run build 驱动 make prettier # Prettier 格式化对应 yarn prettierMakefile 还提供了完整的本地开发与测试入口例如make run-simple运行 simple 示例、make run-demo运行电商示例支持 REST/GraphQL 后端切换、make run-crm、make run-tutorial、make run-no-code、make run-offline构建与测试方面有make build逐包编译、make test 单元测试 lint E2E、make test-unit/make test-unit-watch/make test-e2e、make storybook与make build-storybook文档方面有make docJekyll 文档站点与make doc-headlessheadless 文档站点。十、给 Agent 的落地清单将上述规范归纳为一份可操作的 checklist便于 Agent 在 react-admin 仓库中完成任务时对照执行定位代码逻辑在ra-coreUI 在ra-ui-materialui主包在react-admin需要 provider 适配器时搜索ra-data-*/ra-i18n-*遵守架构红线不引入cloneElement、不检查 children除 Datagrid、不写死代码、不为可自解释代码加注释共享数据走 Context为需要跨层级暴露的数据创建 context并提供use*Contexthook事件处理器用useEvent参考 packages/ra-core/src/util/useEvent.ts 的实现模式改动必带测试新组件补*.stories.tsx与*.spec.tsx复用 stories、断言用户可见行为关键用户路径才补 Cypress 用例API 变更必更文档按 docs 的模板补齐组件/hook 文档页提交遵循规范特性走next、修复走master标题以动词开头commit 信息说明动机提交前跑静态分析make lint、make typecheck、make prettier三者通过后再提交。遵循这份上下文文档Agent 就能以与仓库维护者一致的方式工作产出风格统一、质量达标、易于被团队评审与维护的代码——这也正是Agents.md存在的全部意义让下一个进入仓库的智能体少走弯路。【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
