Codot 运行时适配
- Stitch MCP:通过 Codot 设置 → MCP 集中提供(查找前缀为
stitch:或mcp__stitch__的工具)。请勿为每个代理单独配置 MCP 文件。- 浏览器与视觉验证:在检查本地开发服务器或渲染页面时,优先使用 Codot 内置的
browser_*工具(browser_navigate、browser_snapshot、browser_screenshot、browser_console),而非外部 Chrome DevTools MCP。- 视觉交付:
show_preview处于离线状态且无法访问网络;Stitch 导出的 HTML 依赖 CDN Tailwind/字体,如果直接传递会渲染为空白。请使用stitch-preview技能(本地静态服务器 +browser_*实现高保真/交互,或stitch-offline.mjs+show_preview实现聊天内 HTML 预览,或直接在.png截图上使用show_preview)。- 资源下载:始终使用 Stitch MCP 的
download_file(参数为htmlCode.name/screenshot.name),切勿使用curl访问downloadUrl(该操作需要凭据并返回 JSON 包装)。如果download_file输出被截断为临时文件,请使用stitch-preview/scripts/save-stitch-file.mjs解码。- 对象参数:如果 MCP 工具失败并提示
expected object, got string(某些代理运行时会将对象参数序列化为字符串),请改用stitch-manage-design-system中的纯字符串回退工作流,而不是重试相同的失败调用。- 长时间运行调用:如果
generate_screen_from_text或edit_screens超时,每 60 秒轮询一次list_screens,最长约 5 分钟(5 次轮询);如果没有出现新屏幕,则重新发起调用一次,而不是无限等待。- 工具映射:将通用工具名(
Read、Write、Edit、Bash)映射到活动的 Codot 工具(read、write、edit、bash)。
Stitch 到 Remotion 导览视频
你是一名视频制作专家,专注于根据应用设计创建引人入胜的导览视频。你将结合 Stitch 的屏幕获取能力和 Remotion 的程序化视频生成能力,制作流畅、专业的演示视频。
概述
本技能使你能够创建导览视频,展示带有专业过渡、缩放效果和上下文字幕叠加的应用屏幕。工作流程从 Stitch 项目中检索屏幕,并将其编排成一个 Remotion 视频合成。
前提条件
必须:
- 访问 Stitch MCP 服务器
- 访问 Remotion MCP 服务器(或 Remotion CLI)
- 安装 Node.js 和 npm
- 一个包含设计好的屏幕的 Stitch 项目
推荐:
- 熟悉 Remotion 的视频能力
- 理解 React 组件(Remotion 使用 React)
检索与网络
第 1 步:发现可用的 MCP 服务器
运行 list_tools 以识别可用的 MCP 服务器及其前缀:
- Stitch MCP:查找
stitch:或mcp_stitch:前缀 - Remotion MCP:查找
remotion:或mcp_remotion:前缀
第 2 步:检索 Stitch 项目信息
-
项目查找(如果未提供项目 ID):
- 调用
[stitch_prefix]:list_projects,参数为filter: "view=owned" - 按标题识别目标项目(例如 "计算器应用")
- 从
name字段提取项目 ID(例如projects/13534454087919359824)
- 调用
-
屏幕检索:
- 调用
[stitch_prefix]:list_screens,参数为项目 ID(仅数字) - 查看屏幕标题以识别导览中的所有屏幕
- 从每个屏幕的
name字段提取屏幕 ID
- 调用
-
屏幕元数据获取: 对于每个屏幕:
- 调用
[stitch_prefix]:get_screen,参数为屏幕资源name(projects/{project}/screens/{screen}) - 获取:
screenshot.name(projects/{project}/files/{file})— 视频的视觉资源htmlCode.name(projects/{project}/files/{file})— 可选:用于提取文本/内容width、height— 屏幕分辨率,用于正确缩放- 屏幕标题和描述,用于文字叠加
- 调用
-
资源下载:
- 调用 Stitch MCP
[stitch_prefix]:download_file,参数为screenshot.name(切勿使用curl或web_fetch访问downloadUrl,该操作需要凭据并返回 JSON 包装) - 如果
download_file输出被截断为临时文件,请使用以下命令解码:node skills/stitch/stitch-preview/scripts/save-stitch-file.mjs <tool-output> assets/screens/{screen-name}.png - 按导览流程的顺序组织资源
- 调用 Stitch MCP
第 3 步:设置 Remotion 项目
-
检查现有 Remotion 项目:
- 查找
remotion.config.ts或包含 Remotion 依赖的package.json - 如果存在,使用现有项目结构
- 查找
-
创建新的 Remotion 项目(如果需要):
npm create video@latest -- --blank- 选择 TypeScript 模板
- 在专用的
video/目录中设置
-
安装依赖:
cd video npm install @remotion/transitions @remotion/animated-emoji
视频合成策略
架构
创建一个模块化的 Remotion 合成,包含以下组件:
-
ScreenSlide.tsx— 单个屏幕显示组件- 属性:
imageSrc、title、description、width、height - 特性:放大动画、淡入淡出过渡
- 时长:可配置(默认每个屏幕 3-5 秒)
- 属性:
-
WalkthroughComposition.tsx— 主视频合成- 排序多个
ScreenSlide组件 - 处理屏幕之间的过渡
- 添加文字叠加和注释
- 排序多个
-
config.ts— 视频配置- 帧率(默认:30 fps)
- 视频尺寸(匹配 Stitch 屏幕分辨率或适当缩放)
- 总时长计算
过渡效果
使用 Remotion 的 @remotion/transitions 实现专业效果:
-
淡入淡出:屏幕之间的平滑交叉淡入淡出
import {fade} from '@remotion/transitions/fade'; -
滑动:定向滑动过渡
import {slide} from '@remotion/transitions/slide'; -
缩放:为强调效果使用放大/缩小
- 使用
spring()动画实现平滑缩放 - 应用于重要的 UI 元素
- 使用
文字叠加
使用 Remotion 的文本渲染添加上下文信息:
- 屏幕标题:在每帧的顶部或底部显示
- 功能标注:使用动画指针高亮特定的 UI 元素
- 描述:为每个屏幕淡入描述文字
- 进度指示器:显示当前屏幕在导览中的位置
执行步骤
第 1 步:收集屏幕资源
- 确定目标 Stitch 项目
- 列出项目中的所有屏幕
- 下载每个屏幕的截图
- 按导览流程的顺序组织
- 创建一个清单文件(
screens.json):
{
"projectName": "计算器应用",
"screens": [
{
"id": "1",
"title": "主屏幕",
"description": "带有数字键盘的主计算器界面",
"imagePath": "assets/screens/home.png",
"width": 1200,
"height": 800,
"duration": 4
},
{
"id": "2",
"title": "历史视图",
"description": "查看之前的计算结果",
"imagePath": "assets/screens/history.png",
"width": 1200,
"height": 800,
"duration": 3
}
]
}
第 2 步:生成 Remotion 组件
按照 Remotion 最佳实践创建视频组件:
-
创建
ScreenSlide.tsx:- 使用
useCurrentFrame()和spring()实现动画 - 实现缩放和淡入淡出效果
- 使用恰当的时序添加文字叠加
- 使用
-
创建
WalkthroughComposition.tsx:- 导入屏幕清单
- 使用
<Sequence>组件排列屏幕 - 在屏幕之间应用过渡
- 计算正确的时序和偏移量
-
更新
remotion.config.ts:- 设置合成 ID
- 配置视频尺寸
- 设置帧率和时长
参考资源:
- 使用
resources/screen-slide-template.tsx作为起点 - 参照
resources/composition-checklist.md确保完整性 - 查看
examples/目录中的示例
第 3 步:预览与优化
-
启动 Remotion Studio:
npm run dev- 打开基于浏览器的预览
- 允许实时编辑和优化
-
调整时序:
- 确保每个屏幕有适当的显示时长
- 验证过渡是否平滑
- 检查文字叠加的时序
-
微调动画:
- 调整缩放效果的 spring 配置
- 修改过渡的缓动函数
- 确保文字始终可读
第 4 步:渲染视频
-
使用 Remotion CLI 渲染:
npx remotion render WalkthroughComposition output.mp4 -
替代方案:使用 Remotion MCP(如果可用):
- 调用
[remotion_prefix]:render,传入合成详情 - 指定输出格式(MP4、WebM 等)
- 调用
-
优化选项:
- 设置质量级别(
--quality) - 配置编解码器(
--codec h264或h265) - 启用并行渲染(
--concurrency)
- 设置质量级别(
高级功能
交互式热点
高亮可点击的元素或重要功能:
import {interpolate, useCurrentFrame} from 'remotion';
const Hotspot = ({x, y, label}) => {
const frame = useCurrentFrame();
const scale = spring({
frame,
fps: 30,
config: {damping: 10, stiffness: 100}
});
return (
<div style={{
position: 'absolute',
left: x,
top: y,
transform: `scale(${scale})`
}}>
<div className="pulse-ring" />
<span>{label}</span>
</div>
);
};
旁白集成
为导览添加解说:
- 根据屏幕描述生成旁白脚本
- 使用文字转语音或录制音频
- 使用
<Audio>组件将音频导入 Remotion - 将屏幕时序与旁白节奏同步
动态文本提取
从 Stitch HTML 代码中提取文本以自动生成注释:
- 调用
[stitch_prefix]:download_file,参数为每个屏幕的htmlCode.name(使用save-stitch-file.mjs解码截断的输出) - 解析 HTML 以提取关键文本元素(标题、按钮、标签)
- 为重要的 UI 元素生成自动标注
- 作为定时文字叠加添加到合成中
文件结构
project/
├── video/ # Remotion 项目目录
│ ├── src/
│ │ ├── WalkthroughComposition.tsx
│ │ ├── ScreenSlide.tsx
│ │ ├── components/
│ │ │ ├── Hotspot.tsx
│ │ │ └── TextOverlay.tsx
│ │ └── Root.tsx
│ ├── public/
│ │ └── assets/
│ │ └── screens/ # 下载的 Stitch 截图
│ │ ├── home.png
│ │ └── history.png
│ ├── remotion.config.ts
│ └── package.json
├── screens.json # 屏幕清单
└── output.mp4 # 渲染的视频
与 Remotion 技能的集成
Remotion 维护着自己的代理技能,定义了最佳实践。请查阅这些技能以了解高级技巧:
- 仓库:https://github.com/remotion-dev/remotion/tree/main/packages/skills
- 安装:
npx skills add remotion-dev/skills
要利用的关键 Remotion 技能:
- 动画时序和缓动
- 合成架构模式
- 性能优化
- 音频同步
常见模式
模式 1:简单幻灯片
带有淡入淡出过渡的基本导览:
- 每个屏幕 3-5 秒
- 交叉淡入淡出过渡
- 底部文字叠加显示屏幕标题
- 顶部进度条
模式 2:功能高亮
聚焦于特定的 UI 元素:
- 缩放到特定区域
- 指向功能的动画圆圈/箭头
- 对关键交互进行慢动作强调
- 并排之前/之后对比
模式 3:用户流程
展示逐步的用户旅程:
- 带定向滑动的顺序屏幕流
- 编号步骤叠加
- 高亮用户操作(点击、触摸)
- 使用动画路径连接屏幕
故障排除
| 问题 | 解决方案 |
|---|---|
| 截图模糊 | 确保通过 download_file(screenshot.name)下载全分辨率图像,而不是压缩的缩略图 |
| 文字错位 | 验证屏幕尺寸与合成尺寸匹配;根据实际屏幕尺寸调整文字位置 |
| 动画卡顿 | 将帧率提高到 60fps;使用具有适当阻尼的正确 spring 配置 |
| Remotion 构建失败 | 检查 Node 版本兼容性;确保所有依赖已安装;查看 Remotion 文档 |
| 时序感觉不对 | 在清单中调整每个屏幕的时长;在 Remotion Studio 中预览;与实际用户测试 |
最佳实践
- 保持宽高比:使用实际的 Stitch 屏幕尺寸或按比例缩放
- 一致的时序:除非强调特定屏幕,否则保持屏幕显示时长一致
- 可读的文字:确保足够的对比度;使用适当的字体大小;避免杂乱的叠加
- 平滑的过渡:使用 spring 动画实现自然的运动;避免刺眼的切换
- 全面预览:在最终渲染前始终在 Remotion Studio 中预览
- 优化资源:适当压缩图像;使用高效的格式(UI 用 PNG,照片用 JPG)
示例用法
用户提示:
查找我在 Stitch 项目中的屏幕,项目名称为 "计算器应用",并构建一个 Remotion 视频,展示这些屏幕的导览。
Agent 工作流程:
- 列出 Stitch 项目 → 找到 "计算器应用" → 提取项目 ID
- 列出项目中的屏幕 → 识别所有屏幕(主屏幕、历史、设置)
- 下载每个屏幕的截图 → 保存到
assets/screens/ - 创建
screens.json清单,包含屏幕元数据 - 生成 Remotion 组件(
ScreenSlide.tsx、WalkthroughComposition.tsx) - 在 Remotion Studio 中预览 → 优化时序和过渡
- 渲染最终视频 →
calculator-walkthrough.mp4 - 报告完成并提供视频预览链接
成功提示
- 从简单开始:从基本功能开始,然后逐步增加复杂性
- 参考示例:查看
examples/目录获取灵感 - 迭代测试:经常预览并进行小范围调整
- 记录自定义:在视频项目中保留变更记录
- 寻求反馈:与利益相关者分享预览以验证流程