Kids Learning Cards

一个使用 AI 生成儿童教育资源的 Web 应用。

项目简介

本项目旨在通过 AI 技术为儿童生成各类学习资源，包括：

• 涂色卡片: 使用 AI 图像生成技术创建适合儿童涂色的线稿图片
• 数学练习: 自动生成加减乘除等数学练习题
• 英文练习: 生成英文单词、句子书写和阅读练习
• 书写练习: 创建各类书写练习模板和工作表

技术栈

• 前端框架: React 19 + TypeScript
• 样式系统: Tailwind CSS v4
• 构建工具: Vite
• AI 服务: Cloudflare Workers AI 语音转写 + 多图像 Provider

项目结构

src/
├── components/     # 可复用 UI 组件
├── pages/          # 页面组件
├── services/       # API 服务层 (AI 接口调用)
├── hooks/          # 自定义 React Hooks
├── types/          # TypeScript 类型定义
└── utils/          # 工具函数

开发指南

安装依赖

npm install

启动完整开发环境

npm run dev:full

请访问 http://localhost:5173。该命令同时运行 Vite 和本地 API 服务。如果只 调试前端，仍可使用 npm run dev。

需要使用真实 Worker runtime、D1/R2 或 Cloudflare bindings 时运行：

npm run dev:cf

Wrangler 会在 http://localhost:8787 提供完整站点。远程 secret 不会被下载； 本地调试 Provider 时请将必要值放入已被 Git 忽略的 .dev.vars。

构建生产版本

npm run build

预览生产构建

npm run preview

使用 Cloudflare Worker 预览：

npm run build
npm run preview:cf

Cloudflare 数据存储

Worker 环境使用 D1 kids-learning-cards-db 存储图片索引，使用 R2 kids-learning-cards-images 存储图片。wrangler.toml 是 binding 和 STORAGE_BACKEND 的配置来源。Supabase 数据和 secrets 暂时保留作为回退路径。

新生成的 PNG/JPEG 会通过 Cloudflare Images binding 转为质量 80 的 WebP 后 写入 R2；上游已经返回 WebP 时不会重复转换。转换服务不可用或额度不足时会 自动保存原图，避免影响图片生成流程。

生产环境由 Worker kids-learning-cards-worker 提供服务。执行以下命令会同时 更新 workers.dev 预览地址和 kids.a-dobe.club/* Worker route：

npm run build
npm run deploy:cf

现有 Pages 项目和自定义域名继续保留作为回滚路径。正式流量由 Worker route 优先接管；如需回滚，移除 wrangler.toml 中的 route 并重新部署 Worker 即可。

Worker secrets

Wrangler 和 Cloudflare 不允许读取 Pages 中已有的 secret 值，因此需要在新 Worker 中重新添加。主用和第一 fallback 至少需要：

LABNANA_API_KEY
GPT_IMAGE_API_KEY

其他 provider 如需保持可用，再添加：

ANTIGRAVITY_API_KEY
ANTIGRAVITY_BASE_URL
OPENAI_API_KEY
GEMINI_API_KEY
MODELSCOPE_API_KEY
MODELSCOPE_BASE_URL
MODELSCOPE_MODEL
PROVIDER_PRIORITY

可以在 Cloudflare Dashboard 的 Worker Variables and Secrets 页面填写，也可以 逐项执行 wrangler secret put <NAME>。不要把值写入 wrangler.toml 或提交到 Git。

AI 图片 Provider

默认图片生成顺序为 ListenHub/LabNana 主用，GPT Image 兼容接口作为第一 fallback：

labnana → gpt-image → antigravity → modelscope → gemini → openai

GPT Image provider 使用独立的服务端环境变量，不会暴露到浏览器：

GPT_IMAGE_BASE_URL=https://your-compatible-api.example.com/v1
GPT_IMAGE_API_KEY=your-api-key
GPT_IMAGE_MODEL=gpt-image-2

GPT_IMAGE_MODEL 可省略，默认使用 gpt-image-2。Base URL 可以是服务根地址、 /v1 地址或完整的 /v1/images/generations 地址。只有 Base URL 和 API key 同时存在时 provider 才会注册。

需要调整主备顺序时设置服务端 PROVIDER_PRIORITY，例如未来将 GPT Image 切为主用：

PROVIDER_PRIORITY=gpt-image,labnana,antigravity,modelscope,gemini,openai

项目状态

🚀 规划中 - 项目架构设计阶段

后续计划

1. 设计用户界面和交互流程
2. 集成 AI 图像生成 API
3. 实现涂色卡片生成功能
4. 添加数学和英文练习生成器
5. 优化用户体验和响应速度

License

MIT