SuperAPI AI 工具集

add-oauth-provider

编程与开发

查看项目

更新于 10-16 06:28

技能介绍

用途

add-oauth-provider 用于把一个新的提供方加入 treg 的 OAuth 注册表。这里的注册表路径指的是 treg 自己持有已注册应用(平台批准)的情形,用户只需选择提供方而无需提供任何凭据。与之相对,BYO 模式(POST /oauth/start 由调用方自带 client_id/secret)已经支持任何 OAuth2 提供方,无需改代码。只有在 treg 持有或愿意去申请对应平台批准时,才应在此添加提供方。

主要能力与代码改动

需要按顺序完成以下全部改动,跳过任何一步都会产生一个在 /oauth/providers 看起来正常、但在测试覆盖不到的地方失败的提供方:

  1. 凭据 → src/treg/config.py:在 Settings 中添加 <name>_client_id / <name>client_secret,从 TREG<NAME>_CLIENT_ID / _SECRET 读取。当平台用同一个应用服务多个产品时可复用已有凭据对,例如四个 Google 提供方加 YouTube 共用 google_client_id,因为 Google 的验证与 API 审计是按 Cloud 项目而非 OAuth 客户端划分的。

  2. 提供方 → src/treg/oauth_providers.py:添加 OAuthProvider 并在 REGISTRY 中注册(容易遗漏)。能力是累加超集,绝不互换,例如:read 为 [READ_SCOPES],post 为 [*READ_SCOPES, UPLOAD](post 包含 read),manage 为 [READ_SCOPES, UPLOAD, WRITE](manage 包含 post)。satisfied_capabilities() 是集合包含判断,因此非累加的 write 会产生一个能写却报告“无读取”的连接。default_capability 为最宽(作用域最多)的那个。当平台把作用域拆分时也应拆分能力:YouTube 需要 read/post/manage,因为上传视频与编辑或删除视频是不同的 Google 作用域,合并会导致能发布却无法修改。按提供方的特殊点:对拒绝 Google 的 access_type/prompt 的提供方(LinkedIn、Slack、X)使用 auth_params={};X 需要 pkce=True + token_endpoint_auth_method="client_secret_basic";当需要携带第二份凭据时使用 extra_credential_(如 Google Ads 的 developer token)。

  3. 发现(该连接作用于哪个账号):设置 discover_path / discover_key / discover_id_field / discover_label_field。标签与 id 字段为点路径(dig),因此支持嵌套值,如 discover_label_field="snippet.title"。当列表与数据 API 不在同一主机时用 discover_base_url。当行嵌套一层时用 discover_nested_key。当列表只返回裸 id、需要第二次调用获取可读名称时用 enrich*。discover_path 中可带查询字符串——发现过程不传 params。若凭据作用于整个账号,则留空不设,UI 会显示“whole account”而非空选择器。

  4. probe_path——健康检查与 Tools 中的“Use”预填:对 base_url(注意不是 discover_base_url)做一次廉价的已认证 GET。没有它,工具会永远显示“unchecked”,Try 面板打开时为空。优先选择返回人类可识别字段的路径,并使其与第 5 步的 sample path 保持一致——openUse 优先使用 health_check.path 而非 sample map,两者不同会导致重连后预填内容静默变化。

  5. 仪表盘 → src/treg/web/index.html:提供方行、Connect 按钮和各选择器均由 listing() 数据驱动,新提供方无需改 UI,但:新的能力名称必须加入 capLabel / capHelp(约第 2762 行),未知名称会渲染为裸键加“Requests the x scopes.”;samplePath(约第 3024 行)是主机到路径的硬编码映射,用于尚无 health_check 的工具,应添加该主机以便在探针存在前已供应的工具也能在 Try 面板预填。

  6. 测试:tests/test_oauth_providers_m3.py::test_every_provider_is_registered 断言了一组精确的服务名集合,需要加入你的提供方,否则测试失败。随后运行 uv run --with pytest-xdist pytest -n auto -q(完整测试套件,因为注册表涉及健康检查、工具与连接)。

平台侧工作

代码只需一个下午,审批却需要数周,因此应并行而非串行推进。包括:在触碰同意屏幕前先在项目上启用 API(作用域选择器通常只列出已启用 API 的作用域);添加所需作用域,只申请能演示的;重定向 URI 必须精确匹配 {TREG_PUBLIC_URL}/oauth/callback;在平台对敏感作用域设门槛处进行验证/应用审核;以及独立的产品审计(如 YouTube 的合规审计与配额扩展、Business Profile API 访问、Google Ads developer token、LinkedIn 的 Community Management API)。

验证提交方面:应用名、主页、隐私政策与演示视频必须一致,同意屏幕品牌是审核员的比对基准,不一致会被例行拒绝;隐私政策必须明确列出该平台数据并链接平台的 ToS 与提供方的隐私政策;演示视频必须展示每个申请作用域的实际使用,且在同意 URL 中可见 client id。

限制与注意事项

资料中列出了若干代价高昂的坑:绝不申请无法演示的作用域(“申请作用域超出演示内容”是标准拒绝理由;YouTube 的 youtubepartner 需要 YouTube CMS 账号才能发起调用);没有 refresh_token 的短期令牌等于已失效的连接——Meta 的授权码交换返回 1-2 小时用户令牌且从不签发 refresh_token,因此未设置 long_lived_exchange=True 的提供方其连接会在被使用前就失效,而额外调用 grant_type=fb_exchange_token 可换来约 60 天(Meta 用户令牌的上限),且仍无法无人值守续期,应像 LinkedIn 那样通过 needs_reconnect 暴露而非假装自动修复;发布状态为“Testing”时刷新令牌 7 天后过期,会使连接每周失效,应在信任任何连接前确认应用处于 In production;“尚未验证此应用”的过渡页在审批前属正常,可通过 Advanced 点过;作用域选择器按作用域 URL 而非产品名过滤,如 yt-analytics.readonly 不含“youtube”字符串,可用“manually add scopes”框;TREG_PUBLIC_URL 决定 redirect_uri 而非浏览所用端口;health_check 在连接时附加,为已连接工具添加 probe_path 需其重新连接才生效;httpx 在传入 params(即使是 [])时会替换 URL 的查询字符串,_probe 用 copy_add_param 合并正是为此,不要“简化”回去;.ttable .tn 为 white-space:nowrap 且 .ttable-wrap 为 overflow:hidden,.tn 单元格中的长文本会使表格变宽并裁剪操作按钮;测试上游必须在模块作用域定义,否则声明在测试函数内的路由会返回 422。

验证方式

运行完整测试套件:uv run --with pytest-xdist pytest -n auto -q;启动本地环境:scripts/dev-local.sh up(参见 .agents/skills/dev-local)。随后在仪表盘中依次执行:Connect → 能力选择器以通俗英文可读 → 同意 → 账号/频道选择器显示真实名称(而非裸 id)→ #tools → Use → Send 返回实时数据。只有最后一步能同时证明凭据、绑定、代理与 base URL 都正确。