digital-me-history/digital-me-backend/CLAUDE.md

digital-me-backend — Claude Instructions

Service

数字我 / Digital Me — 主场是 大师数字传承馆 + 线上版权变现：平台签约各领域名家(大师)， 免费为其建【知识库】与【作品墙】，并享有其线上数字化变现版权 —— 知识付费问答、作品周边 (手办/签名作品克隆版)、作品库授权给机构、数字人带货、付费咨询/会员。知识最重要；形象/ 声音次要(照片+预置音即可，无需视频)。个人分身是次级工具(个人在「我的分身」自建，可定向分享)， 不再是平台主打的社交产品。

分身已具备「帮你办事」能力(联网查、记事、待办提醒、工作流定时跑，见 capabilities.js 的 assist 分类) —— 早期文档"NOT 帮你做事的隐形助理""NOT knowledge-work tool"的表述已作废。

国内版数据不出域是红线：LLM 用 DashScope/Qwen；Claude/HeyGen/Resend/Stripe/Azure 等 海外出站由 config 开关门控(overseasFallback / overseasEgress)，默认建站期临时开、进生产前关。

Lineage

The multimodal pipeline is lifted from the proven super-individual-app platform (whose artist vertical is "The Digital Atelier"). Digital Me 现在就是围绕 大师传承馆(master gallery)+ 作品/授权变现构建 —— 早期"no master-gallery/license code" 的说明已不适用(masters/works/agreements/tours 等业务域均已落地)。

Stack

• Node 20 + Express (ES modules — "type": "module")
• MongoDB (own DB digital_me — never share another product's DB)
• LLM: Qwen via DashScope (OpenAI-compatible) primary; Claude Haiku fallback
• Embeddings: DashScope text-embedding-v3 for knowledge RAG
• Avatar 捏脸: 通义万相 wanx-style-repaint (services/media.js)
• Voice clone + TTS: DashScope CosyVoice v2 (services/media.js + ttsWs.js)
• 口播视频: 通义 EMO audio-driven talking head (services/talkingVideo.js)

Conventions

• Routes thin; logic in services/.
• All secrets via .env (see .env.example); never hardcode.
• Per-owner isolation: every /api/twins/:id route ownership-checks via loadTwin (ownerId match). The public /api/embed/:slug router is the ONLY no-auth surface — it reads published twins only and never persists.
• Everything degrades gracefully without AI keys (chat → 502 only if no LLM at all; avatar → flat photo; voice → voice-not-cloned). Keep it usable.
• Rate limit: 120 req/min global.

Two runtime constraints

1. AI features need DASHSCOPE_API_KEY (.env).
2. 捏脸 / 口播视频 need PUBLIC_URL to be publicly reachable — DashScope pulls the photo/audio by URL, so a localhost PUBLIC_URL makes those two features fail (chat + voice still work). Use a tunnel in dev.