personal-bot 0.2.3 → 0.2.5

package/lib/integrations/dsh/messages.js

@@ -0,0 +1,11 @@
+import { lastAssistantStreamChunk } from "@deepseek-ai/dsh-llm";
+export function finalDshAnswer(event) {
+    const { message, interrupted, stream } = event.data;
+    if (interrupted || message.content.some(block => block.type === "tool-call") || lastAssistantStreamChunk(stream, "finish")?.reason.kind !== "stop")
+        return "";
+    return message.content.filter(block => block.type === "text").map(block => block.text).join("\n");
+}
+export function requestSource(message, generation) {
+    const source = message.source;
+    return source.kind === "pbot-input" && source.generation === generation ? source : undefined;
+}

package/lib/integrations/dsh/notifications.d.ts

@@ -0,0 +1,8 @@
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+import type { UserMessage } from "@deepseek-ai/dsh-llm";
+import "./messages.js";
+/** Only committed native context or successful model tool results claim notices.
+ * PTC inner reads require their enclosing transport to have committed success. */
+export declare function deliveredDshNotices(events: readonly SessionEvent[]): Set<string>;
+/** Pending inbox entries prevent duplicate submission, but are not delivery receipts. */
+export declare function pendingDshNotices(messages: readonly UserMessage[]): string[];

package/lib/integrations/dsh/notifications.js

@@ -0,0 +1,55 @@
+import { object } from "../../common/json.js";
+import "./messages.js";
+function keys(value, field) {
+    if (!object(value))
+        return [];
+    const items = value[field];
+    return Array.isArray(items) && items.every(item => typeof item === "string") ? items : [];
+}
+/** Only committed native context or successful model tool results claim notices.
+ * PTC inner reads require their enclosing transport to have committed success. */
+export function deliveredDshNotices(events) {
+    const delivered = new Set();
+    const reads = new Set(), nested = new Map();
+    for (const event of events) {
+        if (event.type === "turn/start" || event.type === "step/start" || event.type === "turn/end") {
+            reads.clear();
+            nested.clear();
+        }
+        if (event.type === "user/message" && event.data.source.kind === "pbot-results") {
+            for (const key of keys(event.data.source, "keys"))
+                delivered.add(key);
+        }
+        if (event.type === "tool/call" && event.data.name === "pbot_agent") {
+            try {
+                const args = JSON.parse(event.data.arguments);
+                if (object(args) && args.action === "read")
+                    reads.add(event.data.callId);
+            }
+            catch { /* An invalid call cannot claim a report. */ }
+        }
+        if (event.type === "tool/ptc-dispatch" && event.data.name === "pbot_agent" && !event.data.isError &&
+            object(event.data.arguments) && event.data.arguments.action === "read") {
+            const values = nested.get(event.data.rootCallId) ?? [];
+            values.push(...keys(event.data.meta, "pbotAgentReadKeys"));
+            nested.set(event.data.rootCallId, values);
+        }
+        if (event.type === "tool/result") {
+            const message = event.data.message;
+            if (!message.isError) {
+                if (reads.has(message.toolCallId))
+                    for (const key of keys(event.data.meta, "pbotAgentReadKeys"))
+                        delivered.add(key);
+                for (const key of nested.get(message.toolCallId) ?? [])
+                    delivered.add(key);
+            }
+            reads.delete(message.toolCallId);
+            nested.delete(message.toolCallId);
+        }
+    }
+    return delivered;
+}
+/** Pending inbox entries prevent duplicate submission, but are not delivery receipts. */
+export function pendingDshNotices(messages) {
+    return messages.flatMap(message => message.source.kind === "pbot-results" ? keys(message.source, "keys") : []);
+}

package/lib/integrations/dsh/resources.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { AgentOptions } from "../../model/agent.js";
+export declare function dshResources(ctx: Context, agent: Agent, root: string, role: "coordinator" | "general-purpose", python: () => {
+    state: string;
+    directory?: string;
+    error?: string;
+}, check: () => void): Promise<void>;
+/** Map the expert's native loadout; this is not isolation from Bash, CLI, or MCP. */
+export declare function dshExpertTools(ctx: Context, agent: Agent, options: AgentOptions): boolean;

package/lib/integrations/dsh/resources.js

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+import { agentText } from "../agent-resources.js";
+import { resourceRoot } from "../../common/paths.js";
+import { requireThat } from "../../common/validation.js";
+export async function dshResources(ctx, agent, root, role, python, check) {
+    let text = await agentText(role, root);
+    const workspace = await readFile(join(resourceRoot, "prompts/workspace.md"), "utf8");
+    check();
+    ctx.systemPrompt.section({ name: "pbot:role", order: 1, text: () => text, interpolate: false });
+    ctx.systemPrompt.section({ name: "pbot:workspace", order: 2, text: workspace, interpolate: false });
+    ctx.systemPrompt.context({ name: "pbot:environment", order: 300, required: true, interpolate: false,
+        text: () => JSON.stringify({ host: "dsh", workspaceRoot: root, cwd: ctx.workingDirectory.get(agent.session), resourceRoot, python: python() }) });
+    ctx.skills.registerProvider(control => new FileSystemSkillProvider(ctx, control, {
+        providerName: "pbot", includeDefaultRoots: false, customSkillDirs: [join(root, ".agents/skills")],
+        bundledSkillDir: join(resourceRoot, "skills"), watch: false,
+    }));
+    ctx.on("agent/pre-step", async (_payload, next) => {
+        check();
+        text = await agentText(role, root);
+        check();
+        return next();
+    });
+}
+/** Map the expert's native loadout; this is not isolation from Bash, CLI, or MCP. */
+export function dshExpertTools(ctx, agent, options) {
+    const names = new Set(ctx.tools.definitions(agent).map(tool => tool.name));
+    const forbidden = new Set(["pbot_agent", "pbot_team", "pbot_history", "subagent", "list_subagent_models", "list_agents", "send_message", "interrupt_agent"]);
+    if (options.noSkills)
+        forbidden.add("skill");
+    if (options.tools) {
+        for (const name of options.tools)
+            requireThat((names.has(name) || name === "pbot_team_message") && !forbidden.has(name), "专家工具不可用：" + name);
+        ctx.tools.restrict({ allow: options.tools.filter(name => name !== "pbot_team_message") });
+    }
+    const deny = [...forbidden].filter(name => names.has(name));
+    if (deny.length)
+        ctx.tools.restrict({ deny });
+    return !options.tools || options.tools.includes("pbot_team_message");
+}

package/lib/integrations/dsh/schema.d.ts

@@ -0,0 +1,7 @@
+import type { TSchema } from "typebox";
+import type { JsonSchemaNode } from "@deepseek-ai/dsh-tools";
+/** Remove TypeBox's non-JSON metadata before passing a schema to the native host. */
+export declare function dshParameters(value: TSchema): Record<string, unknown>;
+/** Collaboration result unions are disjoint. rc.1 enforces structural oneOf schemas;
+ * the producing tool also validates the complete contract, including these bounds. */
+export declare function dshOutputSchema(value: TSchema): JsonSchemaNode;

package/lib/integrations/dsh/schema.js

@@ -0,0 +1,28 @@
+import { requireThat } from "../../common/validation.js";
+/** Remove TypeBox's non-JSON metadata before passing a schema to the native host. */
+export function dshParameters(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Collaboration result unions are disjoint. rc.1 enforces structural oneOf schemas;
+ * the producing tool also validates the complete contract, including these bounds. */
+export function dshOutputSchema(value) {
+    const bounds = new Set(["minLength", "maxLength", "pattern", "minimum", "maximum", "minItems", "maxItems"]);
+    const supported = new Set(["type", "required", "additionalProperties", "enum", "const", "description", "title", "default", "examples"]);
+    function convert(node) {
+        const result = {};
+        for (const [key, item] of Object.entries(node)) {
+            if (key === "anyOf")
+                result.oneOf = item.map(convert);
+            else if (key === "properties")
+                result.properties = Object.fromEntries(Object.entries(item).map(([name, child]) => [name, convert(child)]));
+            else if (key === "items")
+                result.items = convert(item);
+            else if (!bounds.has(key)) {
+                requireThat(supported.has(key), "dsh 输出 schema 不支持字段：" + key);
+                result[key] = item;
+            }
+        }
+        return result;
+    }
+    return convert(dshParameters(value));
+}

package/lib/integrations/dsh/session.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent, AgentHandle, AgentSetup } from "@deepseek-ai/dsh-agent";
+import type { SessionHeader } from "@deepseek-ai/dsh-session";
+import type { AgentDescriptor } from "../../model/agent.js";
+/** Read access must neither claim a writer nor activate an Agent. */
+export declare function readDshAgentSession(ctx: Context, d: AgentDescriptor): Promise<{
+    header: SessionHeader;
+    events: readonly import("@deepseek-ai/dsh-session").SessionEvent[];
+}>;
+/** An empty Agent is not recoverable until this native barrier has materialized it. */
+export declare function flushDshAgent(agent: Agent): Promise<void>;
+export declare function openDshAgent(ctx: Context, d: AgentDescriptor, parent: Agent, resume: boolean, setup: AgentSetup, signal: AbortSignal): Promise<AgentHandle>;
+/** A report refers to one durable turn boundary, never the latest answer. */
+export declare function readDshReport(ctx: Context, d: AgentDescriptor, reference: string): Promise<string>;

package/lib/integrations/dsh/session.js

@@ -0,0 +1,59 @@
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { requireThat } from "../../common/validation.js";
+function validateHeader(d, header) {
+    requireThat(header.id === d.agentId && header.cwd === d.cwd && header.parentSession === d.parentSessionId &&
+        header.origin === "subagent" && !header.isSeeded, "dsh 专家会话身份、父会话或工作目录不匹配。");
+}
+/** Read access must neither claim a writer nor activate an Agent. */
+export async function readDshAgentSession(ctx, d) {
+    const reader = await ctx.sessionPersistence.open(SessionId(d.agentId), "read");
+    try {
+        validateHeader(d, reader.header);
+        return { header: reader.header, events: (await reader.read()).events };
+    }
+    finally {
+        await reader.close();
+    }
+}
+/** An empty Agent is not recoverable until this native barrier has materialized it. */
+export async function flushDshAgent(agent) {
+    requireThat(await agent.ctx.sessions.flush(agent.session), "dsh 会话没有持久化屏障。");
+}
+export async function openDshAgent(ctx, d, parent, resume, setup, signal) {
+    signal.throwIfAborted();
+    requireThat(parent.id === d.parentSessionId && ctx.agents.get(parent.id) === parent, "dsh 父会话已失效。");
+    if (resume)
+        await readDshAgentSession(ctx, d);
+    await flushDshAgent(parent);
+    signal.throwIfAborted();
+    const compose = async (agentCtx, agent) => {
+        validateHeader(d, agent.session.header);
+        if (resume)
+            agent.inbox.clear();
+        const commit = await setup(agentCtx, agent);
+        await flushDshAgent(agent);
+        return commit;
+    };
+    const agentOptions = { ...(d.options.provider ? { provider: d.options.provider } : {}),
+        ...(d.options.model ? { model: d.options.model } : {}),
+        ...(d.options.thinking ? { reasoningEffort: ReasoningEffortId(d.options.thinking) } : {}) };
+    return resume
+        ? ctx.agents.resume({ resumeSessionId: SessionId(d.agentId), parentAgent: parent, agentOptions, setup: compose, signal })
+        : ctx.agents.create({ sessionId: SessionId(d.agentId), parentAgent: parent,
+            meta: { cwd: d.cwd, parentSession: parent.id, origin: "subagent", delegationDepth: 1 },
+            agentOptions, setup: compose, signal });
+}
+/** A report refers to one durable turn boundary, never the latest answer. */
+export async function readDshReport(ctx, d, reference) {
+    const match = /^dsh:(0|[1-9]\d*)$/.exec(reference);
+    requireThat(match, "dsh 报告位置无效。");
+    const end = Number(match[1]);
+    requireThat(Number.isSafeInteger(end), "dsh 报告位置无效。");
+    const { events } = await readDshAgentSession(ctx, d);
+    const boundary = events[end];
+    requireThat(boundary?.type === "turn/end", "dsh 报告结束位置不存在。");
+    const last = events.slice(0, end).findLast(event => event.type === "assistant/message" && event.data.turn === boundary.data.turn);
+    return last?.type === "assistant/message"
+        ? last.data.message.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "";
+}

package/lib/integrations/history-summary.d.ts

@@ -0,0 +1,2 @@
+import type { HistorySummarizer } from "../model/history.js";
+export declare function reduceHistorySummary(budget: number, ask: HistorySummarizer): HistorySummarizer;

package/lib/integrations/history-summary.js

@@ -0,0 +1,21 @@
+import { requireThat } from "../common/validation.js";
+export function reduceHistorySummary(budget, ask) {
+    return async (text, signal) => {
+        while (text.length > budget) {
+            const parts = [];
+            for (let offset = 0; offset < text.length;) {
+                signal.throwIfAborted();
+                let end = Math.min(text.length, offset + budget);
+                if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]))
+                    end--;
+                parts.push(await ask(text.slice(offset, end), signal));
+                offset = end;
+            }
+            const smaller = parts.join("\n\n");
+            requireThat(smaller.length < text.length, "历史摘要未缩短，稍后重试。");
+            text = smaller;
+        }
+        signal.throwIfAborted();
+        return ask(text, signal);
+    };
+}

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