canxiangcc/aminer-pdf-citation-verifier

PDF Citation Verifier

Verify whether the references in a paper PDF actually exist by submitting the PDF to the AMiner pdf-citation-verifier service, polling the asynchronous job, and returning a structured summary. Invoke via natural language or /pdf-citation-verifier.

What This Skill Does

For each reference parsed from the uploaded PDF, the upstream service queries AMiner SearchPro and labels the citation with one of:

• REAL — high-confidence match in AMiner.
• LIKELY_REAL — partial match, likely genuine.
• NEEDS_REVIEW — evidence is inconclusive; ask a human.
• LIKELY_FAKE — partial mismatch, probably fabricated.
• FAKE — no plausible match found.

Each call to the gateway returns the standard envelope {"code": 200, "success": true, "msg": "", "data": ..., "log_id": "..."}. The script unwraps it before printing.

• POST /api/v3/paper/citation/verify/upload returns data: {"job_id": "verify_..."}.
• GET /api/v3/paper/citation/result?job_id=... returns data: [<record>] where the single record has top-level fields like is_finish, has_hallucination, hallucination_ratio, total, counts_by_status, summary, urls, report, result.

The skill returns that record plus the job_id so the user can re-poll later.

File Map

• SKILL.md / SKILL.zh.md — English / Chinese skill definitions (this file).
• commands/pdf-citation-verifier.md — slash command entry.
• scripts/verify_pdf.py — HTTP client: upload → poll → print the unwrapped result record.
• requirements.txt — Python dependencies (requests).

Pre-flight

Run these checks before invoking the script. Stop and surface the error to the user if any check fails.

1. AMINER_API_KEY

[ -z "${AMINER_API_KEY+x}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"

If missing, stop and tell the user to obtain a token from https://open.aminer.cn and export AMINER_API_KEY=<token>. Never print the token value.

2. Python dependency

python3 - <<'PY'
import importlib.util
missing = [name for name in ("requests",) if importlib.util.find_spec(name) is None]
print("Missing: " + ", ".join(missing) if missing else "Python dependencies exist")
PY

If missing, instruct: pip install -r "${CLAUDE_PLUGIN_ROOT}/requirements.txt".

3. PDF input

The user must supply an existing local .pdf file path. If they only describe a paper without a file, ask them to provide the PDF path. Do not invent or download a PDF.

Execution Example

Basic verification with defaults (max 50 references, auto-polls until done):

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/verify_pdf.py" \
  --pdf "/abs/path/to/paper.pdf"

Full options:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/verify_pdf.py" \
  --pdf "/abs/path/to/paper.pdf" \
  --max-refs 80 \
  --strict \
  --timeout 900 \
  --poll-interval 5 \
  --output outputs/pdf-citation-verifier/<safe-paper-stem>/result.json

Submit-only (no polling, return job_id for later lookup):

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/verify_pdf.py" \
  --pdf "/abs/path/to/paper.pdf" --no-wait

Fetch the result for an existing job_id (no new upload):

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/verify_pdf.py" \
  --job-id verify_20260527T090207Z_a72c9ba5

Parameters

| Flag | Default | Notes | | --- | --- | --- | | --pdf | required (unless --job-id) | Local .pdf file path. Server caps body at 50 MB. | | --job-id | – | Skip upload and just fetch the result for an existing job. | | --max-refs | 50 | Server hard cap is 100. | | --strict | off | Stricter FAKE judgement on partial matches. | | --no-wait | off | With --pdf: submit and return job_id without polling. With --job-id: single fetch, return immediately without looping. | | --timeout | 600 | Overall polling timeout in seconds. | | --poll-interval | 5 | Seconds between result polls. | | --request-timeout | 120 | Per-HTTP-request timeout. | | --output | - | Optional path to also write the JSON response. |

Environment Variables

| Var | Required | Purpose | | --- | --- | --- | | AMINER_API_KEY | yes | JWT used in the Authorization header. | | PDF_CITATION_VERIFIER_BASE_URL | no | Override the gateway base URL. Defaults to https://datacenter.aminer.cn/gateway/open_platform. |

Runtime Constraints

• Never print, log, or echo the value of AMINER_API_KEY.
• Never fabricate verification verdicts. If the script fails or times out, surface the error verbatim — do not synthesize results.
• urls, report, result, pdf in the response point to server-side artifacts and may be pre-signed for url_expire_seconds. Do not claim those local paths exist on the user's machine. Use --output if the user needs a local copy of the JSON.
• Respect the per-user active job cap (server returns 429 when exceeded). If a 429 surfaces, stop and tell the user to wait for prior jobs to finish.
• Treat any LIKELY_FAKE / FAKE verdict as a flag for human review, not a final accusation. Surface counts_by_status and per-record reasons when the response includes them.

Output Presentation

After the script returns, summarize the result for the user with at minimum:

• job_id
• total (number of references verified)
• has_hallucination, hallucination_ratio
• A short table built from counts_by_status (REAL / LIKELY_REAL / NEEDS_REVIEW / LIKELY_FAKE / FAKE / etc.)
• Any urls.report / urls.result links from the response, with a note that they may expire after url_expire_seconds
• The full JSON should be either saved (via --output) or echoed back to the user, never silently dropped.

If is_finish is true and a status / msg field signals failure, report it and suggest re-running.