技能名称: chatbi-agent-skill
详细描述:
metadata:
author: ChatBI Skills
version: 1.0.0

---

ChatBI 问数 Agent Skill

概述

scripts/chatbi_cli.py 帮助用户完成 自然语言问数 → 意图理解 → 智能选表 → SQL 生成执行 → 获取结果 的完整流程。

核心能力

本 Skill 调用 ChatBI Agent 流式接口，从丰富的 Agent 输出中只提取关键信息：

1. 1. 意图理解：intenttool → understandingthinking（Agent 对用户问题的理解）
2. 选表结果：tableselecttool → tablename + tableselectedreason（选择了哪些表及原因）
3. SQL 执行：sqlexecuted（生成的 SQL）、executionplan（执行计划）、datapreviewinfo（数据预览）
4. 最终回答：isfinal_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 # 命令参考