postall

name	postall
version	1.0.0
description	AI-powered multi-platform social media content generation and publishing automation. Generate, review, and publish content across Twitter, LinkedIn, Instagram, Pinterest, Threads, and Xiaohongshu.
homepage	https://postall.live
repository	https://github.com/qingxuantang/postall
metadata	{"emoji":"📮","category":"content-automation","platforms":["twitter","linkedin","instagram","pinterest","threads","xiaohongshu","wechat"],"ai_providers":["anthropic","openai","google"]}

PostAll - AI Agent Integration

AI-powered multi-platform content automation. Generate, review, and publish across all social platforms from a single configuration.

Skill Files

File	URL
SKILL.md (this file)	https://postall.live/skill.md
skill.json (metadata)	https://postall.live/skill.json

Quick install for agents:

curl -s https://postall.live/skill.md > ~/.postall/SKILL.md
curl -s https://postall.live/skill.json > ~/.postall/skill.json

---

What PostAll Does

1. Content Generation - AI creates platform-optimized posts from your brand guidelines
2. Director Review - Second AI reviews for quality, brand alignment, factual accuracy
3. Image Generation - Auto-generate matching visuals with correct dimensions per platform
4. Multi-Platform Publishing - Publish to Twitter, LinkedIn, Instagram, Pinterest, Threads, Xiaohongshu
5. RLHF Learning - System improves from feedback over time
6. Scheduling - Optimal posting times per platform

---

Quick Start

Option 1: Docker (Recommended)

# Clone and setup
git clone https://github.com/qingxuantang/postall.git
cd postall
cp .env.example .env

# Configure API keys in .env
# ANTHROPIC_API_KEY=your_key (or OPENAI_API_KEY or GEMINI_API_KEY)

# Start
docker-compose up -d

Option 2: Local Installation

git clone https://github.com/qingxuantang/postall.git
cd postall
pip install -e .
cp .env.example .env
# Edit .env with your API keys

---

Core CLI Commands

All commands use the format: python -m postall.cli <command> --project <path/to/project.yaml>

Generate Content

# Generate content for all platforms
python -m postall.cli generate --project projects/example/project.yaml

# Generate for specific platform
python -m postall.cli generate --project projects/example/project.yaml --platform twitter

# Generate with specific AI model
python -m postall.cli generate --project projects/example/project.yaml --model claude

Publish Content

# Publish all pending content
python -m postall.cli publish --project projects/example/project.yaml

# Publish to specific platform
python -m postall.cli publish --project projects/example/project.yaml --platform linkedin

Run as Daemon

# Continuous operation - auto generate and publish
python -m postall.cli daemon --project projects/example/project.yaml

Check Status

# View system status
python -m postall.cli status --project projects/example/project.yaml

# Review generated content
python -m postall.cli review --project projects/example/project.yaml

---

Docker Commands

# Start PostAll
docker-compose up -d

# View logs
docker-compose logs -f postall

# Stop
docker-compose down

# Restart
docker-compose restart

# Execute CLI inside container
docker exec postall python -m postall.cli status --project /app/projects/example/project.yaml

---

Telegram Bot Integration

PostAll includes a Telegram bot for monitoring and control. Each project gets its own bot.

Bot Commands (in Telegram)

Command	Description
/start	Initialize the bot
/status	View current system status
/upcoming	Posts scheduled for next 24 hours
/schedule	Today's posting schedule
/stats	Recent publishing statistics
/generate	Trigger content generation for next week
/publish	Manually trigger publishing
/help	Show all commands

Bot Menu Buttons

• Upcoming - View posts in the next 24 hours
• Schedule - Today's scheduled posts
• Stats - Publishing statistics by platform
• Content Status - Next week's content status
• Generate - Start content generation

Setting Up Telegram Bot

1. Create a bot via @BotFather
2. Get your bot token
3. Add to .env:

   TELEGRAM_BOT_ENABLED=true
   TELEGRAM_BOT_TOKEN=your_bot_token
   TELEGRAM_CHAT_ID=your_chat_id
   

---

Project Configuration

Create a project.yaml file to define your brand and content strategy:

project_name: "My Brand"

brand:
  name: "My Brand"
  tagline: "Your Tagline"
  website: "mybrand.com"
  
  colors:
    primary: "#3498DB"
    secondary: "#2ECC71"
    accent: "#E74C3C"
  
  voice:
    tone: "professional yet friendly"
    characteristics:
      - "clear and concise"
      - "helpful and educational"
      - "trustworthy and authentic"
    avoid:
      - "aggressive sales language"
      - "overpromising or hype"
      - "technical jargon"

content_strategy:
  pillars:
    product_education: 35
    industry_insights: 25
    tips_productivity: 20
    customer_stories: 10
    behind_scenes: 5
    lead_magnet: 5
  
  themes:
    - "Getting Started"
    - "Best Practices"
    - "Common Mistakes"
    - "Success Stories"

platforms:
  twitter:
    enabled: true
    language: "en"
  linkedin:
    enabled: true
    language: "en"
  instagram:
    enabled: false
  pinterest:
    enabled: false

timezone: "America/Los_Angeles"

generation_schedule:
  day: "saturday"
  time: "09:00"

posting_times:
  twitter: ["08:00", "12:00", "18:00"]
  linkedin: ["07:30", "12:00"]

---

Environment Variables

# AI Providers (at least one required)
ANTHROPIC_API_KEY=           # Claude API
OPENAI_API_KEY=              # GPT-4 API
GEMINI_API_KEY=              # Gemini API

# Twitter/X
TWITTER_ENABLED=true
TWITTER_API_KEY=
TWITTER_API_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_SECRET=

# LinkedIn
LINKEDIN_ENABLED=true
LINKEDIN_ACCESS_TOKEN=
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=
LINKEDIN_PERSON_URN=

# Instagram (Meta)
INSTAGRAM_ENABLED=false
INSTAGRAM_ACCESS_TOKEN=
INSTAGRAM_BUSINESS_ACCOUNT_ID=

# Pinterest
PINTEREST_ENABLED=false
PINTEREST_ACCESS_TOKEN=

# Telegram Bot
TELEGRAM_BOT_ENABLED=false
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

---

Content Generation Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Brand Config   │────▶│  AI Generation  │────▶│ Director Review │
│ (project.yaml)  │     │ (Claude/GPT/    │     │ (Quality Check) │
│                 │     │  Gemini)        │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                         │
                                                         ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Publishing    │◀────│  Human Review   │◀────│ Content Ready   │
│  (Platforms)    │     │   (Optional)    │     │   (Approved)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │  RLHF Learning  │
                        │  (Improvement)  │
                        └─────────────────┘

---

Director Review System

The Director is a second AI that reviews generated content for:

• Brand Alignment - Does it match your voice and tone?
• Quality Standards - Is it well-written and engaging?
• Platform Fit - Is it optimized for the target platform?
• Factual Accuracy - No fabricated statistics or claims
• Compliance - No problematic content

Posts receive a score. Low-scoring posts can be regenerated automatically.

---

Supported Platforms

Platform	Publishing	Image Support	Notes
Twitter/X	✅	✅	Threads supported
LinkedIn	✅	✅	Personal & Company pages
Instagram	✅	✅	Requires Meta Business
Pinterest	✅	✅	Pin creation
Threads	✅	✅	Meta Threads API
Xiaohongshu	✅	✅	Card generation + publishing
WeChat	✅	✅	Article publishing

---

Image Generation

PostAll automatically generates images optimized for each platform:

• Twitter: 1200x675 (16:9)
• LinkedIn: 1200x627 (1.91:1)
• Instagram: 1080x1080 (1:1)
• Pinterest: 1000x1500 (2:3)

Recommended: Use Gemini Pro for image generation (best quality).

---

RLHF Learning

The system learns from your feedback:

1. Rate Content - Mark posts as good, bad, or needs improvement
2. Custom Feedback - Provide specific notes on what to change
3. Auto-Learning - System adjusts future generations based on patterns

---

Agent Integration Patterns

Pattern 1: Scheduled Generation

Set up weekly content generation with auto-publish:

# In your agent's scheduled tasks
import subprocess

def weekly_content_generation():
    # Generate content
    subprocess.run([
        "python", "-m", "postall.cli", "generate",
        "--project", "projects/mybrand/project.yaml"
    ])
    
    # Publish approved content
    subprocess.run([
        "python", "-m", "postall.cli", "publish", 
        "--project", "projects/mybrand/project.yaml"
    ])

Pattern 2: On-Demand Generation

Generate content when triggered by your agent:

# Generate a single post for a specific topic
python -m postall.cli generate \
  --project projects/mybrand/project.yaml \
  --topic "New product feature announcement" \
  --platform twitter

Pattern 3: Monitor via Telegram

Let your agent receive status updates via Telegram bot, then take action based on results.

---

File Structure

postall/
├── postall/                    # Core library
│   ├── cli.py                  # Command-line interface
│   ├── config.py               # Configuration management
│   ├── cloud/                  # Cloud services
│   │   ├── daemon.py           # Background daemon
│   │   ├── generation_controller.py
│   │   └── telegram_bot.py
│   ├── director/               # AI review system
│   │   └── director.py
│   ├── executors/              # AI model executors
│   │   ├── claude_api_executor.py
│   │   ├── gemini_api_executor.py
│   │   └── gemini_image_executor.py
│   ├── publishers/             # Platform publishers
│   │   ├── twitter_publisher.py
│   │   ├── linkedin_publisher.py
│   │   ├── instagram_publisher.py
│   │   └── xhs_publisher.py
│   └── learning/               # RLHF system
│       ├── feedback_collector.py
│       └── rlhf_manager.py
├── projects/
│   └── example/                # Example project
│       ├── project.yaml
│       ├── output/             # Generated content
│       └── database/           # Persistent data
├── docker-compose.yml
├── Dockerfile
└── .env.example

---

Critical Rules

When using PostAll, follow these rules to avoid common issues:

1. NO parentheses in content - 括号会导致 LinkedIn 内容被截断
2. NO AI clichés - 避免「久久不能平静」「震撼了我」「颠覆认知」等空洞表达
3. NO fabricated data - 只使用原始内容中的真实信息，不要编造统计数据
4. Image prompts in English - AI 图像生成器无法渲染中文字符
5. Image prompts must reference a concrete object or scene, not the abstract thesis - 配图必须基于一个具体物件或场景，不要用文章的抽象论点。 Models like Gemini produce generic geometric blocks or flowing color shapes when given abstract conceptual phrases like "components dissolving" or "intelligence augmentation." Read the post body, find one concrete thing it mentions — a vintage radio with a TV camera pointed at it, a presentation slide with a score badge, a stack of old books, a key, a bridge — and use that as the image hero element. The abstract thesis is conveyed through the literal scene, not through the prompt language. — 模型对抽象概念词（例如「组件正在消解」「AI 重塑工程师角色」）出图都是几何 blocks 或流动色块，没有视觉记忆点。必须从文章里找一个具体的物件或场景，用那个作为 image 主体。抽象论点通过具体场景让读者自己悟出来。
6. Handle rate limits gracefully - 遇到平台限制时等待后重试
7. *WeChat: use _content.md files - Content parser 可能错误分割单篇文章，发布时永远使用完整的 *_content.md 文件（如 wechat_content.md），不要使用分割后的小文件（如 01_monday_morning_article.md）

Content File Structure

When content is generated, you'll see:

wechat-posts/
├── wechat_content.md           # ✅ 完整内容 - 发布时用这个
├── 01_monday_morning_article.md # ❌ 可能被截断
├── 02_tuesday_morning_post.md   # ❌ 可能被截断
└── ...

Always publish using the *_content.md file, not the numbered split files.

---

Prompt Design Tips

Lessons that surface only after running the pipeline against real platforms. Two patterns to bake into your run_topic_*.py from day one.

Tip 1: Set explicit per-platform character caps — don't assume the model honors them

The LLM is bad at counting characters. Telling it "stay under N chars" reduces overrun frequency but does NOT guarantee compliance. Always verify with wc -c after generation and trim manually if over.

Per-account, per-platform caps to know:

Platform / tier	Max characters per single post
Twitter Free	280
Twitter Premium Basic	4,000
Twitter Premium+	25,000
LinkedIn personal feed	3,000 (hard cap, no exceptions)
LinkedIn org page	3,000
WeChat article body	no hard cap (practical 5,000-10,000)

Encode the cap explicitly in your prompt's CRITICAL RULES section. Example:

twitter_prompt_en = f"""...
CRITICAL RULES:
- HARD CAP: body text MUST stay under <N> characters. Count carefully.
  If your draft is over, cut paragraphs until under.
- Single tweet, NO thread structure
...
"""

After each generation, verify:

python3 -c "import re; t=open('x.md').read(); body=re.sub(r'\*\*([^*]+)\*\*', r'\1', t.split('### Image Prompt')[0]); print(len(body.strip()))"

If your draft is over, paragraph-level trims are usually enough. Prioritize keeping: the hook, the concrete examples, the closing CTA.

Tip 2: Don't let prompt blocks contradict each other

If your prompt has multiple instruction blocks (e.g. TOPIC describes the content + CTA_INSTRUCTION describes the CTA + HITLIST_INSTRUCTION describes style constraints), check for direct contradictions BEFORE every run.

Failure mode observed in production: when one block says "include link X" and another block says "don't include link X", the model resolves the conflict probabilistically — sometimes X appears, sometimes it doesn't. The result is unpredictable output across batch runs.

Cheap mitigation: after editing any prompt block, grep across all blocks for the same concept:

# Example: check whether "include this link" and "don't include this link"
# both appear in the same script
grep -nE "tarai\.dev|don't include" run_topic_my_post.py

If you see both directions present, fix the conflict before running. The LLM cannot reliably honor mutually exclusive instructions.

Tip 3: Ban bridge phrases the LLM defaults to

When generating posts that mention multiple numbers or categories (e.g. dual scores, before/after metrics), the LLM tends to produce filler bridge sentences like "those two numbers tell different stories" or "the gap between them is the point." These add nothing and feel generic.

Add an explicit ban in your HITLIST 禁止 list:

⚠️ 禁止：
- 不要写"两个数字讲不同的故事" / "telling different stories" /
  "gap between them" / similar abstract bridge phrasing —
  go straight to the specific cause / specific finding / specific layer

This is in the same spirit as banning generic AI cliché phrases — the goal is to force the model into concrete, specific writing.

---

Troubleshooting

Common Issues

Content not publishing:

# Check platform credentials
python -m postall.cli status --project project.yaml

# View detailed logs
docker-compose logs -f postall | grep ERROR

Rate limits:

• Twitter: 1 post per platform per posting slot
• LinkedIn: Respect 100 posts/day limit
• Instagram: 25 posts/day limit

Image generation failing:

• Ensure GEMINI_API_KEY is set
• Check quota limits on Google AI Studio

---

Third-Party Integration Policy

PostAll's official docs do not recommend, endorse, or document third-party SaaS middlemen for any platform action — content collection, posting, scheduling, scraping, authentication proxying, or anything that routes user credentials or content through an external service.

This includes but is not limited to: Twitter/X middleman APIs, "agent-friendly" social scrapers, hosted content-collection services, and any closed-source plugin that requires users to give a third party their platform credentials or session cookies.

Why this policy exists

• A doc that says "install package X" is read by users as a tacit endorsement from the maintainers, even when the README disclaims it.
• Third-party SaaS integrations introduce supply chain risk that PostAll cannot audit. Today's benign version is tomorrow's malicious release.
• "Optional integration" PRs are increasingly generated by AI coding agents at scale and submitted to many OSS repos as a free marketing channel. See the codex/* PR pattern observed in 2026.
• PostAll's value is in clean, auditable, first-party publisher implementations. Routing through a middleman defeats that.

What we accept instead

• Users are free to integrate anything they want in their own project fork or downstream automation.
• Third-party tool authors are free to publish their own README documenting how to use their package alongside PostAll. That belongs in the third-party's repo, not in PostAll's.
• PRs that add a first-party publisher for a platform PostAll doesn't yet support are welcome — code and config, not links to a hosted service.
• PRs that add defensive controls against credential leakage, prompt injection, or supply-chain risk are welcome.

PRs we will close on sight

• PRs that add install <third-party-package> / pip install <middleman> / npm install @vendor/x instructions to any official doc.
• PRs that propose docs changes from a branch prefixed codex/, chatgpt-*, copilot-*, or other AI-agent autogeneration patterns when the substance is third-party promotion.
• PRs whose validation checklist reads like a generic AI boilerplate (markdown-link-check, git diff --check, python -m compileall) and whose substantive change is one ad block repeated across multiple files.

We close these without merging, regardless of how defensively-framed the proposed text is. Defensive framing is a known social-engineering pattern.

---

Resources

• Website: https://postall.live
• GitHub: https://github.com/qingxuantang/postall
• Demo Video: https://youtube.com/shorts/12EMDFuA8mc
• Platform Setup Guide: https://github.com/qingxuantang/postall/blob/master/docs/PLATFORM_SETUP.md

---

License

MIT License - Free to use and modify.

---

Last updated: 2026-03-04