fix: route cross-device OAuth through device flow

docs/architecture.md

@@ -8,11 +8,11 @@
                                                              └─ 薪福通
 ```
 
-支持远程 MCP 和标准 OAuth 的宿主直接连接网关，不安装客户端运行时。只有宿主缺少远程传输或 OAuth 能力时，才使用本地 Bridge 把 stdio 转换为远程 Streamable HTTP；Bridge 只保存用户自己的短期 access/refresh token，不包含企业密钥、不读取审批上游，也不监听端口。
+支持远程 MCP 和标准 OAuth，且用户能完成宿主所注册回调的场景直接连接网关，不安装客户端运行时。若宿主使用 `127.0.0.1`/`localhost` 回调，授权页必须在 Agent 所在设备打开。宿主缺少远程传输/OAuth 能力，或用户通过 SSH、无头终端、Messenger 等方式跨设备交互而无法完成本机回调时，使用本地 Bridge 把 stdio 转换为远程 Streamable HTTP，并通过可跨设备的 device-code 登录。Bridge 只保存用户自己的短期 access/refresh token，不包含企业密钥、不读取审批上游，也不监听端口。
 
 ## 客户端安装边界
 
-默认安装仅在宿主中登记远程 HTTPS MCP URL。OAuth 客户端注册、PKCE、Token 保存和刷新均由宿主的标准 MCP 实现负责，终端不需要 Node/npm、Bridge 或项目安装器。网关的 MCP `instructions` 与工具描述提供业务工作流，终端修改本地提示不能绕过服务器的身份和写前校验。
+同机回调可达时，默认安装仅在宿主中登记远程 HTTPS MCP URL。OAuth 客户端注册、PKCE、Token 保存和刷新均由宿主的标准 MCP 实现负责，终端不需要 Node/npm、Bridge 或项目安装器。安装 Agent 必须按实际回调拓扑选择路径：能够显示 URL 不等于能够完成回调；回调是 loopback 且用户会在另一台设备打开时直接选择兼容 Bridge。网关的 MCP `instructions` 与工具描述提供业务工作流，终端修改本地提示不能绕过服务器的身份和写前校验。
 
 兼容发行物只为不支持远程 MCP/OAuth 的宿主保留。它不使用全局 npm prefix：首次安装器以固定 Ed25519 公钥验证 schema v3 清单和 artifact SHA-256，并把内置依赖展开到稳定的用户目录。Windows/Linux/macOS 引导可复用系统 Node 或安装经官方哈希校验的固定私有 Node，不改 PATH、不要求管理员权限。发布物优先使用国内 Gitea 和 Node 固定版本源，自建 HTTPS/官方源作为受同一签名或哈希保护的备用。
 
@@ -82,7 +82,7 @@ Agent 面向统一审批语义，不直接理解钉钉 `processInstanceId/taskId
 
 撤回接口若返回 `XFTSYS*` 服务异常或网络级异常，网关会立即只读复核本人单据状态：已撤回则返回 `revoked`，仍为待审批则返回带 `postWriteVerified` 的 `failed`，无法明确归类才返回 `outcome_uncertain`。任何分支都不会自动重试写操作。
 
-截至 `1.1.0-rc.13`，薪福通撤回仍是实验能力：当前企业真实调用 `approve/recall` 会返回 `XFTSYS9999`，写后复核确认单据仍为待审批，尚无成功样本。该限制不影响薪福通查询、审批处理或发起审批；正式版不得把“接口已接通”表述为“撤回已验证成功”。
+截至 `1.1.0-rc.14`，薪福通撤回仍是实验能力：当前企业真实调用 `approve/recall` 会返回 `XFTSYS9999`，写后复核确认单据仍为待审批，尚无成功样本。该限制不影响薪福通查询、审批处理或发起审批；正式版不得把“接口已接通”表述为“撤回已验证成功”。
 
 薪福通创建或撤回需要复核时，`approval_get_submission_status` 先用服务器派生的本人员工号和单据详情双重确认目标属于当前用户的已发起单据，再返回状态名称和精简流程历史。只有实时状态仍为 `1（待审批）` 才签发新的短期、用户绑定 `revokeId`；已通过、草稿、拒绝或已撤回单据都不会获得撤回引用。该工具不返回审批正文，也不触发写操作。
 

docs/deployment.md

@@ -37,7 +37,7 @@ https://approval.justconn.top/oauth/dingtalk/callback
 
 创建接口必须保持权限校验开启。网关统一提交 `APPRV_PEND`，并在写后实时读取本人单据状态：进入待审批时提供撤回引用；按企业流程规则即时通过时返回 `completed`，不提供撤回引用且禁止重复提交。
 
-`1.1.0-rc.13` 中薪福通撤回仍标记为实验能力：权限和调用契约已接通，但当前企业真实请求返回 `XFTSYS9999`，尚未取得成功样本。网关会写后复核并禁止自动重试。面向试用用户时必须保留这一说明；若业务要求撤回必须稳定可用，应等待薪福通定位后再升级为正式能力。
+`1.1.0-rc.14` 中薪福通撤回仍标记为实验能力：权限和调用契约已接通，但当前企业真实请求返回 `XFTSYS9999`，尚未取得成功样本。网关会写后复核并禁止自动重试。面向试用用户时必须保留这一说明；若业务要求撤回必须稳定可用，应等待薪福通定位后再升级为正式能力。
 
 ## 首次凭证配置
 
@@ -117,9 +117,9 @@ release/
 https://approval.justconn.top/downloads/dingmcp/install.md
 ```
 
-公开 `install.md` 是远程优先的短安装说明。Agent 应按宿主官方方式注册名为 `dingtalk-approval` 的远程 Streamable HTTP MCP，URL 为 `https://approval.justconn.top/mcp`，并由宿主使用标准 OAuth 元数据、动态客户端注册和 PKCE 登录。该路径不下载 Node/npm、Bridge 或 Skill；网关 MCP `instructions` 已提供完整业务规则。登录后只读调用 `approval_list_todos(source=all, limit=1)`，钉钉 OA 与薪福通都为 `ok` 才算验收通过。
+公开 `install.md` 是按回调拓扑选择路径的短安装说明。同机浏览器能够完成宿主回调时，Agent 应按宿主官方方式注册名为 `dingtalk-approval` 的远程 Streamable HTTP MCP，URL 为 `https://approval.justconn.top/mcp`，并由宿主使用标准 OAuth 元数据、动态客户端注册和 PKCE 登录。该路径不下载 Node/npm、Bridge 或 Skill；网关 MCP `instructions` 已提供完整业务规则。登录后只读调用 `approval_list_todos(source=all, limit=1)`，钉钉 OA 与薪福通都为 `ok` 才算验收通过。
 
-仅当宿主明确缺少远程 MCP 或标准 OAuth 能力时，`install.md` 才引导到 `compat-install.md`。兼容页保留签名客户端、平台引导、Skill、stdio MCP、独立登录、更新、卸载和故障恢复步骤。Windows PowerShell 产物必须带 UTF-8 BOM，Node 探测使用外层双引号/内层单引号，避免 PowerShell 5.1 吞掉传给原生程序的双引号。
+宿主缺少远程 MCP/标准 OAuth，或 loopback 回调与用户打开授权页的设备不一致时，`install.md` 引导到 `compat-install.md`，无需先尝试一次必然失败的远程登录。兼容页保留签名客户端、平台引导、Skill、stdio MCP、可跨设备的 device-code 登录、更新、卸载和故障恢复步骤。Windows PowerShell 产物必须带 UTF-8 BOM，Node 探测使用外层双引号/内层单引号，避免 PowerShell 5.1 吞掉传给原生程序的双引号。
 
 兼容 Windows 下载优先使用 `curl.exe`，从系统代理变量继承代理，并设置 10 秒连接超时、20 秒低速判定和 90 秒单源总时限；没有 curl 才以 `Invoke-WebRequest -TimeoutSec 90` 兜底。Node 固定版本制品仍按阿里云、npmmirror、官方源顺序尝试并强制校验官方 SHA-256。项目 artifact 由 Ed25519 清单和 SHA-256 保护；来源失败可换源，签名或哈希不符必须立即停止。
 

docs/release-checklist.md

@@ -8,9 +8,9 @@
 - `release:build`、`test-bundle:build` 和 `release:verify` 成功，`SHA256SUMS` 校验通过，发行物不包含 `.secrets`、`.runtime`、数据库、私钥或机器私有路径。
 - 国内 Gitea 首选源与自建 HTTPS 备用目录的 `manifest.json`、`manifest.sig` 和全部安装附件逐文件哈希一致；黑盒测试包及动态提示词只要求自建目录可用。连续部署同一 Tag 必须复用既有 Release 和固定 `createdAt`，不得重复创建或因测试包时间戳产生哈希漂移。模拟首选源网络失败/404 后能从备用源完成首次安装和更新，模拟首选源返回错误哈希或签名时必须立即停止而不换源。
 - Nginx bootstrap 只开放 ACME challenge；正式站点启用 HSTS，mutable 发行文件返回 `no-cache`，客户端 tgz 才返回 immutable。连续两次部署时公开目录始终对应一个完整签名清单，旧版本保留数符合策略。
-- 从新生成的公开 `install.md` 按宿主官方方式注册远程 `https://approval.justconn.top/mcp`；确认不下载 Node/npm/Bridge、不要求本地命令，并能通过 Protected Resource / Authorization Server Metadata、DCR 和 PKCE 完成宿主原生 OAuth。
+- 从新生成的公开 `install.md` 验证两条决策路径：同机浏览器可完成回调时注册远程 `https://approval.justconn.top/mcp`，确认不下载 Node/npm/Bridge、不要求本地命令，并能通过 Protected Resource / Authorization Server Metadata、DCR 和 PKCE 完成宿主原生 OAuth；SSH/无头/Messenger 跨设备打开授权页且宿主使用 loopback 回调时，不先尝试必然失败的远程登录，直接选择兼容 Bridge。
 - 远程 OAuth 后可发现全部 12 个业务工具，`approval_list_todos(source=all, limit=1)` 中钉钉 OA 与薪福通均为 `ok`；网关重启后宿主能刷新或重新授权，用户身份仍由服务端 Token 决定。
-- `install.md` 只有在能力缺失时才链接 `compat-install.md`。用至少一个只支持 stdio 的宿主验证兼容安装可发现 `approval_login` 加 12 个业务工具，且不产生第二套用户身份。
+- `install.md` 只有在远程能力缺失或本机 OAuth 回调对用户不可达时才链接 `compat-install.md`。用至少一个只支持 stdio 的宿主和一个跨设备 loopback 场景验证兼容安装可发现 `approval_login` 加 12 个业务工具，device-code 链接可在另一台设备打开，且不产生第二套用户身份。
 - 在未安装 Node 的干净 Windows x64/ARM64、Linux x64/ARM64、macOS Intel/Apple Silicon 环境验证兼容引导。确认固定版本、国内镜像回退、哈希失败即停止、私有 Node 不改 PATH；至少每类操作系统一次端到端，其余架构由 CI/制品校验覆盖。
 - 在 Windows PowerShell 5.1 验证生成的 `.ps1` 具有 UTF-8 BOM，中文可解析，Node 版本和代理能力探测不会因原生程序参数引号被吞而失败；确认 `.zip` 仅去除一次扩展名，解压目录与 `node-v<version>-win-<arch>` 完全一致。Windows 下载优先 `curl.exe` 并继承 `HTTPS_PROXY`；连接 10 秒、低速 20 秒或总计 90 秒触发明确失败换源，不得出现 300 秒静默等待。
 - 兼容安装继续验证 stdout 只有最终 JSON、stderr 有阶段进度；模拟离线 npm 超时、外部终止、死亡锁、staging 和并发安装，确认明确失败、安全恢复和零并发写入。父进程含 Node 代理选项时，npm 子进程不得继承 `--use-env-proxy`。