Petdesk

把你自家的猫或狗，变成一只明显像它的数字宠物。

上传照片 → 得到一只保留原图毛色与脸的数字宠物 → 拖它、摸它、把它甩出屏幕再召回。

这是根据你提供的照片和描述创建的数字伙伴，不是真实宠物的意识复制。

---

文档

文档	用途
doc/PROGRESS.md	当前进展、阻塞项与下一步
doc/MVP_SPEC.md	当前实施依据。收敛后的 MVP 工程合同
doc/PRD.md	完整产品需求（含 MVP 之后的范围）
doc/TECHNICAL_SPEC.md	完整技术规格（含 MVP 之后的范围）
doc/ADR/	架构决策记录
doc/DESIGN_SYSTEM.md	UI/UX 设计系统（Neo-Brutalism × 三语）
doc/ANIMATION_CONTRACT.md	Blender Action 命名与缺口清单
doc/uplaod_generate.md	Template 3D 生成管线设计（digital_service/）

MVP 聚焦一件事：让用户觉得「这就是我家那只」。对话、语音、记忆、主动提醒、设备连接均已明确延后，范围差异见 MVP_SPEC §0.1。

数字宠物走双轨生成（ADR-0002）： 1 张照片即可得到 Photo Puppet（2.5D 原图抠像，发布依赖）；补齐多视角可解锁 Template 3D（SMAL 骨骼 + 纹理投影，资产在 digital_service/）；3D 质检不过自动降级回 2.5D。

---

本地开发

需要 Node ≥ 20 与 pnpm 9。不需要 Docker、不需要 PostgreSQL、不需要任何 API 密钥。

pnpm install
pnpm dev

数据库默认使用 PGlite（嵌入式 PostgreSQL），队列走进程内实现，对象存储走本地文件系统，AI provider 全部有 mock 实现。理由见 ADR-0001。

想用真实服务时，设置 DATABASE_URL / REDIS_URL / STORAGE_DRIVER=s3 即可切换，schema 与业务代码不变。

快速演示

./demo.sh

启动后打开 http://localhost:3000/login，点黄色的「直接体验」按钮即可跳过注册， 直接进入创建流程。

⚠️ 演示模式（AUTH_DEMO_MODE=true）会跳过登录，只用于本地演示。 生产环境设置这个变量会让 API 拒绝启动——宁可启动失败， 也不能悄悄带着认证旁路上线。

常用命令

pnpm typecheck    # 类型检查
pnpm lint         # ESLint
pnpm test         # 单元与集成测试
pnpm test:e2e     # Playwright
pnpm format       # Prettier

---

仓库结构

apps/
  web/        React + Vite + React Three Fiber，创建流与互动房间
  api/        Fastify + Zod + Drizzle
  worker/     媒体处理、抠图、Motion Profile 等异步任务
packages/
  domain/           领域类型与 Zod schema（无 React / 无 DB / 无供应商 SDK）
  api-client/       typed client，不依赖 window
  pet-runtime/      XState 行为状态机（无网络 / 无 UI）
  pet-renderer/     只消费 PetAvatarManifest
  ai-providers/     LLM / VLM / 抠图 provider 抽象与实现
  ui/ config/ test-fixtures/
infrastructure/     docker-compose 与数据库迁移

依赖规则见 MVP_SPEC §2.3。要点：客户端永不直接调用 AI/存储供应商，密钥只存在于 worker 环境变量。

---

AI Provider

LLM 与视觉能力开源/免费优先，通过 OpenAI 兼容接口在 硅基流动 与 OpenRouter 之间切换，模型名全部走配置不硬编码。

抠图默认使用本地开源模型，不依赖任何在线服务。

硬要求：LLM 全部不可用时，创建流程仍能跑通且结果仍然「很像」。AI 是增强层，不是阻塞项。详见 MVP_SPEC §5。

---

测试素材

example_artifacts/ 中的宠物照片与视频是个人素材，默认不入库（见 .gitignore）。本仓库为公开仓库，git 历史不可撤销，请在提交任何真实宠物素材前确认这是你想要的。

自动化测试使用 packages/test-fixtures 中的合成素材。测试素材不得使用用户生产数据。

---

安全

• .env 与任何密钥永不入库。
• 兑换码只存哈希；生码 CLI 的明文只写入本地 CSV（已在 .gitignore 中）。
• 日志不包含原始媒体、token 或完整兑换码。