birchloveye/draw-flowchart

플로우차트 포스터 그리기

작업은 두 부분으로 나뉩니다:

1. 프로세스를 Mermaid로 변환합니다. 이 부분은 판단력이 필요합니다: 상태는 무엇인지, 어떤 분기가 누락되었는지, 프로세스가 어디에서 막히거나 규칙을 위반할 수 있는지.
2. scripts/make_poster.py가 렌더링합니다. 모델이 관여하지 않으므로 동일한 입력은 항상 동일한 포스터를 생성합니다.

<skill>은 이 파일이 들어 있는 폴더를 나타냅니다.

워크플로

1. 프로세스를 이해합니다. 사용자의 목표를 한 문장으로 다시 말합니다. 모호한 점, 누락된 분기("이 단계가 실패하면 어떻게 되나요?") 및 위험한 단계를 나열합니다. 직접 해결할 수 없는 분기에 대해서만 사용자에게 질문합니다.

2. 모델링합니다. 차트 폴더를 만듭니다(포스터당 하나의 폴더).

   • pstack 사용 (권장). pstack의 statechart 스킬을 사용할 수 있는 경우(Claude Code: /pstack:statechart; Cursor: /statechart; 또는 디스크의 SKILL.md), 이를 사용합니다: 사용자의 규칙을 INVARIANT로 갖는 TLA+ 스펙을 작성하고, 실행한 후 report.md를 읽습니다. references/pstack-statechart.md에 설명된 대로 뷰 모듈을 작성하여 차트가 깔끔하게 변환되도록 합니다. 그런 다음 변환합니다:

     python3 <skill>/scripts/make_poster.py <folder> --from-statechart <statechart-out>/chart.mmd
     

     이 명령은 <folder>/flow.mmd를 작성하고 문제 번호를 순서대로 출력하며 각 문제가 위반하는 규칙도 함께 출력합니다. 사용자가 pstack을 끄도록 요청한 경우 켜지 말고 다음 경로를 사용한다고 알립니다.
   • pstack 없이. references/mermaid-rules.md를 따라 수동으로 <folder>/flow.mmd를 작성합니다. 발견한 각 문제(위반된 규칙, 막다른 길, 누락된 분기)는 breaks 클래스로 표시합니다.
   • make_poster.py <folder> --init [--lang zh] 명령은 편집 가능한 시작용 flow.mmd와 poster.json을 작성합니다.

3. <folder>/poster.json을 작성합니다 (references/poster-json.md): 사용자 언어로 된 제목, 부제, 범례, 그리고 breaks 노드당 한 줄씩 카드(숫자와 동일한 순서).

4. 렌더링합니다.

   python3 <skill>/scripts/make_poster.py <folder>
   

   오류가 있는 동안에는 아무것도 그리지 않고 먼저 검사합니다. 모든 오류를 수정하고, 모든 경고를 읽습니다. 출력: poster.html (자체 포함, 오프라인 작동), poster.png (2x) 및 poster.svg.

5. poster.png를 확인합니다. 이미지를 볼 수 없거나 비용을 절약하려면 이 작업을 저렴한 모델이나 하위 에이전트에 넘깁니다. 확인 사항:

   • 빨간색 원이 있는 모든 노드에 카드 줄이 있고 번호가 일치하는지;
   • 어떤 선도 텍스트를 통과하거나 잘못된 상자에 연결된 것처럼 보이지 않는지;
   • 레이블이 사용자 언어로 되어 있고 읽을 수 있을 만큼 짧은지;
   • 중요한 부분이 좁게 느껴지지 않는지. 수정 방법: 레이블을 짧게 하고, 줄 바꿈이 필요한 곳에 공백을 넣고, 큰 차트를 두 개의 포스터로 나누거나 poster.json style에서 간격을 재정의합니다. 그런 다음 다시 렌더링합니다.

6. 사용자에게 보고합니다: 먼저 PNG 경로를, 그 다음 문제당 한 줄(규칙과 프로세스가 해당 상태에 도달하는 방법), 마지막으로 모델이 생략한 내용을 알립니다. poster.html에 PNG/SVG 내보내기 버튼이 있다고 언급합니다.

요구 사항

• Python 3.8+ (표준 라이브러리; Pillow가 설치되어 있으면 사진 크기 축소에 사용됨).
• PNG/SVG 내보내기를 위한 Chrome, Edge 또는 Chromium. 찾을 수 없으면 poster.html은 여전히 작성됩니다. 내보내기를 활성화하려면 CHROME을 브라우저 바이너리로 설정하세요.
• 선택 사항: TLA+ 검사를 위한 pstack (https://github.com/cursor/plugins/tree/main/pstack). Java 11+ 및 TLA+ 도구가 필요합니다 (references/pstack-statechart.md 참조).
• 글꼴은 시스템 글꼴입니다(macOS: American Typewriter, Baskerville, Songti, Kaiti; Windows 및 Linux는 Courier New / Georgia / SimSun / Noto Serif CJK로 대체). Linux의 경우 중국어를 위해 Noto Serif CJK와 같은 CJK 글꼴을 설치하세요.

한계

• 위에서 아래로의 레이아웃만 지원합니다.
• 복합 상태, 병렬 영역, 노트 또는 서브그래프는 지원하지 않습니다. 상태차트 출력의 경우 플랫 뷰(state()가 문자열을 반환)를 사용하세요.
• 15~25개의 상자에 가장 적합합니다. 30개를 초과하면 검사에서 경고합니다. 더 큰 프로세스는 여러 포스터로 나누세요.
• 자동 레이아웃은 때때로 관련 없는 상자 가까이에 선을 배치할 수 있습니다. 이것이 5단계가 존재하는 이유입니다.

예시

저장소의 examples/paper-submission/ 폴더: 저널 투고의 TLA+ 모델(statechart/), 변환된 flow.mmd, poster.json 및 렌더링된 포스터. examples/paper-submission-zh/는 중국어 뷰가 있는 동일한 모델입니다.