chatbi-skil-test

通过命令行调用 ChatBI 问数 Agent 流式接口，对企业数据表进行自然语言驱动的数据查询分析。 本工具支持：发起自然语言问数、实时跟踪 Agent 执行流程、提取意图理解/选表结果/SQL/最终回答。 当用户需要查询数据库、分析数据、用自然语言问数，或提到"ChatBI"、"问数"、"数据查询"、"SQL分析"时使用本 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 的内容

---

安装

pip install -r scripts/requirements.txt

---

快速开始

# 基本问数
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       # 命令参考