chatbi-agent-skill

metadata: author: ChatBI Skills version: "1.0.0" --- # ChatBI 问数 Agent Skill ## 概述 `scripts/chatbi_cli.py` 帮助用户完成 **自然语言问数 → 意图理解 → 智能选表 → SQL 生成执行 → 获取结果** 的完整流程。 ### 核心能力 本 Skill 调用 ChatBI Agent 流式接口，从丰富的 Agent 输出中只提取关键信息： 1. **意图理解**：`intent_tool` → `understanding_thinking`（Agent 对用户问题的理解） 2. **选表结果**：`table_select_tool` → `table_name` + `table_selected_reason`（选择了哪些表及原因） 3. **SQL 执行**：`sql_executed`（生成的 SQL）、`execution_plan`（执行计划）、`data_preview_info`（数据预览） 4. **最终回答**：`is_final_answer=true` 且 `type=answer` 的内容 --- ## 安装 ```bash pip install -r scripts/requirements.txt ``` --- ## 快速开始 ```bash # 基本问数 python3 scripts/chatbi_cli.py -q "查询乳制品的销售情况" # 指定输出模式 python3 scripts/chatbi_cli.py -q "各品类月度销售趋势" --output detail # 仅输出 SQL python3 scripts/chatbi_cli.py -q "查询销量 Top10 的商品" --output sql-only ``` --- ## 输出模式 - **summary**（默认）：意图理解 + 选表结果 + SQL + 最终回答 - **detail**：完整的 Agent 执行过程 - **sql-only**：仅输出生成的 SQL - **raw**：输出被过滤命中的事件 JSON 及未匹配事件标注（调试用） --- ## ⚠️ 调用规范（必读） > **必须使用 `yieldMs=200` 参数**，否则无法实现流式输出！ 本 Skill 的 CLI 脚本执行耗时约 30-50 秒（Agent 意图理解 → 选表 → SQL 生成执行 → 回答）。 CLI 内部每个阶段完成后会立即 `flush` 输出，配合 `yieldMs=200` 可实现渐进式展示。 ### 正确调用方式 ``` exec(command="python3 scripts/chatbi_cli.py -q '查询乳制品的销售情况' --output summary", yieldMs=200) ``` ### 错误调用方式 ``` # ❌ 缺少 yieldMs，会等进程跑完才一次性返回所有结果 exec(command="python3 scripts/chatbi_cli.py -q '查询乳制品的销售情况'") ``` ### 参数说明 | 参数 | 值 | 说明 | |------|-----|------| | `yieldMs` | `200` | 每 200ms 把已产生的 stdout 分批推送给用户，实现渐进式展示 | | `--output` | `summary` | 默认模式，只输出关键信息（意图/选表/SQL/回答） | | `--output` | `detail` | 额外输出执行计划和数据预览详情 | | `--output` | `sql-only` | 仅输出 SQL，适合管道使用 | --- ## 项目结构 ``` ├── SKILL.md # 本文档 ├── scripts/ │ ├── chatbi_cli.py # CLI 入口 │ ├── requirements.txt # 依赖 │ └── chatbi/ # 核心模块 │ ├── __init__.py │ ├── config.py # 配置管理 │ ├── client.py # 流式 API 客户端 │ ├── parser.py # 流式事件解析与过滤 │ ├── formatter.py # 输出格式化 │ └── models.py # 数据模型 └── references/ └── COMMANDS.md # 命令参考 ```