pi-webapp 0.1.21 → 0.1.23

package/README.md

@@ -4,13 +4,20 @@
 
 ## Download pi desktop
 
-### [⬇ Download for macOS Apple Silicon (.dmg)](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.20-b5/pi-0.1.20-desktop.5-mac-arm64.dmg)
+**⬇ Test release · v0.1.21 / desktop build 6 · bundled Pi 1.3.0**
 
-**Test release · v0.1.20 / desktop build 5 · Apple M-series only**
+| Your computer | Download |
+| --- | --- |
+| macOS · Apple Silicon (M-series, arm64) | [Download DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-arm64.dmg) |
+| macOS · Intel (x64) | [Download DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-x64.dmg) |
+| Windows · x64 | [Download EXE installer](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-win-x64.exe) |
+| Linux · x64 | [Download AppImage](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-linux-x86_64.AppImage) |
 
-[Release notes and SHA-256 checksums](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.20-b5) · [All desktop releases](https://github.com/chengzhiyi/pi-webapp/releases) · [Use the Web/npm version instead](#install-and-open)
+[Release notes](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.21-b6) · [SHA-256 checksums](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/SHA256SUMS) · [Runtime/source metadata](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/desktop-release.json) · [Previous build 5](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.20-b5) · [Use Web/npm instead](#install-and-open)
 
-> Open the DMG and drag **pi.app** into Applications. This test build is unsigned/unnotarized; do not globally disable macOS security. Windows/Linux/Intel Mac installers are not yet validated. Node and a tested, pinned Pi runtime are bundled; you do not need to install them separately.
+> **Install:** macOS: open the DMG and drag **pi.app** into Applications. Windows: run the EXE installer. Linux: make the AppImage executable, then run it; use `--appimage-extract-and-run` if FUSE is unavailable. Node and pinned Pi **1.3.0** are bundled; no separate installation is required. Configure your model account in Settings. Quit the old desktop before replacing it; a reused external Web service keeps its own Pi version and is never automatically stopped or upgraded.
+>
+> **Unsigned test build:** macOS is not notarized; Windows may show an unknown-publisher warning. Only proceed if you trust the source; never globally disable system security. Installer-payload smoke tests passed on all four targets, not every Linux distribution or real model-provider login. Windows ARM/Linux ARM are not included. Desktop automatic updates are not provided in this build.
 
 ![pi-webapp cover](assets/cover-webapp.png)
 
@@ -57,6 +64,7 @@ In Pi, enter `/web` to open the interface in your default browser. Pi also print
 - In **Git changes → Changes**, use each file’s **+ / −** button to stage or unstage it, use the fixed bottom composer to commit only the staged index (Ctrl/Cmd+Enter is supported), and click the branch name to search/switch local branches or open **New branch**. The file list scrolls independently; full repository metadata is available on the short repository name’s tooltip. Drafts stay with each chat’s Git tab. Commits and branch switches require a root workspace; switching also requires a clean working tree, including untracked files. Writes require all known chats using the worktree to be idle, reject stale snapshots, and honor Git hooks/signing. Conflicts, active Git operations, locks and occupied worktree branches block incompatible writes. Failed or unconfirmed operations retain drafts and never retry automatically. Changes are shared by chats using the same worktree. No fetch/push, forced switch, stash or discard is performed.
 - In **Git changes → History**, browse commits alongside their branch/merge graph, with HEAD, local branch, remote-tracking branch and tag labels. Load history 50 commits at a time; a ref change resets pagination to prevent mixed histories. Open commit details for the full message, author/committer, timestamps, parents and changed files, then preview a read-only file diff alongside the same commit file list without opening another tab. Merge details let you select the parent to compare against; root commits compare against an empty tree. The graph shows repository-wide metadata while commit files and diffs stay within the session directory. Graph selection and loaded history remain with each chat’s Git tab until the page reloads. Remote labels use local refs without fetching.
 - 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.
+- Open Plugins directly below New session in the sidebar to inspect and switch the bundled Git, Files and Terminal capabilities. Switches are global, persist locally, and require every chat to be idle. Disabling closes related tabs and blocks backend requests; Terminal asks for confirmation before ending all service-owned terminals. External Pi Web runtimes remain managed through Packages & extensions rather than a misleading UI-only switch.
 - 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.
 
 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 load enabled Web plugin Pi entries explicitly while keeping other Pi extensions isolated from the parent bridge.
@@ -91,7 +99,7 @@ npm run stop
 
 For local Web plugin development with the sibling `pi-extensions` workspace, follow its `README.md`. Set `PI_WEBAPP_PLUGIN_DEV_ROOTS=../pi-extensions/packages/plan-mode` when starting this app; browser asset changes refresh automatically and Pi entry changes trigger a safe reload when the agent is idle.
 
-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.
+Source ownership is split across `src/adapters/pi/` (the thin Pi entry), `src/host/` (server and browser host), `src/plugins/builtin/` (Git, Files and Terminal, each with server/client/contracts), `src/contracts/`, and shared UI in `web/src/ui/`. See [architecture and plugin management](docs/architecture.md). 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.
 
 ## Error collection
 

package/README.zh-CN.md

@@ -4,13 +4,20 @@
 
 ## 下载 pi 桌面版
 
-### [⬇ 下载 macOS Apple 芯片版（DMG）](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.20-b5/pi-0.1.20-desktop.5-mac-arm64.dmg)
+**⬇ 测试版 · v0.1.21 / 桌面构建 6 · 内置 Pi 1.3.0**
 
-**测试版 · v0.1.20 / 桌面构建 5 · 仅支持 Apple M 系列芯片**
+| 你的电脑 | 下载安装包 |
+| --- | --- |
+| macOS · Apple 芯片（M 系列，arm64） | [下载 DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-arm64.dmg) |
+| macOS · Intel 芯片（x64） | [下载 DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-x64.dmg) |
+| Windows · x64 | [下载 EXE 安装程序](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-win-x64.exe) |
+| Linux · x64 | [下载 AppImage](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-linux-x86_64.AppImage) |
 
-[版本说明与 SHA-256 校验和](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.20-b5) · [所有桌面版本](https://github.com/chengzhiyi/pi-webapp/releases) · [改用 Web/npm 方式](#安装与打开)
+[版本说明](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.21-b6) · [SHA-256 校验和](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/SHA256SUMS) · [运行时与源码元数据](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/desktop-release.json) · [旧构建 5（保留回退）](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.20-b5) · [改用 Web/npm 方式](#安装与打开)
 
-> 打开 DMG，将 **pi.app** 拖入“应用程序”即可。此测试版未签名、未公证，请勿全局关闭 macOS 安全保护。Windows/Linux/Intel Mac 安装包尚未验收。安装包已内置 Node 与经过验证、锁定版本的 Pi，无需另行安装。
+> **安装：** macOS 打开 DMG，将 **pi.app** 拖入“应用程序”；Windows 运行 EXE 安装程序；Linux 为 AppImage 添加可执行权限后运行，缺少 FUSE 时可加 `--appimage-extract-and-run`。已内置 Node 和锁定版本的 Pi **1.3.0**，无需另装；首次使用在设置中配置模型账户。替换前先退出旧桌面。复用外部 Web 后台时，其 Pi 仍保持原版本，不会自动停止或升级。
+>
+> **未签名测试版：** macOS 未公证，Windows 可能提示未知发布者；仅在确认来源可信后按单个应用的系统提示处理，不要全局关闭系统安全保护。四种实际安装包均通过原生运行冒烟，但不代表已测试所有 Linux 发行版或真实模型账户登录。不含 Windows ARM/Linux ARM；本构建尚无桌面自动更新。
 
 ![pi-webapp 封面](assets/cover-webapp.png)
 
@@ -57,6 +64,7 @@ pi
 - 在「Git 改动 → 改动」中，用文件右侧的 **+ / −** 逐文件暂存或取消暂存；底部固定提交栏仅提交暂存区内容（支持 Ctrl/Cmd+Enter）；点击顶部分支名称，可搜索和切换本地分支，选择「新建分支」才展开创建表单。文件列表独立滚动，仓库完整信息通过短名称的悬停提示查看。草稿随各聊天的 Git 标签保留。提交和切换分支要求仓库根目录工作区，切换还要求整个工作树干净（包括未跟踪文件）。写操作要求共用工作树的已知聊天均为空闲，并校验状态快照，遵守 Git hooks 与签名配置。冲突、未完成的 Git 操作、锁及其他工作树占用的分支会阻止相应操作。失败或结果不明时保留草稿，不自动重试。同一工作树的改动由多个聊天共享。不执行 fetch/push、强制切换、stash 或丢弃改动。
 - 在「Git 改动 → 历史」中浏览提交及其分支、合并关系图，显示 HEAD、本地分支、远端跟踪分支和标签。历史每次加载 50 条；引用变化时重新加载首页，避免分页混入不同版本的历史。点击提交查看完整说明、作者与提交者、时间、父提交及改动文件，再点击文件在当前提交详情内预览只读差异，保留文件列表，不再新建差异标签。合并提交可选择比较的父提交，根提交与空目录比较。关系图展示整个仓库的提交元数据，提交文件和差异仍限制在当前会话目录内。历史选中项与已加载页随各聊天的 Git 标签保留，网页刷新后重置。远端标签仅使用本地记录，不发起拉取。
 - 通过选择、拖放或粘贴附加文件，最多 20 个，每个不超过 20 MB。图片会显示预览，并作为 Pi 图片内容发送。
+- 从侧栏「新会话」下方的「插件」入口管理内置 Git、文件和终端。支持列表/详情、搜索、真实启停和全局持久化；所有聊天空闲后才可切换。停用会关闭相关标签并阻止后端请求，停用终端需确认并结束此服务的全部终端。外部 Pi Web 插件展示运行时归属，仍通过「包与扩展」管理，不提供只隐藏 UI 的假开关。
 - 在设置面板中管理外观、Pi 软件包、扩展、技能和模型。模型页可添加模型、编辑显示名称、上下文窗口、最大输出 token 数和输入类型，或恢复内置模型的默认参数；配置写入 Pi 的 `models.json`。网页登录会自动打开提供方授权页；当回调无法到达 Pi 时，仍可手动粘贴授权码。已保存的提供方认证可在这里移除。凭据保留在 Pi 本地的 `auth.json`，不会返回给浏览器。
 
 如果通过 Pi 终端手动输入 `/web`，该终端会话会与浏览器保持同步。使用启动器时，Pi 在后台运行。在其他工作区打开的会话使用 Pi SDK，并加载该工作区的技能和项目上下文；已启用的 Web 插件 Pi 入口会显式加载，其他普通 Pi 扩展仍与主会话隔离。
@@ -91,7 +99,7 @@ npm run stop
 
 与同级 `pi-extensions` 联调时，先在该目录运行 `pnpm install && pnpm build`，再运行 `pnpm dev`；在本项目设置 `PI_WEBAPP_PLUGIN_DEV_ROOTS=../pi-extensions/packages/plan-mode` 后执行 `npm run start`。浏览器资源变化后页面会刷新，Pi 入口变化后会等待代理空闲并重载扩展。完整步骤见 `pi-extensions/README.md`。
 
-源代码位于 `extension/`、`shared/` 和 `web/src/`。npm 软件包仅包含打包并压缩后的 JavaScript 扩展、构建后的 Web 资源、封面图片，以及英文和中文 README；不会发布 TypeScript 源码或 source map。代码压缩会增加阅读发布版本代码的难度，但不会对 JavaScript 加密。
+源码按职责组织：`src/adapters/pi/` 为薄 Pi 入口，`src/host/` 为前后端宿主，`src/plugins/builtin/` 分别集中 Git、文件和终端的 server/client/contract，`src/contracts/` 保存宿主跨端契约，`web/src/ui/` 保留共享 UI。详见[目录与插件管理说明](docs/architecture.md)。npm 软件包仅包含打包并压缩后的 JavaScript 扩展、构建后的 Web 资源、封面图片，以及英文和中文 README；不会发布 TypeScript 源码或 source map。代码压缩会增加阅读发布版本代码的难度，但不会对 JavaScript 加密。
 
 ## 错误采集
 

package/bin/open-web-page.mjs

@@ -9,6 +9,9 @@ const runOpenCommand = (command, args) => new Promise((resolve, reject) => {
 
 /** 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) {
+  // Embedded desktop owns its window. Awaiting xdg-open here can keep its RPC
+  // readiness notification blocked for the lifetime of an external browser.
+  if (env.PI_WEBAPP_AUTO_OPEN === "0" || env.PI_WEBAPP_RUNTIME === "desktop") return false;
   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;

package/bin/pi-webapp.mjs

@@ -146,6 +146,9 @@ async function serve(pi, args) {
         instanceId, pid: process.pid, piPid: child.pid, uptimeMs: Math.round(performance.now() - startedAt), ...fields }));
     } catch { /* Diagnostics must not interrupt process supervision. */ }
   };
+  // Opt-in fixture diagnostics: fixed milestones only, never RPC content or URLs.
+  const startupStage = stage => { if (process.env.PI_WEBAPP_STARTUP_TRACE === "1") lifecycle("launcher_startup_stage", { stage }); };
+  let sawStdout = false;
   const devWatchers = [];
   let devReloadTimer;
   let devReloadCount = 0;
@@ -187,6 +190,7 @@ async function serve(pi, args) {
   process.on("SIGINT", () => shutdown("signal_sigint"));
   child.stdout?.on("data", (chunk) => {
     if (failed) return;
+    if (!sawStdout) { sawStdout = true; startupStage("first-rpc-output"); }
     buffer += chunk.toString("utf8");
     if (buffer.length > 8 * 1024 * 1024) { fail("Pi RPC 输出超出预期大小"); return; }
     for (let index; (index = buffer.indexOf("\n")) !== -1;) {
@@ -200,6 +204,7 @@ async function serve(pi, args) {
       }
       if (ready || opening) continue;
       if (record?.type === "response" && record.id === "list-commands") {
+        startupStage("command-list-response");
         if (record.success !== true || !Array.isArray(record.data?.commands)) {
           fail("无法读取 Pi 扩展命令列表");
           return;
@@ -212,6 +217,7 @@ async function serve(pi, args) {
         }
         devReloadCommand = record.data.commands.find((item) => item?.source === "extension"
           && item.sourceInfo?.path === extension && /^web-dev-reload(?::\d+)?$/.test(item.name))?.name;
+        startupStage("opening-web-command");
         child.stdin?.write(JSON.stringify({ id: "open-web", type: "prompt", message: `/${command.name}` }) + "\n");
         continue;
       }
@@ -220,6 +226,7 @@ async function serve(pi, args) {
         return;
       }
       if (record?.type !== "extension_ui_request" || record.method !== "notify" || typeof record.message !== "string" || !record.message.startsWith("pi-webapp: ")) continue;
+      startupStage("web-ready-notification");
       let url;
       try { url = new URL(record.message.slice("pi-webapp: ".length)); }
       catch { continue; }
@@ -252,6 +259,7 @@ async function serve(pi, args) {
     }
   });
   child.stdin?.on("error", (error) => fail(`无法向 Pi 发送启动命令：${error.message}`));
+  startupStage("waiting-command-list");
   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(); });