OmniRoute Notion Context Source 详解把 Notion 工作区变成 Agent 可检索、可写回的知识库【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 支持将 Notion 工作区挂载为 Context Source上下文来源让 LLM Agent 通过内置 MCP Server 的 6 个工具搜索、读取、查询并写回 Notion 页面与数据库。本文基于 docs/frameworks/NOTION_CONTEXT.md 并结合仓库源码完整拆解其加固的 REST 客户端、Token 持久化机制、配置流程、MCP 工具契约与 Scope 权限模型读完后你可以直接完成配置并理解其底层调用链。核心文件与整体架构该集成的事实来源分布在四层每一层职责清晰文件职责src/lib/notion/api.ts加固的 Notion REST 客户端重试、超时、错误分类、消息清洗src/lib/db/notion.tsToken 在 SQLitekey_value表中的持久化open-sse/mcp-server/tools/notionTools.ts6 个 MCP 工具定义含 Zod 输入 schema 与 Scope 声明src/app/api/settings/notion/route.ts设置 REST API保存/校验/断开 Token工具注册与 Scope 接线位于 open-sse/mcp-server/server.ts。整体思路是Notion 的凭据与 API 细节被封装在 OmniRoute 服务端模型只与 MCP 工具交互永远不直接触碰 Notion API——这既简化了 Agent 侧的调用也让凭据、重试、超时策略集中在一个可测试的模块中。集成对象是官方 Notion REST APIhttps://api.notion.com/v1请求头固定携带Notion-Version: 2026-03-11见 api.ts 头部常量。加固的 Notion REST 客户端createNotionClient 返回一个薄客户端6 个方法分别映射到 Notion API 的 6 个端点所有请求都收敛到内部的notionFetch在那里实现了文档中列出的四项加固能力。重试与指数退避notionFetch的循环最多执行MAX_RETRIES 3次尝试重试策略在 api.ts 第 99–155 行 中可见并非所有错误都重试而是按错误类型区分429限流解析错误消息中的 retry-after 提示正则retry after (\d)解析失败则退回到消息中的第一个数字再失败取默认 1 秒等待retryAfter * 1000 2^attempt * 200毫秒后继续5xx服务端错误等待2^attempt * 500毫秒后重试仅在非最后一次尝试时进行401/403/404/400/409认证/未找到/校验/冲突直接抛出不重试——重试这类错误没有意义只会浪费配额网络级异常如 fetch 抛错按2^attempt * 500毫秒退避重试最后一次仍失败则抛出lastError ?? NotionServerError(Exhausted all retries)。55 秒超时每个请求通过AbortController施加TIMEOUT_MS 55000毫秒的超时。如果调用方自身传入了options.signalcombineSignals第 157–167 行会把调用方信号与超时信号合并——任一信号 abort 即中断请求。超时或外部 abort 统一转化为NotionTimeoutError(Notion API request timed out after 55s)避免把浏览器/undici 原始 abort 错误暴露给上层。类型化错误分类classifyNotionError 把 Notion 的{object: error, status, code, message}错误体映射到六个具名错误类错误类触发条件特点NotionAuthError401 / 403403 会前缀Access denied:以区分拒绝原因NotionNotFoundError404—NotionRateLimitError429携带retryAfter数值字段NotionValidationError400 / 409409 会前缀Conflict:NotionServerError≥ 500可触发重试NotionTimeoutErrorAbortController 超时固定 55 秒语义消息清洗在错误消息向上传播前sanitize第 81–83 行会剥除类堆栈片段的模式如at identifier、/path/file.ext:123并截断到 4096 字符防止内部路径与堆栈细节泄露到 MCP 工具返回文本中。Token 存储SQLite key_value 表Notion Token没有任何环境变量通道它持久化在 SQLite 的key_value表中命名空间notion、键integration_token值以 JSON 字符串形式存放。src/lib/db/notion.ts 提供四个函数getNotionToken()读取并JSON.parse任何异常都静默返回nullMCP 调用侧把它解释为未配置setNotionToken(token)INSERT OR IGNORE写入持久化失败不致命注释明确说明失败时 Token 仍可在内存中工作clearNotionToken()按 namespace key 删除getNotionConfig()返回{ token, connected }connected定义为Token 非空且长度大于 0。配置流程Token 是Notion 内部集成internal integrationToken。由于 Notion 的权限模型是基于分享而非工作区级授权的你必须在创建集成后把希望 OmniRoute 访问的页面/数据库逐一分享给该集成工具才能读到它们。方式一仪表盘 Context Sources 页签在 Endpoint 仪表盘的Context Sources页签中NotionSourceCardsrc/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx/dashboard/endpoint/components/NotionSourceCard.tsx)与ObsidianSourceCard并列。卡片显示Connected / Not connected徽标展开后提供密码型输入框占位符ntn_... or secret_...与 Connect 按钮已连接时展示 Token configured. Notion tools are available via MCP. 并给出 Disconnect 按钮。前端逻辑就是对该设置 REST API 的三个方法的直接封装GET 刷新状态、POST 保存、DELETE 断开。方式二设置 REST API# 保存并校验集成 TokenPOST 会发起一次真实测试搜索来验证 curl -X POST http://localhost:20128/api/settings/notion \ -H Content-Type: application/json \ -d {token:ntn_xxx} # 查询连接状态 curl http://localhost:20128/api/settings/notion # 断开清除已存 Token curl -X DELETE http://localhost:20128/api/settings/notion三种方法都要求通过仪表盘认证isAuthenticated未认证返回401 Unauthorized。POST 的行为细节可以从 route.ts 中确认请求体用 Zod schema 严格校验token为 1–500 字符的字符串.strict()拒绝多余字段不合法时返回400及parsed.error.issues校验通过后先setNotionToken落库再立即用该 Token 发起一次1 条结果的测试搜索searchPagesAndDatabases(test, undefined, 1)若 Notion 返回object error的错误体、或调用抛出异常如NotionAuthError服务端会clearNotionToken()把刚写入的 Token 清掉并返回400Token validation failed: invalid token或清洗后的错误消息成功则返回{ connected: true, message: Notion integration token saved and validated }。GET 返回{ connected, hasToken }DELETE 清除 Token 后返回{ connected: false, message: Notion integration disconnected }。所有错误响应都经过sanitizeErrorMessage处理。六个 MCP 工具工具定义在 open-sse/mcp-server/tools/notionTools.ts。每次调用时通过getNotionToken()解析 Token未配置则抛出Notion integration token not configured. Set it in Settings Context Sources.——这个提示在 server.ts 的注册包装 中会被捕获并转成isError: true的工具文本结果Agent 据此可以引导用户去配置。工具Scope说明对应 Notion APInotion_searchread:notion按文本搜索页面与数据库返回标题、ID、URL分页POST /search客户端固定附加filter: { value: page, property: object }notion_get_pageread:notion按 ID 获取页面内容与元数据GET /pages/{pageId}notion_list_block_childrenread:notion列出块/页面的子块块树分页GET /blocks/{blockId}/childrennotion_query_databaseread:notion带可选filtersorts查询数据库Notion API 格式分页POST /databases/{databaseId}/querynotion_get_databaseread:notion获取数据库的 schema/元数据GET /databases/{databaseId}notion_append_blockswrite:notion向已有块/页面追加子块单次最多 100 块PATCH /blocks/{blockId}/children输入参数Zod schemanotion_search—query1–500 字符、pageSize1–100默认 20、startCursor可选notion_get_page—pageId32 位十六进制或 UUIDnotion_list_block_children—blockId、pageSize1–100默认 50、startCursor可选notion_query_database—databaseId、filter可选Notion 过滤器格式、sorts可选数组、pageSize1–100默认 50、startCursor可选notion_get_database—databaseIdnotion_append_blocks—blockId、children块对象数组、after可选定位参数。除 schema 层约束外客户端还做了防御性钳制page_size一律Math.min(pageSize, 100)appendBlocks会children.slice(0, 100)截断到 100 块上限——即使 schema 被绕过也不会超出 Notion API 的硬限制。Scope 权限模型读工具要求read:notion写工具要求write:notion。Scope 强制由 server.ts 中的withScopeEnforcement()实现仅当环境变量OMNIROUTE_MCP_ENFORCE_SCOPEStrue时生效该开关与允许列表在 第 104–110 行 读取。调用方允许 scope 的来源有两个环境变量OMNIROUTE_MCP_SCOPES逗号分隔作为回退或经认证 API Key 携带的 per-key scope 上下文后者优先。Scope 不足时工具不会静默失败而是返回明确提示缺失了哪个 scope、调用方 ID 与来源并记录logToolCall审计条目。完整的 scope 模型参见 MCP-SERVER.md其 README 中也有示例export OMNIROUTE_MCP_ENFORCE_SCOPEStrue export OMNIROUTE_MCP_SCOPESread:notion,write:notion # 按需组合其他 scope注册链路在 server.ts 第 1391–1415 行 中notionTools.forEach将每个工具server.registerTool先inputSchema.parse(args)做入参校验调用 handler 后将结果JSON.stringify(result, null, 2)作为文本返回任何异常统一转为{ content: [{ type: text, text: Error: ... }], isError: true }保证错误信息回到 Agent 上下文而不是让 MCP 会话崩溃。端点边界方法路径用途GET/api/settings/notion返回{ connected, hasToken }POST/api/settings/notion保存并校验集成 TokenDELETE/api/settings/notion断开清除已存 Token需要强调的是这些是仪表盘设置路由不存在面向/v1的公开 Notion 代理端点——Notion 访问只能通过上述 MCP 工具完成这也是该集成与 OmniRoute 常规模型路由路径解耦的原因。典型使用模式结合工具语义四类典型场景知识接地问答Agent 先notion_search工作区再对命中结果notion_get_page读取正文之后才作答——回答引用的是真实内部文档而非模型记忆数据库驱动的工作流对任务/CRM 类数据库用notion_query_database施加 filter sort 查询然后对行数据做汇总或分诊建议先notion_get_database拿到属性 schema 再构造过滤器写回/日志用notion_append_blocks把会议纪要、运行摘要或 Agent 产出追加到已有页面。注意这是append-only语义——工具集不提供删除或就地编辑块的能力属于刻意设计的安全边界结构探索用notion_list_block_children逐层遍历页面块树配合notion_search返回的 URL/ID 定位目标。测试覆盖仓库为该模块保留了完整的测试面可用于验证行为边界tests/unit/notion-api.test.ts — REST 客户端的重试、超时与错误分类tests/unit/notion-tools.test.ts — 6 个 MCP 工具的入参校验与 Token 缺失路径tests/unit/db/notion.test.mjs —key_value表中 Token 的读写清除。相关文档MCP Server — 传输方式、Scope 强制与完整工具清单Obsidian Context Source — 另一个内置 Context SourceMemory System — 持久化会话记忆互补的上下文层自动注入而非工具拉取。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/8 20:45:51 · 阅读 1.2k OmniRoute Notion Context Source 详解：把 Notion 工作区变成 Agent 可检索、可写回的知识库
OmniRoute Notion Context Source 详解把 Notion 工作区变成 Agent 可检索、可写回的知识库【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 支持将 Notion 工作区挂载为 Context Source上下文来源让 LLM Agent 通过内置 MCP Server 的 6 个工具搜索、读取、查询并写回 Notion 页面与数据库。本文基于 docs/frameworks/NOTION_CONTEXT.md 并结合仓库源码完整拆解其加固的 REST 客户端、Token 持久化机制、配置流程、MCP 工具契约与 Scope 权限模型读完后你可以直接完成配置并理解其底层调用链。核心文件与整体架构该集成的事实来源分布在四层每一层职责清晰文件职责src/lib/notion/api.ts加固的 Notion REST 客户端重试、超时、错误分类、消息清洗src/lib/db/notion.tsToken 在 SQLitekey_value表中的持久化open-sse/mcp-server/tools/notionTools.ts6 个 MCP 工具定义含 Zod 输入 schema 与 Scope 声明src/app/api/settings/notion/route.ts设置 REST API保存/校验/断开 Token工具注册与 Scope 接线位于 open-sse/mcp-server/server.ts。整体思路是Notion 的凭据与 API 细节被封装在 OmniRoute 服务端模型只与 MCP 工具交互永远不直接触碰 Notion API——这既简化了 Agent 侧的调用也让凭据、重试、超时策略集中在一个可测试的模块中。集成对象是官方 Notion REST APIhttps://api.notion.com/v1请求头固定携带Notion-Version: 2026-03-11见 api.ts 头部常量。加固的 Notion REST 客户端createNotionClient 返回一个薄客户端6 个方法分别映射到 Notion API 的 6 个端点所有请求都收敛到内部的notionFetch在那里实现了文档中列出的四项加固能力。重试与指数退避notionFetch的循环最多执行MAX_RETRIES 3次尝试重试策略在 api.ts 第 99–155 行 中可见并非所有错误都重试而是按错误类型区分429限流解析错误消息中的 retry-after 提示正则retry after (\d)解析失败则退回到消息中的第一个数字再失败取默认 1 秒等待retryAfter * 1000 2^attempt * 200毫秒后继续5xx服务端错误等待2^attempt * 500毫秒后重试仅在非最后一次尝试时进行401/403/404/400/409认证/未找到/校验/冲突直接抛出不重试——重试这类错误没有意义只会浪费配额网络级异常如 fetch 抛错按2^attempt * 500毫秒退避重试最后一次仍失败则抛出lastError ?? NotionServerError(Exhausted all retries)。55 秒超时每个请求通过AbortController施加TIMEOUT_MS 55000毫秒的超时。如果调用方自身传入了options.signalcombineSignals第 157–167 行会把调用方信号与超时信号合并——任一信号 abort 即中断请求。超时或外部 abort 统一转化为NotionTimeoutError(Notion API request timed out after 55s)避免把浏览器/undici 原始 abort 错误暴露给上层。类型化错误分类classifyNotionError 把 Notion 的{object: error, status, code, message}错误体映射到六个具名错误类错误类触发条件特点NotionAuthError401 / 403403 会前缀Access denied:以区分拒绝原因NotionNotFoundError404—NotionRateLimitError429携带retryAfter数值字段NotionValidationError400 / 409409 会前缀Conflict:NotionServerError≥ 500可触发重试NotionTimeoutErrorAbortController 超时固定 55 秒语义消息清洗在错误消息向上传播前sanitize第 81–83 行会剥除类堆栈片段的模式如at identifier、/path/file.ext:123并截断到 4096 字符防止内部路径与堆栈细节泄露到 MCP 工具返回文本中。Token 存储SQLite key_value 表Notion Token没有任何环境变量通道它持久化在 SQLite 的key_value表中命名空间notion、键integration_token值以 JSON 字符串形式存放。src/lib/db/notion.ts 提供四个函数getNotionToken()读取并JSON.parse任何异常都静默返回nullMCP 调用侧把它解释为未配置setNotionToken(token)INSERT OR IGNORE写入持久化失败不致命注释明确说明失败时 Token 仍可在内存中工作clearNotionToken()按 namespace key 删除getNotionConfig()返回{ token, connected }connected定义为Token 非空且长度大于 0。配置流程Token 是Notion 内部集成internal integrationToken。由于 Notion 的权限模型是基于分享而非工作区级授权的你必须在创建集成后把希望 OmniRoute 访问的页面/数据库逐一分享给该集成工具才能读到它们。方式一仪表盘 Context Sources 页签在 Endpoint 仪表盘的Context Sources页签中NotionSourceCardsrc/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx/dashboard/endpoint/components/NotionSourceCard.tsx)与ObsidianSourceCard并列。卡片显示Connected / Not connected徽标展开后提供密码型输入框占位符ntn_... or secret_...与 Connect 按钮已连接时展示 Token configured. Notion tools are available via MCP. 并给出 Disconnect 按钮。前端逻辑就是对该设置 REST API 的三个方法的直接封装GET 刷新状态、POST 保存、DELETE 断开。方式二设置 REST API# 保存并校验集成 TokenPOST 会发起一次真实测试搜索来验证 curl -X POST http://localhost:20128/api/settings/notion \ -H Content-Type: application/json \ -d {token:ntn_xxx} # 查询连接状态 curl http://localhost:20128/api/settings/notion # 断开清除已存 Token curl -X DELETE http://localhost:20128/api/settings/notion三种方法都要求通过仪表盘认证isAuthenticated未认证返回401 Unauthorized。POST 的行为细节可以从 route.ts 中确认请求体用 Zod schema 严格校验token为 1–500 字符的字符串.strict()拒绝多余字段不合法时返回400及parsed.error.issues校验通过后先setNotionToken落库再立即用该 Token 发起一次1 条结果的测试搜索searchPagesAndDatabases(test, undefined, 1)若 Notion 返回object error的错误体、或调用抛出异常如NotionAuthError服务端会clearNotionToken()把刚写入的 Token 清掉并返回400Token validation failed: invalid token或清洗后的错误消息成功则返回{ connected: true, message: Notion integration token saved and validated }。GET 返回{ connected, hasToken }DELETE 清除 Token 后返回{ connected: false, message: Notion integration disconnected }。所有错误响应都经过sanitizeErrorMessage处理。六个 MCP 工具工具定义在 open-sse/mcp-server/tools/notionTools.ts。每次调用时通过getNotionToken()解析 Token未配置则抛出Notion integration token not configured. Set it in Settings Context Sources.——这个提示在 server.ts 的注册包装 中会被捕获并转成isError: true的工具文本结果Agent 据此可以引导用户去配置。工具Scope说明对应 Notion APInotion_searchread:notion按文本搜索页面与数据库返回标题、ID、URL分页POST /search客户端固定附加filter: { value: page, property: object }notion_get_pageread:notion按 ID 获取页面内容与元数据GET /pages/{pageId}notion_list_block_childrenread:notion列出块/页面的子块块树分页GET /blocks/{blockId}/childrennotion_query_databaseread:notion带可选filtersorts查询数据库Notion API 格式分页POST /databases/{databaseId}/querynotion_get_databaseread:notion获取数据库的 schema/元数据GET /databases/{databaseId}notion_append_blockswrite:notion向已有块/页面追加子块单次最多 100 块PATCH /blocks/{blockId}/children输入参数Zod schemanotion_search—query1–500 字符、pageSize1–100默认 20、startCursor可选notion_get_page—pageId32 位十六进制或 UUIDnotion_list_block_children—blockId、pageSize1–100默认 50、startCursor可选notion_query_database—databaseId、filter可选Notion 过滤器格式、sorts可选数组、pageSize1–100默认 50、startCursor可选notion_get_database—databaseIdnotion_append_blocks—blockId、children块对象数组、after可选定位参数。除 schema 层约束外客户端还做了防御性钳制page_size一律Math.min(pageSize, 100)appendBlocks会children.slice(0, 100)截断到 100 块上限——即使 schema 被绕过也不会超出 Notion API 的硬限制。Scope 权限模型读工具要求read:notion写工具要求write:notion。Scope 强制由 server.ts 中的withScopeEnforcement()实现仅当环境变量OMNIROUTE_MCP_ENFORCE_SCOPEStrue时生效该开关与允许列表在 第 104–110 行 读取。调用方允许 scope 的来源有两个环境变量OMNIROUTE_MCP_SCOPES逗号分隔作为回退或经认证 API Key 携带的 per-key scope 上下文后者优先。Scope 不足时工具不会静默失败而是返回明确提示缺失了哪个 scope、调用方 ID 与来源并记录logToolCall审计条目。完整的 scope 模型参见 MCP-SERVER.md其 README 中也有示例export OMNIROUTE_MCP_ENFORCE_SCOPEStrue export OMNIROUTE_MCP_SCOPESread:notion,write:notion # 按需组合其他 scope注册链路在 server.ts 第 1391–1415 行 中notionTools.forEach将每个工具server.registerTool先inputSchema.parse(args)做入参校验调用 handler 后将结果JSON.stringify(result, null, 2)作为文本返回任何异常统一转为{ content: [{ type: text, text: Error: ... }], isError: true }保证错误信息回到 Agent 上下文而不是让 MCP 会话崩溃。端点边界方法路径用途GET/api/settings/notion返回{ connected, hasToken }POST/api/settings/notion保存并校验集成 TokenDELETE/api/settings/notion断开清除已存 Token需要强调的是这些是仪表盘设置路由不存在面向/v1的公开 Notion 代理端点——Notion 访问只能通过上述 MCP 工具完成这也是该集成与 OmniRoute 常规模型路由路径解耦的原因。典型使用模式结合工具语义四类典型场景知识接地问答Agent 先notion_search工作区再对命中结果notion_get_page读取正文之后才作答——回答引用的是真实内部文档而非模型记忆数据库驱动的工作流对任务/CRM 类数据库用notion_query_database施加 filter sort 查询然后对行数据做汇总或分诊建议先notion_get_database拿到属性 schema 再构造过滤器写回/日志用notion_append_blocks把会议纪要、运行摘要或 Agent 产出追加到已有页面。注意这是append-only语义——工具集不提供删除或就地编辑块的能力属于刻意设计的安全边界结构探索用notion_list_block_children逐层遍历页面块树配合notion_search返回的 URL/ID 定位目标。测试覆盖仓库为该模块保留了完整的测试面可用于验证行为边界tests/unit/notion-api.test.ts — REST 客户端的重试、超时与错误分类tests/unit/notion-tools.test.ts — 6 个 MCP 工具的入参校验与 Token 缺失路径tests/unit/db/notion.test.mjs —key_value表中 Token 的读写清除。相关文档MCP Server — 传输方式、Scope 强制与完整工具清单Obsidian Context Source — 另一个内置 Context SourceMemory System — 持久化会话记忆互补的上下文层自动注入而非工具拉取。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考