feat(api): documents[].reason + messages 对不存在会话回 404（安卓回执九两条；契约 v0.63）
- ① documents[] 元素增可选 reason（omitempty）：装配期在给出 status 的**同一处**填充，取的**就是注入模型清单里那份原因文案**（同一字符串两处用，服务端不为客户端另编一句），只在 unreadable 时下发；随 S3.5 的回合后回写落进 document 列 ⇒ 历史接口 / 握手回放都有。文案只含原因、不含落盘路径/存储名以外内容/凭据（有独特目录名反证断言）。
- ② GET /sessions/{id}/messages：不存在/已删除 ⇒ 404 session_not_found；**存在但无消息仍 200 {data:[]}**（空会话绝不能被答成 404）；参数形状校验仍先于 404；存在性判定复用既有窄视图（history.Store.SessionPersona，未知 id 报 ErrSessionNotFound），**未新增 SQL/存储方法**；判不出来（未接该视图）保持旧语义（判不出 ≠ 不存在），判定本身失败回 500 不静默。
- 契约 v0.63（三档：reason 纯增量 / messages 404 行为变更 / 无破坏性）：api-client §1 行 6 + §1.2④ 的 10 条逐字文案 + §4.4 错误码 + changelog + banner；api-reference §1.2 行 6 + §3.4 + §3.8 DTO + §8.1 错误码表。
- 主会话独立核对的副作用（隔离会话 sess-* 现在也 404）：查活库 chat_sessions 里**根本没有 sess-* 行**（只有 web 与 web:<uuid>），sess-backthink 消息数 0，前端唯一提到 sess-backthink 的是 graph_update 的内存桶测试 ⇒ **没有客户端按 id 读隔离会话的 messages**；且这与 POST /sessions/{id}/read（v0.37 起即 404）一致 ⇒ 接受不加 sess- 例外，并在回执里问安卓确认。
- 主会话独立验收：隔离 worktree（S9 的 13 文件）build/vet 绿、整树连跑 2 次 59 ok / 0 FAIL、reason/404 用例 8 PASS、双平台交叉编译绿；**变异亲自复现**（在调用点短路 404 守卫 ⇒ UnknownSessionIs404 与 DeletedSessionIs404 双红：status = 200, want 404）。
- 如实登记：验收过程中出现过**一次不可复现的子集 FAIL**（restore 之后那次 Session|Reason 子集跑；未记到用例名）—— 随后同一子集、那三条用例 ×5、以及整树 ×2 全绿，判为瞬时；已记入账本，后续留意。
This commit is contained in:
AskaEth committed
1 parent
c1fa1e9b9a
commit
902b6eecfd
13 files changed
+779
-21
No files matched your search
@@ -72,7 +72,7 @@
|
||||
| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/400/404/409/500/503 | 发消息（同步回复或触发 WS 流式）；**v0.56**：`stream:true` 受理成功才回（`202` 续接排队 / `409` 队列满 / `500 chat_unavailable` 未接 loop / `503 chat_dispatch_failed` 兜底派发失败）、`image` 超上限 → `400 image_too_large`（上限 = `CHAT_IMAGE_MAX_BYTES`，默认 5 MiB 与 `/upload` 同口径；≤0 视为用默认）、`clientMsgId` 重复 → `200 {duplicate:true}`；**v0.59**：可选 `documents:[{name}]`（≤5 条、只收服务端存储名）→ 超限 `400 too_many_documents`、名非法/不存在 `404 document_not_found`（见 §3.8） | M8/M15 |
|
||||
| 4 | GET | `/api/v1/sessions` | JWT | 200 | 会话列表（持久化会话 or 渠道会话回退） | M16 |
|
||||
| 5 | GET | `/api/v1/personas` | JWT | 200 | 人格列表 | M8 |
|
||||
| 6 | GET | `/api/v1/sessions/{id}/messages` | owner\|admin | 200 | 会话消息热分页 | M16 |
|
||||
| 6 | GET | `/api/v1/sessions/{id}/messages` | owner\|admin | 200/**404** | 会话消息热分页；**v0.63**：会话**不存在/已删除** ⇒ `404 session_not_found`，**存在但没有消息仍 `200 {"data":[]}`**（见 §3.4） | M16 |
|
||||
| 7 | POST | `/api/v1/sessions` | owner\|admin | 201 | 新建次级会话 | M16 |
|
||||
| 8 | DELETE | `/api/v1/sessions/{id}` | owner\|admin | 200 | 删除次级会话 | M16 |
|
||||
| 9 | PATCH | `/api/v1/sessions/{id}` | owner\|admin | 200 | 会话改名(A4) + 置顶(`pinned`, D5) body `{title?,pinned?}`（部分更新，只回显变更字段；见 §3.6a） | M16 |
|
||||
@@ -345,7 +345,7 @@ curl -s http://<host>:8080/api/v1/personas -H "Authorization: Bearer $TOKEN" -H
|
||||
|
||||
### 3.4 GET /api/v1/sessions/{id}/messages
|
||||
- **鉴权**：`Authorize(owner, admin)`（会话消息/thinking 属主人私密历史，viewer 不可读）。
|
||||
- **Path**：`{id}` = 会话 id（`web` 或 `web:<uuid>`；IM 隔离会话 `sess-xxx` 亦可用）。
|
||||
- **Path**：`{id}` = **会话注册表 `chat_sessions` 里可寻址的**会话 id（`web` 或 `web:<uuid>`）。**v0.63 起**：不在 `chat_sessions` 里的 id（已删除的次级会话、凭空编造的 id、**以及隔离的 IM 会话 `sess-xxx` 与内部 `sess-backthink`**）⇒ `404 session_not_found` —— 这与 `POST /sessions/{id}/read`（v0.37 起对隔离会话即 404）是同一口径；隔离会话的消息请走 `GET /api/v1/admin/channels/{platform}/messages`（§4.7）。⚠️ 旧文那句「IM 隔离会话 `sess-xxx` 亦可用」**已随 v0.63 作废**。
|
||||
- **Query**：
|
||||
| 参数 | 类型 | 必填 | 默认 | 说明 |
|
||||
|------|------|:---:|------|------|
|
||||
@@ -366,7 +366,7 @@ curl -s http://<host>:8080/api/v1/personas -H "Authorization: Bearer $TOKEN" -H
|
||||
| `mode` | string | 该条的模式（`omitempty`，供渲染气泡不用猜） |
|
||||
| `mood` | string | 情绪标记（`omitempty`） |
|
||||
| `image` | string | 图像引用（`omitempty`） |
|
||||
| `documents` | array | **文档附件与抽取统计**（`omitempty`，**v0.59**）：`[{name,mime,size,chars,truncated,status}]`，**≤5 条**、顺序 = 客户端发送顺序；**0 个附件时该键省略**；`status ∈ extracted|listed|unreadable`。⚠️ **`chars`/`truncated` 是「本回合注入侧」事实**——`chars` = 本回合**注入**上下文的字符数、`truncated` = **注入**是否被截断（**不是**「文件是否被截断」）；**全文长度**只有 `document-read` 的 `totalChars` 能看到。**不含正文**。同一字段也出现在 `message_persisted` / `channel_persisted` / `message_edited` / 握手回放（同一结构体、四处同时生效）。⚠️ 单数 `document`（对象）形状**从未随任何已发布版本号发布**，本版起一律是 `documents` 数组 |
|
||||
| `documents` | array | **文档附件与抽取统计**（`omitempty`，**v0.59**）：`[{name,mime,size,chars,truncated,status,reason?}]`，**≤5 条**、顺序 = 客户端发送顺序；**0 个附件时该键省略**；`status ∈ extracted|listed|unreadable`。⚠️ **`chars`/`truncated` 是「本回合注入侧」事实**——`chars` = 本回合**注入**上下文的字符数、`truncated` = **注入**是否被截断（**不是**「文件是否被截断」）；**全文长度**只有 `document-read` 的 `totalChars` 能看到。**不含正文**。**`reason`（v0.63，可选）**＝**读不到的原因文案**，**只在 `status:"unreadable"` 时出现**（`extracted`/`listed` 时该键缺席）；它**逐字就是注入模型的那份原因**（如 `无法抽取正文：这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）`），**只有文案**：不含路径、不含凭据、不含存储名以外的内容（原始错误只进日志）。同一字段也出现在 `message_persisted` / `channel_persisted` / `message_edited` / 握手回放（同一结构体、四处同时生效）；⚠️ 实时帧在用户消息落库时发出，那时抽取未发生 ⇒ **`status`/`reason` 以读接口为准**。⚠️ 单数 `document`（对象）形状**从未随任何已发布版本号发布**，本版起一律是 `documents` 数组 |
|
||||
| `thinking` | string | 思维链（`omitempty`；**本端点 owner/admin-only，故可达**；**公开回放 / 实时持久化帧中已剥离**）。**v0.59 口径（有意默认，非缺陷）**：消息体的 `thinking` 字段在 `message_persisted` / `channel_persisted` / `message_edited` 与握手 `history` 回放中**恒为空**；**历史消息的思维链只有本端点（owner\|admin）返回**。实时思维链另走 `thinking.*` 流帧（§6.4，owner/admin 档） |
|
||||
| `platform` | string | 来源平台（`web` / `telegram` / `weixin-ilink` / `qq-obv11`...，`omitempty`） |
|
||||
| `deviceId` | string | 客户端端标识（`omitempty`，如 `web:chrome:a1b2c3`） |
|
||||
@@ -380,8 +380,8 @@ curl -s http://<host>:8080/api/v1/personas -H "Authorization: Bearer $TOKEN" -H
|
||||
{"data":[{"id":"m1","sessionId":"web","role":"assistant","content":"你好","mode":"normal","mood":"calm","platform":"web","deviceId":"web:chrome:a1b2c3","createdAt":1753...}]}
|
||||
```
|
||||
|
||||
- **错误**：`400`（`limit`/`before`/`after` 非法、`before`+`after` 同传、`id` 缺失）；`501` `{"error":{"code":"not_implemented","message":"会话历史服务未配置（未注入 HistoryStore）"}}`；`500` `{"error":{"code":"messages_failed",...}}`。
|
||||
- **备注**：热分页（design/16 §2.2,§5.1）。`thinking` 只在本 owner/admin 端点可见；WS 回放/广播已剥离。curl：
|
||||
- **错误**：`400`（`limit`/`before`/`after` 非法、`before`+`after` 同传、`q`+`after` 同传、`id` 缺失）；**`404` `{"error":{"code":"session_not_found","message":"session \"<id>\" not found"}}`（v0.63，行为变更）——会话不存在 / 已删除**（含不在 `chat_sessions` 的隔离 `sess-xxx`）；**存在但确实没有消息仍是 `200 {"data":[]}`**；参数校验**先于**存在性判定；`501` `{"error":{"code":"not_implemented","message":"会话历史服务未配置（未注入 HistoryStore）"}}`；`500` `{"error":{"code":"messages_failed",...}}`（含存在性判定本身读不出来时 —— **不静默退化成空列表**）。
|
||||
- **备注**：热分页（design/16 §2.2,§5.1）。`thinking` 只在本 owner/admin 端点可见；WS 回放/广播已剥离。**会话存活判据（v0.63）**：客户端用 **404（`session_not_found`）**判定「当前会话已不在」，据此退回主会话 + 一句提示；**不要**用「返回空数组」推断存活 —— 空数组现在**只**表示「这条会话存在但没有消息」。curl：
|
||||
|
||||
```bash
|
||||
curl -s 'http://<host>:8080/api/v1/sessions/web/messages?limit=50&before=1753000000000&platform=web' \
|
||||
@@ -545,7 +545,7 @@ curl -s -X POST http://<host>:8080/api/v1/sessions/web/read \
|
||||
- **≤5 条/回合**：超出 → `400 too_many_documents`，**先于任何文件系统访问**判定；名非法 / 穿越 / 不存在 → `404 document_not_found`；**任一条不合规都让整个请求被拒**（绝不静默丢掉附件）。
|
||||
- 附件部件挂在**同一条 `user` 消息**上；**纯附件回合**（无文本、无图片）成立。WS 上行帧仍有 **4096 字节**硬上限 ⇒ 现实中文档走 REST；两条入口共用同一份解析与校验，不会分叉。
|
||||
- **WS 侧失败**：经 `error` 帧下发 `data.code`（`too_many_documents` / `document_not_found` / `chat_documents_unavailable`）并**中止本回合**，绝不静默。
|
||||
- **历史 / 实时 DTO（四处同源）**：`historyMessage.documents`（见 §3.4 表）——`[{name,mime,size,chars,truncated,status}]`，`status ∈ extracted|listed|unreadable`，**0 个附件时省略该键**；⚠️ `chars` / `truncated` 是**本回合注入侧**事实（全文长度只有 `document-read` 的 `totalChars` 可见）。
|
||||
- **历史 / 实时 DTO（四处同源）**：`historyMessage.documents`（见 §3.4 表）——`[{name,mime,size,chars,truncated,status,reason?}]`，`status ∈ extracted|listed|unreadable`，**0 个附件时省略该键**；⚠️ `chars` / `truncated` 是**本回合注入侧**事实（全文长度只有 `document-read` 的 `totalChars` 可见）；**`reason`（v0.63）**只在 `unreadable` 时出现 = 读不到的原因文案（**逐字**等于注入模型那份，**只有文案、不含路径/凭据**）。
|
||||
|
||||
**D) 内置工具 `document-read`（模型侧）**：`{name, offset?, limit?}` → `{name,status,offset,limit,totalChars,truncated,nextOffset,text,extractTruncated?}`；`limit` 默认 **8000**、上限 **64K** 字符（`≤0` 用缺省、超上限夹取）；`offset` 为 **0 基 rune 偏移**、起点 = sidecar 正文（含 CSV/TSV 摘要行）；`offset<0` 或 `>totalChars` → 工具错误（`==totalChars` 合法）；`extractTruncated=true` 专指「抽取期撞上 **8 MiB** sidecar 安全上限」。只读 sidecar、**绝不重抽**；策略默认 **owner-only**。**诚实边界**：design/24 §6.2 列的 `document_unreadable`(400) **没有对应的 REST 错误码**，它只以本工具的错误形态存在（客户端在 DTO 里看到的是 `status:"unreadable"`）。
|
||||
|
||||
@@ -1422,7 +1422,7 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
| 400 | `bad_request` / `invalid_cron` / `invalid_rule` / `invalid_role` / `unsupported_action` / `invalid_param` / `invalid_provider` / `invalid_scope` / `too_many_documents`(v0.59) | 请求体/参数非法 |
|
||||
| 401 | `unauthorized` | 认证缺失/失效/过期（REST Bearer 与 WS） |
|
||||
| 403 | `forbidden` | 角色不足（viewer 读管理/主会话删除/写操作）；主会话不可删 |
|
||||
| 404 | `not_found` / `document_not_found`(v0.59) | 资源不存在（文档：名字非法 / 路径穿越 / 文件不存在**同一响应**） |
|
||||
| 404 | `not_found` / `document_not_found`(v0.59) / `session_not_found`(**v0.63**) | 资源不存在（文档：名字非法 / 路径穿越 / 文件不存在**同一响应**；会话：`GET /sessions/{id}/messages` 对**不存在 / 已删除**的会话，**空会话仍是 `200 {"data":[]}`**） |
|
||||
| 409 | `chat_busy` / `duplicate` / `device_offline` / `needs_login` | 冲突：队列满（**REST 响应体与 WS 定向 `error` 帧同码**，v0.59/G5）/ 人格已存在 / 设备离线 / 渠道未登录 |
|
||||
| 413 | `document_too_large`(v0.59) | 文档超 `CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB），文案带生效上限字节数 |
|
||||
| 415 | `unsupported_media_type`(v0.59；判定口径 v0.61) | 文档类型不在白名单——**扩展名白名单（23 项，含 `.pdf`）与字节嗅探的成对裁决**任一不过（HTML/纯文本改名成 `.pdf`、或 PDF 改名成 `.txt` 都走它） |
|
||||
|
||||
Reference in new issue
Block a user