名称： wordpress-publisher
描述： 通过 REST API 直接向 WordPress 网站发布内容，完全支持古腾堡（Gutenberg）区块。可创建和发布文章/页面、自动加载并选择网站分类、生成 SEO 优化标签、发布前预览文章，并为表格、图片、列表和富文本格式生成古腾堡区块。适用于用户想要发布到 WordPress、发布博客文章、创建 WordPress 文章、更新 WordPress 文章或将 Markdown 转换为古腾堡区块的场景。
作者： xCloud
版本： 1.0.0

WordPress 发布器

使用 REST API 直接向 WordPress 网站发布内容，支持完整的古腾堡区块格式化、自动分类选择、SEO 标签生成和预览功能。

完整工作流程概览

1. 连接    → 与 WordPress 站点进行身份验证
2. 分析    → 从站点加载分类，分析内容以寻找最佳匹配
3. 生成    → 基于内容创建 SEO 优化标签
4. 转换    → 将 Markdown/HTML 转换为古腾堡区块
5. 预览    → 创建草稿并验证渲染效果
6. 发布    → 发布或定时发布文章
7. 验证    → 确认已发布文章正确显示

步骤 1：连接设置

获取凭据

向用户询问：
- WordPress 站点 URL（例如 https://example.com）
- WordPress 用户名
- 应用程序密码（非常规密码）

如何创建应用程序密码

引导用户：
1. 在 WordPress 管理后台进入 用户 → 个人资料
2. 滚动到 应用程序密码 部分
3. 输入名称：Claude Publisher
4. 点击 添加新的应用程序密码
5. 复制生成的密码（仅显示一次，带空格）

测试连接

from scripts.wp_publisher import WordPressPublisher

wp = WordPressPublisher(
    site_url="https://example.com",
    username="admin",
    password="xxxx xxxx xxxx xxxx xxxx xxxx"  # 应用程序密码
)

# 测试连接
user_info = wp.test_connection()
print(f"已连接为：{user_info['name']}")

步骤 2：加载并选择分类

从站点自动加载分类

# 从 WordPress 站点获取所有分类
categories = wp.get_categories_with_details()

# 返回类似列表：
# [
#   {'id': 1, 'name': '未分类', 'slug': 'uncategorized', 'count': 5},
#   {'id': 2, 'name': '教程', 'slug': 'tutorials', 'count': 12},
#   {'id': 3, 'name': '云托管', 'slug': 'cloud-hosting', 'count': 8},
# ]

智能分类选择

系统分析内容并选择最合适的分类：

# 分析内容并建议最佳分类
suggested_category = wp.suggest_category(
    content=article_content,
    title=article_title,
    available_categories=categories
)

# 或让用户从可用选项中选择
print("可用分类：")
for cat in categories:
    print(f"  [{cat['id']}] {cat['name']} ({cat['count']} 篇文章)")

分类选择逻辑

1. 精确匹配 - 标题/内容包含分类名称
2. 关键词匹配 - 分类别名与主题关键词匹配
3. 父级分类 - 若无匹配则回退到更广泛的父级分类
4. 创建新分类 - 若无合适分类则创建新分类（需用户批准）

步骤 3：生成 SEO 优化标签

自动标签生成

生成可提高 Google 搜索可见性的标签：

# 基于内容分析生成标签
tags = wp.generate_seo_tags(
    content=article_content,
    title=article_title,
    max_tags=10
)

# 返回类似列表：
# ['n8n 托管', '工作流自动化', '自托管 n8n',
#  '经济型托管', 'Docker 部署', 'Node.js 托管']

标签生成规则

1. 主要关键词 - 始终作为第一个标签包含
2. 次要关键词 - 包含 2-3 个相关术语
3. 长尾关键词 - 包含 3-4 个特定短语
4. 实体标签 - 包含提到的产品/品牌名称
5. 主题标签 - 包含更广泛的分类术语

在 WordPress 中创建/获取标签

# 获取或创建所有标签，返回标签 ID 列表
tag_ids = wp.get_or_create_tags(tags)

步骤 4：将内容转换为古腾堡区块

Markdown 转古腾堡

from scripts.content_to_gutenberg import convert_to_gutenberg

# 转换 Markdown 内容
gutenberg_content = convert_to_gutenberg(markdown_content)

支持的转换

表格转换（对 AI 内容至关重要）

表格被转换为具有正确古腾堡结构：

# 输入 Markdown：
| 功能 | 方案 A | 方案 B |
|---------|--------|--------|
| 价格   | $10    | $20    |

# 输出古腾堡：
<!-- wp:table -->
<figure class="wp-block-table"><table>
  <thead><tr><th>功能</th><th>方案 A</th><th>方案 B</th></tr></thead>
  <tbody><tr><td>价格</td><td>$10</td><td>$20</td></tr></tbody>
</table></figure>
<!-- /wp:table -->

步骤 5：发布前预览

创建预览草稿

# 首先创建为草稿
result = wp.create_draft(
    title="文章标题",
    content=gutenberg_content,
    categories=[category_id],
    tags=tag_ids,
    excerpt="自动生成或自定义摘要"
)

post_id = result['post_id']
preview_url = result['preview_url']
edit_url = result['edit_url']

验证预览

# 获取预览页面以验证渲染效果
preview_content = wp.fetch_preview(post_id)

# 检查问题
issues = wp.validate_rendered_content(preview_content)
if issues:
    print("发现问题：")
    for issue in issues:
        print(f"  - {issue}")

预览检查清单

• [ ] 标题正确显示
• [ ] 所有标题渲染正确（H2、H3、H4）
• [ ] 表格渲染格式正确
• [ ] 列表显示正确（项目符号和编号）
• [ ] 代码块具有语法高亮
• [ ] 图片加载（如有）
• [ ] 链接可点击
• [ ] 分类显示正确
• [ ] 标签在文章中显示

步骤 6：发布文章

发布草稿

# 预览批准后，发布
result = wp.publish_post(post_id)
live_url = result['live_url']

或直接创建并发布

# 在一个调用中完成完整发布工作流程
result = wp.publish_content(
    title="文章标题",
    content=gutenberg_content,
    category_names=["云托管"],  # 按名称，自动解析为 ID
    tag_names=["n8n", "托管", "自动化"],
    status="publish",  # 或 "draft"、"pending"、"private"、"future"
    excerpt="用于 SEO 的自定义摘要",
    slug="自定义-URL-别名"
)

定时发布文章

# 安排未来发布时间
from datetime import datetime, timedelta

publish_date = datetime.now() + timedelta(days=1)
result = wp.publish_content(
    title="定时发布文章",
    content=content,
    status="future",
    date=publish_date.isoformat()
)

步骤 7：验证已发布文章

检查已发布文章

# 验证已发布文章
verification = wp.verify_published_post(post_id)

print(f"实时 URL：{verification['url']}")
print(f"状态：{verification['status']}")
print(f"分类：{verification['categories']}")
print(f"标签：{verification['tags']}")

常见问题及解决方法

完整示例工作流程

from scripts.wp_publisher import WordPressPublisher
from scripts.content_to_gutenberg import convert_to_gutenberg

# 1. 连接
wp = WordPressPublisher(
    site_url="https://xcloud.host",
    username="admin",
    password="xxxx xxxx xxxx xxxx"
)

# 2. 加载分类并选择最佳匹配
categories = wp.get_categories_with_details()
best_category = wp.suggest_category(content, title, categories)

# 3. 生成 SEO 标签
tags = wp.generate_seo_tags(content, title, max_tags=10)

# 4. 转换为古腾堡
gutenberg_content = convert_to_gutenberg(markdown_content)

# 5. 创建草稿并预览
draft = wp.create_draft(
    title="2026 年 7 个最佳 n8n 托管服务商",
    content=gutenberg_content,
    categories=[best_category['id']],
    tags=wp.get_or_create_tags(tags)
)
print(f"预览：{draft['preview_url']}")

# 6. 验证后，发布
result = wp.publish_post(draft['post_id'])
print(f"已发布：{result['live_url']}")

快速参考

API 端点

文章状态

必需文件

• scripts/wp_publisher.py - 主要发布器类
• scripts/content_to_gutenberg.py - Markdown/HTML 转换器
• references/gutenberg-blocks.md - 区块格式参考

错误处理

最佳实践

1. 始终先预览 - 先创建草稿，验证后再发布
2. 使用应用程序密码 - 切勿使用常规 WordPress 密码
3. 选择合适分类 - 有助于网站组织和 SEO
4. 生成相关标签 - 提高 Google 可发现性
5. 验证古腾堡区块 - 确保正确的区块结构
6. 摘要保持在 160 字符以内 - 适合搜索摘要的最佳长度
7. 使用描述性别名 - 在 URL 中包含主要关键词