pi-app 0.7.0

package/.next/types/validator.ts

@@ -0,0 +1,511 @@
+// 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/share/[token]/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/share/[token]">> = Specific
+  const handler = {} as typeof import("../../app/share/[token]/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]/export.html/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/agent/[id]/export.html">> = Specific
+  const handler = {} as typeof import("../../app/api/agent/[id]/export.html/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/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/extensions/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/extensions">> = Specific
+  const handler = {} as typeof import("../../app/api/extensions/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/files/stage/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/files/stage">> = Specific
+  const handler = {} as typeof import("../../app/api/files/stage/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/git-branch/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/git-branch">> = Specific
+  const handler = {} as typeof import("../../app/api/git-branch/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/health/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/health">> = Specific
+  const handler = {} as typeof import("../../app/api/health/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/history/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/history/[id]">> = Specific
+  const handler = {} as typeof import("../../app/api/history/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/history/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/history">> = Specific
+  const handler = {} as typeof import("../../app/api/history/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/notifications/agent-end/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/notifications/agent-end">> = Specific
+  const handler = {} as typeof import("../../app/api/notifications/agent-end/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/preferences/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/preferences">> = Specific
+  const handler = {} as typeof import("../../app/api/preferences/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/product-sessions/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/product-sessions/[id]">> = Specific
+  const handler = {} as typeof import("../../app/api/product-sessions/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/push/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/push">> = Specific
+  const handler = {} as typeof import("../../app/api/push/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/remote/audit/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/remote/audit">> = Specific
+  const handler = {} as typeof import("../../app/api/remote/audit/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/remote/client/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/remote/client">> = Specific
+  const handler = {} as typeof import("../../app/api/remote/client/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/remote/pair/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/remote/pair">> = Specific
+  const handler = {} as typeof import("../../app/api/remote/pair/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/remote/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/remote">> = Specific
+  const handler = {} as typeof import("../../app/api/remote/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/scene-overrides/[sceneId]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/scene-overrides/[sceneId]">> = Specific
+  const handler = {} as typeof import("../../app/api/scene-overrides/[sceneId]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/scene-overrides/export/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/scene-overrides/export">> = Specific
+  const handler = {} as typeof import("../../app/api/scene-overrides/export/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/scene-overrides/import/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/scene-overrides/import">> = Specific
+  const handler = {} as typeof import("../../app/api/scene-overrides/import/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/scene-overrides/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/scene-overrides">> = Specific
+  const handler = {} as typeof import("../../app/api/scene-overrides/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]/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/[id]/share/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions/[id]/share">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/[id]/share/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/sessions/new/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/sessions/new">> = Specific
+  const handler = {} as typeof import("../../app/api/sessions/new/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/settings/default-model/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/settings/default-model">> = Specific
+  const handler = {} as typeof import("../../app/api/settings/default-model/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/share/[token]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/share/[token]">> = Specific
+  const handler = {} as typeof import("../../app/api/share/[token]/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/usage/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/usage">> = Specific
+  const handler = {} as typeof import("../../app/api/usage/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/web-fetch/install-agent-browser/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/web-fetch/install-agent-browser">> = Specific
+  const handler = {} as typeof import("../../app/api/web-fetch/install-agent-browser/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/web-fetch/preferences/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/web-fetch/preferences">> = Specific
+  const handler = {} as typeof import("../../app/api/web-fetch/preferences/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../app/api/web-fetch/status/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/web-fetch/status">> = Specific
+  const handler = {} as typeof import("../../app/api/web-fetch/status/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,142 @@
+# pi-web
+
+[pi 编程智能体](https://github.com/badlogic/pi-mono) 的网页界面。在浏览器中浏览会话、与智能体对话、分叉对话、切换消息分支。
+
+## 快速开始
+
+**无需安装，直接运行：**
+
+```bash
+npx @agegr/pi-web@latest
+```
+
+**或全局安装后使用：**
+
+```bash
+npm install -g @agegr/pi-web
+pi-web
+```
+
+启动后打开 [http://localhost:30141](http://localhost:30141)。
+
+**可选参数：**
+
+```bash
+pi-web --port 8080               # 自定义端口
+pi-web --hostname 127.0.0.1      # 仅本机访问
+pi-web --remote                  # 开启远程访问并绑定 0.0.0.0
+pi-web -p 8080 -H 127.0.0.1     # 组合使用
+
+PORT=8080 pi-web                 # 也支持环境变量
+```
+
+> 安全提示：pi-web 会提供本地会话删除、模型配置和 API key 写入等接口。默认仅绑定 localhost。远程访问需显式开启（`--remote` 或 Settings → Remote access），并通过配对链接或 Bearer token 认证。详见 [docs/remote-access.md](docs/remote-access.md)。
+
+## 功能介绍
+
+- **会话浏览器** — 按工作目录分组展示所有 pi 会话
+- **实时对话** — 通过 SSE 流式输出与智能体实时交互
+- **会话分叉** — 从用户消息「从这里另开一版」创建独立 `.jsonl` 子会话
+- **复制为新对话** — 将当前分支整段复制为新的独立会话（Clone）
+- **会话内分支** — 回退到任意节点继续对话，在同一文件内创建分支
+- **分支导航器** — 可视化切换分支；可选「切换前先总结」
+- **整理摘要** — 自动/手动整理后在时间线显示可折叠的白话摘要块
+- **会话标题** — 侧栏重命名，顶栏与列表同步显示
+- **模型切换** — 对话中途随时切换模型
+- **工具面板** — 控制智能体可使用的工具
+- **压缩会话** — 对长会话进行摘要，节省上下文窗口
+- **引导 / 追加** — 打断正在运行的智能体，或在其完成后追加消息
+
+## 注意事项
+
+- **数据目录** — 默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他目录（本地开发时见下方「端口与数据隔离」，勿写入 `.env.local`）。
+- **模型配置** — 从智能体数据目录下的 `models.json` 读取可用模型，可在侧边栏的「Models」面板中编辑。
+- **文件浏览** — 侧边栏内置文件浏览器，可在标签页中查看当前工作目录下的文件。
+
+## 规划
+
+总计划：[docs/plan-pi-web-macos-workbench.md](docs/plan-pi-web-macos-workbench.md)  
+贯穿原则：[docs/product-principles.md](docs/product-principles.md)
+
+## 开发
+
+```bash
+npm install
+npm run lint
+npm run test:run
+```
+
+### 端口与数据隔离
+
+**原则：30141 是你日常使用的服务；开发、改代码、跑测试只动 30142，不要影响 30141。**
+
+| 用途 | 端口 | 命令 | 数据目录 | 说明 |
+|------|------|------|----------|------|
+| **日常使用** | **30141** | `npm start` 或全局 `pi-web` | `~/.pi/agent/` | 稳定服务，不随源码热更新 |
+| **开发 / 测试** | **30142** | `npm run dev` | `~/tmp/pi-dev-agent/` | 改代码、试功能只用此端口 |
+
+```bash
+# 30141 — 日常服务（先 build 一次，之后可长期开着）
+npm run build && npm start
+
+# 30142 — 开发测试（与 30141 可同时运行）
+npm run dev
+```
+
+### 让改动在 30141 上生效
+
+30141 使用 `next start`，读取仓库根目录的 `.next` 生产构建，**不会**像 30142 那样随保存自动热更新。在 30142 上验证通过的 UI/逻辑修复，要同步到日常端口必须：
+
+```bash
+npm run build
+# 若 30141 已在运行，先结束占用该端口的进程，再：
+npm start
+```
+
+浏览器打开 [http://127.0.0.1:30141](http://127.0.0.1:30141) 后建议 **硬刷新**（Cmd+Shift+R），避免旧前端资源缓存。
+
+- **本仓库**：`npm start` 或 macOS [PiWorkbench](macos/README.md)（内嵌子进程连 `127.0.0.1:30141`）——在本目录 `build` 并重启即可。
+- **全局 `pi-web`**：需在该包的安装目录执行 `npm run build` 后再启动 CLI，否则仍是旧构建。
+
+`npm run dev` 会设置 `PI_CODING_AGENT_DIR=~/tmp/pi-dev-agent`，并使用独立构建目录 `.next-dev-30142`，避免与 30141 抢锁、混数据。
+
+**不要在 30141 上跑 `next dev`**（包括 `npm run dev:prod`）：它与 30142 共用同一份源码，保存文件时两边都会热更新，开发中的半成品会直接打断你在 30141 上的使用。30141 请用 `npm start`（或已安装的 `pi-web`）。
+
+**不要在 `.env.local` 里设置 `PI_CODING_AGENT_DIR`**：Next.js 会在所有模式下加载该文件，导致 30141 误读空的 dev 目录、会话「丢失」。数据目录隔离只写在 `npm run dev` 脚本里。
+
+偶尔需要在真实数据上调试 HMR 时，可临时使用 `npm run dev:prod`（30141 + `~/.pi/agent/`），**不要与 `npm run dev` 同时开**。
+
+更多细节见 [AGENTS.md](AGENTS.md#dev--production-isolation)。
+
+### macOS App（M1 本机测试）
+
+```bash
+npm run package:macos   # 产出 dist/macos/Pi.app（干净 .next + 生产依赖 + 内嵌 Node）
+rm -rf /Applications/Pi.app
+ditto dist/macos/Pi.app /Applications/Pi.app
+open /Applications/Pi.app
+```
+
+大体积请用 `ditto` 安装，勿用 `cp -R`（易超时/异常）。若无法打开：`xattr -cr /Applications/Pi.app`。
+
+详见 [macos/README.md](macos/README.md)。
+
+## 项目结构
+
+```
+app/
+  api/
+    sessions/      # 读写会话文件
+    agent/         # 发送命令、SSE 事件流
+    files/         # 文件内容读取
+    models/        # 可用模型列表与默认模型
+    models-config/ # 读写 models.json
+components/        # UI 组件
+lib/
+  session-reader.ts  # 解析 .jsonl 会话文件
+  rpc-manager.ts     # 管理 AgentSession 生命周期
+  normalize.ts       # 规范化 toolCall 字段名
+  types.ts
+```
+
+会话文件存储路径：`~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`