@liguoshuai/pi-web-chat 2.14.0 → 2.14.12

package/docs/ARCHITECTURE.md

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

package/docs/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+## [2.14.12] - 2026-09-05
+
+### Fixed
+- **修复 HarmonyOS `versionCode` 位数与数值回退**：将 `clients/harmony/AppScope/app.json5` 的 `versionCode` 从错误的三位缩短格式（`21411`）恢复为标准的七位格式（`2141200`），并统一全仓版本号至 2.14.12。修正自 2.14.7 起 `versionCode` 由 `2140600` 误缩为 `21407` 造成的数值回退，避免 HarmonyOS 应用商店因版本号非单调递增而拒绝上架。
+
+## [2.14.11] - 2026-09-05
+
+### Fixed
+- **固化服务端与测试进程生命周期回收**：在 `createServer().close()` 中增加 `httpServer.closeAllConnections()` 及 `wss.clients` 强制 terminate 机制，杜绝单元测试及异常退出时因 TCP Keep-Alive 或 WebSocket 连接残留导致 `server.close()` 阻塞挂死。
+
+## [2.14.10] - 2026-09-05
+
+### Fixed
+- **兼容 Node 18+ 原生测试参数**：移除 `node --test` 中 Node 18 不支持的 `--test-timeout` 选项，统一在异步测试内部通过标准 `setTimeout` + `try ... finally` 进行跨版本超时控制与资源清理。
+
+## [2.14.9] - 2026-09-05
+
+### Fixed
+- **修复 CI 依赖安装与 Lockfile 同步**：补全 `clients/web/package.json` 中的依赖声明并同步 `pnpm-lock.yaml`，修复 GitHub Actions 流水线中 `pnpm install --frozen-lockfile` 报错。
+
+## [2.14.8] - 2026-09-05
+
+### Fixed
+- **修复移动端（Android & HarmonyOS）新会话无法正常拉起且卡在“思考中…”的关键 Bug**：
+  - **反序列化强类型报错丢包修复**：`GenericServerMessage` 中 `message`、`code`、`id`、`content` 等多态字段由 `String?` 调整为 `JsonElement?`。修复 Pi 发送 `message_start` / `message_end`（`message` 为 JSON 对象）及 `pi_exit`（`code` 为数字）时抛出 `JsonDecodingException: Expected string, but had BEGIN_OBJECT/0` 导致事件被静默丢弃、会话状态无法流转的问题。
+  - **Prompt 失败响应与错误透传闭环**：服务端在 `activeAgent.send(prompt)` 发生预检失败或 Agent 进程死亡时立即回传 `success: false` 响应；移动端（Android `ChatRepository` 与鸿蒙 `ChatViewModel`）补充 `response.command === "prompt"` 失败处理分支，立即重置 `isStreaming = false` 并展示错误卡片，杜绝无响应时永久卡在“思考中…”。
+  - **新建会话状态全链路同步**：移动端在触发 `new_session` 成功后，自动重置流式状态并向服务端重新请求 `get_state` 与 `get_available_models`，同时将当前已选模型及思考级别重新应用到新会话 Agent 实例中。
+  - **模型报错与异常 UI 渲染完善**：补充 `message_end` 中 `stopReason === "error"` 及 `MessageStatus.ERROR` 的多端错误占位与提示渲染，避免异常时产生空白或假死气泡。
+- **单元测试防挂死与超时保护**：为全仓 Node 测试命令增加 `--test-timeout=30000` 超时保护，网关 WebSocket 单元测试增加显式超时 reject 与 `try ... finally` 资源安全释放，防止异常未捕获导致测试进程永久挂起阻塞流水线。
+
+## [2.14.7] - 2026-09-05
+
+### Fixed
+- **修复僵死任务问题**：服务端 `send()` 对 `prompt`/`steer`/`client_send` 等长运行命令增加可配置超时（默认 10 分钟，环境变量 `LONG_RUNNING_TIMEOUT_MS`），超时后清理 pending entry、重置 streaming 状态并广播 error 事件，防止 pi 子进程挂起时 agent 成为不可回收的僵尸。
+- **前端 `tool_execution_end` 清理 activeToolCalls**：工具执行完成时从 `activeToolCalls` Map 中删除该 entry，避免 stale 条目累积。此前仅在 `finalizeStreamingMsg`/`clearChat` 等批量清空，若 `tool_execution_end` 事件丢失则工具永远卡在"执行中…"。
+- **WebSocket 断线时标记 stale 工具为"已中断"**：`ws.onclose` 中遍历 `activeToolCalls`，将仍为"执行中…"状态的 tool block 标记为"已中断"并停止计时，防止断线后残留僵尸工具块。
+- **`backfill_end` 后清理 stale 工具**：重连回放结束后，若服务端表示 `!streaming`，将所有仍为"执行中…"的 tool block 标记为"已中断"，处理 buffer 溢出丢失 `tool_execution_end` 事件的场景。
+
+## [2.14.6] - 2026-09-05
+
+### Docs
+- 在 `AGENTS.md` 新增「⚡ 效率、专注与职业化准则」章节，从效率（并行执行、合并命令、禁止冗余读取、最小路径）、专注（单一目标、范围控制、先澄清后动手、一次到位）、职业化（诚实不作假、先诊断后修复、最小改动、透明收尾）三个维度规范 AI 智能体行为，提升交付效率与专业度。
+
+## [2.14.5] - 2026-09-05
+
+### Fixed
+- 修复 CI `publish-npm` 与 `publish-release` 的依赖判定：将 `!cancelled()` 改为 `success()`，测试失败时不会发布 NPM 包与 GitHub Release。
+- 修正 README、各客户端 README、UED 原型、架构文档中残留的旧版本号（2.12.7 / 2.12.9 / 2.13.0），并同步全仓版本至 2.14.5。
+
+### Docs
+- 精简 `CLAUDE.md`，明确以 `AGENTS.md` 为唯一权威来源，补齐铁律四（CI 绿勾闭环）。
+
+## [2.14.4] - 2026-09-05
+
+### Performance
+- **添加 HTTP gzip 压缩中间件**：使用 Node.js 内置 `zlib` 实现（零外部依赖），对 `app.js` (123KB→~30KB)、`style.css` (46KB→~10KB) 等文本资源自动 gzip，传输体积减少约 70%。
+- **添加静态资源 Cache-Control 头**：常规资源缓存 1 天，带哈希文件名的资源缓存 1 年（immutable），减少浏览器重复拉取。
+
+### Refactor
+- **提取路径遍历安全校验为 `validateSessionFile()` helper**：`routes.js` 中 GET /api/session 和 DELETE /api/session 的重复安全校验逻辑（~30 行 × 2）合并为一处，降低维护风险。
+- **提取环境变量数值解析为 `parseEnvNum()` helper**：`config.js` 中 4 处重复的 IIFE 模式合并为一个带 `{ integer }` 选项的 helper 函数。
+
+### Fixed
+- 修复 `agent.js` `saveTimingData()` 中注释与代码不一致：注释写 "Keep last 200 turns" 但实际保留 1000 条。
+
 ## [2.14.0] - 2026-09-04
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liguoshuai/pi-web-chat",
-  "version": "2.14.0",
+  "version": "2.14.12",
   "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
   "type": "module",
   "main": "server.js",
@@ -42,8 +42,8 @@
   "dependencies": {
     "express": "^4.21.2",
     "ws": "^8.18.0",
-    "@liguoshuai/pi-chat-protocol": "2.14.0",
-    "@liguoshuai/pi-chat-server": "2.14.0"
+    "@liguoshuai/pi-chat-protocol": "2.14.12",
+    "@liguoshuai/pi-chat-server": "2.14.12"
   },
   "scripts": {
     "build": "node --check server.js && node --check bin/pi-web-chat.js && node --check public/app.js",

package/public/app.js

@@ -604,7 +604,8 @@ function stopStreamingTimer() {
 function sameSession(a, b) {
   if (!a || !b) return false;
   if (a === b) return true;
-  return a.replace(/^[.~]\//, "") === b.replace(/^[.~]\//, "");
+  const norm = (s) => s.replace(/^(?:\.\.?|~)\//, "").replace(/^~$/, "").replace(/\/+$/, "");
+  return norm(a) === norm(b);
 }
 
 // ---- Sidebar / sessions ----
@@ -771,7 +772,7 @@ async function deleteSession(file, title) {
     }
     showToast("会话已删除");
     if (state.currentSessionFile === file) {
-      startNewSession(false);
+      startNewSession();
     } else {
       await refreshSessions();
     }
@@ -831,13 +832,13 @@ async function syncSessionHistory(file, force = false) {
       renderModelPill();
     }
 
-    const topName = data.sessionName || (data.header?.id ? baseName(file) : "新对话");
+    const topName = data.sessionName || data.firstUser || "新对话";
     $("#topSessionName").textContent = topName;
 
     // Only overwrite chat if not actively backfilling
     if (!state.isBackfilling && (force || !state.streaming)) {
       clearChat();
-      const msgs = reconstructFromEntries(data.entries || []);
+      const msgs = reconstructFromEntries(data.entries || [], data.timing || null);
       showEmptyState(msgs.length === 0);
       for (const m of msgs) {
         appendMessageNode(m.role, m);
@@ -883,7 +884,7 @@ function parseEntryTimestamp(ts) {
   return isNaN(parsed) ? null : parsed;
 }
 
-function reconstructFromEntries(entries) {
+function reconstructFromEntries(entries, timing = null) {
   // Map toolResults by toolCallId so we can attach them to their toolCall in the assistant message
   const toolResults = new Map();
   for (const e of entries) {
@@ -900,6 +901,7 @@ function reconstructFromEntries(entries) {
 
   const out = [];
   let lastUserTs = null;
+  let assistantMsgCount = 0;
   for (const e of entries) {
     if (e.type !== "message") continue;
     const m = e.message;
@@ -921,18 +923,35 @@ function reconstructFromEntries(entries) {
       out.push({ role: "user", text: extractContentText(m.content), images, ts: msgTs });
     } else if (m.role === "assistant") {
       let turnDurationMs = null;
-      if (lastUserTs && msgTs && msgTs >= lastUserTs) {
+      // Try timing data first, then fall back to timestamp heuristic
+      const turnTiming = timing ? timing[assistantMsgCount] : null;
+      if (turnTiming?.turnDuration != null) {
+        turnDurationMs = turnTiming.turnDuration;
+      } else if (lastUserTs && msgTs && msgTs >= lastUserTs) {
         const diff = msgTs - lastUserTs;
         if (diff > 0 && diff < 15 * 60 * 1000) {
           turnDurationMs = diff;
         }
       }
+      let thinkingIdx = 0;
       const rawContent = Array.isArray(m.content) ? m.content : (m.content ? [{ type: "text", text: String(m.content) }] : []);
       const content = rawContent.map(part => {
+        if (part && part.type === "thinking") {
+          // Apply persisted thinking duration from timing data
+          let thinkingDurationMs = null;
+          if (turnTiming?.thinkingDurations && thinkingIdx < turnTiming.thinkingDurations.length) {
+            thinkingDurationMs = turnTiming.thinkingDurations[thinkingIdx];
+          }
+          thinkingIdx++;
+          return { ...part, durationMs: thinkingDurationMs };
+        }
         if (part && part.type === "toolCall") {
           const res = toolResults.get(part.id);
           let durationMs = null;
-          if (res) {
+          // Try timing data first
+          if (turnTiming?.toolDurations && part.id && turnTiming.toolDurations[part.id] != null) {
+            durationMs = turnTiming.toolDurations[part.id];
+          } else if (res) {
             const startTs = parseEntryTimestamp(part.timestamp || m.timestamp || e.timestamp);
             const endTs = res.entryTs || parseEntryTimestamp(res.timestamp);
             if (startTs && endTs && endTs >= startTs) {
@@ -952,6 +971,7 @@ function reconstructFromEntries(entries) {
         content.push({ type: "text", text: `⚠️ **生成失败**: ${errMsg}` });
       }
       out.push({ role: "assistant", content, ts: msgTs, turnDurationMs, usage: m.usage });
+      assistantMsgCount++;
     }
     // toolResult entries are attached directly to assistant toolCall parts, so they don't produce standalone messages
   }
@@ -1912,6 +1932,22 @@ function connectWs(opts = {}) {
     isConnecting = false;
     if (ws._suppressOnclose) return;
 
+    // Mark any tool blocks still in "执行中…" as interrupted — otherwise they
+    // stay as zombie "执行中…" blocks forever after a disconnect mid-execution.
+    for (const [, tc] of state.activeToolCalls) {
+      const stateEl = tc.head?.querySelector(".state");
+      if (stateEl && stateEl.classList.contains("running")) {
+        stateEl.className = "state error";
+        stateEl.textContent = "已中断";
+      }
+      if (tc.durationEl && tc.durationEl._startedAt) {
+        const dur = Math.max(0, Date.now() - tc.durationEl._startedAt);
+        tc.durationEl.className = "tool-duration";
+        tc.durationEl._startedAt = null;
+        tc.durationEl.textContent = `耗时 ${formatDuration(dur)}`;
+      }
+    }
+
     wasDisconnected = true;
     setConnStatus("disconnected");
     scheduleReconnect();
@@ -1959,9 +1995,8 @@ function handlePiMessage(obj) {
       const newUrl = window.location.pathname + "?session=" + encodeURIComponent(sessionFile);
       window.history.replaceState({ session: sessionFile }, "", newUrl);
     } catch {}
-    if ($("#topSessionName").textContent === "新对话") {
-      $("#topSessionName").textContent = baseName(sessionFile);
-    }
+    // Do not set baseName(sessionFile) as title — it's a session ID, not a user-friendly summary.
+    // The proper title will be set by syncSessionHistory (via firstUser) or by the user prompt.
     refreshSessions();
   }
 
@@ -1987,6 +2022,22 @@ function handlePiMessage(obj) {
         syncSessionHistory(state.currentSessionFile, false);
       }
     } else {
+      // Server says not streaming — finalize any stale tool blocks that were
+      // left in "执行中…" by a partial backfill (e.g. buffer overflow lost
+      // the matching tool_execution_end event).
+      for (const [, tc] of state.activeToolCalls) {
+        const stateEl = tc.head?.querySelector(".state");
+        if (stateEl && stateEl.classList.contains("running")) {
+          stateEl.className = "state error";
+          stateEl.textContent = "已中断";
+        }
+        if (tc.durationEl && tc.durationEl._startedAt) {
+          const dur = Math.max(0, Date.now() - tc.durationEl._startedAt);
+          tc.durationEl.className = "tool-duration";
+          tc.durationEl._startedAt = null;
+          tc.durationEl.textContent = `耗时 ${formatDuration(dur)}`;
+        }
+      }
       finalizeStreamingMsg();
       state.streaming = false;
       state.aborting = false;
@@ -2266,6 +2317,10 @@ function handlePiMessage(obj) {
           stateEl.textContent = obj.isError ? "错误" : "完成";
           stateEl.className = "state" + (obj.isError ? " error" : "");
         }
+        // Remove from activeToolCalls so stale entries don't accumulate.
+        // Previously only cleared wholesale in finalizeStreamingMsg/clearChat/etc,
+        // which meant a missed tool_execution_end left tools stuck in "执行中…" forever.
+        state.activeToolCalls.delete(obj.toolCallId);
       }
       break;
     }
@@ -2365,7 +2420,11 @@ function updateState(d) {
     renderThinkingPill();
   }
   updateEmptyStateModelInfo();
-  $("#topSessionName").textContent = d?.sessionName || (d?.sessionFile ? baseName(d.sessionFile) : "新对话");
+  // Only update top bar title from state if sessionName is explicitly available;
+  // otherwise keep current title (set by syncSessionHistory or user prompt) to avoid showing session file name.
+  if (d?.sessionName) {
+    $("#topSessionName").textContent = d.sessionName;
+  }
 
   // Sync streaming state upon state updates (e.g. after reconnect)
   if (d && typeof d.isStreaming === "boolean") {
@@ -3173,7 +3232,7 @@ async function init() {
   await loadServerConfig();
 
   // event listeners
-  $("#btnNew").addEventListener("click", () => startNewSession(true));
+  $("#btnNew").addEventListener("click", () => startNewSession());
 
   $("#sendBtn").addEventListener("click", () => {
     if (state.streaming) {
@@ -3246,7 +3305,7 @@ async function init() {
 
     if (isCmdOrCtrl && e.shiftKey && (e.key.toLowerCase() === "n" || e.key.toLowerCase() === "o")) {
       e.preventDefault();
-      startNewSession(true);
+      startNewSession();
       return;
     }
     if ((isCmdOrCtrl && e.key.toLowerCase() === "k") || (e.ctrlKey && e.key === "/")) {