📖 AI Companion 使用帮助手册

这是一个「会聊天、有人格、记得住你、还能语音应答」的本地 AI 伴侣系统。 大脑（LLM/Agent）+ 记忆（PG+pgvector）+ 嘴（TTS）都在你本地机器上跑， 数据不出内网。

目录快速开始聊天人格记忆语音(V2)API手机测试运维FAQ

一、快速开始

访问入口

  • 浏览器打开 https://aib.it865.com（外网入口，经 Nginx，Let's Encrypt 证书； 前端同源反代到后端，HTTPS 安全上下文下麦克风可直接使用）。
  • 内网备选：http://192.168.5.135:8080（非安全上下文，麦克风被浏览器禁用）。
  • 首页是登录页（设备身份注册），点「登录进入」进 /chat（聊天页）。
  • 健康检查：GET /api/health（数据库/Redis/Ollama/ASR 各项状态）。

身份（user_id）

系统用浏览器 localStorage 里的一个 UUID 作为「你是谁」， 首次访问自动生成并幂等注册到后端。换浏览器/清缓存 = 新用户； 同一浏览器记住你的对话与记忆。

用户 (UUID)对话人格长期记忆
示意图：每个 UUID 用户拥有自己的对话列表、可关联多个人格、有独立的长期记忆。

二、聊天（💬 聊天 标签）

聊天页（含真实对话）
真图 · 聊天页：选了人格「Alice」，发了"你好，简单介绍一下你自己"，AI 真的回了一段自我介绍实拍

在 /chat 页顶部 选择人格（下拉），然后在输入框打字 + 发送：

  • 消息会带上「该人格 + 相关长期记忆」一起交给大模型，回复更贴合人设。
  • 左侧是历史对话列表，可点开旧对话；「新建对话」开一个全新的。
  • 回复完成后，系统会自动在后台提取长期记忆（偏好/事实/事件）。
我今天有点累
累了就歇一会儿呀，我陪你。要不要聊聊今天发生了什么？
示意图：聊天页 = 人格下拉 + 消息气泡 + 输入区。回复时显示「发送中…」。

三、人格（👤 人格设置 标签）

人格管理页（真实人格卡片）
真图 · 人格管理：服务器上已建了多个人格卡片，每张可"编辑 / 删除"实拍

人格 = 大模型的「人设」，包括名字、性格、说话方式、背景、喜恶、相处模式。

  1. 点「+ 创建新人格」→ 填表单 → 创建。
  2. 已有人格卡片上可「编辑 / 删除」。
  3. 回到聊天页在顶部下拉里选它即可。

小雅

温柔、会倾听，喜欢深夜陪你聊天。

示意图：人格卡片列表；新建/编辑是表单（姓名* / 性格 / 说话方式 / 背景 / 喜好 / 厌恶 / 相处模式）。

四、记忆（🧠 记忆管理 标签）

长期记忆页（真实记忆条目）
真图 · 长期记忆：服务器上有 5 条真实记忆（💝偏好 / 📌事实 / 📅事件），带重要度与日期实拍

系统把聊天中的重要信息自动存成「长期记忆」，分三类，可用下拉按人格查看：

  • 💝 偏好（preference）／ 📌 事实（fact）／ 📅 事件（event）。
  • 每条带「重要度」与日期；可手动删除。
  • 记忆用向量（pgvector）语义检索，聊天时自动召回相关条目。
💝 偏好 · 重要度 82% · 09-08

用户偏好安静一点的对话节奏，喜欢被主动关心但不喜欢长篇大论。

示意图：记忆列表（按 persona 过滤），可逐条删除。

五、语音（V2：录音 → 转写 → 应答 → 配音）

⚠️ 当前服务器跑的是 V1 版本（GET /api/health 无 asr 项、无语音端点）， 聊天页暂不显示语音工具条。等 docker compose 重新部署 V2（api + tts-worker + 前端）后， 下方这条链路才会生效。下面为功能说明与界面示意。

部署 V2 后，聊天页下方会出现一条「语音工具条」（仅当后端 ASR 可用时显示）：

  1. 🎙 录音：点「录音」开始，再点「停止」自动发送；或 📁 直接上传音频文件（mp3/wav/ogg）。
  2. 音频 → 本地 ASR（faster-whisper） 转成文字（消息气泡上显示「🎙 已转写」标签）。
  3. 转写文本 + 人格/记忆 → 大模型生成回复。
  4. 回复文本进 TTS 队列，worker 合成语音（Piper/Coqui），你轮询到完成后自动播放（「⏳ 语音生成中…」→ 播放器）。
录音或上传音频，AI 会语音回复
好呀，那我慢慢说，你听着就好。
示意图：语音工具条 + 语音回复播放器。麦克风需 HTTPS 或 localhost：外网入口 https://aib.it865.com 可直接录音；内网 http://192.168.5.135:8080 会降级为「只能上传文件」。

降级式 若没装 whisper/Piper，整条链路仍能跑通： ASR 不可用会显示「🎙 ASR 不可用」，TTS 引擎为 noop 时显示 「TTS 引擎未合成音频」，聊天文字不受影响。

五·五、手机测试（登录页下载 App / PWA / 安卓 APK）

在手机上测试本系统有三种方式：外网 HTTPS 入口 https://aib.it865.com（推荐， 手机任意网络可用，麦克风可录）、内网 http://192.168.5.135:8080（PWA）、 安卓 APK 侧载。打开首页（登录页 /）就能看到「⬇ 下载安卓 App」按钮，直链下载/download/AICompanion.apk（Nginx 托管）。

方式 A：移动 WebApp / PWA（最简单，推荐先试）

  1. 外网入口（推荐）：手机任意网络，浏览器直接打开 https://aib.it865.com。 内网入口：手机与服务器 192.168.5.135 连同一个局域网， 打开 http://192.168.5.135:8080。
  2. Android：Chrome 菜单 →「添加到主屏幕 / 安装应用」；iPhone：Safari 底部分享 →「添加到主屏幕」。 之后图标即像 App 一样全屏打开（PWA 独立窗口、带图标）。
  3. 进去选人格 → 聊天；需要语音就点「📁 上传音频」（见下方麦克风说明）。

麦克风录音限制：浏览器只在安全上下文（HTTPS 或 localhost）允许麦克风。 走外网入口 https://aib.it865.com（Let's Encrypt 公共证书）即为安全上下文，录音可直接使用； 走内网 http://192.168.5.135:8080 是非安全上下文，录音按钮会被禁用， 但「📁 上传音频文件」（mp3/wav/ogg）始终可用。

身份：手机和电脑是不同浏览器 = 不同 user_id，各自有独立的历史对话与记忆（同一台手机内保持一致）。

方式 B：安卓 APK 侧载（原生壳，体验最像 App）

  1. 手机浏览器打开首页（登录页 /），点「⬇ 下载安卓 App」按钮，直链/download/AICompanion.apk（Nginx 托管，支持断点续传）。
  2. 或手动：构建产物在服务器 download/AICompanion.apk（Capacitor WebView 壳，内部加载 https://aib.it865.com）；也可 adb install 或文件传输到手机。
  3. 安装时勾选「允许安装未知应用」→ 打开即进入系统（登录页 → 进入聊天）。

APK 与 PWA 共用同一套前端与后端 API；APK 现加载 https://aib.it865.com（HTTPS 安全上下文）， 录音可直接使用，上传音频同样可用。

自动升级（V2.3 起）：App 每次启动会在后台检查 /download/app-update.json 版本清单， 发现新版本时弹窗「立即升级」→ 自动下载 + SHA-256 校验 + 调起系统安装器。 首次安装新版需在系统设置中允许「安装未知应用」（App 会引导跳转）；安装完成后重新打开 App 即可。

连不上 / 白屏怎么办

  • 外网入口打不开：确认 https://aib.it865.com 域名解析正常、443 放行； 服务器 /abcdata/AiCompanion 的 Nginx 容器在跑（docker ps | grep ai-companion-nginx）。
  • 内网入口打不开（手机和 135 不在同一网段）：确认能 ping 通 135，或手机连到能路由到 135 的 WiFi。
  • 内网端口 8080 被防火墙拦：服务器放行 8080（ufw allow 8080 等）。
  • 白屏 / 接口 404：确认 Nginx 在跑、/api/health 返回 200；PWA 缓存若旧，长按图标"重新加载"或清站点数据。

六、后端 API 速查

方法 路径作用
GET /api/health各服务状态（db/redis/ollama/asr/llm）
POST /api/users注册/幂等获取用户（可传 user_id）
GET /api/personas人格列表
POST/PUT/DELETE /api/personas/:id人格增改删
GET/POST /api/conversations?user_id=历史对话列表 / 新建对话
DELETE /api/conversations/:id删除某条对话
GET /api/messages/:conversationId取某对话的消息
POST /api/chat?user_id=文字聊天（Brain+Memory）
POST /api/voice/chat?user_id=语音聊天（ASR→Brain→TTS 入队）
GET /api/voice/status/{task_id}轮询 TTS 任务状态 / 取音频 URL
GET /voices/<id>.wavTTS 音频产物（Nginx 反代）
GET/DELETE /api/memories查看/删除长期记忆

七、运维命令（服务器端）

部署 / 重启

cd /abcdata/AiCompanion docker compose up -d            # 起全栈（含 tts-worker） docker compose logs -f api      # 跟踪 api 日志 docker compose build api tts-worker && docker compose up -d   # 改代码/依赖后重建

模型 / 音色（让语音"真实可用"）

./download_models.sh            # 预热 whisper + 下载 Piper 音色到 models/ TTS_ENGINE=piper docker compose up -d --build tts-worker   # 启用 Piper 引擎 # 想备份模型：BACKUP_MODELS=1 ./backup.sh

备份 / 恢复

./backup.sh                    # pg_dump + 关键文件（每日 03:00 cron） psql -U companion -d companion < backup/<最新.sql>   # 恢复数据库

开机兜底

./boot.sh    # 等 Docker 就绪 → compose up → 等 api 健康 → 预热模型（失败不阻断）

八、FAQ / 故障排查

  • 录音按钮没出现？ 说明后端 ASR 不可用。看 GET /api/health 的 asr 项； 需要容器里装好 faster-whisper + ffmpeg，并跑过 download_models.sh。
  • 能录音但没声音（麦克风被拒）？ getUserMedia 需安全上下文： 走外网 https://aib.it865.com（HTTPS）即可用麦克风；内网 http://192.168.5.135:8080非安全上下文，改用「上传音频文件」即可。
  • 语音一直「生成中」？ TTS 引擎是 noop（默认）→ 只跑通队列、不合成。 设 TTS_ENGINE=piper 重建 tts-worker 并下载音色后才有真声音。
  • 回复很慢？ 大模型是共享 Ollama（3B，塞进 4.8GB 显存），且 LLM 有并发限流防 OOM，属正常。
  • 看不到历史对话？ 对话按当前 persona 过滤，且属于「你这个浏览器」的 user_id；换浏览器会看不到。

需要实拍截图？

本手册的「示意图」按真实组件样式绘制。若要真·实拍：在https://aib.it865.com（或内网 192.168.5.135:8080）打开 /chat（各标签）与/help，用系统截图工具分别截「聊天 / 人格 / 记忆 / 语音工具条」， 再让我把对应 .mock 块替换为 <img> 即可。

返回 聊天页 →