pi-web-ui 0.94.1 → 0.96.0

package/dist/server/plugin-manifest-validate.js

@@ -0,0 +1,305 @@
+/**
+ * manifest 本体校验：schema 失败即拒（DSH 对照 P1-6）。
+ *
+ * 与 `parseUiItem` / `parseSettingsSchema` 的"宽容丢弃"正交：
+ * 那些是字段级容错（坏条目跳过、文本截断），这里是**结构级否决**
+ * （坏 manifest 不该变成运行时 `undefined` 再在远处 nổ）。
+ *
+ * 语义对齐既有契约：
+ * - 旧插件（无 `permissions` 且 `apiVersion<2`）走宽容通道：只拦
+ *   JSON 坏 / 非对象 / apiVersion 非法这类"连启动都不该启动"的；
+ *   未知能力族、v2 必填缺失等只在严格模式下才算 error。
+ * - `errors` 非空 → 拒绝激活（scan 置 error + activate 首行回卷）；
+ *   `warnings` 永不阻断，只进 `diagnostics` 供设置面板查看。
+ */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 与 `plugin-sdk/index.d.ts#PluginPermissionFamily` + 运行时 `requestPermission` 同口径。 */
+export const KNOWN_PERMISSION_FAMILIES = new Set([
+    "fs",
+    "fs:read",
+    "fs:write",
+    "ui",
+    "tools",
+    "http",
+    "chat",
+    "net",
+    "llm",
+    "dom",
+    "dom:anchor",
+]);
+function isRecord(v) {
+    return Boolean(v) && typeof v === "object" && !Array.isArray(v);
+}
+/** 能力串是否已知：完整串或冒号前族名命中其一即算（如 "ui:read" 归 ui 族）。 */
+export function isKnownPermission(v) {
+    return KNOWN_PERMISSION_FAMILIES.has(v) || KNOWN_PERMISSION_FAMILIES.has(v.split(":")[0]);
+}
+export function validatePluginManifest(raw, dirName) {
+    const errors = [];
+    const warnings = [];
+    if (!isRecord(raw)) {
+        errors.push({
+            path: "manifest",
+            message: "manifest.json 必须是对象",
+            messageEn: "manifest.json must be an object",
+        });
+        return { errors, warnings, apiVersion: 1, permissions: [], strict: false };
+    }
+    const o = raw;
+    // id：缺省回落目录名（向后兼容，只警告）；写了就必须合法且与目录一致。
+    const idRaw = o.id;
+    if (idRaw === undefined) {
+        // 旧插件大量不写 id，不警告（避免全仓黄灯），仅回落。
+    }
+    else if (typeof idRaw !== "string" || !idRaw.trim()) {
+        warnings.push({
+            path: "id",
+            message: "id 非字符串，已回落为目录名",
+            messageEn: 'invalid "id", fell back to directory name',
+        });
+    }
+    else if (!ID_RE.test(idRaw.trim())) {
+        errors.push({
+            path: "id",
+            message: `id「${idRaw.trim().slice(0, 32)}」非法（只允许字母数字/_/-）`,
+            messageEn: `invalid "id" (only [A-Za-z0-9_-] allowed)`,
+        });
+    }
+    else if (idRaw.trim() !== dirName) {
+        errors.push({
+            path: "id",
+            message: `id「${idRaw.trim()}」与目录名「${dirName}」不一致`,
+            messageEn: `"id" does not match directory name "${dirName}"`,
+        });
+    }
+    // apiVersion：缺省 1（旧插件常态，不警告）；写了必须是 1..2 整数。
+    let apiVersion = 1;
+    const av = o.apiVersion;
+    if (av === undefined) {
+        apiVersion = 1;
+    }
+    else if (typeof av !== "number" || !Number.isInteger(av) || av < 1) {
+        errors.push({
+            path: "apiVersion",
+            message: "apiVersion 必须是 >=1 的整数",
+            messageEn: '"apiVersion" must be an integer >= 1',
+        });
+        apiVersion = 1;
+    }
+    else {
+        apiVersion = av;
+    }
+    // permissions：非数组即错；条目逐个校验。
+    let permissions = [];
+    const perms = o.permissions;
+    if (perms === undefined) {
+        permissions = [];
+    }
+    else if (!Array.isArray(perms)) {
+        errors.push({
+            path: "permissions",
+            message: "permissions 必须是字符串数组",
+            messageEn: '"permissions" must be an array of strings',
+        });
+    }
+    else {
+        if (perms.length > 16) {
+            warnings.push({
+                path: "permissions",
+                message: `permissions 超出 16 个，多余的将被忽略`,
+                messageEn: '"permissions" capped at 16 entries',
+            });
+        }
+        for (let i = 0; i < Math.min(perms.length, 16); i++) {
+            const p = perms[i];
+            const path = `permissions[${i}]`;
+            if (typeof p !== "string" || !p.trim()) {
+                errors.push({ path, message: "能力声明不能为空", messageEn: "capability must be a non-empty string" });
+                continue;
+            }
+            const v = p.trim();
+            if (!isKnownPermission(v)) {
+                // 未知族：拼写错了就永远授权失败，与静默丢弃同源 —— 直接拒。
+                errors.push({
+                    path,
+                    message: `未知能力「${v.slice(0, 32)}」（可选 ${[...KNOWN_PERMISSION_FAMILIES].join("/")})`,
+                    messageEn: `unknown capability "${v.slice(0, 32)}"`,
+                });
+                continue;
+            }
+            permissions.push(v);
+        }
+    }
+    const strict = permissions.length > 0 || apiVersion >= 2;
+    // v2 必须声明 permissions（与 §2.5 严格模式同口径）。只对宿主认识的版本强制：
+    // apiVersion > 2 交给版本门出“请升级”（见 activate/scan），这里不抢它的错误信息。
+    if (apiVersion === 2 && permissions.length === 0 && perms === undefined) {
+        errors.push({
+            path: "permissions",
+            message: "apiVersion 2 的插件必须声明 permissions",
+            messageEn: 'apiVersion 2 plugins must declare "permissions"',
+        });
+    }
+    // engines：只收字符串映射；坏形状即错（否则约束被静默吞掉）。
+    if (o.engines !== undefined) {
+        if (!isRecord(o.engines)) {
+            errors.push({ path: "engines", message: "engines 必须是对象", messageEn: '"engines" must be an object' });
+        }
+        else {
+            for (const [k, v] of Object.entries(o.engines).slice(0, 8)) {
+                if (typeof v !== "string") {
+                    errors.push({
+                        path: `engines.${k}`,
+                        message: "engines 约束值必须是字符串",
+                        messageEn: '"engines" constraint values must be strings',
+                    });
+                }
+            }
+        }
+    }
+    // requires（P2-8 硬依赖）：坏形状即错（依赖判定错不得，静默吞掉等于回到 peerPlugins 的老路）。
+    if (o.requires !== undefined) {
+        if (!isRecord(o.requires)) {
+            errors.push({ path: "requires", message: "requires 必须是对象", messageEn: '"requires" must be an object' });
+        }
+        else {
+            const r = o.requires;
+            if (r.hostApi !== undefined &&
+                (typeof r.hostApi !== "number" || !Number.isInteger(r.hostApi) || r.hostApi < 1)) {
+                errors.push({
+                    path: "requires.hostApi",
+                    message: "requires.hostApi 必须是 >=1 的整数",
+                    messageEn: '"requires.hostApi" must be an integer >= 1',
+                });
+            }
+            if (r.families !== undefined) {
+                if (!Array.isArray(r.families)) {
+                    errors.push({
+                        path: "requires.families",
+                        message: "requires.families 必须是字符串数组",
+                        messageEn: '"requires.families" must be an array of strings',
+                    });
+                }
+                else {
+                    if (r.families.length > 8) {
+                        warnings.push({
+                            path: "requires.families",
+                            message: "requires.families 超出 8 个，多余的将被忽略",
+                            messageEn: '"requires.families" capped at 8 entries',
+                        });
+                    }
+                    for (let i = 0; i < Math.min(r.families.length, 8); i++) {
+                        const f = r.families[i];
+                        const path = `requires.families[${i}]`;
+                        if (typeof f !== "string" || !f.trim()) {
+                            errors.push({ path, message: "能力族不能为空", messageEn: "family must be a non-empty string" });
+                        }
+                        else if (!isKnownPermission(f.trim())) {
+                            errors.push({
+                                path,
+                                message: `未知能力族「${f.trim().slice(0, 32)}」（拼写？或需要更新 pi-web-ui）`,
+                                messageEn: `unknown family "${f.trim().slice(0, 32)}" (typo? or needs newer pi-web-ui)`,
+                            });
+                        }
+                    }
+                }
+            }
+            if (r.plugins !== undefined) {
+                if (!Array.isArray(r.plugins)) {
+                    errors.push({
+                        path: "requires.plugins",
+                        message: "requires.plugins 必须是插件 id 数组",
+                        messageEn: '"requires.plugins" must be an array of plugin ids',
+                    });
+                }
+                else {
+                    if (r.plugins.length > 16) {
+                        warnings.push({
+                            path: "requires.plugins",
+                            message: "requires.plugins 超出 16 个，多余的将被忽略",
+                            messageEn: '"requires.plugins" capped at 16 entries',
+                        });
+                    }
+                    for (let i = 0; i < Math.min(r.plugins.length, 16); i++) {
+                        const dep = r.plugins[i];
+                        if (typeof dep !== "string" || !ID_RE.test(dep.trim())) {
+                            errors.push({
+                                path: `requires.plugins[${i}]`,
+                                message: "插件 id 非法（只允许字母数字/_/-）",
+                                messageEn: "invalid plugin id (only [A-Za-z0-9_-] allowed)",
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // view / preload：坏类型只警告（不影响安全语义，回落缺省）。
+    for (const key of ["view", "preload"]) {
+        if (o[key] !== undefined && typeof o[key] !== "boolean") {
+            warnings.push({
+                path: key,
+                message: `${key} 必须是布尔值，已回落缺省`,
+                messageEn: `"${key}" must be a boolean, fell back to default`,
+            });
+        }
+    }
+    // 文本字段：坏类型只警告（回落缺省，不阻断）。
+    for (const key of ["name", "version", "description", "icon"]) {
+        if (o[key] !== undefined && typeof o[key] !== "string") {
+            warnings.push({
+                path: key,
+                message: `${key} 必须是字符串，已忽略`,
+                messageEn: `"${key}" must be a string, ignored`,
+            });
+        }
+    }
+    // 数组型声明：坏形状只警告（解析层已按"过滤+截断"处理）。
+    for (const key of [
+        "netAllowlist",
+        "peerPlugins",
+        "renderers",
+        "messageWidgets",
+        "attachmentCards",
+        "composerProviders",
+    ]) {
+        if (o[key] !== undefined && !Array.isArray(o[key])) {
+            warnings.push({
+                path: key,
+                message: `${key} 必须是数组，已忽略`,
+                messageEn: `"${key}" must be an array, ignored`,
+            });
+        }
+    }
+    if (o.settings !== undefined && !Array.isArray(o.settings) && !isRecord(o.settings)) {
+        warnings.push({
+            path: "settings",
+            message: "settings 必须是数组或对象，已忽略",
+            messageEn: '"settings" must be an array or object, ignored',
+        });
+    }
+    if (o.fileHandlers !== undefined && !Array.isArray(o.fileHandlers)) {
+        warnings.push({
+            path: "fileHandlers",
+            message: "fileHandlers 必须是数组，已忽略",
+            messageEn: '"fileHandlers" must be an array, ignored',
+        });
+    }
+    // ui：有声明却无 ui 能力（严格模式）= 整份不会生效 —— 算 error 而不是等解析层那条英文诊断。
+    // 同样只对宿主认识的版本（apiVersion<=2）强制，未来版本交给版本门。
+    if (o.ui !== undefined && strict && apiVersion <= 2 && !permissions.some((x) => x.split(":")[0] === "ui")) {
+        errors.push({
+            path: "ui",
+            message: '声明了 ui 却未声明 "ui" 能力，整份 ui 不会生效',
+            messageEn: 'manifest declares "ui" but lacks the "ui" capability — the whole ui section is ignored',
+        });
+    }
+    if (o.ui !== undefined && typeof o.ui !== "object") {
+        errors.push({ path: "ui", message: "ui 必须是对象", messageEn: '"ui" must be an object' });
+    }
+    return { errors, warnings, apiVersion, permissions, strict };
+}
+/** 诊断行渲染（scan/activate 共用）：`path: 中文（en）`。 */
+export function formatManifestIssue(i) {
+    return `${i.path}: ${i.message} (${i.messageEn})`;
+}

package/dist/server/plugin-project.js

@@ -24,7 +24,8 @@
  */
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readdir as fspReaddir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { killPidTree } from "./process-utils.js";
 /** 单条 git 命令的默认墙钟上限：大仓库 clone 可能很慢，给足 5 分钟。 */
@@ -91,8 +92,9 @@ function realpathOf(p) {
  * 目标自身（存在时）或它最近一个**已存在的祖先**的真实路径；一路到盘根都解析不出来 → null。
  * 用途是复核符号链接：`<root>/link/file.txt` 里 link 若是指向别处的 junction，
  * 单看字符串它「在 root 里」，realpath 之后就露馅了。
+ * 导出给 plugin-facilities / plugins.ts 的写类操作复用（同一套越界复核语义）。
  */
-function realPathOfNearest(abs) {
+export function realPathOfNearest(abs) {
     let probe = abs;
     for (let i = 0; i < MAX_ANCESTOR_HOPS; i++) {
         try {
@@ -111,6 +113,28 @@ function realPathOfNearest(abs) {
 function toSlash(p) {
     return p.split(sep).join("/");
 }
+/**
+ * 递归列目录，返回树内全部符号链接 / junction 的绝对路径。
+ * win32 上 Dirent.isSymbolicLink() 同样覆盖 junction（lstat 语义）；只读不跟随。
+ * 目录读不了（权限/竞态删除）返回空数组 —— 兜底交给写入前的逐目标 realpath 复核。
+ */
+async function findSymlinks(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await fspReaddir(dir, { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (!e.isSymbolicLink())
+            continue;
+        const parent = e.parentPath ?? dir;
+        out.push(join(parent, e.name));
+    }
+    return out;
+}
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -191,26 +215,62 @@ async function runGit(bin, args, opts) {
         child.stdout?.on("data", (chunk) => stdout.push(chunk));
         child.stderr?.on("data", (chunk) => stderr.push(chunk));
         let timedOut = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            if (typeof child.pid === "number" && child.pid > 0)
-                killPidTree(child.pid);
-            else
-                child.kill("SIGKILL");
-        }, opts.timeoutMs);
+        let settled = false;
+        let graceTimer;
         let spawnError;
-        child.on("error", (err) => {
-            spawnError = `无法启动 git（${bin}）：${errMessage(err)}`;
-        });
-        child.on("close", (code) => {
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
+            if (graceTimer)
+                clearTimeout(graceTimer);
             stdout.flush();
             stderr.flush();
             let tail = stderrLines.join("\n");
             if (tail.length > MAX_STDERR_TAIL)
                 tail = `…${tail.slice(-MAX_STDERR_TAIL)}`;
             settle({ code: code ?? -1, timedOut, stderrTail: tail, ...(spawnError ? { spawnError } : {}) });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (typeof child.pid === "number" && child.pid > 0) {
+                void killPidTree(child.pid);
+                // On Windows taskkill is asynchronous and a child may not emit close
+                // promptly. Directly kill the git process too, then force settlement
+                // after a short grace period so callers never hang on close.
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+            else {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+            graceTimer = setTimeout(() => {
+                try {
+                    child.stdout?.destroy();
+                    child.stderr?.destroy();
+                }
+                catch {
+                    /* already closed */
+                }
+                finish(-1);
+            }, 500);
+        }, opts.timeoutMs);
+        child.on("error", (err) => {
+            spawnError = `无法启动 git（${bin}）：${errMessage(err)}`;
+            if (timedOut)
+                finish(-1);
         });
+        child.on("close", (code) => finish(code));
     });
 }
 /**
@@ -358,6 +418,28 @@ export async function createProject(spec, deps = {}) {
         return undefined;
     };
     try {
+        // 本轮真正 clone 出的目录（根目录本身除外 —— 它是授权目录，绝不清理）与
+        // 已写入的文件，供「clone 后置复核命中」时回滚，不把半个带毒仓库留在盘上。
+        const clonedThisRun = plannedRepos.filter((r) => !samePath(r.dest, root)).map((r) => r.dest);
+        const writtenThisRun = [];
+        const cleanupThisRun = () => {
+            for (const f of writtenThisRun) {
+                try {
+                    rmSync(f, { force: true });
+                }
+                catch {
+                    /* 清理尽力而为 */
+                }
+            }
+            for (const d of clonedThisRun) {
+                try {
+                    rmSync(d, { recursive: true, force: true });
+                }
+                catch {
+                    /* 清理尽力而为 */
+                }
+            }
+        };
         for (const r of plannedRepos) {
             const atRoot = samePath(r.dest, root);
             // 根目录已存在是常态（它就是那个已存在的授权目录），既不 rm 也不 mkdir ——
@@ -384,10 +466,32 @@ export async function createProject(spec, deps = {}) {
             if (why)
                 return fail(`${why}${res.stderrTail === "" ? "" : `：${res.stderrTail}`}`);
         }
+        // ——— ⑥ clone 后置复核（写文件前）：前置校验（③④）都在 clone 之前，而恶意
+        //     仓库可以在 clone 时落地指向 root 之外的符号链接，随后的文件写入就会跟着
+        //     链接跑出授权目录（「先 clone 后校验」的逃逸窗口）。两道防线：
+        //     a. 扫描 clone 出的目录树，出现任何符号链接即视为恶意仓库整体拒绝
+        //        （clone --depth 1 不跑包管理器，正常仓库极少提交 symlink，宁可误杀）；
+        //     b. 每个写入目标写前再做一次 realPathOfNearest 复核（覆盖 a 与写盘之间的窗口）。
+        //     任一命中：清理本轮 clone 的目录（rmSync 不跟随符号链接，安全）与已写文件。
+        for (const dest of clonedThisRun) {
+            const offenders = await findSymlinks(dest);
+            if (offenders.length > 0) {
+                cleanupThisRun();
+                return fail(`仓库包含符号链接（视为恶意仓库拒绝），例如：${toSlash(relative(root, offenders[0]))}`);
+            }
+        }
         for (const f of plannedFiles) {
+            // 写前复核目标仍解析在 rootReal 内：前置校验时它还不存在（最近祖先在 root 内），
+            // clone 之后可能被仓库塞进来的符号链接顶掉。
+            const real = realPathOfNearest(f.abs);
+            if (real === null || !isInsideRoot(rootReal, real)) {
+                cleanupThisRun();
+                return fail(`files 路径越界（clone 后复核：符号链接指向 dir 之外）：${f.rel}`);
+            }
             emit(`write ${f.rel}`);
             mkdirSync(dirname(f.abs), { recursive: true });
             writeFileSync(f.abs, f.content, "utf8");
+            writtenThisRun.push(f.abs);
         }
         if (spec?.gitInit === true) {
             emit("git init");

package/dist/server/plugin-tool-guard.js

@@ -0,0 +1,120 @@
+/**
+ * 插件工具拦截扩展点：类型化 Decision（DSH 对照 P1-5）。
+ *
+ * 只做 **pre + post 两阶段**、只覆盖**已接管**的工具（`bash` / `read`），
+ * 不照搬 DSH 的五阶段 —— 工具执行在 pi SDK 内部，只有这两处有插手面
+ * （`agent-service.ts` 的 customTools 覆盖 + 终端接管 bash）。
+ *
+ * - pre：`allow` 放行 / `deny` 拒绝（带原因）/ `ask` 需要用户确认。
+ *   首个非 allow 胜出；handler 抛错或超时一律降级为弃权（allow），
+ *   与 DSH chain 的「select 抛错降级为弃权」同源。
+ * - post：变换内容（脱敏/改写）/ 附加 `additionalContext`（自动补上下文）。
+ *   逐个顺序合并，抛错的那个被跳过。
+ * - `ask` 的完整审批 UI（弹框等人点）本次不做：按阻断处理，原因里注明
+ *   待确认，模型能看到、人能在诊断里看到；以后要做审批流只改
+ *   `plugins.ts#evaluateToolPre` 的 ask 分支，不用动类型。
+ */
+/** 单个守卫的最长等待：超时按弃权处理（不能让一个插件挂住整轮工具调用）。 */
+export const GUARD_HANDLER_TIMEOUT_MS = 5000;
+/** 附加上下文的上限（字符）：插件补的上下文不能无节制进 LLM 上下文。 */
+export const GUARD_CONTEXT_CAP = 2000;
+/** 归一 pre 返回：void/null/垃圾一律按 allow（弃权）；只认三决策的形状。 */
+export function normalizePreDecision(raw) {
+    if (!raw || typeof raw !== "object")
+        return { decision: "allow" };
+    const d = raw.decision;
+    if (d === "deny" || d === "ask") {
+        const o = raw;
+        const reason = typeof o.reason === "string" ? o.reason.slice(0, 500) : undefined;
+        const reasonEn = typeof o.reasonEn === "string" ? o.reasonEn.slice(0, 500) : undefined;
+        return d === "deny" ? { decision: "deny", reason, reasonEn } : { decision: "ask", reason, reasonEn };
+    }
+    return { decision: "allow" };
+}
+/** 是否阻断执行（deny/ask 都算阻断；ask 只是原因不同）。 */
+export function isBlockingDecision(d) {
+    return d.decision === "deny" || d.decision === "ask";
+}
+function pickText(zh, en, fbZh, fbEn, lang) {
+    if (lang === "zh")
+        return zh?.trim() ? zh.trim() : fbZh;
+    return en?.trim() ? en.trim() : fbEn;
+}
+/** 阻断时给模型看的一句话（ask 注明待确认 + 按拒绝处理）。 */
+export function denialText(d, pluginId, lang) {
+    if (d.decision === "ask") {
+        return pickText(d.reason, d.reasonEn, `插件 ${pluginId} 要求先确认再执行，已按拒绝处理（审批 UI 尚未实现，ask 暂按 deny 执行）`, `Plugin ${pluginId} asked for confirmation before execution; treated as denied (approval UI not implemented yet, ask behaves as deny)`, lang);
+    }
+    return pickText(d.decision === "deny" ? d.reason : undefined, d.decision === "deny" ? d.reasonEn : undefined, `插件 ${pluginId} 拒绝了本次工具调用`, `Plugin ${pluginId} denied this tool call`, lang);
+}
+/** 归一 post 返回：void/null/垃圾 → undefined（无编辑）；content 坏形状时只保留上下文。 */
+export function normalizePostEdit(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const o = raw;
+    let content;
+    if (Array.isArray(o.content)) {
+        const rows = o.content.filter((p) => Boolean(p) && typeof p === "object" && typeof p.type === "string");
+        if (rows.length > 0 && rows.length === o.content.length) {
+            content = rows.map((p) => ({
+                type: p.type.slice(0, 32),
+                ...(typeof p.text === "string" ? { text: p.text } : {}),
+            }));
+        }
+        else if (rows.length > 0) {
+            content = rows.map((p) => ({
+                type: p.type.slice(0, 32),
+                ...(typeof p.text === "string" ? { text: p.text } : {}),
+            }));
+        }
+    }
+    const additionalContext = typeof o.additionalContext === "string" && o.additionalContext.trim()
+        ? o.additionalContext.slice(0, GUARD_CONTEXT_CAP)
+        : undefined;
+    const additionalContextEn = typeof o.additionalContextEn === "string" && o.additionalContextEn.trim()
+        ? o.additionalContextEn.slice(0, GUARD_CONTEXT_CAP)
+        : undefined;
+    if (!content && !additionalContext && !additionalContextEn)
+        return undefined;
+    return {
+        ...(content ? { content } : {}),
+        ...(additionalContext ? { additionalContext } : {}),
+        ...(additionalContextEn ? { additionalContextEn } : {}),
+    };
+}
+/** 把一次 post 编辑合进执行结果（返回新对象，不改原结果）。 */
+export function applyPostEdit(result, edit, lang) {
+    const ctx = lang === "zh"
+        ? edit.additionalContext?.trim()
+        : (edit.additionalContextEn?.trim() ?? edit.additionalContext?.trim());
+    const tail = ctx ? [{ type: "text", text: ctx }] : [];
+    if (edit.content) {
+        return { ...result, content: [...edit.content, ...tail] };
+    }
+    if (!tail.length)
+        return result;
+    return { ...result, content: [...(result.content ?? []), ...tail] };
+}
+/** 带超时的守卫调用：超时按弃权（pre→allow，post→undefined），调用方再归一。 */
+export function withGuardTimeout(p, ms = GUARD_HANDLER_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+    });
+    return Promise.race([p, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/** 封存请求参数：浅冻一层（插件拿到的是快照，改了也不影响执行）。 */
+export function freezeParams(params) {
+    if (params && typeof params === "object" && !Object.isFrozen(params)) {
+        try {
+            Object.freeze(params);
+        }
+        catch {
+            // 冻不住（如 sealed 变体）就原样给：决策只读快照，不依赖冻结成功。
+        }
+    }
+    return params;
+}