그래픽 초록 빌더
연구 자료(PDF, 노트, 기록)를 단일 페이지 그래픽 초록으로 변환합니다. 모든 요소는 자료에 추적 가능하며, 계약을 완전히 이행하는 result.json이 함께 생성됩니다.
역할 분담 — 에이전트는 과학을 수행하고, 스크립트는 그림을 그립니다:
- 에이전트(사용자): 실제 자료를 읽고, 개체/관계/데이터를 추출하며, 시각적 인코딩을 선택하고, 캔버스에 들어갈 내용과 캡션에 들어갈 내용을 결정하며, 자료와 그림을 대조하여 검증합니다.
- 스크립트(
scripts/, 순수 Python + matplotlib): 레이아웃, 렌더링, 검사, 결과 조립을 담당합니다. 결정론적입니다. 동일한 모델을 입력하면 동일한 그림이 출력됩니다.
환경 및 경로
- 스킬 루트:
/skills/weekly-skill(스크립트는scripts/아래, 스키마 문서는references/아래)./app/work디렉토리에서 작업하며, 최종 결과물은/app/output에 저장됩니다. - 입력:
/input/case.json(+ task.md; 자료 파일은 케이스에서 참조). - Python과 matplotlib이 필요합니다. matplotlib이 없으면 PNG 내보내기는 Pillow로 자동 대체되며, PDF 내보내기는 해결 방법과 함께 오류를 발생시킵니다. 자세한 내용은 플레이북을 참조하세요.
- 일반 비용: 10–20회의 모델 요청으로, 64회 요청 / 900초 예산 내에서 충분히 처리됩니다. 각 빌드/검증 스크립트 실행은 한 번의 도구 호출로 간주됩니다.
워크플로우
단계 0 — 케이스를 읽고 result.json 뼈대를 만듭니다 (먼저 수행)
/input/case.json을 완전히 읽습니다. case_id와 output_contract의 모든 필드를 확인합니다. 이는 반드시 이행해야 할 전달 의무입니다. 그런 다음 즉시:
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
이 명령은 모든 계약 필드를 명시적인 null과 보류 사유로 기록합니다. 이후에 충돌이 발생하더라도 계약을 완전히 이행한 결과물이 남아 있습니다. (6단계에서 --stage final로 다시 실행하여 채웁니다.)
단계 1 — 실제 자료를 읽습니다
케이스가 가리키는 실제 파일을 엽니다 (레이블만으로 내용을 추정하지 마십시오). PDF는 pdf-text-tool / scientific-python을 사용하고, OCR이 필요한 경우에만 페이지를 스캔합니다. 각 자료 파일을 추출된 텍스트에 매핑하는 sources.json을 저장합니다. 이후 단계에서 인용문을 자료와 자동으로 대조 검증합니다:
{ "materials/paper.pdf": "<전체 추출 텍스트>" }
단계 2 — 과학적 내용을 추출합니다 (에이전트의 판단, 스크립트가 아닌)
워크시트(템플릿: templates/agent_worksheet.md)를 자료에서 직접 작성합니다:
- 질문 — 자료가 제기하는 문제는 무엇인가요? 그대로 인용합니다.
- 개체 — 반드시 등장해야 하는 대상(분자, 세포, 장치, 방법, 코호트 등)입니다. 각각에 대해: 레이블, 한 개의 그대로 인용한 인용문, 위치 정보(파일 + 페이지/섹션/문장).
- 관계 — 자료가 명시하는 방향성 연결(A가 B를 활성화함, 투여량이 질문을 유발함 등)입니다. 방향과 해당 문장을 기록합니다.
- 데이터 — 그림에 그릴 모든 숫자: 값, 단위, 조건, 그리고 해당 문장을 기록합니다. 원하는 숫자가 자료에 없다면 그림에 그리지 말고, 대신
uncertainty/limits에 나열합니다. - 결론 — 자료 자체가 주장하는 바입니다.
증거 규칙: 인용문은 자료의 하위 문자열을 그대로 사용하며, 위치 정보는 사람이 몇 초 안에 찾을 수 있을 정도로 정확해야 합니다. 출처를 확인할 수 없는 내용은 캡션/노트에 기록하고, 절대 데이터로 캔버스에 그리지 않습니다.
단계 3 — figure_model.json을 작성합니다
references/model_schema.md의 스키마에 따라 /app/work/figure_model.json을 작성합니다 (전체 예제: examples/transformer-1706.03762/). 주요 결정 사항:
- 패널 계획: 보통 읽기 순서대로 4–6개 패널 (질문 → 방법 → 결과(1–2) → 결론), 패널당 하나의 발견.
- 패널별 레이아웃:
flow(개체/관계를 위한 상자 + 화살표),chart(데이터를 위한 막대/수평 막대/그룹화 막대/선),stats(주요 값 2–4개를 위한 큰 숫자 강조),text(글머리 기호 결론). - 시각적 채널: 공통 단위와 0 기준선이 있는 크기에는 길이 사용, 시계열에는 위치 사용, 범주형 계열에만 색상 사용(Okabe–Ito 팔레트 내장, 절대 빨강-초록 사용 금지), 초점 개체에는 모양/강조 사용. 채널당 하나의 의미, 의미당 하나의 채널.
- 캔버스: 기본 1800×1000 px (≈ A4 가로 150 dpi). 모든 글꼴 크기는 12 px 이상으로 유지합니다(검사기가 강제).
- 워크시트의 인용문/위치 정보를 각 요소의
source에 복사합니다.
단계 4 — 빌드 및 반복
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
graphical_abstract.svg(편집 가능한 소스 진실: 명명된 id, layer-* 그룹, 모든 요소에 출처 <desc>), .png(300 dpi), .pdf, element_map.json, export_report.json을 생성합니다. 종료 코드 2 = 모델 오류(JSON 수정), 3 = SVG 실패(플레이북에 따라 수정). PNG/PDF 렌더링 실패는 실행을 중단하지 않으며, export_report.json.failures에 기록됩니다.
반복: 보고서에 오류가 있으면 SVG가 아닌 모델을 편집하고 다시 빌드합니다. 모든 오류 코드가 사라질 때까지 그림은 잘못된 상태입니다.
단계 5 — 리뷰어처럼 검증합니다
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
이 스크립트는 모든 검사를 다시 실행합니다: SVG 정합성, 최소 글꼴 크기, 캔버스 경계, 요소 맵 완전성, 인용문-자료 대조(허위 숫자 및 잘못된 인용 발견), 그레이스케일/대비, 내보내기 무결성. 그런 다음 직접 PNG를 확인하고(렌더링된 미리보기를 읽음) 다음을 확인합니다: 읽기 순서가 명확한가? 개체/화살표 방향이 자료와 일치하는가? 범례가 인코딩과 일치하는가? 모든 축에 단위가 있는가? 경고를 제거할 수 없으면 기록하고, 숨기지 않습니다.
단계 6 — 최종 result.json을 조립합니다
/app/work/values.json에 계약 필드 값(scientific_summary, uncertainty, 경로 목록, export_checks 등)을 작성합니다. element_source_map과 export_checks는 빌드에서 자동으로 채워집니다. 그런 다음:
python scripts/make_result.py --stage final \
--case /input/case.json --out /app/output/result.json \
--values /app/work/values.json \
--map /app/work/out/element_map.json \
--export /app/work/out/export_report.json \
--issues /app/work/out/issues.json \
--status complete --uncertainty "<정직한 한 문장>"
매처는 정확한 키, 그 다음 포함, 그 다음 설명 키워드를 기준으로 계약 필드를 채웁니다. 일치하지 않는 필드는 명시적인 null과 사유로 남습니다. 오류 수준의 문제가 남아 있으면 상태는 자동으로 partial로 강등됩니다. 검사 실패에도 complete라고 주장하지 마십시오. 결과물을 /app/output에 복사합니다:
graphical_abstract.svg + figure_model.json(편집 가능한 소스),
graphical_abstract.png(미리보기) + graphical_abstract.pdf(내보내기),
result.json.
단계 7 — 최종 자체 점검
- result.json:
case_id가 존재하고, 모든 계약 필드가 채워졌거나 명시적인null과 사유가 있으며, 상태가 정직합니다(자동 강등이 존중됨). - SVG가 열리고(올바른 XML 형식), 텍스트가 실제
<text>이며(편집 가능), 모든 요소에 id가 있고, 레이어 이름이 지정되어 있습니다. - PNG와 PDF가 존재하고 비어 있지 않으며, PNG ≥ 300 dpi입니다.
- 캔버스 위의 모든 숫자가
element_map.json내의 인용문에 나타납니다. - 범례가 색상/계열 인코딩과 정확히 일치합니다.
-
uncertainty/limits가 모든 누락되거나 출처가 불분명한 항목을 언급합니다.
문제 발생 시
모든 실패 모드, 증상 및 해결 방법(자료에 주요 숫자 누락, 개체 모호성, 텍스트 오버플로, 글꼴 대체, 캔버스 오버플로, 내보내기 실패, matplotlib 없음 등)은 references/exception_playbook.md에 있습니다. 빨간색 출력이 발생하면 이를 참조하십시오. 모든 것을 무시하는 한 가지 규칙: 정직하게 기록하고, 절대 지어내지 마십시오. 문서화된 한계가 있는 partial 결과가 증거를 지어낸 예쁜 그림보다 더 좋은 점수를 받습니다.
참고 자료
references/model_schema.md— figure_model.json의 필드별 설명, 기본값 및 제약 조건.references/exception_playbook.md— 실패 증상 → 해결 방법.references/design_notes.md— 빌더에서 사용하는 시각적 인코딩 규칙, 색각 안전성, 레이아웃 규칙.templates/agent_worksheet.md— 2단계 추출 워크시트.templates/figure_model.template.json— 최소 시작 모델.examples/transformer-1706.03762/— 실제 논문 작업 예제 (arXiv:1706.03762, 그대로 인용 + sha256).