react

React 应用工程

将此技能用于 React 特定的实现层。除非用户要求迁移，否则保留项目现有的 React 版本、包管理器、构建脚本、样式约定和路由模型。

操作流程

1. 编辑前先诊断。 运行 scripts/react-doctor.py --json [PROJECT]，并检查 package.json、源码入口、Vite 配置、TypeScript 配置、路由和测试脚本。诊断范围有限且只读。
2. 定义组件契约。 明确页面／功能边界、输入和输出、自有状态、服务端状态、加载／空／错误／成功状态以及副作用。让可复用组件独立于路由全局对象，并避免通过无关层传递状态。
3. 明确数据流后再实现。 局部行为优先使用局部状态；只有确实需要跨领域共享时才使用 context；远程数据则使用现有的服务端状态／缓存方案。将 effect 用于与外部系统同步；在渲染期间推导值，而不是存储重复数据。
4. 确保 UI 具有韧性。 提供实用的加载、空、错误和成功体验。取消或忽略过期的异步任务，处理中止情况，避免在过时请求完成后设置状态。保留稳定的 key，避免修改 props 或状态。
5. 面向浏览器构建。 使用语义化 HTML、可通过键盘操作的控件、清晰可见的焦点、响应式布局以及稳定的无障碍名称。详细的无障碍要求请参阅 web-accessibility。
6. 分层验证。 先运行范围最小的现有单元／组件测试，再运行 lint／类型检查，最后执行生产构建。浏览器级流程请使用 playwright，不要临时编写浏览器自动化。报告确切的命令，以及跳过的、依赖环境的检查。

React 特定规则

• 每次渲染时，Hooks 都必须无条件地按相同顺序执行；切勿在分支、循环、事件处理程序或嵌套函数中调用 Hooks。
• Effects 用于与外部系统同步。不要用 effect 计算可由 props／状态推导出的值，也不要在没有明确用户编辑需求时将 props 镜像到状态中。
• 当下一个状态依赖于前一个状态时，使用函数式更新。如果列表可能重新排序、插入或删除，请使用基于领域实体标识的稳定 key，而不是数组索引。
• 将事件处理程序视为用户意图，并与渲染时的计算分开。禁用或防护重复提交，并显示待处理状态。
• 在集成边界验证和转换 API 响应；组件应使用类型明确、行为可预测的视图模型。
• 不要仅仅因为某个状态库或路由器很流行就添加它。应先梳理状态归属，并采用项目现有的方案。
• 在 Vite 中，只通过项目文档规定的前缀（通常为 VITE_）公开有意公开的变量；绝不要将密钥放入客户端包。请阅读 references/vite-diagnostics.md，了解环境、构建和部署检查。

路由与交接

• 组件架构、响应式实现、性能预算和通用前端测试：frontend-engineering。
• 浏览器 E2E 编写、定位器选择、网络拦截和 Playwright 运行：playwright。
• 语义结构、键盘／焦点行为、WCAG 验收证据和无障碍审计：web-accessibility。
• React Native、Expo、Android 或 iOS 实现：mobile-development。

参考路由

加载时机	参考资料
选择组件边界、状态归属、副作用或异步 UI 行为时	references/component-and-state.md
诊断 Vite 环境变量暴露、依赖版本、构建输出或部署路径时	references/vite-diagnostics.md

内含脚本

scripts/react-doctor.py 是一款只读、无依赖的诊断工具。运行 scripts/react-doctor.py --help 可查看选项。它接受项目目录作为输入， 检查常见的 React/Vite 信号，并输出人类可读格式或有限长度的 JSON 结果。它不会安装软件包、执行项目脚本、访问网络或打印环境变量值。

完成范围

当所需的 React 更改已实现、项目相关检查已运行，并且剩余失败均已附上命令和根因证据后，即可停止。未经明确要求，不要将组件任务扩展为框架迁移或无障碍审计。