⌕
← 返回文章
技术分享约 13 分钟阅读

用 Skill 自动发布 Notion 文章：notion-publisher 的用法与实现

这篇文章记录了 notion-publisher skill 的使用方式、适配过程和实现原理：如何让 Codex / Claude Code 通过 Notion MCP 发布文章，并让 OpenClaw 在无 MCP 环境中通过 CLI runtime 调用 Notion API 创建和更新页面。

#工具#开发#agent#LLM

😀

前言：notion-publisher 是一个把文章发布到 Notion 数据库的通用 skill。它现在已经整理成开源仓库，可以同时用于 Codex 和 Claude Code。

这篇文章记录它的使用方式、实现原理、模板系统，以及如何把自己的 Notion 默认模板缓存到本地，减少重复配置和不必要的请求。

📝 主旨内容

💡 一、把 Notion 发文流程沉淀成 skill

一个好用的 skill，不只是“帮我写文章”，而是把重复流程、工具调用和边界规则固定下来。

平时发布一篇 Notion 文章，真正容易出错的地方往往不是正文，而是周边流程：

  • 选择正确的 Notion 数据库

  • 读取数据库 schema，确认字段名和枚举值

  • 根据文章内容生成 slug、summary、category、tags、status

  • 选择封面

  • 选择数据库默认模板或本地模板

  • 调用 Notion MCP 创建或更新页面

notion-publisher 把这些步骤整理成一个可复用 skill。触发后，它会先检查配置，再让用户选择数据库，随后读取 schema，并按照真实字段生成页面属性。这样可以避免把不存在的字段、标签或状态写进 Notion。

🔍 二、开源仓库和安装方式

当前版本已经开源，仓库里只保留通用模板和示例配置，不包含私人 Notion 数据库 ID、页面 ID 或私有模板内容。

GitHub 仓库：

https://github.com/Miraclemin/notion-publisher-skill

安装方式很直接：

git clone https://github.com/Miraclemin/notion-publisher-skill.git
cd notion-publisher-skill

安装到 Codex：

mkdir -p ~/.codex/skills
cp -R notion-publisher ~/.codex/skills/notion-publisher

安装到 Claude Code：

mkdir -p ~/.claude/skills
cp -R notion-publisher ~/.claude/skills/notion-publisher

首次运行时，如果配置文件不存在，skill 会自动创建：

~/.notion_publish/notion-publisher-config.json

默认配置如下：

{
  "default_status": "Draft",
  "template_strategy": "ask_each_time"
}

这里不会保存数据库 ID、页面 ID、文章草稿、标签、分类、封面偏好或 Notion token。数据库和封面每次发布时都会询问，避免误发。

🧩 三、模板系统怎么工作

模板是这个 skill 里最值得复用的部分：它既可以使用 Notion 数据库默认模板，也可以使用本地缓存模板，还可以退回到内置通用模板。

当前模板分为两类。

1. Notion 默认模板缓存

目录：

notion-publisher/templates/notion-defaults/

里面有两个关键文件：

  • catalog.md：模板索引表，用来把 Notion 数据库或模板 ID 映射到本地模板文件。

  • example-article-template.md：缓存模板示例，展示一个 Notion 默认模板同步到本地后应该长什么样。

实际使用时，如果你的数据库默认模板已经缓存到本地，skill 会优先读取本地文件，而不是每次请求 Notion 模板页面。只有当缓存不存在，或者你明确要求“刷新模板 / 同步模板 / 重新读取 Notion 模板”时，才会请求 Notion。

2. 内置备用模板

目录：

notion-publisher/templates/

目前包含这些模板：

  • clean-essay.md：适合观点、思考、方法论文章

  • technical-deep-dive.md：适合工具、代码、架构、实现原理

  • product-update.md：适合功能发布、版本更新、项目复盘

  • knowledge-note.md：适合学习笔记、概念整理、教程

  • minimal-blog.md：适合短文、随笔、轻量记录

这些模板都使用 Notion-flavored Markdown，包含 emoji 标题、callout、quote、toggle、空行分隔等结构。生成正文时，skill 会尽量保留这些视觉样式，而不是把模板压平成普通段落。

模板策略说明

  • ask\_each\_time：每次发文都询问模板策略。

  • use\_cached\_notion\_template：默认使用 Notion 数据库模板创建页面，不直接写正文。

  • generate\_from\_cached\_template：默认使用本地缓存模板生成完整正文。

🛠️ 四、Notion MCP 如何配置

这个 skill 本身不直接连接 Notion，它依赖当前客户端里可用的 Notion MCP 工具。

Claude Code 可以添加 Notion 官方 hosted MCP server：

claude mcp add --transport http notion https://mcp.notion.com/mcp

然后在 Claude Code 里运行：

/mcp

按提示完成 Notion OAuth 授权。

Codex 可以在 ~/.codex/config.toml 中添加：

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

然后执行：

codex mcp login notion

Notion MCP 官方文档：

https://developers.notion.com/docs/mcp

🧰 五、没有 MCP 时如何支持 OpenClaw

OpenClaw 这类环境如果没有 Notion MCP，也可以通过内置 CLI runtime 走 Notion 官方 API。

新版本增加了 notion-publisher/scripts/notion\_publisher.py，它是一个纯 Python 标准库脚本，不依赖 MCP，也不依赖 requests。只要当前环境能执行 shell 命令，并且本地配置了 Notion integration token，就可以创建和更新 Notion 页面。

运行前可以先检测当前平台：

which openclaw 2>/dev/null && echo "PLATFORM=openclaw" || echo "PLATFORM=other"

如果输出 PLATFORM=openclaw，skill 会优先走 CLI runtime；如果是 Codex 或 Claude Code，则优先使用 Notion MCP，MCP 不可用时再回退到 CLI。

CLI 模式需要先创建 Notion internal integration，把目标数据库分享给这个 integration，然后把 secret 保存到本地：

mkdir -p ~/.notion_publish
printf 'NOTION_TOKEN=secret_xxx\n' > ~/.notion_publish/.env

创建文章可以这样：

python3 notion-publisher/scripts/notion_publisher.py publish \
  --data-source-id "collection://DATA_SOURCE_ID" \
  --title "文章标题" \
  --body-file article.md \
  --status Draft \
  --type Post

更新已有文章也已经支持：

python3 notion-publisher/scripts/notion_publisher.py update \
  --page-id "NOTION_PAGE_ID_OR_URL" \
  --mode replace \
  --body-file article.md

--mode replace 会替换全文，接近 MCP 的 replace\_content；--mode append 会在原页面末尾追加内容。CLI 还会把正文图片写成 Notion 原生 image block，所以图片不仅能被博客前端渲染，也应该能在 Notion App 里直接显示。

🖼️ 六、封面和正文插图

新版本把封面和正文插图拆成两个独立确认项：封面每次询问，正文插图可选，图片 URL 必须确认后才插入。

封面不保存偏好，每次发文都会询问。默认推荐真实图片类封面，比如 NASA 或博物馆画作，不再默认使用纯色或大面积纯色背景。只有用户明确要求简单渐变时，才会考虑渐变封面。

正文插图也是可选项。发布时可以选择：

  1. 不插入正文图片

  2. 根据文章标题和摘要搜索图片

  3. 使用自定义关键词搜索图片

  4. 手动输入图片 URL

如果选择搜索图片，skill 会根据标题、摘要和主题生成 2-4 个关键词，使用当前环境可用的 web / image search 能力寻找候选图片。它不会直接把随机 Google Images 缩略图塞进文章，而是优先选择稳定 URL、官方来源、开放授权来源或适合引用的页面图片。

确认后，图片会以 Notion-flavored Markdown 插入正文：

![图片说明](https://example.com/image.jpg)

这个设计的重点是让文章更丰富，但不牺牲可控性：图片要相关、稳定、可访问，并且由用户确认后才进入正文。

🚀 七、如何使用

在 Codex 或 Claude Code 里可以直接触发 /notion-publisher；在 OpenClaw 里则通过 CLI runtime 调用 Notion API。

最直接的方式：

/notion-publisher

也可以自然语言触发：

帮我发布一篇文章到 Notion，主题是我如何构建这个项目。

执行时大致流程是：

  1. 检查配置文件，不存在则自动创建默认配置。

  2. 询问目标 Notion 数据库。

  3. 读取数据库 schema。

  4. 收集标题和正文，或根据主题生成正文。

  5. 推断 slug、summary、category、tags、status。

  6. 每次询问封面，不保存封面偏好。

  7. 询问是否插入正文图片，搜索或手动确认图片 URL。

  8. 选择模板策略。

  9. 根据环境选择 Notion MCP 或 CLI runtime 创建/更新页面。

  10. 输出页面链接。

🧠 实现原理

notion-publisher 的核心是一份结构化的 SKILL.md，加上一组 Notion-flavored Markdown 模板。

SKILL.md 负责告诉 agent：什么时候触发、需要哪些工具、每一步如何处理、哪些信息必须询问用户、哪些字段必须从 schema 读取。

模板文件负责控制正文结构。比如技术文章会有：

  • 🧩 标题

  • 🔍 背景

  • ⚙️ 使用方式

  • 🧭 工作流程

  • 🏗️ 实现原理

  • 🔧 关键适配点

  • ✅ 总结

这让生成出来的 Notion 页面更像正式文章，而不是一段纯文本。

另外，配置文件只保存很少的偏好：

{
  "default_status": "Draft",
  "template_strategy": "ask_each_time"
}

这样既能减少重复选择，又不会把私人数据库、文章内容或 token 写进本地配置，更适合开源和迁移。

🤗 总结归纳

notion-publisher 的价值在于把“写文章到 Notion”这件事拆成稳定流程：读 schema、推断属性、选择模板、创建或更新页面。它把容易重复出错的部分固定下来，同时保留数据库、封面、状态和模板策略的人工确认。现在它既能在 Codex / Claude Code 中通过 MCP 工作，也能在 OpenClaw 这类无 MCP 环境中通过 CLI runtime 调用 Notion API。

如果你经常把内容发布到 Notion，或者希望 Codex / Claude Code 更稳定地帮你管理文章数据库，这类 skill 很适合沉淀成长期工作流。

📎 参考文章

💡

如果你也有固定的 Notion 文章格式，可以把默认模板缓存到 templates/notion-defaults/，再让 skill 按这个结构生成正文。这样每次发文都能保持统一排版和写作风格。

KEEP READING

继续阅读