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会检测「忽略之前指令」「你现在是」等典型的提示词注入模式命中关键威胁的技能会被阻止注册注册与快照通过扫描的技能以名称为键注册进SkillRegistryAgent 执行时通过快照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），仅供参考