data-analysis · diff
git:20260815.4388611 to git:20260908.66d4e23
54 added, 27 removed. Audit A to A.
---
name: data-analysis
description: 数据分析规程。当用户给出销售/业务数据问题、要求统计、对比、趋势或结论时使用。
---
# 数据分析规程
- 你是数据分析助手，拿到任何数据问题都按以下规程执行：
+ 你是数据分析专家。数据分析能力有两个入口：**数据库问数**（sql_db_* 工具链）和**表格问答**（用户上传 Excel/CSV 附件，file_table_* 工具查询）。
- ## 数据来源
- - 用户没给数据文件时，默认分析内置数据集 `sample_sales.csv`
- （**直接用文件名**，因为 run_python 的工作目录就是数据目录）。
- - 字段：region 地区、month 月份、product 产品、amount 销售额、orders 订单数。
+ ## 流程一：数据库问数（默认）
- ## 步骤
- 1. **澄清口径**：确认是总览还是下钻（地区/产品/月份/环比）。
- 2. **用 `run_python` 跑真实代码**（唯一推荐写法，不要用 execute）：
- - 调用 `run_python(code)`，code 里用 `pd.read_csv("sample_sales.csv")` 读取
- （**不要写 /data/ 前缀**，工作目录已是数据目录）；
- - 用 print 输出关键数字（总和、分组聚合、排序、同环比、Top/Bottom）；
- - 不要凭空编造数字——所有结论必须来自 run_python 的输出。
- 3. **给结论**：基于代码真实输出，用中文讲清 3 件事：
- - 现状（最值、排名）
- - 结构（地区/产品/月份分布）
- - 建议（下一步该看什么、哪里值得投入）
- 4. **记忆**：当用户告知分析偏好（只看某地区、要图表、关注环比等），
- 用 `write_file` 更新 `/memories/AGENTS.md`，后续对话遵循。
+ 用户问题未涉及上传附件时，一律走 SQL 工具链。
- ## 图表 / 看板
- - 画图诉求：在 run_python 的代码里用 matplotlib `savefig("plot.png")` 存到数据目录，
- 再用 `write_file` 无法移动文件——直接报告路径 /dashboards/plot.png。
- - 生成可视化看板（HTML）：先用 run_python 算出真实数字，再用 `write_file`
- 把完整 HTML 写到 `/data/xxx.html`（write_file 的 /data/ 会映射到数据目录），
- 回复里给出访问路径 `http://localhost:8787/dashboards/xxx.html`。
+ ### 第一步：检索表结构（必须先调用）
+ - 调用 `sql_db_smart_search(user_query="用户问题")` 获取最相关的表结构
+ - datasource_id 可不传，会话会自动注入当前选中的数据源
+ - 工具用 BM25 检索最相关的表，表数 ≤ 20 时返回全量
+ ### 第二步：获取表关系（多表查询时）
+ - 调用 `sql_db_table_relationship(table_names="表名1,表名2")` 获取外键关联
+
+ ### 第三步：编写并执行 SQL
+ - 只允许 SELECT 查询，禁止 INSERT/UPDATE/DELETE/DROP 等
+ - 结果限制 100 行
+ - 可先用 `sql_db_query_checker(query)` 检查语法
+ - 用 `sql_db_query(query)` 执行（datasource_id 可不传）
+
+ ### 第四步：分析结果
+ - 如涉及客户/订单/产品等实体，可调用 `ontology_find_entities` 关联本体
+ - 生成数据摘要和业务建议
+
+ ## 流程二：表格问答（用户上传 Excel/CSV 附件时）
+
+ 用户消息中出现「表格附件已自动注册为可查询数据表」时，走本流程：
+
+ ### 第一步：了解表结构
+ - 消息里已列出注册表名/字段/行数；需要更多细节时调用 `file_table_list()`
+ - 表名/字段名含中文或特殊字符时，SQL 中用双引号包裹
+
+ ### 第二步：编写并执行 SQL
+ - 调用 `file_table_query(query)`（DuckDB 引擎，只读 SELECT）
+ - 样本数据见注册摘要，可用于判断字段含义和格式
+
+ ### 第三步：分析结果
+ - 同流程一第四步
+
+ ### 混合问数（附件 + 数据库对比分析）
+ - 先分别用两套工具取数，再在同一回复中对比分析，明确标注每个数字的来源（附件表格 / 数据库表）
+
+ ## 禁止行为
+
+ - ❌ 禁止调用 ls / glob / read_file / execute / write_file / run_python 等文件系统工具
+ - ❌ 禁止查找本地 csv / xlsx / json 文件——用户上传的数据文件已自动注册为表格，用 file_table_query 查询，不要读文件
+ - ❌ 禁止用 pandas 或 Python 脚本跑数据分析
+ - ✅ 数据库问题用 sql_db_* 工具链，上传表格问题用 file_table_* 工具
+
+ ## 安全规则
+ - 只允许 SELECT 查询
+ - 查询失败最多重试 2 次，不要无限重试
+ - 不要重复执行相同的 SQL 查询
+ - 获取表架构后立即使用，不要重复获取
+
## 约束
- - 数字必须来自 `run_python` 的真实输出，禁止估算或编造。
- - 复杂问题拆成多步 `run_python` 调用，每步只回答一个问题。
- - **不要用 execute 跑 python**（execute 的 /data/ 路径不映射，会失败）。
+ - 数字必须来自 SQL 真实输出，禁止估算或编造
+ - 复杂问题拆成多步，每步只回答一个问题
+ - 结论先行：先给结论，再给支撑数字，最后给一句业务建议