nsfc-report-downloader

name

nsfc-report-downloader

description

General downloader for public NSFC (National Natural Science Foundation of China, kd.nsfc.cn) final/conclusion project reports. Use when the user asks to download, batch download, save, or merge 国家自然科学基金结题报告, 成果报告, finalDetails reports, or image-format report pages by keyword, project detail URL, or project ID. Produces raw page images, one PDF per project, metadata JSON, URL JSON, and a merged PDF.

NSFC Report Downloader

Use this skill to download public NSFC final/conclusion reports from https://kd.nsfc.cn and merge image-format report pages into PDFs.

Use The Script

Run the bundled script from the current workspace. Prefer a task-specific output folder under output/pdf/.

Keyword search:

python "C:\Users\Administrator\.codex\skills\nsfc-report-downloader\scripts\download_nsfc_reports.py" "榛子" --output "output/pdf/nsfc_reports_榛子"

Single detail URL:

python "C:\Users\Administrator\.codex\skills\nsfc-report-downloader\scripts\download_nsfc_reports.py" --url "https://kd.nsfc.cn/finalDetails?id=6119577a10db3ed34a44ce65900fe3fe" --output "output/pdf/nsfc_reports_one"

Known project detail ID:

python "C:\Users\Administrator\.codex\skills\nsfc-report-downloader\scripts\download_nsfc_reports.py" --id "6119577a10db3ed34a44ce65900fe3fe" --output "output/pdf/nsfc_reports_one"

Multiple known IDs or URLs:

python "C:\Users\Administrator\.codex\skills\nsfc-report-downloader\scripts\download_nsfc_reports.py" --id "ID1" --id "ID2" --output "output/pdf/nsfc_reports_batch"

Outputs

• projects.json: detected/downloaded project metadata.
• <ratifyNo>_<projectTitle>_final_report.pdf: one PDF per project.
• NSFC_final_reports_merged.pdf: all downloaded report pages merged in processing order.
• images/<ratifyNo>/page_###.jpg: raw page images.
• <ratifyNo>_urls.json: report image URLs returned by the NSFC API.

Workflow

1. Use the script for normal requests. Do not manually reimplement the CDP/API/retry/PDF logic unless debugging.
2. Choose the input mode:
   • keyword when the user gives a topic, name, unit, approval number, or general query;
   • --url when the user gives a finalDetails URL;
   • --id when the user gives a finalDetails?id=... value.
3. Use --max-projects when the keyword is broad.
4. After completion, verify page counts with Python/Fitz or another PDF reader.
5. When pdftoppm is available, render at least the first, middle, and last page of the merged PDF.
6. Report the output paths, number of projects, and page counts to the user.

Browser Requirement

Keyword search requires a browser because the NSFC search page is a Vue app and project detail IDs are exposed in runtime state. The script will:

• connect to Chrome/Edge remote debugging port 9222 if available;
• otherwise launch Chrome/Edge with --remote-debugging-port=9222 using tmp/nsfc_chrome_profile;
• navigate to https://kd.nsfc.cn/finalSearchList?s=<keyword>;
• extract project IDs and metadata from resultsData.

Direct --id and --url downloads do not need the browser search step.

If a browser is already open on another CDP port:

python "C:\Users\Administrator\.codex\skills\nsfc-report-downloader\scripts\download_nsfc_reports.py" "榛子" --port 9223

Dependencies

Required Python packages:

python -m pip install requests websocket-client pillow

For page-count validation, fitz/PyMuPDF is useful if installed. For rendering validation, use Poppler:

pdftoppm -png -f 1 -l 1 "output/pdf/nsfc_reports/NSFC_final_reports_merged.pdf" "tmp/nsfc_check/first"

Options

• --output DIR: output directory.
• --max-projects N: limit number of report-bearing projects.
• --max-pages N: safety cap for pages per report; default 160.
• --port N: Chrome/Edge CDP port for keyword search; default 9222.
• --keep-browser: fail if CDP is unavailable instead of launching a browser.

Site Behavior And Limits

The NSFC report image server may temporarily return 503 during rapid downloads. The script includes throttling and retries. A 404 page image is treated as the end of a report because the API can return a next image URL that is not actually available.

Do not bypass login, CAPTCHA, paywalls, or access controls. If the public page stops serving the report or requires interactive verification, stop and tell the user what happened.