基本流程
- 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 或审计者需要底层契约时，再回到这里。