FiftyOne 仓库 AI 编码代理开发指南Python 核心与 React App 的双栈协作规范全解析【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyoneFiftyOne 是一个Python 核心fiftyone/ React 应用app/的双栈仓库其 AGENTS.md 与 app/AGENTS.md 是为 AI 编码代理如 Claude、Copilot 等量身编写的仓库级操作指引进入仓库后先读什么、改动哪一侧代码遵守哪份规范、新增 UI 用什么组件库。读完本文你将掌握该仓库对 Python 后端与 TypeScript 前端的全部强制约束行宽、导入分组、docstring、VOODO 组件优先、MUI 迁移冻结、状态管理分层等并能据此写出风格一致、可通过 CI 检查的提交。一、进入仓库的第一件事AGENTS.md 教你如何认路根目录 AGENTS.md 全文虽短却是整个仓库协作规则的入口。它给出了三条决定性指令FiftyOne 由Python 核心fiftyone/与React Appapp/两部分组成任何改动先分清归属改动fiftyone/下的任何内容必须阅读 STYLE_GUIDE.md改动app/下的任何内容必须先读 app/AGENTS.md并把 app/CODING_STANDARDS.md 视为具有约束力binding的规范同时明确要求新 App UI 使用 VOODOvoxel51/voodo不得新增 Material UI。从仓库布局看这条认路指令与目录结构完全对应fiftyone/下是core/数据集、视图、标签、聚合等核心实现、utils/、operators/、server/、plugins/等 Python 包app/则是包含packages/core、packages/state、packages/components等十几个子包的 TypeScript monorepo。两条规范线Python 风格 vs App 编码标准彼此独立、互不越界这正是双栈仓库最需要 AI 代理遵守的纪律。二、Python 侧规范STYLE_GUIDE.md 的核心约束STYLE_GUIDE.md 规定了 FiftyOne 主要语言Python、TypeScript、RST、Markdown的风格。对fiftyone/的改动以下 Python 约束是硬性的格式化与行宽最大行宽79 字符不可拆分的超长 URL 除外使用4 空格缩进禁止 Tab删除所有行尾空白顶层定义之间空两行类方法之间空一行。导入分组Import 顺序导入必须位于模块 docstring 之后按最通用 → 最不通用分组组间空一行、组内按完整包路径字母序排序标准库最通用第三方依赖如cv2、numpyVoxel51 出品但非 FiftyOne 的包如eta.core.*FiftyOne 自身模块最不通用。核心 FiftyOne 模块按fox缩写规则导入x为模块首字母首字母冲突时用foxy区分例如import fiftyone.core.labels as fol、import fiftyone.core.media as fom。STYLE_GUIDE 给出的完整示例import os import sys import cv2 import numpy as np import eta.core.image as etai import eta.core.video as etav import fiftyone as fo from fiftyone.core.document import Document import fiftyone.core.labels as fol import fiftyone.core.media as fom命名与私有化命名遵循module_name、ClassName、function_name、GLOBAL_CONSTANT_NAME、instance_var_name、function_parameter_name等约定所有私有变量、常量、函数、方法、类都必须以_开头无基类的类显式继承object。Docstring 与文档系统联动公共类与方法的 docstring 会被 Sphinx Sphinx-Napoleon 自动收录进 docs因此必须使用 Sphinx 构造:ref:、:class:、:func:、.. note::并遵守 Google 风格、不使用类型注解。函数 docstring 需包含Args:带默认值如tolerance (2)、Returns:、Raises:等段落类 docstring 直接记录__init__()的参数。日志与异常使用标准库logging按logger logging.getLogger(__name__)获取模块级 logger用debug/info/warning输出日志错误一律用原生异常raise Exception(...)抛出而不是logger.error()循环中需要只提示一次的警告使用warnings.warn()。工具链落地Python 代码经 pre-commit hooks 用black和pylint自动格式化与检查black 不自定义[tool.black]仅在 pyproject.toml 中保留有限配置pylint 消息的永久禁用写入 pylintrc 的disable字段局部禁用使用# pylint: disablerule行内注释。三、App 侧的第一原则VOODO 优先MUI 是历史包袱app/AGENTS.md 开宗明义App UI 用voxel51/voodoVoxel51 的组件库构建永远优先找 VOODO。原因很直接——该代码库大量代码早于 VOODO 诞生、是用 Material UI 写的因此模仿周围代码的写法恰恰会产出 MUI而这正是团队正在迁离的方向。周边代码不是可靠的风格指南这是 AGENTS.md 对 AI 代理最反直觉也最重要的一条提醒。从 app/package.json 可以看到voxel51/voodo: ^0.1.0被声明在根依赖中且packages/core、packages/state、packages/components、packages/multimodal、packages/playback等 12 个子包都以catalog:或*方式引用它印证了 VOODO 已铺到整个 App 面。如何确认 VOODO 是否有某组件不要靠猜直接查已安装包的真实导出。在app/目录下执行grep -F export * from node_modules/voxel51/voodo/dist/components/index.d.ts注意两点barrel 文件列出的是模块路径而非导出名导入前必须到对应组件目录自己的.d.ts里确认精确标识符——例如Datepicker/目录导出的是DatePicker而Slider/导出SingleValueSlider与MultiValueSlider。这份声明文件对实际安装的版本是权威的因为 VOODO 的组件集在不同版本间会变化。样式 token 的使用使用 VOODO 导出的 tokens 与枚举禁止硬编码var(--...)字符串禁止使用字符串字面量import { Text, TextVariant, TextColor, Icon, IconName, Size } from voxel51/voodo; Text variant{TextVariant.Md} color{TextColor.Fg}{label}/Text Icon name{IconName.CaretDown} size{Size.Sm} color{TextColor.Secondary} /兜底规则如果确实需要 VOODO 没有的组件才可以用 MUI且必须在 PR 描述中说明命中了哪个缺口绝不悄悄替换。四、MUI 迁移冻结一条只缩不增的 ESLint 白名单VOODO 优先不是一句口号而是被 ESLint 规则机械强制执行的。app/CODING_STANDARDS.md 把 MUI 使用分成两档Tier 1禁止forbidden——VOODO 有等价物时新代码/重写代码不得用 MUI且没有赶发布豁免。文档给出一张完整的替换对照表核心映射如下节选禁用的mui/material导入必须替换为voxel51/voodoTypographyText、HeadingBox、Stack、GridStackButtonButton、RichButtonIconButtonClickableTextField、OutlinedInputInput/TextArea配FormField承载 label/errorSelect、AutocompleteSelect、DropdownMenu、MenuList、MenuItem、PopoverContextMenu、DropdownCard、Paper系列CardChipPill、TextBadgeCircularProgress等加载类SpinnerSliderSingleValueSlider、MultiValueSliderSnackbarToast、ActivityToast任意mui/icons-material图标IconIconName注意同名陷阱Stack、Button、Tooltip在两个库里都存在务必确认 import 解析到的是哪个。且部分替换是近似而非直接替换Stack是一维 flexbox真正的二维布局可用div CSS grid但不用 MUIGridDropdown/ContextMenu是菜单而非通用锚定 popoverSelect支持 typeahead 与多选但不支持异步加载。迁移时必须保留原有的布局、交互与无障碍行为。Tier 2不鼓励discouraged——VOODO 暂无等价物的已知缺口Alert/AlertTitle、Dialog系列与Modal、Tabs、Link、MUI 主题工具useTheme、styled、sx。这些允许为了发布继续使用 MUI但应尽量用 VOODO 原语组合并向 VOODO 维护者反馈缺口、在 PR 中说明。落地机制Tier 2 的使用仍会触发 app/.eslintrc.js 中no-restricted-imports的警告——这是预期且可接受的不要为了消音把文件加进 app/.mui-allowlist.txt。该白名单只为冻结开始前2026-08-21 快照遗留的 MUI 文件服务它的定位是只缩不增每迁移一个文件就从名单里删掉一行名单清空之日就是 MUI 彻底退出之时。审查口径存量 MUI 不算违规code review 时只标记本次变更新增的mui/*导入或新增的 MUI 组件用法仅修改 prop、移动/重排 import 的存量维护不算违规。存量 MUI 代码也不要顺手重构——除非你本来就在重写该组件。五、冻结规则的源码级实现.eslintrc.js 的双重白名单app/.eslintrc.js 把上述规则落成了可运行的代码它同时管理两条冻结线Recoil → Jotai 迁移冻结recoil与recoil-relay的新用法被no-restricted-imports拦截白名单是 app/.recoil-allowlist.txtMUI → Voodoo 迁移冻结拦截mui/icons-material、mui/icons-material/*、mui/material、mui/material/*全部入口白名单是 app/.mui-allowlist.txt。实现上有两个值得注意的细节两条冻结共用同一个规则名而 ESLint 的overrides替换规则配置而非合并因此 app/.eslintrc.js 把两份配置分开维护让 override 只重新应用仍生效的那一条只在 MUI 白名单上的文件重新声明 Recoil 冻结只在 Recoil 白名单上的文件重新声明 MUI 冻结同时命中两个名单的文件则对两条冻结都豁免bothAllowlist。冻结拦截的是导入路径而非组件使用这正是 CODING_STANDARDS 强调从mui/system、mui/base、mui/lab导入同一原语仍是 Material UI的原因——规则必须封死所有mui/*入口否则换一个子包导入即可绕过。此外app/.eslintrc.js 还配置了only-warn插件把错误降级为警告、分阶段清零、React/React Hooks/TypeScript/Prettier 推荐规则以及针对packages/looker-3d/**的 react-three-fiber 专有属性豁免attach、rotation、args等 three.js 对象属性可作 JSX props。六、TypeScript 纪律严格类型不留抑制app/AGENTS.md 对 App 侧 TypeScript 的要求非常明确新代码必须严格类型化——不允许any不允许无注释的ts-ignore、ts-expect-error、eslint-disable确有必要时必须附带解释原因的注释。这与 ESLint 配置中typescript-eslint/no-unused-vars对_前缀参数的豁免argsIgnorePattern: ^_配合形成严格但可表达的写作环境。七、App 状态管理规范CODING_STANDARDS.md 的分层模型app/CODING_STANDARDS.md 是 App 侧第二份约束力文档其状态管理部分贯彻least capability最小能力原则能用简单方案就不用复杂方案。状态选型三档本地状态仅 UI 用、随组件销毁重置 →useState、useReducerContext API小而受限的组件树、静态数据 →useContextcontext 保持最小避免多余重渲染Atoms响应式全局状态 →Jotai首选或Recoil遗留。Atom 四条铁律绝不直接导出 atoms把 atom 视为实现细节只导出领域 hooks来读写 atom组件内禁止裸用useAtomValue、useSetAtomValue、useRecoilValue、useSetRecoilValue领域 hook 命名约定useFeature()为读取 API、必须幂等如useLighter()、useTimeline()useFeatureAction()或useActionFeature()为命令、可带副作用如useCreateTimeline()、useLighterSetup()文件布局固定packages/domain/model/atoms.ts不导出packages/domain/model/selectors.ts不导出packages/domain/hooks.ts导出packages/domain/bridge.ts可选供 JS 互操作从源码看该规范已在仓库落地app/packages/state/src/jotai/下真实存在jotai-store.ts、modal.ts、modalBridge.ts、group-annotation.ts等文件其中modalBridge.ts正是bridge 用于非 React 访问的实例。JS 互操作要求使用显式命名的 bridge API如lighterBridge、annotationBridge如果必须把 atom 暴露到全局前缀__unsafe如__unsafeGlobalFeatureAtom。八、AI 编码代理实操清单一次合规提交的检查顺序综合两份 AGENTS.md 与配套规范一个 AI 编码代理在提交前应依次自检判断归属改动在fiftyone/还是app/前者遵循 STYLE_GUIDE.md后者必读 app/AGENTS.md 与 app/CODING_STANDARDS.mdPython 侧79 字符行宽、4 空格缩进、导入四组排序、_私有前缀、Sphinx docstring、原生异常而非logger.errorApp UI 侧先查 VOODOgrep -F export * from node_modules/voxel51/voodo/dist/components/index.d.ts确认导出名后再导入用 VOODO tokens/enums 而非var(--...)无 VOODO 等价物才用 MUI并在 PR 描述说明缺口冻结规则新mui/*导入会被 app/.eslintrc.js 的no-restricted-imports警告不要往 app/.mui-allowlist.txt 或 app/.recoil-allowlist.txt 加文件来消音——这两份名单只缩不增TypeScript无any、无裸抑制注释新状态走atoms.tsselectors.tshooks.ts布局组件只消费领域 hooks迁移纪律不要顺手改写存量 MUI/Recoil 代码真正迁移某文件时把它从对应白名单中删除。这套规范的价值在于它把风格一致性从约定俗成变成了可被 lint 强制、可被 review 审计、可被白名单追踪的工程事实。对任何要在这个双栈仓库中长期工作的 AI 代理或人类开发者而言按上述顺序执行即可避免提交被 CI 拦下、review 反复打回的常见返工路径。【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考