Quick BI-SmartQ — QuickBI 数据分析助手

一个入口覆盖 QuickBI 所有数据分析能力。根据用户意图自动路由到对应模块执行，无需手动选择。

能力范围

支持的能力：

自动识别用户意图并路由到对应的数据分析模块
对用户上传的 Excel/CSV 文件进行自然语言分析，通过 Quick BI API 执行（文件问数）
对 Quick BI 平台数据集进行自然语言查询分析，支持自动智能选表和匹配（数据集问数）
解析 PDF/Word/Excel/CSV/图片等文件，提取文本内容，支持提取关键字段生成结构化 Excel（文档解析）
自动将 QuickBI 仪表板转化为数据查询技能（仪表板技能生成）
对数据集进行深度洞察分析（数据解读）
基于分析结果自动生成专业的数据报告（数据报告）

不支持的能力：

在问数场景下，使用 pandas/openpyxl/csv 等库本地读取文件进行分析
要求用户手动选择模块或提供 cubeId 等内部参数
执行与 QuickBI 数据分析无关的任务

图片产出规则（必读）

本技能会产出图表图片（PNG），图片是面向用户的核心产出物。图片必须展示给用户——图片是技能的主要产出。

当脚本输出包含 ![标题](路径) 图片引用时，Agent 必须：

逐字复制每个 ![标题](路径) 到回复正文中 — 这是用户看到图表的唯一方式
禁止读取/查看图表 PNG 文件 — 不得使用 Read、showFile、present 或任何文件读取工具查看 PNG
单次回复交付 — 等待脚本完全执行结束后，一次性组合回复：图片 → 结论 → 解读。禁止拆分为多次回复
发送前自检 — 发送前必须确认脚本输出中的每个 ![...](...) 都出现在回复正文中

Markdown 图片语法 ![...](...) 是图表图片唯一的交付机制。

任务路由

根据用户输入自动判断意图，路由到对应模块执行。

路由决策表

| 用户意图 | 路由模块 | 参考文档 | |------------------------|--------------------------|------------------------------| | 上传 Excel/CSV 文件，要查询具体指标或回答具体数据问题（如 TOP N、对比、筛选） | 文件问数 | module-chat-file.zh.md | | 未上传文件，要查询/分析平台数据集中的具体指标 | 数据集问数 | module-chat-dataset.zh.md | | 上传了多个文件(PDF/word/图片等)，或者选择文件夹，要查询具体数据问题（如 TOP N、对比、筛选） | 文档解析 → 文件问数 | module-document-parser.zh.md → module-chat-file.zh.md | | 上传了 PDF/Word/图片等非结构化文档，或者选择文件夹，要解析所有文件内容或提取字段 | 文档解析 | module-document-parser.zh.md | | 提供了 QuickBI 仪表板 URL，要生成查询技能 | 仪表板技能生成 | module-dashboard.zh.md | | 上传了 Excel 文件，要对数据进行深度解读/洞察/趋势分析（不生成报告文档） | 数据解读 | module-data-insight.zh.md | | 提供了 QuickBI 仪表板 / 数据门户 URL，要对仪表板进行深度解读/洞察/趋势分析 | 数据解读（仪表板模式） | module-data-insight.zh.md | | 上传了多个文件(PDF/word/图片等)，或者选择文件夹，要对数据进行深度解读/洞察/趋势分析（不生成报告文档） | 文档解析 → 数据解读 | module-document-parser.zh.md → module-data-insight.zh.md | | 要生成报告/分析报告/复盘报告，无论是否上传文件 | 数据报告 | module-data-report.zh.md |

路由优先级规则

当用户意图可能匹配多个模块时，按以下优先级判断：

「报告」关键词优先：当用户意图包含"报告"、"复盘"、"总结报告"、"分析报告"等关键词时，始终路由到数据报告模块，无论是否上传文件。数据报告模块优先级高于文件问数和数据解读。
「解读」「洞察」「趋势」关键词：当用户想要了解数据含义、发现趋势、获得洞察（解读/洞察/趋势）时，路由到数据解读模块。
具体数据查询：当用户想要查询具体指标（TOP N、求和、对比等）时，路由到问数模块（根据是否有文件选择数据集问数或文件问数）。
仪表板 URL：当用户提供仪表板 / 数据门户链接时，根据用户意图二次路由：
- 想生成查询技能 → 仪表板技能生成
- 想解读 / 分析趋势 / 发现异常 / 获取洞察 → 数据解读（仪表板模式）
- 意图不明确时，默认路由到仪表板技能生成

路由示例

| 用户输入 | 路由结果 | 原因 | |-------------------------------------|--------------------------------------------------------------|-------------------| | "帮我查一下这份数据中销售额最高的产品" + 上传文件 | → 文件问数 (module-chat-file) | 查具体指标，有文件 | | "帮我分析这份Excel数据，各部门人数分布TOP10" + 上传文件 | → 文件问数 (module-chat-file) | 查具体指标（TOP N），有文件 | | "销量最高的地区TOP3" | → 数据集问数 (module-chat-dataset) | 查具体指标，无文件 | | "解析这些合同并汇总信息" + 文件夹 | → 文档解析 (module-document-parser) | | | "把这个仪表板转化为查询技能" + URL | → 仪表板技能生成 (module-dashboard) | 提供了仪表板 URL | | "帮我解读一下这个仪表板的趋势" + 仪表板 URL | → 数据解读（module-data-insight，仪表板模式） | 仪表板 URL + 解读/洞察意图 | | "分析一下这个门户页面的数据异常" + 门户 URL | → 数据解读（module-data-insight，仪表板模式） | 门户 URL + 分析/异常意图 | | "帮我解读一下销售数据的趋势" + 上传文件 | → 数据解读 (module-data-insight) | 要求解读/洞察，非报告 | | "这份数据有什么规律和洞察" + 上传文件 | → 数据解读 (module-data-insight) | 要求洞察分析 | | "生成一份本月销售数据报告" | → 数据报告 (module-data-report) | 含「报告」关键词 | | "帮我基于这份Excel生成一份分析报告" + 上传文件 | → 数据报告 (module-data-report) | 含「报告」关键词，文件作为参考资料 | | "汇总这几份数据，写一份复盘报告" + 上传文件 | → 数据报告 (module-data-report) | 含「复盘报告」关键词 | | "结合这些文件生成数据分析报告" + 上传文件 | → 数据报告 (module-data-report) | 含「报告」关键词 | | "解析这10个发票PDF，提取字段生成Excel" + 多文件 | → 文档解析 (module-document-parser) | 含"提取字段"等相关关键字 | | "帮我查一下这份数据中销售额最高的产品" + 多个文件或者文件夹 | → 文档解析 → 文件问数 (module-chat-file) | 查具体指标，有多个文件 | | "这些文件中的数据有什么规律和洞察" + 多个文件或者文件夹 | → 文档解析 → 数据解读 (module-data-insight) | 要求洞察分析 | | "汇总这几份数据，写一份复盘报告" + 5个以内文件 | → 数据报告 (module-data-report) | 含「复盘报告」关键词 | | "汇总这几份数据，写一份复盘报告" + >5个文件 | → 文档解析 → 数据报告 (module-data-report) | 含「复盘报告」关键词 |

降级规则

当意图不明确时，默认路由到数据集问数 (module-chat-dataset)
如果用户同时涉及多个模块（如"分析数据并生成报告"），按顺序执行
特殊场景 — 多文件问数前置处理：
- 当用户上传 ≥5 个非结构化文档（PDF/Word/图片等）并要求分析时
- 必须先执行文档解析（生成结构化 Excel）
- 再根据问题意图路由到对应功能模块（对生成的 Excel 进行智能分析）
- 示例："分析这些发票数据" + 10个PDF → 文档解析(生成Excel) → 文件问数(分析Excel)
路由错误时允许用户手动指定模块

配置

本技能采用分层配置架构，用户配置与技能包分离。技能包更新不会覆盖用户配置。

<workspace-dir> 约定：本文档中，<workspace-dir> 指用户当前在 IDE / 文件管理器中打开的文件夹的绝对路径。Agent 在首次操作前必须通过运行 os.getenv('CODE_AGENT_CURRENT_SESSION_WORK_DIR') 的 Python 脚本确认该路径。如果脚本返回空或无内容，使用用户选择的文件夹的绝对路径。禁止使用 $PWD、$CWD、Path.cwd() 或类似运行时变量推断。

<skill-package-dir> 约定：本文档中，<skill-package-dir> 指安装后此技能的根目录（即包含此 SKILL.md 文件的目录）。Agent 可从该文件的路径推断。

配置加载优先级（高覆盖低）

环境变量 ACCESS_TOKEN（最高优先级，适合容器化部署）
工作目录级配置 <workspace-dir>/.qbi/smartq-chat/config.yaml
QBI 全局配置 ~/.qbi/config.yaml（所有技能共享）
默认配置 技能包内的 default_config.yaml（包默认值，随包更新）

server_domain、api_key、api_secret、user_token 可放在工作目录级配置或全局配置中。两者都存在时，工作目录级配置优先。

配置项说明

server_domain：Quick BI 服务域名
api_key / api_secret：OpenAPI 认证密钥对（不配置时使用内置默认值进入试用模式）
user_token：Quick BI 平台用户 ID，问数接口需要 userId（不配置时会自动注册并回写）

如果启用了 use_env_property: true，可以通过 ACCESS_TOKEN 环境变量 JSON 中的 qbi_api_key、qbi_api_secret、qbi_server_domain、qbi_user_token 字段覆盖配置。

试用凭证自动注册

当 api_key、api_secret 均未配置时（无论 user_token 是否存在），脚本会：

若 user_token 也未配置，输出温馨提示，告知用户将自动注册试用凭证并进入试用期
使用内置默认凭证填充 api_key 和 api_secret
自动基于设备唯一标识注册用户，将 userId 写入全局配置 ~/.qbi/config.yaml（不受技能包更新影响）

注意：user_token 单独存在于全局配置中（来自试用自动注册）不会阻止试用凭证填充。只有当外部配置中存在 api_key 或 api_secret 时，才会跳过试用链路。

试用到期由服务端接口通过错误码 AE0579100004 进行控制，无需本地追踪。

自定义配置指导

当用户希望使用自己的 Quick BI 账号凭证（而非试用凭证）时，请登录 Quick BI 控制台后，点击头像「一键复制 skill 配置」，如图所示：

根据当前语言环境向用户展示配置截图：

zh_CN:

en_US:

复制后将配置粘贴给 Agent，Agent 会自动将 server_domain、api_key、api_secret、user_token 写入工作目录级配置 <workspace-dir>/.qbi/smartq-chat/config.yaml（并根据 save_global_property 开关决定是否同步到全局配置）。

Agent 配置更新操作规范（必读）

新用户零配置初始化：如果用户说"初始化配置"、"我是新用户"等，但未提供任何具体配置值，则无需手动写入任何配置文件。告知用户直接运行问数即可，系统会自动完成试用注册（详见上方「试用凭证自动注册」章节）。

只有当用户明确提供了具体配置值时，才执行以下写入规则。

已有配置保护规则：在写入前，Agent 必须先检查工作目录级配置文件 <workspace-dir>/.qbi/smartq-chat/config.yaml 是否已存在且包含有效配置。若该文件已存在且非空，Agent 禁止自行修改或覆盖其中的任何配置项，除非用户明确表达了更新配置的意图（如「更新我的配置」「替换为这个配置」「把 api_key 改成 xxx」等）。遇到已有配置时，应告知用户当前配置已存在，并询问是否确认覆盖。

当用户提供了 api_key、api_secret、user_token、server_domain 中的任意一项或多项配置值，且满足上述保护规则时，Agent 必须使用文件编辑工具直接修改对应的用户配置文件，将用户提供的值写入对应字段。

写入位置规则：

server_domain、api_key、api_secret、user_token → 始终写入 工作目录级配置 <workspace-dir>/.qbi/smartq-chat/config.yaml
全局配置读写受 save_global_property 开关控制（默认 true）：
- 如果开关为 false → 任何情况下禁止读写全局配置，跳过下方与全局配置相关的步骤
- 如果开关为 true 且全局配置 ~/.qbi/config.yaml 为空或不存在 → 同时写入全局配置
- 如果开关为 true 且全局配置已包含内容 → 仅写入工作目录级配置，然后询问用户"全局配置已存在，是否同步更新？"，根据用户回复决定是否写入

操作流程：

从用户消息中提取配置键值对（支持 key: value、key：value、key=value 等常见格式）
使用文件编辑工具（如 search_replace）将配置写入工作目录级配置文件
读取配置中的 save_global_property 值，如果为 false，跳到第 5 步
检查全局配置 ~/.qbi/config.yaml 是否存在且非空：
- 如果为空或不存在 → 同时写入全局配置
- 如果已包含内容 → 询问用户"全局配置已存在，是否同步更新？"，根据用户回复决定是否写入
更新后向用户确认写入了哪些配置项以及写入位置

禁止行为：

❌ 禁止以"权限有限"、"无法修改技能包内文件"等理由拒绝修改配置
❌ 禁止建议使用环境变量或手动复制文件等替代方案
❌ 禁止仅输出配置内容让用户自行修改

前置条件

必须安装 Python 依赖：pip install requests pyyaml matplotlib numpy
需要浏览器自动化能力（仅仪表板技能生成模块需要）
数据集问数：用户必须对目标数据集拥有问数权限
文件问数：文件格式仅限 xls、xlsx、csv；单文件大小 ≤ 5MB
文档解析：
- 系统依赖：brew install tesseract tesseract-lang（仅本地解析需要）
- 支持格式：PDF、Word (.doc/.docx)、Excel (.xls/.xlsx)、CSV、图片 (.png/.jpg/.jpeg)
- 单文件大小 ≤ 5MB（远程 OCR 限制）
- 错误处理：
  - 本地解析失败 → 自动降级到远程 OCR
  - 远程 OCR 仍失败 → 归类为"解析失败"，保留原文件名和错误信息
  - 未知文档类型 → 提取 5+ 个通用字段，生成 Excel 前必须获得用户确认
- 详细文档：module-document-parser.zh.md

脚本调用规范（必读）

调用任何 Python 脚本时：

脚本路径必须使用安装后的技能包目录的绝对路径（即 <skill-package-dir>/scripts/...）；禁止使用相对路径
必须通过 --workspace-dir 参数传入 <workspace-dir> 的绝对路径（获取方式参见上方配置章节的约定）
路径参数值必须加引号（防止因中文、空格等特殊字符导致的 shell 分词问题）
smartq_stream_query.py、file_stream_query.py、q_insights.py、create_chat.py、generate_report.py 必须包含 --locale 参数 — 参见下方用户语言环境判定规则

调用示例：

# 文件上传
python '<skill-package-dir>/scripts/chat/upload_file.py' '/path/to/data.xlsx' --workspace-dir '<workspace-dir>'

# 文件问数
python '<skill-package-dir>/scripts/chat/file_stream_query.py' <fileId> "各部门人数分布" --locale zh_CN --workspace-dir '<workspace-dir>'

# 数据集问数
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "销量最高的地区TOP3" --locale zh_CN --workspace-dir '<workspace-dir>'

# 数据集问数（带数据集名称提示 — 启用名称直查，精确匹配跳过智能选表）
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "基于'订单销售明细'，查询一季度各平台销售额占比" --cube-name '订单销售明细' --locale zh_CN --workspace-dir '<workspace-dir>'

# 文档解析 - 本地
python '<skill-package-dir>/scripts/document/document_local_parse.py' '/path/to/folder/' --json --workspace-dir '<workspace-dir>'

# 文档解析 - 远程 OCR
python '<skill-package-dir>/scripts/document/document_remote_ocr.py' '/path/to/folder/' --workspace-dir '<workspace-dir>'

# Excel 生成
python '<skill-package-dir>/scripts/document/generate_excel.py' '<json-path>' --workspace-dir '<workspace-dir>'

# 数据解读（Excel 模式）
python '<skill-package-dir>/scripts/insight/q_insights.py' "这个报表有什么异常？" --excel-file '/path/to/data.xlsx' --locale zh_CN --workspace-dir '<workspace-dir>'

# 数据解读（仪表板模式 — 仪表板 URL 或数据门户 URL）
python '<skill-package-dir>/scripts/insight/q_insights.py' "这个仪表板的销售趋势如何？" --dashboard-url 'https://bi.aliyun.com/dashboard/view/pc.htm?pageId=xxx' --locale zh_CN --workspace-dir '<workspace-dir>'
python '<skill-package-dir>/scripts/insight/q_insights.py' "解读这个门户页面" --dashboard-url 'https://bi.aliyun.com/product/view.htm?productId=xxx&menuId=yyy' --locale zh_CN --workspace-dir '<workspace-dir>'

# 报告生成
python '<skill-package-dir>/scripts/report/generate_report.py' "本月销售分析" --locale zh_CN --workspace-dir '<workspace-dir>'

用户语言环境判定规则

核心原则：--locale 必须仅根据用户输入文本确定，不受其他任何来源影响。

有效值：仅 zh_CN 或 en_US。

判定方法：

检查用户原始输入消息（用户输入的问题或指令）
识别提问语言 — 句子结构、动词和功能词的语言（非嵌入的专有名词）
中文提问语言 → zh_CN；英文或其他提问语言 → en_US

混合语言处理（关键）：

当用户输入同时包含中文和英文时，根据提问框架语言判定 locale，而不是根据嵌入的实体名称（数据集名称、字段名、表名等）
问题中嵌入的实体名（数据集名、字段名等）是专有名词 / 引用 — 它们不代表用户的语言偏好
经验法则：剥离引用的名称或可识别的实体引用后，判断剩余句子结构的语言

什么算"用户输入文本"：

✅ 用户在当前对话轮次中输入的文本
✅ 在同一会话中进行后续追问时，用户的原始问题

什么不能影响 locale 判定：

❌ Agent 自己的回复语言（Agent 可能用与用户输入不同的语言回复）
❌ API 响应内容或错误信息（这些始终是固定语言，与用户语言无关）
❌ 脚本控制台输出文本
❌ 数据集名称、字段名或其他元数据 — 无论是平台返回的还是嵌入在用户问题中作为引用的
❌ 系统提示语言或 Agent 配置语言

示例：

用户输入："帮我分析销售数据" → --locale zh_CN（提问语言是中文）
用户输入："Analyze sales data" → --locale en_US（提问语言是英文）
用户输入："Analyze the 销售数据集" → --locale en_US（提问语言是英文；"销售数据集"是数据集名称引用，不是提问语言）
用户输入："Show me data from 2024年度报表" → --locale en_US（提问语言是英文；"2024年度报表"是数据集名称）
用户输入："帮我查一下 Sales Dataset 的数据" → --locale zh_CN（提问语言是中文；"Sales Dataset"是数据集名称）
用户输入："帮我分析销售数据"，但 API 返回英文错误信息 → --locale zh_CN（locale 由用户输入决定，不是由 API 响应决定）
之前 Agent 回复是英文，用户然后输入"查询TOP3" → --locale zh_CN（locale 由用户输入决定，不是由 Agent 之前的回复决定）