React app
React app 标记 React 是主要用户界面、管理台、控制台或嵌入式操作面 runtime。这里关心的是 route、component tree、client state、表单流、dashboard 交互和前端构建后的真实运行边界,而不是“项目依赖里有 React”。 这个 Topic 用来回答“用户实际操作的是不是一个 React runtime,以及它在系统里承担什么职责”。
- 前端
目录
Definition
React app 标记 React 是主要用户界面、管理台、控制台或嵌入式操作面 runtime。这里关心的是 route、component tree、client state、表单流、dashboard 交互和前端构建后的真实运行边界,而不是“项目依赖里有 React”。
这个 Topic 用来回答“用户实际操作的是不是一个 React runtime,以及它在系统里承担什么职责”。它不替代 shadcn/ui、Storybook component QA、embedded admin UI 或 TypeScript web;这些 Topic 分别解释组件系统、QA surface、随服务交付的形态和底层 tooling。很多样本都不是“纯 React 产品”,而是 Rust service、Cloudflare Worker、Astro public site 或 firmware 系统里的一个操作面,所以必须把 React 的责任边界单独讲清楚(projects/kaisoumail.md、projects/loadlynx.md、projects/proxy-broker.md)。
When to use
当 web/、apps/web/、apps/admin/ 或 web/src/main.tsx 等入口证明 React/Vite/SPA 是产品界面时使用。纯文档站或只含 React 依赖的脚本不应自动命中。
如果改动会影响 React route、component state、form、dashboard、operator workflow、控制台 auth、SSE/polling 消费、theme、embedded UI build 或版本显示,就应使用本 Topic。若 React 只出现在示例、测试 fixture、历史依赖或由 Astro/MDX 间接使用,必须先核对当前入口、运行脚本和 project snapshot 再决定(projects/blog-26.md、projects/codex-vibe-monitor.md)。
Habits / defaults
- Rust-backed services常把 React app embed 到同一 binary;要同时验证 web build 和 backend build。
- React app 的项目标题不应显示 npm package name;用产品/系统名作为 H1。
- 当 React app 采用 shadcn/ui,组件系统由
shadcn/uiTopic 说明,不要把所有 UI 规则塞进 React app。 - 设备/ops UI 应保留 Storybook/Playwright/visual evidence 的项目记忆。
- React app 的验证默认至少包含 typecheck/build;对 owner-facing UI 还应结合 Storybook、Playwright 或浏览器截图证据,尤其是表单、表格、Dialog、长文本和空态(
projects/proxy-broker.md、projects/kaisoumail.md)。 - 命中本 Topic 的 React 任务默认采用项目锁定版本的 React Doctor;目标项目未接入时,执行该任务的 Agent 应在当前 React 任务中补齐锁定依赖、版本化配置和现有 hook 接入,Playbook 本身不自动改写目标项目(
https://github.com/millionco/react-doctor)。 - React Doctor 的 pre-commit 以 staged React 文件为输入,CI 以 changed React 文件为输入;先成功计算下述文件集合,Git diff、base 解析或范围计算失败必须 fail-closed,不能当作空集合。集合为空时跳过并通过,不要求 React Doctor、依赖、锁文件或配置可执行;集合非空时才检查项目锁定工具及依赖、锁文件和配置,任一无法执行均阻断。执行成功后,
error阻断提交或 merge,warning保持可见但不阻断。 - CI 的 React Doctor 结果必须由 required check 承载;承载 job、失败传播、空集合状态和实际分支规则核验遵循
skills/style-playbook/references/topics/quality-gates/TOPIC.md。完整项目检查仍由 typecheck、build、测试和其他交付面 gate 负责。 - 复用目标项目已有的 hook 管理器,不覆盖现有 hook;monorepo 只检查受影响的 React package,多交付面项目只把 React UI 纳入本默认契约,后端、固件和其他 UI 由相邻 Topic 覆盖。
- 使用项目现有 package manager 和锁定版本,不在 hook 中使用
npx react-doctor@latest或临时联网安装;规则例外通过下述版本化配置与审计注释表达,不通过本地命令参数静默绕过(https://react.doctor/docs/getting-started/install-for-coding-agents)。 - 当前适用范围是 Web React;React Native 和 Expo 不继承本默认契约。
- 对嵌入后端 binary 的 React UI,要同时检查前端 build 输出和后端静态资源服务路径;只跑其中一侧会漏掉版本注入、asset path 或 cache 问题(
projects/codex-vibe-monitor.md)。 - 先回答 React UI 是“主产品面”还是“辅助操作面”。
projects/kaisoumail.md的 control plane、projects/loadlynx.md的设备 UI、projects/proxy-broker.md的 operator console,风险和验证重点都不同,不能沿用同一套默认话术。 - 对控制台类 React app,auth 和数据流通常和页面本身一样重要。Forward Auth、owner API key、Cloudflare identity/passkeys、SSE/polling 这些都属于 React surface 的真实边界,因为用户在 UI 上看到的行为取决于它们(
projects/proxy-broker.md、projects/kaisoumail.md、projects/codex-vibe-monitor.md)。 - 若 React app 只是 hybrid repo 的一个面,回答问题时默认把相邻 runtime 一起纳入检查清单。像
projects/blog-26.md需要同时考虑 Astro/Next/gateway,不能只修 React 页面就宣称主题已覆盖。
React Doctor 文件选择
- pre-commit 的 staged 集合来自
HEAD到 Git index 的差异;首次提交没有HEAD时使用空树到 index 的差异。PR CI 的 changed 集合来自merge-base(base SHA, head SHA)到候选 head 的差异,base/head 取 PR 事件元数据;其他 CI 入口必须显式提供比较 base/head,不假定main、master或origin/main。所需 ref、历史或 merge-base 不可解析时阻断。 - Git 文件列表使用 NUL 分隔,以正确处理空格等路径字符;选择
ACMRT的目标路径,即新增、复制、修改、重命名和类型变化。纯删除不进入扫描集合,重命名使用新路径;参与扫描的路径必须在对应 index 或候选 head 中存在。 - 根据目标项目版本化的 workspace/package 声明、构建配置和 React 入口确定 Web React 源码根,纳入其中的
.js、.jsx、.ts、.tsx,包括相关 hooks/helpers。排除依赖目录、构建产物和版本化配置明确标记的生成目录;不能只按.tsx后缀或 React import 过滤,也不能把全仓所有 TypeScript 文件都视为 React 文件。 - 按源码归属分组到受影响的 React package,传给该 package 使用的项目锁定 React Doctor 与配置;不扫描未受影响的 package,也不把后端、固件等相邻交付面混入输入。路径归属或排除范围无法确定属于范围计算失败,不能静默跳过。
- 将筛选后的文件路径作为显式输入,报告这些文件的全部诊断;执行时不得让配置中的 partial scope 把结果收窄为仅新增问题或 changed lines。
--scope changed只报告相对 base 新引入的问题,不等于“选中文件中的全部诊断”,不能代替本契约。输入与诊断归属收敛到所选文件不表示内部分析绝不读取项目上下文;例如 maintainability 分析可能读取完整源码语料(https://www.react.doctor/docs/reference/cli-reference)。
React Doctor 规则例外
规则例外必须进入版本化 doctor.config.*。优先使用 doctor.config.ts,已有 .jsonc 可继续使用;在对应的 rules 或 ignore.overrides 配置旁以注释记录准确规则 ID、理由、影响路径/package 和复核日期。机器配置对象只使用 React Doctor 支持的字段,不添加 reason、reviewDate 等未知审计属性(https://www.react.doctor/docs/configuration/config-files)。
下面按两条 TypeScript 语句示范 doctor.config.ts 的合法审计格式;只有目标项目已验证理由成立时才采用该例外,其他文件仍执行同一规则:
import { defineConfig } from "react-doctor/api";export default defineConfig({ ignore: { overrides: [{ /* 规则:react-doctor/no-danger;理由:此组件只消费经统一 HTML 净化入口处理且已验证的内容;影响范围:当前 React package 的 src/components/SanitizedHtml.tsx;复核日期:2027-01-14。 */ files: ["src/components/SanitizedHtml.tsx"], rules: ["react-doctor/no-danger"] }] } });
Reference implementations
projects/proxy-broker.md:Rust service + embedded shadcn/ui operator console。projects/kaisoumail.md:Cloudflare control plane 的 React UI。projects/blog-26.md:admin SPA 与 Astro/Next runtime 共存。projects/loadlynx.md:设备 Web UI 作为双 MCU 系统的辅助控制面。projects/codex-vibe-monitor.md:React dashboard 通过 REST API 与 SSE 消费 Rust service 数据,适合检查 UI runtime 与后端事件流如何共同形成产品。projects/flux-purr.md:设备控制台把 React UI 放在 hardware/firmware mono-repo 内,提醒维护者 UI 变化可能牵动真实设备语义。
Failure modes
- 把 React app 当成项目整体,会掩盖后端、固件或文档站边界。
- 只跑 backend tests 不跑 web build/e2e,会漏掉 embedded UI 失败。
- 把组件库选择写成 React Topic,会让 shadcn/ui / Storybook 规则失焦。
- 只根据
package.json依赖打标签会误伤文档站或历史包;应核对src/main.tsx、route entry、build scripts 和项目快照中对 UI surface 的描述(projects/blog-26.md)。 - React UI 预览通过不等于真实系统通过。对设备、ops 或 proxy dashboard,API、auth、SSE/polling、硬件状态和部署路径仍要在相邻 Topic 中记录验证边界(
projects/loadlynx.md、projects/proxy-broker.md)。 - 把 React surface 当作纯视觉层处理,会漏掉控制台的权限和数据契约。很多维护事故不是按钮样式错,而是 UI 连到了错误的 API、错误的 auth 上下文或错误的事件流(
projects/kaisoumail.md、projects/codex-vibe-monitor.md)。 - 混淆“公开站点的 React 岛”和“真正的 React app runtime”也很常见。修正方式是回看项目快照里是否存在独立
web//apps/admin/、独立 dev/build/preview 脚本,以及 UI 是否承担持续的用户任务。 - 将 React Doctor 的
error结果作为非阻断建议,会使默认质量契约失去阻断价值;应保留error阻断、warning仅报告的结果语义。 - 在 hook 中使用
@latest、临时联网安装或未锁定依赖,会让本地提交结果随时间漂移;应使用项目现有 package manager 和锁定版本。 - 让 pre-commit 扫描整个仓库或把无关交付面混入 React Doctor,会拖慢本地反馈并扩大责任边界;应按 staged/changed React 文件和受影响 package 收敛范围。
- 文件集合非空时,React Doctor 或其依赖、锁文件、配置无法执行却继续放行,会把“未检查”误报为“通过”;工具执行失败必须 fail-closed。成功确认空集合时应直接跳过,不先检查工具;Git diff、base 解析和范围计算失败也不得伪装成空集合。
- 使用工具自行猜测的 base、只按
.tsx过滤、忽略重命名目标或使用--scope changed只拦新增问题,会偏离 staged/changed 文件契约;应使用明确的 Git 比较范围、package 归属和显式文件输入,报告选中文件的全部诊断。 - 通过临时命令参数绕过规则而不留下版本化记录,会使例外不可审计;在配置对象里臆造审计字段也不合法。例外应使用受支持的配置字段,并通过相邻注释记录规则、理由、影响范围和复核日期。
- 把 React Doctor 当成 typecheck、build、测试、Storybook、Playwright、后端、固件或其他交付面检查的替代品,会留下未覆盖的系统风险。
Evidence index
projects/proxy-broker.mdprojects/blog-26.mdprojects/kaisoumail.mdprojects/loadlynx.mdskills/style-playbook/references/topics/shadcn-ui/TOPIC.mdskills/style-playbook/references/topics/quality-gates/TOPIC.mdhttps://github.com/millionco/react-doctorhttps://react.doctor/docs/getting-started/install-for-coding-agentshttps://www.react.doctor/docs/reference/cli-referencehttps://www.react.doctor/docs/configuration/config-fileshttps://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
相关内容
Ivan's Blog 2026
项目实践Ivan's Blog 2026 是 Ivan 博客平台的公开开源镜像,由 Astro public site、Vite/React admin SPA 和 Bun gateway/API 组成。README.md、astro.config.mjs、apps/admin/、src/server/ 和 package.
Codex Vibe Monitor
项目实践Codex Vibe Monitor 是面向自部署的 OpenAI 兼容代理观测工作台:它接入 /v1/* HTTP / WebSocket 流量,将调用留证、实时 SSE、历史统计、请求排障、上游账号池、forward proxy、价格目录和 SQLite 持久化收在同一套运营界面中。
Dockrev
项目实践Dockrev 是 self-hosted Docker/Compose update manager。README.md 把根文档定位为快速入口,完整部署、使用、运维、排障和 API 文档在 docs-site/,这说明它是运维工具而不是普通 CRUD 管理台。
Flux Purr
项目实践Flux Purr 是 embedded firmware + React control console 的设备 mono-repo。README.md 将仓库组织为 firmware/、web/、tools/flux-purr-devd/、docs/specs/、docs/hardware/、.
IsolaPurr USB Hub
项目实践IsolaPurr USB Hub 是带 USB-C 上行、USB-C 下行和 USB-A 下行的有源 USB 集线器/供电模块。README.md 记录 CH334P、URB2405S、CH224Q、TPS55288、SW2303/IP6557、DC5025 输入和理想二极管 OR-ing 等硬件方案,说明这是硬件/固件/Web/文档一体的 device mono-repo。
KaisouMail
项目实践KaisouMail 是 Cloudflare temporary email platform,基于 Email Routing、Workers、D1、R2,以及 React + shadcn/ui control plane。README.md 和 README.zh-CN.md 同时存在,说明文档需要中英双语入口;公开 docs site 与 Storybook 也是产品交付面,而不只是开发辅助。
LoadLynx
项目实践LoadLynx 是 STM32G431 + ESP32-S3 便携式电子负载。README.md 明确采用分体式架构:STM32G431 执行快速电流/功率闭环与保护,ESP32-S3 负责 UI/Wi-Fi/OTA/记录/标定及上位机桥接。这是典型 device mono-repo,不能只从一个 firmware 目录理解。
MCU Agentd
项目实践MCU Agentd 是可配置 MCU 管理工具,包含每项目 daemon/CLI mcu-agentd 和用户级辅助 daemon mcu-managerd。README.md 明确它通过 mcu-agentd.toml 定义多个 MCU target,并基于 espflash 与 probe-rs 执行操作,当前 v1 只支持 ELF artifact 和固定策略。
OctoRill
项目实践OctoRill 把与 Ivan 相关的 GitHub 动态整理成适合持续阅读的工作区:发布更新、获星/关注动态、日报和 Inbox,发布内容还支持中文翻译和要点整理。README.md 同时指向 public docs-site、quick start、config、product 和 internal docs,说明它是产品化 Rust 服务 + React UI + 文档站,而不是一次性脚本。
Oidrune
项目实践Oidrune 是一个由运营者控制的 GitHub Actions 通知中继:它验证短期 GitHub OIDC 身份,只接受已批准来源的 workflow completion event,并把调用方提供的规范化正文投递到一个运营者控制的 Telegram destination。
PastePreset
项目实践PastePreset 是一个 privacy-first、纯浏览器端的图片处理 Web app。package.json、README.md、docs/pwa-offline-support.md 和 public/manifest.
Proxy Broker
项目实践Proxy Broker 是 standalone Rust service,用于加载 mihomo subscriptions,按 IP 构建带 probe/geo metadata 的代理池,按选择的 IP 开关本地 proxy listener sessions,并从同一 binary 提供 Bun-built operator web console。README.
Style Playbook Skills
项目实践Style Playbook Skills 是 Ivan style playbook 的 source-of-truth 仓库:它保存人工维护的 project snapshots、Topic packages、六个 global group Skills,以及用于浏览、筛选和触发生成任务的本地 library site。
Tavily Hikari
项目实践Tavily Hikari 是 Rust + Axum proxy,用于 Tavily MCP endpoint:它复用多 API key、匿名化上游请求、把完整 audit logs 写入 SQLite,并附带 React + Vite web console 做实时可视化。README.md 与 README.zh-CN.md 说明这个项目同时服务英文/中文维护入口。
Tuckmark
项目实践Tuckmark 是一个 agent-native label printing workspace,统一承载打印机发现、能力探测、模板渲染、批量预览、位图打印,以及 CLI、MCP、HTTP 和 Web surfaces(README.md)。
XP Cluster Manager
项目实践XP Cluster Manager 是 self-hosted multi-host Xray cluster manager。README.md 明确每台 host 运行 xp 和 xray 两个进程,xp 用 OpenRaft 保存 cluster-wide desired state,并通过 Xray gRPC API reconcile 本地 runtime。