ghost-cms-skill

全面的 Ghost CMS 集成，用于创建、发布、安排和管理博客内容、时事通讯、成员和分析。在使用 Ghost 博客进行内容创建（草稿、发布、日程安排）、成员/订阅者管理（级别、时事通讯）、评论审核或分析（热门帖子、订阅者增长）时使用。支持所有 Ghost 管理 API 操作。

## 概述（中文）

全面的 Ghost CMS 集成，用于创建、发布、安排和管理博客内容、时事通讯、成员和分析。在使用 Ghost 博客进行内容创建（草稿、发布、日程安排）、成员/订阅者管理（级别、时事通讯）、评论审核或分析（热门帖子、订阅者增长）时使用。支持所有 Ghost 管理 API 操作。

## 原文

# Ghost CMS

Manage Ghost blog content, members, analytics, and newsletters through the Ghost Admin API.

## ⚠️ Security Warning

**Ghost Admin API keys provide FULL access to your Ghost site:**

- **Content Management:** Create, update, delete, publish posts and pages
- **Member Management:** Add, modify, delete members and subscriptions
- **Subscription Management:** Create, modify, delete membership tiers
- **Comment Management:** Reply to, approve, delete comments
- **User Management:** Invite, modify, delete users
- **Media Management:** Upload images and files (affects storage)
- **Site Configuration:** Modify newsletters and settings

**Published content is IMMEDIATELY PUBLIC** - be extra careful with publish operations.

**Security Best Practices:**
- **Store API keys securely** - Use 1Password CLI or secure env vars
- **Review before publishing** - Always check content before making it public
- **Never commit keys** - Keep credentials out of version control
- **Rotate keys regularly** - Create new integrations every 90 days
- **Use dedicated integrations** - Separate keys for different use cases
- **Test on staging first** - Use a test Ghost site when possible

**Admin API Key Scope:**
Ghost Admin API keys have **no scoping options** - they provide full access to everything. There are no read-only keys.

**Operation Types:**

**Read-Only Operations** (✅ Safe):
- List posts, pages, tags, members, tiers, newsletters, comments
- Get analytics and member stats
- All GET requests

**Destructive Operations** (⚠️ Modify or delete data, may be public):
- Create/update/delete posts, pages, tags (POST, PUT, DELETE)
- Publish/unpublish/schedule posts (**makes content public**)
- Create/update/delete members, tiers, newsletters
- Create replies, approve/delete comments
- Upload images (uses storage quota)
- All POST, PUT, DELETE requests

For detailed operation documentation, see [api-reference.md](references/api-reference.md).

## Quick Setup

1. **Get your Ghost Admin API credentials:**
   - Ghost dashboard → Settings → Integrations
   - Create a new "Custom Integration"
   - Copy the **Admin API Key** and **API URL**

2. **Store credentials securely:**

   **Option A: Environment Variables (Recommended)**
   ```bash
   # Add to your shell profile (~/.zshrc, ~/.bashrc)
   export GHOST_ADMIN_KEY="YOUR_ADMIN_API_KEY"
   export GHOST_API_URL="YOUR_GHOST_URL"
   ```

   **API URL Examples (works with ALL hosting types):**
   ```bash
   # Ghost(Pro) hosted
   export GHOST_API_URL="https://yourblog.ghost.io"
   
   # Self-hosted with reverse proxy (production)
   export GHOST_API_URL="https://blog.yourdomain.com"
   
   # Self-hosted development (Ghost default port 2368)
   export GHOST_API_URL="http://localhost:2368"
   
   # Self-hosted with custom port
   export GHOST_API_URL="https://ghost.example.com:8080"
   ```

   **Important:**
   - Always include protocol (`http://` or `https://`)
   - Include `:PORT` if Ghost runs on non-standard port
   - Do NOT include trailing slash
   - Do NOT include `/ghost/api/admin` (added automatically)

   **Option B: Config Files**
   ```bash
   mkdir -p ~/.config/ghost
   echo "YOUR_ADMIN_API_KEY" > ~/.config/ghost/api_key
   echo "YOUR_GHOST_URL" > ~/.config/ghost/api_url
   
   # Secure the files (owner read-only)
   chmod 600 ~/.config/ghost/api_key
   chmod 600 ~/.config/ghost/api_url
   ```

   **Option C: 1Password CLI (Most Secure)**
   ```bash
   # Store key in 1Password
   op item create --category=API_CREDENTIAL \
     --title="Ghost Admin API" \
     admin_key[password]="YOUR_ADMIN_API_KEY" \
     api_url[text]="YOUR_GHOST_URL"

   # Use in commands
   export GHOST_ADMIN_KEY=$(op read "op://Private/Ghost Admin API/admin_key")
   export GHOST_API_URL=$(op read "op://Private/Ghost Admin API/api_url")
   ```

   **Security Notes:**
   - Keys provide **full site access** - protect them like passwords
   - Rotate keys every 90 days (create new integration, revoke old)
   - Never commit to git or share keys publicly
   - Consider separate keys for production vs. staging
   - **HTTPS recommended:** Use HTTPS for production (HTTP acceptable for localhost only)

3. **Install dependencies:**
   ```bash
   cd ghost-cms-skill/scripts
   npm install
   ```

   **Dependencies installed:**
   - `form-data` (^4.0.5) - Multipart file uploads (theme ZIP files)
   - `jsonwebtoken` (^9.0.3) - JWT token generation for Ghost Admin API authentication

   **Optional dependencies** (install manually if needed):
   - `gscan` (^5.2.4) - Official Ghost theme validator (from TryGhost)
     - Only needed for theme validation feature
     - Install with: `cd scripts && npm install gscan`

   **All dependencies from public npm registry. No custom downloads.**

4. **Test connection:**
   See [setup.md](references/setup.md) for detailed authentication and troubleshooting.

## Tools & Utilities

### Snippet Extractor

**Purpose:** Migrate existing Ghost snippets to local library for programmatic use.

**Why needed:** Ghost Admin API blocks snippet access (403 Forbidden) for integration tokens. This tool works around that limitation.

**Usage:**
```bash
# Extract snippets from a specially-formatted draft post
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker prefix
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help
```

**Workflow:**
1. Create draft post in Ghost
2. For each snippet: add paragraph marker (e.g., "SNIPPET: name" or "This is: name")
3. Insert the snippet content below each marker
4. Run extractor → all snippets saved to `snippets/library/`

**Features:**
- ✅ Extracts all card types (bookmarks, callouts, images, markdown, HTML, etc.)
- ✅ Preserves exact Lexical structure
- ✅ Auto-detects credentials from `~/.config/ghost/` or env vars
- ✅ Supports custom marker formats
- ✅ Dry-run and validation modes
- ✅ Verbose output for debugging

**Example:**
```bash
# User has 12 snippets in Ghost
# Creates "My Snippets" draft with markers
# Runs: node scripts/snippet-extractor.js my-snippets --marker "This is:"
# Result: All 12 snippets in library/ ready for use
```

See `snippets/README.md` for complete documentation.

### Theme Manager

**Purpose:** Upload, activate, switch, and manage Ghost themes programmatically.

**Why needed:** Automate theme deployments, switch themes, manage theme versions.

**Usage:**
```bash
cd scripts

# List all installed themes
node theme-manager.js list

# Upload theme ZIP
node theme-manager.js upload /path/to/theme.zip

# Upload and activate immediately
node theme-manager.js upload /path/to/theme.zip --activate

# Activate existing theme
node theme-manager.js activate theme-name

# Download theme backup
node theme-manager.js download theme-name backup.zip

# Delete theme (cannot delete active theme)
node theme-manager.js delete old-theme

# Show current active theme
node theme-manager.js active
```

**Features:**
- ✅ Upload custom themes from ZIP files
- ✅ Switch between installed themes
- ✅ Download theme backups
- ✅ Delete unused themes
- ✅ Validation and error handling
- ✅ **Immediate activation** - theme changes are public instantly

**⚠️ Important:**
- Theme activation is **immediate and public** - site appearance changes instantly
- Cannot delete the currently active theme (switch first)
- Themes must be valid Ghost theme ZIP files

**Workflow:**
```bash
# Safe theme switching with rollback
node theme-manager.js active              # Note current theme
node theme-manager.js activate new-theme  # Switch to new theme
# Test site in browser
node theme-manager.js activate ol