pi-web-ui 0.85.0 → 0.86.2

package/dist/server/index.js

@@ -41,6 +41,8 @@ import { launchOrigin, toServiceInfo } from "./launch-origin.js";
 import { parseTabs, tabsRefusal } from "./tabs.js";
 import { installPack, isKnownPack, listPacks, loadServerStrings, readPackFile, removePack, unloadServerStrings, } from "./locales.js";
 import { PluginManager, resolvePluginClientFile, } from "./plugins.js";
+import { PluginInstaller } from "./plugin-installer.js";
+import { syncPluginCatalog } from "./plugin-catalog-sync.js";
 import { McpBridge } from "./mcp-bridge.js";
 /** 从 CLI 参数中取 flag 值：支持 --flag value 与 --flag=value 两种写法。
  *  让 `node dist/server/index.js --host 0.0.0.0 --port 9000` 这类直接启动也能生效，
@@ -59,6 +61,19 @@ function cliFlag(name) {
 const PORT = Number(cliFlag("--port") ?? process.env.PI_WEB_PORT ?? 8787);
 const CWD = resolve(cliFlag("--cwd") ?? process.env.PI_WEB_CWD ?? process.cwd());
 const DATA_DIR = resolve(cliFlag("--data-dir") ?? process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"));
+// Dev-no-cache setting read without a ClientStateStore instance (the index.html
+// route runs before any client attaches). Reads the same global settings blob.
+function readDevNoCacheSetting() {
+    try {
+        const raw = readFileSync(join(DATA_DIR, "client-state.json"), "utf8");
+        const all = JSON.parse(raw);
+        const v = all["__settings__"]?.settings?.devNoCache;
+        return typeof v === "boolean" ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Bind address. Default is loopback ONLY — the service is a local personal
  *  tool and should not be reachable from the network unless explicitly asked
  *  (e.g. PI_WEB_HOST=0.0.0.0 for LAN access / Docker port mapping). */
@@ -105,6 +120,23 @@ function appVersion() {
     }
     return appVersionCache;
 }
+/** On-disk web-build id: the main JS bundle hash from the built index.html.
+ *  Changes on every rebuild — stale pages compare and reload themselves.
+ *  Declared near use (below webDist), not here: webDist is a const further
+ *  down and calling this at module-init time would hit its dead zone. */
+let buildIdCache = null;
+function buildId() {
+    if (buildIdCache === null) {
+        try {
+            const html = readFileSync(join(webDistPath(), "index.html"), "utf8");
+            buildIdCache = html.match(/\/assets\/index-([A-Za-z0-9_-]+)\.js/)?.[1] ?? "";
+        }
+        catch {
+            buildIdCache = "";
+        }
+    }
+    return buildIdCache;
+}
 // Root of the SDK default per-project session dirs — chat transcripts live in
 // <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
 // honors PI_CODING_AGENT_DIR).
@@ -478,6 +510,10 @@ app.get("/plugins/:id/client/*", (req, res) => {
 /** Set in the env of the replacement child spawned by a self-update restart. */
 const RESTART_CHILD_ENV = "PI_WEB_RESTART_CHILD";
 const webDist = join(pkgRoot, "web", "dist");
+/** webDist accessor for buildId() (declared above webDist's const). */
+function webDistPath() {
+    return webDist;
+}
 if (existsSync(webDist)) {
     // gzip/deflate 响应压缩：前端 bundle ~1MB，局域网/反代场景传输量降到 ~1/4；
     // 对 API JSON 同样生效，WS 升级不受影响
@@ -510,6 +546,17 @@ if (existsSync(webDist)) {
         // Callback form: a failed stat here (npm i -g is mid-replacement of the
         // package dir) responds 503 instead of crashing the request pipeline
         // with an unhandled ENOENT stack trace.
+        // Dev caching (settings → message display → devNoCache): index.html pins
+        // hashed asset URLs — a cached copy keeps pointing at stale bundles
+        // after a rebuild+restart. Default follows the install: ON from source
+        // (.git next to the package root), OFF for installs. PI_WEB_DEV_CACHE=0/1
+        // overrides either way.
+        const devCache = process.env.PI_WEB_DEV_CACHE;
+        const fromSource = existsSync(join(pkgRoot, ".git"));
+        const envDefault = devCache !== undefined ? devCache !== "0" : fromSource;
+        const stored = readDevNoCacheSetting();
+        const noStore = stored ?? envDefault;
+        res.setHeader("Cache-Control", noStore ? "no-store" : "public, max-age=0");
         res.sendFile(join(webDist, "index.html"), (err) => {
             if (err && !res.headersSent) {
                 res.status(503).send("正在更新 pi-web-ui，请稍后刷新…");
@@ -634,6 +681,58 @@ loadServerStrings(DATA_DIR);
 // Optional UI plugins (<dataDir>/plugins/<id>/): scanned on every client
 // attach so freshly dropped plugins appear without a server restart.
 const pluginMgr = new PluginManager(DATA_DIR, CWD, join(pkgRoot, "plugins", "catalog.json"));
+// 插件作业（安装/更新/卸载）后台执行：不占用户终端、不打断设置面板（issue #152）。
+// 真正干活的是 CLI（<pkgRoot>/bin/pi-web-ui.mjs），这里只做进程编排 + 进度转发。
+const pluginInstaller = new PluginInstaller({ dataDir: DATA_DIR, pkgRoot, managed: MANAGED });
+/** 插件目录/市场变化后统一收尾：重扫激活 + 重推 plugins 与 plugin_catalog。 */
+async function reloadPluginsAndPush(lang) {
+    await pluginMgr.reload(lang);
+    await pluginMgr.pushToAll();
+    await pluginMgr.pushCatalog();
+}
+const pendingPathRequests = new Map();
+/** 把授权表推给所有在线客户端（设置面板展示 + 撤销后刷新）。 */
+function pushPluginGrants() {
+    const grants = pluginMgr.grants.list();
+    const payload = JSON.stringify({ type: "plugin_grants", grants });
+    for (const client of wss.clients) {
+        if (client.readyState === WebSocket.OPEN) {
+            try {
+                client.send(payload);
+            }
+            catch {
+                /* 死连接：index.ts 自己会清理 */
+            }
+        }
+    }
+}
+pluginMgr.pathAccessRequester = (pluginId, dir, reason) => new Promise((resolve) => {
+    const id = randomUUID();
+    const timer = setTimeout(() => {
+        pendingPathRequests.delete(id);
+        resolve(false);
+    }, 120_000);
+    pendingPathRequests.set(id, { resolve, timer });
+    const payload = JSON.stringify({
+        type: "plugin_path_request",
+        id,
+        pluginId,
+        path: dir,
+        ...(reason ? { reason } : {}),
+    });
+    for (const client of wss.clients) {
+        if (client.readyState === WebSocket.OPEN) {
+            try {
+                client.send(payload);
+            }
+            catch {
+                /* 死连接 */
+            }
+        }
+    }
+});
+// 用户点了「允许」→ 授权表变了 → 立刻重推给所有在线客户端（设置面板「已授权目录」即时可见）。
+pluginMgr.onGrantsChanged = () => pushPluginGrants();
 // MCP 工具桥：读取 <dataDir>/mcp.json 启动外部 MCP 服务器（stdio），把它们的
 // 工具并入与插件工具相同的 customTools 管线；单服务器失败不炸进程。
 const mcpBridge = new McpBridge(DATA_DIR, (...a) => console.log("[mcp]", ...a));
@@ -664,7 +763,11 @@ service.pluginBgTasksProvider = () => pluginMgr.bgTasks();
 service.pluginStopBgTask = (taskId) => pluginMgr.stopPluginBgTask(taskId);
 // 插件宿主工作区实时跟随当前项目：任意客户端 set_cwd 成功后同步给
 // PluginManager，编辑器等工作区跟随型插件随即切根（详见 plugins.ts notifyCwd）。
-service.onClientCwdChanged = (cwd) => pluginMgr.notifyCwd(cwd);
+service.onClientCwdChanged = (cwd, roots) => {
+    pluginMgr.notifyCwd(cwd);
+    // 工作区根（宿主侧多根，issue #146）：插件宿主的「工作区内」判定要跟着变。
+    pluginMgr.notifyWorkspaceRoots(roots);
+};
 // ---------------------------------------------------------------------------
 // Self-update
 // ---------------------------------------------------------------------------
@@ -919,6 +1022,11 @@ wss.on("connection", (ws) => {
             case "set_cwd":
                 void cs.setCwd(msg.path);
                 break;
+            case "set_workspace_roots":
+                // 宿主侧多根（issue #146）：只改「哪些路径算工作区内」与右栏文件树的根，
+                // 不动 cwd（AI 仍只在主 cwd 里干活）。
+                void cs.setWorkspaceRoots(msg.roots);
+                break;
             case "set_locale":
                 // UI language report — per-client persist + lang-aware prompt
                 // refresh (streaming-safe). Engine-agnostic via DispatchSession.
@@ -1010,8 +1118,14 @@ wss.on("connection", (ws) => {
                 break;
             case "terminal_create": {
                 const tm = cs.getTerminalManager(msg.conversationId);
-                if (tm)
-                    tm.create(msg.terminalId, msg.cwd, msg.cols, msg.rows, cs.getTerminalCwd(msg.conversationId), msg.title, msg.locale ? { locale: msg.locale } : undefined);
+                if (tm) {
+                    // agentBash 透传：前端重建已退出的 AI 终端时保留其身份（issue #147）；
+                    // 字段缺省（旧前端）时 create() 再从 history 继承。
+                    const createOpts = msg.locale !== undefined || msg.agentBash !== undefined
+                        ? { locale: msg.locale, agentBash: msg.agentBash }
+                        : undefined;
+                    tm.create(msg.terminalId, msg.cwd, msg.cols, msg.rows, cs.getTerminalCwd(msg.conversationId), msg.title, createOpts);
+                }
                 break;
             }
             case "terminal_input":
@@ -1080,6 +1194,8 @@ wss.on("connection", (ws) => {
                     goalModeEnabled: msg.goalModeEnabled,
                     thinkingWrap: msg.thinkingWrap,
                     toolsWrap: msg.toolsWrap,
+                    devNoCache: msg.devNoCache,
+                    autoReload: msg.autoReload,
                     skillsFullText: msg.skillsFullText,
                     visionBridgeEnabled: msg.visionBridgeEnabled,
                     visionBridgeModel: msg.visionBridgeModel,
@@ -1094,6 +1210,7 @@ wss.on("connection", (ws) => {
                     quickPhrases: msg.quickPhrases,
                     quickPhrasesEnabled: msg.quickPhrasesEnabled,
                     quickPhrasesSeeded: msg.quickPhrasesSeeded,
+                    uiLayout: msg.uiLayout,
                 });
                 break;
             case "extensions_reload":
@@ -1135,6 +1252,87 @@ wss.on("connection", (ws) => {
                 }
                 break;
             }
+            // -- 插件后台作业（安装/更新/卸载，issue #152）----------------------------
+            // 不再是「开一个可见终端 tab 并关掉设置面板」：作业在服务端后台跑，输出按行
+            // 回给发起者，设置面板原就位显示。真正的执行者是 CLI（单一实现）。
+            case "plugin_job": {
+                const jobLang = () => cs?.getLang() ?? "en";
+                const jobId = String(msg.jobId ?? "");
+                const pluginId = String(msg.id ?? "");
+                const started = pluginInstaller.start({
+                    jobId,
+                    action: msg.action,
+                    id: pluginId,
+                    source: msg.source,
+                    build: msg.build === true,
+                }, {
+                    lang: jobLang,
+                    emit: (m) => send(m),
+                    done: async (ok, info) => {
+                        if (ok) {
+                            await reloadPluginsAndPush(jobLang);
+                        }
+                        else if (info.error) {
+                            cs?.emitNotice("error", `插件操作失败：${info.error}`, `Plugin operation failed: ${info.error}`);
+                        }
+                    },
+                });
+                if (!started.ok) {
+                    // 被拒（忙 / 托管实例 / 参数非法）也要回一条 done，让面板上的作业就地结束。
+                    send({
+                        type: "plugin_job",
+                        jobId,
+                        action: msg.action,
+                        pluginId,
+                        phase: "done",
+                        ok: false,
+                        error: started.error,
+                        output: "",
+                    });
+                }
+                break;
+            }
+            case "plugin_job_cancel":
+                pluginInstaller.cancel(String(msg.jobId ?? ""));
+                break;
+            // -- 插件目录授权（issue #146）------------------------------------------
+            case "plugin_path_response": {
+                const pending = pendingPathRequests.get(String(msg.id ?? ""));
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    pendingPathRequests.delete(String(msg.id ?? ""));
+                    pending.resolve(msg.ok === true);
+                }
+                break;
+            }
+            case "plugin_path_revoke": {
+                const removed = pluginMgr.grants.revoke(typeof msg.pluginId === "string" ? msg.pluginId : undefined, typeof msg.path === "string" ? msg.path : undefined);
+                cs?.emitNotice("info", `已撤销 ${removed} 条插件目录授权`, `Revoked ${removed} plugin path grant(s)`);
+                pushPluginGrants();
+                break;
+            }
+            // -- 插件市场目录同步（issue #148）--------------------------------------
+            case "plugin_catalog_sync": {
+                const syncLang = () => cs?.getLang() ?? "en";
+                const requestId = String(msg.requestId ?? "");
+                void syncPluginCatalog(String(msg.source ?? ""), { install: msg.install === true, replace: msg.replace === true }, {
+                    customCatalogPath: pluginMgr.customCatalogPath,
+                    pluginsDir: join(DATA_DIR, "plugins"),
+                    installer: pluginInstaller,
+                    afterWrite: () => reloadPluginsAndPush(syncLang),
+                    lang: syncLang,
+                }).then((r) => {
+                    send({
+                        type: "plugin_catalog_sync_result",
+                        requestId,
+                        ok: r.ok,
+                        ...(r.error ? { error: r.error } : {}),
+                        entries: pluginMgr.catalog(),
+                        ...(r.installed ? { installed: r.installed } : {}),
+                    });
+                });
+                break;
+            }
             case "dsh_patches_list":
                 void cs.listDshPatches?.();
                 break;
@@ -1194,6 +1392,7 @@ wss.on("connection", (ws) => {
                     // and the client used to learn ours from the update check —
                     // which a managed instance never runs.
                     appVersion: appVersion(),
+                    buildId: buildId(),
                     managed: MANAGED,
                     tabs: TABS ? [...TABS] : undefined,
                     service: SERVICE_INFO ?? undefined,
@@ -1215,6 +1414,8 @@ wss.on("connection", (ws) => {
                     // 让各插件向新接入的客户端推送自身初始状态（onAttach 钩子）——
                     // 插件不要依赖客户端挂载后自己拉（见 plugins.ts onAttach 注释）。
                     pluginMgr.notifyAttach(cid);
+                    // 插件目录授权表（设置面板展示 + 可撤销）
+                    send({ type: "plugin_grants", grants: pluginMgr.grants.list() });
                     // 插件命令可能在本客户端 attach 过程中才注册（首载竞态）——
                     // 重推一次目录，保证选择器完整。
                     service.applyPluginCommandCatalog();
@@ -1325,6 +1526,7 @@ async function shutdown() {
     clearInterval(heartbeatTimer);
     stopControl();
     pluginMgr.dispose();
+    pluginInstaller.dispose();
     mcpBridge.dispose();
     await service.disposeAll();
     wss.close();

package/dist/server/managed.js

@@ -33,6 +33,10 @@ export const MANAGED_MESSAGES = [
     "install_pi_agent",
     /** Plugin market: fetches and installs a plugin from the network. */
     "plugin_catalog_add",
+    /** Plugin install/update/uninstall run as a background job (issue #152). */
+    "plugin_job",
+    /** Catalog sync can install/update entries too (issue #148). */
+    "plugin_catalog_sync",
 ];
 /**
  * Whether this instance is managed from outside.

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

@@ -0,0 +1,117 @@
+/**
+ * plugin-catalog-sync — 受支持的「插件市场目录同步」（issue #148）。
+ *
+ * 第三方插件想把自己的插件清单同步进宿主，本来只能：派发私有的浏览器事件
+ * `pi-web-ui:plugin-run-command` + 让用户在可见终端里看它跑命令。私有事件随时会变，
+ * 宿主的目录更新也没有回执。这里把它做成**受支持的一条路径**：
+ *
+ *   host.reloadCatalog(source, { install, replace })       （插件侧，浏览器）
+ *     → plugin_catalog_sync                                （协议）
+ *       → 本文件：读文档 → 校验 → 原子写盘 → 可选安装 → 重载 + 重推 → 回执
+ *
+ * 三条纪律（对齐 issue 的验收标准）：
+ *   1. 校验与市场「添加到列表」同源（plugin-catalog.ts 的 toEntry）——不合法条目丢弃，
+ *      形状不对 / 读不到 / 解析失败时**一个字节都不写盘**（旧目录保持有效）；
+ *   2. 安装走正常安装器（PluginInstaller，同 CLI + 同一把锁），失败逐条回报，
+ *      不因为一条坏条目就停掉整批；
+ *   3. 回执是结构化的（ok/error/entries/installed），不靠 DOM 事件或控制台文字。
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { pick } from "./i18n.js";
+import { normalizeSyncPayload, writeCustomCatalog } from "./plugin-catalog.js";
+/**
+ * 读同步文档：`http(s)://` 走网络，其余当本地文件路径（须为绝对路径）。
+ * 只读文本，JSON 解析交给调用方（解析失败也走同一条「不写盘」的路径）。
+ */
+async function readDocument(source, deps, lang) {
+    const l = lang();
+    const maxBytes = Math.max(1024, Number(deps.maxBytes ?? 1024 * 1024));
+    if (/^https?:\/\//i.test(source)) {
+        let res;
+        try {
+            res = await fetch(source, {
+                redirect: "follow",
+                signal: AbortSignal.timeout(Math.max(1000, Number(deps.fetchTimeoutMs ?? 30_000))),
+            });
+        }
+        catch (err) {
+            return {
+                error: pick(l, `拉取目录失败：${err?.message ?? err}`, `Failed to fetch the catalog: ${err?.message ?? err}`, "plugincatalog.sync.fetch.failed", { reason: String(err?.message ?? err) }),
+            };
+        }
+        if (!res.ok)
+            return {
+                error: pick(l, `拉取目录失败：HTTP ${res.status}`, `Failed to fetch the catalog: HTTP ${res.status}`, "plugincatalog.sync.http", { status: String(res.status) }),
+            };
+        const text = await res.text();
+        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 };
+    }
+    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"),
+        };
+    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 };
+    }
+    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) }),
+        };
+    }
+}
+/**
+ * 同步一次目录：读 → 校验 → 原子写 → 可选安装 → 重载 + 重推。
+ * 任何一步失败都以 `{ ok:false, error }` 返回（不抛），由协议层原样回给调用者。
+ */
+export async function syncPluginCatalog(source, opts, deps) {
+    const lang = deps.lang ?? (() => "en");
+    const l = lang();
+    const src = String(source ?? "").trim();
+    if (!src)
+        return {
+            ok: false,
+            error: pick(l, "缺少目录来源", "Missing catalog source", "plugincatalog.sync.source.missing"),
+        };
+    const doc = await readDocument(src, deps, lang);
+    if ("error" in doc)
+        return { ok: false, error: doc.error };
+    let raw;
+    try {
+        raw = JSON.parse(doc.text);
+    }
+    catch (err) {
+        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) }),
+        };
+    }
+    const payload = normalizeSyncPayload(raw, lang);
+    if ("error" in payload)
+        return { ok: false, error: payload.error };
+    // 到这里才动磁盘：校验失败的文档绝不覆盖一份有效目录。
+    writeCustomCatalog(deps.customCatalogPath, payload.entries, opts.replace === true);
+    await deps.afterWrite();
+    let installed;
+    if (opts.install === true && payload.entries.length) {
+        installed = [];
+        for (const e of payload.entries) {
+            const action = existsSync(join(deps.pluginsDir, e.id)) ? "update" : "install";
+            const res = await deps.installer.run({ jobId: `catalog-sync:${e.id}`, action, id: e.id, source: e.source }, { lang });
+            installed.push({ id: e.id, ok: res.ok, ...(res.error ? { error: res.error } : {}) });
+        }
+        // 安装改变了 <dataDir>/plugins —— 再重载/重推一次，让新插件与前端清单对齐。
+        await deps.afterWrite();
+    }
+    return { ok: true, installed };
+}

package/dist/server/plugin-catalog.js

@@ -37,6 +37,8 @@ function isValidSource(source) {
             return false;
     return true;
 }
+/** 导出给服务端其它模块（后台作业的安装源校验、目录同步），单一事实源。 */
+export { isValidSource };
 /** 推导默认 id：与 CLI（bin/pi-web-ui.mjs）的规则对齐 —— 子路径末段 > 仓库名
  *  > 来源末段；非法字符替换为 -，两端去 -；空则 "plugin"。显式 raw（含合法
  *  id 校验）优先。返回的 id 不保证通过 ID_RE（Cyrillic 等），调用方再校验。 */
@@ -161,3 +163,68 @@ export function removeCustomEntry(customPath, id) {
     atomicWrite(customPath, { entries: next });
     return true;
 }
+/**
+ * 把同步文档规范化为自定义条目列表（纯函数，不碰磁盘）。
+ *
+ * 文档形状：JSON 数组，或 `{ entries: [...] }`（与本文件自身的磁盘格式同形）。
+ * 每个条目走 `toEntry` —— 与市场“添加到列表”**同一套校验**（id 字符集、source 必须
+ * 是远程 owner/repo[/subdir][#ref]、字段 trimmed + 长度上限），非法条目丢弃并计数；
+ * 整份文档形状不对则直接报错，由调用方原样回给调用者（绝不写盘）。
+ */
+export function normalizeSyncPayload(raw, lang) {
+    const l = lang?.() ?? "en";
+    const list = Array.isArray(raw)
+        ? raw
+        : raw && typeof raw === "object" && Array.isArray(raw.entries)
+            ? raw.entries
+            : null;
+    if (!list)
+        return {
+            error: pick(l, '目录 JSON 需为数组，或 {"entries": [...]} 形状', 'Catalog JSON must be an array or the {"entries": [...]} shape', "plugincatalog.sync.shape"),
+        };
+    const entries = [];
+    let skipped = 0;
+    for (const it of list) {
+        const e = it && typeof it === "object" ? toEntry(it, false) : null;
+        if (e)
+            entries.push(e);
+        else
+            skipped += 1;
+    }
+    return { entries, skipped };
+}
+/**
+ * 原子写入用户自定义列表。
+ *
+ * `replace=true` 整体替换（文档即真相）；`false`（默认）按 id upsert：文档里出现的
+ * id 覆盖同名旧条目，文档没提的旧条目**保留** —— 这样插件只推送增量也能用。
+ * 写入内容只包含本文件认识的白名单字段（id/source/name/description/descriptionEn/
+ * icon/homepage），远端文档里塞的其他键不会落到磁盘上。
+ *
+ * 返回写盘后的自定义条目数（合并列表由 PluginManager.catalog() 重读得出）。
+ */
+export function writeCustomCatalog(customPath, incoming, replace) {
+    const byId = new Map();
+    if (!replace) {
+        const raw = readJsonSafe(customPath, {});
+        const existing = Array.isArray(raw.entries) ? raw.entries : [];
+        for (const it of existing) {
+            const e = it && typeof it === "object" ? toEntry(it, false) : null;
+            if (e)
+                byId.set(e.id, e);
+        }
+    }
+    for (const e of incoming)
+        byId.set(e.id, e);
+    const entries = [...byId.values()].map((e) => ({
+        id: e.id,
+        source: e.source,
+        name: e.name,
+        ...(e.description ? { description: e.description } : {}),
+        ...(e.descriptionEn ? { descriptionEn: e.descriptionEn } : {}),
+        ...(e.icon ? { icon: e.icon } : {}),
+        ...(e.homepage ? { homepage: e.homepage } : {}),
+    }));
+    atomicWrite(customPath, { entries });
+    return entries.length;
+}