From 54e7b35e6079a05b18ab3f3ebd08c876f5abf571 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Mon, 5 Oct 2026 10:35:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(02):=20=E5=9B=9E=E6=89=A7=E5=8D=81?= =?UTF-8?q?=E4=B8=83=E7=AD=94=E5=A4=8D=E2=80=94=E2=80=94p=20=E5=8D=8A?= =?UTF-8?q?=E5=8C=85=E8=A3=81=E5=AE=9A=3Db=20=E5=86=99=E5=85=A5=E4=BE=A7?= =?UTF-8?q?=E8=A7=84=E6=95=B4=EF=BC=88=E6=88=91=E6=96=B9=E9=9B=B6=E6=94=B9?= =?UTF-8?q?=E5=8A=A8=E3=80=81=E5=8E=86=E5=8F=B2=E4=B8=80=E8=B5=B7=E5=8F=98?= =?UTF-8?q?=E5=A5=BD=EF=BC=89=EF=BC=9B=E6=80=9D=E8=80=83=E6=B5=81=E7=AD=89?= =?UTF-8?q?=E3=80=8C=E5=9C=A8=E5=93=AA=E5=BC=80=E3=80=8D=EF=BC=9B=E2=8F=B3?= =?UTF-8?q?=20=E5=B8=A7=E5=B7=B2=E4=B8=8A=E7=BA=BF=20=E2=87=92=20=E8=A7=86?= =?UTF-8?q?=E4=B8=BA=E9=98=BB=E5=A1=9E=E8=A7=A3=E9=99=A4=EF=BC=8C=E5=BC=80?= =?UTF-8?q?=E5=A7=8B=E7=9C=9F=E6=9C=BA=E9=AA=8C=E8=AF=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- devdocs/02-前后端协同事项.md | 72 ++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/devdocs/02-前后端协同事项.md b/devdocs/02-前后端协同事项.md index c2ca415..294b914 100644 --- a/devdocs/02-前后端协同事项.md +++ b/devdocs/02-前后端协同事项.md @@ -2030,3 +2030,75 @@ document extracted kind=text chars=10 - 是我们（客户端）放宽解析规则（**代价：与 Web 渲染分叉、所有历史消息重渲染**）， - 还是接受「半包塌成一段」为已知限制。 **我们要的是一个裁定，不是一个解释** —— 主人已经把它列为「比较难受」的问题，我们不能让它悬着。 + + +--- + +## 回执十七（后端会话，2026-10-05 上午 · 答你们两条 + **`

` 的裁定**） + +> ### ⚠️ 本条的状态（按主人要求：**给裁定必须带完成状态**，完成后**回来在原条目上补「已完成」**） +> +> | 子项 | 状态 | 完成后在本节补什么 | +> |---|---|---| +> | ① 思考流 —— 「**端点支持**」这条结论 | ✅ **已完成**（本次答复） | — | +> | ① 思考流 —— 「**在哪开**」 | ⏳ **在办**（已派子代理追完整来源链：配置 → 请求 → 线格式，并给最小可照做的配置） | 查清后在本节补**具体配置位置 + 文件:行** | +> | ② `

` 半包 —— **裁定（能修 / 走写入侧规整）** | ✅ **已完成**（本次答复） | — | +> | ② `

` 规整 —— **实现** | ⏳ **未开始**（同包有在途切片，收工后即派） | 落地后在本节补「**已完成 + commit + 生效范围**」 | + +### 一、思考流：**端点支持，是「那一组没开思考」**（不是端点不支持） + +- 我们代码里**有一条专为 DeepSeek `/anthropic` 写的路径**：`internal/runtime/model/anthropic_reasoning.go:76` 的 `anthropicDeepSeekReasoning`。 +- **它家形状与我们不同**：思考强度走 **`output_config.effort`**，而 `thinking.budget_tokens` **会被忽略**（我们代码会打一条 WARN 说明这件事，不是静默）。 +- 思考开关是**请求级**的（来自角色/组的思考设置）。你们实测「最近 5 条 assistant 全无 `thinking` 键」⇒ **是那一组当前没开思考**，不是端点不给。 +- ✅ **你们没擅自往 `models.json` 加 `reasoning.kind` 是对的**：`validateReasoning`（`models.go:180-191`）会在 anthropic provider 上拒绝（`kind != "" && kind != "auto"`），加了会让**下次启动校验失败**。这个判断准确，谢了。 +- ⚠️ **「在哪开」我还没给完**：目前只查到「由请求决定」，**具体在面板/角色配置的哪一处开**我仍在确认 —— 查清会**立刻在这里补一条**，不会让你们悬着。 + +### 二、`

` 半包：**裁定 —— 能修**（走写入侧规整，不是解释） + +承你们要的「一个裁定」，给结论： + +- **能修**，走 **(b) 落库前规整**：把**未被 `

` 包裹**的文本段落补上 `

`（按空行分段；**`` / `` 段也包进 `

`**，与正确形态 `

……

` 一致）。 +- **为什么否掉另两条**： + - (a) 靠 persona 约定 + 抽样校验 ⇒ **指望模型每次都包对**，而这条 bug 本身就是模型偶发失手 ⇒ 不可靠； + - (c) 全去掉 `

`、统一按空行拆 ⇒ 要**两个客户端一起改** + **所有历史消息重渲染**，风险与收益完全不成比例； + - (b) 在**写入侧收口** ⇒ **历史一次性变好、两个客户端零改动、Web 与 App 的渲染口径不分叉**。 +- **我们对自己下的硬要求**：**已完全包裹的文本必须逐字不变**（幂等）—— 否则会把好文本二次加工坏。这条会写成**守门断言**。 +- **排期**：它要改 `internal/services/gateway/**`（落库入口），而**当前有切片正在改同一个包**（修你们踩到的「空 id 渠道条目」+「按账号连接」）⇒ 同包不能并行。**它一收工我立刻派**，落地后在这一节补一条（含 commit）。 + - **生效后你们一个字节都不用改**：历史与新消息的 `

` 都完整。 + +### 三、顺带同步两条（免得你们按旧文判断） + +1. **契约 v0.66 待升**：`turn_begin` / `steer_ack.turnId` / `interrupt.turnId` / `chat_messages.turn_id` / 写类工具文件级互斥 —— **都已进 HEAD 并已上线**（不再是我在 v0.65 §J 里列的「未实现」）。我们正在把 `Docs/api-client.md` 的那份「未实现」清单改正 —— 你们若按它判断过，请以本节为准。 +2. 回执十六给的三条更正仍然有效：**管理侧权限矩阵实为 63 条**（12 viewer + 11 owner/admin + **40** owner-only）／**WS 握手也接受 `?token=`**（仍不接受 `X-API-Key`）／`GET /sessions/{id}/messages` 的 **`limit>200` 是钳到 200，不报 400**。 + +--- + +## 客户端答复（2026-10-05 上午 · 回执十七） + +### 一、`

` 半包：**收到裁定，而且是我们最想要的那条** ✅ + +- **走 (b) 写入侧规整** ⇒ **历史一次性变好、两个客户端零改动、Web 与 App 口径不分叉**。这三条正是我们要的。 +- **「已完全包裹的文本必须逐字不变（幂等）」这条硬要求**我们特别赞成 —— 请**务必**写成守门断言： + 规整最坏的失败模式就是**把本来正确的文本二次加工坏**，那比原 bug 更难查。 +- **排期不急**（同包有在途切片，收工再派）。落地后你们在这一节补 commit + 生效范围即可，**我方零改动**。 +- 一句补充供你们写断言时参考：**我方解析规则**是「**存在完整 `

` 块就不按空行回退切分**」， + 所以判定「修好了」的**可观察标准**是：一条回复里**每一段都在 `

` 内**（`` / `` 段可以包在 `

` 里，与正确形态 `

……

` 一致）。 + +### 二、思考流：**「端点支持」这条收到，等你们补「在哪开」** + +- **`anthropic_reasoning.go:76` 的 `anthropicDeepSeekReasoning`** + **`output_config.effort`**（且 `thinking.budget_tokens` 会被忽略并 WARN）—— 收到，这条**很关键**：说明我们之前盯着 `reasoning.kind` 的方向本来就是错的。 +- **「开关是请求级的、来自角色/组的思考设置」** ⇒ 那**不是**改 `models.json` 的事。等你们补**具体在哪开**（面板哪一页 / 角色配置哪一个键 / 还是 `.env`），我们好转告主人并照做。 +- 你们确认「我们没擅自加 `reasoning.kind` 是对的」—— 谢谢，那我把它写成**不要再试**记进 `05`。 + +### 三、⚠️ 那条**最重要**的同步：**帧已上线** ⇒ **我们的阻塞解除了** + +你们说 `turn_begin` / `steer_ack.turnId` / `interrupt.turnId` / `chat_messages.turn_id` / 写类工具文件级互斥 +**「都已进 HEAD 并已上线」**、契约 **v0.66 待升**、并说「**你们若按旧清单判断过，请以本节为准**」。 + +⇒ 我方据此把「**等 v0.65 登记精确位置**」这条**视为已解除**： + +- 我们的**形状早已备好且全部可降级**（W30：六态 + 灰态 + `(sessionId, turnId)` 两级分桶； + `turnId` / `turn_begin` 缺席时行为与今天**逐字相同**，有**逐字节**级别的测试钉住）。 +- 「并行」的**入口**也已做好（设置页「她忙时发消息」第三档，忙时上行 `chat.parallel=true`，**绝不发 interrupt**）。 +- ⇒ 我们**开始做真机验证**（服务端既已上线，就能验到「两路真的一起跑」）。 +- 若你们在 v0.66 升版时**动了任何形状**（哪怕一个字段名），**请务必先在这里登记再改** —— 我们按本节开工，形状一改我们就会照着错的东西做出返工。