@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/productivity/memento-flashcards/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: memento-flashcards
+description: >-
+  间隔重复抽认卡系统。支持从事实或文本创建卡片，
+  通过由 agent 评分的自由文本答案与抽认卡进行互动，
+  从 YouTube 字幕生成问答题，利用自适应时间安排复习到期卡片，
+  并支持以 CSV 格式导出/导入卡片组。
+version: 1.0.0
+author: Memento AI
+license: MIT
+platforms: [macos, linux]
+metadata:
+  hermes:
+    tags: [Education, Flashcards, Spaced Repetition, Learning, Quiz, YouTube]
+    requires_toolsets: [terminal]
+    category: productivity
+---
+
+# Memento Flashcards — Spaced-Repetition Flashcard Skill
+
+## 概览
+
+Memento 为您提供了一个基于本地文件的、带有间隔重复调度功能的抽认卡系统。
+用户可以通过输入自由文本答案与抽认卡进行互动，由 agent 对回答进行评分，然后安排下一次复习。
+当用户想要以下操作时，可以使用此技能：
+
+- **记住某个事实** — 将任何陈述转化为问答抽认卡
+- **利用间隔重复进行学习** — 通过自适应间隔和 agent 评分的自由文本答案复习到期卡片
+- **通过 YouTube 视频进行测验** — 获取视频字幕并生成包含 5 个问题的问答题
+- **管理卡片组** — 将卡片组织成集合，导出/导入 CSV
+
+所有卡片数据都存储在单个 JSON 文件中。无需外部 API 密钥 — 由您（agent）直接生成抽认卡内容和测验问题。
+
+Memento Flashcards 面向用户的回复风格：
+- 仅使用纯文本。在对用户的回复中不要使用 Markdown 格式。
+- 保持复习和测验反馈简短且中立。避免额外的夸奖、鼓励或冗长的解释。
+
+## When to Use
+
+当用户希望执行以下操作时，使用此技能：
+- 将事实保存为抽认卡以便日后复习
+- 利用间隔重复复习到期卡片
+- 从 YouTube 视频字幕生成问答题
+- 导入、导出、检查或删除抽认卡数据
+
+不要将此技能用于一般的问答、编程帮助或非记忆类任务。
+
+## Quick Reference
+
+| 用户意图 | 操作 |
+|---|---|
+| "记住 X" / "把这个保存为抽认卡" | 生成问答卡片，调用 `memento_cards.py add` |
+| 发送事实但未提及抽认卡 | 询问 "是否需要将此保存为 Memento 抽认卡？" — 只有在用户确认时才创建 |
+| "创建一张抽认卡" | 询问问题、答案、集合；调用 `memento_cards.py add` |
+| "复习我的卡片" | 调用 `memento_cards.py due`，逐一展示卡片 |
+| "用 [YouTube URL] 测验我" | 调用 `youtube_quiz.py fetch VIDEO_ID`，生成 5 个问题，调用 `memento_cards.py add-quiz` |
+| "导出我的卡片" | 调用 `memento_cards.py export --output PATH` |
+| "从 CSV 导入卡片" | 调用 `memento_cards.py import --file PATH --collection NAME` |
+| "显示我的统计数据" | 调用 `memento_cards.py stats` |
+| "删除一张卡片" | 调用 `memento_cards.py delete --id ID` |
+| "删除一个集合" | 调用 `memento_cards.py delete-collection --collection NAME` |
+
+## Card Storage
+
+卡片存储在以下 JSON 文件中：
+
+```
+~/.hermes/skills/productivity/memento-flashcards/data/cards.json
+```
+
+**绝对不要直接编辑此文件。** 始终使用 `memento_cards.py` 子命令。该脚本会处理原子写入（先写入临时文件，然后重命名）以防止数据损坏。
+
+首次使用时会自动创建该文件。
+
+## Procedure
+
+### Creating Cards from Facts
+
+### Activation Rules
+
+并非所有陈述事实的语句都应成为抽认卡。请使用以下三级检查机制：
+
+1. **明确意图** — 用户提到 "memento"、"flashcard"、"remember this"、"save this card"、"add a card"，或类似明确要求创建抽认卡的措辞 → **直接创建卡片**，无需确认。
+2. **隐含意图** — 用户发送了陈述事实的语句，但未提及抽认卡（例如 "光速为 299,792 公里/秒"） → **先询问**："是否需要将此保存为 Memento 抽认卡？" 只有在用户确认后才创建卡片。
+3. **无意** — 消息是编程任务、提问、指令、正常对话，或任何显然不需要记忆的事实 → **完全不要激活此技能**。交由其他技能或默认行为处理。
+
+当确认激活时（第一级直接激活，第二级在确认后激活），生成一张抽认卡：
+
+**Step 1:** 将陈述语句转化为问答对。内部使用以下格式：
+
+```
+Turn the factual statement into a front-back pair.
+Return exactly two lines:
+Q: <question text>
+A: <answer text>
+
+Statement: "{statement}"
+```
+
+规则：
+- 问题应测试对关键事实的回忆
+- 答案应简明扼要
+
+**Step 2:** 调用脚本存储卡片：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add \
+  --question "What year did World War 2 end?" \
+  --answer "1945" \
+  --collection "History"
+```
+
+如果用户未指定集合，默认使用 `"General"`。
+
+脚本会输出确认已创建卡片的 JSON 数据。
+
+### Manual Card Creation
+
+当用户明确要求创建抽认卡时，请向用户询问：
+1. 问题（卡片正面）
+2. 答案（卡片背面）
+3. 集合名称（可选 — 默认为 `"General"`）
+
+然后如上所述调用 `memento_cards.py add`。
+
+### Reviewing Due Cards
+
+当用户想要复习时，获取所有到期的卡片：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
+```
+
+这会返回一个包含 `next_review_at <= now` 卡片的 JSON 数组。如果需要按集合过滤：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due --collection "History"
+```
+
+**复习流程（自由文本评分）：**
+
+以下是您必须严格遵循的互动模式示例。用户回答后，您进行评分，告诉他们正确答案，然后为卡片评级。
+
+**示例 interaction:**
+
+> **Agent:** 柏林墙是哪一年倒塌的？
+>
+> **User:** 1991
+>
+> **Agent:** 不完全对。柏林墙是在 1989 年倒塌的。下次复习时间是明天。
+> *(agent calls: memento_cards.py rate --id ABC --rating hard --user-answer "1991")*
+>
+> 下一个问题：第一个在月球上漫步的人是谁？
+
+**规则：**
+
+1. 仅展示问题。等待用户回答。
+2. 收到用户的回答后，将其与预期答案进行比较并评分：
+   - **correct** → 用户答对了关键事实（即使措辞不同）
+   - **partial** → 方向正确但缺少核心细节
+   - **incorrect** → 错误或偏离主题
+3. **您必须告诉用户正确答案以及他们的表现。** 保持简短且使用纯文本。使用以下格式：
+   - correct: "正确。答案：{answer}。下次复习时间：7 天后。"
+   - partial: "很接近。答案：{answer}。{他们遗漏的内容}。下次复习时间：3 天后。"
+   - incorrect: "不完全对。答案：{answer}。下次复习时间：明天。"
+4. 然后调用评级命令：correct→easy，partial→good，incorrect→hard。
+5. 然后展示下一个问题。
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
+  --id CARD_ID --rating easy --user-answer "what the user said"
+```
+
+**绝对不要跳过第 3 步。** 在继续之前，用户必须始终看到正确答案和反馈。
+
+如果没有到期的卡片，请告诉用户："当前没有需要复习的到期卡片。请稍后再来查看！"
+
+**强制退出：** 用户可以在任何时候说 "retire this card" 以将其从复习中永久移除。为此请使用 `--rating retire`。
+
+### Spaced Repetition Algorithm
+
+评级决定了下一次复习的时间间隔：
+
+| 评级 | 时间间隔 | ease_streak | 状态变化 |
+|---|---|---|---|
+| **hard** | +1 天 | 重置为 0 | 保持 learning 状态 |
+| **good** | +3 天 | 重置为 0 | 保持 learning 状态 |
+| **easy** | +7 天 | +1 | 如果 ease_streak >= 3 → 退出 (retired) |
+| **retire** | 永久 | 重置为 0 | → 退出 (retired) |
+
+- **learning**: 卡片正在积极参与轮换
+- **retired**: 卡片不会出现在复习中（用户已掌握或手动让其退出）
+- 连续三次获得 "easy" 评级将自动使卡片退出
+
+### YouTube Quiz Generation
+
+当用户发送 YouTube URL 并想要进行测验时：
+
+**Step 1:** 从 URL 中提取视频 ID（例如从 `https://www.youtube.com/watch?v=dQw4w9WgXcQ` 中提取 `dQw4w9WgXcQ`）。
+
+**Step 2:** 获取字幕：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/youtube_quiz.py fetch VIDEO_ID
+```
+
+这会返回 `{"title": "...", "transcript": "..."}` 或一个错误。
+
+如果脚本报告 `missing_dependency`，请告诉用户安装它：
+```bash
+pip install youtube-transcript-api
+```
+
+**Step 3:** 从字幕生成 5 个测验问题。使用以下规则：
+
+```
+You are creating a 5-question quiz for a podcast episode.
+Return ONLY a JSON array with exactly 5 objects.
+Each object must contain keys 'question' and 'answer'.
+
+Selection criteria:
+- Prioritize important, surprising, or foundational facts.
+- Skip filler, obvious details, and facts that require heavy context.
+- Never return true/false questions.
+- Never ask only for a date.
+
+Question rules:
+- Each question must test exactly one discrete fact.
+- Use clear, unambiguous wording.
+- Prefer What, Who, How many, Which.
+- Avoid open-ended Describe or Explain prompts.
+
+Answer rules:
+- Each answer must be under 240 characters.
+- Lead with the answer itself, not preamble.
+- Add only minimal clarifying detail if needed.
+```
+
+使用字幕的前 15,000 个字符作为上下文。由您自己（作为 LLM）生成问题。
+
+**Step 4:** 验证输出是否为有效的 JSON，是否恰好包含 5 个项目，并且每个项目都具有非空的 `question` 和 `answer` 字符串。如果验证失败，请重试一次。
+
+**Step 5:** 存储测验卡片：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add-quiz \
+  --video-id "VIDEO_ID" \
+  --questions '[{"question":"...","answer":"..."},...]' \
+  --collection "Quiz - Episode Title"
+```
+
+该脚本会根据 `video_id` 进行去重 — 如果该视频的卡片已存在，它将跳过创建并报告现有的卡片。
+
+**Step 6:** 使用与前面相同的自由文本评分流程，逐一展示问题：
+1. 展示 "问题 1/5: ..." 并等待用户的回答。绝对不要包含答案或任何暗示答案的线索。
+2. 等待用户用自己的话回答
+3. 使用评分规则对用户的答案进行评分（参见 "Reviewing Due Cards" 章节）
+4. **重要提示：您必须先向用户回复反馈，然后再进行其他操作。** 展示评级、正确答案以及卡片下次复习的时间。绝对不要悄无声息地跳到下一个问题。保持简短且使用纯文本。示例："不完全对。答案：{answer}。下次复习时间：明天。"
+5. **在展示反馈之后**，调用评级命令，然后在同一条消息中展示下一个问题：
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
+  --id CARD_ID --rating easy --user-answer "what the user said"
+```
+6. 重复此过程。在展示下一个问题之前，每一个答案都必须收到可见的反馈。
+
+### Export/Import CSV
+
+**Export:**
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py export \
+  --output ~/flashcards.csv
+```
+
+生成包含 3 列的 CSV：`question,answer,collection`（无表头行）。
+
+**Import:**
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py import \
+  --file ~/flashcards.csv \
+  --collection "Imported"
+```
+
+读取包含 question、answer 以及可选的 collection（第 3 列）的 CSV。如果缺少集合列，则使用 `--collection` 参数。
+
+### Statistics
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
+```
+
+返回包含以下内容的 JSON：
+- `total`: 卡片总数
+- `learning`: 处于活跃轮换中的卡片
+- `retired`: 已掌握的卡片
+- `due_now`: 当前需要复习的卡片
+- `collections`: 按集合名称分类的明细
+
+## Pitfalls
+
+- **绝对不要直接编辑 `cards.json`** — 始终使用脚本子命令以避免数据损坏
+- **字幕获取失败** — 某些 YouTube 视频没有英文字幕或禁用了字幕；请告知用户并建议其他视频
+- **可选 dependency** — `youtube_quiz.py` 需要 `youtube-transcript-api`；如果缺少，请告诉用户运行 `pip install youtube-transcript-api`
+- **大量导入** — 包含数千行的 CSV 导入可以正常工作，但 JSON 输出可能会非常冗长；请为用户总结结果
+- **视频 ID 提取** — 同时支持 `youtube.com/watch?v=ID` 和 `youtu.be/ID` 两种 URL 格式
+
+## 验证
+
+直接验证辅助脚本：
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add --question "Capital of France?" --answer "Paris" --collection "General"
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
+```
+
+如果您正在从仓库检出（repo checkout）中进行测试，请运行：
+
+```bash
+pytest tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q
+```
+
+Agent 级别的验证：
+- 启动复习流程，并确认反馈是否为纯文本、是否简明扼要，以及在展示下一张卡片之前是否始终包含正确答案
+- 运行 YouTube 测验流程，并确认在展示下一个问题之前，每一个答案是否都收到了可见的反馈

package/extensions/skills/optional/productivity/memento-flashcards/scripts/memento_cards.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""Memento card storage, spaced-repetition engine, and CSV I/O.
+
+Stdlib-only. All output is JSON for agent parsing.
+Data file: $HERMES_HOME/skills/productivity/memento-flashcards/data/cards.json
+"""
+
+import argparse
+import csv
+import json
+import os
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+DATA_DIR = _HERMES_HOME / "skills" / "productivity" / "memento-flashcards" / "data"
+CARDS_FILE = DATA_DIR / "cards.json"
+
+RETIRED_SENTINEL = "9999-12-31T23:59:59+00:00"
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _iso(dt: datetime) -> str:
+    return dt.isoformat()
+
+
+def _parse_iso(s: str) -> datetime:
+    return datetime.fromisoformat(s)
+
+
+def _empty_store() -> dict:
+    return {"cards": [], "version": 1}
+
+
+def _load() -> dict:
+    if not CARDS_FILE.exists():
+        return _empty_store()
+    try:
+        with open(CARDS_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict) or "cards" not in data:
+            return _empty_store()
+        return data
+    except (json.JSONDecodeError, OSError):
+        return _empty_store()
+
+
+def _save(data: dict) -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=DATA_DIR, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp, CARDS_FILE)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _out(obj: object) -> None:
+    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+# ── 子命令 ──────────────────────────────────────────────────────────────
+
+def cmd_add(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    card = {
+        "id": str(uuid.uuid4()),
+        "question": args.question,
+        "answer": args.answer,
+        "collection": args.collection or "General",
+        "status": "learning",
+        "ease_streak": 0,
+        "next_review_at": _iso(now),
+        "created_at": _iso(now),
+        "video_id": None,
+        "last_user_answer": None,
+    }
+    data["cards"].append(card)
+    _save(data)
+    _out({"ok": True, "card": card})
+
+
+def cmd_add_quiz(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+
+    try:
+        questions = json.loads(args.questions)
+    except json.JSONDecodeError as exc:
+        _out({"ok": False, "error": f"Invalid JSON for --questions: {exc}"})
+        sys.exit(1)
+
+    # 去重：如果已有包含此 video_id 的卡片则跳过
+    existing_ids = {c["video_id"] for c in data["cards"] if c.get("video_id")}
+    if args.video_id in existing_ids:
+        existing = [c for c in data["cards"] if c.get("video_id") == args.video_id]
+        _out({"ok": True, "skipped": True, "reason": "duplicate_video_id", "existing_count": len(existing), "cards": existing})
+        return
+
+    created = []
+    for qa in questions:
+        card = {
+            "id": str(uuid.uuid4()),
+            "question": qa["question"],
+            "answer": qa["answer"],
+            "collection": args.collection or "Quiz",
+            "status": "learning",
+            "ease_streak": 0,
+            "next_review_at": _iso(now),
+            "created_at": _iso(now),
+            "video_id": args.video_id,
+            "last_user_answer": None,
+        }
+        data["cards"].append(card)
+        created.append(card)
+
+    _save(data)
+    _out({"ok": True, "created_count": len(created), "cards": created})
+
+
+def cmd_due(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    due = []
+    for card in data["cards"]:
+        if card["status"] == "retired":
+            continue
+        review_at = _parse_iso(card["next_review_at"])
+        if review_at <= now:
+            if args.collection and card["collection"] != args.collection:
+                continue
+            due.append(card)
+    _out({"ok": True, "count": len(due), "cards": due})
+
+
+def cmd_rate(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    card = None
+    for c in data["cards"]:
+        if c["id"] == args.id:
+            card = c
+            break
+    if not card:
+        _out({"ok": False, "error": f"Card not found: {args.id}"})
+        sys.exit(1)
+
+    rating = args.rating
+    user_answer = getattr(args, "user_answer", None)
+    if user_answer is not None:
+        card["last_user_answer"] = user_answer
+
+    if rating == "retire":
+        card["status"] = "retired"
+        card["next_review_at"] = RETIRED_SENTINEL
+        card["ease_streak"] = 0
+    elif rating == "hard":
+        card["next_review_at"] = _iso(now + timedelta(days=1))
+        card["ease_streak"] = 0
+    elif rating == "good":
+        card["next_review_at"] = _iso(now + timedelta(days=3))
+        card["ease_streak"] = 0
+    elif rating == "easy":
+        card["next_review_at"] = _iso(now + timedelta(days=7))
+        card["ease_streak"] = card.get("ease_streak", 0) + 1
+        if card["ease_streak"] >= 3:
+            card["status"] = "retired"
+
+    _save(data)
+    _out({"ok": True, "card": card})
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    data = _load()
+    cards = data["cards"]
+    if args.collection:
+        cards = [c for c in cards if c["collection"] == args.collection]
+    if args.status:
+        cards = [c for c in cards if c["status"] == args.status]
+    _out({"ok": True, "count": len(cards), "cards": cards})
+
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    total = len(data["cards"])
+    learning = sum(1 for c in data["cards"] if c["status"] == "learning")
+    retired = sum(1 for c in data["cards"] if c["status"] == "retired")
+    due_now = 0
+    for c in data["cards"]:
+        if c["status"] != "retired" and _parse_iso(c["next_review_at"]) <= now:
+            due_now += 1
+
+    collections: dict[str, int] = {}
+    for c in data["cards"]:
+        name = c["collection"]
+        collections[name] = collections.get(name, 0) + 1
+
+    _out({
+        "ok": True,
+        "total": total,
+        "learning": learning,
+        "retired": retired,
+        "due_now": due_now,
+        "collections": collections,
+    })
+
+
+def cmd_export(args: argparse.Namespace) -> None:
+    data = _load()
+    output_path = Path(args.output).expanduser()
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f, lineterminator="\n")
+        for card in data["cards"]:
+            writer.writerow([card["question"], card["answer"], card["collection"]])
+    _out({"ok": True, "exported": len(data["cards"]), "path": str(output_path)})
+
+
+def cmd_import(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    file_path = Path(args.file).expanduser()
+
+    if not file_path.exists():
+        _out({"ok": False, "error": f"File not found: {file_path}"})
+        sys.exit(1)
+
+    created = 0
+    with open(file_path, "r", encoding="utf-8") as f:
+        reader = csv.reader(f)
+        for row in reader:
+            if len(row) < 2:
+                continue
+            question = row[0].strip()
+            answer = row[1].strip()
+            collection = row[2].strip() if len(row) >= 3 and row[2].strip() else (args.collection or "Imported")
+            if not question or not answer:
+                continue
+            card = {
+                "id": str(uuid.uuid4()),
+                "question": question,
+                "answer": answer,
+                "collection": collection,
+                "status": "learning",
+                "ease_streak": 0,
+                "next_review_at": _iso(now),
+                "created_at": _iso(now),
+                "video_id": None,
+                "last_user_answer": None,
+            }
+            data["cards"].append(card)
+            created += 1
+
+    _save(data)
+    _out({"ok": True, "imported": created})
+
+
+def cmd_delete(args: argparse.Namespace) -> None:
+    data = _load()
+    original = len(data["cards"])
+    data["cards"] = [c for c in data["cards"] if c["id"] != args.id]
+    removed = original - len(data["cards"])
+    if removed == 0:
+        _out({"ok": False, "error": f"Card not found: {args.id}"})
+        sys.exit(1)
+    _save(data)
+    _out({"ok": True, "deleted": args.id})
+
+
+def cmd_delete_collection(args: argparse.Namespace) -> None:
+    data = _load()
+    original = len(data["cards"])
+    data["cards"] = [c for c in data["cards"] if c["collection"] != args.collection]
+    removed = original - len(data["cards"])
+    _save(data)
+    _out({"ok": True, "deleted_count": removed, "collection": args.collection})
+
+
+# ── 命令行界面 ──────────────────────────────────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Memento flashcard manager")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_add = sub.add_parser("add", help="Create one card")
+    p_add.add_argument("--question", required=True)
+    p_add.add_argument("--answer", required=True)
+    p_add.add_argument("--collection", default="General")
+
+    p_quiz = sub.add_parser("add-quiz", help="Batch-add quiz cards")
+    p_quiz.add_argument("--video-id", required=True)
+    p_quiz.add_argument("--questions", required=True, help="JSON array of {question, answer}")
+    p_quiz.add_argument("--collection", default="Quiz")
+
+    p_due = sub.add_parser("due", help="List due cards")
+    p_due.add_argument("--collection", default=None)
+
+    p_rate = sub.add_parser("rate", help="Rate a card")
+    p_rate.add_argument("--id", required=True)
+    p_rate.add_argument("--rating", required=True, choices=["easy", "good", "hard", "retire"])
+    p_rate.add_argument("--user-answer", default=None)
+
+    p_list = sub.add_parser("list", help="List cards")
+    p_list.add_argument("--collection", default=None)
+    p_list.add_argument("--status", default=None, choices=["learning", "retired"])
+
+    sub.add_parser("stats", help="Show statistics")
+
+    p_export = sub.add_parser("export", help="Export cards to CSV")
+    p_export.add_argument("--output", required=True)
+
+    p_import = sub.add_parser("import", help="Import cards from CSV")
+    p_import.add_argument("--file", required=True)
+    p_import.add_argument("--collection", default="Imported")
+
+    p_del = sub.add_parser("delete", help="Delete one card")
+    p_del.add_argument("--id", required=True)
+
+    p_delcol = sub.add_parser("delete-collection", help="Delete all cards in a collection")
+    p_delcol.add_argument("--collection", required=True)
+
+    args = parser.parse_args()
+    cmd_map = {
+        "add": cmd_add,
+        "add-quiz": cmd_add_quiz,
+        "due": cmd_due,
+        "rate": cmd_rate,
+        "list": cmd_list,
+        "stats": cmd_stats,
+        "export": cmd_export,
+        "import": cmd_import,
+        "delete": cmd_delete,
+        "delete-collection": cmd_delete_collection,
+    }
+    cmd_map[args.command](args)
+
+
+if __name__ == "__main__":
+    main()