Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/plugin-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading