# MatrixMedia (hanliang97/MatrixMedia)

> MatrixMedia (矩媒) is a desktop and CLI tool for publishing short videos in batches to many Chinese video platforms at once, such as Douyin, Kuaishou, Xiaohongshu, Bilibili and WeChat Channels.

- GitHub: https://github.com/hanliang97/MatrixMedia
- GitHub.Locker page: https://github.locker/hanliang97/MatrixMedia
- Stars: 1.5K
- Language: JavaScript
- License: GPL-2.0
- Last push: 2026-11-14

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is it a desktop app, a CLI or a library?**

It is primarily an Electron desktop app with a GUI, and it also has a full command-line interface (cli publish, cli accounts, cli history) and an HTTP API and MCP server for automation.

**How do I get it running?**

Download the installer from the GitHub or Gitee releases page. On Windows the NSIS installer adds the matrixmedia CLI to PATH automatically; on macOS you drag the app to Applications and create a symlink for the CLI.

**Do I need Node.js to use it?**

Not for end users with the packaged app. Node 20 and yarn are only needed to develop it from source, via 'yarn dev' or 'yarn build'.

**Does publishing always work?**

No. Only 8 platforms are fully automated for CLI publishing, and you must log in once through the GUI because the MCP and CLI cannot show login windows. Platforms can add manual checks, and Xiaohongshu may flag the embedded window, so there is an optional real-Chrome mode.

**Which operating systems does it support?**

Windows and macOS for the GUI, plus the CLI. macOS has separate x64 and arm64 builds, and unsigned builds may show a 'damaged' warning that needs a one-time xattr fix.

**What is the main feature?**

You configure a set of accounts once, then push one video to several platforms in a single command or API call, with optional scheduled publishing.

**Can AI agents call it?**

Yes. The CLI uses stable exit codes and --json output, and there is an MCP server with nine tools, so tools like Claude Desktop, Cursor or Dify can drive it.

**Can it read comments and stats?**

Yes. Commands like cli comments and cli stats read comments and follower or view snapshots, and comment replies are dry-run by default until --execute is passed.

**Why does it use the CLI instead of a web API?**

The author designed the CLI as tool-agnostic so any shell-capable automation platform can use it without SDK changes.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/hanliang97/MatrixMedia/blob/main/README.md

<p align="center">
  <img src="./lib/icons/icon.png" alt="MatrixMedia · 矩媒" width="128" />
</p>

<h1 align="center">矩媒 MatrixMedia</h1>

> **自媒体 · 矩阵 · 批量** — 多平台视频矩阵发布与批量分发工具（Electron + CLI）

<p align="center">
  <img src="./src/renderer/layout/components/Sidebar/ptcion/dy.png" alt="抖音" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/ks.png" alt="快手" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/bjh.png" alt="百家号" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/blbl.jpeg" alt="哔哩哔哩" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/tt.png" alt="头条号" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/sph.png" alt="视频号" width="36" />&nbsp;&nbsp;
  <img src="./src/renderer/layout/components/Sidebar/ptcion/xhs.png" alt="小红书" width="36" />
</p>

## 官网

[GitHub Pages · 矩媒官网](https://hanliang97.github.io/MatrixMedia/)

## 软件下载地址

- 国内 Gitee：[gitee.com/gzlingyi_0/pubtw/releases](https://gitee.com/gzlingyi_0/pubtw/releases/)
- GitHub：[github.com/hanliang97/MatrixMedia/releases](https://github.com/hanliang97/MatrixMedia/releases)

## 工具使用文档

- 国内文档：[Gitee Wiki](https://gitee.com/gzlingyi_0/pubtw/wikis/pages?sort_id=14772656&doc_id=7335804)
- 官网文档：[hanliang97.github.io/MatrixMedia](https://hanliang97.github.io/MatrixMedia/)

## 关键词（便于搜索）

自媒体、自媒体矩阵、矩阵发布、矩阵运营、内容矩阵、视频矩阵、多平台矩阵、跨平台发布、批量发布、批量上传、批量分发、一键发布、多账号发布、多平台发布、本地视频发布、短视频矩阵、内容分发、账号矩阵、自动化发布、CLI 批量、命令行发布、无头发布、智能体编排、OpenClaw、MCP 发布、抖音矩阵、快手矩阵、小红书矩阵、百家号矩阵、哔哩哔哩矩阵、头条矩阵、视频号矩阵、番茄视频、番茄视频矩阵、MatrixMedia、矩媒、pubtw

## <strong>📺 [教程视频](https://www.bilibili.com/video/BV1fiX5BzEb7)</strong>

自媒体矩阵发布工具（Electron）。支持图形界面与**命令行（CLI）**自动化，适合**批量**向多平台账号矩阵分发视频：

- **支持平台**：Windows、macOS、CLI。
- **CLI 登录**：目前支持**抖音**与**视频号**（终端二维码；抖音另支持 puppeteer 无头）。
- **CLI 发布**：**8 个平台**已完整自动化——抖音、快手、百家号、哔哩哔哩、头条、视频号、小红书、番茄视频。`file` 支持本地路径或 `http(s)` 远程 URL（自动下载，上传后清理临时文件）。
- **CLI 查询**：`cli accounts` 实时检测登录态，`cli history` 查看本机发布记录。
- **CLI 评论互动**：`cli comments` 拉取已发布作品评论（抖音/快手/视频号），`cli comments-reply` 回复评论（默认 dry-run，`--execute` 真发，全程台账）。
- **HTTP API**：GUI 启动后可通过 `POST http://127.0.0.1:30088/publish` 由其它程序触发发布（见 [docs/http-api.md](./docs/http-api.md) 或应用内「项目详情」页）。

便于脚本与智能体编排。GUI 打开后默认进入「**项目详情**」页，可查看 HTTP / MCP / CLI 接入说明。

<!-- openclaw-integrable: id=matrixmedia-cli version=1 platform=electron argv-marker=cli -->
<!-- 说明：本仓库以 argv 含 `cli` 作为统一入口，可被 OpenClaw / Hermes / Claude Code / OpenAI Codex / WorkBuddy / Cursor / Dify / n8n 等 AI 工具与智能体编排框架发现与调用；子命令 `login`（抖音 / 视频号）、`publish`、`publish-article` 等详见 [docs/cli.md](./docs/cli.md)。 -->

## AI 工具 / 智能体联动

本项目的 CLI 被刻意设计为 **AI 工具无关 / 框架无关** 的外部命令：只要你的工具能调用 shell、读取退出码或 JSON stdout，就能直接对接 —— 包括但不限于：

- [OpenClaw](https://github.com/openclaw/openclaw)
- [Hermes](https://github.com/NousResearch/hermes-agent)
- Claude Code、OpenAI Codex（Codex CLI / Codex Cloud）、WorkBuddy 等 AI 办公 / 编程智能体
- Cursor、Cline、Aider 等 IDE 编程助手
- Dify、n8n、LangChain、CrewAI、AutoGen 等工作流 / 多智能体编排框架
- 任何支持「外部命令 + argv + 退出码」约定的自动化平台（含自研调度器）

统一约定：

| 约定项        | 内容                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| 进入 CLI 模式 | argv 含子串 `cli` 即进入无 GUI 流程（如 `matrixmedia cli publish ...`）                                |
| 子命令        | `cli login \| publish \| publish-article \| accounts \| history`，每个均支持 `--help`                  |
| 退出码        | `0` 成功 / `1` 异常 / `2` 参数错误 / `3` 业务失败（登录、上传等）                                      |
| 机器可读输出  | `cli accounts --json` 与 `cli history --json` 产出稳定 JSON，便于上游消费                              |
| 登录态共享    | CLI 与 GUI 共用 `persist:<phone><平台>` session partition，互不侵扰                                    |
| HTTP API      | GUI 启动后 `POST http://127.0.0.1:30088/publish` 发布视频（见 [docs/http-api.md](./docs/http-api.md)） |

详细文档：[CLI](./docs/cli.md) · [HTTP API](./docs/http-api.md) · [MCP](./docs/mcp.md)

仓库顶部的 `<!-- openclaw-integrable ... -->` HTML 注释以 OpenClaw 的 schema 示例上述约定；其它平台如需类似的仓库级可发现标记，可沿用同一 `argv-marker=cli` 语义，或加上自家的注释标签（例如 `<!-- hermes-integrable ... -->`），互不冲突。

典型用法：在 AI 平台/智能体侧将本应用配置为 **外部命令**（`command` + `args`）：`cli login` 可用于 **抖音 / 视频号** 扫码登录；其它平台请先在 GUI 登录一次，CLI 会复用同一 session partition；`cli publish` 对已自动化 8 平台一致可用。终端二维码与无头模式等行为见 [docs/cli.md](./docs/cli.md) 与各子命令 `--help`。

### MCP Server（Claude Desktop / Cursor / Cline 原生接入）

仓库内置 `mcp/` 子包，实现了 [Model Context Protocol](https://modelcontextprotocol.io) Server，让支持 MCP 的 AI 工具**无需 shell 调用**即可直接操作 MatrixMedia。

**第一步：构建 MCP Server**

```bash
cd mcp && npm install && npm run build
```

**第二步：配置 AI 工具**

以下配置适用于 Claude Desktop、Cursor、Cline 等支持 MCP stdio transport 的工具。
将 `MATRIXMEDIA_DIR` 设为本仓库根目录的绝对路径。

_Claude Desktop_（`~/Library/Application Support/Claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "matrixmedia": {
      "command": "node",
      "args": ["<MATRIXMEDIA_DIR>/mcp/dist/index.js"],
      "env": {
        "MATRIXMEDIA_DIR": "<MATRIXMEDIA_DIR>"
      }
    }
  }
}
```

_Cursor / Cline_（`.cursor/mcp.json` 或全局 MCP 配置，格式相同）：

```json
{
  "mcpServers": {
    "matrixmedia": {
      "command": "node",
      "args": ["<MATRIXMEDIA_DIR>/mcp/dist/index.js"],
      "env": {
        "MATRIXMEDIA_DIR": "<MATRIXMEDIA_DIR>"
      }
    }
  }
}
```

重启 AI 工具后，以下 9 个 tool 即可在对话中直接调用（完整说明见 [docs/mcp.md](./docs/mcp.md)）：

| Tool                 | 说明                                                        |
| -------------------- | ----------------------------------------------------------- |
| `list_accounts`      | 列出本机已登录账号，支持按平台过滤                          |
| `list_history`       | 查询本机发布记录，支持按平台 / 状态 / 天数过滤              |
| `publish_video`      | 发布视频到指定平台（最长 35 分钟，支持定时发布）            |
| `publish_article`    | 发布掘金文章（需已登录掘金账号）                            |
| `get_account_stats`  | 读取账号粉丝数据快照（粉丝/播放/点赞/评论/收藏）            |
| `sync_account_stats` | 主动采集该账号最新数据并写入快照                            |
| `get_work_stats`     | 按完整标题查某个视频的发布数据（含发布时间、互动数据）      |
| `list_comments`      | 拉取账号已发布作品的评论列表（抖音/快手/视频号，只读）      |
| `reply_comment`      | 回复评论/发顶层评论（默认 dry-run，`confirm=true` 才真发）  |

> **登录说明**：所有平台均需在 GUI 中完成登录后再通过 MCP 发布。MCP 运行在无头 stdio 环境，无法弹出扫码窗口。

**DeepSeek Harness（DSH）**：[`dsh-plugin/`](./dsh-plugin) 目录是现成的 DSH 插件（范式同 [dsh-plugin-kuaizi-atom](https://github.com/hanliang97/dsh-plugin-kuaizi-atom)），在 DSH Web UI → 插件 → 添加插件 → Git 仓库中填入插件仓库地址即可一键接入上述 MCP 工具，详见 [dsh-plugin/README.md](./dsh-plugin/README.md)。

### AI 自动 e2e 开发模式（v0.14.0）

[`.agent/`](./.agent) 是 AI 编程智能体在本仓库的工作入口：`skills/` 可复用技能 + **「AI 自动 e2e 开发模式」工作流引导**。发布主链路的 AI 开发必须走完整闭环：

> 改代码 → 单测 → **e2e 真实平台验证**（`node e2e/run.js -p <平台> --yes`，自动构建本地产物免打包）→ 读证据（诊断行 / 截图 / 回执 JSON）→ 修正 → 重跑 → 直至 `draftVerified=true`

红线：不允许无条件回报成功；误判失败会触发重试导致重复上传；证据不足时诚实标注「待人工核对」。工作流详见 [.agent/README.md](./.agent/README.md)，完整迭代实录（10 轮 e2e、每轮现象/证据/动作）见 [.agent/case-2026-10-31-video-draft-e2e.md](./.agent/case-2026-10-31-video-draft-e2e.md)。
## 抖音商品挂载（待账号实机验收）

GUI「本地视频发布 → 第三方属性」可为每个账号配置一种商品。抖音填写完整商品链接和 1–10 字商品短标题，商品短标题独立于视频号的视频短标题。

此实现依据 #30 的桌面操作截图完成（#31），已通过离线 DOM、参数和发布控制流测试，尚无具备带货权限的真实账号验收。平台结构不符、无权限、无效商品或无法确认挂载会停止发布，不承诺已保存草稿。显式开启抖音商品的任务只尝试一次，人工核对后再重试；选择「无」保持原流程。快手商品挂载已实现但暂缓合入，待有权限账号实测校验。

本次只增加 GUI 单视频配置与发布器接入；目录批量若配置了抖音商品会明确阻断，请改用单视频。CLI / HTTP / MCP 未新增抖音商品参数；原有视频号商品、短剧和剧集参数保持原意。

## 目前可以一键发布视频的平台有

1. 抖音
2. 快手
3. 百家号
4. 哔哩哔哩
5. 头条号
6. 视频号
7. 小红书
8. 番茄视频

小红书平台对 Electron 内置窗口的自动化检测日趋严格，可能出现「AI 托管」警告。为此新增**真实浏览器发布模式**，使用本机已安装的 Google Chrome / Chromium 代替内置窗口进行发布，从根源上规避检测。

**启用方法**：

1. 进入账号管理 → 小红书账号 → 「发布设置」卡片
2. 打开「使用真实浏览器」开关
3. 首次开启会**自动检测**本机 Chrome 路径；也可手动点击「选择 Chrome 浏览器」选取应用（macOS 直接选 `.app`，Windows 选 `.exe`）
4. 点击「测试连接」确认 Chrome 可用
5. 保存设置

**工作原理**：

- 使用项目已有的 `puppeteer-core`（轻量库，不捆绑 Chromium）直接驱动本机 Chrome
- 发布时自动从内置窗口同步登录态（Cookie）到真实 Chrome
- Chrome 路径为全局配置（所有小红书账号共用），保存在 `userData/chrome-config.json`
- 若检测不到 Chrome 或启动失败，自动回退到内置窗口模式

### 番茄视频

[番茄视频创作平台](https://pugc.yueduwuxian.com/fqvideo/login) 已支持 GUI 登录、自动上传发布与作品列表审核状态回查。

| 用途     | URL                                                     |
| -------- | ------------------------------------------------------- |
| 登录页   | https://pugc.yueduwuxian.com/fqvideo/login              |
| 发布页   | https://pugc.yueduwuxian.com/fqvideo/home/publish-video |
| 作品列表 | https://pugc.yueduwuxian.com/fqvideo/home/video-list    |

| 能力                    | 状态                |
| ----------------------- | ------------------- |
| GUI 添加账号 / 登录窗口 | 可用                |
| GUI / CLI 自动发布      | 可用                |
| 登录 Cookie 自动检测    | 可用（`sessionid`） |
| 发布审核状态回查        | 可用                |

**CLI / 配置别名**：`fqsp`、`fanqie`、`fq`、`番茄视频`

**主要代码位置**：

| 文件                               | 说明                |
| ---------------------------------- | ------------------- |
| `src/renderer/utils/configUrl.js`  | 渲染层 URL          |
| `src/main/config/ptConfig.js`      | 主进程 / CLI 用 URL |
| `src/main/services/upLoad/fqsp.js` | 自动发布逻辑        |
| `src/main/services/zt/fqsp.js`     | 审核状态查询        |
| `src/main/services/getCookie.js`   | 登录态 Cookie 规则  |

侧栏图标（可选）：将 `fqsp.png` 放到 `src/renderer/layout/components/Sidebar/ptcion/`。

## 命令行（CLI）

从项目根或已安装应用启动时，在参数中加入 **`cli`** 即进入 CLI（不打开主窗口）。完整参数说明见 **[docs/cli.md](./docs/cli.md)**。子命令一览：

| 子命令                | 支持平台                                                                      | 作用                                                           |
| --------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `cli login`           | **抖音**（`-p dy`）、**视频号**（`-p sph`）                                   | 终端二维码扫码登录                                             |
| `cli publish`         | **8 个已自动化平台**（`dy \| tt \| ks \| blbl \| bjh \| sph \| xhs \| fqsp`） | 发布视频（本地路径或 http(s) URL，与 GUI「本地视频发布」等价） |
| `cli publish-article` | **掘金**（`juejin`）                                                          | 发布文章（`--content` 或 `--file`）                            |
| `cli accounts`        | 全平台（含 `fqsp` 番茄视频）                                                  | 列出所有账号并实时检测 cookie 登录态                           |
| `cli history`         | 全平台（含 `fqsp` 番茄视频）                                                  | 读取本机发布记录（`pushData`），支持平台/手机号/状态/时间过滤  |
| `cli stats`           | 7 个统计平台（`dy \| sph \| blbl \| bjh \| tt \| ks \| xhs`）                 | 读取账号粉丝数据快照（粉丝/播放/点赞/评论/收藏）               |
| `cli stats-sync`      | 同上                                                                          | 主动采集该账号最新数据并写入快照（需 GUI 已登录）              |
| `cli stats-work`      | 同上                                                                          | 按完整标题查某个视频的发布数据（含发布时间）                   |
| `cli comments`        | 抖音、快手、视频号                                                            | 拉取已发布作品的评论列表（只读，归一化 JSON）                  |
| `cli comments-reply`  | 同上                                                                          | 回复评论（默认 dry-run 校验，`--execute` 真发，写台账）        |

> **非 CLI 登录平台的登录怎么办？** 当前 CLI 登录已实现抖音与视频号；其它平台**先在 GUI 完成一次登录**即可——CLI 通过同一 `persist:<phone><平台>` session partition 读取 cookie，后续 `cli publish` / `cli accounts` 会自动复用登录态。登录态过期时 `cli accounts` 会报 `cookie 已过期`，此时回到 GUI 重登一次即可。

常用示例：

```bash
# 抖音登录
matrixmedia cli login -p dy --phone 13800138000

# 发布视频（简介、标签；视频号另加短标题）
matrixmedia cli publish -p dy --phone 13800138000 -f /path/to/video.mp4 \
  -t "标题" --description "视频简介" --tags "#跑步 #新手"
matrixmedia cli publish -p sph --phone 13800138000 -f /path/to/video.mp4 \
  -t "标题" --description "视频简介" --short-title "5公里新手挑战" --tags "#跑步 #新手"

# 发布掘金文章
matrixmedia cli publish-article -p juejin --phone 13800138000 -t "文章标题" --file ./post.md

# 查看账号 / 历史（JSON）
matrixmedia cli accounts --json
matrixmedia cli history --json --days 7

# 数据统计：先采集，再读快照 / 查单个视频
matrixmedia cli stats-sync -p sph --phone 123
matrixmedia cli stats -p sph --phone 123
matrixmedia cli stats-work -p ks --phone 123 --title "视频完整标题"

# 评论互动：拉评论 → dry-run 校验 → 人工核准后真发
matrixmedia cli comments -p ks --phone 123
matrixmedia cli comments-reply -p ks --phone 123 --file replies.json
matrixmedia cli comments-reply -p ks --phone 123 --file replies.json --execute
```

开发环境调用示例：

```bash
ELECTRON_RUN_AS_NODE= electron . cli login --help
ELECTRON_RUN_AS_NODE= electron . cli publish --help
ELECTRON_RUN_AS_NODE= electron . cli publish-article --help
ELECTRON_RUN_AS_NODE= electron . cli accounts --help
ELECTRON_RUN_AS_NODE= electron . cli history --help
```

### Windows：安装即可用

Windows NSIS 安装包从 `0.4.5` 起会在安装时自动把应用安装目录加入当前用户 `PATH`，并固定 CLI 命令名为 `matrixmedia`。安装完成并重新打开终端后，可直接执行：

```bash
matrixmedia cli login --help
matrixmedia cli publish --help
matrixmedia cli accounts
matrixmedia cli history -d 7
```

### macOS：一条命令加入 PATH

macOS 的 `.dmg` 只是磁盘镜像，无法像 NSIS 那样自动写 PATH。把 app 拖进 `/Applications` 后，执行一次下面的命令创建符号链接即可：

```bash
sudo ln -sf /Applications/matrixmedia.app/Contents/MacOS/matrixmedia /usr/local/bin/matrixmedia
```

之后在任意终端都能直接用 `matrixmedia cli ...`。若后续升级 app 只是覆盖安装（app 路径不变），符号链接仍然有效，无需重复执行。卸载时删除链接：

```bash
sudo rm /usr/local/bin/matrixmedia
```

若无需永久写入，也可临时 alias：

```bash
alias mm='/Applications/matrixmedia.app/Contents/MacOS/matrixmedia'
```

### macOS：提示“已损坏，无法打开”

macOS 分发 `x64` 与 `arm64` 两套安装包。**Apple Silicon（M1/M2/M3/M4 芯片）请用 `MatrixMedia-<version>-mac-arm64.dmg`**。若提示“已损坏，无法打开”，通常不是安装包真的损坏，而是 macOS Gatekeeper 对未签名 / 未公证应用的拦截。

临时处理方式（拖进「应用程序」后执行一次即可，之后双击正常打开）：

```bash
xattr -dr com.apple.quarantine /Applications/matrixmedia.app
```

> 如果 app 装在别的位置，把路径换成实际路径；系统级目录（如 `/Applications` 属主为 root）时才需要前面加 `sudo`。

正式分发给普通用户时，建议使用 Apple Developer 的 Developer ID 证书对 macOS 包进行签名和公证。

### 其它提示

- 中英文可执行文件名已统一为 `matrixmedia`，无需区分。
- 若环境变量 `ELECTRON_RUN_AS_NODE` 被误开启，请先按提示关闭后再启动。
- `cli accounts` / `cli history` 仅读取本机数据，不会触发任何登录或发布动作，适合在 pipeline 里做 preflight 检查。

## 内置 HTTP API（需 GUI 已启动）

应用图形界面启动后，会自动在本机 **30088** 端口（`BuiltInServerPort`，见 `env/.env`）监听内置 Express 服务。完整路由与参数说明见 **[docs/http-api.md](./docs/http-api.md)**（应用内「项目详情」页亦有摘要）。

> **与 CLI 的区别**：HTTP API 依赖 GUI 主进程已运行（托盘/窗口在即可）；CLI 可独立启动。单平台请求会等待上传完成或超时；多平台请求与 GUI 批量发布一致，提交到发布队列后立即返回。

### 数据接口

| 方法 | 路径                   | 说明                                                              |
| ---- | ---------------------- | ----------------------------------------------------------------- |
| POST | `/changeData`          | 读写本地 JSON 数据（账号树、发布历史等）                          |
| GET  | `/creative-statements` | 各平台创作声明选项（对齐 GUI 批量设置）                           |
| GET  | `/stats`               | 读账号粉丝数据快照：`?phone=<分组>&pt=<平台>`（支持短码与中文名） |
| POST | `/stats/sync`          | 主动采集该账号最新数据并写库：`{"phone":"123","pt":"blbl"}`       |
| GET  | `/stats/work`          | 按完整标题查视频发布数据（含发布时间）：`?phone&pt&title`         |

### 发布视频

| 方法 | 路径       | 说明                                               |
| ---- | ---------- | -------------------------------------------------- |
| POST | `/publish` | 发布视频到单平台或多平台（本地路径或 http(s) URL） |

视频元数据字段与 GUI「本地视频发布」一致：`title` 为标题，`description` 为简介，`shortTitle` 仅视频号短标题，`tags` 为标签。抖音 / 快手 / 视频号会把简介与标签拼进正文；小红书正文写简介、标签走话题控件；哔哩哔哩简介和标签各自独立填写；头条 / 百家号只写标题。旧字段 `bt2` 仍兼容：视频号当短标题，其他平台当简介。

**请求体（JSON）**：

| 字段                 | 必填   | 说明                                                                                                                                     |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `platform`           | 单平台 | 平台：`dy` / `抖音`、`sph` / `视频号`、`ks` / `快手` 等（与 `platforms` 二选一）                                                         |
| `platforms`          | 多平台 | 平台数组，如 `["dy","sph","ks"]`；或对象数组 `[{ "platform": "dy", "phone": "138..." }, ...]`（可覆盖共享字段）                          |
| `file`               | 是     | 本地视频绝对路径，或 `http://` / `https://` 远程视频 URL（会先下载到临时目录，全部平台发布结束后自动删除；定时发布则在到点执行时再下载） |
| `title`              | 是     | 视频标题                                                                                                                                 |
| `description`        | 否     | 视频简介；抖音、快手、视频号会与标签拼接，小红书写入正文，哔哩哔哩写入简介控件                                                           |
| `shortTitle`         | 否     | 视频号短标题，建议 6 ～ 16 字；其他平台忽略                                                                                              |
| `phone`              | 二选一 | 账号手机号（与 GUI 账号树一致）；多平台时可作为默认值，单个平台对象内可覆盖                                                              |
| `partition`          | 二选一 | 完整 session，如 `persist:13800138000抖音`                                                                                               |
| `bt2`                | 否     | 旧兼容字段：视频号作为短标题，其他平台作为简介                                                                                           |
| `tags`               | 否     | 标签，支持空格 / 逗号分隔；HTTP 会按 GUI 批量发布习惯拆分                                                                                |
| `publishAt`          | 否     | 一次性定时发布，格式 `YYYY-MM-DD HH:mm:ss`（多平台时需全部一致）                                                                         |
| `creativeStatement`  | 否     | 全局创作声明，等同 GUI「批量设置」；详见 [docs/http-api.md](./docs/http-api.md)                                                          |
| `creativeStatements` | 否     | 按平台覆盖，如 `{ "dy": "ai_generated", "blbl": "fiction" }`                                                                             |

**响应体（JSON）**：

| 字段                             | 说明                                               |
| -------------------------------- | -------------------------------------------------- |
| `success`                        | 请求是否被接受；多平台表示已成功提交到发布队列     |
| `status`                         | 单平台为最终状态；多平台提交成功为 `submitted`     |
| `exitCode`                       | 单平台同 CLI；多平台提交成功为 `0`                 |
| `message`                        | 结果说明                                           |
| `total` / `succeeded` / `failed` | 多平台提交汇总；最终成功失败以 `pushData` 记录为准 |
| `results`                        | 多平台时各平台提交明细数组                         |
| `id`                             | 单平台时写入 `pushData` 的记录 id                  |
| `scheduled` / `publishAt`        | 定时发布时返回                                     |

**示例**：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "dy",
    "phone": "13800138000",
    "file": "/Users/me/video.mp4",
    "title": "我的视频标题",
    "tags": "减脂 健身"
  }'
```

远程视频 URL 示例：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "dy",
    "phone": "13800138000",
    "file": "https://example.com/video.mp4",
    "title": "我的视频标题"
  }'
```

多平台一次发布（同一视频顺序发布到抖音、视频号、快手；远程 URL 只下载一次）：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "file": "https://example.com/video.mp4",
    "title": "我的视频标题",
    "description": "视频简介",
    "shortTitle": "5公里新手挑战",
    "tags": "跑步 新手",
    "platforms": ["dy", "sph", "ks"]
  }'
```

多平台响应示例：

```json
{
  "success": true,
  "exitCode": 0,
  "status": "submitted",
  "message": "已提交 3 个平台发布",
  "total": 3,
  "succeeded": 0,
  "failed": 0,
  "results": [
    {
      "platform": "视频号",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    },
    {
      "platform": "抖音",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    },
    {
      "platform": "快手",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    }
  ]
}
```

成功响应示例（单平台）：

```json
{
  "success": true,
  "status": "success",
  "exitCode": 0,
  "id": "abc123",
  "publishAt": null,
  "scheduled": false,
  "message": "上传成功"
}
```

参数错误时返回 HTTP `400`；发布失败（如未登录）仍返回 HTTP `200`，但 `success: false`、`exitCode: 3`。服务已配置 CORS，浏览器或本机脚本均可调用。

## Contributors

- **核心维护**：[@hanliang97](https://github.com/hanliang97)
- **集成协作**：[OpenClaw](https://github.com/openclaw/openclaw)、[Hermes](https://github.com/NousResearch/hermes-agent) 等智能体 / 编排生态 — 本仓库顶部以 `openclaw-integrable` 注释示例地显式声明 CLI 入口；`cli login` / `cli publish` / `cli accounts` / `cli history` 的参数与退出码约定面向所有「外部命令型」AI 工具设计，任何遵循同样契约的平台（含自研调度器）都可直接接入，欢迎围绕 CLI 契约反馈与共建。
- **AI 协作声明**：部分 CLI 子命令（`cli accounts` / `cli history`）、skills 文档（`.cursor/skills/matrixmedia-cli-publish/`）以及 README 的 CLI 章节由 Anthropic Claude（通过 [Claude Code](https://claude.com/claude-code)）、OpenAI Codex（Codex CLI / Codex Cloud）、WorkBuddy、DeepSeek、GPT 等 AI 办公与编程工具辅助设计、实现与撰写；人类维护者负责需求决策、代码评审与合入。所有产出遵循本仓库的 [GPL-2.0-only](./LICENSE) 授权条款，不因 AI 参与而改变许可。

欢迎通过 Issue / PR 参与共建。

## 使用声明

1. 本项目仅用于合法合规的学习与效率提升场景，请严格遵守各平台服务协议与当地法律法规。
2. 请勿将本项目用于批量作弊、恶意营销、侵权搬运、刷量等违规用途，由此产生的风险与责任由使用者自行承担。
3. 涉及账号、Cookie、本地素材等敏感数据时，请妥善保管并自行评估安全风险。
4. 部分平台可能需要人工参与（例如手动上传封面），请以平台当前页面规则为准。

## 开发环境 node 20

##### 使用 yarn 安装

yarn

##### 启动之后，会在 9080 端口监听

yarn dev

##### build 命令在不同系统环境中，需要的的不一样，需要自己根据自身环境进行配置

yarn build

## Star History

<a href="https://www.star-history.com/?repos=hanliang97%2FMatrixMedia&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=hanliang97/MatrixMedia&type=date&theme=dark&legend=top-left&sealed_token=e4cVgVwtHcXivuAHq9wCjXaykvJCKDP73Jp_s71S9xmzZxi2iD9fdkwdL6977hG7j9rRqLDQH25TwiZhydVJrXHmm-et_8ul06SVXS2vZoQoUYJcKcrRiw" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=hanliang97/MatrixMedia&type=date&legend=top-left&sealed_token=e4cVgVwtHcXivuAHq9wCjXaykvJCKDP73Jp_s71S9xmzZxi2iD9fdkwdL6977hG7j9rRqLDQH25TwiZhydVJrXHmm-et_8ul06SVXS2vZoQoUYJcKcrRiw" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=hanliang97/MatrixMedia&type=date&legend=top-left&sealed_token=e4cVgVwtHcXivuAHq9wCjXaykvJCKDP73Jp_s71S9xmzZxi2iD9fdkwdL6977hG7j9rRqLDQH25TwiZhydVJrXHmm-et_8ul06SVXS2vZoQoUYJcKcrRiw" />
 </picture>
</a>

