Hasan-Laraib/Mirofy

Mirofy은(는) 무엇을 하나요?

작은 형식화된 JSON 명세에서 자체 포함된 대화형 HTML 다이어그램을 생성합니다. 정적 출력이 기본입니다. 사용자가 데모나 프레젠테이션을 요청할 때만 모션을 활성화합니다.

스캔 우선: 실제 리포지토리에서 다이어그램 파생

다이어그램이 존재하는 코드를 설명해야 하는 경우, 기억에 의존하지 말고 파생하십시오:

npm run scan      # 리포지토리 -> 증거 그래프 (사실과 갭)
npm run model     # 증거 + 문서 -> 하나의 시스템 모델
npm run compile   # 모델 -> 의도가 있는 경계 뷰

각 단계는 결정할 수 없었던 것을 보고합니다. scan은 분석할 수 없는 모든 파일에 대한 갭을 기록하고, compile은 생략된 모든 객체와 그 이유를 기록합니다. 사용자에게 이를 전달하십시오. 절반의 시스템을 조용히 생략하는 다이어그램은 생략된 내용을 명시하는 것보다 더 나쁩니다.

사용자가 아직 존재하지 않는 것을 설명하거나 리포지토리를 사용할 수 없는 경우 아래 빠른 경로를 사용하십시오.

빠른 작성 경로

일반 생성을 위해 이 경계 경로를 사용하십시오. 사용자가 해당 기능에 대해 묻지 않는 한 선택적 Viewer Runtime 참조를 읽지 마십시오.

1. 질문에서 architecture, workflow, sequence, dataflow, 또는 lifecycle을 선택합니다.

2. schemas/에서 일치하는 스키마 하나, schemas/common.schema.json 및 examples/에서 일치하는 JSON 예제 하나를 읽습니다. 해당 파일만 읽습니다. 새로운 작성은 새로운 안정적인 ID, 도메인 용어 및 레이아웃을 의미합니다. 예제는 필드 모양을 위한 것이지 사실을 위한 것이 아닙니다. 실제 제품 ID가 중요한 경우 node bin/mirofy.mjs brands "<name>" --json을 실행합니다. 사용자가 제공한 URL이 있는 알 수 없는 브랜드에 대해서만 references/brand-marks.md를 읽습니다.

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

4. 모든 후보 편집 후 및 핸드오프 직전에 유효성을 검사하십시오:

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

   아티팩트 검사가 4개만 있는 영수증은 기본 검증일 뿐이며, showcase 승인이 아닙니다. Showcase 통과는 9개의 모든 아티팩트 검사가 0개의 구성 오류와 0개의 경고로 보고되어야 합니다. 후보가 정확한 meta.quality_profile 필드를 생략하거나 잘못 입력한 경우 기하학보다 먼저 수정하십시오. 최종 검증 통과는 후보를 고정시킵니다. 이후에는 절대 편집하지 마십시오.

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

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

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

첫 번째 후보 전에 renderers/shared/geometry.mjs, 렌더러 소스, 검증자 소스, 테스트 또는 벤치마크를 읽지 마십시오. 지원되지 않는 내부 진단 또는 두 번의 집중 수리 실패 후에만 구현을 검사하십시오.

유형 라우터

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

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

Mermaid 입력

node bin/mirofy.mjs import mermaid <input.mmd> [output.json] [--json]

flowchart/graph → architecture, sequenceDiagram → sequence, stateDiagram(-v2) → lifecycle.

임포터는 추측하지 않습니다. 읽을 수 없는 모든 줄은 해당 줄 번호와 함께 갭이 되므로, 결과를 완전하다고 부르기보다 전달되지 않은 것을 보고하십시오. 또한 위치를 할당하지 않습니다. 변환된 아키텍처는 layout.mode: "grid"를 사용하며, 팬아웃은 노드를 통해 에지를 배치할 수 있으며, 이는 항상 켜져 있는 clean-flow 게이트를 실패하게 합니다. 가져온 후 항상 검증하십시오. 의미도 함께 읽으십시오. 임포터는 도메인 판단이 아닌 토폴로지를 전달하므로 레이블과 유형은 종종 다시 작성할 가치가 있습니다.

기하학 수리

검증이 겹치는 구성 요소를 보고하는 경우, 좌표를 하나씩 수동 편집하지 마십시오:

node bin/mirofy.mjs repair <type> <input.json> [output.json] --safe

--safe는 작성된 좌표를 다시 쓰기 때문에 필수입니다. 수리는 겹침과 관련된 구성 요소만 이동하며, 각각 검증자의 8px 갭을 해제하는 가장 작은 수정으로 이동하고, 모든 조정의 영수증을 출력하며, 지오메트리 외에는 아무것도 건드리지 않습니다(레이블, 유형, 연결 또는 ID는 절대 아님). 재검증하고 변위로 수정할 수 없는 것(라우팅, 레이블 배치)을 다음 실행에서 다시 발견하지 않도록 이름을 지정합니다.

작성 불변 규칙

• 하나의 명백한 주요 경로; 사이드 브랜치는 가장 가까운 주요 경로 노드를 떠납니다. 라우팅 제어를 추가하기 전에 가치가 낮은 에지를 제거하십시오.
• 기본적으로 meta.visual_preset을 생략하여 해결된 색상 모드(밝음 또는 어두움)에 관계없이 모든 다이어그램이 classic으로 열리도록 합니다. 색상 모드와 시각적 프리셋은 독립적입니다. Light/Dark 전환은 현재 프리셋을 유지해야 합니다. 사용자가 명시적으로 해당 시각적 스타일을 요청할 때만 signal-flow, blueprint 또는 editorial을 설정하십시오.
• 기본적으로 meta.subtitle을 생략하십시오. 제목, 노드 또는 카드를 다시 설명하는 부제를 절대 만들지 마십시오. 사용자가 명시적으로 요청할 때만 하나의 짧은 지원 라인을 포함하십시오.
• 독립형 데스크톱 뷰어를 기본적으로 얕은 스트립이 아닌 첫 번째 화면 아티팩트로 취급하십시오. 노트북 및 외부 디스플레이를 위한 하나의 반응형 아티팩트를 생성하십시오. 장치별 HTML이나 대체 토폴로지는 절대 생성하지 마십시오. 뷰어는 라이브 뷰포트 높이에서 외부 읽기 너비만 조정할 수 있습니다. 작성된 SVG/viewBox, 비율, 의미론적 지오메트리 및 일반 문서 흐름을 유지해야 합니다. 넓거나 높은 데스크톱에서는 다이어그램 패널과 필요한 결론 카드가 균형 잡힌 전체로 화면을 차지할 수 있도록 충분한 작성된 수직 리듬을 사용하십시오. 런타임 크기 조정은 과도하게 압축된 Y 레이아웃이나 너무 작은 명시적 meta.viewBox를 복구할 수 없습니다. 핸드오프 전에 실제 HTML을 1440x900, 1600x1000 및 1920x1080에서 엽니다. 대형 데스크톱 디스플레이용 구성의 경우 2048x1320에서도 확인하십시오. 모든 확인된 크기에서 document.documentElement.scrollWidth <= window.innerWidth 및 scrollHeight <= window.innerHeight를 요구하면서 다이어그램이 가장 큰 확인된 뷰포트에서 편안하게 읽을 수 있고 수직적으로 균형이 잡혀 있는지 시각적으로 확인하십시오. 노드, 레이블 또는 메인 패널을 축소하기 전에 진정으로 중복된 콘텐츠를 제거하거나 간격을 압축하여 오버플로를 수리하십시오. 가장 큰 뷰포트에서 여전히 뷰어의 너비 캡에서 눈에 띄는 빈 하단 밴드가 있는 경우, 작성된 Y 위치를 재분배하고 viewBox 높이를 비례적으로 늘리십시오. 필러 카피나 장식용 카드를 추가하지 마십시오. overflow: hidden, 잘린 콘텐츠, 내부 다이어그램 스크롤러, 늘어난 SVG 높이 또는 더 작은 타이포그래피로 통과를 위조하지 마십시오. 좁은/모바일 레이아웃은 포함이 필요할 때 수직으로 스크롤될 수 있습니다.
• 진실한 auto 기본값에 대해 meta.legend를 생략하십시오. 필요한 경우에만 mode: auto|all|hidden 및 렌더러 지원 entries.<kind>.label|visible을 사용하십시오. 레이블은 의미를 변경하지 않습니다.
• 명시적인 사용자 선택에서 하나의 기본 작성 언어를 선택하십시오. 그렇지 않으면 요청 또는 대화의 지배적인 언어를 따르십시오. meta.locale은 렌더러 소유 Viewer UI만 제어합니다. 지원되는 해당 기본 언어에 대해 "en" 또는 "zh-CN"을 사용하십시오. 다른 모든 언어의 경우 meta.locale을 생략하고 고정된 Viewer UI와 <html lang>이 영어로 대체된다는 점을 명시적으로 공개하십시오. 렌더러는 작성된 콘텐츠를 번역하지 않습니다. 자세한 내용은 references/authoring-contract.md를 참조하십시오.
• 정확한 제품 이름, 코드 식별자, 명령, 프로토콜, API 경로 및 환경 이름을 유지하십시오. 지역화된 텍스트 내에서 영어로 남아 있을 수 있지만, 주변 설명 산문을 다른 언어로 남겨두는 것을 정당화하지 마십시오.
• 브랜드 ID는 선택 사항이며 명시적입니다. 노드가 해당 실제 제품의 이름을 지정할 때 brand에 표준 내장 ID를 넣으십시오. 일치하는 프리셋이 없고 사용자가 공식 HTTP(S) URL을 제공한 경우 먼저 node bin/mirofy.mjs brands capture "<url>" --json을 실행한 다음 반환된 다이제스트 고정 brand 객체를 작성하십시오. 렌더 및 검증은 고정되지 않은 캡처를 절대 수행하지 않습니다. 그렇지 않으면 brand를 생략하십시오. "데이터베이스"와 같은 모호한 역할에서 브랜드를 추론하지 말고 배지가 의미론적 type, 레이블 또는 관계 사실을 대체하지 않도록 하십시오.
• 시퀀스 다이어그램의 경우 안정적인 fixed 레이아웃에 대해 meta.column_fit을 생략하십시오. 넓은 viewBox가 사용되지 않은 수평 공간을 남기거나 의미 있는 참가자 레이블이 고정된 상자에 맞지 않을 때 "spread"로 설정하십시오. spread를 시도하기 전에 의미론적 레이블을 줄이지 마십시오.
• 컴포넌트 유형은 frontend, backend, database, cloud, security, messagebus, external입니다. 변형은 default, emphasis, security, dashed입니다.
• 관계 레이블은 의미론적 데이터입니다. 충돌이 발생하면 레이블을 이동하고 경로 또는 간격을 조정한 다음 의미를 유지하면서 단어를 줄이십시오. 두 엔드포인트가 관계를 완전히 암시하고 프로토콜, 동작, 방향, 동기/비동기 동작 또는 경계 간 메커니즘이 포함되지 않은 경우에만 레이블을 삭제하십시오. 삭제된 레이블이 왜 중복되는지 설명하십시오. showcase를 통과하기 위해 의미 있는 레이블을 삭제하지 마십시오.
• 기본적으로 meta.engineering_profile을 생략하십시오. 지역, 클러스터 및 보안 경계 표현이 그 자체로 활성화하지는 않습니다. 사용자가 프로덕션 배포 토폴로지, 소유권 핸드오프 또는 폐쇄 실패 배포 검토를 명시적으로 요청하고 소스 사실이 알려진 경우에만 deployment-ownership을 활성화하십시오. 일단 활성화되면 검증을 통과하기 위해 엔지니어링 프로필을 제거해서는 안 됩니다. 사실을 수리하거나 진단을 진실하게 보고하십시오.
• 간격은 중심 거리가 아닌 명확한 갭을 의미합니다. 관계 레이블의 경우 명확한 갭은 측정된 마스크 너비를 초과해야 합니다. 삭제를 고려하기 전에 레이블 보존 수리 순서를 사용하십시오.
• 자동 경로는 자체 엔드포인트 측면을 소유합니다. 측면은 방향 계약입니다. 첫 번째 및 마지막 세그먼트는 해당 측면에 수직으로 떠나거나 들어와야 합니다.
• 자동 포트 확산은 architecture, workflow, data-flow 및 lifecycle에 대한 기본 렌더러 동작입니다. 단일 관계 및 명시적 via, channelX, channelY, labelAt 또는 auto가 아닌 경로를 건너뜁니다. 병렬 포트 근처에서는 자동 라우팅이 8px 미만의 세그먼트 또는 16px 미만의 내부 회전을 생성할 수 없도록 외부 브리지를 사용합니다. Architecture는 별도로 장애물이 없는 마주보는 자동 포트(left/right 또는 top/bottom)를 오프셋이 16px 미만이고 두 포트 모두 모서리 여유를 유지할 때 하나의 공유 축에 유지합니다. 정확히 하나의 엔드포인트가 확산된 경우 공유되지 않은 엔드포인트만 해당 축으로 이동할 수 있습니다. 두 엔드포인트가 모두 확산된 경우 경쟁 포트가 구별되도록 외부 브리지를 유지하십시오.
• 관련 없는 불투명 노드, 모호한 공유 복도 또는 다른 경로를 가리는 관계 레이블을 가로지르는 에지를 절대 허용하지 마십시오.

references/authoring-contract.md는 필드 열거형, 간격 수학, 자동 포트 배치, 지오메트리 수리 규칙, 리포지토리 증거 또는 모드별 배치가 필요할 때만 읽으십시오.

전달

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

전달 후, 신뢰할 수 있는 HTML을 수정하거나 다시 렌더링하지 않고 경계 데스크톱 증거를 수집하십시오:

node bin/mirofy.mjs visual-check <output.html> --json

visual-check는 1440x900, 1600x1000, 1920x1080 및 2048x1320에서 포함을 측정합니다. 가장 작은 크기와 가장 큰 크기에서 밝음/어두움 스크린샷을 캡처하고 아티팩트 옆에 상대 경로 접촉 시트 및 JSON 사이드카를 작성합니다. 자동화된 영수증은 항상 visualReview: "pending"을 보고합니다. 스크린샷은 검사를 위한 증거이지 자동 폴리시 주장이 아닙니다. 종료 0은 포함 및 캡처가 통과되었음을 의미하고, 1은 오버플로 또는 캡처 실패를 의미하며, 2는 Chrome/Chromium을 사용할 수 없고 영수증이 skipped임을 의미합니다. 이 명령은 전달된 HTML을 절대 변경하지 않습니다. 사용자가 즉시 로컬 미리보기를 원할 때만 --open을 추가하십시오. 활성 데스크톱 작성 루프의 경우 선택적 명령은 다음과 같습니다:

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

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

선택적 뷰어 기능

생성된 HTML에는 이미 테마 전환, 팬/줌, 검색, 포커스, 관계 추적, 의미론적 뷰, 프레젠테이션 및 진실한 내보내기가 포함되어 있습니다. 이들은 추가 작성 작업이 아닌 독자 기능입니다. meta.animation: "trace"는 옵트인입니다. meta.views는 선택 사항이며 최대 5개의 큐레이션된 챕터를 포함해야 합니다. 사용자가 공유 카드, 경로/도달 카드, 모션, 안내 스토리, 딥 링크, 프레젠테이션, 검색/포커스 또는 기타 Viewer Runtime 기능을 명시적으로 요청할 때만 references/viewer-runtime.md를 읽으십시오.

설정 및 대체

스킬 설치는 선택 사항입니다.