From ae68bb02418db5b39c0d0283ccfe342ab6326969 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Tue, 13 Oct 2026 19:41:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20=E5=A5=91=E7=BA=A6=20v0.90=20?= =?UTF-8?q?=E2=80=94=E2=80=94=20=E6=B8=A0=E9=81=93=E8=BF=9E=E6=8E=A5?= =?UTF-8?q?=E6=80=81=E4=B8=89=E6=80=81=EF=BC=88=E5=8F=AF=E9=80=89=20pendin?= =?UTF-8?q?g/ready/reason=20+=20connected=20=E8=AF=AD=E4=B9=89=E6=94=B6?= =?UTF-8?q?=E7=B4=A7=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 登记 POST /admin/channels/open|close 响应与 GET /admin/channels 平台行/账号行新增的三个可选键，并写明 connected 由「动作被受理」纠正为「真实连接状态」这一行为变更（老客户端若只看 2xx 会继续骗人）。新增 §2.4(d) 字段级说明；C19/C20 两行标注；计数不变（14 + 25 + 40 = 79）。 --- Docs/api-client.md | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/Docs/api-client.md b/Docs/api-client.md index 7f519af..afa9be3 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -1,6 +1,6 @@ # Cyrene v2 客户端 API 契约 -> **契约版本：`v0.89`**（上一版 `v0.88`，其条目见 §6；`v0.87` / `v0.86` / `v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 +> **契约版本：`v0.90`**（上一版 `v0.89`，其条目见 §6；`v0.88` / `v0.87` / `v0.86` / `v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 > **读者**：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等**跨平台客户端开发者**。 > **唯一真源 = 当前代码**（`internal/services/gateway/*` 等）。本文档由代码逐条核对得出；与代码不符时**以代码为准**，并回改本文档。 > **旧的超详细版已归档、只读**：`Docs/archive/api-client.v0.65.md`（412 KB，含 v0.28→v0.65 全部历史条目）与 `Docs/archive/api-reference.v0.65.md`（170 KB，后端全量字段级文档）。归档的原因是**结构性臃肿 + 历史条目并列 + 长期漂移**；本文档**不复制**那段历史，需要考古时去归档。 @@ -255,8 +255,8 @@ | C16 | POST | `/api/v1/admin/llm` | 添加/更新 LLM provider（写 `models.json` + 热重载） | | C17 | POST | `/api/v1/admin/llm/test` | 连通性测试 | | C18 | POST | `/api/v1/admin/llm/reset-from-env` | 重置为 env 默认（切片 R1，v0.62；body 必须 `{"confirm":true}`，否则 `400` 且一个字节都不动；审计 `llm.resetFromEnv`） | -| C19 | POST | `/api/v1/admin/channels/open` | 打开渠道（v0.66 增 `accountId`，见下注） | -| C20 | POST | `/api/v1/admin/channels/close` | 关闭渠道（v0.66 增 `accountId`，见下注） | +| C19 | POST | `/api/v1/admin/channels/open` | 打开渠道（v0.66 增 `accountId`，见下注；**v0.90 起 `connected` 为真实状态**，并按需回可选 `pending`/`ready`/`reason`） | +| C20 | POST | `/api/v1/admin/channels/close` | 关闭渠道（v0.66 增 `accountId`，见下注；**v0.90 起 `connected` 取真实 `IsConnected()`**） | | C21 | POST | `/api/v1/admin/channels/test` | 渠道连通测试 | | C22 | GET | `/api/v1/admin/channels/{platform}/login-qr` | 取登录二维码（获取凭据，故 owner-only） | | C23 | GET | `/api/v1/admin/channels/{platform}/login-status` | 查扫码登录状态 | @@ -291,7 +291,7 @@ > - `id` 与 `empty=1` 同时给出 ⇒ `400 bad_request`；**两者都缺 ⇒ `400 bad_request`**（绝不把「id 缺失」默认解释成删无 id 条目 —— 那是一次没有字面证据的批量删除）。`?empty=` / `?empty=0` / `?empty=false` 一律是「否」。 > - 响应：`{data:{persisted, path, platform, accountId, empty, removed}}`（`empty`/`removed` 是 v0.66 新增）；`removed` = 实际删除的条目数。删空后平台键整个消失（与按 id 删除的收尾口径一致）。 -### 2.4 v0.67 登记的管理面（渠道事件查询 + 账号在线状态）—— **(a) 已实现 / (b) 已实现**；v0.78 追加 **(c) iLink 凭据三态** +### 2.4 v0.67 登记的管理面（渠道事件查询 + 账号在线状态）—— **(a) 已实现 / (b) 已实现**；v0.78 追加 **(c) iLink 凭据三态**；v0.90 追加 **(d) 渠道连接态三态** > ⚠️ **本节两项都已落地**（账号在线状态 `52dac45`；渠道事件查询面本切片 E6）：形状取自设计文档（`design/26 §4.5`、`§2.6`），落地时已按代码核对。**§2.0 的计数（12 + 11 + 40 = 63）原本不含本节端点**；两个渠道事件端点已登记进 `routes.go`（`owner|admin` 档），下版改文档时应把它们并入 §2.1/§2.2 并更新计数。**本行留在此处仅为与 v0.67 冻结版对照**。 @@ -334,6 +334,15 @@ - 🔴 **同域但未实现的面**：`GET /api/v1/admin/channels` 的 `accounts[]` 元素**尚未**带**每账号** `authState`/`authDetail`（缺 `AdminChannelAccount` 两字段与合并器的接线）—— 见 §7.2。 - ⚠️ **未确证（真机）**：真实 `errcode=-14` 至今**从未在日志里观测到** ⇒ `rejected` 分支只有单测 / httptest 证据，**没有真机证据**（见 §7.4-26）。 +#### (d) 渠道连接态三态：`pending` / `ready` / `reason`（**v0.90 新增，已实现**） + +- **出现位置**：`POST /api/v1/admin/channels/open` 与 `.../close` 的响应体、`GET /api/v1/admin/channels` 的**平台行**与 `accounts[]` **账号行**（三处同名同义）。 +- **三个键都是可选的，取不到就整键缺席**（同 `needsRescan` / `lastError` 口径）：`connected:true` 时，或适配器没有这条状态面时，`pending` / `ready` / `reason` 一律不出现。 +- `reason` 只可能在 `pending:true` 时出现，是**已脱敏**的原因短句（`access_token` 等凭据绝不出现在其中）。 +- **判据是结构化字段**（适配器自报的闭集状态），不是正文、不是提示词 —— 客户端据此把卡片画成「已连接 / 连接中（原因）/ 就绪待接入 / 未连接」四档。 +- **口径归属**：**适配器自报**（`ConnectOutcome`，网关经类型断言探测）；核心 `sdk.Channel` 契约**刻意不扩展** ⇒ 没实现该状态面的平台响应**逐字节不变**。 +- ⚠️ **为什么 `ready` 不带 `reason`**：它本来就不是坏消息（监听已就绪、就等对面来连），给它编一个原因等于把「等接入」说成「出问题了」。 + --- ## 3. WebSocket `/ws/chat` @@ -1487,7 +1496,26 @@ curl -s -X POST -H "X-API-Key: $KEY" \ > 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。 > 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。** -### v0.89（当前契约版本） +### v0.90（当前契约版本） + +**「渠道连接态三态」版 —— 管理面新增三个可选键，并把 `connected` 的语义从「动作被受理」纠正为「真的连上了」**（依据：2026-10-13 主人报「改了 QQ 适配器配置后点连接，卡片仍显示未连接，却提示已连接」；实现推库 `b4d55f4`。） + +- 🔴 **纠正的谎**：`POST /api/v1/admin/channels/open` 此前在 `ch.Connect` 返回 nil 后**硬编码** `connected:true`。而 `Connect` 返回 nil 只说明「这次调用没有致命失败」——**ws+client 首连失败刻意非致命**（OneBot 实现可能比 Cyrene 后启动，重试交给读循环），**ws+server 则只需监听就绪**，这两种情况下 `IsConnected()` 都是 `false`。前端又只按「请求成功」写死「已连接」⇒ 管理面把「后端受理了」说成了「渠道连上了」。 +- **三态闭集（口径落在适配器自身，网关只做映射）**： + +| 状态 | 含义 | 线上投影 | +|---|---|---| +| `connected` | 真连上（client 拨号成功 / HTTP 传输已装配就绪） | `connected: true`，三个可选键**全缺席** | +| `pending` | 已在后台重试、当前未连上（仅 ws+client 有重试循环） | `connected: false` + `pending: true` + `reason` | +| `ready` | 已绑定监听、就绪等对端接入（ws+server）；`IsConnected()` 同样为 `false`，但**不是失败** | `connected: false` + `ready: true`（**不带** `reason`） | +| 无意见 | 未启动，或已启动但无可解释的就绪面 | 退回只看 `IsConnected()`，三个键全缺席 | + +- **新增可选键（三处形状同名同义）**：① `POST /api/v1/admin/channels/open` 与 `.../close` 的响应体；② `GET /api/v1/admin/channels` 的**平台行**；③ 同端点的**账号行**（`accounts[]`）。`reason` 已**脱敏**（形状级 → 已知明文替换 → 剥 `access_token=` 查询参数），**凭据绝不出现**。 +- 🔴 **行为变更（须客户端跟进）**：`open` 的 `connected` 现在是**真实连接状态**，**不再恒为 `true`**；`close` 报**真实** `IsConnected()`，不再假定「调用成功 ⇒ 一定断开了」。老客户端若只看 HTTP 2xx 就提示「已连接」，在 `pending` / `ready` 下会继续骗人 —— 请改读 `connected` 加上述两个键，把卡片画成「已连接 / 连接中（原因）/ 就绪待接入 / 未连接」四档。 +- **退回行为（无破坏性）**：没实现该状态面的平台（kook / telegram / webhook / weixin-iLink）响应**逐字节不变**（既有四键 + 零变换）。 +- **计数不变**：无新端点 ⇒ §2.0 维持 `14 + 25 + 40 = 79`。详见 **§2.4(d)**。 + +### v0.89 **「助手消息的行内标签白名单」版 —— 只影响渲染口径，**服务端 API 形状一字未改****（依据：主人 2026-10-07「她在聊天消息中插入了 html/md 标签，能否增加网页前端对此类标签的基本渲染支持？」；Web 端实现推库 `2dae469`。）