pi-web-ui 0.94.1 → 0.96.0

package/dist/server/plugin-api-catalog.js

@@ -0,0 +1,296 @@
+export const PLUGIN_API_CATALOG_VERSION = 1;
+/** 每个 slot 的 manifest 最小例子（与 parseUiContributions 同口径，别名已展开写法也收）。 */
+export const SLOT_EXAMPLES = {
+    "topbar.primary": `{ "topbar": [{ "id": "inbox", "label": "收件箱", "kind": "action", "action": "my:open" }] }`,
+    "topbar.overflow": `{ "topbar.more": [{ "id": "about", "label": "关于", "kind": "action", "action": "my:about" }] }`,
+    bottombar: `{ "ui": { "bottombar": [{ "id": "st", "label": "状态", "kind": "action", "action": "my:st" }] } }`,
+    "composer.leading": `{ "ui": { "composer.leading": [{ "id": "m", "label": "＋", "kind": "action", "action": "my:m" }] } }`,
+    "composer.actions": `{ "composer": [{ "id": "pick", "label": "拾取", "kind": "action", "action": "my:pick" }] }`,
+    "message.actions": `{ "message": [{ "id": "send", "label": "转存", "kind": "action", "action": "my:send" }] }`,
+    "rightpanel.tabs": `{ "rightpanel": [{ "id": "mail", "label": "邮件", "kind": "view" }] }`,
+    "contextmenu.topbar": `{ "ui": { "contextmenu.topbar": [{ "id": "m", "label": "顶栏菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.message": `{ "ui": { "contextmenu.message": [{ "id": "m", "label": "消息菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.session": `{ "ui": { "contextmenu.session": [{ "id": "m", "label": "会话菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.file": `{ "contextmenu.file": [{ "id": "mail", "label": "发到邮箱", "kind": "action", "action": "my:send" }] }`,
+    "contextmenu.toolcall": `{ "ui": { "contextmenu.toolcall": [{ "id": "m", "label": "工具菜单", "kind": "action", "action": "my:m" }] } }`,
+    "settings.pages": `{ "settings": [{ "id": "conf", "label": "邮箱设置", "kind": "page" }] }`,
+    "leftpanel.sessions": `{ "ui": { "leftpanel.sessions": [{ "id": "m", "label": "会话区", "kind": "action", "action": "my:m" }] } }`,
+    "chat.header": `{ "ui": { "chat.header": [{ "id": "m", "label": "会话题头", "kind": "action", "action": "my:m" }] } }`,
+    "chat.empty": `{ "ui": { "chat.empty": [{ "id": "m", "label": "空态", "kind": "action", "action": "my:m" }] } }`,
+    "file.preview.toolbar": `{ "ui": { "file.preview.toolbar": [{ "id": "m", "label": "预览工具", "kind": "action", "action": "my:m" }] } }`,
+    "terminal.toolbar": `{ "ui": { "terminal.toolbar": [{ "id": "m", "label": "终端工具", "kind": "action", "action": "my:m" }] } }`,
+    "scm.toolbar": `{ "ui": { "scm.toolbar": [{ "id": "m", "label": "SCM 工具", "kind": "action", "action": "my:m" }] } }`,
+    "goalbar.actions": `{ "ui": { "goalbar.actions": [{ "id": "m", "label": "目标条", "kind": "action", "action": "my:m" }] } }`,
+    "notice.actions": `{ "ui": { "notice.actions": [{ "id": "m", "label": "通知动作", "kind": "action", "action": "my:m" }] } }`,
+    "modal.dialog": `{ "modal": [{ "id": "m", "label": "弹窗", "kind": "action", "action": "my:m" }] }`,
+};
+/** 宿主方法表（与 server/plugins.ts#PluginHost 同语义的精简版：只收发现用的注册/调用面）。
+ *  needs="-" = 观察/基础设施类（无需能力声明）；其余走 can() 门控。 */
+export const HOST_METHODS = [
+    {
+        name: "ui.register",
+        needs: "ui",
+        summary: "运行时注册 UI 条目（与 manifest 同口径，别名映射+枚举校验）",
+        example: `host.ui.register({ slot: "topbar.primary", id: "btn", label: "按钮" })`,
+    },
+    {
+        name: "ui.update",
+        needs: "ui",
+        summary: "按 id 改已存在条目（label/badge/checked/value/progress）",
+        example: `host.ui.update("btn", { badge: "3" })`,
+    },
+    {
+        name: "ui.remove",
+        needs: "ui",
+        summary: "移除条目（manifest 声明的也能压住，直到 reload）",
+        example: `host.ui.remove("btn")`,
+    },
+    {
+        name: "ui.arrange",
+        needs: "ui",
+        summary: "整理任何条目（含 host:* 内置）：hide/order/group/label",
+        example: `host.ui.arrange([{ id: "host:tasks", hide: true }])`,
+    },
+    {
+        name: "ui.list",
+        needs: "ui",
+        summary: "自查本插件的 items + arrange（调别的插件看不见）",
+        example: `host.ui.list()`,
+    },
+    {
+        name: "onUiAction",
+        needs: "ui",
+        summary: "订阅条目点击（action 名 → 回调，client bundle 侧）",
+        example: `__piWebUiHost.onUiAction("my:open", () => {})`,
+    },
+    {
+        name: "registerAgentTool",
+        needs: "tools",
+        summary: "给 AI 注册工具（插件给模型加能力，与 AI 写插件方向相反）",
+        example: `host.registerAgentTool({ name: "mail_list", description: "…", execute: async () => ({}) })`,
+    },
+    {
+        name: "onToolPre",
+        needs: "tools",
+        summary: "工具 pre 拦截（仅 bash/read）：allow/deny/ask，首个阻断胜出",
+        example: `host.onToolPre((req) => req.params?.command?.includes("rm -rf") ? { decision: "deny" } : undefined)`,
+    },
+    {
+        name: "onToolPost",
+        needs: "tools",
+        summary: "工具 post 编辑（仅 bash/read）：换 content / 补 additionalContext",
+        example: `host.onToolPost(({ result }) => ({ content: result.content }))`,
+    },
+    {
+        name: "onToolEvent",
+        needs: "-",
+        summary: "订阅工具执行事件（start/end 成对，只观测）",
+        example: `host.onToolEvent((ev) => {})`,
+    },
+    {
+        name: "bash",
+        needs: "tools",
+        summary: "受限 shell（无 piped shell，按词切分；cwd 锁工作区内，默认 60s 超时）",
+        example: `await host.bash("ls", { timeoutMs: 10000 })`,
+    },
+    {
+        name: "registerCommand",
+        needs: "-",
+        summary: "注册斜杠命令（/name 选择器 + prompt 拦截执行）",
+        example: `host.registerCommand({ name: "deploy", description: "部署", run: (args) => {} })`,
+    },
+    {
+        name: "route",
+        needs: "http",
+        summary: "挂载 HTTP 路由（/plugins-api/<id><path>）",
+        example: `host.route("GET", "/inbox", (req, res) => res.json([]))`,
+    },
+    {
+        name: "registerProxy",
+        needs: "http",
+        summary: "反向代理前缀（透传到 127.0.0.1:port，防 SSRF 锁回环）",
+        example: `host.registerProxy("/app", 3000)`,
+    },
+    {
+        name: "chat",
+        needs: "chat",
+        summary: "无头调用：把外部通道文本投给 agent（fire-and-forget）",
+        example: `await host.chat({ text: "hi" })`,
+    },
+    {
+        name: "chatWait",
+        needs: "chat",
+        summary: "等无头调用的 run_end（默认 120s，上下钳制）",
+        example: `await host.chatWait({ conversationId })`,
+    },
+    {
+        name: "llm.complete",
+        needs: "llm",
+        summary: "孤立无工具一次性补全（花用户模型额度）",
+        example: `await host.llm.complete({ prompt: "…" })`,
+    },
+    {
+        name: "requestPermission",
+        needs: "-",
+        summary: "申请能力授权（net 主机 / llm 模型作用域，用户确认）",
+        example: `await host.requestPermission({ family: "net", hosts: ["api.example.com"] })`,
+    },
+    {
+        name: "fs",
+        needs: "fs",
+        summary: "工作区文件（list/read/readText/write/remove…，锚定活 cwd，越界拒绝）",
+        example: `await host.fs.readText("notes/todo.md")`,
+    },
+    {
+        name: "fs.requestAccess",
+        needs: "fs",
+        summary: "申请工作区外目录授权（浏览器确认框，remember 记盘）",
+        example: `await host.fs.requestAccess("/data")`,
+    },
+    {
+        name: "project.create",
+        needs: "fs",
+        summary: "在已授权目录组装项目（mkdir/clone/写文件/git init）",
+        example: `await host.project.create({ dir: "/data/app", files: {} })`,
+    },
+    {
+        name: "schedule",
+        needs: "-",
+        summary: "定时任务（cron/延迟，持久化可重启不丢，远期分片防溢出）",
+        example: `host.schedule("0 9 * * *", () => {})`,
+    },
+    {
+        name: "registerBackgroundTask",
+        needs: "-",
+        summary: "常驻后台任务（并入后台任务面板，随反激活移除）",
+        example: `host.registerBackgroundTask({ id: "svc", label: "服务" })`,
+    },
+    {
+        name: "onRunEvent",
+        needs: "-",
+        summary: "订阅运行轨迹（run/message/tool…，时间线聚合用）",
+        example: `host.onRunEvent((ev) => {})`,
+    },
+    {
+        name: "getActiveConversation",
+        needs: "-",
+        summary: "读当前打开对话快照（只读引用，广播前抽摘要）",
+        example: `host.getActiveConversation()`,
+    },
+    {
+        name: "onConversationChanged",
+        needs: "-",
+        summary: "订阅切对话（轨迹插件重拉时间线）",
+        example: `host.onConversationChanged(() => {})`,
+    },
+    {
+        name: "storage",
+        needs: "-",
+        summary: "插件私有 KV（storage.json，原子写，卸载即删）",
+        example: `host.storage.get("k")`,
+    },
+    { name: "secrets", needs: "-", summary: "加密 secrets（明文永不落盘/下发）", example: `host.secrets.get("token")` },
+    {
+        name: "ensureDeps",
+        needs: "-",
+        summary: "依赖自动补装（单飞，npm 包）",
+        example: `await host.ensureDeps(["dayjs"])`,
+    },
+    {
+        name: "getSettings",
+        needs: "-",
+        summary: "读声明式设置值（manifest.settings 字段）",
+        example: `host.getSettings()`,
+    },
+    {
+        name: "onSettingsChanged",
+        needs: "-",
+        summary: "订阅设置保存（⚙ 面板保存后触发）",
+        example: `host.onSettingsChanged((v) => {})`,
+    },
+    { name: "onCwdChange", needs: "-", summary: "订阅工作区切换", example: `host.onCwdChange((cwd) => {})` },
+    {
+        name: "onAttach",
+        needs: "-",
+        summary: "订阅浏览器接入（主动推完整状态，服务端是唯一事实源）",
+        example: `host.onAttach((clientId) => {})`,
+    },
+    {
+        name: "broadcast",
+        needs: "-",
+        summary: "向所有浏览器广播本插件消息",
+        example: `host.broadcast({ kind: "state" })`,
+    },
+    { name: "notify", needs: "-", summary: "发系统通知条（notice toast）", example: `host.notify("info", "完成")` },
+    {
+        name: "effect",
+        needs: "-",
+        summary: "自建副作用挂进 effect 栈（反激活逆序回卷）",
+        example: `host.effect("timer", () => clearInterval(t))`,
+    },
+    {
+        name: "events.emit/on",
+        needs: "-",
+        summary: "插件间事件总线（topic 建议 <id>: 前缀，发送方不可伪造）",
+        example: `host.events.on("notes:changed", () => {})`,
+    },
+    { name: "models.list", needs: "-", summary: "列出已配置鉴权的模型（provider/id）", example: `host.models.list()` },
+    {
+        name: "scm",
+        needs: "-",
+        summary: "只读 git 查询（status/branches/history，不经过 shell）",
+        example: `await host.scm.status()`,
+    },
+    {
+        name: "net.fetch",
+        needs: "net",
+        summary: "出站网络（白名单命中才放行，失败回 {ok:false} 不抛）",
+        example: `await host.net.fetch("https://api.example.com/x")`,
+    },
+    {
+        name: "conversations",
+        needs: "-",
+        summary: "会话目录（list/get/search，只读组装+定向投递）",
+        example: `await host.conversations.list()`,
+    },
+    {
+        name: "prompt",
+        needs: "-",
+        summary: "向指定对话发一条用户消息（无注入回 ok:false）",
+        example: `await host.prompt(convId, { text: "hi" })`,
+    },
+    { name: "steer", needs: "-", summary: "插队指定对话的当前运行", example: `await host.steer(convId, "换方向")` },
+    { name: "abortRun", needs: "-", summary: "中止指定对话的运行", example: `await host.abortRun(convId)` },
+];
+/** 装配目录：静态表（本模块）+ 动态占用（调用方现算）。调用方保证入参即真相（别名/枚举与解析层同源）。 */
+export function buildPluginApiCatalog(opts) {
+    const aliasByTarget = new Map();
+    for (const [alias, target] of Object.entries(opts.aliases)) {
+        const list = aliasByTarget.get(target) ?? [];
+        list.push(alias);
+        aliasByTarget.set(target, list);
+    }
+    const slots = [...opts.slots].sort().map((slot) => {
+        const example = SLOT_EXAMPLES[slot] ??
+            `{ "ui": { "${slot}": [{ "id": "m", "label": "条目", "kind": "action", "action": "my:m" }] } }`;
+        return {
+            slot,
+            aliases: [...(aliasByTarget.get(slot) ?? [])].sort(),
+            kinds: [...opts.kinds].sort(),
+            occupants: [...opts.occupantsOf(slot)].sort((a, b) => (a.pluginId < b.pluginId ? -1 : 1)),
+            replaceRisk: "插件 arrange 可改任何条目（含 host:* 内置），用户偏好最后说话（布局页可恢复）",
+            example,
+        };
+    });
+    return {
+        version: PLUGIN_API_CATALOG_VERSION,
+        slots,
+        agentTools: opts.agentTools.map((t) => ({
+            name: t.name,
+            group: t.group,
+            defaultOn: t.defaultOn,
+            dshVisible: t.dshVisible,
+        })),
+        hostMethods: HOST_METHODS.map((m) => ({ ...m })),
+    };
+}

package/dist/server/plugin-catalog-sync.js

@@ -16,14 +16,22 @@
  *      不因为一条坏条目就停掉整批；
  *   3. 回执是结构化的（ok/error/entries/installed），不靠 DOM 事件或控制台文字。
  */
-import { readFileSync, existsSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { pick } from "./i18n.js";
 import { normalizeSyncPayload, writeCustomCatalog } from "./plugin-catalog.js";
+import { workspacePath } from "./files-service.js";
 /**
- * 读同步文档：`http(s)://` 走网络，其余当本地文件路径（须为绝对路径）。
- * 只读文本，JSON 解析交给调用方（解析失败也走同一条「不写盘」的路径）。
+ * 读同步文档：`http(s)://` 走网络，其余当本地文件路径 —— **只允许工作区内的路径**
+ * （复用 files-service 的 workspacePath 校验；任意绝对路径可读会成为「文件存在 /
+ * 可读性」探测 oracle）。只读文本；本地来源的读失败与过大统一进 `localDocFailed`
+ * 这一条错误（调用方把解析失败也并进来），不区分「读不到 / 解析失败」两种失败。
  */
+function localDocFailed(l) {
+    return {
+        error: pick(l, "目录文档无效或不可读（仅支持 http(s) URL 或工作区内的 JSON 文件）", "Invalid or unreadable catalog document (http(s) URL or an in-workspace JSON file only)", "plugincatalog.sync.doc.invalid"),
+    };
+}
 async function readDocument(source, deps, lang) {
     const l = lang();
     const maxBytes = Math.max(1024, Number(deps.maxBytes ?? 1024 * 1024));
@@ -51,24 +59,21 @@ async function readDocument(source, deps, lang) {
             };
         return { text };
     }
-    const p = source.trim();
-    if (!isAbsolute(p))
-        return {
-            error: pick(l, "来源需为 http(s) URL 或本地文件的绝对路径", "Source must be an http(s) URL or an absolute local file path", "plugincatalog.sync.source.invalid"),
-        };
+    // 本地来源：必须在工作区内（workspacePath 对相对/绝对路径统一做越界判定）。
+    // 越界 / 读不到 / 过大统一返回同一条错误，不给调用方区分的余地。
+    const wp = deps.workspaceRoot ? workspacePath(deps.workspaceRoot, source.trim()) : null;
+    if (!wp)
+        return localDocFailed(l);
+    let text;
     try {
-        const text = readFileSync(p, "utf8");
-        if (text.length > maxBytes)
-            return {
-                error: pick(l, `目录文档过大（> ${Math.round(maxBytes / 1024)} KB）`, `Catalog document too large (> ${Math.round(maxBytes / 1024)} KB)`, "plugincatalog.sync.too.large", { kb: String(Math.round(maxBytes / 1024)) }),
-            };
-        return { text };
+        text = readFileSync(wp.abs, "utf8");
     }
-    catch (err) {
-        return {
-            error: pick(l, `读取目录文件失败：${err?.message ?? err}`, `Failed to read the catalog file: ${err?.message ?? err}`, "plugincatalog.sync.read.failed", { reason: String(err?.message ?? err) }),
-        };
+    catch {
+        return localDocFailed(l);
     }
+    if (text.length > maxBytes)
+        return localDocFailed(l);
+    return { text };
 }
 /**
  * 同步一次目录：读 → 校验 → 原子写 → 可选安装 → 重载 + 重推。
@@ -86,11 +91,16 @@ export async function syncPluginCatalog(source, opts, deps) {
     const doc = await readDocument(src, deps, lang);
     if ("error" in doc)
         return { ok: false, error: doc.error };
+    const isLocalSource = !/^https?:\/\//i.test(src);
     let raw;
     try {
         raw = JSON.parse(doc.text);
     }
     catch (err) {
+        // 本地来源不区分「读得到但解析失败 / 读不到 / 越界」——组合起来就是文件探测
+        // oracle；http(s) 来源与本地文件无关，保留解析细节方便排障。
+        if (isLocalSource)
+            return { ok: false, error: localDocFailed(lang()).error };
         return {
             ok: false,
             error: pick(l, `目录 JSON 解析失败：${err?.message ?? err}`, `Catalog JSON is not valid JSON: ${err?.message ?? err}`, "plugincatalog.sync.parse.failed", { reason: String(err?.message ?? err) }),
@@ -104,6 +114,13 @@ export async function syncPluginCatalog(source, opts, deps) {
     await deps.afterWrite();
     let installed;
     if (opts.install === true && payload.entries.length) {
+        // 安装确认门（P0）：安装/更新插件是高风险动作，必须先经用户确认。第三方页面
+        // 脚本可以直发 plugin_catalog_sync，没有这道门就能静默装任意插件。拒绝 /
+        // 超时 / 无确认设施（无头 DSH）一律只保留目录更新，不安装。
+        const items = payload.entries.map((e) => ({ id: e.id, source: e.source }));
+        const confirmed = deps.confirmInstall ? await deps.confirmInstall(items) : false;
+        if (!confirmed)
+            return { ok: true, installRefused: true, installed: [] };
         installed = [];
         for (const e of payload.entries) {
             const action = existsSync(join(deps.pluginsDir, e.id)) ? "update" : "install";

package/dist/server/plugin-catalog.js

@@ -92,7 +92,11 @@ function toEntry(raw, builtin) {
         ...(homepage ? { homepage } : {}),
     };
 }
-/** 读合并后的目录：builtin 在前，custom 在后（同 id 时 custom 覆盖 builtin）。 */
+/** 读合并后的目录：builtin 在前，custom 在后（同 id 时 custom 覆盖 builtin）。
+ *  custom 覆盖 builtin 时强制打 `overridesBuiltin: true` 标记（builtin 同时为
+ *  false）：显示字段（name/icon/description）来自用户可写来源，可能仿冒官方条目，
+ *  前端据此把它标识为「自定义覆盖」。source 始终保留真实（custom）安装来源，
+ *  不允许伪装成官方来源。 */
 export function readCatalog(builtinPath, customPath) {
     const out = [];
     const seen = new Set();
@@ -117,10 +121,13 @@ export function readCatalog(builtinPath, customPath) {
         if (!e)
             continue;
         const idx = out.findIndex((x) => x.id === e.id);
-        if (idx >= 0)
-            out[idx] = e;
-        else
+        if (idx >= 0) {
+            // 覆盖了同名 builtin 条目：强制带标识（不信任 custom 文件里的任何自标字段）。
+            out[idx] = { ...e, builtin: false, overridesBuiltin: true };
+        }
+        else {
             out.push(e);
+        }
         seen.add(e.id);
     }
     return out;

package/dist/server/plugin-facilities.js

@@ -21,6 +21,9 @@ import { readFile as fspReadFile, readdir as fspReaddir, rm as fspRm, mkdir as f
 import { dirname, join, relative, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
+// 与 plugin-project 共用同一套 realpath 越界复核（isInsideRoot / realPathOfNearest），
+// 避免「同一个安全语义、两份实现」漂移。
+import { isInsideRoot, realPathOfNearest } from "./plugin-project.js";
 /** tmp+rename 原子写（错误由调用方隔离——插件设施的 IO 一律尽力而为）。 */
 function atomicWrite(file, data) {
     mkdirSync(dirname(file), { recursive: true });
@@ -29,6 +32,43 @@ function atomicWrite(file, data) {
     renameSync(tmp, file);
 }
 // ---------------------------------------------------------------------------
+// storage.json 的进程内「读-改-写」互斥
+// ---------------------------------------------------------------------------
+/** 按文件路径的 RMW 互斥链（key = resolve 后的绝对路径）。 */
+const rmwChains = new Map();
+/**
+ * 进程内「读-改-写」互斥（按文件路径的 promise 链锁）。
+ *
+ * storage.json 有两个读-改-写者：PluginStorage（插件 KV）与宿主 settings 面板的
+ * saveSettingsValues（plugins.ts，直写同一文件的 settings 键）。两段 RMW 必须互斥
+ * —— 现在两段关键区都是同步的（单线程下本就不会交错），但只要将来任何一处把
+ * 「读」和「写」之间插进 await，就会退回「旧快照整份回写、抹掉对方刚写的键」的
+ * 丢更新。两处统一收进这把锁：
+ *  - 空链 + 同步 fn：原地直跑（不引入微任务延迟，set() 后同步 get() 立即可见，
+ *    语义与未加锁完全一致）；fn 若返回 promise（异步写者）则占住链尾，后续排队；
+ *  - 链忙：挂到链尾串行（前一个成功/失败都放行下一个）。
+ * Map 不主动清理：键数量 = 有 storage.json 的插件数，天然有界。
+ */
+export function withFileRmwLock(file, fn) {
+    const key = resolve(file);
+    const prev = rmwChains.get(key);
+    if (prev) {
+        const queued = prev.then(fn, fn);
+        rmwChains.set(key, queued.then(() => undefined, () => undefined));
+        return queued;
+    }
+    const result = fn();
+    if (result instanceof Promise) {
+        const tail = result.then(() => undefined, () => undefined);
+        rmwChains.set(key, tail);
+        void tail.then(() => {
+            if (rmwChains.get(key) === tail)
+                rmwChains.delete(key);
+        });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
 // storage
 // ---------------------------------------------------------------------------
 /** 每插件的 JSON 文件 KV。所有方法同步（数据量小，避免并发写乱序）。
@@ -88,29 +128,37 @@ export class PluginStorage {
     set(key, value) {
         if (!key)
             throw new Error("storage.set: key 不能为空");
-        // 写前必重读磁盘：宿主 settings 面板的 saveSettingsValues 直写同一文件的
-        // settings 键（不经过本缓存），拿旧快照整份回写会把它抹掉。写是低频路径，
-        // 重读的代价可忽略；mtime 粒度即使同毫秒也抹不掉（这里是无条件重读）。
-        const store = this.readFromDisk();
-        store[key] = value;
-        try {
-            atomicWrite(this.file, JSON.stringify(store));
-        }
-        catch (err) {
-            console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
-        }
+        // 与宿主 saveSettingsValues 同一把按文件路径的 RMW 锁（见 withFileRmwLock）：
+        // 两段「读-改-写」互斥，谁也不会拿旧快照抹掉对方刚写的键。当前关键区是同步的
+        // （空链直跑），set() 后同步 get() 立即可见，行为与未加锁一致。
+        void withFileRmwLock(this.file, () => {
+            // 写前必重读磁盘：宿主 settings 面板的 saveSettingsValues 直写同一文件的
+            // settings 键（不经过本缓存），拿旧快照整份回写会把它抹掉。写是低频路径，
+            // 重读的代价可忽略；mtime 粒度即使同毫秒也抹不掉（这里是无条件重读）。
+            const store = this.readFromDisk();
+            store[key] = value;
+            try {
+                atomicWrite(this.file, JSON.stringify(store));
+            }
+            catch (err) {
+                console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
+            }
+        });
     }
     delete(key) {
-        const store = this.readFromDisk(); // 同 set：写前重读，不拿旧快照回写
-        if (!(key in store))
-            return;
-        delete store[key];
-        try {
-            atomicWrite(this.file, JSON.stringify(store));
-        }
-        catch (err) {
-            console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
-        }
+        // 同 set：写前重读 + RMW 锁，不拿旧快照回写。
+        void withFileRmwLock(this.file, () => {
+            const store = this.readFromDisk();
+            if (!(key in store))
+                return;
+            delete store[key];
+            try {
+                atomicWrite(this.file, JSON.stringify(store));
+            }
+            catch (err) {
+                console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
+            }
+        });
     }
 }
 function seal(key, plaintext) {
@@ -362,6 +410,24 @@ export class WorkspaceFS {
         }
         return target;
     }
+    /**
+     * 写类操作（write/append/mkdir/remove）的 realpath 复核：abs() 是纯字符串
+     * 比较，工作区里的符号链接/junction 能把写入（或递归删除）引到工作区之外。
+     * 取目标最近已存在祖先的 realpath，复核它仍在「活根」的 realpath 内。
+     * 读/list/stat/glob 保持字符串校验（高频路径；读不存在「把内容写到别处」
+     * 的风险，性能优先 —— 有意的取舍）。
+     */
+    assertRealInsideRoot(rel) {
+        const target = this.abs(rel); // 字符串越界先拒绝（错误文案不变）
+        const targetReal = realPathOfNearest(target);
+        if (!targetReal)
+            throw new Error(`路径越界：无法解析真实路径 ${String(rel)}`);
+        const rootDir = resolve(this.root());
+        const rootReal = realPathOfNearest(rootDir) ?? rootDir;
+        if (!isInsideRoot(rootReal, targetReal)) {
+            throw new Error(`路径越界（符号链接指向工作区之外）：${String(rel)}`);
+        }
+    }
     /** 单层目录列表（浅层；深度遍历请插件自行递归）。 */
     async list(relDir = "") {
         try {
@@ -386,18 +452,21 @@ export class WorkspaceFS {
     }
     /** 写文件（自动补父目录；注意相对路径锚定当前项目——切换 cwd 后写进新项目）。 */
     async write(relPath, data) {
+        this.assertRealInsideRoot(relPath);
         const target = this.abs(relPath);
         await fspMkdir(dirname(target), { recursive: true });
         await fspWriteFile(target, data);
     }
     /** 追加写文件（日志/队列场景；父目录自动补；越界拒绝与 write 同口径）。 */
     async append(relPath, data) {
+        this.assertRealInsideRoot(relPath);
         const target = this.abs(relPath);
         await fspMkdir(dirname(target), { recursive: true });
         await fspAppendFile(target, data);
     }
     /** 建目录（递归；已存在幂等成功；越界拒绝与 write 同口径）。 */
     async mkdir(relDir) {
+        this.assertRealInsideRoot(relDir);
         await fspMkdir(this.abs(relDir), { recursive: true });
     }
     /** 文件元信息（size/mtime 供同步/缓存判断；不存在抛错）。 */
@@ -457,6 +526,8 @@ export class WorkspaceFS {
     }
     /** 删除文件/目录（递归；只允许删工作区内的路径）。 */
     async remove(relPath) {
+        // remove 同样做 realpath 复核：递归删除跟着目录链接走，比写文件更危险。
+        this.assertRealInsideRoot(relPath);
         await fspRm(this.abs(relPath), { recursive: true, force: false });
     }
 }