---
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-json2plot.md`](references/smart-json2plot.md)

## 核心职责

1. 识别是否为数据类请求（数据资产、取数、指标、表/视图、治理职责、知识网络）。
2. 根据用户意图路由到：
   - `smart-search-tables`：找表/找视图/找字段/找职责
   - `smart-ask-data`：问数（text2sql，返回 SQL + 数据）
3. 对齐并传递上下文：`kn_id`、时间范围、过滤条件、业务口径。
4. 对超出问数/找表能力边界的请求给出明确说明，不伪造结果。

## 强约束

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

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

### 1) 环境检测

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

- 检查 `kweaver` 是否安装可用（如 `kweaver --version` 可正常返回）。
- 若未安装或不可用：立即告知用户先安装/修复，再停止后续路由。
- 若同一会话前文已确认通过：可跳过重复检测，并输出第 1 步“已校验通过（复用前文结果）”。

### 2) 配置检查

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

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

### 3) 意图路由

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

- **模糊问题澄清（必须执行）**：若同一问题可同时落入“问数/找数/其他”中的多个意图，或关键信息不足以唯一判定路由，必须先向用户发起澄清问题；在用户确认前不得进入任一子流程。
- **问数**（查多少、明细、汇总、统计）→ 路由到 `smart-ask-data`
- **找数**（找表、找字段、找视图、找职责）→ 路由到 `smart-search-tables`
- **其他**（超边界/非数据任务）→ 返回边界说明或转普通对话，不强行进入子技能

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

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

- 总入口固定执行到第 4 步（完成路由）。
- 路由到 `smart-ask-data` 时，继续执行其第 5-12 步。
- 路由到 `smart-search-tables` 时，继续执行其第 5-10 步。
- 子流程内若引用“第 N 步”，均以该连续编号体系为准。

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

- 总入口与子流程统一使用“连续步骤编号”展示进度。
- 每完成一步，立即输出一次进度，不得仅在最后汇总时输出。
- 进度输出需要包含：流程名称、当前完成步骤、下一步计划。
- 若当前步骤尚未输出进度，**不得进入下一步**。
- 若发现缺步、跳步或步骤失败，必须**立即停止流程**并说明原因，不得继续执行。
- 子流程结束时必须输出“流程完成”格式（如：`[smart-search-tables] 进度：已完成第 10 步（总结结果）；流程完成`）。

推荐模板：

```text
[smart-data-analysis] 进度：已完成第 N 步（步骤名称）；下一步：第 N+1 步（步骤名称）
```

步骤 1/2 复用前文结果时，可使用：

```text
[smart-data-analysis] 进度：已完成第 1 步（环境检测，已校验通过-复用前文结果）；下一步：第 2 步（配置检查）
[smart-data-analysis] 进度：已完成第 2 步（配置检查，已校验通过-复用前文结果）；下一步：第 3 步（意图路由）
```

在进入子流程后继续使用同一模板：

```text
[smart-ask-data] 进度：已完成第 N 步（步骤名称）；下一步：第 N+1 步（步骤名称）
[smart-search-tables] 进度：已完成第 N 步（步骤名称）；下一步：第 N+1 步（步骤名称）
```

## 标准进度输出示例清单

### A. 总入口（第 1-4 步）

```text
[smart-data-analysis] 进度：已完成第 1 步（环境检测）；下一步：第 2 步（配置检查）
[smart-data-analysis] 进度：已完成第 2 步（配置检查与确认 kn_id 上下文）；下一步：第 3 步（意图路由）
[smart-data-analysis] 进度：已完成第 3 步（意图路由）；下一步：第 4 步（路由到子流程）
[smart-data-analysis] 进度：已完成第 4 步（路由到子流程）；下一步：进入子流程第 5 步
```

复用前文已通过校验时：

```text
[smart-data-analysis] 进度：已完成第 1 步（环境检测，已校验通过-复用前文结果）；下一步：第 2 步（配置检查）
[smart-data-analysis] 进度：已完成第 2 步（配置检查，已校验通过-复用前文结果）；下一步：第 3 步（意图路由）
[smart-data-analysis] 进度：已完成第 3 步（意图路由）；下一步：第 4 步（路由到子流程）
[smart-data-analysis] 进度：已完成第 4 步（路由到子流程）；下一步：进入子流程第 5 步
```

### B. 问数分支（`smart-ask-data`，第 5-12 步）

```text
[smart-ask-data] 进度：已完成第 5 步（检查知识网络）；下一步：第 6 步（配置知识网络）
[smart-ask-data] 进度：已完成第 6 步（配置知识网络）；下一步：第 7 步（寻找候选表）
[smart-ask-data] 进度：已完成第 7 步（寻找候选表）；下一步：第 8 步（获取候选表详情）
[smart-ask-data] 进度：已完成第 8 步（获取候选表详情）；下一步：第 9 步（生成查询 SQL）
[smart-ask-data] 进度：已完成第 9 步（生成查询 SQL）；下一步：第 10 步（执行查询接口）
[smart-ask-data] 进度：已完成第 10 步（执行查询接口）；下一步：第 11 步（画图需求分支）
[smart-ask-data] 进度：已完成第 11 步（画图需求分支）；下一步：第 12 步（总结结果）
[smart-ask-data] 进度：已完成第 12 步（总结结果）；流程完成
```

### C. 找数分支（`smart-search-tables`，第 5-10 步）

```text
[smart-search-tables] 进度：已完成第 5 步（确认知识网络）；下一步：第 6 步（配置知识网络）
[smart-search-tables] 进度：已完成第 6 步（配置知识网络）；下一步：第 7 步（查询数据）
[smart-search-tables] 进度：已完成第 7 步（查询数据）；下一步：第 8 步（筛选视图）
[smart-search-tables] 进度：已完成第 8 步（筛选视图）；下一步：第 9 步（查询职责信息）
[smart-search-tables] 进度：已完成第 9 步（查询职责信息）；下一步：第 10 步（总结结果）
[smart-search-tables] 进度：已完成第 10 步（总结结果）；流程完成
```

## 路由规则

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

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

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

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

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

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

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

交付形态：SQL + 查询结果 + 最小口径说明（时间、过滤、数据来源）。

### 3) 超范围场景

若用户需求为纯业务解读、归因建议、图表出图、代码二次加工等，不属于本仓库问数链路，需明确告知边界并引导用户收敛为“找表”或“可 SQL 表达的问数”。

## 执行清单

```text
总入口进度：
- [ ] 1. 环境检测：确认 kweaver 可用
- [ ] 2. 配置检查：检查 SOUL.md 知识网络配置，确认 kn_id 与上下文，并注入本 skill 约束（仅首次）
- [ ] 3. 意图路由：问数 / 找数 / 其他
- [ ] 4. 路由到子流程并衔接连续编号（问数 5-12 / 找数 5-10）
```

## 典型调用

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

## 注意事项

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