可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载Phoenix 是一款 AI 可观测性与评估平台其前端位于 js/app 目录由 React 19、TypeScript、Relay 与 React Aria 构建。本文以仓库内置的 phoenix-frontend 技能文档 为骨架结合其五份参考文档组件模式、Relay 数据获取、无障碍、测试标识、SVG Logo 资源与真实源码实现系统梳理 Phoenix 前端开发的核心规范如何组织组件分层、如何选择 Drawer 与 Modal、如何正确管理 Relay 查询缓存、如何命名data-testid、如何维护路由可发现性等。读完本文你将掌握一套可直接套用的 Phoenix 前端工程化打法并理解每一条规范背后的源码依据。一、规范总览与工作起点phoenix-frontend 技能文档开篇即给出开发前的强制动作在动工之前先探索js/app/src/components/与js/app/package.json理解已有的组件模式、依赖包与约定再遵循规则编码。这一原则贯穿全文Phoenix 前端不是从零写起的绿地项目而是高度约定化的既有代码库任何新功能都应当先对齐存量再增量实现。SKILL.md 提供了一张参考文件索引表按任务类型选择阅读对象参考文件适用场景references/components.md创建、组合或重构组件references/relay.md使用 Relay 进行数据获取references/accessibility.md任何交互元素、表单、浮层或语义化标记references/test-ids.md为 E2E 测试新增或修改data-testid属性references/resize-svg-logo-assets.md新增或更新 provider/integration 品牌 Logo 图标此外还有两条贯穿始终的全局要求视觉变更后必须验证任何界面改动都要借助浏览器工具确认 UI 渲染正确修改共享组件时必须检查其在全应用中的使用点。路由元数据同步新增、删除、重命名或实质性改变页面内容时若希望智能助手PXI能引导用户跳转到该目的地需要更新 js/app/src/Routes.tsx 中路由的handle.agentRoute元数据——保持精简且面向搜索label为人类可读的页面名description为凝练的页面用途说明并包含用户在寻找该页面时可能对 PXI 说出的口语化关键词。如果内容改动使既有路由的自然语言可发现性发生变化应在同一次改动中同步调整description。二、组件分层Core 原语与 Domain 组合components.md 定义了 Phoenix 组件架构的两层结构这是理解整个前端组织方式的第一把钥匙Corecomponents/core/纯展示性原语。严禁包含数据获取或业务逻辑只负责视觉与交互基础能力。Domain其余所有目录数据密集型组件由 Core 原语组合而成。两条硬性规定随之而来新功能必须优先复用既有 Core 原语而不是重新造低级 UI布局时必须复用已有的 flex/view 布局原语以保证间距与对齐一致禁止随手写临时布局包装器。从源码结构看components/core/下已经沉淀了包括 overlayDrawer/Modal、表单控件、布局原语等一整套基础件Domain 层通过组合它们完成具体业务页面。文件组织约定新增组件时应先探索几个既有组件对齐已经成型的文件结构组件本体、样式、类型定义、barrel 导出index.ts各归其位。共享常量校验正则、固定字符串集合等必须收敛到 js/app/src/constants 目录下的聚焦模块中并通过index.ts统一再导出以phoenix/constants路径引用——禁止从组件或表单文件中导出共享常量。Storybook 要求新 Core 组件必须附带最小化的 Storybook stories覆盖主要变体与状态。既有约定位于 js/app/stories 目录新增 story 时先参考该目录的写法保持一致。三、React 19 时代的组件编写规则Phoenix 前端已启用React Compiler这直接改变了一大批传统 React 编码习惯是本节所有规则的根因。1. 不要手动 memoizationReact Compiler 会自动处理记忆化因此禁止使用useMemo、useCallback和React.memo。这包括传给子组件的回调 props——直接内联定义不要用useCallback包裹。编译器会在编译期自动完成依赖分析与缓存生成手写 memoization 反而可能干扰编译器的优化决策并增加噪音。2. 条件 className 统一走 classNames构建条件 className 字符串必须使用phoenix/utils/classNames它是clsx的再导出禁止手写重复 base class 的三元表达式或模板字符串。规范写法是base class 传字符串开关条件传对象className{classNames(attachment-info, { attachment-info--with-detail: detail, })}3. React 19 的 ref 即普通 propReact 19 将ref视为普通 prop因此不要使用forwardRef。直接在 props 类型中声明ref?: RefElementType并像普通 prop 一样解构使用。这一约定与 React 19 的官方演进方向一致也让组件签名更扁平、更易阅读。4. 回调 props 以事件命名回调 props 必须按事件命名onProjectCreated、onDismiss而不是按父组件的实现命名如refetchProjects。目的让调用点读起来像自然语言// Good —— 调用点读起来像一句英文 NewProjectButton onProjectCreated{() refetchProjects()} / // Avoid —— 泄露了父组件内部实现 NewProjectButton refetchProjects{() refetchProjects()} /5. 规避 useEffect拥抱声明式优先使用声明式 React 与 React Aria 模式避免命令式useEffect——只有不存在声明式替代方案时才允许使用。两条具体的替代路径防抖搜索/过滤输入组合共享的DebouncedSearch字段而不是手写useEffectsetTimeout。高开销的上下文驱动更新树过滤、列表过滤、全局展开/折叠保持 transition 策略与状态所有者一致——通过 context 暴露动作由 provider 在底层状态更新外包一层startTransition消费者直接调用这些动作即可无需关心 transition 细节。四、覆盖层体系Drawer 与 Modal 的选择Phoenix 提供两个用途截然不同的覆盖层组件选错会直接破坏交互模型。这一节的决策依据在 components.md 中有完整论述源码实现分别位于 Drawer.tsx 与 Modal.tsx。Drawer非模态右侧面板Drawer 用于列表-详情list-detail流程用户选中一行、查看其详情同时列表保持可见、可交互。从 Drawer.tsx 的源码可以看出其设计特征不渲染 backdrop点击可穿透到页面背后通过拖拽手柄调整宽度宽度以视口百分比持久化到localStorage源码中定义了DRAWER_DEFAULT_SIZE、DRAWER_DEFAULT_MIN_SIZE、DRAWER_HARD_MIN_SIZE_PX等常量还支持键盘以 5% 步进调整通过 Escape 或折叠箭头按钮关闭路由驱动打开 Drawer 意味着导航到嵌套路由如/sessions/:sessionId对应的表格行必须高亮data-selected让用户始终清楚正在查看哪一行。适用场景traces、spans、sessions 这类瞥一眼详情、随即返回列表的浏览型操作。Modal模态浮层Modal 是要求焦点集中的模态覆盖层通过ModalOverlay阻断与背后页面的交互有两个变体variantdefault——居中对话框 backdrop用于确认、表单和需要用户全神贯注的聚焦工作流variantslideover——全高右侧面板 backdrop用于内容比居中对话框更宽、但仍需模态焦点的场景如复杂的创建表单不应与背后页面竞争注意力。决策速查表信号选择用户在浏览列表并检查条目Drawer用户必须完成某动作才能继续Modaldefault模态内容需要全高面板布局Modalslideover五、分层列表-详情模式layered list-detail对于点击行打开详情视图的表格Phoenix 强制采用分层列表-详情模式其完整实现路径如下行点击导航到嵌套路由如/traces/:traceId详情视图通过Outlet /与表格并列渲染选中行高亮在tr上设置data-selected{isSelected}其中isSelected用useParams取 URL 参数与row.original.id比较既有样式selectableTableCSS会自动为tr[data-selectedtrue]加高亮Drawer 打开承载详情内容表格在其后保持可见、可滚动关闭 Drawer即导航回父路由同时清除选中状态。这个模式的价值在于持续定向orientation用户永远看得到自己选中了哪一行且无需先关闭当前详情就能直接点击另一行切换查看。从仓库的useParams用法与selectableTableCSS样式钩子看该模式已在多个表格页面traces、sessions 等落地为通用范式。六、Relay 数据获取规范缓存保留与所有权relay.md 是一份风险导向极强的数据层规范核心围绕数据会不会被静默逐出缓存展开。1. 声明式 hooks 有缓存保留保证fetchQuery 没有usePreloadedQuery、useLazyLoadQuery这类声明式 hooks其查询与拉取的数据会在组件挂载期间保留在 Relay store 缓存中因此可以安全地用于水合hydrate页面渲染数据。而fetchQuery没有这种保留保证——在足够的后续请求如分页触发的请求之后数据可能被逐出 Relay store。这意味着用fetchQuery水合页面上渲染的数据是危险的组件仍挂载时数据可能已静默消失。2. 查询 ref 的所有权与销毁loadQuery返回的查询 ref 会被保留直到被 dispose组件自己负责加载时用useQueryLoader——它自动处理 ref 的保留与销毁路由 loader 或其他外部持有者直接把loadQueryref 交给组件时组件在不再拥有它时必须负责 dispose。3. useOwnedPreloadedQueryloader 持有的 ref 专用钩子Phoenix 为最常见的路由 loader 模式提供了专用 hookjs/app/src/hooks/useOwnedPreloadedQuery.ts。从源码看其实现非常精巧它把外部传入的 query ref 交给useQueryLoader(query, queryRef)初始化从而让 Relay 在 ref 被替换或组件卸载时自动 dispose再通过usePreloadedQuery读取数据并用invariant保证 ref 必存在。适用条件当前组件拥有外部创建的 query ref 的生命周期典型场景是useLoaderData()返回loadQuery的结果。禁止在以下情况使用query ref 已由useQueryLoader管理ref 是共享的、销毁权归另一个组件ref 经 context 或 props 传给多个读者无明确的单一所有者语义。4. 五条铁律优先声明式 hooks用usePreloadedQuery/useLazyLoadQuery获取要渲染到页面的数据页面渲染数据禁用 fetchQuery不要用它水合挂载组件依赖的渲染数据fetchQuery 的有限安全用途仅当结果被立即消费、不留在 store 中用于渲染时才可接受如为 redirect 或一次性动作取数组件自持的 ref 用 useQueryLoaderloader 持有的 ref 用 useOwnedPreloadedQuery把销毁当作所有权决策——过早销毁共享 ref会让仍挂载的读者在后续遭遇缺失数据或 GC 相关崩溃。5. 单实体查询走 node(id:)禁止过度拉取需要按 id 取单个对象时如懒加载 tooltip、详情 popover应通过根字段node(id: $id)配合具体类型的内联 fragment 直接获取——不要拉取整个集合再在客户端.find()。按列表取单行是浪费一次往返且扩展性差的反模式。如果目标类型尚未暴露到node接口规范要求在后端将其做成NodeGQL 类型声明id: NodeID[int]/ 实现Node字段按 id 惰性解析并在src/phoenix/server/api/queries.py的Query.node中为type_name增加return X(idnode_id)分支而不是用集合查询绕过。七、无障碍WCAG 2.1 AA 与语义化基线accessibility.md 篇幅不长但规定了两条不可妥协的底线语义化元素强制交互动作必须用 button禁止可点击的 div列表必须用ul/olli即使是非项目符号布局键值行、菜单、标签列表也不能退化成 div 堆叠。重置浏览器默认样式时用list-style: none; margin: 0; padding: 0;再在语义列表之上施加 flex/grid 布局。WCAG 2.1 AA 基线文本对比度 4.5:1、键盘可操作性、可见焦点指示、表单输入必须有 label。这条规范的价值在于它把语义正确与视觉还原解耦——先保证结构语义再通过样式覆盖视觉避免视觉稿驱动出不可访问的 DOM。设计系统层面的错误展示、布局、对话框、tokens 规则由 phoenix-design 技能.agents/skills/phoenix-design/单独承载组件开发与设计规范各司其职。八、data-testid 命名与状态分离test-ids.md 定义了 E2E 测试标识的完整命名体系。data-testid是当 role/label/text 选择器不够稳定或不够具体时的逃生通道加了就必须遵守以下规则命名规则kebab-case纯 ASCII不缩写完整拼出元素角色button、menu-item、link、tab、dialog、input、option——绝不写btn、mi具体且限定范围用功能/页面/组件名做前缀保证全局唯一。create-dataset-button优于create-buttondataset-form-submit-button优于submit-button以元素角色结尾模式为scope-subject-rolecreate-dataset-buttonplayground-run-buttondataset-form-submit-buttonrun-dataset-experiment-via-sdk-menu-itemllm-evaluator-form-submit-button表单主提交控件统一为form-name-submit-button不用随模式变化的动词同一元素避免create-.../update-...反复横跳。状态进>// ❌ testid 随状态变化编辑模式下干脆消失 Button>page.getByTestId(llm-evaluator-form-submit-button); // 永远解析成功 page.locator([data-testidllm-evaluator-form-submit-button][data-modecreate]);常用的状态属性包括data-modecreate|edit、data-stateopen|closed|loading、data-selected。若既有组件已自带data-state等能表达状态的属性优先复用而不是另造新名。放置位置与使用优先级data-testid及配套data-*必须放在元素的第一个 prop便于一致性与快速扫描。使用优先级上不要第一时间就上 testid依次尝试role 选择器getByRole→ label 选择器getByLabel→ 文本/占位符选择器仅当这些方案有歧义、不稳定或不存在时才加data-testid——典型场景是纯图标按钮、重复出现的行操作、可见文本会变化的元素。九、URL 状态可还原性SKILL.md 的最后一个硬性要求显著视图状态必须能从 URL 重建。用户能够选择的 tab、子视图或详情状态只要需要扛住刷新、分享或相邻记录分页就必须编码进路由参数route params或搜索参数search params并在导航过程中保留相关 URL 状态。这条规则与前面的路由驱动 Drawer一脉相承Phoenix 的深链能力trace/session 详情、tab 选择、过滤条件全部依赖 URL 承载状态既保证了刷新后的还原也让 PXI 等智能助手可以生成可直达的链接。十、SVG Logo 资源从原始 SVG 到 TSX 组件的确定性流程resize-svg-logo-assets.md 描述了为 Phoenix 前端新增 provider/integration 品牌 Logo 的完整管线配套脚本为 scale-svg.py。两类目标目标画布目标文件组件形态provider24×24js/app/src/components/generative/GenerativeProviderIcon.tsx私有常量组件接受{ height }propintegration32×32js/app/src/components/project/IntegrationIcons.tsx命名导出无 props固定 32×32用户未指定目标时必须先询问再动手。七步工作流Step 1 — 收集 SVG接受单个文件路径、文件列表、含.svg的目录或对话中粘贴的原始 SVG 标记先写入临时文件。Step 2 — 确定性缩放使用辅助脚本缩放是数学级坐标重写而非包一层 transform输出与 Figma 缩放结果等价# 单文件 uvx --with svgpathtools python .agents/skills/phoenix-frontend/scripts/scale-svg.py target_size input.svg output.svg # 批量 uvx --with svgpathtools python .agents/skills/phoenix-frontend/scripts/scale-svg.py --batch target_size input_dir output_dir目标尺寸provider→24integration→32。从 scale-svg.py 源码看脚本借助svgpathtools解析 path 数据按SCALE_X/SCALE_Y/SCALE_UNIFORM分类缩放坐标属性含 Line/CubicBezier/QuadraticBezier/Arc 各段类型处理并处理多子路径的不连续 M 命令数值统一保留最多 4 位小数。Step 3 — SVG 转 JSX将输出 SVG 转为 JSX 组件属性名映射表如下class→className、clip-path→clipPath、clip-rule→clipRule、fill-rule→fillRule、fill-opacity→fillOpacity、stop-color→stopColor、stop-opacity→stopOpacity、stroke-width→strokeWidth、stroke-linecap→strokeLinecap、stroke-linejoin→strokeLinejoin、stroke-dasharray→strokeDasharray、stroke-dashoffset→strokeDashoffset、stroke-opacity→strokeOpacity、xmlns:xlink→删除。同时移除根svg的xmlnsReact 自动添加、无子元素的标签自闭合如path ... /、viewBox原样保留。Step 4 — 颜色规则纯单色黑/近黑/深灰Logo 将 fill 替换为currentColor使其跟随 Phoenix 主题的明暗模式有明确品牌色的多色 Logo 保留原色。Step 5 — 插入 TSX插入前确认与既有条目不冲突若有相似 Logo 需先列出并征得用户确认再覆盖。Provider 图标模式const NewProviderSVG ({ height }: { height: number }) ( svg viewBox0 0 24 24 width{height} height{height} xmlnshttp://www.w3.org/2000/svg {/* scaled paths here */} /svg );再在PROVIDER_ICONSrecord 中注册NEW_PROVIDER: NewProviderSVG。注意key 必须匹配ModelProvider类型中的某个值若 provider 不存在于该类型中需向用户说明类型可能需要在上游更新。Integration 图标则作为命名导出写入export const NewIntegrationSVG () ( svg width32 height32 viewBox0 0 32 32 fillnone xmlnshttp://www.w3.org/2000/svg {/* scaled paths here */} /svg );Step 6 — 由文件名推导组件名遵循iconName.svg约定时组件名 去掉icon前缀、去除空格、追加SVG。例如iconLlamaIndex.svg→LlamaIndexSVG、iconCerebras.svg→CerebrasSVG、iconLiveKit Agents.svg→LiveKitAgentsSVG。Step 7 — 验证读取修改后的 TSX 确认组件能与周边代码一起编译若用户提供了期望图标名列表逐一确认已添加。效率与安全红线逐文件推进不批量倾倒缩放一个 → 读输出 → 改 TSX → 再处理下一个不让文件内容穿越对话缩放产物在磁盘上需要时直接读取整体替换组件更新既有 SVG 组件时整段删除重写不零敲碎打绝不手改 SVG path 数据所有坐标变更必须走缩放脚本不猜不近似路径几何脚本对某 SVG 失败时向用户报告错误而不是手动修补未经明确要求不得修改文件中既有图标。十一、规范在仓库中的落地印证上述规范并非纸上谈兵均可在仓库中找到对应实现useOwnedPreloadedQuery见 js/app/src/hooks/useOwnedPreloadedQuery.ts其用useQueryLoader接管外部 ref 以实现自动 dispose的实现与文档描述完全一致Drawer 源码见 js/app/src/components/core/overlay/Drawer.tsx约 484 行DRAWER_DEFAULT_*/DRAWER_VISIBLE_GUTTER_PX等常量、键盘 5% 步进调整、localStorage宽度持久化等特性均有据可查Modal 双变体见 js/app/src/components/core/overlay/Modal.tsxProvider 图标注册表见 js/app/src/components/generative/GenerativeProviderIcon.tsx缩放脚本见 .agents/skills/phoenix-frontend/scripts/scale-svg.py路由元数据见 js/app/src/Routes.tsx 的handle.agentRoute前端依赖与脚本见 js/app/package.jsonReact 19、React Compiler、Relay、React Aria 等依赖与项目脚本均在次声明。十二、结语一套可解释的前端规范Phoenix 前端规范的独特之处在于每条规则几乎都能追溯到一个具体的风险或一个具体的源码实现。Core/Domain 分层防止了业务逻辑泄漏进展示层React Compiler 的启用让 memoization 规则从建议变为禁令Relay 缓存保留语义直接决定了数据获取 hooks 的选择Drawer/Modal 的决策表把交互模型的选择从个人偏好变成了可判定的工程决策data-testid的ID 恒定、状态分离原则则从根本上解决了 E2E 选择器因状态变化而失效的经典难题。对于在 js/app 下工作的开发者与 AI 编码助手而言这套规范既是编码约束也是决策框架动手前先读 SKILL.md 与对应的参考文件按需对照源码即可保证产出与 Phoenix 现有代码库在组件分层、数据流、无障碍与测试可访问性上保持一致同时让页面状态可深链、可被智能助手发现。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐plate 组件架构实战指南组合式、可访问、数据属性驱动的 React 组件规范plate 组件架构实战指南组合式、可访问、数据属性驱动的 React 组件规范 导读 本文基于 plate 仓库内的 components 技能规范 htt前端富文本UI组件高效动漫资源聚合平台实战指南AnimeGarden一站式解决方案高效动漫资源聚合平台实战指南AnimeGarden一站式解决方案 AnimeGarden是一个专业的动漫花园第三方镜像站和BT资源聚合平台为动漫爱好者提供智后端前端网页爬虫MCP 服务AI 技能Logto Console 前端开发规范目录组织与 React Hook Form 数据处理的工程实践Logto Console 前端开发规范目录组织与 React Hook Form 数据处理的工程实践 导读 本文基于 packages/console/CO后端认证鉴权身份认证单点登录上一篇3种高效修复MP4视频损坏的方法untrunc工具完全指南下一篇Laravel HTML 生成器教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
