docs(api): api-client → v0.54（渠道配置 patch 语义 + 阶段 6 四项）+ api-reference 同步
- 渠道写路径语义变更：config 从「整条替换」改为**三态补丁**（省略=保留 / 非空=覆盖 / 显式 null 或 ""=清除）， 并写明四类数据安全后果与破坏性提示；api-reference §5.24 同步 - 阶段 6 四项登记：16.4.1 静默/活动态与预约切换、16.4.5 会话级消息缓存（非激活帧按 sessionId 入桶、 不再丢弃）、16.4.3/16.4.6 虚拟滚动与专属页只读卡、16.4.4 双档 UI 模式（性能档=现状，持久化 cyrene.ui-mode） - 修正 4 类过时陈述：① 渠道写路径整条替换；②「忽略非激活会话的帧 / 按激活会话过滤」（api-client 四处 + api-reference 一处）；③ graph_update 无会话归属；④ api-reference 漏记 GET /admin/llm/catalog（补 §4.9.1） - 自证：旧陈述 0 命中；新词 PatchChannel/补丁/ui-mode-fancy/sessionCache/sess-backthink 均命中
This commit is contained in:
AskaEth committed
1 parent
4ae714883d
commit
7b05b4bfa9
2 files changed
+22
-13
No files matched your search
@@ -507,6 +507,11 @@ curl -s http://<host>:8080/api/v1/admin/iot -H "Authorization: Bearer $TOKEN" -H
|
||||
curl -s http://<host>:8080/api/v1/admin/llm -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
|
||||
```
|
||||
|
||||
### 4.9.1 GET /api/v1/admin/llm/catalog（v0.53，此前漏记）
|
||||
- **鉴权**：`owner|admin` 读（**只读**）。**Query**：`?refresh=1` 强制在线刷新；否则复用 24h TTL 内的本地快照。数据源 `https://models.dev/api.json`。
|
||||
- **响应**：`200 {"data":{"source":"cache"|"models.dev", fetchedAt?, stale?, warning?, providers:[{id,name,api?,doc?,env?,npm?,models:[{id,name,attachment,reasoning,toolCall,contextLimit?,outputLimit?}]}]}}`；**既无本地快照又抓不到** → `503 {"error":{"code":"catalog_unavailable","message"}}`；**有快照但刷新失败** → `200` + `stale:true` + `warning`。带 `Accept-Encoding: gzip` 时响应带 `Content-Encoding: gzip`（**信封形状不变**）。
|
||||
- **副作用只有一处**：落盘快照 `<DATA_DIR>/llm_catalog.json`（**不含任何凭据**、`data/` 已 gitignore、TTL 24h），**不改 `models.json`**。**审计动作**：`llm.catalog`（`ok`/`stale`/`error`）。完整契约与「不进运行时热路径」的边界见 `api-client.md` §2「模型配置契约（v0.53）」。
|
||||
|
||||
### 4.10 GET /api/v1/admin/automations
|
||||
- **响应**：`200 {"data":[<AdminAutomationRecord>...]}`。
|
||||
- `AdminAutomationRecord`：`{id, name, kind, cron?, enabled, lastRun?, nextRun?}`。`kind` ∈ `cron|event`；`lastRun/nextRun` 为 RFC3339（未知省略）。curl：
|
||||
@@ -870,7 +875,8 @@ curl -s -X POST 'http://<host>:8080/api/v1/admin/channels/kook/message/test?acco
|
||||
| `msgPerMin` | int | 用户消息限流 |
|
||||
| `maxMessages` | int | 单账号最大消息数 |
|
||||
> 空配置时：`weixin-ilink` 豁免（先建账号再扫码），其它平台 `400`。
|
||||
- **响应**：`201 {"data":{"persisted":true,"path":"<channels.json 路径>","platform":"<platform>","accountId":"<accountId>"}}`。**真实持久化 + 热更新**（读 channels.json→UpsertChannel→落盘→`Reload(platform)` 热替换 adapter，无需重启）。token 写入文件但**不回显**（GET 列表掩码）。
|
||||
> **`config` 是补丁（v0.54，与 `personaId` 同构）**：只含本次请求显式给出的键——键省略（`config` 里没有该键 / `config` 整体缺席或 `null`）= **保留已存值**、给非空值 = 覆盖、显式 `null`/`""` = **清除**（`0`/`false` 不算空）；顶层便捷字段（`token`/`baseURL`/…）是普通 string，只在**非空**时并入 ⇒ 清除 `bot_token` 须走 `config` 的显式 `null`/`""`。`allowGroups`/`denyGroups`/`allowUsers`/`denyUsers` 与三个限流键仍是**整值替换**（省略 = 清空）。
|
||||
- **响应**：`201 {"data":{"persisted":true,"path":"<channels.json 路径>","platform":"<platform>","accountId":"<accountId>"}}`。**真实持久化 + 热更新**（读 channels.json→**按 id 打补丁**（`PatchChannel`）→落盘→`Reload(platform)` 热替换 adapter，无需重启；**v0.54 起 `config` 为 patch 三态**（与 `personaId` 同构）：键省略=保留该账号已存值 / 给出非空值=覆盖该键 / 显式 `null`或`""`=清除该键，详见 `api-client.md` §2）。token 写入文件但**不回显**（GET 列表掩码）。
|
||||
- **错误**：`400`（platform 缺失 / 空配置）；`500`（渠道配置服务未注入 / 写盘失败 / 热重载失败）。
|
||||
- **审计**：`channel.save`。curl：
|
||||
|
||||
@@ -1020,7 +1026,7 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
| `type` | string | 是 | 事件类型（见 §6.3 表） |
|
||||
| `turnId` | string | 否 | 一轮交换的关联 id（流式；`turn-<hex>`）；OnStream 结构化流路径**不带** |
|
||||
| `seq` | int | 否 | hub 级单调递增序号，供客户端排序关联流式突发 |
|
||||
| `sessionId` | string | 否 | 能确定会话的事件带上，客户端按激活会话过滤 |
|
||||
| `sessionId` | string | 否 | 能确定会话的事件带上，客户端按它把帧路由到该会话的消息桶（v0.54 起非激活会话的帧不再丢弃；只有单槽忙态仍按激活会话判定，见 `api-client.md` §3.1/§3.2/§3.3） |
|
||||
| `data` | any | 否 | 类型化负载（每个事件见 §6.3） |
|
||||
|
||||
- **上行（客户端→服务端）** `wsInbound`：
|
||||
|
||||
Reference in new issue
Block a user