pi-web-ui 0.90.1 → 0.92.0

package/dist/server/plugins.js

@@ -22,10 +22,11 @@ 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";
+import { normalizeIconSvg } from "./icon-svg.js";
 import { PluginDomConsent, declarationWantsDom } from "./plugin-dom.js";
 // 工作区根的归一化与 client-state 共用一份（同一份语义：只收绝对路径 / 去重 / 上限）。
 import { normalizeWorkspaceRoots } from "./client-state.js";
@@ -161,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 完整版）。
  *
@@ -371,6 +376,9 @@ export function parseUiItem(raw, slot, diagnostics) {
         ...(align ? { align } : {}),
         ...(trimStr(o.labelEn, 60) ? { labelEn: trimStr(o.labelEn, 60) } : {}),
         ...(trimStr(o.icon, 16) ? { icon: trimStr(o.icon, 16) } : {}),
+        ...(normalizeIconSvg(o.iconSvg)
+            ? { iconSvg: normalizeIconSvg(o.iconSvg) }
+            : {}),
         ...(trimStr(o.hint, 200) ? { hint: trimStr(o.hint, 200) } : {}),
         ...(trimStr(o.hintEn, 200) ? { hintEn: trimStr(o.hintEn, 200) } : {}),
         kind,
@@ -538,6 +546,9 @@ export function parseUiArrange(raw, diagnostics) {
             ...(trimStr(o.label, 60) ? { label: trimStr(o.label, 60) } : {}),
             ...(trimStr(o.hint, 200) ? { hint: trimStr(o.hint, 200) } : {}),
             ...(trimStr(o.icon, 16) ? { icon: trimStr(o.icon, 16) } : {}),
+            ...(normalizeIconSvg(o.iconSvg)
+                ? { iconSvg: normalizeIconSvg(o.iconSvg) }
+                : {}),
         });
     }
     return out;
@@ -566,7 +577,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 = {
@@ -577,6 +593,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);
@@ -663,14 +680,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") {
             // 空串/缺省 = 不改（浏览器侧回显的本来就是有无布尔，前端把“没碰”发成空串）。
@@ -1582,15 +1614,15 @@ export class PluginManager {
         }
     }
     /** 当前目录清单（重扫 manifest，不重新 import）。 */
-    async list() {
-        return this.scan();
+    async list(lang) {
+        return this.scan(lang);
     }
     /**
      * attach 时调用：重扫目录 + 激活尚未加载的新插件。
      * 返回给浏览器的目录（含激活失败的条目，前端显示为不可用）。
      */
     async ensureLoaded(lang) {
-        const found = await this.scan();
+        const found = await this.scan(lang);
         for (const info of found) {
             if (this.loaded.has(info.id) || this.attempted.has(info.id))
                 continue;
@@ -1607,10 +1639,13 @@ export class PluginManager {
         }
         return found.map((f) => {
             const base = this.loaded.get(f.id)?.info ?? f;
+            // 运行相位（设置面板清单用）：宿主持有实例即 active（含激活失败的占位行；
+            // 纯前端插件无 index.mjs、从未进 loaded 表，保持非 active）。
+            const withPhase = { ...base, active: this.loaded.has(f.id) };
             const agentTools = this.agentToolsSnapshot(f.id);
             if (agentTools.length)
-                return { ...base, agentTools };
-            const { agentTools: _drop, ...rest } = base;
+                return { ...withPhase, agentTools };
+            const { agentTools: _drop, ...rest } = withPhase;
             return rest;
         });
     }
@@ -1702,7 +1737,8 @@ export class PluginManager {
         this.pluginLogs.clear();
     }
     /** 读 manifest 清单；坏目录（无 manifest/id 非法）直接跳过。 */
-    async scan() {
+    async scan(lang) {
+        const l = lang?.() ?? "en";
         let names;
         try {
             names = await readdir(this.pluginsDir);
@@ -1731,6 +1767,7 @@ export class PluginManager {
                     version: typeof m.version === "string" ? m.version : undefined,
                     description: typeof m.description === "string" ? m.description : undefined,
                     icon: typeof m.icon === "string" && m.icon.trim() ? m.icon.trim() : undefined,
+                    iconSvg: normalizeIconSvg(m.iconSvg),
                     hasClient: existsSync(join(dir, "client", "entry.mjs")),
                     error: this.loaded.get(name)?.info.error,
                     // manifest 声明的能力清单（fs/net/tools…）——设置面板展示用
@@ -1787,6 +1824,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" 族，否则整份忽略；旧全权格式放行。
@@ -1840,7 +1880,19 @@ export class PluginManager {
                 }
             }
             catch {
-                continue; // 无 manifest / JSON 坏 —— 不是插件
+                // 无 manifest.json / JSON 解析失败 —— 占位行展示（坏插件不跳过，
+                // 设置面板清单标红 + 给原因；ensureLoaded 照例跳过激活）。
+                const msg = pick(l, `manifest.json 缺失或解析失败（${name}/），不是有效插件 —— 修复或移走该目录后点“重新扫描”`, `manifest.json missing or unparsable (${name}/), not a valid plugin — fix or remove the directory, then hit Rescan`, "plugins.manifest.broken", { name });
+                console.error(`[plugin:${name}] ${msg}`);
+                const brokenDiags = this.diagnosticsOf(name);
+                out.push({
+                    id: name,
+                    name,
+                    hasClient: existsSync(join(dir, "client", "entry.mjs")),
+                    error: msg,
+                    view: false,
+                    ...(brokenDiags ? { diagnostics: brokenDiags } : {}),
+                });
             }
         }
         // 删掉的目录不同时清快照：门禁会把不存在的 id 当 403，正确的应该是 404。
@@ -2073,7 +2125,22 @@ export class PluginManager {
             if (text.length > 8000)
                 return Promise.reject(new Error("chat: text 超长（>8000 字），请裁剪后重发"));
             const accountId = String(req?.accountId ?? "default").slice(0, 64);
-            return self.chatProvider(info.id, { text, accountId });
+            // issue #226：透传定时任务对齐的四件套（各按长度封顶，语义校验归宿主 chatFromPlugin）。
+            const r = (req ?? {});
+            const passthrough = { text, accountId };
+            const cwd = String(r.cwd ?? "").trim();
+            if (cwd)
+                passthrough.cwd = cwd.slice(0, 1024);
+            const conversationId = String(r.conversationId ?? "").trim();
+            if (conversationId)
+                passthrough.conversationId = conversationId.slice(0, 128);
+            const model = String(r.model ?? "").trim();
+            if (model)
+                passthrough.model = model.slice(0, 256);
+            const thinkingLevel = String(r.thinkingLevel ?? "").trim();
+            if (thinkingLevel)
+                passthrough.thinkingLevel = thinkingLevel.slice(0, 64);
+            return self.chatProvider(info.id, passthrough);
         };
         const host = {
             broadcast: (payload) => this.broadcast(info.id, payload),
@@ -2702,10 +2769,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;
@@ -2713,6 +2782,10 @@ export class PluginManager {
                     }
                     return `每 ${Math.round(ms / 1000)}s`;
                 };
+                const statusText = () => {
+                    const next = nextText();
+                    return next === null ? "不再触发（表达式在一年内不会命中）" : `下次 ${next}`;
+                };
                 // 后台面板条目（持久任务独有）：看得见下次时间，停止=删声明（不再复活）。
                 let bgRefresh;
                 let bgUnreg;
@@ -2723,7 +2796,7 @@ export class PluginManager {
                         id: taskId,
                         label: `⏰ ${label ?? sid}`,
                         since: Date.now(),
-                        status: `下次 ${nextText()}`,
+                        status: statusText(),
                         stop: () => off(),
                     };
                     bgTaskTable.set(taskId, entry);
@@ -2739,7 +2812,7 @@ export class PluginManager {
                     bgRefresh = () => {
                         if (!bgTaskTable.has(taskId))
                             return;
-                        entry.status = `下次 ${nextText()}`;
+                        entry.status = statusText();
                         fireBg();
                     };
                     bgUnreg = () => {
@@ -2773,14 +2846,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)
@@ -2792,7 +2881,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/prompt-composer.js

@@ -149,7 +149,7 @@ export function buildSkillsText(skills, lang = "en", fullText = false) {
         return "";
     const lines = [
         pick(lang, "以下技能为特定任务提供专门的指令。", "The following skills provide specialized instructions for specific tasks.", "prompt.skills.intro.specialized"),
-        pick(lang, "当任务与某技能的描述相符时，用 read 工具加载该技能文件。", "Use the read tool to load a skill's file when the task matches its description.", "prompt.skills.intro.use.read"),
+        pick(lang, "当任务与某技能的描述相符时，用 skill 工具按名称加载该技能全文。", "Use the skill tool to load a skill's full text by name when the task matches its description.", "prompt.skills.intro.use.skill"),
         pick(lang, "当技能文件引用相对路径时，以技能目录（SKILL.md 的父目录 / 该路径的 dirname）为基准解析，并在工具命令中使用解析后的绝对路径。", "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.", "prompt.skills.intro.resolve.path"),
         "",
         "<available_skills>",

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 = 17;
+export const PROTOCOL_VERSION = 18;