omni-content-builder

Omni 内容构建器

通过 Omni CLI 以编程方式创建、更新和管理 Omni 文档、仪表板和应用，包括文档生命周期、草稿、工作簿模型、筛选器、控件和仪表板内容。

提示：使用 omni-model-explorer 了解可用字段，并使用 omni-content-explorer 查找现有仪表板以便修改或参考。

文档通过 v2 documents API（omni documents v2-*）创建和编辑，该 API 使用明确的封装结构，包括 queryPresentations、controls、containers 和 settings，并通过 草稿 → 发布 流程进行编辑。这是构建、读取或更改文档的唯一途径——切勿回退到 v1 documents create/get 命令（v1 put/update 已在 CLI 1.2.2 中移除）。少数文档管理操作（列出、删除、移动、复制、下载）没有 v2 形式；请参阅下方的命令。

设计默认规范

这里的机制旨在构建一个 正确 的仪表板；若要打造一个 出色 的仪表板，请遵循 Omni 的仪表板最佳实践。以下要点是该指南在没有其他明确要求时的默认规范。它们绝不会凌驾于已给出的要求之上：用户指定的布局、图表类型、配色或控件位置优先；你正在编辑的现有仪表板惯例或当前生效的组织主题也同样优先。如果某项要求与默认规范冲突，请遵循该要求，最多只需提及一次默认规范。没有其他要求时，默认采用以下做法：

• 在左上角突出答案。 将主要 KPI / 用于回答问题的图表放在左上方——查看者通常会按 F/Z 形路径浏览。
• 每页放置 3–5 个图表。 超出此数量时，拆分到多个页面/标签页（请参阅 containers.md）。
• 颜色服务于功能，遵循 90/10 原则。 以中性色调为主，用一种强调色突出重点或状态，而非装饰。
• 根据问题选择图表——趋势 → 折线图/面积图/柱状图；排名 → 横向条形图；部分与整体 → 100% 堆叠图；相关性 → 散点图。
• 将控件放在其作用对象旁边， 并使用以操作为导向的标签（例如“按地区筛选”，而不是“地区”）。
• 将复杂性隐藏在父控件之后——一个控件驱动多个项目；不放置子控件（请参阅 controls.md）。
• 图表无需悬停即可读懂。 查看者应能直接从图表中获取关键信息；工具提示用于补充细节，而不是传递核心信息。

对于运营或高管仪表板，还应遵循 references/dashboard-style.md（打造可助人采取行动的仪表板）：

• 按仍有机会改变的事项排序。 将有风险的事项排在已无法挽回的事项前；每行列表都注明负责人。
• 表格列数不超过 5 列，且表头不得截断。 否则使用 markdown {{#result}} 列表行；根据图块大小设置 limit，并检查 PNG。
• 每个视图都支持下钻。 在 markdown 中使用 {{view.field.value}} 显示名称和关键数字；.value_static 仅用于展示。
• 日期一律使用相对日期——日期控件和每个图块筛选器都如此；标题或标签中不要使用月份名称。
• 每种颜色只表示一种含义， 并始终附带文本标签；明确设置单序列颜色。
• 在图块筛选器中固定范围；查看者控件不超过 5 个。
• 适合触发提醒的图块应使用简短的分类关注列表（约 10 行，并按阈值筛选），且在副标题中注明触发条件。

已知问题与安全默认规范

• 发布前务必运行完整的验证流程——请参阅下文的 验证流程。
• 图块读回的结构与写入时相同。 v2-get / v2-get-draft 会以 { visType, config } 的形式返回内部可视化配置，因此可以按原样编辑图块并将其补丁写回，包括恢复、复制和移动图块。验证写入的每个图块：读回图块并在发布前运行其查询。请参阅 references/documents-v2.md。
• 补丁按键合并；只有 containers（以及 order 数组）会被完整替换。 要更改一个图块，只发送对应的键。要删除图块，将其键设为 null，并从 order 中移除。发送 containers 时，请发送已应用编辑的完整布局树；省略它则保留布局，并让服务自动放置新增图块。
• 创建或补丁请求未携带 containers 时，新图块会自动放置——每个符合仪表板条件的图块都会放到第一页。只有在需要自行设置布局时才发送 containers，并确保引用每个应显示的图块。请参阅 references/containers.md。
• 创建时的图块 "1" 会与服务端种子图块合并，即使发送 false，它仍会保留 automaticVis: true（从图块 "2" 开始则会保留 false）。如果这点很重要，请在草稿上再次补丁更新图块 "1"。
• 控件只会显示在容器放置它的位置。 要隐藏控件，请将其从所有容器中移除；它仍会继续应用其值。请参阅 references/controls.md。
• 图块查询不包含 modelId。 不要在图块查询中发送 modelId 或 model_extension_id；服务会将图块关联到文档的工作簿模型，并在不发出警告的情况下改写你发送的任何值。其他必需的查询字段列于 references/documents-v2.md；省略其中任意字段都会返回一条指出该字段的 400 错误。
• 硬性规则——未经用户明确决定，不得使用交接过来的 SQL 创建非主题图块。 先将每个查询映射到一个主题（请参阅 omni-query）。如果没有合适的主题，请停止并询问用户是要扩展现有主题还是创建新主题（通过 omni-model-builder 在分支上操作，且仅在获得确认后合并）。只有用户明确选择此路径后（拒绝建模、确实只需一次性使用，或必须使用 userEditedSQL），才能创建非主题 / userEditedSQL 图块；对于交接过来的 SQL，Access Boost 绝不是默认选项。请参阅基于主题构建查询。
• 查看者和受限查询者看不到非主题图块。 userEditedSQL 有值的图块，或不含 join_paths_from_topic_name 的基础视图查询，均属于非主题图块。在最终确定此类图块之前，请询问仪表板的受众是否包括这些角色。如果包括，请建议将 Access Boost 作为单独且经过明确确认的步骤（它仅会让所选用户、群组或整个组织在仪表板上查看这些图块；需要组织功能以及文档的 Manager 权限），并使用满足需求的最小范围。未经用户同意，绝不要启用。请参阅 references/queryPresentations.md 中的 原始 SQL 图块 配方，以及 omni-admin → 文档权限。
• --body 会覆盖简写标志。 使用 --body 时，所有简写标志（--name、--summary、--branch-id 等）都会被忽略，且不会发出警告。每次创建和补丁请求都要将这些字段放入 JSON 请求体；只有当标志足以构成完整请求时，才在不使用 --body 的情况下使用标志。
• 工作簿模型 ID 会随每次草稿和发布而变化——每个草稿都会复制工作簿模型（包括扩展），发布时文档会切换到该副本。不要缓存工作簿模型 ID；每次需要时，都从 v2-get-draft（或 omni documents list-drafts <identifier>）读取 workbookModelId。
• Markdown 图块需要设置 automaticVis: false——否则渲染器会自动生成图表，导致图块空白。请参阅 references/visConfig.md；Markdown KPI 和卡片配方见 references/markdown-tiles.md。
• Mustache：从 filters 读取筛选器的值。 要在图块标题中显示筛选器的当前值，请使用 {{filters.…summary}}；controls 命名空间用于字段切换器、选择器和 Top-N 控件，用于筛选器时会渲染为空值。在 Markdown 可视化图块中，filters 的键为 view.field；在仪表板文本图块中，键为控件 id。令牌和场景请参阅：references/mustache.md。
• query.filters 需要使用对象形式——相对日期简写（"last 6 months"）会抛出 500 错误；请发送 {type:"date", kind:"TIME_FOR_INTERVAL_DURATION", ui_type:"PAST", left_side, right_side}。请参阅 references/documents-v2.md。
• 没有实际 visConfig 的图块会显示为“缺少项目”。 新图块的初始设置为 visConfig.visType: null 和 automaticVis: false，因此不会绘制任何内容。如果用户指定了特定图表或格式，请为每个图块设置明确的 visConfig（例如 references/visConfig.md 中的表格配方）；否则设置 automaticVis: true。创建请求会将每个图块放入 order，因此问题始终要在图块的 visConfig 中修复。
• **“没有可用的图表”**表示内部配置、visType 或 prefersChart 有误。对于用户要求的图表，请在 visConfig.visConfig.config 下发送 references/visConfig.md 中的完整配置；只有在有意使用备用方案时才设置 chartType: "table"。
• 每个查询都必须至少包含一个度量值——只有维度的查询会生成空白或无意义的图块（例如只有月份而没有数据）。
• 存在 pivots 数组时，布尔筛选器可能会被静默丢弃（已报告的 Omni bug）。如果布尔筛选器未生效，请移除透视并再次测试。
• 使用 identifier，不要使用 id——从 v2-create / 补丁响应或 omni documents list 记录中获取文档的 identifier。
• 不要使用 omni unstable documents-import 更新现有仪表板——导入会创建新文档，且可能丢弃新添加的图块。请在现有文档上使用草稿流程。
• 不要保存无效的查询级筛选器——如果 omni query run 对图块查询筛选器返回服务端解析错误，请先验证一次未筛选的基础查询。不要将该无效筛选器保存到图块中。如果仪表板级控件可以满足需求，请使用该方案并通过读回进行验证；否则保持仪表板不变并报告阻碍。
• 限制失败更新的重试次数——如果补丁返回验证错误，最多只进行一次修正后重试。不要反复尝试不同的筛选器语法或循环调用端点。由于编辑是在草稿上进行的，恢复很简单：丢弃草稿（omni documents discard-draft <identifier>），并报告保留了哪些内容——已发布的文档从未被修改。

前提条件

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Verify the CLI has the v2 documents commands — if not, ask the user to upgrade it
omni documents v2-get --help >/dev/null 2>&1 || echo "ERROR: CLI is too old for the v2 documents API — upgrade it."

# Show available profiles and select the appropriate one
omni config show
# If multiple profiles exist, ask the user which to use, then switch:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

身份验证：如果 whoami 或任何调用返回 401，请让用户运行 ! omni config login <profile>。有关配置 Profile、何时可以自行运行登录，以及 --schema 的信息，请参阅 omni-api-conventions 规则。

发现命令

omni documents --help              # Document operations (v2-* + lifecycle)
omni dashboards --help             # Dashboard downloads
omni models yaml-create --help     # Writing model YAML
omni documents v2-create --schema  # Body schema + example (add --depth 1 for an overview, --field PATH to drill in)

提示：使用 -o json 强制输出结构化内容，以便进行程序化解析；使用 -o human 输出易读的表格。默认值为 auto（在 TTY 中输出人类可读内容，管道传输时输出 JSON）。--compact 会移除缩进，便于通过管道传输。

命令

始终使用 documents v2-* 命令构建和编辑文档。 无论何种情况，都不要回退到 v1 的 documents create/get 路径来构建、读取或更改文档；v2 草稿流程已涵盖所有这些操作。

操作	命令
创建文档	documents v2-create
读取文档 / 草稿状态	documents v2-get / v2-get-draft
编辑文档（图块、控件、布局、设置、重命名）	documents v2-patch-draft（+ v2-patch-draft-by-identifier）
获取工作簿模型 ID	documents v2-get（已发布文档）或 v2-get-draft（对应草稿）中的 workbookModelId；也可通过 documents list-drafts 获取
重命名文档标识符（slug）	documents v2-update-identifier <identifier>
将图块绑定到查询模型或解除绑定	在草稿上使用 documents v2-bind-query-model / v2-unbind-query-model（CLI ≥ 1.1.2）；请参阅 references/documents-v2.md
发布草稿	documents v2-publish-draft
读取或编辑 应用（HTML，而非仪表板）	documents get-app / put-app / patch-app / remove-app（以及草稿和自动草稿形式）——alpha，CLI ≥ 1.4.0；请参阅 references/documents-v2.md

少数文档管理操作没有 v2 形式——它们不是 v2 构建流程的替代方案，只是完成相应工作的唯一命令：documents list / list-drafts（查找文档和草稿）、documents discard-draft（放弃草稿）、documents delete / move / duplicate（生命周期管理）、documents get-queries（提取图块中可运行的查询以进行验证）、dashboards download / download-status、documents upgrade-layout（将经典布局仪表板升级为高级布局；此操作会发布，因此请先确认），以及 models yaml-create / validate（模型写入）。

仪表板架构

Omni 仪表板由文档构成。文档的 v2 状态是一个包含四个切片的信封：queryPresentations、controls、containers 和 settings（标注见 references/documents-v2.md）：

• 磁贴位于 queryPresentations.data 中，以记录键（"1"、"2"……）为键；order 表示标签页顺序。磁贴键必须是数字字符串（"1"、"42"）——像 "revenue_kpi" 或 "probe" 这样的描述性键会被拒绝，并返回 400 … Invalid key in record。请在构建脚本中跟踪磁贴与含义的映射，而不是将其写在键中。
• 筛选器和交互式控件共用一个映射：controls（见 references/controls.md）。与磁贴键不同，此处的控件 ID 可以是任意字符串（"date_filter"、"granularity"）——不要将这种自由度用于磁贴键，反之亦然。
• 布局是 containers 树——只有容器引用了磁贴，该磁贴才会渲染（见 references/containers.md）。
• 每个文档还包含一个工作簿模型，用于管理各仪表板的模型变更（见 references/workbook-model.md）。

通过草稿编辑文档：v2-patch-draft 会创建草稿并应用补丁；在执行 v2-publish-draft 之前，已发布的文档不会受到影响。v2-get 返回已发布状态。v2-get-draft 返回草稿状态；使用草稿自身的 ID 调用 v2-get 也会返回该状态（响应中的 draftOf 表示对应的文档）。草稿还可以绑定到模型分支（见 references/branch-bound-drafts.md）。

基于主题构建查询

尽可能让每个磁贴的查询都基于主题构建：将查询的 table 设为主题的基础视图，并传入 join_paths_from_topic_name: <topic>，同时在呈现配置中设置 topicName: <topic>（呈现配置级别的 topicName 是磁贴专属的——独立查询没有对应配置）。随后，联接视图字段会通过基础视图对应的主题联接映射解析。完整结构——联接映射如何关联到联接视图字段、示例，以及如何使用 omni models get-topic 验证（base_view_name/join_via_map）——请参见 omni-query 中的 Build queries on a topic。

未基于主题构建的磁贴仍可运行（裸基础视图查询或使用全局 relationships 文件的原始 SQL userEditedSQL 磁贴），但受限查询者和查看者无法看到它。上文的两个已知问题规则说明了何时应提问以及何时应建议使用 Access Boost。要编写原始 SQL 磁贴并完成端到端的权限提升，请参见 references/queryPresentations.md → Raw-SQL tiles；有关权限提升命令和组织级前提条件，请参见 omni-admin → Document Permissions（使用带有 accessBoost 的 add-permits，或使用 update-permission-settings）。

编写限制（不同于上述可见性限制）：如果你是受限查询者，就完全无法编写非主题查询/原始 SQL 磁贴——QUERY_TOPICS 只能查询主题——因此你构建的每个磁贴都必须基于主题。非主题查询 + Access Boost 的路径仅适用于由 QUERY_FULL_MODEL 作者为受限受众构建磁贴的情况。（使用 whoami 检查；参见 omni-admin → Model Roles & Caller Access。）

文档管理

使用 documents v2-create 创建文档，可以仅指定名称，也可以通过一个 --body 一次性传入完整信封（磁贴、控件、设置）。通过草稿补丁重命名（使用 --name，然后发布）。使用 documents delete / move / duplicate 删除、移动和复制文档；只有已发布的文档才能复制。示例、创建请求体的关键要点以及端到端构建工作流，见 references/document-lifecycle.md。

更新现有仪表板

编辑通过草稿流程进行；在发布之前，不会改动已发布的仪表板：

1. 使用 omni documents v2-get <identifier> > doc.json 读取当前状态；如果已有草稿，则使用 v2-get-draft。如果没有文档标识符，请先通过 omni-content-explorer 或 omni documents list 查找文档。
2. 编写补丁，只发送有改动的内容。补丁按键合并；order 数组和 containers 则会被完整替换。要删除磁贴，请将其键设为 null，并从 order 中移除。
3. 打开草稿：使用 omni documents v2-patch-draft <identifier> --body @patch.json，并在请求体中加入 summary，同时保留返回的 draftIdentifier。--body @file 无需 shell 引号，并会在发送前检查 JSON。
4. 验证草稿：使用 v2-get-draft <identifier> <draftIdentifier> 读回草稿，并运行受影响的查询（请参阅验证循环）。使用 v2-patch-draft-by-identifier <identifier> <draftIdentifier> 迭代更新。
5. 使用 omni documents v2-publish-draft <identifier> 发布，然后分享链接（请参阅URL 模式）。要放弃草稿，请使用 omni documents discard-draft <identifier>；已发布的文档不会受到影响。

错误映射、合并语义详情和操作示例见 references/updating-dashboards.md。

更新仪表板的模型

仪表板专属字段应放在文档的工作簿模型中，该模型扩展共享模型。首先根据你的访问权限（omni whoami whoami --model-id <sharedModelId>）确定新字段应放在哪里：表计算、共享模型的分支，或此工作簿模型。切勿写入架构模型。仅存在于尚未合并的分支中的字段需要使用绑定分支的草稿。使用 "mode": "extension" 编写工作簿模型 YAML；默认的组合模式会将你省略的所有字段标记为已忽略。决策步骤、yaml-create 操作示例、基于新字段构建磁贴的顺序，以及验证方法，详见：references/workbook-model.md。

仪表板筛选器和控件

筛选器和交互式控件共用一个封装切片：controls: {data, order}。每个条目都是 {config, map}——config 保存筛选器或控件定义，map 可选，用于按磁贴限定其范围。创建时即可包含这些内容，也可以稍后通过补丁添加（控件像磁贴一样按键合并）；请求体创建示例见 references/controls.md。

• controls.data 中的键是任意 ID，且必须与 order 中的条目一致。
• 筛选器类型（日期／字符串／数字／布尔值，均为必需）和交互式控件（字段／时间范围切换器）及其示例，详见 references/controls.md。
• map 可按磁贴限定控件范围：{"<tileKey>": false} 表示排除某个磁贴；{"<tileKey>": "<fieldName>"} 表示重新映射字段——筛选器和交互式切换器均适用。
• 每个筛选器都必须包含 fieldName，且该值必须是完全限定的字段名（日期筛选器无需添加时间范围括号），否则筛选器不会绑定到任何列。
• 要复用现有仪表板中的筛选器，请使用 omni documents v2-get 读回；其 controls 切片可以原样放入补丁。

应建模，还是用控件？ 如果主题涉及的每个工作簿和仪表板都应包含某个筛选器，某个控件会驱动多列或度量阈值，或者某个控件会切换字段使用的列或度量，则应将该筛选器建模为仅用于筛选的字段。其他情况使用仪表板控件。完整判断标准（包括 Restricted Querier 可以执行的操作）见：references/controls.md。

文档设置

settings 是一个浅合并对象：crossfilterEnabled（点击一个图块中的值以筛选其他图块）、facetFilters、refreshInterval（秒；null 表示禁用）、runQueriesOn（"current-page" / "all-pages" / null）和 customText（覆盖 {queryError, queryNoResults}）。只修改需要变更的键。

布局（容器）

containers 树决定图块和控件的渲染位置：先是保留的 "filter-bar" 堆栈，然后每页各有一个 page 容器，每个容器包含一个由图块堆栈组成的 24 列 grid，并带有 gridPosition {x,y,w,h}。何时发送，以及它会替换整个布局的说明，见上文的“已知问题”。多页仪表板、页面切换器、分组带、图块内控件和尺寸规则：references/containers.md。

URL 模式

创建或找到内容后，务必向用户提供直接链接：

Dashboard: {OMNI_BASE_URL}/dashboards/{identifier}
Workbook:  {OMNI_BASE_URL}/w/{identifier}
Draft:     {OMNI_BASE_URL}/dashboards/{draftIdentifier}

identifier 来自 v2-create/patch 响应或 omni documents list；draftIdentifier 来自 v2-patch-draft 响应或 omni documents list-drafts。 将 {OMNI_BASE_URL} 替换为活动配置文件或环境中的实际基础 URL，并去掉末尾的斜杠。除非凭据不可用且你明确说明该 URL 是模板，否则不要返回字面占位符字符串。

验证循环

每次构建或更新都必须在发布之前进行验证：图块损坏、字段引用错误和规格配置不当可能会显示“Chart unavailable”或“No data”，且没有 API 错误。

1. 使用 omni models validate <modelId> 验证模型。
2. 使用 omni query run 先测试每个查询，包括仪表板将使用的筛选器。
3. 检查每个可视化规格：prefersChart: true、规格位于 visConfig.visConfig.config 下，并且 chartType 与其 visType 和 configType 匹配。
4. 发布前验证草稿：使用 v2-get-draft 读取草稿，运行每个图块的查询（omni documents get-queries + omni query run），并报告每个图块的状态和行数。

每个响应中需要检查的内容、完整的可视化规格表、检查清单，以及浏览器可访问时可选的浏览器检查（页面永远不会进入空闲状态，因此有自己的等待规则）：references/validation-and-testing.md。

仪表板下载

下载是异步的：使用 omni dashboards download 启动下载，轮询 download-status 直到任务进入终止状态，然后使用 download-file 获取文件。单图块和数据格式、多页仪表板的单页限制，以及“Job failed to render”的含义：references/downloads.md。

文档参考

• Documents API · 仪表板下载 · Query API · Schedules API · 可视化类型

相关技能

• omni-model-explorer — 了解可用字段
• omni-model-builder — 创建共享模型字段
• omni-query — 添加到仪表板前测试查询
• omni-content-explorer — 查找现有仪表板以供参考
• omni-embed — 将已构建的仪表板嵌入外部应用
• omni-admin — 计划交付、收件人和仅限电子邮件的用户