@remixmate/cli

English | 简体中文

原名 ab-skill-cli（bin ab-skill），现已更名为 @remixmate/cli（bin remixmate）。旧包已在 npm 标记弃用，请迁移到新包。

面向 Claude Code / Codex 的 AI 媒体生成技能集。

包含 13 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获与正文抽取、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。

安装

npm install -g @remixmate/cli && remixmate install

npm install 装的是 remixmate 这个命令；remixmate install 才让 agent 自己发现 这些 skill —— 它把内置的 skills/ 铺进检测到的每个 agent 目录。下面这些宿主用的是 同一套 SKILL.md 格式，所以一份 skills/ 全都能喂：

| 宿主 | 用户级 | 项目级 | 可用环境变量改位置 | | --- | --- | --- | --- | | Claude Code | ~/.claude/skills | ./.claude/skills | CLAUDE_CONFIG_DIR | | Codex | ~/.codex/skills | — | CODEX_HOME | | WorkBuddy | ~/.workbuddy/skills | ./.workbuddy/skills | — | | CodeBuddy | ~/.codebuddy/skills | ./.codebuddy/skills | — | | Trae / TraeWork | — | ./.trae/skills | — |

Trae CN 与 TraeWork CN 共用 ~/.trae-cn，且只定义了工作区位置（.trae/skills/<name>/，依据是它自带的 skill-creator）， 所以只能按项目装 —— 直接跑 remixmate install 会提示你进项目目录加 --project 重跑。 装完重启 agent 生效。

remixmate install --host workbuddy  # 只装某一个宿主
remixmate install --project         # 装到 ./<配置目录>/skills（Codex 没有项目级目录）
remixmate install --dir <path>      # 指定目录，用于上表之外的宿主
remixmate uninstall                 # 按装机记录精确卸载

这里的安装是受管的，不是 cp -R：每个 skills 目录下会写一份 .remixmate-install.json 回执，记录版本与本次铺下去的 skill 名单。靠它，重跑即原地升级、 uninstall 只删自己装的目录、remixmate doctor 能在 npm update -g 之后提示铺出去的副本 已经落后。同名但不是本 CLI 装的 skill，不加 --force 绝不覆盖。

不装也能用，只是得点名（remixmate --list，或让 agent 去跑 remixmate <skill> --help）； agent 不会主动想到它。

认证

推荐方式（人类用户）：浏览器设备登录，无需手动粘贴 token：

remixmate login     # 在浏览器确认授权，凭证安全保存到本机
remixmate whoami    # 查看当前身份（绝不打印 token）
remixmate logout    # 从本机移除已存储的凭证

login 使用 OAuth 2.0 设备授权流程（RFC 8628）：CLI 给出一条已预填设备码的授权链接，你在已登录 Web 的浏览器中点一下确认，CLI 随后取回凭证并保存到系统钥匙串（或 ~/.config/remixmate/credentials.json，权限 0600）。

不需要交互式终端 —— 设备流不读键盘输入，agent 宿主（Claude Code / Codex）可以直接执行并把链接转述到聊天里。只有在浏览器根本不可达时才会拒绝：CI、无桌面会话的 Linux、或设置了 REMIXMATE_NO_BROWSER_AUTH=1；这些场景请改用 PRIV_TOKEN。

CI 与 agent 宿主（ab-agent / Claude Code）继续使用 PRIV_TOKEN 环境变量。凭证解析优先级：

--token 参数  >  PRIV_TOKEN 环境变量  >  本地已存凭证（remixmate login 写入）

设置了 PRIV_TOKEN 时，login 会跳过，且任何命令都不会自动触发设备登录流程。

凭证只在 CLI 的 Node 侧解析一次（src/auth/ensure.ts），再通过环境变量注入给被调起的 Python 技能 —— 技能脚本自己不读凭证库、不读钥匙串。需要让其它命令（如维护脚本）拿到同一份凭证时，用 exec：

remixmate exec -- python3 scripts/test-template-pipeline.py

每个技能在 skill.json 里用 auth 声明鉴权需求：required（缺 token 就发起授权）、optional（有就用，没有则降级继续，如 web-record 只保留本地文件）、none（纯本地，如 web-screenshot）。

失败时的退出码：4 = 需要授权，5 = 后端不可达，2 = 用法错误。

非阻塞授权（agent 宿主）

阻塞式 login 会一直等到设备码过期（10 分钟），超过 agent 单次工具调用的时长。改用两段式：

remixmate login --start --json               # 立刻返回授权链接，不等待
remixmate login --wait --timeout 60 --json   # 有界轮询；还没授权就再调一次

--start 把设备码写入 0600 的 ~/.config/remixmate/pending.json；--wait 兑换后清除它。用户尚未确认时 --wait 返回 {"status":"pending"} 与退出码 4，并保留 pending 状态，可以反复调用。

排障

remixmate doctor            # 检查 node / python3 / Playwright / 凭证 / 后端
remixmate doctor --offline  # 跳过联网探测

只有凭证一项有问题时，doctor 退出码为 4。

列出技能

remixmate --list 默认输出人类可读表格（技能名 + 是否需登录 + 摘要），末尾附一行当前登录状态（写到 stderr，不干扰管道）。给工具消费请用 remixmate --list --json。

安全提示：若你此前曾把 PRIV_TOKEN 粘贴到聊天框或写进 shell 历史，切换到 remixmate login 后建议轮换该 token。

环境

多数技能通过 PRIV_TOKEN 向 ab-api 鉴权。没有有效 token（以及访问 ab-api 的网络）时，模板 / 媒体生成类技能不可用——代码是开源的，但生成能力托管在 ab-api 服务上。运行前把 .env.example 拷为 .env 并 source：

cp .env.example .env
# 修改其中的值
source .env

Python 技能（13 个中的 9 个）需要 python3 >= 3.10。web-screenshot / web-record / web-read 需要 Playwright（首次运行自动安装 chromium）。ffmpeg 仅 video-parser 的可选本地工具（deconstruct_video.py）需要；video-parser 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。

技能

本项目包含 13 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。

技能分层

┌─────────────────────────────────────────────────────────────┐
│ 编排层 Skills                                                │
│  gen-script           主题 → Video DSL（脚本生成）           │
│  template-registry        DSL → TemplateBinding（模板列表）      │
│  prepare-video-assets DSL + Binding → 素材补齐（Phase 1）    │
│  render-video         RenderPlan → Remotion 渲染（Phase 3）  │
│  export-jianying      素材 → 剪映草稿 ZIP                    │
├─────────────────────────────────────────────────────────────┤
│ 原子层 Skills                                                │
│  gen-image         文生图 / 图生图（Seedream 5.0）           │
│  gen-video         文生视频（Seedance 2.0）                  │
│  gen-voice         语音合成（Minimax TTS）                   │
│  gen-digital-human 数字人口播（即梦 / 飞影）                 │
├─────────────────────────────────────────────────────────────┤
│ 工具层 Skills                                                │
│  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
│  web-screenshot    网页截图（png / jpg）                     │
│  web-record        网页录屏 / 滚动录屏 / 分镜视频            │
│  web-read          网页正文抽取（markdown / 纯文本 / JSON）  │
└─────────────────────────────────────────────────────────────┘

目录结构

├── docs/
│   └── video-production-architecture.md   # 架构文档
├── src/                        # TypeScript CLI + http/builtin handlers
├── skills/
│   ├── gen-image/              # 原子: AI 生图（http handler）
│   ├── gen-video/              # 原子: AI 生视频（http handler）
│   ├── gen-voice/              # 原子: 语音合成（http handler）
│   ├── gen-digital-human/      # 原子: 数字人口播（http handler）
│   ├── gen-script/             # 编排: 主题 → Video DSL
│   ├── template-registry/          # 编排: 模板列表（python list_templates.py）
│   ├── prepare-video-assets/   # 编排: Phase 1 素材准备（thin wrapper）
│   ├── render-video/           # 编排: Phase 3 Remotion 渲染（含 render_video.py 实现）
│   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
│   ├── video-parser/           # 工具: 视频解构与分析
│   ├── web-screenshot/         # 工具: 无头浏览器截图（record.py 也放在这里）
│   ├── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
│   └── web-read/               # 工具: 无头浏览器正文抽取（入口指向 web-screenshot/scripts/read_page.py）
└── README.md

技能说明

| 技能 | 类型 | 说明 | 运行方式 / entry | |------|------|------|------------------| | gen-image | 原子 | 文生图 / 图生图（Seedream 5.0 Lite / Pro） | http handler | | gen-video | 原子 | 文生视频（Seedance 2.0 三档） | http handler | | gen-voice | 原子 | 语音合成（Minimax TTS） | http handler | | gen-digital-human | 原子 | 数字人口播（即梦 / 飞影） | http handler | | gen-script | 编排 | 主题 → Video DSL JSON | python scripts/gen_script.py | | template-registry | 编排 | 模板列表（绑定逻辑内嵌于 prepare-video-assets） | python scripts/list_templates.py | | prepare-video-assets | 编排 | DSL + Binding → 素材补齐 → 落库 RenderPlan | python scripts/prepare_video_assets.py（包装 render_video.py --resolve-only） | | render-video | 编排 | job_id → Remotion 渲染 → 上传 | python scripts/render_video.py | | export-jianying | 编排 | 素材 URL → 剪映草稿 ZIP（支持从 RenderPlan 自动转换） | python scripts/gen_jianying_draft.py | | video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | python scripts/parse_via_render.py | | web-screenshot | 工具 | 网页截图（png / jpg） | python scripts/screenshot.py | | web-record | 工具 | 网页录屏 / 滚动录屏 / 分镜视频（webm → mp4 → VOD） | python ../web-screenshot/scripts/record.py | | web-read | 工具 | 网页正文抽取（markdown / 纯文本 / 结构化 JSON） | python ../web-screenshot/scripts/read_page.py |

核心链路

详见 视频内容生产架构文档 和 编排流程指南。

链路 A：主题 → Remotion 视频

gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
→ ✅用户确认素材 → render-video(--job-id) → MP4

链路 B：主题 → 剪映草稿

gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
→ ✅用户确认素材 → export-jianying(--from-job-id) → 剪映 ZIP

测试

# 列出所有技能（名称、tool、entry 类型）
remixmate --list

# 离线注册表 smoke + 规范守卫
npm run smoke

# CLI 单元测试（argv 解析器 + skill schema）
npm run test:cli

# Python 技能会把 --help 透传给底层脚本：
remixmate gen-script --help
remixmate prepare-video-assets --help
remixmate render-video --help
remixmate export-jianying --help
remixmate video-parser --help
remixmate web-screenshot --help
remixmate web-record --help
remixmate web-read --help
remixmate template-registry --help

# http 技能（gen-image、gen-video、gen-voice、gen-digital-human）没有
# python --help；参数见各自的 SKILL.md / skill.json。

# 查看可用音色
remixmate gen-voice --list-voices

# 查看可用模板
remixmate template-registry --list-templates

开发流程

• 克隆此项目到本地
• 在 skills 目录下各技能文件夹中开发
• 每个技能包含 SKILL.md（技能说明）、version.json（元数据）和 scripts/（脚本）

快速体验

@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用 seedream-pro，国画风 + 严格按该文档执行
@skills/gen-video/SKILL.md 生成一段熊猫在竹林奔跑的视频，9:16，长度6秒，用 seedance-mini + 严格按该文档执行
@skills/gen-voice/SKILL.md 生成一段语音，介绍熊猫的习性，大概100字左右 + 严格按该文档执行
@skills/gen-digital-human/SKILL.md 获取数字人列表 + 严格按该文档执行
@skills/template-registry/SKILL.md 获取模版列表 + 严格按该文档执行
@skills/gen-script/SKILL.md 基于模版 image-slide，创作一个关于AI学习方法的视频 + 严格按该文档执行

许可证

MIT