pi-web-ui 0.95.0 → 0.96.1

package/dist/server/read-tool.js

@@ -12,11 +12,16 @@
  * 与 SDK ls 完全一致）；其余情况（文件、图片、路径不存在、读取报错）原样
  * 转发基底，行为与内置完全一致。
  *
+ * 基底也可能是**第三方扩展注册的 read**：`customTools` 恒胜、会把它顶掉（见
+ * tool-overrides.ts），所以那种情况下改走 `withReadDirSupport()` —— 把扩展的实现
+ * 整个当基底叠目录能力，它的 schema/描述/prompt 指引/渲染原样保留（扩展独有的参数
+ * 照旧可用），只有目录分支归 pi-web-ui。
+ *
  * 开关：`readDirEnabled`（设置面板「工具」页，默认开）。**行为开关**不是
  * ActiveSet 开关（read 本体不可关，关了 agent 就残了），因此不进
  * tool-manager 的 AGENT_TOOL_CATALOG；每次调用实时读设置，改动即时生效。
  *
- * 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+ * 文案约定：工具 definition（description/promptSnippet/promptGuidelines）为纯英文；per-call
  * 返回文本（目录头）按 lang 取 pick(lang, zh, en, key)，缺表回落英文内联。
  *
  * DSH 引擎无 customTool 注册面（工具来自 shipped preset），本覆盖只服务 pi 引擎。
@@ -26,7 +31,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve as nodeResolve } from "node:path";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, createLsToolDefinition, createReadToolDefinition, defineTool, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { bilingual, pick } from "./i18n.js";
+import { pick } from "./i18n.js";
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 /**
  * 目录判定用的路径归一：~ / @ 前缀、Unicode 空格、相对 → 绝对（对齐 SDK
@@ -56,16 +61,16 @@ export async function isDirectoryPath(absolutePath) {
 /** 覆盖定义的参数 schema：内置的 path/offset/limit + file_path 别名。 */
 const readDirSchema = Type.Object({
     path: Type.String({
-        description: bilingual("Path to the file (or directory) to read (relative or absolute)", "要读取的文件（或目录）路径（相对或绝对）"),
+        description: "Path to the file (or directory) to read (relative or absolute)",
     }),
     file_path: Type.Optional(Type.String({
-        description: bilingual("Alias of `path` — some clients/models emit file_path; if both are given, `path` wins", "`path` 的别名 —— 部分客户端/模型习惯发 file_path；两者都给时以 `path` 为准"),
+        description: "Alias of `path` — some clients/models emit file_path; if both are given, `path` wins",
     })),
     offset: Type.Optional(Type.Number({
-        description: bilingual("Line number to start reading from (1-indexed)", "从第几行开始读（从 1 起算）"),
+        description: "Line number to start reading from (1-indexed)",
     })),
     limit: Type.Optional(Type.Number({
-        description: bilingual("Maximum number of lines to read (for a directory path: maximum number of entries)", "最多读多少行（路径是目录时 = 最多列多少条目）"),
+        description: "Maximum number of lines to read (for a directory path: maximum number of entries)",
     })),
 }, {});
 /**
@@ -81,9 +86,59 @@ export function prepareReadArguments(raw) {
     // 两者都没给时这里仍缺 path（静态类型是谎，运行时交给 schema 校验报错）。
     return args;
 }
+/** Directory support note appended to any read definition (definitions are English-only). */
+const DIR_DESCRIPTION_NOTE = "Also accepts a directory path: its entries are then listed instead of file contents (one entry per line, directories suffixed with '/'); in that case `limit` caps the number of entries and `offset` is ignored.";
+const DIR_GUIDELINE = "Use read on a directory to list its entries — no need to shell out to `ls`";
+/**
+ * 两条路（内置基底 / 扩展基底）共用的执行体：先判「路径是不是目录」—— 是就复用 SDK 的
+ * ls 列条目（排序/`/` 后缀/截断提示口径一致），否则把请求转发给基底实现。
+ *
+ * `normalizePath`：只给了 `file_path` 别名时补出 `path` 再转发（SDK 内置实现需要）；
+ * 扩展基底传 false —— 它自带 `prepareArguments`，参数原样交给它，免得我们这边把扩展
+ * 独有的字段（如 better-edit 的 `windows`）吃掉。
+ */
+async function dirAwareExecute(base, ls, fallbackCwd, dirEnabled, getLang, normalizePath, toolCallId, params, signal, onUpdate, ctx) {
+    const input = (params ?? {});
+    // 兜底（不依赖 prepareArguments 一定跑过）：path 缺省/空时用 file_path。
+    const rawPath = typeof input.path === "string" && input.path.trim() ? input.path : input.file_path;
+    const path = typeof rawPath === "string" ? rawPath : "";
+    if (path && dirEnabled()) {
+        const cwd = typeof ctx?.cwd === "string" ? ctx.cwd : fallbackCwd;
+        if (await isDirectoryPath(resolvePathForDirCheck(path, cwd))) {
+            const limit = typeof input.limit === "number" && input.limit > 0 ? Math.floor(input.limit) : undefined;
+            // 列目录本体完全复用 SDK 的 ls。
+            const listed = (await ls.execute(toolCallId, { path, ...(limit !== undefined ? { limit } : {}) }, signal, onUpdate, ctx));
+            const header = pick(getLang(), `[目录：${path}]`, `[Directory: ${path}]`, "read.dir.header", { path });
+            // 只取列出来的正文：截断/条目上限提示已在正文末尾，read 卡片的
+            // details 不需要 ls 的字段。
+            const content = listed.content.map((part, index) => index === 0 && part.type === "text" ? { ...part, text: `${header}\n${part.text}` } : part);
+            return { content, details: undefined };
+        }
+    }
+    return base.execute(toolCallId, (normalizePath ? { ...input, path } : params), signal, onUpdate, ctx);
+}
+/**
+ * 在**任意** read 实现（SDK 内置，或第三方扩展 `registerTool` 注册的同名工具）之上叠加
+ * 「路径是目录时列出条目」。基底的 name/label/描述/参数 schema/prepareArguments/render*
+ * 全部原样保留，只补一句目录说明与一条目录指引 —— 于是扩展的锚协议、独有参数、渲染都不丢。
+ */
+export function withReadDirSupport(base, fallbackCwd, options = {}) {
+    const dirEnabled = options.dirEnabled ?? (() => true);
+    const getLang = options.getLang ?? (() => "en");
+    const ls = createLsToolDefinition(fallbackCwd);
+    return defineTool({
+        ...base,
+        description: `${base.description} ${DIR_DESCRIPTION_NOTE}`,
+        promptGuidelines: [...(base.promptGuidelines ?? []), DIR_GUIDELINE],
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            return dirAwareExecute(base, ls, fallbackCwd, dirEnabled, getLang, false, toolCallId, params, signal, onUpdate, ctx);
+        },
+    });
+}
 /**
- * 生成「read 读目录」覆盖定义。cwd 仅供创建时固定；执行时优先 ctx.cwd
- * （会话工作区）。
+ * 生成「read 读目录」覆盖定义（**没有**扩展同名工具时的完整实现：内置基底 + 英文描述 +
+ * `file_path` 别名）。cwd 仅供创建时固定；执行时优先 ctx.cwd（会话工作区）。
+ * 有扩展同名工具时改用 `withReadDirSupport` 组合它的实现（见 tool-overrides.ts）。
  */
 export function makeReadDirTool(fallbackCwd, options = {}) {
     const base = createReadToolDefinition(fallbackCwd);
@@ -92,34 +147,18 @@ export function makeReadDirTool(fallbackCwd, options = {}) {
     const getLang = options.getLang ?? (() => "en");
     return defineTool({
         ...base,
-        description: bilingual(`${base.description} Also accepts \`file_path\` as an alias of \`path\`. If the path is a directory, its entries are listed instead of file contents (one entry per line, directories suffixed with '/'); in that case \`limit\` caps the number of entries and \`offset\` is ignored.`, `读取文件内容。支持文本文件与图片（jpg, png, gif, webp, bmp），图片作为附件发出。文本输出截断到 ${DEFAULT_MAX_LINES} 行或 ${DEFAULT_MAX_BYTES / 1024}KB（先到者为准），大文件用 offset/limit 续读。路径也可用 \`file_path\` 传（path 的别名，两者都给时以 path 为准）。路径是目录时改为列出目录条目（一行一项，目录带 '/' 后缀；此时 limit 是条目上限，offset 忽略）。`),
-        promptSnippet: bilingual("Read file contents (a directory path lists its entries)", "读取文件内容（传目录则列出其条目）"),
+        description: `${base.description} Also accepts \`file_path\` as an alias of \`path\`. ` +
+            "If the path is a directory, its entries are listed instead (one per line, directories suffixed with '/'); `limit` caps the entries and `offset` is ignored.",
+        promptSnippet: "Read file contents (a directory path lists its entries)",
         promptGuidelines: [
             ...(base.promptGuidelines ?? []),
-            bilingual("Use read on a directory to list its entries — no need to shell out to `ls`", "要看目录内容直接把目录路径交给 read，不必再走 bash 的 ls"),
+            "Use read on a directory to list its entries — no need to shell out to `ls`",
         ],
         parameters: readDirSchema,
         prepareArguments: prepareReadArguments,
         async execute(toolCallId, params, signal, onUpdate, ctx) {
-            const input = (params ?? {});
-            // 兜底（不依赖 prepareArguments 一定跑过）：path 缺省/空时用 file_path。
-            const rawPath = typeof input.path === "string" && input.path.trim() ? input.path : input.file_path;
-            const path = typeof rawPath === "string" ? rawPath : "";
-            if (path && dirEnabled()) {
-                const cwd = typeof ctx?.cwd === "string" ? ctx.cwd : fallbackCwd;
-                if (await isDirectoryPath(resolvePathForDirCheck(path, cwd))) {
-                    const limit = typeof input.limit === "number" && input.limit > 0 ? Math.floor(input.limit) : undefined;
-                    // 列目录本体完全复用 SDK 的 ls（排序/`/` 后缀/截断提示口径一致）。
-                    const listed = await ls.execute(toolCallId, { path, ...(limit !== undefined ? { limit } : {}) }, signal, onUpdate, ctx);
-                    const header = pick(getLang(), `[目录：${path}]`, `[Directory: ${path}]`, "read.dir.header", { path });
-                    // 只取列出来的正文：截断/条目上限提示已在正文末尾，read 卡片的
-                    // details 不需要 ls 的字段。
-                    const content = listed.content.map((part, index) => index === 0 && part.type === "text" ? { ...part, text: `${header}\n${part.text}` } : part);
-                    return { content, details: undefined };
-                }
-            }
-            // 转发内置实现时带上归一后的 path（模型可能只给了 file_path）。
-            return base.execute(toolCallId, { ...input, path }, signal, onUpdate, ctx);
+            // 目录分支与转发都在共用执行体里（normalizePath=true：只给了 file_path 时补出 path）。
+            return dirAwareExecute(base, ls, fallbackCwd, dirEnabled, getLang, true, toolCallId, params, signal, onUpdate, ctx);
         },
     });
 }

package/dist/server/resolve-global-sdk.js

@@ -1,22 +1,25 @@
 /**
- * resolve-global-sdk — 可选的「优先用全局/祖先那份 pi SDK」解析钩子（issue #260）。
+ * resolve-global-sdk — pi SDK 副本选择钩子（issue #260；#321 起默认启用）。
  *
  * 背景：pi-web-ui 依赖 `@earendil-works/pi-coding-agent`，而 npm 全局安装会把依赖
  * **嵌在** `<npm root -g>/pi-web-ui/node_modules/`（不 hoist，实测），Node 又「嵌套优先于
  * 祖先」—— 于是用户 `npm i -g @earendil-works/pi-coding-agent@latest` 改的是全局那份，
  * 服务加载的仍是自带那份，表现为「升了 0.86.1，横幅和 /api/health 还显示 0.85.1」。
+ * 这个割裂在 #321 里反复咬人（界面此前完全看不见），所以解析顺序默认反转：
  *
- * 本模块把解析顺序反过来，但**只在显式开启时**：
+ *   缺省 / global / auto   → 机器上有**更新**的 pi 副本（祖先链，如全局 pi CLI）就用它，
+ *                              多份取版本最高的；没有或都更旧 → 自带副本兜底。
+ *   bundled / 0 / off /
+ *   false / no             → 强制自带副本（可复现、CI 覆盖的那份；报 bug 请用它复现）。
  *
- *   PI_WEB_SDK=global   → 祖先链上存在一份版本**更新**的 SDK 时，把裸标识符重定向到它；
- *                         否则原样不动（同版本也不折腾 —— 没意义）。
- *   （缺省 / 其它值）    → 什么都不做，用自带副本。
+ * 为什么「绝不降级」：祖先副本必须严格比自带的新才采用（同版本继续用自带那份，
+ * 少一次重定向）；绝不为了「用全局」而跑更旧的版本。
  *
- * 为什么默认关：服务运行的 SDK 版本会变成「用户机器上装了什么」，同一个 pi-web-ui 版本在
- * 不同机器上跑不同 SDK，报 bug 时无法复现；自带副本可复现、且是 CI 覆盖的那一份。
- *
- * 为什么只做「必须更新」这一道门：仓库没有 semver 依赖，手写完整范围解析容易出错，
- * 「祖先那份比自带那份新」是保守且够用的判据（旧的 / 同版本的都不采用）。
+ * 为什么默认跟随（#321）：用户升级全局 pi 后界面「显示没更新」，每个版本都有人踩，
+ * 每次都要人肉排查。可复现性的代价用两条路补回来：界面更新面板与 /api/health 的
+ * `piSdkCopies` 都如实报出实际加载的那份；`PI_WEB_SDK=bundled` 随时显式换回自带。
+ * 「全局 SDK 比宿主新」的兼容风险是被接受的：pi 与 pi-web-ui 同步演进，跟随全局
+ * 正是用户升级 pi 的本意。
  *
  * 安全约定：整个注册流程包在 try/catch 里，任何异常都退回默认解析 —— 这个模块**绝不允许**
  * 让服务起不来。它必须在任何 SDK 静态 import **之前**被加载（`--import <本文件>`，
@@ -26,18 +29,28 @@ import { registerHooks } from "node:module";
 import { pathToFileURL } from "node:url";
 import { compareVersions, sdkCopies } from "./sdk-origin.js";
 const PKG = "@earendil-works/pi-coding-agent";
+/** 显式强制自带副本的取值（旧默认；可复现、CI 覆盖的那份）。 */
+const BUNDLED_MODES = new Set(["bundled", "0", "off", "false", "no"]);
 /**
  * 该用哪一份对外解析（纯函数，便于单测）。
- * `copies` 按 Node 的解析顺序（[0] = 自带的、实际会被用到的），返回 null = 保持默认。
+ * `copies` 按 Node 的解析顺序（[0] = 自带的、无钩子时实际会被用到的），
+ * 返回 null = 保持默认（用自带副本兜底）。
  */
 export function pickGlobalSdk(copies, mode) {
-    if ((mode ?? "bundled").trim().toLowerCase() !== "global")
+    if (BUNDLED_MODES.has((mode ?? "global").trim().toLowerCase()))
         return null;
     const bundled = copies[0];
-    // 只考虑祖先链上的副本，且必须是**更新**的（旧的或同版本都不折腾）。
-    return copies.slice(1).find((c) => !bundled || compareVersions(c.version, bundled.version) > 0) ?? null;
+    // 只考虑祖先链上**严格更新**的副本，多份取版本最高的（旧的/同版本的都不折腾）。
+    let best = null;
+    for (const copy of copies.slice(1)) {
+        if ((!bundled || compareVersions(copy.version, bundled.version) > 0) &&
+            (!best || compareVersions(copy.version, best.version) > 0)) {
+            best = copy;
+        }
+    }
+    return best;
 }
-/** 注册钩子；返回实际选中的副本（null = 没启用 / 没找到可用的）。 */
+/** 注册钩子；返回实际选中的副本（null = 用自带副本）。 */
 export function registerGlobalSdkPreference(mode = process.env.PI_WEB_SDK, fromFile = import.meta.url) {
     try {
         const copies = sdkCopies(fromFile);
@@ -68,5 +81,6 @@ export function registerGlobalSdkPreference(mode = process.env.PI_WEB_SDK, fromF
 // ---- 副作用：被 `--import` 加载时立刻生效 --------------------------------
 const used = registerGlobalSdkPreference();
 if (used) {
-    console.log(`[pi-web-ui] PI_WEB_SDK=global → using the pi SDK at ${used.path} (v${used.version})`);
+    console.log(`[pi-web-ui] following a newer pi SDK on this machine: ${used.path} (v${used.version}; ` +
+        "set PI_WEB_SDK=bundled to pin the bundled copy)");
 }

package/dist/server/schedule-agent-tool.js

@@ -13,12 +13,12 @@
 // 到期执行走 index.ts 的 executor：目标对话还在 → steer 语义唤醒它（不切用户
 // 当前对话）；不在了（关闭/重启）→ 回落原有无头执行；单次任务触发后自动删除。
 //
-// 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+// 文案约定：工具 definition（description/promptSnippet/promptGuidelines）为纯英文；per-call
 // 返回文本按 lang 取 pick(lang, zh, en, key, vars)，缺表回落英文内联。
 // ---------------------------------------------------------------------------
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { bilingual, pick } from "./i18n.js";
+import { pick } from "./i18n.js";
 import { SCHEDULE_CANCEL_TOOL_NAME, SCHEDULE_LIST_TOOL_NAME, SCHEDULE_TASK_TOOL_NAME } from "./tool-manager.js";
 import { computeNextFire, describeIntervalMs, SCHEDULER_MIN_INTERVAL_MS, } from "./scheduler-tasks.js";
 import { parseCronSpec } from "./plugin-schedule.js";
@@ -107,17 +107,11 @@ export function makeScheduleTools(host, ownerConversationId, lang) {
     const taskTool = defineTool({
         name: SCHEDULE_TASK_TOOL_NAME,
         label: "Schedule a wake-up in this conversation",
-        description: bilingual("Create a scheduled wake-up in the CURRENT conversation: at the given cron time or after the given delay, the scheduler automatically delivers your prompt back into this conversation so you continue the work and report to the user. " +
-            "Use it when the user asks for periodic checks, delayed reminders, or scheduled summaries — do NOT fake it with sleep loops (a sleeping script can never push a message back). " +
-            'Schedule accepts a 5-field cron ("0 * * * *" = hourly) or a relative delay ("in 30m", "in 1h", "30m"); minimum interval is 60s. ' +
-            "One-shot by default (recurring=false auto-deletes the task after it fires); pass recurring=true for repeats. " +
-            "The wake-up binds the originating conversation AND its persisted session file: after context compaction or a restart the scheduler re-binds to the same session automatically; if the original conversation is gone it first falls back to the project's active conversation (and visibly reports the move), and only runs headless (report in panel history) when no live conversation exists for the project. " +
-            "Manage with schedule_list / schedule_cancel; the user can also cancel from the background-tasks panel.", "在**当前对话**里创建一个定时唤醒：到指定 cron 时间或延迟后，调度器自动把你的 prompt 投回本对话，你继续执行并向用户汇报。" +
-            "用户要求定时巡检、延时提醒、定时汇总时用它 —— 不要用 sleep 死循环假装答应（休眠的脚本推不回任何消息）。" +
-            "时间写法收 5 字段 cron（“0 * * * *”=每小时）或相对延迟（“in 30m”“in 1h”“30m”）；最短间隔 60s。" +
-            "默认单次（recurring=false 触发后自动删除）；传 recurring=true 做周期任务。" +
-            "唤醒绑定发起对话与其落盘会话文件：上下文压缩或重启后自动重绑到同一会话；原对话不在时先回落到同项目的活跃对话（并明确提示迁移），同项目无存活对话才无头执行，报告留在调度面板历史里。" +
-            "用 schedule_list / schedule_cancel 管理；用户也可从后台任务面板取消。"),
+        description: "Create a scheduled wake-up in the CURRENT conversation: at the cron time or after the delay, your prompt is delivered back into this conversation so you continue and report. " +
+            "Use for periodic checks, delayed reminders, scheduled summaries — never sleep loops (they cannot push messages back). " +
+            'schedule: 5-field cron ("0 * * * *" hourly) or delay ("in 30m"); minimum 60s. One-shot by default; recurring=true repeats. ' +
+            "Re-binds to the same session after compaction/restart; if the conversation is gone it falls back to the project's active conversation (visibly reported), headless only when none exists. " +
+            "Manage with schedule_list / schedule_cancel.",
         promptSnippet: "schedule a wake-up in this conversation (cron or delay), auto-report on fire",
         parameters: Type.Object({
             schedule: Type.String({
@@ -210,7 +204,9 @@ export function makeScheduleTools(host, ownerConversationId, lang) {
     const listTool = defineTool({
         name: SCHEDULE_LIST_TOOL_NAME,
         label: "List scheduled tasks",
-        description: bilingual("List all built-in scheduled tasks (all projects): id, name, cron/interval, on/paused, one-shot, target conversation, next fire, last run. Use it to inspect before cancelling, or to answer the user about what is scheduled.", "列出全部内置定时任务（跨项目）：id、名称、cron/间隔、启用/暂停、单次、目标对话、下次触发、上次结果。取消前先看，或回答用户“排了什么”时用。"),
+        description: "List all built-in scheduled tasks (all projects): " +
+            "id, name, cron/interval, on/paused, one-shot, target conversation, next fire, last run. " +
+            "Use it to inspect before cancelling, or to answer the user about what is scheduled.",
         promptSnippet: "list scheduled wake-up tasks",
         parameters: Type.Object({}),
         execute: async () => {
@@ -235,7 +231,8 @@ export function makeScheduleTools(host, ownerConversationId, lang) {
     const cancelTool = defineTool({
         name: SCHEDULE_CANCEL_TOOL_NAME,
         label: "Cancel a scheduled task",
-        description: bilingual("Delete a scheduled task by id (see schedule_list). Deleting stops all future fires; use it when the user says the schedule is no longer needed.", "按 id 删除定时任务（id 见 schedule_list）。删除后不再触发；用户说不用排了时用它。"),
+        description: "Delete a scheduled task by id (see schedule_list). " +
+            "Deleting stops all future fires; use it when the user says the schedule is no longer needed.",
         promptSnippet: "cancel a scheduled task by id",
         parameters: Type.Object({
             id: Type.String({ description: "Task id from schedule_list." }),

package/dist/server/sdk-origin.js

@@ -52,13 +52,29 @@ export function compareVersions(a, b) {
     return 0;
 }
 /**
- * 启动横幅要打印的一行（不含前缀），以及是否需要提示「你升的不是服务在用的那份」。
+ * 本进程实际加载的是否为**随包自带**的那份（未被钩子重定向到祖先链副本）。
+ * 判据：自带副本是解析顺序上的第一份，且钩子只在祖先副本**严格更新**时才重定向
+ * （同版本继续用自带），所以 running == copies[0] ⟺ 自带在用。copies 为空
+ * （如部分桌面/容器布局）时按自带算 —— 那本来就是唯一能加载的份。
+ * UI 用它决定是否亮「安装全局引擎并切换」入口（issue #321）。
+ */
+export function isBundledInUse(copies, effectiveVersion) {
+    return copies.length === 0 || effectiveVersion === copies[0].version;
+}
+/**
+ * 启动横幅要打印的一行（不含前缀），以及是否需要提示「本进程在用的不是最新的那份」。
  * `effective` 为空时（没找到副本）返回空串，调用方照旧只打印版本号。
+ *
+ * #321 起默认会自动跟随更新的那份（resolve-global-sdk），所以这条提示出现即意味着：
+ * 进程启动时没跟上（升级发生在启动后 / 旧构建没注入钩子），或用户显式
+ * PI_WEB_SDK=bundled 钉死了自带副本 —— 文案把两种出路都写明。
  */
 export function sdkOriginNote(copies, effectiveVersion) {
     const shadowed = copies.slice(1);
     const newer = shadowed.filter((c) => compareVersions(c.version, effectiveVersion) > 0);
     if (newer.length === 0)
         return null;
-    return `a newer pi SDK is installed elsewhere (${newer.map((c) => `v${c.version}`).join(", ")}) but pi-web-ui runs its own bundled copy (v${effectiveVersion}).`;
+    return (`a newer pi SDK is installed on this machine (${newer.map((c) => `v${c.version}`).join(", ")}) ` +
+        `but this process runs v${effectiveVersion} — restart to follow it (default), ` +
+        `or set PI_WEB_SDK=bundled to pin the bundled copy.`);
 }

package/dist/server/serialize.js

@@ -65,7 +65,11 @@ function serializeAssistantContent(content) {
             return { type: "text", text, truncated };
         }
         if (b.type === "thinking") {
-            return { type: "thinking", thinking: b.thinking };
+            // thinking 也走 TEXT_CAP：思维链没有长度保证（长任务能刷出远超正文的
+            // 体量），不截断会把快照推送撑爆。UiThinkingBlock 没有 truncated 字段
+            // （protocol 不动），截断语义靠 truncate 自带的 "… [truncated]" 尾标。
+            const { text } = truncate(b.thinking, TEXT_CAP);
+            return { type: "thinking", thinking: text };
         }
         if (b.type === "toolCall") {
             if (b.arguments === undefined) {
@@ -107,18 +111,98 @@ export function stripTransientRetryErrors(messages, retryActive) {
     }
     return end === messages.length ? messages : messages.slice(0, end);
 }
+/**
+ * Single source for rendered message ids. Both serializeMessage (下发) and
+ * resolveMessageEntry (解析) must derive ids through this function — recomputing
+ * the format anywhere else is how the two sides drifted apart and fork/rollback
+ * on assistant bubbles stopped resolving (issue #381).
+ */
+export function uiMessageId(m, seq) {
+    switch (m.role) {
+        case "user":
+            return `u-${m.timestamp}-${seq}`;
+        case "assistant":
+            return `a-${m.timestamp}-${seq}`;
+        case "toolResult":
+            return `t-${m.toolCallId}`;
+        case "bashExecution":
+            return `b-${m.timestamp}-${seq}`;
+        case "custom":
+            return `c-${m.timestamp}-${seq}`;
+        case "branchSummary":
+            return `bs-${m.timestamp}-${seq}`;
+        case "compactionSummary":
+            return `cs-${m.timestamp}-${seq}`;
+        default:
+            return `x-${seq}`;
+    }
+}
+/**
+ * Find the session entry a rendered message id points at, by re-deriving each
+ * entry's rendered id through uiMessageId() — the same function serializeMessage
+ * used to hand ids to the browser. `seqOf` supplies the per-message seq; the
+ * caller injects its counter there (agent-service passes uiMessageKey().n, which
+ * is exactly the counter serialization drew from — issue #381).
+ */
+export function findEntryByUiId(entries, messageId, seqOf) {
+    const userSeqByTs = new Map();
+    for (const entry of entries) {
+        if (entry.id === messageId)
+            return entry;
+        if (entry.type === "message" && entry.message) {
+            const m = entry.message;
+            let seq;
+            if (m.role === "user") {
+                // User ids count messages sharing a timestamp — mirrors the
+                // special-case in serializeCachedFor() (see its comment).
+                const ts = m.timestamp ?? 0;
+                seq = (userSeqByTs.get(ts) ?? 0) + 1;
+                userSeqByTs.set(ts, seq);
+            }
+            else {
+                seq = seqOf(m);
+            }
+            if (uiMessageId(m, seq) === messageId)
+                return entry;
+        }
+        else if (entry.type === "custom_message" && entry.display !== false) {
+            // Custom messages carry content/timestamp on the entry itself (no
+            // message object); rebuild the shape uiMessageId()/seqOf() key on —
+            // the same conversion createCustomMessage() uses on reload.
+            const m = {
+                role: "custom",
+                content: entry.content,
+                timestamp: entry.timestamp ? new Date(entry.timestamp).getTime() : 0,
+            };
+            if (uiMessageId(m, seqOf(m)) === messageId)
+                return entry;
+        }
+    }
+    return null;
+}
 export function serializeMessage(m, seq) {
+    // SDK 的 system 消息是 prompt sections 的内部差量
+    // (content 空串 + sections 结构化内存)、compaction 的
+    // systemMessage 等——从来不面向用户。不过滤的话
+    // 会掉进 default 分支被序列化成 content: []
+    // 的空气泡、前端顶着 system 标题白显示一条
+    // (对话结束后底部冒出的空 SYSTEM 气泡就是它)。
+    // LLM 上下文不受影响——这里只决定浏览器看到什么。
+    if (m.role === "system") {
+        return null;
+    }
+    const id = uiMessageId(m, seq);
     switch (m.role) {
         case "user":
             return {
-                id: `u-${m.timestamp}-${seq}`,
+                id,
                 role: "user",
                 content: serializeUserContent(m.content),
                 timestamp: m.timestamp,
             };
         case "assistant":
             return {
-                id: `a-${m.timestamp}-${seq}`,
+                id,
                 role: "assistant",
                 content: serializeAssistantContent(m.content),
                 timestamp: m.timestamp,
@@ -152,7 +236,7 @@ export function serializeMessage(m, seq) {
             const { text, truncated } = truncate(raw, TOOL_OUTPUT_CAP);
             const content = raw || images.length === 0 ? [{ type: "text", text, truncated }, ...images] : [...images];
             const msg = {
-                id: `t-${m.toolCallId}`,
+                id,
                 role: "toolResult",
                 content,
                 toolCallId: m.toolCallId,
@@ -177,7 +261,7 @@ export function serializeMessage(m, seq) {
         case "bashExecution": {
             const { text, truncated } = truncate(m.output, TOOL_OUTPUT_CAP);
             return {
-                id: `b-${m.timestamp}-${seq}`,
+                id,
                 role: "bashExecution",
                 content: [
                     {
@@ -199,19 +283,32 @@ export function serializeMessage(m, seq) {
                 return null;
             }
             const content = serializeUserContent(m.content);
-            return {
-                id: `c-${m.timestamp}-${seq}`,
+            const msg = {
+                id,
                 role: "custom",
                 content,
                 customType: m.customType,
-                details: m.details,
                 timestamp: m.timestamp,
             };
+            // custom details 与 toolResult 的 details 同一闸门（TOOL_DETAILS_CAP）：
+            // details 随每 60ms 一发的快照推送，扩展塞进来的大对象不能无节制；
+            // 超限/序列化失败整丢（截断后的 JSON 不可解析，前端还得写容错）。
+            const rawDetails = m.details;
+            if (rawDetails !== undefined) {
+                try {
+                    if (JSON.stringify(rawDetails).length <= TOOL_DETAILS_CAP)
+                        msg.details = rawDetails;
+                }
+                catch {
+                    // 循环引用等序列化不了的值：details 是附加信息，丢掉不影响消息本体。
+                }
+            }
+            return msg;
         }
         case "branchSummary": {
             const { text, truncated } = truncate(m.summary, TEXT_CAP);
             return {
-                id: `bs-${m.timestamp}-${seq}`,
+                id,
                 role: "branchSummary",
                 content: [{ type: "text", text, truncated }],
                 timestamp: m.timestamp,
@@ -220,26 +317,16 @@ export function serializeMessage(m, seq) {
         case "compactionSummary": {
             const { text, truncated } = truncate(m.summary, TEXT_CAP);
             return {
-                id: `cs-${m.timestamp}-${seq}`,
+                id,
                 role: "compactionSummary",
                 content: [{ type: "text", text, truncated }],
                 timestamp: m.timestamp,
                 tokensBefore: m.tokensBefore,
             };
         }
-        case "system": {
-            // SDK 的 system 消息是 prompt sections 的内部差量
-            // (content 空串 + sections 结构化内存)、compaction 的
-            // systemMessage 等——从来不面向用户。不过滤的话
-            // 会掉进 default 分支被序列化成 content: []
-            // 的空气泡、前端顶着 system 标题白显示一条
-            // (对话结束后底部冒出的空 SYSTEM 气泡就是它)。
-            // LLM 上下文不受影响——这里只决定浏览器看到什么。
-            return null;
-        }
         default:
             return {
-                id: `x-${seq}`,
+                id,
                 role: String(m.role ?? "unknown"),
                 content: [],
                 timestamp: m.timestamp,

package/dist/server/settings-service.js

@@ -569,11 +569,13 @@ export class SettingsService {
         if (partial.quickPhrasesEnabled !== undefined) {
             this.settings.quickPhrasesEnabled = partial.quickPhrasesEnabled;
         }
-        this.host.stateStore.saveSettings(this.host.clientId, this.settings);
-        this.push();
         // 统一工具开关 live 生效（ActiveSet 加减；失败静默，下次创建/reload 重放）。
+        // 必须在 this.push() 前生效，保证 promptSnapshot 收集到的是最新的活跃工具集与完整提示词！
         if (toolGatingChanged)
             this.host.applyToolGating();
+        this.host.stateStore.saveSettings(this.host.clientId, this.settings);
+        this.push();
+        this.host.flushSnapshot();
         if (needsReload)
             await this.applyRuntime();
     }

package/dist/server/skill-tool.js

@@ -14,13 +14,13 @@
 //     查不到被禁用的技能；
 //   - 与 SDK 同名工具撞名时 customTools 按 name 覆盖（bash 本体是先例）。
 //
-// 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+// 文案约定：工具 definition（description/promptSnippet/promptGuidelines）为纯英文；per-call
 // 返回文本按 lang 取 pick(lang, zh, en, key)，缺表回落英文内联。
 // ---------------------------------------------------------------------------
 import { statSync, readFileSync } from "node:fs";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { bilingual, pick } from "./i18n.js";
+import { pick } from "./i18n.js";
 import { SKILL_TOOL_NAME } from "./tool-manager.js";
 import { decodeText } from "./text-sniff.js";
 /** 单文件正文上限（与 agent-service fillSkillContents 同口径：8KB）。 */
@@ -61,12 +61,10 @@ export function makeSkillTool(host, lang) {
     return defineTool({
         name: SKILL_TOOL_NAME,
         label: "Load a skill",
-        description: bilingual("Load a skill's full text by its exact name (see the <available_skills> catalog in the system prompt). " +
+        description: "Load a skill's full text by its exact name (see the <available_skills> catalog in the system prompt). " +
             "Prefer this over reading the skill file with the read tool — no path guessing needed. " +
-            "Call without a name to list the current catalog.", "按技能精确名加载其全文（名录见系统提示词里的 <available_skills>）。" +
-            "优先用它，不要自己拼路径调 read 工具读技能文件。" +
-            "不给名则返回当前名录。"),
-        promptSnippet: bilingual("load a skill's full text by name (skill tool, preferred over read)", "按名加载技能全文（skill 工具，优先于 read）"),
+            "Call without a name to list the current catalog.",
+        promptSnippet: "load a skill's full text by name (skill tool, preferred over read)",
         parameters: Type.Object({
             name: Type.Optional(Type.String({
                 description: "Exact skill name from the catalog. Omit to list the current catalog.",

package/dist/server/subagent-templates.js

@@ -42,6 +42,53 @@ export function pickTemplatePrompt(t, lang) {
 }
 /** 名字去空白折叠后非空且 ≤ 60 字符（工具参数可读，允许中文）。 */
 const NAME_MAX = 60;
+/**
+ * 模板体积上限（保存期拒绝，不静默截断）：模板会整体进入设置面板快照并被
+ * subagent_templates 工具列给 AI，systemPrompt 还会拼进子代理上下文，无上限
+ * 的单条模板能把快照推送与子代理首响都拖爆。对齐常见上下文预算的保守值。
+ */
+export const TEMPLATE_LIMITS = {
+    /** 模板系统提示词上限（systemPrompt / systemPromptEn 各自计）。 */
+    systemPrompt: 32_768,
+    /** 模板简介上限（description / descriptionEn 各自计）。 */
+    description: 2_000,
+    /** 技能/扩展白名单各自最多条目数。 */
+    whitelistEntries: 64,
+    /** 白名单单条字符上限。 */
+    whitelistEntryLength: 200,
+};
+/**
+ * 保存期体积校验：超限返回明确错误文本（让设置面板能原样提示），null = 通过。
+ * 只拦新保存，不拦读盘老数据（向后兼容，与 replace 空提示词的拦截口径一致）；
+ * 拒绝而非截断——静默截断会让用户以为保存的是完整内容。
+ */
+export function validateTemplateLimits(t) {
+    if (t.systemPrompt.length > TEMPLATE_LIMITS.systemPrompt) {
+        return `模板 "${t.name}" 的系统提示词超长（${t.systemPrompt.length} > ${TEMPLATE_LIMITS.systemPrompt} 字符），请精简后再保存`;
+    }
+    if ((t.systemPromptEn ?? "").length > TEMPLATE_LIMITS.systemPrompt) {
+        return `模板 "${t.name}" 的英文系统提示词超长（${(t.systemPromptEn ?? "").length} > ${TEMPLATE_LIMITS.systemPrompt} 字符），请精简后再保存`;
+    }
+    if (t.description.length > TEMPLATE_LIMITS.description) {
+        return `模板 "${t.name}" 的简介超长（${t.description.length} > ${TEMPLATE_LIMITS.description} 字符），请精简后再保存`;
+    }
+    if ((t.descriptionEn ?? "").length > TEMPLATE_LIMITS.description) {
+        return `模板 "${t.name}" 的英文简介超长（${(t.descriptionEn ?? "").length} > ${TEMPLATE_LIMITS.description} 字符），请精简后再保存`;
+    }
+    for (const [label, list] of [
+        ["技能白名单", t.enabledSkills],
+        ["扩展白名单", t.enabledExtensions],
+    ]) {
+        if (list.length > TEMPLATE_LIMITS.whitelistEntries) {
+            return `模板 "${t.name}" 的${label}条目过多（${list.length} > ${TEMPLATE_LIMITS.whitelistEntries} 条）`;
+        }
+        const over = list.find((entry) => entry.length > TEMPLATE_LIMITS.whitelistEntryLength);
+        if (over) {
+            return `模板 "${t.name}" 的${label}有超长条目（${over.length} > ${TEMPLATE_LIMITS.whitelistEntryLength} 字符）`;
+        }
+    }
+    return null;
+}
 /**
  * 内置默认模板（第一次运行时种子进列表；用户改动后以 <dataDir> 文件为准）。
  * 文案改编自 pi-subagents 社区项目（tintinweb / nicobailon）的角色提示词,
@@ -629,6 +676,10 @@ export class SubagentTemplatesStore {
         if (t.promptMode === "replace" && !t.systemPrompt.trim() && !(t.systemPromptEn ?? "").trim()) {
             return `模板 "${t.name}" 用了 replace 模式但系统提示词为空：replace 会整体替换子代理 persona，空提示词等于模板没生效。请填写提示词（中文或英文至少一个），只想限定技能/扩展白名单请用 append 模式`;
         }
+        // 体积上限同样只在保存期拦：超限明确报错，绝不静默截断。
+        const limitError = validateTemplateLimits(t);
+        if (limitError)
+            return limitError;
         const list = this.load();
         const i = list.findIndex((x) => x.name === t.name);
         if (i >= 0)