@liguoshuai/pi-web-chat 1.6.0 → 1.7.0

package/README.md

@@ -8,17 +8,18 @@
 
 ---
 
-## 📸 功能
-
-- 💬 **流式对话** —— 文本逐字流式渲染，带打字光标
-- 🗂️ **会话历史** —— 自动读取 `~/.pi/agent/sessions/` 下所有历史会话，按首条用户消息做标题
-- 🆕 **新建 / 切换会话** —— 通过左侧栏点击或生成中新建
-- ⚙️ **工具调用折叠块** —— bash / read / write / edit 等以可折叠卡片显示，实时输出
-- 💭 **思考过程折叠块** —— 模型 thinking 以独立可折叠卡片显示
-- 🧩 **模型切换** —— 顶栏模型 pill，覆盖所有 pi 已配置的模型
-- ⏹️ **中止生成** —— 生成中点击发送按钮即可中断
-- ⌨️ **Markdown 渲染** —— 代码块、表格、列表、链接、引用、标题
-- 🖥️ **工作目录绑定** —— 每个 ws 连接由 cwd 决定会话范围（默认 `~`）
+## 📸 功能特性
+
+- 💬 **流式对话** —— 文本逐字流式渲染，带打字光标与 Markdown 高亮
+- ⚡ **后台任务持久化** —— 关闭网页/标签页不中断正在生成的任务，重新进入自动回放（Backfill）追平进度
+- 🌐 **多端/多设备同步协同** —— 多个浏览器标签页或多设备（手机/电脑）可同时连入同一会话，实时双向同步
+- 🧭 **运行时实时插入指令 (Steer)** —— 生成过程中可随时插入转向指令指导 AI 调整后续行动
+- 🗂️ **会话历史与管理** —— 自动读取并显示 `~/.pi/agent/sessions/` 下所有历史会话，实时自动落盘
+- ⚙️ **工具与思考过程折叠** —— bash / read / write / edit 等工具调用与 thinking 思考卡片实时展开/收起
+- 🧩 **动态模型切换** —— 顶栏模型胶囊，零延迟覆盖所有 pi 已配置的模型
+- 🔄 **断线自动重连与心跳** —— 带指数退避自动重连、双向心跳 Ping/Pong 检测
+- 📋 **快捷复制** —— 支持代码块、工具指令、回答全文一键复制
+- 📱 **移动端响应式** —— Viewport `100dvh` 优化、顶栏常驻固定、滚动置顶/置底快捷悬浮按钮（FAB）
 
 ---
 
@@ -28,19 +29,26 @@
 cd pi-web-chat
 npm install
 
-# 确保 pi 已安装并已配置好至少一个 provider/model：
+# 确保 pi 已安装并已配置好至少一个 provider：
 #   pi         （交互模式 → 运行 /login 选择 provider，或设置 API key）
 npm start
 # → http://localhost:3000
 ```
 
-### 环境变量
+---
+
+## ⚙️ 环境变量配置
 
-| 变量                  | 默认值                                     | 说明                          |
-| -------------------- | --------------------------------------- | --------------------------- |
-| `PORT`               | `3000`                                  | Web 服务监听端口                    |
-| `PI_BIN`             | 自动探测（`~/.npm-global/bin/pi` 等）             | 显式指定 pi 可执行文件路径                |
-| `PI_SESSIONS_DIR`    | `~/.pi/agent/sessions`                  | pi 的 session 存储目录           |
+| 变量 | 默认值 | 说明 |
+| ---- | ------ | ---- |
+| `PORT` | `3000` | Web 服务监听端口 |
+| `PI_BIN` | 自动探测（`~/.npm-global/bin/pi` 等） | 显式指定 pi 可执行文件绝对路径 |
+| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | pi 的 session 存储目录 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的进程回收超时（0 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `1800000` (30分钟) | 单个 Agent 进程后台生存硬上限（0 为无上限） |
+| `EVENT_BUFFER_SIZE` | `2000` | 离线环形 Buffer 允许缓存的最大事件条数 |
+| `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
+| `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
 
 ---
 
@@ -49,31 +57,38 @@ npm start
 ```
 pi-web-chat/
 ├── README.md                       本文件
-├── DESIGN.md                       设计文档（架构、数据流、决策）
-├── ISSUES.md                       历次问题排查与修复
-├── CHANGELOG.md                    版本变更日志
 ├── package.json
 ├── package-lock.json
-├── server.js                       Express + WebSocket，桥接 pi RPC
-├── .gitignore
-└── public/
-    ├── index.html                  单页 UI
-    ├── app.js                      前端逻辑
-    └── style.css                   ChatGPT/Gemini 风格样式
+├── server.js                       Express + WebSocket，桥接 pi RPC 与进程池管理
+├── bin/
+│   └── pi-web-chat.js              CLI 可执行入口
+├── public/
+│   ├── index.html                  单页 UI
+│   ├── app.js                      前端逻辑与状态机
+│   └── style.css                   ChatGPT/Gemini 风格样式
+└── docs/                           项目文档库
+    ├── ARCHITECTURE.md             架构设计文档
+    ├── DESIGN.md                   详细设计与决策文档
+    ├── ISSUES.md                   历次问题排查与修补记录
+    └── CHANGELOG.md                版本变更日志
 ```
 
 ---
 
-## 🏗️ 架构
+## 🏗️ 架构概览
 
 ```
- 浏览器 ──WebSocket(/ws?cwd=...&session=...)──► Node server.js ──stdin/stdout(JSONL)──► pi --mode rpc
-                                             (一个 ws 连接 spawn 一个 pi 子进程)
-                                             │
-                                             ├──REST /api/sessions ──► 直读 JSONL 列历史
-                                             └──REST /api/session?file=... ─► 重建根→叶路径
+ 浏览器 (多 Tab / 多设备) ──WebSocket(/ws?cwd=...&session=...)──► Node server.js
+                                                                (Session Key 进程池 activeAgents)
+                                                                │
+                                                                ├──► pi --mode rpc (后台持久化 Worker)
+                                                                ├──► REST /api/sessions ──► 列会话历史
+                                                                ├──► REST /api/session ────► 构建对话链
+                                                                └──► REST /api/agents ─────► 实时监控看板
 ```
 
+详细架构说明与设计决策请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 与 [docs/DESIGN.md](docs/DESIGN.md)。
+
 ---
 
 ## 📝 License
@@ -94,11 +109,6 @@ MIT
 ./scripts/install-service.sh 8080
 ```
 
-脚本会：
-1. 在 `~/.config/systemd/user/pi-web-chat.service` 生成 unit
-2. `systemctl --user daemon-reload && systemctl --user enable --now pi-web-chat`
-3. 设置 `Restart=on-failure` 自动重启
-
 查看状态 / 日志：
 ```bash
 systemctl --user status pi-web-chat
@@ -110,7 +120,7 @@ journalctl --user -u pi-web-chat -f
 > sudo loginctl enable-linger $USER
 > ```
 
-卸载：
+卸载服务：
 ```bash
 systemctl --user disable --now pi-web-chat
 rm ~/.config/systemd/user/pi-web-chat.service

package/docs/ARCHITECTURE.md

@@ -0,0 +1,179 @@
+# 架构设计文档
+
+> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v1.6.0 版本）。
+
+---
+
+## 1. 高层架构
+
+```
+┌─────────────────┐             WebSocket (JSON)             ┌──────────────────────┐
+│  Browser Tab A  │ ◄──────────────────────────────────────► │                      │
+└─────────────────┘                                          │                      │
+┌─────────────────┐                                          │  Node.js server      │
+│  Browser Tab B  │ ◄──────────────────────────────────────► │  (server.js)         │
+└─────────────────┘                                          │                      │
+                                                             │  ┌────────────────┐  │
+                                                             │  │  PiAgent Pool  │  │
+                                                             │  │ (activeAgents) │  │
+                                                             │  └───────┬────────┘  │
+                                                             └──────────┼───────────┘
+                                                                        │
+                                                    spawn child_process │ (1 agent per session key)
+                                                                        ▼
+                                                             ┌──────────────────────┐
+                                                             │   pi --mode rpc      │
+                                                             │   (后台 Agent 子进程)  │
+                                                             │   stdin/stdout       │
+                                                             └──────────┬───────────┘
+                                                                        │
+                                                     ┌──────────────────┼──────────────────┐
+                                                     ▼                  ▼                  ▼
+                                            ~/.pi/agent/sessions/   ~/.pi/agent/       配置/扩展/
+                                            --home-zrlgs--/         extensions/        skills/
+                                                    │
+                                                    ▼
+                                            *.jsonl (append-only tree)
+```
+
+**核心设计原则**：
+- **按 Session Key 池化进程**：以 `${cwd}:${resolvedSessionPath}` 作为唯一 Key，多标签页或多设备连接同一个 Session 时共享同一个后台 `PiAgent` 进程。
+- **后台持久化运行（Headless Persistence）**：网页断开（如关闭标签页）不会立即终止进程。只要 Agent 处于流式生成或有未响应请求状态，后台进程会坚持跑完当前任务。
+- **离线事件环形缓存与回放（Ring Buffer & Backfill）**：无客户端连接时，pi 输出的事件自动存入环形 Buffer（默认 2000 条）。客户端重连时通过 `backfill_start` → 离线事件 → `backfill_end` 进行增量补齐。
+- **真正空闲回收（True-Idle Timeout）**：仅在“无 WebSocket 连接”且“进程彻底进入 idle（非 streaming、无挂起 RPC）”时，才启动 `IDLE_TIMEOUT_MS` 空闲回收倒计时。
+- **磁盘 JSONL 为唯一真理（Single Source of Truth）**：会话历史与树状分支全由 pi 本身维护在磁盘 `.jsonl` 文件中，Web 端通过 REST 接口与 RPC 消息与文件保持同步。
+
+---
+
+## 2. 关键数据流
+
+### 2.1 打开已有会话与增量回放（Backfill）
+
+```
+Browser                          server.js                      PiAgent (RPC)
+  │                                 │                                │
+  ├─ GET /api/session?file=X ──────►│ 读 JSONL 主干消息               │
+  │◄─── { header, entries[] }──────┤                                │
+  │                                 │                                │
+  ├─ 渲染历史消息                    │                                │
+  │                                 │                                │
+  ├─ WS /ws?cwd=...&session=X ─────►│ 查找/创建 activeAgents[Key]     │
+  │                                 ├─► attachWs(ws)                 │
+  │                                 ├─► 发现有离线缓存事件            │
+  │◄─── { type: "backfill_start" }─┤                                │
+  │◄─── N 条离线事件 (text_delta…)  │ (将离线事件批量回放给当前 ws)      │
+  │◄─── { type: "backfill_end" }───┤                                │
+  │                                 │                                │
+  ├─ 矫正当前 streaming 与 Composer 状态                              │
+```
+
+### 2.2 新建会话与发送消息
+
+```
+Browser                         server.js                       pi RPC 子进程
+  │                                │                                 │
+  ├─ WS /ws?cwd=... (无 session)   │ spawn pi --mode rpc             │
+  │                                │◄─ pi 创建新 session jsonl       │
+  │◄─── ws open (状态记为已连接)     │                                 │
+  │                                │                                 │
+  ├─ sendWs({type:"prompt", ...})─►│────────────────────────────────►│
+  │                                │                                 ├─ agent_start (state=streaming)
+  │◄─── message_update/text_delta ─┼◄────────────────────────────────┤
+  │◄─── agent_settled              │◄────────────────────────────────┤ (state=idle)
+  │                                │                                 ├─ session 文件实时追加
+```
+
+### 2.3 中途插话 / 转向（Mid-turn Steering）
+
+```
+Browser                         server.js                       pi RPC 子进程
+  │                                │                                 │
+  ├─ Agent 处于 streaming 状态 ────┼─────────────────────────────────┤ (正在执行长任务/工具)
+  ├─ sendWs({type:"steer", ...})──►│────────────────────────────────►│
+  │                                │                                 ├─ 注入 steer 命令
+  │◄─── agent 收到并调整后续思考 ────┼◄────────────────────────────────┤
+```
+
+---
+
+## 3. 关键模块职责
+
+### 3.1 `server.js`
+
+| 模块/函数 | 职责 |
+|-----------|------|
+| `PiAgent` 类 | 管理单个 `pi --mode rpc` 子进程：维护状态（`idle`/`streaming`）、离线事件 Buffer、挂起请求表、真·空闲回收定时器与硬生存上限定时器。 |
+| `activeAgents` Map | 以 `${cwd}:${sessionFile}` 为 Key 的进程池，实现多端/多标签页共享。 |
+| `GET /api/sessions` | 扫描 `~/.pi/agent/sessions/**/*.jsonl`，读取 header 做 cwd 过滤，按更新时间排序返回。 |
+| `GET /api/session` | 读取单个 `.jsonl` 文件，按 parentId 关系重构叶子到根节点的标准对话链。 |
+| `GET /api/agents` | 暴露后台活跃 Agent 的状态信息（运行状态、客户端数量、存活时长、离线 Buffer 消息数、最近提示词等）。 |
+| `WebSocketServer` | 处理连接建立与断开，分发 `prompt`、`steer`、`abort`、`ping` 等指令，并在 `SIGINT`/`SIGTERM` 时进行优雅关闭。 |
+
+### 3.2 `public/app.js`
+
+| 模块/函数 | 职责 |
+|-----------|------|
+| `state` | 全局状态对象：维护 `wsConnected`、`streaming`、`isBackfilling`、`activeToolCalls`、`sessionId`、`wsGen` 等。 |
+| `connectWs(opts)` | 管理 WebSocket 生命周期：携带代次 `wsGen` 防止旧消息污染，处理重连逻辑与心跳。 |
+| `handlePiMessage(obj)` | 核心事件分发器：处理 `backfill_start`/`backfill_end`、16 种 pi 事件以及状态同步。 |
+| `ensureStreamingMsg / refreshStreamingContent` | 增量渲染/更新正在流式的文本、思考过程（Thinking）与工具卡片。 |
+| `renderMarkdown` | 自研轻量 Markdown 渲染器（代码块抠出保护、Html Escape、行内语法转换）。 |
+
+### 3.3 `public/style.css`
+
+- 暗色与明色响应式样式变量。
+- 左侧 260px 侧边栏与右侧主聊天区自适应布局。
+- 移动端 Fixed 顶栏、Viewport height 100dvh 适配与悬浮置顶按钮（FAB）。
+
+---
+
+## 4. 关键设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| **进程池粒度** | **Session Key 池化** | 允许同一会话在多设备/多 Tab 间同步，同时保证进程资源不重复浪费。 |
+| **断连处理** | **后台继续跑 + 环形 Buffer 回放** | 解决关闭标签页导致未完成任务断掉的问题；用环形 Buffer 防止长时间离线膨胀内存。 |
+| **回收策略** | **真·空闲倒计时（True-Idle Timeout）** | 区分“无连接”与“真正的空闲”，保障长时间后台生成任务不被中断。 |
+| **通讯协议** | **直接透传 pi 原生 JSONL** | 不做二次包装，保持与 pi RPC 协议同频更新。 |
+| **持久化** | **复用 pi 本身 .jsonl** | 零额外存储依赖，Web 端与终端命令完全同源共享会话。 |
+
+---
+
+## 5. 配置与环境变量
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| `PORT` | `3000` | HTTP 与 WebSocket 监听端口 |
+| `PI_BIN` | 自动探测 | pi 可执行文件绝对路径 |
+| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | 会话 JSONL 文件存取目录 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的回收超时（0 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `1800000` (30分钟) | 单个 Agent 进程后台生存硬上限（0 为无上限） |
+| `EVENT_BUFFER_SIZE` | `2000` | 离线环形 Buffer 允许缓存的最大事件条数 |
+| `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
+| `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
+
+---
+
+## 6. 目录结构
+
+```
+pi-web-chat/
+├── README.md                       # 主说明文档
+├── package.json
+├── package-lock.json
+├── server.js                       # Express + WebSocket 服务器与 PiAgent 管理
+├── bin/
+│   └── pi-web-chat.js              # 可执行入口
+├── public/
+│   ├── index.html                  # 单页 UI
+│   ├── app.js                      # 前端逻辑与状态机
+│   └── style.css                   # CSS 样式
+├── docs/                           # 所有文档统一收纳
+│   ├── ARCHITECTURE.md             # 架构设计文档（本文件）
+│   ├── DESIGN.md                   # 详细设计与决策文档
+│   ├── ISSUES.md                   # 排查与修补记录
+│   └── CHANGELOG.md                # 版本变更日志
+└── scripts/                        # 服务安装/卸载脚本
+    ├── install-service.sh
+    └── pi-web-chat.service
+```

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.0] - 2026-07-26
+
+### Added
+- **前端流式渲染防抖节流 (rAF UI Throttling)**：使用 `requestAnimationFrame` 节流高频 Token/Delta 事件，消除倒水式输出时的 DOM 频繁销毁与全量重塑，大幅提升高频打字时的流畅帧率，显著降低 CPU 和发热消耗。
+- **后端 Session 列表 mtime 内存缓存 (Session Metadata Caching)**：`/api/sessions` 引入基于文件修改时间（`mtimeMs`）的元数据内存缓存。对无改动的历史 Session 文件跳过磁盘读取与全量 JSON 逐行解析，大幅提升侧边栏列表加载响应速度。
+- **离线事件 Buffer 算法优化 (Ring Buffer O(1) Push)**：将 `PiAgent.bufferEvent` 从 $O(N)$ 复杂度的 `Array.shift()` 改为 $O(1)$ 的指针环形队列，消除无客户端连接时的数组平移消耗。
+- **WebSocket 垃圾连接自动回收 (Dead Socket Cleanup)**：在 `wsSend` 广播消息时动态检测并自动剔除已处于关闭状态（`CLOSING`/`CLOSED`）的垃圾 Socket 引用，避免泄露。
+
+---
+
 ## [1.6.0] - 2026-07-26
 
 ### Added
@@ -153,14 +163,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 多模型切换（pi 配置的所有 provider/model）
 - 响应式深色主题（ChatGPT/Gemini 风格）
 
-### Technical Debt (已知)
-- 图片上传未接
-- 多 cwd / 项目切换器未做
-- fork / tree / clone 浏览未接
-- 浅/深主题切换未做
-- 双端实时同步未做
-- 鉴权未做
-
 ---
 
 ## Legend

package/docs/DESIGN.md

@@ -0,0 +1,88 @@
+# 详细设计与决策文档
+
+## 目标
+
+将 [pi](https://pi.dev) 终端编码代理包装为一个**类 ChatGPT / Gemini 的 Web 界面**，使用户能够：
+
+- 在浏览器中与 pi 展开对话，享受流式文本输出、思考过程卡片、Markdown 渲染与工具调用可视化；
+- 与终端共享会话历史（一份存储、两端可见）；
+- 支持后台持久化运行：关闭标签页或切换设备不打断正在生成的任务，重新进入时自动追进度。
+
+非目标：
+- 引入复杂的前端构建链（保持单页原生 JS/CSS，无打包工具）；
+- 替代 pi 本身的文件存储层或重新实现数据库。
+
+---
+
+## 核心设计与进程模型
+
+### 进程池化与后台持久化运行
+
+```
+Browser Tab 1 ──┐
+                ├── WebSocket ──► server.js (activeAgents[Key]) ──stdio (JSONL)──► pi (rpc mode)
+Browser Tab 2 ──┘
+```
+
+与早期“1 个 WebSocket = 1 个子进程”不同，当前设计以 **Session Key**（`${cwd}:${resolvedSessionPath}`）作为唯一标识：
+
+1. **多端/多标签页共享**：多个浏览器标签页或多个设备打开同一个 Session 时，附加到同一个 `PiAgent` 实例。
+2. **后台任务持久化**：关闭网页仅表示断开 WebSocket 连接，`PiAgent` 会继续运行直到当前的流式任务结束。
+3. **离线 Buffer 与回放**：在无客户端连接期间，pi 抛出的事件将缓存在 `eventBuffer` 环形队列中。新客户端连接后，服务端通过 `backfill_start` → 增量事件 → `backfill_end` 进行追回。
+4. **真·空闲回收（True-Idle Timeout）**：仅在“无 WebSocket 连接”且“真正 Idle”（非 streaming，无挂起 RPC 请求）时启动 `IDLE_TIMEOUT_MS`（默认 5 分钟）倒计时回收进程。
+
+---
+
+## 数据流设计
+
+### 1. 消息发送与流式渲染
+
+```
+1. 浏览器发送 JSON: {"type": "prompt", "message": "..."}
+2. 服务端转给对应 Session 的 PiAgent
+3. PiAgent 更新状态为 streaming，写入 pi 的 stdin
+4. pi 往 stdout 输出事件流 (agent_start / text_delta / toolcall_start / agent_end / agent_settled)
+5. 服务端广播给所有连入该 Session 的 WebSocket，并写入离线 Buffer（若无连接）
+6. 浏览器 handlePiMessage 增量更新 DOM（文本、思考块、工具卡片）
+```
+
+### 2. 中途中断与转向（Steering）
+
+在代理正在执行长任务或工具调用时，用户可以输入补充指令：
+- **Abort**：发送 `{"type": "abort"}` 中断当前生成。
+- **Steer**：发送 `{"type": "steer", "message": "..."}` 插入中途指令，指导代理调整后续行动。
+
+---
+
+## 关键设计决策与权衡
+
+### 1. 渲染策略：重构 vs 增量 DOM
+
+针对流式输出中出现的文本、思考块（Thinking）、工具卡片交错问题：
+- 选择**每次更新时重构当前 assistant 消息的内容节点**。因为单次回复文本长度通常有限，原生 DOM 节点重写开销在 5ms 以内，极大地简化了复杂的节点插入与折叠逻辑。
+
+### 2. 代次标记（`wsGen`）
+
+解决浏览器在极短时间内快速切换 WebSocket 会话时的竞态：
+- 全局分配单调递增的 `wsGen` 代次。每次建立新 WebSocket 时递增。在接收消息前比对 `ws._gen === wsGen`，避免旧连接迟到的消息破坏新会话的状态。
+
+### 3. Markdown 渲染：Escape-First 零依赖
+
+不使用第三方大型 Markdown 渲染库，采用原生轻量处理：
+- 在渲染入口统一对文本做 HTML Escape 转义（防止 XSS 攻击）；
+- 先将围栏代码块（Fenced Code Blocks）抠出暂存，再做行内语法转换，最后还原代码块。
+
+---
+
+## 消息事件与 UI 控件对照表
+
+| pi RPC 事件 | 触发动作 / 前端 UI 表现 |
+|-------------|-------------------------|
+| `agent_start` | 切换发送按钮为“停止/中止”状态，标志进入流式生成状态 |
+| `message_start` | 在聊天区域末尾追加新的 Assistant 消息卡片 |
+| `message_update` / `text_delta` | 累加到文本缓冲并重新渲染 Markdown |
+| `message_update` / `thinking_delta` | 累加到 Thinking 折叠卡片并实时显示 |
+| `message_update` / `toolcall_start` | 创建可视化工具调用卡片（可折叠） |
+| `tool_execution_start / update / end` | 动态更新工具卡片的输入参数、标准输出与执行状态 |
+| `agent_end` / `agent_settled` | 恢复发送按钮，标记流式生成结束，触发侧边栏会话列表刷新 |
+| `backfill_start` / `backfill_end` | 前端标记处于历史回放状态，回放期间暂停自动滚动，回放结束后一次性同步状态并滚动到底部 |

package/docs/ISSUES.md

@@ -0,0 +1,66 @@
+# 问题排查与修补记录
+
+项目开发与演进过程中遇到并修复的技术问题与设计优化记录。
+
+---
+
+## 1. 侧边栏 `cwd` 路径编码错误
+
+**症状**：API `GET /api/sessions?cwd=/home/zrlgs` 拿不到任何结果。
+
+**根因**：第一版用了 `cwd.replace(/\//g, "-")` 把 `/home/zrlgs` 编码成 `-home-zrlgs`，但 pi 实际上用的是 `--home-zrlgs--`（前后都带 `-`）。
+
+**修复**：弃用编码猜测，扫描 sessions 根目录下所有子目录，读每个 jsonl 的 header 里 `cwd` 字段，再按 `cwd` 严格比对过滤。
+
+---
+
+## 2. 关闭网页标签页导致正在生成的 pi 任务中断
+
+**症状**：在用户提交了一个复杂 Prompt（或正在跑 Bash 工具）后关闭网页，AI 回答直接中断，下次连入时拿不到完整结果。
+
+**根因**：原先 WebSocket 断开会直接触发 5 分钟倒计时杀进程；即使倒计时未到，没有客户端连入时生成的事件也被直接抛弃，未在内存中保留。
+
+**修复**：
+- 引入 **PiAgent 进程池化** 与 **真·空闲回收（True-Idle Timeout）**：只有在“无 WS 连接”且“真正 Idle”（非 streaming、无挂起 RPC）时才倒计时。
+- 引入 **离线事件环形 Buffer（Event Ring Buffer）**：无客户端时缓存在 Buffer，新连接重连时发送 `backfill_start` → 增量事件 → `backfill_end` 进行追回并一次性同步状态。
+
+---
+
+## 3. 局域网 / 移动端 Safari 100vh 动态导航栏遮挡底部输入框
+
+**症状**：移动端 Safari 浏览器打开 Web 界面时，底部输入框被 iOS 动态地址栏遮挡，且顶栏在滚动时会跟着滑走。
+
+**修复**：
+- 在 CSS 中使用 `100dvh` (Dynamic Viewport Height) 替代 `100vh`。
+- 将顶栏改为 `sticky` / `fixed` 布局，保障移动端交互体验。
+- 增加悬浮置顶/置底快捷按钮（FAB）。
+
+---
+
+## 4. WebSocket 代次竞态 —— 旧 socket 残留消息污染新会话
+
+**症状**：点“新对话”快速发消息时，前一次会话延迟到达的 `agent_end` / `agent_settled` 事件跑进新会话，导致新会话 `streaming` 状态被错误覆盖。
+
+**修复**：
+- 引入全局 `wsGen` 单调递增计数器，给每个 WebSocket 分配 `_gen` 编号。
+- 接收消息前比对代次，丢弃非当前代次发来的旧事件。
+
+---
+
+## 5. `/api/session` 中局部变量遮蔽 Node `path` 模块
+
+**症状**：在调用 `/api/session` 接口获取历史对话时，出现 `TypeError: path.basename is not a function` 报错。
+
+**根因**：函数内部在处理 jsonl 包含的文件条目时，使用了 `const path = ...` 局部变量名，屏蔽了 Node.js 顶层的 `import path from "node:path"` 模块。
+
+**修复**：重命名局部变量为 `filePath` / `resolvedPath`，消除变量同名遮蔽。
+
+---
+
+## 6. 多设备 / 多 Tab 共享会话不同步
+
+**症状**：同一个 Session 在手机和电脑上同时打开时，手机发送的消息电脑看不到，状态互相覆盖。
+
+**修复**：
+- 以 Session Key 为粒度管理 `PiAgent` 实例。
+- 任何一个客户端发送 `prompt` 或 `steer` 指令时，通过 `agent.wsSend(..., senderWs)` 广播同步给连入该 Session 的其他客户端。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liguoshuai/pi-web-chat",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
   "type": "module",
   "main": "server.js",
@@ -11,8 +11,8 @@
     "server.js",
     "bin/",
     "public/",
+    "docs/",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/public/app.js

@@ -773,6 +773,16 @@ function ensureStreamingMsg() {
   return node;
 }
 
+let isRefreshScheduled = false;
+function refreshStreamingContentDebounced() {
+  if (isRefreshScheduled) return;
+  isRefreshScheduled = true;
+  requestAnimationFrame(() => {
+    isRefreshScheduled = false;
+    refreshStreamingContent();
+  });
+}
+
 function refreshStreamingContent() {
   const node = state.streamingMsg;
   if (!node) return;
@@ -1142,7 +1152,7 @@ function handlePiMessage(obj) {
       if (!ev) break;
       if (ev.type === "text_delta") {
         state.streamingText += ev.delta;
-        refreshStreamingContent();
+        refreshStreamingContentDebounced();
       } else if (ev.type === "text_end") {
         // Authoritative final text for this content slot. Overwrite any
         // accumulated/delta text so we display exactly what the model
@@ -1156,7 +1166,7 @@ function handlePiMessage(obj) {
         if (ev.type === "thinking_delta") {
           state.streamingThinking += ev.delta || "";
         }
-        refreshStreamingContent();
+        refreshStreamingContentDebounced();
       } else if (ev.type === "toolcall_start") {
         ensureStreamingMsg();
         const call = ev.toolCall || { id: obj.toolCallId || ev.id, name: obj.toolName, arguments: obj.args };
@@ -1222,7 +1232,7 @@ function handlePiMessage(obj) {
 function ensureToolBlock(toolCallId, name, args) {
   if (state.activeToolCalls.has(toolCallId)) return state.activeToolCalls.get(toolCallId);
   makeToolBlockFromCall({ id: toolCallId, name, arguments: args });
-  refreshStreamingContent();
+  refreshStreamingContentDebounced();
   return state.activeToolCalls.get(toolCallId);
 }
 

package/server.js

@@ -129,6 +129,7 @@ class PiAgent {
     // ring buffer of pi->browser events while no socket is attached, so a
     // reconnecting client can replay what happened in the background.
     this.eventBuffer = [];
+    this.bufferHead = 0;
     // lightweight summary of the task currently running in background, for
     // the /api/agents dashboard and reconnecting clients.
     this.lastUserPrompt = null;
@@ -303,18 +304,24 @@ class PiAgent {
 
   bufferEvent(obj) {
     if (EVENT_BUFFER_SIZE <= 0) return;
-    this.eventBuffer.push(obj);
-    if (this.eventBuffer.length > EVENT_BUFFER_SIZE) {
-      this.eventBuffer.shift();
+    if (this.eventBuffer.length < EVENT_BUFFER_SIZE) {
+      this.eventBuffer.push(obj);
+    } else {
+      this.eventBuffer[this.bufferHead] = obj;
+      this.bufferHead = (this.bufferHead + 1) % EVENT_BUFFER_SIZE;
     }
   }
 
   replayBuffered(ws) {
     if (this.eventBuffer.length === 0) return;
     if (ws.readyState !== 1) return;
+    const count = this.eventBuffer.length;
     // Send a marker so the client knows the next burst is backfill, not live.
-    try { ws.send(JSON.stringify({ type: "backfill_start", count: this.eventBuffer.length })); } catch {}
-    for (const ev of this.eventBuffer) {
+    try { ws.send(JSON.stringify({ type: "backfill_start", count })); } catch {}
+    const start = count === EVENT_BUFFER_SIZE ? this.bufferHead : 0;
+    for (let i = 0; i < count; i++) {
+      const idx = (start + i) % EVENT_BUFFER_SIZE;
+      const ev = this.eventBuffer[idx];
       try { ws.send(JSON.stringify(ev)); } catch {}
     }
     try { ws.send(JSON.stringify({ type: "backfill_end", streaming: this.isBusy, state: this.state })); } catch {}
@@ -347,12 +354,17 @@ class PiAgent {
 
   wsSend(obj, excludeSocket = null) {
     const payload = typeof obj === "string" ? obj : JSON.stringify(obj);
-    for (const ws of this.sockets) {
+    for (const ws of [...this.sockets]) {
+      if (ws.readyState > 1) { // CLOSING or CLOSED
+        this.sockets.delete(ws);
+        continue;
+      }
       if (ws !== excludeSocket && ws.readyState === 1) {
         try {
           ws.send(payload);
         } catch (e) {
           console.error("wsSend error", e);
+          this.sockets.delete(ws);
         }
       }
     }
@@ -462,6 +474,47 @@ async function listAllSessionFiles() {
   return files;
 }
 
+// Memory metadata cache keyed by file path -> { mtimeMs, cwd, sessionInfo }
+const sessionMetadataCache = new Map();
+
+async function getSessionMetadata(file) {
+  const fileStat = await stat(file);
+  const cached = sessionMetadataCache.get(file);
+  if (cached && cached.mtimeMs === fileStat.mtimeMs) {
+    return cached;
+  }
+
+  const content = await readFile(file, "utf8");
+  const lines = content.split("\n").filter(Boolean);
+  let header = null, title = null, msgCount = 0;
+  for (const line of lines) {
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (o.type === "session") header = o;
+    if (o.type === "message" && o.message && o.message.role === "user" && !title) {
+      title = extractText(o.message.content).slice(0, 80);
+    }
+    if (o.type === "message") msgCount++;
+  }
+
+  if (!header) return null;
+
+  const result = {
+    mtimeMs: fileStat.mtimeMs,
+    cwd: normalizeCwd(header.cwd),
+    sessionInfo: {
+      file,
+      name: path.basename(file),
+      id: header.id,
+      timestamp: header.timestamp,
+      firstUser: title,
+      messageCount: msgCount,
+    },
+  };
+  sessionMetadataCache.set(file, result);
+  return result;
+}
+
 app.get("/api/sessions", async (req, res) => {
   try {
     const cwd = normalizeCwd(req.query.cwd);
@@ -469,27 +522,10 @@ app.get("/api/sessions", async (req, res) => {
     const sessions = [];
     for (const full of all) {
       try {
-        const content = await readFile(full, "utf8");
-        const lines = content.split("\n").filter(Boolean);
-        let header = null, title = null, msgCount = 0;
-        for (const line of lines) {
-          let o;
-          try { o = JSON.parse(line); } catch { continue; }
-          if (o.type === "session") header = o;
-          if (o.type === "message" && o.message && o.message.role === "user" && !title) {
-            title = extractText(o.message.content).slice(0, 80);
-          }
-          if (o.type === "message") msgCount++;
+        const meta = await getSessionMetadata(full);
+        if (meta && meta.cwd === cwd) {
+          sessions.push(meta.sessionInfo);
         }
-        if (!header || normalizeCwd(header.cwd) !== cwd) continue;
-        sessions.push({
-          file: full,
-          name: path.basename(full),
-          id: header.id,
-          timestamp: header.timestamp,
-          firstUser: title,
-          messageCount: msgCount,
-        });
       } catch {}
     }
     sessions.sort((a, b) => (b.timestamp || "").localeCompare(a.timestamp || ""));