smart-data-analysis

# Smart Data Analysis（总编排）

本 skill 是 **数据分析员工角色的总入口**：在本体数据技能栈中，**所有数据相关问题必须先经过本 skill**，完成 **KN 与上下文对齐、意图路由** 后，再委派至 **找表** 或 **问数**（或其它数据子 skill），**禁止**在未做编排判断时直接跳到 `smart-search-tables`、`smart-ask-data` 或零散工具调用。

**Never** 由本 skill 直接执行 `ontology` CLI；所有 CLI 调用（包括为选 KN 取候选元数据的 `bkn list/get`，与问数分支的 `bkn object-type get / dataview query --sql` 等）均委托 [ontology-core](../ontology-core/SKILL.md) 执行。

调用链：

```
smart-data-analysis（顶层意图 + LLM 决策：选 KN / 生成 SQL）
  ├─ ontology-core（直接委托：bkn list/get 等用于自身决策）
  └─ smart-search-tables 或 smart-ask-data（子流程）
       └─ ontology-core（子流程的 CLI 委托）
```


## 总入口原则（必须遵守）

1. **先编排，后执行**：识别用户问题是否属于「数据域」（资产/表/视图/指标/SQL/图表/职责/元数据/多 KN 等）；若是，**先走本节下方「编排总流程」与「路由识别」**，再打开对应子 skill 或工具链。
2. **单一前门**：同一轮对话中新增的数据子任务，仍应 **回到本 skill 的编排逻辑** 决定是延续当前分支还是切换找表/问数。
3. **按最终意图路由**：先判断用户最终想要的是“定位数据资产（表/视图）”还是“拿到数据结果（指标/明细/统计/图表）”。前者走找表；后者走问数，必要时在问数分支内先找表再生成 SQL。
4. **交接清晰**：转入 [smart-search-tables](../smart-search-tables/SKILL.md) 或 [smart-ask-data](../smart-ask-data/SKILL.md) 时，在内部上下文中保留已解析的 **`kn_id_*`、时间口径**，避免子 skill 重复猜 KN。
5. **非数据问题**：与数据无关时 **不必** 强行套用本 skill；若用户一句话里混有数据与非数据，**数据部分**仍按上述原则经本 skill 编排（可分段回答）。
6. **禁止交叉兜底**：本轮路由为 **问数** 时，若问数走不通，**禁止**改走 **找表** 分支代替交付；路由为 **找表** 时，若找表走不通，**禁止**改走 **问数** 分支代替交付。两种情况下均应 **直接输出走不通的原因**（缺 KN、无命中、平台错误等）及用户侧可采取的修复条件。细则见下方「分支走不通时的处理（禁止交叉兜底）」。

## 知识网络声明（KN id 单一来源）

KN id 在下表中直接声明，**由本 skill 路由时透传到下游**（smart-ask-data / smart-search-tables）。下游 skill **不** 自行选 KN、**不** 调 `bkn list/get` 枚举或决策。

| 分支 | 用途 | KN ID |
|------|------|-------|
| 找表 | 表/视图实例检索（必填） | `<填入KN id>` |
| 找表 | 部门职责检索（可选） | `<填入KN id>` |
| 问数 | SQL 取数（必填） | `<填入KN id>` |

约束：

- 维护者一次性通过 ontology-core 调 `bkn list` 取得平台可用 KN id 后，**直接编辑本表**填入；运行时不再做 KN 列举或选择。
- 若占位仍为 `<填入...>`：进入对应分支时直接告知用户"未在 smart-data-analysis/SKILL.md 中配置对应 KN"，**不得**用其它 KN 凑数。
- 用户明确说「用 XX 知识网络问数 / 找表」→ 仅当该 id 等于上表已声明值时采用；否则提示用户先把该 KN 添加到本表再用。

## 与其它技能的分工

| 能力 | 本 skill（编排） | 专用 skill（执行细节） |
|------|------------------|------------------------|
| 路由、kn 切换、上下文注入 | ✅ 主责 | 配合 |
| KN id 声明 + 透传到下游 | ✅ 主责（见上方「知识网络声明」表） | 接收注入，不自行选 KN |
| 找表 / 定位 / 职责 / 澄清 | 定义路由与交接 | [smart-search-tables/SKILL.md](../smart-search-tables/SKILL.md) |
| 问数：SQL **生成**（基于 schema 摘要） | ✅ 主责（LLM） | 输出 SELECT/WITH SQL 给 smart-ask-data 步骤 4 |
| 问数：步骤顺序、口径约束、SQL **执行** | 定义路由与交接 | [smart-ask-data/SKILL.md](../smart-ask-data/SKILL.md) |
| ontology native CLI 执行（`bkn / ds / dataview / vega / call`） | **不直接执行** | [ontology-core/SKILL.md](../ontology-core/SKILL.md) |

## 子技能依赖

| 子技能 | 角色 | 返回 | 约束 |
|--------|------|------|------|
| [ontology-core](../ontology-core/SKILL.md) | smart-data-analysis 的 CLI 委托 | 命令执行结果与回执 | Never 跳过 smart-data-analysis 直接接管流程 |
| [smart-search-tables](../smart-search-tables/SKILL.md) | 找表分支执行 | 候选表/视图清单、归属、职责要点 | 走找表分支时由 smart-data-analysis 路由进入；本 skill 需向其透传 `accountId / kn_id / duty_kn_id / <ot-id> / search` 等入参；不直接执行 ontology CLI |
| [smart-ask-data](../smart-ask-data/SKILL.md) | 问数分支执行 | SQL 执行结果 + 口径 | 走问数分支时由 smart-data-analysis 路由进入；本 skill 需向其透传 `accountId / kn_id / 生成的 SQL` 三件套 |

## 职能矩阵（谁做什么）

| 角色/技能 | 负责（Do） | 不负责（Don't） | 典型输出 |
|-----------|------------|-----------------|----------|
| `smart-data-analysis`（总编排） | 识别主意图；**从「知识网络声明」表读取 KN id 并透传给下游**；组织 `date` / `accountId` 等上下文；问数分支基于 schema 摘要生成 SELECT SQL | 不直接执行 ontology CLI；不在运行时用 `bkn list` 决策 KN；不直接做对象检索细节；不替代子 skill 结果 | 路由决策、KN 透传、生成 SQL、交接约束 |
| `smart-search-tables`（找表执行） | 接收 smart-data-analysis 透传的 `kn_id` / `duty_kn_id` / `<ot-id>` / `accountId`；按 2 步顺序触发 `bkn object-type query`（必要时 `bkn object-type list`）等 native 命令的委托；产出候选表/视图清单 + 职责要点 | 不承担跨流程总路由；不在 skill 内自行选 KN；不直接执行 ontology CLI | 候选表清单、归属、职责说明 |
| `smart-ask-data`（问数执行） | 接收 smart-data-analysis 透传的 `kn_id` 与 SQL；按 5 步顺序触发 `bkn object-type get` / `dataview query --sql` 等 native 命令的委托；产出取数结果与口径展示 | 不承担跨流程总路由；不在 skill 内自行选 KN 或生成 SQL；不直接执行 ontology CLI | 数值结果、口径说明、SQL 与依据 |
| `ontology-core`（CLI 委托执行） | 实际承载所有 `ontology` 命令的执行（`bkn / ds / dataview / vega / call`）；统一处理 `--user-id / --base-url / -bd` 等横向约束 | 不替代业务编排判断；不直接定义问数口径 | 命令执行结果与回执 |

若仅有顶层编排而无子 skill 正文：**仍须按下方路由规则执行**；找表/问数细节分别以 [smart-search-tables](../smart-search-tables/SKILL.md)、[smart-ask-data](../smart-ask-data/SKILL.md) 为准；CLI 与 BKN 以 `ontology-core` 的 `references/*.md` 为准（尤其 `bkn.md`）。

## 编排总流程（必须按序）

复制并勾选：

```text
编排进度：
- [ ] 1. 解析任务中的 KN / 业务域（见「知识网络分域」）
- [ ] 2. 注入公共上下文（见「上下文注入」）
- [ ] 3. 意图路由：找表 / 问数（见「路由识别」）
- [ ] 4. 进入对应分支清单并完成；歧义时先澄清
- [ ] 5. 输出结构：结论 + 依据（表/视图/KN）+ 下一步可选动作
```

## KN 切换规则

实际 KN id 见上方「[知识网络声明](#知识网络声明kn-id-单一来源)」表；切换时按以下规则透传给下游：

- 路由到 **找表分支** → 注入"找表"行的 KN id 为 `kn_id`；若"职责"行非空则同时注入 `duty_kn_id`。
- 路由到 **问数分支** → 注入"问数"行的 KN id 为 `kn_id`。
- 用户明确说「用 XX 知识网络问数 / 找表」→ 仅当 XX 等于声明表中某行的值时采用；否则要求用户先把它加进声明表。
- 同时跨找表/问数（先找表再算数）→ 两步分别注入各自分支的 KN id，不混用。

## 上下文注入

在调用检索或问数工具前，尽量在推理上下文中 **显式整理**（不必向用户冗长展示）：

| 键 | 含义 | 来源 / 用途 |
|----|------|--------------|
| `accountId` | 当前会话用户的账户 id | 由会话框架/调用方提供；委托 ontology-core 时注入 `--user-id <accountId>`（必传，缺失时向用户索要，不得编造） |
| `date` | 用户问题中的时间范围、默认「当前日期」与对比周期（同比/环比） | 解析自用户问题 |
| 路由分支 + 注入下游的 `kn_id`（找表分支额外含 `duty_kn_id`） | 当前要进入的分支决定注入哪行声明值 | 从「知识网络声明」表读取；占位为 `<填入...>` 时告知用户并停止 |

将上述一并作为后续工具调用的隐含约束，减少跨 KN 误查。网关（`ONTOLOGY_BASE_URL`）由 [ontology-core](../ontology-core/SKILL.md) 侧承担；本部署 ontology CLI **无须 token**，本 skill 与子 skill 均不持有任何凭证。


## 路由识别

按优先级匹配用户**最终意图**（一句可多标签，取最终要交付给用户的结果）：

### 走「找表（找数）」分支（最终目标是定位资产）

触发词或场景示例：表在哪、哪个视图、字段在哪个模型、主题域/部门职责、资产目录、「有没有叫…的表」、**仅**定位不做指标计算。

找表分支通过 ontology-core 委托 `bkn object-type query`（必要时 ``bkn object-type list`）：第 1 步在元数据型 KN 下做实例检索拿候选表/视图，第 2 步在职责型 KN 下做实例检索拿相关部门职责。详见 [smart-search-tables/SKILL.md](../smart-search-tables/SKILL.md)。

**分支清单**

```text
找表进度：
- [ ] 确认 `accountId`（缺失则向用户索取，不得编造）
- [ ] 从「知识网络声明」表读取找表 KN id 作为 `kn_id`；占位仍为 `<填入...>` → 告知用户并停止
- [ ] 同步读取职责 KN id 作为 `duty_kn_id`（可空；空则后续跳过职责检索）
- [ ] 选定 `<ot-id>`：每个 KN 内用于实例检索的对象类 id；不确定时先 `bkn object-type list <