fix: route cross-device OAuth through device flow

distribution/agent-install.template.md

@@ -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。
 
 ## 完成后