diff --git a/Docs/api-client.md b/Docs/api-client.md index 7d43de4..a2c42a2 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -27,12 +27,12 @@ | 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` | | 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06）——**真视觉需配 `LLM_VISION_MODEL`/凭据，无凭据时降级为主模型直接看图或视觉·OCR 工具文本描述**；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `

` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` | | 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 | -| 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色，等价于随后 PATCH 一次（design/22 §2：渠道级只作"新会话的初始角色提供者"）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） | -| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：会话可在保留上下文的前提下换角色，故每条消息都记"谁说的"；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` | +| 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色（design/22 §2：渠道级只作"新会话的初始角色提供者"；**会话角色只在创建时写入、之后不可变**，见 §1 行 8 / design/22 §8-1）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） | +| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：逐条记录"谁说的"——会话角色在创建时固定，§8-1；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` | | 6a | `/api/v1/messages/{id}` | PATCH | JWT(owner/admin) | ✅ | **编辑单条消息**（D3）：body `{content}`（非空、≤4000 rune，空/纯空白/超长回 `400`）→ **`{data:<消息DTO>}`**（`data` **直接就是**更新后的完整消息 DTO，含 `id/sessionId/role/content/.../createdAt`，**无 `message` 包一层**；**只改 `content`**，role/时间戳/平台保持不变）；消息不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_edited`**（§3.8，账号其它端免刷新同步）。**重发不单独设端点**——客户端用「编辑后的内容再 `POST /chat`」即可（避免重复轮次语义） | | 6b | `/api/v1/messages/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除单条消息**（D3）→ `{data:{deleted:}}`；不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_deleted`**（§3.8，账号其它端按 `id` 移除） | | 7 | `/api/v1/sessions/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除次级会话及其消息** → `{data:{deleted:}}`；主会话不可删回 `403 forbidden`；未注入 HistoryStore 回 `501` | -| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶 + v0.42 选角）：body `{title?,pinned?,personaId?}`（**至少一个字段**，都缺回 `400`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）；**`personaId`**（v0.42）重新绑定该会话的角色——**显式 `""` = 解绑**（回到"继承全局默认"），未知角色 id 回 `400`，主会话与次级会话均可改（design/22 §4.5）；**改角色不动已存会话内容**：历史消息仍带各自"说话时的角色"（`chat_messages.persona_id`），只有**下一回合**起用新角色的提示词/记忆域/情绪/思考预算。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / `{data:{id,personaId?}}` / 多项同改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶/选角但不可删；未注入 HistoryStore 回 `501`（不支持角色绑定的 HistoryStore 在 `personaId` 路径也回 `501`）。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 | +| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶）：body `{title?,pinned?}`（**至少一个字段**，都缺回 `400`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）；**`personaId` 出现即 `400`**（v0.46，design/22 §8-1：**会话角色在创建时确定、之后不可变，要换角色请新开会话**）——**不是静默忽略、也不是 200 空操作**：**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request`，错误消息点名 `personaId`，且该检查**先于**会话存在性检查（**未知会话 + `personaId` 也回 `400`**，不是 `404`；连 `title` 同传也整体 `400`、不改任何字段）。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / 两项同改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶但不可删；未注入 HistoryStore 回 `501`。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 | | 8a | `/api/v1/sessions/{id}/read` | POST | JWT(owner/admin) | ✅ | **推进已读游标**（D4 / Android 协同 B3）：body `{before?}`——`before` 为**可选**的毫秒 Unix 时间戳，**缺省（或空 body）= 现在**，即「我看到的都算已读」。→ `200 {data:{sessionId,readAt}}`（`readAt` 为推进后的游标毫秒）。**判定**：`createdAt <= readAt` 的消息算已读（列表 `unreadCount` 只数 `createdAt > readAt` 的）；**语义**：**会话级单一游标、单 owner 账号**——读一处 = **该账号所有端已读**（不做 per-device 游标，与「同一账号所有浏览器都属于同一 owner」一致）；**只前进不后退**（SQL `read_at = MAX(read_at, before)`），所以乱序/并发/重试请求幂等安全、绝不会把已读变回未读。`before` 为 `0`/负数/非数字、或 body 不是 JSON 对象 → `400`；未知会话（含隔离 `sess-xxx`，不在 `chat_sessions`）→ `404`；未注入 HistoryStore → `501 not_implemented`。**成功后广播下行 `session_read`**（§3.9）让同账号其它端清红点；**失败路径不广播**。**升级回填**：迁移 `0010` 把既有会话游标回填为「该会话现有最新消息时间」，升级当天不误报未读 | | 9 | `/api/v1/personas` | GET | JWT | ✅ | **角色目录**（任意已认证角色可读）→ `{data:[PersonaSummary...]}`，每项 `{id,name,character,isDefault,mode,memoryNamespace,avatar?,chatBackground?,mood}`。**`mood`（v0.43）** = 该角色**当前情绪状态**（角色级，取值见 `GET /meta/enums` 的 `moods`；`""` = 该角色暂无被跟踪的情绪，**不伪造默认值**）。**语义：情绪跟随角色，与会话无关**——同一角色的所有会话看到同一 `mood`；客户端登录/加载角色目录时用它**播种心情徽标**，避免刷新后短暂空白（随后以 WS `mood` 帧为准）。**不含 admin 专属的 `thinking` 旋钮**（用户侧不暴露模型调用参数）。 | | 10 | `/api/v1/audio/transcribe` | POST | JWT(owner) | ✅ | **语音→文本**：body `{audio:"",format?,deviceId?}` → `{data:{text, provider?}}`（走后端 STT，百炼 `qwen-audio-3.0-asr-flash`；**当结果为空文本/silent 降级时响应体带 `provider`**（如 `"silent"`，非空文本省略），客户端据此提示「没识别到声音」） | @@ -110,7 +110,7 @@ - Web 端镜像实现在 `frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 对未知值返回原值），权威仍以本端点为准。 - **反漂移保证（后端）**：后端有测试断言「每个内置适配器的 `Name()` 都在 `platforms` 表内」「`moods` 与 persona 情绪状态机的内置状态一致」「`modes` 与前端 `MODES` 九模式一致」——漏登记即 CI FAIL，客户端拿到的表不会滞后于代码。 -> **契约版本 `v0.45`**（**`PUT /admin/channels/{platform}/config` 的 `personaId` 由「省略/`""` 都 = 解绑」修订为三态**：**省略（或 `null`）= 保留已存绑定**、**显式 `""` = 解绑**、**非空 id = 绑定**，未知角色仍 `400`——修 v0.44 会**静默清空**渠道角色绑定的一处前后端契约不一致；纯语义收紧，**字段与端点形状不变**）。上一版 `v0.44`：渠道级选角（`PUT /admin/channels/{platform}/config` body 新增可选 `personaId`、`GET /admin/channels` 每账号新增可选 `personaId`）+ 角色解析优先级（会话绑定 > 渠道绑定 > 全局默认，群聊/陌生人强制默认角色）。 +> **契约版本 `v0.46`**（**`PATCH /api/v1/sessions/{id}` 的 `personaId` 由「可重新绑定该会话的角色」改为「出现即 `400`」**：**会话角色在创建时确定、之后不可变**，要换角色请新开会话（design/22 §8-1）——**明确拒绝**而非静默忽略/200 空操作；**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request` 且消息点名 `personaId`，该检查**先于**会话存在性检查（未知会话 + `personaId` 也回 `400` 而不是 `404`）。**破坏性**：按 v0.42–v0.45 旧文实现、依赖「PATCH 换角色 / 显式 `""` 解绑」的客户端必须改为**新建会话**选角色；`title`/`pinned` 行为与 `POST /sessions {personaId}`（创建时绑定）**完全不变**，不再有 `501/200 {personaId}` 的 PATCH 路径）。上一版 `v0.45`：`PUT /admin/channels/{platform}/config` 的 `personaId` 由「省略/`""` 都 = 解绑」修订为三态（**省略（或 `null`）= 保留已存绑定**、**显式 `""` = 解绑**、**非空 id = 绑定**，未知角色仍 `400`）。 ## 2. REST 端点（管理，`/api/v1/admin/*`） @@ -332,15 +332,15 @@ ### 4.2 会话与消息用法（聊天） - **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]`。**排序：置顶会话（`pinned=true`）最前，其次主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；次级 `web:` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。**`personaId`（v0.42）=该会话绑定的角色**；空/缺省 = **继承全局默认角色**，客户端渲染激活会话的名字/头像用它（后端唯一真源是 `chat_sessions.persona_id`，localStorage 之类只作缓存）。 -- **选角 / 换角色（v0.42）**：`POST /api/v1/sessions` body `{personaId?}` 在**新建时**就绑角色；已存在的会话用 `PATCH /api/v1/sessions/{id}` body `{personaId}` 重新绑定（显式 `""` 解绑回"跟随默认"）。**换角色保留上下文**：历史消息逐条带自己的 `personaId`，只有**下一回合**起提示词/记忆域/情绪/思考预算换成新角色（design/22 §7-5）。**记忆按角色隔离**：不同角色的会话各记各的，同一角色的多个会话互相可见（design/22 §3 口径 1）；群聊/陌生人会话仍**只读**、且强制默认角色。 +- **新建时选角（v0.42，v0.46 收口）**：`POST /api/v1/sessions` body `{personaId?}` 在**新建时**就绑角色（省略/空 = 跟随全局默认角色）。**会话角色在创建时确定、之后不可变**（design/22 §8-1）：**没有"会话内换角色"这回事**——`PATCH /api/v1/sessions/{id}` 一旦收到 `personaId` 键就回 `400`（见 §1 行 8），**要换角色请新开会话**。**记忆按角色隔离**：不同角色的会话各记各的，同一角色的多个会话互相可见（design/22 §3 口径 1）；群聊/陌生人会话仍**只读**、且强制默认角色。 - **角色解析优先级（v0.44，design/22 §2 裁决规则 + §7-3/§7-4）**：一个回合到底以哪个角色答话，**自上而下**取第一个命中的： 1. **请求级覆盖** —— 仍**未实现**（design/22 §2 裁决规则 1，留待后续批次）； - 2. **会话绑定** `chat_sessions.persona_id`（`POST/PATCH /sessions` 写入）—— 非空即赢； + 2. **会话绑定** `chat_sessions.persona_id`（`POST /sessions {personaId}` 在**创建**时写入；之后不可变，design/22 §8-1）—— 非空即赢； 3. **渠道绑定** —— 该 IM 账号的 `personaId`（`PUT /admin/channels/{platform}/config`，v0.44）。**仅**作用于该账号的**主人私聊**，且仅当该会话（=镜像目标主会话 `web`）**自身未绑角色**时； 4. **全局默认角色** `owner.yaml:defaultPersona` —— 兜底（`''` 始终 = 当前默认角色）。 **群聊 / 陌生人隔离会话强制默认角色**（§7-4，更保守）：这两类会话**跳过** 2/3 两条渠道与主会话绑定，一律用默认角色，避免把第三方会话挪进某个角色的记忆域；记忆仍是**只读**。**Web 主会话与 IM 主人私聊共享同一角色**（§7-3）：主会话绑 Y 时，同一主会话里 IM 镜像进来的主人私聊回合也以 Y 答话。 - **模型上下文里的「谁说的」（v0.44，design/22 §7-5）**：一回合的上下文由该会话**最近 20 条**持久化消息（`chat_messages`，含 `persona_id`）+ 本回合新消息组成（此前只带新消息本身，模型看不到会话前文）；**每条 assistant 历史消息按其说话角色标注**，模型收到形如 `[发言归属] 以下发言来自「昔涟」（xilian），不是你说的。` 的独立 system 标注，以及一条声明当前角色的 `[会话角色] …` 段。**正文永不被改写**：标注只走 system 消息，用户正文与 assistant 正文一字不改（design/11 §10：不给用户正文冒充系统指令的机会）。**对客户端透明**（无新字段、无新端点）。 -- **改名 / 置顶 / 选角**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）或 `{pinned?:bool}` 或 `{personaId?:string}`（至少一个字段）→ `{data:{id,title?,pinned?,personaId?}}`（只回显变更字段）。 +- **改名 / 置顶**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）和/或 `{pinned?:bool}`（至少一个字段）→ `{data:{id,title?,pinned?}}`（只回显变更字段）。**body 里出现 `personaId` 键一律 `400`**（会话角色不可变，v0.46 / design/22 §8-1）。 - **未读 / 已读游标（D4）**：列表项的 **`unreadCount`** 直接用于会话列表红点（恒返回整数，0 = 无未读）。客户端进入会话、或滚到底看到最新消息后调用 **`POST /api/v1/sessions/{id}/read`**：body `{"before":<毫秒>}`（如「本次已渲染的最新一条的 `createdAt`」），或**省略 body** = 标记到**现在**。后端**只前进**地推进该会话**唯一**游标（单 owner 账号：读一处 = 所有端已读），并广播 `session_read`（§3.9）——同账号其它端**免刷新**清红点。列表 → 读 → 再看列表即可自洽（漏收广播的端下次拉列表自然收敛）。 - **拉取激活会话历史**：`GET /api/v1/sessions/{id}/messages?limit=50&before=&platform=&q=`。 - **热分页**：`limit` 默认 50（上限 200），`before` = 当前最旧一条的 `createdAt`（毫秒），向上翻页。`platform` 可选（IM 适配器传本平台只拉本渠道；Web/通用客户端不传 = 全量共享主会话）。 @@ -367,10 +367,11 @@ - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。 ## 5. 变更记录 +- `v0.46`（**会话角色不可变：`PATCH /sessions/{id}` 拒绝 `personaId`**，对客户端**是破坏性变更**——按 v0.42–v0.45 旧文实现、依赖「PATCH 换角色」的客户端必须改为**新建会话**选角；design/22 §8-1 主人拍板定稿）：① **`PATCH /api/v1/sessions/{id}` 的 `personaId` 改为「**出现即 `400`**」**：只要请求体里**有 `personaId` 键**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）就回 `400 bad_request`，**错误消息点名 `personaId`** 并说明「会话角色在创建时确定、之后不可变，要换角色请新开会话」。**实现取「明确拒绝」而非静默忽略或 200 空操作**：静默忽略会让客户端以为绑定已改。② **顺序保证**：该检查在解析完 body 后**立即**执行、**先于**会话存在性检查 —— **未知会话 + `personaId` 回 `400`（不是 `404`）**；`title` + `personaId` 同传也整体 `400`，**其余字段一个都不落库**。③ **不变的部分**：`title` / `pinned` 的语义、边界（≤80 rune 等）与响应形状**逐字不变**；`POST /api/v1/sessions {personaId}`（**创建时**绑定、未知角色 `400`、非空回显）**完全不变**；`GET /sessions` 与消息 DTO 的只读 `personaId` 不变。④ **移除的路径**：PATCH 上再也没有 `{personaId}` 成功响应、也没有「不支持角色绑定的 HistoryStore → `501`」这条路（网关的 `Server.setSessionPersona` 及其中间层随之删除；`history.Store.SetSessionPersona` 作为存储能力保留）。⑤ **前端同步**：用户端**移除**「会话行 → 切换角色」菜单与面板「挂角色」下拉，**保留**「新建会话时选角色」；管理面板「角色」列改为**只读**展示创建时绑定的角色。⑥ **测试与变异验证**：新增断言覆盖「键出现即 400（六种取值）+ 绑定未变 + 未知会话仍 400 + `title`/`pinned` 不变」，并把「静默忽略」与「改回写绑定」两种反向实现各跑一次（两处断言均必须 FAIL，见提交说明）。 - `v0.45`（**渠道 `personaId` 三态修订：修「省略 = 解绑」会静默清空绑定**，对客户端**无字段/端点形状变更**，但**语义收紧**——按 v0.44 旧文实现的客户端若靠「省略 `personaId`」来解绑，必须改为**显式传 `""`**；design/22 §2 方案 b）：① **`PUT /api/v1/admin/channels/{platform}/config` 的 `personaId` 改为三态**：**键省略（或 JSON `null`）= 保留该账号已存绑定**（不动）；**显式 `""` = 解绑**（写盘时该账号不带 `personaId` 键）；**非空 id = 绑定该角色**；**未知角色 id 仍 `400 bad_request`**（且**只校验本次真的传了值**的情形——省略时继承的已存绑定在当初写入时已校验）。② **修的问题（数据安全）**：管理面板只在主人**动过**角色下拉时才发这个键（前端 `channelPersona.ts` / `channelPersonaRequest`），而 v0.44 后端把「键不存在」也当成解绑 ——**主人打开一个已绑角色的账号、不动下拉、只改 token 并保存 → 该账号的角色绑定被静默清空**（无提示、无审计可见的理由），两端语义相反。现在后端的「省略」与前端一致 = 保留。③ **实现**：请求 DTO 的该字段由 `string` 变 `*string`（指针区分「省略」与「显式空串」），应用逻辑在既有「读当前配置（channels.json）→ `UpsertChannel` → 落盘 → `bridge.Reload(platform)`」路径内按三态取值（省略时从**同平台同 id** 的已存账号继承，故保存一个账号不会动到同平台其它账号的绑定）；**无新端点、无新字段、无响应形状变更**。④ **`GET /api/v1/admin/channels` 每账号的 `personaId` 回显不变**（v0.44 新增，非敏感、不掩码），面板据此回填角色下拉。⑤ **测试**：省略 → 绑定保留、显式 `""` → 清除、非空 id → 绑定、未知 id → `400`（含「省略时改其它字段后读回确认」与「同平台多账号互不影响」），并把「省略 = 解绑」作为变异反向验证（该断言必须失败）。 - `v0.44`（**渠道级选角 + 「谁说的」进模型上下文**，对客户端**新增两个可选字段**，向后兼容；design/22 批次 2 后端 = §2 裁决规则 + §4.4 + §7-3/§7-4/§7-5）：① **`PUT /api/v1/admin/channels/{platform}/config` body 新增可选 `personaId`**（渠道级绑定，design/22 §2 方案 b）：=该账号答话时的角色 id；**未知角色 `400 bad_request`**，~~**省略/`""` = 解绑**（写盘时该账号不带 `personaId` 键）~~（**本条的「省略」一项已由 v0.45 修订为「保留已存绑定」；只有显式 `""` 才解绑**，见上）；沿用既有「读当前配置 → `UpsertChannel` → 落盘 `channels.json`(0600) → `bridge.Reload(platform)` 热更新」路径，保存即生效（下一批入站消息），**无新端点**。② **`GET /api/v1/admin/channels` 每账号新增可选 `personaId`**（非敏感，不掩码），供面板回填。③ **角色解析优先级明确化（对客户端语义澄清，无形状变更）**：**会话绑定 > 渠道绑定 > 全局默认角色**；渠道绑定**只**作用于该账号的**主人私聊**且仅当主会话自身未绑角色（§7-3：IM 主人私聊镜像随主会话角色）；**群聊/陌生人隔离会话强制默认角色**（§7-4，更保守，仍只读）。④ **模型上下文新增角色归属标注（§7-5 的剩下一半）**：一回合上下文改为该会话**最近 20 条**持久化消息 + 本回合新消息（此前只带新消息本身），每条 assistant 历史消息按其说话角色出具 `[发言归属] 以下发言来自「<名字>」（），不是你说的。` 独立 system 标注 + 一条 `[会话角色] …` 当前角色声明；**消息正文一字不改**（标注只走 system 消息，design/11 §10），**对客户端透明**（无新字段）。前端无需改动即可继续工作；面板可选用 ① 让每个 IM 账号挂角色。⑤ **向后兼容**：纯新增可选字段；未配置 `personaId` 的账号与不读新字段的客户端行为不变（渠道绑定缺省 = 全局默认角色，与 v0.43 完全一致）。 - `v0.43`（**人格读侧合并批：admin 回读 `thinking` + 用户侧角色级 `mood`**，对客户端**新增两个可选字段**，向后兼容；design/01 §2/§2.1、design/04 §3.2）：① **`GET /api/v1/admin/personas` 每项新增可选 `thinking`**（`{budgetTokens,effort,showToUser,mode}`），与写侧同构、供面板回填编辑。**未配置的人格不带 `thinking` 键**（不是全零对象），与 `PUT` 的「省略 `thinking` = 保留已存」互为镜像。② **`showToUser` 三态原样回读**：**`null` = 未配置 → 保持现行为（thinking 帧照常推客户端）**，`true`/`false` = 显式开关；**服务端不把 `null` 拍平成 `false`**（否则面板会把「没配过」误显示为「关」，v0.41 的语义会被读侧丢掉）。③ **`GET /api/v1/personas` 每项新增 `mood`（角色级）**：= 该角色**当前情绪状态**（取值同 `GET /meta/enums` 的 `moods`；`""` = 暂无被跟踪情绪，不伪造）。**情绪跟随角色、与会话无关**——同一角色的所有会话看到同一 `mood`；客户端登录/加载角色目录时用它**播种心情徽标**（按角色 id 分桶），消除「刷新后徽标短暂为空」，随后仍以 WS `mood` 帧为准。**用户侧不暴露 `thinking`**（模型调用旋钮属管理侧）。④ **`effort` 的能力提示归服务端**：读端点只回读**已存配置**，**不承诺**该值在当前 provider 上生效——白名单校验/降级/WARN 仍在模型层（design/04 §3.2），客户端不得把「配了」呈现为「已启用」。⑤ **向后兼容**：纯新增字段；不读新字段的客户端行为逐字节不变（旧面板仍可编辑并保留已存 `thinking`）。 -- `v0.42`（**多角色并存 + 按会话选角**，对客户端**新增可选字段/可选请求字段**，向后兼容；design/22 批次 1 = 后端会话级绑定）：① **`chat_sessions` 新增 `persona_id TEXT NOT NULL DEFAULT ''`、`chat_messages` 新增 `persona_id TEXT NOT NULL DEFAULT ''`**（同一迁移 **0011**，down 可逆，**不回填**）。`''` **= 继承全局默认角色**（`owner.yaml:defaultPersona`），所以**既有一切行升级后行为逐字节不变**，且默认角色改名后这些行跟着变（design/22 §4.7/§7-6）。② **`GET /api/v1/sessions` 每项新增可选 `personaId`**（=会话绑定角色）；**消息 DTO（REST `GET /sessions/{id}/messages`、WS `history` 回放、`message_persisted`/`message_edited` 广播）新增可选 `personaId`**（=**说话时的角色**，design/22 §7-5）。③ **`POST /api/v1/sessions` body 新增可选 `{personaId}`**（创建即绑定；未知角色 `400`；响应仅在非空时回显 `personaId`，故**省略时响应形状与 v0.41 完全一致**）；**`PATCH /api/v1/sessions/{id}` body 新增可选 `{personaId}`**（重新绑定，**显式 `""` 解绑**，未知角色 `400`；只回显变更字段）。④ **回合语义**：角色决定**系统提示词 / 记忆命名空间 / 情绪与好感度 / 思考预算**四者**同源**解析（design/22 §4.2），换角色**保留上下文**、**不动已存消息**，**下一回合**起生效；**记忆口径 = 保持 persona 隔离**（design/22 §3）：不同角色的会话互不浮现，同角色的多个会话互相可见。⑤ **请求级覆盖（每次发送临时指定角色）本批未实现**（design/22 §2 裁决规则 1 仍待批次 2/后续）；**渠道级绑定（IM 账号/群默认角色）本批未实现**（design/22 §4.4 批次 2），故 IM 路径仍按默认角色解析。⑥ **契约内新增内部读接口**：网关经窄接口类型断言读取 `history.Store.SessionPersona/SetSessionPersona/NewSubSessionFor`（注入的 HistoryStore **不支持**角色绑定时，`personaId` 写路径回 `501` 而非假成功）。 +- `v0.42`（**多角色并存 + 按会话选角**，对客户端**新增可选字段/可选请求字段**，向后兼容；design/22 批次 1 = 后端会话级绑定）：① **`chat_sessions` 新增 `persona_id TEXT NOT NULL DEFAULT ''`、`chat_messages` 新增 `persona_id TEXT NOT NULL DEFAULT ''`**（同一迁移 **0011**，down 可逆，**不回填**）。`''` **= 继承全局默认角色**（`owner.yaml:defaultPersona`），所以**既有一切行升级后行为逐字节不变**，且默认角色改名后这些行跟着变（design/22 §4.7/§7-6）。② **`GET /api/v1/sessions` 每项新增可选 `personaId`**（=会话绑定角色）；**消息 DTO（REST `GET /sessions/{id}/messages`、WS `history` 回放、`message_persisted`/`message_edited` 广播）新增可选 `personaId`**（=**说话时的角色**，design/22 §7-5）。③ **`POST /api/v1/sessions` body 新增可选 `{personaId}`**（创建即绑定；未知角色 `400`；响应仅在非空时回显 `personaId`，故**省略时响应形状与 v0.41 完全一致**）；~~**`PATCH /api/v1/sessions/{id}` body 新增可选 `{personaId}`**（重新绑定，**显式 `""` 解绑**，未知角色 `400`；只回显变更字段）~~（**本条的「PATCH 重新绑定/解绑」已由 v0.46 作废**：会话角色在创建时确定、之后不可变，PATCH 一旦收到 `personaId` 即回 `400`，见 §1 行 8 / §8-1）。④ **回合语义**：角色决定**系统提示词 / 记忆命名空间 / 情绪与好感度 / 思考预算**四者**同源**解析（design/22 §4.2）；~~换角色**保留上下文**、**不动已存消息**，**下一回合**起生效~~（**已由 v0.46 作废**：会话内不再换角色——角色在创建时定死，`chat_messages.persona_id` 仍逐条记录"谁说的"）；**记忆口径 = 保持 persona 隔离**（design/22 §3）：不同角色的会话互不浮现，同角色的多个会话互相可见。⑤ **请求级覆盖（每次发送临时指定角色）本批未实现**（design/22 §2 裁决规则 1 仍待批次 2/后续）；**渠道级绑定（IM 账号/群默认角色）本批未实现**（design/22 §4.4 批次 2），故 IM 路径仍按默认角色解析。⑥ **契约内新增内部读接口**：网关经窄接口类型断言读取 `history.Store.SessionPersona/SetSessionPersona/NewSubSessionFor`（**v0.46 起**请求路径不再调用 `SetSessionPersona`——PATCH 的 persona 写路径已整体移除；「注入的 HistoryStore **不支持**角色绑定」只在 `POST /sessions` **显式传** `personaId` 时回 `501`，而非假成功）。 - `v0.41`（**人格 `thinking` 配置 + 推理旋钮按 provider 映射**，对客户端**新增一个可选请求字段**，向后兼容）：① `POST /admin/personas` / `PUT /admin/personas/{id}` body 新增可选 **`thinking`** 对象 `{budgetTokens?,effort?,showToUser?,mode?}`（design/01 §2.1），原样写入并持久化到 `configs/personas/.yaml` 的 `thinking` 节；非法 `mode`/负预算回 **`400 bad_request`**；**`PUT` 省略该对象时保留已存 `thinking`**（旧面板/脚本不会抹掉它）；该字段只描述**呈现/资源**，不构成能力边界。② **`showToUser` 语义**：**缺省 = 照常把 `thinking.*` 流帧推给客户端**（现行为），显式 `false` = 仅落库/剥离语义不变、**不推帧**（展示与落库解耦）。③ **服务端推理映射**（对客户端透明，仅影响上游请求）：Anthropic 系在 persona 配置 `budgetTokens`/`mode: on` 时发 `thinking:{type:"enabled",budget_tokens:N}`，并**保证 `budget_tokens + 正文留量 ≤ max_tokens`**（不足则抬高 `max_tokens` 并记 WARN，绝不把正文吃空）；OpenAI 兼容系按**识别到的厂商白名单**校验 `reasoning_effort`（OpenAI 系 `none…max`、DeepSeek 仅 `low/high/max`），非法值**降级到最近一档并记 WARN**；**未知 provider/未识别模型、以及 Qwen 的 `enable_thinking` 硬开关（协议无统一 wire 形状）** 一律记 **WARN（含 provider/字段/取值）并保持请求不变**，绝不静默无效。详见 design/04 §3.2。 - `v0.40`（**`viewer` 角色真正接线：只读监控档**，对客户端**收紧/放宽若干 admin 读的鉴权**，无端点/字段形状变更）：此前 `viewer` 只是常量（`internal/auth` 的 `RoleViewer` 注释写着「只读 dashboard/logs/monitoring」）而**从未接线**——管理侧 24 条 GET 全走 owner/admin，`viewer` 一条都读不到（**全 403**）。本版新增第四道门 `viewerAuth = owner+admin+viewer`，并把 **12 条只读监控 GET** 从 owner/admin 放宽到 owner/admin/**viewer**：`GET /admin/personas`、`/admin/sessions`、`/admin/plugins`、`/admin/plugins/installed`、`/admin/channels`、`/admin/iot`、`/admin/automations`、`/admin/rag`、`/admin/observability/metrics`、`/admin/observability/trace`、`/admin/observability/logs`、`/admin/notifications`。**明确不放给 viewer**（含凭据获取路径、他人数据、完整消息/导出明文、审计流水，或 `admin` 也不给）：`GET /admin/memories`、`/admin/llm`、`/admin/users`、`/admin/backthink`、`/admin/observability/audit`、`/admin/channels/messages`、`/admin/channels/{platform}/messages`、`/admin/sessions/{id}/export`、`POST /admin/rag/query`（这 9 条 owner/admin）以及其余 **35 条 owner-only**（全部写操作 + `login-qr`/`login-status`/`view`/`friends`/渠道连接与配置/`plugins/*`/`users/*`/`system/*`）。**匿名**：任意 admin 路由仍 `401`（fail-closed）。**向后兼容**：`owner`/`admin` 语义不变（放行集合是超集），仅 `viewer` 的可见面从「全 403」变为 12 条只读监控；不依赖 `viewer` 的客户端行为不变。完整分档见 §2.0「管理侧权限矩阵」。 - `v0.39`（**微信 iLink 会话被拒可见化 + 不再假 OK**，对客户端**新增两个可选字段、一处错误码**，向后兼容）：① **`GET /api/v1/admin/channels` 每平台行新增可选 `needsRescan`（bool，`omitempty`）+ `lastError`（string，`omitempty`）**——仅当适配器**真的**要求重新授权时出现（今天只有微信 iLink 返回 `errcode=-14` 这一种），取值来自适配器新增的**可选能力接口** `RescanRequired() (bool, string)`，网关**经类型断言**读取（主 `PlatformAdapter` 契约**不变**；未实现该能力的平台字段**缺省不出现**）。用途：把「需要重新扫码」与「主人自己关掉的未连接」区分开——后者仅 `connected:false`。② **`POST /admin/channels/open`** 对「iLink 已拒绝该会话」回 **`409 session_rejected`**（message 明确要求用「扫码登录」重新绑定），**不再**吞掉错误回 200；`409 needs_login`（尚无 token，v0.8 起）不变。③ **适配器行为**：iLink `errcode=-14` 进入**显式被拒态**——`IsConnected()` 恒 `false`；`Connect()` 返回被拒错误（**不再**对被拒会话报成功）；`HealthCheck` 区分「会话被拒」与「未连接」；并以 **`ERROR`** 级日志写明「本次会话已被 iLink 拒绝，需要重新扫码绑定」（只带 `bot_id` 等非敏感标识，**token 永不入日志**）。被拒态在读循环与发送两条路径**都会**置位，并仅在**扫码登录拿到新 token** 或**配置换了新 token**（保存 + 热重载）时清除。④ 扫码登录侧：被拒期间 `login-status` 报 **`failed` + 被拒原因**（**不再**假报 `confirmed`，否则面板会把已作废凭据当成功重新落盘）；`login-qr` 仍可正常出码（**不**回 `already_logged_in`，否则重新扫码这条路被堵死）；`get_bot_qrcode` 不再携带已被拒的 token（否则服务端以「已绑定」应答、**不**发新凭据）。**向后兼容**：只新增可选字段与一处更诚实的错误码；不读新字段、不处理 409 的客户端行为不变（此时面板显示「未连接」，仍可用「扫码登录」恢复）。**语义澄清（本次仅措辞，不改契约形状、不另起版本号——v0.39 尚未被任何客户端采用）**：iLink 的 bot token 是**长期凭据**（实测一个月前扫码得到的 token 仍可用），`errcode=-14` 表示 **iLink 侧拒绝/作废了该会话凭据**，**不是时间性过期**。详见 §2 行 6 与「微信 iLink『会话被拒』契约」。 diff --git a/frontend/web/src/admin/modules/Sessions.tsx b/frontend/web/src/admin/modules/Sessions.tsx index eff7f59..f0d9d8f 100644 --- a/frontend/web/src/admin/modules/Sessions.tsx +++ b/frontend/web/src/admin/modules/Sessions.tsx @@ -1,12 +1,7 @@ import { useState } from "react"; import { useAsyncData } from "../../lib/useAsyncData"; -import { - adminListPersonas, - adminListSessions, - createSubSession, - patchSession, -} from "../../lib/api"; -import type { PersonaRecord, SessionMeta } from "../../lib/types"; +import { adminListSessions, createSubSession } from "../../lib/api"; +import type { SessionMeta } from "../../lib/types"; import { useAutoReload } from "../hooks"; import { useAuditStore } from "../audit"; import { AdminTable, Notice, PageHeader, type AdminColumn } from "../components"; @@ -22,49 +17,11 @@ function exportMeta(sess: SessionMeta): void { URL.revokeObjectURL(url); } -/** The role cell of one row: the session's bound role, editable in place. An id - * that is not in the catalog (role deleted, catalog still loading) keeps its own - * option, so the cell never silently reads as "inherit the default". */ -function PersonaCell({ - session, - personas, - disabled, - onChange, -}: { - session: SessionMeta; - personas: PersonaRecord[]; - disabled: boolean; - onChange: (personaId: string) => void; -}): React.ReactNode { - const bound = session.personaId ?? ""; - const unknown = bound !== "" && !personas.some((p) => p.id === bound); - return ( - - ); -} - -/** The session table's columns. Built per render because two of the cells are - * wired to the module's live state (the busy flag, the role catalog). */ -function buildColumns(opts: { - personas: PersonaRecord[]; - busy: string | null; - onChangePersona: (sessionId: string, personaId: string) => void; -}): AdminColumn[] { - const { personas, busy, onChangePersona } = opts; +/** The session table's columns. Built per render because the action cell is wired to + * the module's live busy flag. The 角色 cell is read-only: a session's role is fixed + * when it is created (design/22 §8-1), so the panel shows the binding it was created + * with instead of offering a re-bind — changing the role means creating a session. */ +function buildColumns(busy: string | null): AdminColumn[] { return [ { key: "type", title: "类型", render: (s) => {s.type === "main" ? "主会话" : "次级会话"} }, { key: "title", title: "标题", render: (s) => {s.title ? s.title : （未命名）} }, @@ -73,12 +30,9 @@ function buildColumns(opts: { key: "persona", title: "角色", render: (s) => ( - onChangePersona(s.id, personaId)} - /> + + {s.personaId ? s.personaId : （继承默认角色）} + ), }, { key: "createdAt", title: "创建时间", render: (s) => {new Date(s.createdAt).toLocaleString()} }, @@ -94,14 +48,12 @@ function buildColumns(opts: { ]; } -/** The page's two write actions, both audited. The list is re-read on success — - * the PATCH reply is not a full session row — which also refreshes the row from - * server truth instead of a local guess. */ +/** The page's write action, audited. The list is re-read on success so the new row + * comes from server truth instead of a local guess. */ function useSessionMutations(reload: () => void): { busy: string | null; fail: string | null; newSubSession: () => void; - changePersona: (sessionId: string, personaId: string) => void; } { const [busy, setBusy] = useState(null); const [fail, setFail] = useState(null); @@ -132,19 +84,14 @@ function useSessionMutations(reload: () => void): { fail, newSubSession: () => run("new", "session.create", () => createSubSession(), "新建次级会话失败"), - changePersona: (sessionId, personaId) => - run(sessionId, "session.persona", () => patchSession(sessionId, { personaId }), "挂角色失败"), }; } export function SessionsModule(): React.ReactNode { const { data, loading, error, reload } = useAsyncData(adminListSessions, []); useAutoReload(reload, 10000); - // The role catalog for the "挂角色" column (design/22 §4.6); the panel reads it - // from the admin endpoint, and the write goes through the ordinary session PATCH. - const personas = useAsyncData(adminListPersonas, []); const [query, setQuery] = useState(""); - const { busy, fail, newSubSession, changePersona } = useSessionMutations(reload); + const { busy, fail, newSubSession } = useSessionMutations(reload); const filtered = (data ?? []).filter((s) => { if (!query.trim()) return true; @@ -156,11 +103,7 @@ export function SessionsModule(): React.ReactNode { ); }); - const columns: AdminColumn[] = buildColumns({ - personas: personas.data ?? [], - busy, - onChangePersona: changePersona, - }); + const columns: AdminColumn[] = buildColumns(busy); return (

@@ -200,8 +143,7 @@ export function SessionsModule(): React.ReactNode { 列表来自后端持久化会话（主会话 + 次级会话），主会话 id 固定。导出为会话元数据 JSON；身份判定永远由 actor 元数据 + 白名单 + 策略引擎完成，不依赖提示词。 - 「角色」列是会话挂载的角色（design/22 §4.6）：「继承默认角色」= 会话不绑定，随全局默认角色走； - 改角色决定该会话记忆/情绪/提示词的归属（owner-only + 审计）。 + 「角色」列只读显示该会话创建时绑定的角色（design/22 §4.6/§8-1）：会话角色在创建时确定、之后不可变，要换角色请新开会话（本页「新建次级会话」按默认角色新建，用户端侧栏的新建会话可选角色）。
); diff --git a/frontend/web/src/components/SessionRail.tsx b/frontend/web/src/components/SessionRail.tsx index cc56bc4..5bd69ec 100644 --- a/frontend/web/src/components/SessionRail.tsx +++ b/frontend/web/src/components/SessionRail.tsx @@ -1,6 +1,5 @@ import { useState } from "react"; -import { createSubSession, getAuthToken, patchSession } from "../lib/api"; -import { setSessionPersona } from "../lib/sessionPersona"; +import { createSubSession, getAuthToken } from "../lib/api"; import { useAppStore } from "../store/useAppStore"; import type { PersonaRecord, SessionMeta } from "../lib/types"; import { Icon } from "./Icon"; @@ -8,14 +7,12 @@ import { NavItem } from "./NavItem"; import { Button } from "./primitives"; /** - * The conversation list in the rail (design/16 §2 + design/22 §4.6): + * The conversation list in the rail (design/16 §2 + design/22 §4.6/§8-1): * - main session first, secondary sessions by creation time, unread badges; * - "新建会话" reveals a role picker, so a new conversation can start bound to a - * role (empty = inherit the global default role); - * - every row has a role menu that re-binds *that* session through - * `PATCH /sessions/{id} {personaId}` (design/22 §4.6). Changing a session's - * role changes which memory / emotion / system prompt the session talks to, so - * it stays an explicit, per-session action instead of a global switch. + * role (empty = inherit the global default role). This is the ONLY place a role + * is picked: a session's role is fixed at creation (design/22 §8-1), so a row has + * no role menu to re-bind it — switching roles means starting a new conversation. * * Kept out of `Nav.tsx` so no single component grows past the 80-line rule. */ @@ -25,12 +22,6 @@ export function SessionRail({ onNavigate }: { onNavigate: () => void }): React.R const setSessions = useAppStore((s) => s.setSessions); const setActiveSession = useAppStore((s) => s.setActiveSession); const personas = useAppStore((s) => s.personas); - const setSessionPersonaLocal = useAppStore((s) => s.setSessionPersona); - /** The session whose role menu is expanded, or null when none is open. */ - const [menuFor, setMenuFor] = useState(null); - /** Set when a role change was rejected, so the row can say so instead of - * silently showing the role the server still has. */ - const [failed, setFailed] = useState(false); if (!getAuthToken()) return null; @@ -58,104 +49,37 @@ export function SessionRail({ onNavigate }: { onNavigate: () => void }): React.R onNavigate(); }; - /** Re-bind one session to a role: written optimistically into the store and - * rolled back when the PATCH is rejected (lib/sessionPersona.ts), so the rail - * never keeps showing a binding the server refused. */ - const changePersona = async (sessionId: string, personaId: string) => { - setFailed(false); - const applied = await setSessionPersona( - { - read: (id) => useAppStore.getState().sessions[id]?.personaId ?? "", - write: setSessionPersonaLocal, - persist: (id, pid) => patchSession(id, { personaId: pid }), - }, - sessionId, - personaId - ); - if (applied) setMenuFor(null); - else setFailed(true); - }; - return (
会话
{sessionList.map((s) => ( - openSession(s.id)} - onToggleMenu={() => { - setFailed(false); - setMenuFor(menuFor === s.id ? null : s.id); - }} - onChangePersona={(personaId) => void changePersona(s.id, personaId)} - /> + openSession(s.id)} /> ))}
); } -/** One conversation row plus its role menu. */ +/** One conversation row. It carries no role affordance: the role is fixed when the + * session was created (design/22 §8-1), so the only thing a row does is open. */ function SessionEntry({ session, active, - menuOpen, - failed, - personas, onOpen, - onToggleMenu, - onChangePersona, }: { session: SessionMeta; active: boolean; - menuOpen: boolean; - failed: boolean; - personas: PersonaRecord[]; onOpen: () => void; - onToggleMenu: () => void; - onChangePersona: (personaId: string) => void; }): React.ReactNode { const label = session.title ?? (session.type === "main" ? "主会话" : "次级会话"); return ( -
- - - - } - /> - {menuOpen ? ( -
- 会话角色 - - {failed ? ( - 切换失败，已保持原角色 - ) : null} -
- ) : null} -
+ ); } @@ -236,11 +160,12 @@ function CreateSessionSection({ ); } -/** Miuix-styled role picker over `GET /personas` (design/22 §4.6). The empty - * option means "inherit the global default role" — the value a session with no - * binding has — so a session can always be returned to the default. A value that - * is not in the catalog (role deleted, catalog still loading) is shown as its own - * option rather than silently reading as "inherit". */ +/** Miuix-styled role picker over `GET /personas` (design/22 §4.6), used only by the + * "new conversation" panel: the empty option means "inherit the global default + * role", which is a perfectly normal way to create a session (and the only role + * choice left — a created session cannot be re-bound, §8-1). Every value this + * control shows comes from that catalog or is "", so it needs no "unknown role" + * escape hatch. */ function RoleSelect({ value, personas, @@ -254,7 +179,6 @@ function RoleSelect({ label: string; onChange: (personaId: string) => void; }): React.ReactNode { - const unknown = value !== "" && !personas.some((p) => p.id === value); return (