diff --git a/docs/plugin-protocol.md b/docs/plugin-protocol.md index 622f184b2b..27c7e86a77 100644 --- a/docs/plugin-protocol.md +++ b/docs/plugin-protocol.md @@ -213,6 +213,14 @@ Marker divert (#3248 phase 2 — native extensions): instead of switching the pr 中文集成要点:fork 协议现为 2(服务端同时接受 1);先读取 manifest 能力及 snapshot,按原文、role、工具身份确认匹配前缀,仅提交该前缀的 orderedMessages,不猜测多模态分支点。被 `compress.protectedTools` 硬排除的消息在两个数组中均为 `"ref": null`(参与顺序与身份、无地址 ref),与其他前缀条目一样逐字提交;ref 合法值仅 `mNNNNN` 字符串或 `null`。父 revision 变化必须重新取快照并重新匹配。子会话使用独立稳定 id,首次请求可追加尚未出站的模型回复,不能重置继承的 refs/blocks。手动摘要使用 snapshot 的 refs 和 `expectedRevision: snapshot.parentRevision` 调用公开 tool;摘要期间历史发生变化时返回 409,不执行旧摘要。状态栏读取 `contextTokens`、`contextTokensSource`、`contextTokensAt`、`model`、`contextLimit`、`contextGeneration`、`sessionId` 与 `sessionRevision`,不得用累计账单 input/cache 冒充有效上下文。手动 compress/decompress 后为独立时间及 generation 的 estimate,不改累计账单或 last-usage 基线;下一次正数 usage 才恢复 usage,零值或缺失 usage 不得复活旧观测。未知来源返回 unavailable,tokens/time/generation 为 null。 +Session display name (`POST /__bili/plugin/session-name`, #2322): a host names its conversation so the web panel shows a real title instead of the derived first-message fallback. Body `{ conversationId, name }`; latest-wins, an empty `name` clears it (display falls back to the derived first-message title), and `name` is whitespace-normalized and capped at 200 chars. Only **pi** (`src/agent/pi.ts`) and **dsh-native** (`src/agent/dsh-native.ts`) report it today — each reads the host's own session title from its in-loop seam and POSTs on change; omp/opencode do not report either. **zcode does not**: its lane is only a SessionStart hook plus an MCP entry, neither sits on the model-request path, and ZCode keeps the conversation title in its Electron layer where the plugin cannot read it — until ZCode exposes a title seam, zcode sessions fall back to the derived first-message title (#5702). + +Residency semantics (why an idle POST returns 404): the endpoint resolves `conversationId` against RESIDENT sessions only — the in-memory session object lives in a bounded LRU resident pool (session-count + byte-budget caps), so it survives the gaps between requests of an active conversation but cools out of memory once an idle session is evicted under pool pressure, and a POST after that answers `404`. The error distinguishes the two causes: `(id registered but session not resident)` when the id was seen before but the session has since cooled out of memory, vs `(no model request has arrived with this conversation id yet)` when it was never seen. Practical rule: report during a model-request window. Other errors: `400` invalid JSON / missing `conversationId` / non-string `name`. + +Direct-write caveat (for operators scripting around the gap): writing `sessions.host_title` directly in the unified store takes effect immediately for a COOLED session (the panel reads the store), but is clobbered by the resident process's end-of-request writeback while the session is active — the in-memory meta (empty `hostTitle`) overwrites the value you wrote. Direct-write only cooled sessions; never an active one. + +中文要点(#5702):宿主可用 `POST /__bili/plugin/session-name`(body `{conversationId, name}`)给会话命名,面板优先显示它;最新值生效,空 name 清除并回退到首条消息派生标题,name 归一化空白并截断到 200 字。目前只有 pi 与 dsh-native 上报(各自从 in-loop 接缝读宿主标题),omp/opencode 不上报;zcode 车道只有 SessionStart hook + MCP,都不在模型请求路径上,且 ZCode 把会话标题存在 Electron 层、插件读不到——在 ZCode 提供标题出口之前,zcode 会话只能回退到派生首条消息标题。该端点只对 RESIDENT(常驻内存)会话解析:会话对象住在有界 LRU 常驻池(会话数+字节预算双上限)中,活跃会话在请求间隙保持常驻,空闲会话被池压力逐出后 POST 才返回 404;错误文案区分「id 已注册但会话不在内存」与「从未收到该 id 的模型请求」;实操上请在模型请求窗口内上报。绕过缺口时直写统一存储的 `sessions.host_title`:对已冷却会话立即生效,但对活跃会话会被常驻进程请求结束时的回写(内存里空的 hostTitle)冲掉——只直写冷却会话,切勿直写活跃会话。 + ### Incremental cache-mark updates `GET /__bili/plugin/turn` advertises `cacheControlRetouch: true` when the server