amirtaherkhani/diago

Archify

작은 타입의 JSON 명세에서 셀프 컨테이너 방식의 인터랙티브 HTML 다이어그램을 생성합니다. 정적 출력이 기본값이며, 사용자가 데모나 프레젠테이션을 요청할 때만 모션을 활성화하세요.

빠른 작성 경로

일반적인 생성에는 이 제한된 경로를 사용하세요. 사용자가 해당 기능에 대해 묻지 않는 한 선택적 뷰어 런타임 참조는 읽지 마세요.

1. 질문에서 architecture, workflow, sequence, dataflow, 또는 lifecycle 중 하나를 선택합니다.

2. schemas/에서 일치하는 스키마 하나, schemas/common.schema.json 하나, 그리고 examples/에서 일치하는 JSON 예제 하나를 읽습니다. 해당 파일만 읽습니다. 새로운 저작은 새로운 안정적인 ID, 도메인 단어, 레이아웃을 의미합니다. 예제는 사실이 아닌 필드 형태를 위해 사용합니다.

3. 먼저 아티팩트: 다음 도구 작업은 후보를 작성해야 합니다. 후보를 렌더러 내부를 조사하기 전에 작성하세요. 정확한 좌표를 산문으로 계획하지 마세요. 하나의 명확한 메인 경로, 짧은 사이드 분기, 드문 레이블, 그리고 최대 12개의 기본 노드로 시작하세요. meta.quality_profile을 "showcase"로 설정합니다. 사용자가 명시적으로 조밀한 standard 맵을 요청하지 않는 한 말입니다. 자동 경로와 레이블로 시작하세요. 진단에서 요구하기 전에 via, channelX, channelY, 또는 labelAt을 추가하지 마세요. 수리당 진단된 지오메트리 제어를 최대 하나만 적용합니다.

4. 모든 후보 편집 후, 그리고 인계 직전에 검증합니다:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   아티팩트 검사가 4개만 있는 영수증은 기본 검증일 뿐이며, 쇼케이스 승인이 아닙니다. 쇼케이스 패스는 9개의 모든 아티팩트 검사에서 구성 오류 0, 경고 0을 보고해야 합니다. 후보가 정확한 meta.quality_profile 필드를 생략하거나 잘못 입력한 경우, 지오메트리 전에 수정하세요. 최종 검증 통과는 후보를 고정시킵니다: 그 후에는 편집하지 마세요.

5. 전달된 HTML의 경우, deliver가 최종 승인 명령입니다:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   0이 아닌 종료 코드는 절대 성공으로 설명될 수 없습니다. 검증이 실패하면 진단된 subject만 변경하고, evidence를 확인하며, supportedFixes 중에서 선택하고, 다시 실행하세요. 목표 오류 수가 새로운 최소값에 도달할 때까지 집중 수정을 계속합니다. 두 번의 연속 라운드가 최상의 수를 개선하지 못하면 중단하고 해결되지 않은 진단을 정직하게 보고합니다.

첫 번째 후보 전에는 renderers/shared/geometry.mjs, 렌더러 소스, 검증기 소스, 테스트, 또는 벤치마크를 읽지 마세요. 지원되지 않는 내부 진단에 대해서만 또는 두 번의 집중 수리가 실패한 후에만 구현을 검사합니다.

라이프사이클 참고: 0..4 단계 열은 메인 레일을 차지합니다. 이벤트/결과 열 0..2는 이후 단계 아래에 정렬됩니다. 복구 가능한 상태는 type: "failure"와 함께 활성 상태로 돌아가는 실제 전환을 사용합니다.

유형 라우터

유형	사용 목적
architecture	컴포넌트, 서비스, 클라우드/보안 경계, 인프라
workflow	프로세스, 승인 게이트, 도구 호출, 런북, CI/CD
sequence	API 호출 체인, 요청 라이프사이클, 비동기 추적, 반환
dataflow	파이프라인, ETL/ELT, 계보, 거버넌스, 소비자
lifecycle	상태/상태 전환, 재시도, 대기 및 터미널 상태

모호한 경우 node bin/archify.mjs guide "<scenario>" --json을 실행하세요. 시나리오 증명 예제는 복사할 사실이 아닌 구조적 참조입니다.

Mermaid 입력

토폴로지와 의미를 위해 Mermaid를 읽은 후, 새로운 Archify JSON을 작성합니다. Mermaid 스타일링을 기계적으로 렌더링하지 마세요.

• flowchart / graph → workflow, 또는 컴포넌트 맵의 경우 architecture.
• sequenceDiagram → sequence; 참여자는 의미적 참여자가 되고 화살표는 메시지가 됩니다.
• stateDiagram → lifecycle; 상태와 전환은 Mermaid 스타일이 아닌 의미를 유지합니다.

작성 불변 규칙

• 하나의 명확한 메인 경로; 사이드 분기는 가장 가까운 메인 경로 노드에서 시작합니다. 라우팅 제어를 추가하기 전에 가치가 낮은 엣지를 제거합니다.
• meta.legend는 정직한 auto 기본값에 대해 생략합니다. 필요한 경우에만 mode: auto|all|hidden과 렌더러가 지원하는 entries.<kind>.label|visible을 사용합니다. 레이블은 의미를 절대 변경하지 않습니다.
• 컴포넌트 유형은 frontend, backend, database, cloud, security, messagebus, external입니다. 변형은 default, emphasis, security, dashed입니다.
• 간격은 중심 거리가 아닌 명확한 갭을 의미합니다. 관계 레이블의 경우, 명확한 갭은 측정된 마스크 너비를 초과해야 합니다. 그렇지 않으면 레이블을 생략하거나 의도적으로 이동합니다.
• 자동 경로는 자체 엔드포인트 측면을 소유합니다. 측면은 방향 계약입니다: 첫 번째 및 마지막 세그먼트는 해당 측면에 수직으로 진입/이탈해야 합니다.
• 자동 포트 분산은 아키텍처, 워크플로우, 데이터 흐름 및 라이프사이클을 위한 기본 렌더러 동작입니다. 단일 관계 및 명시적 via, channelX, channelY, labelAt, 또는 auto가 아닌 경로를 건너뜁니다. 거의 평행한 포트는 외부 브리지를 사용하여 자동 라우팅이 8px 미만 세그먼트 또는 16px 미만 내부 회전을 생성하지 못하도록 합니다.
• 관련 없는 불투명 노드, 모호한 공유 통로, 또는 다른 경로를 마스킹하는 관계 레이블을 엣지가 교차하는 것을 절대 허용하지 마세요.

필드 열거형, 간격 수학, 지오메트리 수리 규칙, 저장소 증거 또는 모드별 배치가 필요한 경우에만 references/authoring-contract.md를 읽으세요.

전달

수리 중에는 validate를 사용하고 최종 승인을 위해 deliver를 한 번 사용하세요. 전달은 정확한 명세 바이트를 개인적인 동일 디렉토리 스냅샷으로 고정하고, 해당 스냅샷을 렌더링 및 검사하며, HTML을 원자적으로 커밋하고, 명세와 아티팩트 모두에 대해 SHA-256 및 바이트 수를 보고합니다.

사용자가 즉시 로컬 미리보기를 원할 때만 --open을 추가하세요. 활성 데스크톱 작성 루프의 경우 선택적 명령은 다음과 같습니다:

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

기본적으로 미리보기를 시작하지 마세요. 미리보기, 저장소 증거, 내보내기 영수증, 시각적 검토 또는 커밋 후 열기를 사용할 때는 references/delivery-contract.md를 읽으세요.

선택적 뷰어 기능

생성된 HTML에는 이미 테마 전환, 팬/줌, 검색, 포커스, 관계 추적, 의미론적 뷰, 프레젠테이션 및 정직한 내보내기가 포함되어 있습니다. 이들은 독자 기능이지 추가 작성 작업이 아닙니다. meta.animation: "trace"는 옵트인입니다. meta.views는 선택 사항이며 최대 5개의 선별된 챕터를 포함해야 합니다.

사용자가 공유 카드, 경로/도달 카드, 모션, 가이드 스토리, 딥 링크, 프레젠테이션, 검색/포커스 또는 기타 뷰어 런타임 기능을 명시적으로 요청할 때만 references/viewer-runtime.md를 읽으세요.

설정 및 폴백

스킬 패키지 내부에는 설치가 필요하지 않습니다. 다음으로 확인하세요:

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

쉘 접근이 불가능한 경우, 아키텍처 SVG를 assets/template.html에 직접 배치하고, 인라인 색상 대신 CSS 의미론적 클래스를 사용하며, references/delivery-contract.md의 시각적 검토 계약을 따르세요.

출력

확인된 HTML 경로, 다이어그램 유형, 검증 요약, 명세/아티팩트 영수증 및 정직한 시각적 검토 상태를 반환합니다. 0이 아닌 명령에 대해 성공을 주장하거나 수행하지 않은 시각적 검사를 주장하지 마세요.