muninn-cli 0.1.1__py3-none-any.whl

muninn_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: muninn-cli
+Version: 0.1.1
+Summary: Muninn - The Extensible Reciting CLI
+Project-URL: Repository, https://github.com/a1fredbao/muninn
+Project-URL: Issues, https://github.com/a1fredbao/muninn/issues
+Author-email: Alfred <your@email.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,flashcard,memorize,recite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Muninn
+
+Muninn (雾尼) - An Extensible Reciting CLI.
+
+[中文文档](./README_zh.md)
+
+## What is Muninn?
+
+Muninn is a highly extensible CLI application designed to help you memorize anything. Instead of hardcoding questions, Muninn relies on a **Plugin Architecture**. You can install "Reciting Packs" created by others (like chemistry elements, GRE vocabulary, or historical events) or develop your own packs using Python.
+
+Muninn acts as a "host" that provides:
+
+1. A **Smart Scheduling Algorithm** (focuses on your weak-points).
+2. **Persistent State Management** (remembers your progress across sessions).
+3. A clean, distraction-free **Terminal UI**.
+
+## Installation & Usage
+
+Install Muninn globally using `uv` (recommended) or `pip`:
+
+```bash
+# Using uv (Recommended)
+uv tool install muninn-cli
+
+# Or using pip
+pip install muninn-cli
+```
+
+Available commands:
+
+```bash
+# List all installed packs
+muninn list
+
+# Install a pack (supports directories or .zip files)
+muninn install path/to/pack_or_zip
+
+# Uninstall a previously installed pack
+muninn uninstall <pack_id>
+
+# Run a specific pack by ID
+muninn run <pack_id>
+
+# Generate a new plugin template for development
+muninn new <your_new_pack_id>
+```
+
+## Plugin Development Guide
+
+Muninn provides a layered API. Choose the level that fits your needs.
+
+### Quickstart: `FlashcardPlugin` (zero boilerplate)
+
+For simple front/back flashcards (e.g. GRE words), create a CSV or JSON file with `front` and `back` columns, then write a 3-line plugin:
+
+```python
+from core.helpers import FlashcardPlugin
+
+
+class Plugin(FlashcardPlugin):
+    DATA_FILE = "words.csv"
+```
+
+That's it. `FlashcardPlugin` handles rendering, answer-checking, and ID generation automatically.
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Pack metadata (name, author, version). |
+| `words.csv` | Data with `front` and `back` columns. |
+| `plugin.py` | The 3-line plugin above. |
+
+### For structured data: `DataPlugin` + `QuestionType`
+
+When each data record can be quizzed from multiple angles, use `DataPlugin`. Declare your **question types** and let Muninn generate all problem variants automatically.
+
+**Example** — Chemistry elements quizzed from 4 directions (symbol → name, name → number, etc.):
+
+```python
+import os, json
+from core.helpers import DataPlugin, QuestionType, Matchers
+
+
+class Plugin(DataPlugin):
+    QUESTION_TYPES = [
+        QuestionType(
+            label="看序号背元素",
+            statement=lambda el: f"原子序数: {el['num']}",
+            answer=lambda el: f"{el['name']} {el['sym']}",
+            matcher=Matchers.chinese_symbol_pair("name", "sym"),
+        ),
+        QuestionType(
+            label="看元素背序号",
+            statement=lambda el: f"元素: {el['name']} ({el['sym']})",
+            answer=lambda el: str(el["num"]),
+            matcher=Matchers.exact_integer("num"),
+        ),
+    ]
+
+    def load_records(self) -> list:
+        with open(
+            os.path.join(self.workspace_dir, "elements.json"), encoding="utf-8"
+        ) as f:
+            return json.load(f)
+
+    def filter(self, record, q_type):
+        # Optional: skip certain question types for specific records
+        return True
+```
+
+`DataPlugin` auto-generates problem IDs (`{record_index}__{question_label}`) and routes all five interface methods. You only supply data + question types.
+
+### Built-in Matchers
+
+Instead of writing custom regex for every question type, use the built-in `Matchers` factories:
+
+| Matcher | Behavior |
+|---------|----------|
+| `Matchers.exact(key)` | Exact match after trimming whitespace. |
+| `Matchers.exact_integer(key)` | Extract digits, compare numerically. |
+| `Matchers.case_insensitive(key)` | Case-insensitive match. |
+| `Matchers.chinese_symbol_pair(key1, key2)` | Match "中文+符号" or "符号+中文" in any order. |
+| `Matchers.any_order(*keys)` | Match all field values appearing anywhere in the input. |
+| `Matchers.custom(fn)` | Pass your own `(record, user_input) -> bool` function. |
+
+### Low-level: `BaseRecitePlugin`
+
+For full control, implement the base interface directly:
+
+```python
+from core.base_plugin import BaseRecitePlugin
+
+
+class Plugin(BaseRecitePlugin):
+    def load_data(self):
+        # Load static data from self.workspace_dir
+        pass
+
+    def get_all_problem_ids(self) -> list[str]:
+        """Return all unique problem IDs."""
+        pass
+
+    def render_statement(self, problem_id: str) -> str:
+        """Return the question text to display."""
+        pass
+
+    def check_answer(self, problem_id: str, user_input: str) -> bool:
+        """Return True if correct."""
+        pass
+
+    def get_expected_display(self, problem_id: str) -> str:
+        """Return the correct answer to show on failure."""
+        pass
+
+    def get_expand_info(self, problem_id: str) -> str:
+        """Optional: Return extra info to show on success."""
+        return ""
+```
+
+### Developing a pack from scratch
+
+1. **Generate a template**:
+
+   ```bash
+   muninn new my_cool_pack
+   ```
+
+   This creates a `my_cool_pack/` directory with `manifest.json` and a skeleton `plugin.py`.
+
+2. **Write your logic** using one of the approaches above.
+
+3. **Install and test**:
+
+   ```bash
+   muninn install ./my_cool_pack
+   muninn run my_cool_pack
+   ```

muninn_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/main.py,sha256=jDfnAF8WVUtOz1TshANchnWoNNi9_6pPt8dJQ2U11uU,2925
+src/ui.py,sha256=uP6qx9mmBvt6XUaO3zThEvZ3gucHh-qUuHgrmHaYHOE,1168
+src/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/cli/manager.py,sha256=b9fte4QX1P-9y1LNuDbN7-4NZShFHHRoo-4Lcaq3OxI,5787
+src/cli/runner.py,sha256=olEke0H7ZheZQs7EwiBLq-Qm7vOvyncFVevjA4Nw868,3872
+src/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/core/base_plugin.py,sha256=J1TDlkfNZq-illtHruld4jakOzK2gdkLrGMPRfAxtoM,1214
+src/core/helpers.py,sha256=TN7nLTm8sQs6Ep9qYwG_H3qmX-HJY1xZamkB7Lo-qaE,7180
+src/core/scheduler.py,sha256=57G6fKK7QfveIY0QM1-b1_KmH67FgGtb76dcGvVgS2Y,1675
+src/core/state.py,sha256=LMMb8Uj81tbt_LyHTUHQuxSNvhgzkGxU1TwK7fWyC7c,2185
+muninn_cli-0.1.1.dist-info/METADATA,sha256=uKsmryWAKS2X9mzqZ6Xwb8SvlUeOb_Jvg0b90rxyGrw,5996
+muninn_cli-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+muninn_cli-0.1.1.dist-info/entry_points.txt,sha256=IUx54nFj9LxkwOnMCH6Gcx6HruFkKGL7mJerkDTjRrg,41
+muninn_cli-0.1.1.dist-info/licenses/LICENSE,sha256=8EOHZ_sSvknlRG8QxCYLwgsfj_Uo3ZqljHadd-2kK0I,1067
+muninn_cli-0.1.1.dist-info/RECORD,,

muninn_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

muninn_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+muninn = src.main:main

muninn_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alfred Bao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/cli/manager.py

@@ -0,0 +1,161 @@
+import importlib.util
+import json
+import os
+import shutil
+import sys
+import zipfile
+
+from ..core.base_plugin import BaseRecitePlugin
+
+
+class PackageManager:
+    def __init__(self):
+        self.packs_dir = os.path.expanduser("~/.muninn/packs")
+        os.makedirs(self.packs_dir, exist_ok=True)
+
+    def _get_pack_dir(self, pack_id: str) -> str:
+        return os.path.join(self.packs_dir, pack_id)
+
+    def create_template(self, pack_id: str, target_dir: str = "."):
+        """Generate a new plugin template."""
+        pack_dir = os.path.join(target_dir, pack_id)
+        if os.path.exists(pack_dir):
+            raise FileExistsError(f"Directory {pack_dir} already exists.")
+
+        os.makedirs(pack_dir)
+
+        manifest = {
+            "id": pack_id,
+            "name": f"{pack_id} Pack",
+            "author": "Your Name",
+            "version": "1.0.0",
+            "description": "A new reciting pack for Muninn.",
+        }
+        with open(os.path.join(pack_dir, "manifest.json"), "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=4, ensure_ascii=False)
+
+        plugin_code = '''"""A minimal Muninn plugin using DataPlugin.
+
+For flashcard-style packs (front/back), use FlashcardPlugin instead.
+For full control, use the BaseRecitePlugin interface directly.
+"""
+from typing import ClassVar
+
+from core.helpers import (
+    DataPlugin,
+    Matchers,
+    QuestionType,
+)
+
+
+class Plugin(DataPlugin):
+    QUESTION_TYPES: ClassVar[list[QuestionType]] = [
+        # TODO: Define your question types here.
+        # Each QuestionType needs a label, statement, answer, and matcher.
+        # See the documentation for examples.
+    ]
+'''
+        with open(os.path.join(pack_dir, "plugin.py"), "w", encoding="utf-8") as f:
+            f.write(plugin_code)
+
+        print(f"✅ Template created at {pack_dir}")
+
+    def install_pack(self, source_path: str) -> str:
+        """Install a pack from a directory or zip file."""
+        if not os.path.exists(source_path):
+            raise FileNotFoundError(f"Path not found: {source_path}")
+
+        temp_dir = os.path.join(self.packs_dir, ".temp_install")
+        if os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir)
+
+        if os.path.isdir(source_path):
+            shutil.copytree(source_path, temp_dir)
+        elif zipfile.is_zipfile(source_path):
+            with zipfile.ZipFile(source_path, "r") as zip_ref:
+                zip_ref.extractall(temp_dir)
+        else:
+            raise ValueError(
+                "Unsupported file format. Must be a directory or zip file."
+            )
+
+        # Find manifest.json
+        manifest_path = os.path.join(temp_dir, "manifest.json")
+        if not os.path.exists(manifest_path):
+            shutil.rmtree(temp_dir)
+            raise FileNotFoundError("manifest.json not found in the package.")
+
+        with open(manifest_path, "r", encoding="utf-8") as f:
+            manifest = json.load(f)
+
+        pack_id = manifest.get("id")
+        if not pack_id:
+            shutil.rmtree(temp_dir)
+            raise ValueError("Invalid manifest: missing 'id'")
+
+        target_dir = self._get_pack_dir(pack_id)
+        if os.path.exists(target_dir):
+            print(f"🔄 Updating existing pack: {pack_id}")
+            shutil.rmtree(target_dir)
+
+        shutil.move(temp_dir, target_dir)
+        print(f"✅ Successfully installed pack '{pack_id}'")
+        return pack_id
+
+    def uninstall_pack(self, pack_id: str):
+        """Remove a pack from the local packs directory."""
+        pack_dir = self._get_pack_dir(pack_id)
+        if not os.path.exists(pack_dir):
+            raise FileNotFoundError(f"Pack '{pack_id}' is not installed.")
+        shutil.rmtree(pack_dir)
+        print(f"🗑️  Pack '{pack_id}' has been uninstalled.")
+
+    def load_plugin(self, pack_id: str) -> BaseRecitePlugin:
+        """Dynamically load the plugin.py from the pack_id directory."""
+        pack_dir = self._get_pack_dir(pack_id)
+        if not os.path.exists(pack_dir):
+            raise FileNotFoundError(f"Pack '{pack_id}' not found.")
+
+        plugin_path = os.path.join(pack_dir, "plugin.py")
+        if not os.path.exists(plugin_path):
+            raise FileNotFoundError(f"plugin.py not found in {pack_id}.")
+
+        src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+        sys.path.insert(0, src_dir)
+
+        try:
+            spec = importlib.util.spec_from_file_location(
+                f"muninn.plugins.{pack_id}", plugin_path
+            )
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+
+            # Find the class that inherits from BaseRecitePlugin
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (
+                    isinstance(attr, type)
+                    and attr.__module__ == module.__name__
+                    and any(b.__name__ == "BaseRecitePlugin" for b in attr.__mro__)
+                    and attr.__name__ != "BaseRecitePlugin"
+                ):
+                    return attr(workspace_dir=pack_dir)
+
+            raise ValueError(
+                f"No valid BaseRecitePlugin subclass found in {plugin_path}"
+            )
+        finally:
+            sys.path.pop(0)
+
+    def list_packs(self):
+        packs = []
+        for pack_id in os.listdir(self.packs_dir):
+            pack_dir = self._get_pack_dir(pack_id)
+            if not os.path.isdir(pack_dir):
+                continue
+            manifest_path = os.path.join(pack_dir, "manifest.json")
+            if os.path.exists(manifest_path):
+                with open(manifest_path, "r", encoding="utf-8") as f:
+                    manifest = json.load(f)
+                    packs.append(manifest)
+        return packs

src/cli/runner.py

@@ -0,0 +1,121 @@
+import sys
+import time
+
+from ..core.base_plugin import BaseRecitePlugin
+from ..core.scheduler import Scheduler
+from ..core.state import StateManager
+from ..ui import TerminalUI
+
+
+class GameRunner:
+    def __init__(self, pack_id: str, plugin: BaseRecitePlugin):
+        self.pack_id = pack_id
+        self.plugin = plugin
+
+        self.problem_ids = self.plugin.get_all_problem_ids()
+        self.state_manager = StateManager(pack_id)
+        self.scheduler = Scheduler(self.problem_ids, self.state_manager)
+
+        self.combo = 0
+
+        # Calculate distinct AC count across all problems at startup
+        self.distinct_ac = 0
+        self.total_ac_count = 0
+        self.total_count = 0
+        self.total_ac_time = 0.0
+
+        for pid in self.problem_ids:
+            stats = self.state_manager.get_stats(pid)
+            if stats["ac_count"] > 0:
+                self.distinct_ac += 1
+            self.total_ac_count += stats["ac_count"]
+            self.total_count += stats["total_count"]
+            self.total_ac_time += stats["total_ac_time"]
+
+    def run(self):
+        TerminalUI.clear_screen()
+        TerminalUI.print_green(f"====== 正在学习包: {self.pack_id} ======\n")
+        TerminalUI.wait_any_key()
+
+        try:
+            while True:
+                problem_id = self.scheduler.next_problem()
+                if not problem_id:
+                    print("题库为空！")
+                    break
+                self.ask(problem_id)
+        except (KeyboardInterrupt, EOFError):
+            self.quit()
+
+    def ask(self, problem_id: str):
+        TerminalUI.clear_screen()
+
+        avg_time = (
+            self.total_ac_time / self.total_ac_count if self.total_ac_count > 0 else 0
+        )
+        TerminalUI.print_stats_banner(
+            distinct_ac=self.distinct_ac,
+            total_problems=len(self.problem_ids),
+            ac_count=self.total_ac_count,
+            total_count=self.total_count,
+            combo=self.combo,
+            avg_time=avg_time,
+        )
+
+        statement = self.plugin.render_statement(problem_id)
+        TerminalUI.print_cyan(statement)
+        print("（输入 q 退出）")
+
+        start_time = time.perf_counter()
+        user_input = input(">> ").strip()
+
+        if user_input.lower() == "q":
+            self.quit()
+
+        end_time = time.perf_counter()
+        time_spent = end_time - start_time
+
+        self.total_count += 1
+
+        is_correct = self.plugin.check_answer(problem_id, user_input)
+
+        if is_correct:
+            self._handle_ac(problem_id, time_spent)
+        else:
+            self._handle_wa(problem_id)
+
+        self.scheduler.update_problem(problem_id, is_correct, time_spent)
+
+    def _handle_ac(self, problem_id: str, time_spent: float):
+        stats = self.state_manager.get_stats(problem_id)
+        if stats["ac_count"] == 0:
+            self.distinct_ac += 1
+
+        self.total_ac_count += 1
+        self.combo += 1
+        self.total_ac_time += time_spent
+
+        TerminalUI.print_success_banner(time_spent)
+        expand_info = self.plugin.get_expand_info(problem_id)
+        if expand_info:
+            print(f"💡 拓展信息: {expand_info}\n")
+
+        TerminalUI.wait_any_key()
+
+    def _handle_wa(self, problem_id: str):
+        self.combo = 0
+        TerminalUI.print_error_banner()
+        expected = self.plugin.get_expected_display(problem_id)
+        print(f"标准答案: \033[33;1m{expected}\033[0m\n")
+        TerminalUI.wait_any_key()
+
+    def quit(self):
+        TerminalUI.clear_screen()
+        print("=== 学习统计 ===")
+        print(f"总答题数: {self.total_count}")
+        if self.total_count > 0:
+            print(
+                f"总正确率: {self.total_ac_count} / {self.total_count} ({self.total_ac_count / self.total_count * 100:.1f}%)"
+            )
+        self.state_manager.close()
+        sys.exit(0)

src/core/base_plugin.py

@@ -0,0 +1,32 @@
+class BaseRecitePlugin:
+    def __init__(self, workspace_dir: str):
+        """
+        初始化插件
+        :param workspace_dir: CLI 分配给该包的私有静态数据目录
+        """
+        self.workspace_dir = workspace_dir
+        self.load_data()
+
+    def load_data(self):
+        """加载 workspace_dir 中的静态数据，由子类实现"""
+        raise NotImplementedError
+
+    def get_all_problem_ids(self) -> list[str]:
+        """返回题库中所有题目的唯一 ID，供 CLI 调度器建立索引和存档进度"""
+        raise NotImplementedError
+
+    def render_statement(self, problem_id: str) -> str:
+        """根据题目 ID 返回要在终端显示的问题文本"""
+        raise NotImplementedError
+
+    def check_answer(self, problem_id: str, user_input: str) -> bool:
+        """回调函数：判断用户输入是否正确"""
+        raise NotImplementedError
+
+    def get_expected_display(self, problem_id: str) -> str:
+        """回答错误时，展示给用户的标准答案"""
+        raise NotImplementedError
+
+    def get_expand_info(self, problem_id: str) -> str:
+        """回答正确时，展示给用户的拓展/提示信息 (可选)"""
+        return ""

src/core/helpers.py

@@ -0,0 +1,205 @@
+import csv
+import json
+import os
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from .base_plugin import BaseRecitePlugin
+
+# ---------------------------------------------------------------------------
+# Matchers – factory functions for reusable answer-checking logic
+# ---------------------------------------------------------------------------
+
+
+class Matchers:
+    """Built-in matcher factories.
+
+    Each classmethod returns a ``(data_item: dict, user_input: str) -> bool``
+    callable, suitable for use as a ``QuestionType.matcher``.
+    """
+
+    @staticmethod
+    def exact(key: str):
+        """Exact match after stripping whitespace."""
+
+        def match(data_item: dict, user_input: str) -> bool:
+            return user_input.strip() == str(data_item[key]).strip()
+
+        return match
+
+    @staticmethod
+    def exact_integer(key: str):
+        """Extract digits from the user input and compare numerically."""
+
+        def match(data_item: dict, user_input: str) -> bool:
+            digits = re.sub(r"\D", "", user_input)
+            return digits == str(data_item[key])
+
+        return match
+
+    @staticmethod
+    def case_insensitive(key: str):
+        """Case-insensitive match after stripping whitespace."""
+
+        def match(data_item: dict, user_input: str) -> bool:
+            return user_input.strip().lower() == str(data_item[key]).strip().lower()
+
+        return match
+
+    @staticmethod
+    def chinese_symbol_pair(key1: str, key2: str):
+        """Match "中文+符号" or "符号+中文" in either order, ignoring
+        whitespace and case (for the Latin part)."""
+
+        def match(data_item: dict, user_input: str) -> bool:
+            val1 = str(data_item[key1]).strip()
+            val2 = str(data_item[key2]).strip()
+            clean = re.sub(r"\s+", "", user_input).lower()
+            return clean in ((val1 + val2).lower(), (val2 + val1).lower())
+
+        return match
+
+    @staticmethod
+    def any_order(*keys: str):
+        """Match when all field values appear somewhere in the input,
+        ignoring non-alphanumeric characters and case."""
+
+        def match(data_item: dict, user_input: str) -> bool:
+            clean_input = re.sub(r"[^a-zA-Z0-9]", "", user_input).upper()
+            values = [
+                re.sub(r"[^a-zA-Z0-9]", "", str(data_item[k])).upper() for k in keys
+            ]
+            return all(v in clean_input for v in values)
+
+        return match
+
+    @staticmethod
+    def custom(fn: Callable[[dict, str], bool]):
+        """Pass-through for a fully custom matcher function."""
+        return fn
+
+
+# ---------------------------------------------------------------------------
+# QuestionType – a reusable question "direction"
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class QuestionType:
+    """Encapsulates one question direction: how to render the statement,
+    how to render the expected answer, and how to check correctness."""
+
+    label: str
+    statement: Callable[[dict], str]
+    answer: Callable[[dict], str]
+    matcher: Callable[[dict, str], bool]
+
+
+# ---------------------------------------------------------------------------
+# DataPlugin – base class for record × QuestionType plugins
+# ---------------------------------------------------------------------------
+
+
+class DataPlugin(BaseRecitePlugin):
+    """Higher-level plugin for "entity + multi-question-direction" scenarios.
+
+    Subclasses supply:
+    - ``QUESTION_TYPES``: a list of ``QuestionType`` instances.
+    - ``load_records()``: returns a list of data dicts.
+    - (optional) ``filter(record, q_type)``: return False to skip a
+      particular record × question-type combination.
+
+    ``DataPlugin`` auto-generates problem IDs, routes all five abstract
+    methods, and exposes ``_resolve(problem_id) -> (record, q_type)`` for
+    subclasses that need custom ``get_expand_info`` or similar overrides.
+    """
+
+    QUESTION_TYPES: ClassVar[list[QuestionType]] = []
+
+    def load_data(self) -> None:
+        self._records = self.load_records()
+        self._problem_map: dict[str, tuple[dict, QuestionType]] = {}
+        for i, record in enumerate(self._records):
+            for qt in self.QUESTION_TYPES:
+                if self.filter(record, qt):
+                    pid = f"{i}__{qt.label}"
+                    self._problem_map[pid] = (record, qt)
+
+    def load_records(self) -> list[dict[str, Any]]:
+        """Override to return a list of data records from workspace_dir."""
+        raise NotImplementedError
+
+    def filter(self, record: dict, q_type: QuestionType) -> bool:
+        """Override to exclude some record × question-type combos."""
+        return True
+
+    def _resolve(self, problem_id: str) -> tuple[dict, QuestionType]:
+        return self._problem_map[problem_id]
+
+    # -- BaseRecitePlugin interface -----------------------------------------
+
+    def get_all_problem_ids(self) -> list[str]:
+        return list(self._problem_map.keys())
+
+    def render_statement(self, problem_id: str) -> str:
+        record, qt = self._resolve(problem_id)
+        return f"【{qt.label}】 {qt.statement(record)}"
+
+    def check_answer(self, problem_id: str, user_input: str) -> bool:
+        record, qt = self._resolve(problem_id)
+        return qt.matcher(record, user_input.strip())
+
+    def get_expected_display(self, problem_id: str) -> str:
+        record, qt = self._resolve(problem_id)
+        return qt.answer(record)
+
+    def get_expand_info(self, problem_id: str) -> str:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# FlashcardPlugin – zero-boilerplate front/back flashcard
+# ---------------------------------------------------------------------------
+
+
+class FlashcardPlugin(DataPlugin):
+    """Plug-and-play flashcard-style plugin.
+
+    Point ``DATA_FILE`` at a CSV (columns ``front``, ``back``) or JSON
+    (list of ``{"front": ..., "back": ...}`` objects) in the workspace
+    directory.  All five plugin methods are handled automatically.
+
+    Example::
+
+        class Plugin(FlashcardPlugin):
+            DATA_FILE = "words.csv"
+    """
+
+    DATA_FILE: str = ""
+
+    def load_data(self) -> None:
+        path = os.path.join(self.workspace_dir, self.DATA_FILE)
+        if path.endswith(".csv"):
+            with open(path, encoding="utf-8", newline="") as f:
+                self._records = list(csv.DictReader(f))
+        elif path.endswith(".json"):
+            with open(path, encoding="utf-8") as f:
+                self._records = json.load(f)
+        else:
+            raise ValueError(
+                f"Unsupported DATA_FILE format: {self.DATA_FILE!r}. "
+                "Expected .csv or .json"
+            )
+
+        qt = QuestionType(
+            label="闪卡",
+            statement=lambda r: str(r.get("front", "")),
+            answer=lambda r: str(r.get("back", "")),
+            matcher=Matchers.exact("back"),
+        )
+
+        self._problem_map: dict[str, tuple[dict, QuestionType]] = {}
+        for i, record in enumerate(self._records):
+            self._problem_map[str(i)] = (record, qt)

src/core/scheduler.py

@@ -0,0 +1,44 @@
+import heapq
+import random
+
+from .state import StateManager
+
+
+class Scheduler:
+    def __init__(self, problem_ids: list[str], state_manager: StateManager):
+        self.problem_ids = problem_ids
+        self.state_manager = state_manager
+        self.q_queue = []
+        self._init_queue()
+
+    def _calculate_weight(self, problem_id: str) -> float:
+        stats = self.state_manager.get_stats(problem_id)
+        ac_count = stats["ac_count"]
+        total_count = stats["total_count"]
+        total_ac_time = stats["total_ac_time"]
+
+        ac_ratio = ac_count / total_count if total_count > 0 else 0
+        avg_time = total_ac_time / ac_count if ac_count > 0 else 10.0
+
+        # Smart weight: higher ac_count & ratio -> lower weight (less likely)
+        # Higher avg_time -> higher weight
+        return random.random() - ac_count - 10.0 * ac_ratio + avg_time
+
+    def _init_queue(self):
+        for pid in self.problem_ids:
+            weight = self._calculate_weight(pid)
+            # heapq is a min-heap, so we push negative weight to pop the max weight
+            heapq.heappush(self.q_queue, (-weight, pid))
+
+    def next_problem(self) -> str:
+        """Returns the ID of the next problem to display."""
+        if not self.q_queue:
+            return None
+        _, pid = heapq.heappop(self.q_queue)
+        return pid
+
+    def update_problem(self, problem_id: str, is_ac: bool, time_spent: float):
+        """Updates the state and pushes the problem back into the queue."""
+        self.state_manager.update_stats(problem_id, is_ac, time_spent)
+        weight = self._calculate_weight(problem_id)
+        heapq.heappush(self.q_queue, (-weight, problem_id))

src/core/state.py

@@ -0,0 +1,62 @@
+import os
+import sqlite3
+from typing import Any
+
+
+class StateManager:
+    def __init__(self, pack_id: str):
+        self.pack_id = pack_id
+        # ~/.muninn/states/
+        self.state_dir = os.path.expanduser(os.path.join("~", ".muninn", "states"))
+        os.makedirs(self.state_dir, exist_ok=True)
+
+        self.db_path = os.path.join(self.state_dir, f"{pack_id}.db")
+        self.conn = sqlite3.connect(self.db_path)
+        self._init_db()
+
+    def _init_db(self):
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS problem_stats (
+                problem_id TEXT PRIMARY KEY,
+                ac_count INTEGER DEFAULT 0,
+                total_count INTEGER DEFAULT 0,
+                total_ac_time REAL DEFAULT 0.0
+            )
+        """)
+        self.conn.commit()
+
+    def get_stats(self, problem_id: str) -> dict[str, Any]:
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "SELECT ac_count, total_count, total_ac_time FROM problem_stats WHERE problem_id = ?",
+            (problem_id,),
+        )
+        row = cursor.fetchone()
+        if row:
+            return {"ac_count": row[0], "total_count": row[1], "total_ac_time": row[2]}
+        return {"ac_count": 0, "total_count": 0, "total_ac_time": 0.0}
+
+    def update_stats(self, problem_id: str, is_ac: bool, time_spent: float):
+        stats = self.get_stats(problem_id)
+
+        new_total_count = stats["total_count"] + 1
+        new_ac_count = stats["ac_count"] + (1 if is_ac else 0)
+        new_total_ac_time = stats["total_ac_time"] + (time_spent if is_ac else 0.0)
+
+        cursor = self.conn.cursor()
+        cursor.execute(
+            """
+            INSERT INTO problem_stats (problem_id, ac_count, total_count, total_ac_time)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(problem_id) DO UPDATE SET
+                ac_count = excluded.ac_count,
+                total_count = excluded.total_count,
+                total_ac_time = excluded.total_ac_time
+        """,
+            (problem_id, new_ac_count, new_total_count, new_total_ac_time),
+        )
+        self.conn.commit()
+
+    def close(self):
+        self.conn.close()

src/main.py

@@ -0,0 +1,91 @@
+import argparse
+import sys
+import traceback
+
+from src.cli.manager import PackageManager
+from src.cli.runner import GameRunner
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Muninn - The Extensible Reciting CLI")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Command: new
+    parser_new = subparsers.add_parser("new", help="Create a new plugin template")
+    parser_new.add_argument("pack_id", type=str, help="The ID/name of the new pack")
+    parser_new.add_argument(
+        "--dir", type=str, default=".", help="Directory to create the template in"
+    )
+
+    # Command: install
+    parser_install = subparsers.add_parser(
+        "install", help="Install a pack from a directory or zip file"
+    )
+    parser_install.add_argument(
+        "path", type=str, help="Path to the pack directory or .zip file"
+    )
+
+    # Command: uninstall
+    parser_uninstall = subparsers.add_parser(
+        "uninstall", help="Uninstall a previously installed pack"
+    )
+    parser_uninstall.add_argument(
+        "pack_id", type=str, help="The ID of the pack to uninstall"
+    )
+
+    # Command: list
+    subparsers.add_parser("list", help="List all installed packs")
+
+    # Command: run
+    parser_run = subparsers.add_parser("run", help="Run a reciting pack")
+    parser_run.add_argument("pack_id", type=str, help="The ID of the pack to run")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    manager = PackageManager()
+
+    if args.command == "new":
+        try:
+            manager.create_template(args.pack_id, args.dir)
+        except Exception as e:  # noqa: BLE001
+            print(f"❌ Failed to create template: {e}")
+
+    elif args.command == "install":
+        try:
+            manager.install_pack(args.path)
+        except Exception as e:  # noqa: BLE001
+            print(f"❌ Failed to install pack: {e}")
+
+    elif args.command == "uninstall":
+        try:
+            manager.uninstall_pack(args.pack_id)
+        except Exception as e:  # noqa: BLE001
+            print(f"❌ Failed to uninstall pack: {e}")
+
+    elif args.command == "list":
+        packs = manager.list_packs()
+        if not packs:
+            print("No packs installed yet. Use 'muninn install <path>' to add one.")
+        else:
+            print(f"=== Installed Packs ({len(packs)}) ===")
+            for p in packs:
+                print(
+                    f"- {p.get('id')} (v{p.get('version')}): {p.get('name')} by {p.get('author')}"
+                )
+
+    elif args.command == "run":
+        try:
+            plugin = manager.load_plugin(args.pack_id)
+            runner = GameRunner(args.pack_id, plugin)
+            runner.run()
+        except Exception as e:  # noqa: BLE001
+            print(f"❌ Failed to run pack '{args.pack_id}': {e}")
+            traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

src/ui.py

@@ -0,0 +1,47 @@
+import os
+
+
+class TerminalUI:
+    @staticmethod
+    def clear_screen():
+        os.system("cls" if os.name == "nt" else "clear")
+
+    @staticmethod
+    def wait_any_key():
+        input("按回车键继续...")
+
+    @staticmethod
+    def print_cyan(text: str):
+        print(f"\033[36;1m{text}\033[0m")
+
+    @staticmethod
+    def print_green(text: str):
+        print(f"\033[32m{text}\033[0m")
+
+    @staticmethod
+    def print_yellow(text: str):
+        print(f"\033[33;1m{text}\033[0m")
+
+    @staticmethod
+    def print_success_banner(time_spent: float):
+        print(f"\n\033[42;37;1m Accepted \033[0m 耗时: {time_spent:.2f} 秒")
+
+    @staticmethod
+    def print_error_banner():
+        print("\n\033[41;37;1m Wrong Answer \033[0m")
+
+    @staticmethod
+    def print_stats_banner(
+        distinct_ac: int,
+        total_problems: int,
+        ac_count: int,
+        total_count: int,
+        combo: int,
+        avg_time: float,
+    ):
+        print(
+            f"掌握题数: {distinct_ac} / {total_problems}\t"
+            f"总正确率: {ac_count} / {total_count}\t"
+            f"Combo: {combo}\t"
+            f"平均用时: {avg_time:.2f}s\n"
+        )