孙子（grandson）

一个面向老年人陪伴场景的 AI 系统。当前仓库处于 MVP 第一阶段（后端基础能力），目标是先跑通“文字对话 + 会话记忆 + 持久化 + 异步任务骨架”。

当前阶段（与代码一致）

依据 PLAN.md 与现有代码，当前已落地到 Week 1：

• ✅ FastAPI 后端骨架（backend/app/main.py）
• ✅ 健康检查接口：GET /health
• ✅ 对话接口：POST /api/chat
• ✅ Redis 工作记忆（最近对话缓存、TTL）
• ✅ Redis 令牌桶限流
• ✅ DeepSeek 主路由 + Qwen 降级（LLMService）
• ✅ PostgreSQL + pgvector 的 ORM 数据模型（8 类核心实体）
• ✅ Celery worker 与任务入口骨架（记忆提取/内容策展/推送）
• ✅ Alembic 异步迁移环境配置
• ✅ 请求 ID、中间件日志、统一异常返回

还未实现（计划中）

以下能力在 PLAN.md 中已有规划，但代码尚未完成：

• ⬜ 微信公众号接入与语音消息处理
• ⬜ RAG 检索与人格蒸馏链路
• ⬜ 事实提取入库（当前 task 为占位）
• ⬜ ESP32 语音硬件链路
• ⬜ Next.js 管理控制台

仓库结构（当前）

grandson/
├── PLAN.md
├── README.md
├── .env.example
├── docker/
│   ├── docker-compose.yml
│   ├── docker-compose.dev.yml
│   ├── init.sql
│   └── nginx/
└── backend/
    ├── pyproject.toml
    ├── Dockerfile
    ├── alembic.ini
    ├── app/
    │   ├── main.py
    │   ├── api/
    │   ├── db/
    │   ├── schemas/
    │   ├── services/
    │   └── worker/
    └── tests/

快速启动（Docker Compose）

1) 准备环境变量

cd grandson
cp .env.example .env

至少配置：

• DEEPSEEK_API_KEY（必填）
• QWEN_API_KEY（建议填，作为降级）

2) 启动服务

cd grandson
docker compose -f docker/docker-compose.yml up --build

默认端口：

• Backend: 8000
• Postgres: 5432
• Redis: 6379
• Nginx: 80

3) 接口试跑

健康检查：

curl http://localhost:8000/health

对话接口（需先有合法 user_id，且数据库已初始化对应用户）：

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "爷爷今天感觉怎么样？",
    "message_type": "text"
  }'

如需快速创建测试用户（PostgreSQL）：

INSERT INTO users (id, name, role, is_active)
VALUES ('550e8400-e29b-41d4-a716-446655440000', '测试爷爷', 'grandpa', true)
ON CONFLICT (id) DO NOTHING;

API 概览

GET /health

返回服务存活状态：

{"status":"ok"}

POST /api/chat

请求体字段：

• user_id：用户 UUID
• message：消息文本（1~5000）
• message_type：text 或 voice
• conversation_id：可选，续聊时传入

返回字段：

• conversation_id
• message_id
• reply
• provider（deepseek / qwen / cache）

技术栈（已使用部分）

• Python 3.12
• FastAPI
• SQLAlchemy 2 (async) + Alembic
• PostgreSQL 16 + pgvector
• Redis
• Celery
• OpenAI 兼容 SDK（调用 DeepSeek / Qwen）

开发与检查

cd grandson/backend
PYTHONPATH=. pytest
ruff check .

当前状态说明：/health 与 POST /api/chat 为现阶段主验证链路；微信接入、RAG、人格蒸馏、ESP32 与 Web 控制台仍在计划开发中。

里程碑

• 已完成：Week 1（基础设施 + 对话引擎）
• 进行中：向 Week 2（记忆系统 + 微信接入）推进

---

如需查看完整路线图、愿景与周计划，请阅读：

• PLAN.md