SuperAPI AI 工具集

studio-checklist

前端与建站

查看项目

更新于 11-11 03:16

技能介绍

Studio checklist 是 Remotion 官方提供的一份开发与审查清单,适用于实现或审查 Remotion Studio 本身,覆盖常规 Studio 以及 remotion.new 上的 Browser Studio。

用途 该清单用于在开发或审查 Studio 功能与 UI 时提供统一原则,确保操作反馈、智能体访问、模式差异、悬停行为、设计一致性、性能和验证流程都得到考虑。

主要能力与原则

  1. 乐观操作:每个操作都必须有乐观更新,立即反映用户意图,而不是等待服务器请求、文件系统写入、codemod 或热重载。对于结果未知的工作,立即显示待处理状态,但不声称已完成。乐观状态需与持久化结果协调,保留至更新后的源码/配置通过 HMR 到达,失败时回滚并显示错误。迟到的响应或回滚不得覆盖更新的编辑或撤销。使用现有的 mutation 队列和历史机制,例如 enqueueStudioSourceMutation 和乐观 composition 元数据。

  2. 智能体、交互与代码一致性:每个状态和操作都必须能通过项目代码或 WebMCP 供智能体使用。项目源码中已可编辑的内容即满足此要求,例如移动或裁剪序列不需要额外的 WebMCP 工具。不要仅为镜像源码支持的编辑操作而添加冗余工具。当项目源码无法表示时,通过 WebMCP 暴露临时 Studio 状态和操作,例如播放、选择、待处理渲染任务和渲染取消。遵循 WebMcp.tsx 中已有的注册和相关功能的工具。在 WebMCP 文档中记录每个新工具及其输入输出变化,包括待处理状态、结果和模式可用性。每个源码支持的编辑必须能交互式工作,也能通过编辑项目代码工作,后者同时提供智能体访问。直接代码更改必须在热重载后正确显示。存在 WebMCP 编辑工具时,它必须使用与 UI 相同的源码 mutation/历史路径,避免多个事实来源。在交互式和 WebMCP 入口点之间保持验证、乐观行为、撤销/重做、错误和模式限制一致。工具执行时读取当前状态,而不是在注册时捕获过时快照。

  3. 考虑全部四种 Studio 模式:决定可用性时读取 studio-mode。对照全部四种模式检查每个新操作及其 WebMCP 入口点:常规交互式 Studio(附加 Studio 服务器;源码编辑、codemod、依赖安装、服务器渲染和支持的“Open in”操作);预览服务器分离的常规 Studio(previewServerConnected 为 false;实际只读,客户端渲染仍可用);只读部署 Studio(无附加服务器;隐藏或禁用依赖服务器的操作,GitHub 是唯一支持的“Open in”操作);Browser Studio(remotion.new,在 iframe 中运行,虚拟文件系统对用户隐藏;支持 codemod 和依赖安装,但没有“Open in”操作)。使用现有能力检查。部署的 Studio 不一定只读:Browser Studio 有自己的 mutation 能力。隐藏或禁用不支持的 UI 操作,并在智能体调用时执行相同限制。

  4. 防止 iframe 悬停缺陷:悬停缺陷是指指针离开 Studio 的 iframe 后悬停状态过时。浏览器可能丢失 pointerleave/mouseleave 事件,导致事件驱动的 React 悬停状态卡住:按钮和菜单行保持高亮,或工具提示在指针离开后仍然可见。参见 issue #9886 和工具提示与悬停修复。纯粹视觉悬停样式应使用 CSS :hover 驱动,使用 hoverable.ts 中的 HOVERABLE_CLASS_NAME 和 hoverableStyle()。使用现有 hover-group 类显示行操作。不要仅为改变颜色、背景或可见性而引入 React 悬停状态。当 JavaScript 行为依赖悬停时,例如延迟菜单或工具提示,使用 observeHover()。它处理丢失离开事件、窗口失焦、可见性变化以及 Browser Studio 转发的 remotion-browser-studio-pointerleave 事件的恢复。在清理和关闭期间释放观察器并取消待处理计时器。保留有意的选中、键盘聚焦和打开菜单状态。嵌套操作不应仅因父行悬停而显示为悬停。保持操作可通过键盘和触摸使用。在 iframe 和常规 Studio 中验证:悬停、离开框架、重新进入、切换窗口焦点。高亮和待处理/可见工具提示必须正确清除。browser-studio.test.ts 中已有的回归测试即使丢失指针离开事件也会清除悬停背景,故意抑制离开事件以触发此失败。

  5. 遵循 Studio 设计和 CSS reset:添加或更改 UI 时读取 studio-css-reset 和 no-pointer。复用最接近的现有 Studio 控件、布局和交互模式。匹配它们的颜色、字体、字号、控件尺寸、间距、边框、图标以及悬停、聚焦、选中和禁用特征。使用 colors.ts 中的共享 token 和现有组件样式,而不是引入单独的视觉语言。.css-reset, .css-reset * 规则适用于 reset 容器中的每个后代,而不仅仅是父级。它重置字号、行高、颜色、字体系列、背景和盒模型。仅父级文本样式不会覆盖每个子级的 reset。为绘制文本或 SVG 的元素设置样式,或使用适当的后代选择器。检查计算样式,包括嵌套标签和图标。永远不要为工具提示添加 DOM title 属性,包括 title=""。使用工具提示组件:现有 Studio 实现暴露了 ActionTooltip.tsx 中的 ActionTooltip 和 ClippedTextTooltip。保留可访问标签和键盘焦点行为。永远不要为 Studio 控件或链接使用 cursor: 'pointer'。使用 cursor: 'default'。遵循共享的悬停和 :focus-visible 约定;保持可见的键盘焦点指示器。

  6. 性能不得回退:读取 studio-perf。当值仅在操作期间需要时,优先通过现有稳定 ref 或命令式 getter 消费上下文。在订阅后将响应式上下文值复制到 ref 并不能避免订阅的重新渲染。例如,在事件处理器和 WebMCP 工具中从 imperative-state.ts 读取 getCurrentFrame(),而不是将 Internals.Timeline.useTimelinePosition() 导入其所属组件。仅在可见输出必须每帧变化的最小叶子中订阅帧。在 memoized 边界之间保持 props 和上下文值稳定。添加功能时测试性能;仅检查源码不够。捕获基线并在更改后重复相同的代表性交互,包括当功能参与帧更新时的播放/拖动。使用 react-scan 进行渲染/提交测量,使用浏览器分析进行非 React 工作。保持 composition、视口和重复次数可比。检查不必要的渲染、提交持续时间、交互延迟和播放流畅度(如相关),并在完成前解决回退。报告测量结果和任何验证限制。

  7. 验证功能:通过 UI 和直接代码更改练习源码支持的编辑。在提供工具或需要临时 Studio 状态和操作时练习 WebMCP。检查即时反馈、HMR 后的持久性、失败恢复以及参与历史的编辑的撤销/重做。检查每种模式中的可用性以及上述相关的悬停、聚焦、光标和 CSS-reset 行为。对于 Studio 代码更改,运行包构建和相关现有检查:bunx turbo run make --filter='@remotion/studio' 和 bunx turbo run lint test --filter='@remotion/studio'。当更改跨越这些边界时,包括受影响的包和现有浏览器回归测试。添加或更改测试时遵循 writing-tests。

适用场景 适用于 Remotion Studio 功能开发、UI 审查、WebMCP 工具集成、跨模式行为一致性检查、iframe 悬停问题修复、设计规范遵循、性能验证以及功能测试。

限制 该清单为开发与审查指导,不涉及收费、价格、平台或效果承诺。具体实现细节需参考 Remotion 项目中的相关文件和文档。