Posty: Social Media Scheduler

与 AI Agent 配合使用

此软件包包含面向 Agent 编写的完整命令参考 SKILL.md。安装后，将它展示给 Agent，它就能直接使用整个 CLI，无需进一步说明。

此仓库附带两个有意分开维护的 Claude Code 插件：

• posty，用于对话的 MCP 连接器（Claude app、Cowork、Claude Code）。通过浏览器登录，无需密钥；它使用 Posty 的 MCP 工具，不会在你的机器上安装任何内容。
• posty-cli，命令行工具及其完整参考，面向编码 Agent（Claude Code、Codex、OpenClaw、Hermes），适用于以终端作为工作界面的场景。

claude plugin marketplace add norbertlevente/posty-agent
claude plugin install posty@posty-agent        # MCP, for conversation
claude plugin install posty-cli@posty-agent    # CLI, for the terminal and scripts

在 ChatGPT 中，同一个 MCP 服务就是官方插件：https://posty.hu/ai/chatgpt

---

Posty CLI

从命令行或 AI Agent 安排社交媒体发布。

Posty 是一款社交媒体排期工具，而 CLI 是它的命令行界面。它使用与 Web 应用相同的公共 API：你在这里安排的内容会显示在 Posty 日历中，你在那里安排的内容也能在这里查看。

Posty 刻意不内置 AI 写作工具。你已经为优质模型付费；使用 CLI，模型可以直接在你的日历中工作，这样你就不必在两个窗口之间复制内容。SKILL.md 是为 AI Agent 编写的。将它展示给 Claude、ChatGPT、Codex、Muse、OpenClaw 或 Hermes，它们就能直接使用整个 CLI，无需进一步说明。

命令、标志和输出特意使用英文：命令行面向开发者和 Agent。产品本身在应用中仍使用匈牙利语。

安装

npm install -g posty-cli
# or
pnpm install -g posty-cli

软件包名是 posty-cli，命令名是 posty。 这两个名称有意不同。npm 上的裸名称 posty 已属于另一个无关项目，因此 npm install -g posty 会悄悄安装别人的软件包。

身份验证

选项 1：OAuth2（推荐）

posty auth:login     # device flow, opens a browser
posty auth:status    # checks the credential; a valid key whose workspace has no plan yet is reported as such, not as invalid
posty auth:logout    # deletes stored credentials

CLI 会将凭据存储在 ~/.posty/credentials.json 中，文件权限为 0600，所在目录权限为 0700。该文件与设置分开，因此 logout 会清除密钥，但保留你的配置。

选项 2：API 密钥 — 适用于服务端、CI 或 Agent：

export POSTY_API_KEY=your_api_key   # Settings → Developers, in the web app

还没有账户？可在终端中创建

posty auth:signup --email [email protected]            # e-mails a code, asks for it and for the terms
posty auth:signup --email [email protected] --code 123456 --accept-terms --workspace-name "Anna Kávézó"

Posty 会向该地址发送一个六位数验证码；由本人读给你听（或在提示处输入）。本人必须同意条款（https://posty.hu/aszf）和隐私声明（https://posty.hu/adatvedelem）：`--accept-terms` 表示本人已同意，否则命令会在终端中询问。新账户的完整工作区密钥会像 auth:login 存储密钥一样保存，且绝不会打印出来。通过此方式创建的账户没有免费试用期：在本人付费之前，只有 billing:* 命令可用，因此下一步是运行 posty billing:plans 和 posty billing:subscribe。如果该地址已有账户，系统会拒绝创建（请使用 posty auth:login 登录）。在非终端环境中，首次运行只会发送验证码，并打印下一步要运行的命令，其中包含首次运行时的所有选项（--api-url、--language、--workspace-name、--timezone）。时区默认采用 config:set 保存的时区，否则采用此机器自身的时区。付款后，只有在具备 API 访问权限的套餐（billing:plans 中的 apiAndMcpAccess: true）上，密钥才能用于所有命令；Alap 没有此权限，因此在本人选择该套餐前请说明这一点。--workspace 仍是全局工作区 ID 标志；新工作区的名称使用 --workspace-name。

工作区

一个凭据可以访问一个或多个工作区（在批准页面勾选 “All my workspaces”，或在 Settings 中创建多工作区密钥）。频道 ID 属于某个工作区，因此 CLI 必须知道你指的是哪个工作区：

posty workspaces:list          # what this credential can act on; "current" marks the active one
posty workspaces:use <id>      # every following command acts on that workspace
posty workspaces:current       # the one commands act on now
posty posts:list --workspace <id>   # one command in another workspace

如果密钥关联了多个工作区，auth:login 会询问要使用哪个工作区。所选工作区会与登录信息一起保存（如果使用环境变量密钥，则保存在 ~/.posty/config.json 中）；POSTY_WORKSPACE 和 --workspace 可分别为一个 shell 或一条命令指定工作区。多工作区密钥若未指定工作区，API 会对除 workspaces:list 以外的所有路由返回 403 拒绝请求，因此绝不会把内容发布到猜测的工作区。

命令

发现频道

posty integrations:list                      # connected channels and their ids
posty integrations:list --group <group-id>   # one customer's channels
posty integrations:groups                    # groups (customers)
posty integrations:settings <id>             # settings schema, rules, character limit
posty integrations:trigger <id> <method>     # channel-specific lookup

创建帖子

# Simple scheduled post
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id>"

# Draft
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -t draft -i "<id>"

# Publish now (no date needed)
posty posts:create -c "Content" -t now -i "<id>"

# With media — upload the file first
IMG=$(posty upload photo.jpg | jq -r '.path')
posty posts:create -c "Content" -m "$IMG" --date "2026-12-31T12:00:00Z" -i "<id>"

# Several channels at once
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id1>,<id2>"

# With channel-specific settings
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" \
  --settings '{"who_can_reply_post":"everyone"}' -i "<x-id>"

# Complex post from JSON
posty posts:create --json post.json

每次执行 posts:create 都会发送一个 Idempotency-Key（每次运行生成一个新的 UUID）。网络故障或收到 5xx 响应后，命令会使用相同的键重试一次，因此服务器会返回已创建的帖子，而不是再创建一条。再次运行命令会创建新帖子：发生错误后，请先检查 posts:list。

管理帖子

posty posts:list                                   # default -30 … +30 days
posty posts:list --startDate "..." --endDate "..." # a given range
posty posts:delete <id>                            # delete one post (one channel)
posty posts:delete-group <group>                   # delete every channel of a group
posty posts:status <id> --status draft             # back to draft
posty posts:status <id> --status schedule          # queue a draft
posty posts:find-slot <id>                         # next free slot

分析

posty analytics:platform <integration-id>        # channel, 7 days
posty analytics:platform <integration-id> -d 30  # channel, 30 days
posty analytics:post <post-id>                   # post, 7 days

如果 analytics:post 返回 {"missing": true}，说明帖子已发布，但平台未返回可用 ID。此时：

posty posts:missing <post-id>                     # available content from the provider
posty posts:connect <post-id> --release-id "<id>" # connect it
posty analytics:post <post-id>                    # works now

媒体

posty upload file.jpg

对于 -m，只能传入 posty upload 返回的路径。 裸文件名（photo.jpg）和外部 URL（https://...）都不起作用，因为平台只接受 Posty 提供的地址。

设置

posty config:set timezone Europe/Budapest
posty config:get
posty workspaces:use <id>          # see "Workspaces" above

FotoAI 图片和视频

使用密钥所有者自己的 FotoAI 账户和积分（fotoai.hu），生成的图片和视频会保存到工作区的媒体库中，可直接用于 posts:create。用户只需在 Posty 中连接一次 FotoAI（/integraciok/fotoai）；如果尚未连接，命令会显示该链接。密钥需要 media:write 权限。

posty fotoai:status                                              # connected?, as whom, credit balance, connectUrl
posty fotoai:models --category image                             # models, parameters (aspect, resolution, duration), base price
posty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5              # the price only; nothing is spent
posty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5 --yes --wait 60  # generate; prints media[].path
posty fotoai:get <id> --wait 60                                  # status, and the outputs saved in the media library

fotoai:generate 只有在使用 --yes 时才会消耗积分，且消耗的积分绝不会超过刚刚报价的价格（FotoAI 会返回 PRICE_CHANGED）。生成失败不会产生费用。fotoai:get 还可以导入在 fotoai.hu 上直接生成的内容；重复导入会返回同一媒体。

订阅

Agent 可以帮助用户从“帮我订阅 Pro 年度计划”开始，完成订阅并使其生效。唯一需要用户亲自完成的步骤是在 Stripe Checkout 中付款，并使用用户自己的 Link 钱包或银行卡。

posty billing:plans                                       # the four plans, prices in HUF, limits, trial rule, current tier
posty billing:subscribe --tier pro --period yearly        # a Stripe Checkout link as JSON; nothing is charged
posty billing:subscribe --tier pro --period yearly --open # same, and open it in this machine's browser
posty billing:status                                      # none | trialing | active | past_due | read_only | cancelled, plus any unpaid checkout (plan, start time, expiry)
posty billing:manage                                      # a link to the Stripe billing portal (plan change, cancel, invoices, card)

切勿使用一次性银行卡或由 Agent 提供的银行卡付款。 Posty 订阅按月或按年续费；一次性银行卡会在首次续费时失效，导致计划终止。将链接发给订阅者，让其完成付款，然后运行 posty billing:status 确认后再继续设置。

billing:subscribe 和 billing:manage 需要完整工作区密钥（在 posty auth:login 批准页面勾选 “the whole workspace”）或 OAuth 令牌；令牌必须由为工作区付款的人持有（如果目前还没有人付款，则由工作区所有者持有）。使用受限密钥时，命令会拒绝请求并说明原因。即使工作区尚未拥有可访问 API 的计划，这四条命令也都能使用：它们正是获取该计划的途径。

特定频道的设置

确切的架构始终以 posty integrations:settings <id> 显示的内容为准。 简而言之：

X（Twitter）— x

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" \
  --settings '{"who_can_reply_post":"everyone"}' -i "<x-id>"

who_can_reply_post 为必填项。可选值：everyone、following、mentionedUsers、subscribers、verified。

Facebook — facebook

IMG=$(posty upload photo.jpg | jq -r '.path')
posty posts:create -c "Content" -m "$IMG" --date "2026-12-31T12:00:00Z" \
  --settings '{"post_type":"post"}' -i "<facebook-id>"

post_type：post 或 story。你可以发布到公共主页，但不能发布到个人主页。

Instagram — instagram

IMG=$(posty upload photo.jpg | jq -r '.path')
posty posts:create -c "Caption #hashtag" -m "$IMG" --date "2026-12-31T12:00:00Z" \
  --settings '{"post_type":"post"}' -i "<instagram-id>"

post_type 为必填项：post 或 story。

Threads — threads、Bluesky — bluesky

无设置。 省略 --settings 标志。

完整架构：PROVIDER_SETTINGS.md。

面向 AI Agent

发现。 不要让 Agent 猜测。integrations:list 会显示实际已连接的渠道，integrations:settings <id> 会显示已接受的设置。不在 integrations:list 中的渠道无法发布内容。

输出约定。 命令会以 JSON 格式将结果写入 stdout，并将状态行和错误写入 stderr。失败时会以非零代码退出：

posty integrations:list | jq -r '.[].id'

JSON 模式。 对于复杂的营销活动，请将帖子写入文件并通过 --json 传入。可在 examples/ 中查看可运行示例。

帖子串。 重复使用 -c 来构建帖子串：第一项是帖子，其余项是评论。每个 -m 都属于其前面的 -c：

posty posts:create \
  -c "First post"     -m "$(posty upload one.jpg | jq -r '.path')" \
  -c "Second post" \
  -c "Third post" -m "$(posty upload three.jpg | jq -r '.path')" \
  -d 2 \
  --date "2026-12-31T12:00:00Z" -i "<id>"

-d 的单位是分钟，不是秒。

常见工作流

在多个渠道开展营销活动，并为每个渠道使用不同文案——将内容写入 JSON 文件并通过 --json 传入；参见 examples/multi-platform-with-settings.json。

通过脚本安排每周发布：

DATES=("2026-09-01T09:00:00Z" "2026-09-02T09:00:00Z" "2026-09-03T09:00:00Z")
TEXTS=("Monday kickoff" "Tuesday tip" "Wednesday takeaway")

for i in "${!DATES[@]}"; do
  posty posts:create -c "${TEXTS[$i]}" --date "${DATES[$i]}" -i "<id>"
done

发布前检查字符数限制：

MAX=$(posty integrations:settings "<id>" | jq '.output.maxLength')

环境变量

变量	必需	默认值	用途
POSTY_API_KEY	否	—	使用 API 密钥代替 auth:login
POSTY_API_URL	否	https://posty.hu/api	覆盖 API 端点
POSTY_TIMEZONE	否	—	为没有时区偏移的日期时间指定 IANA 时区
POSTY_WORKSPACE	否	—	适用于跨多个工作区的密钥的工作区 ID（参见 workspaces:use）
POSTY_AUTH_SERVER	否	https://posty.hu	OAuth2 服务（自托管）
POSTY_CLIENT_NAME	否	posty-cli	设备授权时显示的客户端名称

日期和时区

单独的 "2026-12-31 12:00" 存在歧义。CLI 会直接报错，而不是悄悄提前或延后一小时发布。它按以下顺序查找时区：

1. 日期中明确指定的偏移量——2026-12-31T12:00:00Z 或 +01:00
2. --timezone Europe/Budapest
3. POSTY_TIMEZONE
4. posty config:set timezone Europe/Budapest

如果以上均未设置，命令就会报错，并列出全部四种解决方法。时区值不能是数字偏移量。

错误处理

CLI 会将所有错误写入 stderr，并以非零代码退出。stdout 始终保持干净且便于机器读取。

错误	含义
--date is required...	安排发布时间需要指定日期，或使用 -t now
--integrations is required...	未指定渠道；运行 integrations:list
naive date error	未设置任何时区；见上文
Integration not found	ID 错误，或该渠道已断开连接
401 "no plan with API access"	密钥有效；工作区需要订阅套餐：billing:plans、billing:subscribe
403 "missing the required permission"	密钥有效，但缺少所需权限范围；请创建具有该权限范围的密钥。重新登录无济于事
其他 401 / 403	授权已过期或撤销；运行 posty auth:login

开发

src/
├── index.ts        # commands and flags (yargs)
├── api.ts          # HTTP client
├── commands/       # posts, integrations, analytics, upload, auth, config
├── dates.ts        # timezone resolution
├── settings.ts     # channel settings
└── output.ts       # the JSON/stderr output contract

git clone https://github.com/norbertlevente/posty-agent.git
cd posty-agent
pnpm install
pnpm run build          # tsup → dist/index.js
node dist/index.js --help

脚本	功能
pnpm run build	编译到 dist/
pnpm run dev	监视并重新编译
pnpm run release:check	检查软件包和发布流程（不会发布）

快速参考

# Authentication
posty auth:status
posty auth:login
posty auth:signup --email <address>
posty auth:logout

# Workspaces
posty workspaces:list
posty workspaces:use <id>

# Discovery
posty integrations:list
posty integrations:settings <id>
posty integrations:trigger <id> <method>

# Posting
posty posts:create -c "text" --date "2026-12-31T12:00:00Z" -i "<id>"
posty posts:create -c "text" -t draft --date "..." -i "<id>"
posty posts:create -c "text" -t now -i "<id>"
posty posts:create --json file.json

# Management
posty posts:list
posty posts:delete <id>
posty posts:delete-group <group>
posty posts:status <id> --status draft
posty posts:find-slot <id>
posty upload <file>
posty upload:link
posty upload:files <id>

# Analytics
posty analytics:platform <id> -d 30
posty analytics:post <id>
posty posts:missing <id>
posty posts:connect <id> --release-id "<rid>"

# Subscription (the person pays in Stripe Checkout; never with an agent card)
posty billing:plans
posty billing:subscribe --tier pro --period yearly
posty billing:status
posty billing:manage

文件不在这台机器上时

posty upload 会从磁盘上传文件。如果图片或视频在手机上，或者运行 CLI 的 Agent 无法访问你的文件系统，请生成上传链接：

posty upload:link            # {id, url, expiresAt}
# open the url anywhere (it works signed out), drop the files on it
posty upload:files <id>      # {status, count, files:[{id, name, path, type}]}

每项的 path 都要传给 posts:create -m。链接有效期为两小时，可接受多个文件，并且只能将文件上传到创建该链接时指定的工作区。

文档

• SKILL.md — 面向 AI Agent 编写的完整命令参考
• HOW_TO_RUN.md — 从源代码安装和运行
• PROVIDER_SETTINGS.md — 各渠道的设置架构
• SUPPORTED_FILE_TYPES.md — 支持的媒体类型

支持的渠道

渠道	identifier	设置
X（Twitter）	x	必须设置 who_can_reply_post
Facebook（Pages）	facebook	post_type
Instagram	instagram	必须设置 post_type
LinkedIn	linkedin	无需设置
TikTok	tiktok	必须设置 privacy_level、content_posting_method
YouTube	youtube	必须设置 title、type
Threads	threads	无
Bluesky	bluesky	无
Telegram	telegram	无
Discord	discord	必须设置 channel（来自 channels 工具）
Slack	slack	必须设置 channel（来自 channels 工具）

integrations:list 会显示你实际可以使用哪些渠道。表格列出的是 Posty 支持的渠道，命令输出则列出你已连接的渠道。

参与贡献

1. Fork 项目
2. 创建分支（git checkout -b feature/something）
3. 构建并试用：pnpm run build && node dist/index.js --help
4. 提交拉取请求

链接

• 网站：posty.hu
• npm：posty-cli
• GitHub：norbertlevente/posty-agent

许可证

AGPL-3.0，详见 LICENSE 文件。

© 2026 Kiss Industries