# OAuth 连接没有成功时，先定位哪一层失败

返回[首次成功统一入口](README.md)。

适用场景：市场卡片要求 OAuth 2.0 PKCE，但按钮显示“自动重试中”“需重新授权”或连接异常。OAuth 接入能力依赖服务商公开元数据、客户端注册、账号权限与网络条件；插件支持 OAuth 流程，不等于每个市场连接器都已对任意账号开放。

## 授权前提、费用与数据去向

授权前先核对：服务商是否允许公开客户端注册，是否要求企业套餐/管理员批准，本次 scope 是否仅覆盖验收所需的只读权限。记录服务商公布的免费额度或套餐；插件不能确认单次调用的实际费用时，写“未知/待服务商确认”。

授权时，浏览器会与服务商的授权端点通信；后续工具参数和结果会经 DSH Host 与目标 MCP Server 交换。不要因为回调在本机完成就宣称数据不出本机；具体保留和下游处理以服务商文档为准。

## 先看状态，而不是反复点击授权

1. 在“市场”或“已安装”找到对应连接，记录服务商名称、插件版本和按钮状态，不记录 Token/授权码。
2. 展开详情中的诊断，记录 `stage`、稳定 `code`、`checkedAt` 与建议动作。`状态未知` 只表示缺少当前进程的观察证据，既不是成功也不是失败。
3. 若为“自动重试中”，先检查网络与服务商状态，等待有界退避；临时刷新失败不必立刻重新授权。
4. 若明确为“需重新授权”，再从卡片发起新授权。不要向未获授权的企业账号反复尝试登录，也不要把真实凭据交给第三方排障者。

## 按失败阶段处理

| 观察到的阶段或代码 | 首先核对 | 不应推断 |
|---|---|---|
| OAuth 元数据/动态客户端注册；HTTP 403 | 服务商是否允许公开注册、是否需要预登记客户端或企业资格 | 浏览器没弹出就认定插件损坏；重复点击可绕过服务商政策 |
| `auth` / `refresh` | 账号权限、授权范围、Grant 是否失效、服务商撤销状态 | 所有 refresh 错误都意味着永久失效 |
| `dns` / `tls` / `timeout` / `http` | DNS、代理、证书、VPN/专线、白名单、服务端状态 | 授权已成功就说明 MCP 端点也可用 |
| `protocol` | URL 是否为兼容的 MCP Streamable HTTP 端点 | 普通网页登录地址或 REST API 地址可直接替代 MCP URL |
| `host-tools-pending` / `host-status-unavailable` | DSH Host 是否完成工具注册、版本是否能观测状态 | “已保存”就等于工具可调用 |

只有页面明确显示“客户端注册被拒绝、尚未进入浏览器授权”时，才将问题定位到服务商注册政策；这不是用户 OAuth 登录失败。服务商可能要求登记客户端，不能靠重复尝试用户登录绕过。

## 可复现步骤与成功判据

1. 在“市场”打开目标连接器，记录插件版本、连接器名、预期 scope 和开始时间，不记录 Token/授权码。
2. 发起一次授权，在服务商页面核对账号、组织和 scope 后确认。若没有进入浏览器而立即显示客户端注册 403，停止并按服务商政策处理。
3. 回到 DSH，检查连接诊断与最近观察时间。预期：不再是 `auth`/`refresh` 失败；多 Server 卡片没有未解决的“部分异常”。
4. 在当前工作区打开“工具”，确认对应连接/服务的预期只读工具被发现；若未选择 Workspace，只会显示全局连接。最后成功缓存可帮助定位，但不代表当前可调用。
5. 在正常 DSH 会话里，经 Host 审批链执行一个服务商许可的只读任务。预期：得到可辨认结果，且无写入、删除、发布或未批准付费。页面里的“检查连接/重新发现工具”不会执行目标工具。
6. 记录“授权”“工具注册”“业务调用”三个独立结果和时间；任一层缺证据就写“无数据/待验收”。

授权成功、工具注册成功和业务调用成功是三个不同结果。只有全部完成，才可说“首次使用通过”。不要用含真实业务数据、付费或有副作用的调用做公开演示。

## 安全反馈模板

在 [GitHub Issue](https://github.com/duhu2000/dsh-mcp-connector/issues) 提供：DSH 版本、插件版本、连接器名称、操作系统、脱敏的阶段/code、时间、复现步骤，以及“浏览器是否进入授权”“工具是否注册”“只读调用是否成功”三个独立结论。不要上传 Token、API Key、Cookie、授权码、完整 Header、用户信息或本机路径。

完整状态语义见[用户手册：连接诊断](../USER-GUIDE.md#75-如何理解连接诊断)。