alibabacloud-quickbi-smartq

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

一个入口即可使用 QuickBI 的所有数据分析功能。系统会根据用户意图自动路由至对应模块，无需手动选择。

范围

可以：

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

不可以：

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

图片输出规则（必须阅读）

此技能会生成图表图片（PNG），作为用户的核心交付内容。必须向用户展示图片——它们是此技能的主要输出。

当脚本输出包含 ![Title](path) 图片引用时，Agent 必须：

1. 在回复正文中原样包含每个 ![Title](path)——这是用户查看图表的唯一方式
2. 不得使用 Read、showFile、present 或任何文件读取工具读取/查看图表 PNG 文件
3. 单次回复交付——等待脚本完全执行后，再撰写一条包含以下内容的回复：图片 → 结论 → 解读。不得拆分为多条回复
4. 发送前自检——发送前，确认脚本输出中的每个 ![...](...) 都出现在回复正文中

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

任务路由

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

路由决策表

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

路由优先级规则

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

1. “报告”关键词优先：当用户意图包含“报告”“评审”“总结报告”“分析报告”等关键词时，始终路由到数据报告模块，无论是否上传文件。数据报告模块的优先级高于文件问答和数据洞察。
2. “解读”“洞察”“趋势”关键词：当用户希望理解数据含义、发现趋势或获得洞察时，路由到数据洞察模块。
3. 特定数据查询：当用户希望查询特定指标（TOP N、总和、比较等）时，路由到问答模块（根据是否有文件选择数据集问答或文件问答）。
4. 仪表板 URL：当用户提供仪表板/数据门户链接时，根据用户意图进行路由：
   • 希望生成查询技能 → 仪表板技能生成
   • 希望对仪表板进行解读/趋势分析/查找异常/获取洞察 → 数据洞察（仪表板模式）
   • 意图不明确时，默认路由到仪表板技能生成

路由示例

用户输入	路由结果	判断依据
“帮我找出这份数据中销量最高的产品” + 上传的文件	→ 文件问答（module-chat-file）	查询具体指标，且有文件
“帮我分析这份 Excel 数据，找出各部门人数排名前 10 的部门” + 上传的文件	→ 文件问答（module-chat-file）	查询具体指标（TOP N），且有文件
“销量最高的前 3 个地区”	→ 数据集问答（module-chat-dataset）	查询具体指标，没有文件
“解析这些合同并总结信息” + 文件夹	→ 文档解析（module-document-parser）
“将此仪表板转换为查询技能” + URL	→ 仪表板技能生成（module-dashboard）	提供了仪表板 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 在首次操作前，必须运行 Python 脚本，通过 os.getenv('CODE_AGENT_CURRENT_SESSION_WORK_DIR') 确认此路径。如果脚本未返回内容或返回空值，则使用用户所选文件夹的绝对路径。不得使用 $PWD、$CWD、Path.cwd() 或类似运行时变量推断路径。

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

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

1. 环境变量 ACCESS_TOKEN（优先级最高，适用于容器部署）
2. 工作区级配置 <workspace-dir>/.qbi/smartq-chat/config.yaml
3. QBI 全局配置 ~/.qbi/config.yaml（所有技能共享）
4. 默认配置 技能包中的 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），脚本将：

1. 如果也未配置 user_token，则向用户显示友好提示，告知系统将自动注册试用凭证并进入试用模式
2. 使用内置默认凭证填充 api_key 和 api_secret
3. 根据设备的唯一标识自动注册用户，并将 userId 写入全局配置 ~/.qbi/config.yaml（不受技能包更新影响）

注意：如果全局配置中只有 user_token（由自动试用注册写入），仍不会阻止系统填充试用凭证。只有外部配置中存在 api_key 或 api_secret 时，才会跳过试用流程。

试用有效期由服务端接口通过错误码 AE0579100004 控制，无需本地跟踪。

自定义配置指南

如果用户想使用自己的 Quick BI 账号凭证（而非试用凭证），请登录 Quick BI 控制台，点击头像选项 “一键复制技能配置”，如下所示：

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

• 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 是否已存在且包含有效配置。如果文件已存在且非空，除非用户明确表示要更新（例如“更新我的配置”“替换为此配置”“将 api_key 更改为 xxx”等），否则 Agent 不得自行修改或覆盖任何配置项。发现现有配置时，应告知用户配置已存在，并询问是否确认覆盖。

当用户提供 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，且全局配置已有内容 → 仅写入工作区级配置，然后询问用户：“全局配置已存在。是否要同步更新？”并根据用户的回复决定是否写入

流程：

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

禁止操作：

• ❌ 不得以“权限有限”或“无法修改技能包内的文件”等理由拒绝修改配置
• ❌ 不得建议使用环境变量或手动复制文件等变通方法
• ❌ 不得只输出配置内容并让用户自行修改

前置条件

• 必须安装 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.md

脚本调用约定（必读）

调用任何 Python 脚本时：

1. 脚本路径必须使用已安装技能包目录的绝对路径（即 <skill-package-dir>/scripts/...）；不得使用相对路径
2. 必须通过 --workspace-dir 参数传入 <workspace-dir> 的绝对路径（如何获取该路径，请参见上文配置部分中的约定）
3. 路径参数值必须用引号括起来（以避免中文字符、空格或其他特殊字符导致的 Shell 分词问题）
4. smartq_stream_query.py、file_stream_query.py、q_insights.py、create_chat.py、generate_report.py 必须包含 --locale 参数 — 请参见下文的用户区域设置确定规则

调用示例：

# File upload
python '<skill-package-dir>/scripts/chat/upload_file.py' '/path/to/data.xlsx' --workspace-dir '<workspace-dir>'

# File Q&A
python '<skill-package-dir>/scripts/chat/file_stream_query.py' <fileId> "headcount distribution by department" --locale zh_CN --workspace-dir '<workspace-dir>'

# Dataset Q&A
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "TOP 3 regions by sales" --locale zh_CN --workspace-dir '<workspace-dir>'

# Dataset Q&A (with dataset name hint — enables name lookup, exact match skips intelligent table selection)
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "Based on 'Order Sales Details', what is the sales share by platform in Q1?" --cube-name 'Order Sales Details' --locale zh_CN --workspace-dir '<workspace-dir>'

# Document Parsing - local
python '<skill-package-dir>/scripts/document/document_local_parse.py' '/path/to/folder/' --json --workspace-dir '<workspace-dir>'

# Document Parsing - remote OCR
python '<skill-package-dir>/scripts/document/document_remote_ocr.py' '/path/to/folder/' --workspace-dir '<workspace-dir>'

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

# Data Insight
python '<skill-package-dir>/scripts/insight/q_insights.py' "any anomalies in this report?" --excel-file '/path/to/data.xlsx' --locale zh_CN --workspace-dir '<workspace-dir>'

# Data Insight (Dashboard mode — dashboard URL or data portal URL)
python '<skill-package-dir>/scripts/insight/q_insights.py' "what are the sales trends in this dashboard?" --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' "Interpret this portal page" --dashboard-url 'https://bi.aliyun.com/product/view.htm?productId=xxx&menuId=yyy' --locale en_US --workspace-dir '<workspace-dir>'

# Report generation
python '<skill-package-dir>/scripts/report/generate_report.py' "this month sales analysis" --locale zh_CN --workspace-dir '<workspace-dir>'

用户语言环境判定规则

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

有效值：仅限 zh_CN 或 en_US。

判定方法：

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

混合语言的处理方式（重要）：

• 当用户输入同时包含中文和英文时，根据问题的框架语言判定语言环境，而非根据嵌入的实体名称（数据集名称、字段名称、表名称等）
• 问题中嵌入的实体名称（数据集名称、字段名称等）是专有名词／引用，不表示用户的语言偏好
• 经验法则：去掉引号中的名称或可识别的实体引用，然后根据剩余句子结构判定语言

“用户输入文本”的范围：

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

以下内容不得影响语言环境判定：

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

示例：

• 用户输入："please analyze sales data" → --locale zh_CN（问题语言为中文）
• 用户输入："Analyze sales data" → --locale en_US（问题语言为英文）
• 用户输入："Analyze the sales-dataset" → --locale en_US（问题语言为英文；数据集名称是引用，不代表问题语言）
• 用户输入："Show me data from 2024-annual-report" → --locale en_US（问题语言为英文；数据集名称是引用）
• 用户输入："please query Sales Dataset data" → --locale zh_CN（问题语言为中文；"Sales Dataset" 是数据集名称）
• 用户输入："please analyze sales data"，但 API 返回英文错误消息 → --locale zh_CN（语言环境由用户输入决定，而非 API 响应）
• 上一条 Agent 回复为英文，随后用户用中文输入"query TOP3" → --locale zh_CN（语言环境由用户输入决定，而非 Agent 的上一条回复）

禁止的操作：

• ❌ 调用脚本时不得省略 --workspace-dir 参数
• ❌ 调用脚本时不得使用相对路径（例如 python3 scripts/chat/...）
• ❌ 不得使用硬编码路径或猜测的路径
• ❌ 调用需要 --locale 参数的脚本时不得省略该参数
• ❌ 不得根据 Agent 自身的输出语言或 API／脚本返回内容确定 --locale