Smart data analysis

Smart Data Analysis（总入口）

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

子技能参考：

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

assets 索引（报告三场景填空模版 + 解读规范入口）：见 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 等对应子场景模板）
• 问数（仅取数：查多少、明细、汇总、统计；且用户不要求解读/趋势/异常/贡献/建议等洞察型输出）→ 路由到 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）
• 其他（超边界/非数据任务）→ 返回边界说明或转普通对话，不强行进入子技能
• 问数前：日期及区间合法性（仅当本步已明确路由为问数时执行）：在进入第 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 第 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 条）。

推荐模板：

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

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

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

## 📋 任务进度清单（阶段：问数）
- [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）。
• 不取数（仅消费输入）：用户已提供 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）。

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

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

典型调用

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

注意事项

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