配置 OAuth 应用

本页使用 Notion 的 OAuth 连接，也称公开连接（Public connection）。已有可用授权客户端的成员直接从第 4 步开始；使用内部连接令牌请阅读访问令牌指南。

如果平台已经提供可用的默认 OAuth 客户端，也可以直接连接账号，无需再为团队创建一套凭证。

1. 创建 Notion OAuth 连接

1. 登录 Notion 开发者后台，确认当前 Notion 工作空间。
2. 在 Connections → New connection 中填写名称，例如 EasyXAI 团队资料。
3. 将 Authentication method 选为 OAuth。
4. 在 Installable in 中选择可安装范围。仅供指定工作空间使用时，选择相应工作空间；需要其他工作空间授权时，按用途选择 Any workspace。创建前确认范围，官方说明该范围创建后不可修改。
5. 在 Redirect URIs 中添加当前 EasyXAI 部署的完整回调地址，确认它显示为已添加的地址项。
6. 检查信息后点击 Create connection。

图 1：真实创建表单，示例未提交。example.com 仅用于说明格式；实际操作请替换为部署管理员提供的地址。

回调地址格式为：

https://<当前环境的回调域名>/v1/asset/integration/oauth/callback

回调域名可能与 EasyXAI 前端域名不同。协议、域名和路径必须与当前服务部署配置一致；资源库页面地址、Notion 页面链接和登录首页都不能替代它。

部分界面将入口分为 Public connections → Create new connection，旧界面可能称 Public integration。请以 OAuth 认证方式为判断依据。创建步骤和安装范围见 Notion 公开连接说明。

2. 配置能力并取得凭证

创建完成后，进入连接的 Configuration，核对 Capabilities，并找到 OAuth client ID 和 OAuth client secret。

读取能力与页面访问范围分别控制：具备 Read content，也只能读取已经授权给该连接的内容。以后更改能力时，受影响成员需要重新授权。详见 Notion 能力说明。

Notion 的 Marketplace 上架是单独流程；本指南不要求把团队连接发布到应用市场。不要套用飞书的“权限标识 → 创建版本 → 发布”步骤。

3. 在 EasyXAI 登记授权应用

1. 切换到目标工作空间，点击资源库 → 扩展 → 应用中心 → Notion。
2. 如未安装，由工作空间管理员点击安装到本团队。
3. 进入自带授权应用 → 添加应用，填写下表并保存。

图 2：名称与 Client ID 为占位示例，未保存。首次保存时必须填写真实 Client Secret；“权限范围”中的灰字是通用占位提示，不是 Notion 权限清单。

不要在权限范围中填写 offline_access、飞书权限标识或截图里的 GitHub 示例。也不要将内部连接令牌填入 Client Secret；它属于另一种连接方式。

保存后确认授权应用处于启用中。编辑已有配置时，Client Secret 留空表示保留原密钥。普通成员看不到此配置页签时，请工作空间管理员处理。

4. 连接自己的 Notion 账号

1. 在当前工作空间打开应用中心 → Notion → 连接账号，点击连接账号。
2. 若有多个授权客户端，先选择团队指定的客户端，再点击一键授权；单一授权方式的页面可能显示前往授权。
3. 在 Notion 授权页确认应用名称，并选择正确的 Notion 工作空间。
4. 点击 Select pages，选择要授权的页面或数据库，再点击 Allow access 完成授权。
5. 返回 EasyXAI 后，到应用中心 → 我的连接检查账号，点击验证应提示“连接正常”。

图 3：本页选择“一键授权”。此图只展示方式选择，未执行新的账号授权。

页面选择器只展示当前用户拥有 Full access（完全访问）、能够授予访问权限的内容；仅能阅读某页，不代表可以将它授权给连接。选择父页面也会影响其下可访问的子页面，请确认范围。相关界面与规则见 Notion 授权说明。

授权应从 EasyXAI 发起，让系统完成回跳和凭据保存。无需手动复制授权码、拼接授权链接或粘贴 OAuth 返回的 Token。

5. 验证接入结果

按资源库同步创建 Notion 数据源，先选刚才授权的一篇文本页面。同步后分别检查标题、文本预览和原文链接。

如果连接正常却找不到页面，先检查页面授权与搜索更新延迟，见常见问题。