Smart Data Fetch（数据获取与导出）

根据用户给出的主题或任务，从网页、本地文件（csv/excel/图片）、数据库获取数据，清洗合并后导出为 CSV / Excel / JSON。

工作流程

理解任务：分析用户主题，判断需要哪些数据源（网页 / 本地文件 / 图片 / 数据库）。
获取数据：调用 scripts/ 下对应脚本，参数化调用，不要现场改写脚本逻辑。
图片数据：脚本不支持图片，由 AI 直接多模态读取图片，整理为 records JSON（见"图片数据提取"）。
合并清洗：多源数据统一为 records 数组（[{"列名": 值, ...}, ...]），必要时去重、对齐列名。
导出：将 records 写入临时 JSON 文件，调用 export.py 导出目标格式。

所有脚本输出均为结构化 JSON：成功为 {"success": true, ...}；失败为 {"success": false, "error": {"type", "message", "hint"}}，按 hint 处理或向用户说明原因。

脚本参考

统一用法：python3 scripts/<脚本名>.py [参数]（下文以 S 代指本 SKILL.md 同级的 scripts/ 目录）。

fetch_web.py — 网页数据

python3 S/fetch_web.py <url> [--type tables|text|links] [--selector CSS选择器]
                         [--headers '{"Authorization": "..."}'] [--timeout 30]

--type tables（默认）：提取页面所有 <table>，返回 tables: [{headers, rows}]
--type text：提取正文段落文本
--type links：提取链接 {text, href}
局限：JS 动态渲染页面无法获取，失败时向用户说明并建议提供静态源或本地文件

read_files.py — 本地 csv/excel 读取

python3 S/read_files.py <path> [--sheet 0] [--preview 20] [--full]

返回 shape、columns（含 dtype）、sheet_names、preview（前 N 行）
默认仅返回预览，确认结构无误后加 --full 取全量，避免大文件刷屏

query_db.py — 数据库只读查询

python3 S/query_db.py --sql "SELECT ..." [--env-var SMART_DB_URL] [--params '{"id": 1}'] [--max-rows 10000]

连接串从环境变量读取（默认 SMART_DB_URL），禁止将连接串写入命令或文件
SQL 安全校验：仅允许单条 SELECT/WITH 语句（sqlglot AST 白名单 + 关键字黑名单兜底），写操作直接拒绝
--params 传命名参数，避免拼接 SQL

export.py — 统一导出

python3 S/export.py --input <输入文件> --to csv|xlsx|json [--output 输出路径]

输入支持 .json（records 数组或 {"records": [...]}）、.csv、.xlsx，可实现格式互转
缺省输出路径为同名换扩展名；CSV 使用 utf-8-sig 编码（Excel 打开中文不乱码）

图片数据提取（AI 多模态，无脚本）

用 Read 工具读取用户提供的图片；
识别表格/图表结构，将数据整理为 records JSON（列名取图表表头/坐标轴语义）；
写入临时 JSON 文件（如 smart_data_fetch_records.json，置于系统临时目录），调用 export.py 导出；
对识别不确定的数值，在导出前向用户标注确认。

安全约束（必须遵守）

数据库仅允许只读 SELECT 查询；连接串只从环境变量读取，不得出现在命令行参数、导出文件或日志中。
导出结果、临时文件中不得携带凭证、token、连接串等敏感信息。
网页获取仅用于用户明确请求的数据，遵守目标站点 robots 与版权要求。
多源数据合并时保留来源标注（可增加 source 列），便于用户溯源。

依赖

pandas、requests、beautifulsoup4、openpyxl（xlsx 读写）、sqlalchemy（数据库）、sqlglot（可选，SQL AST 校验，缺失时自动降级为关键字校验）。脚本运行时自动检测缺失项并输出安装提示。