pi-web-ui 0.90.1 → 0.92.0

package/dist/server/skill-tool.js

@@ -0,0 +1,120 @@
+// ---------------------------------------------------------------------------
+// skill-tool.ts — 让 AI 按名取技能全文（名录 + skill 工具）
+// ---------------------------------------------------------------------------
+// 背景：{{skills}} 默认只渲染名录（name/description/location），引导语原来让
+// 模型“用 read 工具加载技能文件”——模型要自己拼 location 路径调 read，权限大
+// 且容易猜错路径。本工具提供专用通道：skill({name}) 精确命中，读文件包成与
+// SDK 一致的 `<skill name location>` 块（前端 parseSkillBlock 直接认，渲染折叠
+// 卡片）；不给 name 则返回名录 + 用法，找错名则给纠错列表。
+//
+// 约束（第 1 条定稿，不破坏现有体系）：
+//   - 名录渲染不动；skillsFullText 名单注入不动；/skill:name 手势不动；
+//   - 正文每次重读（不缓存），单文件 8KB 封顶（与 fillSkillContents 同口径）；
+//   - 禁用集由 host 在调用时过滤（与 skillsOverride 主会话语义一致），工具侧
+//     查不到被禁用的技能；
+//   - 与 SDK 同名工具撞名时 customTools 按 name 覆盖（bash 本体是先例）。
+//
+// 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；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 { decodeText } from "./text-sniff.js";
+/** 单文件正文上限（与 agent-service fillSkillContents 同口径：8KB）。 */
+export const SKILL_TOOL_FILE_CAP = 8192;
+/** 精确名匹配（大小写敏感，与 skillsFullText 名单语义一致）。 */
+export function findSkill(skills, name) {
+    const n = name.trim();
+    if (!n)
+        return undefined;
+    return skills.find((s) => s.name === n);
+}
+/** 大小写不敏感子串纠错（空 query 全匹配，调用方截行数）。 */
+export function suggestSkills(skills, name) {
+    const q = name.trim().toLowerCase();
+    if (!q)
+        return skills;
+    return skills.filter((s) => s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q));
+}
+/** 名录文本（一行一名 + 一句话描述，无技能时给空目录句）。 */
+export function formatSkillCatalog(skills, lang) {
+    if (skills.length === 0) {
+        return pick(lang, "当前没有可用技能。", "No skills are currently available.", "skill.catalog.empty");
+    }
+    const head = pick(lang, `可用技能（${skills.length}）：`, `Available skills (${skills.length}):`, "skill.catalog.title", { count: skills.length });
+    const lines = skills.map((s) => `- ${s.name}${s.description.trim() ? ` — ${s.description.trim()}` : ""}`);
+    return `${head}\n${lines.join("\n")}`;
+}
+/** 技能全文块（与 SDK 的 /skill:name 展开格式一致，前端按 skill 卡片渲染）。 */
+export function renderSkillContent(name, location, body) {
+    return `<skill name="${name}" location="${location}">\n${body.trim()}\n</skill>`;
+}
+export function makeSkillTool(host, lang) {
+    const getLang = lang ?? (() => "en");
+    const text = (t, details = {}) => ({
+        content: [{ type: "text", text: t }],
+        details,
+    });
+    return defineTool({
+        name: "skill",
+        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). " +
+            "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）"),
+        parameters: Type.Object({
+            name: Type.Optional(Type.String({
+                description: "Exact skill name from the catalog. Omit to list the current catalog.",
+            })),
+        }),
+        execute: async (_id, p) => {
+            let skills = [];
+            try {
+                skills = host.listSkills();
+            }
+            catch {
+                skills = [];
+            }
+            const L = getLang();
+            const name = typeof p.name === "string" ? p.name.trim() : "";
+            // 无名 → 名录 + 用法。
+            if (!name) {
+                const hint = pick(L, "用 skill({name}) 按名取全文。", "Use skill({name}) to load the full text by name.", "skill.catalog.hint");
+                return text(`${formatSkillCatalog(skills, L)}\n${hint}`, { count: skills.length });
+            }
+            const found = findSkill(skills, name);
+            // 找错名 → 纠错列表（不抛错，报名录）。
+            if (!found) {
+                const sug = suggestSkills(skills, name).slice(0, 10);
+                const head = pick(L, `没有名为 ${name} 的技能。`, `No skill named ${name}.`, "skill.not.found", { name });
+                const sugText = sug.length > 0 ? `\n${formatSkillCatalog(sug, L)}` : `\n${formatSkillCatalog(skills, L)}`;
+                return text(`${head}${sugText}`, { name, count: skills.length });
+            }
+            // 命中 → 最好努力读正文（每次重读，不缓存；失败/超限给可读错）。
+            if (!found.filePath) {
+                return text(pick(L, `技能 ${name} 没有关联文件路径，取不到全文。`, `Skill ${name} has no file path; full text unavailable.`, "skill.no.filepath", { name }));
+            }
+            try {
+                const st = statSync(found.filePath);
+                if (!st.isFile() || st.size <= 0 || st.size > SKILL_TOOL_FILE_CAP) {
+                    return text(pick(L, `技能 ${name} 的文件不可读（不存在/超 ${SKILL_TOOL_FILE_CAP / 1024}KB 上限）。`, `Skill ${name} file unreadable (missing or over the ${SKILL_TOOL_FILE_CAP / 1024}KB cap).`, "skill.file.unreadable", { name }));
+                }
+                const body = decodeText(readFileSync(found.filePath).subarray(0, st.size)).trim();
+                if (!body) {
+                    return text(pick(L, `技能 ${name} 的文件是空的。`, `Skill ${name} file is empty.`, "skill.file.empty", { name }));
+                }
+                return text(renderSkillContent(found.name, found.filePath, body), {
+                    name: found.name,
+                    location: found.filePath,
+                });
+            }
+            catch {
+                return text(pick(L, `技能 ${name} 的文件读取失败（可能已被删除或移走）。`, `Failed to read skill ${name} file (may have been deleted or moved).`, "skill.file.failed", { name }));
+            }
+        },
+    });
+}

package/dist/server/soft-cap.js

@@ -0,0 +1,68 @@
+/**
+ * 自定义上下文压缩阈值（Soft Cap，issue #229）。
+ *
+ * 背景：SDK 的自动压缩只看物理上限（shouldCompact：tokens > window - reserveTokens，
+ * reserveTokens 默认 16384）。对 1M 上下文的模型会堆到 ~900K 才压；对 Grok 这类
+ * 200K 起阶梯翻倍计费的模型，会在高价区跑很久，还伴随长上下文降智。
+ *
+ * 实现：软上限 C 转成 reserveTokens = W - C，经
+ * session.settingsManager.applyOverrides({ compaction: { reserveTokens } })
+ * 注入（与重试次数覆盖同一 live 机制，reload/建会话/换模型后重放）。
+ * 关掉软上限时回填 SDK 默认（DEFAULT_COMPACTION_SETTINGS.reserveTokens），
+ * 不让旧覆盖泄漏。
+ */
+import { DEFAULT_COMPACTION_SETTINGS } from "@earendil-works/pi-coding-agent";
+/** SDK 默认保留 token（软上限关闭时的回填值）。 */
+export const DEFAULT_COMPACTION_RESERVE_TOKENS = DEFAULT_COMPACTION_SETTINGS.reserveTokens;
+/** 软上限下限（tokens）：低于此值每轮都压，无意义，直接视为关闭。 */
+export const SOFT_CAP_MIN_TOKENS = 2000;
+/** 压缩后至少要剩这么多工作空间（摘要本身也要占 reserve*0.8 的预算）。 */
+export const SOFT_CAP_MIN_HEADROOM = 2048;
+/** 单客户端最多存多少条按模型覆盖（防手滑粘贴刷爆 client-state）。 */
+export const SOFT_CAP_MAX_OVERRIDES = 64;
+/** 归一化全局软上限：非数值/<=0 = 关闭；钳制到 [0, 10_000_000] 整数。 */
+export function normalizeSoftCapTokens(v) {
+    const n = Math.floor(Number(v));
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.min(10_000_000, n);
+}
+/** 归一化按模型覆盖：key = "provider/id" 非空（≤200 字），value 走
+ *  normalizeSoftCapTokens；0 值条目丢弃（= 用全局）；上限 64 条。纯函数。 */
+export function normalizeSoftCapByModel(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (Object.keys(out).length >= SOFT_CAP_MAX_OVERRIDES)
+            break;
+        const key = String(k).trim();
+        if (!key || key.length > 200)
+            continue;
+        const n = normalizeSoftCapTokens(val);
+        if (n > 0)
+            out[key] = n;
+    }
+    return out;
+}
+/** 当前模型的生效软上限（0 = 关闭）：按模型覆盖优先于全局。 */
+export function effectiveSoftCap(globalCap, byModel, modelId) {
+    if (modelId) {
+        const per = byModel?.[modelId.trim()];
+        if (per !== undefined && per > 0)
+            return per;
+    }
+    return globalCap > 0 ? globalCap : 0;
+}
+/** 软上限 → SDK reserveTokens（null = 不合法/关闭，走 SDK 默认）。
+ *  合法条件：cap ≥ SOFT_CAP_MIN_TOKENS 且压完至少剩 SOFT_CAP_MIN_HEADROOM。 */
+export function softCapToReserve(contextWindow, cap) {
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return null;
+    if (!Number.isFinite(cap) || cap < SOFT_CAP_MIN_TOKENS)
+        return null;
+    const reserve = Math.floor(contextWindow - cap);
+    if (reserve < SOFT_CAP_MIN_HEADROOM)
+        return null;
+    return reserve;
+}

package/dist/server/subagent-templates.js

@@ -623,6 +623,12 @@ export class SubagentTemplatesStore {
         const t = normalize(input);
         if (!t)
             return `模板名称不合法（去空白后 1-${NAME_MAX} 字符）`;
+        // replace + 空提示词 = 子代理静默用默认 persona 运行（模板等于没生效），
+        // 在保存期直接拦下：只想限定白名单请用 append 模式。读盘的老数据不拦
+        // （向后兼容，只拦新保存）。
+        if (t.promptMode === "replace" && !t.systemPrompt.trim() && !(t.systemPromptEn ?? "").trim()) {
+            return `模板 "${t.name}" 用了 replace 模式但系统提示词为空：replace 会整体替换子代理 persona，空提示词等于模板没生效。请填写提示词（中文或英文至少一个），只想限定技能/扩展白名单请用 append 模式`;
+        }
         const list = this.load();
         const i = list.findIndex((x) => x.name === t.name);
         if (i >= 0)

package/dist/server/subagents.js

@@ -130,7 +130,18 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 if (p.template && !host.isTemplateUsable(p.template)) {
                     return text(pick(getLang(), `子代理模板不可用：${p.template}（不存在或已停用）。用 subagent_templates 查看当前可用模板清单；不传 template 则按默认配置运行。`, `Subagent template unavailable: ${p.template} (missing or disabled). Use subagent_templates to list available templates; omit template to run with defaults.`, "subagents.spawn.template.unavailable", { "p.template": p.template }));
                 }
-                const convId = await host.spawnSubagent(p.prompt, p.type ?? "general", p.cwd ?? ctx.cwd, p.template, p.model);
+                // spawn 通道是唯一的失败面（数量上限 / runtime 创建失败 / 坏 cwd 都经由
+                // host 抛错）：转成返回文本而不是直接抛，让 AI 能读到原因并调整重试。
+                let convId;
+                try {
+                    convId = await host.spawnSubagent(p.prompt, p.type ?? "general", p.cwd ?? ctx.cwd, p.template, p.model);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return text(pick(getLang(), `子代理启动失败：${msg}`, `Failed to start subagent: ${msg}`, "subagents.spawn.failed", {
+                        error: msg,
+                    }));
+                }
                 const subagentType = p.type ?? "general";
                 const subagentTitleText = subagentTitle(p.prompt);
                 // Optional segments are pre-rendered per language (translators pick
@@ -197,6 +208,10 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 }),
             }),
             execute: async (_id, p) => {
+                if (!host.getSubagent(p.runId)) {
+                    const missingSteerId = shortId(p.runId);
+                    return text(pick(getLang(), `未找到子代理 ${missingSteerId}（可能已移出），消息未注入。请用 subagent_list 确认仍在运行的子代理。`, `Subagent ${missingSteerId} not found (may have been dismissed); message not injected. Use subagent_list to confirm running subagents.`, "subagents.steer.not.found", { missingSteerId: missingSteerId }));
+                }
                 await host.steerSubagent(p.runId, p.message);
                 const steerId = shortId(p.runId);
                 return text(pick(getLang(), `已向子代理 ${steerId} 注入消息。`, `Message injected into subagent ${steerId}.`, "subagents.steer.injected", { steerId: steerId }));
@@ -229,6 +244,10 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 }),
             }),
             execute: async (_id, p) => {
+                if (!host.getSubagent(p.runId)) {
+                    const missingStopId = shortId(p.runId);
+                    return text(pick(getLang(), `未找到子代理 ${missingStopId}（可能已移出或已结束），无需停止。请用 subagent_list 确认仍在运行的子代理。`, `Subagent ${missingStopId} not found (may have been dismissed or already finished); nothing to stop. Use subagent_list to confirm running subagents.`, "subagents.stop.not.found", { missingStopId: missingStopId }));
+                }
                 await host.stopSubagent(p.runId);
                 const stopId = shortId(p.runId);
                 return text(pick(getLang(), `已请求停止子代理 ${stopId}。`, `Stop requested for subagent ${stopId}.`, "subagents.stop.requested", { stopId: stopId }));
@@ -239,12 +258,15 @@ export function makeSubagentTools(host, lang, selfConvId) {
             label: "Wait for subagents",
             description: bilingual("Wait for multiple subagents to finish at once (blocks this round until all reach a terminal state or time out), " +
                 "then summarize each result/error — no need to poll subagent_get_result. Pass runIds for specific subagents " +
-                "(convIds returned by subagent_spawn); omit = wait for all currently running ones. The calling session itself " +
-                "is never waited on (a subagent calling this without runIds won't deadlock on itself). " +
+                "(convIds returned by subagent_spawn); omit = wait for own descendant subagents when called from a subagent, " +
+                "else all currently running ones. The calling session itself and its ancestors are never waited on " +
+                "(a subagent calling this without runIds won't deadlock on itself or its parent). " +
+                "Descendants spawned during the wait are picked up automatically. " +
                 "On timeout or abort of this round, returns the remaining unfinished list; call again to continue waiting. " +
                 "Good for: collecting parallel subagents.", "一次性等待多个子代理全部完成（阻塞本回合直到它们都到达终态或超时），然后汇总返回每个的结果/错误——" +
                 "不用反复调 subagent_get_result 轮询。传 runIds 指定要等的子代理（subagent_spawn 返回的 convId）；" +
-                "不传 = 等当前全部运行中的子代理。调用者自身永不计入等待（子代理不传 runIds 时不会等自己）。" +
+                "不传 = 子代理调用时只等自己的后代，主对话调用时等当前全部运行中的子代理。调用者自身与祖先永不计入等待" +
+                "（子代理不传 runIds 时不会等自己或父级，避免父子互等到超时）。等待期间新派生的后代会自动纳入。" +
                 "超时或本轮被中止时返回剩余未完成名单，可再次调用继续等。" +
                 "适合：并行派发多个子代理后收口。"),
             promptSnippet: "wait for multiple subagents to finish (no polling) and get all results",
@@ -259,25 +281,129 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 })),
             }),
             execute: async (_id, p, signal) => {
-                const wanted = new Set(p.runIds && p.runIds.length > 0 ? p.runIds : host.listSubagents().map((r) => r.convId));
-                // 调用者自身永不等待：子代理调本工具时它自己正在 streaming，不排除
-                // 就是自己等自己、永远到超时（self-wait deadlock）。主会话的普通
-                // 对话 id 不在子代理列表里，delete 是 no-op。
-                if (selfConvId)
-                    wanted.delete(selfConvId);
+                // 祖先链：调用者往上经 parentId 能走到的子代理集合。父级正在执行中的
+                // wait_all 卡着（streaming=true），等它 = 父子互等、必到超时才返回。
+                // parentId 可能指向普通主对话（不在子代理列表里），走到空即停；环按 visited 截断。
+                const ancestorIdsOf = (selfId) => {
+                    const out = new Set();
+                    const seen = new Set([selfId]);
+                    let cur = host.getSubagent(selfId)?.parentId;
+                    while (cur && !seen.has(cur)) {
+                        seen.add(cur);
+                        // 只有子代理才可能被圈进等待集；普通主对话记下来也无妨（wanted 里没有它）。
+                        out.add(cur);
+                        cur = host.getSubagent(cur)?.parentId;
+                    }
+                    return out;
+                };
+                // 后代展开：roots 里任一 id 经 parentId 链能向上走到的子代理。等待集
+                // 传了显式 runIds 时也要顺带等它们的后代（fire-and-forget 的孙子辈否则会漏）。
+                const expandDescendants = (roots) => {
+                    if (roots instanceof Set ? roots.size === 0 : roots.length === 0)
+                        return [];
+                    const rootSet = roots instanceof Set ? roots : new Set(roots);
+                    const all = host.listSubagents();
+                    const byId = new Map(all.map((s) => [s.convId, s]));
+                    const out = [];
+                    for (const s of all) {
+                        if (rootSet.has(s.convId))
+                            continue;
+                        let curParent = s.parentId;
+                        const seen = new Set();
+                        while (curParent) {
+                            if (rootSet.has(curParent)) {
+                                out.push(s.convId);
+                                break;
+                            }
+                            if (seen.has(curParent))
+                                break;
+                            seen.add(curParent);
+                            curParent = byId.get(curParent)?.parentId;
+                            // parentId 指向普通主对话（不在 byId 里）：链到此为止，
+                            // 但 root 本身可能就是那个主对话 id（主调 wait_all 的 selfConvId）。
+                            if (!curParent)
+                                break;
+                        }
+                    }
+                    return out;
+                };
+                const explicit = p.runIds && p.runIds.length > 0;
+                const wanted = new Set();
+                const roots = new Set();
+                let implicitGlobal = false;
+                // 调用者自身 + 祖先永不等待：子代理调本工具时它自己正在 streaming，
+                // 父级同样 streaming（卡在它自己的 wait 里），等谁都是互等死锁到超时。
+                // 先算好排除集，显式 runIds 里的祖先直接剔除（不再展开它的子树，
+                // 否则等父会顺带把整棵子树含兄弟分支都圈进来）。
+                const excluded = new Set();
+                if (selfConvId) {
+                    excluded.add(selfConvId);
+                    for (const a of ancestorIdsOf(selfConvId))
+                        excluded.add(a);
+                }
+                if (explicit) {
+                    for (const id of p.runIds) {
+                        if (!excluded.has(id))
+                            roots.add(id);
+                    }
+                    for (const id of roots)
+                        wanted.add(id);
+                    for (const id of expandDescendants(roots)) {
+                        if (!excluded.has(id))
+                            wanted.add(id);
+                    }
+                }
+                else if (selfConvId && host.getSubagent(selfConvId)) {
+                    // 子代理无参：只等自己的后代（不含自己）。全局等会把父级/无关兄弟
+                    // 也圈进来：父级卡在 wait 里 streaming=true，子等父 = 父子互等到超时。
+                    roots.add(selfConvId);
+                    for (const id of expandDescendants(roots)) {
+                        if (!excluded.has(id))
+                            wanted.add(id);
+                    }
+                }
+                else {
+                    // 主对话无参：等当前全部（保持老语义），但同样动态追后代。
+                    implicitGlobal = true;
+                    for (const r of host.listSubagents()) {
+                        if (!excluded.has(r.convId))
+                            wanted.add(r.convId);
+                    }
+                }
                 if (wanted.size === 0) {
                     const emptyLang = getLang();
-                    return text(pick(emptyLang, "没有需要等待的子代理（调用者自身不计入等待）。", "No subagents to wait for (the calling session itself is never waited on).", "subagents.wait.empty"));
+                    return text(pick(emptyLang, "没有需要等待的子代理（调用者自身与祖先不计入等待；子代理无参时只等自己的后代）。", "No subagents to wait for (the calling session itself and its ancestors are never waited on; a subagent without runIds only waits for its own descendants).", "subagents.wait.empty"));
                 }
                 const timeoutMs = Math.min(Math.max(p.timeoutSeconds ?? 600, 1), Math.floor(WAIT_CAP_MS / 1000)) * 1000;
                 const waitStart = Date.now();
                 const deadline = waitStart + timeoutMs;
                 // 已到终态的、（或已被移出找不到的）直接归位；剩下的阻塞轮询到
                 // 全部完成/超时/中止（移出 = 无法再等，立即按收口处理）。
-                const pending = () => [...wanted].filter((id) => {
-                    const r = host.getSubagent(id);
-                    return r !== undefined && !isSubagentTerminal(r);
-                });
+                // 每轮动态追踪：等待期间新派生的后代（roots 的子孙、或主调全局新增）自动纳入，
+                // fire-and-forget 的孙子辈不会漏；自身与祖先永远排除（父子互等死锁）。
+                const trackNewArrivals = () => {
+                    if (implicitGlobal) {
+                        for (const r of host.listSubagents()) {
+                            if (excluded.has(r.convId))
+                                continue;
+                            wanted.add(r.convId);
+                        }
+                    }
+                    else {
+                        for (const id of expandDescendants(roots)) {
+                            if (excluded.has(id))
+                                continue;
+                            wanted.add(id);
+                        }
+                    }
+                };
+                const pending = () => {
+                    trackNewArrivals();
+                    return [...wanted].filter((id) => {
+                        const r = host.getSubagent(id);
+                        return r !== undefined && !isSubagentTerminal(r);
+                    });
+                };
                 while (pending().length > 0 && Date.now() < deadline && !(signal?.aborted ?? false)) {
                     await new Promise((resolve) => setTimeout(resolve, 300));
                 }
@@ -295,7 +421,7 @@ export function makeSubagentTools(host, lang, selfConvId) {
                         ? `- ${shortId(r.convId)}（${r.type}）· ${r.title} · ${subagentVerdict(r, tLang)}`
                         : `- ${shortId(r.convId)} (${r.type}) · ${r.title} · ${subagentVerdict(r, tLang)}`) +
                         (body ? `\n  ${body}` : "") +
-                        (r.output ? `\n  ${r.output.split("\n").slice(0, 30).join("\n  ")}` : ""));
+                        (r.output ? `\n  ${clipSubagentOutput(r.output, tLang).split("\n").join("\n  ")}` : ""));
                 })
                     .join("\n");
                 const timeoutSecs = Math.round(timeoutMs / 1000);
@@ -354,6 +480,21 @@ export function makeSubagentTools(host, lang, selfConvId) {
 function shortId(id) {
     return id.slice(0, 8);
 }
+/**
+ * wait_all 收口时的长输出截断：留头（任务复述）+ 留尾（最终结论），中间折叠。
+ * 旧实现只取前 30 行，长输出的子代理结论（一般在尾部）会被丢掉，模型收回一个
+ * 没结论的摘要。短输出原样返回。
+ */
+function clipSubagentOutput(output, lang) {
+    const HEAD = 10;
+    const TAIL = 30;
+    const lines = output.split("\n");
+    if (lines.length <= HEAD + TAIL + 5)
+        return output;
+    const omitted = lines.length - HEAD - TAIL;
+    const marker = lang === "zh" ? `… [中间省略 ${omitted} 行，头尾保留] …` : `… [${omitted} lines omitted, head and tail kept] …`;
+    return [...lines.slice(0, HEAD), marker, ...lines.slice(-TAIL)].join("\n");
+}
 /**
  * 收集 root 的传递子代理后代 id（parentId 链向上能走到 root 的；含嵌套的嵌套）。
  * root 自身不含；非子代理对话不含（普通对话不参与子代理清理口径）。

package/dist/server/text-sniff.js

@@ -20,6 +20,10 @@ const PREVIEW_IMAGE_EXTS = new Set([
     "tiff",
 ]);
 const PREVIEW_VIDEO_EXTS = new Set(["mp4", "webm", "mov", "mkv", "avi", "m4v", "ogv", "mpg", "mpeg", "wmv", "flv"]);
+/** 浏览器 <audio> 能直接播放的音频容器（present_files 的卡片与 /api/file 白名单
+ *  共用这一份）：不在表里的（wma/aiff/midi/…）一律按二进制处理，让用户下载或
+ *  本地打开，而不是给一个永远播不出来的播放器。 */
+const PREVIEW_AUDIO_EXTS = new Set(["mp3", "wav", "wave", "ogg", "oga", "opus", "m4a", "aac", "flac", "weba"]);
 const PREVIEW_TEXT_EXTS = new Set([
     // code
     "ts",
@@ -151,6 +155,17 @@ export function previewKind(name) {
         return "text";
     return "none";
 }
+/**
+ * 扩展名是否为浏览器可直接播放的音频。与 previewKind 分开：PreviewKind 只有
+ * image/video/text/none 四档（右栏图标、附件、预览弹窗都按它分支），把音频塞进去
+ * 要动整条链路；而 /api/file 的媒体白名单与 present_files 的卡片只需要一个
+ * 「能不能 inline 播」的布尔判断。
+ */
+export function isAudioFile(name) {
+    const dot = name.lastIndexOf(".");
+    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+    return PREVIEW_AUDIO_EXTS.has(ext);
+}
 /**
  * Content sniff for the preview: any data that has no NUL bytes and no
  * meaningful control-char ratio is treated as text — so files with unknown

package/dist/server/themes.js

@@ -22,9 +22,10 @@ const ID_RE = /^[A-Za-z0-9_-]+$/;
  *  filename stays ASCII (id must match ID_RE). */
 const THEME_NAME_RE = /\/\*\s*theme-name:\s*(.+?)\s*\*\//;
 const THEME_NAME_EN_RE = /\/\*\s*theme-name-en:\s*(.+?)\s*\*\//;
+const THEME_GROUP_RE = /\/\*\s*theme-group:\s*(.+?)\s*\*\//;
 function readDisplayName(path, fallback) {
     try {
-        const head = readFileSync(path, "utf8").slice(0, 300);
+        const head = readFileSync(path, "utf8").slice(0, 400);
         return head.match(THEME_NAME_RE)?.[1]?.trim() || fallback;
     }
     catch {
@@ -33,13 +34,25 @@ function readDisplayName(path, fallback) {
 }
 function readDisplayNameEn(path) {
     try {
-        const head = readFileSync(path, "utf8").slice(0, 300);
+        const head = readFileSync(path, "utf8").slice(0, 400);
         return head.match(THEME_NAME_EN_RE)?.[1]?.trim() || undefined;
     }
     catch {
         return undefined;
     }
 }
+function readGroup(path) {
+    try {
+        const head = readFileSync(path, "utf8").slice(0, 400);
+        const g = head.match(THEME_GROUP_RE)?.[1]?.trim();
+        if (g === "classic")
+            return "classic";
+    }
+    catch {
+        // ignore
+    }
+    return "builtin";
+}
 export function listThemes(builtinDir, userDir) {
     const scan = (dir, builtin) => {
         if (!existsSync(dir))
@@ -53,10 +66,12 @@ export function listThemes(builtinDir, userDir) {
             const id = f.slice(0, -4);
             const name = readDisplayName(path, id);
             const nameEn = readDisplayNameEn(path);
+            const group = readGroup(path);
             return {
                 id,
                 name,
                 builtin,
+                group,
                 ...(nameEn ? { nameEn } : {}),
             };
         });

package/dist/server/tool-manager.js

@@ -50,14 +50,20 @@ export const BROWSER_PAGE_TOOL_NAME = "browser_page";
 /** 别的对话读取工具（定义见 conversation-read-tool.ts）：运行中对话（含子代理）+
  *  历史会话转录，只读。 */
 export const CONVERSATION_READ_TOOL_NAME = "conversation_read";
+/** 技能全文按名加载工具（定义见 skill-tool.ts）：名录见 {{skills}} 段，
+ *  全文走本工具按需取，不再让模型拼路径调 read。 */
+export const SKILL_TOOL_NAME = "skill";
 /** 定时任务工具（定义见 schedule-agent-tool.ts）：创建/查看/取消内置调度任务，
  *  到期自动唤醒发起对话执行 prompt 并汇报。 */
 export const SCHEDULE_TASK_TOOL_NAME = "schedule_task";
 export const SCHEDULE_LIST_TOOL_NAME = "schedule_list";
 export const SCHEDULE_CANCEL_TOOL_NAME = "schedule_cancel";
+/** 展示文件工具（定义见 present-files-tool.ts）：把图片/视频/文本作为预览卡片
+ *  推到对话里，卡片带预览/本地打开/在文件夹中显示/下载/复制路径。 */
+export const PRESENT_FILES_TOOL_NAME = "present_files";
 /** 旧工具名（持久化迁移用；新代码一律用 MARKERS_LIST_TOOL_NAME）。 */
 export const LEGACY_MARKERS_LIST_TOOL_NAME = "markers_list";
-/** 可开关的 Agent 工具总目录（共 23 个；bash 本体与 SDK 内置 edit/read
+/** 可开关的 Agent 工具总目录（共 25 个；bash 本体与 SDK 内置 edit/read
  *  不进目录——关了 agent 就残了，不给关）。 */
 export const AGENT_TOOL_CATALOG = [
     ...TERMINAL_TOOL_NAMES.map((name) => ({
@@ -81,11 +87,17 @@ export const AGENT_TOOL_CATALOG = [
     { name: BROWSER_PAGE_TOOL_NAME, group: "other", defaultOn: false, dshVisible: false },
     // 只读别的对话（含子代理实时消息与历史转录），默认开；DSH 引擎没有该 customTool。
     { name: CONVERSATION_READ_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
+    // 技能全文按名加载（名录仍在 {{skills}} 段），默认开；DSH 引擎没有该 customTool
+    // （走 goal-rpc，无 customTool 注册面）。
+    { name: SKILL_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
     // 定时/延时唤醒：默认开（不打开 AI 根本不知道能定时；60s 间隔底线＋面板可随时取消），
     // DSH 引擎没有该 customTool（走 goal-rpc，无 customTool 注册面）。
     { name: SCHEDULE_TASK_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
     { name: SCHEDULE_LIST_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
     { name: SCHEDULE_CANCEL_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
+    // 展示文件给用户（图片/视频内联、文本开预览弹窗、本地打开按钮）：默认开，
+    // 不打开模型根本不知道能“给用户看”；DSH 引擎没有该 customTool（走 shipped preset）。
+    { name: PRESENT_FILES_TOOL_NAME, group: "other", defaultOn: true, dshVisible: false },
 ];
 const KNOWN_NAMES = new Set(AGENT_TOOL_CATALOG.map((t) => t.name));
 /** 是否为本表登记的可开关工具（未知名一律 false，不抛错）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-web-ui",
-	"version": "0.90.1",
+	"version": "0.92.0",
 	"description": "Just open your browser to get all your work done — browser cockpit for AI coding agents (chat, code, files, terminal, Git in one tab)",
 	"license": "MIT",
 	"author": {
@@ -91,6 +91,7 @@
 		"electron-updater": "^6.8.9",
 		"express": "^5.2.1",
 		"highlight.js": "^11.12.0",
+		"html-to-image": "^1.11.13",
 		"katex": "^0.18.7",
 		"node-pty": "^1.1.0",
 		"react": "^19.3.0",

package/plugin-sdk/README.md

@@ -120,6 +120,7 @@ describe("my-plugin", () => {
 | `kind: "select"` + `options` + `value`，`host.ui.update(id, { value })` 刷新                     | ✅                    | 顶栏/输入框/消息工具条已渲染    |
 | `when` 肯定形条件（`file.isDir` / `file.isFile` / `session.isRunning` / `message.hasSelection`） | —                     | 右键菜单现场求值，置灰          |
 | `settings` 新增 `secret` 类型（加密存，浏览器只见有无）                                          | ✅                    | 设置表单掩码 + 留空不改         |
+| `settings` 的 `select` 支持 `optionsFrom`（宿主现算候选值：`models` / `thinkingLevels`）         | ✅                    | 下拉自动带「跟随全局默认」      |
 | `host.llm.complete`（孤立无工具补全，不建对话）                                                  | ✅（要 `llm` 能力族） | —                               |
 | `schedule` 持久版（`{id, persistent, catchUp, label}`，落盘+补跑+进后台面板）                    | ✅                    | —                               |
 | `host.requestPermission`（动态授权：net 补主机 / llm 限模型，用户逐条确认可记住）                | ✅（基础族须已声明）  | 确认框 + 设置面板「已授权能力」 |