kellyvv · deepen-pro · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@ node_modules/
 *.out
 .gemini/
 .vscode/
+.idea/
 .claude/
 .cache/
 .data/

diff --git a/README.md b/README.md
@@ -276,6 +276,7 @@ OpenHer 支持多种大模型——但不是所有模型都能胜任人格涌现
 
 - Python 3.11+
 - macOS 14.0+（桌面客户端，可选）
+- Node.js 20.19+ 或 22.12+（网页端，可选）
 - 任一支持的 LLM 服务商 API 密钥
 
 ### 一、克隆 & 安装
@@ -337,7 +338,7 @@ INFO:     Uvicorn running on http://0.0.0.0:8000
 ✓ GenomeEngine loaded · 10 personas available
 ```
 
-### 四、启动桌面客户端
+### 四、启动桌面客户端（可选）
 
 1. 从 [GitHub Releases](https://github.com/kellyvv/OpenHer/releases) 下载 `OpenHer.app.zip`
 2. 解压得到 `OpenHer.app`
@@ -359,7 +360,29 @@ chmod +x run.sh
 
 </details>
 
-### 五、长期记忆（可选）
+### 五、启动网页端（可选）
+
+网页端位于 `web/`，是基于 Vite + React 的浏览器客户端。它不修改 Python 后端或人格引擎，适合直接在浏览器中体验角色发现、唤醒、聊天、演示面板和引擎调试信息。
+
+使用前请先保持后端运行（步骤三），默认连接 `http://localhost:8000`。
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+打开 `http://localhost:5173` 即可使用。若后端地址不是默认值，可以在网页端的设置面板中修改，配置会保存在浏览器 `localStorage`。
+
+生产构建：
+
+```bash
+npm run build
+```
+
+构建产物会输出到 `web/dist`。
+
+### 六、长期记忆（可选）
 
 连接 [EverMemOS](https://evermind.ai) 获得跨对话的持久化记忆。
 

diff --git a/README_EN.md b/README_EN.md
@@ -248,6 +248,7 @@ OpenHer works with multiple LLMs — but not all models are created equal. Perso
 
 - Python 3.11+
 - macOS 14.0+ (for desktop client, optional)
+- Node.js 20.19+ or 22.12+ (for web client, optional)
 - An API key from any supported LLM provider
 
 ### 1. Clone & Install
@@ -309,7 +310,7 @@ INFO:     Uvicorn running on http://0.0.0.0:8000
 ✓ GenomeEngine loaded · 10 personas available
 ```
 
-### 4. Launch the Desktop Client
+### 4. Launch the Desktop Client (Optional)
 
 1. Download `OpenHer.app.zip` from [GitHub Releases](https://github.com/kellyvv/OpenHer/releases)
 2. Unzip to get `OpenHer.app`
@@ -331,7 +332,29 @@ Requires macOS 14.0+ and Xcode Command Line Tools (`xcode-select --install`).
 
 </details>
 
-### 5. Long-Term Memory (Optional)
+### 5. Launch the Web Client (Optional)
+
+The web client lives in `web/`. It is a Vite + React browser client that does not modify the Python backend or persona engine. It lets you use persona discovery, awakening, chat, demo panels, engine status, and debug views directly from a browser.
+
+Before using it, keep the backend running (step 3). By default, the web client connects to `http://localhost:8000`.
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173` to use it. If your backend is not using the default URL, change it in the web settings panel. The value is stored in browser `localStorage`.
+
+Production build:
+
+```bash
+npm run build
+```
+
+The production output is written to `web/dist`.
+
+### 6. Long-Term Memory (Optional)
 
 Connect [EverMemOS](https://evermind.ai) for cross-session persistent memory.
 

diff --git a/web/.gitignore b/web/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo
diff --git a/web/README.md b/web/README.md
@@ -0,0 +1,32 @@
+# OpenHer Web
+
+Standalone browser client for OpenHer. It does not modify the Python backend or persona engine.
+
+## Run
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173` and keep the OpenHer backend running at `http://localhost:8000`.
+
+The backend URL can be changed in the web settings panel. The value is stored in browser `localStorage`.
+
+## Build
+
+```bash
+npm run build
+```
+
+The production output is written to `web/dist`.
+
+## Protocol Coverage
+
+- `GET /api/status`
+- `GET /api/personas`
+- `GET /api/chat/history/{persona_id}?client_id=...`
+- `GET /api/persona/{persona_id}/media/{front|face|awakening|awakened}`
+- `WebSocket /ws/chat`
+- WebSocket events: `chat_start`, `chat_chunk`, `chat_end`, `silence`, `proactive`, `tts_audio`, `error`, `persona_switched`
diff --git a/web/index.html b/web/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f0e4d2" />
+    <title>OpenHer Web</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,6 +13,7 @@ node_modules/ @@
     *.out
     .gemini/
     .vscode/
+    .idea/
     .claude/
     .cache/
     .data/
@@ Expand Down @@