fix: route cross-device OAuth through device flow

2026-08-19 02:05:07 +00:00
parent 7e2a01c913
commit 2aa78aebd9
12 changed files with 39 additions and 28 deletions
@@ -1,6 +1,6 @@
 # 钉钉审批兼容客户端安装任务

-仅当当前 Agent 明确不支持远程 Streamable HTTP MCP 或标准 OAuth 时，才使用本兼容安装。支持远程 MCP 的宿主应返回主安装页并直接连接 `{{GATEWAY_URL}}`，不要安装本地 Bridge。
+仅当当前 Agent 明确不支持远程 Streamable HTTP MCP、标准 OAuth，或用户无法在宿主本机 OAuth 回调所在设备打开授权页面时，才使用本兼容安装。即使宿主支持远程 MCP，只要它使用 `127.0.0.1`/`localhost` 回调，而用户通过 SSH、无头环境或 Messenger 在另一台设备操作，就应使用本地 Bridge 的可跨设备 device-code 登录；同机回调可以完成时才返回主安装页直接连接 `{{GATEWAY_URL}}`。

 用户把本文件或本文件的链接交给你，即表示授权你为当前用户安装或更新“钉钉审批”兼容客户端、Skill 和名为 `dingtalk-approval` 的 MCP。该授权不包含同意、拒绝、退回、撤回或发起任何审批。

@@ -6,14 +6,17 @@

 ## 默认安装

-1. 检查当前 Agent 是否支持远程 **Streamable HTTP MCP** 和 MCP 标准 **OAuth 2.0**。按能力判断，不要按 Agent 品牌判断。
-2. 若支持，按宿主官方方式新增或更新连接器：
+1. 先同时检查两项条件：
+   - 当前 Agent 支持远程 **Streamable HTTP MCP** 和 MCP 标准 **OAuth 2.0**；
+   - 用户打开授权页面的设备能够完成宿主注册的 OAuth 回调。若回调地址是 `127.0.0.1` 或 `localhost`，用户必须在运行 Agent 的同一台设备上打开页面。通过 SSH、无头终端或 Messenger 操作远程 Agent，而用户会在手机或另一台电脑打开链接时，不满足此条件。
+   按实际能力和交互环境判断，不要按 Agent 品牌判断。若无法确定，只问用户一个问题：是否会在运行 Agent 的这台设备上打开授权页面。
+2. 仅当两项都满足时，按宿主官方方式新增或更新连接器：
   - 名称：`dingtalk-approval`
   - URL：`{{GATEWAY_URL}}`
   - 传输：Streamable HTTP
   - 认证：OAuth（允许宿主使用服务端发现元数据和动态客户端注册）
 3. 不要安装 Node.js、npm、本地 Bridge、DWS 或浏览器自动化；不要索取 AppKey、AppSecret、AuthoritySecret、CorpId、userId、员工号、Cookie、Token 或其他企业凭证。
-4. 让宿主发起标准 OAuth 登录，把宿主返回的授权页面交给用户本人确认。不得代替用户点击授权，也不得声称链接已通过其他消息通道发送。
+4. 让宿主发起标准 OAuth 登录，并确保用户在能够完成该回调的设备上本人确认。不得代替用户点击授权，也不得声称链接已通过其他消息通道发送。若此时发现宿主使用本机回调而用户只能跨设备打开链接，应停止等待并改用下面的兼容安装，不要把不可完成的链接交给用户反复尝试。
 5. 连接成功后调用一次只读 `approval_list_todos`，参数为 `source="all"`、空搜索、`limit=1`。只有响应中的钉钉 OA 与薪福通来源都为 `ok`，才报告安装完成。不得在安装验证中执行任何审批写操作。
 6. 若宿主需要重启或重新加载才能识别新连接器，按其官方机制操作；不要因为等待加载而改装本地 Bridge。

@@ -21,14 +24,14 @@

 ## 兼容安装

-只有在宿主明确不支持远程 Streamable HTTP MCP，或不能完成 MCP 标准 OAuth 时，才使用本地 STDIO Bridge：
+只有在宿主明确不支持远程 Streamable HTTP MCP、不能完成 MCP 标准 OAuth，或用户无法在宿主本机回调所在设备打开授权页面时，才使用本地 STDIO Bridge：

 `{{COMPAT_INSTALL_URL}}`

 备用地址：
 {{COMPAT_INSTALL_MIRROR_URLS_MARKDOWN}}

-不要先尝试兼容安装来“提高成功率”。远程连接失败时应先报告宿主给出的具体错误；只有确认属于能力缺失，才进入兼容路径。
+本地 Bridge 使用可跨设备完成的 device-code 登录，授权页面可以通过当前对话发给用户并在手机或另一台电脑打开。不要在同机回调明确可用时先安装 Bridge 来“提高成功率”；若已经明确是 SSH、无头或跨设备交互，应直接进入兼容路径，不必先制造一次必然失败的远程 OAuth。

 ## 完成后

@@ -4,9 +4,9 @@

 - 测试包：`{{BUNDLE_URL}}`
 - SHA-256：`{{BUNDLE_SHA256}}`
- 模式：远程 Streamable HTTP MCP + 宿主原生 OAuth；一次钉钉登录同时覆盖钉钉 OA 与薪福通，必须完整验证两个审批源
+- 模式：同机回调可达时使用远程 Streamable HTTP MCP + 宿主原生 OAuth；跨设备且宿主使用 loopback 回调时使用本地 Bridge + device-code。一次钉钉登录同时覆盖钉钉 OA 与薪福通，必须完整验证两个审批源

-安装必须从包内的 `install.md` 进入。默认不得安装 Node/npm 或本地 Bridge；只有宿主明确不支持远程 MCP 或标准 OAuth 时，才按其中链接的 `compat-install.md` 走签名兼容安装，并在报告中说明能力缺口。
+安装必须从包内的 `install.md` 进入。同机回调可达时不得安装 Node/npm 或本地 Bridge；只有宿主明确不支持远程 MCP/标准 OAuth，或用户无法在宿主 loopback 回调所在设备打开授权页时，才按其中链接的 `compat-install.md` 走签名兼容安装，并在报告中说明选择原因。

 只通过安装后的 `dingtalk-approval` MCP 读取和处理审批业务，不使用上游接口旁路。验证一次登录、钉钉 OA 与薪福通的待办、详情和动作能力；任何来源显示 `disabled` 都应视为发行配置错误并停止测试。真实写操作仅限用户明确确认的一次同意；可从任一来源选择，但不得因其中一方不可用而跳过。不要真实拒绝或退回。若结果为 `outcome_uncertain`，禁止自动重试。