• Automatically identify user intent and route to the corresponding data analysis module
• Perform natural-language analysis on user-uploaded Excel/CSV files via the Quick BI API (File Q&A)
• Perform natural-language query analysis on Quick BI platform datasets, with automatic intelligent table selection and matching (Dataset Q&A)
• Parse PDF/Word/Excel/CSV/images, extract text, and support extracting key fields to generate structured Excel (Document Parsing)
• Auto-convert QuickBI dashboards into data query skills (Dashboard Skill Generation)
• Perform deep insight analysis on datasets (Data Insight)
• Auto-generate professional data reports based on analysis results (Data Report)

• Use pandas/openpyxl/csv or similar libraries to read files locally for analysis in Q&A scenarios
• Require users to manually choose a module or provide internal parameters such as cubeId
• Perform tasks unrelated to QuickBI data analysis

1. "Report" keyword takes priority (「报告」关键词优先): When user intent contains keywords like "report", "review", "summary report", "analysis report" (报告/复盘/总结报告/分析报告), ALWAYS route to the Data Report module, regardless of whether files are uploaded. Data Report module has higher priority than File Q&A and Data Insight.
2. "Interpret", "insight", "trend" keywords (「解读」「洞察」「趋势」关键词): When user wants to understand data meaning, discover trends, or gain insights (解读/洞察/趋势), route to the Data Insight module.
3. Specific data query (具体数据查询): When user wants to query specific metrics (TOP N, sum, comparison, etc.), route to the Q&A module (choose Dataset Q&A or File Q&A based on whether files are present).
4. Dashboard URL (仪表板 URL): When user provides a dashboard link, route to Dashboard Skill Generation.

• When intent is unclear, default to Dataset Q&A (module-chat-dataset) (当意图不明确时，默认路由到数据集问数)
• If the user involves multiple modules at the same time (e.g. "analyze data and generate a report" ("分析数据并生成报告")), execute them in sequence
• Special scenario — multi-file preprocessing before Q&A (特殊场景 — 多文件问数前置处理):
  • When user uploads ≥5 unstructured documents (PDF/Word/images, etc.) and requests analysis
  • MUST execute Document Parsing first (generate structured Excel)
  • Then route to the corresponding functional module based on question intent (perform intelligent analysis on the generated Excel)
  • Example: "Analyze these invoice data" + 10 PDFs → Document Parsing (generate Excel) → File Q&A (analyze Excel)
  • 示例："分析这些发票数据" + 10个PDF → 文档解析(生成Excel) → 文件问数(分析Excel)
• If routing is incorrect, allow the user to manually specify the module (路由错误时允许用户手动指定模块)

<workspace-dir>

convention: In this document,

<workspace-dir>

refers to the absolute path of the folder the user currently has open in the IDE / file manager. The Agent MUST confirm this path before the first operation by running a Python script with

os.getenv('CODE_AGENT_CURRENT_SESSION_WORK_DIR')

. If the script returns nothing or empty, use the absolute path of the folder selected by the user. MUST NOT infer using

$PWD

,

$CWD

, or

Path.cwd()

or similar runtime variables.

<skill-package-dir>

convention: In this document,

<skill-package-dir>

refers to the root directory of this skill after installation (i.e. the directory containing this

SKILL.md

file). The Agent can infer it from the path of this file.

1. Environment variable

   ACCESS_TOKEN

   (highest priority, suitable for container deployment)
2. Workspace-level configuration

   <workspace-dir>/.qbi/smartq-chat/config.yaml

3. QBI global configuration

   ~/.qbi/config.yaml

   (shared by all skills)
4. Default configuration

   default_config.yaml

   inside the skill package (package defaults, updated with the package)

server_domain

api_key

api_secret

user_token

• server_domain

  : Quick BI service domain

• api_key

  /

  api_secret

  : OpenAPI authentication key pair (if not configured, built-in defaults are used for trial mode)

• user_token

  : Quick BI platform user ID; the Q&A interface requires

  userId

  (if not configured, it is registered automatically and written back)

use_env_property: true

qbi_api_key

qbi_api_secret

qbi_server_domain

qbi_user_token

ACCESS_TOKEN

api_key

api_secret

user_token

1. If

   user_token

   is also not configured, print a friendly message informing the user that trial credentials will be registered automatically and trial mode will begin
2. Use built-in default credentials to populate

   api_key

   and

   api_secret

3. Automatically register a user based on the device's unique identifier and write the userId to the global configuration

   ~/.qbi/config.yaml

   (not affected by skill package updates)

Note:

user_token

existing alone in the global configuration (from automatic trial registration) will NOT prevent trial credential population. ONLY when

api_key

or

api_secret

exists in an external configuration will the trial flow be skipped.

AE0579100004

Show the configuration screenshot to the user based on current locale:

• zh_CN:
• en_US:

server_domain

api_key

api_secret

user_token

<workspace-dir>/.qbi/smartq-chat/config.yaml

save_global_property

<workspace-dir>/.qbi/smartq-chat/config.yaml

api_key

api_secret

user_token

server_domain

• server_domain

  ,

  api_key

  ,

  api_secret

  ,

  user_token

  → ALWAYS write to the workspace-level configuration

  <workspace-dir>/.qbi/smartq-chat/config.yaml

• Global configuration read/write is controlled by the

  save_global_property

  switch (default

  true

  ):
  • If the switch is

    false

    → MUST NOT read or write global configuration under any circumstance, skip the global-configuration-related steps below
  • If the switch is

    true

    and the global configuration

    ~/.qbi/config.yaml

    is empty or does not exist → also write to the global configuration
  • If the switch is

    true

    and the global configuration already contains content → write ONLY to the workspace-level configuration, then ask the user "Global configuration already exists. Do you want to sync the update?" and decide whether to write based on the user's reply

1. Extract configuration key-value pairs from the user message (support common formats such as

   key: value

   ,

   key：value

   , and

   key=value

   )
2. Use a file editing tool (such as search_replace) to write the configuration into the workspace-level configuration file
3. Read the

   save_global_property

   value in the configuration; if it is

   false

   , skip to step 5
4. Check whether the global configuration

   ~/.qbi/config.yaml

   exists and is non-empty:
   • If it is empty or does not exist → also write to the global configuration
   • If it already contains content → ask the user "Global configuration already exists. Do you want to sync the update?" and decide whether to write based on the user's reply
5. After the update, confirm to the user which configuration items were written and where they were written

• ❌ MUST NOT refuse to modify configuration citing reasons such as "limited permissions" or "unable to modify files inside the skill package"
• ❌ MUST NOT suggest workarounds such as using environment variables or manually copying files
• ❌ MUST NOT only output the configuration content and ask the user to modify it themselves

• Python dependencies MUST be installed:

  pip install requests pyyaml matplotlib numpy

• Browser automation capability is required (Dashboard Skill Generation module ONLY)
• Dataset Q&A: user MUST have Q&A permission for the target dataset
• File Q&A: file formats limited to

  xls

  ,

  xlsx

  ,

  csv

  ; single file size ≤ 10MB
• Document Parsing:
  • System dependency:

    brew install tesseract tesseract-lang

    (required for local parsing ONLY)
  • Supported formats: PDF, Word (.doc/.docx), Excel (.xls/.xlsx), CSV, images (.png/.jpg/.jpeg)
  • Single file size ≤ 10MB (remote OCR limit)
  • Error handling:
    • Local parsing failure → automatically falls back to remote OCR
    • Remote OCR still fails → classified as "parse failure", retaining original filename and error message
    • Unknown document type → extract 5+ generic fields, MUST obtain user confirmation before generating Excel
  • Detailed documentation: module-document-parser.md

1. The script path MUST use the absolute path of the installed skill package directory (i.e.

   <skill-package-dir>/scripts/...

   ); MUST NOT use relative paths
2. MUST pass the absolute path of

   <workspace-dir>

   via the

   --workspace-dir

   parameter (see the conventions in the Configuration section above for how to obtain it)
3. Wrap path parameter values in quotes (to prevent shell tokenization issues caused by Chinese characters, spaces, or other special characters)

4. smartq_stream_query.py

   ,

   file_stream_query.py

   ,

   q_insights.py

   ,

   create_chat.py

   ,

   generate_report.py

   MUST include the

   --locale

   parameter — see User Locale Determination Rules below

undefined

Core principle:

--locale

MUST be determined SOLELY based on the user's input text, NOT influenced by any other source.

zh_CN

en_US

• Examine the user's original input message (the question or instruction the user typed)
• Identify the question/instruction language — the language of the sentence structure, verbs, and functional words (not embedded proper nouns)
• Chinese question language →

  zh_CN

  ; English or other question language →

  en_US

• When user input contains both Chinese and English, determine locale by the question framing language, NOT by embedded entity names (dataset names, field names, table names, etc.)
• Entity names (dataset names, field names, etc.) embedded in the question are proper nouns / references — they do NOT indicate the user's language preference
• Rule of thumb: strip out quoted names or recognizable entity references, then judge the language of the remaining sentence structure

• ✅ The text the user typed in the current conversation turn
• ✅ The user's original question when performing follow-up queries in the same session

• ❌ The Agent's own reply language (Agent may reply in a language different from the user's input)
• ❌ API response content or error messages (these are always in a fixed language regardless of the user's language)
• ❌ Script console output text
• ❌ Dataset names, field names, or other metadata — whether returned by the platform OR embedded in the user's question as references
• ❌ System prompt language or Agent configuration language

• User input: "帮我分析销售数据" →

  --locale zh_CN

  (question language is Chinese)
• User input: "Analyze sales data" →

  --locale en_US

  (question language is English)
• User input: "Analyze the 销售数据集" →

  --locale en_US

  (question language is English; "销售数据集" is a dataset name reference, not the question language)
• User input: "Show me data from 2024年度报表" →

  --locale en_US

  (question language is English; "2024年度报表" is a dataset name)
• User input: "帮我查一下 Sales Dataset 的数据" →

  --locale zh_CN

  (question language is Chinese; "Sales Dataset" is a dataset name)
• User input: "帮我分析销售数据", but API returns English error message →

  --locale zh_CN

  (locale is determined by user input, NOT by API response)
• Previous Agent reply was in English, user then types "查询TOP3" →

  --locale zh_CN

  (locale is determined by user input, NOT by Agent's previous reply)

• ❌ MUST NOT omit the

  --workspace-dir

  parameter when calling scripts
• ❌ MUST NOT use relative paths to call scripts (e.g.

  python3 scripts/chat/...

  )
• ❌ MUST NOT use hard-coded paths or guessed paths
• ❌ MUST NOT omit the

  --locale

  parameter when calling scripts that require it
• ❌ MUST NOT determine

  --locale

  based on Agent's own output language or API/script return content