asktable-advisor 1.5.0
Conversational AI Agent for building AskTable demo scenarios
License: MIT
Requires Python: >=3.10
Keywords: asktable, ai-agent, conversational-ai, data-analysis, database, llm, tool-use

# AskTable Advisor - AI场景构建助手

**AskTable Advisor** 是一个对话式 AI Agent，专门帮助用户快速创建和管理高质量的 AskTable 演示项目。

## 🎯 核心特点

### 💬 对话式交互
- 自然语言沟通，无需记忆复杂命令
- Agent 主动询问细节，引导场景构建
- 多轮对话，循序渐进完成任务

### 🤖 AI 驱动
- 使用阿里云百炼 qwen3-max 模型
- 自动设计数据库结构
- 生成真实感的业务数据
- 智能配置 AskTable 资源

### ⚡ 一站式构建
只需一句话："创建一个电商平台的演示场景"，Agent 自动完成：
1. 📊 设计数据库表结构
2. 💾 生成虚拟业务数据
3. 🗄️ 创建数据库和导入数据
4. 🔗 创建 AskTable Datasource
5. 🤖 配置智能 Bot（包含业务知识和示例问题）
6. 💬 创建演示 Chat
7. 🔐 配置权限管理（可选）

## 快速开始

### 1. 安装

#### 方式 1：使用 uv（推荐）

```bash
cd asktable-advisor

# 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 一键设置（创建虚拟环境 + 安装依赖）
./scripts/setup.sh

# 或手动设置
uv venv
source .venv/bin/activate  # Linux/Mac
uv pip install -e .
```

#### 方式 2：使用 pip

```bash
cd asktable-advisor
pip install -e .
```

### 2. 配置

复制 `.env.example` 到 `.env` 并填入配置：

```bash
# AskTable API
ASKTABLE_API_KEY=your_api_key_here
ASKTABLE_API_BASE=https://api.asktable.com

# LLM API（阿里云百炼）
ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
ANTHROPIC_API_KEY=your_dashscope_api_key_here

# MySQL 数据库
MYSQL_HOST=mysql8.test.dminfra.cn
MYSQL_PORT=3006
MYSQL_USER=at_admin
MYSQL_PASSWORD=2546b7c367e4be0045369fdF
MYSQL_DATABASE=asktable_advisor
```

### 3. 启动对话

```bash
python -m asktable_advisor
```

## 使用示例

### 示例 1：创建新场景

```
你: 创建一个在线教育平台的演示场景

Advisor: 好的！让我帮你创建在线教育平台场景。

为了生成更贴合需求的方案，请告诉我：
1. 平台规模：小型（< 1000学生）/ 中型（1-5万）/ 大型（> 5万）
2. 核心业务：需要包含哪些模块？
   - 课程管理 ✓（默认包含）
   - 学生管理 ✓（默认包含）
   - 在线支付？
   - 作业/考试系统？

你: 中型，包含支付和作业系统

Advisor: 收到！开始创建...

📊 [1/6] 设计数据库结构
✓ 设计完成：8 张表
  - students, courses, enrollments, lessons
  - assignments, submissions, payments, instructors

💾 [2/6] 生成虚拟数据
✓ 生成 20,000 名学生
✓ 生成 150 门课程
✓ 生成 45,000 条选课记录
...

🎉 场景创建完成！
```

### 示例 2：查看现有场景

```
你: 看看我现在有哪些场景

Advisor: 正在检查你的 AskTable 项目...

发现 2 个场景：

📚 1. 在线教育平台
   └─ Datasource: edu_platform (8 张表, 128,000 行数据)
   └─ Bot: 教育数据分析师 (20 个示例问题)
   └─ Chats: 1 个演示对话

🛒 2. 电商数据分析
   └─ Datasource: ecommerce_db (7 张表, 61,000 行数据)
   └─ Bot: 电商分析师 (15 个示例问题)
   └─ Chats: 2 个对话
```

### 示例 3：增强场景

```
你: 给教育平台的 Bot 增加一些权限相关的示例

Advisor: 好主意！为"教育数据分析师"Bot 添加权限示例。

我将创建 3 个角色：
• 平台管理员（全部数据）
• 教师（只能看自己的课程）
• 学生（只能看自己的学习数据）

开始配置...

✓ 完成！已添加：
  • 3 个 Role 配置
  • 8 条 Policy 规则
  • 12 个权限相关示例问题
```

## 项目结构

```
asktable_advisor/              # 新架构
├── __init__.py
├── __main__.py               # CLI 入口
├── config.py                 # 配置管理
│
├── agent/                    # AI Agent 核心
│   ├── advisor.py            # 主 Agent（对话 + 工具执行）
│   ├── llm_client.py         # LLM 客户端（qwen3-max）
│   ├── tools.py              # Agent 工具定义
│   └── prompts.py            # System prompts
│
├── asktable/                 # AskTable API 封装
│   ├── client.py             # AskTable 客户端
│   ├── inspector.py          # 项目检查器
│   └── resources/            # 资源管理模块
│
├── database/                 # 数据库管理
│   ├── manager.py            # 数据库连接管理
│   ├── schema_generator.py   # LLM 生成 Schema
│   └── data_generator.py     # LLM 生成数据
│
└── utils/                    # 工具函数
    └── console.py            # Rich console
```

## Agent 工具

Advisor 可以使用以下工具：

- **inspect_asktable_project** - 检查项目现有资源
- **design_database_schema** - AI 设计数据库结构
- **generate_sample_data** - AI 生成真实感数据
- **execute_sql** - 执行 SQL 语句
- **create_asktable_datasource** - 创建数据源
- **create_asktable_bot** - 创建智能 Bot
- **create_asktable_chat** - 创建演示对话
- **enhance_bot** - 增强现有 Bot
- **create_permissions** - 配置权限（占位）

## 技术栈

- **LLM**: 阿里云百炼 qwen3-max（通过 Anthropic 兼容接口）
- **AskTable SDK**: Python SDK for AskTable API
- **Database**: MySQL with SQLAlchemy
- **CLI**: Rich library for beautiful terminal output
- **Configuration**: Pydantic Settings

## 开发

### 代码格式化

```bash
black asktable_advisor/
ruff check --fix asktable_advisor/
```

### 运行测试

```bash
pytest
```

## License

见 LICENSE 文件