@liguoshuai/pi-web-chat 2.12.2 → 2.14.0

package/README.md

@@ -9,7 +9,7 @@
 (`pi --mode rpc`) 与 pi 子进程通信，前端走 WebSocket 流式渲染。
 
 > 📦 **NPM 软件包**：[`@liguoshuai/pi-web-chat`](https://www.npmjs.com/package/@liguoshuai/pi-web-chat)  
-> 🔗 **项目主页**：https://github.com/liguoshuai-1990/pi-web-chat
+> 🔗 **项目主页**：https://github.com/liguoshuai-1990/pi-chat
 
 ---
 
@@ -132,8 +132,8 @@ npx @liguoshuai/pi-web-chat --port 8080 --cwd /path/to/your/project
 #### 方式 C：通过 Git 源码克隆与启动（适合二次开发）
 
 ```bash
-git clone https://github.com/liguoshuai-1990/pi-web-chat.git
-cd pi-web-chat
+git clone https://github.com/liguoshuai-1990/pi-chat.git
+cd pi-chat
 npm install
 npm start
 ```
@@ -181,11 +181,14 @@ Web 服务启动后，在浏览器中访问：
 | `PORT` | `3000` | Web 服务监听端口 |
 | `PI_BIN` | 自动探测（`~/.npm-global/bin/pi`、`/usr/local/bin/pi` 或 `PATH`） | 显式指定 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 允许缓存的最大事件条数 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的进程回收超时（`0` 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `0` (无上限) | 单个 Agent 进程后台生存硬上限（`0` 为禁用） |
+| `EVENT_BUFFER_SIZE` | `5000` | 离线环形 Buffer 允许缓存的最大事件条数 |
 | `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
 | `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
+| `HOST` | `0.0.0.0` | 服务监听地址 |
+| `AUTH_TOKEN` / `PI_AUTH_TOKEN` | 空 | 全局访问令牌，客户端需以 Bearer Token 鉴权（空为不鉴权） |
+| `ALLOWED_ORIGINS` | 空 | 允许的 CORS/WebSocket 源白名单（逗号分隔，空为仅允许 localhost/同源） |
 
 ---
 

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构设计文档
 
-> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v2.3.0 版本）。
+> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v2.12.7 版本）。
 
 ---
 
@@ -147,11 +147,14 @@ Browser                         server.js                       pi RPC 子进程
 | `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 允许缓存的最大事件条数 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的回收超时（`0` 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `0` (无上限) | 单个 Agent 进程后台生存硬上限（`0` 为禁用） |
+| `EVENT_BUFFER_SIZE` | `5000` | 离线环形 Buffer 允许缓存的最大事件条数 |
 | `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
 | `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
+| `HOST` | `0.0.0.0` | 服务监听地址 |
+| `AUTH_TOKEN` / `PI_AUTH_TOKEN` | 空 | 全局访问令牌，客户端需以 Bearer Token 鉴权（空为不鉴权） |
+| `ALLOWED_ORIGINS` | 空 | 允许的 CORS/WebSocket 源白名单（逗号分隔，空为仅允许 localhost/同源） |
 
 ---
 

package/docs/CHANGELOG.md

@@ -5,7 +5,143 @@ 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).
 
+
+
+## [2.14.0] - 2026-09-04
+
+### Changed
+- 全端版本号统一递增至 2.14.0（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+- 触发 CI 发布流程，产出全平台交付物（NPM 包 / HarmonyOS 包 / Android APK / GitHub Release）。
+
+## [2.13.1] - 2026-09-04
+
+### Fixed
+- **修复 Android `ChatRepository.changeCwd()` 永久破坏 Repository 的关键 Bug**：
+  - `disconnect()` 原先调用 `wsClient.shutdown()` + `scope.cancel()`，会关闭 OkHttp 线程池并永久取消协程作用域；
+  - `changeCwd()` 调用 `disconnect()` 后再调用 `connect()`，但 OkHttp 已关闭无法创建新连接，`scope` 已取消导致 `init{}` 中的 `connectionState` 和 `incomingMessages` 两个 collector 永久死亡；
+  - 用户切换工作目录后，Repository 永久失聪 — WebSocket 消息无法处理，连接状态无法更新，所有 `scope.launch{}` 静默失效；
+  - 修复：`disconnect()` 改为仅调用 `wsClient.disconnect()`（只关闭当前 WebSocket），`close()` 改为 `wsClient.shutdown()` + `scope.cancel()`（完整清理），`onCleared()` 改为调用 `close()`。
+- **修复 Android 真机无法连接局域网网关服务器的问题**：
+  - `network_security_config.xml` 原先仅允许 `10.0.2.2`（模拟器环回）、`localhost`、`127.0.0.1` 三个地址的明文 HTTP 流量；
+  - 真机连接局域网服务器（如 `http://192.168.1.x:3000`）时，Android 系统会静默拦截明文请求，导致 WebSocket 握手失败、App 显示"连接失败"；
+  - 改为 `<base-config cleartextTrafficPermitted="true" />`，允许所有域名的明文 HTTP，因为 Pi Gateway 是局域网/本地开发工具，设计上只跑纯 HTTP（无 TLS），要求用户配置证书不现实。
+
+## [2.13.0] - 2026-09-04
+
+### Added
+- **新增 UED 界面原型样例 (`docs/ued/`)**：
+  - 为网页 WEB、手机 WEB、手机 APP 三端创建 HTML 交互原型（代码级 Mockup），可浏览器直接打开预览；
+  - `index.html`：UED 总览页，含术语说明（UED/UX/UI/IXD）、业界原型绘制方式对比表、设计规范摘要；
+  - `desktop-web.html`：桌面网页端原型，双栏布局（侧边栏+主聊天区），含会话列表、消息流、代码块、输入栏；
+  - `mobile-web.html`：手机网页端原型，单栏布局+左滑抽屉，含 iPhone 设备框架、触控优化输入栏；
+  - `mobile-app.html`：手机 APP 端原型，含聊天页（气泡式消息）和设置页（模型/连接/界面配置），Android/HarmonyOS 通用风格；
+  - `README.md`：UED 设计说明文档，含三端布局差异对比表、配色规范、间距圆角规范。
+
+### Changed
+- 全端版本号统一递增至 2.13.0（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+## [2.12.11] - 2026-09-04
+
+### Added
+- **AI Agent 规范升级：新增铁律四（GitHub Actions CI 全绿保障闭环）(`AGENTS.md`)**：
+  - 将《Pi-Chat AI Coding Agent 工作指南》核心原则升级为“四大强制原则”；
+  - 正式确立“铁律四：推送后必监控并保证 GitHub Actions CI 全绿”，要求智能体在每次 push 后通过 `gh run list` / `gh run watch` 跟踪 CI 流水线状态，若发生故障必须立即闭环修复至 100% 成功，保证主干代码时刻健康。
+
+### Changed
+- 全端版本号统一递增至 2.12.11（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+## [2.12.10] - 2026-09-04
+
+### Fixed
+- **修复 GitHub Actions CI 的 Android 构建失败 (`clients/android/app/build.gradle.kts`)**：Kotlin DSL 脚本中 `java.util.Properties()` 因 `java` 标识符被 Java 插件扩展遮蔽而解析失败，导致 `./gradlew assembleDebug` 编译报错 `Unresolved reference: util`。改为脚本顶部显式 `import java.util.Properties` 并引用 `Properties()`，恢复 Android Debug APK 产物构建。
+
+### Changed
+- 全端版本号统一递增至 2.12.10（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+---
+---
+
+## [2.12.9] - 2026-09-04
+
+### Fixed
+- **用户旅途文档修正与补充 (`docs/USER_JOURNEY.md`)**：基于 5 个代码探索子代理的完整分析结果，修正并补充文档内容：
+  - 修正痛点 #7：会话搜索功能仅 HarmonyOS 缺失（Web 和 Android 已有），原误标为"全端"问题。
+  - 新增痛点 #9-#13：HarmonyOS 端无 Token 输入 UI、错误信息不可见、无删除会话、无模型选择 UI；Android/HarmonyOS 端错误提示 UI 薄弱。
+  - 功能对齐矩阵补充 7 行：空状态引导芯片、键盘快捷键、消息发送失败重试、离开页面警告、图片 Lightbox、代码块复制按钮、错误提示方式。
+  - 三端交互差异对比补充 8 行：空状态引导、键盘快捷键、离开警告、发送失败重试、图片大图查看、明文 HTTP 限制、流式看门狗超时。
+  - 改进建议从 8 条扩展至 9 条，新增移动端错误提示增强建议。
+  - 文档末尾补充分析方法说明与子代理交叉验证过程。
+
+### Changed
+- 全端版本号统一递增至 2.12.9（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+---
+---
+
+## [2.12.8] - 2026-09-04
+
+### Added
+- **用户旅途全景分析文档 (`docs/USER_JOURNEY.md`)**：新增面向终端使用者的 Customer Journey Map 文档，深度分析代码库后从用户视角梳理完整用户旅途，覆盖六大阶段（发现获取 → 配置连接 → 核心对话 → 会话管理 → 高级功能 → 异常恢复），包含产品定位与用户画像、系统拓扑与触点、三端功能对齐矩阵、交互模式差异对比、用户痛点与改进建议、协议消息全景附录。
+
+### Changed
+- 全端版本号统一递增至 2.12.8（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
 ---
+---
+
+## [2.12.7] - 2026-09-04
+
+### Fixed
+- **全仓文档版本号漂移清理 (`README.md`, `clients/harmony/README.md`, `clients/android/README.md`)**：修复多处残留的旧版本号（`version-2.10.0` 徽章、HarmonyOS / Android 页首标题与工程目录注释中的 `v2.11.3`、`2.10.0`），统一对齐至当前版本 2.12.7。
+- **Web 客户端仓库地址更新 (`clients/web/package.json`, `clients/web/README.md`)**：`repository` / `bugs` / `homepage` 及克隆地址由已废弃的 `pi-web-chat` 仓库更正为 Monorepo 主仓 `pi-chat`。
+- **环境变量文档补齐与默认值修正 (`.env.example`, `server/.env.example`, `clients/web/README.md`, `clients/web/docs/ARCHITECTURE.md`)**：补充缺失的 `PI_AUTH_TOKEN`、`MAX_AGENT_LIFETIME_MS`、`EVENT_BUFFER_SIZE`、`IDLE_DROP_HEAP`、`HOST`、`ALLOWED_ORIGINS` 说明；修正 `MAX_AGENT_LIFETIME_MS`（默认 `0` 禁用）与 `EVENT_BUFFER_SIZE`（默认 `5000`）两处过时默认值。
+- **Android 构建产物命名文档同步 (`README.md`, `clients/android/README.md`, `docs/ARCHITECTURE.md`)**：将过时的 `app-debug.apk` 引用更正为构建脚本实际产出的 `pi-chat-v{version}-debug.apk` 命名。
+
+### Changed
+- 全端版本号统一递增至 2.12.7（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+---
+
+## [2.12.6] - 2026-09-04
+
+### Fixed
+- **服务端代码深度扫描修复（`server/src/*`）**：
+  - `auth.js`：Token 校验改用 `crypto.timingSafeEqual` 恒定时间比较，消除计时侧信道攻击风险，并对非字符串输入做安全归一化。
+  - `ws.js`：修复 WebSocket 鉴权失败/容量拒绝时错误消息的 `id` 被错误放入 `details` 字段的问题，改为顶层 `id`，保证客户端可按请求 id 正确关联错误响应。
+  - `ws.js`：移除 `verifyClient` 中残留的空操作死代码（仅注释无逻辑的判断块）。
+  - `agent.js`：修复 `replayBufferedSse` 在非流式状态下回放后未清空事件缓冲区的问题（与 `replayBufferedWs` 行为对齐），避免旧事件向新连接的 SSE 客户端重复回放。
+  - `routes.js`：`/api/log-error` 端点新增字段长度截断（每字段上限 2048 字符），防止恶意/异常客户端写入超大内容刷屏服务端日志。
+
+---
+
+## [2.12.5] - 2026-09-04
+
+### Improved
+- **CI NPM 发布支持动态 OTP 验证与 Automation Token 配置 (`.github/workflows/ci.yml`)**：
+  - 在 `workflow_dispatch` 触发器中新增可选的 `npm_otp` 参数，允许在缺少 Automation Token 时通过手动输入 2FA 一次性验证码完成 NPM 发布；
+  - 完善发布环境的 Token 传递与错误提示。
+
+### Changed
+- 全端版本号统一递增至 2.12.5（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+## [2.12.4] - 2026-09-04
+
+### Added
+- **GitHub Actions CI 自动发布至 NPM Registry (`.github/workflows/ci.yml`)**：
+  - 新增 `publish-npm` 任务，集成 GitHub 仓库配置的 `NPM_TOKEN` Secret 与 `actions/setup-node` 注册表认证；
+  - 支持在推送版本 Tag（如 `v2.12.4`）或手动触发 `workflow_dispatch`（勾选 `publish_npm: true`）时，自动将全套 Monorepo 包（`@liguoshuai/pi-chat-protocol`、`@liguoshuai/pi-chat-server`、`@liguoshuai/pi-web-chat`）安全发布至 NPM Registry。
+
+### Changed
+- 全端版本号统一递增至 2.12.4（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
+
+## [2.12.3] - 2026-09-04
+
+### Fixed
+- **Android 端 Compose `Modifier.padding` 参数签名编译错误 (`clients/android/app/src/main/java/com/pichat/android/ui/screen/ChatScreen.kt`)**：修复输入栏容器 `Column` 中非法混用 `horizontal` 与 `top` / `bottom` 命名参数导致 Kotlin 编译报错（`None of the following candidates is applicable`）的问题，规范化为四向命名参数（`start`, `top`, `end`, `bottom`）。
+- **GitHub Actions CI 升级 (`.github/workflows/ci.yml`)**：将 `actions/setup-java` 从 v4 升级至官方推荐的 v5。
+
+### Changed
+- 全端版本号统一递增至 2.12.3（Monorepo Lockstep：Root / Protocol / Server / Web / Android / HarmonyOS）。
 
 ## [2.12.2] - 2026-09-04
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liguoshuai/pi-web-chat",
-  "version": "2.12.2",
+  "version": "2.14.0",
   "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
   "type": "module",
   "main": "server.js",
@@ -26,12 +26,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/liguoshuai-1990/pi-web-chat.git"
+    "url": "git+https://github.com/liguoshuai-1990/pi-chat.git"
   },
   "bugs": {
-    "url": "https://github.com/liguoshuai-1990/pi-web-chat/issues"
+    "url": "https://github.com/liguoshuai-1990/pi-chat/issues"
   },
-  "homepage": "https://github.com/liguoshuai-1990/pi-web-chat#readme",
+  "homepage": "https://github.com/liguoshuai-1990/pi-chat#readme",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -42,8 +42,8 @@
   "dependencies": {
     "express": "^4.21.2",
     "ws": "^8.18.0",
-    "@liguoshuai/pi-chat-server": "2.12.2",
-    "@liguoshuai/pi-chat-protocol": "2.12.2"
+    "@liguoshuai/pi-chat-protocol": "2.14.0",
+    "@liguoshuai/pi-chat-server": "2.14.0"
   },
   "scripts": {
     "build": "node --check server.js && node --check bin/pi-web-chat.js && node --check public/app.js",