最佳实践：业务自助取数
OpenInsight 可以让 Agent 优先走语义层数据集回答业务问题：先对齐口径，再查数，最后在回答末尾用脚注标明来源、可信度与数据新鲜度。
对话：查环比变化
问题： 帮我查一下某店铺 6 月商品销量比 5 月的环比变化。
Agent 思路：
- 先读当前 project 的
datasets/*.md，匹配业务问题对应的数据集、粒度与指标字段。 - 按数据集约定取数：同一月份仅取最新落盘数据，避免重复落盘干扰。
- 给出结果表，并说明口径（汇总字段、过滤条件、时间窗口）。
- 若两期覆盖范围不一致，补充可比口径结果，确认趋势是否一致。
- 回答末尾附脚注：来源、可信度、审查轮次、数据新鲜度、归属。
使用原理
业务自助取数依赖两层约定一起工作：
- 数据分析 Skill（
openinsight-data-analysis-skill）：规定 Agent 遇到业务取数问题时必须怎么走。 - 权威数据集（
datasets/*.md）：由分析师沉淀的语义口径，是 Agent 取数的强制默认路径。
只有语义层覆盖不了时，才允许回退到表元信息、看板或原始 SQL 探索，并在脚注中下调可信度。
数据分析 Skill
初始化项目后，模板会安装 openinsight-data-analysis-skill。当用户用自然语言查销量、环比、对比等业务数据时，Agent 应调用该 Skill，而不是直接拼 SQL。
Skill 要求的工作流：
- 定位项目路径：运行
openinsight current，读取knowledge.domain、knowledge.glossary、resources.datasets等路径。 - 加载业务知识：读取业务域与术语表，对齐用户说法和指标含义。
- 加载权威数据集：读取
datasets/下除example.md外的全部*.md。 - 发现与细查：按问题关键词匹配数据集、字段、指标、来源表和使用限制；命中后读完整定义。
- 编译并运行：按数据集口径构造查询，通过
openinsight cluster query执行。 - 回退：仅当数据集明确不覆盖需求、或无法从定义可靠构造 SQL 时，才读表 / 看板元信息或做原始探索。
不要因为“需要自定义日期过滤”“需要 JOIN”“用户提到了看板”就过早放弃语义层：先检查数据集是否已定义时间字段、来源关系与口径，再用看板验证呈现方式。
查询前还需对齐日期窗口与数据新鲜度：优先用数据集约定；没有约定时先查 max(date) 或等价分区，不要默认“昨天”。
权威数据集
权威数据集是本地维护的语义契约，存放于当前 project 的 datasets/<id>.md。文件名即数据集 id，正文用 Markdown 描述业务上下文、维度、关联表、注意事项与常见查询模式。
它解决的是“Agent 该按什么口径取数”：
- 业务问题优先映射到数据集，而不是直接扫物理表。
- 字段、粒度、过滤条件、适用 / 禁用场景以数据集为准。
- 物理表只有被数据集引用时，才视为语义层来源表。
分析师维护数据集后，Agent 就能在取数时自动对齐口径；数据集未覆盖时再降级，并在回答脚注明示来源降级。
数据集示例
下面是一份脱敏后的市场行情权威数据集示例（已隐藏具体平台与真实表前缀），结构可直接复用到自己的 datasets/：
# [市场行情域] 平台行情数据集
## 快速参考
### 业务上下文 — 本数据集存放电商平台市场大盘数据
## 维度
- **业务日期**：统计数据的日期，格式为 YYYY-MM-DD，如果是月份则 DD 为 01，例如 2026-06-01
- **dt**：数据落盘日期。注意一份数据可能会落盘多次，取最近一次落盘的日期
- **类目ID**：代表平台类目树中的叶子类目 ID
## 关联数据表
### market_brand_pool_monthly_du
- **粒度**：每行代表某个品牌 * 某个月的市场行情数据统计
### market_category_pool_monthly_du
- **粒度**：每行代表某个叶子类目 * 某个月的市场行情数据统计
### market_shop_pool_monthly_du
- **粒度**：每行代表某个店铺 * 某个月的市场行情数据统计
### market_product_pool_monthly_du
- **粒度**：每行代表某个商品 * 某个月的市场行情数据统计
### market_brand_pool_du
- **粒度**：每行代表某个品牌 * 某个月的市场行情数据统计
### market_category_pool_du
- **粒度**：每行代表某个叶子类目 * 某个月的市场行情数据统计
### market_shop_pool_du
- **粒度**：每行代表某个店铺 * 某个月的市场行情数据统计
### market_product_pool_du
- **粒度**：每行代表某个商品 * 某个月的市场行情数据统计
### market_metadata_du
- **粒度**：每行代表一个叶子类目
- **使用场景**：查询平台类目列表
- **注意**：忽略其中的 `validity_start_date` `validity_end_date` 字段，数据未启用
- **注意**：每天都是一份完整数据，只取最新日期的即可
## 注意事项
- 暂无
## 最佳实践 / 常见查询模式
- **类目ID** 在各表中字段名均为 `cate_id`，与 `market_metadata_du` 表中的 `leaf_category_id` 进行关联
## 交叉引用
- 暂无
维护建议：
- 把“一行代表什么”、落盘去重规则、JOIN 键写清楚，Agent 才不会猜。
- 同一业务日期多次落盘时，在数据集里约定“只取最新
dt”。 - 不适用场景也要写出来，避免 Agent 误用后仍标高可信度。
回答脚注
每个取数回答都应带脚注，方便业务方判断“能不能直接用”。常见字段：
| 脚注字段 | 含义 |
|---|---|
| 来源 | 结果依据哪类知识：语义层数据集、语义层来源表、非语义层表元信息、看板/图表元信息、原始探索。 |
| 可信度 | 高 / 中 / 低，由来源类型与口径确定性共同决定。 |
| 已审查 | 是否完成对抗性 SQL 审查，以及审查轮次。 |
| 数据新鲜度 | 所用数据的最新业务日期或最新落盘时间；未知时明确写未知。 |
| 归属 | 数据集或表的负责人 / 团队；未知时写 unknown。 |
来源与可信度
| 来源 | 典型场景 | 可信度建议 |
|---|---|---|
| 语义层数据集 | 严格按 datasets/*.md 中的字段、指标、过滤条件和使用限制取数。 | 高 |
| 语义层来源表 | SQL 用到的物理表出现在相关数据集的来源表 / 关联表中，但仍需自行拼口径。 | 中～高（口径明确可为高） |
| 看板 / 图表元信息 | 复现或解释看板数字，口径来自仪表盘 / 图表定义。 | 中～高（与数据集冲突时先对齐） |
| 非语义层表元信息 | 表只在本地表元信息中存在，未被数据集引用。 | 中及以下；须注明“未在语义层定义” |
| 原始探索 | 靠表名、字段名或样本临时摸索，缺少语义层 / 看板 / 业务文档支撑。 | 低～中 |
可信度下调场景
| 场景 | 处理方式 | 可信度 |
|---|---|---|
| 两期覆盖范围不一致（如类目数不同） | 同时给出全量与可比子集结果，说明差异。 | 口径说明清楚时可保持 高 |
| 数据集未覆盖该问题 | 回退到表元信息或看板，并标明来源降级。 | 通常 中 |
| 文档过期、枚举未知、字段需猜测 | 先用小样本 / 最大分区验证，再回答。 | 中 或 低 |
| 使用了未被数据集引用的物理表 | 明确写出未定义；除非用户确认口径，否则不得标高。 | 不得高于 中 |
| 业务上下文缺失（术语 / 域知识为空） | 可继续取数，但在回答中标注上下文缺失。 | 视口径确定性降为 中 |
| 数据新鲜度未知 | 脚注写“未知”，不要默认“昨天”。 | 视情况降为 中 |
脚注示例：
来源：语义层数据集（店铺月度数据集） · 可信度：高 · 已审查：SQL 审查 ✓，第 2 轮 · 数据新鲜度：该店 6 月数据最新落盘于 2026-07-11 · 归属：数据负责人
适用场景
- 业务方用自然语言查销量、环比、对比等常规指标。
- 需要把结果口径、新鲜度、可信度一并交代清楚。
- 语义层能覆盖时优先走数据集；覆盖不了时再降级到表 / 看板 / 探索，并下调可信度。