sjqsgg/paperwise/paperwise

/paper — Academic Paper Workflow

Default Config

Edit this section to customize for your project.

output_dir: "./papers"
# Obsidian vault users: set paper_output_dir in your project's CLAUDE.md
# Drive/OneDrive: use the appropriate MCP, then set path (e.g. "gdrive://My Drive/Papers")
 
venues: [CHI, ACL, EMNLP, NAACL, NeurIPS, ICML, ICLR, EDM, LAK, AIED, ITS, CSCW, SIGIR, CIKM]
 
keywords:
  - cognitive load
  - adaptive learning
  - intelligent tutoring
  - conversational learning
  - LLM tutoring
  - learning analytics
  - behavioral signals
  - educational dialogue
 
min_citations: 5      # /paper find: filter out papers with fewer citations
daily_max: 10         # /paper digest: max papers per run
 
annotation_lang: zh   # zh = Chinese annotations | en = English; override with --lang
 
openalex_email: ""    # Optional. Add email to join OpenAlex Polite Pool (higher rate limits).
semantic_scholar_api_key: ""  # Optional. Free key: semanticscholar.org/product/api

Override any config value in your project's CLAUDE.md using keys: paper_output_dir, paper_venues, paper_keywords, paper_annotation_lang.

Subcommands

Flags:

• --context "ML课第3周" — override project context
• --questions "Q1:... Q2:..." — switch to Question mode (Mode A)
• --questions — interactive question mode (Claude asks you)
• --output /path/ — override output directory for this run
• --top N — return N results (default: 5 for find, daily_max for digest); also accepts bare number after query
• --lang en — override annotation language for this run
• --source arxiv — search only arxiv (latest preprints, no citation filter)
• --source venues — search only papers from config venues list (citation-weighted ranking)
• --local /path/ — read local PDFs from folder (no API calls); or --local a.pdf b.pdf for specific files

Flags can be written with or without `--`. Claude accepts natural language equivalents (e.g. `top 5`, `source venues`, `local /path/`, `questions "..."`).

Context Resolution (in priority order)

1. --context flag in command
2. Current directory's CLAUDE.md (auto-loaded by Claude Code)
3. No context → use Mode B directly (zero-config, logic analysis mode)

Data Sources

Primary: OpenAlex

Free, no API key required, 10 req/s rate limit.

https://api.openalex.org/works?search={query}
  &select=title,authorships,publication_year,cited_by_count,primary_location,doi
  &per-page=20
  [&mailto={openalex_email}  ← add if configured]

After fetching: immediately extract and keep only — title, first author, year, cited_by_count, venue name (primary_location.source.display_name), DOI. Discard all other fields from the response before further processing.

Secondary: Semantic Scholar (only if semantic_scholar_api_key is set)

https://api.semanticscholar.org/graph/v1/paper/search?query={topic}
  &fields=title,authors,year,citationCount,venue,externalIds&limit=20

Header: x-api-key: {semantic_scholar_api_key}

Tertiary: arxiv (fallback + digest source)

https://export.arxiv.org/api/query?search_query=(cat:cs.CL+OR+cat:cs.HC+OR+cat:cs.AI+OR+cat:cs.LG)
  +AND+({keywords})&sortBy=submittedDate&sortOrder=descending&max_results=30

Note: arxiv papers have no citation count. Label as preprint.

Rate Limit Handling

If a source returns 429: check Retry-After header → wait that many seconds. If no header: wait 2s → 5s → 10s (3 retries). After 3 failures → skip source, move to next in priority. Note which source was skipped in output.

Subcommand: find

1. Parse flags: topic query, --top N (default: 5), --lang, --source (default: mixed), --local (path or file list)

• --top N also accepts a bare number immediately after the query string (e.g. /paper find "query" 10 → top 10)

1. Resolve source strategy:

`--local` and `--source` are mutually exclusive. If both are given, return an error.

1. If `--local` flag present — execute local PDF steps instead of steps 3–6:
2. Scan the given folder for all .pdf files, or use the explicitly listed files directly
3. If file count > --top N, take first N (alphabetical order)
4. For each PDF, extract: title, authors, year, abstract (first 300 words), conclusion paragraph (last 300 words)
5. Generate a Digest Card per PDF (same 4-sentence format: 研究问题 / 核心方法 / 关键发现 / 相关性)
6. Citation badge: fixed as 📄 Local PDF (no OpenAlex lookup)
7. Card bottom link: /paper read /absolute/path/to/file.pdf 精读 (use absolute path)
8. Save to: {output_dir}/FindResults/find-local-YYYY-MM-DD-HHmm-{folder-slug}.html
9. Print summary and exit — skip steps 4–8 below

3b. Fetch papers (online mode):

• Add &filter=cited_by_count:>{min_citations} for default/venues mode (skip for arxiv)
• After fetch: immediately discard all fields except title, first author, year, cited_by_count, venue name, DOI
• On any source failure → follow Rate Limit Handling

1. Deduplicate against existing files:

• Check {output_dir}/FindResults/ and {output_dir}/ root for [FirstAuthor-YYYY-slug].html
• Mark existing papers as [已有], include in summary with their path, skip card generation

1. Rank top N using the formula for the active source strategy

1. Generate Digest HTML — a single self-contained HTML file containing N paper cards.

Digest Card format (one card per paper): `` [Title] — [First Author] et al., [Year] — [Venue or arXiv] [Citation badge] [Source tag] 研究问题: [1 sentence — what problem does this paper solve?] 核心方法: [1 sentence — what approach do they use?] 关键发现: [1 sentence — what is the main result?] 相关性: [1 sentence — why this matters for your research, based on CLAUDE.md context] [DOI link if available] · → /paper read <doi_or_path> 精读 ``

• Citation badge uses tier logic from Paper Quality Bar section
• Annotation language for cards follows annotation_lang config (or --lang flag)
• HTML structure: simple cards layout, embed references/template.css in <style>

1. Save Digest HTML to: {output_dir}/FindResults/find-YYYY-MM-DD-HHmm-{query-slug}.html

• Create subdirectory automatically if it doesn't exist

1. Print summary:

``` Found N papers via {source}. Digest saved: → 30_Research/FindResults/find-2026-03-14-1430-cognitive-load-llm.html

Papers included:

• Jin-2025-llm-teachable-agent [⭐ 47 citations · CHI]
• Cai-2025-intrinsic-load [📄 preprint · arXiv]
• Klepsch-2017-two-types-icl [已有 → 30_Research/FindResults/...]

```

Subcommand: read

1. Read the PDF at provided path
2. Extract: title, authors, year, venue/journal, abstract, full text
3. Resolve mode:

• No --questions → Mode B (logic analysis)
• --questions "..." → Mode A (inline). Parse questions using these rules:
• Strip optional Q1: / Q2: etc. prefixes (they are decorative, not required)
• Split on: comma , / semicolon ; / newline / Q\d+ pattern boundaries
• Extract up to 6 questions; if more are given, take first 6 and warn the user
• Accept any of these formats:

`` "Q1: 方法? Q2: 与 baseline 比较?" ← Q-label + colon "方法?, 与 baseline 比较?" ← comma-separated "方法?; 与 baseline 比较?" ← semicolon-separated ``

• --questions (no argument) → Mode A (interactive):

Output exactly: 请输入你的阅读问题（每行一个，或逗号分隔，最多6个）： Wait for user input, then parse using the same rules above, then proceed with Mode A

1. Resolve annotation language: --lang flag > annotation_lang config
2. Generate full dual-column HTML annotation (see HTML Template section)

• Paper Quality Bar: omit (no citation data from local PDF unless found in text)

1. Save to {output_dir}/[FirstAuthorLastName-YYYY-keyword].html

• Write directly to path; do not ls the directory beforehand

1. Output: file path + brief summary of key arguments found

Subcommand: digest

1. Check cache: if {output_dir}/PaperDigests/YYYY-MM-DD-digest.html exists today → skip fetch, output cached path
2. Fetch arxiv: same URL as Data Sources section above
3. Filter: keep top daily_max most relevant to config keywords (semantic match on title+abstract)
4. Deduplicate: skip arxiv IDs seen in previous 7 days' digests
5. Annotate: for each paper, run Mode B annotation (brief version); annotation language follows config
6. Combine: all annotations → single HTML digest file; each paper has a compact Paper Quality Bar
7. Save: {output_dir}/PaperDigests/YYYY-MM-DD-digest.html
8. Update daily note: append to 10_Daily/YYYY-MM-DD.md:

`` ## Paper Digest → [[30_Research/PaperDigests/YYYY-MM-DD-digest|Today's Paper Digest]] (N papers) ``

Subcommand: cite

1. Parse note name from user input (e.g., [[Klepsch-2017-annotation]] or file path)
2. Find HTML or MD file in {output_dir}/ or vault root
3. Extract metadata: title, authors, year, venue, DOI/URL
4. Output directly (no file saved):

• APA 7th: Author, A., & Author, B. (Year). Title. *Venue*, *vol*(issue), pages. https://doi.org/...
• BibTeX:

``bibtex @article{key, author = {...}, title = {...}, journal = {...}, year = {...}, doi = {...} } ``

HTML Annotation Template

Paper Quality Bar (find/digest only — between navbar and section-nav)

Shows: {source_icon} {source} | {venue} | {year} | {citation_badge} | {venue_type_tag}

Citation tiers:

Venue type tag: A* 会议 (top venues: CHI/NeurIPS/ACL/EMNLP/ICML/ICLR/SIGIR/CSCW) | 会议/期刊 (other config venues) | Workshop | Preprint

Source icon: 🔍 OpenAlex | 📚 Semantic Scholar | 📄 arXiv

CSS: see references/template.css (.quality-bar, .badge-*, .qb-* classes).

Mode B: Logic Analysis (Default)

Generate a complete, self-contained HTML file. CSS: embed references/template.css as <style> in <head>. Google Fonts: import Lora + IBM Plex Sans.