Notion知识库搜索与页面内容提取|简诗 AI
将以下提示词粘贴到你的 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 页面的完整嵌套正文并转换成结构化格式存储。
- 维护多个项目任务列表的自动化工程师,需要编写脚本对指定数据库执行复杂条件过滤及全量同步。