@youweichen/pi-harness 0.0.0-stage → 1.0.0

package/dist/server/plan/state.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function text(v, name, max) {
+    if (typeof v !== "string" || !v.trim() || v.length > max)
+        throw new Error(`${name} must be non-empty and at most ${max} characters`);
+    return v;
+}
+export function editableState(value) {
+    if (!object(value))
+        throw new Error("Submit a complete plan object");
+    const title = text(value.title, "title", 80), completionCriteria = text(value.completionCriteria, "completionCriteria", 240);
+    if (!["active", "completed", "cancelled", "failed"].includes(String(value.status)))
+        throw new Error("Invalid plan status");
+    if (!Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > 16)
+        throw new Error("steps must contain 1–16 items");
+    const steps = value.steps.map(step => {
+        if (!object(step))
+            throw new Error("Invalid step");
+        return { id: text(step.id, "step.id", 64), title: text(step.title, "step.title", 80), ...(step.detail !== undefined ? { detail: text(step.detail, "step.detail", 500) } : {}) };
+    });
+    const ids = new Set(steps.map(step => step.id));
+    if (ids.size !== steps.length)
+        throw new Error("Step IDs must be unique");
+    if (!Array.isArray(value.completedStepIds) || value.completedStepIds.some(id => typeof id !== "string" || !ids.has(id)) || new Set(value.completedStepIds).size !== value.completedStepIds.length)
+        throw new Error("completedStepIds must be unique existing step IDs");
+    const completedStepIds = value.completedStepIds;
+    if (value.currentStepId !== null && (typeof value.currentStepId !== "string" || !ids.has(value.currentStepId) || completedStepIds.includes(value.currentStepId)))
+        throw new Error("currentStepId must be null or an incomplete existing step ID");
+    if (value.status !== "active" && value.currentStepId !== null)
+        throw new Error("Terminal plans must have currentStepId: null");
+    if (value.status === "completed" && completedStepIds.length !== steps.length)
+        throw new Error("Completed plans must complete every step");
+    return { title, completionCriteria, status: value.status, steps, completedStepIds: [...completedStepIds], currentStepId: value.currentStepId,
+        ...(value.changeSummary !== undefined ? { changeSummary: text(value.changeSummary, "changeSummary", 240) } : {}) };
+}
+export function changesBetween(before, after) {
+    const changes = [];
+    for (const [index, step] of after.steps.entries()) {
+        const oldIndex = before?.steps.findIndex(old => old.id === step.id) ?? -1;
+        const old = before?.steps[oldIndex];
+        if (!old)
+            changes.push({ kind: "added", stepId: step.id, title: step.title, position: index + 1 });
+        else if (old.title !== step.title || old.detail !== step.detail || oldIndex !== index)
+            changes.push({ kind: "updated", stepId: step.id, title: step.title, position: index + 1 });
+        if (after.completedStepIds.includes(step.id) && !before?.completedStepIds.includes(step.id))
+            changes.push({ kind: "completed", stepId: step.id, title: step.title, position: index + 1 });
+        else if (after.currentStepId === step.id && before?.currentStepId !== step.id)
+            changes.push({ kind: "started", stepId: step.id, title: step.title, position: index + 1 });
+        else if (old && !after.completedStepIds.includes(step.id) && after.currentStepId !== step.id && (before?.completedStepIds.includes(step.id) || before?.currentStepId === step.id))
+            changes.push({ kind: "pending", stepId: step.id, title: step.title, position: index + 1 });
+    }
+    for (const step of before?.steps ?? [])
+        if (!after.steps.some(next => next.id === step.id))
+            changes.push({ kind: "removed", stepId: step.id, title: step.title });
+    if (before && before.status !== after.status)
+        changes.push({ kind: "status", status: after.status });
+    return changes;
+}
+export function transition(value, current, newId = randomUUID) {
+    if (!object(value) || !["create", "update"].includes(String(value.action)))
+        throw new Error("action must be create or update");
+    if (value.action === "update") {
+        const reason = !current ? "No plan exists on this branch" : current.status !== "active" ? "The latest plan has ended" : value.planId !== current.planId ? "planId does not match this branch's latest plan" : value.expectedRevision !== current.revision ? "expectedRevision is stale" : undefined;
+        if (reason)
+            throw new Error(`${reason}. ${!current || current.status !== "active" ? "Use create for a new plan." : "Use update with the current planId and expectedRevision and submit the full corrected plan."}\nCurrent editable state: ${current ? JSON.stringify({ action: current.status === "active" ? "update" : "create", planId: current.planId, expectedRevision: current.revision, ...editableState(current) }) : "none; use create"}`);
+    }
+    const state = editableState(value);
+    const changes = changesBetween(value.action === "update" ? current : undefined, state);
+    if (value.action === "create" && current?.status === "active")
+        changes.unshift({ kind: "replaced", planId: current.planId, revision: current.revision, reason: "Replaced by a newly created plan" });
+    return { schemaVersion: 3, planId: value.action === "create" ? newId() : current.planId, revision: value.action === "create" ? 1 : current.revision + 1, ...state, changes };
+}
+/** Validate and copy only known fields. Never forward arbitrary extension details. */
+export function planSnapshot(value) {
+    try {
+        if (!object(value) || value.schemaVersion !== 3 || typeof value.planId !== "string" || !value.planId || value.planId.length > 128 || !Number.isSafeInteger(value.revision) || Number(value.revision) < 1 || !Array.isArray(value.changes) || value.changes.length > 64)
+            return;
+        const state = editableState(value);
+        const changes = value.changes.map(change => {
+            if (!object(change))
+                throw new Error("Invalid change");
+            if (change.kind === "replaced") {
+                if (!Number.isSafeInteger(change.revision) || Number(change.revision) < 1)
+                    throw new Error("Invalid replacement revision");
+                return { kind: "replaced", planId: text(change.planId, "planId", 128), revision: Number(change.revision), reason: text(change.reason, "reason", 240) };
+            }
+            if (change.kind === "status" && ["active", "completed", "cancelled", "failed"].includes(String(change.status)))
+                return { kind: "status", status: change.status };
+            if (!["added", "updated", "removed", "completed", "started", "pending"].includes(String(change.kind)))
+                throw new Error("Invalid change kind");
+            if (change.position !== undefined && (!Number.isInteger(change.position) || Number(change.position) < 1 || Number(change.position) > 16))
+                throw new Error("Invalid position");
+            return { kind: change.kind, stepId: text(change.stepId, "stepId", 64), title: text(change.title, "title", 80), ...(change.position !== undefined ? { position: Number(change.position) } : {}) };
+        });
+        return { schemaVersion: 3, planId: value.planId, revision: Number(value.revision), ...state, changes };
+    }
+    catch {
+        return;
+    }
+}
+export function snapshotFromDetails(details) {
+    return object(details) ? planSnapshot(details.planSnapshot) : undefined;
+}
+export function latestPlan(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.toolName !== "plan" || entry.message.isError)
+            continue;
+        const snapshot = snapshotFromDetails(entry.message.details);
+        if (snapshot)
+            return { snapshot, entryId: entry.id, toolCallId: entry.message.toolCallId };
+    }
+}

package/dist/server/plugin-facilities.js

@@ -0,0 +1,304 @@
+/**
+ * 插件宿主设施：插件私有 KV 存储 + 加密 secrets，从 plugins.ts 抽出的纯设施。
+ *
+ * storage —— <pluginDir>/storage.json 单文件 JSON KV：
+ *   - 全内存缓存、写入 tmp+rename 原子落盘（同 client-state.ts 的做法）；
+ *   - 供插件存非敏感配置（窗口布局、上次选中项…），替代各家手搓的
+ *     read/write config.json 样板；
+ *   - 生命周期跟插件目录绑定（uninstall 即删除），跨升级保留。
+ *
+ * secrets —— AES-256-GCM 加密的机密存储（密码/API key/token）：
+ *   - 密钥文件 <dataDir>/secrets.key（随机 32 字节，首次生成；chmod 0600 仅对
+ *     POSIX 有意义，Windows 上 NTFS 权限继承用户目录默认 ACL）；
+ *   - 密文文件随插件目录 <pluginDir>/secrets.bin——拷到别的机器因无密钥解不开
+ *     （fail closed）；卸载插件即连密文一起删除；
+ *   - 威胁模型：防「 casually 复制/查看文件」（混淆级保护）与「密文外泄」，
+ *     不能防同一用户账号下的完整进程妥协——本地个人工具的合理折衷。
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { writeFileAtomic } from "./private-file.js";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFile as fspReadFile, readdir as fspReaddir, rm as fspRm, mkdir as fspMkdir, writeFile as fspWriteFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+/** tmp+rename 原子写（错误由调用方隔离——插件设施的 IO 一律尽力而为）。 */
+function atomicWrite(file, data, mode) {
+    if (mode === undefined) {
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        writeFileSync(tmp, data);
+        renameSync(tmp, file);
+        return;
+    }
+    writeFileAtomic(file, data, { mode });
+}
+// ---------------------------------------------------------------------------
+// storage
+// ---------------------------------------------------------------------------
+/** 每插件的 JSON 文件 KV。所有方法同步（数据量小，避免并发写乱序）。 */
+export class PluginStorage {
+    file;
+    cache;
+    constructor(file) {
+        this.file = file;
+    }
+    load() {
+        if (this.cache)
+            return this.cache;
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+            this.cache = parsed && typeof parsed === "object" ? parsed : {};
+        }
+        catch {
+            this.cache = {}; // 不存在/损坏 = 空表（损坏不致命，重新积累）
+        }
+        return this.cache;
+    }
+    get(key, fallback) {
+        const v = this.load()[key];
+        return v === undefined ? fallback : v;
+    }
+    all() {
+        return { ...this.load() };
+    }
+    set(key, value) {
+        if (!key)
+            throw new Error("storage.set: key 不能为空");
+        const store = this.load();
+        store[key] = value;
+        try {
+            atomicWrite(this.file, JSON.stringify(store), 0o600);
+        }
+        catch (err) {
+            console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
+        }
+    }
+    delete(key) {
+        const store = this.load();
+        if (!(key in store))
+            return;
+        delete store[key];
+        try {
+            atomicWrite(this.file, JSON.stringify(store), 0o600);
+        }
+        catch (err) {
+            console.error(`[plugin-storage] 写入失败 (${this.file}):`, err);
+        }
+    }
+}
+function seal(key, plaintext) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return { iv: iv.toString("hex"), tag: cipher.getAuthTag().toString("hex"), ct: ct.toString("hex") };
+}
+function unseal(key, blob) {
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(blob.iv, "hex"));
+    decipher.setAuthTag(Buffer.from(blob.tag, "hex"));
+    return Buffer.concat([decipher.update(Buffer.from(blob.ct, "hex")), decipher.final()]).toString("utf8");
+}
+/** 读或创建全局密钥文件（懒加载一次）。 */
+function loadOrCreateKey(dataDir) {
+    const keyFile = join(dataDir, "secrets.key");
+    try {
+        if (existsSync(keyFile)) {
+            const encoded = readFileSync(keyFile, "utf8").trim();
+            if (/^[a-f\d]{64}$/i.test(encoded))
+                return Buffer.from(encoded, "hex");
+            throw new Error("invalid secrets key");
+        }
+    }
+    catch {
+        /* fallthrough → regenerate */
+    }
+    const key = randomBytes(32);
+    atomicWrite(keyFile, `${key.toString("hex")}\n`, 0o600); // 创建即 0600，没有先 0644 再 chmod 的窗口
+    return key;
+}
+/** 每插件的加密 KV。所有方法同步；任何读写失败都静默回退（机密丢失优于崩进程）。 */
+export class PluginSecrets {
+    store;
+    file;
+    constructor(dataDir, pluginDir) {
+        this.file = join(pluginDir, "secrets.bin");
+        this.key = PluginSecrets.keyFor(dataDir);
+    }
+    key;
+    static keys = new Map();
+    /** 按 dataDir 惰性生成/复用密钥（同进程内共享，避免重复 IO）。 */
+    static keyFor(dataDir) {
+        let k = PluginSecrets.keys.get(dataDir);
+        if (!k) {
+            k = loadOrCreateKey(dataDir);
+            PluginSecrets.keys.set(dataDir, k);
+        }
+        return k;
+    }
+    load() {
+        if (this.store)
+            return this.store;
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+            this.store =
+                parsed && parsed.v === 1 && parsed.items && typeof parsed.items === "object"
+                    ? parsed
+                    : { v: 1, items: {} };
+        }
+        catch {
+            this.store = { v: 1, items: {} };
+        }
+        return this.store;
+    }
+    set(name, value) {
+        if (!name)
+            throw new Error("secrets.set: name 不能为空");
+        const s = this.load();
+        s.items[name] = seal(this.key, value);
+        try {
+            atomicWrite(this.file, JSON.stringify(s), 0o600);
+        }
+        catch (err) {
+            console.error("[plugin-secrets] 写入失败:", err);
+        }
+    }
+    get(name) {
+        const blob = this.load().items[name];
+        if (!blob)
+            return undefined;
+        try {
+            return unseal(this.key, blob);
+        }
+        catch {
+            return undefined; // 换机器 / 密钥轮换 → 解不开返回空（fail closed）
+        }
+    }
+    has(name) {
+        return name in this.load().items;
+    }
+    delete(name) {
+        const s = this.load();
+        if (!(name in s.items))
+            return;
+        delete s.items[name];
+        try {
+            atomicWrite(this.file, JSON.stringify(s), 0o600);
+        }
+        catch (err) {
+            console.error("[plugin-secrets] 写入失败:", err);
+        }
+    }
+    list() {
+        return Object.keys(this.load().items);
+    }
+}
+// ---------------------------------------------------------------------------
+// deps（宿主代插件自动补装运行时依赖）
+// ---------------------------------------------------------------------------
+const DEP_TIMEOUT_MS = 180_000; // 慢网安装兜底（含第一次拉取包元数据）
+/** 从插件目录出发能否解析到这个模块（模拟插件自身 import() 的查找链）。 */
+export function isDepAvailable(pluginDir, spec) {
+    try {
+        createRequire(join(pluginDir, "index.mjs")).resolve(spec);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const depInstallLocks = new Map();
+/** 确保依赖就绪：先逐个解析，缺了才一次性 `npm install` 补装，装完复查。
+ *  返回 true = 全部可用；false = 安装失败或超时。同目录并发调用单飞合并。
+ *
+ *  这是 webmail / db-client / vscode-editor 三家手搓 ensureXxxMod 的上收——
+ *  之前每家都自己拼 spawn 参数、自己处理 win32 的 npm.cmd、自己等 install 完成。 */
+export function ensurePluginDeps(pluginDir, specs, onProgress) {
+    if (specs.length === 0)
+        return Promise.resolve(true);
+    const missing = specs.filter((s) => !isDepAvailable(pluginDir, s));
+    if (missing.length === 0)
+        return Promise.resolve(true);
+    const lockKey = join(pluginDir, missing.sort().join("|"));
+    const inflight = depInstallLocks.get(lockKey);
+    if (inflight)
+        return inflight;
+    const run = async () => {
+        // 无 package.json 时 npm 会沿目录树向上找最近一个，可能把依赖装进父目录——
+        // 先落一个最小 package.json 钉住安装位置。
+        if (!existsSync(join(pluginDir, "package.json"))) {
+            try {
+                atomicWrite(join(pluginDir, "package.json"), JSON.stringify({ name: "plugin-runtime-deps", private: true }, null, 2));
+            }
+            catch { }
+        }
+        onProgress?.(`正在安装依赖：${missing.join(", ")}…（首次约需几分钟）`);
+        // win32 的 npm 是 .cmd——spawnSync 直接跑会被 EINVAL 拒绝，必须走 shell；
+        // posix 不用 shell（路径不含空格假设成立，与宿主其它 spawn 一致）。
+        const res = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "--no-audit", "--no-fund", ...missing], { cwd: pluginDir, timeout: DEP_TIMEOUT_MS, shell: process.platform === "win32", encoding: "utf8" });
+        if (res.error || res.status !== 0) {
+            console.error(`[plugin-deps] ${join(pluginDir)} npm install 失败:`, res.error ?? res.stderr?.slice(0, 500));
+            return false;
+        }
+        const stillMissing = specs.filter((s) => !isDepAvailable(pluginDir, s));
+        if (stillMissing.length) {
+            console.error(`[plugin-deps] 安装完成但仍缺：${stillMissing.join(", ")}`);
+            return false;
+        }
+        onProgress?.("依赖安装完成");
+        return true;
+    };
+    const p = run().finally(() => depInstallLocks.delete(lockKey));
+    depInstallLocks.set(lockKey, p);
+    return p;
+}
+export class WorkspaceFS {
+    root;
+    /** root 是活值 getter（返回当前工作区绝对路径），跟随 set_cwd。 */
+    constructor(root) {
+        this.root = root;
+    }
+    /** 相对路径 → 活根下的绝对路径；越界抛错。空串 = 根本身。 */
+    abs(rel) {
+        const rootDir = resolve(this.root());
+        const target = resolve(rootDir, typeof rel === "string" ? rel : "");
+        if (target !== rootDir && !target.startsWith(rootDir + sepOf())) {
+            throw new Error(`路径越界：${String(rel)}`);
+        }
+        return target;
+    }
+    /** 单层目录列表（浅层；深度遍历请插件自行递归）。 */
+    async list(relDir = "") {
+        try {
+            const dirents = await fspReaddir(this.abs(relDir), { withFileTypes: true });
+            return dirents
+                .slice(0, 2000)
+                .map((d) => ({ name: d.name, type: d.isDirectory() ? "dir" : "file" }));
+        }
+        catch (err) {
+            throw new Error(`读取目录失败：${err.message}`);
+        }
+    }
+    /** 读文件（二进制）。声明为 async：路径校验失败以 rejected promise 表达
+     * （非 async 版本会同步 throw，破坏调用方 .catch/.rejects 契约）。 */
+    async read(relPath) {
+        return fspReadFile(this.abs(relPath));
+    }
+    /** 读文本（默认上限 512KB，超出截断——预览同款约定）。 */
+    async readText(relPath, maxBytes = 512 * 1024) {
+        const buf = await this.read(relPath);
+        return buf.subarray(0, maxBytes).toString("utf8");
+    }
+    /** 写文件（自动补父目录；注意相对路径锚定当前项目——切换 cwd 后写进新项目）。 */
+    async write(relPath, data) {
+        const target = this.abs(relPath);
+        await fspMkdir(dirname(target), { recursive: true });
+        await fspWriteFile(target, data);
+    }
+    /** 删除文件/目录（递归；只允许删工作区内的路径）。 */
+    async remove(relPath) {
+        await fspRm(this.abs(relPath), { recursive: true, force: false });
+    }
+}
+function sepOf() {
+    return process.platform === "win32" ? "\\" : "/";
+}

package/dist/server/plugin-updater.js

@@ -0,0 +1,245 @@
+/**
+ * 插件更新辅助（备份/回滚 + 远端 sha 对比）——纯逻辑，供 CLI（bin/pi-harness.mjs）
+ * 与单测共用。零网络依赖：远端 sha 经注入的 exec 获取（生产 = git ls-remote；
+ * 测试 = fake exec 或本地 git 仓库路径，git ls-remote 支持本地仓库，完全离线）。
+ *
+ * 布局：
+ *   <dataDir>/plugins/<id>/           安装本体（含 .pi-source.json + .pi-git-sha）
+ *   <dataDir>/plugin-backups/<id>-<ts>/  覆盖安装前的旧版本快照（保留最近 N 份）
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, cpSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+const PLUGIN_ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 保留的备份份数（超出删除最旧的）。 */
+export const BACKUP_KEEP = 3;
+/** 默认执行器：execFile 直跑 git（不经 shell），15s 超时。 */
+export const execGit = (cmd, args) => new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 15_000, encoding: "utf8" }, (err, stdout, stderr) => {
+        if (err)
+            resolve({ ok: false, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+        else
+            resolve({ ok: true, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+    });
+});
+/**
+ * 覆盖安装前备份旧插件目录 → <dataDir>/plugin-backups/<id>-<ts>/。
+ * 目标不存在/备份失败返回 null（调用方可继续——备份是尽力而为的保护）。
+ */
+export function ensureBackup(dataDir, id, opts) {
+    if (!PLUGIN_ID_RE.test(id))
+        return null;
+    const target = join(dataDir, "plugins", id);
+    if (!existsSync(target))
+        return null;
+    const ts = stamp();
+    const dest = join(dataDir, "plugin-backups", `${id}-${ts}`);
+    try {
+        mkdirSync(dirnameOf(dest), { recursive: true });
+        cpSync(target, dest, {
+            recursive: true,
+            // 与安装一致：不备份 .git/node_modules（纯运行目录），config.json 等保留。
+            filter: (s) => !/(^|[\\/])(\.git|node_modules)([\\/]|$)/.test(s),
+        });
+        writeFileSync(join(dest, ".pi-backup.json"), JSON.stringify({ id, ts, source: opts?.source }, null, 2) + "\n");
+        pruneBackups(dataDir, id);
+        return ts;
+    }
+    catch (err) {
+        try {
+            rmSync(dest, { recursive: true, force: true });
+        }
+        catch {
+            /* 清理失败忽略 */
+        }
+        console.warn(`[plugin-updater] 备份 ${id} 失败：`, err instanceof Error ? err.message : err);
+        return null;
+    }
+}
+/** 该插件的备份目录列表（按时间从新到旧）。 */
+export function listBackups(dataDir, id) {
+    if (!PLUGIN_ID_RE.test(id))
+        return [];
+    const dir = join(dataDir, "plugin-backups");
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const re = new RegExp(`^${id.replace(/[^A-Za-z0-9_-]/g, "")}-(\\d{8}-\\d{9})$`);
+    return names
+        .filter((n) => re.test(n) && existsSync(join(dir, n, ".pi-backup.json")))
+        .sort()
+        .reverse();
+}
+/**
+ * 回滚到最近一份备份：删当前 plugins/<id> → 拷贝备份回 → 删备份。
+ * 返回最近备份 ts；无备份返回 null。
+ */
+export function restoreBackup(dataDir, id) {
+    const backups = listBackups(dataDir, id);
+    if (backups.length === 0)
+        return null;
+    const src = join(dataDir, "plugin-backups", backups[0]);
+    const target = join(dataDir, "plugins", id);
+    try {
+        if (existsSync(target))
+            rmSync(target, { recursive: true, force: true });
+        mkdirSync(join(dataDir, "plugins"), { recursive: true });
+        cpSync(src, target, { recursive: true });
+        rmSync(src, { recursive: true, force: true });
+        return backups[0];
+    }
+    catch (err) {
+        console.warn(`[plugin-updater] 回滚 ${id} 失败：`, err instanceof Error ? err.message : err);
+        return null;
+    }
+}
+/** 保留最近 BACKUP_KEEP 份，删除更旧的。 */
+export function pruneBackups(dataDir, id, keep = BACKUP_KEEP) {
+    const backups = listBackups(dataDir, id);
+    for (const b of backups.slice(keep)) {
+        try {
+            rmSync(join(dataDir, "plugin-backups", b), { recursive: true, force: true });
+        }
+        catch {
+            /* 忽略 */
+        }
+    }
+}
+/**
+ * 解析一个安装源并取远端 HEAD sha（前 12 位）。
+ *  - 本地 git 仓库路径 / file:// → git ls-remote <path> HEAD（离线）
+ *  - GitHub owner/repo、URL → git ls-remote https://github.com/o/r.git HEAD
+ *  - 无法识别 / git 不在 / 网络失败 → null（调用方标记「无法检查」）
+ */
+export async function resolveRemoteSha(spec, exec = execGit) {
+    const clean = String(spec ?? "").trim();
+    if (!clean)
+        return null;
+    let remote = null;
+    if (existsSync(clean)) {
+        remote = clean; // 本地 git 仓库路径
+    }
+    else if (/^file:\/\//i.test(clean)) {
+        remote = clean.slice("file://".length);
+    }
+    else {
+        // GitHub 形态（owner/repo、URL、git@）
+        let s = clean.replace(/^git@([^:]+):/, "");
+        const m = s.match(/^https?:\/\/(?:www\.)?github\.com\/(.+?)(?:\.git)?\/?$/i);
+        if (m)
+            [, s] = m;
+        s = s.split("#")[0]; // 去掉 #分支
+        const segs = s.split("/").filter(Boolean);
+        if (segs.length < 2)
+            return null;
+        // 只取 owner/repo（/tree/<ref>/<subpath> 等后缀不影响远端 sha）
+        const repo = segs[0] + "/" + segs[1].replace(/\.git$/, "");
+        remote = `https://github.com/${repo}.git`;
+    }
+    if (!remote)
+        return null;
+    const res = await exec("git", ["ls-remote", remote, "HEAD"]);
+    if (!res.ok)
+        return null;
+    // 行格式: <sha>\tHEAD（可能多行——取第一行）
+    const sha = (res.stdout.match(/^([0-9a-f]{40,64})\s+HEAD/m)?.[1]) ?? null;
+    return sha ? sha.slice(0, 12) : null;
+}
+/** 扫描全部已装插件，对比本地 sha 与远端 sha，报告更新状态。 */
+export async function checkPluginUpdates(dataDir, exec = execGit) {
+    const pluginsDir = join(dataDir, "plugins");
+    let names = [];
+    try {
+        names = readdirSync(pluginsDir).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        if (!PLUGIN_ID_RE.test(n))
+            continue;
+        const dir = join(pluginsDir, n);
+        try {
+            const sourceJson = readFileSync(join(dir, ".pi-source.json"), "utf8");
+            const { source } = JSON.parse(sourceJson);
+            if (!source)
+                continue; // 无来源记录（手工拷入）→ skip
+            let localSha = null;
+            try {
+                localSha = readFileSync(join(dir, ".pi-git-sha"), "utf8").trim() || null;
+            }
+            catch {
+                localSha = null; // 无 sha 记录 → 保守认为可更新（不知道装了哪个版本）
+            }
+            let remoteSha = null;
+            let error;
+            try {
+                remoteSha = await resolveRemoteSha(source, exec);
+            }
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+                remoteSha = null;
+            }
+            if (!remoteSha && !error)
+                error = "无法检查（非 git 源或 git 不可用）";
+            let name;
+            let version;
+            try {
+                const m = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+                name = m.name;
+                version = m.version;
+            }
+            catch {
+                /* 坏 manifest：仍报告 */
+            }
+            const updatable = !!remoteSha && (!localSha || localSha !== remoteSha);
+            out.push({
+                id: n,
+                name,
+                version,
+                source,
+                localSha,
+                remoteSha,
+                updatable,
+                error,
+            });
+        }
+        catch {
+            continue; // 坏目录跳过
+        }
+    }
+    return out;
+}
+/** Last stamp handed out, so the next one is always strictly greater. */
+let lastStampMs = 0;
+/**
+ * Backup directory name: `YYYYMMDD-HHMMSSmmm`.
+ *
+ * Monotonic on purpose. The name is the backup's only identity — two calls
+ * landing in the same millisecond produced the same directory, so the second
+ * cpSync() merged into the first instead of creating a new backup, silently
+ * losing one and leaving pruneBackups() keeping fewer than `keep`. Taking
+ * several backups in a row is fast enough that this is not theoretical: eight
+ * consecutive calls routinely share a millisecond.
+ *
+ * Colliding calls are pushed to the next millisecond rather than given a
+ * disambiguating suffix, because listBackups() matches names against a strict
+ * `\d{8}-\d{9}$` pattern — a suffixed backup would be invisible to it, and
+ * therefore never pruned either.
+ */
+function stamp() {
+    const now = Math.max(Date.now(), lastStampMs + 1);
+    lastStampMs = now;
+    const d = new Date(now);
+    const p = (x, n = 2) => String(x).padStart(n, "0");
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}${p(d.getMilliseconds(), 3)}`;
+}
+function dirnameOf(p) {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i >= 0 ? p.slice(0, i) : null;
+}