기본 흐름
- Agent가 하나의 .owx 소스 패키지를 작성합니다.
ow a2ui check가 폐쇄형 작성 계약에 맞춰 소스를 검증합니다.ow a2ui compile가 타입이 지정된 Render Document JSON 산출물을 만듭니다.ow publish가 검증된 산출물을 OWL Compose Hosted로 보냅니다.
OWX가 유일한 작성 원본입니다. 컴파일된 JSON은 출력물이지 두 번째 작성 언어가 아닙니다. 지원되지 않는 XML, 임의의 HTML, JavaScript, 원시 Markdown, 수동으로 편집한 컴파일 파일은 계약 범위 밖입니다.
튜토리얼
OWX 문서를 단계별로 만들어 보세요.
이 튜토리얼은 최소 문서에서 시작해 데이터, 쿼리, 팩트, 표시 컴포넌트를 차례로 추가하고 검증·컴파일·게시 명령을 실행합니다. 정확히 확인할 때는 마지막의 노드 표와 기계 계약을 사용하세요.
1. 문서 뼈대부터 시작하기
모든 작품에는 하나의 ow-document 루트가 있습니다. 정확한 프로토콜 버전과 메타데이터를 선언하고 독자용 내용을 section과 타입 노드 안에 넣습니다.
<ow-document owx-version="1" title="Decision brief" canvas="briefing">
<section id="overview">
<ow-text id="summary" title="Decision brief" title-level="1" body="A concise conclusion." />
</section>
</ow-document>루트 title은 메타데이터입니다. 화면에 보이는 제목은 명시적인 ow-text 자식으로 만들고 같은 제목을 일반 문장으로 반복하지 마세요.
2. 데이터, 쿼리, 팩트 추가하기
근거를 타입화하고 재현 가능하게 유지하세요. 데이터셋을 불러오고 쿼리로 변환한 다음, 컴포넌트가 표시할 정확한 값을 fact로 노출합니다.
<ow-document owx-version="1" title="Regional revenue">
<ow-data id="sales" src="./sales.csv" schema="./sales.toml" />
<ow-query id="sales-by-region" from="dataset:sales">
<ow-group by="region" />
<ow-aggregate name="revenue" operation="sum" field="revenue" />
</ow-query>
<ow-fact id="total-revenue" query="query:sales-by-region" field="revenue" />
</ow-document>Query는 변환을 설명하고 Fact는 표시 노드가 소비할 값에 이름을 붙입니다. 컴파일된 JSON을 손으로 편집해 숫자를 바꾸지 마세요.
3. 지원되는 컴포넌트 배치하기
타입이 지정된 레이아웃과 표시 노드로 독자 화면을 구성합니다. 메트릭, 차트, 테이블은 검증된 쿼리나 팩트에 연결하고 본문에서 같은 주장을 반복하지 않습니다.
<section id="summary">
<ow-grid id="cards">
<ow-metric id="revenue" fact="fact:total-revenue" label="Revenue" />
<ow-chart id="revenue-chart" data="query:sales-by-region" type="bar" title="Revenue by region" summary="Compare revenue by region." />
<ow-table id="regional-table" data="query:sales-by-region" title="By region" />
</ow-grid>
</section>독자의 질문에 맞는 컴포넌트를 고르세요. 차트, 테이블, 지도, 관계도는 데이터 바인딩과 시각적 역할이 명확할 때만 유용합니다.
4. 검증하고 컴파일하고 게시하기
소스 패키지가 작성 원본입니다. 결정적 검사를 순서대로 실행하고 컴파일 결과를 확인한 뒤 검증된 Render Document JSON 산출물만 게시합니다.
ow a2ui check ./artifact/document.owx
ow a2ui fmt ./artifact/document.owx
ow a2ui compile ./artifact/document.owx --output ./artifact/document.json
ow a2ui digest ./artifact/document.json
ow publish ./artifact/document.json --no-open`check`는 문법, 타입, 바인딩, catalog 소속, 리소스 경계를 검사합니다. `compile`은 산출물을 만들고 `digest`는 정확한 식별자를 기록하며 `publish`는 Hosted로 보냅니다.
자주 쓰는 노드 한눈에 보기
Agent가 가장 자주 사용하는 노드입니다. 각 시그니처에는 노드를 식별하는 일반적인 속성이 표시됩니다. 모든 선택 필드나 자식 관계가 필요하면 생성된 catalog를 확인하세요.
문서 구조
루트에서 시작해 모든 화면 영역에 실제 부모를 둡니다.
| 태그 | 시그니처 | 용도 |
|---|---|---|
ow-document | <ow-document owx-version title> | 단 하나의 작성 루트이자 프로토콜 경계. |
section | <section id> | 안정적인 id를 가진 의미적 페이지 영역. |
ow-text | <ow-text id title title-level> | 보이는 제목, 설명, 본문 또는 팩트 참조. |
ow-grid | <ow-grid id class> | 타입 자식을 배치하는 반응형 레이아웃 컨테이너. |
데이터와 근거
소스에서 표시 값까지의 경로를 검사할 수 있게 만듭니다.
| 태그 | 시그니처 | 용도 |
|---|---|---|
ow-data | <ow-data id src schema> | 패키지 내부 소스에서 불러오는 타입 데이터셋. |
ow-query | <ow-query id from> | 같은 절차로 다시 실행할 수 있는 필터·파생·그룹·집계 파이프라인. |
ow-fact | <ow-fact id query field> | 쿼리와 필드에서 해석되는 이름 있는 값. |
ow-sources | <ow-sources src> | 작품에 연결된 소스 원장. |
표현
구체적인 독자 질문에 답할 때만 타입 시각화를 사용합니다.
| 태그 | 시그니처 | 용도 |
|---|---|---|
ow-metric | <ow-metric id fact label> | 하나의 팩트에 연결된 강조 값. |
ow-chart | <ow-chart id data type title summary> | 유형을 명시하고 쿼리에 연결한 차트. |
ow-table | <ow-table id data> | 검증된 데이터셋이나 쿼리의 표 보기. |
ow-map | <ow-map id data place country level join value title summary> | 장소와 값 필드를 가진 지리적 보기. |
관계와 상호작용
임의의 HTML을 그리지 말고 토폴로지와 제한된 상태를 선언합니다.
| 태그 | 시그니처 | 용도 |
|---|---|---|
ow-graph | <ow-graph id layout direction> | 토폴로지를 인식하는 그래프 컨테이너. |
ow-graph-node | <ow-graph-node id label> | ow-graph 안의 라벨이 있는 노드. |
ow-connector | <ow-connector from to> | 알려진 끝점을 연결하는 타입 관계. |
ow-view-switcher | <ow-view-switcher id label> | 이름이 있는 제한된 뷰 모음. |
보조 콘텐츠
패키지 내부 미디어와 명시적인 보조 블록을 사용합니다.
| 태그 | 시그니처 | 용도 |
|---|---|---|
ow-media | <ow-media id file alt> | 의미 있는 alt가 있는 패키지 내부 이미지. |
ow-code | <ow-code id language value> | 언어를 명시한 코드 블록. |
ow-list | <ow-list id> | 순서가 있거나 없는 타입 목록. |
ow-callout | <ow-callout id title body> | 라벨이 있는 참고 또는 결정 콜아웃. |
안전한 결과를 위한 규칙
- 작성 catalog는 폐쇄형입니다. 등록되지 않은 ow-* 태그나 속성을 대체 컴포넌트로 사용할 수 없습니다.
- .owx 하나를 작성 원본으로 유지하세요. 컴파일된 JSON은 생성 산출물이지 두 번째 작성 언어가 아닙니다.
- 외부 사실은 타입 데이터, 쿼리, 팩트로 연결하고 화면을 채우려고 값을 만들지 마세요.
- 패키지 내부 미디어와 지원되는 class만 사용합니다. 임의 HTML, JavaScript, 원격 자산, 경로 탈출은 거부됩니다.
지원되는 OWX 흐름
기계 계약 및 감사 가이드
위 튜토리얼이 일반적인 진입점입니다. 아래 링크에서 지원되는 흐름, 이 페이지의 노드 표, 유지 관리되는 CLI 및 저작 가이드를 확인할 수 있습니다. Agent나 검토자가 이름·속성·관계·버전을 검증할 때 사용하세요.
사람에게 보여줄 것
작성자 화면에는 목표, 자료, 소스 경계, 검증 결과, 실제 미리보기, 승인을 기다리는 작업이 보여야 합니다. 원시 OWX는 감사 화면이지 기본 독자 경험이 아닙니다. 출처나 디버깅이 필요할 때만 소유자가 소스 패키지와 정확한 digest를 확인합니다.
OWL Compose가 처음인가요?
Agent와 시작하세요.
먼저 제품 흐름을 알아보세요. Agent나 감사자가 기반 계약을 확인해야 할 때만 여기로 돌아오면 됩니다.