# 账号连接诊断

更新时间：2026-09-13 21:09（Asia/Shanghai）

本次实现完成，沿用 I015 账号设置迭代。安装状态见末尾；关联提交信息：`feat: diagnose IM connections with platform APIs`，未发布。

## 实际检查内容

| 渠道 | 实际调用 | 通过所证明的内容 |
| --- | --- | --- |
| 微信 | `POST /ilink/bot/getconfig` | 当前 token 与原用户上下文能取得配置；不调用 getupdates，不消费游标，不发送输入状态 |
| 企业微信 | 现有连接发送 `ping`，等待同 req_id 的回执 | 当前长连接能完成请求响应；无连接时未验证，不另建连接 |
| 钉钉 | `POST https://api.dingtalk.com/v1.0/oauth2/accessToken` | 应用凭据能取得 token；不证明 Stream 接收或消息发送权限 |
| 飞书 / Lark | 对应域名 `/open-apis/auth/v3/tenant_access_token/internal`，随后 `/open-apis/bot/v3/info` | 应用鉴权与机器人身份查询成功；不证明事件订阅正常 |
| QQ | `https://bots.qq.com/app/getAppAccessToken`，随后 `https://api.sgroup.qq.com/gateway` | 应用鉴权与网关查询成功；不额外建立 WebSocket |
| Telegram | `getMe`、`getWebhookInfo` | token 与机器人身份有效，且没有与轮询冲突的 Webhook；不调用 getUpdates |

不会发送聊天测试消息或自动修改平台配置。单项通过不代表整个收发链路通过，结果明确说明实际消息投递权限未验证。微信缺少原聊天身份时不猜测用户 ID；企微没有现有连接时不抢占其他实例。

接口依据来自现有适配器及已安装官方 SDK：钉钉、QQ、微信复用已有请求地址和字段；飞书 tenant token 路径同时核对 `@larksuiteoapi/node-sdk`；企微公开 `WSClient.reply(frame, body, cmd)` 可发指定命令，SDK 的 `handleFrame` 按 req_id 处理回执。独立 `diagnostic_` 前缀避免被 SDK 常规 ping 前缀分支吞掉。本次使用真实 SDK 加模拟传输验证了回执关联，真实企微服务是否接受此帧仍待用户验证。

## 结果与生命周期

- 各项显示通过、失败或未验证、耗时、HTTP 或数字业务码，以及下一步建议。只显示静态结论，不返回 token、用户标识、Webhook 地址或平台原始错误正文。
- 凭据缺失／失效、HTTP 401、403、429、服务端故障、网络失败、超时、无效回包和 Webhook 冲突分别处理；未知业务错误保留数字码并提示核对配置，不猜测具体权限。
- 同账号并发诊断合并为一个请求，执行期间与账号修改串行。执行阶段总等待上限 12 秒；宿主卸载中止等待，不保存过期结果。
- HTTP 不跟随重定向、回包上限 64 KiB。诊断独立获取所需 token，不清空正常收发的 token 缓存。
- 未运行账号只构造查询适配器，不调用 start，不启用消息接收。企微需要用户先恢复现有连接。
- 界面保留明确就绪才计入在线的修复；未知状态不着绿。缺少接收字段时显示无法读取，不误判关闭。
- 新客户端要求后端返回诊断协议标记；旧后端只返回账号快照时提示完整重启 DSH、刷新页面，不将旧快照冒充诊断。

- 评审补修：取密或适配器初始化异常返回 failed / local-state；普通取消返回 unverified / cancelled，仅 TimeoutError 归超时。新增状态 AST 守卫覆盖渠道赋值、条件返回和模板状态。旧后端缺少 receiveConfigured 时账号行开关禁用，并提示重启。

## 管理接口

`POST /api/dsh-im-connect/accounts/:accountId/check`，请求体 `{}`。继续要求 `Content-Type: application/json`、`x-dsh-im-connect-client: 1` 和同源宿主登录 Cookie。

HTTP 200：`{ ok: true, account: AccountView, diagnostics: { version: 1, checkedAt, checks } }`。`ok` 表示诊断请求完成，不代表每项通过。

`checks` 每项包含 `id`、`status`、`reason`；可选 `durationMs`、`httpStatus`、`platformCode`。`status` 为 `passed | failed | unverified`。`checkedAt` 为 ISO 时间，失败项也有对应结果；账号的 `lastCheckedAt` 同步更新，保存失败回滚内存时间。

`AccountView` 保留 `connectionState`、`receiveConfigured`；既有 `receiveEnabled` 继续表示已连接且接收开启。旧响应缺少新增字段时前端采用未知状态。

账号不存在 404；未登录或来源／写入标记非法沿用 401/403；认证不可用 503；内容类型不支持 415；非法 JSON 400；超限 413；内部异常 500。沿用现有认证，不新增公开入口。

本轮新增 reason：`local-state` 表示本地凭据读取或账号初始化失败，`cancelled` 表示检查取消。保持 diagnostics.version = 1，返回结构不变；前端与后端应一起更新以显示对应建议。

## 验证

- 先确认原适配器缺少诊断入口，再实现平台请求。正常与失败测试用模拟 HTTP，不等于真实账号验收。
- 评审补修后全量回归 773 项：748 通过、0 失败、25 项宿主契约环境未配置跳过；包含构建。取密异常与普通取消两项回归先失败，修复后通过。
- 覆盖七渠道请求路径、不发聊天／不启轮询、鉴权失败、平台拒绝、限流、服务错误、超时、无效和超大回包、微信 -14、Webhook 冲突、同账号请求合并与卸载取消。
- 企微测试使用实际 SDK 的 reply 队列、pendingAcks 和 handleFrame，验证成功／拒绝回执及队列释放；模拟的是底层 WebSocket。
- UI 行为覆盖重复点击、加载禁用、跨账号响应、失败反馈、旧后端提示。浏览器检查了 320px、760px 容器中的中英文通过、失败、未验证结果；仅新增组件，未完整启动用户宿主。

## 安装、恢复与阅读顺序

已安装本次接口诊断版到 web Profile，版本仍为 `0.1.46`，依赖指向 `C:\Users\YUJIYU\.dsh\local-packages\im-connect-diagnostic-20260913\michengai-dsh-im-connect-0.1.46.tgz`。管理器、诊断模块、状态模块、六个渠道实现与客户端共 10 个产物 SHA256 与工作区一致，加载清单包含插件。安装成功，包管理器仍提示 peer 依赖警告。未主动重启宿主或发送聊天消息；需要完整退出并重新启动 DSH，再刷新页面测试。此前状态快照包 `im-connect-status-20260913` 保留可供回退。

无需迁移账号、凭据或会话数据。回退时只恢复本次源码和对应产物，或重新安装之前保留的本地包；不回退工作区其他来源的改动。

先读 [迭代总览](00-迭代总览.md)，再读本文；使用说明见 [中文 README](../../../README.zh-CN.md)。

## 评审补修交付

诊断补修提交 `032a088`，CI 提交 `85c8372`；本文档与双语入口纳入 `docs: align bilingual guides and record diagnostic validation`。本轮未安装、未推送或发布。英文入口与中文 README 同步修正开关位置、诊断章节与结果补发层级；发布任务去除显式重复测试，保留 prepublishOnly 构建测试；Release 精确查询标签，仅 404 创建，其他错误终止。双语说明缺失仍拒绝发布。未增加可选冷却，维持同账号并发合并。真实平台验收仍待用户执行。

## 二次评审补修

修正中英 README 的 PowerShell 路径示例为带引号的 `$HOME\Projects`，注明替换为已存在目录。Release 步骤显式关闭原生命令自动异常，由既有 HTTP 状态和退出码分支处理错误。新增接收开关渲染回归，以 AST 提取实际 SettingsPage 按钮，覆盖中英文、旧后端字段缺失禁用及提示、新后端开启/关闭与操作中禁用。产品运行时代码未变化。

验证：接收诊断 UI 测试 4 项全部通过；两份 README 的 PowerShell 代码块解析通过。设置 ErrorActionPreference=Stop 与原生命令异常开关为 true，以真实 Node 子进程模拟 HTTP 输出及退出码，先复现旧版 404 提前中止，修复后确认 200 编辑、404 创建、403/500/网络失败终止。未调用远程发布接口；尚未在 GitHub runner 实测。本次未重跑全量测试，前述 773/748 为上次全量记录。差异检查通过。

本次补修纳入 `fix: harden PowerShell release handling and cover receive controls` 提交；未推送、未安装。

## 0.1.47 发布验证

已完成本地回归、隔离安装与真实宿主连接诊断/消息往返/重启恢复验证。验证边界、结果和截图见 [07-0.1.47发布验证.md](07-0.1.47发布验证.md)。本轮版本和验证记录纳入 `chore: release v0.1.47`；未更新正式 Profile。此前未提交、未发布等描述为当时阶段记录。

0.1.47 已于本轮发布：提交 `3844bf0`，三版 CI 成功，npm 官方 latest 与 GitHub 最新正式 Release 均为 0.1.47；公开包和双语说明核验通过，测试进程已停止。详细数字及真实平台边界见上述发布验证记录。