@rainmanhhh/pi-web 0.15.25 → 0.15.27

package/README.md

@@ -1,152 +1,123 @@
 # Pi Web
 
-[中文文档](./README.zh-CN.md)
+[pi 编程智能体](https://github.com/earendil-works/pi)（核心 npm 包 [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)）的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
 
-Local web UI for the [pi coding agent](https://github.com/earendil-works/pi) (core npm package [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)). Pi Web reads your local pi session files and gives you a browser workspace for session browsing, real-time chat, model configuration, skill management, and project file preview.
+本项目是 [@agegr/pi-web](https://github.com/agegr/pi-web) 的 fork。
 
-This project is a fork of [@agegr/pi-web](https://github.com/agegr/pi-web).
+## 快速开始
 
-The same pi session in CLI and Pi Web: structured tool calls, readable Markdown, session browsing, and cleaner results.
+Pi Web 要求 Node.js 24.0.0 或更高版本。可通过 `node --version` 检查当前版本。
 
-## Quick Start
-
-Pi Web requires Node.js 24.0.0 or newer. Check your version with `node --version`.
-
-**Run without installing:**
+**无需安装，直接运行：**
 
 ```bash
 npx @rainmanhhh/pi-web@latest
 ```
 
-**Or install globally:**
+**或全局安装后使用：**
 
 ```bash
-npm install -g @rainmanhhh/pi-web  # 或 bun add -g @rainmanhhh/pi-web
+npm install -g @rainmanhhh/pi-web
 pi-web
 ```
 
-The packaged server listens on `http://127.0.0.1:31415` by default and binds `127.0.0.1`. It serves the API and the built frontend from one process; add `--open` to open the browser automatically once it is ready.
+发布版服务默认监听 `http://127.0.0.1:31415` 并绑定 `127.0.0.1`，单进程同时提供 API 和构建后的前端；加 `--open` 可在服务就绪后自动打开浏览器。
 
-**Options:**
+**可选参数：**
 
 ```bash
-pi-web --port 8080              # custom port
-pi-web --hostname 0.0.0.0       # expose on a trusted network
-pi-web -p 8080 -H 0.0.0.0       # combine options
-pi-web --open                   # open the browser when the server is ready
-pi-web --agent-dir ~/.pi/agent  # point at another pi agent directory
-pi-web -d                       # verbose debug logs (also written to server.log)
-
-PORT=8080 pi-web                # environment variable is also supported
-HOST=0.0.0.0 pi-web             # explicit network exposure
-PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # allow an exact proxy/custom hostname
-PI_WEB_PASSWORD='a-long-random-password' pi-web  # require Basic Auth (username: pi)
+pi-web --port 8080              # 自定义端口
+pi-web --hostname 0.0.0.0       # 在可信网络中开放访问
+pi-web -p 8080 -H 0.0.0.0       # 组合使用
+pi-web --open                   # 服务就绪后自动打开浏览器
+pi-web --agent-dir ~/.pi/agent  # 指定其他 pi agent 目录
+pi-web -d                       # 输出调试日志（同时写入 server.log）
+
+PORT=8080 pi-web                # 也支持环境变量
+HOST=0.0.0.0 pi-web             # 显式开放网络访问
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # 允许指定的代理或自定义主机名
+PI_WEB_PASSWORD='足够长的随机密码' pi-web  # 启用 Basic Auth（用户名固定为 pi）
 ```
 
-Set `PI_WEB_PASSWORD` to protect the web interface and every API endpoint with HTTP Basic Auth. The username is always `pi`. Leaving the variable unset or empty disables authentication.
+设置 `PI_WEB_PASSWORD` 后，网页和所有 API 端点都会启用 HTTP Basic Auth，用户名固定为 `pi`。未设置或设置为空值时不启用认证。
 
-Pi Web can invoke a high-privilege agent. Basic Auth does not encrypt the password in transit, so do not expose plain HTTP to the internet. Use HTTPS through a trusted reverse proxy or a trusted VPN for remote access.
-API requests accept loopback names, IP literals, and exact comma-separated names in `PI_WEB_ALLOWED_HOSTS`. Configure that variable when a trusted reverse proxy uses a different external hostname. `PI_WEB_HOSTNAME` is a legacy alias for the same allow-list — it does **not** control the bind address (use `HOST` for that).
+Pi Web 可以调用高权限智能体。Basic Auth 不会加密传输中的密码，因此不要把明文 HTTP 暴露到互联网。远程访问时应使用可信反向代理提供 HTTPS，或通过可信 VPN 访问。
+API 请求仅接受 loopback 名称、IP 字面量，以及 `PI_WEB_ALLOWED_HOSTS` 中以逗号分隔的精确主机名。可信反向代理使用不同的外部主机名时，请配置该变量。`PI_WEB_HOSTNAME` 是该白名单的旧别名，**不**控制监听地址（绑定地址请用 `HOST`）。
 
-## HTTP Proxy
+## 运行时：Node.js 还是 Bun
 
-Pi Web reads the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for server-side model and API requests.
+发布产物里声明的是 `#!/usr/bin/env node`，各启动器都会遵循这个 shebang —— Windows 的 npm shim 调用 Node，Bun 也会启动 Node 进程来执行。因此**默认运行时始终是 Node**。
 
-On macOS or Linux:
+Pi Web 同样支持 Bun，且启动更快（会话文件很多的项目收益最明显）。Bun 默认尊重 shebang，所以要显式指定，`--bun` 必须写在包名**之前**：
 
 ```bash
-HTTP_PROXY=http://127.0.0.1:7890 \
-HTTPS_PROXY=http://127.0.0.1:7890 \
-NO_PROXY=localhost,127.0.0.1 \
-npx @rainmanhhh/pi-web@latest
-```
-
-On Windows PowerShell:
-
-```powershell
-$env:HTTP_PROXY = "http://127.0.0.1:7890"
-$env:HTTPS_PROXY = "http://127.0.0.1:7890"
-$env:NO_PROXY = "localhost,127.0.0.1"
-npx @rainmanhhh/pi-web@latest
+bunx --bun @rainmanhhh/pi-web@latest   # 无需安装，直接运行
+bunx --bun pi-web                      # 已全局安装时
 ```
 
-## Features
+直接 `bunx pi-web` 仍然跑在 Node 上。Node 是经过充分测试的配置；如果在 Bun 下出现异常，请先换回 Node 复现，以区分运行时差异与程序缺陷。
 
-- **Pick work back up**: browse previous pi conversations by project without digging through terminal history or session paths.
-- **Try different directions safely**: continue from an earlier message or fork a session into a separate route.
-- **Work across branches**: switch Git worktrees from the sidebar so new sessions and the Explorer follow the checkout you choose.
-- **Chat beside the project**: browse files on the left and preview source, docs, images, audio, and PDFs on the right while the agent works.
-- **See session state clearly**: context usage, cost, compaction state, and system prompt details are visible from the top bar.
-- **Configure less from the terminal**: manage models, login/API keys, model tests, thinking levels, and skill switches from the web UI.
-- **Commit faster from the Explorer**: stage, commit, and push from the web UI, with AI-generated Conventional Commits messages — use a small fixed model or follow the current chat model. Remotes are auto-fetched in the background for active workspaces (interval configurable in Settings → Git), so pull readiness is always up to date.
-- **Stay updated automatically**: pi-web checks for updates to itself and installed plugins on startup — an in-app banner and the Settings center's Updates section tell you when something new is available. You can disable the checks or ignore a specific version there.
-- **Use the interface in your language**: switch between the supported UI languages from the top bar.
+## 功能介绍
 
-## Notes
+- **把历史工作接回来**：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
+- **放心试不同方向**：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
+- **跨分支工作**：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
+- **边聊边看项目文件**：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
+- **随时掌握会话状态**：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
+- **少离开当前界面**：模型、登录/API key、模型测试、思考级别和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
+- **在 Explorer 里更快提交**：网页内完成暂存、提交和推送，还能用 AI 生成符合 Conventional Commits 的提交信息——可以固定用一个小模型，也可以跟随当前会话的主模型。活动工作区的远端由服务端在后台自动 fetch（间隔可在 设置 → Git 里调整），随时都能看到是否有内容可拉取。
+- **更新自动提醒**：打开应用时自动检查 pi-web 和已装插件是否有新版本——有更新时聊天区顶部横幅提示，设置中心的更新分区也能随时手动检查；检测可在设置中关闭，某个版本也可以单独忽略。
+- **界面语言可选**：在顶部栏切换界面支持的 UI 语言。
 
-- **Data directory**: Pi Web reads `~/.pi/agent/sessions` by default. Set `PI_CODING_AGENT_DIR` to point at another pi agent directory.
-- **Session files**: files are stored as `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`.
-- **Model config**: the Models panel reads and writes `models.json` in the pi agent directory. Model lists and defaults come from pi's config; lists synced from a provider's `/models` endpoint are cached under `<agentDir>/pi-web/provider/`.
-- **Preferences**: UI preferences (scroll step, auto-reload, long-block collapse, …) live in `<agentDir>/pi-web/config.json` (default `~/.pi/agent/pi-web/config.json`). The browser's `localStorage` holds a front-end copy; the server file is the source of truth for other clients. The legacy `pi-web-preferences.json` is migrated once on startup.
-- **File access**: file browsing and preview are scoped to the selected project directory and working directories that appear in sessions.
-- **Git worktrees**: see [Worktrees in Pi Web](./docs/worktrees.md) for when the switcher appears, how new worktrees are created, and what removal does.
-- **Forks vs in-session branches**: Fork creates a new `.jsonl` file. "Edit from here" creates another branch inside the same session file.
-- **Internationalization**: see [Internationalization](./docs/i18n.md) for using translations and adding languages or UI text.
+## 注意事项
 
-## Development
+- **数据目录**：默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **会话文件**：路径形如 `~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`。
+- **模型配置**：Models 面板读写 pi agent 目录下的 `models.json`，模型列表和默认模型由 pi 的配置解析得到；从服务商 `/models` 端点同步的模型列表缓存在 `<agentDir>/pi-web/provider/` 下。
+- **偏好配置**：UI 偏好（滚动步长、自动刷新、长块折叠等）保存在 pi agent 目录下的 `pi-web/config.json`（默认 `~/.pi/agent/pi-web/config.json`）。浏览器 `localStorage` 是前端副本，服务端文件是其他客户端读取的权威来源。旧版 `pi-web-preferences.json` 会在启动时一次性迁移。
+- **文件访问**：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
+- **Git worktree**：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 [Pi Web 里的 Worktree](./docs/worktrees.md)。
+- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；"Edit from here" 是同一会话文件里的分支。
+- **国际化**：翻译使用与新增语言/UI 文案的方法见 [Internationalization](./docs/i18n.md)。
+- **代理支持**：Pi Web **不会**读取 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。需要让服务端请求走代理时，请改用系统层方案（TUN / 透明代理）——无需应用配合，且覆盖所有请求。
 
-Developer-facing debugging guide (fixture URLs, manual verification scenarios, e2e tips): [docs/development.md](./docs/development.md).
+## 开发
 
-Requires [Bun](https://bun.sh) and Node.js 24.0.0+.
+需要 [Bun](https://bun.sh) 和 Node.js 24.0.0+。面向开发者的调试指南（手动端口隔离、fixture URL 参数、手动验证场景、e2e 技巧）见 [docs/development.md](./docs/development.md)，发布流程见 [docs/release.md](./docs/release.md)。
 
 ```bash
 bun install
 ```
 
-Run the API server and the Vite dev server in two terminals:
+两个终端分别跑 API 服务和 Vite dev server：
 
 ```bash
-bun run api     # Hono API server on http://127.0.0.1:30002
-bun run dev     # Vite dev server on http://127.0.0.1:30001 (proxies /api → :30002)
+bun run api     # Hono API 服务，http://127.0.0.1:30002
+bun run dev     # Vite dev server，http://127.0.0.1:30001（/api 代理到 :30002）
 ```
 
-Open [http://127.0.0.1:30001](http://127.0.0.1:30001). The dev proxy target defaults to `30002`; override it with `VITE_API_PORT` if your API server runs elsewhere.
-
-Common checks:
-
-```bash
-bun run check        # tsc --noEmit
-bun run lint
-bun run test:unit
-bun run test:e2e   # Playwright; e2e uses isolated ports (E2E_API_PORT etc.)
-```
-
-Avoid running `bun run build` during local development. It writes to `dist/` and can interfere with the dev server; leave builds for release work.
-
-Other scripts: `bun run check` (tsc --noEmit), `bun run format` (biome), `bun run build:server` (bundle the API for Node), `bun run api:node` (run the bundled server), `bun run e2e:stop` (kill leftover e2e processes). Publish with `pnpm publish` (use `pnpm publish --dry-run` to preview the pack) — `prepublishOnly` runs check + builds both the frontend and the server bundle first, and `publishConfig.access` makes the scoped package public.
-
-Known issue: `bun publish` does not read the `//registry.npmjs.org/:_authToken` from `.npmrc`/`~/.npmrc` (loginless publish config) and fails with `error: missing authentication (run bunx npm login)` — use `pnpm publish` instead, which reads the token.
+打开 [http://127.0.0.1:30001](http://127.0.0.1:30001)。
 
-## Project Structure
+## 项目结构
 
 ```text
 src/
-  components/   # React UI: AppShell, SessionSidebar, ChatWindow, ChatInput,
-                #   MessageView, ModelsConfig, SkillsConfig, FileExplorer, FileViewer, …
-  hooks/        # useAgentSession (WebSocket bus state machine), useTheme, useDragDrop, …
-  lib/          # session .jsonl parsing, RPC manager, file-access safety,
-                #   request security, i18n, markdown setup
-  main.tsx      # frontend entry
+  components/   # React UI：AppShell、SessionSidebar、ChatWindow、ChatInput、
+                #   MessageView、ModelsConfig、SkillsConfig、FileExplorer、FileViewer 等
+  hooks/        # useAgentSession（WebSocket 总线状态机）、useTheme、useDragDrop 等
+  lib/          # 会话 .jsonl 解析、RPC manager、文件访问安全边界、
+                #   请求安全、i18n、markdown 配置
+  main.tsx      # 前端入口
 server/
-  main.ts       # API entry + pi-web CLI (Bun or Node, honors PORT/HOST,
-                #   --port/--hostname/--open/--agent-dir)
-  index.ts      # Hono app wiring
-  routes/       # API handlers: agent, auth, cwd, files, git, models,
-                #   sessions, skills, worktrees, preferences, project-trust, …
-  static.ts     # serves dist/static in production (single-process mode)
-  mount.ts      # Next-style route-module adapter for Hono
-scripts/        # e2e-stop, cdp-capture helpers
-tests/e2e/      # Playwright specs and fixtures
-vite.config.ts        # dev server (:30001), /api proxy → :30002, build outDir
-playwright.config.ts  # e2e webServers (API + Vite) on isolated ports
+  main.ts       # API 入口 + pi-web CLI（Bun 或 Node，支持 PORT/HOST、
+                #   --port/--hostname/--open/--agent-dir）
+  index.ts      # Hono app 装配
+  routes/       # API 处理器：agent、auth、cwd、files、git、models、
+                #   sessions、skills、worktrees、preferences、project-trust 等
+  static.ts     # 生产环境提供 dist/static（单进程模式）
+  mount.ts      # 路由模块（每个路径一个 route.ts）到 Hono 的适配
+scripts/        # e2e-stop、cdp-capture、prune-fonts（build 后清理字体）等辅助脚本
+tests/e2e/      # Playwright 测试与 fixtures
+vite.config.ts        # dev server（:30001）、/api 代理 → :30002、build outDir
+playwright.config.ts  # e2e webServer（API + Vite）
 ```