@changliu007/pi-web 0.8.0

package/.next/types/routes.d.ts

@@ -0,0 +1,99 @@
+// This file is generated automatically by Next.js
+// Do not edit this file manually
+
+type AppRoutes = "/"
+type AppRouteHandlerRoutes = "/api/agent/[id]" | "/api/agent/[id]/events" | "/api/agent/new" | "/api/agent/running/events" | "/api/auth/all-providers" | "/api/auth/api-key/[provider]" | "/api/auth/login/[provider]" | "/api/auth/logout/[provider]" | "/api/auth/providers" | "/api/cwd/validate" | "/api/default-cwd" | "/api/directories/list" | "/api/file-index" | "/api/files/[...path]" | "/api/home" | "/api/models" | "/api/models-config" | "/api/models-config/test" | "/api/plugins" | "/api/sessions" | "/api/sessions/[id]" | "/api/sessions/[id]/context" | "/api/sessions/[id]/export" | "/api/skills" | "/api/skills/install" | "/api/skills/search" | "/api/worktrees"
+type PageRoutes = never
+type LayoutRoutes = "/"
+type RedirectRoutes = never
+type RewriteRoutes = never
+type Routes = AppRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes | AppRouteHandlerRoutes
+
+
+interface ParamMap {
+  "/": {}
+  "/api/agent/[id]": { "id": string; }
+  "/api/agent/[id]/events": { "id": string; }
+  "/api/agent/new": {}
+  "/api/agent/running/events": {}
+  "/api/auth/all-providers": {}
+  "/api/auth/api-key/[provider]": { "provider": string; }
+  "/api/auth/login/[provider]": { "provider": string; }
+  "/api/auth/logout/[provider]": { "provider": string; }
+  "/api/auth/providers": {}
+  "/api/cwd/validate": {}
+  "/api/default-cwd": {}
+  "/api/directories/list": {}
+  "/api/file-index": {}
+  "/api/files/[...path]": { "path": string[]; }
+  "/api/home": {}
+  "/api/models": {}
+  "/api/models-config": {}
+  "/api/models-config/test": {}
+  "/api/plugins": {}
+  "/api/sessions": {}
+  "/api/sessions/[id]": { "id": string; }
+  "/api/sessions/[id]/context": { "id": string; }
+  "/api/sessions/[id]/export": { "id": string; }
+  "/api/skills": {}
+  "/api/skills/install": {}
+  "/api/skills/search": {}
+  "/api/worktrees": {}
+}
+
+
+export type ParamsOf<Route extends Routes> = ParamMap[Route]
+
+interface LayoutSlotMap {
+  "/": never
+}
+
+
+export type { AppRoutes, PageRoutes, LayoutRoutes, RedirectRoutes, RewriteRoutes, ParamMap, AppRouteHandlerRoutes }
+
+declare global {
+  /**
+   * Props for Next.js App Router page components
+   * @example
+   * ```tsx
+   * export default function Page(props: PageProps<'/blog/[slug]'>) {
+   *   const { slug } = await props.params
+   *   return <div>Blog post: {slug}</div>
+   * }
+   * ```
+   */
+  interface PageProps<AppRoute extends AppRoutes> {
+    params: Promise<ParamMap[AppRoute]>
+    searchParams: Promise<Record<string, string | string[] | undefined>>
+  }
+
+  /**
+   * Props for Next.js App Router layout components
+   * @example
+   * ```tsx
+   * export default function Layout(props: LayoutProps<'/dashboard'>) {
+   *   return <div>{props.children}</div>
+   * }
+   * ```
+   */
+  type LayoutProps<LayoutRoute extends LayoutRoutes> = {
+    params: Promise<ParamMap[LayoutRoute]>
+    children: React.ReactNode
+  } & {
+    [K in LayoutSlotMap[LayoutRoute]]: React.ReactNode
+  }
+
+  /**
+   * Context for Next.js App Router route handlers
+   * @example
+   * ```tsx
+   * export async function GET(request: NextRequest, context: RouteContext<'/api/users/[id]'>) {
+   *   const { id } = await context.params
+   *   return Response.json({ id })
+   * }
+   * ```
+   */
+  interface RouteContext<AppRouteHandlerRoute extends AppRouteHandlerRoutes> {
+    params: Promise<ParamMap[AppRouteHandlerRoute]>
+  }
+}

package/.next/types/validator.ts

@@ -0,0 +1,313 @@
+// This file is generated automatically by Next.js
+// Do not edit this file manually
+// This file validates that all pages and layouts export the correct types
+
+import type { AppRoutes, LayoutRoutes, ParamMap, AppRouteHandlerRoutes } from "./routes.js"
+import type { ResolvingMetadata, ResolvingViewport } from "next/types.js"
+import type { NextRequest } from 'next/server.js'
+
+type AppPageConfig<Route extends AppRoutes = AppRoutes> = {
+  default: React.ComponentType<{ params: Promise<ParamMap[Route]> } & any> | ((props: { params: Promise<ParamMap[Route]> } & any) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
+  generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
+  generateMetadata?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingMetadata
+  ) => Promise<any> | any
+  generateViewport?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingViewport
+  ) => Promise<any> | any
+  metadata?: any
+  viewport?: any
+}
+
+type LayoutConfig<Route extends LayoutRoutes = LayoutRoutes> = {
+  default: React.ComponentType<LayoutProps<Route>> | ((props: LayoutProps<Route>) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
+  generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
+  generateMetadata?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingMetadata
+  ) => Promise<any> | any
+  generateViewport?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingViewport
+  ) => Promise<any> | any
+  metadata?: any
+  viewport?: any
+}
+
+type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRoutes> = {
+  GET?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  POST?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  PUT?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  PATCH?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  DELETE?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  HEAD?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+  OPTIONS?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response | void> | Response | void
+}
+
+
+// Validate ../../app/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/">> = Specific
+  const handler = {} as typeof import("../../app/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/agent/[id]/events/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/agent/[id]/events">> = Specific
+  const handler = {} as typeof import("../../app/api/agent/[id]/events/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/agent/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/agent/[id]">> = Specific
+  const handler = {} as typeof import("../../app/api/agent/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/agent/new/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/agent/new">> = Specific
+  const handler = {} as typeof import("../../app/api/agent/new/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/agent/running/events/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/agent/running/events">> = Specific
+  const handler = {} as typeof import("../../app/api/agent/running/events/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/auth/all-providers/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/auth/all-providers">> = Specific
+  const handler = {} as typeof import("../../app/api/auth/all-providers/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/auth/api-key/[provider]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/auth/api-key/[provider]">> = Specific
+  const handler = {} as typeof import("../../app/api/auth/api-key/[provider]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/auth/login/[provider]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/auth/login/[provider]">> = Specific
+  const handler = {} as typeof import("../../app/api/auth/login/[provider]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/auth/logout/[provider]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/auth/logout/[provider]">> = Specific
+  const handler = {} as typeof import("../../app/api/auth/logout/[provider]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/auth/providers/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/auth/providers">> = Specific
+  const handler = {} as typeof import("../../app/api/auth/providers/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/cwd/validate/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/cwd/validate">> = Specific
+  const handler = {} as typeof import("../../app/api/cwd/validate/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/default-cwd/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/default-cwd">> = Specific
+  const handler = {} as typeof import("../../app/api/default-cwd/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/directories/list/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/directories/list">> = Specific
+  const handler = {} as typeof import("../../app/api/directories/list/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/file-index/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/file-index">> = Specific
+  const handler = {} as typeof import("../../app/api/file-index/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/files/[...path]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/files/[...path]">> = Specific
+  const handler = {} as typeof import("../../app/api/files/[...path]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/home/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/home">> = Specific
+  const handler = {} as typeof import("../../app/api/home/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/models-config/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/models-config">> = Specific
+  const handler = {} as typeof import("../../app/api/models-config/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/models-config/test/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/models-config/test">> = Specific
+  const handler = {} as typeof import("../../app/api/models-config/test/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/models/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/models">> = Specific
+  const handler = {} as typeof import("../../app/api/models/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/plugins/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/plugins">> = Specific
+  const handler = {} as typeof import("../../app/api/plugins/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/sessions/[id]/context/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions/[id]/context">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/[id]/context/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/sessions/[id]/export/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions/[id]/export">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/[id]/export/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/sessions/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions/[id]">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/sessions/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/skills/install/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/skills/install">> = Specific
+  const handler = {} as typeof import("../../app/api/skills/install/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/skills/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/skills">> = Specific
+  const handler = {} as typeof import("../../app/api/skills/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/skills/search/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/skills/search">> = Specific
+  const handler = {} as typeof import("../../app/api/skills/search/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/worktrees/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees">> = Specific
+  const handler = {} as typeof import("../../app/api/worktrees/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+
+
+
+
+// Validate ../../app/layout.tsx
+{
+  type __IsExpected<Specific extends LayoutConfig<"/">> = Specific
+  const handler = {} as typeof import("../../app/layout.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agegr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# pi-web
+
+[中文文档](./README.zh-CN.md)
+
+> **This is a modified fork of [agegr/pi-web](https://github.com/agegr/pi-web)**, distributed under the same MIT license. Original copyright (c) 2026 agegr is retained in the [LICENSE](./LICENSE).
+
+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](./docs/screenshot2.png)
+
+The same pi session in CLI and pi-web: structured tool calls, readable Markdown, session browsing, and cleaner results.
+
+## Quick Start
+
+**Run without installing:**
+
+```bash
+npx @changliu007/pi-web@latest
+```
+
+**Or install globally:**
+
+```bash
+npm install -g @changliu007/pi-web
+pi-web
+```
+
+Then open [http://localhost:30141](http://localhost:30141). The CLI will try to open the browser automatically after the server is ready.
+
+**Options:**
+
+```bash
+pi-web --port 8080              # custom port
+pi-web --hostname 127.0.0.1     # local access only
+pi-web -p 8080 -H 127.0.0.1     # combine options
+
+PORT=8080 pi-web                # environment variable is also supported
+```
+
+## 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.
+
+## 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.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+The local dev server runs at [http://localhost:30141](http://localhost: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/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
+  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/
+  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
+```

package/README.zh-CN.md

@@ -0,0 +1,112 @@
+# pi-web
+
+[English](./README.md)
+
+> **本项目是 [agegr/pi-web](https://github.com/agegr/pi-web) 的修改分支**，沿用同一 MIT 协议；原作者版权声明 (c) 2026 agegr 保留在 [LICENSE](./LICENSE) 中。
+
+[pi 编程智能体](https://github.com/badlogic/pi-mono) 的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
+
+## 快速开始
+
+**无需安装，直接运行：**
+
+```bash
+npx @changliu007/pi-web@latest
+```
+
+**或全局安装后使用：**
+
+```bash
+npm install -g @changliu007/pi-web
+pi-web
+```
+
+启动后打开 [http://localhost:30141](http://localhost:30141)。命令行版本会在服务就绪后尝试自动打开浏览器。
+
+**可选参数：**
+
+```bash
+pi-web --port 8080              # 自定义端口
+pi-web --hostname 127.0.0.1     # 仅本机访问
+pi-web -p 8080 -H 127.0.0.1     # 组合使用
+
+PORT=8080 pi-web                # 也支持环境变量
+```
+
+## 功能介绍
+
+- **把历史工作接回来**：打开网页就能按项目找到以前的 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://localhost:30141](http://localhost: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/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
+  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/
+  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 入口
+```