wiki-ingest은(는) 무엇을 하나요?
과학 지식 베이스를 위한 LLM-위키 수집 패턴을 구현합니다. 수집된 각 논문은 고립된 노트가 아닌, 추적 가능하고 축적되는 지식을 생성합니다.
첫 수집 전에, 키트(수집, 합성, 린트를 위한 운영상의 주의사항)에서
docs/GOTCHAS.md를 읽으세요.
모드
- 기본 모드 (수집):
/wiki-ingest <논문>명령으로 논문 노트를 생성하거나 업데이트하고, 개념 및 방법 노트로 전파합니다(기본 워크플로우 참조). - 검증 모드:
/wiki-ingest verify:<PaperNote>명령으로 기존 노트의 전체 텍스트를 재확인하고, 차이점만 보고하며 아무것도 재생성하거나 덮어쓰지 않습니다(references/VERIFY-DIFF-MODE.md참조). 사용자가 각 편집을 확인하지 않는 한 읽기 전용입니다.
역할 및 경계
수행하는 작업: 논문 노트 생성/업데이트, 개념 및 방법 노트로 전파, 인덱스 및 로그 업데이트, 모든 변경 사항 보고.
수행하지 않는 작업: 인용을 조작하지 않음, 단일 사용 개념에 대한 개념 노트를 생성하지 않음, 데이터베이스에 쓰지 않음. 모든 쓰기 작업은 호스트의 파일 도구(Read/Write/Edit)를 통해 이루어집니다.
파일 위치
경로는 wiki.config.json(볼트 루트, 위키 루트, 폴더 이름, 언어, 임계값)에서 가져옵니다. 기본값:
<vault_root>/
<wiki_root>/ # 기본값: wiki/
papers/ concepts/ methods/ books/ fields/ debates/
WIKI_SCHEMA.md # 프론트매터 계약, 명명 규칙, 분류 체계, 수집 프로토콜
index.md log.md
templates/ # paper.md, concept.md, method.md, book.md, chapter.md, submoc.md, synthesis.md
<kit>는 tools/(seal.py, pmc_tables.py)를 보관하는 science-wiki-kit 체크아웃을 의미합니다. 설치 프로그램이 작성한 wiki.config.json의 kit_dir 키에 그 경로가 있습니다. 누락된 경우, 스킬이 체크아웃에서 링크될 때 이 스킬의 디렉토리보다 두 폴더 위에 있습니다.
시작하기 전에 항상 WIKI_SCHEMA.md를 읽으세요. 이 파일은 이 위키의 프론트매터 계약, 명명 규칙, 분류 체계를 정의합니다.
관련 스킬
wiki-lint:wiki.config.json(인덱스 업데이트에 사용되는 케밥-케이스에서 Title Case로의 필드 맵)을 공유합니다. 각 수집 후 실행하여 드리프트가 발생하지 않았는지 확인하세요.wiki-ingest-book: 책 및 장을 위한 동반 스킬입니다. 동일한 상태 규칙과 인덱스 라우팅이 적용됩니다.wiki-synthesize: 이 스킬이 생성한 노트를 소비합니다.
초기 상태 결정 (모든 새 노트에 적용)
status를 신중히 설정하세요. 템플릿 기본값을 그대로 두지 마세요. 아래 N은 설정 파일의 min_distinct_sources_for_final(기본값 2)입니다.
| 노트 유형 | 조건 | 초기 status |
|---|---|---|
| 논문 | 초록 + 최소 2개의 출처 기반 발견 내용 추출 | read |
| 논문 | DOI/제목 메타데이터만 있고 전체 텍스트 없음 | stub + > [!warning] Stub: pending ingest. 콜아웃 |
| 개념 | 최소 2개의 출처 기반 발견 내용이 N개 이상의 서로 다른 출처 저작물에서 비롯됨 | final |
| 개념 | 최소 2개의 출처 기반 발견 내용이 모두 단일 출처 저작물에서 비롯됨 | draft (단일 출처 합성) |
| 개념 | 정의 + 1개의 출처 기반 발견 내용 | draft |
| 개념 | 정의만 있고 핵심 발견 내용 없음 | stub + > [!warning] Stub: no sourced findings yet. 콜아웃 |
| 방법 | 정의 + N개 이상의 서로 다른 출처 저작물이 "이 방법을 사용한 논문"에 있음 | final |
| 방법 | 정의 및 출처 저작물 1개만 있음 | draft (단일 출처) |
| 방법 | 정의만 있고 출처 인용 없음 | draft |
| 방법 | 골격만 있음 | stub |
final로 승격하려면 N개의 서로 다른 출처 저작물이 필요합니다. "서로 다른"은 독립적인 논문 또는 책을 의미합니다. 책 부모 노트와 그 자체 장 노트(Author_2025+Author_2025_Ch01+Author_2025_Ch02)는 하나의 저작물로 통합되며, 동일한 책의 여러 장도 마찬가지입니다. 하나의 풍부한 출처(체계적 리뷰, 교과서 장)는 개념을 만들고 여러 발견을 산출할 수 있지만, 두 번째 독립 출처가 이를 확인할 때까지 노트는draft상태로 유지됩니다.draft노트에 발견 내용을 추가할 때, 편집 후 서로 다른 저작물을 세고, 숫자가 N에 도달하면 승격을 진행하며, 수집 보고서에 승격을 기록합니다. 단일 출처draft노트는 본문에 간단한 "단일 출처 합성, 2차 출처 수집 시 확인 필요" 줄을 포함합니다.
기본 워크플로우
1. 스키마 읽기
WIKI_SCHEMA.md를 읽습니다.
2. 논문 출처 확인
환경이 제공하는 것을 사용하여 다음 순서로 시도합니다:
- 참조 관리자 (Zotero MCP가 지원되는 어댑터입니다): 검색 후 메타데이터, 그 다음 전체 텍스트. 순서 및 검색 관련 주의사항은
references/INGEST-WORKFLOW.md에 있습니다. - 게시자 XML 테이블 (PMC의 오픈 액세스): DOI에 PMCID가 있으면, PDF 텍스트 계층과 독립적으로 Europe PMC JATS에서 셀 단위로 테이블을 가져올 수 있습니다:
python <kit>/tools/pmc_tables.py <DOI> --out _temp/<stem>_pmc.md --body(exit 2는 PMCID 없음을 의미). 페이지 이미지를 열기 전에 JATS와 테이블 번호를 확인하세요. JATS와 PDF 간 불일치 시 인쇄된 PDF가 우선하며 불일치를 기록합니다. PMCID 없음: PDF를 사용합니다. - PubMed MCP (논문이 참조 관리자에 없음): 키워드로 검색한 후 PMID로 가져옵니다(DOI는 빈
full_text를 반환할 수 있음). PMID를 논문 노트의notes:필드에 저장합니다. 생물의학 논문에만 사용하며 사용자가 라이브러리에 없다고 확인한 후에만 사용합니다. - DOI만 있음: 기록만 하고 메타데이터를 조작하지 않습니다.
- 웹 기사 (오픈 액세스 HTML/URL): 먼저 웹-투-마크다운 도구(예:
defuddle스킬)로 깨끗한 마크다운으로 변환한 후, 출력물을 초록과 본문으로 취급합니다. DOI가 없는 경우 인용 출처로 URL을 사용합니다. - 수동: 사용자가 초록 또는 텍스트를 붙여넣습니다. 메타데이터를 추출하고 알려지지 않은 것을 표시합니다.
PDF가 있는 위치가 중요합니다. 노트는 정리될 작업 폴더(Downloads/, 임시 디렉토리)를 절대 인용해서는 안 됩니다. 노트를 작성하기 전에 그룹에서 사용하는 라이브러리 위치에 PDF를 정리하고 source_verification에 기록합니다. 논문이 라이브러리에 없거나 적절한 컬렉션이 명확하지 않은 경우, 이동하기 전에 사용자에게 물어보세요.
3. 논문 노트 파일 이름 결정
형식: FirstAuthor_Year_Keyword.md
- FirstAuthor = 첫 번째 저자의 성(ASCII만, 악센트 없음, 공백 없음)
- Year = 4자리 숫자
- Keyword = 1~3 단어 설명어(CamelCase 또는 밑줄, 공백 없음)
- 예:
Smith_2023_Eccentric_Training.md
중복 및 동일성 확인 (쓰기 전에 실행하며, 데이터 손실을 방지합니다):
- 기본 이름에 대한 콘텐츠 검색 또는
test -f "<wiki_root>/papers/{filename}.md"로 존재 여부를 확인합니다. 단일 glob이 "파일을 찾을 수 없음"을 반환하는 것을 신뢰하지 마십시오: 파일 glob 도구는 존재하는 노트에 대해 거짓 부정을 반환한 적이 있으며, 이후 맹목적인Write는 완전히 전파된 노트를 덮어쓸 수 있습니다.Write가 "파일을 아직 읽지 않았습니다" 오류를 반환하면, 이는 노트가 존재한다는 증거입니다: 그것을 읽고 제자리에서 업데이트하며, 처음부터 다시 작성하지 마십시오. - 기존 노트가
status: stub인 경우, 동일한 논문이라고 가정하지 마십시오. 다른 논문의 인용 맥락에서 생성된 스텁은 임시 메타데이터를 가지며, 때로는 다른 논문(잘못된 연도, 논문 대 책 장, 두 관련 논문이 혼동됨)입니다. 먼저 실제 출처를 확인하고 저자, 연도, 저널을 스텁과 인용 노트의 참조 목록 모두와 비교하십시오. 다른 논문이라면 새 노트로 수집하고 스텁을 유지하거나 개선하십시오. - 동일한 논문으로 확인되면 제자리에서 업데이트하고, 중복을 생성하지 마십시오. 전체 텍스트를 보유한 후 파일 이름이 더 설명적인 키워드로 합법적으로 변경될 수 있습니다. 그렇다면 모든
[[OldName]]을 다시 링크하고 고아 스텁을 삭제한 후wiki-lint를 다시 실행하여 끊어진 링크가 없는지 확인하십시오. - Citekey 동일성 가드. 동일한 논문에 대한 두 노트는 다른 파일 이름을 가질 수 있으므로, 깨끗한 기본 이름 프로브는 동일성에 대해 아무것도 증명하지 않습니다. 참조 관리자가 항목을 확인한 후,
papers/에서 작성하려는 정확한 citekey를 검색하십시오(grep -l '^citekey: "?{citekey}"?$' papers/*.md). 다른 파일 이름에서 일치하면 논문이 이미 수집되었음을 의미합니다: 해당 노트를 업데이트하십시오. 정확한 문자열 일치이므로 거짓 긍정이 없습니다.
4. 논문 노트 생성 또는 업데이트
templates/paper.md에서 <wiki_root>/papers/{filename}.md를 작성합니다. 확인된 메타데이터로 모든 프론트매터 필드를 채웁니다. last_verified를 오늘 날짜로 설정합니다(수집은 확인 이벤트입니다). WIKI_SCHEMA.md의 분류 슬러그에서 research_lines를 할당합니다.
5. 추출 및 평가
초록, 결과, 논의를 한 번에 살펴보며 다음을 모두 수행합니다:
- 식별 3
8개의 도메인 개념(경험적 구성, 변수)과 14개의 주요 방법.references/INGEST-WORKFLOW.md에 있는 휴리스틱 참조. evidence_level분류: 연구 설계,WIKI_SCHEMA.md의 통제 어휘(SR-MA,RCT,cohort, ...). 이는 살아있는 합성 계층이 가중치를 부여하는 설계 축입니다. 측정 품질 축은 관련성이 있을 때 각 발견 내용에 인라인으로 유지됩니다((MRI),(anthropometric estimate)), 절대 프론트매터에 넣지 않습니다.- 연구 라인 라우팅: 논문을
WIKI_SCHEMA.md의 연구 라인과 일치시킵니다. 관련 콘텐츠에 일치하는 라인이 없으면 전파하기 전에 스키마에 하나를 추가합니다(슬러그 + 레이블 쌍을 추가하고, 기존 라인을 이름 바꾸거나 제거하지 마십시오). 경계선에 있는 경우 가장 가까운 라인을 사용하고 보고서에 표시합니다. - 개념 대 방법 라우팅: 경험적 발견은
concepts/로 이동합니다. 통계 도구, 연구 설계, 측정 프로토콜은methods/로 이동합니다. 여기서 결정합니다. - 순수 방법론적 지름길: 논문이 경험적 주장을 하지 않으면 6단계를 건너뛰고 7단계로 이동합니다.
5b. 증거 테이블, 전파 전에
concepts/ 또는 methods/의 노트에 도달할 모든 발견 내용("이 방법을 사용한 논문" 아래의 주장 포함)에 대해, 스크래치 파일(절대 위키에 넣지 않음)에 한 행을 작성합니다:
| 대상 노트 | 발견 내용(작성될 그대로) | 출처의 축어적 인용구 | 페이지(PDF/인쇄본) | 섹션, 테이블 또는 그림 |
- 출처는 PDF입니다(테이블 셀의 경우 JATS). 초록만 있거나 PDF 없음: 발견 내용 텍스트에
abstract only를 표시하고 보고서에 명시합니다. - 각 특정 항목에는 자체 인용구가 필요합니다: 각 그림, 모집단, 장치, 메커니즘, 명명된 개체 및 강도 동사. 발견 내용을 분할하거나 여러 인용구를 사용하여 모두 포함될 때까지 진행합니다.
- 일치하는 숫자 주변의 전체 단락이나 테이블 행을 읽습니다, 일치하는 숫자만 읽지 마십시오.
- 테이블, 그림, 부호, CI 및 ±: 페이지를 렌더링하고 봅니다. 텍스트 추출은 가설이며, 이미지가 증거입니다. 일부 PDF는 텍스트 계층에서 마이너스 부호를 잃습니다(
-5.2%가25.2%로 추출됨), 그럴듯한 잘못된 숫자를 생성합니다. - 부재는 긍정적 검색이 필요합니다, 레이아웃 및 비레이아웃 텍스트 모두에서 철자 변형과 함께, 무엇이든 "논문이 ...하지 않는다"고 쓰기 전에.
5c. 작성 전 테이블 확인
노트를 건드리기 전에 모든 행을 해당 인용구와 대조하여 읽습니다. 하위 에이전트가 논문을 추출한 경우, 그림이나 부호가 있는 행뿐만 아니라 PDF의 모든 행을 다시 읽습니다. 판단할 결함 클래스: 출처를 넘어선 추론, 귀인 오류, 잘못된 숫자, 손실된 헤지, 지원되지 않는 최상급, 잘못된 개체, 조작된 세부 사항, 생략.
- 인용구가 지원하지 않는 행은 인용구가 말하는 내용으로 축소되거나 삭제됩니다. 출처 노트는 증거가 아닙니다: 동일한 추출에서 비롯됩니다.
- 출처의 헤지("~할 수 있다", "~인 것 같다", "~때문일 수 있다")와 그 모집단을 유지합니다.
- 위키 자체의 읽기는 위키의 것으로 표시됩니다, 절대 출처의 행위나 결론으로 쓰지 마십시오.
5c 단계를 통과한 행만 6단계와 7단계로 이동합니다.
6. 개념 노트로 전파
5단계의 각 개념에 대해:
concepts/{Concept_Name}.md가 존재하는지 확인합니다.- 존재함:
[[paper_note]]역링크와 함께 "핵심 발견" 아래 발견 내용을 추가합니다. 새 링크가 나타나면related_concepts를 업데이트합니다. - 존재하지 않음: 먼저
references/CONCEPT-PROPAGATION.md의 생성 규칙을 적용합니다.
7. 방법 노트로 전파
5단계의 각 방법에 대해:
methods/{Method_Name}.md가 존재하는지 확인합니다.- 존재함: "이 방법을 사용한 논문" 아래에 논문을 추가합니다.
- 존재하지 않음:
templates/method.md에서 생성합니다.
8. 논문 노트 프론트매터 업데이트
생성되거나 업데이트된 개념 및 방법 노트로 concepts_touched를 채웁니다.
작성 후 확인: concepts_touched의 모든 이름은 concepts/ 또는 methods/의 기존 노트로 반드시 확인되어야 합니다. 작성 후 각 기본 이름을 다시 확인합니다. 하나라도 확인되지 않으면 지금 누락된 스텁을 생성하거나 이름을 제거합니다. 매달린 참조는 조용한 린트 드리프트가 됩니다.
8b. 출처 노트 봉인
논문 노트의 source_verification에 확인을 기록합니다(한 줄: 참조 관리자 키, 날짜, 무엇과 무엇을 확인했는지). 그런 다음 발견 내용을 받고 5c를 통과한 각 (노트, 저작물) 쌍을 봉인합니다: 작은 JSON 스펙을 작성하고 python <kit>/tools/seal.py spec.json --dry-run을 실행한 후, --dry-run 없이 실행합니다(형식 및 규칙은 docs/SEALS.md 참조). 초록에 대해서만 확인된 저작물은 봉인되지 않습니다. 시스템 시계(date +%F)에서 날짜를 가져오고, 절대 추정하지 마십시오.
9. 마무리
세 가지 편집 후 보고서를 작성합니다. wiki.config.json의 field_titlecase_map을 사용하여 각 새 개념 또는 방법에 대한 올바른 하위 섹션을 찾고, 섹션 끝의 날짜가 지정된 포괄 블록에 절대 추가하지 마십시오.
index.md: 인덱스가 Obsidian Bases 뷰를 포함하는 경우(index_mode: bases설정), 노트별 목록을 유지하지 말고, 선별된## Quick Stats개수와 관련## Coverage by Field행만 업데이트한 후 테이블을 다시 읽습니다(신선한 위키에는 두 섹션이 모두 없음: 추가할 때까지 생략하면 드리프트가 없습니다).manual모드에서는 올바른 알파벳 슬롯에 노트를 추가합니다. 동결된 레거시 인덱스를 절대 건드리지 마십시오.- 하위-MOC 라우팅 (
WIKI_SCHEMA.md, Sub-MOC Architecture 참조): 노트의field+subfield를 확인하고,fields/{field-slug}/MOC_{Title_Case_Underscore(subfield)}.md를 계산합니다(케밥-케이스를 Title_Case로 결정적 변환, 맵 불필요). 존재하지 않으면templates/submoc.md에서 생성하고 필드 MOC의 하위-MOC 인덱스에 행을 추가합니다. 하위-MOC의 올바른 섹션(개념 노트, 방법 노트, 논문, 책) 아래에 노트를 추가합니다.
… [번역을 위해 잘림]