Flujo básico

El agente escribe un paquete fuente .owx.
ow a2ui check valida la especificación de autoría cerrada.
ow a2ui compile emite el artefacto JSON tipado de Render Document.
ow publish envía el artefacto validado a OWL Compose Hosted.

OWX es la fuente de autoría. El JSON compilado es una salida, no un segundo lenguaje de autoría. XML no compatible, HTML arbitrario, JavaScript, Markdown sin procesar y archivos compilados editados a mano quedan fuera del contrato.

Tutorial

Crea un documento OWX paso a paso.

Este tutorial empieza con un documento mínimo, añade datos, consultas, hechos y componentes de presentación, y termina con los comandos para validarlo, compilarlo y publicarlo. Consulta la tabla de nodos y el contrato de máquina del final cuando necesites una referencia exacta.

1. Empieza por la estructura del documento

Cada trabajo tiene una única raíz ow-document. Declara la versión exacta del protocolo y los metadatos, y coloca el contenido para lectores dentro de sections y nodos tipados.

<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>

El title de la raíz es metadato. Un encabezado visible debe ser un hijo ow-text explícito; no repitas el mismo título como texto suelto.

2. Añade datos, consultas y hechos

Mantén la evidencia tipada y reproducible. Carga un dataset, transfórmalo con una consulta y expón mediante un fact el valor exacto que debe mostrar un componente.

<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>

Las queries describen transformaciones; los facts nombran los valores que consumen los nodos de presentación. No edites a mano el JSON compilado para cambiar una cifra.

3. Coloca componentes compatibles

Compón la vista del lector con nodos tipados de diseño y presentación. Enlaza métricas, gráficos y tablas a una consulta o un hecho verificado en vez de repetir afirmaciones en prosa.

<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>

Elige el componente según la pregunta del lector. Un gráfico, una tabla, un mapa o un grafo solo sirve cuando su vínculo de datos y su papel visual son explícitos.

4. Valida, compila y publica

El paquete fuente es el origen editable. Ejecuta los controles en orden, revisa el resultado compilado y publica únicamente el artefacto JSON de Render Document validado.

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` detecta sintaxis, tipos, bindings, pertenencia al catalog y límites de recursos. `compile` crea el artefacto, `digest` registra su identidad exacta y `publish` lo envía a Hosted.

Nodos habituales de un vistazo

Estos son los nodos que un agente usa con más frecuencia. Cada firma muestra los atributos que suelen identificarlo; consulta el catalog generado para todos los campos opcionales y relaciones de hijos.

Estructura del documento

Empieza por la raíz y da un padre real a cada región visible.

Etiqueta	Firma	Uso
`ow-document`	`<ow-document owx-version title>`	La única raíz de autoría y límite del protocolo.
`section`	`<section id>`	Una región semántica con un id estable.
`ow-text`	`<ow-text id title title-level>`	Título, antetítulo, cuerpo o referencias a hechos visibles.
`ow-grid`	`<ow-grid id class>`	Contenedor de diseño adaptable para hijos tipados.

Datos y evidencia

Haz inspeccionable el camino desde el material fuente hasta el valor mostrado.

Etiqueta	Firma	Uso
`ow-data`	`<ow-data id src schema>`	Dataset tipado cargado desde una fuente local al paquete.
`ow-query`	`<ow-query id from>`	Pipeline reproducible de filtros, derivados, grupos o agregaciones.
`ow-fact`	`<ow-fact id query field>`	Valor con nombre resuelto desde una consulta y un campo.
`ow-sources`	`<ow-sources src>`	Registro de fuentes asociado al trabajo.

Presentación

Usa una visualización tipada solo cuando responde a una pregunta concreta.

Etiqueta	Firma	Uso
`ow-metric`	`<ow-metric id fact label>`	Valor destacado enlazado a un hecho.
`ow-chart`	`<ow-chart id data type title summary>`	Gráfico enlazado a una consulta con tipo explícito.
`ow-table`	`<ow-table id data>`	Vista tabular de un dataset o consulta verificados.
`ow-map`	`<ow-map id data place country level join value title summary>`	Vista geográfica con campos de lugar y valor.

Relaciones e interacción

Declara topología y estado acotado en vez de dibujar HTML arbitrario.

Etiqueta	Firma	Uso
`ow-graph`	`<ow-graph id layout direction>`	Contenedor de grafo consciente de la topología.
`ow-graph-node`	`<ow-graph-node id label>`	Nodo etiquetado dentro de un ow-graph.
`ow-connector`	`<ow-connector from to>`	Relación tipada entre extremos conocidos.
`ow-view-switcher`	`<ow-view-switcher id label>`	Conjunto acotado de vistas con nombre.

Contenido auxiliar

Usa medios locales al paquete y bloques de apoyo explícitos.

Etiqueta	Firma	Uso
`ow-media`	`<ow-media id file alt>`	Imagen local al paquete con texto alt significativo.
`ow-code`	`<ow-code id language value>`	Bloque de código con lenguaje explícito.
`ow-list`	`<ow-list id>`	Lista tipada ordenada o sin ordenar.
`ow-callout`	`<ow-callout id title body>`	Nota o llamada de decisión con etiqueta.

Reglas para mantener el resultado seguro

El catalog de autoría es cerrado: una etiqueta o atributo ow-* no registrado no es un componente alternativo.
Conserva una única fuente .owx. El JSON compilado es un artefacto generado, no un segundo lenguaje de autoría.
Vincula los hechos externos mediante datos, consultas y facts tipados; no inventes valores para llenar el diseño.
Usa solo medios locales al paquete y clases compatibles. HTML arbitrario, JavaScript, recursos remotos y escapes de ruta fallan de forma cerrada.

Flujo OWX compatible

Guía del contrato de máquina y auditoría

El tutorial de arriba es la entrada normal. Los enlaces siguientes llevan al flujo compatible, al mapa de nodos de esta página y a las guías mantenidas de CLI y autoría, para que un agente o revisor pueda comprobar nombres, atributos, relaciones o versiones.

Flujo OWX compatibleRuta de autoría, validación, compilación y publicación Mapa de nodos de esta páginaNodos habituales, firmas y usos Referencia de comandos CLIComandos para validar, compilar y publicar Guía de autoría OWXIndicaciones mantenidas para obras creadas por agentes

Lo que debe ver una persona

El flujo para autores debe mostrar el objetivo, los materiales, los límites de las fuentes, el resultado de la validación, una vista previa real y la acción pendiente de aprobación. El OWX sin procesar es una superficie de auditoría, no la experiencia de lectura predeterminada. El propietario puede revisar el paquete fuente y el digest exacto cuando necesite comprobar la procedencia o depurar.

¿Nuevo en OWL Compose?

Empieza con tu agente.

Aprende primero el flujo del producto. Vuelve aquí solo cuando el agente o un auditor necesite el contrato subyacente.

Entender OWX primero