personal-bot 0.2.2 → 0.2.4

package/docs/validation.md

@@ -9,14 +9,16 @@ git diff --check
 npm pack --dry-run
 ```
 
-npm test 先构建 dist，再串行执行 Node 测试。测试使用真实本地文件、进程、计算与 Pi 1.4.0 SDK。Pi 开发依赖与相关传递组件统一锁定 1.4.0；宿主提供的包仍按 Pi 要求声明为 peer，不增加运行时副本。
+npm test 先构建测试导入 dist 和安装 CLI 的 lib，再串行执行 Node 测试。测试使用真实本地文件、进程、计算与 Pi 1.4.0 SDK。Pi 开发依赖与相关传递组件统一锁定 1.4.0；宿主提供的包声明为 optional peer，不增加运行时副本。发布包包含 bin/lib，扩展仍由 Pi 加载 src，dist 不进入发布包。
 
 | 范围 | 检查内容 |
 | --- | --- |
 | 领域与基础模块 | 工具契约、状态转换、版本兼容、原子保存和非法路径 |
+| tests/installation/ | 真实子进程、Pi 原生配置、来源与资源过滤保留、过期计划、CLI 打包入口、无模型认证时的初始化分发与拦截 |
 | tests/smoke/ | 实际 tarball 加载、资料准备、独立 Python setup 脚本 |
 | tests/e2e/ | Pi SDK/RPC 命令与工具、确认、持久化、重启和 Bash 环境继承 |
 | 专家协作 | 真实 tmux/Pi 进程、无任务待命、原 inbox、消息顺序、分支归属、通知领取和异常退出 |
+| 历史查询 | 真实 SDK 保存的问答、补充输入、工具过滤、分支隔离、四叉分组、原文与摘要搜索、正文分页、重载复用、空会话不误报、旧目录复制、跨目录读取、缺失原文时保留存档、旧路径清理、按会话 ID 重新关联与工具契约 |
 | 原生会话存储 | 真实 CLI 的默认 cwd 目录、settings/环境变量优先级、tmux 旧环境覆盖、空待命恢复、进入已停止会话不入队或重放旧任务、绝对路径绑定、身份检查、固定叶节点只读报告与旧布局保留 |
 | 团队协作 | 轮流顺序、并行上限与轮间汇合、暂停/领取、原文分页、并发保存、mixed 隐私边界与未知结果 |
 | 团队宿主接入 | Pi 1.4.0 的用户/custom 消息 before_agent_start、turn_end、原生 context 去重、子 reload 不重跑、窄通信工具与实例关闭 |
@@ -31,6 +33,19 @@ npm test 先构建 dist，再串行执行 Node 测试。测试使用真实本地
 
 Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python 说明](../python/README.md)。
 
+## 安装器验收（2026-11-03）
+
+本次实现完成以下验证。安装验收使用临时工作区与独立的用户目录、npm cache/prefix，不使用个人凭据或模型请求：
+
+- Linux、Node 24.15.0、npm 11.19.1、Pi SDK 1.4.0：`npm ci --ignore-scripts`、`npm run check`、`npm test` 全部通过，99 项测试无跳过；`npm pack --dry-run` 通过。
+- macOS、Node 24.22.2、npm 11.19.1：17 项安装测试通过；实际 tarball 的全局安装与 npm exec 均可执行 `pbot --version`，两种安装都未下载 Pi SDK。现有 Pi 1.5.0 managed launcher 与实际安装根目录的识别通过。
+- Linux 真实终端：从无 Pi 的独立 prefix 安装 Pi 1.5.0，再通过 Pi 安装 registry 的 pbot 0.2.3；重复运行、原生项目信任确认和不启动 Pi 的选择均成功。另将临时 Pi 安装为 1.4.0，确认 setup 通过原生 `pi update` 升级至 1.5.0。工作区仅有 `npm:personal-bot@latest` 声明，未选插件未安装，未直接创建 AGENTS.md。
+- 全局 npm 资源过滤的真实终端验收：工作区声明继承 `extensions: []` 和 `skills: []`，全局配置原文未变化，未启用被禁用的资源。
+- 本次打包的 pbot 与 Pi 1.5.0 SDK 完成 `/pbot init` 分发，创建资料且不调用模型；没有 pbot 时，保护扩展拦截未分发输入。共享 Python 环境使用真实的不可用临时目录，验证失败提示和资料初始化的独立性，不作为 Python 依赖安装成功的证据。
+- 系统 Python 缺少 ensurepip 时，真实 CLI 在安装软件前退出。正向终端验收使用已存在的 Python 3.13.13，没有更改系统 Python。服务器原有 npm 12.0.2 的 `npm ci` 未接受仓库 shrinkwrap，本次仓库回归使用临时安装的 npm 11.19.1，未更换服务器 npm。
+
+仍需验收 Homebrew/各 Linux 包管理器的提权与 tmux 实际安装、macOS 完整安装交互、Pi TUI 登录及模型选择、配套插件的外部服务与模型调用。同一工作区不应并发运行多个安装器；各原生包管理器不提供跨组件事务。全局 Git/本地来源与工作区 npm 来源发生身份冲突时，安装器保留现状并要求先用 Pi 原生配置调整加载范围，不自动移除全局来源。
+
 ## 已批准的真实模型冒烟（0.1.3）
 
 2026-10-28 在 Linux、Node.js 24.15.0、tmux 3.3a、Pi 1.1.0 下验收当时的 0.1.3 源码。0.2.0 改用原生会话位置及开发依赖升级至 Pi 1.4.0 后均未追加真实模型冒烟，以下结果不作为新布局或新宿主版本的模型验收。主会话与两个独立子进程均使用 openai-codex/gpt-6-astra、low 思考级别；复用同一对成员，roundRobin 和 parallel 各运行一轮。这是同型号多 agent 验收，不是异构模型组合验收。
@@ -57,12 +72,13 @@ Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python
 
 | 范围 | 验收重点 |
 | --- | --- |
+| 历史摘要 | 真实模型的摘要质量、递归汇总后按大意回溯、取消与恢复的实际模型请求、长会话扫描性能及人工浏览 |
 | 真实模型与专家 | 0.2.0 原生会话存储下的委派交付与认证模型恢复、运行中 steer/follow-up、独立复核、通知推进和实际用量 |
 | 真实模型团队 | 异构模型组合、三人及多轮讨论、并行轮间互相引用、自动重试/恢复、人工 mixed 输入、团队/私人工作切换、长时间运行及实际账单 |
 | Task Conductor | 实际多节点产物、至少两轮周期任务、Pi 关闭或重载后的查询与防重复提交 |
 | CLI/MCP | 认证、发现、重连、动态工具、取消与业务结果 |
 | TUI/RPC | 人工 attach、焦点、批准、查看器、长时间运行和会话导航 |
-| npm 分发 | 全新依赖安装、Pi 安装加载、OIDC 发布与公开 registry |
+| npm 分发 | 包含安装器的新版本 OIDC 发布、公开 registry 的 npx 入口与用户环境反馈 |
 | 平台与存储 | macOS 整体验收、断电持久性与文件系统差异 |
 
 研究与资料方法使用真实任务资料验收，重点检查来源追溯、口径一致、缺失数据处理、历史前提复核、产物引用和结项依据。知识沉淀需检查是否提炼方法与口径，以及后续任务能否据此重新取数。探索任务应区分实验失败与假设被否定。

package/lib/common/package-source.js

@@ -0,0 +1,16 @@
+import { prerelease, satisfies, valid } from "semver";
+export function npmName(source) {
+    return /^npm:((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(?:@[^\s]+)?$/.exec(source)?.[1];
+}
+export function ordinaryNpm(source) {
+    const name = npmName(source);
+    return name !== undefined && (source === `npm:${name}` || source === `npm:${name}@latest`);
+}
+export function checkStableVersion(version, nodeRange) {
+    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/lib/extension/setup-cli.js

@@ -0,0 +1,136 @@
+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 { 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) => "'" + value.replaceAll("'", "'\\''") + "'";
+export async function main(args) {
+    let options;
+    try {
+        options = parseSetupArgs(args);
+    }
+    catch (error) {
+        console.error(String(error));
+        return 2;
+    }
+    const manifest = JSON.parse(await readFile(new URL("package.json", root), "utf8"));
+    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;
+        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 = { 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/lib/extension/setup-guard.js

@@ -0,0 +1,11 @@
+// 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) {
+    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/lib/integrations/installation/pi-bridge.js

@@ -0,0 +1,131 @@
+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 { npmName } from "../../common/package-source.js";
+async function sdkAt(root) {
+    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);
+}
+const sourceOf = (entry) => {
+    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, workspace) {
+    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;
+            try {
+                content = readFileSync(file, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (content !== undefined) {
+                const value = JSON.parse(content);
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    throw new Error(`无效的 Pi 配置：${file}`);
+                const packages = value.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 = [];
+    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;
+        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"));
+                    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.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, workspace, old, target) {
+    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);
+        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; });
+}

package/lib/integrations/installation/pi-setup.js

@@ -0,0 +1,193 @@
+import { access, readFile, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { checkStableVersion, npmName } from "../../common/package-source.js";
+import { findExecutable, npmGlobalBinary, SetupProcesses } from "./processes.js";
+export const piPackageName = "@earendil-works/pi-coding-agent";
+export class PiBootstrapRequired extends Error {
+}
+const bridge = fileURLToPath(new URL("./pi-bridge.js", import.meta.url));
+const guard = fileURLToPath(new URL("../../extension/setup-guard.js", import.meta.url));
+async function packageRoot(command, version, env) {
+    const resolved = await realpath(command);
+    let directory = dirname(resolved);
+    while (true) {
+        try {
+            const pkg = JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+            if (pkg.name === piPackageName && pkg.version === version)
+                return directory;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    const roots = [join(dirname(dirname(resolved)), "install"), env.PI_MANAGED_INSTALL_ROOT].filter((root) => !!root);
+    for (const root of roots) {
+        try {
+            // The native managed launcher resides beside install/. Only accept a matching
+            // launcher, not an unrelated PI_MANAGED_INSTALL_ROOT inherited from another Pi.
+            const launcher = await realpath(join(dirname(root), "bin/pi"));
+            if (launcher !== resolved)
+                continue;
+            const current = (await readFile(join(root, "current-version"), "utf8")).trim();
+            if (current !== version || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(current))
+                continue;
+            const candidate = join(root, "releases", current, "node_modules", piPackageName);
+            const pkg = JSON.parse(await readFile(join(candidate, "package.json"), "utf8"));
+            if (pkg.name === piPackageName && pkg.version === version)
+                return candidate;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    throw new Error(`无法定位 ${command} 对应的 Pi 包。请先按此 Pi 的原生安装方式修复，不会覆盖该命令。`);
+}
+export class PiSetup {
+    processes;
+    npm;
+    cwd;
+    constructor(processes, npm, cwd) {
+        this.processes = processes;
+        this.npm = npm;
+        this.cwd = cwd;
+    }
+    async inspectPi(command) {
+        const executable = command ?? await findExecutable("pi", this.processes.env);
+        if (!executable)
+            return undefined;
+        const version = await this.processes.run(executable, ["--version"], this.cwd);
+        if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version))
+            throw new Error(`PATH 中的 ${executable} 不是可识别的 Pi。`);
+        return { command: executable, version, root: await packageRoot(executable, version, this.processes.env) };
+    }
+    async latest(name) {
+        const text = await this.processes.run(this.npm, ["view", `${name}@latest`, "version", "engines", "--json",
+            "--fetch-retries=0", "--fetch-timeout=15000"], this.cwd);
+        const value = JSON.parse(text);
+        if (typeof value.version !== "string")
+            throw new Error(`无法取得 ${name} 的最新版本。`);
+        return checkStableVersion(value.version, value.engines?.node);
+    }
+    async inspectPackages(pi, workspace) {
+        if (!pi) {
+            // A fresh machine can be planned without loading a Pi SDK. Existing declarations
+            // require Pi's own resolver; don't guess git cache paths or package identities.
+            const agentDir = this.processes.env.PI_CODING_AGENT_DIR ?? join(this.processes.env.HOME ?? homedir(), ".pi/agent");
+            for (const file of [join(agentDir, "settings.json"), join(workspace, ".pi/settings.json")]) {
+                try {
+                    const settings = JSON.parse(await readFile(file, "utf8"));
+                    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+                        throw new Error(`无效的 Pi 配置：${file}`);
+                    const packages = settings.packages;
+                    if (packages !== undefined && !Array.isArray(packages))
+                        throw new Error(`packages 必须是数组：${file}`);
+                    if (Array.isArray(packages) && packages.length > 0) {
+                        throw new PiBootstrapRequired(`已有插件配置但未找到 Pi：${file}`);
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+            return [];
+        }
+        const data = await this.processes.run(process.execPath, [bridge, "inspect", pi.root, workspace], this.cwd);
+        return JSON.parse(data);
+    }
+    async installTmux(command) {
+        await this.processes.run(command.command, command.args, this.cwd, { interactive: true });
+        const tmux = await findExecutable("tmux", this.processes.env);
+        if (!tmux)
+            throw new Error("tmux 安装后仍不在 PATH 中，请修复 PATH 后重试。");
+        await this.processes.run(tmux, ["-V"], this.cwd);
+    }
+    async ensurePi(existing, version) {
+        if (existing) {
+            if (existing.version !== version)
+                await this.processes.run(existing.command, ["update"], this.cwd, { interactive: true });
+            const installed = await this.inspectPi(existing.command);
+            if (!installed || installed.version !== version)
+                throw new Error(`Pi 实际版本 ${installed?.version ?? "未知"} 与目标 ${version} 不同。请用原安装方式更新后重试。`);
+            return installed;
+        }
+        const prefix = await this.processes.run(this.npm, ["prefix", "--global"], this.cwd);
+        if (!prefix || !prefix.startsWith("/"))
+            throw new Error("无法确定 npm 全局安装目录。");
+        try {
+            await access(prefix, constants.W_OK);
+        }
+        catch {
+            throw new Error(`npm 全局目录不可写：${prefix}。请先配置当前用户的 npm prefix 或 Node.js 版本管理器。`);
+        }
+        await this.processes.run(this.npm, ["install", "--global", "--ignore-scripts", "--engine-strict",
+            `${piPackageName}@${version}`], this.cwd, { interactive: true });
+        const installed = await this.inspectPi(npmGlobalBinary(prefix));
+        if (!installed || installed.version !== version)
+            throw new Error("Pi 安装版本验证失败。");
+        const onPath = await findExecutable("pi", this.processes.env);
+        if (!onPath || await realpath(onPath) !== await realpath(installed.command)) {
+            throw new Error(`Pi 已安装到 ${installed.command}，请把 ${join(prefix, "bin")} 加入 PATH 后重新运行 setup。`);
+        }
+        return installed;
+    }
+    async verifyKeptPackage(pi, workspace, choice) {
+        const old = choice.existing[0];
+        if (choice.existing.length !== 1 || !old)
+            throw new Error("保留来源不可用或存在多份来源，请先通过 pi config 处理。");
+        const current = (await this.inspectPackages(pi, workspace)).find(pkg => pkg.source === old.source && pkg.scope === old.scope);
+        if (!current?.installedPath || current.name !== npmName(choice.plugin.source) || JSON.stringify(current.entry) !== JSON.stringify(old.entry)) {
+            throw new Error("保留来源已变化或不可读取，请重新运行 setup。");
+        }
+        return current.source;
+    }
+    async installPackage(pi, workspace, choice) {
+        const name = npmName(choice.plugin.source);
+        if (!name || !choice.target)
+            throw new Error("缺少目标包或目标版本。");
+        // Re-read just before mutation so a stale plan cannot replace a changed source.
+        const current = (await this.inspectPackages(pi, workspace)).filter(pkg => pkg.name === name);
+        for (const old of choice.existing) {
+            const actual = current.find(pkg => pkg.scope === old.scope && pkg.source === old.source);
+            if (!actual || JSON.stringify(actual.entry) !== JSON.stringify(old.entry))
+                throw new Error(`${name} 配置已改变，请重新运行 setup。`);
+        }
+        if (current.some(pkg => !choice.existing.some(old => old.scope === pkg.scope && old.source === pkg.source) &&
+            !(pkg.scope === "user" && npmName(pkg.source) && choice.existing.some(old => old.scope === "project" && npmName(old.source))))) {
+            throw new Error(`${name} 出现新的来源，请重新运行 setup。`);
+        }
+        const otherSources = choice.existing.filter(pkg => !npmName(pkg.source));
+        if (otherSources.length > 1 || otherSources.some(pkg => pkg.scope === "user")) {
+            throw new Error("存在不同身份的全局来源或多份自定义来源。请先用 pi config 调整加载范围后重试。");
+        }
+        const globals = choice.existing.filter(pkg => pkg.scope === "user" && npmName(pkg.source));
+        if (globals.length > 1 && globals.some(pkg => pkg.filtered))
+            throw new Error("存在多份全局 npm 资源过滤，请先用 pi config 调整后重试。");
+        const template = otherSources[0] ?? globals.find(pkg => pkg.filtered);
+        const target = `npm:${name}@latest`;
+        await this.processes.run(pi.command, ["install", "--local", target], workspace, { interactive: true });
+        const records = await this.inspectPackages(pi, workspace);
+        const installed = records.find(pkg => pkg.scope === "project" && pkg.source === target);
+        if (!installed?.installedPath || installed.version !== choice.target) {
+            throw new Error(`${name} 实际版本 ${installed?.version ?? "未知"} 与目标 ${choice.target} 不同，请检查 registry 后重试。`);
+        }
+        if (template) {
+            await this.processes.run(process.execPath, [bridge, "replace", pi.root, workspace,
+                JSON.stringify({ old: template, target })], this.cwd);
+        }
+        return installed.version;
+    }
+    async start(pi, workspace) {
+        await access(guard, constants.R_OK);
+        await this.processes.run(pi.command, ["--extension", guard, "/pbot init"], resolve(workspace), { interactive: true, timeoutMs: 0 });
+    }
+}