SmartDeck

纯前端 PWA：在仓库 public/decks/ 维护题库（清单 + JSON），用户通过浏览器使用。仅「收藏」的题库会下载全文到本机 IndexedDB；清单版本变新时只提示，需用户手动点「更新到最新」。支持 问题模式 / 记忆模式（费曼引导）、卡片翻转、移动端滑动与 PC 键盘。

开发

npm install
npm run dev

根路径开发默认 VITE_BASE=/。若模拟 GitHub Pages 子路径：

VITE_BASE=/SmartDeck/ npm run dev

可选：复制 .env.example 为 .env 并设置 VITE_GITHUB_REPO_URL 以显示页脚源码链接。

构建

npm run build

生产环境通过 VITE_BASE 指定静态资源前缀（GitHub 项目站一般为 /仓库名/，Cloudflare 根域一般为 /）。

部署

GitHub Pages

仓库已含 .github/workflows/pages.yml。请在仓库 Settings → Pages 启用 GitHub Actions 源，并将 workflow 中的 VITE_BASE 改成与你的仓库名一致。可选在仓库 Variables 中设置 VITE_GITHUB_REPO_URL。

推送至 main 时，若变更包含 public/decks/、应用源码或 public/ 下静态资源等，会自动构建并发布；仅修改根目录与各处的 *.md、docs/、.cursor/ 不会触发。需要时可到 Actions 里对该 workflow 使用 Run workflow 手动部署。

Cloudflare Pages

• Build command: npm run build
• Output directory: dist
• 环境变量：VITE_BASE=/，VITE_GITHUB_REPO_URL（可选）

PWA 更新

• 应用壳（JS/CSS）：安装 PWA 后，新版本会提示「刷新更新」。
• 题库内容：不依赖自动静默覆盖；由清单 version + 用户在「我的题库」中手动更新。

题库维护

见 docs/question-bank-format.md。改正文务必递增 index.json 里该库的 version。

AI 协作

• 完整写作规范：docs/agents/smartdeck-question-bank.md
• Codex / 通用：AGENTS.md
• Claude Code：CLAUDE.md
• Gemini：GEMINI.md
• Cursor Skill：.cursor/skills/smartdeck-question-bank/SKILL.md

快捷键（学习页）

• ← / →：上一张 / 下一张
• 空格：翻转卡片

技术栈

Vite、React 19、TypeScript、Tailwind CSS v4、React Router（HashRouter）、Zod、idb、framer-motion、vite-plugin-pwa。