ghost-blog

Ghost 博客管理

通过 Admin API 管理 Ghost CMS 文章和标签。

设置

1. 安装依赖

cd .claude/skills/ghost-blog/scripts
uv venv
uv pip install -r requirements.txt

2. 配置环境

cd .claude/skills/ghost-blog/scripts
cp .env.example .env
# Edit .env with your Ghost credentials

.env 文件：

GHOST_URL=https://your-blog.ghost.io
GHOST_ADMIN_KEY=your-key-id:your-secret-key
GHOST_API_VERSION=v5.0

获取 Admin API Key：

1. 前往 Ghost Admin → Settings → Integrations
2. 创建自定义集成
3. 复制 Admin API Key（格式：id:secret）

3. 验证设置

cd .claude/skills/ghost-blog/scripts && uv run python ghost_core.py

快速入门

列出文章：

python scripts/posts_browse.py --status draft
python scripts/posts_browse.py --tag news --featured

管理单篇文章：

python scripts/posts_crud.py get --id POST_ID
python scripts/posts_crud.py create --title "New Post" --html "<p>Content</p>"
python scripts/posts_crud.py publish --id POST_ID

批量操作：

python scripts/posts_bulk.py publish --filter "status:draft" --execute
python scripts/posts_bulk.py add-tag --filter "status:published" --tag "archive" --execute

管理标签：

python scripts/tags_manage.py list
python scripts/tags_manage.py create --name "Tutorial"

分发规则

用户意图	脚本	示例命令
测试、运行测试	pytest	cd scripts && uv run pytest -v
列出文章、显示草稿、筛选文章	posts_browse.py	--status draft --tag news
获取文章、阅读文章、显示文章	posts_crud.py get	--id xxx 或 --slug xxx
创建文章、新建文章、撰写文章	posts_crud.py create	--title "..." --html "..."
更新文章、编辑文章、修改文章	posts_crud.py update	--id xxx --title "..."
删除文章、移除文章	posts_crud.py delete	--id xxx --confirm
发布文章、发布草稿	posts_crud.py publish	--id xxx
取消发布文章	posts_crud.py unpublish	--id xxx
批量发布、发布所有草稿	posts_bulk.py publish	--filter "..." --execute
批量取消发布	posts_bulk.py unpublish	--filter "..." --execute
为文章添加标签、给文章添加标签	posts_bulk.py add-tag	--filter "..." --tag xxx --execute
从文章移除标签	posts_bulk.py remove-tag	--filter "..." --tag xxx --execute
列出标签、显示标签	tags_manage.py list	（无需选项）
创建标签、新建标签	tags_manage.py create	--name "..."
删除标签、移除标签	tags_manage.py delete	--slug xxx --confirm

脚本

脚本	用途
ghost_core.py	共享功能：JWT 身份验证、HTTP 客户端、错误处理
posts_browse.py	列出、筛选、搜索文章
posts_crud.py	单篇文章的 CRUD 操作
posts_bulk.py	批量操作（发布、标签、精选）
tags_manage.py	标签的 CRUD 操作

筛选语法（NQL）

Ghost 使用 NQL 进行筛选：

# Status
status:draft
status:published
status:scheduled

# Tags (use slug, not name)
tag:news
tags:[news,tutorial]

# Featured
featured:true

# Combine (AND)
status:published+featured:true

# Combine (OR)
status:draft,status:scheduled

注意： posts_browse.py 中的 --tag 选项既接受标签名称，也接受标签 slug。它会通过 API 查询自动将名称解析为 slug。

从 Markdown 文件创建文章

从 Markdown 文件（例如，博客系列）创建文章时：

import markdown
from ghost_core import api_request

# 1. Convert Markdown to HTML
md_content = open('article.md').read()
html_content = markdown.markdown(md_content, extensions=['extra', 'nl2br'])

# 2. Create post with source=html (CRITICAL for Ghost 5.0+)
post_data = {
    'title': 'My Post',
    'html': html_content,
    'status': 'draft',
    'tags': ['my-tag']
}
response = api_request('POST', 'posts/',
                       data={'posts': [post_data]},
                       params={'source': 'html'})  # Required!

重要： Ghost 5.0+ 使用 Lexical 编辑器格式。source=html 参数会告知 Ghost 将 HTML 转换为 Lexical。若不使用此参数，文章内容将为空！

修复内部链接

如果 Markdown 文件中包含 [Title](other-file.md) 这类内部链接，请在创建文章后将其替换为 Ghost slug：

LINK_MAP = {
    'old-file.md': '/new-ghost-slug/',
}

html = html.replace('href="old-file.md"', 'href="/new-ghost-slug/"')

安全功能

• 批量操作：默认使用预览模式

• 删除操作：必须使用 --confirm 标志

• API 版本：使用 Ghost v5.0 API

• HTML 转换：自动添加 source=html 参数，以兼容 Ghost 5.0+

测试

设置测试环境

cd .claude/skills/ghost-blog/scripts
uv venv
uv pip install -r requirements.txt

运行测试

cd .claude/skills/ghost-blog/scripts && uv run pytest -v

运行并生成覆盖率报告

cd .claude/skills/ghost-blog/scripts && uv run pytest -v --cov=. --cov-report=term-missing

故障排除

错误	原因	解决方案
"No virtual environment found"	缺少 venv	在 scripts 目录中运行 uv venv
"Failed to spawn: pytest"	缺少依赖	运行 uv pip install -r requirements.txt
"GHOST_URL not set"	缺少 .env	将 .env.example 复制为 .env 并进行配置
"GHOST_ADMIN_KEY invalid format"	密钥格式错误	密钥必须采用 id:secret 格式
"UnauthorizedError"	API 密钥无效	检查密钥是否有效且具备相应权限
"UPDATE_COLLISION"	帖子已修改	重试操作（会自动重新获取 updated_at）
帖子内容为空	缺少 source=html	Ghost 5.0+ 要求使用 source=html 参数
标签筛选结果为 0	使用名称而非 slug	使用标签 slug，或让脚本解析
标签列表返回 HTTP 422	参数无效	不要使用 include=count.posts 或 order
链接指向 .md 文件	内部 Markdown 链接	创建帖子后，将链接替换为 Ghost slug

参考资料

• Ghost Admin API 文档

• NQL 筛选参考