docs: add YouTube videos, WeChat EN section, fix port + install UX

- README: demo video below top screenshots, how-it-works video in engine
  architecture section (both zh + en)
- README_EN: add WeChat integration section (parity with zh)
- README_EN: fix port typo 8800 → 8000
- GitHub Actions: build + ad-hoc sign + release OpenHer.app.zip on tag push
- setup.sh: auto-detect Python 3.11+ (tries 3.13/3.12/3.11 via Homebrew)
- run.sh: venv path validation — upgrade first, rebuild only on failure
- .gitignore: add .venv/, .build/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kellyvv

.github/workflows/build-app.yml

@@ -0,0 +1,101 @@
+name: Build macOS App
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build with Swift (Release)
+        working-directory: desktop/OpenHer
+        run: swift build -c release
+
+      - name: Assemble .app bundle
+        working-directory: desktop/OpenHer
+        run: |
+          BUILD_DIR=".build/release"
+          APP_DIR="$BUILD_DIR/OpenHer.app"
+          CONTENTS="$APP_DIR/Contents"
+          MACOS_DIR="$CONTENTS/MacOS"
+          RESOURCES_DIR="$CONTENTS/Resources"
+
+          mkdir -p "$MACOS_DIR" "$RESOURCES_DIR"
+
+          # Binary
+          cp "$BUILD_DIR/OpenHer" "$MACOS_DIR/OpenHer"
+
+          # Icon
+          if [ -f "Sources/Resources/AppIcon.icns" ]; then
+            cp "Sources/Resources/AppIcon.icns" "$RESOURCES_DIR/AppIcon.icns"
+          fi
+
+          # SPM resource bundles
+          for bundle in "$BUILD_DIR"/*.bundle; do
+            if [ -d "$bundle" ]; then
+              cp -R "$bundle" "$MACOS_DIR/"
+            fi
+          done
+
+          # Info.plist
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          cat > "$CONTENTS/Info.plist" << PLIST
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>CFBundleExecutable</key>
+            <string>OpenHer</string>
+            <key>CFBundleIdentifier</key>
+            <string>com.openher.app</string>
+            <key>CFBundleName</key>
+            <string>OpenHer</string>
+            <key>CFBundleDisplayName</key>
+            <string>OpenHer</string>
+            <key>CFBundleVersion</key>
+            <string>${TAG_VERSION}</string>
+            <key>CFBundleShortVersionString</key>
+            <string>${TAG_VERSION}</string>
+            <key>CFBundleIconFile</key>
+            <string>AppIcon</string>
+            <key>CFBundlePackageType</key>
+            <string>APPL</string>
+            <key>LSMinimumSystemVersion</key>
+            <string>14.0</string>
+            <key>NSHighResolutionCapable</key>
+            <true/>
+          </dict>
+          </plist>
+          PLIST
+
+          # Ad-hoc code signing (avoids Gatekeeper quarantine block)
+          codesign --force --deep --sign - "$APP_DIR"
+
+          echo "✅ OpenHer.app assembled and signed (ad-hoc)"
+
+      - name: Create zip
+        working-directory: desktop/OpenHer
+        run: |
+          cd .build/release
+          ditto -c -k --keepParent OpenHer.app OpenHer.app.zip
+          echo "✅ OpenHer.app.zip created ($(du -h OpenHer.app.zip | cut -f1))"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: desktop/OpenHer/.build/release/OpenHer.app.zip
+          body: |
+            ## OpenHer macOS 客户端
+
+            下载 `OpenHer.app.zip`，解压后双击打开。
+
+            > ⚠️ 首次打开 macOS 可能会提示"无法验证开发者"，请右键 → 打开 → 信任。
+
+            需要后端服务配合使用，请参考 [快速开始](https://github.com/kellyvv/OpenHer#-快速开始)。
+          generate_release_notes: true

.gitignore

@@ -18,6 +18,8 @@ node_modules/
 .data/
 models/
 .pytest_cache/
+.venv/
+.build/
 venv/
 *.egg-info/
 dist/

README.md

@@ -32,6 +32,11 @@
 </table>
 
 *她们在等你唤醒。*
+
+<br>
+
+[![演示视频](https://img.youtube.com/vi/AE7bspVHEI8/maxresdefault.jpg)](https://www.youtube.com/watch?v=AE7bspVHEI8)
+
 </div>
 
 ---
@@ -187,8 +192,12 @@ OpenHer 以同样的逻辑构建 Persona Engine——**运用仿生机制，创
 
 <div align="center">
 <img src="docs/assets/architecture.png" alt="OpenHer Persona Engine 架构图" width="90%">
-</div>
 
+<br>
+
+[![原理讲解视频](https://img.youtube.com/vi/9X8CnuJpc9M/maxresdefault.jpg)](https://www.youtube.com/watch?v=9X8CnuJpc9M)
+
+</div>
 
 不同的随机种子 → 不同的神经网络初始化 → 不同的涌现人格。相同 MBTI，完全不同的人——连我们自己都会感到意外。
 
@@ -324,13 +333,24 @@ INFO:     Uvicorn running on http://0.0.0.0:8000
 
 ### 四、启动桌面客户端
 
+**推荐：下载预编译版本**
+
+从 [GitHub Releases](https://github.com/kellyvv/OpenHer/releases) 下载最新的 `OpenHer.app.zip`，解压后双击打开。
+
+> ⚠️ 首次打开 macOS 可能提示"无法验证开发者"，请右键 → 打开 → 信任。
+
+<details>
+<summary>🔧 开发者：从源码编译</summary>
+
 ```bash
 cd desktop/OpenHer
 chmod +x run.sh
 ./run.sh          # 编译 SwiftUI 应用并启动 OpenHer.app
 ```
 
-> 需要 macOS 14.0+ 和 Xcode 命令行工具（`xcode-select --install`）。
+需要 macOS 14.0+ 和 Xcode 命令行工具（`xcode-select --install`）。
+
+</details>
 
 ### 五、长期记忆（可选）
 

README_EN.md

@@ -32,6 +32,11 @@
 </table>
 
 *They are waiting for you to awaken them.*
+
+<br>
+
+[![Demo](https://img.youtube.com/vi/AE7bspVHEI8/maxresdefault.jpg)](https://www.youtube.com/watch?v=AE7bspVHEI8)
+
 </div>
 
 ---
@@ -165,6 +170,11 @@ An extensible skill framework that gives her real-world capabilities. Weather, s
 
 <div align="center">
 <img src="docs/assets/architecture.png" alt="OpenHer Persona Engine Architecture" width="90%">
+
+<br>
+
+[![How It Works Video](https://img.youtube.com/vi/9X8CnuJpc9M/maxresdefault.jpg)](https://www.youtube.com/watch?v=9X8CnuJpc9M)
+
 </div>
 
 **The core insight:** no line of prompt describes her personality. The Critic perceives 8-dimensional context, 5 drives metabolize with real time, and the Genome Engine's random neural network fuses it all into 8 behavioral signals — what the LLM reads is not an instruction, but a living personality state. Different seeds → different people → emergent surprises.
@@ -295,19 +305,30 @@ python main.py
 
 You should see:
 ```
-INFO:     Uvicorn running on http://0.0.0.0:8800
+INFO:     Uvicorn running on http://0.0.0.0:8000
 ✓ GenomeEngine loaded · 10 personas available
 ```
 
 ### 4. Launch the Desktop Client
 
+**Recommended: Download pre-built app**
+
+Download the latest `OpenHer.app.zip` from [GitHub Releases](https://github.com/kellyvv/OpenHer/releases), unzip and double-click to open.
+
+> ⚠️ macOS may warn "unverified developer" on first launch — right-click → Open → Trust.
+
+<details>
+<summary>🔧 Developers: Build from source</summary>
+
 ```bash
 cd desktop/OpenHer
 chmod +x run.sh
 ./run.sh          # Builds SwiftUI app and launches OpenHer.app
 ```
 
-> Requires macOS 14.0+ and Xcode Command Line Tools (`xcode-select --install`).
+Requires macOS 14.0+ and Xcode Command Line Tools (`xcode-select --install`).
+
+</details>
 
 ### 5. Long-Term Memory (Optional)
 
@@ -332,6 +353,50 @@ Set in `.env`:
 EVERMEMOS_BASE_URL=http://localhost:1995/api/v1
 ```
 
+### 💬 WeChat Integration (Optional)
+
+Connect OpenHer to WeChat via [wechat-to-anything](https://www.npmjs.com/package/wechat-to-anything) for the full text, voice, and photo experience.
+
+**How it works:** A lightweight Python adapter (`wechat_adapter.py`) translates the OpenHer REST API into OpenAI-compatible format. `wechat-to-anything` handles WeChat message routing.
+
+```
+WeChat user ←→ wechat-to-anything ←→ wechat_adapter.py ←→ OpenHer
+                   (bridge)              (adapter :8001)    (backend :8000)
+```
+
+**1. Start the adapter**
+
+```bash
+python wechat_adapter.py
+# 🔗 OpenHer WeChat Adapter
+#    Listen: 0.0.0.0:8001
+```
+
+Environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENHER_BASE` | OpenHer backend URL | `http://localhost:8000` |
+| `OPENHER_PERSONA` | Default persona | `luna` |
+| `ADAPTER_PORT` | Adapter port | `8001` |
+
+**2. Start the WeChat bridge**
+
+```bash
+npx -y wechat-to-anything@latest http://localhost:8001/v1
+# A QR code will appear on first run — scan with WeChat to log in
+```
+
+**Supported message types:**
+
+| Direction | Text | Voice | Photo | File |
+|:----------|:----:|:-----:|:-----:|:----:|
+| WeChat → Agent | ✅ | ✅ auto-transcribed | ✅ multimodal | ✅ content extracted |
+| Agent → WeChat | ✅ | ✅ persona TTS | ✅ CDN upload | — |
+
+- **Voice replies:** Uses the persona engine's emotional TTS (Qwen3-TTS + emotional guidance), auto-encoded to SILK format
+- **Photo replies:** Gemini Imagen → adapter serves locally → bridge downloads and CDN-uploads → WeChat image message
+
 ---
 
 ## 🎨 Create Your Own Character

run.sh

@@ -12,8 +12,27 @@ cd "$(dirname "$0")"
 PORT=${PORT:-8000}
 LOG_FILE=".data/server.log"
 
-# Activate venv
+# Activate venv (with path validation)
 if [ -d ".venv" ]; then
+    # Check if venv python shebang points to a valid interpreter
+    VENV_PYTHON=".venv/bin/python"
+    if [ -f "$VENV_PYTHON" ]; then
+        SHEBANG_PATH=$(head -1 "$VENV_PYTHON" | sed 's/^#!//')
+        if [ ! -x "$SHEBANG_PATH" ]; then
+            echo "⚠️  虚拟环境路径已失效（项目被移动过？）"
+            echo "   尝试修复..."
+            if python3 -m venv --upgrade .venv 2>/dev/null; then
+                echo "✅ 虚拟环境已修复 (upgrade)"
+            else
+                echo "♻️  修复失败，正在重建虚拟环境..."
+                rm -rf .venv
+                python3 -m venv .venv
+                source .venv/bin/activate
+                pip install -r requirements.txt -q
+                echo "✅ 虚拟环境已重建"
+            fi
+        fi
+    fi
     source .venv/bin/activate
 fi
 

setup.sh

@@ -10,18 +10,36 @@ echo "║   OpenHer — 环境安装                 ║"
 echo "╚══════════════════════════════════════╝"
 echo ""
 
-# 1. Python version check
+# 1. Python version check (auto-detect Homebrew versions)
 PYTHON=${PYTHON:-python3}
 PY_VERSION=$($PYTHON --version 2>&1 | grep -oE '[0-9]+\.[0-9]+')
 PY_MAJOR=$(echo "$PY_VERSION" | cut -d. -f1)
 PY_MINOR=$(echo "$PY_VERSION" | cut -d. -f2)
 
 if [ "$PY_MAJOR" -lt 3 ] || ([ "$PY_MAJOR" -eq 3 ] && [ "$PY_MINOR" -lt 11 ]); then
-    echo "❌ 需要 Python 3.11+，当前版本: $PY_VERSION"
-    echo "   brew install python@3.13  (macOS)"
-    exit 1
+    echo "⚠️  默认 Python 版本太低: $PY_VERSION（需要 3.11+）"
+    echo "   正在搜索更高版本..."
+    FOUND=0
+    for V in python3.13 python3.12 python3.11; do
+        if command -v "$V" &>/dev/null; then
+            PYTHON="$V"
+            PY_VERSION=$($PYTHON --version 2>&1 | grep -oE '[0-9]+\.[0-9]+')
+            echo "✅ 找到 $V ($PY_VERSION)"
+            FOUND=1
+            break
+        fi
+    done
+    if [ "$FOUND" -eq 0 ]; then
+        echo ""
+        echo "❌ 未找到 Python 3.11+，请先安装："
+        echo ""
+        echo "   brew install python@3.13"
+        echo ""
+        echo "   安装后重新运行 bash setup.sh"
+        exit 1
+    fi
 fi
-echo "✅ Python $PY_VERSION"
+echo "✅ Python $PY_VERSION ($PYTHON)"
 
 # 2. Virtual environment
 if [ ! -d ".venv" ]; then