Awesome-LLM-Research-Collections

Imported from BrenchCC/Awesome-LLM-Research-Collections (AGENTS.md). Install upstream with npx skills add BrenchCC/Awesome-LLM-Research-Collections. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This repository is documentation-first, bilingual, and website-enabled. The primary maintained content is the paired paper catalog in README.md, README.zh-CN.md, the Quarto paper pages under papers/en/ and papers/zh/, the notes section, and the blogs catalog.

• README.md: primary Markdown catalog and taxonomy.
• README.zh-CN.md: Chinese catalog with the same papers, Chinese descriptions, and localized link labels.
• _quarto.yml: Quarto website configuration and navigation.
• index.qmd, zh/index.qmd: generated bilingual homepage entry surfaces for Papers, Notes, and Blogs.
• papers/en/index.qmd, papers/zh/index.qmd: generated bilingual paper overview pages.
• papers/en/*.qmd, papers/zh/*.qmd: generated bilingual paper category pages.
• data/blog_shares.json: source data for curated blogs.
• blogs/en/index.qmd, blogs/zh/index.qmd: generated bilingual blogs website pages.
• assets/favicon.svg: local SVG site icon and visual identity source.
• assets/icons/: local SVG resource icons for paper/project/code/model links.
• styles.css: shared Quarto website styling for homepage, overview, notes, blogs, and paper pages.
• scripts/check_readme_qmd_sync.py: bilingual sync checker and qmd regeneration helper.
• scripts/sync_blog_shares.py: blogs README and Quarto page generator/checker.
• scripts/sync_feishu_wiki.py: GitHub-to-Feishu bilingual Wiki converter and incremental synchronizer.
• scripts/feishu_wiki_sync/: modular Feishu synchronizer implementation for models, content conversion, lark-cli access, planning, execution, and CLI orchestration.
• tests/test_feishu_wiki_*.py: split tests for Feishu conversion, manifests, planning, recovery, retries, concurrency, and deletion boundaries.
• .github/workflows/feishu-wiki-sync.yml: push, manual, and daily Feishu Wiki synchronization workflow.
• docs/feishu-wiki-sync.md: Feishu permissions, setup, operation, recovery, and key rotation runbook.
• docs/feishu-wiki-sync-code-guide.md: code ownership guide for the Feishu synchronizer modules, data flow, invariants, and test split.
• LICENSE: project license.
• .codex/, .claude/, .omc/, .omx/: local tooling metadata; do not edit unless your change is tooling-related.

When contributing papers, update the matching sections in both README files, keep both contents lists aligned with heading changes, then regenerate and verify both language versions of the Quarto pages.

When contributing blogs, update data/blog_shares.json, then regenerate and verify the generated README blog sections and blogs/ index pages.

The homepage is generated by scripts/check_readme_qmd_sync.py. It must remain a three-entry hub for Papers, Notes, and Blogs, while the paper category and recent-paper browsing surface lives in papers/en/index.qmd and papers/zh/index.qmd.

Topic Classification

Use the following boundary consistently for papers and notes:

• agents covers agent concepts, system design, evaluation, and application analysis. It is for material that explains how agents are organized or used, and normally excludes training methods.
• reinforcement-learning covers reinforcement-learning training, including reasoning RL and Agentic RL. Put material about rollouts, reward construction, policy optimization, trajectory data, token-level masks or log probabilities, and credit assignment here, even when the training target is an agent.

When a topic spans both areas, classify it by its main question: agent behavior or application belongs to agents; how an agent is trained with reinforcement learning belongs to reinforcement-learning.

Shared Generated README Safety

README.md and README.zh-CN.md are shared generated surfaces. Paper, Notes, and Blogs workflows all read or write portions of them.

• Generators must preserve sections and Contents entries owned by other generators.
• Keep Notes / 笔记 immediately before Blogs / 博客 in # Contents / # 目录.
• Generator writes must be idempotent: running the same generator twice must produce no second diff.
• After any generator writes either README, rerun all shared README checks in CI order:

python scripts/check_readme_qmd_sync.py
python scripts/sync_blog_shares.py
quarto render --no-execute

• If either checker reports README drift, run that generator with --write, then restart the full check sequence. Do not stop after the first generator passes.

Feishu Wiki Mirror

GitHub main is the only source of truth for the managed private Wiki space Awesome LLM Research Collections. The production mirror is already initialized and reuses the selected existing Feishu application; do not recreate the space, replace the application, or repeat membership setup during routine content work.

• Papers are generated from the bilingual README catalogs, notes from notes/en/ and notes/zh/, and blogs from data/blog_shares.json.
• Reader-facing introductions must describe the page's subject and purpose only; never lead with synchronization warnings or implementation details. Put source path and source commit in the neutral document-information footer. Manual edits to managed Feishu page bodies can still be overwritten on the next apply.
• The homepage contains the versioned ownership manifest. Never edit its manifest JSON manually, claim nodes by title alone, or delete unknown/unmanaged nodes.
• --check performs local conversion validation only. --plan reads Wiki nodes, the manifest, and candidate Docx information without writing. --apply uses up to 4-way read concurrency, up to 2-way body-write concurrency for different documents, keeps structure and homepage writes serialized, and commits the completed manifest last.
• Use lark-cli 1.0.86 and rsvg-convert for local remote operations. Follow docs/feishu-wiki-sync.md instead of guessing CLI parameters or recovery steps.
• Read docs/feishu-wiki-sync-code-guide.md before refactoring the synchronizer or splitting tests into multiple files.
• Remote commands require LARKSUITE_CLI_APP_ID, LARKSUITE_CLI_APP_SECRET, LARKSUITE_CLI_BRAND=feishu, and FEISHU_WIKI_SPACE_ID. Never print, commit, or pass the App Secret as a command-line argument.
• GitHub Actions expects Secrets FEISHU_APP_ID and FEISHU_APP_SECRET, plus Variable FEISHU_WIKI_SPACE_ID.
• Relevant pushes to main run apply; UTC cron 0 4 * * * targets 12:00 Asia/Shanghai; workflow_dispatch accepts plan or apply. Local unpushed changes do not trigger synchronization.
• For a manual remote update, first run the Sync Feishu Wiki workflow with plan, inspect the diff, then rerun it with apply. Push and scheduled runs always use apply.
• The equivalent CLI trigger is gh workflow run feishu-wiki-sync.yml --ref main -f mode=plan; change the mode to apply only after reviewing the plan run.
• Manifest v2 records obj_edit_time for non-home pages to support the no-op fast path; v1 manifests are migrated during apply with a light remote audit.
• Synchronization intentionally uses bounded read and body-write concurrency plus transient retries. Duplicate titles, corrupt manifests, moved managed nodes, revision conflicts, and unknown children fail closed.

When changing the synchronizer or any mirrored content, include these checks as appropriate:

python -m unittest discover -s tests -v
python scripts/sync_feishu_wiki.py --check

Build, Test, and Development Commands

Use lightweight checks before committing:

• rg --files - quick file inventory.
• rg -n "^#|^##|^- \\*\\*" README.md - inspect heading and paper-entry structure.
• python scripts/check_readme_qmd_sync.py --write - regenerate English and Chinese qmd pages from both README files.
• python scripts/check_readme_qmd_sync.py - verify all qmd pages match the bilingual README sources.
• python scripts/sync_notes.py --write - regenerate README notes sections and bilingual notes index pages.
• python scripts/sync_notes.py - verify generated notes content is in sync.
• python scripts/check_note_attachments.py - validate explicitly authorized TeX/PDF note downloads and bilingual attachment alignment.
• python scripts/sync_blog_shares.py --write - regenerate README blog sections and bilingual blog index pages.
• python scripts/sync_blog_shares.py - verify generated blog content is in sync.
• python -m unittest discover -s tests -v - run the Feishu Wiki synchronizer test suite.
• python scripts/sync_feishu_wiki.py --check - validate all local content conversions without contacting Feishu.
• quarto render - render the website into _site/.
• git diff -- README.md README.zh-CN.md index.qmd papers zh blogs data assets _quarto.yml styles.css scripts - review intended content edits.
• git log --oneline -n 10 - check recent commit style.

Local Tooling Configuration

Before running Python commands, check .codex/project.local.json for a conda_env value. If it exists, use that environment with conda run -n <conda_env> python ... and do not ask for the environment name again. If the file is missing or the value is empty, ask for the Conda environment before executing Python.

The local config file is intentionally git-ignored because it may contain machine-specific settings.

Coding Style & Naming Conventions

Markdown and qmd consistency are the core style requirements.

• Keep heading hierarchy stable (# for top sections, ## for subsections).
• Use existing paper entry format consistently: title, date (YYYY.MM), concise description, and links.
• Keep paper titles in official English wording in both README files.
• Use **Description** and English link labels in README.md; use **描述** and Chinese link labels (论文, 项目, 代码) in README.zh-CN.md.
• Preserve ordering rules within sections (newer papers first unless section policy says otherwise).
• Keep Quarto pages synchronized with both README files by running the sync script after paper edits.
• Keep the generated homepage focused on the three collection entries; do not reintroduce direct paper lists there.
• Keep paper-category browsing and recent-paper lists on the generated paper overview pages.
• Use two dates in note front matter: date is the immutable creation date and controls newest-created-first ordering; date-modified is the latest source-modification date. Set both to the current Asia/Shanghai date for a new bilingual note pair. On later edits, preserve date and update date-modified in both paired notes before regenerating indexes.
• Note downloads are opt-in per bilingual note pair and may be enabled only when the user explicitly requests downloadable attachments. File presence alone is never authorization: list each requested local .pdf or .tex file in both resources and other-links, keep normalized paths and order aligned across the language pair, and localize only the link labels.
• Do not add global download globs, automatically scan attachment directories, or expose downloads in README/Notes index cards. Unless requested, preserve the original attachment bytes and do not translate, duplicate, rebuild, or replace TeX/PDF files. Preserve previously authorized links during unrelated edits unless the user asks to remove them.
• The Feishu mirror may emit attachment resources only from that same explicit resources plus other-links authorization. GitHub Actions validates this metadata and packages only authorized files; it must not infer downloads from repository contents.
• Keep blogs in data/blog_shares.json with exact fields: slug, date, title_en, title_zh, description_en, description_zh, blog_url, github_url.
• Blogs sort by date descending through scripts/sync_blog_shares.py; do not hand-edit generated Blogs sections.
• Leave github_url empty when a blog has no official linked GitHub repository.
• Keep README command snippets environment-agnostic (python ... / pip ...), not Conda-specific.
• Avoid unrelated reformatting or whitespace-only churn.

Math Rendering Is Target-Specific

Do not reuse display-math delimiters mechanically between GitHub Markdown and Quarto source files. The two rendering targets require different syntax.

• In Quarto .qmd files, write display formulas with $$ delimiters:

  $$
  y = f(x)
  $$

• Do not use fenced math blocks in .qmd files. Quarto renders ```math as <pre class="math"><code>...</code></pre>, which displays the LaTeX source as a code block instead of typesetting it.

• In GitHub-targeted .md files such as README.md and README.zh-CN.md, continue to use fenced math blocks rather than multi-line $$ blocks.

• In formulas for either target, use \mathrm{...} instead of \operatorname{...}, and use \lt / \gt instead of raw < / > operators.

• If one generator emits both .md and .qmd, it must generate target-specific math syntax rather than copying the same delimiters to both outputs.

After changing formulas in .qmd files, render the site and inspect the generated HTML:

quarto render --no-execute
rg -n '<pre class="math"' _site
rg -n 'class="math display"' _site

The first scan must return no matches for intended display formulas. The second scan should find one rendered math display element per display formula. A successful Quarto command alone is insufficient: fenced math blocks can compile without warnings while still rendering incorrectly.

Testing Guidelines

The Feishu Wiki synchronizer has an automated unittest suite; catalog and generated-site review still relies on the content checks below:

• Verify links are canonical and point to paper/project/code roots.
• Ensure the paper is placed in the best-matching category/subcategory in both languages.
• Confirm both # Contents / # 目录 match actual headings after edits.
• Confirm python scripts/check_readme_qmd_sync.py passes.
• Confirm edited English and Chinese note pairs have matching creation date and date-modified values, with only date-modified updated for later revisions.
• Confirm python scripts/sync_notes.py passes after note edits.
• Confirm python scripts/check_note_attachments.py passes after adding, changing, or removing note downloads.
• Confirm python scripts/sync_blog_shares.py passes after blog edits.
• Confirm homepage stats are refreshed by rerunning python scripts/check_readme_qmd_sync.py --write after note or blog generator writes.
• Confirm both shared README checks pass after any Notes, Blogs, paper catalog, Contents, or generator change.
• Confirm python -m unittest discover -s tests -v and python scripts/sync_feishu_wiki.py --check pass after synchronization code or conversion changes.
• Use --plan before any local --apply; a successful local test run does not replace checking the real GitHub Actions and remote Wiki result.
• Confirm quarto render --no-execute succeeds before pushing website changes.

GitHub Pages deploys through .github/workflows/quarto-gh-pages.yml using GitHub Actions artifacts. Do not commit _site/ or .quarto/.

Commit & Pull Request Guidelines

Follow Conventional Commits seen in project history:

• Preferred types: docs, chore, style.
• Example: docs: add <paper title> to reinforcement learning section.

For PRs, include:

• What changed (sections touched).
• Why the placement is correct (classification rationale).
• Any taxonomy updates (new category/subcategory and bilingual contents updates).
• Whether bilingual Quarto pages were regenerated and rendered successfully.
• For blog changes, whether scripts/sync_blog_shares.py --write and the check command were run.

Keep PRs focused and small; one paper batch per PR is preferred.