pi-webapp 0.1.2 → 0.1.3

package/README.md

@@ -8,7 +8,24 @@
 
 ## Install and open
 
-Requires Node.js 22.19 or later and Pi 0.87.1 or later.
+Requires Node.js 22.19 or later. To open the web interface directly:
+
+```bash
+npx pi-webapp
+```
+
+This starts Pi in the background and opens the default browser on a local graphical desktop, leaving the terminal free. If Pi is missing, the launcher installs the official `@earendil-works/pi-coding-agent` package with npm. An existing Pi installation must be version 0.87.1 or later. The launcher does not replace an older installation automatically. Running the launcher again reopens the existing server. Remote or headless sessions print the address instead; set `PI_WEBAPP_AUTO_OPEN=0` to disable automatic opening.
+
+Use `npx pi-webapp status` to show the address and `npx pi-webapp stop` to stop the background service. After a global install, use `pi-webapp status` and `pi-webapp stop`.
+
+You can also install the launcher globally:
+
+```bash
+npm install -g pi-webapp
+pi-webapp
+```
+
+To use the extension inside an existing Pi terminal, the original workflow remains available:
 
 ```bash
 pi install npm:pi-webapp
@@ -23,11 +40,11 @@ In Pi, enter `/web` to open the interface in your default browser. Pi also print
 - Send messages, stop a run, start a new Pi session, and change the current model or thinking level.
 - Browse workspaces and saved sessions. Add a workspace with the native directory picker when available, or use the built-in directory browser over SSH.
 - Attach up to 20 files of 20 MB each by selecting, dropping, or pasting them. Images show previews and are also sent as Pi image content.
-- Manage appearance, Pi packages, extensions, skills, and models from the settings panel. Provider credentials remain in Pi's local authentication store and are never returned to the browser.
+- Manage appearance, Pi packages, extensions, skills, and models from the settings panel. The Models page can add models, edit display names, context windows, output limits, and input types, and restore built-in defaults; changes are saved to Pi's `models.json`. Browser sign-in opens the provider's authorization page automatically; manual code entry remains available when a callback cannot reach Pi. Stored provider credentials can also be removed there. Credentials stay in Pi's local `auth.json` and are never returned to the browser.
 
-The Pi terminal session that opened `/web` stays synchronized with the browser. Sessions opened in other workspaces use the Pi SDK and load that workspace's skills and project context. They do not load extensions again in the same process.
+If you enter `/web` manually in a Pi terminal, that terminal session stays synchronized with the browser. With the launcher, Pi runs in the background. Sessions opened in other workspaces use the Pi SDK and load that workspace's skills and project context. They do not load extensions again in the same process.
 
-Workspace records and attachments stay under Pi's existing `pi-web/` data directory for compatibility with earlier releases. Removing a workspace from the sidebar does not delete its files or sessions.
+On startup, the app discovers workspaces from Pi's saved sessions, so conversations from other directories appear in the sidebar. Workspace records and attachments stay under Pi's existing `pi-web/` data directory. Removing a workspace from the sidebar does not delete its files or sessions; you can add it again manually.
 
 ## Develop locally
 
@@ -36,10 +53,12 @@ npm install
 npm run check
 npm run test
 npm run build
-pi -e .
+npm run start
+npm run status
+npm run stop
 ```
 
-After editing the extension, rebuild it, then enter `/reload` and `/web` in Pi. Refreshing an old browser page alone does not replace the running bridge.
+`npm run start` builds the project, starts Pi in the background, and opens the web interface. After editing the extension, run `npm run stop` followed by `npm run start`. If you develop with `pi -e .`, enter `/reload` and `/web` in Pi after rebuilding. Refreshing an old browser page alone does not replace the running bridge.
 
 The source lives in `extension/`, `shared/`, and `web/src/`. The npm package contains only the bundled, minified JavaScript extension, built web assets, cover image, and the English and Chinese READMEs. No TypeScript source or source maps are published. Minification makes the shipped code harder to read; it does not encrypt JavaScript.
 

package/README.zh-CN.md

@@ -8,7 +8,24 @@
 
 ## 安装与打开
 
-需要 Node.js 22.19 或更新版本，以及 Pi 0.87.1 或更新版本。
+需要 Node.js 22.19 或更新版本。推荐直接运行：
+
+```bash
+npx pi-webapp
+```
+
+该命令会在后台启动 Pi，并在本地图形桌面用默认浏览器打开网页，终端可继续使用。若未找到 Pi，会自动通过 npm 安装官方 `@earendil-works/pi-coding-agent`。已有 Pi 需要 0.87.1 或更新版本；启动器不会自动覆盖旧版本。再次运行启动命令会重新打开已有服务。远程或无图形界面时只显示地址；设置 `PI_WEBAPP_AUTO_OPEN=0` 可关闭自动打开。
+
+可用 `npx pi-webapp status` 查看地址，用 `npx pi-webapp stop` 停止后台服务。全局安装后可直接运行 `pi-webapp status` 和 `pi-webapp stop`。
+
+也可以将启动器安装为全局命令：
+
+```bash
+npm install -g pi-webapp
+pi-webapp
+```
+
+如果希望在已有 Pi 终端中使用，仍可按原方式安装扩展：
 
 ```bash
 pi install npm:pi-webapp
@@ -23,11 +40,11 @@ pi
 - 发送消息、停止运行、启动新的 Pi 会话，以及切换当前模型或思考级别。
 - 浏览工作区和已保存的会话。环境支持时可通过系统目录选择器添加工作区；通过 SSH 使用时，也可使用内置目录浏览器。
 - 通过选择、拖放或粘贴附加文件，最多 20 个，每个不超过 20 MB。图片会显示预览，并作为 Pi 图片内容发送。
-- 在设置面板中管理外观、Pi 软件包、扩展、技能和模型。模型提供商的凭据保留在 Pi 本地的身份验证存储中，不会返回给浏览器。
+- 在设置面板中管理外观、Pi 软件包、扩展、技能和模型。模型页可添加模型、编辑显示名称、上下文窗口、最大输出 token 数和输入类型，或恢复内置模型的默认参数；配置写入 Pi 的 `models.json`。网页登录会自动打开提供方授权页；当回调无法到达 Pi 时，仍可手动粘贴授权码。已保存的提供方认证可在这里移除。凭据保留在 Pi 本地的 `auth.json`，不会返回给浏览器。
 
-打开 `/web` 的 Pi 终端会话会与浏览器保持同步。在其他工作区打开的会话使用 Pi SDK，并加载该工作区的技能和项目上下文；同一进程中不会再次加载扩展。
+如果通过 Pi 终端手动输入 `/web`，该终端会话会与浏览器保持同步。使用启动器时，Pi 在后台运行。在其他工作区打开的会话使用 Pi SDK，并加载该工作区的技能和项目上下文；同一进程中不会再次加载扩展。
 
-工作区记录和附件继续存放在 Pi 现有的 `pi-web/` 数据目录下，以兼容早期版本。从侧边栏移除工作区不会删除其文件或会话。
+启动时会从 Pi 已保存的会话中发现工作区，因此先前在其他目录使用 Pi 的会话也会出现在侧边栏。工作区记录和附件继续存放在 Pi 现有的 `pi-web/` 数据目录下。从侧边栏移除工作区不会删除其文件或会话；移除后如需再次显示，可以手动添加。
 
 ## 本地开发
 
@@ -36,10 +53,12 @@ npm install
 npm run check
 npm run test
 npm run build
-pi -e .
+npm run start
+npm run status
+npm run stop
 ```
 
-修改扩展后，需要重新构建扩展，再在 Pi 中依次输入 `/reload` 和 `/web`。仅刷新旧的浏览器页面不会替换正在运行的连接桥接代码。
+`npm run start` 会构建项目、在后台启动 Pi 并打开 Web 界面。修改扩展后，运行 `npm run stop`，再运行 `npm run start`；如果使用 `pi -e .` 开发，则在 Pi 中依次输入 `/reload` 和 `/web`。仅刷新旧的浏览器页面不会替换正在运行的连接桥接代码。
 
 源代码位于 `extension/`、`shared/` 和 `web/src/`。npm 软件包仅包含打包并压缩后的 JavaScript 扩展、构建后的 Web 资源、封面图片，以及英文和中文 README；不会发布 TypeScript 源码或 source map。代码压缩会增加阅读发布版本代码的难度，但不会对 JavaScript 加密。
 

package/bin/open-web-page.d.mts

@@ -0,0 +1,2 @@
+export type OpenPageRunner = (command: string, args: readonly string[]) => Promise<void>;
+export declare function openWebPage(url: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, run?: OpenPageRunner): Promise<boolean>;

package/bin/open-web-page.mjs

@@ -0,0 +1,18 @@
+import { execFile } from "node:child_process";
+
+const runOpenCommand = (command, args) => new Promise((resolve, reject) => {
+  execFile(command, [...args], { windowsHide: true }, (error) => {
+    if (error) reject(error);
+    else resolve();
+  });
+});
+
+/** Open on the host desktop only when this process has a local graphical session. */
+export async function openWebPage(url, platform = process.platform, env = process.env, run = runOpenCommand) {
+  if (env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT) return false;
+  if (platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false;
+  const command = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : platform === "win32" ? "explorer.exe" : null;
+  if (command === null) return false;
+  await run(command, [url]);
+  return true;
+}

package/bin/pi-webapp.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { spawn as spawnNode } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, openSync } from "node:fs";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import spawn from "cross-spawn";
+import { openWebPage } from "./open-web-page.mjs";
+
+const minimum = [0, 87, 1];
+const launcher = fileURLToPath(import.meta.url);
+const extension = fileURLToPath(new URL("../dist/extension.js", import.meta.url));
+const agentDir = resolve((process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent")).replace(/^~(?=$|[\\/])/, homedir()));
+const statePath = join(agentDir, "pi-web", "launcher.json");
+const stopPath = join(agentDir, "pi-web", "launcher.stop");
+const logPath = join(agentDir, "pi-web", "launcher.log");
+
+function versionParts(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compatible(parts, required) {
+  for (let i = 0; i < 3; i++) {
+    if (parts[i] !== required[i]) return parts[i] > required[i];
+  }
+  return true;
+}
+
+function probe(command) {
+  const result = spawn.sync(command, ["--version"], { encoding: "utf8" });
+  if (result.error?.code === "ENOENT") return null;
+  if (result.error || result.status !== 0) {
+    throw new Error(`无法运行 Pi：${result.error?.message || result.stderr?.trim() || command}`);
+  }
+  const version = result.stdout.trim();
+  const parts = versionParts(version);
+  if (!parts || !compatible(parts, minimum)) {
+    throw new Error(`Pi 版本 ${version || "未知"} 不受支持，需要 0.87.1 或更新版本。请更新 Pi 后重试。`);
+  }
+  return command;
+}
+
+function installPi() {
+  console.error("未找到 Pi，正在通过 npm 安装 @earendil-works/pi-coding-agent …");
+  const result = spawn.sync("npm", ["install", "-g", "--ignore-scripts", "@earendil-works/pi-coding-agent"], { stdio: "inherit" });
+  if (result.error || result.status !== 0) {
+    throw new Error(`Pi 安装失败。请手动运行 npm install -g --ignore-scripts @earendil-works/pi-coding-agent${result.error ? `（${result.error.message}）` : ""}`);
+  }
+  const inPath = probe("pi");
+  if (inPath) return inPath;
+  const prefix = spawn.sync("npm", ["prefix", "-g"], { encoding: "utf8" });
+  if (prefix.status === 0) {
+    const installed = process.platform === "win32" ? join(prefix.stdout.trim(), "pi.cmd") : join(prefix.stdout.trim(), "bin", "pi");
+    if (existsSync(installed)) return probe(installed);
+  }
+  throw new Error("Pi 已安装，但找不到 pi 命令。请将 npm 全局可执行目录加入 PATH 后重试。");
+}
+
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === "EPERM"; }
+}
+
+async function activeState() {
+  let state;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try { state = JSON.parse(await readFile(statePath, "utf8")); break; }
+    catch (error) {
+      if (error?.code === "ENOENT") return null;
+      if (!(error instanceof SyntaxError)) throw error;
+      if (attempt < 2) { await new Promise((resolveWait) => setTimeout(resolveWait, 50)); continue; }
+      const age = Date.now() - (await stat(statePath)).mtimeMs;
+      if (age < 5000) return { starting: true };
+      await unlink(statePath).catch(() => {});
+      return null;
+    }
+  }
+  if (alive(state?.pid)) return state;
+  await unlink(statePath).catch(() => {});
+  return null;
+}
+
+async function saveState(state) {
+  const temporary = `${statePath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
+    await rename(temporary, statePath);
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+function notifyParent(message) {
+  if (process.connected) process.send?.(message);
+}
+
+async function serve(pi, args) {
+  const nonce = randomUUID();
+  await mkdir(dirname(statePath), { recursive: true });
+  let claimed = false;
+  let lock;
+  try {
+    lock = await open(statePath, "wx", 0o600);
+    claimed = true;
+    await lock.writeFile(JSON.stringify({ pid: process.pid, nonce, cwd: process.cwd(), starting: true }));
+  } catch (error) {
+    if (claimed) await unlink(statePath).catch(() => {});
+    notifyParent({ type: "error", message: error?.code === "EEXIST" ? "pi-webapp 已在启动或运行" : String(error) });
+    return;
+  } finally { await lock?.close().catch(() => {}); }
+
+  const child = spawn(pi, ["--mode", "rpc", "-e", extension, ...args], {
+    cwd: process.cwd(), env: { ...process.env, PI_WEBAPP_AUTO_OPEN: "0" }, stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stderr?.pipe(process.stderr, { end: false });
+  let ready = false;
+  let opening = false;
+  let failed = false;
+  let closed = false;
+  let stateWrite = Promise.resolve();
+  let stopping = false;
+  let buffer = "";
+  let killTimer;
+  const shutdown = () => {
+    if (stopping) return;
+    stopping = true;
+    child.stdin?.end();
+    killTimer = setTimeout(() => child.kill("SIGTERM"), 5000);
+    killTimer.unref();
+  };
+  const fail = (message) => {
+    if (failed || ready) return;
+    failed = true;
+    notifyParent({ type: "error", message });
+    shutdown();
+  };
+  const startupTimer = setTimeout(() => fail(`Pi 启动超时。日志：${logPath}`), 60000);
+  const stopTimer = setInterval(async () => {
+    try { if ((await readFile(stopPath, "utf8")).trim() === nonce) shutdown(); }
+    catch { /* No stop request. */ }
+  }, 400);
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  child.stdout?.on("data", (chunk) => {
+    if (ready || opening || failed) return;
+    buffer += chunk.toString("utf8");
+    if (buffer.length > 8 * 1024 * 1024) { fail("Pi RPC 输出超出预期大小"); return; }
+    for (let index; (index = buffer.indexOf("\n")) !== -1;) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      let record;
+      try { record = JSON.parse(line); } catch { continue; }
+      if (record?.type === "response" && record.id === "list-commands") {
+        if (record.success !== true || !Array.isArray(record.data?.commands)) {
+          fail("无法读取 Pi 扩展命令列表");
+          return;
+        }
+        const command = record.data.commands.find((item) => item?.source === "extension"
+          && item.sourceInfo?.path === extension && /^web(?::\d+)?$/.test(item.name));
+        if (!command) {
+          fail("Pi 没有加载当前项目的 Web 扩展");
+          return;
+        }
+        child.stdin?.write(JSON.stringify({ id: "open-web", type: "prompt", message: `/${command.name}` }) + "\n");
+        continue;
+      }
+      if (record?.type === "response" && record.id === "open-web" && record.success === false) {
+        fail(`Pi 拒绝打开网页：${record.error ?? "未知错误"}`);
+        return;
+      }
+      if (record?.type !== "extension_ui_request" || record.method !== "notify" || typeof record.message !== "string" || !record.message.startsWith("pi-webapp: ")) continue;
+      let url;
+      try { url = new URL(record.message.slice("pi-webapp: ".length)); }
+      catch { continue; }
+      if (url.hostname !== "127.0.0.1" || !url.hash) continue;
+      opening = true;
+      stateWrite = saveState({ pid: process.pid, piPid: child.pid, nonce, cwd: process.cwd(), url: url.href })
+        .then(() => {
+          if (closed || failed) return;
+          ready = true;
+          clearTimeout(startupTimer);
+          notifyParent({ type: "ready", pid: process.pid, url: url.href });
+        })
+        .catch((error) => fail(`无法保存启动状态：${error.message}`));
+      return;
+    }
+  });
+  child.stdin?.on("error", (error) => fail(`无法向 Pi 发送启动命令：${error.message}`));
+  child.stdin?.write(JSON.stringify({ id: "list-commands", type: "get_commands" }) + "\n");
+  await new Promise((resolveExit) => {
+    child.once("error", (error) => { fail(`无法启动 Pi：${error.message}`); resolveExit(); });
+    child.once("close", (code) => {
+      closed = true;
+      if (!ready) fail(`Pi 提前退出（代码 ${code ?? "未知"}）。日志：${logPath}`);
+      resolveExit();
+    });
+  });
+  await stateWrite;
+  clearTimeout(startupTimer);
+  clearInterval(stopTimer);
+  clearTimeout(killTimer);
+  try { if ((await readFile(stopPath, "utf8")).trim() === nonce) await unlink(stopPath); } catch { /* Already removed. */ }
+  if (claimed) {
+    try { if (JSON.parse(await readFile(statePath, "utf8")).nonce === nonce) await unlink(statePath); }
+    catch { /* Already removed. */ }
+  }
+}
+
+async function start(args) {
+  const existing = await activeState();
+  if (existing) {
+    console.log(existing.url ? `pi-webapp 已在后台运行：${existing.url}` : "pi-webapp 正在启动");
+    if (existing.url) await openPageIfLocal(existing.url);
+    return;
+  }
+  const nodeVersion = versionParts(process.versions.node);
+  if (!nodeVersion || !compatible(nodeVersion, [22, 19, 0])) throw new Error("需要 Node.js 22.19 或更新版本。");
+  if (!existsSync(extension)) throw new Error("找不到构建后的扩展。请先运行 npm run build。");
+  if (args.some((arg) => ["--mode", "--print", "-p"].includes(arg))) throw new Error("后台启动不支持覆盖 Pi 的运行模式");
+  const pi = probe("pi") ?? installPi();
+  await mkdir(dirname(statePath), { recursive: true });
+  const logFd = openSync(logPath, "a", 0o600);
+  let worker;
+  try {
+    worker = spawnNode(process.execPath, [launcher, "__serve", pi, ...args], {
+      detached: true, cwd: process.cwd(), env: process.env, stdio: ["ignore", logFd, logFd, "ipc"],
+    });
+  } finally { closeSync(logFd); }
+  let ready;
+  try {
+    ready = await new Promise((resolveReady, rejectReady) => {
+      const timer = setTimeout(() => rejectReady(new Error(`后台启动超时。日志：${logPath}`)), 65000);
+      worker.once("message", (message) => {
+        clearTimeout(timer);
+        if (message?.type === "ready") resolveReady(message);
+        else rejectReady(new Error(message?.message ?? "后台启动失败"));
+      });
+      worker.once("error", rejectReady);
+      worker.once("exit", (code) => rejectReady(new Error(`后台进程退出（代码 ${code ?? "未知"}）。日志：${logPath}`)));
+    });
+  } finally {
+    if (worker.connected) worker.disconnect();
+    worker.unref();
+  }
+  console.log(`pi-webapp 已在后台运行（PID ${ready.pid}）：${ready.url}`);
+  console.log("停止服务：pi-webapp stop（源码目录中可运行 npm run stop）");
+  await openPageIfLocal(ready.url);
+}
+
+async function openPageIfLocal(url) {
+  if (process.env.PI_WEBAPP_AUTO_OPEN === "0") return;
+  try {
+    if (!await openWebPage(url)) console.log("当前没有本地图形桌面，请手动打开上方地址。");
+  } catch {
+    console.error("无法自动打开浏览器，请手动打开上方地址。");
+  }
+}
+
+async function stop() {
+  const state = await activeState();
+  if (!state) { console.log("pi-webapp 未运行"); return; }
+  if (!state.nonce) throw new Error("pi-webapp 正在启动，请稍后再停止");
+  await writeFile(stopPath, state.nonce, { mode: 0o600 });
+  for (let attempt = 0; attempt < 120; attempt++) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+    const current = await activeState();
+    if (!current || current.nonce !== state.nonce) { console.log("pi-webapp 已停止"); return; }
+  }
+  throw new Error(`停止超时。后台进程 PID：${state.pid}；日志：${logPath}`);
+}
+
+async function main() {
+  const [argument, ...rest] = process.argv.slice(2);
+  if (argument === "__serve") { await serve(rest[0], rest.slice(1)); return; }
+  if (argument === "stop" || argument === "status") {
+    if (rest.length) throw new Error(`用法：pi-webapp ${argument}`);
+    if (argument === "stop") await stop();
+    else {
+      const state = await activeState();
+      console.log(state ? `pi-webapp ${state.url ? `正在运行：${state.url}` : "正在启动"}` : "pi-webapp 未运行");
+    }
+    return;
+  }
+  if (argument === "--help" || argument === "-h") { console.log("用法：pi-webapp [start|status|stop] [Pi 参数]"); return; }
+  if (argument && argument !== "start" && !argument.startsWith("-")) throw new Error("用法：pi-webapp [start|status|stop] [Pi 参数]");
+  await start(argument === "start" || !argument ? rest : [argument, ...rest]);
+}
+
+main().catch((error) => {
+  console.error(`pi-webapp: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});