@liguoshuai/pi-web-chat 1.7.4 → 1.7.6

package/README.md

@@ -154,6 +154,10 @@ pi-web-chat/
 │   ├── index.html                  单页 UI
 │   ├── app.js                      前端逻辑与状态机
 │   └── style.css                   ChatGPT/Gemini 风格样式
+├── scripts/                        Systemd 服务安装与管理脚本
+│   ├── pi-web-chat.service         Systemd user unit 模板
+│   ├── install-service.sh          一键安装与启动脚本
+│   └── uninstall-service.sh        一键卸载脚本
 └── docs/                           项目文档库
     ├── ARCHITECTURE.md             架构设计文档
     ├── DESIGN.md                   详细设计与决策文档
@@ -210,6 +214,10 @@ journalctl --user -u pi-web-chat -f
 
 卸载服务：
 ```bash
+# 使用一键卸载脚本
+./scripts/uninstall-service.sh
+
+# 或手动清理：
 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

@@ -37,15 +37,43 @@ Examples:
 }
 
 function parseArgs(argv) {
-  const opts = { port: process.env.PORT || 3000, cwd: process.env.HOME };
+  const opts = { port: process.env.PORT || 3000, cwd: process.env.HOME || os.homedir() };
   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); }
+    if (a === "-p" || a === "--port") {
+      const val = argv[++i];
+      if (!val || isNaN(Number(val))) {
+        console.error(`Error: --port requires a valid number`);
+        process.exit(1);
+      }
+      opts.port = Number(val);
+    } else if (a.startsWith("--port=")) {
+      const val = a.split("=")[1];
+      if (!val || isNaN(Number(val))) {
+        console.error(`Error: --port requires a valid number`);
+        process.exit(1);
+      }
+      opts.port = Number(val);
+    } else if (a === "-c" || a === "--cwd") {
+      const val = argv[++i];
+      if (!val) {
+        console.error(`Error: --cwd requires a path`);
+        process.exit(1);
+      }
+      opts.cwd = val;
+    } else if (a.startsWith("--cwd=")) {
+      const val = a.split("=")[1];
+      if (!val) {
+        console.error(`Error: --cwd requires a path`);
+        process.exit(1);
+      }
+      opts.cwd = val;
+    } else {
+      console.error(`Unknown option: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
   }
   return opts;
 }

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构设计文档
 
-> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v1.7.4 版本）。
+> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v1.7.5 版本）。
 
 ---
 

package/docs/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.6] - 2026-07-26
+
+### Security
+- **Markdown 渲染 HTML 属性逃逸注入安全漏洞修复 (HTML Attribute Breakout XSS Vulnerability)**：升级 `public/app.js` 中的 `escapeHtml` 严密性，将原有对 `&`、`<`、`>` 的处理，扩展至双引号 `"` (`&quot;`) 与单引号 `'` (`&#39;`)，阻断由于模型生成恶意链接等引起的 `href` 属性逃逸与任意 HTML 属性/事件（XSS）注入风险。
+
+### Fixed
+- **多设备与多标签页流式事件同步及中途连入追平优化 (Multi-device/Multi-tab Live Event Streaming Sync)**：
+  - 优化 `PiAgent` 事件录制范围：只要处于流式生成（Busy/Streaming）状态，即便当前已有在线浏览器连接，也会向 `eventBuffer` 持续录制。
+  - 优化缓存释放策略：若 Agent 仍处于 busy 生成状态，新连入的客户端消费完 `eventBuffer` 后不再立即清空 Buffer。
+  - 优化重连/中途断开录制：若最后一个客户端在 streaming 途中断开连接，只要生成任务仍在运行中，即不销毁当前的缓存。
+  - 以上多项优化完美实现了多台设备（例如手机、电脑）、多个浏览器 Tab 随时刷新或中途连入正在运行中的流式会话时，能够无缝重播已生成的上半段内容并追平后续实时流，极大地增强了多端多 Tab 的协同可靠性。
+
+---
+
+## [1.7.5] - 2026-07-26
+
+### Fixed
+- **初始化 CWD 配置加载与 WebSocket 建立竞态修复 (Async CWD Init Race Condition)**：
+  - 前端 `init()` 声明为异步函数，优先 `await loadServerConfig()` 完成服务器配置（`serverCwd` / `homeDir`）与本地缓存读取后，再发起 WebSocket 连接或加载会话，彻底消除首次加载时 agent 子进程工作目录与前端显示不一致的问题。
+  - 服务端 `normalizeCwd(dir)` 在 `dir` 为空时默认使用 `process.cwd()`（服务启动目录），保证前后端默认工作目录始终精确统一。
+- **错误信息二次 HTML 转义修复 (Double Escape on Error Messages)**：移除 `message_end` 中冗余的 `escapeHtml()` 调用，避免错误信息包含特殊符号时被 Markdown 渲染器二次转义显示为实体编码字符。
+- **CLI 参数解析健壮性增强 (CLI Arguments Validation)**：`bin/pi-web-chat.js` 增加对 `-p/--port` 与 `-c/--cwd` 选项值的合法性检验与防越界保护，避免 `NaN` 或 `undefined`。
+- **输入法合成事件优化 (IME Keycode Handling)**：输入框 `keydown` 事件追加 `e.keyCode !== 229` 判断，进一步增强各平台中文输入法选词回车时的兼容性。
+- **Systemd 安装脚本优化 (Systemd Absolute ExecStart Path)**：`scripts/install-service.sh` 生成 unit 文件时将 `ExecStart` 明确为绝对路径 `$NODE_BIN "$PROJECT_DIR/server.js"`。
+
+---
+
 ## [1.7.4] - 2026-07-26
 
 ### Added

package/docs/ISSUES.md

@@ -99,4 +99,52 @@
 - 给 `.session-list` 增加 `min-height: 0`，给 `.sidebar-bottom` 增加 `flex-shrink: 0`。
 - 引入 `safe-area-inset-bottom` 底部安全区自适应内边距，并将 z-index 提升至 105，确保手机端完整可见。
 
+---
+
+## 10. 页面初次加载时服务端配置加载与 WebSocket 连接的竞态
+
+**症状**：在未设置 localStorage CWD 时打开页面，前端顶栏胶囊显示为当前服务启动目录（`serverCwd`），但后端生成的 agent 子进程的工作目录实际上是用户的 home 目录（`~`），导致执行文件操作或命令时位置不一致。
+
+**根因**：前端 `init()` 中 `loadServerConfig()` 异步发起 `/api/config` 请求，但没有等待返回就同步调用了 `connectWs({})`。此时 `state.cwd` 尚为空字符串 `""`，WebSocket URL 为 `/ws?cwd=`，后端 fallback 成了 `home()`。等到 fetch 返回后 `state.cwd` 虽被赋予 `serverCwd`，但 WebSocket 连接和 `PiAgent` 已经按 `home()` 创建。
+
+**修复**：
+- 前端 `init()` 改为异步函数，显式 `await loadServerConfig()` 保证配置解析完毕后再建立 WebSocket 连接或加载会话。
+- 后端 `normalizeCwd(dir)` 在 `dir` 为空时优先返回 `process.cwd()`，其次回退到 `home()`，确保前后端默认工作目录始终精确一致。
+
+---
+
+## 11. 模型异常响应错误信息二次转义 (Double Escape)
+
+**症状**：当模型返回错误（如 stopReason="error"）且错误信息中含有 `<`、`&` 等字符时，聊天框中显示为 `&lt;`、`&amp;` 字面量。
+
+**根因**：`public/app.js` 在 `message_end` 处理中对 `errMsg` 调用了一次 `escapeHtml()`，随后 `refreshStreamingContent()` 调用 `renderMarkdown()` 时又内部进行了一次 `escapeHtml()`。
+
+**修复**：移除 `message_end` 中冗余的 `escapeHtml()`，统一由 Markdown 渲染器进行安全转义。
+
+---
+
+## 12. Markdown 渲染中潜在的 XSS 注入安全漏洞 (HTML Attribute Breakout)
+
+**症状**：若模型返回了特制格式的 Markdown 链接（例如 `[点击](http://abc.com" style="..." onmouseover="alert(1))`），该链接渲染为 HTML 时能逃逸 `href="..."` 属性，注入任意 HTML 属性与恶意 JavaScript。
+
+**根因**：原先 `escapeHtml()` 仅转义了 `&`、`<`、`>`，未能转义双引号 `"` 与单引号 `'`，使得属性逃逸攻击成为可能。
+
+**修复**：修改 `public/app.js` 中的 `escapeHtml()` 实现，额外对 `"` (`&quot;`) 与 `'` (`&#39;`) 进行了严格转义，阻止任何 HTML 属性级别的注入攻击。
+
+---
+
+## 13. 多设备 / 多 Tab 流式对话时新连入客户端无法追平进度
+
+**症状**：在某一会话处于流式文本生成（Streaming）状态时，若用户在另一台设备或新的浏览器标签页中打开相同会话，由于 `PiAgent` 检测到已连接客户端而不将流式事件写入 `eventBuffer`，新连入的客户端无法回放当前的流式消息，导致其显示为空白、缺页或卡在加载中。
+
+**根因**：
+- 原逻辑在 `onPiMessage` 中判断只有在无客户端连接时才缓存事件（`if (!this.hasWs) this.bufferEvent(obj)`）。
+- 离线回放完毕后，会强制清空环形 Buffer，导致后续其他客户端连入时无内容可播。
+
+**修复**：
+- 在 `server.js` 的 `onPiMessage` 逻辑中，当 `PiAgent` 处于繁忙或流式对话过程中（`this.isBusy` 为真）即便有客户端在线也开启缓存。
+- 修改 `detachWs`，当所有连接断开但 Agent 仍在生成中时，保留 `eventBuffer` 保证继续录制。
+- 修改 `replayBuffered`，在 Agent 仍处于 busy 状态时消费后不清空缓存，使多个设备/多个 Tab 可多次或同时连入并安全回溯追平全部生成细节，并在流式终止时通过 `agent_settled` 进行最终的统一清理。
+
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liguoshuai/pi-web-chat",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
   "type": "module",
   "main": "server.js",

package/public/app.js

@@ -177,7 +177,11 @@ async function confirmCwdChange() {
 
 // ---- Markdown render (small, safe renderer) ----
 function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return s.replace(/&/g, "&amp;")
+          .replace(/</g, "&lt;")
+          .replace(/>/g, "&gt;")
+          .replace(/"/g, "&quot;")
+          .replace(/'/g, "&#39;");
 }
 
 async function copyToClipboard(text) {
@@ -1226,7 +1230,7 @@ function handlePiMessage(obj) {
           const parsed = JSON.parse(errMsg);
           if (parsed.error?.message) errMsg = parsed.error.message;
         } catch {}
-        state.streamingItems.push({ type: "text", text: `⚠️ **${escapeHtml(errMsg)}**` });
+        state.streamingItems.push({ type: "text", text: `⚠️ **${errMsg}**` });
         refreshStreamingContent();
       }
       break;
@@ -1668,11 +1672,13 @@ function autoResize() {
 }
 
 // ---- Init ----
-function init() {
+async function init() {
   // Default cwd to home (server uses home default too).
   state.cwd = document.body.dataset.cwd || "";
 
-  // event listeners
+  // Load server config & restore saved CWD before connecting WebSocket
+  await loadServerConfig();
+
   // event listeners
   $("#btnNew").addEventListener("click", () => {
     if (state.streaming) {
@@ -1716,7 +1722,7 @@ function init() {
     updateComposerUI();
   });
   ta.addEventListener("keydown", (e) => {
-    if (e.key === "Enter" && !e.shiftKey && !e.isComposing) {
+    if (e.key === "Enter" && !e.shiftKey && !e.isComposing && e.keyCode !== 229) {
       e.preventDefault();
       if (state.streaming) {
         if (ta.value.trim()) {
@@ -1826,9 +1832,6 @@ function init() {
     });
   }
 
-  // Load server config & restore saved CWD
-  loadServerConfig();
-
   // Status badge click to reconnect
   const connStatusEl = $("#connStatus");
   if (connStatusEl) {

package/server.js

@@ -37,7 +37,7 @@ const PI_BIN = resolvePiBin();
 function home() { return os.homedir(); }
 
 function normalizeCwd(dir) {
-  if (!dir) return home();
+  if (!dir) return process.cwd() || home();
   let resolved = dir;
   if (dir.startsWith("~")) {
     resolved = path.join(home(), dir.slice(1));
@@ -159,9 +159,13 @@ class PiAgent {
   detachWs(ws) {
     this.sockets.delete(ws);
     if (this.sockets.size === 0) {
-      // Reset event buffer so we only capture events that happen while nobody is connected
-      this.eventBuffer = [];
-      this.bufferHead = 0;
+      // Reset event buffer only if NOT busy.
+      // If we are currently streaming/busy, we must retain the buffer so a reconnecting client
+      // can replay the full stream from the beginning of the active generation.
+      if (!this.isBusy) {
+        this.eventBuffer = [];
+        this.bufferHead = 0;
+      }
       // Browser closed. We do NOT kill the subprocess here: a background task
       // keeps running. We only arm the idle-kill, which fires once the agent
       // is truly idle (no streaming, no pending requests) for IDLE_TIMEOUT_MS.
@@ -326,8 +330,11 @@ class PiAgent {
     }
     // Forward every event / response to connected browsers as-is.
     this.wsSend(obj);
-    // If nobody is listening, remember it so a reconnect can replay.
-    if (!this.hasWs) this.bufferEvent(obj);
+    // If nobody is listening, or if the agent is currently busy (streaming), remember it
+    // so any reconnecting or newly connecting clients can replay and catch up.
+    if (!this.hasWs || this.isBusy) {
+      this.bufferEvent(obj);
+    }
   }
 
   bufferEvent(obj) {
@@ -353,9 +360,12 @@ class PiAgent {
       try { ws.send(JSON.stringify(ev)); } catch {}
     }
     try { ws.send(JSON.stringify({ type: "backfill_end", streaming: this.isBusy, state: this.state })); } catch {}
-    // Clear buffer once consumed by the reconnecting client
-    this.eventBuffer = [];
-    this.bufferHead = 0;
+    // Only clear the buffer if the agent is not busy.
+    // If the agent is still busy, keep the buffer so that other clients or future reconnects can still catch up.
+    if (!this.isBusy) {
+      this.eventBuffer = [];
+      this.bufferHead = 0;
+    }
   }
 
   send(cmd) {