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

type

Post

status

Published

date

Apr 28, 2026

slug

codex-skill-notion-publisher-usage-and-implementation

summary

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

📝 主旨内容

💡 一、把 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

安装方式很直接：

安装到 Codex：

安装到 Claude Code：

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

默认配置如下：

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

🧩 三、模板系统怎么工作

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

当前模板分为两类。

1. Notion 默认模板缓存

里面有两个关键文件：

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

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

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

2. 内置备用模板

目前包含这些模板：

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 Code 里运行：

按提示完成 Notion OAuth 授权。

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

然后执行：

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 页面。

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

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

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

创建文章可以这样：

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

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

🖼️ 六、封面和正文插图

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

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

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

不插入正文图片

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

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

手动输入图片 URL

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

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

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

🚀 七、如何使用

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

最直接的方式：

也可以自然语言触发：

执行时大致流程是：

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

询问目标 Notion 数据库。

读取数据库 schema。

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

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

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

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

选择模板策略。

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

输出页面链接。

🧠 实现原理

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

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

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

🧩 标题

🔍 背景

⚙️ 使用方式

🧭 工作流程

🏗️ 实现原理

🔧 关键适配点

✅ 总结

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

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

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

🤗 总结归纳

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

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