docs(devtools): 假后端补「主动消息」验收配方（proactive_inject.py + README 场景五）
改了什么： - 新增 devtools/fake-backend/proactive_inject.py：按真后端 SendProactive 的顺序 （先落库、再发帧）造一条主动消息 —— 落一行 assistant 历史行，再广播带同一 id/createdAt 的 proactive_message 帧。--without-id 是另一档（落库失败）：不落行、帧上不带 id。 - README 新增「场景五」：完整命令序列 + 帧形状 + App 侧三条判据；端点速查/形状出处/已知不确定 各补一条。 - 更正两处过时内容：§1 的工作目录还是旧 worktree 名 Cyrene-Android-FB；§8 说「客户端 W41 起先探 /health」——W45 已把那整套删掉（SendFallback.kt:120），这个端点客户端不再消费。 - 记录踩到的坑：ws_probe.py --listen N 单独用只有 1 秒（ws_probe.py:201 是 min(listen, 1.0)）， 不带 --send/--ping 时连接会先关掉，之后所有广播都是 delivered=0。 为什么： - 真后端没有任何 HTTP 入口能按需触发一次主动推送（backthink 只由心跳/事件决定，路由里只有一个 GET /admin/backthink），所以「她主动说的话」在客户端这一段的验收只能自己造帧。真后端只把 proactive_message 广播给在线连接、没有离线补发，帧壳又不带 sessionId（客户端必须自己钉主会话） —— 形状抄错或漏掉落库那条腿，验出来的结论就是假的。落成脚本 + 文档，下次不必重推。
This commit is contained in:
AskaEth committed
1 parent
d9b7c22ecb
commit
4c938c7330
2 files changed
+132
-2
No files matched your search
@@ -20,7 +20,7 @@
|
||||
## 1. 起服务（Windows + Git Bash）
|
||||
|
||||
```bash
|
||||
cd /d/Project/Code/Uni/Cyrene-Android-FB/devtools/fake-backend
|
||||
cd /d/Project/Code/Uni/Cyrene-For-Android/devtools/fake-backend
|
||||
python fake_backend.py --port 18080
|
||||
```
|
||||
|
||||
@@ -271,6 +271,39 @@ curl -s "$B/__control/requests?limit=20"
|
||||
> Git Bash 的坑：命令行里的中文会被转成本地代码页（GBK）再交给子进程，服务端按 UTF-8 解 ⇒ 400 `invalid json body`。
|
||||
> 所以**带中文的请求体写进文件再用 `--data-binary @file`**，控制端点的参数用 URL 编码（`%E4%BD%A0%E5%A5%BD`）。
|
||||
|
||||
### 场景五：主动消息（`proactive_message`）实时到达
|
||||
|
||||
「她主动说的话」在线上有两条路：有在线客户端时走 `proactive_message` 帧，走 IM 桥时走 `message_persisted{proactive:true}`。
|
||||
**帧壳不带 `sessionId`**（真后端 `gateway` 的 `wsEvent{Type, Data}` 逐字如此），所以客户端必须自己钉死主会话。
|
||||
|
||||
真后端**没有任何 HTTP 入口**能按需触发一次主动推送（`backthink` 只由心跳/事件决定，路由里只有一个
|
||||
`GET /api/v1/admin/backthink`），所以本机验收只能自己造帧 —— `proactive_inject.py` 按真后端的顺序
|
||||
（**先落库、再发帧**）把那一对动作做出来：
|
||||
|
||||
```bash
|
||||
python fake_backend.py --port 18090 &
|
||||
|
||||
# 探针**必须带 `--send` 或 `--ping`** —— 不带时 `ws_probe.py:201` 只监听 `min(listen, 1.0)` 秒就收工，
|
||||
# 连接随即关闭 ⇒ 之后广播的帧 `delivered=0`（本工具没有补发，白忙一场）
|
||||
python ws_probe.py --port 18090 --send '{"type":"noop","data":{}}' --listen 8 &
|
||||
|
||||
# 落一行 assistant 历史行 + 广播带**同一 id** 的 proactive_message（两条腿都在这一个脚本里）
|
||||
python proactive_inject.py --port 18090 --text "验收：她主动说了一句"
|
||||
```
|
||||
|
||||
探针那边应当原样收到（形状出处：`Cyrene_v2/internal/services/gateway/proactive.go:23-41`）：
|
||||
|
||||
```json
|
||||
{"type":"proactive_message","data":{"content":"验收：她主动说了一句","platform":"web",
|
||||
"messageId":"im-msg-000004","sender":"昔涟","id":"msg-000004","createdAt":1791243748593}}
|
||||
```
|
||||
|
||||
`--without-id` 是**另一档**：帧上不带 `id`/`createdAt`，而且**连历史行都不落**（落了行就验不出这一档）——
|
||||
它等价于真后端「落库失败」。此时客户端只该有个**本地气泡**、**刷新后它就不该在了**，
|
||||
但它**绝不能被静默丢掉**（「落库失败也不能让消息消失」正是这条的验收点）。
|
||||
|
||||
App 侧三个判据：① 主会话（`web`）里**实时**多一条助手气泡；② 切到任一次级会话 —— **不**出现；③ 重进聊天页后**还在，且只有一条**。
|
||||
|
||||
## 8. 端点速查
|
||||
|
||||
`/api/v1/**`（一律包信封：成功 `{data}` / 失败 `{error:{code,message}}`，`ApiEnvelope.kt:8`）：
|
||||
@@ -278,7 +311,7 @@ curl -s "$B/__control/requests?limit=20"
|
||||
| 端点 | 备注 |
|
||||
|---|---|
|
||||
| `POST /api/v1/auth/login` `/refresh` `/logout` | 回假 token（`role:"owner"`，`expiresAt` 是 **Unix 秒**） |
|
||||
| `GET /api/v1/health` | 存活探针：回 `{"status":"ok"}`。**不鉴权、不做任何重活**（对齐真后端 `registerPublicRoutes`）。客户端 W41 起在「WS 未就绪」时先探它一次，通就回落 REST 发那条消息；缺了它，那条阶梯在本机就退化成「直接排队」 |
|
||||
| `GET /api/v1/health` | 存活探针：回 `{"status":"ok"}`。**不鉴权、不做任何重活**（对齐真后端 `registerPublicRoutes`）。⚠️ 客户端**已经不消费它**（W45 删掉了「先探 `/health` 再回落 REST」那一整套，见 `SendFallback.kt:120`）：现在 WS 未就绪就**直接**试 REST，只有网络类失败才进队列 —— 所以这个端点留着只是别的消费者在用，**缺了不影响本机任何验证** |
|
||||
| `GET /api/v1/sessions` | 排序照真契约：`pinned DESC, type='main' DESC, created_at ASC`；`unreadCount` 按已读游标算 |
|
||||
| `POST /api/v1/sessions` | 可绑 `personaId`（未知角色 → 400）；支持**完全不带 body** |
|
||||
| `PATCH /api/v1/sessions/{id}` | 局部响应；`{}` → 400；`personaId` → 400；title trim 后空 → 400；>80 字 → 400 |
|
||||
@@ -339,6 +372,7 @@ curl -s "$B/__control/requests?limit=20"
|
||||
| `chat_duplicate` / `pending_full` 的可选键整键缺席 | `WsEvent.kt:291-336, 798-809` |
|
||||
| `interrupt{scope}` 取值与「只取消在跑回合」 | `WsOutbound.kt:59-78` + `InterruptScope.kt:27` |
|
||||
| `stream_chunk` + `stream_end` 回退形状 | `WsEvent.kt:205-228` + `ChatViewModel.kt:1451-1472` |
|
||||
| `proactive_message` 载荷（`id`/`createdAt` 与落库行**同源**、帧壳**不带** `sessionId`） | **后端源码**：`Cyrene_v2/internal/services/gateway/proactive.go:23-41` + `proactive_persist.go:36`。这是本工具唯一一处**以真后端为准**而不是以客户端为准的形状 —— 因为它正是「后端加了新键、客户端旧版静默丢弃」的那条路 |
|
||||
|
||||
## 11. 已知不确定 / 没做
|
||||
|
||||
@@ -351,6 +385,12 @@ curl -s "$B/__control/requests?limit=20"
|
||||
- **不实现**：admin 面全部端点、`documents` / `upload`、`voice_input` 的落库、`mode_switch` 的语义、
|
||||
`observability_*` 推送、`subagent_ask` / `task_output_query`。上行收到这些帧**只记录、不处置**。因此 App 里
|
||||
管理员页面、附件上传这类路径在这个假后端上跑不通。
|
||||
- **主动消息只能靠 `proactive_message` 帧造**：本工具不模拟 `backthink`（真后端也没有 HTTP 入口），
|
||||
所以「她自己决定什么时候开口」这件**服务端**行为在这里验不到 —— 能验的是「帧到了客户端之后」那一段
|
||||
（见第 7 节场景五）。同理，本工具**不会**自动补发 `message_persisted`：真后端走 IM 桥的主动消息会额外
|
||||
广播一条 `message_persisted{proactive:true}`，那条路在本机需要自己造帧。
|
||||
- **`ws_probe.py --listen N` 单独用只有 1 秒**（`ws_probe.py:201` 是 `min(listen, 1.0)`）：要让它守着连接
|
||||
等别人广播，必须带 `--send` 或 `--ping`，否则连接会先关掉、之后所有广播都是 `delivered=0`。
|
||||
- **`message_persisted` 与流帧的先后顺序**是我按「正文流完再落库」安排的，没有对着真后端核过。
|
||||
- **`--hold-replies` 的三个代价**（都刻意保留，因为改掉就不再是「只关那一件事」了）：
|
||||
1. `POST /api/v1/chat` 的回执形状**逐字不变**（仍 `{stream:true,queued:false,queueDepth:0,messageId,sessionId}`），
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""注入一条「主动消息」：先落一行 assistant 历史行，再广播带**同一 id** 的 `proactive_message` 帧。
|
||||
|
||||
为什么要成对做：真后端 `SendProactive`（`Cyrene_v2/internal/services/gateway/proactive.go:59`）的顺序是
|
||||
**先落库、再发帧** —— 帧载荷里的 `id`/`createdAt` 就是那条落库行的（`proactive_persist.go:36`）。
|
||||
客户端据此把实时气泡对齐到历史行：**实时可见 + 刷新后仍在 + 按 id 不会重复**。
|
||||
只发帧不落行，就相当于真后端「落库失败」那一档（那时帧上**没有** `id`），验的是退化路径，不是正常路径 ——
|
||||
`--without-id` 走的就是这一档，且它**连历史行都不造**（落了行就验不出「刷新后它不在了」）。
|
||||
|
||||
帧壳**不带 `sessionId`**（真后端 `wsEvent{Type, Data}` 逐字如此）—— 客户端必须自己钉死主会话，
|
||||
否则会在每个次级会话里都冒一条。
|
||||
|
||||
python proactive_inject.py --port 18080 --text "验收：她主动说了一句"
|
||||
python proactive_inject.py --port 18080 --without-id # 退化档：落库失败
|
||||
|
||||
判据（App 侧）：
|
||||
1. 主会话（`web`）里**实时**多一条助手气泡，正文就是 `--text`；
|
||||
2. 切到任一次级会话 —— **不**出现这条；
|
||||
3. 下拉/重进聊天页（触发 `GET .../messages`）—— 它**还在**，且**只有一个**（没有被合并成两条）。
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
|
||||
def control(port, action, params=None, body=None):
|
||||
url = "http://127.0.0.1:{}/__control/{}".format(port, action)
|
||||
if params:
|
||||
url += "?" + urllib.parse.urlencode(params)
|
||||
data = json.dumps(body).encode("utf-8") if body is not None else None
|
||||
request = urllib.request.Request(url, data=data, method="POST")
|
||||
request.add_header("Content-Type", "application/json; charset=utf-8")
|
||||
with urllib.request.urlopen(request, timeout=5) as response:
|
||||
return json.loads(response.read().decode("utf-8"))
|
||||
|
||||
|
||||
def main(argv=None):
|
||||
parser = argparse.ArgumentParser(description="注入一条带落库行的主动消息")
|
||||
parser.add_argument("--port", type=int, default=18080)
|
||||
parser.add_argument("--session", default="web", help="落库行进哪个会话（真后端恒为主会话）")
|
||||
parser.add_argument("--text", default="验收：她主动说了一句")
|
||||
parser.add_argument("--sender", default="昔涟")
|
||||
parser.add_argument("--without-id", action="store_true",
|
||||
help="故意不带 id/createdAt —— 等价于真后端落库失败那一档")
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
if args.without_id:
|
||||
data = {
|
||||
"content": args.text,
|
||||
"platform": "web",
|
||||
"sender": args.sender,
|
||||
"messageId": "im-orphan-1",
|
||||
}
|
||||
print("（落库失败档）**不**造历史行 —— 落了行就验不出「刷新后它不在了」")
|
||||
else:
|
||||
seeded = control(args.port, "messages", {
|
||||
"session": args.session, "role": "assistant", "text": args.text,
|
||||
})["data"]
|
||||
data = {
|
||||
"content": args.text,
|
||||
"platform": "web",
|
||||
"sender": args.sender,
|
||||
"messageId": "im-{}".format(seeded["lastId"]),
|
||||
"id": seeded["lastId"],
|
||||
"createdAt": seeded["newestCreatedAt"],
|
||||
}
|
||||
print("落库行 id={} createdAt={}（{}）".format(
|
||||
seeded["lastId"], seeded["newestCreatedAt"], args.session))
|
||||
|
||||
frame = {"type": "proactive_message", "data": data}
|
||||
delivered = control(args.port, "frame", body=frame)["data"]["delivered"]
|
||||
print("广播 proactive_message delivered={} —— {}".format(
|
||||
delivered, json.dumps(frame, ensure_ascii=False)))
|
||||
if not delivered:
|
||||
print("⚠ delivered=0：这一刻没有客户端连着 WS（看 GET /__control/state 的 wsClients）。"
|
||||
"广播没有补发，重跑前先确认连接在。")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
for _stream in (sys.stdout, sys.stderr):
|
||||
try:
|
||||
_stream.reconfigure(encoding="utf-8", errors="replace")
|
||||
except Exception:
|
||||
pass
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user