双栖

双栖是两个人、两台 Android 手机共用的私密关系空间。正式客户端使用 Capacitor；PWA 只用于调试和应急访问。

AI 以“AI 分身 · 姓名”出现：使用伴侣本人发布的表达画像提供情感陪伴，可以读取共享记录；任何写入都由服务端创建短期确认动作，确认后才会执行。

开发

项目使用 Node 22：

nvm use
npm run setup
npm run dev

npm run setup 按两份 lockfile 安装前端与 server/ 的独立依赖。首次克隆、 切换 Node 版本或 lockfile 更新后都应重新执行。

Vite 默认运行在 http://127.0.0.1:3015/，并把 /api 代理到 http://127.0.0.1:3000。也可用 VITE_DEV_API_ORIGIN 指定本地后端。

需要界面验收数据时，使用 ?seed=1 显式注入一次；附加 &onboard=1 可停留在连接流程。测试数据只在开发构建生效，并会拒绝写入已连接云端的小屋。

完整检查：

npm run verify

verify 依次执行 typecheck、node --test 单元测试、服务端测试、check:hooks（静态扫描 useEffect/useCallback/useMemo 的 deps 是否引用了在 hook 之后声明的 const/let/var，防止运行时 TDZ 白屏）、生产构建。

服务端

服务端源码在 server/。复制 server/.env.example 为部署机器上的 .env，并从环境变量提供配对密钥、AES-256-GCM 数据密钥和轮换后的模型 Key。任何密钥、数据库、媒体和备份都不能提交到 Git。

/api/v2 的边界：

• 设备令牌只保存哈希；houseId/memberId/identity 一律由令牌推导。
• 关系实体使用 baseVersion 乐观锁、墓碑和 cursor 增量同步。
• 画像原文、私有对话、长期记忆、纠正覆盖与媒体均加密保存。
• 每个人只维护自己的原话；另一半只能读取已发布的画像快照。
• AI Key、上游地址和模型白名单只存在服务端。

迁移期间只打开 ENABLE_LEGACY_V1=true。两台设备完成 code 8 覆盖安装并核对数据后，将所有 ENABLE_LEGACY_* 设置为 false。

Android 发布

签名证书默认位于 ~/.config/shuangqi/signing/android.keystore，密码从 macOS Keychain 的 shuangqi-android-signing/android 读取。Gradle 只接收临时环境变量，不读取仓库内密码。

VITE_API_ORIGIN=https://你的固定域名 npm run android:release

VITE_API_ORIGIN 必须是固定 HTTPS 域名；localhost、IP 地址和 Quick Tunnel 都会被拒绝。产物为 releases/shuangqi-0.8.0-code8.apk，脚本依次执行 Web 构建、Capacitor sync、Gradle release 和 APK 签名校验。

本地数据

业务实体、outbox、会话、记忆、画像与媒体缓存存入 IndexedDB。首次启动会把旧 localStorage 三套数据一次性导入，并保留迁移备份；导出的备份不包含设备令牌或模型 Key。