cloudflare-os 前端开发规范实战：Workshop 与 Gatekeeper 管理界面的 React、Kumo 与测试约定

人工智能AI 应用AI AgentAgent 沙箱AI 安全治理【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址https://gitcode.com/gh_mirrors/cl/cloudflare-os点击查看免费下载本文以仓库内 frontend-conventions 技能文档 为核心骨架系统讲解 cloudflare-os 项目中 Workshop SPA、各 gatekeeper 管理 SPA 以及共享 UI 包gadgets/ui的统一前端开发约定。读完本文你将掌握这套项目在代码组织、组件与 Hooks 抽取、组件 API 设计、Kumo 样式体系、React 语义、注释与测试上的完整规范并看到它们在gadgets/ui的HierarchicalList源码中的真实落地形态可直接套用于该仓库内任何packages/*下的 React 前端开发与评审。适用范围与文档定位frontend-conventions是仓库内一个以 Agent 技能SKILL.md形式沉淀的规范文档其元信息frontmatter明确了触发场景创建、修改、移动或评审packages/*中任何位置的 React 前端代码涵盖 Workshop 页面、gatekeeper 管理应用、共享 UI、组件、Hooks、表单、交互、样式、可访问性与前端测试。规范适用的三块前端面Workshop SPApackages/workshop-frontend纯客户端单页应用通过持久 WebSocket 上的 RPC API 与后端通信使用 React、Kumo UI、Phosphor icons 与 Vite。各 gatekeeper 管理 SPApackages/gatekeeper-*下的src/configurator/、app/等目录例如 gatekeeper-context 的 Context Library 管理界面、gatekeeper-scheduler 的管理页面。共享 UI 包gadgets/uipackages/ui跨应用复用的运行期 React UI 层。需要特别强调的是层级关系各包的AGENTS.md会补充产品特定的规则但不能取代本规范本规范是所有包之上的公共底线。仓库根 AGENTS.md 中的前端约定小节即是对本技能文档的强制摘要并要求在packages/*下动 React 前端代码前先加载本技能。所有权优先的代码组织按产品归属组织而非按实现类型规范的第一原则是代码按产品归属product ownership组织先于按实现类型组织。功能目录feature directory拥有产品行为可以把因为同一个原因而变更的组件、Hooks、测试与工具函数放在一起。这与按文件类型分目录的传统习惯相反——不应仅仅为了分类而引入components/、hooks/、helpers/、tests/这类子目录。只有在多个文件构成一个内聚单元、或扁平目录已难以扫读时才引入以职责命名的子系统目录。命名与测试文件位置组件文件名用PascalCaseHooks 与非组件模块文件名用camelCase*.test.ts(x)测试文件与被测主体同目录放置colocate功能目录组织不能取代一组件一文件one-component-per-file的模型。代码提升的所有权边界产品行为必须留在所属产品内即使被其他功能消费也要留在原地。提升promote代码只能提升到其所有权所要求的最高层级共有四档代码归属放置位置单功能内部共享最近的公共功能目录同一应用内跨无关区域、与功能无关该应用的components/或hooks/目录多个独立前端共享的运行期 UIgadgets/ui产品特定的组合留在产品侧即使底层使用了共享原语两点硬性约束不要因为组件长得像就合并它们避免用泛化、重 prop 的抽象抹掉领域行为。这在gadgets/ui的 AGENTS.md 中有呼应只有至少两个独立前端需要同一与功能无关的行为、或跨前端一致性是明确产品需求时才把组件放进gadgets/ui产品数据获取、路由、RPC、权限与领域工作流必须留在消费方应用内。组件与 Hooks 的抽取准则什么时候该拆组件当它拥有有意义的状态、副作用、交互、可访问性行为或可复用职责时当它代表一个独立的 UI 关注点时当它遮挡了父组件主流程时。小而无状态的渲染辅助函数保持私有直到它们发展出独立关注点为止。什么时候该抽 Hooks当它拥有连贯的行为或外部同步生命周期时——而不是仅仅为了缩短文件。反过来如果抽出的子组件大部分只是在转发标记markup或高度依赖父组件的 refs、setters 与同步回调就不要拆让代码留在原地。组件/Hooks 书写风格优先使用具名箭头函数组件与 Hooksprops 直接类型标注不要使用React.FC对memo、forwardRef这类包装器要给出稳定的 DevTools 名称命名包装便于调试。组件 API 约定Props 建模仅在同时出现时才有意义的 props建模为对象或可辨识联合discriminated union。受控值必须有变更回调否则就暴露非受控的初始值uncontrolled initial value。不要用 Effect 把受控 prop 复制进本地 state——这是规范明确禁止的反模式。一个现成的落地例子是gadgets/ui中 HierarchicalList.types.ts 里的HierarchicalListExpansionProps它是一个可辨识联合——要么是受控形态{ expandedIds, onExpandedChange }要么是非受控形态{ initialExpandedIds }受控值expandedIds与回调onExpandedChange永远成对出现且两种形态互斥expandedIds?: never/initialExpandedIds?: never从类型层面杜绝了只传值不传回调的用法。回调命名与传值回调统一命名为onAction如onItemClick、onSelectionClear、onExpandedChange、onMove。回调传递领域值domain values而不是 React setter 或浏览器事件对象。例如HierarchicalList的onMove收到的是(item, destination)renderContextMenu收到的是列表项本身。自定义扩展面children、slots、variants、className、DOM 透传、命令式 ref只为当前调用方添加不做投机式复用speculative reuse的预留。Context 的边界Context 只用于真正应用级的值认证authentication、主题theme、toast 提示等实例相关的功能数据与动作必须通过 props 传递。这保证了组件复用不依赖隐式上下文。Kumo 与样式约定默认使用 Kumo 组件与语义 token默认使用Kumo 组件与语义 token动手创建控件或交互模式前先检查 Kumo 与gadgets/ui是否已有现成方案。共享 Gadgets 组件应当组合composeKumo 行为而不是仅仅重命名或重排一个 Kumo 原语不要包一层只为了改样式。禁止引入自定义颜色字面量、任意 Tailwind 颜色、功能本地 token 体系或为 Kumo 的 surface、border、text、status、focus、interaction token 做本地替代——除非用户明确要求。已有的遗留颜色不是先例不能作为新代码的依据。Tailwind 与自定义 CSS 的分工场景手段结构、间距、尺寸、定位、响应式、排版Tailwind 工具类Kumo 与工具类无法表达的技术行为自定义 CSS全局 Kumo token 主题化应用级决策普通功能开发中不得改动gadgets/ui的 AGENTS.md 补充了一个关键实操细节由于共享组件里的工具类由消费方应用编译Tailwind 消费方必须把packages/ui/src加入source否则共享组件的 utility class 不会被生成。源码印证HierarchicalList的 Kumo 落地在 HierarchicalList.tsx 中可以看到这套约定的完整实践基础控件全部来自 KumoButton、DropdownMenu、LayerCard、Text以及 primitives 下的ContextMenu、Drawer、Menu缩进、拖拽预览、下拉指示器等全部用语义 tokenbg-kumo-control、text-kumo-default、ring-kumo-line、bg-kumo-recessed、text-kumo-subtle、text-kumo-inactive、border-kumo-brand、bg-kumo-brand没有一处自定义颜色图标来自phosphor-icons/reactCaretDownIcon、DotsSixVerticalIcon、FolderIcon所有结构/布局诉求用 Tailwind 工具类表达flex、gap-2、min-w-0、max-w-64、rounded-lg、媒体查询[media(any-pointer:coarse)]等显式处理motion-reduce:transition-none、data-[popup-open]等 Kumo 状态选择器遵守了保留可访问性的强制要求。package.json也印证了层次packages/ui/package.json 把 React 与cloudflare/kumo声明为peerDependenciesreact: ^19.2.8、cloudflare/kumo: ^2.12.0确保所有消费方共享同一个运行期与设计系统版本gadgets/ui自身是 private 包、直接导出源码exports指向./src/index.ts没有发布或构建产物步骤。React 语义Effect、State 与性能Effect 是同步机制不是派生状态机器规范把Effect 视为与外部系统的同步而不是派生状态的计算手段也不是串联用户交互的途径。具体规则渲染期数据在渲染期计算calculate render data during render不要塞进 Effectstate 靠近它的拥有者需要身份重置时优先用组件key适合的外部 store 用useSyncExternalStore。Effect 的正确性要求负责 fetch 或 subscribe 的 Effect 必须清理过期工作并且在被重启restart时保持正确避免 Effect 链chains of Effects当一份 state 可以由另一份派生出来时不要同步两份 React state。性能与可访问性没有具体的身份identity或性能需求不要加useMemo或useCallback保留键盘行为、焦点管理、可访问名称accessible names、屏幕阅读器通告announcements以及鼠标/触屏/混合输入的输入一致性input parityRPC stub 必须遵守仓库根 AGENTS.md 中关于释放disposal与 React state 的规则——注意根文档特别警告useState的 setter 遇到可调用对象会把它当函数执行因此 state 中要存放RpcStub时必须包进一个对象stub 不再需要时要调用stub[Symbol.dispose]()或在useEffect的 cleanup 中释放。注释规范优先用名称与类型表达意图注释只解释非显然的约束、安全或性能原因、以及刻意偏离约定之处不要逐行叙述代码do not narrate the next line当约束变化时同步更新或删除对应注释。测试规范测试的目标是保护可观察行为而不是凑覆盖率覆盖产品规则、可访问性、状态转换、竞态races与失败路径不要为了覆盖率去测试 React、JavaScript、Kumo 或其他框架自身的行为避免只耦合实现细节的断言避免琐碎的直通passthrough断言行为保持不变的移动behavior-preserving moves除 import 外不应改动测试只有抽取暴露了此前未测试的重要逻辑时才补充针对性覆盖。测试同样遵循 colocate 约定。gadgets/ui的 AGENTS.md 进一步补充优先headless 行为原语 Kumo 适配层的组合当两者都是真实消费方需求时headless 模型保持无表现策略测试围绕可观察契约而非包边界或框架行为编写。源码印证测试与可访问性在HierarchicalList的实践测试文件与被测文件同目录HierarchicalList.test.tsx、HierarchicalListPrimitive.test.tsx、HierarchicalListDragAndDrop.test.tsxheadless 与样式分离HierarchicalListPrimitive.tsx 是行为原语只拥有展开/选择/拖拽行为通过renderRow、renderDropIndicator、renderTouchDragPreview、slots等渲染槽交给消费方定制表现HierarchicalList是 Kumo 适配层负责把行为原语渲染成 Kumo 风格的行、ContextMenu 与 Drawer可访问性细节在源码中一一落实拖拽移动后有双通道aria-livepolite的rolestatus通告{name} moved to position {n} in {parent}双通道轮换以避免重复播报、拖拽后的焦点恢复逻辑、aria-current、aria-expanded、aria-hidden装饰元素、focus-visible样式。把规范串起来HierarchicalList是一个完整的范本案例gadgets/ui的HierarchicalList入口导出几乎覆盖了本规范的所有条目可作为评审与编写新组件时的对照范本所有权属于跨应用共享 UI因此放在gadgets/ui而不在各 app 内重复实现命名文件 PascalCase组件为具名箭头函数export const HierarchicalList (...)不出现React.FC组件 API受控/非受控可辨识联合、onAction回调、领域值传递、slots/className/DOM 透传只服务于当前调用方Kumo 与样式Kumo 原语 语义 token Tailwind 结构类 motion-reduce可访问性适配无自定义颜色React 语义行为原语内useState/useRef/useEffect各司其职Effect 只做订阅、焦点恢复等同步工作派生状态展开集合、拖拽控制器保持在拥有者附近可访问性aria-live通告、焦点管理、键盘/触屏/鼠标输入一致性、触屏拖拽专用把手与长按抽屉测试colocated 测试围绕可观察行为拖拽移动通告、展开切换、选中清理。落地检查清单把本规范压缩成一份提交前自检清单适用于任何packages/*下的 React 改动目录按产品归属组织未按类型强行建components/、hooks/子目录组件 PascalCase、Hooks/模块 camelCase测试文件与主体同目录共享跨应用 UI 放入gadgets/ui含 Tailwindsource配置未在 app 内复制未合并长得像的组件未引入重 prop 泛化抽象受控值有变更回调未用 Effect 复制受控 prop回调命名onAction传递领域值而非 setter/浏览器事件自定义扩展面只为当前调用方未做投机式预留默认使用 Kumo 组件与语义 token无自定义颜色字面量Tailwind 用于结构/布局自定义 CSS 仅限 Kumo 表达不了的技术行为Effect 只做外部同步无 Effect 链、无冗余派生 state、无空转的useMemo/useCallback键盘、焦点、可访问名称、通告与输入一致性已保留RPC stub 已按根 AGENTS.md 释放注释只解释非显然约束未逐行叙述代码测试保护可观察行为与失败路径未测框架自身行为评审他人代码时同一份清单同样适用frontend-conventions技能文档是仓库内所有 React 前端评审的共同标准包级AGENTS.md只做补充、不做替代。赞分享人工智能AI 应用AI AgentAgent 沙箱AI 安全治理【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址https://gitcode.com/gh_mirrors/cl/cloudflare-os点击查看免费下载相关推荐Cloudflare Agents 前端视觉体系实战基于 Kumo 设计系统构建 Agent Playground 界面Cloudflare Agents 前端视觉体系实战基于 Kumo 设计系统构建 Agent Playground 界面 本文以仓库中的 design/visAI AgentAgent 框架后端云原生MCP 服务实时通信LaMa图像修复教程10分钟跑通照片修复与物体移除LaMa图像修复教程10分钟跑通照片修复与物体移除 LaMa图像修复是一款基于傅里叶卷积的高分辨率图像修复工具给它一张照片加一张掩码用黑白像素标明要修哪人工智能计算机视觉深度学习图像处理Activepieces Web 前端工程规范实战指南React 19 Vite TypeScript 下的一致性开发约定Activepieces Web 前端工程规范实战指南React 19 Vite TypeScript 下的一致性开发约定 导读 本文以 Active工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端上一篇Vision-RWKV视觉感知的未来之选下一篇【亲测免费】 OkHttps打造优雅高效的网络通信体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考