OpenFang 内置 Notion 技能指南：用 Agent 智能管理工作区、数据库与 API 自动化-创锋一号

OpenFang 内置 Notion 技能指南：用 Agent 智能管理工作区、数据库与 API 自动化

【免费下载链接】openfangOpen-source Agent Operating System项目地址: https://gitcode.com/gh_mirrors/op/openfang

导读

本文围绕 OpenFang 仓库中内置的notion技能（即 crates/openfang-skills/bundled/notion/SKILL.md）展开，讲解如何让 Agent 以 Notion 专家的身份组织工作区、设计数据库、构建模板、管理内容，并通过 Notion API 与内置功能自动化工作流。读完本文，你将掌握 OpenFang 中 prompt-only 技能的内部原理（SKILL.md 如何被解析、注入 Agent 系统提示词并经过安全扫描），以及一套可直接落地的 Notion 工作区治理方法论。

Notion 技能在 OpenFang 中的定位与加载方式

notion是 OpenFang 随二进制内置的 61 个技能之一，属于prompt-only（提示词型）技能：它不携带可执行代码，而是把专家知识写进 SKILL.md 正文，在 Agent 启动时注入系统提示词，指导 LLM 直接调用内置工具来完成 Notion 相关操作。

从源码看，技能通过编译期宏嵌入二进制，见 crates/openfang-skills/src/bundled.rs：

("notion", include_str!("../bundled/notion/SKILL.md")),

该技能以 YAML frontmatter + Markdown 正文的形式存在（这是 OpenClaw 兼容格式），frontmatter 中的name与description是 Agent 注册和检索该技能的依据。SKILL.md 会被 crates/openfang-skills/src/openclaw_compat.rs 中的convert_skillmd_str解析为SkillManifest：正文存入prompt_context，运行时类型固定为PromptOnly，来源标记为Bundled。加载时，crates/openfang-skills/src/registry.rs 的load_bundled会先对提示词内容执行 prompt injection 安全扫描，只有通过检查的技能才会注册进SkillRegistry。

在运行时层面，crates/openfang-skills/src/loader.rs 对PromptOnly类型技能的处理方式是：返回一条提示信息，告知 LLM「指令已在系统提示词中，请直接使用内置工具」，而不是派生子进程执行代码。

核心原则：按层级组织信息

SKILL.md 首先为 Agent 确立了四条工作准则，这也是任何 Notion 工作区治理的起点：

信息层级化组织：层级顺序为 Workspace（工作区）> Teamspace（团队空间）> Page（页面）> Sub-page（子页面）或 Database（数据库），一切内容都要在这个层级中找到自己的位置。
结构化信息用数据库，而非罗列式页面：凡是需要查询、筛选、排序的信息（任务、Bug、客户记录等），都应该建成数据库，而不是用一整页项目符号堆砌——数据库才能支持 Notion API 的结构化查询。
为可发现性而设计：使用清晰的命名约定与一致的页面结构，让团队成员（以及后续的 Agent）能够快速定位所需内容。
保持工作区整洁：定期归档过期内容，对重复性结构使用模板，避免工作区无限膨胀。

这四条原则背后是「信息架构先行」的思路：先决定信息放在哪里、以什么形态存在，再考虑怎么写内容。

数据库设计：选择合适的视图与属性

SKILL.md 为数据库设计给出了三条具体指导，分别对应视图、属性类型和模板：

1. 按工作形态选择视图类型。Notion 数据库支持多种视图，不同视图服务于不同使用场景，Agent 应根据业务形态为用户推荐合适的视图：

视图	适用场景
Table（表格）	数据录入、批量浏览
Board（看板）	Kanban 工作流、状态流转
Calendar（日历）	基于日期的条目（会议、截止日期）
Gallery（画廊）	视觉化内容（图片、作品集）
Timeline（时间线）	项目规划、排期

2. 有意识地使用属性类型。属性（Property）是数据库的字段定义，类型选择直接决定后续查询能力：

Select/Multi-select：用于固定的分类维度，例如状态（未开始/进行中/已完成）、优先级、部门；
Relation：用于关联两个数据库，例如「任务 → 项目」；
Rollup：用于跨数据库计算聚合值，例如统计某项目下所有任务的完成率；
Formula：用于派生字段，例如根据日期属性自动计算截止剩余天数。

3. 用链接数据库替代数据复制。在相关页面上创建链接数据库（filtered views，即带筛选条件的视图），而不是把同一份数据复制到多个位置——前者保证单一数据源，后者必然导致不一致。

4. 为重复出现的条目类型使用数据库模板。会议记录、项目简报（project brief）、Bug 报告这类高频条目，应当沉淀为数据库模板，让创建动作标准化。

页面结构：为可扫描性与一致性而设计

对于非数据库类的页面内容，SKILL.md 给出了五条结构规范，核心目标是「可扫描、可导航、不重复」：

每个主要页面以简短摘要或目的说明开头：让读者（和 Agent）在进入页面 30 秒内理解「这一页是干什么的」。
一致使用 H1/H2/H3 标题：标题层级既是排版规范，也是 Notion 自动生成目录（Table of Contents）的基础。
用 callout 块承载重要提示、警告和要点：callout 在视觉上与正文分离，适合放置「注意」「警告」类信息。
用 toggle 块折叠不需要所有人看到的细节内容：例如背景说明、附录、展开式补充资料。
嵌入相关数据库、书签和链接页面，而非复制信息：与数据库设计原则一致，优先引用、禁止复制。

Notion API：程序化操作的关键细节

SKILL.md 明确了 Agent 在程序化操作 Notion 时应遵循的 API 使用方式，这一节是最具可操作性的部分，值得展开：

认证方式

内部集成（Internal integrations）：仅用于当前工作区，适合团队内部工具和 Agent 自动化；
公开集成（Public integrations）：面向对外分发场景，例如需要覆盖多个工作区的通用应用。

核心操作接口

页面创建、数据库查询与内容更新均通过 Notion API 完成；
数据库查询使用POST /v1/databases/{id}/query，在请求体中携带filter与sorts参数实现筛选与排序；
页面创建使用block children API写入富文本内容块，支持标题、段落、列表、callout、toggle 等块类型。

典型的数据库查询请求体结构如下（filter 与 sorts 位于 body 中）：

{ "filter": { "property": "状态", "select": { "equals": "进行中" } }, "sorts": [ { "property": "优先级", "direction": "descending" } ] }

速率限制与重试

速率限制：Notion API 的平均限制为3 个请求/秒，Agent 必须控制请求频率，避免在批量操作时触发限流；
重试策略：实现带**指数退避（exponential backoff）**的重试逻辑，遇到限流（HTTP 429）或临时性错误时自动退避重试，而不是立即重试或直接放弃。

这两点对 Agent 自动化尤其重要：LLM 驱动的操作常常产生突发请求，缺少限速和退避逻辑的自动化脚本很容易被 Notion 临时封禁接口访问。

工作区组织：从团队 Wiki 到例行维护

SKILL.md 给出了一套可复制的工作区搭建清单：

创建团队 Wiki，主页清晰链接关键资源：主页相当于工作区的导航中枢，应集中放置高频入口；
用 Teamspace 划分业务域：按团队或职能拆分（例如 Engineering、Marketing、Operations），避免单一空间内内容混杂；
标准化常用文档模板：会议记录、项目简报、RFC、复盘（retrospective）等高频文档统一模板，降低创建成本；
设置周期性内容评审与归档提醒：通过定期提醒驱动内容治理，防止工作区腐化。

需要规避的常见陷阱

SKILL.md 在最后专门列出了四条反模式，Agent 在提供建议时应主动规避：

页面嵌套不要超过 3~4 层——层级过深会导致信息难以被发现；
避免使用内联数据库（inline database）——当全页数据库配合链接视图更清晰时，不要图省事用内联数据库；
避免跨页面复制内容——使用同步块（synced blocks）或链接数据库替代；
不要在一开始过度设计工作区结构——先保持简单，根据实际使用情况迭代演进，这符合「结构跟随使用」的原则。

在 OpenFang 中使用该技能：CLI 与 Agent 配置

notion技能开箱即用（随二进制内置，无需安装），但理解技能系统的使用方式有助于你将其接入自定义 Agent：

查看与体检：openfang doctor会校验内置技能加载情况并扫描提示词注入风险，相关实现见 crates/openfang-cli/src/main.rs。

技能管理命令：OpenFang CLI 提供了一组 skill 子命令（见 crates/openfang-cli/src/main.rs 附近的命令定义）：

# 安装技能（本地目录、FangHub 名称或 git URL） openfang skill install <source> # 列出已安装技能 openfang skill list # 移除技能 openfang skill remove <name> # 搜索技能 openfang skill search <query> # 交互式创建技能脚手架 openfang skill create

在 Agent 清单中引用技能：在 agent 清单（如agents/目录下的agent.toml）的skills字段中声明所需技能，内核会在 Agent 启动时加载对应技能的提示词与工具，与 Agent 基础能力合并。技能安装到~/.openfang/skills/后由SkillRegistry统一管理，同名用户技能会覆盖内置技能，完整机制见 crates/openfang-skills/src/registry.rs 及 docs/skill-development.md。

源码级原理解析：SKILL.md 是如何变成 Agent 能力的

为了让你真正理解这个技能「为什么是这样工作」，这里梳理一遍 OpenFang 的技能流水线（全部有源码佐证）：

编译期嵌入：bundled.rs 通过include_str!把 61 个 SKILL.md 编译进二进制，notion位列其中；
解析与转换：openclaw_compat.rs 的parse_skillmd_str校验 YAML frontmatter 定界符并解析出name/description/config等字段，正文作为prompt_context保留；convert_skillmd_str 将其转换为SkillManifest（运行时类型PromptOnly、来源Bundled）；
安全扫描：registry.rs 在加载内置技能时也会执行防御性扫描，verify.rs 中的scan_prompt_content会检测「忽略之前指令」「你现在是」等典型的提示词注入模式，命中关键威胁的技能会被阻止注册；
注册与快照：通过扫描的技能以名称为键注册进SkillRegistry，Agent 执行时通过快照（snapshot）获取技能列表；
提示词注入：内核在 Agent 启动时把技能的prompt_context合并进系统提示词，LLM 据此获得 Notion 专家知识并直接调用内置工具执行操作——对于 prompt-only 技能，loader.rs 不会派生子进程，这正是它轻量、安全、开箱即用的原因。

结语

notion技能是 OpenFang「以专家提示词扩展 Agent 能力」的典型样本：通过 crates/openfang-skills/bundled/notion/SKILL.md 这一份文档，Agent 即可获得完整的 Notion 工作区治理方法论（层级组织、数据库设计、页面规范、API 操作与陷阱规避）。如果你想为团队定制 Notion 工作流，完全可以参照 docs/skill-development.md 编写自己的 SKILL.md——它会经过同样的解析、安全扫描与注入流水线，成为你的专属 Agent 能力。

【免费下载链接】openfangOpen-source Agent Operating System项目地址: https://gitcode.com/gh_mirrors/op/openfang

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析