用 Electron + Puppeteer 把视频自动发布变成 AI Agent 可调用的 CLI 工具

本文预计阅读：5 分钟

---

一、我为什么要做这个工具

做矩阵号的人都有一个固定动作：视频剪好，打开6个 Tab，逐个上传、填标题、填标签、点发布。

一条视频，最快 15 分钟，遇上网速慢或者平台抽风，半小时就没了。

我当时的状态是：用 n8n 跑了一条自动化流程------AI 生成脚本、自动合成视频、自动生成封面，到最后一步"发布到平台"，流程断了，还得人坐在那手动点。

市面上有易媒这类付费工具，但它们全是 GUI 黑盒，外部程序没有任何办法调度它。n8n 节点调不到，Claude Code 写不进去，你的 AI 流程到这一步只能停下来等人。

这就是 MatrixMedia 的出发点：不只是"自动点鼠标"，而是让 AI Agent 能把发布视频当成一个普通命令来调用。

开源地址：github.com/hanliang97/...

---

二、CLI 设计：让 AI Agent 能"读懂"这个工具

这是整个项目最核心的部分，其他功能都是围绕这里展开的。

统一入口

argv 里含 cli 子串就进入无 GUI 模式，Electron 窗口不会弹出来：

matrixmedia cli publish \
  -p dy \
  --phone 13800138000 \
  -f "/path/to/video.mp4" \
  -t "视频标题" \
  --tags "#标签1 #标签2"
echo "exit: $?"

这条命令跑完，AI Agent 只需要读 $?，就知道下一步该干什么。

exit code 规范

这是 AI Agent 能不能真正用起来的关键。设计了 4 个退出码：

code	含义
0	发布成功
1	未知异常
2	参数错误（比如 -p 传了不支持的平台）
3	业务失败（登录态过期、平台接口报错）

code 3 和 code 2 对 AI Agent 来说意义完全不同------2 说明要修命令，3 说明要先去重新登录。如果全部返回 1，Agent 根本判断不了下一步。

JSON stdout

查账号列表和发布历史，加 --json 会输出稳定结构的 JSON Array，没有任何噪音行混进去：

matrixmedia cli accounts --json
# 输出：[{"platform":"dy","phone":"138xxxx","status":"active"}, ...]

这是给 n8n 的 JSON Parse 节点、或者 Claude Code 里的 shell 调用直接消费用的。不用正则解析，不会因为哪天加了一行 log 就崩。

4 个子命令

• publish --- 发布单条视频
• accounts --- 查登录账号和存活状态
• history --- 查发布记录
• schedule --- 登记定时任务

---

三、定时发布：调度引擎的实现

CLI 里有个 --publish-at 参数：

matrixmedia cli publish \
  -p dy \
  --phone 13800138000 \
  -f "/path/to/video.mp4" \
  -t "视频标题" \
  --publish-at "2026-05-08 09:00:00"

这条命令执行后，任务被写入本地调度队列，到点自动触发 Puppeteer 去发布。

几个有意为之的设计边界：

不支持周期循环。 每条任务都必须明确指定时间。原因：矩阵号的发布节奏通常由上游 AI 流程决定，MatrixMedia 只负责"在指定时间把这条内容发出去"，不替你决定"什么时候发"。

程序关闭期间错过的任务显示"过期"，不补发。 补发一条过了时间的内容没有意义，平台算法已经错过了那个时间窗口。

与 n8n 配合的方式： n8n 跑完内容生成流程，最后一步 Execute Command 节点里传 --publish-at，整条链路不需要人在场。

---

四、AI 工具联动实战

n8n 场景

典型流程：HTTP 触发 → 视频生成 → Execute Command 调 matrixmedia cli publish → Switch 节点读退出码 → 0 走成功分支，3 走重登录分支，2 走报警分支。

这个流程里没有任何人工节点。

AI 编程助手场景

在上下文里描述 CLI 的用法和退出码含义，AI 编程助手就能直接生成正确的 shell 调用，也能在退出码不为 0 时写出正确的错误处理逻辑。

一个实际例子：让 AI 编程助手写一个发布脚本，生成的代码会自动处理 code 2（修参数）和 code 3（提示重新登录），不用人手动告诉它每个错误该怎么处理。

为什么这件事值得专门设计

现有的矩阵发布工具，哪怕 GUI 做得再好，对 AI Agent 来说都是不透明的。MatrixMedia 的 CLI 契约是专门为"被程序调用"设计的，不是把 GUI 功能硬加一个命令行入口。这是本质区别。

---

五、开源地址 + 路线图

GitHub：github.com/hanliang97/...

演示视频（B站）：www.bilibili.com/video/BV1hQ...

当前版本 0.5.4，支持抖音 / 快手 / 百家号 / B站 / 头条 / 视频号。

CLI 契约已通过 22 条断言的自动化验证脚本（verify-cli.sh）覆盖，exit code 和 JSON stdout 有保障。

路线图上的下一步：

• MCP Server --- 让 MatrixMedia 成为标准 MCP Tool，Cursor / Claude Desktop 直接调
• Webhook 推送发布结果 --- 发布完成后主动通知上游流程，不用轮询
• 更完整的 AI Agent SDK 封装

如果你在用 n8n / Claude Code / Cursor 搭自动化流程，又在做矩阵号，欢迎试试。有问题直接开 issue，中文优先。

---