check-your-advisor 0.2.0__tar.gz

check_your_advisor-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AschoofAlpha
+
+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.

check_your_advisor-0.2.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: check-your-advisor
+Version: 0.2.0
+Summary: Read what PubMed records about a researcher and report it back as facts with denominators — first-author slots, time to a first slot, turnover, byline position. 查导师：把发表记录读成带分母的事实，不替你下结论。
+Author: AschoofAlpha
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AschoofAlpha/check-your-advisor
+Project-URL: Repository, https://github.com/AschoofAlpha/check-your-advisor
+Project-URL: Issues, https://github.com/AschoofAlpha/check-your-advisor/issues
+Project-URL: Chinese README, https://github.com/AschoofAlpha/check-your-advisor/blob/main/README.zh-CN.md
+Keywords: pubmed,advisor,graduate-school,bibliometrics,research-integrity,scientometrics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdf
+Requires-Dist: PyMuPDF>=1.23; extra == "pdf"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: all
+Requires-Dist: PyMuPDF>=1.23; extra == "all"
+Requires-Dist: openpyxl>=3.1; extra == "all"
+Dynamic: license-file
+
+# Check Your Advisor
+
+*[中文说明](README.zh-CN.md)*
+
+You are choosing a PhD or master's advisor. You have a name, a lab page written
+by the lab, and no way to check any of it. This reads what PubMed records about
+that person and reports it back as facts with denominators.
+
+**It does not tell you whether the advisor is good.** That judgement stays
+yours. What it does is replace hearsay with counts that carry the population
+they were counted over.
+
+```bash
+python scripts/run.py harvest --author "Wang Wei" --orcid 0000-0002-1825-0097 \
+    --years-back 10 --output-dir ./record --no-download
+python scripts/run.py cite    --output-dir ./record
+python scripts/run.py profile --pi-name "Wang Wei" --output-dir ./record
+```
+
+Three commands, one HTML report. Nothing to install: the standard library only.
+
+## What it answers
+
+- who has appeared in this group over the window
+- who the first-author slots went to, and how concentrated they are
+- how long a newcomer waits before getting one
+- how long people stay before they stop appearing
+- where the PI sits in their own bylines — last, corresponding, or doing the work
+- how much comes out per year, and whether it goes to the same few journals
+- citation counts and an h-index, with the coverage they were computed over
+- one composite score out of 100, with every component's raw input printed
+
+And, once you supply a table it cannot fetch: what those journals are rated in
+the edition you looked them up in, and **how many people finished a degree here
+without a single indexed paper** — the one group every other number is blind to.
+
+## What it refuses, and why the distinction matters
+
+Four different things stand behind "it does not say whether the advisor is
+good", and the report keeps them apart on the page:
+
+| | Examples | Why |
+|---|---|---|
+| **Computed** | citation counts, h-index, composite score, rank, star band | measurements, printed with denominators |
+| **Refused** | percentile, quantile, letter grade, fitted trend, any ordering of *people* | a decision — see below |
+| **Waiting on a file** | impact factor, JCR quartile, CAS partition, graduate roster | licensed or defended databases; the tool ships schemas, not a crawler |
+| **Never visible** | lab culture, whether the PI is decent, people who left before finishing | in no database at all |
+
+A percentile is not withheld here, it is *uncomputable*: nothing in the
+calculation ever holds more than the few corpora on one page, so there is no
+reference population to take a position in. Letter grades are refused while
+star bands are produced — that split between two coarsenings of one number is a
+decision, and the report says so rather than leaving it looking like an
+oversight.
+
+## The corpus decides everything
+
+Every number is computed over the papers `harvest` kept. If papers by a
+different person with the same name get in, the roster, the time-to-first-author
+and the turnover figures are all wrong — and wrong in a way that looks perfectly
+normal on the page.
+
+**Give `harvest` at least one unique identifier.** In descending order of
+strength:
+
+| Flag | Strength |
+|---|---|
+| `--orcid 0000-0002-...` | Strongest. One is worth all the rest |
+| `--email-domain your-university.edu.cn` | The corresponding author's address. Repeatable |
+| `--affiliation-keyword "..."` | Weakest — it fails on same-name colleagues inside one university system |
+
+The report **refuses to render** if the harvest recorded no evidence at all
+(gate G3). But the dangerous case passes that gate: weak evidence produces a
+complete, normal-looking report about several people. A real run for one Chinese
+surgeon, keyed on a province name rather than the full institution, returned 28
+records spanning gastrointestinal surgery, analytical chemistry, structural
+biology, soil microbiology and machine learning — and scored 78.2 out of 100.
+
+**Section 19 is the check for that.** It removes the PI, who is on every record
+by construction, and asks which records are still tied together by a shared
+co-author. One person's output is held together by the people they work with;
+two people sharing a name have no reason to share anyone else. It applies no
+threshold — the measurements do not support one, and the README of a tool like
+this should not pretend otherwise — it prints the clusters and their journals
+and hands the reading to you. It is usually not subtle.
+
+## Two tables you fill in by hand
+
+Impact factor, JCR quartile and CAS partition live in licensed products with no
+free redistributable source. Degree-thesis libraries defend against scraping.
+So this ships the schema, the worklist and the join, and no crawler:
+
+```bash
+python scripts/run.py journal-worklist --output-dir ./record
+```
+
+That writes a CSV holding **only the journals this corpus actually uses** —
+typically a couple of dozen, not the twenty thousand in the world — pre-filled
+with ISSN and paper count, indicator columns blank. Fill it from whichever
+source you have access to, then:
+
+```bash
+python scripts/run.py profile --output-dir ./record \
+    --journal-table ./record/journal_worklist_*.csv \
+    --thesis-roster ./record/theses.csv
+```
+
+Two columns are **required** in the journal table: `版本来源` (which edition —
+official, rising-star, folk, or JCR) and `数据获取日期`. Without them a
+partition number is unfalsifiable two years from now. Where a journal has rows
+from two editions, both are shown and neither wins; disagreements are listed.
+
+The graduate roster is the more important of the two. Export the advisor's
+supervised theses from a degree library and it produces the number PubMed
+structurally cannot: **how many graduates have no indexed paper at all.** Add a
+romanised-name column or the Chinese roster will not match the English bylines.
+Note that people who enrolled and left before finishing are in no library
+either — the roster narrows the missing group, it does not close it.
+
+## Install
+
+As a Claude Code skill:
+
+```bash
+git clone https://github.com/AschoofAlpha/check-your-advisor.git \
+    ~/.claude/skills/check-your-advisor
+```
+
+Or run it directly as a CLI from anywhere — `scripts/run.py` is the single
+entry point and needs no installation.
+
+## Optional extras
+
+Both degrade with a tested fallback; neither is required.
+
+- **PyMuPDF** (AGPL-3.0, so deliberately not a hard dependency of an MIT
+  project) lets PDF identity validation quarantine a wrong file. Without it
+  every download is still checked for the `%PDF-` magic.
+- **openpyxl** enables the `.xlsx` export. Without it the same data is written
+  as a timestamped CSV.
+
+## Tests
+
+```bash
+python tests/run_all.py
+python tests/run_all.py --block-third-party
+```
+
+1925 assertions across 19 files. The second run installs an import hook that
+blocks `requests`, `urllib3`, `pandas`, `numpy`, `matplotlib`, `fitz` and
+`openpyxl` inside each test process. It is the only thing that keeps "no install
+needed" true rather than merely claimed: exactly three assertions behave
+differently without them, and all three are the cases that need a real PDF file.
+
+## Known limitations
+
+- The report is in English; the command-line logs are in Chinese. Not a decision
+  anyone would defend — it is where the tool grew up, and unifying it is open.
+- `cite` has no cache of its own. `--max-age-days N` reuses counts from the
+  previous run's file, which is the workaround.
+- Journal name matching falls back to a token heuristic for corpora harvested
+  before ISSN capture existed. Re-harvest to get the exact join.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Citation counts come from OpenAlex, Semantic Scholar and Europe PMC, none of
+which requires a key. Bibliographic records come from NCBI E-utilities. This
+project ships no licensed data.

check_your_advisor-0.2.0/README.md

@@ -0,0 +1,170 @@
+# Check Your Advisor
+
+*[中文说明](README.zh-CN.md)*
+
+You are choosing a PhD or master's advisor. You have a name, a lab page written
+by the lab, and no way to check any of it. This reads what PubMed records about
+that person and reports it back as facts with denominators.
+
+**It does not tell you whether the advisor is good.** That judgement stays
+yours. What it does is replace hearsay with counts that carry the population
+they were counted over.
+
+```bash
+python scripts/run.py harvest --author "Wang Wei" --orcid 0000-0002-1825-0097 \
+    --years-back 10 --output-dir ./record --no-download
+python scripts/run.py cite    --output-dir ./record
+python scripts/run.py profile --pi-name "Wang Wei" --output-dir ./record
+```
+
+Three commands, one HTML report. Nothing to install: the standard library only.
+
+## What it answers
+
+- who has appeared in this group over the window
+- who the first-author slots went to, and how concentrated they are
+- how long a newcomer waits before getting one
+- how long people stay before they stop appearing
+- where the PI sits in their own bylines — last, corresponding, or doing the work
+- how much comes out per year, and whether it goes to the same few journals
+- citation counts and an h-index, with the coverage they were computed over
+- one composite score out of 100, with every component's raw input printed
+
+And, once you supply a table it cannot fetch: what those journals are rated in
+the edition you looked them up in, and **how many people finished a degree here
+without a single indexed paper** — the one group every other number is blind to.
+
+## What it refuses, and why the distinction matters
+
+Four different things stand behind "it does not say whether the advisor is
+good", and the report keeps them apart on the page:
+
+| | Examples | Why |
+|---|---|---|
+| **Computed** | citation counts, h-index, composite score, rank, star band | measurements, printed with denominators |
+| **Refused** | percentile, quantile, letter grade, fitted trend, any ordering of *people* | a decision — see below |
+| **Waiting on a file** | impact factor, JCR quartile, CAS partition, graduate roster | licensed or defended databases; the tool ships schemas, not a crawler |
+| **Never visible** | lab culture, whether the PI is decent, people who left before finishing | in no database at all |
+
+A percentile is not withheld here, it is *uncomputable*: nothing in the
+calculation ever holds more than the few corpora on one page, so there is no
+reference population to take a position in. Letter grades are refused while
+star bands are produced — that split between two coarsenings of one number is a
+decision, and the report says so rather than leaving it looking like an
+oversight.
+
+## The corpus decides everything
+
+Every number is computed over the papers `harvest` kept. If papers by a
+different person with the same name get in, the roster, the time-to-first-author
+and the turnover figures are all wrong — and wrong in a way that looks perfectly
+normal on the page.
+
+**Give `harvest` at least one unique identifier.** In descending order of
+strength:
+
+| Flag | Strength |
+|---|---|
+| `--orcid 0000-0002-...` | Strongest. One is worth all the rest |
+| `--email-domain your-university.edu.cn` | The corresponding author's address. Repeatable |
+| `--affiliation-keyword "..."` | Weakest — it fails on same-name colleagues inside one university system |
+
+The report **refuses to render** if the harvest recorded no evidence at all
+(gate G3). But the dangerous case passes that gate: weak evidence produces a
+complete, normal-looking report about several people. A real run for one Chinese
+surgeon, keyed on a province name rather than the full institution, returned 28
+records spanning gastrointestinal surgery, analytical chemistry, structural
+biology, soil microbiology and machine learning — and scored 78.2 out of 100.
+
+**Section 19 is the check for that.** It removes the PI, who is on every record
+by construction, and asks which records are still tied together by a shared
+co-author. One person's output is held together by the people they work with;
+two people sharing a name have no reason to share anyone else. It applies no
+threshold — the measurements do not support one, and the README of a tool like
+this should not pretend otherwise — it prints the clusters and their journals
+and hands the reading to you. It is usually not subtle.
+
+## Two tables you fill in by hand
+
+Impact factor, JCR quartile and CAS partition live in licensed products with no
+free redistributable source. Degree-thesis libraries defend against scraping.
+So this ships the schema, the worklist and the join, and no crawler:
+
+```bash
+python scripts/run.py journal-worklist --output-dir ./record
+```
+
+That writes a CSV holding **only the journals this corpus actually uses** —
+typically a couple of dozen, not the twenty thousand in the world — pre-filled
+with ISSN and paper count, indicator columns blank. Fill it from whichever
+source you have access to, then:
+
+```bash
+python scripts/run.py profile --output-dir ./record \
+    --journal-table ./record/journal_worklist_*.csv \
+    --thesis-roster ./record/theses.csv
+```
+
+Two columns are **required** in the journal table: `版本来源` (which edition —
+official, rising-star, folk, or JCR) and `数据获取日期`. Without them a
+partition number is unfalsifiable two years from now. Where a journal has rows
+from two editions, both are shown and neither wins; disagreements are listed.
+
+The graduate roster is the more important of the two. Export the advisor's
+supervised theses from a degree library and it produces the number PubMed
+structurally cannot: **how many graduates have no indexed paper at all.** Add a
+romanised-name column or the Chinese roster will not match the English bylines.
+Note that people who enrolled and left before finishing are in no library
+either — the roster narrows the missing group, it does not close it.
+
+## Install
+
+As a Claude Code skill:
+
+```bash
+git clone https://github.com/AschoofAlpha/check-your-advisor.git \
+    ~/.claude/skills/check-your-advisor
+```
+
+Or run it directly as a CLI from anywhere — `scripts/run.py` is the single
+entry point and needs no installation.
+
+## Optional extras
+
+Both degrade with a tested fallback; neither is required.
+
+- **PyMuPDF** (AGPL-3.0, so deliberately not a hard dependency of an MIT
+  project) lets PDF identity validation quarantine a wrong file. Without it
+  every download is still checked for the `%PDF-` magic.
+- **openpyxl** enables the `.xlsx` export. Without it the same data is written
+  as a timestamped CSV.
+
+## Tests
+
+```bash
+python tests/run_all.py
+python tests/run_all.py --block-third-party
+```
+
+1925 assertions across 19 files. The second run installs an import hook that
+blocks `requests`, `urllib3`, `pandas`, `numpy`, `matplotlib`, `fitz` and
+`openpyxl` inside each test process. It is the only thing that keeps "no install
+needed" true rather than merely claimed: exactly three assertions behave
+differently without them, and all three are the cases that need a real PDF file.
+
+## Known limitations
+
+- The report is in English; the command-line logs are in Chinese. Not a decision
+  anyone would defend — it is where the tool grew up, and unifying it is open.
+- `cite` has no cache of its own. `--max-age-days N` reuses counts from the
+  previous run's file, which is the workaround.
+- Journal name matching falls back to a token heuristic for corpora harvested
+  before ISSN capture existed. Re-harvest to get the exact join.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Citation counts come from OpenAlex, Semantic Scholar and Europe PMC, none of
+which requires a key. Bibliographic records come from NCBI E-utilities. This
+project ships no licensed data.

check_your_advisor-0.2.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "check-your-advisor"
+version = "0.2.0"
+description = "Read what PubMed records about a researcher and report it back as facts with denominators — first-author slots, time to a first slot, turnover, byline position. 查导师：把发表记录读成带分母的事实，不替你下结论。"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AschoofAlpha" }]
+keywords = [
+    "pubmed",
+    "advisor",
+    "graduate-school",
+    "bibliometrics",
+    "research-integrity",
+    "scientometrics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "Natural Language :: Chinese (Simplified)",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Text Processing :: Indexing",
+]
+
+# No `dependencies` key, and that is the point rather than an omission. Every
+# import in this package is from the standard library, and the test suite proves
+# it: `python tests/run_all.py --block-third-party` installs an import hook that
+# makes requests, urllib3, pandas, numpy, matplotlib, fitz and openpyxl
+# unimportable, and 1922 of 1925 assertions still pass. Adding a dependency here
+# would make that suite a claim nobody checks.
+
+[project.optional-dependencies]
+# Both are genuinely optional and both have a tested fallback path. PyMuPDF is
+# AGPL-3.0 and this package is MIT, which is why it is not a hard dependency:
+# without it a downloaded PDF is still checked for the `%PDF-` magic bytes, it
+# just cannot be quarantined by content. openpyxl only decides whether the
+# corpus export is .xlsx or a timestamped .csv.
+pdf = ["PyMuPDF>=1.23"]
+xlsx = ["openpyxl>=3.1"]
+all = ["PyMuPDF>=1.23", "openpyxl>=3.1"]
+
+[project.urls]
+Homepage = "https://github.com/AschoofAlpha/check-your-advisor"
+Repository = "https://github.com/AschoofAlpha/check-your-advisor"
+Issues = "https://github.com/AschoofAlpha/check-your-advisor/issues"
+"Chinese README" = "https://github.com/AschoofAlpha/check-your-advisor/blob/main/README.zh-CN.md"
+
+[project.scripts]
+check-your-advisor = "check_your_advisor.cli:main"
+
+[tool.setuptools]
+# The package lives under `scripts/` because this repository is also a Claude
+# Code skill, where `SKILL.md` sits at the root and the code sits beside it.
+# Moving the package to the root would break the skill layout; telling setuptools
+# where to look costs one line and breaks nothing.
+package-dir = { "" = "scripts" }
+packages = ["check_your_advisor", "check_your_advisor.profile"]

check_your_advisor-0.2.0/scripts/check_your_advisor/__init__.py

@@ -0,0 +1,17 @@
+"""
+check-your-advisor — author-disambiguated PubMed harvesting and reference verification.
+
+Two entry points over one shared HTTP and normalisation layer:
+
+  fetch/download  Search PubMed, keep only the target researcher's papers via
+                  ORCID + affiliation + email verification, race 8 open-access
+                  sources for the PDF, then verify the downloaded file really
+                  is the requested paper.
+
+  verify          Check a bibliography against CrossRef and PubMed, including
+                  bidirectional DOI <-> PMID resolution.
+"""
+
+__version__ = "0.3.1"
+
+__all__ = ["__version__"]

check_your_advisor-0.2.0/scripts/check_your_advisor/__main__.py

@@ -0,0 +1,8 @@
+"""Allow `python -m check_your_advisor ...`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

check_your_advisor-0.2.0/scripts/check_your_advisor/cache.py

@@ -0,0 +1,160 @@
+"""
+缓存模块（SQLite）
+==================
+替代原代码中仅通过 os.path.exists(pdf_path) 检查的简陋缓存。
+
+改进：
+- 记录每篇论文的元数据（DOI、PMID、下载状态、来源、时间）
+- 支持过期清理
+- 支持查询命中/未命中统计
+"""
+
+import logging
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+logger = logging.getLogger("check_your_advisor.cache")
+
+CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS paper_cache (
+    doi TEXT,
+    pmid TEXT,
+    title TEXT,
+    pdf_path TEXT,
+    source TEXT,
+    status TEXT DEFAULT 'pending',
+    file_size_bytes INTEGER DEFAULT 0,
+    created_at REAL,
+    updated_at REAL,
+    PRIMARY KEY (pmid)
+);
+CREATE INDEX IF NOT EXISTS idx_doi ON paper_cache(doi);
+CREATE INDEX IF NOT EXISTS idx_status ON paper_cache(status);
+"""
+
+
+class PaperCache:
+    def __init__(self, db_path: str = "paper_cache.db"):
+        self.db_path = db_path
+        db_parent = Path(db_path).parent
+        if str(db_parent) not in {"", "."}:
+            db_parent.mkdir(parents=True, exist_ok=True)
+        # check_same_thread=False 允许跨线程使用；加锁保证串行访问
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._lock = threading.Lock()
+        self._init_db()
+        self.hits = 0
+        self.misses = 0
+
+    def _init_db(self):
+        with self._lock:
+            cursor = self._conn.cursor()
+            cursor.executescript(CREATE_TABLE_SQL)
+            self._conn.commit()
+
+    def lookup(self, pmid: str) -> dict | None:
+        """查询缓存。返回 dict 或 None。"""
+        with self._lock:
+            cursor = self._conn.cursor()
+            cursor.execute("SELECT * FROM paper_cache WHERE pmid = ?", (pmid,))
+            row = cursor.fetchone()
+
+        if row and row["status"] == "downloaded" and row["pdf_path"]:
+            if Path(row["pdf_path"]).exists():
+                self.hits += 1
+                logger.debug("  缓存命中: PMID %s", pmid)
+                return dict(row)
+            else:
+                logger.warning("  缓存记录存在但文件丢失: %s", row["pdf_path"])
+                self.update(pmid, status="pending", pdf_path="")
+        self.misses += 1
+        return None
+
+    def update(self, pmid: str, **kwargs):
+        """更新或插入缓存记录"""
+        now = time.time()
+        with self._lock:
+            existing = self._conn.execute(
+                "SELECT pmid FROM paper_cache WHERE pmid = ?", (pmid,)
+            ).fetchone()
+
+            if existing:
+                sets = ", ".join(f"{k} = ?" for k in kwargs)
+                vals = list(kwargs.values()) + [now, pmid]
+                self._conn.execute(
+                    f"UPDATE paper_cache SET {sets}, updated_at = ? WHERE pmid = ?",
+                    vals,
+                )
+            else:
+                kwargs["pmid"] = pmid
+                kwargs["created_at"] = now
+                kwargs["updated_at"] = now
+                cols = ", ".join(kwargs.keys())
+                placeholders = ", ".join("?" for _ in kwargs)
+                self._conn.execute(
+                    f"INSERT INTO paper_cache ({cols}) VALUES ({placeholders})",
+                    list(kwargs.values()),
+                )
+            self._conn.commit()
+
+    def mark_downloaded(
+        self,
+        pmid: str,
+        pdf_path: str,
+        source: str,
+        file_size: int = 0,
+        doi: str = "",
+        title: str = "",
+    ):
+        self.update(
+            pmid,
+            doi=doi,
+            title=title,
+            status="downloaded",
+            pdf_path=pdf_path,
+            source=source,
+            file_size_bytes=file_size,
+        )
+
+    def mark_failed(self, pmid: str, doi: str = "", title: str = ""):
+        self.update(pmid, doi=doi, title=title, status="all_sources_failed")
+
+    def cleanup_expired(self, max_age_days: int = 90) -> int:
+        """清理超过指定天数的失败记录（下载成功的不清理）。返回删除条数。"""
+        cutoff = time.time() - max_age_days * 86400
+        with self._lock:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "DELETE FROM paper_cache WHERE status = 'all_sources_failed' AND updated_at < ?",
+                (cutoff,),
+            )
+            deleted = cursor.rowcount
+            self._conn.commit()
+        if deleted:
+            logger.info("  清理了 %d 条过期失败记录", deleted)
+        return deleted
+
+    def stats(self) -> dict:
+        with self._lock:
+            cursor = self._conn.cursor()
+            total = cursor.execute("SELECT COUNT(*) FROM paper_cache").fetchone()[0]
+            downloaded = cursor.execute(
+                "SELECT COUNT(*) FROM paper_cache WHERE status = 'downloaded'"
+            ).fetchone()[0]
+            failed = cursor.execute(
+                "SELECT COUNT(*) FROM paper_cache WHERE status = 'all_sources_failed'"
+            ).fetchone()[0]
+        return {
+            "total": total,
+            "downloaded": downloaded,
+            "failed": failed,
+            "session_hits": self.hits,
+            "session_misses": self.misses,
+        }
+
+    def close(self):
+        with self._lock:
+            self._conn.close()