Communitygithub.com

ChatCut-Inc/agent-plugin

当 Codex 使用 ChatCut 插件(chatcut MCP 服务器)添加、创建、手动编辑、修补或放置动态图形 JSX 资源时使用。涵盖参考浏览、直接内联 JSX 编写、可编辑属性、资源绑定、时间线放置和合成验证。

agent-plugin 是什么?

该技能专为 Codex 驱动的工作流设计,允许 AI 代理在 ChatCut 基于 Web 的编辑器中直接创作和管理动态图形 (MG) 资源。它通过 `chatcut` MCP 服务器运行,支持从视觉参考浏览和应用完整的设计流程,到将 MG 作为内联 JSX 代码进行创作、编辑和放置。该技能强调基于参考的设计、严格符合项目样式、以及通过可编辑属性实现用户控制,确保生成的图形既能保持视觉一致性,又易于后续调整。 主要功能包括:浏览和应用预先设计的设计风格、搜索和适配适合特定动态图形形式的实例、直接从选中的实例继承编写代码,以及管理时间线放置和时序。它还提供了关于字体选择、资源导入和图层合成的详细指南,以确保在 ChatCut 的渲染环境中获得准确结果。该技能适用于需要精细控制动态图形元素细节和交互的复杂项目,是 ChatCut 插件生态中的高级工具。

兼容平台~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/ChatCut-Inc/agent-plugin/tree/HEAD/claude/skills/create-motion-graphics

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

创建动态图形

插件主机与项目

使用 chatcut MCP 服务器以及来自用户编辑器 URL 或插件项目结果的项目 ID。此插件适用于 Web 编辑器,包括本地开发 URL。对于 Web 项目,请勿打开 ChatCut Desktop 或使用 chatcut_desktop。如果 chatcut 工具不可用,请报告连接故障;不要将任务提交给编辑器的原生 Agent 作为替代。

设计前查找 MG 参考

浏览并确认视觉方向

在生产环境中,重用已接受的项目样式或用户提供的品牌/参考。当其完整规格尚未知晓时,使用 manage_design_style get。常规的文本/放置编辑无需新的样式选择或目录重新扫描。

当需要新方向或用户要求浏览备选方案时,从 browse_library references: {view: "style-overview"} 开始。阅读所有编号的联系页,跟随 nextOffset 直到 complete。这些页面包含已发布的、启用代理的风格代表,包括链接的现有设计样式。list_presets 仅是旧版目录的子集;它不能替代此视觉概览。重试失败页面;报告不完整的概览,而不是静默跳过。

对于语音引导的视频,在缩小样式列表前,理解口语内容并检查代表性视频帧。重用上下文中已有的转录和帧证据。考虑主题、传达语气、屏幕语言以及镜头的色彩、主体构图和背景,同时参考样式预览。

当视觉方向尚未达成一致时,为当前内容和镜头缩小最多 6 个不同的合适样式,并读取它们的 hero 部分。加载主机的 widget-forms 技能,显示带有简短名称的实际 heroPreview.url 图片。工具返回的图片是给代理的证据,不是面向用户的选择器;纯文本的选择无法显示视觉差异。将每个选择映射到其参考 ID;使用表单的“其他”分支来处理偏好或另一批选择,不要重复选择或添加单独的“显示更多”选项。在应用新样式并生成 MG 之前等待选择,除非用户已经选择了方向或明确委托了样式选择。“其他”回答不算接受。

应用选定的样式

读取所选代表的 summary、hero 和 members。使用 manage_design_style 执行其 designStyleAction:

  • apply_preset:直接使用返回的 presetId;不要仅仅为了保存参考元数据而克隆或更新预设。
  • apply:对已有的已保存用户样式重用返回的 designStyleId。
  • create:只有独立的参考需要创建新的用户自有样式。从选定的参考中定义并保存其调色板、字体和可复用的视觉规则。重用参考的文档化调色板;如果缺失,从其代表性图像中推导出连贯的调色板。保存 designSpec.referenceSources: [{id: "<参考ID>"}],并将单个 heroPreview.url 同时保存在 thumbnailUrl 和 designSpec.images: [{role: "style reference", url: "<heroPreview.url>"}] 中。使用 applyToProject: true;修补数组时保留现有图像。

应用后,调用 get 获取最新的完整规格和源 ID;不要沿用前一个样式的缓存规则。对于新样式,验证其调色板、字体、源、封面和参考图像已保存。仅保存源 ID 并不会保存图像。 参考图像是视觉证据,不是要嵌入的镜头/背景或要复制的示例文案。

根据实际屏幕文本(包括双语文本和拉丁数字)使用 fontRecommendations["zh-Hans"] / .en。重用已接受的字体方案;空的语言组表示未解决。匹配参考的排版字符和标题/正文层次,检查字形覆盖和运行时可用性。在 designSpec.fonts 中保存选定的系列/角色,在 styleGuide 中保存语言、粗细、斜体及所需轴。跨样式表单示例不能替代此方案。仅当策划缺失字体或显式调整版式时,阅读 字体匹配;中文匹配从生成的中文效果图像开始,而不是英文字样。

将实例匹配到所需的 MG 形式

使用口语内容和目标帧来决定哪些 MG 形式有用;让参考预览来优化这些选择。在整个视频中保持已确认的视觉语言,并为每个所需形式找到合适的实例。除非用户要求比较,否则自行选择实例。不同的形式可以使用不同的实例;重复出现的组件可以复用已检查过的实例。当返回 nextReferenceSearch 时,遵循它:

  • 对于相关成员,浏览 kind: "instance", styleId: "<代表UUID>" 或读取相关成员 ID。
  • 如果所需形式没有合适的成员,通过内容/形式 query 或 facets.form 搜索整个实例库,省略 styleId、facets.style 和样式名称词条,即使其他形式已有相同样式的匹配。
  • 比较封面拼贴,然后使用 parts: ["summary", "hero"] 读取选定的 ID。添加 motion 用于动画,code 用于实现。如果代码支持的参考返回 templateInspection,使用其只读调用获取已保存的属性模式/默认值;JSX 可能在不声明其值的情况下读取 props。legacyTemplateRefs 是模板 ID:manage_template get 读取元数据,list_assets 读取 MG 属性。两者都不会应用或复制模板。inspect_asset 用于当前项目媒体/MG,而非目录源 ID。

调整实例的构图、层次、间距和展示结构,以适应固定的项目字体、调色板、材质和实际镜头。如果更广泛的形式搜索也没有匹配,则扩展样式板并说明该限制。批量读取相关的细节;找到一个实例并不能覆盖其他不相关的形式。对分页响应遵循 pendingIds;known 可能仅包含仍在上下文中的返回版本和部分。每个动态表是一个在真实时间戳上的单一设计;蒙太奇不是单一布局,静态图像也无法建立动画。

对于新建/大幅重新设计的讲话者头部覆盖层,阅读 覆盖层构图。仅从 materials 导入将出现在结果中的生产文件;使用它们的项目资产 ID。审查与目标镜头合成的 MG。

编写时使用参考

在借用其实现时,读取所选实例的 code,或使用 manage_template list_assets 读取链接的模板属性。在下面的代码工作流中将其用作参考,同时保持项目样式。

同时检查选定的图像:URL、ID 或搜索结果本身并不是已查看的参考。保留 STYLE 证据用于外观,以及跨样式 FORM 证据用于结构。如果选定的参考失败,重试或报告缺失的证据,而不是声称已检查。

当 ChatCut 插件任务需要创作或修补作为内联 JSX 的动态图形资源时,使用此技能。内置的 ChatCut Agent 有自己的 motion-graphic-gen 工作流;不要在此插件任务中切换到它。

Codex 插件的动态图形是直接创作的。对于新的 JSX 资源使用 create_motion_graphic_from_code,对于现有的 MG JSX 使用 edit_asset。此表面不提供 submit_motion_graphic;不要将请求转换为 Gemini 提示或生成简报。如果直接创作工具缺失,请停止并报告 ChatCut 插件工具不可用。

通过 chatcut MCP 工具内联传递动态图形源代码。当工具直接接受内联 JSX 时,不要将代码暂存到 ChatCut 仓库、ai-working/、/tmp、本地 HTTP 服务器、生成的代码文件或猜测的应用程序路径中。

核心原则

  • 当画布大小、fps、现有视觉语言、放置或时间线冲突尚不明确时,检查项目状态。
  • 在编写 JSX 之前,在 编写前 中确定所需的输入。
  • 通过可用的内联代码资源工作流创建或更新动态图形资源;使用当前工具模式获取准确的有效载荷形状。
  • 当编辑需要时间线放置时,通过时间线编辑工作流放置或移动资源。
  • 在结构性或视觉更改后,重新读取项目状态并验证可见帧。

编写前

在编写 JSX 之前,仅确定此编辑所需的信息:

  • 放置:开始时间、持续时间、目标层(如果已知)以及图形必须与之合成的目标帧。
  • 编辑中的角色:此动态图形在视频中执行什么任务。
  • 内容:必须出现的确切文本、数字、媒体或视觉事实。
  • 时序:内部动画是否应与语音、音乐或视觉事件同步。
  • 视觉来源:用户提供的样式、项目设计样式、品牌颜色/字体或已接受的现有动态图形。
  • 可编辑字段:哪些文本、颜色、数字、布尔值、图像或视频值应成为属性。

仅询问缺失的、会对结果产生重大影响的高杠杆输入。

视觉系统与放置

使用已确认的完整设计样式和上述检查的参考。对于新的自定义方向,先建立合成结果,再进行批量处理;已接受的方向和常规修复无需重新确认样式。

根据实际镜头和语音跨度选择每个构图、位置、大小和阅读时间。保持共享的排版、调色板、材质和动画,同时调整参考形式以适应内容。仅当构图要求时,才使用固定的左/右锚点或卡片容器。

对于具有相同信息结构的有意重复组件,重用带有逐项属性的资源。新结构需要它们自己的实例参考和构图。覆盖层边界应紧密包含图形;仅对明显跨越帧的设计使用时间线尺寸。

将资源持续时间和内部节拍与放置的时间线跨度匹配。如果时序发生重大变化,更新 MG 而不是截断未完成的动画。对于批量处理,并排审查已合成的静止帧,在报告完成前纠正碰撞、可读性和意外重复。

可编辑属性

将用户可见且可能更改的值暴露为可编辑属性。

  • 可见文本、主色、强调色和关键数值应为属性。
  • 当用户可能合理更改时,字体选择应为 font 属性。
  • 图像和视频源必须为 image / video 属性。
  • 代码键必须与属性模式键完全匹配。
  • 从 item.props 读取值;不要硬编码用户以后可能合理更改的可见内容。
  • 仅对具有相同查看者任务、信息结构和视觉形式的有意重复组件使用项目级属性覆盖。如果任何一项不同,请创建另一个 MG 资源,并共享调色板、类型和动画逻辑。

属性条目应声明稳定的键、面向用户的标签、类型和默认值。支持的属性类型包括文本、数字、颜色、布尔值、选择、字体、图像和视频。

字体

动态图形必须使用 ChatCut 渲染器可用的字体,以确保预览和本地导出保持一致。不要依赖特定于机器的系统字体,如 STKaiti、PingFang SC、Microsoft YaHei、Arial、Helvetica、Comic Sans MS、system-ui、-apple-system 或通用 CSS 系列作为主要渲染字体;可用性因机器而异,可能导致回退。

在选择或替换字体时,调用 search_fonts,并逐字使用返回的规范系列名称作为 fontFamily 值和匹配的 font 属性 defaultValue。使用目录返回的 Google Fonts 或项目自定义字体。如果请求的特定于机器的字体不在目录中,解释无法保证一致的本地渲染,搜索具有类似风格的支持替代品,并使用它,除非用户明确接受字体回退。

资源与构图

一个参考实例可能描述由多个时间线项目组成的完整构图。它并不意味着一个自包含的 MG 资源。保持参考截图、生产材料和当前项目镜头的区别。

当设计将普通媒体与图形结合时,默认使用单独的项目:

  • 可复用的纸张/纹理/背景:构图后面的图像或视频项目。
  • 当前项目照片、产品图像或镜头:其自己的媒体项目。代理选择/替换、裁剪、定位并对其应用支持的效果;用户不应期望手动组装图层。
  • 排版、形状和动画装饰:透明 MG 项目。当媒体必须位于其间时,将背景装饰与前部文本分开。

在创作前规划图层顺序、目标媒体矩形、开始/持续时间和入场时序。在 MG 简报/代码范围中说明哪些图层已存在于 MG 外部,以便参考的照片或纸张不会再次生成。将黑白/彩色/颗粒应用于预期的媒体项目,而不是意外影响前部文本。在实际播放/导出表面上验证效果支持;拆分图层本身并不能证明 Web/Desktop 的对等性。

  1. 从 当前项目 中的 browse_assets 重用资源。仅将输出所需的生产文件导入到我的资产中。加载 asset-import 并使用其 import_media 会话/上传助手。注册项目媒体并不会将其发布到公共资源库。
  2. 通过 edit_item 放置普通生产媒体,使用返回的当前项目资产 ID。代理处理用当前任务的内容替换示例人物、文案和数据。不要使用参考的完成。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能