介绍
# WordPress Publisher
使用 REST API 直接将内容发布到 WordPress 站点，支持完整的 Gutenberg 区块格式、自动分类选择、SEO 标签生成和预览功能。
## 完整工作流程概览
``` 1. CONNECT → Authenticate with WordPress site 2. ANALYZE → Load categories from site, analyze content for best match 3. GENERATE → Create SEO-optimized tags based on content 4. CONVERT → Transform markdown/HTML to Gutenberg blocks 5. PREVIEW → Create draft and verify rendering 6. PUBLISH → Publish or schedule the post 7. VERIFY → Confirm live post renders correctly ```
---
## 步骤 1：连接设置
### 获取凭据
向用户询问： - WordPress 站点 URL（例如 `https://example.com`） - WordPress 用户名 - 应用程序密码（注意：不是常规密码）
### 如何创建应用程序密码
指导用户： 1. 在 WordPress 管理后台进入 **用户 → 个人资料** 2. 滚动到 **应用程序密码** 部分 3. 输入名称：`Claude Publisher` 4. 点击 **添加新的应用程序密码** 5. 复制生成的密码（仅显示一次，带空格）
### 测试连接
```python from scripts.wp_publisher import WordPressPublisher
wp = WordPressPublisher( site_url="https://example.com", username="admin", password="xxxx xxxx xxxx xxxx xxxx xxxx" # Application password )
# Test connection user_info = wp.test_connection() print(f"Connected as: {user_info['name']}") ```
---
## 步骤 2：加载并选择分类
### 从站点自动加载分类
```python # Get all categories from the WordPress site categories = wp.get_categories_with_details()
# Returns list like: # [ # {'id': 1, 'name': 'Uncategorized', 'slug': 'uncategorized', 'count': 5}, # {'id': 2, 'name': 'Tutorials', 'slug': 'tutorials', 'count': 12}, # {'id': 3, 'name': 'Cloud Hosting', 'slug': 'cloud-hosting', 'count': 8}, # ] ```
### 智能分类选择
系统会分析内容并选择最合适的分类：
```python # Analyze content and suggest best category suggested_category = wp.suggest_category( content=article_content, title=article_title, available_categories=categories )
# Or let user choose from available options print("Available categories:") for cat in categories: print(f" [{cat['id']}] {cat['name']} ({cat['count']} posts)") ```
### 分类选择逻辑
1. **精确匹配** - 标题/内容包含分类名称 2. **关键词匹配** - 分类别名与主题关键词匹配 3. **父分类** - 如果没有匹配，回退到更广泛的父分类 4. **新建分类** - 如果都不合适则创建新分类（需用户批准）
---
## 步骤 3：生成 SEO 优化标签
### 自动标签生成
生成可提高 Google 搜索可见性的标签：
```python # Generate tags based on content analysis tags = wp.generate_seo_tags( content=article_content, title=article_title, max_tags=10 )
# Returns list like: # ['n8n hosting', 'workflow automation', 'self-hosted n8n', # 'affordable hosting', 'docker deployment', 'node.js hosting'] ```
### 标签生成规则
1. **主要关键词** - 始终作为第一个标签包含 2. **次要关键词** - 包含 2-3 个相关术语 3. **长尾关键词** - 包含 3-4 个特定短语 4. **实体标签** - 包含提到的产品/品牌名称 5. **主题标签** - 包含更广泛的分类术语
### 在 WordPress 中创建/获取标签
```python # Get or create all tags, returns list of tag IDs tag_ids = wp.get_or_create_tags(tags) ```
---
## 步骤 4：将内容转换为 Gutenberg 区块
### Markdown 转 Gutenberg
```python from scripts.content_to_gutenberg import convert_to_gutenberg
# Convert markdown content gutenberg_content = convert_to_gutenberg(markdown_content) ```
### 支持的转换
| Markdown | Gutenberg 区块 | |----------|-----------------| | `# Heading` | `wp:heading` | | `**bold**` | 段落中的 `<strong>` | | `- list item` | `wp:list` | | `1. ordered` | `wp:list {"ordered":true}` | | `\`\`\`code\`\`\`` | `wp:code` | | `> quote` | `wp:quote` | | `` | `wp:image` | | `\| table \|` | `wp:table` |
### 表格转换（对 AI 内容至关重要）
表格将转换为正确的 Gutenberg 结构：
```python # Input markdown: | Feature | Plan A | Plan B | |---------|--------|--------| | Price | $10 | $20 |
# Output Gutenberg: <!-- wp:table --> <figure class="wp-block-table"><table> <thead><tr><th>Feature</th><th>Plan A</th><th>Plan B</th></tr></thead> <tbody><tr><td>Price</td><td>$10</td><td>$20</td></tr></tbody> </table></figure> <!-- /wp:table --> ```
---
## 步骤 5：发布前预览
### 创建草稿以进行预览
```python # Create as draft first result = wp.create_draft( title="Article Title", content=gutenberg_content, categories=[category_id], tags=tag_ids, excerpt="Auto-generated or custom excerpt" )
post_id = result['post_id'] preview_url = result['preview_url'] edit_url = result['edit_url'] ```
### 验证预览
```python # Fetch preview page to verify rendering preview_content = wp.fetch_preview(post_id)
# Check for issues issues = wp.validate_rendered_content(preview_content) if issues: print("Issues found:") for issue in issues: print(f" - {issue}") ```
### 预览检查清单
- [ ] 标题显示正确 - [ ] 所有标题均渲染（H2、H3、H4） - [ ] 表格使用正确的格式渲染 - [ ] 列表显示正确（项目符号和编号） - [ ] 代码块具有语法高亮 - [ ] 图片加载（如果有） - [ ] 链接可点击 - [ ] 分类显示正确 - [ ] 标签显示在文章中
---
## 步骤 6：发布文章
### 发布草稿
```python # After preview approval, publish result = wp.publish_post(post_id) live_url = result['live_url'] ```
### 或直接创建并发布
```python # Full publish workflow in one call result = wp.publish_content( title="Article Title", content=gutenberg_content, category_names=["Cloud Hosting"], # By name, auto-resolves to ID tag_names=["n8n", "hosting", "automation"], status="publish", # or "draft", "pending", "private", "future" excerpt="Custom excerpt for SEO", slug="custom-url-slug" ) ```
### 定时文章
```python # Schedule for future publication from datetime import datetime, timedelta
publish_date = datetime.now() + timedelta(days=1) result = wp.publish_content( title="Scheduled Post", content=content, status="future", date=publish_date.isoformat() ) ```
---
## 步骤 7：验证已发布的文章
### 检查在线文章
```python # Verify the published post verification = wp.verify_published_post(post_id)
print(f"Live URL: {verification['url']}") print(f"Status: {verification['status']}") print(f"Categories: {verification['categories']}") print(f"Tags: {verification['tags']}") ```
### 常见问题与修复
| 问题 | 原因 | 解决方案 | |-------|-------|----------| | 表格未渲染 | 缺少 figure 包装器 | 使用正确的 `wp:table` 区块结构 | | 代码未高亮 | 缺少 language 属性 | 向代码块添加 `{"language":"python"}` | | 图片损坏 | URL 错误或媒体丢失 | 先上传到 WordPress，使用媒体 ID | | 标签未显示 | 主题不显示标签 | 检查主题设置或使用不同主题 |
---
## 完整示例工作流程
```python from scripts.wp_publisher import WordPressPublisher from scripts.content_to_gutenberg import convert_to_gutenberg
# 1. Connect wp = WordPressPublisher( site_url="https://xcloud.host", username="admin", password="xxxx xxxx xxxx xxxx" )
# 2. Load categories and select best match categories = wp.get_categories_with_details() best_category = wp.suggest_category(content, title, categories)
# 3. Generate SEO tags tags = wp.generate_seo_tags(content, title, max_tags=10)
# 4. Convert to Gutenberg gutenberg_content = convert_to_gutenberg(markdown_content)
# 5. Create draft and preview draft = wp.create_draft( title="7 Best n8n Hosting Providers in 2026", content=gutenberg_content, categories=[best_category['id']], tags=wp.get_or_create_tags(tags) ) print(f"Preview: {draft['preview_url']}")
# 6. After verification, publish result = wp.publish_post(draft['post_id']) print(f"Published: {result['live_url']}") ```
---
## 快速参考
### API 端点
| 资源 | 端点 | |----------|----------| | 文章 | `/wp-json/wp/v2/posts` | | 页面 | `/wp-json/wp/v2/pages` | | 分类 | `/wp-json/wp/v2/categories` | | 标签 | `/wp-json/wp/v2/tags` | | 媒体 | `/wp-json/wp/v2/media` |
### 文章状态
| 状态 | 描述 | |--------|-------------| | `publish` | 已上线且可见 | | `draft` | 已保存但不可见 | | `pending` | 等待审核 | | `private` | 仅管理员可见 | | `future` | 已计划稍后发布 |
### 所需文件
- `scripts/wp_publisher.py` - 主发布器类 - `scripts/content_to_gutenberg.py` - Markdown/HTML 转换器 - `references/gutenberg-blocks.md` - 区块格式参考
---
## 错误处理
| 错误代码 | 含义 | 解决方案 | |------------|---------|----------| | 401 | 无效的凭据 | 检查用户名和应用程序密码 | | 403 | 权限不足 | 用户需要编辑或管理员角色 | | 404 | 未找到端点 | 验证 REST API 是否已启用 | | 400 | 无效数据 | 检查分类/标签 ID 是否存在 | | 500 | 服务器错误 | 重试或检查 WordPress 错误日志 |
---
## 最佳实践
1. **始终先预览** - 创建为草稿，验证后再发布 2. **使用应用程序密码** - 切勿使用常规 WordPress 密码 3. **选择合适的分类** - 有助于站点组织和 SEO 4. **生成相关标签** - 提高 Google 可发现性 5. **验证 Gutenberg 区块** - 确保区块结构正确 6. **将摘要保持在 160 字符以内** - 搜索摘要的最佳长度 7. **使用描述性别名** - 在 URL 中包含主要关键词