smart-data-analysis

---
name: smart-data-analysis
version: "1.0.0"
user-invocable: true
description: >-
  数据分析员工（Data Analyst Agent）的唯一总入口：凡与数据资产、取数、指标、表/视图、
  治理职责、知识网络等相关的问题，必须先经本 skill 做编排与路由，再进入找表或问数等子流程。
  当用户提出数据类问题、需要知识网络选择、或需要在找表与问数之间切换时使用。
metadata:
  openclaw:
    skillKey: smart-data-analysis
allowed-tools: Bash(kweaver *), Bash(npx kweaver *)
argument-hint: [数据任务描述，可包含 kn_id、时间范围、指标口径]
---

# Smart Data Analysis（总入口）

本 skill 是数据分析员工的唯一前门，负责**编排与路由**，不直接替代找表与问数子流程。

子技能参考：

- 问数：[`references/smart-ask-data.md`](references/smart-ask-data.md)
- 找数：[`references/smart-search-tables.md`](references/smart-search-tables.md)
- 权限申请：[`references/smart-apply-data-auth.md`](references/smart-apply-data-auth.md)
- 报告：[`references/smart-reporting.md`](references/smart-reporting.md)
- 图表数据：[`references/smart-json2plot.md`](references/smart-json2plot.md)
- 数据洞察：[`references/smart-data-insights.md`](references/smart-data-insights.md)（含归因子场景 [`references/attribution_analysis.md`](references/attribution_analysis.md)）
- Schema Search 脚本（`search_schema` HTTP）：[`references/search-schema-scripts.md`](references/search-schema-scripts.md)

**assets 索引**（报告三场景填空模版 + 解读规范入口）：见 [`assets/README.md`](assets/README.md)。

## 核心职责

1. 识别是否为数据类请求（数据资产、取数、指标、表/视图、治理职责、知识网络）。
2. 根据用户意图路由到：
   - `smart-search-tables`：找表/找视图/找字段/找职责
   - `smart-ask-data`：问数（第 10 步按查询类型分流执行；仅 `complex_query` 走 SQL，返回数据结果与口径）
   - `smart-apply-data-auth`：为指定数据视图申请 `data_query`/`view_detail` 权限
   - `smart-json2plot`：画图数据转换（仅消费上游结构化数据，不新增取数）
   - `smart-data-interpretation`（`data_interpretation`）：基于既有取数结果做趋势/异常/贡献/建议解读（不新增取数）
   - `smart-reporting`：将既有找数/问数/归因结果组装为可复核报告（不新增取数）
   - `smart-data-insights`：当用户要求「解读数据/趋势/异常/贡献/建议」或「多角度/多维度/分布」或「对比/同比/环比」或「归因/根因/为什么/MECE 证据链」等时使用；若用户同轮要求 **归因分析报告** 书面终态，须在洞察（含归因子场景）交付证据包后 **同轮** 衔接 `smart-reporting`（`attribution_analysis_report`）。
3. 对齐并传递上下文：`kn_id`、时间范围、过滤条件、业务口径。
4. 对超出问数/找表能力边界的请求给出明确说明，不伪造结果。

## 强约束

- 知识网络来源以 `SOUL.md` 为准。
- `smart-search-tables` 与 `smart-ask-data`、 `smart-data-insights`使用的 `kn_id` 必须来自 `SOUL.md` 已声明配置。
- 不允许在未完成路由判定前直接进入子技能执行。
- 问数命中后必须输出结果数据与口径说明；仅在 `complex_query` 场景产生 SQL（内部执行且不对用户展示）；不得扩写为主观分析结论。
- 先执行门禁机制（环境检测、约束检测、意图路由），再进入子技能。
- 进度输出必须遵循“进度显示规范（必须执行）”中的统一硬约束。
- 必须严格按照编排流程与连续步骤编号执行，不得跳步、并步、倒序或绕过门禁。
- 禁止编造或篡改流程：不得虚构已执行步骤、不得伪造步骤结果、不得擅自修改流程定义与执行记录。
- 任一步骤失败必须立即停止流程并返回真实失败原因；在失败状态下不得继续后续步骤。
- 会话复用约束：若同一会话前文已完成并通过第 1 步和第 2 步，允许跳过重复检测；但必须先输出“第 1 步已校验通过、第 2 步已校验通过”的进度，再进入第 3 步。

## 门禁机制（必须先执行）

### 1) 环境检测

目标：确认当前环境可执行 KWeaver 命令。

- 检查 `kweaver` 是否安装可用（如 `kweaver --version` 可正常返回）。
- 版本门槛：`kweaver` 版本必须满足 `>= 0.7.2`。
- 若版本低于 `0.7.2`：立即停止后续流程，并明确提示用户先升级 `kweaver` 到 `0.7.2` 或更高版本后再继续。
- 若未安装或不可用：立即告知用户先安装/修复，再停止后续路由。
- 若同一会话前文已确认通过：可跳过重复检测，并输出第 1 步“已校验通过（复用前文结果）”。

### 2) 配置检查

目标：确保本 skill 的运行配置可用（含知识网络配置、kn_id 上下文）并完成约束注入。

- 检查是否存在知识网络配置：`SOUL.md` 可读取且包含可用 `kn_id` 声明。
- 若无知识网络配置：先提示用户补充配置，再停止后续路由。
- 从 `SOUL.md` 确认本次请求可用的 `kn_id` 与上下文（时间、过滤、口径）。
- 校验 `kn_id` 在平台中是否真实存在且可访问；若 `kn_id` 不存在或不可用，必须提示用户先**配置或创建知识网络**（并补充有效 `kn_id`）后再继续。
- 检查当前会话是否已存在本 skill 约束（来源 `SOUL.md`、KN 必须声明、问数按第 10 步分流执行并返回结果+口径等）。
- 若不存在：先注入约束，再继续执行。
- 注入后在会话中记忆，后续同会话优先复用，不重复注入。
- 若同一会话前文已确认通过：可跳过重复检查，并输出第 2 步“已校验通过（复用前文结果）”。

### 3) 意图路由

目标：根据用户问题进行分流。

- **模糊问题澄清（必须执行）**：若同一问题可同时落入“问数/找数/其他”中的多个意图，或关键信息不足以唯一判定路由，必须先向用户发起澄清问题；在用户确认前不得进入任一子流程。
- **路由优先级（关键，必须遵守）**：当同一请求同时包含「取数」与「洞察/解读」诉求时，**优先路由到 `smart-data-insights`**（其内部再按 smart-ask-data 第 5～9 步完成取数），不得仅因为出现“查/统计/汇总/多少”等词就路由到 `smart-ask-data`。
- **趋势/对比/同环比默认问数路由（新增，必须遵守）**：当用户问题属于**趋势/对比/同比/环比**查询，且**未明确提出**“解读/分析/异常说明/建议/归因”等洞察型输出时，必须优先路由到 `smart-ask-data`（按问数流程执行，不进入 `smart-data-insights`）。
- **画图优先级约束（必须遵守）**：当同一请求同时出现“画图”与任一数据主意图（找数 / 问数 / 数据洞察 / 报告）时，必须先按数据主意图路由；仅当用户问题**只包含画图意图**、且不包含找数/问数/洞察/报告意图时，才可直接路由到 `smart-json2plot`。
- **数据洞察**（当用户要求「解读数据/趋势/异常/贡献/建议」或「多角度/多维度/分布」或「对比/同比/环比的分析解读」或「归因/根因/为什么/驱动因素/MECE 证据链」等；尤其出现“重新取数/查一下再解读/基于最新数据解读”等）→ 路由到 `smart-data-insights`（启用 [`references/attribution_analysis.md`](references/attribution_analysis.md) 等对应子场景模板）
- **问数**（仅取数：查多少、明细、汇总、统计；且用户**不要求**解读/趋势/异常/贡献/建议等洞察型输出）→ 路由到 `smart-ask-data`
- **冲突判定示例（同环比）**：  
  - 示例 A：「查询企业数量同环比」/「给我同环比数据表」→ 仅取数，路由 `smart-ask-data`。  
  - 示例 B：「查询企业数量同环比，并分析原因/给建议」→ 取数 + 洞察，路由 `smart-data-insights`。  
  - 示例 C：「先查同环比，再解读趋势异常」→ 按优先级进入 `smart-data-insights`（其内完成取数并输出洞察）。
  - 示例 D：「查询企业数量趋势」→ 未要求洞察，路由 `smart-ask-data`。  
  - 示例 E：「只要A与B对比结果」→ 未要求洞察，路由 `smart-ask-data`。  
  - 示例 F：「查询企业数量趋势，并分析异常原因」→ 取数 + 洞察，路由 `smart-data-insights`。  
- **找数**（找表、找字段、找视图、找职责）→ 路由到 `smart-search-tables`
- **报告**（基于已有找数/问数/归因交付写标准报告）→ 路由到 `smart-reporting`
- **画图**（用户仅要求“把已有结构化数据转换为图表数据”，且不含找数/问数/洞察/报告意图）→ 路由到 `smart-json2plot`（参考 [`references/smart-json2plot.md`](references/smart-json2plot.md)）
- **其他**（超边界/非数据任务）→ 返回边界说明或转普通对话，不强行进入子技能
- **问数前：日期及区间合法性（仅当本步已明确路由为问数时执行）**：在**进入第 4 步、衔接 `smart-ask-data` 之前**，若用户问题中**已出现或可唯一定义**的**公历日期或日期区间**（自然语言如「某年某月某日」「A 到 B」等），须先做**日历合法性**校核。若出现**不存在的月日、不存在的公历日**（如 13 月、非闰年的 2 月 29 日等，按公历规则判定）或**区间不合法**（上界早于下界、开闭与业务冲突且无法自洽等），**立即终止**总入口后续步，**不得**进入子流程，并向用户**点名无效处**及**建议改法**；在日期/区间**无法识别为需要校验**时，可不在此步作实质校核。本步是问数在平台侧的**首道**日期门闸，与 `smart-ask-data` 第 10 步查询数据校验**配合**（`dsl_query`/`metric_aggregation`/`complex_query`，`simple_aggregation` 为兼容别名；见 [`references/smart-ask-data.md`](references/smart-ask-data.md) 第 10 步）。  

### 4) 子流程衔接（序号连续）

目标：将总入口门禁与子流程门禁打通，避免重复编号和跳号。

- 总入口固定执行到第 4 步（完成路由）。
- 路由到 `smart-ask-data` 时，继续执行其第 5-11 步（第 5 步为“检查知识网络”）。
  - 问数第 5 步知识网络校验要求：`kn_id_ask_data`（明细条件查询）为必校验；`kn_id_metric`（指标聚合/同环比）仅在命中指标分支时必校验。命中分支所需网络需通过 `kweaver bkn get` 后再进入第 6 步。
- 路由到 `smart-search-tables` 时，继续执行其第 5-10 步（第 5 步为“确认知识网络”，第 6 步使用 `kweaver context-loader query-object-instance <知识网络id> <查询命令>`）。
- 路由到 `smart-data-interpretation`（或 `data_interpretation`）时：**令 S 为进入解读前已完成的最后一步编号**，继续执行 **7** 个解读步，全局为 **第 S+1 步至第 S+7 步**（不得固定写死为第 5–11 步）。
- 路由到 `smart-data-insights` 时：**令 S 为进入解读前已完成的最后一步编号**，继续执行 **7** 个解读步，全局为 **第 S+1 步至第 S+7 步**（不得固定写死为第 5–11 步）。常见：仅总入口后自备证据直解读（S=4）→ 第 5–11 步；接找数完结（S=11）→ 第 12–18 步；接问数完结（S=13）→ 第 14–20 步。
- 路由到 `smart-reporting` 时：**令 S 为进入报告前已完成的最后一步编号**，继续执行 **6** 个报告步，全局为 **第 S+1 步至第 S+6 步**（不得固定写死为第 5–10 步）。常见：接问数完结（S=13）→ 第 14–19 步；接找数完结（S=11）→ 第 12–17 步；仅总入口后自备证据直出报告（S=4）→ 第 5–10 步。
- 子流程内若引用“第 N 步”，均以该连续编号体系为准。

## 进度显示规范（必须执行）

- 总入口与子流程统一使用“连续步骤编号”展示进度。
- 每完成一步，立即输出一次进度，不得仅在最后汇总时输出。
- 进度输出需要包含：流程名称、当前完成步骤、下一步计划。
- 若当前步骤尚未输出进度，**不得进入下一步**。
- 若发现缺步、跳步或步骤失败，必须**立即停止流程**并说明原因，不得继续执行。
- 子流程结束时必须在任务进度清单中标注最后一步“已完成”并追加“流程完成”；`smart-reporting` 的最后一步为 `S+6`（其中 S 的定义见「子流程衔接」中 `smart-reporting` 条）。

推荐模板：

```text
## 📋 任务进度清单（阶段：总控制台）
- [ ] 已完成 · 步骤N（步骤名称）
- [ ] 待完成 · 步骤N+1（步骤名称）
```

步骤 1/2 复用前文结果时、以及进入子流程后，均继续使用同一“任务进度清单”模板（仅更新“已完成步骤、待完成步骤”两项）。

## 标准进度输出示例清单（新版）

```text
## 📋 任务进度清单（阶段：问数）
- [x] 已完成 · 步骤8（校验候选表数据查询权限）
- [ ] 进行中 · 步骤9（获取候选表详情）
- [ ] 待完成 · 步骤10（查询数据）
- [ ] 待完成 · 步骤11（画图需求分支）
- [ ] 待完成 · 步骤12（总结结果）
```

## 路由规则

### 1) 找表分支（`smart-search-tables`）

当用户目标是定位数据资产时进入该分支，例如：

- “某指标在哪张表”
- “有没有企业基本信息视图”
- “这个字段归哪个部门维护”

交付形态：候选表/视图/字段/职责信息，不直接代替问数结果。

### 2) 问数分支（`smart-ask-data`）

当用户目标是查询具体数据时进入该分支，例如：

- “查近30天新增企业数”
- “按地区统计企业数量”
- “查某企业住址/状态”

交付形态：查询结果 + 最小口径说明（时间、过滤、数据来源）；仅 `complex_query` 在内部生成并执行 SQL，且不对用户展示 SQL 原文。

### 3) 超范围场景

若用户需求超出已接入分支能力（例如要求脱离证据的主观判断、无法复核的推断、或需要外部系统能力），需明确告知边界并引导用户收敛为「找表」「可 SQL 表达的问数」「数据洞察（解读/维度/对比/归因等子场景，见 `references/smart-data-insights.md`）」或「基于既有证据的报告（`smart-reporting`）」。

### 4) 数据洞察分支（`smart-data-insights`）

当用户要求「解读数据/趋势/异常/贡献/建议」或「多角度/多维度/分布」或「对比/同比/环比的分析解读」或「归因/根因/为什么/MECE 证据链」等**洞察型输出**时进入该分支：

- **需要取数（默认）**：用户未提供可复核的问数交付物，或明确要求“重新取数/查一下再解读/基于库里最新数据解读”等 → 路由到 `smart-data-insights`（其内部按新版 `smart-ask-data` 第 5～9 步完成取数，再按模板合成洞察；归因子场景见 [`references/attribution_analysis.md`](references/attribution_analysis.md)）。
- **不取数（仅消费输入）**：用户已提供 `smart-ask-data` 最终交付原文（每段含 kn_id、原样 SQL、原样结果、最小口径），或已提供与 `attribution_analysis_report` 输入契约一致的**归因证据包**，且明确“不再新取数/不要重新查库/仅基于以下结果…” → 仍路由到 `smart-data-insights`，走其**模式 B**降级路径。

交付形态：洞察摘要 + 证据口径 +（数据解读 / 维度分析 / 对比分析 / **归因分析** 章节按需）+ 建议 + 局限与下一步；取数时需包含「原样 SQL + 原样结果 + 最小口径」作为可复核证据。若同轮要求归因报告终态，证据包就绪后须衔接 `smart-reporting`（`attribution_analysis_report`）。

### 5) 报告分支（`smart-reporting`）

当用户需要将已有找数/问数/归因结果整理为标准报告时进入该分支。

交付形态：标准报告框架（口径、证据、结论、限制、下一步），仅复用输入证据，不新增取数。

### 6) 画图分支（`smart-json2plot`）

当用户仅要求将**已有结构化数据**转换为图表数据（柱状图/饼图/折线图/散点图），且不包含找数、问数、洞察、报告意图时进入该分支。

交付形态：Markdown + 标识符的图表数据对象（不执行查询、不直接出图，参考 `references/smart-json2plot.md`）。

## 📋 任务进度清单（阶段：总控制台）

- [ ] 待完成 · 步骤一（环境检测）
- [ ] 待完成 · 步骤二（配置检查）
- [ ] 待完成 · 步骤三（意图路由，含问数场景日期与区间合法性校核）
- [ ] 待完成 · 步骤四（路由到子流程并衔接连续编号）

## 典型调用

```text
/smart-data-analysis 查企业基本信息相关表
/smart-data-analysis 查询近30天个体工商户数量
/smart-data-analysis 用 d71o5e1e8q1nr9l7mb80 查询快讯传媒有限公司住址
```

## 注意事项

- 本 skill 负责“编排与路由”，不是最终执行器。
- 子流程失败时应返回真实原因（权限、口径缺失、无命中等），不跨分支伪造答案。