datapilot

# DataAgent OpenAPI Assistant

## 何时使用

当用户要求任何"问数 / 查数 / 数据分析 / 报表"相关能力时使用本技能，包括但不限于：

- 基于数据源创建通用数据分析 Agent（面向任意业务域，不限行业）
- 自然语言问数、SQL 校验、图表展示、报告导出与下载
- 列出和检索当前全部 Agent（含描述）
- 维护 Agent 知识库（参考 SQL、业务知识、分析模板）

## 能力总览

| 能力 | CLI 命令 | 说明 |
|------|----------|------|
| 创建 DataAgent 实例 | `create-instance` | 一步完成 agent 创建，接入数据源 |
| 自然语言问数 | `ask` | SSE 对话，返回 SQL / 表格 / 图表 / 报告下载链接 |
| 列出全部 Agent | `list-agents` | 跨 namespace 汇总所有 agent 信息 |
| 查看知识库 | `knowledge-list` | 列出指定 agent 的知识条目（可按类型过滤） |
| 新增/更新知识 | `knowledge-upsert` | 新增或覆盖一条知识（reference_sql / business_knowledge / analysis_template） |
| 查看知识条目 | `knowledge-get` | 获取单条知识详情 |
| 删除知识条目 | `knowledge-delete` | 删除一条知识 |

## 核心流程

```
用户需求
  │
  ├─ 首次使用 ──► create-instance（接入数据源，创建 Agent）
  │                    │
  │                    ▼
  │              返回 namespaceId + agentId
  │
  ├─ 问数分析 ──► ask（传入 agentId + 自然语言问题）
  │                    │
  │                    ▼
  │              SSE 流式返回：SQL / 表格 / 图表 / 报告下载链接
  │
  ├─ 查看 Agent ► list-agents（列出所有可用 Agent）
  │
  └─ 知识管理 ──► knowledge-list / knowledge-upsert / knowledge-get / knowledge-delete
```

## 配置与鉴权

- **API 基础前缀**：`/api`
- **响应格式**：`{ code, message, data }`，`code === 0` 视为成功
- **鉴权**：Header `Authorization: Bearer <token>`
- **语言**：Header `X-Lang: zh`

## 调用方式

所有能力通过 Node 脚本 `dataagent_openapi_cli.mjs` 调用。

```bash
node dataagent_openapi_cli.mjs <command> [options]
```

### 通用参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--base-url` | API 服务地址 | 环境变量 `DATAPILOT_API_URL` |
| `--token` 或 `--apiKey` | 鉴权令牌 | 环境变量 `DATAPILOT_API_KEY` |


## 命令详解

### 1. create-instance — 创建...