QinghongLin/data2story-skill

데이터 저널리스트 에이전트 (Data2Story)

$ARGUMENTS를 블로그로 변환합니다. 아래 역할을 순차적으로 오케스트레이션합니다.

설정

명령을 실행하기 전에 경로를 확인하세요:

• 절대 로컬 머신 경로를 하드코딩하거나 사용자에게 경로 변수를 내보내도록 요청하지 마세요.
• SKILL_DIR = 이 SKILL.md가 포함된 디렉토리 (.../skills/data2story) 를 확인하세요.
• ARCHIVE_DIR = skills/를 포함하는 상위 디렉토리 (SKILL_DIR에서 두 단계 위, 즉 SKILL_DIR/../..) 를 확인하세요.
• DATA2STORY_ROOT = ARCHIVE_DIR의 부모 디렉토리
• 아래 명령은 ARCHIVE_DIR과 같은 기호적 플레이스홀더를 사용하므로 Bash를 실행하기 전에 확인된 따옴표로 묶인 경로로 대체하세요.
• DATA_NAME = 데이터셋 폴더 이름 (예: pick_a_card)
• DATA_DIR = $ARGUMENTS가 기존 경로이면 해당 경로를 사용하고, 그렇지 않으면 DATA2STORY_ROOT/data/{DATA_NAME}을 사용합니다.
• TIMESTAMP = 현재 시간을 MMDD_HHMM 형식으로 포맷 (예: 0401_1618): date +%m%d_%H%M (bash에서 실행)
• PROJECT_DIR = DATA2STORY_ROOT/project/{DATA_NAME}/blog_{MODEL}_{TIMESTAMP}
• PROJECT_DIR/, PROJECT_DIR/assets/, PROJECT_DIR/code/를 생성합니다.

아카이브

PROJECT_DIR을 만든 직후, 현재 스킬의 스냅샷을 저장합니다:

mkdir -p PROJECT_DIR/archival
cp -r ARCHIVE_DIR/skills PROJECT_DIR/archival/skills

이렇게 하면 이 실행에 사용된 정확한 스킬 버전이 보존됩니다.

사용 가능한 도구

모든 미디어 도구는 OpenRouter를 통해 라우팅됩니다. 생성 호출 전에 OPENROUTER_API_KEY를 설정하세요.

미디어 생성은 Designer의 작업이므로 미디어 도구(text2image, text2video, image2video, text2music, embeddings)는 SKILL_DIR/designer/scripts/openrouter-*/ 아래에 있습니다. 전체 목록(기본 모델 및 정확한 python3 ... 호출)은 **designer/references/tools.json**에 있습니다. 각 도구의 전체 문서는 SKILL_DIR/designer/scripts/openrouter-*/ 아래에 있는 해당 도구의 자체 SKILL.md에 있습니다.

파이프라인 개요

파이프라인은 원시 데이터에서 추적 가능한 HTML 블로그를 생성하는 단일 선형 시퀀스입니다:

DATA → Detective → Analyst → Editor → Designer → Programmer → Auditor → Inspector → 최종 index.html + viewer.html

각 단계를 순서대로 실행합니다. 각 단계는 시작하기 전에 이전 아티팩트를 읽습니다. 현재 아티팩트가 완료될 때까지 다음 단계로 진행하지 마세요.

1단계 — Detective

입력: DATA_DIR 출력: PROJECT_DIR/detective.json 내용: 외부 컨텍스트(배경 지식, 도메인 역사, 관련 발견 사항, 이 데이터가 중요한 이유)를 조사합니다. 각 발견 사항은 det_xx ID를 받습니다.

2단계 — Analyst

입력: DATA_DIR, PROJECT_DIR/detective.json 출력: PROJECT_DIR/code/*.py, PROJECT_DIR/analyst.json 내용: Detective의 컨텍스트를 바탕으로 데이터에 대한 철저한 정량적 분석을 수행합니다. 모든 코드는 실행 가능한 스크립트로 code/에 저장됩니다. 각 발견 사항은 calculation(파일 + 라인 + 출력) 및 data_table(차트 준비 데이터)과 함께 ana_xx ID를 받습니다.

3단계 — Editor

입력: PROJECT_DIR/detective.json, PROJECT_DIR/analyst.json 출력: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json 내용: 편집 결정 — 어떤 발견 사항이 중요한지, 내러티브 아크는 무엇인지, 블로그가 주장하는 바는 무엇인지. 각 섹션은 ana_xx 발견 사항 및 det_xx 컨텍스트에 대한 명시적 참조와 함께 edt_xx ID를 받습니다. 시각적 디자인은 포함하지 않습니다.

4단계 — Designer

입력: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json 출력: PROJECT_DIR/designer.json, PROJECT_DIR/assets/* 내용: 데이터 기반의 창의적인 시각적 결정 — 차트, 이미지, 비디오, 오디오, 지도, 인터랙티브, 통계 콜아웃, 인스턴스 또는 텍스트 전용 처리를 사용하여 각 포인트를 어떻게 제시할지. 미디어 믹스는 고정된 체크리스트가 아닌 데이터셋의 속성에서 나와야 합니다. 페이지는 기본적으로 멀티미디어가 풍부해야 합니다: 공유된 frontend-design 스킬의 시각적 언어를 차용하고, 문서화된 폴백이 조작되거나 순수 장식용이 아닌 이상 5가지 채널(차트, 이미지, 비디오, 오디오, 인터랙티브/지도)을 모두 사용하세요. 각 시각 요소는 데이터 주도적일 때 ana_xx data_table을 가리키는 data_source와 함께 des_xx ID를 받습니다. 선택된 에셋을 생성합니다. HTML은 생성하지 않습니다.

5단계 — Programmer

입력: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json, PROJECT_DIR/designer.json 출력: PROJECT_DIR/index.html 내용: 최종 블로그를 HTML로 구현합니다. designer.json의 page_rhythm에 기록된 테마/강조 색상을 적용하고 frontend-design 스킬의 컴포넌트 및 토큰 레시피를 차용합니다. analyst.json data_table에서 차트 데이터를 해결합니다(원시 데이터에 직접 접근하지 않음). 모든 요소에 추적 가능성을 위해 data-edt, data-ana, data-det, data-des 속성을 태깅합니다.

6단계 — Auditor

입력: PROJECT_DIR/index.html 출력: PROJECT_DIR/index.html (수정됨), PROJECT_DIR/auditor.json 내용: 콘텐츠나 디자인 의도를 변경하지 않고 레이아웃 문제(겹침, 간격, 정렬)를 감지하고 수정합니다. Programmer 후에 자동으로 실행되어 시각적 요소가 적절하게 감싸지고 간격이 조정되었는지 확인합니다.

호출: Skill auditor PROJECT_DIR

7단계 — Inspector

입력: PROJECT_DIR/index.html, 모든 JSON 파일 출력: PROJECT_DIR/inspector.json, PROJECT_DIR/viewer.html 내용: 문장 수준의 추적 가능성 검증을 실행하고 인터랙티브 뷰어를 생성합니다. 두 단계로 구성됩니다:

python3 SKILL_DIR/inspector/scripts/verify.py PROJECT_DIR --log-errors
python3 SKILL_DIR/inspector/scripts/generate_viewer.py PROJECT_DIR

1단계는 inspector.json(문장→증거 매핑)을 생성합니다. 2단계는 viewer.html(자체 포함, file://에서 동작 — 서버 불필요)을 생성합니다. 자세한 내용은 inspector/SKILL.md를 참조하세요.

추적 가능성: 파이프라인을 통한 ID 흐름

det_01 ──┐
det_02 ──┤
         ├──▶ ana_01 (based_on: [det_02]) ──┐
         │    ana_02 (based_on: [])          ├──▶ edt_01 (findings: [ana_01, ana_02], context: [det_01]) ──▶ des_01 (section: edt_01, data_source: ana_01)
         │    ana_03 (based_on: [det_01])    │    edt_02 (findings: [ana_03], context: [det_02])         ──▶ des_02 (section: edt_02, data_source: ana_03)
         └────────────────────────────────────┘

최종 HTML의 모든 값은 추적 가능합니다: HTML data-des="des_01" → designer.json des_01.data_source="ana_01" → analyst.json ana_01.calculation.code → 검증 가능.

인계 규칙

• 각 아티팩트는 다음 단계가 시작되기 전에 완료되어야 합니다.
• 아티팩트에 필요한 섹션이 누락된 경우, 진행하기 전에 수정하세요.
• 미디어 풍부성 게이트 (Designer 이후, Programmer 이전): designer.json은 5가지 채널(차트, 이미지, 비디오, 오디오, 인터랙티브_또는_지도)을 모두 사용해야 합니다. used: false로 표시된 채널의 경우, 문서화된 폴백이 진정으로 시도되었고 데이터 기반 이유가 meta.media_decisions에 기록되었는지 확인하세요. 편의상 건너뛰었거나 데이터가 지원할 수 없는 이유로 건너뛴 경우, Programmer가 실행되기 전에 Designer에게 다시 보내세요.
• 생성된 모든 에셋은 PROJECT_DIR/assets/에만 저장됩니다.
• 최종 산출물: PROJECT_DIR/index.html, PROJECT_DIR/detective.json, PROJECT_DIR/analyst.json, PROJECT_DIR/code/*.py, PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/designer.json, PROJECT_DIR/inspector.json, PROJECT_DIR/viewer.html.