将 Notion 用作你的 AI 知识库：完整实战手册
本指南将把你的 ABC Salesbot AI Agent 连接到公司的 Notion 工作区，让团队成员可以在 WhatsApp 上提问，并直接从你的 SOP、政策和文档中获得答案。
1. 概述
使用场景
- 公司信息： “我们公司的使命是什么？”
- HR 政策： “我有多少天假期？”
- SOP： “如何为新客户办理入职？”
- 规范指引： “报销限额是多少？”
前置要求
- 拥有 AI Agent 权限的 ABC Salesbot 账户
- 拥有管理员权限的 Notion 工作区
- 文档已经存放在 Notion 中
所需时间
设置大约需要 30 分钟。
2. 架构
工作原理
团队成员提出问题后，你的 AI Agent 会调用两个基于 Notion API 的自定义工具，然后回复答案并附上来源页面的链接：
- 团队成员在聊天中提问
- AI Agent 在 Notion 中搜索匹配的页面
- AI Agent 获取最匹配页面的内容
- AI Agent 用实际内容回答，并附上 Notion 链接
双工具工作流
Notion API 需要两次独立的调用：
- 第 1 步，
query_notion_pages： 搜索 Notion 并返回页面标题和 ID - 第 2 步，
get_notion_page_content： 从指定页面获取实际内容
为什么需要两个工具？ Notion 的搜索 API 只返回页面元数据（标题、ID），不包含页面内的实际内容。我们需要第二次调用来获取内容。
3. 第 1 步：创建 Notion 集成
3.1 打开 Notion Integrations
- 打开 https://www.notion.so/my-integrations
- 点击 + New integration（新建集成）
3.2 配置集成
- Name（名称）： ABC Salesbot（或你喜欢的名称）
- Logo： 可选，上传你的公司 Logo
- Associated workspace（关联工作区）： 选择你的公司工作区
3.3 设置能力
在 Content Capabilities（内容能力）下启用：
- Read content（读取内容，必需）
在 Comment Capabilities（评论能力）下：
- Read comments（读取评论，可选）
3.4 保存并复制密钥
- 点击 Save
- 点击 Internal Integration Secret 旁边的 Show
- 复制 Internal Integration Secret（内部集成密钥）
- 把它保存在安全的地方，稍后在 ABC Salesbot 中会用到
3.5 配置页面访问权限
关键步骤！你的集成只能访问你明确授权的页面。
- 在集成设置中，点击 Access（访问权限）标签
- 你会看到可以选择集成能访问哪些页面或工作区
- 选择你希望 AI 能够读取的页面：你可以授权特定页面，也可以授权整个工作区
- 点击 Save 或 Update 确认
提示：如果你授权了某个父页面，其下所有子页面也都可以访问。
推荐结构：把所有内容放在一个顶层页面下，例如一个 Company Knowledge Base（公司知识库）页面，其中包含以下子页面：
- 使命、愿景与价值观
- 公司目标
- HR 政策： 休假政策、费用报销、行为准则
- SOP： 客户入职、支持流程、销售流程
- 技术文档： 产品设置、故障排除
授权顶层的 “Company Knowledge Base” 页面后，里面的所有子页面都可以被访问。
4. 第 2 步：在 ABC Salesbot 中创建自定义工具
你需要创建两个自定义工具。
工具 1：query_notion_pages
该工具用于搜索你的 Notion 工作区。
Info（信息）标签：
- Name：
query_notion_pages - Description： Search the company Notion knowledge base for relevant pages. Returns page titles and IDs. After searching, you MUST use get_notion_page_content to fetch the actual content.
- Method： POST
- URL：
https://api.notion.com/v1/search - Enabled： On
- Crawl page： Off
Configurations（配置）标签：
- Username： 留空
- Password： 留空
- API Key： 留空
- Bearer Token： 粘贴你的 Notion 集成密钥
Custom Headers（自定义标头）（每一项都点击 “Add Header” 添加）：
- Notion-Version：
2022-06-28 - Content-Type：
application/json
Parameters（参数）标签（点击 “Add Params” 并填写）：
- Name：
query - Description： The search keywords to find relevant Notion pages
- Type： string
- Default： 留空
- Location： body
- Required： On
点击 Save。
工具 2：get_notion_page_content
该工具用于获取页面的实际内容。
Info（信息）标签：
- Name：
get_notion_page_content - Description： Retrieve the full content of a Notion page using its page ID. ALWAYS use this after query_notion_pages to get the actual text content before answering the user.
- Method： GET
- URL：
https://api.notion.com/v1/blocks/{page_id}/children - Enabled： On
- Crawl page： Off
Configurations（配置）标签：
- Username： 留空
- Password： 留空
- API Key： 留空
- Bearer Token： 粘贴你的 Notion 集成密钥（与工具 1 相同）
Custom Headers（自定义标头）（点击 “Add Header”）：
- Notion-Version：
2022-06-28
Parameters（参数）标签（点击 “Add Params” 并填写）：
- Name：
page_id - Description： The Notion page ID from search results (the "id" field)
- Type： string
- Default： 留空
- Location： path
- Required： On
点击 Save。
重要：保存后再次检查
保存两个工具后，请回头确认两个工具的自定义标头都保存成功了。可能存在第一次保存标头不生效的问题。请检查：
- 工具 1： Notion-Version 和 Content-Type 标头仍然存在
- 工具 2： Notion-Version 标头仍然存在
如果丢失了，请重新添加并保存。
5. 第 3 步：配置系统提示词
从本指南末尾的附录中复制完整的系统提示词，并粘贴到你的 AI Agent 的 System Prompt（系统提示词）字段中。
系统提示词中的关键部分
- Identity & Purpose（身份与目的）： 告诉 AI 它是谁、做什么
- Two-Tool Workflow（双工具工作流）： 必须使用两个工具的关键指令
- Terminology Translation（术语转换）： 将口语化的说法映射到业务术语
- Search Strategy（搜索策略）： 如何高效搜索
- Escalation Guidelines（升级指引）： 何时转给经理、HR 等
- Response Format（回复格式）： 如何组织答案
- Sample Interactions（示例对话）： 优秀回复的范例
自定义清单
使用前，请更新以下部分：
- Terminology Translation： 加入你公司特有的术语
- 升级联系人： 更新部门名称和联系人
- 示例对话： 加入与你的文档相关的示例
6. 第 4 步：测试
运行以下测试，验证一切正常。
测试 1：基础搜索
提问：“What is our company mission?”
预期行为：
- AI 使用 “mission vision” 调用
query_notion_pages - AI 从结果中提取 page_id
- AI 用该 page_id 调用
get_notion_page_content - AI 回复实际的使命宣言，并附上 Notion 链接
测试 2：政策问题
提问：“How many days annual leave do I get?”
预期行为：
- AI 搜索与休假相关的页面
- AI 获取页面内容
- AI 给出具体答案并附上链接
测试 3：术语转换
提问：“What's my commission?”（而你的文档中写的是 “fees”）
预期行为：
- AI 将 “commission” 转换为 “fees”
- AI 找到并返回相关内容
测试 4：未找到内容
提问：“What's the pet policy?”（假设该政策不存在）
预期行为：
- AI 搜索后没有找到任何内容
- AI 如实说明没有找到
- AI 给出替代建议（询问经理、HR）
成功标准
- AI 调用了两个工具
- AI 给出的是实际内容，而不只是页面标题
- AI 在回复中附上了 Notion 链接
- AI 能够得体地处理 “未找到” 的情况
7. 故障排除
错误：“missing_version”
报错信息：Notion-Version header failed validation, Notion-Version header should be defined。
解决方法： 在 Configurations 标签中添加自定义标头 Notion-Version，值为 2022-06-28。
错误：“unauthorized” 或 “invalid_token”
报错信息：API token is invalid。
解决方法：
- 在 Notion integrations 中重新生成令牌
- 将新令牌复制到 Bearer Token 字段
- 确认令牌前后没有多余的空格
错误：“object_not_found”
报错信息：Could not find page with ID: xxxxx。
解决方法： 该页面没有共享给你的集成。前往 Notion，打开该页面，通过 Connections（连接）添加你的集成。
错误：“invalid_request_url”
报错信息：Invalid request URL。
解决方法： 在工具设置中关闭 “Crawl page” 开关。
AI 只返回页面标题，不返回内容
原因： AI 没有调用第二个工具。
解决方法：
- 检查系统提示词中是否包含双工具指令
- 让
get_notion_page_content的描述更明确 - 用更强硬的指令测试：“After searching, you MUST call get_notion_page_content”
搜索没有结果
可能的原因：
- 页面没有共享给集成
- 搜索词与页面内容不匹配
- 缺少 Notion-Version 标头
解决方法：
- 确认页面已共享（在 Notion 中检查 Connections）
- 尝试更宽泛的搜索词
- 检查 Configurations 标签中的标头
AI 不做术语转换
原因： 系统提示词中没有该术语，或 AI 忽略了指令。
解决方法：
- 将缺失的术语加入 Terminology Translation 部分
- 让术语部分在系统提示词中更突出
- 考虑使用更强的模型（用 GPT-4o 替代 GPT-4.1 mini）
模型推荐
- GPT-4.1 mini： 可靠性约 70-80%，成本最低，适合预算有限的简单知识库
- GPT-4o mini： 可靠性约 85%，成本低，性能均衡
- GPT-4o： 可靠性约 95%，成本中等，适合需要高准确率的复杂知识库
- GPT-4.1： 可靠性约 95%，成本中等，适合复杂的多步骤任务
8. 附录：完整系统提示词
将下方折叠区内的全部内容复制到你的 AI Agent 的 System Prompt（系统提示词）字段中，然后根据你的公司情况自定义术语和升级联系人。
以下系统提示词请保持英文原样粘贴到产品中，请勿翻译。
快速参考卡
设置清单
- 在 notion.so/my-integrations 创建一个 Notion 集成
- 复制集成密钥（Bearer Token）
- 将你的 Notion 页面共享给该集成
- 创建工具 1：
query_notion_pages（POST 到/v1/search） - 创建工具 2：
get_notion_page_content（GET 到/v1/blocks/{page_id}/children） - 为两个工具都添加标头
Notion-Version: 2022-06-28 - 粘贴系统提示词
- 用 “What is our company mission?” 进行测试
工具速查
- query_notion_pages： POST 到
https://api.notion.com/v1/search，关键参数query（body） - get_notion_page_content： GET 到
https://api.notion.com/v1/blocks/{page_id}/children，关键参数page_id（path）
必需的标头（两个工具都需要）
- Notion-Version：
2022-06-28 - Content-Type：
application/json（仅工具 1）