personal-bot 0.2.3 → 0.2.4

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

@@ -0,0 +1,162 @@
+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 type { InstalledPackage, PackageChoice, PiInstallation, SetupOperations, SystemCommand } from "../../services/installation/setup-service.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: string, version: string, env: NodeJS.ProcessEnv): Promise<string> {
+  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 as NodeJS.ErrnoException).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 is string => !!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 as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  throw new Error(`无法定位 ${command} 对应的 Pi 包。请先按此 Pi 的原生安装方式修复，不会覆盖该命令。`);
+}
+
+export class PiSetup implements SetupOperations {
+  constructor(readonly processes: SetupProcesses, readonly npm: string, readonly cwd: string) {}
+
+  async inspectPi(command?: string): Promise<PiInstallation | undefined> {
+    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: string): Promise<string> {
+    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) as { version?: string; engines?: { node?: string } };
+    if (typeof value.version !== "string") throw new Error(`无法取得 ${name} 的最新版本。`);
+    return checkStableVersion(value.version, value.engines?.node);
+  }
+
+  async inspectPackages(pi: PiInstallation | undefined, workspace: string): Promise<InstalledPackage[]> {
+    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: unknown = JSON.parse(await readFile(file, "utf8"));
+          if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error(`无效的 Pi 配置：${file}`);
+          const packages = (settings as { packages?: unknown }).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 as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      }
+      return [];
+    }
+    const data = await this.processes.run(process.execPath, [bridge, "inspect", pi.root, workspace], this.cwd);
+    return JSON.parse(data) as InstalledPackage[];
+  }
+
+  async installTmux(command: SystemCommand): Promise<void> {
+    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: PiInstallation | undefined, version: string): Promise<PiInstallation> {
+    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: PiInstallation, workspace: string, choice: PackageChoice): Promise<string> {
+    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: PiInstallation, workspace: string, choice: PackageChoice): Promise<string> {
+    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: PiInstallation, workspace: string): Promise<void> {
+    await access(guard, constants.R_OK);
+    await this.processes.run(pi.command, ["--extension", guard, "/pbot init"], resolve(workspace), { interactive: true, timeoutMs: 0 });
+  }
+}

package/src/integrations/installation/processes.ts

@@ -0,0 +1,124 @@
+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";
+import type { SystemCommand } from "../../services/installation/setup-service.js";
+
+export async function findExecutable(name: string, env: NodeJS.ProcessEnv = process.env): Promise<string | undefined> {
+  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 as NodeJS.ErrnoException).code ?? "")) throw error;
+    }
+  }
+  return undefined;
+}
+
+export class SetupProcesses {
+  constructor(readonly signal: AbortSignal, readonly env: NodeJS.ProcessEnv = process.env) {}
+
+  async run(command: string, args: string[], cwd: string,
+    options: { interactive?: boolean; timeoutMs?: number; input?: string } = {}): Promise<string> {
+    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: Buffer[] = [], stderr: Buffer[] = [];
+      let bytes = 0, failure: Error | undefined, escalation: NodeJS.Timeout | undefined;
+      const kill = (signal: NodeJS.Signals) => {
+        if (!child.pid) return;
+        try { if (interactive) child.kill(signal); else process.kill(-child.pid, signal); } catch { /* Process already exited. */ }
+      };
+      const stop = (reason: Error) => {
+        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: Buffer[]) => (chunk: Buffer) => {
+        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", () => { /* An exiting child may close stdin early. */ });
+      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: string, commands: ReadonlyMap<string, string>, root: boolean): SystemCommand {
+  let command: string | undefined, args: string[];
+  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: SetupProcesses, cwd: string): Promise<{ npm: string; tmux?: SystemCommand }> {
+  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)] as const));
+  const commands = new Map(entries.filter((entry): entry is readonly [string, string] => entry[1] !== undefined));
+  return { npm, tmux: tmuxInstallCommand(process.platform, commands, process.getuid?.() === 0) };
+}
+
+export function npmGlobalBinary(prefix: string): string { return join(prefix, "bin", "pi"); }

package/src/integrations/installation/workspace.ts

@@ -0,0 +1,18 @@
+import { stat, realpath } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+export async function resolveWorkspace(value: string, cwd: string, home: string): Promise<string> {
+  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 as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = dirname(existing);
+      if (parent === existing) throw error;
+      existing = parent;
+    }
+  }
+}

package/src/services/installation/setup-service.ts

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

package/src/ui/setup.ts

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