Companion Space
简体中文 | English
Companion Space 是一款本地优先的二次元陪伴学习应用。你可以为不同主题创建独立空间，导入自己的资料，与虚拟角色进行文字或实时语音交流，并在会话后整理复盘、记忆和复习内容。
项目默认运行在你自己的电脑上。资料和凭据保存在本地；如果接入 OpenAI 兼容服务、Ollama 等外部 Provider，相关请求会按照你的配置发送给对应服务。
核心能力
- 独立学习空间：按课程、项目或兴趣组织资料、角色和对话记录。
- 资料问答与引用：导入资料后进行检索增强对话，并保留答案引用。
- 文字与实时语音：支持连续对话、语音播放和插话打断。
- 虚拟角色演出：支持浏览器本地 VRM 3D 角色，以及 2D 备用形象、口型、情绪、目光和动作反馈。
- 可替换的 AI 服务：内置 Mock 便于直接体验，也可接入 OpenAI 兼容接口、Ollama 等 Provider；长期记忆需要用户确认后才会写入。
当前版本范围
当前最完整的使用路径是桌面浏览器配合本机 Docker 和 Mock 或自备 Provider。Android 与 iOS 客户端目前是连接同一服务的测试壳，需要受信任的 HTTPS 和设备配对，尚未作为商店成品发布。本项目暂不包含 WebRTC、MuseTalk、LivePortrait 或真人 talking-head 视频能力。
源码采用 Apache License 2.0。角色模型、动作、语音权重和示例素材可能适用各自的许可要求，详见 NOTICE 和 第三方素材说明。
快速开始
需要 Docker Desktop（或兼容的 Docker Engine）和 Docker Compose v2。先 不要 打开 neural-tts profile。
git clone https://github.com/Johnson-Durui/Companion-Space.git
cd Companion-Space
cp .env.example .env
docker compose up --build
首次启动后：
- 打开
https://companion.localhost
- 按浏览器提示信任 Caddy 本地 CA（
tls internal，不是 公网 Let's Encrypt）
- 先走 Mock：Vault → 空间 → 资料 → 角色 → 共学
健康检查：Caddy 起来后访问 https://companion.localhost/healthz。api 与 web 容器带 healthcheck；Caddy 会等它们 healthy。
可选神经语音（NVIDIA GPU，首次约 2.5 GB 权重）只有在你明确打开 profile 后才会构建：
COMPOSE_PROFILES=neural-tts
BUILTIN_NEURAL_TTS_ENABLED=true
不要把真实的 .env、storage/、infra/caddy/data、私钥、token 或数据库提交进 git。
Windows
仓库根目录有 START-WINDOWS.ps1：适合把 WSL/Docker 内存帽打到 14 GB 的 16 GB 主机。别的机器可以：
Copy-Item .env.example .env
docker compose up --build
或 .\START-WINDOWS.ps1 -SkipWslMemoryCheck。Docker 没开时用 .\START-LOCAL-WINDOWS.ps1，浏览器打开 http://127.0.0.1:3000。备份只用仓库内脚本，默认写到 backups/（已 gitignore）：
.\BACKUP-WINDOWS.ps1
不要在 API 运行时直接复制 companion.db、WAL/SHM 或整个 storage/。更换 API 镜像前先跑备份。
本地开发（不用 Docker）见 WINDOWS-README.md。本仓库是 npm workspace，用 npm.cmd / npm，不要用 pnpm。
项目结构
.
├── apps/web/ Next.js UI（VRM / 2D、会话、设置）
├── apps/mobile/ Capacitor Android/iOS 壳与安全配对 launcher
├── services/api/ FastAPI
├── services/tts/ 可选 Qwen3-TTS sidecar
├── infra/caddy/ 唯一 HTTPS 入口（当前 Caddyfile 对所有 APP_HOST 使用 tls internal）
├── docker-compose.yml
├── .env.example
├── LICENSE
├── NOTICE
└── assets/THIRD_PARTY_NOTICES.md
Web 默认用同源相对地址构建：
NEXT_PUBLIC_API_BASE_URL=/
NEXT_PUBLIC_REALTIME_WS_URL=/api/v1/sessions/:sessionId/realtime
这样手机用 IP、电脑用 companion.localhost，只要反代同源，都不需要为每个主机名重编一套前端。改了这些构建期变量必须重建 web 镜像，只重启容器不够。
移动端（可选）
手机不能用 companion.localhost。需要给宿主机一个手机能访问、系统信任的 HTTPS origin，再把同一个 origin 编进壳：
$env:COMPANION_MOBILE_TRUSTED_ORIGINS='https://companion.example.com'
npm run check:mobile
npm run typecheck:mobile
npm run build:mobile
npm run cap:sync --workspace @companion-space/mobile
在电脑浏览器解锁 Vault，打开 设置 → 移动设备 生成 8 位码，5 分钟内在手机输入。刷新凭据只进 Android Keystore / iOS Keychain；access token 不进 URL、localStorage 或日志。详见 docs/lan-pairing.md 和 apps/mobile/README.md。
Windows 上打 Android 调试包
需要 JDK 21、Android SDK 36、Build Tools 36.0.0。装好后把 SDK 路径写进本机 apps/mobile/android/local.properties（已 gitignore，不要提交）：
sdk.dir=C:\\Users\\<you>\\AppData\\Local\\Android\\Sdk
用占位 origin 只验收能否出包；真机配对必须换成手机能访问、系统信任的 HTTPS origin，并重新 build:mobile + cap:sync。不要把含真实 Tailscale / 局域网 IP 的 apps/mobile/dist 提交进 git。
$env:COMPANION_MOBILE_TRUSTED_ORIGINS='https://companion.example.com'
npm.cmd run build:mobile
npm.cmd run cap:sync --workspace @companion-space/mobile
cd apps\mobile\android
.\gradlew.bat :app:assembleDebug
调试 APK：apps/mobile/android/app/build/outputs/apk/debug/app-debug.apk（debug 签名即可）。这只证明工程能编过，不等于已在真机配对成功，也没有上架。iPhone 编译仍需 macOS / Xcode。
当前 infra/caddy/Caddyfile 对 所有 APP_HOST 使用 tls internal。换成公网域名 不会 自动拿到公开 ACME 证书；那是以后改 Caddyfile 之后的事。
角色与许可（请读）
| 产品角色 |
当前 3D |
许可摘要 |
| 澄羽 MIRA |
Mira.vrm 原创定制 |
嵌入 VRM 权限：个人商业可用；企业商业未授权 |
| 曜柚 KITE |
Kite.vrm 原创定制 |
嵌入 VRM 权限：个人商业可用；企业商业未授权 |
| 凛序 CAEL |
Cael.vrm 原创定制 |
嵌入 VRM 权限：个人商业可用；企业商业未授权 |
| 弦灯 LYRA |
Lyra.vrm 原创定制 |
嵌入 VRM 权限：个人商业可用；企业商业未授权 |
卡面插画与四主角 3D 均为本项目原创。Sendagaya Shino / Seed-san / Sakurada Fumiriya / Constraint Twist 仍作为许可样本保留。Mori / Yuzu 的 2D atlas 是本项目资源。不要从 CyberVerse（GPL-3.0）拷代码进来。
四个原创 VRM 允许再分发和修改且无需署名，但其内嵌权限不授权企业商业使用，并禁止过度暴力/性、政治/宗教、反社会或仇恨用途；不得剥离内嵌元数据。完整字段见模型 manifest.json 与 第三方/素材声明。
仓库发布的是经过校验的四个 VRM 二进制与哈希；精确的 painted albedo 输入和本地 .blend 工作文件不在公开仓库。干净 clone 可以直接运行这些模型，但不承诺从公开源逐字节重建相同哈希。详见 原创 3D 契约。
验证命令
从仓库根目录：
npm run typecheck:web
npm run lint:web
npm run check:mobile
npm run typecheck:mobile
npm run test:original-vrm
npm run test:runtime-config
npm run test:pet-assets
API（需要本机 Python 依赖）：
python3 -m ruff check services/api
PYTHONPATH=services/api python3 -m pytest services/api/tests -q
不要并发跑两个 Next production build，也不要在正在跑的 next start 旁边覆盖 .next。
文档
Companion Space 是一个本地优先的动漫风格陪伴与学习应用：你按主题创建独立空间，导入自己的学习资料，然后通过文字或实时语音与一个 VRM 3D 角色聊天，帮助你复习和记住所学内容。