@liguoshuai/pi-web-chat 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Fixed
+- **空内容 pi 气泡**：`message_start` 原本不区分角色，用户消息回显也建了一个空 pi 气泡 — 现在只对 `role:assistant` 开 streaming 块。
+- **重复文本渲染**：pi 在 `message_start` 就带完整 content、随后又用 `text_delta` 发同一文本 — 改用 `text_end.content` 覆盖累加结果，避免出现 `WS_OKWS_OK`。
+- **模型出错时空白回复**：当模型返回 `stopReason=error` 又无内容时（如选了不可用模型），现在显示明确的“生成失败 / 请换模型”提示。
+- **侧边栏漏掉 Web 新建的会话**：`server.js` 传给 pi 的 `--session-dir` 导致新 session 被直接放在 sessions 根目录而非 cwd 子目录中；`listAllSessionFiles` 原仅扫子目录，于是 11 条 Web 创建的会话一个都列不出来 — 现在同时扫根目录下的 `.jsonl`。
+- **新建会话非手动刷新不可见**：根因是上一条 — 侧边栏根本扫不到新文件。现在 `agent_settled` 后列表实时反映新会话，无需刷新页面。
+- **初始化时模型 pill 永远空白**：`init()` 里 `// pull current state once:\n setTimeout(...)` 把 `\n` 当成字面字符写进了单行注释，`get_state` / `get_available_models` 永不发出 — 改为真实换行后两调用均发出。
+- **工具调用参数显示不全**：新增 `toolcall_delta` / `toolcall_end` 处理，用 `toolcall_end` 的最终 `toolCall.arguments` 刷新头部 args 显示。
+- **同一 agent 多轮 agent message 互相污染**：`message_start`(assistant) 重置本块的 text/thinking 累加器，避免上一轮工具调用与下一轮文本串到一起。
+
+### Added
+- 会话切换时右侧完整历史恢复（通过 REST `/api/session` 重建 parent 链）
+- 模型切换器（顶栏 pill，支持所有 pi 配置的模型）
+- Tool-call 折叠块（实时输出、可展开/折叠）
+- Thinking 折叠块
+- 发送按钮双态（发送/停止）+ 红色停止态
+- 新会话后侧边栏在 `agent_settled` 立即刷新（无需手动刷新页面）
+
+### Changed
+- 侧边栏会话项去除无意义的 `●` 圆点，改为 tooltip 显示完整 jsonl 路径
+- 发送按钮禁用逻辑：仅在 wsConnected=false 时禁用，而非 streaming 时
+
+---
+
+## [0.2.0] - 2026-07-19
+
+### Added
+- **新建会话流程修复**：`btnNew` 点击后刷新侧边栏、清理流式状态、生成新 ws 代次
+- **WebSocket 代次机制**：`wsGen` 防止旧 socket 消息污染新上下文
+- **输入框红边提示**：ws 未连时提交会有 350ms 红色 flash
+- **连接状态文本动态更新**：「连接中…」→「已连接」/「已断开」
+- **提交**：`5a8f036` "Fix new-session flow: ws generation guard + sidebar refresh + drop input"
+
+### Fixed
+- 新建会话后左侧不出现（缺 `refreshSessions()`）
+- 快速切换会话导致 prompt 被当作 abort（旧 socket stragglers）
+
+---
+
+## [0.1.0] - 2026-07-19
+
+### Added
+- 项目初始化：`server.js` (Express + ws) + `public/` (HTML/JS/CSS)
+- REST API：
+  - `GET /api/sessions?cwd=` — 列出该 cwd 下所有 session（标题、时间、消息数）
+  - `GET /api/session?file=` — 重建会话的根→叶对话线
+- WebSocket `/ws?cwd=&session=` — 1:1 桥接 `pi --mode rpc`
+- 前端 UI：
+  - 左侧栏：搜索、历史列表、点击切换
+  - 右侧：空状态建议、流式对话、Markdown 渲染
+  - 底部：textarea + 发送/停止按钮
+  - 顶栏：会话名、模型选择 pill
+- 流式渲染：文本打字光标、thinking 块、工具折叠块
+- 会话历史持久化：复用 pi 原生 `~/.pi/agent/sessions/*.jsonl`
+- 多模型切换（pi 配置的所有 provider/model）
+- 响应式深色主题（ChatGPT/Gemini 风格）
+
+### Technical Debt (已知)
+- 图片上传未接
+- 多 cwd / 项目切换器未做
+- fork / tree / clone 浏览未接
+- 浅/深主题切换未做
+- 双端实时同步未做
+- 鉴权未做
+
+---
+
+## Legend
+
+| 标记 | 含义 |
+|------|------|
+| **Added**    | 新功能 |
+| **Changed**  | 现有功能变更 |
+| **Deprecated** | 即将移除 |
+| **Removed**  | 已移除 |
+| **Fixed**    | Bug 修复 |
+| **Security** | 安全相关修复 |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liguoshuai
+
+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,118 @@
+# pi-web-chat
+
+一个 [pi](https://pi.dev) 编程代理的 Web 界面，风格参考 ChatGPT / Gemini ——
+左侧历史会话侧边栏 + 右侧对话区 + 底部输入框。底层通过 pi 的 **RPC 模式**
+(`pi --mode rpc`) 与 pi 子进程通信，前端走 WebSocket 流式渲染。
+
+> 项目主页：https://github.com/liguoshuai-1990/pi-web-chat
+
+---
+
+## 📸 功能
+
+- 💬 **流式对话** —— 文本逐字流式渲染，带打字光标
+- 🗂️ **会话历史** —— 自动读取 `~/.pi/agent/sessions/` 下所有历史会话，按首条用户消息做标题
+- 🆕 **新建 / 切换会话** —— 通过左侧栏点击或生成中新建
+- ⚙️ **工具调用折叠块** —— bash / read / write / edit 等以可折叠卡片显示，实时输出
+- 💭 **思考过程折叠块** —— 模型 thinking 以独立可折叠卡片显示
+- 🧩 **模型切换** —— 顶栏模型 pill，覆盖所有 pi 已配置的模型
+- ⏹️ **中止生成** —— 生成中点击发送按钮即可中断
+- ⌨️ **Markdown 渲染** —— 代码块、表格、列表、链接、引用、标题
+- 🖥️ **工作目录绑定** —— 每个 ws 连接由 cwd 决定会话范围（默认 `~`）
+
+---
+
+## 🚀 快速开始
+
+```bash
+cd pi-web-chat
+npm install
+
+# 确保 pi 已安装并已配置好至少一个 provider/model：
+#   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 存储目录           |
+
+---
+
+## 📁 项目结构
+
+```
+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 风格样式
+```
+
+---
+
+## 🏗️ 架构
+
+```
+ 浏览器 ──WebSocket(/ws?cwd=...&session=...)──► Node server.js ──stdin/stdout(JSONL)──► pi --mode rpc
+                                             (一个 ws 连接 spawn 一个 pi 子进程)
+                                             │
+                                             ├──REST /api/sessions ──► 直读 JSONL 列历史
+                                             └──REST /api/session?file=... ─► 重建根→叶路径
+```
+
+---
+
+## 📝 License
+
+MIT
+
+---
+
+## 🛠️ Systemd 服务（可选）
+
+若希望开机自启、后台常驻、重启自愈，可安装为 user-level systemd 服务（无需 sudo）：
+
+```bash
+# 从项目根目录运行
+./scripts/install-service.sh 3000
+
+# 或自定义端口（默认 3000）：
+./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
+journalctl --user -u pi-web-chat -f
+```
+
+> ⚠️ **Linger**：systemd user 服务默认随登录会话结束。若需 **开机自启 / 登出后继续跑**，需一次性启用：
+> ```bash
+> sudo loginctl enable-linger $USER
+> ```
+
+卸载：
+```bash
+systemctl --user disable --now pi-web-chat
+rm ~/.config/systemd/user/pi-web-chat.service
+systemctl --user daemon-reload
+```

package/bin/pi-web-chat.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// pi-web-chat CLI entry point
+// Usage: pi-web-chat [--port=3000] [--cwd=/path] [--help]
+
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import { spawn } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, "..");
+const SERVER = resolve(ROOT, "server.js");
+
+function printHelp() {
+  console.log(`
+pi-web-chat — Web UI for pi coding agent (RPC mode)
+
+Usage:
+  pi-web-chat [options]
+
+Options:
+  -p, --port <number>    Port to listen on (default: 3000, env PORT)
+  -c, --cwd <path>       Working directory for pi sessions (default: $HOME)
+  -h, --help             Show this help
+
+Environment:
+  PORT              Same as --port
+  PI_BIN            Path to pi binary (auto-detected if not set)
+  PI_SESSIONS_DIR   Pi session storage directory (default: ~/.pi/agent/sessions)
+
+Examples:
+  pi-web-chat
+  pi-web-chat --port 8080
+  PORT=4000 pi-web-chat
+`);
+}
+
+function parseArgs(argv) {
+  const opts = { port: process.env.PORT || 3000, cwd: process.env.HOME };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") { printHelp(); process.exit(0); }
+    if (a === "-p" || a === "--port") opts.port = Number(argv[++i]);
+    else if (a.startsWith("--port=")) opts.port = Number(a.split("=")[1]);
+    else if (a === "-c" || a === "--cwd") opts.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) opts.cwd = a.split("=")[1];
+    else { console.error(`Unknown option: ${a}`); printHelp(); process.exit(1); }
+  }
+  return opts;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+
+// Spawn server.js as a child so we can forward signals cleanly.
+const child = spawn("node", [SERVER], {
+  cwd: opts.cwd,
+  env: { ...process.env, PORT: String(opts.port) },
+  stdio: "inherit",
+});
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (e) => { console.error(e); process.exit(1); });
+
+// Forward signals.
+["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
+  process.on(sig, () => child.kill(sig));
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@liguoshuai/pi-web-chat",
+  "version": "1.0.1",
+  "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "pi-web-chat": "bin/pi-web-chat.js"
+  },
+  "files": [
+    "server.js",
+    "bin/",
+    "public/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "prepare": "chmod +x bin/pi-web-chat.js"
+  },
+  "keywords": [
+    "pi",
+    "coding-agent",
+    "chat",
+    "web-ui",
+    "rpc",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liguoshuai-1990/pi-web-chat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/liguoshuai-1990/pi-web-chat/issues"
+  },
+  "homepage": "https://github.com/liguoshuai-1990/pi-web-chat#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "ws": "^8.18.0"
+  }
+}