readloops 2.3.0__py3-none-any.whl

app/api/words.py

@@ -0,0 +1,210 @@
+"""单词路由：查词、生词本、批量添加。"""
+import time
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from app.database import get_db
+from app.services.ai import lookup_word, translate_sentence
+
+router = APIRouter(prefix="/api/words", tags=["words"])
+
+
+class AddWordRequest(BaseModel):
+    word: str
+    meaning: str = ""
+    context: str = ""
+
+
+class BatchAddRequest(BaseModel):
+    words: list[str]
+
+
+@router.get("/lookup/{word}")
+async def lookup(word: str):
+    """查询单词释义。优先本地，没有则问 AI。"""
+    result = lookup_word(word)
+    return {
+        "word": result.text,
+        "phonetic": result.phonetic or "",
+        "meaning": result.meaning or "",
+        "examples": [],
+        "in_vocab": result.id is not None,
+        "word_id": result.id,
+    }
+
+
+class TranslateRequest(BaseModel):
+    text: str
+
+
+@router.post("/translate")
+async def translate(req: TranslateRequest):
+    """翻译句子 / 短语。
+
+    划词选中多个单词时走这里 —— 词典查不到整句，
+    以前会直接显示「查询失败」。
+    """
+    translation = translate_sentence(req.text)
+    return {"text": req.text, "translation": translation, "ok": bool(translation)}
+
+
+@router.post("/add")
+async def add_word(req: AddWordRequest):
+    """添加单词到生词本。"""
+    now = int(time.time())
+    with get_db() as conn:
+        row = conn.execute("SELECT id FROM words WHERE text = ?", (req.word,)).fetchone()
+        if row:
+            word_id = row["id"]
+            conn.execute(
+                "UPDATE words SET meaning=COALESCE(NULLIF(?, ''), meaning), status='learning', updated_at=? WHERE id=?",
+                (req.meaning, now, word_id),
+            )
+        else:
+            cur = conn.execute(
+                "INSERT INTO words (lemma, text, type, meaning, level, status, created_at, updated_at) "
+                "VALUES (?, ?, 'word', ?, 'CET4', 'learning', ?, ?)",
+                (req.word, req.word, req.meaning, now, now),
+            )
+            word_id = cur.lastrowid
+    return {"word_id": word_id, "word": req.word, "status": "added"}
+
+
+@router.post("/batch-add")
+async def batch_add(req: BatchAddRequest):
+    """批量添加单词。"""
+    now = int(time.time())
+    added = 0
+    with get_db() as conn:
+        for w in req.words:
+            w = w.strip().lower()
+            if not w or not w.isalpha():
+                continue
+            existing = conn.execute("SELECT id FROM words WHERE text = ?", (w,)).fetchone()
+            if not existing:
+                conn.execute(
+                    "INSERT INTO words (lemma, text, type, level, status, created_at, updated_at) "
+                    "VALUES (?, ?, 'word', 'CET4', 'learning', ?, ?)",
+                    (w, w, now, now),
+                )
+                added += 1
+    return {"added": added, "total": len(req.words)}
+
+
+@router.get("/vocab")
+async def get_vocab(status: str = "learning", limit: int = 100):
+    """获取生词本列表。"""
+    with get_db() as conn:
+        rows = conn.execute(
+            "SELECT id, text, phonetic, meaning, level, status, encounter_count, lookup_count, created_at "
+            "FROM words WHERE status = ? ORDER BY created_at DESC LIMIT ?",
+            (status, limit),
+        ).fetchall()
+    return [
+        {
+            "id": r["id"],
+            "text": r["text"],
+            "phonetic": r["phonetic"] or "",
+            "meaning": r["meaning"] or "",
+            "level": r["level"],
+            "status": r["status"],
+            "encounter_count": r["encounter_count"],
+            "lookup_count": r["lookup_count"],
+            "created_at": r["created_at"],
+        }
+        for r in rows
+    ]
+
+
+class BatchDeleteRequest(BaseModel):
+    word_ids: list[int]
+
+
+class BatchStatusRequest(BaseModel):
+    word_ids: list[int]
+    status: str
+
+
+@router.delete("/{word_id}")
+async def delete_word(word_id: int):
+    """删除单个单词（同时删除相关的遇见记录）。"""
+    with get_db() as conn:
+        conn.execute("DELETE FROM word_encounters WHERE word_id=?", (word_id,))
+        conn.execute("DELETE FROM words WHERE id=?", (word_id,))
+    return {"status": "ok"}
+
+
+@router.post("/batch-delete")
+async def batch_delete(req: BatchDeleteRequest):
+    """批量删除单词。"""
+    with get_db() as conn:
+        for wid in req.word_ids:
+            conn.execute("DELETE FROM word_encounters WHERE word_id=?", (wid,))
+            conn.execute("DELETE FROM words WHERE id=?", (wid,))
+    return {"deleted": len(req.word_ids)}
+
+
+@router.post("/batch-status")
+async def batch_update_status(req: BatchStatusRequest):
+    """批量修改单词状态（learning/known/new/target）。"""
+    now = int(time.time())
+    with get_db() as conn:
+        for wid in req.word_ids:
+            conn.execute("UPDATE words SET status=?, updated_at=? WHERE id=?", (req.status, now, wid))
+    return {"updated": len(req.word_ids), "status": req.status}
+
+
+@router.get("/test/generate")
+async def generate_test(count: int = 20, difficulty: str = "mixed", source: str = "adaptive"):
+    """生成单词测试题。
+    source: adaptive(自适应/基于用户数据)/vocab(生词本)/target(测验词)/all(全部随机)
+    """
+    from app.services.smart_test import generate_smart_test
+    return generate_smart_test(count, source)
+
+
+@router.post("/test/{test_id}/submit")
+async def submit_test(test_id: int, word_id: int, is_correct: bool, reaction_time: int = None):
+    """提交单题测试结果。"""
+    from app.services.smart_test import submit_test_result
+    submit_test_result(test_id, word_id, is_correct, reaction_time)
+    return {"status": "ok"}
+
+
+@router.get("/test/{test_id}/report")
+async def get_test_report(test_id: int):
+    """获取测试报告。"""
+    from app.services.smart_test import get_test_report
+    return get_test_report(test_id)
+
+
+@router.post("/test/start")
+async def start_test():
+    """开始一次测试，创建测试记录。"""
+    import time
+    now = int(time.time())
+    with get_db() as conn:
+        cur = conn.execute(
+            "INSERT INTO tests (type, status, created_at) VALUES ('vocab', 'in_progress', ?)",
+            (now,)
+        )
+        test_id = cur.lastrowid
+    return {"test_id": test_id}
+
+
+@router.get("/review-due")
+async def get_review_due(limit: int = 50):
+    """获取今天到期复习的词（FSRS 驱动）。"""
+    from app.services.srs import get_due_words
+    with get_db() as conn:
+        words = get_due_words(limit=limit, conn=conn)
+    return words
+
+
+@router.get("/srs-stats")
+async def get_srs_stats():
+    """获取 FSRS 统计概览。"""
+    from app.services.srs import get_review_stats
+    with get_db() as conn:
+        return get_review_stats(conn)

app/cli.py

@@ -0,0 +1,185 @@
+"""ReadLoops 命令行入口。
+
+用法：
+    readloops              启动服务并自动打开浏览器
+    readloops serve        只启动服务（不打开浏览器）
+    readloops init         初始化数据库并检查状态
+    readloops doctor       检查运行环境是否就绪
+"""
+import argparse
+import sys
+import threading
+import webbrowser
+
+
+def _masked(key):
+    if not key:
+        return "(未设置)"
+    return key[:8] + "..." if len(key) > 8 else "***"
+
+
+def cmd_init(args):
+    """初始化数据库并报告状态。"""
+    from app import config
+    from app.database import get_db, init_db
+
+    config.DATA_DIR.mkdir(parents=True, exist_ok=True)
+    init_db()
+
+    with get_db() as conn:
+        tables = [r[0] for r in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")]
+        words = conn.execute("SELECT COUNT(*) FROM words").fetchone()[0]
+        phrases = conn.execute("SELECT COUNT(*) FROM phrases").fetchone()[0]
+
+    print("ReadLoops 初始化完成")
+    print(f"  数据目录：{config.DATA_DIR}")
+    print(f"  数据库　：{config.DB_PATH}")
+    print(f"  已建表　：{len(tables)} 张")
+    print(f"  词库　　：{words} 词")
+    print(f"  短语库　：{phrases} 条")
+
+    if words == 0:
+        print()
+        print("⚠️  词库为空，暂时无法生成文章。")
+        print("   请导入一份词表，推荐开源词典 ECDICT：")
+        print("     https://github.com/skywind3000/ECDICT")
+        print("   导入方法见 README 的「数据准备」章节。")
+    return 0
+
+
+def cmd_doctor(args):
+    """检查运行环境。"""
+    from app import config
+
+    ok = True
+    print("ReadLoops 环境检查")
+    print(f"  Python　　　：{sys.version.split()[0]}")
+
+    print(f"  数据目录　　：{config.DATA_DIR} "
+          f"{'✅' if config.DATA_DIR.exists() else '⚠️  不存在'}")
+
+    if config.DB_PATH.exists():
+        print(f"  数据库　　　：{config.DB_PATH} ✅")
+        try:
+            from app.database import get_db
+            with get_db() as conn:
+                words = conn.execute("SELECT COUNT(*) FROM words").fetchone()[0]
+            if words:
+                print(f"  词库　　　　：{words} 词 ✅")
+            else:
+                print("  词库　　　　：0 词 ⚠️  需导入词表")
+                ok = False
+        except Exception as exc:  # noqa: BLE001
+            print(f"  数据库读取失败：{exc}")
+            ok = False
+    else:
+        print(f"  数据库　　　：{config.DB_PATH} ⚠️  不存在（运行 readloops init）")
+        ok = False
+
+    corpus = config.CORPUS_DIR / "真题阅读纯文本" / "all_passages_lazynote.json"
+    print(f"  真题语料　　：{'✅ 已提供' if corpus.exists() else '— 未提供（可选，仅影响相似度匹配）'}")
+
+    try:
+        from app.database import get_db
+        with get_db() as conn:
+            row = conn.execute("SELECT value FROM settings WHERE key='ai_api_key'").fetchone()
+        print(f"  AI Key　　　：{_masked(row[0] if row else '')}")
+    except Exception:  # noqa: BLE001
+        pass
+
+    print()
+    print("结论：" + ("环境就绪 ✅" if ok else "还需完成上述 ⚠️ 项"))
+    return 0 if ok else 1
+
+
+def cmd_import_dict(args):
+    """导入词典 / 词表文件。"""
+    from app.services.dict_import import import_dictionary
+
+    print(f"导入词表：{args.path}")
+    if args.level:
+        print(f"  仅导入等级：{args.level}")
+
+    def progress(n):
+        print(f"  已导入 {n} 词...")
+
+    try:
+        result = import_dictionary(args.path, level_filter=args.level, on_progress=progress)
+    except FileNotFoundError as exc:
+        print(f"❌ {exc}")
+        return 1
+
+    from app.database import get_db
+    with get_db() as conn:
+        total = conn.execute("SELECT COUNT(*) FROM words").fetchone()[0]
+
+    print()
+    print("导入完成")
+    print(f"  识别格式　：{result['format']}")
+    print(f"  新增　　　：{result['inserted']} 词")
+    print(f"  已存在跳过：{result['skipped']} 词")
+    print(f"  词库总量　：{total} 词")
+    return 0
+
+
+def cmd_serve(args):
+    """启动服务。"""
+    import uvicorn
+
+    url = f"http://{args.host}:{args.port}"
+
+    if not args.no_browser:
+        threading.Timer(1.5, lambda: webbrowser.open(url)).start()
+
+    print(f"ReadLoops 运行于 {url}")
+    print("按 Ctrl+C 停止")
+    uvicorn.run("app.main:app", host=args.host, port=args.port, log_level="info")
+    return 0
+
+
+def _force_utf8_io():
+    """Windows 控制台默认代码页（cp1252/GBK 等）可能无法编码中文或符号，
+    统一把标准流重配置为 UTF-8，避免 UnicodeEncodeError。"""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+def main(argv=None):
+    _force_utf8_io()
+    parser = argparse.ArgumentParser(
+        prog="readloops",
+        description="ReadLoops — AI 驱动的英语阅读训练器",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_serve = sub.add_parser("serve", help="启动服务（默认命令）")
+    p_serve.add_argument("--host", default="127.0.0.1", help="监听地址（默认 127.0.0.1）")
+    p_serve.add_argument("--port", type=int, default=8000, help="端口（默认 8000）")
+    p_serve.add_argument("--no-browser", action="store_true", help="不自动打开浏览器")
+    p_serve.set_defaults(func=cmd_serve)
+
+    sub.add_parser("init", help="初始化数据库").set_defaults(func=cmd_init)
+    sub.add_parser("doctor", help="检查运行环境").set_defaults(func=cmd_doctor)
+
+    p_import = sub.add_parser("import-dict", help="导入词典 / 词表文件")
+    p_import.add_argument("path", help="文件路径（支持 ECDICT CSV/JSON、纯文本词表）")
+    p_import.add_argument("--level", help="只导入指定等级，如 CET4")
+    p_import.set_defaults(func=cmd_import_dict)
+
+    args = parser.parse_args(argv)
+
+    # 无子命令 → 默认启动服务
+    if not getattr(args, "command", None):
+        args = parser.parse_args(["serve"] + (argv or []))
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

app/config.py

@@ -0,0 +1,58 @@
+"""全局配置：路径、AI、主题。
+
+数据目录的选取规则（跨平台）：
+- 源码模式（项目根下存在 pyproject.toml）→ `<项目根>/data`，便于开发调试
+- 安装模式（pip install）→ 各系统的用户数据目录，避免写入 site-packages
+- 任何时候都可用环境变量 `READLOOPS_DATA_DIR` 覆盖
+"""
+import os
+import sys
+from pathlib import Path
+
+# 包所在目录
+PACKAGE_DIR = Path(__file__).parent
+# 上一级：源码模式下是项目根；安装模式下是 site-packages
+ROOT_DIR = PACKAGE_DIR.parent
+
+
+def _default_data_dir():
+    """按运行模式与操作系统选取可写的数据目录。"""
+    # 源码模式：项目根下有 pyproject.toml（该文件不会被安装进 site-packages）
+    if (ROOT_DIR / "pyproject.toml").exists():
+        return ROOT_DIR / "data"
+
+    # 安装模式：使用系统约定的用户数据目录
+    if sys.platform == "win32":
+        base = os.getenv("LOCALAPPDATA") or (Path.home() / "AppData" / "Local")
+        return Path(base) / "ReadLoops"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "ReadLoops"
+    # Linux / 其他 Unix
+    base = os.getenv("XDG_DATA_HOME") or (Path.home() / ".local" / "share")
+    return Path(base) / "readloops"
+
+
+# 数据目录可用环境变量覆盖（便于测试与多环境部署）
+DATA_DIR = Path(os.getenv("READLOOPS_DATA_DIR") or _default_data_dir())
+CORPUS_DIR = Path(os.getenv("READLOOPS_CORPUS_DIR") or ROOT_DIR / "语料库")
+WEB_DIR = PACKAGE_DIR / "web"
+
+DB_PATH = Path(os.getenv("READLOOPS_DB_PATH") or DATA_DIR / "yuedu.db")
+DICT_DB_PATH = DATA_DIR / "ecdict.db"
+
+# AI 配置（默认 DeepSeek）
+AI_BASE_URL = os.getenv("AI_BASE_URL", "https://api.deepseek.com")
+AI_API_KEY = os.getenv("AI_API_KEY", "")
+AI_MODEL = os.getenv("AI_MODEL", "deepseek-flash")
+
+# FSRS 配置
+FSRS_RETENTION = 0.9
+FSRS_MAX_INTERVAL = 365
+
+# 文章参数
+TARGET_WORD_COUNT = 300
+MIN_NEW_WORDS = 6
+MAX_NEW_WORDS = 15
+CALIBRATION_ARTICLES = 5
+
+DATA_DIR.mkdir(parents=True, exist_ok=True)

app/database.py

@@ -0,0 +1,204 @@
+"""数据库连接与初始化。
+
+SCHEMA 是数据库结构的**单一事实源**：全新安装由 init_db() 直接建出完整结构（10 表）。
+`tools/migrate_db_v2.py` 仅用于升级历史遗留的旧数据库，不再承担"补全结构"的职责。
+"""
+import sqlite3
+from contextlib import contextmanager
+
+from app.config import DB_PATH
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL DEFAULT '用户1',
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS words (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    lemma TEXT NOT NULL,
+    text TEXT NOT NULL,
+    type TEXT NOT NULL DEFAULT 'word',
+    meaning TEXT,
+    phonetic TEXT,
+    level TEXT DEFAULT 'CET4',
+    frequency INTEGER DEFAULT 0,
+    status TEXT DEFAULT 'new',
+    encounter_count INTEGER DEFAULT 0,
+    lookup_count INTEGER DEFAULT 0,
+    srs_due INTEGER,
+    srs_stability REAL DEFAULT 0,
+    srs_difficulty REAL DEFAULT 0,
+    srs_state INTEGER DEFAULT 0,
+    srs_lapses INTEGER DEFAULT 0,
+    srs_reps INTEGER DEFAULT 0,
+    srs_last_review INTEGER,
+    srs_interval REAL DEFAULT 0,
+    exchange TEXT,
+    wrong_count INTEGER DEFAULT 0,
+    correct_count INTEGER DEFAULT 0,
+    last_test_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS word_encounters (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    word_id INTEGER NOT NULL,
+    article_id INTEGER,
+    context TEXT,
+    action TEXT NOT NULL,
+    implicit_rating TEXT,
+    created_at INTEGER NOT NULL,
+    FOREIGN KEY (word_id) REFERENCES words(id)
+);
+
+CREATE TABLE IF NOT EXISTS articles (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    content TEXT NOT NULL,
+    source TEXT DEFAULT 'ai',
+    word_count INTEGER DEFAULT 0,
+    target_words TEXT DEFAULT '[]',
+    new_word_count INTEGER DEFAULT 0,
+    difficulty_score REAL,
+    reading_time_seconds INTEGER DEFAULT 0,
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS highlights (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    article_id INTEGER NOT NULL,
+    text TEXT NOT NULL,
+    word_id INTEGER,
+    color TEXT DEFAULT 'yellow',
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS reading_sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    article_id INTEGER NOT NULL,
+    start_time INTEGER NOT NULL,
+    end_time INTEGER,
+    duration_seconds INTEGER DEFAULT 0,
+    lookups INTEGER DEFAULT 0,
+    highlights INTEGER DEFAULT 0,
+    FOREIGN KEY (article_id) REFERENCES articles(id)
+);
+
+CREATE TABLE IF NOT EXISTS tests (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    type TEXT DEFAULT 'vocab',
+    status TEXT DEFAULT 'in_progress',
+    score INTEGER DEFAULT 0,
+    total INTEGER DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    completed_at INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS settings (
+    key TEXT PRIMARY KEY,
+    value TEXT
+);
+
+CREATE TABLE IF NOT EXISTS phrases (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    text TEXT UNIQUE NOT NULL,
+    meaning TEXT,
+    frequency INTEGER DEFAULT 0,
+    level TEXT DEFAULT 'CET4',
+    created_at INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS test_questions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    test_id INTEGER,
+    word_id INTEGER,
+    word_text TEXT,
+    question_type TEXT,
+    question TEXT,
+    options TEXT,
+    answer TEXT,
+    user_answer TEXT,
+    is_correct INTEGER,
+    reaction_time INTEGER,
+    created_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_words_status ON words(status);
+CREATE INDEX IF NOT EXISTS idx_words_level ON words(level);
+CREATE INDEX IF NOT EXISTS idx_words_lemma ON words(lemma);
+CREATE INDEX IF NOT EXISTS idx_phrases_level ON phrases(level);
+CREATE INDEX IF NOT EXISTS idx_test_questions_test_id ON test_questions(test_id);
+CREATE INDEX IF NOT EXISTS idx_test_questions_word_id ON test_questions(word_id);
+"""
+
+DEFAULT_SETTINGS = {
+    "theme": "dark",
+    "font_size": "17",
+    "line_height": "1.75",
+    "ai_base_url": "https://api.deepseek.com",
+    "ai_api_key": "",
+    "ai_model": "deepseek-flash",
+}
+
+
+# 列级迁移：为历史遗留数据库补齐 SCHEMA 中新增的列（幂等，可重复执行）
+# 背景：CREATE TABLE IF NOT EXISTS 不会改动已存在的表，导致旧库缺列、代码报
+#       "table X has no column named Y"。这里统一在启动时补齐，避免 schema 漂移。
+COLUMN_MIGRATIONS = {
+    "words": {
+        "exchange": "TEXT",
+        "wrong_count": "INTEGER DEFAULT 0",
+        "correct_count": "INTEGER DEFAULT 0",
+        "last_test_at": "INTEGER",
+        "srs_interval": "REAL DEFAULT 0",
+    },
+    "tests": {
+        "status": "TEXT DEFAULT 'in_progress'",
+        "total": "INTEGER DEFAULT 0",
+        "completed_at": "INTEGER",
+    },
+}
+
+
+def _ensure_columns(conn):
+    """补齐各表缺失的列（幂等）。"""
+    for table, columns in COLUMN_MIGRATIONS.items():
+        existing = {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
+        for name, decl in columns.items():
+            if name not in existing:
+                conn.execute(f"ALTER TABLE {table} ADD COLUMN {name} {decl}")
+
+
+def init_db():
+    """初始化数据库：建表、补齐缺失列、插入默认数据。"""
+    import time
+    now = int(time.time())
+    with get_db() as conn:
+        conn.executescript(SCHEMA)
+        _ensure_columns(conn)
+        # 默认用户
+        conn.execute("INSERT OR IGNORE INTO users (id, name, created_at) VALUES (1, '用户1', ?)", (now,))
+        # 默认设置
+        for key, value in DEFAULT_SETTINGS.items():
+            conn.execute("INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)", (key, value))
+
+
+@contextmanager
+def get_db():
+    """获取数据库连接，自动提交和关闭。"""
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    try:
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+# 模块加载时自动初始化
+init_db()