pi-web-ui 0.91.0 → 0.93.0

package/dist/server/plugin-schedule.js

@@ -136,7 +136,15 @@ export function parseCronSpec(spec) {
 function isFull(values, min, max) {
     return values.length === max - min + 1;
 }
-/** 下一次触发毫秒时间戳（从 fromMs 的下一分钟开始扫，上限约一年）。纯函数，单测覆盖。 */
+/**
+ * 下一次触发毫秒时间戳（从 fromMs 的下一分钟开始扫，上限约一年）；**一年内没有下一次回 null**
+ * （例如 `0 0 31 2 *` 这种永远不存在的日子）。
+ *
+ * 为什么不是回一个「一年后的哨兵值」：调用方 `armCron` 拿它做 `setTimeout(next - now)`，
+ * 而 Node 的 setTimeout 延迟超过 2^31-1ms（≈24.8 天）会**溢出成 1ms** —— 哨兵值配上溢出
+ * 就是「1ms 后触发 → 再排下一次」的死循环（每次触发还伴随插件回调与写盘）。回 null 之后，
+ * 调用方能明确区分「还有很久」与「永远不会发生」。纯函数，单测覆盖。
+ */
 export function nextCronFire(parts, fromMs) {
     const minuteSet = new Set(parts.minute);
     const hourSet = new Set(parts.hour);
@@ -163,7 +171,24 @@ export function nextCronFire(parts, fromMs) {
             continue;
         return t;
     }
-    return limit;
+    return null;
+}
+/**
+ * setTimeout 的安全延迟上限（毫秒）：Node 与浏览器都按 32 位有符号整数存延迟，
+ * 超过 2^31-1 会被截断（Node 会**静默变成 1ms** 并打一条 TimeoutOverflowWarning）。
+ */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * 把「距离下次触发的毫秒数」切成一段安全的 setTimeout 延迟（纯函数，单测覆盖）。
+ *
+ * 超过上限就只等一个分片（默认 6 小时）再重新计算 —— 重新计算这一步是关键：
+ * 过期声明、时钟回拨、系统休眠回来都能自然纠正，比一次性排一个超长定时器稳。
+ */
+export function armDelay(nextAtMs, nowMs, maxChunkMs = 6 * 60 * 60 * 1000) {
+    const raw = Math.max(0, Number(nextAtMs) - Number(nowMs));
+    if (!Number.isFinite(raw))
+        return 0;
+    return Math.min(raw, Math.max(1, Math.min(maxChunkMs, MAX_TIMEOUT_MS)));
 }
 export function scheduleFile(pluginDir) {
     return join(pluginDir, "schedules.json");

package/dist/server/plugins.js

@@ -22,7 +22,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { pick } from "./i18n.js";
 import { PluginStorage, PluginSecrets, ensurePluginDeps, WorkspaceFS } from "./plugin-facilities.js";
-import { parseCronSpec, nextCronFire, loadScheduleRecords, saveScheduleRecords, } from "./plugin-schedule.js";
+import { parseCronSpec, armDelay, nextCronFire, loadScheduleRecords, saveScheduleRecords, } from "./plugin-schedule.js";
 import { PluginPermissionStore } from "./plugin-permissions.js";
 import { readCatalog, addCustomEntry, removeCustomEntry } from "./plugin-catalog.js";
 import { PluginGrantsStore, normalizeGrantPath } from "./plugin-grants.js";
@@ -162,6 +162,10 @@ export function readHostVersion() {
 // 声明式设置 schema（manifest "settings"）
 // ---------------------------------------------------------------------------
 const SETTING_TYPES = new Set(["text", "password", "number", "boolean", "select", "secret"]);
+/** select 字段可由宿主现算的候选数据源（manifest `optionsFrom`）：
+ *  models = 已配置鉴权的模型；thinkingLevels = SDK 思考强度档位。
+ *  清单在浏览器侧现算（模型配置会变，静态表会过期），服务端不做候选值校验。 */
+const SETTING_OPTIONS_FROM = new Set(["models", "thinkingLevels"]);
 /**
  * 解析 manifest "ui" 的某个 slot 数组 → 规范化条目（issue #146 完整版）。
  *
@@ -181,6 +185,7 @@ const UI_SLOTS = new Set([
     "contextmenu.message",
     "contextmenu.session",
     "contextmenu.file",
+    "contextmenu.toolcall",
     "settings.pages",
     "leftpanel.sessions",
     "chat.header",
@@ -573,7 +578,12 @@ function parseSettingsSchema(raw) {
             continue;
         const o = f;
         const key = typeof o.key === "string" ? o.key.trim() : "";
-        const type = typeof o.type === "string" ? o.type : "";
+        // 宿主数据源（models / thinkingLevels）：合法值才认，非法当成没写（回落静态 options）。
+        // 只写 optionsFrom 没写 type = 视为 select（少让作者踩坑，与 options 的写法一致）。
+        const optionsFrom = typeof o.optionsFrom === "string" && SETTING_OPTIONS_FROM.has(o.optionsFrom)
+            ? o.optionsFrom
+            : undefined;
+        const type = (typeof o.type === "string" && o.type ? o.type : optionsFrom ? "select" : "");
         if (!key || !SETTING_TYPES.has(type) || out.some((x) => x.key === key))
             continue;
         const field = {
@@ -584,6 +594,7 @@ function parseSettingsSchema(raw) {
             ...(typeof o.min === "number" ? { min: o.min } : {}),
             ...(typeof o.max === "number" ? { max: o.max } : {}),
             ...(Array.isArray(o.options) ? { options: o.options.filter((x) => typeof x === "string") } : {}),
+            ...(type === "select" && optionsFrom ? { optionsFrom } : {}),
             ...(typeof o.hint === "string" ? { hint: o.hint } : {}),
         };
         out.push(field);
@@ -670,14 +681,29 @@ lang, secrets) {
             clean[f.key] = v === undefined ? Boolean(f.default) : Boolean(v);
         }
         else if (f.type === "select") {
-            if (v !== undefined && !f.options?.includes(String(v)))
+            const s = v === undefined ? "" : String(v);
+            // optionsFrom（宿主数据源）：候选值在浏览器侧现算，服务端无从校验，
+            // 只做个长度护栏；非法值由用的时候（如 host.chat 切模型）报错。
+            if (f.optionsFrom) {
+                if (s.length > 200) {
+                    return {
+                        error: pick(l, `${f.label} 过长`, `${f.label} too long`, "plugins.settings.too.long", {
+                            "f.label": f.label,
+                        }),
+                        clean,
+                    };
+                }
+                clean[f.key] = v === undefined ? (f.default ?? "") : s;
+                continue;
+            }
+            if (v !== undefined && !f.options?.includes(s))
                 return {
                     error: pick(l, `${f.label} 值非法`, `Invalid value for ${f.label}`, "plugins.settings.invalid.value", {
                         "f.label": f.label,
                     }),
                     clean,
                 };
-            clean[f.key] = v === undefined ? f.default : String(v);
+            clean[f.key] = v === undefined ? f.default : s;
         }
         else if (f.type === "secret") {
             // 空串/缺省 = 不改（浏览器侧回显的本来就是有无布尔，前端把“没碰”发成空串）。
@@ -1799,6 +1825,9 @@ export class PluginManager {
                         : undefined,
                     // 是否有独立视图 tab（manifest "view"，缺省 true）；纯 renderer 插件写 false
                     view: typeof m.view === "boolean" ? m.view : true,
+                    // 客户端 bundle 是否常驻加载（manifest "preload"，缺省 false）：无视图
+                    // （view:false）却要顶层代码一直跑（提醒轮询/快捷键/常驻浮窗…）的插件用它。
+                    preload: m.preload === true,
                     // 插件对宿主 UI 的贡献（manifest "ui"：slot 框架 + 整理意图，issue #146）。
                     // 权限：与 activate 的 can("ui") **同一口径**（严格模式 = 声明了 permissions
                     // 或 apiVersion>=2）：严格模式下必须含 "ui" 族，否则整份忽略；旧全权格式放行。
@@ -2741,10 +2770,12 @@ export class PluginManager {
                 let timer;
                 let grace;
                 let cancelled = false;
+                /** 下一次触发时刻的展示串；`null` = 一年内没有下一次（如 2 月 31 日）。 */
                 const nextText = () => {
                     if (parts) {
                         try {
-                            return new Date(nextCronFire(parts, Date.now())).toLocaleString();
+                            const at = nextCronFire(parts, Date.now());
+                            return at === null ? null : new Date(at).toLocaleString();
                         }
                         catch {
                             return specText;
@@ -2752,6 +2783,10 @@ export class PluginManager {
                     }
                     return `每 ${Math.round(ms / 1000)}s`;
                 };
+                const statusText = () => {
+                    const next = nextText();
+                    return next === null ? "不再触发（表达式在一年内不会命中）" : `下次 ${next}`;
+                };
                 // 后台面板条目（持久任务独有）：看得见下次时间，停止=删声明（不再复活）。
                 let bgRefresh;
                 let bgUnreg;
@@ -2762,7 +2797,7 @@ export class PluginManager {
                         id: taskId,
                         label: `⏰ ${label ?? sid}`,
                         since: Date.now(),
-                        status: `下次 ${nextText()}`,
+                        status: statusText(),
                         stop: () => off(),
                     };
                     bgTaskTable.set(taskId, entry);
@@ -2778,7 +2813,7 @@ export class PluginManager {
                     bgRefresh = () => {
                         if (!bgTaskTable.has(taskId))
                             return;
-                        entry.status = `下次 ${nextText()}`;
+                        entry.status = statusText();
                         fireBg();
                     };
                     bgUnreg = () => {
@@ -2812,14 +2847,30 @@ export class PluginManager {
                     }
                     bgRefresh?.();
                 };
+                /**
+                 * 排下一次触发。两个要点：
+                 *  - `nextCronFire` 回 null = 一年内没有下一次（如 `0 0 31 2 *`）→ 不再排；
+                 *  - 延迟走 `armDelay` 分片（默认 ≤6 小时），因为 Node 的 setTimeout 延迟超过
+                 *    2^31-1ms（≈24.8 天）会**溢出成 1ms**，配上「下次在 42 天/一年后」的
+                 *    合法 cron 就是「1ms 后再触发」的死循环（触发还会回调插件 → 写盘 + 广播）。
+                 *    分片醒来后重新计算，真到点才 fire。
+                 */
                 const armCron = () => {
                     if (cancelled || !parts)
                         return;
                     const next = nextCronFire(parts, Date.now());
+                    if (next === null)
+                        return;
                     timer = setTimeout(() => {
-                        fire();
+                        if (cancelled)
+                            return;
+                        const at = nextCronFire(parts, Date.now());
+                        if (at === null)
+                            return;
+                        if (at <= Date.now() + 1000)
+                            fire();
                         armCron();
-                    }, Math.max(0, next - Date.now()));
+                    }, armDelay(next, Date.now()));
                     timer.unref?.();
                 };
                 if (parts)
@@ -2831,7 +2882,12 @@ export class PluginManager {
                 // 漏跑补跑：以上次触发（没跑过按创建时间）为锚，下一次已在过去=漏了。
                 if (persistent && catchUp === "once") {
                     const refTime = loadScheduleRecords(dir)[sid]?.lastRun ?? loadScheduleRecords(dir)[sid]?.createdAt ?? Date.now();
-                    const missed = parts ? nextCronFire(parts, refTime) <= Date.now() : refTime + ms <= Date.now();
+                    const missed = parts
+                        ? (() => {
+                            const at = nextCronFire(parts, refTime);
+                            return at !== null && at <= Date.now(); // null = 一年内没有下一次，不算漏跑
+                        })()
+                        : refTime + ms <= Date.now();
                     if (missed) {
                         // 15s 缓冲：刚启动时模型/网络可能还没就绪，补跑不等那 15 秒可能白跑。
                         grace = setTimeout(() => fire(), 15_000);

package/dist/server/present-files-tool.js

@@ -0,0 +1,303 @@
+/**
+ * present-files-tool.ts —— AI 主动把文件「展示」给用户（present_files）。
+ *
+ * 背景：AI 生成截图/图表/录屏/报告/日志后，只能在正文里写一句路径，用户还得
+ * 自己去右栏一层层点开；图片、视频更是根本没机会出现在对话里。
+ *
+ * 做法：注册一个第一方 customTool（与 read 覆盖、edit_soft、conversation_read
+ * 同机制）。模型给出路径清单，工具只做**只读探测**——stat + 未知扩展嗅探前
+ * 4KB + 文本摘录——把结构化 items 放进 tool result 的 `details`（经
+ * serialize.ts 下发浏览器，并随会话文件持久化），前端 ToolCallBlock 把它渲染
+ * 成预览卡片：图片/视频/音频内联直接看，文本/markdown/HTML 一键开预览弹窗，
+ * 每个条目带「预览 / 本地打开 / 在文件夹中显示 / 下载 / 复制路径」。
+ *
+ * 本工具**不打开任何窗口、不弹通知**：所有系统级动作都由用户在卡片上点击触发
+ * （走既有的 file_open_default / file_reveal 协议，issue #187）。工具本身只读，
+ * 能看到的文件与 read 工具完全一致，不新增任何权限。
+ *
+ * 路径口径与 read 一致（~ / @ / 绝对 / 相对，复用 read-tool 的
+ * resolvePathForDirCheck）；回传的 `path` 是线形绝对路径（"C:/…" / "/…"），
+ * 前端拿它直接打 /api/file、file_reveal、file_open_default，不受会话 cwd 影响。
+ *
+ * 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+ * 结果文本走 pick(lang, zh, en, key, vars)，缺表回落英文内联。
+ *
+ * DSH 引擎无 customTool 注册面（工具来自 shipped preset），本工具只服务 pi 引擎。
+ */
+import { open, stat } from "node:fs/promises";
+import { basename, extname, sep } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { bilingual, pick } from "./i18n.js";
+import { resolvePathForDirCheck } from "./read-tool.js";
+import { decodeText, isAudioFile, looksLikeText, previewKind } from "./text-sniff.js";
+import { PRESENT_FILES_TOOL_NAME } from "./tool-manager.js";
+/** 展示文件工具名（唯一登记见 tool-manager.ts；此处导出供 import 方沿用）。 */
+export { PRESENT_FILES_TOOL_NAME };
+/** 单次展示的条目上限：再多就不是「给你看」而是文件列表了（卡片的纵向预算也有限）。 */
+export const MAX_PRESENT_ITEMS = 12;
+/** 单条文本摘录字符数上限。 */
+export const MAX_EXCERPT_CHARS = 1200;
+/** 一次调用里所有摘录的字符总量上限（details 会进快照与转录，必须封顶）。 */
+export const MAX_EXCERPT_TOTAL_CHARS = 6000;
+/** 摘录只读文件头这么多字节（UTF-8 3 字节/汉字，8KB 足够撑满 1200 字符）。 */
+const EXCERPT_READ_BYTES = 8192;
+/** 未知扩展名文件的内容嗅探字节数（判断文本还是二进制）。 */
+const SNIFF_BYTES = 4096;
+/** 摘录/嗅探的体积闸门：超过就不读内容（几十 MB 的日志摘一句没意义）。 */
+const MAX_SNIFFABLE_BYTES = 4 * 1024 * 1024;
+const MARKDOWN_EXTS = new Set(["md", "markdown", "mdx"]);
+const HTML_EXTS = new Set(["html", "htm", "xhtml"]);
+/**
+ * 归一化模型给的 items：非数组/元素缺 path 一律丢弃；trim + 反斜杠折成正斜杠
+ * （Windows 模型常写 "a\b\c.png"）；按归一化后的路径去重；最多 MAX_PRESENT_ITEMS 条。
+ */
+export function normalizePresentItems(raw, max = MAX_PRESENT_ITEMS) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            const path = normPath(entry);
+            if (!path || seen.has(path))
+                continue;
+            seen.add(path);
+            out.push({ path });
+        }
+        else if (entry && typeof entry === "object") {
+            const e = entry;
+            if (typeof e.path !== "string")
+                continue;
+            const path = normPath(e.path);
+            if (!path || seen.has(path))
+                continue;
+            seen.add(path);
+            const item = { path };
+            if (typeof e.caption === "string" && e.caption.trim())
+                item.caption = e.caption.trim();
+            if (e.focus === true)
+                item.focus = true;
+            out.push(item);
+        }
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/** trim + 反斜杠折成正斜杠（列上是 wire 口径：Windows 路径在协议里一律 "/"）+ 去掉
+ *  结尾斜杠（保留 posix 根 "/" 与盘符根 "C:/")，与 files-service 的 normWirePath 同语义。 */
+export function normPath(p) {
+    const w = String(p ?? "")
+        .trim()
+        .replace(/\\/g, "/");
+    if (w === "/" || w === "")
+        return w;
+    if (w.endsWith("/")) {
+        const trimmed = w.replace(/\/+$/, "");
+        // "C:/" → 保留盘符根形式（去尾斜杠会变成 "C:"，语义不同）。
+        return /^[A-Za-z]:$/.test(trimmed) ? `${trimmed}/` : trimmed;
+    }
+    return w;
+}
+/** 原生绝对路径 → 线形绝对路径（协议/前端统一口径）。 */
+export function toWirePath(abs) {
+    return sep === "/" ? abs : abs.split(sep).join("/");
+}
+/**
+ * 按文件名判类（纯函数，无 I/O）：markdown/html/pdf/audio 先认，其余借
+ * text-sniff 的 previewKind 认图片/视频/文本；未知扩展（含 exe/zip/无扩展名的
+ * 二进制）归 "binary"，由调用方按需读文件头嗅探成文本。
+ */
+export function classifyPresentKind(name) {
+    const ext = extname(name).toLowerCase().replace(/^\./, "");
+    if (MARKDOWN_EXTS.has(ext))
+        return "markdown";
+    if (HTML_EXTS.has(ext))
+        return "html";
+    if (ext === "pdf")
+        return "pdf";
+    if (isAudioFile(name))
+        return "audio";
+    const base = previewKind(name);
+    if (base === "image")
+        return "image";
+    if (base === "video")
+        return "video";
+    if (base === "text")
+        return "text";
+    return "binary";
+}
+/** 该类别是否值得读文件头（二进制/未知扩展 → 嗅探成文本；其余按扩展名已定）。 */
+export function shouldSniff(kind) {
+    return kind === "binary";
+}
+/** 该类别是否带文本摘录（图片/视频/音频/二进制不读内容）。 */
+export function hasExcerpt(kind) {
+    return kind === "text" || kind === "markdown" || kind === "html";
+}
+/** 人类可读体积（工具结果文本与卡片提示共用口径）。 */
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "?";
+    if (n < 1024)
+        return `${Math.round(n)} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(n < 10 * 1024 ? 1 : 0)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+/** 读文件头（关不上就返回 null：读不到内容不算错误，卡片照样出）。 */
+async function readHead(abs, bytes) {
+    let handle;
+    try {
+        handle = await open(abs, "r");
+        const buf = Buffer.alloc(bytes);
+        const { bytesRead } = await handle.read(buf, 0, bytes, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+/** 给一条文本类条目补上摘录（预算耗尽或文件过大则跳过）。`native` = 原生绝对路径。 */
+async function attachExcerpt(item, budget, native) {
+    if (!hasExcerpt(item.kind) || item.size === undefined || item.size === 0)
+        return;
+    if (item.size > MAX_SNIFFABLE_BYTES || budget.left <= 0)
+        return;
+    const head = await readHead(native, EXCERPT_READ_BYTES);
+    if (!head || head.length === 0)
+        return;
+    const text = decodeText(head).replace(/\u0000+$/, "");
+    if (!text)
+        return;
+    const cap = Math.min(MAX_EXCERPT_CHARS, budget.left);
+    const clipped = text.length > cap;
+    const excerpt = clipped ? text.slice(0, cap) : text;
+    item.excerpt = excerpt;
+    item.excerptTruncated = clipped || item.size > head.length;
+    budget.left -= excerpt.length;
+}
+/** 逐条探测：stat → 判类 → （未知扩展）嗅探 → 摘录。 */
+export async function probePresentItem(raw, cwd, budget) {
+    const native = resolvePathForDirCheck(raw.path, cwd);
+    const abs = toWirePath(native);
+    const name = basename(native) || raw.path;
+    const base = { ...raw, name, abs, kind: "missing" };
+    const st = await stat(native).catch(() => null);
+    if (!st)
+        return base;
+    if (st.isDirectory())
+        return { ...base, kind: "dir", mtime: st.mtimeMs };
+    if (!st.isFile())
+        return base;
+    let kind = classifyPresentKind(name);
+    if (shouldSniff(kind) && st.size > 0 && st.size <= MAX_SNIFFABLE_BYTES) {
+        const head = await readHead(native, SNIFF_BYTES);
+        if (head && head.length > 0 && looksLikeText(head))
+            kind = "text";
+    }
+    const item = { ...base, kind, size: st.size, mtime: st.mtimeMs };
+    await attachExcerpt(item, budget, native);
+    return item;
+}
+/** 工具结果里给模型的正文：哪些展示了、哪些没找到、卡片上能做什么。 */
+export function buildPresentResultText(items, lang, title) {
+    const shown = items.filter((i) => i.kind !== "missing");
+    const missing = items.filter((i) => i.kind === "missing");
+    const lines = [];
+    const head = pick(lang, `已把 ${shown.length} 个文件作为预览卡片展示给用户${title ? `（${title}）` : ""}：`, `Presented ${shown.length} file(s) to the user as preview cards${title ? ` (${title})` : ""}:`, "present.files.result.head", { n: shown.length, title: title ?? "" });
+    lines.push(head);
+    for (const [i, it] of shown.entries()) {
+        const meta = it.kind === "dir"
+            ? pick(lang, "目录", "directory", "present.files.result.kindDir")
+            : [it.kind, it.size !== undefined ? formatBytes(it.size) : ""].filter(Boolean).join(", ");
+        const caption = it.caption ? ` — ${it.caption}` : "";
+        lines.push(`${i + 1}. ${it.path} (${meta})${caption}`);
+    }
+    if (missing.length > 0) {
+        lines.push(pick(lang, `未展示（路径不存在或不可读）：${missing.map((m) => m.path).join("、")}`, `Not shown (path missing or unreadable): ${missing.map((m) => m.path).join(", ")}`, "present.files.result.missing", { paths: missing.map((m) => m.path).join(", ") }));
+    }
+    lines.push(pick(lang, "用户在卡片上可以直接看图/播放、打开预览、在本机打开、在文件管理器中显示、下载或复制路径；不要再把文件内容贴一遍。", "The user can view/play media, open the preview dialog, open the file locally, reveal it in the file manager, download it or copy its path from the card — do not paste the file contents again.", "present.files.result.tail"));
+    return lines.join("\n");
+}
+/** 空结果/全部缺失时的错误文案（模型看到 error 才会改策略）。 */
+function missingAllError(lang, paths) {
+    return pick(lang, `这些路径都不存在或不可读，没有任何卡片展示出去：${paths.join("、")}`, `None of these paths exist or are readable, nothing was shown: ${paths.join(", ")}`, "present.files.result.allMissing", { paths: paths.join(", ") });
+}
+/**
+ * present_files 工具定义。cwd 仅供创建时固定；执行时优先 ctx.cwd（会话工作区）。
+ */
+export function makePresentFilesTool(fallbackCwd, options = {}) {
+    const enabled = options.enabled ?? (() => true);
+    const getLang = options.getLang ?? (() => "en");
+    return defineTool({
+        name: PRESENT_FILES_TOOL_NAME,
+        label: "Show files to the user",
+        description: bilingual("Show files to the user as preview cards in the chat. Each item renders as a card: images/videos/audio are displayed inline, text/markdown/HTML can be opened in the preview dialog, and every card carries buttons to open the file locally, reveal it in the file manager, download it or copy its path. " +
+            "Use it whenever the user should LOOK at an artifact you produced or changed: a screenshot, chart, diagram, generated video/audio, report, log, build output. " +
+            "Give workspace-relative paths (or absolute ones); up to 12 items per call; `title` and `note` are shown above the cards, `caption` under the file name, and `focus: true` makes the client open that item in the preview dialog right away. " +
+            "Do not use it for files you merely read while reasoning, and do not repeat the file contents in your reply afterwards.", "把文件作为预览卡片展示给用户。每个条目渲染成一张卡片：图片/视频/音频直接在对话里显示，文本/markdown/HTML 可一键打开预览弹窗，每张卡片都带「本地打开 / 在文件管理器中显示 / 下载 / 复制路径」按钮。" +
+            "适合用户**应该看一眼**的产物：截图、图表、示意图、生成的视频音频、报告、日志、构建产物。" +
+            "路径写工作区相对路径（或绝对路径）；单次最多 12 条；`title`/`note` 显示在卡片上方，`caption` 显示在文件名旁，`focus: true` 让客户端立刻用预览弹窗打开该条目。" +
+            "只是自己读文件来推理时不要调用它，调用后也不要在回复里把文件内容再贴一遍。"),
+        promptSnippet: bilingual("show images/videos/text files to the user as preview cards", "把图片/视频/文本文件作为预览卡片展示给用户"),
+        promptGuidelines: [
+            bilingual("After producing something visual or user-facing (screenshot, chart, video, report, log, build output), call present_files so the user can actually see it instead of only printing the path", "产出可视化或面向用户的文件后（截图、图表、视频、报告、日志、构建产物），调 present_files 让用户真的看到，而不是只打印一行路径"),
+            bilingual("Do not call present_files for ordinary source edits the user did not ask to see, and never call it twice for the same file in one turn", "用户没要求看的普通源码改动不要用 present_files；同一轮里不要为同一个文件调两次"),
+        ],
+        parameters: Type.Object({
+            title: Type.Optional(Type.String({
+                description: "Optional card title shown above the file cards (short, e.g. 'Q3 revenue chart').",
+            })),
+            note: Type.Optional(Type.String({
+                description: "Optional one-line note above the cards (markdown, e.g. what changed / which one to look at first).",
+            })),
+            items: Type.Array(Type.Object({
+                path: Type.String({ description: "File path (workspace-relative like 'docs/chart.png', or absolute)." }),
+                caption: Type.Optional(Type.String({ description: "Optional short caption shown next to the file name." })),
+                focus: Type.Optional(Type.Boolean({
+                    description: "true → the client opens this item in the preview dialog immediately (use for the one file that matters most).",
+                })),
+            }), { description: `Files to show (1-${MAX_PRESENT_ITEMS}).` }),
+        }),
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const lang = getLang();
+            if (!enabled()) {
+                throw new Error(pick(lang, "用户的设置里关闭了 present_files 工具。", "The user disabled the present_files tool in settings.", "present.files.result.disabled"));
+            }
+            const p = params;
+            const items = normalizePresentItems(p.items);
+            if (items.length === 0) {
+                throw new Error(pick(lang, "present_files 至少需要一个带 path 的条目。", "present_files needs at least one item with a path.", "present.files.result.noItems"));
+            }
+            const cwd = typeof ctx?.cwd === "string" && ctx.cwd ? ctx.cwd : fallbackCwd;
+            const budget = { left: MAX_EXCERPT_TOTAL_CHARS };
+            const probed = [];
+            for (const item of items) {
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                probed.push(await probePresentItem(item, cwd, budget));
+            }
+            if (probed.every((i) => i.kind === "missing")) {
+                throw new Error(missingAllError(lang, probed.map((i) => i.path)));
+            }
+            const title = typeof p.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+            const note = typeof p.note === "string" && p.note.trim() ? p.note.trim() : undefined;
+            const details = { items: probed };
+            if (title)
+                details.title = title;
+            if (note)
+                details.note = note;
+            return {
+                content: [{ type: "text", text: buildPresentResultText(probed, lang, title) }],
+                details,
+            };
+        },
+    });
+}

package/dist/server/protocol-version.js

@@ -8,4 +8,4 @@
  * its own copy in web/src/protocol-version.ts; scripts/check-protocol-sync.mjs
  * verifies the two never drift.
  */
-export const PROTOCOL_VERSION = 18;
+export const PROTOCOL_VERSION = 19;

package/dist/server/read-tool.js

@@ -0,0 +1,125 @@
+/**
+ * read-tool.ts —— 覆盖 SDK 内置 read：路径是目录时列出目录条目。
+ *
+ * 背景：SDK 内置 `read` 只处理文件，`read('server')` 直接抛
+ * `EISDIR: illegal operation on a directory, read`；模型想「看一眼这个目录」
+ * 只能改用 bash（`ls`）。SDK 自带的 `ls` 工具不在默认活跃集里
+ * （默认 `["read","bash","edit","write"]`），模型并不总能想到它。
+ *
+ * 做法（与 bash 覆盖同一机制）：customTools 按 name 覆盖内置定义 —— 用
+ * `createReadToolDefinition(cwd)` 拿原实现当基底，只在「路径确实是目录」时
+ * 分流到 `createLsToolDefinition(cwd)`（排序、目录 `/` 后缀、条目/字节截断
+ * 与 SDK ls 完全一致）；其余情况（文件、图片、路径不存在、读取报错）原样
+ * 转发基底，行为与内置完全一致。
+ *
+ * 开关：`readDirEnabled`（设置面板「工具」页，默认开）。**行为开关**不是
+ * ActiveSet 开关（read 本体不可关，关了 agent 就残了），因此不进
+ * tool-manager 的 AGENT_TOOL_CATALOG；每次调用实时读设置，改动即时生效。
+ *
+ * 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+ * 返回文本（目录头）按 lang 取 pick(lang, zh, en, key)，缺表回落英文内联。
+ *
+ * DSH 引擎无 customTool 注册面（工具来自 shipped preset），本覆盖只服务 pi 引擎。
+ */
+import { stat } from "node:fs/promises";
+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";
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+/**
+ * 目录判定用的路径归一：~ / @ 前缀、Unicode 空格、相对 → 绝对（对齐 SDK
+ * resolveToCwd 的主要语义）。这里只是「猜」，猜不中（例如 macOS 截图名的
+ * 变体路径）就走内置实现，不会比现状更差。
+ */
+export function resolvePathForDirCheck(input, cwd) {
+    let p = String(input ?? "").replace(UNICODE_SPACES, " ");
+    if (p.startsWith("@"))
+        p = p.slice(1);
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return join(homedir(), p.slice(2));
+    return isAbsolute(p) ? p : nodeResolve(cwd, p);
+}
+/** 路径是不是目录（不存在/无权限/非目录一律 false → 交回内置实现）。 */
+export async function isDirectoryPath(absolutePath) {
+    try {
+        const st = await stat(absolutePath);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** 覆盖定义的参数 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)", "要读取的文件（或目录）路径（相对或绝对）"),
+    }),
+    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` 为准"),
+    })),
+    offset: Type.Optional(Type.Number({
+        description: bilingual("Line number to start reading from (1-indexed)", "从第几行开始读（从 1 起算）"),
+    })),
+    limit: Type.Optional(Type.Number({
+        description: bilingual("Maximum number of lines to read (for a directory path: maximum number of entries)", "最多读多少行（路径是目录时 = 最多列多少条目）"),
+    })),
+}, {});
+/**
+ * 校验前归一（SDK 的 prepareArguments 在 schema 校验前执行）：只有 file_path 时
+ * 把它当 path（path 在 schema 里仍必填），两者都给时以 path 为准。
+ */
+export function prepareReadArguments(raw) {
+    const args = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...raw } : {};
+    const primary = typeof args.path === "string" ? args.path : "";
+    const alias = typeof args.file_path === "string" ? args.file_path : "";
+    if (!primary.trim() && alias.trim())
+        args.path = alias;
+    // 两者都没给时这里仍缺 path（静态类型是谎，运行时交给 schema 校验报错）。
+    return args;
+}
+/**
+ * 生成「read 读目录」覆盖定义。cwd 仅供创建时固定；执行时优先 ctx.cwd
+ * （会话工作区）。
+ */
+export function makeReadDirTool(fallbackCwd, options = {}) {
+    const base = createReadToolDefinition(fallbackCwd);
+    const ls = createLsToolDefinition(fallbackCwd);
+    const dirEnabled = options.dirEnabled ?? (() => true);
+    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)", "读取文件内容（传目录则列出其条目）"),
+        promptGuidelines: [
+            ...(base.promptGuidelines ?? []),
+            bilingual("Use read on a directory to list its entries — no need to shell out to `ls`", "要看目录内容直接把目录路径交给 read，不必再走 bash 的 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);
+        },
+    });
+}