本文预计阅读：5 分钟
一、我为什么要做这个工具
做矩阵号的人都有一个固定动作：视频剪好，打开6个 Tab，逐个上传、填标题、填标签、点发布。
一条视频，最快 15 分钟，遇上网速慢或者平台抽风，半小时就没了。
我当时的状态是：用 n8n 跑了一条自动化流程------AI 生成脚本、自动合成视频、自动生成封面，到最后一步"发布到平台"，流程断了，还得人坐在那手动点。
市面上有易媒这类付费工具，但它们全是 GUI 黑盒，外部程序没有任何办法调度它。n8n 节点调不到，Claude Code 写不进去，你的 AI 流程到这一步只能停下来等人。
这就是 MatrixMedia 的出发点：不只是"自动点鼠标"，而是让 AI Agent 能把发布视频当成一个普通命令来调用。
开源地址：github.com/hanliang97/...
二、CLI 设计：让 AI Agent 能"读懂"这个工具
这是整个项目最核心的部分，其他功能都是围绕这里展开的。
统一入口
argv 里含 cli 子串就进入无 GUI 模式，Electron 窗口不会弹出来：
bash
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，没有任何噪音行混进去：
css
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 参数：
css
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，中文优先。