积木报表 AI 生成器
不涉及「Online 报表」（cgreport）或「Online 表单」（cgform）。
临时配置文件规则（强制）
所有传给脚本的 --config <xxx.json> 必须写到 {系统临时目录}/{SKILL_NAME}/ 下，由操作系统自动清理；skill 与脚本均不主动删除该目录或文件。
import tempfile, os, json
SKILL_NAME = "<SKILL_NAME>" # 请替换为实际的技能名称
skill_dir = os.path.join(tempfile.gettempdir(), SKILL_NAME)
os.makedirs(skill_dir, exist_ok=True) # 确保目录存在，不主动检查
config_path = os.path.join(skill_dir, 'sk_audit_create.json') # 示例文件名
with open(config_path, 'w', encoding='utf-8') as f:
json.dump(cfg, f, ensure_ascii=False, indent=2)
tempfile.gettempdir() 自动适配：Windows %TEMP%、Linux /tmp、macOS /var/folders/.../T（注意 macOS 并非 /tmp）。
文件名建议使用 <表名>_<步骤>.json（如 sk_audit_create.json），无需重复技能前缀，因路径已包含技能名称，便于排错。
❌ 禁止：
- 写到
<skill>/tmp/或当前工作目录（污染 skill / 用户项目） - 硬编码
/tmp、C:\Temp或任何固定路径（不跨平台） - 每步完成后主动
rm/Remove-Item（操作系统会清理，属多余 tool call） - 主动
os.path.exists()检查（其本身即为一次 tool call）
（使用os.makedirs(…, exist_ok=True)满足需求，不算主动检查）
临时文件可能被操作系统异步清理，但仍遵循 乐观调用 + 报错补救：仅当脚本返回 FileNotFoundError 或 配置文件不存在 时，使用相同内容、在相同的 {系统临时目录}/{SKILL名称}/ 路径下重写（重写前仍需 os.makedirs(skill_dir, exist_ok=True) 确保目录存在），切勿更换路径或回退至 skill 目录。
一键脚本（必看，覆盖三类全场景）
写自定义 JSON / Python 之前，先看用户需求是否命中下表现成脚本，命中则直接调用，禁止重新组装 JSON 或 Python：
| 用户描述（关键词） | 直接调用 | 默认覆盖 |
|---|---|---|
| 「全图表」「所有图表」「图表大全」「测试所有数据集类型」「SQL+API+JSON」「图表展示」 | python scripts/generate_all_reports.py --base-url ... --token ... --name "..." --mysql-host ... --mysql-port ... --mysql-db ... --mysql-user ... --mysql-pwd ... | 25 个图表（SQL 12 + API 2 + JSON 4 + 不绑 7），自动建 chart_demo_all 表插数据 + 自动创建 YApi mock + 一次保存 |
命中规则与禁止事项
- 关键词命中即用：用户说「生成全部图表」「全图表测试」「演示所有图表」「测试 SQL/API/JSON 三种数据集」时，第一反应就是
generate_all_reports.py，不要回头自己写 chart_entry/echarts 模板 - 3 秒能跑完：实测 ~3.1s 端到端创建。脚本启动后不要分块等待、不要发 AskUser 求确认，直接
Bash等结果 - Mock 新建必须用唯一路径：
create_mock遇到同路径会静默覆盖已有接口数据，污染他人接口。创建新接口时必须在路径末尾追加时间戳或序号（如/sales_20260427），只有用户明确说"修改/更新已有接口"时才可复用原路径 - saveDb 串行：脚本已改为串行调用
save_db，避免jimu_report_db_fieldINSERT 并发引发 MySQL deadlock - 新增图表类型时：在
CHARTS列表加一行，写一个tpl_xxx函数即可，无需重写主流程
执行流程
第零步（必须）：Token 优先
用户消息里没有 X-Access-Token 时，立刻询问，拿到 token 后再读任何文件。等待回复期间不要预读文件——等待时间不计入 3 分钟，文件读取时间计入。
⚠️ 凭证禁止读记忆，直接问用户：需要数据库密码、账号密码等任何凭证时，禁止读取 memory 文件获取，必须直接在对话中问用户。
第一步（必须）：按「执行速度规范」表选最小文件集
不要先 Glob examples/，直接查下方「执行速度规范」表，按场景只读指定文件。禁止在表外额外读文件。 场景匹配优先于文件名匹配：
multi-level-header.md主要是交叉表 groupRight/dynamic，纵向分组+静态多级表头不要读它（浪费 ~30s 读不适用示例）。
读完指定文件后直接 Write JSON 配置 → 执行 CLI 命令 → 输出预览链接。两步完成，禁止多余动作。
报表链接格式（创建成功后直接输出，禁止调接口验证是否存在）：
- 设计器：
http://{host}/jmreport/index/{report_id}?token={token}&tenantId=1- 预览：
http://{host}/jmreport/view/{report_id}?token={token}&tenantId=1
报表名称规则：用户明确指定名称时直接使用；未指定时 AI 自动生成名称，生成后须调
GET /jmreport/query/report/folder?pageNo=1&pageSize=10&reportType=&name={name}&token={token}检查是否重复，有同名则追加后缀（如_2、_20260415）。
utils 子模块速查（需确认某函数签名时，Grep 对应小文件，禁止读全量 jimureport_utils.py）：
| 需要确认的函数 | 读哪个文件 |
|---|---|
| Session、gen_id/code/layer、col_letter、_compute_sign | jimureport_core.py |
| parse_api、parse_sql、save_db、update_db、parse_and_save_dataset、parallel_parse/save/api | jimureport_dataset.py |
| make_designer、base_save、get_report、report_urls、print_summary | jimureport_report.py |
| make_styles、STYLE_BASE/DATA/HEADER/TITLE/LINK（命名常量，禁止用魔法数字） | jimureport_styles.py |
| chart_entry、virtual_row、build_chart_layout、update_chart_config、parallel_fill_charts、pick_chart_axes | jimureport_chart.py |
| create_link、parallel_create_links | jimureport_link.py |
| ensure_datasource、find_datasource、get_ds_connection、query_mysql、execute_ds | jimureport_datasource.py |
| 禁止 | 替代 |
|---|---|
| 读全量 jimureport_utils.py | 按上表 Grep/Read 对应子模块（各 25-175 行） |
Grep/Read jimureport_gen.py（任何原因） | api_dataset/group/standard 等函数的签名和参数在 SKILL.md 调用示例中已完整给出（base_url 默认 http://192.168.1.6:8085/jmreport，无需传），"不确定参数"不构成读源码的理由，直接信任文档 |
Grep/Read jimureport_creator.py 确认是否支持某功能（如 fieldList searchMode、paramList 等） | SKILL.md 的 JSON 配置模板和禁止表已覆盖所有场景，直接写 JSON 配置执行，禁止读源码验证 |
Grep/Read jimureport_dataset.py 查看 parse_sql 实现 | parse_sql 接受含 FreeMarker 条件的 SQL，服务端以空参评估后解析字段列表，直接调用即可，无需看源码 |
| 找 DB 凭证 | 用 memory 中的配置或问用户 |
| Windows 下 Bash tool 跑 python | 改用 PowerShell tool 跑 python xxx.py / python -c "..."，同步返回（详见下方「Windows 执行环境」） |
| 调外部 API 验证字段 | 直接按用户提供的字段写脚本，不预调 API |
擅自调用 create_mock() 或 init_yapi() | ⛔ 用户已提供接口 URL 时，直接 save_db(api_url=URL)，严禁调用 create_mock() / init_yapi() / 任何 YApi 登录或验证操作；只有用户明确说"帮我创建 mock 接口"或完全未提供 URL 时才调用；URL 已知 = 直接用，不验证、不询问、不登录 |
sleep + cat 轮询输出 | Bash 命令在 Windows 始终被后台化；若仍要走 Bash，必须用 TaskOutput(task_id, block=true) 等待结果，禁止用 sleep/cat 轮询 |
| 报表创建后调接口验证是否存在 | /save 返回 success:true 即成功，直接输出设计/预览链接，无需查报表列表 |
手写 border 样式（{"style":1} 或任何非数组格式） | 必须用 make_styles() 获取 styles 列表，它已内置正确的 ["thin","#d8d8d8"] 数组格式；手写 border 一律禁止，会导致整表渲染空白 |
customRows 配合空 columns: [] | creator 靠 columns 生成 queryInfo.dbf；columns 为空则不写入绑定元数据，报表预览完全无数据（即使数据集 records=N）。customRows 只控制视觉布局，columns 必须填数据集的实际字段（至少一个） |
用户未指定的可选参数自行填值（如 customEditConf.eventParams、freeze、rpbar、background 等） | 只写用户明确给出的字段，其余可选参数一律省略，不得自造默认值 |
调 report_urls() 工具函数当作 dict 用（如 urls['designer']） | report_urls(report_id, base_url, token, tenant) 返回 tuple (preview_url, design_url)，不是 dict；且第一个参数是 report_id 不是 base_url。直接按本节"报表链接格式"拼字符串，不要调用此函数 |
| 报表创建走自定义 .py 脚本 | ⛔ 必须用 JSON 配置文件 + jimureport_creator.py CLI：只写 xxx.json → python jimureport_creator.py --api-base URL --token TOKEN --config xxx.json。需要同时创建 YApi mock 的 API 数据集报表，用 jimureport_gen.api_dataset(..., mock_data=[...], mock_path="/xxx_日期") 一步完成，内部自动生成 JSON 并调 CLI，无需手写 Python 脚本。用户反馈（2026-05-22 再次确认）："以后只生成JSON"。⚠️ 典型错误场景1：用户要求自定义样式，AI 认为高级函数不支持样式就手写 rows/cols/styles/save_db/base_save——严重违规。⚠️ 典型错误场景2：场景复杂（含钻取+图表+建表），AI 直接写 drill_demo.py 等全流程 Python 脚本——严重违规。正确做法：报表结构部分始终写 JSON；建表/链接创建等 JSON 不支持的步骤写成最小独立 PowerShell inline；两部分分开，不混写。 |
PowerShell Out-File -Encoding utf8 写 JSON | 产生 UTF-8 BOM 导致 json.load 报 Unexpected UTF-8 BOM。必须用：[System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding $false)) |
Windows 执行环境（强制规则，违反会让用户吐槽"执行太慢"）
现象：Windows 的 Bash tool 会把 python / python -c / skill 脚本当作长命令自动 run_in_background，tool 立即返回 background ID，真正输出要等完成通知——把毫秒级调用放大到数秒，历史上多次让单报表从 1 分钟拖到 18 分钟。
规则：
- Windows（platform=win32） → 用 PowerShell tool 直接执行
python xxx.py，同步返回。禁止用 Bash tool 跑 python（会被后台化）。 - Linux / macOS → 用 Bash tool 直接调用
python xxx.py。 - 任何平台都不用
curl：跨平台不一致，Windows Bash 下同样被后台化。
脚本执行前强制检查（2 项）：
- ✅ Windows 下用 PowerShell tool 执行
python xxx.py，不是 Bash tool - ✅ 脚本第一行已加编码声明：
import sys; sys.stdout.reconfigure(encoding='utf-8')（防 GBK 崩溃重试）
Windows 正确示例：
PowerShell: python <skill_base_dir>/scripts/xxx.py --base-url ... --token ...
<skill_base_dir>是本 SKILL.md 所在目录，运行时用实际路径替换，禁止写死C:/Users/...。
Windows 错误示例：
Bash: python generate_all_reports.py ... ← 返回 "Command running in background with ID: xxx"
Bash: curl -X POST ... ← 同上
历史教训：曾因默认走 Bash + python 被用户连续吐槽"执行太慢了 / 生成这么慢"。根因是 Bash tool 在 Windows 对 python 会后台化，不限于 curl。另一常见重试原因：脚本缺编码声明导致
UnicodeEncodeError: 'gbk' codec，加第2项检查可消除。 典型症状：报表生成完成后仍等待约 2 分钟才结束——这是 Bash 后台化的直接表现：脚本已跑完但 tool 在等 background 完成通知。遇到此现象立即确认是否误用了 Bash tool，改 PowerShell 即可消除。
前置条件
用户须提供 X-Access-Token。
SQL 数据集数据源选取（用户未指定 dbSource 时必须执行）
正确流程（必须每次执行，不可跳过）：
- 调
GET /jmreport/initDataSource获取数据源列表 - 按用户提供的数据库名（如
jeecg-boot-cr）精确匹配name字段，取其id - 找不到再询问用户
⚠️ 禁止用 memory 中存的数据源ID直接跳过查询：memory 里的ID可能已过期或被重建，必须每次查询后按名字匹配拿到当前有效ID。memory 只用于记住数据库名，不用于记住ID。 ⚠️ 禁止全量拉取后遍历猜测：有明确数据库名时直接按名字匹配