Social Post Flow

Social Post Flow CLI

面向 AI Agent 的社交媒体自动化工具——以编程方式在 12+ 个社交网络上安排帖子。

这是一个零依赖的 Node.js CLI 封装，用于调用 Social Post Flow API。专为 AI Agent（Claude Code、Cursor、Windsurf、Codex、OpenAI SDK）以及 Shell 脚本 / CI 工作流设计。

**支持：**Facebook、X (Twitter)、LinkedIn、Instagram（Feed + Stories）、Threads、Pinterest、TikTok、Mastodon、Bluesky、Telegram、Google Business Profiles 等。

---

选择安装方式

使用场景	选择
Claude Code	插件（参见下文的 作为 Claude Code 插件安装）——已预先配置 MCP 服务
Claude Desktop、ChatGPT Desktop	MCP 服务（一键连接，无需设置）
Cursor、Codex、Warp、Cline、OpenCode 和其他 Agent	技能（参见下文的 作为技能安装）
Shell 脚本、CI/CD、自有工具	CLI（参见下文的 作为 CLI 安装）

你可以同时使用技能和 CLI。技能会教 Agent 如何使用 Social Post Flow；CLI 则是 Agent 实际运行的工具。

作为 Claude Code 插件安装

该插件将 MCP 服务配置和 Claude 原生技能打包在一起，只需安装一次：

/plugin marketplace add socialpostflow/claude-marketplace
/plugin install socialpostflow@socialpostflow

或者，在社区市场批准后：

/plugin marketplace add anthropics/claude-plugins-community
/plugin install socialpostflow@claude-community

首次使用时，Claude Code 会打开浏览器，让你使用 Social Post Flow 账户登录并批准访问——无需个人访问令牌。

**注意：**如果安装了该插件，请勿再在 Claude Desktop 设置中手动添加 MCP 服务——否则会重复注册同一个端点。请选择其中一种方式。

作为技能安装

将 Social Post Flow 技能添加到 Agent，使其能够用自然语言撰写和安排帖子。这是由 CLI 驱动的技能（Agent 会通过 Shell 调用 spf）。Claude Code 用户应改为安装上面的插件——它使用 MCP 服务，无需 CLI。

单命令安装（适用于任何会读取 ~/.claude/skills/ 的 Agent）：

mkdir -p ~/.claude/skills/socialpostflow && \
  curl -L https://raw.githubusercontent.com/socialpostflow/socialpostflow-cli/main/agent-skill/socialpostflow/SKILL.md \
    -o ~/.claude/skills/socialpostflow/SKILL.md

多 Agent 安装（Cursor、Codex、Warp、Cline、OpenCode 等）：

npx skills add socialpostflow/socialpostflow-cli

出现提示时，选择要为其安装的 Agent。

然后可以向 Agent 提出如下请求：

“将这段文字发布到我的 X 和 LinkedIn 账户。”

“安排下周一上午 9 点发布一条激励帖。”

“将这三篇博客推广内容排入我所有渠道的队列。”

Agent 会从 agent-skill/socialpostflow/SKILL.md 学习，该文件介绍了帖子类型、安排发布的方式和常见工作流。

作为 CLI 安装

通过 npm 全局安装：

npm install -g socialpostflow-cli

也可以通过 npx 直接运行，无需安装：

npx socialpostflow-cli --help

或者克隆代码库并直接运行脚本（零依赖）：

git clone https://github.com/socialpostflow/socialpostflow-cli.git
cd socialpostflow-cli
node scripts/socialpostflow.js --help

需要 Node.js 18 或更高版本（以使用内置的 fetch）。

身份验证

你需要一个已开通 API 访问权限的 Social Post Flow 账户。从个人资料页面获取个人访问令牌，然后：

spf setup --key spf_xxxxxxxxxxxxxxxx

此操作会通过 API 验证令牌，并将其保存到 ~/.socialpostflow/credentials.json（权限设为 chmod 600）。

或者，设置环境变量：

export SOCIALPOSTFLOW_API_TOKEN=spf_xxxxxxxxxxxxxxxx

快速开始

# List your connected social profiles
spf profiles

# Post to one profile, immediately
spf post -c "Hello world!" -i 42

# Post to multiple profiles
spf post -c "Big announcement coming soon" -i 42,87,103

# Schedule for a specific time
spf post -c "Happy Monday!" -i 42 --schedule-type scheduled -s "2026-07-20T09:00:00Z"

# Add to the user's queue (uses their configured queue interval)
spf post -c "Quick tip..." -i 42 --schedule-type queue_end

# List recent posts
spf posts --status posted --order-by posted_at --order desc

# Delete a scheduled post
spf delete 12345

命令

命令	说明
spf setup --key <token>	验证并保存个人访问令牌。
spf whoami	显示已认证用户的个人资料、订阅状态和统计数据。
spf profiles [--post-type T]	列出已连接的社交媒体个人资料。可按帖子类型筛选。
spf posts [--status S] [--profile-id N]	列出帖子。可按状态或个人资料筛选。
spf post -c "..." -i id1,id2 [options]	创建帖子（参见下方选项）。
spf show <post-id>	显示单个帖子的详情。
spf delete <post-id>	删除帖子。如果帖子已排期，则会停止发布。

spf post 选项

标志	说明
-c, --content	帖子文本。除非 --type story，否则必填。
-i, --profile-ids	以逗号分隔的个人资料 ID（必填）。
-t, --type	帖子类型：text（默认）、link、image、story、pin、tiktok、google。
-m, --media	以逗号分隔的公开图片／视频 URL。
-u, --url	要附加的 URL（--type link 时必填）。
--first-comment	首条评论文本。Mastodon、TikTok、Telegram、Google 不支持。
--schedule-type	immediate（默认）、queue_end、queue_start、scheduled。
-s, --scheduled-at	ISO 8601 时间戳（--schedule-type=scheduled 时必填，且必须是未来时间）。

有关完整的帖子类型规则（每种类型的必需项和禁止项），请参阅 agent-skill/socialpostflow/SKILL.md。

所有输出均为 JSON

每条命令都会将 JSON 写入 stdout。错误会以非零退出代码将 JSON 写入 stderr：

PROFILES=$(spf profiles)
TWITTER_ID=$(echo "$PROFILES" | jq -r '.data[] | select(.provider=="x") | .id')

spf post -c "Hello from a shell script" -i "$TWITTER_ID"

环境变量

变量	默认值	说明
SOCIALPOSTFLOW_API_TOKEN	—	你的 API 令牌。可替代 spf setup。
SOCIALPOSTFLOW_API_URL	https://app.socialpostflow.com/api	覆盖 API 基础 URL（适用于测试）。

示例

请参阅 examples/，其中包含演示常见工作流的 shell 脚本：

• post-everywhere.sh — 将相同内容发布到所有已连接且支持文本的个人资料
• schedule-week.sh — 使用队列安排一周的帖子
• github-actions.yml — 通过 GitHub Action 发布博客文章公告

故障排除

“未通过身份验证” — 运行 spf setup --key <token>，或设置 SOCIALPOSTFLOW_API_TOKEN。

“API 返回 HTTP 401” — 你的令牌无效。请从 https://app.socialpostflow.com/profile 获取有效令牌。

“API 返回 HTTP 422” — 验证错误。details 载荷会指出哪个字段验证失败。常见原因：post_type／schedule_type 组合无效、排期时间已过去、图片／story／pin／tiktok 帖子缺少必需的 media_urls。

“API 返回 HTTP 429” — 该个人资料已达到每日发帖上限。用户需要等待或升级套餐。

许可证

MIT — 参见 LICENSE。

链接

• Social Post Flow： socialpostflow.com
• API 文档： socialpostflow.com/documentation/api
• MCP 文档： socialpostflow.com/documentation/mcp
• WordPress 插件： wordpress.org/plugins/social-post-flow
• 问题／反馈： github.com/socialpostflow/socialpostflow-cli/issues