personal-bot 0.2.3 → 0.2.4

package/lib/services/installation/setup-service.js

@@ -0,0 +1,121 @@
+import { npmName, ordinaryNpm } from "../../common/package-source.js";
+export const pbotPackage = {
+    id: "pbot", label: "Personal Bot", description: "工作区个人助手", source: "npm:personal-bot", defaultSelected: true,
+};
+export function parseCatalog(value) {
+    if (!Array.isArray(value))
+        throw new Error("插件清单必须是数组。");
+    const ids = new Set(["pbot"]), names = new Set(["personal-bot"]);
+    return value.map((item) => {
+        if (!item || typeof item !== "object")
+            throw new Error("无效插件清单项。");
+        const entry = item;
+        for (const field of ["id", "label", "description", "source"]) {
+            if (typeof entry[field] !== "string" || !entry[field].trim() || /[\x00-\x1f\x7f]/.test(entry[field])) {
+                throw new Error(`无效插件字段：${field}`);
+            }
+        }
+        const plugin = entry;
+        const name = npmName(plugin.source);
+        if (!/^[a-z0-9-]+$/.test(plugin.id) || !name || !ordinaryNpm(plugin.source) ||
+            typeof plugin.defaultSelected !== "boolean" || ids.has(plugin.id) || names.has(name)) {
+            throw new Error(`无效或重复的插件：${plugin.id}`);
+        }
+        ids.add(plugin.id);
+        names.add(name);
+        return { id: plugin.id, label: plugin.label, description: plugin.description,
+            source: `npm:${name}`, defaultSelected: plugin.defaultSelected };
+    });
+}
+export function packageChoices(catalog, installed) {
+    const first = !installed.some(pkg => pkg.name === "personal-bot");
+    return [pbotPackage, ...catalog].map(plugin => {
+        const matches = installed.filter(pkg => pkg.name === npmName(plugin.source));
+        // A project npm entry overrides the same npm identity in user settings. Different
+        // git/local identities still need an explicit decision before changing sources.
+        const localNpm = matches.some(pkg => pkg.scope === "project" && npmName(pkg.source));
+        const existing = matches.filter(pkg => !(localNpm && pkg.scope === "user" && npmName(pkg.source)));
+        const custom = existing.some(pkg => !ordinaryNpm(pkg.source));
+        return { plugin, required: plugin.id === "pbot", existing,
+            selected: plugin.id === "pbot" || (first ? plugin.defaultSelected : existing.length > 0), keep: custom };
+    });
+}
+export function parseSetupArgs(args) {
+    if (!args.length || args.length === 1 && ["--help", "-h"].includes(args[0]))
+        return { action: "help" };
+    if (args.length === 1 && ["--version", "-v"].includes(args[0]))
+        return { action: "version" };
+    if (args[0] !== "setup")
+        throw new Error("用法：pbot setup [--workspace <目录>]");
+    let workspace;
+    for (let index = 1; index < args.length; index++) {
+        const arg = args[index];
+        if ((arg === "--help" || arg === "-h") && args.length === 2)
+            return { action: "help" };
+        if (arg !== "--workspace" || workspace !== undefined)
+            throw new Error(`不支持的参数：${arg}`);
+        const value = args[++index];
+        if (!value || value.startsWith("--") || /[\x00-\x1f\x7f]/.test(value))
+            throw new Error("--workspace 需要目录。");
+        workspace = value;
+    }
+    return workspace === undefined ? { action: "setup" } : { action: "setup", workspace };
+}
+export async function executeSetup(plan, operations, report, signal) {
+    const results = [];
+    const add = (result) => { results.push(result); report(result); };
+    let pi;
+    try {
+        signal.throwIfAborted();
+        if (plan.tmux) {
+            await operations.installTmux(plan.tmux);
+            add({ name: "tmux", state: "done", detail: "已安装" });
+        }
+        signal.throwIfAborted();
+        pi = await operations.ensurePi(plan.pi, plan.piVersion);
+        add({ name: "Pi", state: "done", detail: pi.version });
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        add({ name: "运行环境", state: "failed", detail: String(error) });
+        return { results };
+    }
+    for (const choice of plan.packages) {
+        signal.throwIfAborted();
+        const name = choice.plugin.label;
+        if (!choice.selected) {
+            add({ name, state: "skipped", detail: "本次不处理" });
+            continue;
+        }
+        if (choice.error) {
+            add({ name, state: "failed", detail: choice.error });
+            if (choice.required)
+                return { results };
+            continue;
+        }
+        if (choice.keep) {
+            try {
+                const source = await operations.verifyKeptPackage(pi, plan.workspace, choice);
+                add({ name, state: "kept", detail: source });
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                add({ name, state: "failed", detail: String(error) });
+                if (choice.required)
+                    return { results };
+            }
+            continue;
+        }
+        try {
+            const version = await operations.installPackage(pi, plan.workspace, choice);
+            add({ name, state: "done", detail: version });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            add({ name, state: "failed", detail: String(error) });
+            if (choice.required)
+                return { results };
+        }
+    }
+    return { pi, results };
+}

package/lib/ui/setup.js

@@ -0,0 +1,52 @@
+import { createInterface } from "node:readline/promises";
+export class SetupUI {
+    controller;
+    constructor(controller) {
+        this.controller = controller;
+    }
+    text(value) { console.log(value); }
+    async ask(label, fallback = "") {
+        this.controller.signal.throwIfAborted();
+        const reader = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        reader.on("SIGINT", () => this.controller.abort(new Error("安装已取消。")));
+        reader.on("close", () => { if (!answered)
+            this.controller.abort(new Error("输入已关闭。")); });
+        let answered = false;
+        try {
+            const value = await reader.question(label + (fallback ? " [" + fallback + "]" : "") + ": ", { signal: this.controller.signal });
+            answered = true;
+            return value.trim() || fallback;
+        }
+        finally {
+            answered = true;
+            reader.close();
+        }
+    }
+    async confirm(label, fallback = true) {
+        while (true) {
+            const answer = (await this.ask(label + (fallback ? " [Y/n]" : " [y/N]"))).toLowerCase();
+            if (!answer)
+                return fallback;
+            if (["y", "yes", "是"].includes(answer))
+                return true;
+            if (["n", "no", "否"].includes(answer))
+                return false;
+            this.text("请输入 y 或 n。");
+        }
+    }
+    async selectMany(labels, defaults) {
+        labels.forEach((label, index) => this.text("  " + (defaults.includes(index) ? "[x] " : "[ ] ") + (index + 1) + ". " + label));
+        while (true) {
+            const answer = await this.ask("选择插件编号（逗号分隔，回车保留默认，0 不选）");
+            if (!answer)
+                return defaults;
+            if (answer === "0")
+                return [];
+            const parts = answer.split(/[,，\s]+/);
+            if (parts.every(part => /^\d+$/.test(part) && Number(part) >= 1 && Number(part) <= labels.length)) {
+                return [...new Set(parts.map(part => Number(part) - 1))];
+            }
+            this.text("请输入列表中的编号。");
+        }
+    }
+}

package/npm-shrinkwrap.json

@@ -1,21 +1,26 @@
 {
   "name": "personal-bot",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "personal-bot",
-      "version": "0.2.3",
+      "version": "0.2.4",
       "dependencies": {
         "ajv": "8.17.1",
-        "ajv-formats": "3.0.1"
+        "ajv-formats": "3.0.1",
+        "semver": "7.8.5"
+      },
+      "bin": {
+        "pbot": "bin/pbot.mjs"
       },
       "devDependencies": {
         "@earendil-works/pi-ai": "1.4.0",
         "@earendil-works/pi-coding-agent": "1.4.0",
         "@earendil-works/pi-tui": "1.4.0",
         "@types/node": "24.10.1",
+        "@types/semver": "7.7.1",
         "dependency-cruiser": "18.5.0",
         "typebox": "1.3.27",
         "typescript": "5.9.3"
@@ -28,6 +33,20 @@
         "@earendil-works/pi-coding-agent": "*",
         "@earendil-works/pi-tui": "*",
         "typebox": "*"
+      },
+      "peerDependenciesMeta": {
+        "@earendil-works/pi-ai": {
+          "optional": true
+        },
+        "@earendil-works/pi-coding-agent": {
+          "optional": true
+        },
+        "@earendil-works/pi-tui": {
+          "optional": true
+        },
+        "typebox": {
+          "optional": true
+        }
       }
     },
     "node_modules/@anthropic-ai/sdk": {
@@ -759,6 +778,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/semver": {
+      "version": "7.7.1",
+      "resolved": "https://registry.npmmirror.com/@types/semver/-/semver-7.7.1.tgz",
+      "integrity": "sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/acorn": {
       "version": "8.18.0",
       "resolved": "https://registry.npmmirror.com/acorn/-/acorn-8.18.0.tgz",
@@ -1965,7 +1991,6 @@
       "version": "7.8.5",
       "resolved": "https://registry.npmmirror.com/semver/-/semver-7.8.5.tgz",
       "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
-      "dev": true,
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "personal-bot",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/realqiyan/personal-bot.git"
@@ -12,6 +12,9 @@
   },
   "description": "A personal assistant connecting knowledge, research, and action. Currently implemented as a Pi extension.",
   "type": "module",
+  "bin": {
+    "pbot": "./bin/pbot.mjs"
+  },
   "keywords": [
     "pi-package"
   ],
@@ -25,6 +28,8 @@
   },
   "files": [
     "npm-shrinkwrap.json",
+    "bin",
+    "lib",
     "src",
     "resources",
     "scripts/setup-python.py",
@@ -42,11 +47,12 @@
   "scripts": {
     "check": "tsc --noEmit && npm run check:dependencies",
     "check:dependencies": "depcruise --config .dependency-cruiser.cjs src",
-    "build": "node scripts/clean-dist.mjs && tsc",
+    "build": "node scripts/clean-dist.mjs && tsc && npm run build:cli",
+    "build:cli": "node scripts/build-cli.mjs",
     "test": "npm run build && node --test --test-concurrency=1 tests/*/*.test.mjs",
     "test:smoke": "npm run build && node --test --test-concurrency=1 tests/smoke/*.test.mjs",
     "test:e2e": "npm run build && node --test --test-concurrency=1 tests/e2e/*.test.mjs",
-    "prepack": "npm run check"
+    "prepack": "npm run check && npm run build:cli"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -54,15 +60,31 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "ajv": "8.17.1",
-    "ajv-formats": "3.0.1"
+    "ajv-formats": "3.0.1",
+    "semver": "7.8.5"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.4.0",
     "@earendil-works/pi-coding-agent": "1.4.0",
     "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "24.10.1",
+    "@types/semver": "7.7.1",
     "dependency-cruiser": "18.5.0",
     "typebox": "1.3.27",
     "typescript": "5.9.3"

package/resources/installer/plugins.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "task-conductor",
+    "label": "Task Conductor",
+    "description": "周期任务、流程和 DAG 的接入与使用引导；服务另行准备",
+    "source": "npm:task-conductor-plugin",
+    "defaultSelected": true
+  },
+  {
+    "id": "web-access",
+    "label": "Pi Web Access",
+    "description": "网页搜索与内容获取",
+    "source": "npm:pi-web-access",
+    "defaultSelected": true
+  }
+]

package/scripts/README.md

@@ -6,6 +6,10 @@
 
 脚本不接受解释器路径，不修改工作区资料或历史记录。路径、激活和失败处理见 [Python 说明](../python/README.md)。
 
+## 安装 CLI 构建
+
+`npm run build:cli` 调用 `build-cli.mjs`，清理生成目录 lib，再按 tsconfig.cli.json 编译独立 CLI、Pi 检查桥接和启动保护。bin/pbot.mjs 转交已生成的入口。npm test 的构建与 prepack 都执行此步骤；扩展运行仍由 Pi 加载 src 源码。消费者直接使用发布包中的 lib，无需安装开发依赖。
+
 ## 构建清理
 
 `clean-dist.mjs` 由 npm run build 调用，仅清理仓库内生成的 dist/，供 TypeScript 重新编译测试导入。

package/src/common/package-source.ts

@@ -0,0 +1,16 @@
+import { prerelease, satisfies, valid } from "semver";
+
+export function npmName(source: string): string | undefined {
+  return /^npm:((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(?:@[^\s]+)?$/.exec(source)?.[1];
+}
+export function ordinaryNpm(source: string): boolean {
+  const name = npmName(source);
+  return name !== undefined && (source === `npm:${name}` || source === `npm:${name}@latest`);
+}
+export function checkStableVersion(version: string, nodeRange?: string): string {
+  if (!valid(version) || prerelease(version)) throw new Error(`latest 不是稳定版本：${version}`);
+  if (nodeRange && !satisfies(process.versions.node, nodeRange)) {
+    throw new Error(`目标版本要求 Node.js ${nodeRange}，当前为 ${process.versions.node}。请先升级 Node.js。`);
+  }
+  return version;
+}

package/src/extension/setup-cli.ts

@@ -0,0 +1,109 @@
+import { mkdir, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { executeSetup, packageChoices, parseCatalog, parseSetupArgs } from "../services/installation/setup-service.js";
+import { npmName, ordinaryNpm } from "../common/package-source.js";
+import type { InstalledPackage, SetupPlan } from "../services/installation/setup-service.js";
+import { PiBootstrapRequired, PiSetup, piPackageName } from "../integrations/installation/pi-setup.js";
+import { inspectSystem, SetupProcesses } from "../integrations/installation/processes.js";
+import { resolveWorkspace } from "../integrations/installation/workspace.js";
+import { SetupUI } from "../ui/setup.js";
+
+const root = new URL("../../", import.meta.url);
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+
+export async function main(args: string[]): Promise<number> {
+  let options: ReturnType<typeof parseSetupArgs>;
+  try { options = parseSetupArgs(args); }
+  catch (error) { console.error(String(error)); return 2; }
+  const manifest = JSON.parse(await readFile(new URL("package.json", root), "utf8")) as { version: string };
+  if (options.action === "version") { console.log(manifest.version); return 0; }
+  if (options.action === "help") {
+    console.log("Personal Bot " + manifest.version + "\n\n用法：pbot setup [--workspace <目录>]\n" +
+      "      npx personal-bot@latest setup\n\nsetup 安装或升级 Pi、pbot 和选中的插件，然后启动 Pi 执行 /pbot init。\n" +
+      "支持 Linux/macOS，需要 Node.js 22.19+、npm 和 Python 3.11+。\n--help 显示帮助；--version 显示安装器版本。");
+    return 0;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error("setup 需要交互终端。请在终端运行 npx personal-bot@latest setup。"); return 2;
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort(new Error("安装已取消；已完成的步骤保留。"));
+  process.on("SIGINT", cancel); process.on("SIGTERM", cancel);
+  const ui = new SetupUI(controller), processes = new SetupProcesses(controller.signal);
+  try {
+    const cwd = process.cwd();
+    ui.text("Personal Bot " + manifest.version + " — 安装与升级\n正在检查 Node/npm、Python 和 tmux…");
+    const system = await inspectSystem(processes, cwd);
+    const supplied = options.workspace ?? await ui.ask("工作区目录（当前、已有或新建目录）", cwd);
+    const workspace = await resolveWorkspace(supplied, cwd, homedir());
+    const host = new PiSetup(processes, system.npm, cwd);
+    let pi = await host.inspectPi();
+    let installed: InstalledPackage[];
+    try { installed = await host.inspectPackages(pi, workspace); }
+    catch (error) {
+      if (!(error instanceof PiBootstrapRequired)) throw error;
+      const version = await host.latest(piPackageName);
+      ui.text(error.message + "\n需先安装 Pi 才能使用其原生接口核对这些来源。目标版本：" + version);
+      if (!await ui.confirm("先通过 npm 安装 Pi，再继续选择工作区插件")) return 130;
+      pi = await host.ensurePi(undefined, version);
+      installed = await host.inspectPackages(pi, workspace);
+    }
+    const catalog = parseCatalog(JSON.parse(await readFile(new URL("resources/installer/plugins.json", root), "utf8")));
+    const choices = packageChoices(catalog, installed), optional = choices.filter(choice => !choice.required);
+    ui.text("\nPersonal Bot 必装。选择配套插件（取消勾选不会卸载已有插件）：");
+    const selected = await ui.selectMany(optional.map(choice => choice.plugin.label + " — " + choice.plugin.description),
+      optional.flatMap((choice, index) => choice.selected ? [index] : []));
+    optional.forEach((choice, index) => { choice.selected = selected.includes(index); });
+    for (const choice of choices.filter(item => item.selected)) {
+      if (choice.existing.some(pkg => !ordinaryNpm(pkg.source))) {
+        ui.text("\n" + choice.plugin.label + " 的已有来源：\n" + choice.existing.map(pkg =>
+          "  " + pkg.scope + ": " + pkg.source + " (" + (pkg.version ?? "版本未知") + ")").join("\n"));
+        choice.keep = !await ui.confirm("切换到 npm 最新稳定版", false);
+      }
+      if (choice.keep) {
+        if (choice.existing.length !== 1 || !choice.existing[0]?.installedPath) choice.error = "保留来源未安装或存在多份来源，请先通过 Pi 原生配置处理。";
+      } else {
+        const others = choice.existing.filter(pkg => !npmName(pkg.source));
+        if (others.length > 1 || others.some(pkg => pkg.scope === "user")) {
+          choice.error = "请先用 pi config 调整全局或重复来源的加载范围，再切换到 npm。";
+        } else {
+          try { choice.target = await host.latest(npmName(choice.plugin.source)!); }
+          catch (error) { controller.signal.throwIfAborted(); choice.error = String(error); }
+        }
+      }
+    }
+    const plan: SetupPlan = { workspace, piVersion: await host.latest(piPackageName), packages: choices,
+      ...(pi ? { pi } : {}), ...(system.tmux ? { tmux: system.tmux } : {}) };
+    ui.text("\n安装计划\n工作区：" + workspace + "\nPi：" + (pi ? pi.command + " (" + pi.version + ")" : "通过 npm 全局安装") + " → " + plan.piVersion);
+    if (system.tmux) ui.text("tmux：" + [system.tmux.command, ...system.tmux.args].map(quote).join(" "));
+    for (const choice of choices) {
+      ui.text("  " + choice.plugin.label + ": " + (!choice.selected ? "本次跳过" : choice.error ??
+        (choice.keep ? "保留 " + choice.existing[0]?.source : (choice.existing.map(pkg => pkg.version ?? "未知").join(", ") || "未安装") + " → " + choice.target)));
+      if (choice.selected && choice.existing.some(pkg => pkg.filtered)) ui.text("    保留已有资源过滤；如 pbot 被禁用，请通过 pi config --local 启用。");
+    }
+    const blocking = choices.find(choice => choice.required && choice.error);
+    if (blocking) throw new Error(blocking.error);
+    ui.text("升级前请停止活动 pbot 子会话和相关 Python 脚本。Pi 为当前用户共用，插件只处理此工作区。");
+    if (!await ui.confirm("执行以上计划")) return 130;
+    await mkdir(workspace, { recursive: true });
+    if (await realpath(workspace) !== workspace) throw new Error("工作区路径已发生变化，请重新运行 setup。");
+    const result = await executeSetup(plan, host, item => ui.text("[" + item.state + "] " + item.name + ": " + item.detail), controller.signal);
+    const failed = result.results.some(item => item.state === "failed");
+    if (!result.pi) return 1;
+    ui.text("\n软件安装阶段结束。初始化、Python 环境和外部服务的状态由 Pi/pbot/插件分别报告。");
+    if (await ui.confirm(failed ? "部分插件失败，是否仍先启动 Pi" : "立即启动 Pi", !failed)) {
+      process.stdin.pause();
+      await host.start(result.pi, workspace);
+    } else {
+      ui.text("稍后执行：\ncd " + quote(workspace) + "\n" + quote(result.pi.command) + " --extension " +
+        quote(fileURLToPath(new URL("extension/setup-guard.js", new URL("../", import.meta.url)))) + " '/pbot init'");
+    }
+    return failed ? 1 : 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return controller.signal.aborted ? 130 : 1;
+  } finally {
+    process.off("SIGINT", cancel); process.off("SIGTERM", cancel);
+  }
+}

package/src/extension/setup-guard.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Native extension commands run before input handlers. Reaching this handler for
+// /pbot init means it was not dispatched; never let the setup input reach a model.
+export default function setupGuard(pi: ExtensionAPI) {
+  pi.on("input", (event, ctx) => {
+    if (event.text.trim() !== "/pbot init") return { action: "continue" };
+    ctx.ui.notify("pbot 未加载或命令存在冲突。请检查项目信任和 pi config --local 后重新运行 setup。", "error");
+    ctx.shutdown();
+    return { action: "handled" };
+  });
+}

package/src/integrations/installation/pi-bridge.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { InstalledPackage } from "../../services/installation/setup-service.js";
+import { npmName } from "../../common/package-source.js";
+
+type PiSdk = typeof import("@earendil-works/pi-coding-agent");
+async function sdkAt(root: string): Promise<PiSdk> {
+  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+  if (manifest.name !== "@earendil-works/pi-coding-agent") throw new Error("不是支持的 Pi 安装。");
+  return import(pathToFileURL(join(root, "dist/index.js")).href) as Promise<PiSdk>;
+}
+const sourceOf = (entry: unknown): string => {
+  if (typeof entry === "string") return entry;
+  if (entry && typeof entry === "object" && "source" in entry && typeof entry.source === "string") return entry.source;
+  throw new Error("无效的 Pi packages 声明。");
+};
+
+export async function inspectPackages(root: string, workspace: string): Promise<InstalledPackage[]> {
+  const sdk = await sdkAt(root), agentDir = sdk.getAgentDir();
+  // Inspect project declarations as data only. This does not load extensions, execute
+  // project npmCommand, grant project trust, or persist migrated settings.
+  const settings = sdk.SettingsManager.fromStorage({ withLock(scope, read) {
+    const file = scope === "global" ? join(agentDir, "settings.json") : join(workspace, sdk.CONFIG_DIR_NAME, "settings.json");
+    let content: string | undefined;
+    try { content = readFileSync(file, "utf8"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (content !== undefined) {
+      const value: unknown = JSON.parse(content);
+      if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`无效的 Pi 配置：${file}`);
+      const packages = (value as { packages?: unknown }).packages;
+      if (packages !== undefined) {
+        if (!Array.isArray(packages)) throw new Error(`packages 必须是数组：${file}`);
+        packages.forEach(sourceOf);
+      }
+    }
+    if (read(content) !== undefined) throw new Error("安装检查不得修改 Pi 配置。");
+  } }, { projectTrusted: true });
+  const errors = settings.drainErrors();
+  if (errors.length) throw new Error(errors.map(item => `${item.scope}: ${item.error.message}`).join("\n"));
+  const manager = new sdk.DefaultPackageManager({ cwd: workspace, agentDir, settingsManager: settings });
+  const result: InstalledPackage[] = [];
+  for (const pkg of manager.listConfiguredPackages()) {
+    const entries = (pkg.scope === "project" ? settings.getProjectSettings() : settings.getGlobalSettings()).packages ?? [];
+    const entry = entries.find(item => sourceOf(item) === pkg.source);
+    let name = npmName(pkg.source), version: string | undefined;
+    if (pkg.installedPath) {
+      let file = pkg.installedPath;
+      if ((await stat(file)).isDirectory()) file = join(file, "package.json");
+      else file = ""; // Single-file extensions have no npm identity.
+      if (file) {
+        try {
+          const manifest = JSON.parse(await readFile(file, "utf8")) as { name?: string; version?: string };
+          if (name && manifest.name !== name) throw new Error(`安装包身份不匹配：${pkg.source}`);
+          name = typeof manifest.name === "string" ? manifest.name : name;
+          version = typeof manifest.version === "string" ? manifest.version : undefined;
+        } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      }
+    }
+    result.push({ source: pkg.source, scope: pkg.scope, filtered: pkg.filtered, entry,
+      ...(pkg.installedPath ? { installedPath: pkg.installedPath } : {}), ...(name ? { name } : {}), ...(version ? { version } : {}) });
+  }
+  return result;
+}
+
+export async function replaceProjectSource(root: string, workspace: string, old: InstalledPackage, target: string): Promise<void> {
+  const fromProject = old.scope === "project" && !npmName(old.source);
+  const fromUser = old.scope === "user" && !!npmName(old.source);
+  if (!fromProject && !fromUser) throw new Error("此操作只替换工作区自定义来源，或继承全局 npm 资源过滤。");
+  const sdk = await sdkAt(root);
+  const settings = sdk.SettingsManager.create(workspace, sdk.getAgentDir(), { projectTrusted: true });
+  const errors = settings.drainErrors();
+  if (errors.length) throw new Error(errors.map(item => item.error.message).join("\n"));
+  const packages = settings.getProjectSettings().packages ?? [];
+  const originals = fromProject ? packages : settings.getGlobalSettings().packages ?? [];
+  const previous = originals.find(entry => sourceOf(entry) === old.source);
+  if (previous === undefined || JSON.stringify(previous) !== JSON.stringify(old.entry)) throw new Error("插件配置已发生变化，请重新运行 setup。");
+  if (!packages.some(entry => sourceOf(entry) === target)) throw new Error("目标包尚未安装，保留原声明。");
+  const manager = new sdk.DefaultPackageManager({ cwd: workspace, agentDir: sdk.getAgentDir(), settingsManager: settings });
+  const installed = manager.getInstalledPath(target, "project");
+  if (!installed || !npmName(target)) throw new Error("目标 npm 包尚未安装，保留原声明。");
+  const manifest = JSON.parse(await readFile(join(installed, "package.json"), "utf8"));
+  if (manifest.name !== npmName(target)) throw new Error("目标安装包身份不符，保留原声明。");
+  // Change only declarations; do not call remove(), which deletes managed git caches.
+  const replacement = typeof previous === "string" ? target : { ...previous, source: target };
+  const next = fromProject
+    ? packages.filter(entry => sourceOf(entry) !== target).map(entry => sourceOf(entry) === old.source ? replacement : entry)
+    : packages.map(entry => sourceOf(entry) === target ? replacement : entry);
+  settings.setProjectPackages(next);
+  await settings.flush();
+  const failures = settings.drainErrors();
+  if (failures.length) throw new Error(failures.map(item => item.error.message).join("\n"));
+}
+
+async function main() {
+  const [action, root, workspace, input] = process.argv.slice(2);
+  if (!root || !workspace) throw new Error("缺少 Pi 路径或工作区。");
+  if (action === "inspect") console.log(JSON.stringify(await inspectPackages(root, workspace)));
+  else if (action === "replace" && input) {
+    const { old, target } = JSON.parse(input) as { old: InstalledPackage; target: string };
+    await replaceProjectSource(root, workspace, old, target);
+  } else throw new Error("无效的安装检查操作。");
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}