Object Model

Open Insight 会把数据平台中的元信息保存成本地文件。这样做的目标是让人和 Agent 都能方便地阅读、对比、编辑、校验和同步这些信息。

文件规则

外部系统对象使用 YAML。
本地数据集、业务描述、领域上下文、术语解释和 Agent 工作说明使用 Markdown。
YAML 文件最小身份字段为 apiVersion、kind、id、title。
对象 id 必须稳定、适合路径使用，并且在一个数据分析库内具备全局含义。
远端系统 id 属于连接器细节，应通过 remoteId 独立保存，不应直接作为本地对象 id。
source 保存对象来源平台、系统对象和拉取时间。
平台特有字段放入 extensions.<platform>。

数据分析库目录

default/
  .open-insight.json
  source/
    systems/
    clusters/
    tables/
    users/
    tasks/
    taskruns/
  datasets/
  knowledge/
    domain.md
    glossary.md
  skills/

project 根目录 .open-insight.json 是当前 project 的本地连接配置，记录 provider、endpoint 和 token。各类数据对象位于同一个 <project>/ 下，不同 project 可以使用不同的连接上下文。

source/ 表示从源站同步过来的元数据：

source/systems/：外部系统配置。
source/clusters/：计算集群或查询引擎。
source/tables/：数仓表。
source/tasks/：调度任务定义（Task），上游血缘内联在 lineage 字段。
source/taskruns/：调度实例（由 taskrun list 同步，按日期/小时分桶存放 instances.json）。
预策用户（User）：由 user list 实时查询远端，不写入本地缓存。
基线定义（Baseline）：由 baseline list 实时查询远端，不写入本地缓存。
基线实例（BaselineInstance）：由 baseline-instance list --date 实时查询远端，不写入本地缓存。

datasets/ 表示本地维护的权威数据集。knowledge/ 表示业务知识。skills/ 表示 Agent 技能和工作流。

System

系统对象描述远端产品和连接引用，存放于 source/systems/。密钥不能写入 YAML。

apiVersion: open-insight/v1alpha1
kind: System
id: system.yuce
title: 预策数据平台
owner: data-team
tags:
  - yuce
systemType: other
vendor: yuce
connectionRef: .open-insight.json:providers.yuce

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `System`	`System`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`system.yuce`
title	展示名称	是	非空字符串	`预策数据平台`
description	对象说明	否	字符串	`企业数据平台连接`
owner	负责人	否（默认 `unknown`）	非空字符串	`data-team`
tags	标签	否（默认 `[]`）	字符串数组	`yuce`
remoteId	远端系统 id	否	字符串	`sys_001`
source.platform	来源平台	否	非空字符串	`yuce`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.yuce`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	—
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemType	系统类型	是	`warehouse` \| `orchestrator` \| `bi` \| `other`	`other`
vendor	厂商/产品	是	非空字符串	`yuce`
connectionRef	连接配置引用	否	字符串	`.open-insight.json:providers.yuce`

Cluster

集群对象描述背后的计算引擎或查询引擎，存放于 source/clusters/。表对象可以通过 clusterId 关联到具体集群。

apiVersion: open-insight/v1alpha1
kind: Cluster
id: cluster.yuce.default
title: 预策默认 StarRocks 集群
owner: data-team
tags:
  - yuce
  - starrocks
systemId: system.yuce
engineType: starrocks
extensions:
  yuce:
    nodeId: ""

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `Cluster`	`Cluster`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`cluster.yuce.default`
title	展示名称	是	非空字符串	`预策默认 StarRocks 集群`
description	对象说明	否	字符串	`默认查询集群`
owner	负责人	否（默认 `unknown`）	非空字符串	`data-team`
tags	标签	否（默认 `[]`）	字符串数组	`starrocks`
remoteId	远端系统 id	否	字符串	`cluster_001`
source.platform	来源平台	否	非空字符串	`yuce`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.yuce`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	`yuce.nodeId`
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.yuce`
engineType	引擎类型	是	非空字符串	`starrocks`

Table

表对象描述来自 Databricks、MySQL、StarRocks、预策或未来其他数仓产品的物理表或逻辑表，存放于 source/tables/。

apiVersion: open-insight/v1alpha1
kind: Table
id: table.starrocks.ads.sales_orders
title: ads.sales_orders
owner: data-team
tags:
  - sales
systemId: system.starrocks
clusterId: cluster.starrocks.default
database: analytics
schema: ads
table: sales_orders
tableType: table
columns:
  - name: order_id
    type: varchar
    nullable: false
    description: 稳定的订单 id。
    tags:
      - primary_key

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `Table`	`Table`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`table.starrocks.ads.sales_orders`
title	展示名称	是	非空字符串	`ads.sales_orders`
description	对象说明	否	字符串	`销售订单表`
owner	负责人	否（默认 `unknown`）	非空字符串	`data-team`
tags	标签	否（默认 `[]`）	字符串数组	`sales`
remoteId	远端系统 id	否	字符串	`tbl_001`
source.platform	来源平台	否	非空字符串	`yuce`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.starrocks`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	—
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.starrocks`
clusterId	所属集群	否	稳定、路径安全的 id	`cluster.starrocks.default`
database	数据库名	否	非空字符串	`analytics`
schema	Schema 名	否	非空字符串	`ads`
table	表名	是	非空字符串	`sales_orders`
tableType	表类型	否（默认 `unknown`）	`table` \| `view` \| `materialized_view` \| `external` \| `unknown`	`table`
columns	列定义	否（默认 `[]`）	见 `columns[]`	—

columns[]

字段	含义	必填	规范	案例
name	列名	是	非空字符串	`order_id`
type	列类型	是	非空字符串	`varchar`
nullable	是否可空	否	布尔	`false`
description	列说明	否	字符串	`稳定的订单 id。`
tags	列标签	否（默认 `[]`）	字符串数组	`primary_key`

Task

任务对象描述来自 Airflow、DolphinScheduler、预策调度或未来其他调度引擎的数据加工任务，存放于 source/tasks/。inputs 和 outputs 用于表达粗粒度血缘；完整上游血缘保存在 lineage 字段。

apiVersion: open-insight/v1alpha1
kind: Task
id: task.airflow.sales_orders_daily
title: sales_orders_daily
owner: data-platform
tags:
  - sales
systemId: system.airflow
schedule: 0 3 * * *
status: enabled
templateCode: tpl_sales_daily
templateName: 销售日同步模板
inputs:
  - table.mysql.ods.orders
outputs:
  - table.starrocks.ads.sales_orders
lineage:
  maxLevel: 1
  upstreamTaskCodes:
    - ods_orders_sync
  lineageNodes: []
  dependencies: []
  groups: []

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `Task`	`Task`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`task.airflow.sales_orders_daily`
title	展示名称	是	非空字符串	`sales_orders_daily`
description	对象说明	否	字符串	`每日销售订单同步`
owner	负责人	否（默认 `unknown`）	非空字符串	`data-platform`
tags	标签	否（默认 `[]`）	字符串数组	`sales`
remoteId	远端系统 id	否	字符串	`task_001`
source.platform	来源平台	否	非空字符串	`yuce`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.airflow`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	—
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.airflow`
schedule	调度表达式	否	字符串	`0 3 * * *`
status	任务状态	否	字符串	`enabled`
templateCode	模板编码	否	字符串	`tpl_sales_daily`
templateName	模板名称	否	字符串	`销售日同步模板`
inputs	输入对象	否（默认 `[]`）	稳定 id 数组	`table.mysql.ods.orders`
outputs	输出对象	否（默认 `[]`）	稳定 id 数组	`table.starrocks.ads.sales_orders`
lineage	上游血缘	否	见 `lineage`	—

lineage

字段	含义	必填	规范	案例
maxLevel	血缘层级上限	否	数字	`1`
upstreamTaskCodes	上游任务编码	否（默认 `[]`）	字符串数组	`ods_orders_sync`
lineageNodes	血缘节点	否	平台相关结构，由连接器填充	`[]`
dependencies	依赖关系	否	平台相关结构，由连接器填充	`[]`
groups	分组信息	否	平台相关结构，由连接器填充	`[]`

User

用户对象描述预策账号。CLI 通过 openinsight user list 直接查询远端，不写入本地缓存。

apiVersion: open-insight/v1alpha1
kind: User
id: user.yuce.u_001
title: 张三
owner: unknown
tags:
  - yuce
remoteId: u_001
systemId: system.yuce
username: zhangsan
name: zhangsan
displayName: 张三
email: zhangsan@example.com
department: 数据平台
status: ACTIVE

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `User`	`User`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`user.yuce.u_001`
title	展示名称	是	非空字符串	`张三`
owner	负责人	否（默认 `unknown`）	非空字符串	`unknown`
tags	标签	否（默认 `[]`）	字符串数组	`yuce`
remoteId	远端用户 id	否	字符串	`u_001`
source.platform	来源平台	否	非空字符串	`yuce`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.yuce`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	`yuce.userId`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.yuce`
username	登录名/用户名	是	非空字符串	`zhangsan`
name	预策原始 `name` 字段	否	字符串	`zhangsan`
displayName	展示名	否	字符串	`张三`
email	邮箱	否	字符串	`zhangsan@example.com`
department	部门	否	字符串	`数据平台`
status	状态	否	字符串	`ACTIVE`

Baseline

基线对象描述预策平台上的数据产出承诺。CLI 通过 openinsight baseline list 直接查询远端，不写入本地缓存。

apiVersion: open-insight/v1alpha1
kind: Baseline
id: baseline.yuce.core_daily
title: 核心日报
owner: data-team
tags:
  - yuce
remoteId: b1
systemId: system.yuce
status: ACTIVE
promiseTime: "08:00:00"
taskIds:
  - task.yuce.job1

字段说明

字段	含义	必填	规范	案例
kind	对象类型	是	固定 `Baseline`	`Baseline`
systemId	所属系统	是	稳定、路径安全的 id	`system.yuce`
status	基线状态	否	字符串	`ACTIVE`
promiseTime	承诺产出时间	否	字符串	`08:00:00`
taskIds	关联调度任务	否（默认 `[]`）	稳定 id 数组	`task.yuce.job1`

BaselineInstance

基线实例表示某业务日期下的一条基线运行记录。CLI 通过 openinsight baseline-instance list --date 直接查询远端，不写入本地缓存；列表展示会包含关联调度实例数量。

apiVersion: open-insight/v1alpha1
kind: BaselineInstance
id: baseline-instance.yuce.bi-1
title: 核心日报
owner: data-team
remoteId: bi-1
systemId: system.yuce
baselineId: baseline.yuce.b1
baselineDate: "2026-07-13"
status: SAFE
completed: false
promiseTime: "08:00:00"
actualTime: "07:58:00"
taskInstances:
  - instanceId: i-1
    taskCode: job1
    instanceStatus: SUCCESS

字段说明

字段	含义	必填	规范	案例
kind	对象类型	是	固定 `BaselineInstance`	`BaselineInstance`
systemId	所属系统	是	稳定、路径安全的 id	`system.yuce`
baselineId	关联基线	是	稳定、路径安全的 id	`baseline.yuce.b1`
baselineDate	业务日期	是	`YYYY-MM-DD`	`2026-07-13`
status	实例状态	否	`SAFE` / `WARNING` / `BROKEN_LINE` / `OTHER`	`SAFE`
completed	是否完成	否	布尔值	`false`
promiseTime	承诺产出时间	否	字符串	`08:00:00`
actualTime	实际产出时间	否	字符串	`07:58:00`
taskInstances	关联调度实例	否（默认 `[]`）	预策原始实例记录数组	见示例

Dashboard

仪表盘用于组织图表。预策仪表盘通过 dashboard list/get 实时查询，不写入本地缓存。

apiVersion: open-insight/v1alpha1
kind: Dashboard
id: dashboard.quickbi.sales_overview
title: 销售概览
owner: bi-team
tags:
  - sales
systemId: system.quickbi
remoteId: "dash_001"
charts:
  - chart.quickbi.sales.revenue_trend

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `Dashboard`	`Dashboard`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`dashboard.quickbi.sales_overview`
title	展示名称	是	非空字符串	`销售概览`
description	对象说明	否	字符串	`销售核心指标看板`
owner	负责人	否（默认 `unknown`）	非空字符串	`bi-team`
tags	标签	否（默认 `[]`）	字符串数组	`sales`
remoteId	远端仪表盘 id	否	字符串	`dash_001`
source.platform	来源平台	否	非空字符串	`quickbi`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.quickbi`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	—
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.quickbi`
charts	包含图表	否（默认 `[]`）	Chart id 数组	`chart.quickbi.sales.revenue_trend`

Chart

图表保存查询逻辑或语义映射定义。预策图表通过 chart list/get 实时查询，不写入本地缓存。

apiVersion: open-insight/v1alpha1
kind: Chart
id: chart.quickbi.sales.revenue_trend
title: 收入趋势
owner: bi-team
tags:
  - sales
systemId: system.quickbi
dashboardId: dashboard.quickbi.sales_overview
remoteId: "123456"
chartType: line
datasetId: dataset.sales.orders
query:
  sql: |
    select dt, sum(revenue) as revenue
    from ads.sales_orders
    group by dt
dimensions:
  - name: dt
    fieldId: dt
    dataType: date
    role: dimension
measures:
  - name: revenue
    fieldId: revenue
    aggregation: sum
    dataType: decimal
  - name: revenue_day_growth
    fieldId: revenue_day_growth
    aggregation: sum
    comparison:
      type: BASE_CONTRAST
      timeFieldId: dt
      timeFieldName: dt
      timeCalPeriod: DAY
      comparePeriod: DAY
      growthValueType: CONTRAST_GROWTH_VALUE
filters:
  - name: region
    fieldId: region
    operator: IN
    values:
      - 华东
      - 华南

字段说明

字段	含义	必填	规范	案例
apiVersion	API 版本	是	固定 `open-insight/v1alpha1`	`open-insight/v1alpha1`
kind	对象类型	是	固定 `Chart`	`Chart`
id	本地稳定标识	是	稳定、路径安全的 id；正则 `^[a-zA-Z0-9][a-zA-Z0-9._:-]*$`	`chart.quickbi.sales.revenue_trend`
title	展示名称	是	非空字符串	`收入趋势`
description	对象说明	否	字符串	`按日收入趋势图`
owner	负责人	否（默认 `unknown`）	非空字符串	`bi-team`
tags	标签	否（默认 `[]`）	字符串数组	`sales`
remoteId	远端图表 id	否	字符串	`123456`
source.platform	来源平台	否	非空字符串	`quickbi`
source.systemId	来源系统 id	否	稳定、路径安全的 id	`system.quickbi`
source.pulledAt	拉取时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
extensions	平台扩展字段	否（默认 `{}`）	`extensions.<platform>` 键值	—
createdAt	创建时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
updatedAt	更新时间	否	ISO 8601 日期时间	`2026-06-04T00:00:00.000Z`
systemId	所属系统	是	稳定、路径安全的 id	`system.quickbi`
dashboardId	所属仪表盘	否	稳定、路径安全的 id	`dashboard.quickbi.sales_overview`
chartType	图表类型	是	非空字符串	`line`
query	查询逻辑	否	对象；推荐 `query.sql` 保存 SQL。兼容历史字符串格式	`query.sql: select dt...`
datasetId	关联数据集	否	稳定、路径安全的 id	`dataset.sales.orders`
dimensions	维度字段	否（默认 `[]`）	对象数组；兼容历史字符串数组	`{ name: dt, fieldId: dt }`
measures	度量字段	否（默认 `[]`）	对象数组；兼容历史字符串数组；可包含 `comparison`、`proportion`、`format`	`{ name: revenue, aggregation: sum }`
measures[].comparison	同比/环比等对比配置	否	对象	`{ comparePeriod: DAY }`
measures[].proportion	占比配置	否	对象	`{ type: COLUMN_TOTAL }`
measures[].format	数值格式	否	对象	`{ round: 1 }`
filters	过滤条件	否（默认 `[]`）	对象数组	`{ name: region, operator: IN }`

Dataset

数据集是本地维护的语义契约，存放于 <project>/datasets/<dataset>.md。文件名即数据集 id，正文用 Markdown 描述业务口径与用法。它可以由 Agent 生成，由人 Review 和修改，并在后续作为 BI 推送流程的输入。

# [领域] 销售订单

## 快速参考
### 业务上下文 — 订单粒度的销售数据集
### 实体粒度 — [一行代表什么]
### 标准过滤条件 — [该领域每个查询都需要应用的过滤器]

## 维度
- [关键维度的编码方式，以及同一个概念在不同表里的不同命名]

## 关键数据表
### [表名]
- **粒度**：[...] · **范围/排除**：[...]
- **使用场景**：[什么时候用、什么时候不用、JOIN键、必须应用的过滤器]

## 注意事项
- [资深分析师会提醒你的那些容易踩坑的地方]

## 最佳实践 / 常见查询模式
- [默认选择、标准切分、查询形式本身就是难点的典型模式]

## 交叉引用
- [负责相邻问题的其他领域文档]

约定

项	说明
路径	`<project>/datasets/<id>.md`
id	取自文件名（不含 `.md`）
title	取自正文首行标题
业务上下文	取自 `### 业务上下文 — ...` 行

业务上下文

当内容以自然语言说明为主时，使用 Markdown 更合适。

推荐文件：

<project>/knowledge/domain.md：业务域背景、口径、分析场景。
<project>/knowledge/glossary.md：术语和指标解释。
<project>/datasets/<dataset>.md：数据集的长描述、使用建议、限制说明。
<project>/skills/<workflow>.md：面向 Agent 的工作流说明。

连接器边界

连接器负责在远端 API 对象和 Open Insight 本地 YAML 对象之间做转换。远端 API 的原始结构不应泄漏到本地对象模型中，除非是明确设计过的字段，例如 remoteId、systemId，或未来可能新增的 extensions 字段。

文件规则​

数据分析库目录​

System​

字段说明​

Cluster​

字段说明​

Table​

字段说明​

columns[]​

Task​

字段说明​

lineage​

User​

字段说明​

Baseline​

字段说明​

BaselineInstance​

字段说明​

Dashboard​

字段说明​

Chart​

字段说明​

Dataset​

约定​

业务上下文​

连接器边界​

文件规则

数据分析库目录

System

字段说明

Cluster

字段说明

Table

字段说明

columns[]

Task

字段说明

lineage

User

字段说明

Baseline

字段说明

BaselineInstance

字段说明

Dashboard

字段说明

Chart

字段说明

Dataset

约定

业务上下文

连接器边界