名称： postiz
描述： Postiz 是一款用于在 28+ 个社交媒体和聊天渠道上安排发布内容的工具，支持 X、LinkedIn、LinkedIn Page、Reddit、Instagram、Facebook Page、Threads、YouTube、Google My Business、TikTok、Pinterest、Dribbble、Discord、Slack、Kick、Twitch、Mastodon、Bluesky、Lemmy、Farcaster、Telegram、Nostr、VK、Medium、Dev.to、Hashnode、WordPress、ListMonk。
主页： https://docs.postiz.com/public-api/introduction
元数据： {"clawdbot":{"emoji":"🌎","requires":{"bins":[],"env":["POSTIZ_API_URL","POSTIZ_API_KEY"]}}}

安装 Postiz（如果尚未安装）

npm install -g postiz
# 或
pnpm install -g postiz

npm 发布页：https://www.npmjs.com/package/postiz
Postiz GitHub：https://github.com/gitroomhq/postiz-app
Postiz CLI GitHub：https://github.com/gitroomhq/postiz-app
官方网站：https://postiz.com

核心工作流

使用 Postiz CLI 的基本模式：

1. 发现 - 列出集成并获取其设置
2. 获取 - 使用集成工具获取动态数据（如 Flairs、播放列表、公司信息）
3. 准备 - 如有需要，上传媒体文件
4. 发布 - 创建包含内容、媒体和平台特定设置的帖子
5. 分析 - 使用平台和帖子级别的分析跟踪性能
6. 解决 - 如果分析返回 {"missing": true}，运行 posts:missing 列出提供者内容，然后运行 posts:connect 进行关联

# 1. 发现
postiz integrations:list
postiz integrations:settings <integration-id>

# 2. 获取（如果需要）
postiz integrations:trigger <integration-id> <method> -d '{"key":"value"}'

# 3. 准备
postiz upload image.jpg

# 4. 发布
postiz posts:create -c "内容" -m "image.jpg" -i "<integration-id>"

# 5. 分析
postiz analytics:platform <integration-id> -d 30
postiz analytics:post <post-id> -d 7

# 6. 解决（如果分析返回 {"missing": true}）
postiz posts:missing <post-id>
postiz posts:connect <post-id> --release-id "<content-id>"

核心命令

设置

# 必需的环境变量
export POSTIZ_API_KEY=your_api_key_here

# 可选的自定义 API URL
export POSTIZ_API_URL=https://custom-api-url.com

集成发现

# 列出所有已连接的集成
postiz integrations:list

# 获取特定集成的设置模式
postiz integrations:settings <integration-id>

# 触发集成工具以获取动态数据
postiz integrations:trigger <integration-id> <method-name>
postiz integrations:trigger <integration-id> <method-name> -d '{"param":"value"}'

创建帖子

# 简单帖子（日期为必填项）
postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" -i "integration-id"

# 草稿帖子
postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"

# 带媒体的帖子
postiz posts:create -c "内容" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"

# 带评论的帖子（每条评论可包含自己的媒体）
postiz posts:create \
  -c "主帖" -m "main.jpg" \
  -c "第一条评论" -m "comment1.jpg" \
  -c "第二条评论" -m "comment2.jpg,comment3.jpg" \
  -s "2024-12-31T12:00:00Z" \
  -i "integration-id"

# 多平台帖子
postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"

# 平台特定设置
postiz posts:create \
  -c "内容" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"我的帖子","type":"text"}}]}' \
  -i "reddit-id"

# 从 JSON 文件创建复杂帖子
postiz posts:create --json post.json

管理帖子

# 列出帖子（默认：过去 30 天到未来 30 天）
postiz posts:list

# 按日期范围列出帖子
postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"

# 删除帖子
postiz posts:delete <post-id>

分析

# 获取平台分析（默认：最近 7 天）
postiz analytics:platform <integration-id>

# 获取平台最近 30 天的分析
postiz analytics:platform <integration-id> -d 30

# 获取帖子分析（默认：最近 7 天）
postiz analytics:post <post-id>

# 获取帖子最近 30 天的分析
postiz analytics:post <post-id> -d 30

返回一个指标数组（例如，关注者、展示次数、点赞、评论），包含每日数据点和周期内的百分比变化。

⚠️ 重要：缺失 Release ID 的处理

如果 analytics:post 返回 {"missing": true} 而不是分析数组，则表示帖子已发布，但平台未返回可用的帖子 ID。在分析功能正常工作之前，您必须解决此问题：

# 1. analytics:post 返回 {"missing": true}
postiz analytics:post <post-id>

# 2. 从提供者处获取可用内容
postiz posts:missing <post-id>
# 返回：[{"id": "7321456789012345678", "url": "https://...cover.jpg"}, ...]

# 3. 将正确的内容连接到帖子
postiz posts:connect <post-id> --release-id "7321456789012345678"

# 4. 现在分析功能将正常工作
postiz analytics:post <post-id>

连接缺失的帖子

某些平台（例如 TikTok）在发布后不会立即返回帖子 ID。发生这种情况时，帖子的 releaseId 将被设置为 "missing"，并且在问题解决之前无法进行分析。

# 为 release ID 缺失的帖子列出提供者的近期内容
postiz posts:missing <post-id>

# 将帖子与其已发布的内容连接起来
postiz posts:connect <post-id> --release-id "<content-id>"

如果提供者不支持此功能或帖子没有缺失的 release ID，则返回空数组。

媒体上传

⚠️ 重要： 在帖子中使用文件之前，务必先将其上传到 Postiz。许多平台（TikTok、Instagram、YouTube）要求使用已验证的 URL，并会拒绝外部链接。

# 上传文件并获取 URL
postiz upload image.jpg

# 支持：图片（PNG、JPG、GIF、WEBP、SVG）、视频（MP4、MOV、AVI、MKV、WEBM）、
# 音频（MP3、WAV、OGG、AAC）、文档（PDF、DOC、DOCX）

# 工作流：上传 → 提取 URL → 在帖子中使用
VIDEO=$(postiz upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" -m "$VIDEO_PATH" -i "tiktok-id"

常用模式

模式 1：发现并使用集成工具

Reddit - 获取子版块的 Flairs：

# 获取 Reddit 集成 ID
REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')

# 获取可用的 Flairs
FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')

# 在帖子中使用
postiz posts:create \
  -c "我的帖子内容" \
  -s "2024-12-31T12:00:00Z" \
  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"帖子标题\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"讨论\"}}}]}" \
  -i "$REDDIT_ID"

YouTube - 获取播放列表：

YOUTUBE_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="youtube") | .id')
PLAYLISTS=$(postiz integrations:trigger "$YOUTUBE_ID" getPlaylists)
PLAYLIST_ID=$(echo "$PLAYLISTS" | jq -r '.output[0].id')

postiz posts:create \
  -c "视频描述" \
  -s "2024-12-31T12:00:00Z" \
  --settings "{\"title\":\"我的视频\",\"type\":\"public\",\"playlistId\":\"$PLAYLIST_ID\"}" \
  -m "video.mp4" \
  -i "$YOUTUBE_ID"

LinkedIn - 以公司身份发布：

LINKEDIN_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="linkedin") | .id')
COMPANIES=$(postiz integrations:trigger "$LINKEDIN_ID" getCompanies)
COMPANY_ID=$(echo "$COMPANIES" | jq -r '.output[0].id')

postiz posts:create \
  -c "公司公告" \
  -s "2024-12-31T12:00:00Z" \
  --settings "{\"companyId\":\"$COMPANY_ID\"}" \
  -i "$LINKEDIN_ID"

模式 2：发布前上传媒体

# 上传多个文件
VIDEO_RESULT=$(postiz upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO_RESULT" | jq -r '.path')

THUMB_RESULT=$(postiz upload thumbnail.jpg)
THUMB_PATH=$(echo "$THUMB_RESULT" | jq -r '.path')

# 在帖子中使用
postiz posts:create \
  -c "看看我的视频！" \
  -s "2024-12-31T12:00:00Z" \
  -m "$VIDEO_PATH" \
  -i "tiktok-id"

模式 3：Twitter 主题帖

postiz posts:create \
  -c "🧵 主题帖开头 (1/4)" -m "intro.jpg" \
  -c "要点一 (2/4)" -m "point1.jpg" \
  -c "要点二 (3/4)" -m "point2.jpg" \
  -c "结论 (4/4)" -m "outro.jpg" \
  -s "2024-12-31T12:00:00Z" \
  -d 2000 \
  -i "twitter-id"

模式 4：多平台营销活动

# 创建包含平台特定内容的 JSON 文件
cat > campaign.json << 'EOF'
{
  "integrations": ["twitter-123", "linkedin-456", "facebook-789"],
  "posts": [
    {
      "provider": "twitter",
      "post": [
        {
          "content": "简短推文版本 #tech",
          "image": ["twitter-image.jpg"]
        }
      ]
    },
    {
      "provider": "linkedin",
      "post": [
        {
          "content": "专业的 LinkedIn 版本，包含更多上下文...",
          "image": ["linkedin-image.jpg"]
        }
      ]
    }
  ]
}
EOF

postiz posts:create --json campaign.json

模式 5：发布前验证设置

#!/bin/bash

INTEGRATION_ID="twitter-123"
CONTENT="您的帖子内容"

# 获取集成设置并提取最大长度
SETTINGS_JSON=$(postiz integrations:settings "$INTEGRATION_ID")
MAX_LENGTH=$(echo "$SETTINGS_JSON" | jq '.output.maxLength')

# 检查字符限制，并在需要时截断
if [ ${#CONTENT} -gt "$MAX_LENGTH" ]; then
  echo "内容超过 $MAX_LENGTH 个字符，正在截断..."
  CONTENT="${CONTENT:0:$((MAX_LENGTH - 3))}..."
fi

# 使用设置创建帖子
postiz posts:create \
  -c "$CONTENT" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"key": "value"}' \
  -i "$INTEGRATION_ID"

模式 6：批量安排

#!/bin/bash

# 安排一周的帖子
DATES=(
  "2024-02-14T09:00:00Z"
  "2024-02-15T09:00:00Z"
  "2024-02-16T09:00:00Z"
)

CONTENT=(
  "周一动力 💪"
  "周二小贴士 💡"
  "周三智慧 🧠"
)

for i in "${!DATES[@]}"; do
  postiz posts:create \
    -c "${CONTENT[$i]}" \
    -s "${DATES[$i]}" \
    -i "twitter-id" \
    -m "post-${i}.jpg"
  echo "已安排：${CONTENT[$i]} 于 ${DATES[$i]}"
done

模式 7：错误处理与重试

#!/bin/bash

CONTENT="您的帖子内容"
INTEGRATION_ID="twitter-123"
DATE="2024-12-31T12:00:00Z"
MAX_RETRIES=3

for attempt in $(seq 1 $MAX_RETRIES); do
  if postiz posts:create -c "$CONTENT" -s "$DATE" -i "$INTEGRATION_ID"; then
    echo "帖子创建成功"
    break
  else
    echo "尝试 $attempt 失败"
    if [ "$attempt" -lt "$MAX_RETRIES" ]; then
      DELAY=$((2 ** attempt))
      echo "${DELAY} 秒后重试..."
      sleep "$DELAY"
    else
      echo "$MAX_RETRIES 次尝试后失败"
      exit 1
    fi
  fi
done

技术概念

集成工具工作流

许多集成需要无法硬编码的动态数据（ID、标签、播放列表）。工具工作流支持发现和使用这些数据：

1. 检查可用工具 - integrations:settings 返回一个 tools 数组
2. 查看工具模式 - 每个工具都有 methodName、description 和 dataSchema
3. 触发工具 - 使用所需参数调用 integrations:trigger
4. 使用输出 - 工具返回的数据可用于帖子设置

按平台分类的工具示例：
- Reddit：getFlairs、searchSubreddits、getSubreddits
- YouTube：getPlaylists、getCategories、getChannels
- LinkedIn：getCompanies、getOrganizations
- Twitter/X：getListsowned、getCommunities
- Pinterest：getBoards、getBoardSections

提供者设置结构

平台特定设置使用带有 __type 字段的鉴别器模式：

{
  "posts": [
    {
      "provider": "reddit",
      "post": [{ "content": "...", "image": [...] }],
      "settings": {
        "__type": "reddit",
        "subreddit": [{
          "value": {
            "subreddit": "programming",
            "title": "帖子标题",
            "type": "text",
            "url": "",
            "is_flair_required": false
          }
        }]
      }
    }
  ]
}

直接传递设置：

postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" --settings '{"subreddit":[...]}' -i "reddit-id"
# 后端会根据集成 ID 自动添加 "__type"

评论与主题帖

帖子可以包含评论（在 Twitter/X 上是主题帖，在其他平台是回复）。每条评论都可以有自己的媒体：

```bash

使用多个 -c 和 -m 标志

postiz posts:create \
-c "主帖" -m "image1.jpg,image2.jpg" \
-c "评论 1" -m "comment-img.jpg" \
-c "评论 2" -m "another.jpg,more.jpg" \
-s "2024-12-31T12:00:00Z" \
-d 5 \