Apt

extract_subcluster.py — 서브 데이터 일괄 추출

사용법: python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/extract_subcluster.py"
동작:  problem.json/method.json의 모든 클러스터를 읽어 서브 디렉토리로 일괄 추출 (1편뿐인 클러스터는 건너뜀)
출력:  ./clusters/{safe_name}/ 디렉토리마다 results.jsonl 생성

build_all.py — 대시보드 + 트리 일괄 빌드

사용법: python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/build_all.py"
동작:  현재 디렉토리부터 재귀 순회하며 results.jsonl + 클러스터 JSON이 있는 모든 디렉토리에 index.html 생성, 루트에 tree.html 생성
출력:  각 디렉토리에 index.html, 루트에 tree.html

단계별 프로세스

0단계: 인자 파싱

스킬 호출 시 전달된 인자를 파싱합니다.

• 언어(language): 논문 분석 결과 및 클러스터링 설명을 작성할 언어. 기본값은 korean. 예: korean, english
• 재귀 깊이(depth): 클러스터링을 몇 단계까지 반복할지. 기본값은 1. 예: 1, 2, 3

이후 모든 단계에서 language와 depth 값을 참조합니다.

results.jsonl이 이미 존재하면 1~3단계를 건너뛰고 4단계로 바로 진행한다.

1단계: 미분석 논문 스캔

python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/scan_papers.py"

stdout에 미분석 PDF 파일명이 출력됩니다. 0개면 2단계만 건너뛰고 3단계부터 계속 진행한다. 스크립트 경로를 직접 조작하거나 절대경로를 생성하지 않는다.

2단계: 병렬 논문 분석

1단계에서 출력된 미분석 논문들에 대해 분석을 실행합니다.

1. 논문 1편당 Abstract_Paper 스킬을 서브에이전트로 실행합니다. 최대 5개의 서브에이전트를 병렬로 실행하며, 한 서브에이전트는 하나의 논문만 처리해야합니다. 서브에이전트 인자: {파일명} {language} (예: paper.pdf korean) 각 에이전트는 results/ 디렉토리에 개별 JSON 파일을 생성하므로 동시 쓰기 충돌이 발생하지 않습니다.
2. 완료 후 scan_papers.py를 다시 실행하여 누락을 확인합니다. 누락이 있으면 해당 논문에 대해 재실행합니다.

3단계: 병합

python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/merge_results.py"

4단계: 클러스터링

results.jsonl 파일을 읽어 각 논문의 problem, methodology, keywords 필드를 파악하고, 다음 두 가지 분류를 수행하여 Write 도구로 저장합니다.

1. 문제(Problem) 클러스터링 → problem.json (problem 필드 중심, keywords 참고)
2. 해결 방식(Methodology) 클러스터링 → method.json (methodology + keywords 필드 중심)

필수 조건: results.jsonl의 모든 논문이 하나 이상의 클러스터에 반드시 포함되어야 한다. Write 전에 filenames 전체를 직접 대조하여 누락이 없음을 확인한다. 누락이 있으면 저장하지 말고 먼저 클러스터에 추가한다. 저장 후 훅이 누락을 감지하면 즉시 수정한다.

형식: 반드시 아래 형식을 준수해야 합니다. 클러스터 이름과 summary 필드는 language에 맞는 언어로 작성합니다.

{
  "영역 이름": {
    "summary": "이 영역에 대한 요약 설명",
    "filenames": ["파일명1.pdf", "파일명2.pdf"]
  }
}

• 최상위 키: 클러스터 영역 이름 (자유 형식 문자열)
• summary (필수): 해당 영역의 핵심 요약
• filenames (필수): results.jsonl의 filename 값과 정확히 일치하는 PDF 파일명 배열
• 논문 중복 허용: 한 논문이 여러 클러스터에 동시에 속할 수 있다. 트리에서 중복 리프끼리 연결선으로 표시된다.

5단계: 재귀 클러스터링 (depth > 1인 경우)

depth가 1보다 크다면, 현재 output_dir의 클러스터들을 한 단계 더 세분화합니다.

핵심 규칙

• 분류 기준 유지: problem.json에서 시작한 재귀는 끝까지 problem.json만, method.json에서 시작한 재귀는 끝까지 method.json만 생성합니다.
• 건너뛰기: 논문이 1편뿐인 클러스터는 건너뜁니다.

5-1. 서브 데이터 일괄 추출

python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/extract_subcluster.py"

stdout에 생성된 서브 디렉토리 목록이 출력됩니다.

5-2. 각 서브 디렉토리에서 서브 클러스터링

stdout에 출력된 각 {sub_dir} (예: clusters/topic_a)에 대해:

1. 해당 디렉토리의 results.jsonl을 Read로 읽습니다. (경로: {sub_dir}/results.jsonl)
2. 논문을 클러스터로 분류합니다.
3. 분류 기준에 맞는 JSON만 Write로 저장합니다:
   • problem.json 계열 → {sub_dir}/problem.json
   • method.json 계열 → {sub_dir}/method.json

논문 중복 허용: 한 논문이 여러 클러스터에 동시에 속할 수 있다. 트리에서 중복 리프끼리 연결선으로 표시된다.

5-3. 재귀

depth - 1이 1보다 크다면, 5-1의 stdout에 출력된 각 서브 디렉토리에 대해 5단계를 반복합니다.

5-1의 stdout에 출력된 상대경로를 그대로 인자로 전달한다:

python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/extract_subcluster.py" "{sub_dir}"

디렉토리 구조는 깊이에 따라 중첩됩니다:

clusters/topic_a/                  ← depth=2일 때 5-1 stdout
clusters/topic_a/clusters/sub_x/   ← depth=3일 때 5-3 stdout

stdout에 출력된 하위 상대경로들에 대해 5-2(서브 클러스터링)를 수행한 뒤, depth - 1이 1보다 크면 5-3을 반복합니다. 분류 기준은 유지합니다.

6단계: 빌드

모든 클러스터링이 완료된 후 대시보드와 트리를 일괄 생성합니다.

python "${CLAUDE_PLUGIN_ROOT}/skills/APT/scripts/build_all.py"

현재 작업 디렉토리(논문 디렉토리)를 루트로 재귀 순회하며 모든 index.html과 tree.html을 한 번에 생성합니다.