personal-bot 0.2.3 → 0.2.4

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 });
+    }
+}

package/lib/integrations/installation/processes.js

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { access, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+export async function findExecutable(name, env = process.env) {
+    const directories = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const directory of directories) {
+        const path = resolve(directory, name);
+        // npm exec prepends transient bins. Never use a cached peer as the user's Pi.
+        if (name === "pi" && path.split(/[\\/]/).includes("_npx"))
+            continue;
+        try {
+            await access(path, constants.X_OK);
+            if (!(await stat(path)).isFile())
+                continue;
+            const target = await realpath(path);
+            if (name === "pi" && target.split(/[\\/]/).includes("_npx"))
+                continue;
+            return path;
+        }
+        catch (error) {
+            if (!["ENOENT", "ENOTDIR", "EACCES"].includes(error.code ?? ""))
+                throw error;
+        }
+    }
+    return undefined;
+}
+export class SetupProcesses {
+    signal;
+    env;
+    constructor(signal, env = process.env) {
+        this.signal = signal;
+        this.env = env;
+    }
+    async run(command, args, cwd, options = {}) {
+        this.signal.throwIfAborted();
+        if (!isAbsolute(cwd))
+            throw new Error("进程工作目录必须是绝对路径。");
+        const interactive = options.interactive ?? false;
+        const timeoutMs = options.timeoutMs ?? (interactive ? 15 * 60_000 : 60_000);
+        return new Promise((resolveResult, reject) => {
+            const child = spawn(command, args, { cwd, env: this.env, shell: false, detached: !interactive,
+                stdio: interactive ? "inherit" : ["pipe", "pipe", "pipe"] });
+            const stdout = [], stderr = [];
+            let bytes = 0, failure, escalation;
+            const kill = (signal) => {
+                if (!child.pid)
+                    return;
+                try {
+                    if (interactive)
+                        child.kill(signal);
+                    else
+                        process.kill(-child.pid, signal);
+                }
+                catch { /* Process already exited. */ }
+            };
+            const stop = (reason) => {
+                if (failure)
+                    return;
+                failure = reason;
+                kill("SIGTERM");
+                escalation = setTimeout(() => kill("SIGKILL"), 2000);
+            };
+            const cancel = () => stop(new Error("安装已取消。"));
+            const timer = timeoutMs > 0 ? setTimeout(() => stop(new Error(`命令超时：${command}`)), timeoutMs) : undefined;
+            this.signal.addEventListener("abort", cancel, { once: true });
+            const collect = (chunks) => (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 2 * 1024 * 1024)
+                    stop(new Error(`命令输出超过限制：${command}`));
+                else
+                    chunks.push(chunk);
+            };
+            child.stdout?.on("data", collect(stdout));
+            child.stderr?.on("data", collect(stderr));
+            child.stdin?.on("error", () => { });
+            child.on("error", error => { failure = error; });
+            child.on("close", (code, exitSignal) => {
+                clearTimeout(timer);
+                clearTimeout(escalation);
+                this.signal.removeEventListener("abort", cancel);
+                if (this.signal.aborted)
+                    return reject(this.signal.reason);
+                if (failure)
+                    return reject(failure);
+                if (code !== 0)
+                    return reject(new Error(`${command} 失败 (${exitSignal ?? code})\n${Buffer.concat(stderr).toString("utf8").slice(-8000)}`));
+                resolveResult(Buffer.concat(stdout).toString("utf8").trim());
+            });
+            child.stdin?.end(options.input);
+            if (this.signal.aborted)
+                cancel();
+        });
+    }
+}
+export function tmuxInstallCommand(platform, commands, root) {
+    let command, args;
+    if (platform === "darwin") {
+        command = commands.get("brew");
+        args = ["install", "tmux"];
+    }
+    else {
+        const manager = ["apt-get", "dnf", "pacman", "zypper", "apk"].find(name => commands.has(name));
+        command = manager ? commands.get(manager) : undefined;
+        args = manager === "apt-get" ? ["install", "-y", "tmux"] : manager === "dnf" ? ["install", "-y", "tmux"]
+            : manager === "pacman" ? ["-S", "--needed", "--noconfirm", "tmux"]
+                : manager === "zypper" ? ["--non-interactive", "install", "tmux"] : ["add", "tmux"];
+        if (command && !root) {
+            const sudo = commands.get("sudo");
+            if (!sudo)
+                throw new Error("安装 tmux 需要管理员权限；请手动安装 tmux 后重新运行 setup。");
+            return { command: sudo, args: [command, ...args] };
+        }
+    }
+    if (!command)
+        throw new Error(platform === "darwin"
+            ? "未找到 Homebrew。请先通过现有环境安装 tmux，再运行 setup。"
+            : "未找到支持的系统包管理器。请手动安装 tmux，再运行 setup。");
+    return { command, args };
+}
+export async function inspectSystem(processes, cwd) {
+    if (!["linux", "darwin"].includes(process.platform))
+        throw new Error("setup 支持 Linux 和 macOS；Windows 请使用 WSL。");
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    if (major < 22 || major === 22 && minor < 19)
+        throw new Error("需要 Node.js 22.19 或更高版本。");
+    const npm = await findExecutable("npm", processes.env);
+    if (!npm)
+        throw new Error("未找到 npm。请先安装 Node.js/npm。");
+    const python = await findExecutable("python3", processes.env) ?? await findExecutable("python", processes.env);
+    if (!python)
+        throw new Error("需要 Python 3.11+ 和 venv/ensurepip。请先安装后重试。");
+    try {
+        await processes.run(python, ["-I", "-B", "-c", [
+                "import sys, tempfile, venv, ensurepip",
+                "assert sys.version_info >= (3, 11), 'Python 3.11+ required'",
+                "with tempfile.TemporaryDirectory(prefix='pbot-python-check-') as path:",
+                "    venv.EnvBuilder(with_pip=True).create(path)",
+            ].join("\n")], cwd);
+    }
+    catch (error) {
+        processes.signal.throwIfAborted();
+        throw new Error("基础 Python 检查失败。需要 Python 3.11+ 和 venv/ensurepip；Debian/Ubuntu 还需 python3-venv。\n" + String(error));
+    }
+    const tmux = await findExecutable("tmux", processes.env);
+    if (tmux) {
+        await processes.run(tmux, ["-V"], cwd);
+        return { npm };
+    }
+    const names = process.platform === "darwin" ? ["brew"] : ["apt-get", "dnf", "pacman", "zypper", "apk", "sudo"];
+    const entries = await Promise.all(names.map(async (name) => [name, await findExecutable(name, processes.env)]));
+    const commands = new Map(entries.filter((entry) => entry[1] !== undefined));
+    return { npm, tmux: tmuxInstallCommand(process.platform, commands, process.getuid?.() === 0) };
+}
+export function npmGlobalBinary(prefix) { return join(prefix, "bin", "pi"); }

package/lib/integrations/installation/workspace.js

@@ -0,0 +1,21 @@
+import { stat, realpath } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+export async function resolveWorkspace(value, cwd, home) {
+    const path = resolve(cwd, value === "~" ? home : value.startsWith("~/") ? join(home, value.slice(2)) : value);
+    let existing = path;
+    while (true) {
+        try {
+            if (!(await stat(existing)).isDirectory())
+                throw new Error("工作区或其父路径不是目录：" + existing);
+            return resolve(await realpath(existing), relative(existing, path));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = dirname(existing);
+            if (parent === existing)
+                throw error;
+            existing = parent;
+        }
+    }
+}