@baique/pi-web-sky 0.1.0

package/README.ja.md

@@ -0,0 +1,132 @@
+# Pi Web
+
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [Русский](./README.ru.md)
+
+[pi コーディングエージェント](https://github.com/earendil-works/pi) のローカルブラウザー UI です。Pi Web は pi と同じローカル設定とセッションファイルを使用し、ブラウザーから会話の検索と再開、エージェントの実行、モデルやリソースの設定、プロジェクトファイルの確認を行えます。
+
+![構造化された Markdown、ツール呼び出し、プロジェクトナビゲーションとともに pi セッションを表示する Pi Web](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## 機能
+
+- **セッションワークスペース**：プロジェクトごとに会話を閲覧、再開、名前変更、エクスポート、削除し、実行状態、コンテキスト使用量、コスト、コンパクション情報を確認できます。
+- **2 種類の分岐**：**New session** は以前のメッセージから独立したセッションファイルを作成し、**Edit from here** は現在のセッション内にブランチを作成します。
+- **プロジェクトファイルツール**：ファイルの閲覧とアップロード、Git Diff の確認、ソース、Markdown、画像、音声、PDF、DOCX のプレビューに対応し、変更時は自動更新されます。
+- **Git worktree**：同じリポジトリのセッションをまとめたまま、サイドバーからチェックアウトを切り替えられます。
+- **Web での設定**：Pi Web を離れずに、Provider のログインと API Key、モデル、モデルテスト、プラグインパッケージ、スキルを管理できます。
+- **英語と簡体字中国語の UI**：初回はブラウザーの言語に従い、トップバーから言語を切り替えられます。
+
+## クイックスタート
+
+Pi Web には Node.js 22.19.0 以降が必要です。`node --version` でバージョンを確認してから、次を実行します：
+
+```bash
+npx @agegr/pi-web@latest
+```
+
+サーバーの準備が整うと、CLI はブラウザーを自動的に開こうとします。開かない場合は [http://127.0.0.1:30141](http://127.0.0.1:30141) にアクセスしてください。Pi Web はデフォルトで `127.0.0.1` のみをリッスンします。
+
+モデル Provider が未設定の場合は、**Models** パネルを開いてログインするか API Key を追加してください。
+
+`pi-web` コマンドをグローバルにインストールする場合：
+
+```bash
+npm install -g @agegr/pi-web@latest
+pi-web
+```
+
+更新時は、実行中のプロセスを `Ctrl+C` で停止してから同じインストールコマンドを再実行します。アンインストールするには `npm uninstall -g @agegr/pi-web` を実行します。
+
+## 設定
+
+ポートとホスト名では、コマンドラインオプションが対応する環境変数より優先されます。`--no-open` と `PI_WEB_NO_OPEN=1` は、どちらを指定してもブラウザーの自動起動が無効になります。
+
+| オプションまたは環境変数 | 用途 | デフォルト |
+| --- | --- | --- |
+| `--port <port>`、`-p <port>`、または `PORT` | サーバーポート | `30141` |
+| `--hostname <host>`、`-H <host>`、または `PI_WEB_HOSTNAME` | バインドするホスト名 | `127.0.0.1` |
+| `--no-open` または `PI_WEB_NO_OPEN=1` | ブラウザーを自動的に開かない | 自動的に開く |
+| `PI_WEB_ALLOWED_HOSTS` | 追加で許可するプロキシまたはカスタムホスト名。複数指定はカンマ区切りで完全一致 | 未設定 |
+| `PI_WEB_PASSWORD` | HTTP Basic Auth を有効化。ユーザー名は常に `pi` | 認証なし |
+
+例：
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### リモートアクセス
+
+ループバック以外のアドレスにバインドすると、高い権限の操作を実行できるエージェントがネットワークに公開されます。信頼できる LAN で使用する場合も、十分に長いランダムなパスワードを設定してください：
+
+```bash
+PI_WEB_PASSWORD='十分に長いランダムなパスワード' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth は転送中のパスワードを暗号化しません。平文 HTTP で Pi Web をインターネットに公開せず、信頼できるリバースプロキシによる HTTPS または信頼できる VPN を使用してください。リバースプロキシが外部ホスト名を転送する場合は、その名前を完全一致で `PI_WEB_ALLOWED_HOSTS` に追加します。この許可リストは Pi Web のバインド先を変更しません。
+
+### HTTP プロキシ
+
+サーバー側のモデルリクエストと API リクエストは、標準の `HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY` 環境変数を使用します。
+
+macOS または Linux：
+
+```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 @agegr/pi-web@latest
+```
+
+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 @agegr/pi-web@latest
+```
+
+## 注意事項
+
+- **エージェントデータ**：Pi Web はデフォルトで `~/.pi/agent` の pi データを読み込みます。セッションファイルは `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` にあります。別の pi エージェントディレクトリを使用するには `PI_CODING_AGENT_DIR` を設定してください。
+- **ファイルシステムへのアクセス**：Pi Web はエージェントデータディレクトリと、セッションに記録された作業ディレクトリを読み取れる必要があります。既存の pi セッションを共有する場合は、pi と同じファイルシステム環境で Pi Web を実行してください。
+- **共有設定**：Models パネルは pi のモデル、設定、認証情報ストレージを使用するため、変更は両方のインターフェースに反映されます。
+- **ファイルアクセスの範囲**：ファイルブラウザーは、Pi Web で選択した作業ディレクトリと、既知のプロジェクトまたはセッションルートに限定されます。汎用のファイルシステムブラウザーではありません。
+- **Git worktree**：スイッチャーの表示条件、worktree の作成、削除時の動作については [Worktrees in Pi Web](./docs/worktrees.md) を参照してください。
+
+## 開発
+
+```bash
+npm install
+npm run dev
+```
+
+開発サーバーは [http://127.0.0.1:30141](http://127.0.0.1:30141) で動作します。一般的なチェックは次のコマンドで実行します：
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+通常の開発中は `next build` または `npm run build` を実行しないでください。`.next/` に書き込まれ、開発サーバーに影響する可能性があります。ビルドはリリース作業時にのみ実行してください。
+
+コントリビューター向けガイド：[Internationalization](./docs/i18n.md) と [Release process](./docs/release.md)。
+
+## リポジトリ構成
+
+```text
+app/             Next.js UI と API ルート
+components/      React UI コンポーネント
+hooks/           クライアントの状態と操作に関する hooks
+lib/             セッション、エージェント、モデル、ファイル、Git、セキュリティのロジック
+public/          静的アセットと PWA ファイル
+bin/             npm CLI エントリポイントと起動オプションの解析
+docs/            ユーザーおよびコントリビューター向けの個別ガイド
+```
+
+アーキテクチャの説明と詳細なファイルマップについては [AGENTS.md](./AGENTS.md) を参照してください。
+
+## ライセンス
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,168 @@
+# Pi Web — Sky Edition (@baique/pi-web-sky)
+
+> **Sky 皮肤版**：基于 [pi-web](https://github.com/earendil-works/pi)（经 [@agegr/pi-web](https://github.com/agegr/pi-web) 二开）的独立发行版，MIT 协议。
+> 在原生 pi-web 之上新增了 Sky 皮肤：毛玻璃气泡与面板、JetBrains Mono 消息字体、加深/提亮文字对比度、右上角 todo 面板、右下角堆叠弱通知。
+
+[中文文档](./README.zh-CN.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+Local browser UI for the [pi coding agent](https://github.com/earendil-works/pi). Pi Web uses the same local configuration and session files as pi, so you can browse and resume conversations, run agent turns, configure models and resources, and inspect project files from a browser.
+
+## Sky skin（本版新增）
+
+- **毛玻璃界面**：消息气泡、输入框、工具栏、扩展区、顶栏统一 frosted-glass，壁纸可透出
+- **JetBrains Mono 消息字体**（Consolas 回退，中文兜底）
+- **文字对比度**：浅色偏青蓝深色、深色偏白
+- **右上角 todo 面板**：窄面板展示会话 pi-todo 状态，运行中 6s 轮询 + 展开前即时刷新
+- **右下角堆叠弱通知**：扩展/错误等瞬时提示以小卡片堆叠在右下角，自动消失
+- 生产构建与开发隔离（`.next-prod`），不污染 `npm run dev`
+
+![Pi Web displaying a pi session with structured Markdown, tool calls, and project navigation](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## Features
+
+- **Session workspace**: browse, resume, rename, export, and delete conversations grouped by project, with running state, context usage, cost, and compaction details.
+- **Two ways to branch**: **New session** creates an independent session file from an earlier message; **Edit from here** creates a branch inside the current session.
+- **Project file tools**: browse and upload files, inspect Git diffs, and preview source, Markdown, images, audio, PDFs, and DOCX files with automatic refresh.
+- **Git worktrees**: switch checkouts from the sidebar while keeping sessions from the same repository grouped together.
+- **Web-based configuration**: manage provider login and API keys, models, model tests, plugin packages, and skills without leaving Pi Web.
+- **English and Simplified Chinese UI**: Pi Web follows the browser language initially and provides a language switcher in the top bar.
+
+## Quick Start
+
+Pi Web requires Node.js 22.19.0 or newer. Check your version with `node --version`, then run:
+
+```bash
+npx @agegr/pi-web@latest
+```
+
+The CLI opens a browser after the server is ready. If it does not, open [http://127.0.0.1:30141](http://127.0.0.1:30141). Pi Web listens only on `127.0.0.1` by default.
+
+If no model provider is configured yet, open the **Models** panel to sign in or add an API key.
+
+To install the `pi-web` command globally:
+
+```bash
+npm install -g @agegr/pi-web@latest
+pi-web
+```
+
+To update, stop the running process with `Ctrl+C` and run the same install command again. To uninstall, run `npm uninstall -g @agegr/pi-web`.
+
+## Configuration
+
+For port and hostname, command-line options override the corresponding environment variables. Either `--no-open` or `PI_WEB_NO_OPEN=1` disables automatic browser opening.
+
+| Option or environment variable | Purpose | Default |
+| --- | --- | --- |
+| `--port <port>`, `-p <port>`, or `PORT` | Server port | `30141` |
+| `--hostname <host>`, `-H <host>`, or `PI_WEB_HOSTNAME` | Bind hostname | `127.0.0.1` |
+| `--no-open` or `PI_WEB_NO_OPEN=1` | Do not open a browser automatically | Browser opens |
+| `PI_WEB_ALLOWED_HOSTS` | Additional exact proxy or custom hostnames, comma-separated | Unset |
+| `PI_WEB_PASSWORD` | Enable HTTP Basic Auth; the username is always `pi` | Authentication disabled |
+
+For example:
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### Remote Access
+
+Binding to a non-loopback address exposes an agent that can execute high-privilege actions. On a trusted LAN, require a long random password:
+
+```bash
+PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth does not encrypt the password in transit. Do not expose Pi Web over plain HTTP to the internet; use HTTPS through a trusted reverse proxy or a trusted VPN. If a reverse proxy sends an external hostname, add that exact name to `PI_WEB_ALLOWED_HOSTS`. This allow-list does not change the address Pi Web binds to.
+
+### HTTP Proxy
+
+Server-side model and API requests honor the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.
+
+On macOS or Linux:
+
+```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 @agegr/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 @agegr/pi-web@latest
+```
+
+## Notes
+
+- **Agent data**: Pi Web reads pi data from `~/.pi/agent` by default, including session files under `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. Set `PI_CODING_AGENT_DIR` to use another pi agent directory.
+- **Filesystem access**: Pi Web must be able to read the agent data directory and the working directories recorded by its sessions. Run Pi Web in the same filesystem environment as pi when sharing existing sessions.
+- **Shared configuration**: the Models panel uses pi's model, settings, and credential storage, so changes are visible to both interfaces.
+- **File access boundary**: the file browser is limited to working directories selected in Pi Web and project or session roots it already knows about; it is not a general filesystem browser.
+- **Git worktrees**: see [Worktrees in Pi Web](./docs/worktrees.md) for switcher visibility, worktree creation, and removal behavior.
+
+### Downstream Session Context Menu
+
+Electron wrappers and other downstream integrations can provide a session-row
+context menu without patching `SessionSidebar`. Listen for the cancelable
+`pi-web:session-row-contextmenu` browser event and call `preventDefault()`
+synchronously when the integration will handle it:
+
+```js
+window.addEventListener("pi-web:session-row-contextmenu", (event) => {
+  event.preventDefault();
+  const { id, path, cwd, name, clientX, clientY, refresh } = event.detail;
+
+  void openSessionMenu({ id, path, cwd, name, clientX, clientY }).then((changed) => {
+    if (changed) refresh();
+  });
+});
+```
+
+The detail object contains `id`, `path`, `cwd`, optional `name`, pointer
+coordinates, and a `refresh()` callback for actions that change the session
+list. If no listener cancels the extension event, Pi Web preserves the
+browser's native context menu. This hook is browser-side and independent of
+Pi agent extensions.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+The development server runs at [http://127.0.0.1:30141](http://127.0.0.1:30141). Run the common checks with:
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Do not run `next build` or `npm run build` during normal development. It writes to `.next/` and can interfere with the development server; leave builds for release work.
+
+Contributor guides: [Internationalization](./docs/i18n.md) and [Release process](./docs/release.md).
+
+## Repository Layout
+
+```text
+app/             Next.js UI and API routes
+components/      React UI components
+hooks/           Client state and interaction hooks
+lib/             Session, agent, model, file, Git, and security logic
+public/          Static assets and PWA files
+bin/             npm CLI entrypoint and launch option parsing
+docs/            Focused user and contributor guides
+```
+
+See [AGENTS.md](./AGENTS.md) for the architecture notes and detailed file map.
+
+## License
+
+[MIT](./LICENSE)

package/README.ru.md

@@ -0,0 +1,132 @@
+# Pi Web
+
+[English](./README.md) | [中文文档](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+Локальный браузерный интерфейс для [pi coding agent](https://github.com/earendil-works/pi). Pi Web использует те же локальные настройки и файлы сессий, что и pi, поэтому в браузере можно находить и продолжать диалоги, запускать агента, настраивать модели и ресурсы, а также просматривать файлы проекта.
+
+![Pi Web показывает сессию pi со структурированным Markdown, вызовами инструментов и навигацией по проекту](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## Возможности
+
+- **Рабочее пространство сессий**: просмотр, продолжение, переименование, экспорт и удаление диалогов, сгруппированных по проектам, с отображением состояния выполнения, использования контекста, стоимости и сведений о сжатии.
+- **Два способа создать ветку**: **New session** создаёт независимый файл сессии из более раннего сообщения, а **Edit from here** создаёт ветку внутри текущей сессии.
+- **Инструменты для файлов проекта**: просмотр и загрузка файлов, проверка Git Diff, предпросмотр исходного кода, Markdown, изображений, аудио, PDF и DOCX с автоматическим обновлением.
+- **Git worktree**: переключение рабочих деревьев в боковой панели с сохранением общей группы сессий одного репозитория.
+- **Настройка через Web**: управление входом в Provider и API Key, моделями, тестами моделей, пакетами плагинов и навыками без выхода из Pi Web.
+- **Интерфейс на английском и упрощённом китайском**: при первом запуске Pi Web учитывает язык браузера, а затем язык можно переключить в верхней панели.
+
+## Быстрый старт
+
+Для работы Pi Web требуется Node.js 22.19.0 или новее. Проверьте версию командой `node --version`, затем выполните:
+
+```bash
+npx @agegr/pi-web@latest
+```
+
+Когда сервер будет готов, CLI попытается открыть браузер автоматически. Если этого не произошло, откройте [http://127.0.0.1:30141](http://127.0.0.1:30141). По умолчанию Pi Web прослушивает только `127.0.0.1`.
+
+Если Provider модели ещё не настроен, откройте панель **Models**, войдите в учётную запись или добавьте API Key.
+
+Чтобы установить команду `pi-web` глобально:
+
+```bash
+npm install -g @agegr/pi-web@latest
+pi-web
+```
+
+Для обновления остановите запущенный процесс с помощью `Ctrl+C` и повторите ту же команду установки. Для удаления выполните `npm uninstall -g @agegr/pi-web`.
+
+## Настройка
+
+Для порта и имени хоста параметры командной строки имеют приоритет над соответствующими переменными окружения. И `--no-open`, и `PI_WEB_NO_OPEN=1` отключают автоматическое открытие браузера независимо друг от друга.
+
+| Параметр или переменная окружения | Назначение | Значение по умолчанию |
+| --- | --- | --- |
+| `--port <port>`, `-p <port>` или `PORT` | Порт сервера | `30141` |
+| `--hostname <host>`, `-H <host>` или `PI_WEB_HOSTNAME` | Имя хоста для привязки | `127.0.0.1` |
+| `--no-open` или `PI_WEB_NO_OPEN=1` | Не открывать браузер автоматически | Браузер открывается |
+| `PI_WEB_ALLOWED_HOSTS` | Дополнительные точные имена прокси или пользовательских хостов через запятую | Не задано |
+| `PI_WEB_PASSWORD` | Включить HTTP Basic Auth; имя пользователя всегда `pi` | Аутентификация отключена |
+
+Пример:
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### Удалённый доступ
+
+Привязка к адресу, отличному от loopback, открывает сетевой доступ к агенту, способному выполнять операции с широкими полномочиями. Даже в доверенной локальной сети используйте длинный случайный пароль:
+
+```bash
+PI_WEB_PASSWORD='длинный-случайный-пароль' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth не шифрует пароль при передаче. Не публикуйте Pi Web в интернете по обычному HTTP; используйте HTTPS через доверенный обратный прокси или надёжное VPN-подключение. Если обратный прокси передаёт внешнее имя хоста, добавьте это точное имя в `PI_WEB_ALLOWED_HOSTS`. Этот список разрешённых имён не меняет адрес, к которому привязывается Pi Web.
+
+### HTTP-прокси
+
+Для серверных запросов к моделям и API используются стандартные переменные окружения `HTTP_PROXY`, `HTTPS_PROXY` и `NO_PROXY`.
+
+В macOS и Linux:
+
+```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 @agegr/pi-web@latest
+```
+
+В 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 @agegr/pi-web@latest
+```
+
+## Примечания
+
+- **Данные агента**: по умолчанию Pi Web читает данные pi из `~/.pi/agent`, включая файлы сессий в `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. Чтобы использовать другой каталог агента pi, задайте `PI_CODING_AGENT_DIR`.
+- **Доступ к файловой системе**: Pi Web должен иметь доступ для чтения к каталогу данных агента и рабочим каталогам, записанным в сессиях. При совместном использовании существующих сессий запускайте Pi Web в той же файловой среде, что и pi.
+- **Общие настройки**: панель Models использует хранилища моделей, настроек и учётных данных pi, поэтому изменения видны в обоих интерфейсах.
+- **Граница доступа к файлам**: файловый браузер ограничен рабочими каталогами, выбранными в Pi Web, и уже известными корнями проектов или сессий; это не универсальный файловый менеджер.
+- **Git worktree**: условия отображения переключателя, создание рабочих деревьев и их удаление описаны в документе [Worktrees in Pi Web](./docs/worktrees.md).
+
+## Разработка
+
+```bash
+npm install
+npm run dev
+```
+
+Сервер разработки доступен по адресу [http://127.0.0.1:30141](http://127.0.0.1:30141). Основные проверки запускаются командами:
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Не запускайте `next build` или `npm run build` во время обычной разработки. Эти команды записывают данные в `.next/` и могут помешать работе сервера разработки; выполняйте сборку только при подготовке релиза.
+
+Руководства для участников: [Internationalization](./docs/i18n.md) и [Release process](./docs/release.md).
+
+## Структура репозитория
+
+```text
+app/             UI Next.js и маршруты API
+components/      Компоненты интерфейса React
+hooks/           Состояние клиента и обработчики взаимодействий
+lib/             Логика сессий, агента, моделей, файлов, Git и безопасности
+public/          Статические ресурсы и файлы PWA
+bin/             Точка входа npm CLI и разбор параметров запуска
+docs/            Тематические руководства для пользователей и участников
+```
+
+Описание архитектуры и подробная карта файлов приведены в [AGENTS.md](./AGENTS.md).
+
+## Лицензия
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,137 @@
+# Pi Web — Sky 皮肤版（@baique/pi-web-sky）
+
+> **Sky 皮肤版**：基于 [pi-web](https://github.com/earendil-works/pi)（经 [@agegr/pi-web](https://github.com/agegr/pi-web) 二开）的独立发行版，MIT 协议。
+> 在原生 pi-web 之上新增 Sky 皮肤：毛玻璃气泡与面板、JetBrains Mono 消息字体、加深/提亮文字对比度、右上角 todo 面板、右下角堆叠弱通知。
+
+[English](./README.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+[pi 编程智能体](https://github.com/earendil-works/pi)的本地浏览器界面。Pi Web 与 pi 共用本机配置和会话文件，可在浏览器中查找和继续对话、运行智能体、配置模型与资源，并查看项目文件。
+
+中文微信群：请查看 [GitHub Discussions 帖子](https://github.com/agegr/pi-web/discussions/271)。
+
+![Pi Web 展示包含结构化 Markdown、工具调用和项目导航的 pi 会话](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## 功能
+
+- **会话工作区**：按项目查找、继续、重命名、导出和删除对话，并查看运行状态、上下文占用、花费和压缩信息。
+- **两种分支方式**：**新会话**会从较早的消息创建独立会话文件；**从此处编辑**会在当前会话内创建分支。
+- **项目文件工具**：浏览和上传文件、查看 Git Diff，并预览源码、Markdown、图片、音频、PDF 和 DOCX；文件变化后会自动刷新。
+- **Git worktree**：从侧边栏切换 checkout，同时把同一仓库不同 worktree 的会话归在一起。
+- **网页配置**：无需离开 Pi Web，即可管理 Provider 登录和 API Key、模型、模型测试、插件包及技能。
+- **英文和简体中文界面**：Pi Web 首次打开时跟随浏览器语言，也可从顶部栏切换语言。
+
+## 快速开始
+
+Pi Web 要求 Node.js 22.19.0 或更高版本。先用 `node --version` 检查版本，然后运行：
+
+```bash
+npx @agegr/pi-web@latest
+```
+
+服务就绪后，命令行会尝试自动打开浏览器。如果没有打开，请访问 [http://127.0.0.1:30141](http://127.0.0.1:30141)。Pi Web 默认仅监听 `127.0.0.1`。
+
+如果尚未配置模型 Provider，请打开**模型（Models）**面板登录或添加 API Key。
+
+如需全局安装 `pi-web` 命令：
+
+```bash
+npm install -g @agegr/pi-web@latest
+pi-web
+```
+
+更新前先用 `Ctrl+C` 停止正在运行的进程，再次执行同一条安装命令。卸载时运行 `npm uninstall -g @agegr/pi-web`。
+
+## 配置
+
+端口和主机名以命令行参数为准，优先于对应的环境变量。`--no-open` 与 `PI_WEB_NO_OPEN=1` 中任意一个都会关闭自动打开浏览器。
+
+| 参数或环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `--port <端口>`、`-p <端口>` 或 `PORT` | 服务端口 | `30141` |
+| `--hostname <主机>`、`-H <主机>` 或 `PI_WEB_HOSTNAME` | 监听主机名 | `127.0.0.1` |
+| `--no-open` 或 `PI_WEB_NO_OPEN=1` | 不自动打开浏览器 | 自动打开 |
+| `PI_WEB_ALLOWED_HOSTS` | 额外允许的代理或自定义主机名，多个值用逗号分隔，必须精确匹配 | 未设置 |
+| `PI_WEB_PASSWORD` | 启用 HTTP Basic Auth，用户名固定为 `pi` | 不启用认证 |
+
+例如：
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### 远程访问
+
+监听非回环地址会暴露一个可执行高权限操作的智能体。在可信局域网中使用时，请设置足够长的随机密码：
+
+```bash
+PI_WEB_PASSWORD='足够长的随机密码' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth 不会加密传输中的密码。不要通过明文 HTTP 将 Pi Web 暴露到互联网；远程访问应使用可信反向代理提供 HTTPS，或通过可信 VPN。如果反向代理传递外部主机名，请把该名称精确加入 `PI_WEB_ALLOWED_HOSTS`。这个白名单不会改变 Pi Web 的监听地址。
+
+### HTTP 代理
+
+服务端的模型和 API 请求会读取标准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。
+
+macOS 或 Linux：
+
+```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 @agegr/pi-web@latest
+```
+
+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 @agegr/pi-web@latest
+```
+
+## 注意事项
+
+- **智能体数据**：Pi Web 默认读取 `~/.pi/agent` 下的 pi 数据，包括 `sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl` 中的会话文件。可通过 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **文件系统访问**：Pi Web 必须能读取智能体数据目录及会话记录中的工作目录。与现有 pi 会话共用数据时，请让 Pi Web 运行在与 pi 相同的文件系统环境中。
+- **共享配置**：模型面板使用 pi 的模型、设置和凭据存储，因此两种界面都能看到相关更改。
+- **文件访问边界**：文件浏览器仅能访问在 Pi Web 中选择过的工作目录，以及它已识别的项目或会话根目录；它不是通用的文件系统浏览器。
+- **Git worktree**：切换器何时显示、如何创建 worktree，以及删除会产生什么影响，见 [Pi Web 里的 Worktree](./docs/worktrees.zh-CN.md)。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+开发服务器运行在 [http://127.0.0.1:30141](http://127.0.0.1:30141)。常用检查命令：
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+日常开发时不要运行 `next build` 或 `npm run build`。它们会写入 `.next/`，可能干扰开发服务器；仅在发布流程中执行构建。
+
+贡献者文档：[国际化](./docs/i18n.md)和[发布流程](./docs/release.md)。
+
+## 仓库结构
+
+```text
+app/             Next.js 界面和 API 路由
+components/      React 界面组件
+hooks/           客户端状态和交互 hooks
+lib/             会话、智能体、模型、文件、Git 和安全逻辑
+public/          静态资源和 PWA 文件
+bin/             npm CLI 入口及启动参数解析
+docs/            面向用户和贡献者的专题文档
+```
+
+架构说明和详细文件地图见 [AGENTS.md](./AGENTS.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

package/bin/node-version.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const MIN_NODE_VERSION = "22.19.0";
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+function isNodeVersionSupported(version) {
+  const current = parseNodeVersion(version);
+  const minimum = parseNodeVersion(MIN_NODE_VERSION);
+  if (!current || !minimum) return false;
+
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+function getUnsupportedNodeVersionMessage(version) {
+  return [
+    `Pi Web requires Node.js ${MIN_NODE_VERSION} or newer.`,
+    `Current Node.js version: ${version}.`,
+    "Upgrade Node.js and try again: https://nodejs.org/",
+  ].join("\n");
+}
+
+module.exports = {
+  MIN_NODE_VERSION,
+  getUnsupportedNodeVersionMessage,
+  isNodeVersionSupported,
+};

package/bin/pi-web-options.js

@@ -0,0 +1,43 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+function normalizePort(value) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    throw new Error("Port must be a non-negative integer.");
+  }
+
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port > 65535) {
+    throw new Error("Port must be between 0 and 65535.");
+  }
+
+  return String(port);
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  const { values: cliArgs } = parseArgs({
+    args,
+    options: {
+      port:      { type: "string", short: "p" },
+      hostname:  { type: "string", short: "H" },
+      "no-open": { type: "boolean" },
+    },
+    strict: false,
+  });
+
+  return {
+    port: normalizePort(cliArgs.port ?? env.PORT ?? "30141"),
+    hostname: cliArgs.hostname ?? env.PI_WEB_HOSTNAME ?? "127.0.0.1",
+    openBrowser: !cliArgs["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions };