Agent Skills
返回列表
Notion知识库搜索与页面内容提取|简诗 AI

Notion知识库搜索与页面内容提取|简诗 AI

知识管理 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_fccf428b/notion-search-retrieve。

技能介绍

要解决的问题

在 Notion 里做数据集成时,常见痛点有四处:全工作区内容分散,很难确认哪些页面或数据库已开放给集成;数据库查询需要按多个字段组合筛选时,手写逻辑繁琐且容易出错;列表接口只返回一批数据,手动翻页经常漏掉后续记录;页面正文嵌套在块结构中,递归读取时要么丢失子块、要么把递归深度开得过深导致请求量爆炸。

技能如何工作

notion.search() 用于在当前集成可见的范围内发现页面和数据库。集成只能访问显式共享给它的内容,空查询返回全部已共享项,但新共享的页面需要等待索引刷新,会出现短暂延迟。

数据库层通过 notion.databases.query() 做结构化查询,过滤条件支持 and/or 组合逻辑。属性类型与运算符的对应关系需要查阅技能资料里的 filter-operators 参考文件。

列表类接口全部使用 has_more 与 next_cursor 的游标分页。想拿到完整结果集,需要循环拉取直到游标耗尽,不能假设单次响应包含全部数据。

页面正文靠 notion.pages.retrieve() 获取元信息,再通过 notion.blocks.children.list() 递归读取子块。技能包内置三个助手:queryAllPages() 负责收集全部记录行;extractProperties() 用 switch 覆盖全部 15 种属性类型做类型化提取;getPageContent() 执行带 maxDepth 守卫的递归块遍历。

取数深度要按需选择。只需要扁平记录列表时,用 queryAllPages() 即可,跳过块遍历这一层开销。当需要读取段落、折叠列表、嵌套列表等正文时,再调用 getPageContent(),并把 maxDepth 设置为内容实际嵌套的最大深度。每多一层递归,API 调用次数会成倍增长。

适用边界与注意点

  • 页面或数据库必须通过 Notion Share 菜单显式共享给该集成,模板之外的共享入口需要人工确认。
  • 列表接口严格遵循游标分页,不要信任单批返回的完整性,循环退出条件必须依赖 has_more 判断。
  • 类型转换之前先检查 properties 字段拿到的实际对象形态,避免把 PartialPageObject 当作完整 PageObjectResponse 直接使用。
  • 正文提取结果不完整时,优先检查 has_children 是否为 true,同时适当提高 maxDepth 来覆盖更深嵌套。
  • 高频读取场景建议把 page_size 调到 100,减少翻页次数;遇到限流时读取 Retry-After 响应头来做退避。

使用场景

  • 在全工作区搜索页面和数据库,快速定位所需目标的共享位置。
  • 对指定数据库应用复合过滤器(and/or),精确筛选符合条件的记录集。
  • 处理列表接口的游标分页循环,确保获取所有匹配结果而不遗漏。
  • 递归读取页面的块树结构,提取包含嵌套块与段落的完整正文内容。

适合人员

  • 搭建内部知识库仪表盘的数据工程师,需要通过 API 定期拉取 Notion 结构化数据以生成报表。
  • 开发企业级搜索工具的后端开发者,需要跨工作区定位包含特定关键字或属性的页面与数据库。
  • 构建自动化日志归档系统的开发者,需要提取 Notion 页面的完整嵌套正文并转换成结构化格式存储。
  • 维护多个项目任务列表的自动化工程师,需要编写脚本对指定数据库执行复杂条件过滤及全量同步。