⌨️ PostBot CLI 工具

PostBot CLI 是 PostBot 内容同步助手 的官方命令行工具，一款命令行下的多平台内容同步、任务流程管理效率工具。支持内容快捷同步发布、批量同步发布、任务管理、工作流编排，无缝对接 PostBot / Postar 平台。

NOTE

本文对应 PostBot CLI v1.1.0。当前为快速迭代开发版，适用于开发者与 CI/CD 场景。
如需浏览器扩展或桌面端，请访问 PostBot 内容同步助手。

✨ 特性与适用场景

多平台发布：一次请求写入多个目标平台，由引擎为每个平台创建发布 Job。
多种内容类型：文章、动态、视频、音频。
定时与草稿：支持本地时间、ISO 8601、秒/毫秒时间戳；--draft 仅保存草稿。
发布前预检：校验平台字典、账号与在线桌面端，避免“保存成功但没有 Job”。
批量发布：从 JSON 文件批量创建任务，支持 dry-run、fail-fast 与相对内容文件。
任务与 Job 管理：任务 CRUD、绑定内容 ID、触发自动发布、查询 Job 与执行日志。
账号 / 客户端 / 会话：管理媒体账号、浏览器指纹、扩展/桌面客户端与只读 SessionBot 会话。
脚本友好：--json 输出、明确退出码，全局选项可放在子命令之后。
双模式：通过 --app 在 PostBot（国内版）与 Postar（国际版）之间切换。

📦 安装

一键安装（自动检测 Node.js 环境，通过 npm 全局安装）：

bash

curl -fsSL https://raw.githubusercontent.com/gitcoffee-os/postbot-cli/main/install.sh | bash

安装指定版本：

bash

curl -fsSL https://raw.githubusercontent.com/gitcoffee-os/postbot-cli/main/install.sh | bash -s -- --version 1.1.0

或直接使用 npm / pnpm：

bash

npm install -g @gitcoffee-os/postbot-cli
pnpm add -g @gitcoffee-os/postbot-cli

要求 Node.js >= 18。安装脚本会检测 Node 版本；若 npm 全局目录无写权限，自动改用 ~/.postbot 作为用户级安装目录并提示 PATH 配置。

验证安装

bash

postbot --version

🚀 快速开始

bash

# 1. 配置开发者凭证（可选；不配置则使用直接登录）
postbot config --client-id <id> --client-secret <secret>

# 2. 登录
postbot login

# 3. 查看当前用户
postbot whoami

# 4. 检查引擎平台字典与账号
postbot platform list
postbot account list

# 5. 发布
postbot publish \
  --platforms weixin,xiaohongshu \
  --content-file ./content.json

content.json 示例：

json

{
  "title": "一篇来自 CLI 的文章",
  "content": "<h2>Hello</h2><p>这是正文。</p>",
  "cover": "https://cdn.example.com/cover.jpg",
  "images": ["https://cdn.example.com/1.jpg"]
}

发布成功后，CLI 会打印任务 ID。使用 postbot status <taskId> 查看聚合状态、最新 Job 与最近日志。

⚙️ 配置

配置文件默认位于 ~/.config/postbot-cli/config.json，用于存储开发者凭证、登录 token、IAM 地址与默认应用。

bash

# 查看当前配置
postbot config --show

# 设置 OAuth2 凭证
postbot config --client-id <id> --client-secret <secret>

# 自定义 IAM 地址
postbot config --iam-base-url https://custom-iam.example.com

# 设置默认应用
postbot config --default-app postar

选项	说明
`--show`	显示当前配置（默认行为）
`--client-id <id>`	设置 OAuth2 client ID
`--client-secret <secret>`	设置 OAuth2 client secret
`--iam-base-url <url>`	设置 IAM 地址
`--default-app <postbot\|postar>`	设置默认应用
`--show-secret`	显示完整 client secret（默认打码）

环境变量

变量	作用
`POSTBOT_BASE_URL` / `POSTAR_BASE_URL`	应用站点地址（直接登录使用）
`POSTBOT_API_URL` / `POSTAR_API_URL`	引擎 API 根地址，需包含 `/exmay/authority/api`
`POSTBOT_APP_ID` / `POSTAR_APP_ID`	`App-Id` 请求头
`POSTBOT_PROXY_APP_ID` / `POSTAR_PROXY_APP_ID`	代理登录使用的 appId

环境变量在进程启动时读取，优先级高于内置默认值。

📋 命令总览

命令	作用
`postbot login` / `register` / `logout` / `whoami`	登录、注册、退出、当前用户
`postbot forgot-password`	重置密码
`postbot config`	查看或修改 CLI 配置
`postbot publish`（`pub`）	创建并自动发布任务
`postbot batch-publish`	从 JSON 批量创建任务
`postbot status <taskId>`	聚合任务状态 + 最新 Job + 最近日志
`postbot task list/get/save/update/delete`	任务 CRUD
`postbot task batch-delete`	批量删除任务
`postbot task bind-content`	幂等绑定上游内容 ID
`postbot autopublish trigger/status/jobs/log`	自动发布触发、Job、日志
`postbot logs`	`autopublish log` 快捷方式
`postbot platform list/get`	平台字典
`postbot account ...`（`acc`）	账号 CRUD、浏览器指纹
`postbot client ...`	扩展/桌面/云端客户端
`postbot session list/get`	SessionBot 会话（只读）
`postbot notify`	发送通用通知
`postbot workflow list/execute/status/retry`	工作流

全局选项 --app、--json、--verbose、--yes 可以写在子命令之后：

bash

postbot task list --status FAILED --json
postbot platform list --app postar --json

完整选项见 CLI 命令参考。

📤 发布内容

多平台立即发布

bash

postbot publish \
  --platforms weixin,xiaohongshu,douyin \
  --type article \
  --name "多平台文章" \
  --content-file ./content.json

--platforms 支持逗号、中文逗号或空格分隔。目标平台以 postbot platform list 返回的引擎字典为准。

平台别名会自动转换：

标准码	别名	平台
`xiaohongshu`	`xhs`	小红书
`weixin_channels`	`channels`、`wechat_channels`	视频号
`weixin`	`weixinmp`、`wechat_mp`	公众号
`xianyu`	`goofish`、`idlefish`	闲鱼

常用发布选项

选项	说明
`--name <name>`	任务名称，默认取内容标题
`--type <type>`	`article` / `moment` / `video` / `audio`，默认 `article`
`--platforms <codes>`	目标平台，逗号分隔
`--account <username>` / `--account-id <id>`	主账号元数据；引擎仍按目标平台自动选账号
`--client <client>`	客户端 `id` / `name` / `clientKey`
`--channel <channel>`	发布通道，默认 `CLOUD`
`--content-file <path>`	内容 JSON 文件
`--content <json>`	内联内容 JSON
`--title <title>`	覆盖内容标题
`--scheduled-at <datetime>`	定时发布时间
`--max-retries <count>`	最大重试次数
`--content-id <id>`	上游内容 ID
`--config <json>`	任务扩展配置
`--draft`	仅保存草稿，不自动发布
`--allow-missing-accounts`	跳过账号预检（不推荐）
`--wait` / `--timeout <seconds>` / `--interval <seconds>`	等待发布结束、超时时间与轮询间隔

定时发布

bash

postbot publish \
  --platforms weixin \
  --content-file ./content.json \
  --scheduled-at "2026-09-01 09:00:00"

postbot publish \
  --platforms xhs \
  --content-file ./note.json \
  --scheduled-at "2026-09-01T09:00:00+08:00"

支持的时间格式：

输入	处理结果
`2026-09-01 09:30:00`	`2026-09-01 09:30:00`
`2026-09-01T09:30:00`	`2026-09-01 09:30:00`
`2026-09-01 09:30`	`2026-09-01 09:30:00`
`2026-09-01`	`2026-09-01 00:00:00`
13 位毫秒时间戳	原样传给引擎
10 位秒时间戳	自动转换为毫秒
带时区的 ISO 8601	转换为本地时间

已过去的时间不会报错，引擎会尽快执行，CLI 会给出警告。

草稿

bash

postbot publish --platforms weixin --draft --content-file ./content.json

草稿不会创建发布 Job，也不受“目标平台必须有账号”的限制。

指定发布通道

bash

# 云端 Worker（默认）
postbot publish --platforms weixin --channel CLOUD --content-file ./content.json

# 浏览器扩展
postbot publish --platforms xhs --channel BROWSER_EXTENSION --content-file ./note.json

# 桌面端：自动选择唯一在线桌面端；多个时交互选择
postbot publish --platforms xhs --channel DESKTOP --content-file ./note.json

# 显式指定桌面端（ID / 名称 / clientKey）
postbot publish --platforms xhs --channel DESKTOP --client "MacBook" --content-file ./note.json

通道	说明
`CLOUD`	云端 Worker，默认通道
`BROWSER_EXTENSION`	已保存的浏览器扩展；可用 `--client` 指定，否则由扩展按通道认领
`BROWSER_EXTENSION_EPHEMERAL`	服务端临时浏览器，不接受客户端绑定
`DESKTOP`	桌面端，必须绑定在线桌面端客户端

--client 仅适用于 DESKTOP / BROWSER_EXTENSION。CLOUD / BROWSER_EXTENSION_EPHEMERAL 传入客户端会报错。

发布并等待

bash

postbot publish \
  --platforms weixin \
  --content-file ./content.json \
  --wait --timeout 600

--wait 会轮询任务状态，直到成功、失败或超时。适合 CI 中需要明确发布结果的场景。

保存任务但不发布

bash

postbot task save --platforms weixin --content-file ./content.json --draft

task save 与 publish 使用相同的参数；不传 --draft 时同样会自动发布。

发布前预检

CLI 在创建任务前会检查：

目标平台是否存在于引擎平台字典。
自动发布时，每个目标平台是否有可用账号。
DESKTOP 通道是否有在线桌面端。
视频/音频内容是否提供媒体地址。
内容类型与平台静态注册表是否匹配（不匹配只警告，最终以引擎发布器为准）。

如果出现“保存成功但没有 Job”，优先检查平台 code 是否为引擎标准码，以及 DESKTOP 是否绑定了在线桌面端。可运行 postbot platform list 与 postbot client list 排查。

🧾 内容格式

--content-file / --content 最终写入引擎任务的 data 字段。内容必须是 JSON 对象，不能是数组或纯字符串。

常用字段：

json

{
  "title": "标题",
  "content": "正文（HTML 或纯文本）",
  "description": "视频/音频描述",
  "images": ["https://cdn.example.com/1.jpg"],
  "cover": "https://cdn.example.com/cover.jpg",
  "videoData": {
    "objectUrl": "https://cdn.example.com/demo.mp4",
    "name": "demo.mp4",
    "type": "video/mp4"
  },
  "audioData": {
    "objectUrl": "https://cdn.example.com/ep1.mp3",
    "name": "ep1.mp3",
    "type": "audio/mpeg"
  }
}

内容类型	必填 / 建议字段
文章 `article`	`title` + `content`，可带 `cover` / `images`
动态 `moment`	`title` + `content` + `images`
视频 `video`	`title` + `description` + `videoData`
音频 `audio`	`title` + `description` + `audioData`

完整字段、各平台差异与定时规则见内容数据格式。

📦 批量发布

批量文件支持两种结构。

数组

json

[
  {
    "name": "任务 A",
    "type": "article",
    "platforms": ["weixin", "xhs"],
    "contentFile": "./a.json"
  },
  {
    "name": "任务 B",
    "type": "moment",
    "platforms": "weibo",
    "content": {
      "title": "B",
      "content": "正文"
    }
  }
]

带默认值

json

{
  "defaults": {
    "type": "article",
    "channel": "CLOUD"
  },
  "tasks": [
    {
      "name": "任务 A",
      "platforms": ["weixin", "xhs"],
      "contentFile": "./a.json"
    },
    {
      "name": "任务 B",
      "platforms": "weibo",
      "content": {
        "title": "B",
        "content": "正文"
      },
      "scheduledAt": "2026-09-01 09:00:00"
    }
  ]
}

bash

# 先检查组装结果，不保存
postbot batch-publish --file ./tasks.json --dry-run

# 正式发布；遇到第一个错误即停止
postbot batch-publish --file ./tasks.json --fail-fast

说明：

contentFile 的相对路径基于批量文件所在目录。
任务字段会覆盖 defaults 中的同名字段。
默认继续执行后续任务，最后汇总成功/失败数量；有失败时退出码为 1。
平台字段兼容 platforms / platformCodes / platformCode / platform。
内容字段兼容 content（对象或 JSON 字符串）/ contentFile。
定时字段兼容 scheduledAt / onlineTime。

🗂️ 任务、Job 与日志

bash

# 任务列表与本地筛选
postbot task list --status FAILED
postbot task list --platform xiaohongshu --search "文章"

# 任务详情
postbot task get 123

# 聚合状态（任务 + 最新 Job + 最近日志）
postbot status 123

# 手动触发自动发布（忽略定时时间）
postbot autopublish trigger 123

# 查看 Job 与执行日志
postbot autopublish jobs --task 123
postbot autopublish log --task 123 --full
postbot logs --task 123 --failed

# 更新任务（CLI 会 GET 合并后整体回传）
postbot task update 123 --title "新标题"

# 删除任务
postbot task delete 123 --force

任务更新注意事项

task update 会先读取任务，合并修改后整体回传，避免引擎把未传字段重置。
修改 --scheduled-at 不会重排已经创建的 Job；旧 Job 仍按原时间执行。需要立即执行可使用 postbot autopublish trigger <taskId>。
已绑定客户端的任务无法通过 /update 清空 mediaClientId；如需切换到 CLOUD / BROWSER_EXTENSION_EPHEMERAL，建议新建任务。
--draft 与 --auto-publish 不能同时使用。

状态与筛选

任务状态包括 DRAFT、PENDING、SCHEDULED、RUNNING、SUCCESS、FAILED_RETRYABLE、FAILED、CANCELLED。

task list 支持：

选项	说明
`--page <page>` / `--size <size>`	分页
`--status <status>`	按状态筛选
`--platform <code>`	按平台筛选
`--search <keyword>`	按名称或任务 ID 搜索
`--all`	返回全部任务

🤖 JSON 与自动化

bash

postbot whoami --json
postbot task list --status SUCCESS --json
postbot publish --platforms weixin --content-file ./content.json --wait --json
postbot batch-publish --file ./tasks.json --json

--json 时，提示信息写入 stderr，stdout 保持可解析。错误输出示例：

json

{
  "success": false,
  "error": {
    "message": "…",
    "code": "USER.NOT_FOUND",
    "kind": "user",
    "hint": "…"
  }
}

退出码：成功 0；参数、网络或业务错误为 1。删除类命令在非交互环境必须显式加 --yes 或 --force。

GitHub Actions 自动发布

yaml

name: Publish to PostBot

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @gitcoffee-os/postbot-cli
      - run: |
          postbot config \
            --client-id "${{ secrets.POSTBOT_CLIENT_ID }}" \
            --client-secret "${{ secrets.POSTBOT_CLIENT_SECRET }}"
      - run: |
          postbot login \
            --username "${{ secrets.POSTBOT_USERNAME }}" \
            --password "${{ secrets.POSTBOT_PASSWORD }}"
      - run: |
          postbot publish \
            --platforms weixin \
            --content-file ./release.json \
            --wait --json

非交互环境必须显式传入 --username / --password。建议在 CI 中使用 --json 与 --wait，便于根据退出码判断发布结果。

🌐 应用模式切换

所有命令支持 --app 参数切换应用模式：

bash

# 国际版（Postar）
postbot --app postar login

# 国内版（PostBot）
postbot --app postbot publish --platforms weixin --content-file ./content.json

也可以设置默认应用，之后无需每次传 --app：

bash

postbot config --default-app postar

postbot 与 postar 两个可执行文件等价，区别只是默认 --app：

bash

postar task list

🧩 平台与通道

发布平台以 postbot platform list 返回的引擎字典为准。常用平台包括：

weixin、xiaohongshu、weixin_channels、douyin、kuaishou、bilibili、zhihu、weibo、toutiao、baijiahao、jianshu、xianyu，以及 x、facebook、instagram、tiktok、youtube、linkedin、threads、bluesky 等。

若数据库平台字典仍使用 xhs / channels 等旧编号，保存后可能不创建 Job。先运行 postbot platform list 核对；详见 Engine API 对接。

❓ 常见问题

配置文件存储在哪里？

默认位于 ~/.config/postbot-cli/config.json，包含开发者凭证与登录 token。请勿将 token 提交到代码仓库。

如何切换国内版与国际版？

在所有命令前添加 --app postbot 或 --app postar，例如：

bash

postbot --app postar account list

也可以运行 postbot config --default-app postar 设置默认应用。

如何查询发布是否成功？

使用 postbot status <taskId> 查看任务、最新 Job 与最近日志，或使用 postbot task get <taskId> 查看任务详情。需要等待结果时，使用 postbot publish ... --wait。

常见错误排查

现象	处理
保存成功但没有 Job	检查平台 code 是否存在于引擎字典；`DESKTOP` 是否绑定在线桌面端
提示目标平台没有账号	先在客户端登录该平台账号；或使用 `--draft`
定时任务没按新时间执行	引擎不会重排已有 Job；新建任务或 `autopublish trigger`
`HTTP 502`	网关/引擎不可用，检查 API 地址与网络
登录已失效	重新执行 `postbot login`
发布成功但链接为空	部分发布器不返回链接；用 `postbot logs --task <id> --full` 查看详情

⌨️ PostBot CLI 工具 ​

✨ 特性与适用场景 ​

📦 安装 ​

验证安装 ​

🚀 快速开始 ​

⚙️ 配置 ​

环境变量 ​

📋 命令总览 ​

📤 发布内容 ​

多平台立即发布 ​

常用发布选项 ​

定时发布 ​

草稿 ​

指定发布通道 ​

发布并等待 ​

保存任务但不发布 ​

发布前预检 ​

🧾 内容格式 ​

📦 批量发布 ​

数组 ​

带默认值 ​

🗂️ 任务、Job 与日志 ​

任务更新注意事项 ​

状态与筛选 ​

🤖 JSON 与自动化 ​

GitHub Actions 自动发布 ​

🌐 应用模式切换 ​

🧩 平台与通道 ​

❓ 常见问题 ​

配置文件存储在哪里？ ​

如何切换国内版与国际版？ ​

如何查询发布是否成功？ ​

常见错误排查 ​

📚 更多资源 ​

⌨️ PostBot CLI 工具

✨ 特性与适用场景

📦 安装

验证安装

🚀 快速开始

⚙️ 配置

环境变量

📋 命令总览

📤 发布内容

多平台立即发布

常用发布选项

定时发布

草稿

指定发布通道

发布并等待

保存任务但不发布

发布前预检

🧾 内容格式

📦 批量发布

数组

带默认值

🗂️ 任务、Job 与日志

任务更新注意事项

状态与筛选

🤖 JSON 与自动化

GitHub Actions 自动发布

🌐 应用模式切换

🧩 平台与通道

❓ 常见问题

配置文件存储在哪里？

如何切换国内版与国际版？

如何查询发布是否成功？

常见错误排查

📚 更多资源