muninn-cli 0.1.1__tar.gz

muninn_cli-0.1.1/.agent/api.md

@@ -0,0 +1,193 @@
+# Muninn API 扩展规划 - 面向插件开发者的辅助层
+
+## 背景：当前问题
+
+以 `example/chemistry/plugin.py` 为例，开发者目前需要：
+
+1. 手动维护一个 `self.problems` 字典，每个 "方向" 都需要完整填写 `type`, `element`, `statement`, `expected` 字段
+2. 在 `check_answer` 中用 `if q_type == ...` 分支处理不同题型的判题逻辑
+3. 自己实现所有容错匹配（忽略大小写、空格、输入顺序等）
+4. 即使是最简单的正反面闪卡，也要实现全部 5 个抽象方法
+
+---
+
+## 目标：降低插件开发者的心智负担
+
+Muninn 的 `src/core/` 层新增一组 **辅助工具 (Helpers)**，让开发者专注于"数据"和"语义"，而不是"胶水代码"。
+
+---
+
+## 1. `QuestionType` —— 可复用的题型单元
+
+### 设计思路
+
+把"一种问答方向"抽象成一个独立的 `QuestionType` 对象。它封装了三件事：
+
+- 如何**渲染**题目（给定数据项，生成题目文本）
+- 如何**渲染**预期答案（给定数据项，生成标准答案文本）
+- 如何**判断**用户输入是否正确（使用内置的 Matcher，详见第 2 节）
+
+```python
+# 插件开发者的代码
+from core.helpers import QuestionType, Matchers
+
+# 把一种"问答方向"声明为一行
+q_num_to_element = QuestionType(
+    label="看序号背元素",
+    statement=lambda el: f"原子序数: {el['num']}",
+    answer=lambda el: f"{el['name']} {el['sym']}",
+    matcher=Matchers.chinese_symbol_pair("name", "sym"),  # 内置容错匹配
+)
+```
+
+### 注册到插件
+
+```python
+class Plugin(BaseRecitePlugin):
+    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"),
+        ),
+    ]
+```
+
+---
+
+## 2. `Matchers` —— 内置容错匹配器
+
+常见的输入容错逻辑不应该由每个插件重复实现。Muninn 提供一组开箱即用的 Matcher 工厂函数：
+
+| Matcher                                    | 说明                                             | 示例                      |
+| ------------------------------------------ | ------------------------------------------------ | ------------------------- |
+| `Matchers.exact(key)`                      | 精确匹配某字段（去除首尾空格）                   | 完全相同的字符串          |
+| `Matchers.exact_integer(key)`              | 只提取数字后精确匹配                             | `" 17 "` / `"#17"` → `17` |
+| `Matchers.case_insensitive(key)`           | 忽略大小写匹配                                   | 英文单词背诵              |
+| `Matchers.chinese_symbol_pair(key1, key2)` | 匹配"中文+符号"或"符号+中文"任意顺序，忽略空格   | `氢H` / `H氢` / `氢 H`    |
+| `Matchers.any_order(*keys)`                | 多个字段任意顺序输入，忽略分隔符                 | 周期+族 `4 IVB` / `IVB4`  |
+| `Matchers.custom(fn)`                      | 传入自定义函数 `(data_item, user_input) -> bool` | 完全自由扩展              |
+
+---
+
+## 3. `DataPlugin` —— 面向"实体+多题型"场景的高阶基类
+
+### 设计思路
+
+当一组 `QuestionType` 需要应用到一批数据上（"每条数据 × 每种题型 = 一道题"），这个模式极其常见。`DataPlugin` 是 `BaseRecitePlugin` 的子类，它自动完成 ID 生成、问题注册和方法路由，开发者只需提供：
+
+1. 数据加载逻辑 `load_records()` → 返回记录列表
+2. 题型列表 `QUESTION_TYPES`
+3. 可选的过滤器 `filter(record, q_type)` → 某条数据是否参与某种题型
+
+### 改写后的 chemistry plugin（从 87 行缩减到 ~40 行）
+
+```python
+import os
+import 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"),
+        ),
+        QuestionType(
+            label="看位置背元素",
+            statement=lambda el: f"位置: 第{el['period']}周期 {el['group']}族",
+            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: f"{el['period']} {el['group']}",
+            matcher=Matchers.any_order("period", "group"),
+        ),
+    ]
+
+    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: dict, q_type: QuestionType) -> bool:
+        """过滤掉 0 族元素的位置类题目"""
+        if q_type.label in ("看位置背元素", "看元素背位置"):
+            return record["group"] != "0"
+        return True
+
+    def get_expand_info(self, problem_id: str) -> str:
+        el, _ = self._resolve(problem_id)
+        return f"{el['eng']} ({el['sym']}, {el['name']}) - 第{el['period']}周期 {el['group']}族"
+```
+
+---
+
+## 4. `FlashcardPlugin` —— 最简单的闪卡场景
+
+对于纯粹的"正面→背面"记忆（如 GRE 单词、古诗词），提供一个更高阶的 `FlashcardPlugin`，实现 0 样板代码的目标：
+
+```python
+# flashcard 格式 CSV / JSON：每条数据有 front, back 两个字段即可
+class Plugin(FlashcardPlugin):
+    DATA_FILE = "words.csv"
+
+    # FlashcardPlugin 自动实现 load_records, get_all_problem_ids,
+    # render_statement, check_answer, get_expected_display
+    # 开发者完全不需要写任何一行额外代码（除非需要定制）
+```
+
+---
+
+## 5. 实现计划
+
+### Phase 1：`Matchers` + `QuestionType`
+
+- 在 `src/core/helpers.py` 中实现 `Matchers` 工具类和 `QuestionType` 数据类
+- 无需修改 `BaseRecitePlugin`，完全向后兼容
+
+### Phase 2：`DataPlugin`
+
+- 在 `src/core/helpers.py` 中实现 `DataPlugin(BaseRecitePlugin)` 子类
+- 将 `example/chemistry/plugin.py` 改写为 `DataPlugin` 版本作为验证
+
+### Phase 3：`FlashcardPlugin`
+
+- 支持从 CSV/JSON 自动加载 `front/back` 格式数据
+- 提供一个示例闪卡包（如 GRE 单词）验证
+
+---
+
+## 附：改动涉及文件
+
+```text
+src/
+└── core/
+    ├── base_plugin.py    # 不变
+    ├── helpers.py        # ✅ 新增：QuestionType, Matchers, DataPlugin, FlashcardPlugin
+    ├── scheduler.py      # 不变
+    └── state.py          # 不变
+
+example/
+├── chemistry/plugin.py   # ✅ 改写为 DataPlugin 版本（用于验证）
+└── flashcard/            # ✅ 新增：FlashcardPlugin 示例包
+```

muninn_cli-0.1.1/.agent/plan.md

@@ -0,0 +1,124 @@
+# Muninn - 架构设计与项目规划
+
+## 1. 核心设计理念：宿主与插件架构
+
+本项目旨在将“背诵软件”解耦为一个 **“宿主容器 (Host)”** 和若干 **“背诵包插件 (Plugins)”**。
+
+- **宿主 (CLI Framework)**：负责题目的调度算法（如按权重出题）、界面渲染、用户输入捕获、题库包的管理（导入/导出）以及进度的持久化存储。
+- **插件 (Recite Pack)**：负责定义具体的题目逻辑，包含静态数据（如元素周期表、古诗文内容）和出题/判题的 Python 脚本。
+
+这种架构能让用户自由开发、导入和导出第三方题库包，极大地提高了可扩展性。
+
+---
+
+## 2. “背诵包”的规范定义 (Package Specification)
+
+一个标准的背诵包在物理上是一个独立的文件夹，分发时可打包为 `.zip`，结构如下：
+
+```text
+chemistry/
+├── manifest.json      # 包的元数据 (包名、包ID、作者、版本、描述、当前版本哈希)
+├── data.csv           # 静态数据 (也可以是 json, yaml, sqlite 或媒体资源)
+└── plugin.py          # 核心逻辑脚本 (必须实现 CLI 规定的标准接口)
+```
+
+---
+
+## 3. 标准化 API 契约 (Plugin API Contract)
+
+所有导入的 `plugin.py` 必须提供一个继承自 `BaseRecitePlugin` 的主类。CLI 会在初始化时将专用的工作区路径 (`workspace_dir`) 传给该插件，插件需从该路径加载自己的静态数据。
+
+```python
+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 中的静态数据，由子类实现"""
+        pass
+
+    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 ""
+```
+
+---
+
+## 4. CLI 宿主的四大职责 (CLI Core Responsibilities)
+
+1. **包管理器 (Package Manager)**
+   - `new`: 在当前工作目录生成一个标准的背诵包插件模板（包含 `manifest.json`, 示例 `plugin.py` 和数据文件），方便用户快速开始自己的开发。
+   - `import`: 接收一个本地的文件夹路径或 `.zip` 压缩包，将其拷贝/解压至 `~/.muninn/packs/<pack_id>/`，并校验完整性。如果本地已经有该包的旧版本，应该覆盖为新版本。
+   - `loader`: 使用 `importlib` 动态加载包内的 `plugin.py`。
+2. **状态与存储管理器 (State Manager)**
+   - **进度隔离**：进度的存储（答对次数、耗时）绝对不能放在包的 `workspace_dir` 中，以防止导出时泄露私人数据。
+   - 所有进度集中存放在 `~/.muninn/states/<pack_id>.db`。
+3. **全局调度算法 (Global Scheduler)**
+   - 提取自当前的智能权重逻辑。接管出题顺序，在内存中维护优先队列。
+4. **统一终端 UI (Terminal UI)**
+   - 负责 ANSI 颜色输出、清屏操作、数据统计的 banner 显示及捕捉用户输入。
+
+---
+
+## 5. 工作流示例 (Workflow)
+
+当用户运行命令 `muninn run my_chemistry_pack` 时：
+
+1. **CLI 启动**：定位到 `~/.muninn/packs/my_chemistry_pack/`。
+2. **实例化插件**：初始化插件并传入 `workspace_dir`，插件完成数据加载。
+3. **初始化调度**：CLI 调用 `get_all_problem_ids()`，并从 State Manager 读取每个题目的权重，压入堆中。
+4. **游戏循环**：
+   - 调度器弹出一道题的 ID。
+   - CLI 调用 `render_statement(ID)` 打印题目。
+   - CLI 截获用户输入 `user_input`。
+   - CLI 将其传给插件：`check_answer(ID, user_input)`。
+   - 得到 True/False 后，CLI 更新权重并保存状态，打印拓展信息或标准答案。
+   - 循环往复。
+
+---
+
+## 6. 项目系统目录架构
+
+```text
+muninn/                       # 源码库目录
+├── src/                      # 核心源码
+│   ├── core/
+│   │   ├── base_plugin.py    # 插件基类 API 契约
+│   │   ├── scheduler.py      # 权重与出题队列调度算法
+│   │   └── state.py          # 学习进度持久化管理
+│   ├── cli/
+│   │   ├── manager.py        # New/Import 包管理模块
+│   │   └── runner.py         # 核心游戏循环 (整合 UI, Plugin, Scheduler)
+│   └── ui.py                 # 终端渲染与颜色控制
+└── pyproject.toml        # 使用 uv 管理依赖，打包配置，注册全局命令 'muninn'
+
+~/.muninn/                # App Data 目录 (程序运行时在用户系统生成)
+├── packs/                # 统一存放通过 import 导入的第三方题库包
+│   └── chemistry/        # 具体的包目录 (被当作 workspace_dir)
+│       ├── manifest.json
+│       ├── data.csv
+│       └── plugin.py
+└── states/               # 进度隔离存储
+    └── chemistry.db      # 记录该题库中所有题目的熟练度和学习数据
+```

muninn_cli-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: "\U0001F41E Bug Report"
+about: "报告一个问题 / Report a bug"
+labels: ["bug"]
+assignees: ["a1fredbao"]
+---
+
+## 🐛 问题描述 / Bug Description
+
+<!-- 简要描述你遇到的问题 / Briefly describe the bug -->
+
+## 📋 复现步骤 / Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## 🤔 期望行为 / Expected Behavior
+
+<!-- 描述你期望看到的正确行为 / What did you expect to happen? -->
+
+## 😱 实际行为 / Actual Behavior
+
+<!-- 描述实际发生了什么 / What actually happened? -->
+
+## 🖥️ 环境信息 / Environment
+
+- **OS**:
+- **Python version**: <!-- `python --version` -->
+- **Muninn version**: <!-- `muninn --version` or `pip show muninn` -->
+- **Pack ID** (if applicable):
+
+## 📎 错误日志 / Error Log
+
+```text
+粘贴错误信息 / Paste error output here
+```
+
+## 📝 补充信息 / Additional Context
+
+<!-- 其他你认为相关的信息 / Any other context about the problem -->

muninn_cli-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: "\U0001F680 Feature Request"
+about: "建议一个新功能 / Suggest a new feature or improvement"
+labels: ["enhancement"]
+assignees: ["a1fredbao"]
+---
+
+## 🚀 功能描述 / Feature Description
+
+<!-- 简要描述你希望增加的功能 / Briefly describe the feature you'd like -->
+
+## 💡 动机与背景 / Motivation & Context
+
+<!-- 为什么需要这个功能？它解决了什么问题？ / Why is this feature needed? What problem does it solve? -->
+
+## 🎯 建议方案 / Proposed Solution
+
+<!-- 如果你有实现思路，请描述 / If you have ideas on how to implement this, describe them -->
+
+## 🔄 替代方案 / Alternatives Considered
+
+<!-- 你是否考虑过其他解决方案？ / Have you considered any alternative solutions? -->
+
+## 📝 补充信息 / Additional Context
+
+<!-- 截图、草图、参考链接等 / Screenshots, mockups, reference links, etc. -->

muninn_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Ruff (linter)
+        run: uv run ruff check src/
+
+      - name: Run Ruff (formatter check)
+        run: uv run ruff format --check src/
+
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    needs: lint
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

muninn_cli-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

muninn_cli-0.1.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

muninn_cli-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

muninn_cli-0.1.1/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "muninn"
+    ]
+}