Imported from jeecgboot/skills (jimubi-bigscreen/SKILL.md). Install upstream with npx skills add jeecgboot/skills --skill jimubi-bigscreen. Copyright stays with the author.

JeecgBoot 大屏 AI 自动生成器

本 skill 处理大屏（bigScreen）。仪表盘（看板）请用 jimubi-dashboard skill。

⚠️ 核心强制规则（9条）

1. 所有大屏操作必须通过本 skill（禁止未调用 skill 直接读 memory 凭据自行执行）
2. 入口即分叉：按场景决策树选路径，禁止默认走 spec_builder。spec_builder 仅用于"整屏生成（含组件）"场景。禁止逐组件拼 Python 脚本
3. 🚨 删除/重写/清空前必须询问用户确认（除非用户明确说"删除/去掉/移除/清空/清除"）
4. 🚨 编写 SQL 前必须 SHOW TABLES 确认表名（onl_drag_page ≠ jimu_drag_page）
5. dataMapping.filed 拼写：少一个 d（不是 field）
6. Windows：用 py 不是 python；所有脚本加 PYTHONIOENCODING=utf-8
7. 🚨 用户未指定数据来源时必须先问（纯静态布局/纯装饰除外）。可选项：静态 mock / YApi 接口 / SQL 数据集 / Excel-CSV 文件 / 存储过程 / 自写 Java API / BI 直连 Online 表/设计器表单/Online 报表（dataType=4）。⚠️ 用户说"用某 Online 表 / cgform / jeecg 表 / Online 报表 / desform 作为数据源"时优先 BI 模式而非 SQL 数据集（详见 references/bi-mode-online.md）。禁止默认编造静态数据
8. 真相源优先级（写组件配置 / 数据集绑定都遵循）：
   • 数据集绑定字段映射 → references/data-binding-mapping.md（唯一真相源，描述冲突以此为准；按 §0 检测算法对照 defaults/<CompType>.json 判定 A/B/无映射 三型，别猜）
   • 组件 option 字段名（passthrough 自定义组件 JScrollList / JScrollBoard / JScrollTable / JText / JCurrentTime / JStatsSummary / JDragDecoration / JDragBorder / JFlashList / JRectangle / JLiquid / JSemiGauge / JCustomProgress / JListProgress 等，非穷举），按以下四级顺序查，找到即止：
     • ① references/scripts/defaults/<CompType>.json（初始加载真相源，--schema <CompType> --full 调取）
     • ② references/<comp>-option-config.md（组件专项文档）
     • ③ references/bi-comp-option-config.md（兜底）
     • ④ 以上三级仍找不到 → 说明该字段是 UI 运行时动态写入的（不在 defaults 里）。正确做法：在页面上手动操作一次该属性，再 query_page 观察实际写入了哪些字段，以观察结果为准。典型案例：JRing 的环形尺寸，defaults 只有 series[0].radius（百分比），但 UI 实际写的是 option.outRadius / option.innerRadius（像素整数），不查 ④ 直接写百分比字段会被 Vue 渲染器忽略（实测 2026-04-28）
   • 错字段不报错只会被默认值覆盖（看似"有效"实则无效）。禁止按 Vue/React/Bootstrap 习惯拍脑袋写 bgColor/fontColor/borderColor——实际可能是 backgroundColor/alternateBackgroundColor/BGC 等平台自定义名
   • ECharts 标准字段（series[*].itemStyle.color / xAxis.axisLabel.color 等）可凭记忆写，不受此规则限制
9. 配色禁止 AI 自编色值——用户说"复古/商务/科技/红涨绿跌"等命名色板，必走 style_ops.py set-palette --name <名称>（或 spec 顶层 palette）。查色值用 style_ops.py list-palettes，不调 API 不耗 token
10. 🚨 用户已指定风格/配色/背景时，立即执行，禁止内部反复推翻——用户说"浅色/深色/科技感/复古风/XX 风格"，选一个合理实现方案后直接执行，不得多轮权衡"技术上是否可行"。平台默认深色主题不是拒绝浅色的理由，遇到技术限制先执行再调整。post-creation 颜色调整必须合并批量：style_ops.py 多个子命令尽量串联为 1-2 次调用（set-axis-color + set-title-color + set-grid-color 可各自独立，但禁止因犹豫在 spec 生成后串行执行 6+ 次单独 HTTP 操作）

⚡ 写/改任何组件 option 字段前——强制预检（不可跳过）

在编写任何组件 config 脚本、comp_ops.py edit --set、或手写 Python patch 之前，必须先确认字段名，不允许凭 ECharts 文档或经验直接写。按以下优先级判断：

找到即止，立即执行，禁止从多个来源重复确认同一字段。任一来源确认字段名后直接跑命令，不再查第二个来源。comp_ops.py edit 的 true/false/数字 自动类型转换是固定行为，无需每次验证源码。

错字段不报错不报 warning，只会被默认值静默覆盖（典型案例：option.legend.top 无效，正确字段是 option.legend.t；option.outRadius/innerRadius 与 series[0].radius 同理）。

大屏平台默认值

• 分辨率 1920×1080（后端默认，spec_builder 不写）| style bigScreen | designType 100
• 主题 dark（spec_builder L797）| 背景 /img/bg/bg4.png 深空星空（spec_builder L798）| 图层 bg/border 透明 #FFFFFF00
• bg4 色板（spec_builder 内置）：主标题 #f0c040，副标题 #00d4ff，数值 #d4e8ff，轴 #8ab8d0，分割线 #1a3a5a55
• A股红涨绿跌：#ff4d4f / #52c41a

入口判断（先做这一步）

1. 新建 vs 已有大屏？

2. 模糊需求兜底（用户没指定组件、数据、布局）

禁止默认 spec_builder 编造一通。优先动作：

• 问 1-2 个关键问题（业务主题 / 大致 5-8 个图想看什么 / 数据从哪来）
• 或者直接命中 B-Step1 模板时，向用户确认"我用 XX 模板复制后再改"

3. 高频意图 → 脚本/组件 速查

⚠️ JCommon ≠ ECharts 内置组件（JBar/JLine/JPie 等）。"通用组件"是平台菜单分类，专指 JCommon；用户说"通用组件"时默认指 JCommon，禁止误映射到 builtin handler 图表。区别看 references/data-binding-mapping.md §3。

⭐ 模糊需求 → 快速好看大屏 SOP（核心）

目标：用户没指定组件/布局/数据时，AI 也能 1 次往返产出"快 + 好看 + 不丑"的大屏。

速度铁律（HTTP 越少越快）

潜规则：spec_builder 一个 spec 写 N 个组件 = 1 次 HTTP；逐个 add 一个组件 1 次 HTTP。建 8 个图，前者 1 次，后者 8 次，速度差 ~6-8 倍。

组件挑选原则：5 维结构（用户没指定组件时按这个组）

不靠行业专属清单，靠通用结构——每张大屏从下面 5-7 维选 4-6 项即可，AI 据用户业务描述映射到具体组件。

挑选流程：

1. 读用户描述，提取"想看的指标关键词"
2. 用上方"高频意图→组件"速查表把每个指标映射到具体组件类型
3. 缺维度（如完全没说时间/对比）就反问而非自己脑补
4. 行业模板若 B-Step1 命中，优先 copy 模板再按需替换组件，比从 0 拼快

布局规则（按画布等比例算，不写死坐标）

画布尺寸由用户决定（默认 1920×1080；竖屏 1080×1920；4K 等比例放大）。AI 按下面比例规则算坐标，不要硬背像素。

通用比例（让"不丑"的最小约束）：

• 边距（画布外沿到组件） ≥ 短边 × 4%
• 组件间距 ≥ 短边 × 1.5%–2%
• 标题区高度 ≈ 短边 × 5%–7%
• 所有 x/y/w/h 对齐到 10 或 20 的倍数（防像素错位）
• 检查：组件不重叠（前一个 x+w + 间距 ≤ 后一个 x）、不贴边、不留大块孤儿空白

三种推荐布局形态（描述结构，不锁坐标）：

默认搭配：主题 dark + 平台命名色板（用户说"复古/商务/科技"等走 style_ops.py set-palette）。

演示数据量原则（AI 编 mock 时必读）

总则：用户没给真实数据让 AI 编演示数据时，数据条数尽可能多。默认值偏少（多数 5-7 条），照抄会让大屏空旷且滚动/分页/排行类组件不触发动效。

自检 checklist：

• 滚动组件保存后回查 数据行数 vs (h / row.height + marginBottom) 比值，低于 1.5 倍直接补数据
• spec_builder 默认 chartData 多数是 5-7 条，禁止照抄默认 chartData 当成"演示数据已够"
• 真实接口/数据集到位后此规则失效（取真实数据，量由业务定）

AI 模糊需求处理 SOP（按顺序走）

1. B-Step1 行业模板命中？
   • 是 → template_ops.py copy → 与用户确认改文案/数据 → 完成
   • 否 → 进入 2
2. 5 维结构 + 高频意图速查 = 选 4-6 个组件，按形态 A 默认排版 → spec_builder.py 单次生成 → 给用户预览
3. 数据来源未指定 → 必须先问（强制规则 #7）；用户允许 mock 时首选静态 mock 让效果最快出，后续再换真实数据集

场景决策树（入口即分叉，直达最短路径）

先判断操作类型，再判断子场景，不要默认走 spec_builder。

A. 页面级操作

创建空白大屏标准调用：

cd <skill目录> && python3 - <<'EOF'
import sys, time; sys.path.insert(0, 'references')
import bi_utils
t0 = time.time()
bi_utils.init_api('<API>', '<TOKEN>')
page_id = bi_utils.create_page('<名称>', style='bigScreen', theme='dark', background_image='/img/bg/bg4.png')
wprint(f'预览: <API>/drag/share/view/{page_id}?token=<TOKEN>&tenantId=<TENANT_ID>')
print(f'耗时: {time.time()-t0:.2f}s')
EOF

B. 整屏生成（从头新建含组件的大屏）

Step 1：模板匹配（用户说"从0开始"则跳过）

命中 → template_ops.py copy --replace '{"旧文本":"新文本",...}'（--replace 是 JSON 全局文本替换：对模板内 componentName / chartData / option 的所有匹配文本做 replace），完成，无需进入 Step 2。建议向用户确认"我先用 XX 模板复制再改文案/数据，可以吗？"
未命中 → 不许模糊套用（"教育/政务/HR/人力/营业厅/学校"等不在表里的领域，禁止硬塞最近的科技/金融模板）。直接进入 Step 2。
领域不在表 + 用户没给组件清单 → 必须先问业务主题与想看的核心指标，再走 Step 2。

Step 2：数据来源决定路径

数据来源？
├── 静态 mock 数据（用户给数据 / 让 AI 编造）
│     └── spec_builder（一次生成所有组件）
│           1. 读 references/spec-builder.md
│           2. 写 /tmp/<名称>.spec.json
│           3. 执行 spec_builder.py <API> <TOKEN> /tmp/<名称>.spec.json
│
├── YApi mock 接口
│     └── spec_builder 生成布局 → yapi_ops.py 绑定数据集
│
├── SQL 数据集（查数据库）
│     └── spec_builder 生成布局 → dataset_ops.py 绑定
│           注意：SQL 含 ${} 时用 --sql-file，禁止命令行传递
│           必须先 SHOW TABLES 确认表名
│
├── 文件数据集（Excel/CSV）
│     └── spec_builder 生成布局 → files_ops.py 绑定
│           用户未提供文件路径时：自动从 chartData/mock 数据生成 CSV，用 --mock-data 传入
│           示例: files_ops.py create-bind <api> <token> <page_id> --mock-data '<JSON数组>' --comp JBar --title "标题"
│           禁止提示"请先上传文件"——有数据就能自动建文件
│
├── 存储过程
│     └── spec_builder 生成布局 → proc_ops.py 绑定
│
└── BI 直连 Online 表 / 设计器表单 / Online 报表（dataType=4）
      触发：用户说"用 X 表 / cgform / jeecg 表 / Online 报表 / desform 作为数据源"
      特点：直接绑表字段，不创建独立数据集；自带字段级时间过滤(timeCondition)和字典翻译
      → 走 references/bi-mode-online.md 的脚本模板（spec_builder 当前不支持，需手写组件 config）
        已有参考大屏时优先 deepcopy 其组件 config（见 bi-mode-online.md §七）

用户未指定数据来源时必须先问（纯静态布局除外）。

spec_builder 用法：

--page-id <ID> 追加组件到已有页面（保留原有组件）；不传则新建页面。

# 查组件 schema（字段不确定时）
python3 references/scripts/spec_builder.py --schema JStatsSummary        # L1 精简
python3 references/scripts/spec_builder.py --schema JColorGauge --full   # L2 完整
python3 references/scripts/spec_builder.py --schema --list               # L3 总览

# 生成
python3 \
  references/scripts/spec_builder.py <API> <TOKEN> /tmp/<名称>.spec.json

spec_builder 自动处理：chartData 序列化、透明 bg、dark 主题、ECharts 轴样式、gradient 展开、pie 无 xAxis/yAxis、compareState 转换、命名色板应用、布局约束预警。

变体（variant）写法：spec 中 type 不带后缀（如 "type":"JStatsSummary"），变体通过同级 "variant":"1" 字段指定（生成 JStatsSummary_1）。直接写 "type":"JStatsSummary_1" 会找不到 handler。

🚨 spec JSON 核心字段速查（写错=脚本多跑一次，每次 +2-3 min）

禁止直接 Read references/scripts/defaults/*.json，统一经 --schema --full 调取。

C. 组件操作（修改已有大屏）

组件操作？
├── 查看当前有哪些组件
│     → comp_ops.py list
│
├── ⭐ 迭代替换（删旧+加新+改色一把梭，单次 HTTP 往返）
│     触发：用户说"换别图表"、"把 XX 换成 YY"、"替换饼图为柱形图" 等
│     → spec_builder --page-id <ID>，spec 顶层同时写 delete + components + palette：
│       {
│         "page": {"name":"..."},
│         "palette": "科技",                              // 可选，自动应用命名色板
│         "delete": {"types": ["JPie","JRing","JAntvGauge"]},  // 按 types/names/ids 任一批量删
│         "components": [ ...仅新增组件... ]
│       }
│     优势：1 次 query_page → 过滤旧 → append 新 → 应用色板 → 1 次 save_page
│           （替代原 3 次 comp_ops delete + 1 次 spec_builder append + 2 次 set-palette = 6 HTTP）
│
├── 添加组件（纯布局 / 静态数据 / 1个或多个）
│     → spec_builder --page-id <ID> /tmp/x.spec.json
│       （spec 只写要新增的组件，自动追加，保留已有组件）
│
├── 添加单组件 + 同时绑定 SQL/文件数据集
│     → comp_ops.py add --comp <type> --create-sql / --sql-file / ...
│
├── 添加多组件 + 联动（≥2图）
│     → multi_chart_linkage.py（省 80% 步骤）
│
├── 删除单个/部分组件（必须先确认）
│     → 用户给了名称且唯一：直接 comp_ops.py delete ... --name <名称>（无需先 list）
│       用户给了类型且页面只有 1 个该类型：直接 comp_ops.py delete ... --type <类型>
│       ⚠️ 名称/类型不唯一（如说"删饼图"但页面有 3 个 JPie / 多个组件同名）：
│         必须先 comp_ops.py list 让用户指认 ID，再 --id 删；禁止盲删导致误删
│       批量多类型：comp_ops.py delete ... --types "JPie,JRing,JAntvGauge"（逗号分隔，1 次 HTTP）
│       批量多名称：comp_ops.py delete ... --names "饼图1,柱图2"
│       名称不确定时才先 list，再 comp_ops.py delete ... --id <组件ID>
│
├── 清空所有组件（必须先确认）
│     → bi_utils.query_page(page_id)                     # 加载元数据
│       bi_utils._page_components[page_id] = []
│       bi_utils.save_page(page_id)
│
├── 切换全屏配色（命名色板，与产品 UI "配色" 下拉一致）
│     → style_ops.py set-palette --name <名称>    # 独立操作
│       或 spec_builder spec 顶层 "palette":"<名称>"   # 建屏/迭代时内嵌
│       可选：默认/复古/淡雅/未来/渐变/简洁/商务/柔和/科技/明亮/经典/清新/活力/火红/轻快/灵动
│       自动处理：option.color + customColor + 清除 series 硬编码 color；
│       默认按 y/x 轮转色板起点，--no-rotate 则所有图从 color[0] 起
│       查色值：style_ops.py list-palettes（无需 API/token）
│
├── 批量修改所有组件属性（如隐藏标题/改颜色/改渐变）
│     ⚠️ Step 0 — 组件清单来源优先级（决定是否跳过 query_page）：
│       1. 本会话刚写的 spec JSON / 刚 query_page 的返回值 → 直接用，跳过 query
│       2. 否则 query_page 拿当前清单
│       3. 拿到 unique(c['component']) 集合后，对 references/bi-comp-option-config.md
│          或 references/<comp-group>-option-config.md 定点搜"<CompType>"
│       ⛔ 禁止对整个 references/ 广义 grep "渐变/gradient/color/字体" ——
│          会扫到 99 个无关组件的文档（如 JCurrentTime / JStatsSummary / JOrbitRing
│          / JListProgress / JScrollList / JTabToggle），浪费上下文且延迟决策。
│
│     → 正确修改模式（query_page 返回值取组件，不能从 _page_components 取）：
│       page = bi_utils.query_page(page_id)
│       comps = page.get('template', [])                  # 从返回值取，非 _page_components
│       if isinstance(comps, str): comps = json.loads(comps)
│       for comp in comps: <修改 comp['config']>
│       bi_utils._page_components[page_id] = comps       # 写回缓存
│       bi_utils.save_page(page_id)
│
├── 修改组件配置（标题/颜色/数据/位置）
│     🚨 Step 0 — 先确认字段名（强制预检）：
│       上下文已有该组件 config → 直接看；字段不确定 → 查 bi-comp-option-config.md 对应 section
│
│     Step 1 — 选执行方式（字段名确认后再选）：
│
│       ┌─ 纯赋值（1个或多个字段，无条件判断/计算/循环）
│       │    → comp_ops.py edit --set（支持嵌套路径和数组下标 series[0].top）
│       │    ⚠️ "上下文已有 config"不是写临时脚本的理由——有 config 也用 comp_ops.py edit
│       │    ⚠️ --set 路径从 config 起算，禁止加 config. 前缀；x/y/w/h/componentName 例外写顶层名
│       │
│       └─ 需要 Python 逻辑（条件判断 / 计算值 / 循环遍历）
│            → 临时脚本
│
├── 组件群组/解组
│     → group_ops.py
│
├── 添加联动/钻取
│     → linkage_ops.py（读 references/linkage-drill-guide.md）
│
├── 添加外链/自定义 JS
│     → link_ops.py
│
└── 批量修改样式
      → style_ops.py（10 个子命令）：
        show-colors（看当前色） / set-title-color / set-axis-color / set-grid-color / set-legend-color
        set-font-size / set-bg-all / set-palette / list-palettes
        batch-edit（任意 config 路径赋值，--path/--value/--type/--name 过滤）

D. 数据绑定（给已有组件换数据源）

📌 绑定前必读：references/data-binding-mapping.md（两套映射机制：顶层 dataMapping vs 组件自带 option.fieldMap/header.key）——否则绑了也不显示数据。

🚨 一律走 dataset_ops.py bind / bind-batch，禁止手写临时 .py 直接改 cfg['dataType']=2 / dataSetId / dataMapping。原因：脚本封装了 4 项前端必读的字段元信息回填（option.columns JCommonTable 列定义、fieldOption UI 字段下拉、paramOption、dataSetIzAgent / dataSetMethod / dataSetApi），靠 getAllChartData 拿真实 API 字段名 fallback。手写绑定漏写 → JCommonTable 表头/表体全空（useTableBiz.ts:339 直接读 config.option.columns，缺失时 columns=[]）。UI 复制组件能显示是因为 dataSetCompService 在保存时回填，API 路径不会触发前端的回填逻辑——这是 AI 最容易踩的"看似都改了实则缺关键字段"陷阱。

🚨 ≥2 个组件绑定一律用 dataset_ops.py bind-batch，禁止 shell 并行调多次 bind。每次 bind 都是「query → 改 target → 整页 save」，并发会互相覆盖快照，导致非 target 组件的 option 出现脏写（实测：JRingProgress 的 valueFontSize 被改成 38、lineHeight 被改成 0，KPI 数值不显示）。bind-batch 一次 query → 内存改 N 个 target → 一次 save 彻底规避。

易混脚本对照（防止选错）：

E. 其他操作

按需加载文档（场景触发才读）

bi_utils 核心规则（仅手写 Python 时参考）

bi_utils.API_BASE = 'http://...'
bi_utils.TOKEN    = '...'

PAGE_ID = bi_utils.create_page('名称', style='bigScreen', theme='dark',
                               background_image='/img/bg/bg4.png')   # 返回字符串，禁止 resp['id']
bi_utils._page_components[PAGE_ID] = []     # 必须缓存（否则 add 会覆盖）

bi_utils.add_component(PAGE_ID, 'JBar', '标题', x, y, w, h, config=cfg)
# 组件字段：comp['i']=UUID, ['componentName']=中文, ['component']=compType
# 图层：template[0]=最顶层，新增组件 insert(0, comp)

# query_page 返回 page 对象，组件在 page['template']，不在 _page_components
# 要修改已有组件必须从返回值取：page = bi_utils.query_page(ID); comps = page['template']
# 修改后写回：bi_utils._page_components[ID] = comps，再 save_page
bi_utils.query_page(PAGE_ID); bi_utils.save_page(PAGE_ID)

高频踩坑 Top 12（spec_builder 未覆盖 / 仅直调脚本时需留意）

完整踩坑见 references/pitfalls.md。被 spec_builder 自动消除的（chartData 序列化、透明 bg、颜色、pie xAxis、compareState、ECharts 轴样式、命名色板、布局约束预警）不再单列。变体写法见上方"变体（variant）写法"。

高频命令模板速查（写参数前抄这里）

决策树告诉你选哪个脚本，这里给完整命令模板。只挑参数最容易写错的 6 个高频场景。

1. 迭代替换（删旧+加新+换色板，1 次 HTTP）

cat > /tmp/iter.spec.json <<'EOF'
{
  "page": {"name": "<可选>"},
  "palette": "科技",
  "delete": {"types": ["JPie","JRing"]},
  "components": [ {...仅新增组件...} ]
}
EOF
python3 \
  references/scripts/spec_builder.py <API> <TOKEN> /tmp/iter.spec.json --page-id <PAGE_ID>

2. 批量删多类型 / 多名称（1 次 HTTP）

# 多类型（逗号分隔，禁止空格，禁止单引号包字符串）
python3 references/scripts/comp_ops.py delete \
  --api <API> --token <TOKEN> --page-id <PAGE_ID> \
  --types "JPie,JRing,JAntvGauge"

# 多名称（中文需用双引号包整个值）
python3 references/scripts/comp_ops.py delete \
  --api <API> --token <TOKEN> --page-id <PAGE_ID> \
  --names "饼图1,柱图2"

3. 切换全屏命名色板（禁止 AI 自编色值）

# 查可用色板（不调 API）
python3 references/scripts/style_ops.py list-palettes

# 切配色（默认按 y/x 轮转色板起点）
python3 references/scripts/style_ops.py set-palette \
  --api <API> --token <TOKEN> --page-id <PAGE_ID> --name 复古
# 加 --no-rotate 让所有图都从 color[0] 起

4. SQL 数据集绑定（含 ${} FreeMarker 必走 --sql-file）

# 先 SHOW TABLES 确认表名（强制规则 #4）
# SQL 含 ${var} 占位符时禁止命令行传，会被 shell 消费
cat > /tmp/q.sql <<'EOF'
SELECT name, value FROM onl_drag_page WHERE tenant_id = ${tenantId}
EOF

python3 references/scripts/dataset_ops.py create-sql \
  --api <API> --token <TOKEN> --name "我的数据集" --sql-file /tmp/q.sql \
  --db-source <DS_CODE>

5. 多图新建+联动（一次完成）

# multi_chart_linkage 适合：从 0 建 ≥2 张联动图
# linkage_ops 适合：已有屏的图加联动
python3 references/scripts/multi_chart_linkage.py \
  --api <API> --token <TOKEN> --page-id <PAGE_ID> \
  --spec /tmp/multi_linkage.spec.json

6. YApi 高级 mock（按参数分支返参，支持联动/钻取）

# 高级 mock 脚本走 --advmock-file（含 JS 逻辑，避免 shell 转义）
python3 references/scripts/yapi_ops.py create-mock \
  --project-id <PID> --path /api/sales/trend --method GET \
  --advmock-file /tmp/advmock.js

环境约定（按本机情况调整）：

• Python 解释器：示例统一写 python3（Unix 通用）。Windows 用户改为 py（或本机已配的 Python 3 路径）。脚本要求 Python ≥ 3.10（用了 dict | None 等语法）
• 本地 API 走代理：若本机 HTTP 代理拦截 127.0.0.1/localhost 导致 502，命令前加 no_proxy="127.0.0.1,localhost"（macOS/Linux）或 set no_proxy=127.0.0.1,localhost &&（Windows）
• Windows 中文输出乱码：所有命令前加 set PYTHONIOENCODING=utf-8 &&
• 🚨 临时配置文件路径必须用 tempfile.gettempdir()，不要硬编码 /tmp：所有传给脚本的 --config / --batch-file / --spec / --sql-file 等 JSON/SQL 临时文件，跨平台靠 tempfile.gettempdir()：Windows %TEMP% / Linux /tmp / macOS /var/folders/.../T（不是 /tmp！）。命名带表名+步骤前缀（onl_<场景>_<步骤>.json）便于排错；OS 自动清理，禁止主动 rm / os.path.exists()（自身就是 tool call 浪费）；乐观调用 + 仅当报 FileNotFoundError 时用相同内容重写重试，不换路径。示例：config_path = os.path.join(tempfile.gettempdir(), 'onl_sales_dashboard_iter.json')

Step 4：输出结果

预览地址：
{API_BASE}/drag/share/view/{id}?token={TOKEN}&tenantId=<TENANT_ID>
耗时：约 Xs

脚本开头 t0=time.time()，结尾 print(f'耗时: {time.time()-t0:.1f}s')。