BaskReport AI 报表生成 · 傻瓜式快速上手

本文档教你在 10 分钟内，用「一句大白话」让 AI 帮你生成并部署一张 BaskReport 报表， 不需要懂报表 XML，也不需要懂 BaskReport 设计器。

1. 这是什么

baskreport-ai-report-generator（npm 包）是一套 AI 报表生成器。

核心思路（不需要你理解，了解即可）：

你的一句话需求
   ↓  AI 理解
精简 JSON（Report IR，报表中间层）
   ↓  AI 编译（确定性转换器）
BaskReport 报表 XML
   ↓  AI 部署
BaskServer 服务端（可直接在网页预览）

你的任务只有两件事：

  1. 用大白话告诉 AI 你要什么报表；
  2. 提供服务端连接凭证（一次性配置）。

2. 一次性准备（约 5 分钟）

⚠️ 版本要求：BaskServer 版本需 2.3.3+（AI 生成/部署依赖该版本新增的接口，更低版本会报错）。

2.1 安装

需要 Node.js 18+（没有就先装：https://nodejs.org）。

# 全局安装（推荐，安装完自动挂载到 CodeBuddy / WorkBuddy）
npm install -g baskreport-ai-report-generator

# 想在 Cursor / Claude Code 里也用，在你自己的项目目录执行：
baskreport install --clients claude,cursor

如果是从 skill 仓库（本地目录）使用，首次先构建一次：

cd <skill目录>          # 例如 D:\products\basksoft-ai
npm install
npm run build

2.2 配置服务端凭证

在你执行命令的项目根目录新建一个 .env 文件（复制 .env.example 也可以），填入：

BASK_BASE_URL=http://localhost:8080/baskserver   # 你的 BaskServer 地址
BASK_TENANT_ID=1                                # 租户 ID，必填

# 二选一：账号密码登录（推荐）
BASK_USERNAME=admin
BASK_PASSWORD=123456

# 或二选一：OAuth2 Token 登录（与上面互斥，不要同时填）
# BASK_ACCESS_TOKEN=xxxx

⚠️ 凭证不要提交到 git 仓库，.env 已被 gitignore 忽略。

2.2.1 使用账号密码登录前，先关闭登录验证码（重要）

如果你的 BaskServer 启用了登录页验证码（默认开启），AI 命令行用账号密码登录时会因为无法自动识别验证码而登录失败。

请在数据库的 BASK_PROPERTY 表中检查 key 为 bask.application.login.usecaptcha 的记录：

参数编号 key 默认值 说明 分类
106 bask.application.login.usecaptcha true 是否启用登录页面的验证码 system

将该记录的 VALUE_ 改为`false 即可关闭验证码；如果没有该记录，则插入一条：

INSERT INTO bask_property (KEY_, VALUE_, REMARK_, CATEGORY_)
VALUES ('bask.application.login.usecaptcha', 'false', '是否启用登录页面的验证码', 'system');

💡 如果不想关闭全局验证码，请改用 OAuth2 Token 方式登录（.env 里配置 BASK_ACCESS_TOKEN），无需处理验证码。

2.3 检查是否装好

baskreport --help

能看到命令列表即成功。

3. 三句话用起来（核心流程）

对 AI（CodeBuddy / WorkBuddy / Cursor / Claude Code）说：

生成报表：<你的需求一句话>

AI 会自动执行以下流程（你基本不需要手动敲命令）：

  1. 探查数据源：列出可用的数据源/表，让你确认选哪个；
  2. 写 IR：生成精简 JSON 中间层；
  3. 校验编译：语法校验 + 编译成 XML；
  4. 部署：generate --deploy --tenantId <t> 保存到服务端；
  5. 发布（可选）：加 --publish 让报表上线可预览。

如果之后要修改已部署的报表，直接说：

修改报表 报表名/ID：<改动需求>

AI 会先拉取原报表、转成 IR、按你的要求改、再覆盖回去（自动留底可回滚）。

4. 常用命令速查（进阶可选）

目的 命令
本地编译，导出 XML baskreport generate --in report.json --out report.xml
部署到服务端（新建） baskreport generate --in report.json --deploy --tenantId 1
部署并发布（可预览） baskreport generate --in report.json --deploy --tenantId 1 --publish
覆盖更新已有报表 baskreport generate --in report.json --deploy --id <报表id> --tenantId 1
只导出 XML，不连服务器 baskreport generate --in report.json --out report.xml --no-verify-sql
列出数据源 BASK_NONINTERACTIVE=1 baskreport datasource load-all-datasource-defs --list --tenantId 1
查看表结构 baskreport datasource schema-ctx --datasource-id <数据源id> --tables <表1,表2> --tenantId 1
拉取已有报表做备份 baskreport report get --id <报表id> --tenantId 1 > backup.xml
用 XML 直接改已有报表 baskreport report patch --id <报表id> --xml backup.xml

5. 简单输入范例（直接复制改一改就能用）

以下范例来自 basksoft-ai\reports\ 官方示例，都是「给 AI 的自然语言输入」。

范例 1：最简单的明细报表（入门）

新建一个员工明细报表

  • 报表标题：员工明细报表
  • 筛选条件：可对姓名、性别、学历进行筛选
  • 样式：薪水大于 20000 的行，字体红色显示
  • 水印：报表水印 BaskSoft

对应生成一个带查询条件、条件着色、水印的员工明细表。

范例 2：主从明细报表

新建一个主从明细报表

  • 报表标题：租户信息
  • 主从结构：主表是租户，从表是用户
  • 统计信息：租户数量、用户数量、用户数量（按租户）

对应生成一张「租户 → 用户」的主从报表，并带统计。

范例 3：交叉表（行列统计）

用订单表做一个交叉表

  • 报表标题：订单交叉表
  • 纵向分类：区域、省份
  • 横向分类：产品类型
  • 表头：需要斜线表头
  • 值字段：订单金额 sale（求和）、订单数量 amount（求和），值字段需要有标题
  • 汇总：最下方实现汇总，订单金额求和、订单数量求和

范例 4：同比 / 环比趋势报表

海关进出口同比增长趋势

  • 核心指标：进口额、出口额、同比增长率（进口/出口）
  • 时间维度：按年、月
  • 展示逻辑：数据按「年 → 月」横向展开，上半部分表格展示实际进出口金额，下半部分表格展示同比增速

（把「同比」改成「环比」就是环比报表。）

范例 5：在一张报表上叠加高级需求（迭代式）

先给一个基础需求：

生成租户的用户列表明细报表

再逐步叠加：

  1. 为这个报表添加「角色」和「用户账号」查询条件
  2. 明细行实现奇偶行显色（隔行变色）
  3. 角色是 Manager 的，字体红色粗体显示
  4. 表格下面添加根据角色类型统计人数的功能
  5. 人员合计单元格合并当前行后面的所有单元格（水平合并）
  6. 角色人员合计表格和合计单元格也实现水平合并

AI 会依次把参数查询、条件渲染、分组统计、单元格合并全部加上。

范例 6：Excel 模板 + 参考报表

上传 Excel 模板作版式，再指定 BaskServer 上已有报表作数据绑定参考——AI 自动引入参考报表的字段与 SQL，无需重新探查数据库：

我上传了采购明细模板.xlsx，参照 BaskServer 上的报表 10086 做数据绑定参考，生成报表

  • 版式：完全按上传的 Excel 模板
  • 数据：复用报表 10086 已使用的数据集与字段（供应商、采购日期、采购数量、采购金额）
  • 样式：金额列黄色底纹

💡 输入小技巧：需求越具体越好——说清「报表标题」「主表/从表」「要哪些字段/统计」「特殊样式」，生成质量越高。

6. 常见问题 FAQ

Q1：提示找不到 baskreport 命令？ 确认全局安装成功，或改用 npx baskreport-ai-report-generator <子命令>。

Q2：部署时报登录失败？ 检查 .env 里的 BASK_BASE_URL、BASK_TENANT_ID、账号密码是否正确；OAuth2 Token 方式与账号密码方式二选一，不要同时填。 若报「验证码错误/需要验证码」，说明服务端开启了登录验证码：将数据库 BASK_PROPERTY 表中 bask.application.login.usecaptcha（参数编号 106）的 VALUE_ 改为 false 关闭验证码，或改用 OAuth2 Token 登录（见 2.2.1）。

Q3：AI 说找不到数据源 / 表？ 先让 AI 列出数据源候选（load-all-datasource-defs --list），你从中明确选中一个，再让 AI 用 schema-ctx 查看表结构，不要凭猜的。

Q4：修改报表后内容丢失？ 让 AI 走「IR 闭环」流程：先 report get 留底 → 转 IR → 修改 → generate --deploy --id 覆盖回。带 --id 才会覆盖而不是新建。不要绕开 IR 直接改 XML（除非是仪表盘/图表类报表，那种用 report patch）。

Q5：部署了但网页上预览不到？ 部署时记得加 --publish（只 --deploy 是保存不发布）。修改已有报表时同理。

Q6：报表里有 SQL，怎么确认字段写对了？ generate 会自动用真实 schema 比对（--strict-type 可把类型不一致升级为报错），报错时会给出「你是不是想写 xxx」的修正建议。

7. 参考链接

  • npm 包：https://www.npmjs.com/package/baskreport-ai-report-generator
  • 官方输入范例目录：basksoft-ai\reports\（helloworld.md、master-detail.md、crosstab.md、YoY.md、QoQ.md 等）
  • IR 示例 JSON：skill 目录 src/examples/（detail-table.json、group.json、crosstab.json、master-detail.json、param-query.json 等）

results matching ""

    No results matching ""