Moonweave-Research/ref-verify

ref-verify — 참고문헌 환각 방지 도구

이 스킬이 방지하는 특정 오류 유형: LLM이 논문 내용을 실제 초록이 말하는 내용이 아니라 학습 데이터에서 기억한 내용으로 설명합니다. 논문에 없는 결과가 논문에 있다고 인용되거나, 본문 어디에도 나타나지 않는 주장이 인용됩니다. 해결책은 일관된 규칙 하나입니다:

논문에 관한 모든 내용 주장은 실시간으로 가져온 출처(최상위/헤드라인 주장은 초록, 메커니즘/구현/절차 주장은 전문)에서 인용하거나 직접 의역해야 합니다. 필요한 출처를 가져올 수 없으면 그 사실을 명시적으로 말하고, 절대 기억에 의존한 설명으로 빈틈을 메우지 마십시오. 주제만 맞는 초록 일치를 메커니즘 수준 주장의 증거로 사용하지 마십시오.

---

모드 결정

작업을 시작하기 전에 모드를 선택하십시오. 선택은 비용과 깊이를 결정합니다.

사용자가 DOI를 제공하여 검증을 요청?
  └─ ≤10개 참고문헌 → 모두 Quick Screen
  └─ >10개 참고문헌 → 모두 Quick Screen; MISMATCH/DEAD 결과만 Full Audit

사용자가 "X에 관한 논문 찾아줘" 또는 "주장 Y를 뒷받침하는 논문 인용해줘"라고 말함?
  └─ Full Audit (처음부터 검색하는 경우 내용 검증 필요)

사용자가 "내 참고문헌 목록 확인해줘" 또는 제출 전 감사를 요청?
  └─ ≤5개 참고문헌 → 모두 Full Audit
  └─ >5개 참고문헌 → 먼저 모두 Quick Screen; MISMATCH/DEAD + 특정 사실 주장을 위해 인용된 참고문헌은 Full Audit

사용자가 글을 쓰는 중에 기억에서 단일 인용을 추가?
  └─ 최소 Quick Screen; 특정 주장을 위해 인용하는 경우 Full Audit

비용이 많이 드는 부분은 Full Audit(5계층, 출처 깊이 증거 수집)입니다. Quick Screen은 논문당 약 5초가 소요됩니다. 작업이 진정으로 내용 검증을 요구할 때만 Full Audit으로 전환하십시오.

---

실행 엔진

이것을 스킬 수준의 워크플로우로 사용하십시오. 이 경로를 위해 MCP를 구축하거나 요구하지 마십시오. CLI는 스킬이 터미널에서 호출할 수 있는 실행 엔진입니다. 수동 프로토콜은 여전히 대체 수단이자 CLI가 아직 다루지 않는 계층의 진리 원천(source of truth)으로 남아 있습니다.

CLI 사용 가능 여부 확인

DOI 기반 검사를 시작하기 전에 실행 엔진을 사용할 수 있는지 확인하십시오:

ref-verify --help

npx skills add는 Python CLI를 pip 설치하지 않습니다. 콘솔 스크립트를 사용할 수 없으면 이를 검증 결과로 처리하지 마십시오.

콘솔 스크립트를 사용할 수 없지만 저장소 소스가 있으면 다음을 사용하십시오:

PYTHONPATH=src python3 -m ref_verify.cli --help

두 명령어가 모두 실패하면 아래의 수동 대체 프로토콜을 따르십시오. CLI가 실행되었다고 가장하지 말고, 기억에서 결과를 지어내지 마십시오.

CLI 우선 워크플로우

사용자가 DOI를 제공하거나 DOI 기반 초록이 특정 사실 주장을 뒷받침하는지 물을 때 CLI를 먼저 사용하십시오. 현재 CLI 범위는 CrossRef 메타데이터 검증과 DOI 기반 초록 주장 확인입니다. 주장 확인은 CrossRef를 먼저 사용하고, CrossRef에 초록이 없으면 DOI 기반 OpenAlex, Semantic Scholar, PubMed 대체 소스를 사용합니다.

CrossRef 메타데이터 검사:

ref-verify verify-doi <doi> \
  --title "<제공된 제목>" \
  --first-author <제공된 첫 번째 저자 성> \
  --year <제공된 연도> \
  --json

소스 체크아웃 대체:

PYTHONPATH=src python3 -m ref_verify.cli verify-doi <doi> \
  --title "<제공된 제목>" \
  --first-author <제공된 첫 번째 저자 성> \
  --year <제공된 연도> \
  --json

verify-doi는 PASS인 경우에만 종료 코드 0을 반환합니다. WARN 및 REJECT는 0이 아닌 값을 반환합니다. DOI만 제공하면 CrossRef 확인이 가능하지만 메타데이터 검증을 통과하기에는 충분하지 않습니다.

결과를 처리하십시오:

• PASS: 메타데이터 일치를 보고한 후, 선택한 모드에 필요한 경우 Layer 4 DOI 랜딩 페이지 확인 및 Layer 5 철회 확인을 계속 진행합니다.
• WARN: 누락되거나 약한 메타데이터를 보고한 후, 참고문헌을 묵인하지 않고 누락된 계층에 대한 수동 대체를 계속합니다.
• REJECT: 해당 인용을 검증된 것으로 사용하지 마십시오. 불일치를 보고하고 사용자에게 수정된 DOI 또는 인용을 요청합니다(사용자가 명시적으로 대안을 원하지 않는 경우).

DOI 초록에 대한 단일 주장 확인:

ref-verify check-claim <doi> --claim "<특정 사실 주장>" --json

소스 체크아웃 대체:

PYTHONPATH=src python3 -m ref_verify.cli check-claim <doi> --claim "<특정 사실 주장>" --json

기본적으로 check-claim은 CrossRef를 먼저 사용합니다. CrossRef에 초록이 없으면 DOI 기반 OpenAlex, Semantic Scholar, PubMed 대체 소스를 시도합니다. --source crossref, --source openalex, --source semantic-scholar, 또는 --source pubmed를 사용하여 소스별 디버깅을 할 수 있습니다. 명시적으로 CrossRef가 아닌 소스를 선택하면 CrossRef를 건너뛰므로 OpenAlex, Semantic Scholar 또는 PubMed 실패를 격리할 수 있습니다.

결과를 처리하십시오:

• ACCEPT: CLI 증거를 인용하고 필요한 경우 수동 DOI 확인, 두 번째 소스 존재 확인 및 철회 계층을 계속 진행합니다.
• WARN 또는 PARTIAL: 선택한 초록 소스가 지원한 내용과 지원하지 않은 내용을 보고한 후, 더 많은 계층이 필요한 경우 수동 대체를 계속합니다.
• UNVERIFIABLE: 시도한 CLI 소스에서 신뢰할 수 있는 DOI 기반 초록 증거를 사용할 수 없었습니다. 주장을 기각되거나 지지된 것으로 처리하지 말고 아래의 수동 대체 체인을 계속합니다.

CLI ACCEPT는 초록 수준의 증거일 뿐입니다. 주장이 메커니즘, 구현 또는 절차를 설명하는 경우 그 결과를 Full Audit 판결로 승격시키지 마십시오. Layer 3에서 주장을 분류하고 먼저 필요한 전문 증거를 확보하십시오.

JSON 출력의 경우 abstract_source, source_attempts 및 error_code를 사용하여 다음 단계를 결정하십시오:

• CLAIM_SUPPORTED: 명시적인 초록 지원이 발견됨.
• CLAIM_NOT_EXPLICIT: 초록은 있었지만 주장이 명시적으로 지원되지 않음.
• CLAIM_AMBIGUOUS: 숫자 증거나 맥락이 존재하지만 연결이 모호함.
• NO_ABSTRACT: 시도한 DOI 기반 소스가 초록 텍스트를 제공하지 않음.
• DOI_NOT_FOUND: 선택한 소스가 DOI 기반 레코드를 찾지 못함.
• DOI_MISMATCH: 기본 또는 명시적으로 선택한 DOI 기반 레코드가 요청된 DOI와 일치하지 않음.
• SOURCE_API_ERROR, SOURCE_TIMEOUT, SOURCE_RATE_LIMITED, SOURCE_UNSUPPORTED: 소스 조회 실패, 시간 초과, 속도 제한 또는 사용 불가.

CLI는 Layer 4 DOI 랜딩 페이지 확인, 두 소스 존재 확인 또는 철회 확인을 대체하지 않습니다. 선택한 모드에 필요한 경우 해당 계층에 대한 수동 프로토콜을 계속하십시오.

---

Quick Screen — 메타데이터 + DOI 정합성 확인

사용자가 DOI 또는 전체 인용을 제공하고 정합성 확인을 원할 때 사용합니다.

1. CrossRef 접속: https://api.crossref.org/works/{DOI}
2. 반환된 제목 + 첫 번째 저자 성을 사용자가 제공한 것과 비교
3. https://doi.org/{DOI} 가져오기 — 확인 및 올바른 논문으로 연결되는지 확인
4. 참고문헌당 한 줄씩 보고:

Smith et al. (2021) 10.1234/example — PASS (제목/저자 일치, DOI 확인)
Jones (2019) 10.5678/other — MISMATCH (CrossRef: Jones & Lee 2019, Jones 단독 아님)
Kim (2023) 10.9999/fake — DEAD DOI

다음 경우 Full Audit으로 전환: DOI가 다른 논문으로 연결, 필드 불일치, 또는 사용자가 특정 사실 주장을 위해 인용하는 경우.

---

Full Audit — 문헌 검색 또는 제출 전 검사용

다음 경우 사용: 주장을 뒷받침할 논문을 검색하거나 최종 인용 검사를 수행할 때.

논문당 다섯 개의 계층을 모두 실행하십시오. 계층은 포착하는 내용에 따라 정렬되어 있습니다. 건너뛰지 마십시오.

Layer 1 — 존재 확인

두 개의 소스를 독립적으로 검색:

• CrossRef: https://api.crossref.org/works?query.bibliographic={제목+저자}&rows=5
• Semantic Scholar: https://api.semanticscholar.org/graph/v1/paper/search?query={제목+저자}&fields=title,authors,year,externalIds,abstract&limit=5
• arXiv(사전 출판본): https://export.arxiv.org/api/query?search_query=ti:{제목}&max_results=3

논문은 제목이 본질적으로 일치하고 두 소스에서 첫 번째 저자의 성이 일치하는 경우에만 확인됩니다.

• 두 소스 일치 → CONFIRMED
• 한 소스 → SINGLE-SOURCE ⚠ — 주의하여 진행, 출력에 표시
• 영 → NOT FOUND ✗ — 중단, 명확히 보고, 대체품을 지어내지 마십시오.

Layer 2 — 메타데이터

확인된 소스에서 추출하여 비교: 제목, 모든 저자(성), 연도, 저널 전체 이름, DOI, 권/페이지(없는 경우 [NOT IN SOURCE] 표시). 필드가 소스 간에 다르면 둘 다 표시하십시오. 조용히 하나를 선택하지 마십시오.

Layer 3 — 내용 추적 가능성 ← 가장 중요한 계층

이 스킬의 핵심 가치가 여기에 있습니다. 목표는 "이 논문이 존재하는가"가 아니라 "이 논문이 실제로 인용되는 주장을 포함하는가"입니다.

Step 0 — 주장 분류.

가져오기를 시작하기 전에 확인할 주장의 종류를 분류하십시오:

• 최상위/헤드라인 주장 — 초록이 일반적으로 밝히는 종류의 발견(전체 결과, 최상위 숫자, 일반 결론). 초록 전용 증거는 이 클래스의 진정한 정보 원천입니다.
• 메커니즘/구현/절차 주장 — 무언가가 어떻게 작동하거나 수행되었는지 설명: 특정 메커니즘, 알고리즘, 아키텍처, 매개변수, 실험 단계, 제어 조건, 또는 요약 결과가 아니라 표/그림/방법 섹션에 연결된 숫자 값. 초록은 논문이 이를 뒷받침하더라도 일상적으로 이 내용을 생략합니다. 신호 단어: "메커니즘," "방법," "아키텍처," "알고리즘," "구현," "절차," "프로토콜," "매개변수," "대조군," "절제," "표," "그림," 또는 한 문단 요약이 말할 수 있는 것보다 더 구체적인 모든 주장.

주장이 메커니즘/구현 클래스인 경우, 초록만 확인하는 것으로는 충분하지 않습니다(초록이 주제와 관련이 있더라도). 초록을 존재/주제 일치의 증거로 가져오되, 초록만으로 판결을 내리지 마십시오 — 아래 Layer 3b로 계속 진행하십시오.

다음 우선 순위로 초록을 가져오십시오:

1. CrossRef raw JSON: https://api.crossref.org/works/{DOI} — abstract 필드 확인
2. OpenAlex: https://api.openalex.org/works/doi:{DOI}?mailto={연락처_이메일} — abstract_inverted_index 재구성
3. Semantic Scholar: S2 DOI 조회에 &fields=abstract 추가
4. 오픈 액세스 대체: https://api.unpaywall.org/v2/{DOI}?email={연락처_이메일} — is_oa 및 oa_locations 확인
5. 사전 출판본을 위한 arXiv 대체: https://export.arxiv.org/api/query?id_list={arxiv_id}
6. 생명/생물학 논문을 위한 PubMed Central: https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/

연락처 이메일이 필요한 API의 경우 {연락처_이메일}을 구성에 있는 실제 사용자 승인 주소로 바꾸십시오. 플레이스홀더 주소를 보내지 마십시오.

가져온 후 확인: 초록이 인용되는 특정 주장을 포함합니까?

• 초록이 명시적으로 주장을 포함(그대로 인용) → CONTENT: SUPPORTED
• 초록이 주제와 관련이 있지만 특정 주장을 하지 않음 → CONTENT: PARTIAL — 실제 내용 인용
• 초록이 주장과 모순됨 → CONTENT: CONTRADICTED — 이 인용 사용 금지
• 모든 소스를 시도했지만 초록에 접근 불가 → CONTENT: UNVERIFIABLE — 사용자가 전문 확인 필요
• 주장이 메커니즘/구현 클래스이고 Layer 3b의 모든 소스를 시도했지만 전문을 얻을 수 없음 → CONTENT: ABSTRACT-ONLY — 전문 없음, 검증 불충분. 이 레이블은 절대 SUPPORTED/ACCEPT로 업그레이드되어서는 안 됩니다.

완화할 수 없는 규칙: 논문이 "보여준다" 또는 "입증한다" 또는 "보고한다"를 설명하는 경우, 필요한 깊이로 가져온 소스 텍스트를 인용하거나 직접 의역해야 합니다. 자신이 있다고 느껴도 기억에서 요약하는 것은 허용되지 않습니다.

Layer 3b — 전문 확인 (메커니즘/구현/절차 주문만 해당)

Step 0에서 주장을 메커니즘/구현/절차 클래스로 분류했거나, 초록 판결이 초록 요약 수준보다 더 구체적인 주문에 대해 PARTIAL인 경우에 필요합니다. 초록에서 직접 CONTENT: SUPPORTED를 받은 최상위 주문만 건너뜁니다.

다음 우선 순위로 논문 본문을 가져오고 첫 번째 성공에서 중단하십시오:

1. 로컬 Zotero PDF — Zotero 라이브러리가 구성된 경우, 데이터베이스에서 이 DOI를 쿼리하고 첨부 파일 키를 확인한 후 연결된 PDF를 읽습니다. 일반적인 기본값은 ~/Zotero/zotero.sqlite이며 첨부 파일은 ~/Zotero/storage/{key}/ 아래에 있습니다. 가정하지 말고 실제 경로를 찾으십시오.
2. research-wiki 저장소 — research-wiki 스킬을 사용할 수 있는 경우, 구성된 저장소에서 이미 수집된 전문 복사본을 검색합니다. 시스템별 저장소 경로를 가정하지 마십시오.
3. 오픈 액세스 링크 — 실제 전문(가용성 플래그만이 아니라)을 확인하고 가져옵니다:
   • Unpaywall: https://api.unpaywall.org/v2/{DOI}?email={연락처_이메일} → best_oa_location.url_for_pdf(또는 모든 oa_locations[]의 url_for_pdf)를 가져옵니다.
   • arXiv: https://export.arxiv.org/api/query?id_list={arxiv_id} → <summary> 필드뿐만 아니라 전체 논문을 가져옵니다.
4. 실패 — 위의 어떤 방법도 읽을 수 있는 전문을 제공하지 못하면 초록을 충분한 것으로 처리하지 마십시오. 위에서 정의한 CONTENT: ABSTRACT-ONLY 레이블을 적용하십시오.

전문을 얻은 경우, 주장을 지원, 부분 지원 또는 모순하는 구절을 인용하십시오. 메커니즘/구현 주장의 경우 CONTENT: SUPPORTED는 전문 인용이 필요합니다. 초록 수준의 주제 일치로는 만족할 수 없습니다.

Layer 4 — DOI 확인

https://doi.org/{DOI}를 가져오십시오. 랜딩 페이지가 예상 논문과 일치하는지 확인하십시오. 봇 차단(403)으로 인해 제목과 권을 포함한 URL 슬러그에서 발생한 경우는 끊어진 링크가 아닙니다. 유료화된 것으로 표시하십시오. 관련 없는 페이지로 리디렉션되는 것은 심각한 실패입니다.

Layer 5 — 철회 확인

"{첫 번째 저자 성}" "{저널 이름}" 철회를 검색하고 DOI 랜딩 페이지에서 철회 배너를 확인하십시오. 철회된 논문은 주요 출처로 사용되어서는 안 됩니다.

---

출력 형식

Quick Screen: 참고문헌당 한 줄(위 참조).

Full Audit: 논문당 하나의 카드, 그 다음 요약 표.

참고문헌 감사
────────────────────────────────────────────────
논문:   [실시간 출처의 제목 — 기억이 아님]
DOI:     [DOI] — [✓ 확인 | ✗ 끊어짐 | ✗ 잘못된 논문 | ⚠ 유료화-403]
저자: [전체 저자 목록…]