@remixmate/studio-cli

Remotion 视频模板创作工具集，9 个 MCP 工具：

| 工具 | 作用 | 是否需 priv-token | |---|---|---| | derive_template | 把骨架拷到 scratch（blank=离线；派生公共模板=从 OSS 拉取） | 派生需 ✅ / blank ❌ | | apply_template_edit | 受控写入/删除 scratch 文件（create / overwrite / delete，支持批量原子提交） | ❌ 离线 | | type_check | 包内自带 tsc（零配置）跑 tsc --noEmit + template.json schema + props 契约校验 | ❌ 离线 | | try_render_remote | 把 scratch 草稿提交给 ab-render 出预览 mp4（仅预览，不出片） | ❌ 免凭证 | | save_template | 打包 scratch → OSS → 注册到 ab-api remotion_template 表 | ✅ 必填 | | render_template | 渲染已注册私有模板（按 template_key 出片） | ✅ 必填 | | resolve_assets | 把用户的本地文件/URL 变成模板可用 URL（本地文件上传换 URL，URL 默认透传） | ❌ public 路由 | | probe_capabilities | 只读探测环境能力（token / render / api / tsc / hostTools），开场决定路径 | ❌ 只读 | | inspect_scratch | 只读查询 scratch 状态（文件清单 / 有无 template.json / 摘要） | ❌ 只读 |

v0.3.0 破坏性变更：try_render_remote 改为纯预览，移除 upload / upload_title / render_cover 参数。出正式片请走 save_template → render_template。传入已移除的 --upload* 会返回 param_removed 并给出指引。

可同时安装于两种宿主：

• ab-template-studio（远程 chat agent）—— install-skills 钩子拷到 apps/ab-template-studio/skills-studio/，由 ab_studio MCP server 暴露
• 本地 Claude Code —— 装到 ~/.claude/skills/remixmate-studio/

本地 Claude Code 使用

1. 装包到 skill 目录

方式 A（npm pack，推荐）：

mkdir -p ~/.claude/skills
cd ~/.claude/skills

# 临时目录里 pack（避免污染当前目录）
TMPDIR=$(mktemp -d)
cd $TMPDIR
npm pack @remixmate/studio-cli   # 拉取最新 published 版本
tar -xzf remixmate-studio-cli-*.tgz
mv package ~/.claude/skills/remixmate-studio
cd ~/.claude/skills/remixmate-studio
npm install --omit=dev           # 安装运行依赖（含 typescript，供 type_check 零配置使用）

方式 B（git clone，开发者）：

cd ~/.claude/skills
git clone <repo-url> remixmate-studio
cd remixmate-studio && npm install --omit=dev

2. 配置凭证（仅保存 / 出片需要）

零配置起步：派生空白骨架、编辑、type_check、本地 try_render_remote 预览都不需要任何环境变量或凭证——装完即可开始创作并看预览。

只有在 save_template（注册私有模板）/ render_template（出正式片）/ 派生公共模板时，才需要凭证。两种取得凭证的方式（任选其一）：

方式 A（推荐）：浏览器登录 remixmate-studio login

无需手动复制粘贴 token，在浏览器确认即可，凭证安全保存到 ~/.config/remixmate/credentials.json（0600）：

# 全局安装时 bin 在 PATH 上：
remixmate-studio login        # 浏览器授权
remixmate-studio whoami       # 查看当前认证状态（不打印 token）
remixmate-studio logout       # 清除本地凭证

# 装在 skill 目录（~/.claude/skills/remixmate-studio）时直接跑脚本：
node ~/.claude/skills/remixmate-studio/scripts/cli.mjs login

说明：

• 这套登录与 @remixmate/cli 跑同一套设备授权流程、写同一份凭证文件。所以 「只装 studio-cli」也能登录；若你已用 remixmate login（来自 @remixmate/cli， 且存的是文件凭证）登录过，这里也能直接复用，无需重复登录。
• 登录前需 MM_BACKEND_API_URL 指向你的 ab-api（默认 http://localhost:2999/api）； 登录时与各脚本读凭证用的是同一个 base URL，保持一致即可。
• 仅在交互式终端可用；CI / 无终端环境请用下面的环境变量方式。

方式 B：环境变量 AB_PRIV_TOKEN（CI / 宿主注入）

打开 ab-web「个人设置 → API 凭证」复制 token，在 shell rc（.zshrc / .bashrc）里 export：

# 仅保存/出片/派生公共模板需要：调 ab-api 的凭证
export AB_PRIV_TOKEN="..."

# 可选：ab-api 与 ab-render 地址。不设则用本地默认
#   AB_RENDER_URL 默认 http://localhost:3000
#   MM_BACKEND_API_URL 默认 http://localhost:2999/api
export MM_BACKEND_API_URL="https://api.your-domain.com/api"
export AB_RENDER_URL="https://render.your-domain.com"

# 可选：scratch 工作区位置（默认 $PWD/.ab-scratch）
export AB_SCRATCH_DIR="$HOME/.ab-scratch"

# 可选：启用 type_check 的 DSL 校验分支
export AB_REMIXMATE_CLI_PATH="$HOME/.npm-global/lib/node_modules/@remixmate/cli/dist/cli.js"

reload shell：source ~/.zshrc。

凭证解析优先级：AB_PRIV_TOKEN 环境变量 > remixmate-studio login / remixmate login 写入的本地凭证库。即环境变量始终优先（便于 CI / 宿主覆盖）。

3. 验证

启动 Claude Code，对它说"做一个视频模板"。Claude Code 应该：

1. 自动加载 SKILL.md 并按工作流引导
2. 先问你"基于现有改 / 全新做"
3. 调 derive_template 派生骨架到 $AB_SCRATCH_DIR
4. 接下来 apply / type_check / try_render / save / render 全链路可用

4. 离线 / 零配置模式

derive_template（blank 模式，不传 base-template-id）/ apply_template_edit / type_check / 本地 try_render_remote 预览都不需要凭证——装完即可零配置起手写模板并看预览（本地 ab-render 鉴权关闭时预览免凭证；type_check 用包内自带的 typescript，无需全局安装）。

注意：derive_template 派生公共模板（--base-template-id <id>）从 ab-api/OSS 按需拉取官方骨架，需要 AB_PRIV_TOKEN 且联网（见 builtin-template-registry spec）。save_template / render_template（出正式片）同样需要凭证。

ab-template-studio 集成

ab-template-studio 通过 package.json 把本包作为 dependencies 直接拉取：

{
  "dependencies": {
    "@remixmate/studio-cli": "^0.3.0"
  }
}

npm run install-skills 会把 node_modules/@remixmate/studio-cli/ 整包拷到 apps/ab-template-studio/skills-studio/，再由 studio 的 skill-loader.ts 扫 skill.json 装配进 ab_studio MCP server。

studio 端凭证从 Nacos 拉取，由 chat-service.ts 把 AB_PRIV_TOKEN / MM_BACKEND_API_URL / AB_RENDER_URL 注入到子进程 env。本地 Claude Code 走 shell export，两边契约相同。

开发本仓

本仓不再依赖 sibling clone——公共模板骨架由 ab-api/OSS 按需提供（见 builtin-template-registry spec），derive_template 派生模式运行时拉取。

npm install
npm test                          # 起 mock server 跑 happy/negative 用例（含 OSS 派生链路打桩、props 契约、batch 原子性、retryable 跨端一致）

派生模式下载的内置模板源码缓存在 ~/.cache/remixmate/studio-templates/<key>@v<version>/； 按版本目录天然失效，发布脚本自增版本后下次 derive 会拉新版本。可设 REMIXMATE_TEMPLATE_CACHE_DIR 覆盖缓存位置（测试用）。

内置模板源码的发布（template-library → OSS）由 ab-platform 的 template-library/scripts/publish-builtin-templates.mjs 负责，不在本仓。

工具协议

所有 9 个脚本遵循统一约定：

• 入参：CLI flag，--kebab-case-key <value>；boolean 用 --<key> 出现即 true
• content 走 stdin：apply_template_edit 的 content 入参通过 stdin 透传（避免 ARG_MAX 上限）， 批量模式（--batch）则通过 stdin 传 { edits: [...] } JSON；其他工具用 CLI flag
• 出参：stdout 最末一行 JSON：{"ok": true, ...} 或 {"ok": false, "error": {"kind", "message", "retryable", "detail?"}}
• 错误可判别：error.retryable（布尔）标识该错误是否值得重试，供宿主 executor 做熔断（cli 自身不熔断）
• 进度：可选；__progress__ <json>\n 行协议（phase / progress? / etaSeconds? / extra?）
• 退出码：0 成功 / 1 user-error / 2 internal / 3 scan-rejected（仅 try_render_remote / render_template）

阶段命名（progress.phase）：

| 工具 | 阶段序列 | |---|---| | try_render_remote | scanning → bundling → rendering → done | | save_template | packaging → presign → uploading → registering → done | | render_template | presign-source → bundling → rendering → uploading → done | | resolve_assets | resolving → done |

配套 spec

设计 + 任务拆分见 ab-platform/.kiro/specs/template-creator-skill/ 三件套（requirements / design / tasks）。

License

MIT