@lyhue1991/pi-web 0.8.6

package/README.ja.md

@@ -0,0 +1,150 @@
+# Pi Web
+
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [Русский](./README.ru.md)
+
+[pi コーディングエージェント](https://github.com/badlogic/pi-mono) のローカル Web UI です。Pi Web はローカルの pi セッションファイルを読み込み、セッションの閲覧、リアルタイムチャット、モデル設定、スキル管理、プロジェクトファイルのプレビューを行えるブラウザワークスペースを提供します。
+
+![Pi Web では、CLI と同じ pi セッションを、構造化された Markdown、ツール呼び出し、プロジェクトナビゲーションとともに表示できます](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+CLI と Pi Web で同じ pi セッションを利用できます。構造化されたツール呼び出し、読みやすい Markdown、セッション閲覧、整理された結果表示を備えています。
+
+## クイックスタート
+
+Pi Web には Node.js 22.19.0 以降が必要です。現在のバージョンは `node --version` で確認できます。
+
+**インストールせずに実行：**
+
+```bash
+npx @lyhue1991/pi-web@latest
+```
+
+**またはグローバルにインストール：**
+
+```bash
+npm install -g @lyhue1991/pi-web
+pi-web
+```
+
+続いて [http://127.0.0.1:30141](http://127.0.0.1:30141) を開きます。サーバーの準備が整うと、CLI はブラウザを自動的に開こうとします。Pi Web はデフォルトで `127.0.0.1` のみをリッスンします。
+
+**オプション：**
+
+```bash
+pi-web --port 8080              # カスタムポート
+pi-web --hostname 0.0.0.0       # 信頼できるネットワークに公開
+pi-web -p 8080 -H 0.0.0.0       # オプションを組み合わせる
+pi-web --no-open                # ブラウザを自動的に開かない
+
+PORT=8080 pi-web                # 環境変数にも対応
+PI_WEB_HOSTNAME=0.0.0.0 pi-web  # ネットワーク公開を明示的に有効化
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # プロキシまたはカスタムホスト名を許可
+PI_WEB_PASSWORD='十分に長いランダムなパスワード' pi-web  # Basic Auth を有効化（ユーザー名: pi）
+PI_WEB_NO_OPEN=1 pi-web         # バックグラウンドサービスとして実行する場合に便利
+```
+
+`PI_WEB_PASSWORD` を設定すると、Web インターフェースとすべての API エンドポイントが HTTP Basic Auth で保護されます。ユーザー名は常に `pi` です。未設定または空の場合、認証は無効です。
+
+Pi Web は高権限のエージェントを呼び出せます。Basic Auth は転送中のパスワードを暗号化しないため、平文 HTTP をインターネットに公開しないでください。リモートアクセスには、信頼できるリバースプロキシによる HTTPS または信頼できる VPN を使用してください。
+API リクエストでは、loopback 名、IP リテラル、選択したバインドホスト名、および `PI_WEB_ALLOWED_HOSTS` にカンマ区切りで指定した完全一致のホスト名のみを受け入れます。信頼できるリバースプロキシが異なる外部ホスト名を使用する場合は、この変数を設定してください。
+
+## HTTP プロキシ
+
+Pi Web は、サーバー側のモデルリクエストと 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 @lyhue1991/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 @lyhue1991/pi-web@latest
+```
+
+## 機能
+
+- **作業をすぐに再開**：セッションのパスやターミナル履歴を探さずに、プロジェクトごとに過去の pi の会話を閲覧できます。
+- **別の方向性を安全に試す**：以前のメッセージから続けるか、セッションをフォークして別の進め方を試せます。
+- **ブランチをまたいで作業**：サイドバーから Git worktree を切り替えると、新しいセッションと Explorer が選択したチェックアウトに追従します。
+- **プロジェクトを見ながらチャット**：エージェントの作業中に、左側でファイルを閲覧し、右側でソース、ドキュメント、画像、音声、PDF をプレビューできます。
+- **セッションの状態を明確に把握**：コンテキスト使用量、コスト、コンパクション状態、システムプロンプトの詳細をトップバーで確認できます。
+- **ターミナルでの設定を削減**：モデル、ログイン／API キー、モデルテスト、スキルの切り替えを Web UI から管理できます。
+
+## 注意事項
+
+- **データディレクトリ**：Pi Web はデフォルトで `~/.pi/agent/sessions` を読み込みます。別の pi エージェントディレクトリを指定するには `PI_CODING_AGENT_DIR` を設定してください。
+- **セッションファイル**：ファイルは `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` に保存されます。
+- **モデル設定**：Models パネルは pi エージェントディレクトリ内の `models.json` を読み書きします。モデルの一覧とデフォルト値は pi の設定から取得されます。
+- **ファイルアクセス**：ファイルの閲覧とプレビューは、選択したプロジェクトディレクトリとセッションに含まれる作業ディレクトリに限定されます。
+- **Git worktree**：切り替え機能が表示される条件、新しい worktree の作成方法、削除時の動作については、[Pi Web の Worktree](./docs/worktrees.md) を参照してください。
+- **Fork とセッション内ブランチの違い**：Fork は新しい `.jsonl` ファイルを作成します。"Edit from here" は同じセッションファイル内に別のブランチを作成します。
+
+## 開発
+
+```bash
+npm install
+npm run dev
+```
+
+ローカル開発サーバーは [http://127.0.0.1:30141](http://127.0.0.1:30141) で動作します。
+
+よく使うチェック：
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+ローカル開発中は `next build` / `npm run build` を実行しないでください。`.next/` に書き込みが行われ、開発サーバーに影響する可能性があります。ビルドはリリース作業に任せてください。
+
+## プロジェクト構成
+
+```text
+app/
+  api/
+    agent/          # AgentSession を作成・操作し、SSE イベントを公開
+    auth/           # OAuth と API キーの管理
+    cwd/validate/   # カスタム作業ディレクトリの検証
+    default-cwd/    # pi のデフォルト作業ディレクトリを取得
+    files/          # ファイルの一覧、読み込み、プレビュー、監視
+    home/           # 現在のユーザーのホームディレクトリ
+    models/         # 利用可能なモデル、デフォルトモデル、思考レベル
+    models-config/  # models.json の読み書きとモデルのテスト
+    sessions/       # セッションの読み込み、名前変更、削除、コンテキスト、HTML エクスポート
+    skills/         # スキルの一覧、検索、インストール、有効化／無効化
+components/
+  AppShell.tsx        # メインレイアウト、URL 状態、上部パネル、ファイルタブ
+  SessionSidebar.tsx  # プロジェクト選択、セッションツリー、Explorer
+  ChatWindow.tsx      # メッセージ、SSE、画像のドラッグ＆ドロップ、ミニマップ
+  ChatInput.tsx       # 入力欄、モデル／ツール／思考／コンパクション／スラッシュコントロール
+  MessageView.tsx     # メッセージ、思考、ツール呼び出し／結果の表示
+  ModelsConfig.tsx    # モデルと認証の設定パネル
+  SkillsConfig.tsx    # スキル管理パネル
+  FileExplorer.tsx    # ファイルツリー
+  FileViewer.tsx      # ソース、差分、画像、音声、PDF、DOCX のプレビュー
+lib/
+  http-dispatcher.ts  # サーバー側 fetch の HTTP(S) プロキシ設定
+  rpc-manager.ts      # AgentSessionWrapper のライフサイクルとグローバルレジストリ
+  session-reader.ts   # .jsonl セッションファイルとブランチコンテキストの解析
+  normalize.ts        # toolCall フィールド名の正規化
+  file-access.ts      # ファイル読み込みの安全境界
+  file-paths.ts       # ファイルパスのエンコードと相対パスのヘルパー
+  markdown.ts         # Markdown／Mermaid／KaTeX プラグインの設定
+  pi-types.ts         # pi 関連の型
+hooks/
+  useAgentSession.ts  # セッションの読み込み、コマンド送信、SSE ステートマシン
+  useAudio.ts         # 完了通知音
+  useDragDrop.ts      # 画像のドラッグ＆ドロップ
+  useTheme.ts         # テーマの切り替え
+bin/
+  pi-web.js           # npm CLI エントリポイント
+instrumentation.ts    # サーバー HTTP ディスパッチャーの初期化
+```

package/README.md

@@ -0,0 +1,155 @@
+# Pi Web
+
+[中文文档](./README.zh-CN.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+Local web UI for the [pi coding agent](https://github.com/badlogic/pi-mono). 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.
+
+![Pi Web shows the same pi session with structured Markdown, tool calls, and project navigation beside the CLI](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+The same pi session in CLI and Pi Web: structured tool calls, readable Markdown, session browsing, and cleaner results.
+
+## Quick Start
+
+Pi Web requires Node.js 22.19.0 or newer. Check your version with `node --version`.
+
+**Run without installing:**
+
+```bash
+npx @lyhue1991/pi-web@latest
+```
+
+**Or install globally:**
+
+```bash
+npm install -g @lyhue1991/pi-web
+pi-web
+```
+
+Then open [http://127.0.0.1:30141](http://127.0.0.1:30141). The CLI will try to open the browser automatically after the server is ready. Pi Web listens on `127.0.0.1` by default.
+
+**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 --no-open                # do not open the browser automatically
+
+PORT=8080 pi-web                # environment variable is also supported
+PI_WEB_HOSTNAME=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_NO_OPEN=1 pi-web         # useful when running as a background service
+```
+
+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 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, the selected bind hostname, and exact comma-separated names in `PI_WEB_ALLOWED_HOSTS`. Configure that variable when a trusted reverse proxy uses a different external hostname.
+
+## HTTP Proxy
+
+Pi Web reads the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for server-side model and API requests.
+
+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 @lyhue1991/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 @lyhue1991/pi-web@latest
+```
+
+## Features
+
+- **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, and skill switches from the web UI.
+- **Use the interface in your language**: switch between the supported UI languages from the top bar.
+
+## Notes
+
+- **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.
+- **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
+
+```bash
+npm install
+npm run dev
+```
+
+The local dev server runs at [http://127.0.0.1:30141](http://127.0.0.1:30141).
+
+Common checks:
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Avoid running `next build` / `npm run build` during local development. It writes to `.next/` and can interfere with the dev server; leave builds for release work.
+
+## Project Structure
+
+```text
+app/
+  api/
+    agent/          # creates/drives AgentSession and exposes SSE events
+    auth/           # OAuth and API key management
+    cwd/browse/     # browsable server directory listing
+    cwd/validate/   # custom working directory validation
+    default-cwd/    # pi default working directory lookup
+    files/          # file listing, reading, preview, and watching
+    home/           # current user home directory
+    models/         # available models, default model, thinking levels
+    models-config/  # read/write models.json and test models
+    sessions/       # session reads, rename, delete, context, HTML export
+    skills/         # skill listing, search, install, enable/disable
+components/
+  AppShell.tsx        # main layout, URL state, top panels, file tabs
+  SessionSidebar.tsx  # project selector, session tree, Explorer
+  DirectoryPicker.tsx # browsable and editable working-directory picker
+  ChatWindow.tsx      # messages, SSE, image drag/drop, minimap
+  ChatInput.tsx       # input bar, model/tools/thinking/compact/slash controls
+  MessageView.tsx     # message, thinking, tool call/result rendering
+  ModelsConfig.tsx    # model and auth configuration panel
+  SkillsConfig.tsx    # skill management panel
+  FileExplorer.tsx    # file tree
+  FileViewer.tsx      # source, diff, image, audio, PDF, DOCX preview
+lib/
+  directory-browser.ts # directory normalization and safe listing helpers
+  http-dispatcher.ts  # HTTP(S) proxy setup for server-side fetch
+  rpc-manager.ts      # AgentSessionWrapper lifecycle and global registry
+  session-reader.ts   # parses .jsonl session files and branch contexts
+  normalize.ts        # normalizes toolCall field names
+  file-access.ts      # file read safety boundary
+  file-paths.ts       # path encoding and relative path helpers
+  markdown.ts         # Markdown/Mermaid/KaTeX plugin configuration
+  pi-types.ts         # pi-related types
+hooks/
+  useAgentSession.ts  # session loading, command sending, SSE state machine
+  useAudio.ts         # completion sound
+  useDragDrop.ts      # image drag/drop
+  useTheme.ts         # theme switching
+bin/
+  pi-web.js           # npm CLI entrypoint
+instrumentation.ts    # initializes the server HTTP dispatcher
+```

package/README.ru.md

@@ -0,0 +1,155 @@
+# Pi Web
+
+[English](./README.md) | [中文文档](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+Локальный веб-интерфейс для [pi coding agent](https://github.com/badlogic/pi-mono). Pi Web читает локальные файлы сессий pi и предоставляет рабочее пространство в браузере для просмотра сессий, общения с агентом в реальном времени, настройки моделей, управления навыками и предварительного просмотра файлов проекта.
+
+![Pi Web показывает одну и ту же сессию pi рядом с CLI: структурированный Markdown, вызовы инструментов и навигация по проекту](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+Одна и та же сессия pi в CLI и Pi Web: структурированные вызовы инструментов, удобочитаемый Markdown, просмотр сессий и наглядные результаты.
+
+## Быстрый старт
+
+Для работы Pi Web требуется Node.js **22.19.0** или новее. Проверьте версию командой `node --version`.
+
+**Запуск без установки:**
+
+```bash
+npx @lyhue1991/pi-web@latest
+```
+
+**Или глобальная установка:**
+
+```bash
+npm install -g @lyhue1991/pi-web
+pi-web
+```
+
+Затем откройте [http://127.0.0.1:30141](http://127.0.0.1:30141). После запуска сервера CLI попытается автоматически открыть браузер. По умолчанию Pi Web прослушивает только `127.0.0.1`.
+
+**Параметры:**
+
+```bash
+pi-web --port 8080              # другой порт
+pi-web --hostname 0.0.0.0       # доступ в доверенной сети
+pi-web -p 8080 -H 0.0.0.0       # сочетание параметров
+pi-web --no-open                # не открывать браузер автоматически
+
+PORT=8080 pi-web                # порт также можно задать переменной окружения
+PI_WEB_HOSTNAME=0.0.0.0 pi-web  # явное разрешение сетевого доступа
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # точное имя прокси или другого хоста
+PI_WEB_PASSWORD='длинный-случайный-пароль' pi-web  # Basic Auth (имя пользователя: pi)
+PI_WEB_NO_OPEN=1 pi-web         # удобно для фоновой службы
+```
+
+Задайте `PI_WEB_PASSWORD`, чтобы защитить веб-интерфейс и все конечные точки API с помощью HTTP Basic Auth. Имя пользователя всегда `pi`. Если переменная не задана или пуста, аутентификация отключена.
+
+Pi Web может вызывать агента с широкими полномочиями. Basic Auth не шифрует пароль при передаче, поэтому не публикуйте обычный HTTP-сервер в интернете. Для удалённого доступа используйте HTTPS через доверенный обратный прокси или надёжное VPN-подключение.
+API-запросы принимаются для loopback-имён, IP-адресов, выбранного имени хоста и точных имён из `PI_WEB_ALLOWED_HOSTS`, разделённых запятыми. Задайте эту переменную, если доверенный обратный прокси использует другое внешнее имя хоста.
+
+## HTTP-прокси
+
+Для серверных запросов к моделям и API Pi Web использует стандартные переменные окружения `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 @lyhue1991/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 @lyhue1991/pi-web@latest
+```
+
+## Возможности
+
+- **Продолжайте работу с прежнего места**: просматривайте предыдущие разговоры с pi по проектам, не разыскивая их в истории терминала или путях к сессиям.
+- **Безопасно пробуйте разные подходы**: продолжайте диалог с более раннего сообщения или создавайте отдельный форк сессии.
+- **Работайте с разными ветками**: переключайте Git worktree в боковой панели, чтобы новые сессии и Explorer следовали за выбранным рабочим деревом.
+- **Общайтесь с агентом рядом с проектом**: просматривайте файлы слева, а исходный код, документы, изображения, аудио и PDF — справа, пока агент работает.
+- **Следите за состоянием сессии**: в верхней панели видны использование контекста, стоимость, состояние сжатия и сведения о системном промпте.
+- **Реже обращайтесь к терминалу**: управляйте моделями, учётными данными для входа и API, тестированием моделей и переключателями навыков в веб-интерфейсе.
+- **Используйте удобный язык интерфейса**: переключайтесь между поддерживаемыми языками в верхней панели.
+
+## Примечания
+
+- **Каталог данных**: по умолчанию Pi Web читает `~/.pi/agent/sessions`. Чтобы указать другой каталог агента pi, задайте `PI_CODING_AGENT_DIR`.
+- **Файлы сессий**: файлы хранятся по пути `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`.
+- **Настройка моделей**: панель Models читает и записывает `models.json` в каталоге агента pi. Список моделей и модель по умолчанию берутся из конфигурации pi.
+- **Доступ к файлам**: просмотр файлов ограничен выбранным каталогом проекта и рабочими каталогами, которые встречаются в сессиях.
+- **Git worktree**: условия отображения переключателя, создание новых рабочих деревьев и их удаление описаны в документе [Worktrees in Pi Web](./docs/worktrees.md).
+- **Форк и ветка внутри сессии**: Fork создаёт новый файл `.jsonl`, а «Edit from here» — другую ветку внутри того же файла сессии.
+- **Интернационализация**: использование переводов и добавление языков или текстов интерфейса описаны в документе [Internationalization](./docs/i18n.md).
+
+## Разработка
+
+```bash
+npm install
+npm run dev
+```
+
+Локальный сервер разработки доступен по адресу [http://127.0.0.1:30141](http://127.0.0.1:30141).
+
+Основные проверки:
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Не запускайте `next build` / `npm run build` во время локальной разработки. Эта команда записывает данные в `.next/` и может помешать работе сервера разработки; выполняйте сборку только при подготовке релиза.
+
+## Структура проекта
+
+```text
+app/
+  api/
+    agent/          # создание и управление AgentSession, события SSE
+    auth/           # управление OAuth и ключами API
+    cwd/browse/     # просмотр каталогов на сервере
+    cwd/validate/   # проверка пользовательского рабочего каталога
+    default-cwd/    # рабочий каталог pi по умолчанию
+    files/          # список, чтение, просмотр и отслеживание файлов
+    home/           # домашний каталог текущего пользователя
+    models/         # доступные модели, модель по умолчанию, уровни рассуждения
+    models-config/  # чтение и запись models.json, проверка моделей
+    sessions/       # чтение, переименование, удаление, контекст и экспорт сессий в HTML
+    skills/         # список, поиск, установка, включение и отключение навыков
+components/
+  AppShell.tsx        # основной макет, состояние URL, верхние панели, вкладки файлов
+  SessionSidebar.tsx  # выбор проекта, дерево сессий, Explorer
+  DirectoryPicker.tsx # просмотр и изменение рабочего каталога
+  ChatWindow.tsx      # сообщения, SSE, перетаскивание изображений, мини-карта
+  ChatInput.tsx       # модели, инструменты, рассуждение, сжатие и слеш-команды
+  MessageView.tsx     # сообщения, рассуждения, вызовы инструментов и результаты
+  ModelsConfig.tsx    # настройка моделей и аутентификации
+  SkillsConfig.tsx    # управление навыками
+  FileExplorer.tsx    # дерево файлов
+  FileViewer.tsx      # просмотр кода, diff, изображений, аудио, PDF и DOCX
+lib/
+  directory-browser.ts # нормализация каталогов и безопасный просмотр
+  http-dispatcher.ts  # настройка HTTP(S)-прокси для серверных запросов
+  rpc-manager.ts      # жизненный цикл AgentSessionWrapper и глобальный реестр
+  session-reader.ts   # разбор файлов сессий .jsonl и контекста веток
+  normalize.ts        # нормализация имён полей toolCall
+  file-access.ts      # границы безопасного чтения файлов
+  file-paths.ts       # кодирование путей и работа с относительными путями
+  markdown.ts         # настройка плагинов Markdown, Mermaid и KaTeX
+  pi-types.ts         # типы, связанные с pi
+hooks/
+  useAgentSession.ts  # загрузка сессии, команды и автомат состояний SSE
+  useAudio.ts         # звук завершения
+  useDragDrop.ts      # перетаскивание изображений
+  useTheme.ts         # переключение темы
+bin/
+  pi-web.js           # точка входа npm CLI
+instrumentation.ts    # инициализация HTTP-диспетчера сервера
+```

package/README.zh-CN.md

@@ -0,0 +1,151 @@
+# Pi Web
+
+[English](./README.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+[pi 编程智能体](https://github.com/badlogic/pi-mono) 的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
+
+中文微信群：请查看 [GitHub Discussions 帖子](https://github.com/agegr/pi-web/discussions/271)。
+
+## 快速开始
+
+Pi Web 要求 Node.js 22.19.0 或更高版本。可通过 `node --version` 检查当前版本。
+
+**无需安装，直接运行：**
+
+```bash
+npx @lyhue1991/pi-web@latest
+```
+
+**或全局安装后使用：**
+
+```bash
+npm install -g @lyhue1991/pi-web
+pi-web
+```
+
+启动后打开 [http://127.0.0.1:30141](http://127.0.0.1:30141)。命令行版本会在服务就绪后尝试自动打开浏览器。Pi Web 默认仅监听 `127.0.0.1`。
+
+**可选参数：**
+
+```bash
+pi-web --port 8080              # 自定义端口
+pi-web --hostname 0.0.0.0       # 在可信网络中开放访问
+pi-web -p 8080 -H 0.0.0.0       # 组合使用
+pi-web --no-open                # 不自动打开浏览器
+
+PORT=8080 pi-web                # 也支持环境变量
+PI_WEB_HOSTNAME=0.0.0.0 pi-web  # 显式开放网络访问
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # 允许指定的代理或自定义主机名
+PI_WEB_PASSWORD='足够长的随机密码' pi-web  # 启用 Basic Auth（用户名固定为 pi）
+PI_WEB_NO_OPEN=1 pi-web         # 适用于后台服务或开机自启
+```
+
+设置 `PI_WEB_PASSWORD` 后，网页和所有 API 端点都会启用 HTTP Basic Auth，用户名固定为 `pi`。未设置或设置为空值时不启用认证。
+
+Pi Web 可以调用高权限智能体。Basic Auth 不会加密传输中的密码，因此不要把明文 HTTP 暴露到互联网。远程访问时应使用可信反向代理提供 HTTPS，或通过可信 VPN 访问。
+API 请求仅接受 loopback 名称、IP 字面量、当前监听主机名，以及 `PI_WEB_ALLOWED_HOSTS` 中以逗号分隔的精确主机名。可信反向代理使用不同的外部主机名时，请配置该变量。
+
+## HTTP 代理
+
+Pi Web 的服务端模型请求和 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 @lyhue1991/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 @lyhue1991/pi-web@latest
+```
+
+## 功能介绍
+
+- **把历史工作接回来**：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
+- **放心试不同方向**：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
+- **跨分支工作**：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
+- **边聊边看项目文件**：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
+- **随时掌握会话状态**：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
+- **少离开当前界面**：模型、登录/API key、模型测试和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
+
+## 注意事项
+
+- **数据目录**：默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **会话文件**：路径形如 `~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`。
+- **模型配置**：Models 面板读写 pi agent 目录下的 `models.json`，模型列表和默认模型由 pi 的配置解析得到。
+- **文件访问**：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
+- **Git worktree**：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 [Pi Web 里的 Worktree](./docs/worktrees.zh-CN.md)。
+- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；“Edit from here” 是同一会话文件里的分支。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+本地开发端口为 [http://127.0.0.1:30141](http://127.0.0.1:30141)。
+
+常用检查：
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+开发时不要运行 `next build` / `npm run build`，它会写入 `.next/`，容易影响正在运行的 dev server。发布流程再执行构建。
+
+## 项目结构
+
+```
+app/
+  api/
+    agent/          # 创建/驱动 AgentSession，提供 SSE 事件流
+    auth/           # OAuth 和 API key 管理
+    cwd/browse/     # 服务端目录浏览
+    cwd/validate/   # 自定义工作目录校验
+    default-cwd/    # 获取 pi 默认工作目录
+    files/          # 文件列表、读取、预览、watch
+    home/           # 当前用户 home 目录
+    models/         # 可用模型、默认模型、thinking levels
+    models-config/  # 读写 models.json、测试模型
+    sessions/       # 会话读取、重命名、删除、上下文、HTML 导出
+    skills/         # skills 列表、搜索、安装、启停
+components/
+  AppShell.tsx        # 主布局、URL 状态、顶部面板、文件标签
+  SessionSidebar.tsx  # 项目选择、会话树、Explorer
+  DirectoryPicker.tsx # 支持浏览和路径输入的工作目录选择器
+  ChatWindow.tsx      # 消息区、SSE、拖拽图片、minimap
+  ChatInput.tsx       # 输入栏、模型/工具/thinking/compact/slash controls
+  MessageView.tsx     # 消息、thinking、tool call/result 渲染
+  ModelsConfig.tsx    # 模型和认证配置面板
+  SkillsConfig.tsx    # 技能管理面板
+  FileExplorer.tsx    # 文件树
+  FileViewer.tsx      # 源码、diff、图片、音频、PDF、DOCX 预览
+lib/
+  directory-browser.ts # 目录规范化和安全枚举工具
+  http-dispatcher.ts  # 服务端 fetch 的 HTTP(S) 代理配置
+  rpc-manager.ts      # AgentSessionWrapper 生命周期和全局 registry
+  session-reader.ts   # 解析 .jsonl 会话文件和分支上下文
+  normalize.ts        # 规范化 toolCall 字段名
+  file-access.ts      # 文件读取安全边界
+  file-paths.ts       # 文件路径编码/相对路径工具
+  markdown.ts         # Markdown/Mermaid/KaTeX 插件配置
+  pi-types.ts         # pi 相关类型
+hooks/
+  useAgentSession.ts  # 会话加载、发送命令、SSE 状态机
+  useAudio.ts         # 完成提示音
+  useDragDrop.ts      # 图片拖拽
+  useTheme.ts         # 主题切换
+bin/
+  pi-web.js           # npm CLI 入口
+instrumentation.ts    # 初始化服务端 HTTP dispatcher
+```

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,
+};