适用分支：electron（Electron 34 壳，无需安装 Rust 工具链）
源码仓库：https://github.com/Sogrey/ai-girlfriend
本机部署目录：D:\桌面女友 整理日期：2026-10-23
一个长期驻留在 Windows 桌面上的实时 3D AI 虚拟伴侣：透明无边框窗口中的 VRM 角色，能跟随鼠标视线、听语音说话、开口回应并同步口型、做动作、表达情绪、换装、离开休息与召回。
一、技术栈
二、环境要求
2.1 安装后自检命令
2.2 注意事项
本指南基于 electron 分支，壳层是 Electron，不需要 Rust 工具链；仓库 main 分支为 Tauri 2 壳，才需要 Rust ≥ 1.80。
没有 NVIDIA GPU 也能运行：Whisper 会自动回退 CPU int8 模式，仅语音识别速度慢一些。
安装 Python 时务必勾选 Add Python to PATH；安装 Node.js 保持默认 Add to PATH。
国内网络已在项目内配好镜像：npm → npmmirror，pip → 清华源，Whisper 模型 → hf-mirror.com。
三、下载清单（官方链接，全部写明）
四、部署步骤
前置条件：已装好 Node.js、Python 并加入系统 PATH；源码已解压到 D:\桌面女友。以下命令均在 PowerShell 中、项目根目录 D:\桌面女友 执行。
4.1 获取源码（若尚未解压）
# 方式 A：浏览器下载 ZIP 后解压到 D:\桌面女友# ZIP 直链：https://github.com/Sogrey/ai-girlfriend/archive/refs/heads/electron.zip
# 方式 B：Git 命令（需先安装 Git）
git clone -b electron https://github.com/Sogrey/ai-girlfriend.git D:\桌面女友
4.2 安装 Node 依赖
cd D:\桌面女友# 项目 .npmrc 已配置 npmmirror 与 Electron 镜像，无需手动切换
npm install
4.3 创建 Python 虚拟环境
python -m venv .venv4.4 升级 pip（清华镜像）
.venv\Scripts\python.exe -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple4.5 安装后端依赖（清华镜像）
.venv\Scripts\python.exe -m pip install -r backend\requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4.6 启动应用
# 一键启动（推荐）：双击 scripts\启动AI女友.bat# 手动分步（调试用）
# 终端 1：启动后端
.venv\Scripts\python.exe backend\main.py
# 终端 2：启动前端
npx electron .
一键脚本会自动完成：检查 .venv 与 node_modules → 后台拉起后端（端口 8765）→ 等待后端就绪（最多 40 秒）→ 启动 Electron 显示 3D 角色；退出时自动清理后端进程。
首次使用语音识别会下载 Whisper small 模型（约 460MB，经 hf-mirror 约 5 分钟），之后缓存秒载。
五、首次配置
5.1 必做：填写 DeepSeek API Key
启动后角色会出现在桌面上，但 AI 对话需要先填 Key：
鼠标移近角色 → 底部工具栏淡入；
点击 ⚙️ 设置；
AI 大模型 → 填写 DeepSeek API Key；
保存。
Key 在 https://platform.deepseek.com 免费注册后于控制台创建。
未填 Key 时，3D 渲染、眼神追踪、换装、离开 / 返回、托盘快捷键全部正常，只有 AI 对话会返回 "请填写 API Key" 的提示。
5.2 可选配置
屏幕感知（智谱免费视觉）：设置 → 视觉模型 → 填 API Key（https://bigmodel.cn 注册，GLM-4V-Flash 免费）。点工具栏 👁 立即截屏发问，或直接说 "看看我屏幕上是什么"，她会自动截屏结合画面回答。截图只发给所选视觉接口，不落盘存储。
本地大模型 Ollama：设置面板 → Provider 改为 Ollama，填写地址与模型名。先安装 https://ollama.com ，执行 ollama pull qwen3:4b、ollama serve。6GB 显存建议 4B 级别；24GB 显存可跑 27B+。
本地语音 GPT-SoVITS（免 Key 全离线）：设置 → 语音合成 → 服务选 GPT-SoVITS 本地。默认参考音频在 assets/voices/ref_default.wav；可录 5~10 秒中文女声 wav 替换并填写对应逐字文案。
换装模型：从 https://hub.vroid.com 下载 VRM 文件放入 assets/costumes/，命名规则见下表；未放置文件的槽位自动使用材质配色变体。
修改人格：角色名 / 你的称呼在设置面板 → 女友；性格 Prompt 编辑 prompts/system_prompt.txt。
六、目录结构
ai-girlfriend/├─ scripts/
│ ├─ 启动AI女友.bat ← 一键启动脚本
│ ├─ 首次安装.bat
│ └─ 启动GPT-SoVITS.bat
├─ electron/
│ ├─ main.js ← 主进程（窗口/托盘/快捷键/协议）
│ └─ preload.js ← 安全 API 桥
├─ renderer/ ← Three.js 场景 / 角色 / 动画 / 表情 / 口型 / 交互 / 工具栏
├─ backend/
│ ├─ main.py ← 后端入口
│ ├─ core/ ← WebSocket 服务 / 配置 / 日程提醒引擎
│ ├─ llm/ ← DeepSeek + Ollama 双 Provider
│ ├─ stt/ ← Faster-Whisper 引擎
│ ├─ tts/ ← 五家语音 Provider
│ ├─ conversation/ ← 统一对话管道
│ ├─ actions/ ← 意图校验 + 动作定义
│ └─ vision/ ← 屏幕感知
├─ heart/
│ └─ heart.html ← 爱心挂件窗口
├─ assets/
│ ├─ models/ ← 默认 VRM 模型
│ ├─ costumes/ ← 5 套服装 VRM（按需放入）
│ └─ icons/ ← 托盘图标
├─ config/
│ ├─ config.json ← 默认配置（版本管理）
│ └─ user.json ← 用户覆盖（设置面板写入，git 忽略）
├─ prompts/
│ └─ system_prompt.txt ← 人格 System Prompt
├─ docs/ ← PRD、开发计划、测试用例等文档
└─ package.json
七、配置说明
所有配置集中在 config/config.json（默认值）与 config/user.json（设置面板自动写入）。关键字段如下：
默认配置片段（节选自 config/config.json）：
{ "llm": {
"provider": "deepseek",
"deepseek": { "api_key": "", "base_url": "https://api.deepseek.com", "model": "deepseek-flash" },
"ollama": { "base_url": "http://127.0.0.1:11434", "model": "qwen3:4b" }
},
"stt": { "model": "small", "language": "zh", "device": "auto", "compute_type": "auto", "vad_enabled": true },
"tts": { "provider": "edge", "edge": { "voice": "zh-CN-XiaoxiaoNeural" } },
"vision": { "base_url": "https://open.bigmodel.cn/api/paas/v4", "api_key": "", "model": "glm-4v-flash" },
"server": { "port": 8765 },
"hotkey": "Control+Alt+G"
}
八、操作指南
九、常见问题
Q1：启动后角色没出现？
角色会在模型与纹理全部加载完成后才显示（首次约 3~5 秒）。若超过 15 秒仍未出现：按 Ctrl+Alt+G 尝试唤醒；检查后端是否启动成功（BAT 窗口是否显示 "后端已就绪"）；按 Ctrl+Shift+I 打开开发者工具查看 console 报错。
Q2：AI 对话报 "API Key 未设置"？
这是唯一必做配置。进入 设置 → AI 大模型 → 填写 DeepSeek API Key → 保存；Key 在 https://platform.deepseek.com 免费注册获取。
Q3：语音识别没反应？
首次启动需下载 Whisper small 模型（约 460MB，经 hf-mirror 约 5 分钟），之后缓存秒载；确认麦克风已连接且浏览器有权限；检查设置面板中 Whisper 模型与语言是否正确。
Q4：没有 GPU / CUDA 报错？
Whisper 会自动回退 CPU int8 模式。如需强制指定，编辑 config/config.json：
"stt": { "device": "cpu", "compute_type": "int8" }Q5：想用本地模型离线跑？
设置面板 → Provider 改为 Ollama；先安装 Ollama 并拉取模型：
ollama pull qwen3:4bollama serve
本地模型质量取决于模型大小与显存：6GB 显存建议 4B 级别，24GB 可跑 27B+。
Q6：npm install 很慢或失败？
项目已配 .npmrc 使用 npmmirror 国内镜像。如仍失败，手动切换：
npm config set registry https://registry.npmmirror.comQ7：点爱心召回后角色要等一下才出现？
正常行为：窗口隐藏期间显卡会回收角色纹理，召回时先静默等待约 0.7 秒，待纹理重新就绪后再以完整形象淡入，避免出现半透明、无面部纹理的异常画面。
Q8：功能栏怎么唤出？
鼠标移近角色身体（悬停腿部 / 头部都算），或直接把鼠标移到角色右侧贴身的功能栏区域（隐藏状态下也可唤出）。鼠标在功能栏和各面板上停留时不会消失，移开约 0.3 秒后自动淡出。
Q9：角色太占屏幕 / 想调整位置？
角色默认脚底站在 Windows 任务栏上沿；按住身体拖动可移动位置，重启后自动恢复上次摆放位置，托盘右键也可 "位置复位"；重启后聊天记录自动回填。说 "去休息吧" 让她离开变成爱心，Ctrl+Alt+G 随时召唤 / 隐藏。
十、打包免安装目录版（可选）
npm installnpm run dist
# 产物：dist\win-unpacked\AI-Girlfriend.exe
产物为免安装目录版：dist\win-unpacked\ 整个文件夹拷走即可，双击 AI-Girlfriend.exe，桌宠窗口 + 托盘 + 快捷键与开发版一致。
语音 / 对话后端仍走本机 Python 环境（首次安装所装的 .venv）；用户密钥 config/user.json 与聊天记录不会打进包。
十一、本机实测记录（D:\桌面女友，2026-10-23）
剩余待办：
设置面板填写 DeepSeek API Key；
双击 scripts\启动AI女友.bat 启动；
首次语音对话自动下载 Whisper small 模型（约 460MB）。
附：许可与说明
源码许可：MIT（见仓库 LICENSE）；项目标注 Private / Personal Use、AI 生成。
本指南依据 electron 分支 README v1.0.0 与本机实际安装结果整理；如后续 main 分支（Tauri 2）启用，需另行安装 Rust ≥ 1.80 工具链。