@goldenlustre/agent-studio 1.0.1

package/README.ja.md

@@ -0,0 +1,134 @@
+# AgentStudio
+
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [Русский](./README.ru.md)
+
+[pi コーディングエージェント](https://github.com/earendil-works/pi) のローカルブラウザー UI です。AgentStudio は pi と同じローカル設定とセッションファイルを使用し、ブラウザーから会話の検索と再開、エージェントの実行、モデルやリソースの設定、プロジェクトファイルの確認を行えます。
+
+![構造化された Markdown、ツール呼び出し、プロジェクトナビゲーションとともに pi セッションを表示する AgentStudio](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 での設定**：AgentStudio を離れずに、Provider のログインと API Key、モデル、モデルテスト、プラグインパッケージ、スキルを管理できます。
+- **英語、簡体字中国語、繁体字中国語の UI**：初回はブラウザーの言語に従い、トップバーから言語を切り替えられます。
+
+## クイックスタート
+
+AgentStudio には 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) にアクセスしてください。AgentStudio はデフォルトで `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` は、どちらを指定してもブラウザーの自動起動が無効になります。`pi-web --help`（または `-h`）で起動オプションを表示して終了します。未知のオプションはエラーで終了します。
+
+| オプションまたは環境変数 | 用途 | デフォルト |
+| --- | --- | --- |
+| `--help`、`-h` | 起動オプションを表示して終了 | — |
+| `--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` | ブラウザーのパスワードログインを有効化。API はユーザー名 `pi` の Basic Auth も利用可能 | 認証なし |
+
+例：
+
+```bash
+pi-web --help
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### リモートアクセス
+
+ループバック以外のアドレスにバインドすると、高い権限の操作を実行できるエージェントがネットワークに公開されます。信頼できる LAN で使用する場合も、十分に長いランダムなパスワードを設定してください：
+
+```bash
+PI_WEB_PASSWORD='十分に長いランダムなパスワード' pi-web --hostname 0.0.0.0
+```
+
+パスワード認証は接続を暗号化しません。平文 HTTP で AgentStudio をインターネットに公開せず、信頼できるリバースプロキシによる HTTPS または信頼できる VPN を使用してください。リバースプロキシが外部ホスト名を転送する場合は、その名前を完全一致で `PI_WEB_ALLOWED_HOSTS` に追加します。この許可リストは AgentStudio のバインド先を変更しません。
+
+### 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
+```
+
+## 注意事項
+
+- **エージェントデータ**：AgentStudio はデフォルトで `~/.pi/agent` の pi データを読み込みます。セッションファイルは `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` にあります。別の pi エージェントディレクトリを使用するには `PI_CODING_AGENT_DIR` を設定してください。
+- **ファイルシステムへのアクセス**：AgentStudio はエージェントデータディレクトリと、セッションに記録された作業ディレクトリを読み取れる必要があります。既存の pi セッションを共有する場合は、pi と同じファイルシステム環境で AgentStudio を実行してください。
+- **共有設定**：Models パネルは pi のモデル、設定、認証情報ストレージを使用するため、変更は両方のインターフェースに反映されます。
+- **ファイルアクセスの範囲**：ファイルブラウザーは、AgentStudio で選択した作業ディレクトリと、既知のプロジェクトまたはセッションルートに限定されます。汎用のファイルシステムブラウザーではありません。
+- **Git worktree**：スイッチャーの表示条件、worktree の作成、削除時の動作については [Worktrees in AgentStudio](./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,184 @@
+# AgentStudio
+
+[中文文档](./README.zh-CN.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+Local browser UI for the [pi coding agent](https://github.com/earendil-works/pi). AgentStudio 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.
+
+![AgentStudio 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 AgentStudio.
+- **English, Simplified Chinese, and Traditional Chinese UI**: AgentStudio follows the browser language initially and provides a language switcher in the top bar.
+
+## Quick Start
+
+AgentStudio 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). AgentStudio 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. Run `pi-web --help` (or `-h`) to print startup options and exit without starting the server. Unknown options exit with an error.
+
+| Option or environment variable | Purpose | Default |
+| --- | --- | --- |
+| `--help`, `-h` | Print startup options and exit | — |
+| `--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_SKIP_VERSION_CHECK=1` | Disable AgentStudio update checks | Unset |
+| `PI_WEB_ALLOWED_HOSTS` | Additional exact proxy or custom hostnames, comma-separated | Unset |
+| `PI_WEB_PASSWORD` | Enable browser password login; API clients may use Basic Auth with username `pi` | Authentication disabled |
+| `PI_WEB_IDLE_TIMEOUT_MS` | Session idle timeout in milliseconds, up to `2147483647`; `0` disables idle shutdown; invalid or out-of-range values use the default | `600000` (10 min) |
+
+For example:
+
+```bash
+pi-web --help
+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
+```
+
+Password authentication does not encrypt the connection. Do not expose AgentStudio 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 AgentStudio 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**: AgentStudio 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**: AgentStudio must be able to read the agent data directory and the working directories recorded by its sessions. Run AgentStudio 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 AgentStudio and project or session roots it already knows about; it is not a general filesystem browser.
+- **Git worktrees**: see [Worktrees in AgentStudio](./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, AgentStudio preserves the
+browser's native context menu. This hook is browser-side and independent of
+Pi agent extensions.
+
+### Extension Session Liveness
+
+Server-side Pi extensions with detached work can prevent automatic idle
+session eviction through the versioned global registry:
+
+```js
+const liveness = globalThis[Symbol.for("@agegr/pi-web/session-liveness/v1")];
+const release = liveness?.version === 1
+  ? liveness.register({
+      name: "my-extension",
+      sessionId,
+      sessionFile: sessionFile || undefined,
+      isActive: () => detachedJobs.size > 0,
+    })
+  : () => {};
+```
+
+Register once per active extension session and call the returned idempotent
+`release` function on session shutdown, replacement, or reload. `isActive`
+must be synchronous, cheap, and scoped to the supplied exact session id or
+file. Provider errors fail safe by preserving that session. This lease only
+affects automatic idle eviction; explicit shutdown and Stop fallback cleanup
+still take precedence.
+
+## 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,134 @@
+# AgentStudio
+
+[English](./README.md) | [中文文档](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+Локальный браузерный интерфейс для [pi coding agent](https://github.com/earendil-works/pi). AgentStudio использует те же локальные настройки и файлы сессий, что и pi, поэтому в браузере можно находить и продолжать диалоги, запускать агента, настраивать модели и ресурсы, а также просматривать файлы проекта.
+
+![AgentStudio показывает сессию 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, моделями, тестами моделей, пакетами плагинов и навыками без выхода из AgentStudio.
+- **Интерфейс на английском, упрощённом и традиционном китайском**: при первом запуске AgentStudio учитывает язык браузера, а затем язык можно переключить в верхней панели.
+
+## Быстрый старт
+
+Для работы AgentStudio требуется 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). По умолчанию AgentStudio прослушивает только `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` отключают автоматическое открытие браузера независимо друг от друга. `pi-web --help` (или `-h`) выводит параметры запуска и завершает работу без старта сервера. Неизвестные параметры завершают процесс с ошибкой.
+
+| Параметр или переменная окружения | Назначение | Значение по умолчанию |
+| --- | --- | --- |
+| `--help`, `-h` | Показать параметры запуска и выйти | — |
+| `--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` | Включить вход по паролю в браузере; API также поддерживает Basic Auth с именем `pi` | Аутентификация отключена |
+
+Пример:
+
+```bash
+pi-web --help
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### Удалённый доступ
+
+Привязка к адресу, отличному от loopback, открывает сетевой доступ к агенту, способному выполнять операции с широкими полномочиями. Даже в доверенной локальной сети используйте длинный случайный пароль:
+
+```bash
+PI_WEB_PASSWORD='длинный-случайный-пароль' pi-web --hostname 0.0.0.0
+```
+
+Парольная аутентификация не шифрует соединение. Не публикуйте AgentStudio в интернете по обычному HTTP; используйте HTTPS через доверенный обратный прокси или надёжное VPN-подключение. Если обратный прокси передаёт внешнее имя хоста, добавьте это точное имя в `PI_WEB_ALLOWED_HOSTS`. Этот список разрешённых имён не меняет адрес, к которому привязывается AgentStudio.
+
+### 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
+```
+
+## Примечания
+
+- **Данные агента**: по умолчанию AgentStudio читает данные pi из `~/.pi/agent`, включая файлы сессий в `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. Чтобы использовать другой каталог агента pi, задайте `PI_CODING_AGENT_DIR`.
+- **Доступ к файловой системе**: AgentStudio должен иметь доступ для чтения к каталогу данных агента и рабочим каталогам, записанным в сессиях. При совместном использовании существующих сессий запускайте AgentStudio в той же файловой среде, что и pi.
+- **Общие настройки**: панель Models использует хранилища моделей, настроек и учётных данных pi, поэтому изменения видны в обоих интерфейсах.
+- **Граница доступа к файлам**: файловый браузер ограничен рабочими каталогами, выбранными в AgentStudio, и уже известными корнями проектов или сессий; это не универсальный файловый менеджер.
+- **Git worktree**: условия отображения переключателя, создание рабочих деревьев и их удаление описаны в документе [Worktrees in AgentStudio](./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,136 @@
+# AgentStudio
+
+[English](./README.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+[pi 编程智能体](https://github.com/earendil-works/pi)的本地浏览器界面。AgentStudio 与 pi 共用本机配置和会话文件，可在浏览器中查找和继续对话、运行智能体、配置模型与资源，并查看项目文件。
+
+中文微信群：请查看 [GitHub Discussions 帖子](https://github.com/agegr/pi-web/discussions/271)。
+
+![AgentStudio 展示包含结构化 Markdown、工具调用和项目导航的 pi 会话](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## 功能
+
+- **会话工作区**：按项目查找、继续、重命名、导出和删除对话，并查看运行状态、上下文占用、花费和压缩信息。
+- **两种分支方式**：**新会话**会从较早的消息创建独立会话文件；**从此处编辑**会在当前会话内创建分支。
+- **项目文件工具**：浏览和上传文件、查看 Git Diff，并预览源码、Markdown、图片、音频、PDF 和 DOCX；文件变化后会自动刷新。
+- **Git worktree**：从侧边栏切换 checkout，同时把同一仓库不同 worktree 的会话归在一起。
+- **网页配置**：无需离开 AgentStudio，即可管理 Provider 登录和 API Key、模型、模型测试、插件包及技能。
+- **英文、简体中文和繁体中文界面**：AgentStudio 首次打开时跟随浏览器语言，也可从顶部栏切换语言。
+
+## 快速开始
+
+AgentStudio 要求 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)。AgentStudio 默认仅监听 `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` 中任意一个都会关闭自动打开浏览器。运行 `pi-web --help`（或 `-h`）可打印启动选项并以退出码 0 结束，不会启动服务；未知参数会报错并以退出码 1 结束。
+
+| 参数或环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `--help`、`-h` | 打印启动选项并退出 | — |
+| `--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` | 启用浏览器密码登录；API 客户端可使用用户名为 `pi` 的 Basic Auth | 不启用认证 |
+
+例如：
+
+```bash
+pi-web --help
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### 远程访问
+
+监听非回环地址会暴露一个可执行高权限操作的智能体。在可信局域网中使用时，请设置足够长的随机密码：
+
+```bash
+PI_WEB_PASSWORD='足够长的随机密码' pi-web --hostname 0.0.0.0
+```
+
+密码认证不会加密连接。不要通过明文 HTTP 将 AgentStudio 暴露到互联网；远程访问应使用可信反向代理提供 HTTPS，或通过可信 VPN。如果反向代理传递外部主机名，请把该名称精确加入 `PI_WEB_ALLOWED_HOSTS`。这个白名单不会改变 AgentStudio 的监听地址。
+
+### 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
+```
+
+## 注意事项
+
+- **智能体数据**：AgentStudio 默认读取 `~/.pi/agent` 下的 pi 数据，包括 `sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl` 中的会话文件。可通过 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **文件系统访问**：AgentStudio 必须能读取智能体数据目录及会话记录中的工作目录。与现有 pi 会话共用数据时，请让 AgentStudio 运行在与 pi 相同的文件系统环境中。
+- **共享配置**：模型面板使用 pi 的模型、设置和凭据存储，因此两种界面都能看到相关更改。
+- **文件访问边界**：文件浏览器仅能访问在 AgentStudio 中选择过的工作目录，以及它已识别的项目或会话根目录；它不是通用的文件系统浏览器。
+- **Git worktree**：切换器何时显示、如何创建 worktree，以及删除会产生什么影响，见 [AgentStudio 里的 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)