biopathway-mechanism-diagram은(는) 무엇을 하나요?
경로 그림은 독자가 한 화살표씩 도전하게 될 기전 진술입니다. 이 스킬의 계약: 캔버스의 모든 엔티티와 모든 에지는 위치가 포함된 축어적 인용문으로 추적 가능해야 합니다. 상호작용 의미론(활성화/억제/결합/변형/수송)은 시각적으로 구별되며 혼동되지 않습니다. 출처가 명시하지 않은 모든 것(방향, 위치, 숫자)은 추측하지 않고 '미지정'으로 표시됩니다. 결과물은 계층적이고 ID로 주소 지정 가능한 편집 가능 SVG와 PNG/PDF 내보내기 파일, 그리고 계약을 완전히 충족하는 result.json입니다.
사용 시기 / 사용하지 말아야 할 시기
사용 대상: 기전 그림, 신호 전달 경로 다이어그램, 수용체-핵 연쇄 반응, 경로 상호 대화(crosstalk), "이 논문의 그림 N을 그려줘" 작업, 기존 경로 그림 편집(엔티티 또는 에지 추가/제거, 레이블 변경). 사용 금지: 통계 차트(막대/상자/화산), 실험 개요도, 미적 목적의 단순 보정; 이러한 작업은 인접 스킬에 속합니다.
실행 계약 (플랫폼 런타임)
- 입력:
/input/case.json(+ task.md)./app/work아래에서 작업; 결과물은/app/output아래에. - 전체 실행의 첫 번째 작업(사례를 자세히 읽기 전):
python scripts/scaffold_result.py --input /input/case.json --outdir /app/output이 명령은 모든 출력 계약 필드가 포함된 result.json을 작성하며, 생성되지 않은 필드는 null + 이유를 포함합니다. 계속 단계별로 업데이트하세요. 계약 필드를 절대 삭제하지 마십시오. - 아래의 모든 스크립트는
--model/--svg스타일의 경로를 인수로 받으며, 별도 명시가 없으면 순수 Python 3(stdlib 전용)입니다.references/는 스크립트가 읽습니다. 1단계 전에 직접.md파일을 읽으십시오.
0단계 - 계약 읽기 및 스캐폴드 생성 (1회 요청)
스캐폴드를 실행합니다. task.md + case.json을 훑어보며: 그림 대상을 식별합니다(어떤 기전인지, 재현할 대상 그림이 있는지, 생성 vs 편집 시나리오), 필요한 내보내기 형식, 증거 범위를 파악합니다. 채워야 할 계약 필드 목록을 기록합니다. 예산 인식: 5-8 모델 단계 내에 완료하는 것을 목표로 하세요; 스크립트가 무거운 작업을 수행하고, 당신은 과학적 판단을 합니다.
1단계 - 기전 모델 추출 (과학적 핵심 - 직접 수행)
실제 자료를 읽습니다(PDF를 실제로 구문 분석; 파일을 읽고, 절대 레이블만으로 내용을 추측하지 마십시오). references/layout-conventions.md에 따라 /app/work/model.json을 자신의 판단으로 구축합니다:
- 엔티티 — 유전자 / 단백질 / 수용체 / RNA / 복합체 / 분자 / 세포 / 패밀리.
references/naming-rules.md적용: 유전자 기호는 이탤릭체로, 유전자 노드는 단백질과 구별(MYC vs MYC); 선호 기호와 함께 출처 철자를 동의어에 포함; 패밀리와 구성원 구분; 명시된 각 복합체에 대해 하나의 노드. 각 엔티티는source: {loc, quote}를 포함 — 다시 찾을 수 있을 만큼 정확한 축어적 인용문과 위치(절/문단/페이지/그림 캡션). - 에지 —
references/edge-types.json의 폐쇄 집합에서 유형(활성화, 억제, 결합, 인산화, 유비퀴틴화, 전사조절, 전위, 복합체 형성, ...).directed는 명시적으로 설정해야 합니다. 방향을 절대 추측하지 마십시오: 인용문에 방향 신호가 없으면directed: false로 설정하고 불확실성을 기록합니다(references/uncertainty-policy.md). 결합/동원은 방향성이 없습니다(undirected). 전사 조절은 유전자 노드를 대상으로 하며 부호(sign)가 필요합니다. - 구획 — 세포외 / 막 / 세포질 / 핵 (+ 소포체, 골지체, 소기관 하위 영역, 기전에 필요한 경우). 위치가 명시되지 않은 엔티티는
unspecified대역으로 이동합니다 — 절대 세포질에 조용히 넣지 마십시오. 수용체는 막 대역에 고정됩니다. - 순서 — 경로 상의 위치에 따라
order를 설정합니다(텍스트 순서가 아닌 위상적 순서); 피드백 루프는 자연스럽게 역방향 에지로 나타납니다. - 캔버스 위의 숫자(발현, 유의성)는 출처에 축어적으로 존재하는 경우에만 포함합니다; 그렇지 않으면 데이터 매핑을 명시적 null로 남깁니다.
실제 추출 순서: 첫 번째 읽기에서 전체 흐름 파악; 두 번째 패스에서 문장별로 엔티티 + 인용문 수집; 세 번째 패스에서 억제제, 피드백 및 상호 대화를 포함한 에지 수집(이들은 "그러나/반면에" 문장에 숨어 있습니다).
2단계 - 모델 검증 (스크립트)
python scripts/validate_model.py --model /app/work/model.json \
--report /app/work/validation-report.json
모든 E-* 오류를 수정합니다. E-DIR-01(방향 신호가 없는 방향성 에지)은 핵심 과학적 보호 장치입니다: 방향을 명시하는 문장을 인용하거나, 방향성 없음 + 불확실성으로 전환합니다. 경고는 의식적인 결정이 필요합니다: 패밀리 노드, 수용체 배치, 부호-인용 불일치. 유효할 때까지 재실행합니다. 자료가 필요한 계약 항목을 뒷받침할 수 없는 경우, 지금 기록합니다(5단계에서 null + 이유가 됩니다).
3단계 - SVG 렌더링 및 내보내기 (스크립트)
python scripts/render_svg.py --model /app/work/model.json \
--out /app/output/pathway.svg --report /app/work/render-report.json
python scripts/export_assets.py --svg /app/output/pathway.svg \
--outdir /app/output --model /app/work/model.json \
--png-width 2400 --report /app/work/export-report.json
렌더 리포트의 경고(캔버스 제한, 알 수 없는 구획)를 읽습니다. PNG를 직접 확인합니다; 레이아웃이 기전을 가리는 경우(에지 교차로 분기점이 숨겨지는 경우, 피드백이 연쇄 반응 위에 있는 경우), 모델에서 order/고정 위치를 조정하고 다시 렌더링합니다. SVG는 결정론적입니다: 동일한 모델 → 동일한 SVG.
4단계 - 편집 시나리오 (사례가 기존 그림 편집을 요구하는 경우)
먼저 대상 그림의 모델을 재구성한 후(원본 그림 출처 텍스트에 대한 1단계), 출처를 보존하는 편집을 사용합니다 — 원본 모델/SVG는 백업되고, 모든 편집은 모델의 change_log에 기록됩니다:
python scripts/apply_edit.py --model /app/work/model.json --op add-edge \
--id e-new --src A --tgt B --type inhibition --directed true \
--sign negative --loc "..." --quote "..."
연산: 엔티티 추가/이름 변경/제거(--cascade 없이 에지가 연결된 경우 제거 거부, 연쇄 제거는 불확실성으로 기록), 에지 추가/제거, 구획 추가. 추가된 모든 엔티티/에지는 --loc + --quote에 축어적 인용이 필요합니다. 편집 후 재검증(자동) 및 재렌더링(3단계).
5단계 - result.json 검증 및 최종 확정 (스크립트 + 직접)
python scripts/verify_outputs.py --model /app/work/model.json \
--svg /app/output/pathway.svg --result /app/output/result.json \
--exports /app/output/pathway.png /app/output/pathway.pdf \
--report /app/output/verification-report.json
이 명령은 SVG를 다시 읽고 노드/에지 읽어내기, 범례↔사용 일관성(양방향), 레이블 오버플로우, 캔버스 제한, 내보내기 파일 존재 여부, 그리고 result.json의 모든 null에 이유가 있는지 확인합니다. 그런 다음 result.json을 직접 최종 확정합니다: 계약 필드를 채웁니다(편집 가능한 소스 경로, 백엔드/파라미터가 포함된 내보내기 파일, 인용문이 포함된 entity_table/edge_table, 범례 기준, 버전이 포함된 출처, 불확실성, 검증 요약, 정직한 상태). null인 항목에 대해 _unanswered_reasons를 유지합니다. 부분 전달은 그 한계를 평이한 언어로 명시해야 합니다.
예외 처리 (실제 경로, 장식 아님)
| 실패 | 감지 | 조치 |
|---|---|---|
| PDF를 읽을 수 없음 / 텍스트 레이어 없음 | 구문 분석 실패 또는 빈 텍스트 | pdf-render-tool / ocr-tool로 렌더링, result.json에 "텍스트 레이어 없음" 플래그 표시 |
| 엔티티 이름 모호 (두 가지 해석) | 직접 추출 | 문맥에 따라 선택, 대안 + 불확실성 기록; 결정 불가능 시 null + 이유 |
| 방향이 명시되지 않음 | E-DIR-01 | 방향성 없는 에지(화살표 없음) + 불확실성으로 전환. 절대 추측 금지 |
| 구획 알 수 없음 | E-CMP-01 / 레이아웃 경고 | unspecified 대역 + 메모 |
| 데이터 인코딩 시각 자료에 필요한 숫자 데이터 누락 | 모델에 축어적 숫자 없음 | 토폴로지만 그리고, 매핑 null + "출처에 데이터 없음" 표시 |
| 레이블 오버플로우 | verify label_overflow | 레이블 단축 / label+sub로 분할 / 재정렬 |
| 캔버스가 제한 초과 | 렌더 경고 | 패널로 분할 또는 가지 줄이기; 메모 남기기 |
| 내보내기 백엔드 누락 | 내보내기 리포트 상태 실패 | 대체 체인 이미 시도; SVG 전달, 실패 + 안내를 result.json에 기록 |
| 빈/변질 PNG | blank_check | 렌더 리포트 조사; 재렌더링; 기록 |
| 검증 오류 지속 | 종료 코드 2 | 모델 수정; 자료에서 수정 불가능 시 유효한 부분 집합 + 명시적 한계 전달 |
품질 기준 (완료 전 자체 점검)
- 검토자가 어떤 화살표든 가리키며 포함된 테이블/모델에서 그 축어적 근거를 얻을 수 있는가? (추적 가능성)
- 활성화/억제/결합/변형이 시각적으로 구별되며, 범례가 그려진 것과 일치하는가? — 누락되거나 유령 항목이 없는가?
- 명시되지 않은 모든 것이 시각적으로 명확히 표시되었는가? (방향성 없음, 미지정 대역, null + 이유)
- 누군가 SVG를 열고 하나의 레이블을 변경한 후 다시 내보낼 수 있는가? (계층적, ID 주소 지정 가능, 표준 폰트 스택)
- result.json이 모든 계약 필드를 정직한 상태로 포함하는가?
파일
scripts/scaffold_result.py- null+이유가 포함된 계약 완전 result.jsonscripts/validate_model.py- 스키마 + 방향-증거 + 명명 검사scripts/render_svg.py- model.json에서 결정론적 계층적 SVG 생성scripts/export_assets.py- 대체 체인 + 빈 검사 기능이 있는 PNG/PDF 생성scripts/apply_edit.py- 출처를 보존하고 로그를 남기는 편집scripts/verify_outputs.py- 번들의 읽어내기 검증references/edge-types.json- 기계 판독 가능한 기호 의미론references/symbol-semantics.md- 시각적 문법 및 그 근거references/naming-rules.md- 유전자/단백질/패밀리/복합체 명명 규칙references/uncertainty-policy.md- 전환 규칙; 추측 금지 정책references/layout-conventions.md- model.json 스키마 + 레이아웃 알고리즘examples/ras-mapk-case/- 실제 자료 예제 (Brown & Ried 2022)README.md- 독립형 사용 설명서