jimubi-bigscreen（吉姆比大屏）

JeecgBoot 大屏 AI 自动生成器

将自然语言的大屏需求转换为 drag page 配置，并通过 API 自动创建。

本 skill 专门处理大屏（bigScreen）模式：全屏展示，绝对定位（像素坐标），深色主题，适用于监控室/展厅/展示墙。 仪表盘（看板）请使用 jimubi-dashboard skill。

⚠️ 强制规则：所有大屏相关操作必须优先通过本 skill 处理（无任何例外）

触发范围：凡涉及大屏的任何操作，包括但不限于：

• 创建/删除/修改大屏页面
• 添加/编辑/删除组件
• 数据集（SQL/API/文件/WebSocket）的创建与绑定
• 数据源的创建、编辑、测试（包括修改用户名、密码、连接参数等）
• 模板复制、页面配置修改
• 组件联动、钻取、外部链接

禁止行为：

• 未调用本 skill，直接读 memory 找凭据自行执行
• 未调用本 skill，自己探索 API 路径后直接调用
• 以"操作太简单不需要 skill"为由跳过

正确执行顺序：

1. 用户提出大屏相关需求
2. 第一步必须调用本 skill（Skill jimubi-bigscreen）
3. 在 skill 上下文中读取凭据、选择脚本、执行操作

按需加载指南

本 skill 采用分层加载：核心规则始终在上下文中，专题文档按需读取。

图表查询与推荐（用户询问或需求不明确时）

场景一：用户询问"可以使用什么图表"

触发条件：用户问"有哪些图表"、"支持什么图表"、"可以用什么图表"、"图表有哪些类型"、"列出所有图表"等。

处理方式：直接输出以下完整图表分类表格（无需读取任何文档，无需执行任何脚本）：

场景二：用户图表需求不明确时给出推荐

触发条件：用户说"加一个图表"、"加一个图"、"给我展示数据"、"可视化一下"、"用什么图表好"等，没有明确说要哪种图表类型。

处理方式：根据用户描述的数据类型/业务场景，从以下推荐表中给出 3-5 个建议，说明各自适用场景，让用户选择：

推荐话术： 列出3-5个图表名+compType+一句话原因，末尾"请选择，我将立即创建"。

SQL数据集创建标准流程（强制）

触发条件：用户说"使用SQL数据集"、"增加SQL数据集"、"统计 xxx 表"、"生成图表"等涉及 SQL 数据集的任何场景，必须严格按以下四步执行，不得跳过第1步。

第1步：确认数据源（必须询问，禁止擅自选择）

先列出数据源让用户选择，等用户选择后再继续：

py datasource_ops.py list "<api_base>" "TOKEN"

第2步：根据业务场景自行编写SQL

• 用户指定数据源后，根据用户描述的业务场景，自行设计并编写合适的 SQL 语句
• 🚨 严禁自行猜测或编造表名：必须先通过 pymysql 直连（datasource_ops.py detail 获取连接信息 + 向用户索取密码）执行 SHOW TABLES 确认表存在，再写 SQL。常见错误案例：擅自使用 jimu_drag_page，实际表名是 onl_drag_page（2026-04-15 事故）
• 必须使用预置脚本创建 SQL 数据集，禁止直接调用 /drag/onlDragDatasetHead/add API（直接调 API 报"数据源连接失败"；预置脚本封装了正确的请求体格式）
• 使用 comp_ops.py add --create-sql --db-source <ID> 或 dataset_ops.py create-sql 创建

第3步：创建SQL数据集

• 分组必须使用 "示例数据集"（dataset_ops.py create-sql 已内置 --group "示例数据集" 默认值，自动查询/创建，无需手写代码）
• 直接使用 dataset_ops.py create-sql（已修复 --db-source 参数 bug，可正常使用）：

py dataset_ops.py create-sql $API_BASE $TOKEN \
  --name "数据集名称" --db-source "数据源ID" \
  --sql "SELECT name, value FROM table GROUP BY name" \
  --fields "name:String,value:Integer"
# --group 默认 "示例数据集"，无需额外传参

• 数据集创建完成后，必须执行查询解析验证确认数据正常返回

第4步：后续绑定操作（按需）

• 询问用户是否需要将数据集绑定到图表组件
• 如需要，使用 comp_ops.py --dataset-name 或 comp_ops.py --create-sql 执行绑定

文件数据集创建标准流程（多文件 FILES）

触发条件：用户说"多文件数据集"、"FILES"、"上传多个Excel文件"、"JOIN多个文件"，或明确指定需要多个文件关联查询时使用。 注意：用户只说"文件数据集"或提供一个文件时，应使用单文件数据集（singleFile）流程（见下一节）。

标准流程（5步）

⚠️ 实测可行顺序：先创建空数据集 → 上传文件 → 获取表名 → 更新 SQL + 字段列表；也可先上传再创建（带 content 字段）。两种顺序均可，但先创建再上传更常见（数据集 ID 上传后立即可用）。

关键要点

• 上传文件自动加 HHMM 时间戳后缀（避免 H2 表名冲突）
• value 是 SQL 关键字：用 sales/amount/total 等替代
• 上传必须带 reportId 参数；dbSource 必须与 reportId 一致
• files/get 的 result 是 dict：json.loads(result.get('dbUrl','[]')) 取 name 字段
• queryFileFieldBySql 需签名，bi_utils 不支持：直接传 datasetItemList + getAllChartData 验证
• SQL 别名不加单引号：SELECT col as type（不是 'type'）
• Excel 表名规律：xxx.xlsx → Sheet1_{xxx}_excel（files/get 失败时用作 fallback）

files/get 正确解析方式

# ✅ 正确：result 是 dict，dbUrl 是 JSON 字符串
files_resp = bi_utils._request('GET', '/jmreport/source/datasource/files/get', params={'reportId': PAGE_ID})
result = files_resp.get('result') or {}
file_list = json.loads(result.get('dbUrl', '[]'))  # [{"fileName":"products.xlsx","name":"jmf.Sheet1_products_excel"}, ...]

# 按文件名关键词匹配
products_table = next((f['name'] for f in file_list if 'product' in f['name'].lower()), 'jmf.Sheet1_products_excel')
orders_table   = next((f['name'] for f in file_list if 'order'   in f['name'].lower()), 'jmf.Sheet1_orders_excel')

# ❌ 错误：不能把 result 当 list 迭代
# file_list = (files_resp.get('result') or [])  # result 是 dict 不是 list！

SQL 字段别名与 dataMapping 对应

详细操作步骤和代码示例见 references/dataset-guide.md 的「多文件数据集（FILES）标准操作流程」章节。

单文件数据集创建标准流程（singleFile）

触发条件：用户说"单文件数据集"、"使用单个Excel文件"、"singleFile"，或明确指定只上传一个文件时使用。

关键区别

标准流程（5步）

⚠️ 第5步必须在同一脚本内用 bi_utils.add_component() 完成，禁止拆成两个脚本，禁止用 comp_ops.py --dataset-name。（--dataset-name 按索引顺序映射而非语义匹配，导致图表显示错误数据）

singleFile 快速路径（强制 3 轮完成）

轮次1: [并行] Read 凭据 + Bash openpyxl/xlrd 分析 Excel 列名
轮次2: [并行] Bash cp bi_utils.py + Write singlefile_chart.py（全流程一脚本）
轮次3: Bash PYTHONIOENCODING=utf-8 py singlefile_chart.py && rm 清理

全流程一脚本模板： 详见 references/dataset-guide.md「创建单文件数据集（singleFile）端到端」章节。关键结构：

# 上传（必须用 requests.post，bi_utils._request 不支持 files 参数）
up = requests.post(f"{API_BASE}/jmreport/source/datasource/files/add",
    headers={"X-Access-Token": TOKEN}, params={"reportId": PAGE_ID, "isSingle": "true"},
    files={"file": (filename, file_data, "application/octet-stream")}).json()
table_name = (json.loads((up.get("result") or {}).get("dbUrl", "[]")) or [{}])[0].get("name")
# 建数据集（parentId="1516743332632494082"，code=table_name 含 jmf. 前缀）
# 查询页面缓存template，再 add_component（显式语义映射），再 save_page
page = bi_utils.query_page(PAGE_ID); bi_utils._page_components[PAGE_ID] = page.get('template', [])

关键要点

• querySql：select * from jmf.{table_name}（必须含 jmf. 前缀，不做聚合）
• 表名解析：json.loads(result.get("dbUrl","[]"))[0].get("name")（不是 result.tableName）
• code 字段：保留 jmf. 前缀（缺前缀报 SQLException），禁止 replace('jmf.','')
• dataSetIzAgent：singleFile 设 ''（FILES 才用 '1'）
• parentId：固定 id=1516743332632494082（示例数据集）
• 写脚本用 Write 工具，禁止 bash heredoc（含单引号必报错）

详细操作步骤和代码示例见 references/dataset-guide.md 的「创建单文件数据集（singleFile）端到端」章节。

API数据集创建标准流程（强制）

触发条件：用户说"使用API数据集创建图表"、"用API数据集"，且未明确指定接口地址或SQL数据集时，必须严格按以下五步执行。

⚡ 快捷路径：用户已给出 API 地址时（2轮完成，禁止任何探测步骤）

触发条件：用户需求中明确包含 API 接口地址（如 https://...）。

强制流程（严格 2 轮，禁止多余步骤）：

轮次1: cp dataset_ops.py + comp_ops.py + bi_utils.py + default_configs.json && ls验证
轮次2: dataset_ops.py create-api ... && comp_ops.py add --dataset-name ... && rm

⚠️ 禁止行为（已观测违规 2026-04-10）：

• 禁止先用 --dataset-name 查找不存在的数据集（查不到就添加静态组件，浪费 3 轮）
• 禁止先 comp_ops.py add 添加静态数据组件再删除重来
• 禁止询问数据来源（用户已给出地址，无需问 mock 还是自写接口）

⚡ 快捷路径：YApi Mock + 批量图表（2轮完成，强制规范）

触发条件：用户选择 YApi Mock 方式 + 需要生成同类型全部图表（如柱形图类全部10种）。

强制流程（严格 2 轮）：

轮次1: [并行] Bash: yapi list（查已有接口，复用勿重建）
               Write: 批量脚本（内嵌数据集创建+全部图表添加，直接填入最终凭据）
轮次2: Bash: cp "<skill_base_dir>/references/bi_utils.py" . && \
             cp "<skill_base_dir>/references/scripts/default_configs.json" . && \
             PYTHONIOENCODING=utf-8 py batch_script.py && \
             rm batch_script.py bi_utils.py default_configs.json

五条强制规则：

1. cp 必须与 py 在同一命令链（轮次间文件会丢失）
2. Write 脚本与 yapi list 必须同轮并行
3. 批量脚本内嵌数据集创建逻辑，禁止分轮执行
4. 脚本内置 mock 复用逻辑，禁止看 yapi list 结果后再 Edit 脚本
5. yapi 复用逻辑按路径精确匹配（如 /claude/bar_multi），禁止宽泛正则（如 'bar' in line 命中错误接口）

批量脚本结构（query_page → 缓存 template → 创建数据集 → 批量 add_component → save_page）：

# 1. 查询页面并立即缓存（禁止省略缓存步骤，否则 save_page 清空已有组件）
page = bi_utils.query_page(PAGE_ID)
bi_utils._page_components[PAGE_ID] = page.get('template', [])
# 2. 创建数据集（/drag/onlDragDatasetHead/add，parentId 用示例数据集固定ID 1516743332632494082）
# 3. 循环 bi_utils.add_component() 批量添加（1次 query + N次内存add + 1次save）
# 4. bi_utils.save_page(PAGE_ID)

第1步：确认是否已有接口

• 用户已指定接口地址 → 走上方「快捷路径」，直接 dataset_ops.py create-api + comp_ops.py add
• 用户未指定 → 执行第2步

第2步：询问数据来源方式（必须询问，禁止擅自决定）

向用户提问，选择：

1. 使用 mock 创建API接口（使用YApi Mock系统）
2. 使用自定义接口（在后端编写Java接口）

第3步：根据选择收集信息并创建接口

选择1（mock接口）：

• 询问：mock系统接口地址、账号密码、业务场景描述
• 参考按需加载表中「YApi Mock 系统 + API 数据集」章节（references/pitfalls.md）执行

选择2（自定义接口）：

• 询问：接口要编写到哪个Controller文件、业务场景描述
• 禁止自行搜索文件，必须直接询问用户Controller路径
• 参考按需加载表中「自写 Java API 接口 + API 数据集 + 批量图表」章节（references/pitfalls.md）执行

第4步：创建API数据集（含字段列表）

• 分组用 "示例数据集"（固定 id=1516743332632494082，可直接硬编码）
• 【强制】/add 时直接传 datasetItemList（字段名不是 onlDragDatasetItemList），无需 queryFieldByApi（常返回空）
• /add 返回的 result 是完整对象 dict，取 DS_ID：(add_r.get('result') or {}).get('id')

ds_fields = [
    {'fieldName': 'name',  'fieldTxt': '名称', 'fieldType': 'String',  'izShow': 'Y', 'orderNum': 0},
    {'fieldName': 'value', 'fieldTxt': '数值', 'fieldType': 'Integer', 'izShow': 'Y', 'orderNum': 1},
    # 多系列图表额外加 type/group 字段
    {'fieldName': 'type',  'fieldTxt': '分组', 'fieldType': 'String',  'izShow': 'Y', 'orderNum': 2},
]
add_r = bi_utils._request('POST', '/drag/onlDragDatasetHead/add', data={
    'name': '数据集名', 'code': 'ds_xxx', 'dataType': 'api',
    'querySql': API_URL, 'apiMethod': 'get', 'parentId': parent_id,
    'datasetItemList': ds_fields,  # ⚠️ 直接传，无需解析接口
})
DS_ID = (add_r.get('result') or {}).get('id')  # ⚠️ result 是 dict，取 .id

第5步：绑定图表组件（dataMapping 必须按语义映射）

• 【强制】dataMapping 按字段语义显式指定，禁止按数组索引顺序映射（索引 0→0 不等于语义对应）

# ✅ 语义映射模板（单系列图表：JLine/JSmoothLine/JStepLine/JArea/JPie/JBar 等）
SINGLE_MAP = [
    {'filed': '维度', 'mapping': 'name'},
    {'filed': '数值', 'mapping': 'value'},
]
# ✅ 语义映射模板（多系列图表：JMultipleLine/DoubleLineBar/JStackBar/JMultipleBar 等）
MULTI_MAP = [
    {'filed': '分组', 'mapping': 'type'},   # 分组字段对应 type/group
    {'filed': '维度', 'mapping': 'name'},   # 维度对应 name（x轴标签）
    {'filed': '数值', 'mapping': 'value'},  # 数值对应 value
]

• fieldOption 必须同步传入（前端字段面板显示用）：

field_option = [
    {'label': 'name',  'text': '名称', 'type': 'String',  'value': 'name',  'show': 'Y'},
    {'label': 'value', 'text': '数值', 'type': 'Integer', 'value': 'value', 'show': 'Y'},
    {'label': 'type',  'text': '分组', 'type': 'String',  'value': 'type',  'show': 'Y'},
]

大屏特征

• 布局：绝对定位，坐标和尺寸单位为像素（如 x=50, y=280, w=860, h=380）
• 主题：默认 dark，深色背景，亮色/霓虹文字
• 背景图：默认 /img/bg/bg4.png，支持自定义
• 装饰元素：常用 JDragBorder（边框）、JDragDecoration（装饰条）增强视觉效果
• 典型分辨率：1920×1080

⚠️ 以下为大屏固定默认值，用户未说明时无需重复声明，脚本中直接使用： - 分辨率：1920×1080（desJson.height=1080，宽度由前端固定） - 背景图：/img/bg/bg4.png（深空星空，极暗底色，文字必须用亮色） - 主题：dark，style：bigScreen，designType：100 - 只有用户明确要求更换分辨率或背景图时才修改

默认背景图 bg4.png 配色指引（强制）

bg4.png 是深空星空渐变图：四角纯黑（#000000），中心深海蓝（#021533～#03234d），整体极暗。文字/标签颜色必须足够亮才能保证可读性。

适合在 bg4.png 上使用的颜色（亮色系）：

严禁在 bg4.png 上使用的颜色（深色系，会被背景吞没）：

• #333333、#464646、#666666 等深灰 — ECharts 默认轴色，必须覆盖
• #000000、#0a1628、#021533 — 与背景融为一体，完全不可见
• rgba(0,0,0,x) — 任何黑色半透明

ECharts 组件必须显式覆盖的默认暗色字段（强制）：

opt_patch = {
    'xAxis': {'axisLabel': {'color': '#8ab8d0'}, 'axisLine': {'lineStyle': {'color': '#1a3a5a'}}},
    'yAxis': {'axisLabel': {'color': '#8ab8d0'}, 'splitLine': {'lineStyle': {'color': '#1a3a5a55'}}},
    'legend': {'textStyle': {'color': '#8ab8d0'}},
    'tooltip': {'backgroundColor': '#0b1e3acc', 'textStyle': {'color': '#e0f0ff'}},
}

图层背景色规则（强制）

严禁将图层背景色设为红色或任何非透明颜色（除非用户明确指定）。 用户未指定背景色时，config.background 和 config.borderColor 必须设为 #FFFFFF00（透明）。

图表配色规范（强制）

以下规范适用于所有使用 option.customColor 的图表组件（JPie/JRose/JLine/JArea/JMixLineBar/JMultipleLine/JStackBar/JMultipleBar/JCapsuleChart 等 20 种）。

系统默认9色（"系统自定义配色"的正确值，2026-04-20 实测）：

SYSTEM_CUSTOM_COLORS = [
    {"color1": "#1e90ff", "color": "#1e90ff"},
    {"color1": "#90ee90", "color": "#90ee90"},
    {"color1": "#00ced1", "color": "#00ced1"},
    {"color1": "#e2bd84", "color": "#e2bd84"},
    {"color1": "#7a90e0", "color": "#7a90e0"},
    {"color1": "#3ba272", "color": "#3ba272"},
    {"color1": "#2be7ff", "color": "#2be7ff"},
    {"color1": "#0a8ada", "color": "#0a8ada"},
    {"color1": "#ffd700", "color": "#ffd700"},
]

为什么不是 []：界面选择"系统自定义配色"时，前端会将系统色板中的9个颜色逐一写入该字段，而非清空。[] 与界面行为不一致，会导致图表使用 ECharts 内置配色而非系统配色。

前置条件

用户必须提供 API 地址和 X-Access-Token。

执行效率规则（强制）

简单操作直接执行，禁止多余探索

禁止： brainstorming、Explore子代理探源码、Read模板JSON（92KB+）、读 dataset-guide.md（预置脚本已封装）、展示摘要等确认、预置脚本前 --help、存储过程手写 pymysql（用 proc_ops.py bindcomp）

正确做法：直接使用预置脚本（template_ops.py、comp_ops.py、dataset_ops.py）完成，1-2 轮工具调用。

模板创建快速路径（强制，token 节省 90%+）

创建整个大屏时，必须走以下快速路径，禁止自定义脚本：

轮次1: cp template_ops.py + bi_utils.py（1 条 Bash 命令）
轮次2: py template_ops.py copy ... --replace '{...}' --board-data '{...}' && echo URL | clip.exe && rm（1 条 Bash 命令）

替换字典构建规则： 根据用户行业需求，直接构建 --replace JSON，无需分析模板内容。各模板中的占位文本是固定的：

模板1：大数据可视化展示平台（通用/销售/综合类）

模板2：北京科技数字化云平台（科技/能源/电力/IoT/设备监控类）

示例（风力发电行业，使用北京科技数字化云平台模板）：

py template_ops.py copy $API_BASE $TOKEN \
  --template "北京科技数字化云平台_1014376428645961728.json" \
  --name "风力发电智慧监控平台" \
  --bg-image "/img/bg/bg4.png" \
  --replace '{"北京科技数字化云平台":"风力发电智慧监控平台","网关管理":"风机管理","云组态":"SCADA系统","设备管理":"机组管理","动态数据":"实时数据","人员管理":"运维管理","监控管理":"故障监控","人员定位":"风场巡检","能源管理":"发电管理","功耗总量":"发电总量","电能耗":"发电量","水能耗":"上网电量","17563":"58260","11163":"42850","kw/h":"万kWh","设备列表":"风机列表","信息":"风场信息","站点号：0001":"风场编号：WF-001","设备状态：正常":"风机状态：正常运行","环境温度：36摄氏度":"平均风速：8.5m/s","在线设备：20 台":"在线风机：126 台","近七日设备在线数":"近七日风机在线数","设备功率信息":"风机功率信息","近七日电能耗":"近七日发电量","近七日水能耗":"近七日弃风量","一号机房功率":"A区风机功率","二号机房功率":"B区风机功率","三号机房功率":"C区风机功率","四号机房功率":"D区风机功率","五号机房功率":"E区风机功率","基础折线图":"风机在线趋势","1号机房":"A区-01号风机","2号机房":"B区-03号风机","3号机房":"C区-07号风机","4号机房":"D区-12号风机","5号机房":"E区-05号风机","0374":"WF-A01","0375":"WF-B03","0376":"WF-C07","0377":"WF-D12","0378":"WF-E05","正常":"运行中","功率":"功率(MW)","编号":"风机编号","设备名":"风机名称","设备状态":"运行状态"}'

Online表单全组件快速路径（强制，3 轮完成）

用户要求"使用Online表单创建全组件"时，直接按以下流程执行，禁止读取 online-design-form-chart-guide.md。

⚠️ 凭据已在 MEMORY.md 上下文中，无需 Read 凭据文件（节省1轮）。

轮次1: 列出表单（固定端点，**禁止盲猜其他路径**）：
       Online 表单：  GET /online/cgform/head/list
       设计器表单：   GET /desform/api/list/options  ← 返回 [{value:tableName, label:formName}]
       用户选定后，立即查询字段：
       Online 表单：  GET /online/cgform/field/listByHeadId?headId=xxx
       设计器表单：   GET /desform/api/fields/{tableName}?subTable=true  ← result.id=formId, result.fields[]
       展示字段列表，询问：维度字段（nameFields）、数值字段（valueFields）、分组字段（typeFields）
轮次2: 用户确认字段后 → cp bi_utils.py + Write 全组件脚本（并行）
轮次3: PYTHONIOENCODING=utf-8 py online_all_comps.py && rm bi_utils.py online_all_comps.py

允许的48个 Online 表单图表类型（按顺序硬编码，禁止自行扩充）：

⚠️ 第4个元素是中文名，必须直接用作 componentName，严禁用 ct（英文代码）作图层名！ 正确写法：ct, cat, is_group, cn_name = chart_tuple，然后 'componentName': cn_name

ALL_CHARTS = [
    # (compType, category, isGroup, 中文名)
    ('JBar','Bar',False,'基础柱形图'), ('JStackBar','Bar',True,'堆叠柱形图'),
    ('JMultipleBar','Bar',True,'对比柱形图'), ('JNegativeBar','Bar',True,'正负柱形图'),
    ('JDynamicBar','Bar',False,'动态柱形图'), ('JMixLineBar','Bar',True,'折柱图'),
    ('JCapsuleChart','Bar',False,'胶囊图'), ('JPercentBar','Bar',True,'百分比条形图'),
    ('JHorizontalBar','HorizontalBar',False,'基础条形图'),
    ('JRankingList','HorizontalBar',False,'排行榜'),
    ('JTotalProgress','HorizontalBar',False,'进度图'),   # onlyValueChart，nameFields=[]
    ('JLine','Line',False,'基础折线图'), ('JArea','Line',False,'面积图'),
    ('JMultipleLine','Line',True,'对比折线图'),
    ('DoubleLineBar','Line',True,'双轴图'),               # nameFields=[]，typeFields=[维度]
    ('JStepLine','Line',False,'阶梯折线图'),
    ('JCustomProgress','Progress',False,'基础进度图'),
    ('JProgress','Progress',False,'进度图'),
    ('JLiquid','Progress',False,'水波图'),                # onlyValueChart，nameFields=[]
    ('JPictorialBar','Pictorial',False,'象形柱图'), ('JPictorial','Pictorial',False,'象形柱'),
    ('JPie','Pie',False,'基础饼状图'), ('JRing','Pie',False,'基础环形图'),
    ('JRose','Pie',False,'南丁格尔玫瑰'), ('JRotatePie','Pie',False,'旋转饼图'),
    ('JFunnel','Funnel',False,'基础漏斗图'), ('JPyramidFunnel','Funnel',False,'金字漏斗图'),
    ('JRadar','Radar',True,'基础雷达图'), ('JCircleRadar','Radar',True,'圆形雷达图'),
    ('JRingProgress','Ring',False,'基本环形图'), ('JActiveRing','Ring',False,'动态环形图'),
    ('JRadialBar','Ring',False,'玉珏图'),
    ('JRectangle','Rectangle',False,'矩形图'),
    ('JBar3d','threeD',False,'3D柱形图'), ('JBarGroup3d','threeD',True,'3D分组柱形图'),
    ('JColorGauge','Gauge',False,'多色仪表盘'), ('JGauge','Gauge',False,'基础仪表盘'),
    ('JAntvGauge','Gauge',False,'渐变仪表盘'),  # onlyValueChart（Gauge），nameFields=[]
    ('JNumber','Number',False,'数值图'),         # onlyValueChart（Number），nameFields=[]
    ('JScatter','Scatter',False,'基础散点图'),
    ('JBubble','Scatter',True,'气泡图'), ('JQuadrant','Scatter',True,'象限图'),
    ('JPivotTable','Table',True,'表格'),
    ('JAreaMap','Map',False,'区域地图'), ('JBubbleMap','Map',False,'散点地图'),
    ('JHeatMap','Map',False,'热力地图'), ('JBarMap','Map',False,'柱形地图'),
    ('JWordCloud','WordCloud',False,'词云'),
]

onlyValueChart 判断规则（nameFields/typeFields 必须为 []）：

• category in {'Gauge','Number'} → nameFields=[], typeFields=[]
• compType in {'JTotalProgress','JLiquid'} → nameFields=[], typeFields=[]
• Ring/Progress 分类其他组件（JCustomProgress/JProgress/JRingProgress 等）不是 onlyValueChart，需要 nameFields

DoubleLineBar 特殊字段规则：

• nameFields=[], typeFields=[维度字段(name)], valueFields=[数值字段], assistYFields=[数值字段], assistTypeFields=[分组字段(sex)], seriesType=[]

chart.isGroup 设置规则（JGauge/JColorGauge/JAntvGauge/DoubleLineBar 不设此字段，其余按实际 isGroup 值设）：

no_isg = {'JGauge','JColorGauge','JAntvGauge','DoubleLineBar'}
chart_cfg = {'category': cat, 'subclass': ct}
if ct not in no_isg:
    chart_cfg['isGroup'] = is_group

compStyleConfig 必须包含完整 summary（否则前端报 showTotal 错误）：

'compStyleConfig': {
    'summary': {'showY':True,'showTotal':False,'showField':'all','totalType':'sum','showName':'总计'},
    'showUnit': {'numberLevel':'','decimal':None,'position':'suffix','unit':''},
    'assist': {'summary':{'showY':True,'showField':'all','totalType':'sum','showName':'总计'},
               'showUnit':{'numberLevel':'','decimal':None,'position':'suffix','unit':''}},
    'headerFreeze':False,'unilineShow':False,'izPage':False,
    'columnFreeze':False,'lineFreeze':False,
    'showProgressText':True,'progress':{'show':True,'name':'进度'},'target':{'show':True,'name':'目标'},
}

filter 必须包含 conditionFields:[] 和 customTime:[]（否则 forEach 报错）：

'filter': {'queryField':'create_time','queryRange':'all','conditionMode':'AND','conditionFields':[],'customTime':[]}

⚠️ 必填字段清单：

• dataType: 4（最易漏！ 漏写则 dataType=0 静态数据，读不到表单数据）
• formType: 'online'（漏掉表单未绑定）
• formId: HEAD_ID（必须用 formId 不是 headId）
• formName, tableName（缺失接口无法定位表）
• option：必须是图表专属 ECharts 配置，禁止传 {}（空 option 导致"加载中"）
• commonOption：地图类专用，必须单独设置

option 分发规则（按 ct 选择，详见 references/online-design-form-chart-guide.md 第八节 _get_default_chart_option()）：

• 地图类（MAP_TYPES）：必须同时设 option（含 drillDown/area/geo/visualMap）+ commonOption（必含 breadcrumb）
• 仪表盘（JGauge/JColorGauge/JAntvGauge/JSemiGauge）：无 xAxis/yAxis，series type='gauge'
• 水波图（JLiquid）：series type='liquidFill'
• 漏斗图（JFunnel/JPyramidFunnel）：series type='funnel'，tooltip trigger='item'
• 饼图系列（JPie/JRose/JActiveRing/JRotatePie）：禁用含 xAxis/yAxis 的柱形 option，series:[], tooltip trigger='item'
• JRing：series 必须预填充完整含 radius:['40%','70%']
• 雷达图（JRadar/JCircleRadar）：禁用柱形 option，必须含 radar:{indicator:[]}
• JProgress：专属双 series 结构（前景+背景），无 xAxis，title.show=False
• 条形图（JHorizontalBar/JRankingList/JTotalProgress）：yAxis=category，xAxis=value（轴对调）
• 词云图（JWordCloud/JImgWordCloud/JFlashCloud）：禁用含 xAxis/yAxis 的柱形 option
• DoubleLineBar：yAxis 必须是两元素数组，config 根层必须加 seriesType:[]
• JBar：series 必须含 type:'bar'（禁止传空数组 []）
• 其他（JLine/JStackBar 等坐标轴类）：通用 xAxis/yAxis 对象格式（禁止数组格式）
• analysis：必须是完整结构，禁止传 {}（空 analysis 导致前端访问属性时 TypeError）

'analysis': {'isRawData': True, 'showMode': 1, 'showData': 1, 'showFields': [],
             'isCompare': False, 'compareType': '', 'trendType': '1',
             'compareValue': None, 'izTimeOut': False, 'timeOut': 0}

• sorts: {'name': '', 'type': ''}（必须含 type 键，否则前端排序逻辑报错）
• actionConfig: {'operateType': 'modal', 'modalName': '', 'url': ''}（缺失前端崩溃）
• dataNum: ''、filterField: [...]（从 /online/cgform/field/listByHeadId 过滤后的字段列表）

正确保存方式： query_page → 缓存 _page_components → 循环 add_component → queryById+edit 合并保存 template 和 desJson.height（禁止 save_page 后再单独更新高度）。代码结构同"核心代码结构"章节。

Online 表单字段对象格式（online formType，用于 nameFields/valueFields/typeFields）：

{'fieldName': 'xxx', 'fieldTxt': '显示名', 'fieldType': 'string'|'double'|'int',
 'widgetType': 'text', 'dictCode': '', 'dictField': '', 'dictTable': '', 'dictText': '', 'fieldExtendJson': ''}

设计器表单字段对象格式（design formType，用于 nameFields/valueFields/typeFields）：

# ⚠️ 必须包含 options（完整原始 options）和 fieldShow:True
# 来源：ChartSetModal.vue 第572-579行（设计器 loadField 分支）
{'fieldName': item['model'], 'fieldTxt': item['name'],
 'fieldType': 'string'|'number'|'date',   # 归一化类型
 'widgetType': item['type'],               # 原始控件类型
 'options': item.get('options', {}),       # ⚠️ 必须：原始 options 含 remote/dictCode 等
 'fieldShow': True}                        # ⚠️ 必须：False 时被 allFields.filter() 过滤

设计器表单 filterField 格式（包含系统字段，与 nameFields 格式相同但有额外字段）：

# ⚠️ filterField 必须包含 5 个系统公共字段（来自 constant.ts publicFields 常量）
# 前端 loadField() 第606-615行硬编码追加，和表单本身无关，所有设计器表单都要有
# Online 表单的 filterField 只有 {fieldName, fieldTxt, fieldType, widgetType, dictField}，无 options
PUBLIC_FIELDS_DESIGN = [
    {'fieldName': 'create_by',   'fieldTxt': '创建人',   'fieldType': 'select-user', 'widgetType': 'select-user', 'options': {},                                        'customDateType': '3'},
    {'fieldName': 'update_by',   'fieldTxt': '修改人',   'fieldType': 'select-user', 'widgetType': 'select-user', 'options': {},                                        'customDateType': '3'},
    {'fieldName': 'update_time', 'fieldTxt': '修改时间', 'fieldType': 'date',        'widgetType': 'date',        'options': {},                                        'customDateType': '3'},
    {'fieldName': 'create_time', 'fieldTxt': '创建时间', 'fieldType': 'date',        'widgetType': 'date',        'options': {},                                        'customDateType': '3'},
    {'fieldName': 'bpm_status',  'fieldTxt': '流程状态', 'fieldType': 'select',      'widgetType': 'select',      'options': {'remote': 'dict', 'dictCode': 'bpm_status'}, 'customDateType': '3'},
]
# filterField = [业务字段列表(含options+fieldShow)] + PUBLIC_FIELDS_DESIGN

存储过程快速路径（强制，2 轮完成）

存储过程任务必须走 proc_ops.py bindcomp，禁止手动 pymysql + comp_ops.py 分步执行：

轮次1: Read 凭据 + Bash: cp proc_ops.py comp_ops.py bi_utils.py default_configs.json（并行）
轮次2: py proc_ops.py bindcomp ... && rm proc_ops.py comp_ops.py bi_utils.py default_configs.json && echo URL | clip.exe

示例：

py proc_ops.py bindcomp "<api_base>" "$TOKEN" \
  --page "PAGE_ID" --comp "JCommonTable" --title "Demo数据表格" \
  --x 50 --y 280 --w 900 --h 450 \
  --proc-name "sp_query_demo" \
  --proc-sql "SELECT id, name, sex, age FROM demo ORDER BY create_time DESC" \
  --fields "id:String,name:String,sex:String,age:String" \
  --dict "sex=sex"
# 带参数：追加 --proc-params "IN p_sex varchar(10)" 并在 SQL 中引用 p_sex

proc_ops.py bindcomp 自动完成：获取 DB 连接 → pymysql 创建存储过程 → 验证 CALL → 创建数据集+绑定组件。

执行方式：直接在本 skill 的 references/scripts/ 目录下运行，无需 cp。bi_utils.py 位于上级目录，脚本会自动找到。Claude 执行时根据当前平台构建完整路径（macOS/Linux 用 python3，Windows 用 py）。

多字段页面配置修改必须合并（强制）

修改 2 个及以上页面属性时，禁止逐个调用 page_ops.py，必须编写合并脚本（1 次 query + 修改所有字段 + 1 次 edit）。详见 references/page-config-guide.md。

所有大屏操作以耗时最少为第一优先级（强制）

直接执行；优先预置脚本；并行独立操作；复杂组件从 default_configs.json 加载；理想 2 轮；凭据已知时不重复读取。

耗时目标：

全组件批量生成快速路径（强制）

用户要求"生成全组件大屏"时，直接调用预置脚本 gen_all_comps.py，禁止每次重新 Write 脚本。

预置脚本方式（最优，严格 2 轮）：

凭据已知时：仅1轮
轮次1: cp 3个文件 && ls验证 && py gen_all_comps.py API_BASE TOKEN [页面名] && rm（一条命令）
凭据未知时：2轮
轮次1: Read 凭据
轮次2: cp 3个文件 && ls验证 && py gen_all_comps.py API_BASE TOKEN [页面名] && rm（一条命令）

完整命令：直接在本 skill 的 references/scripts/ 目录下运行，Claude 根据平台自动构建路径和 Python 命令：

python gen_all_comps.py "<api_base>" "TOKEN值" "全组件大屏"

脚本已内置 subprocess clip，URL 自动复制到剪贴板，无需外部 | clip.exe

脚本特性：

• 99 个业务组件（排除 JDragBorder/JDragDecoration/JWeatherForecast）
• 4 列网格布局（440×300，间距 20px），自动计算页面高度（约 8150px）
• 全静态演示数据（从 default_configs.json 加载），无需数据集；传 --ds-id 时绑定指定数据集
• 接受命令行参数（2026-04-09 更新，禁止再 Read 源文件）：

FILES + 已有页面全组件标准命令（3轮完成）：

# <skill_base_dir> = skill 加载时显示的 Base directory for this skill（Windows 路径，Git Bash 下需转为 /c/Users/... 格式）
# 轮次1: 分析Excel列名（openpyxl）+ Read凭据
# 轮次2: cp 4个文件 + ls验证 + 创建数据集（--no-chart）+ 生成全组件 + rm
cp "<skill_base_dir>/references/scripts/files_ops.py" . && \
cp "<skill_base_dir>/references/scripts/gen_all_comps.py" . && \
cp "<skill_base_dir>/references/bi_utils.py" . && \
cp "<skill_base_dir>/references/scripts/default_configs.json" . && \
ls files_ops.py gen_all_comps.py bi_utils.py default_configs.json && \
PYTHONIOENCODING=utf-8 py files_ops.py create-bind API_BASE TOKEN PAGE_ID \
    --files file1.xlsx file2.xlsx --join-on 关联列 --group-by 字段1,字段2 --agg 聚合列 \
    --col-name name --col-type type --col-sales sales --no-chart 2>&1 | tee /tmp/fo.txt && \
DS_ID=$(PYTHONIOENCODING=utf-8 py -c "import re,sys; m=re.search(r'数据集已创建: (\S+)', open('/tmp/fo.txt').read()); print(m.group(1) if m else sys.exit(1))") && \
echo "DS_ID=$DS_ID" && \
PYTHONIOENCODING=utf-8 py gen_all_comps.py API_BASE TOKEN "页面名" \
    --page-id PAGE_ID --ds-id "$DS_ID" --ds-type FILES \
    --ds-name "数据集名称" --ds-fields "name:String,type:String,sales:Integer" && \
rm files_ops.py gen_all_comps.py bi_utils.py default_configs.json

字段映射规则（自动推断，无需手动指定）：

• str_fields[0]（第1个字符串字段）→ 单系列维度 / 表格名称 / 起点名称
• str_fields[-1]（最后一个字符串字段）→ 多系列分组 / 终点名称（与 files_ops.py 的 col_type 一致）
• num_fields[0]（第1个数字字段）→ 数值

核心原则（仅自定义修改脚本时参考）：

1. 必须用 bi_utils.add_component() — 自动处理 config 结构（flat dict → JSON string）、size/chart/turnConfig 等字段
2. _page_components[page_id] = [] 清空缓存 → 批量 add_component → queryById+edit 合并保存
3. chartData 在传入前序列化为 JSON 字符串
4. option.title 可能是 str 类型，需检查后再赋值
5. desJson.height 存页面高度（不是 pageConfig），创建后必须同步更新

关键代码结构（gen_all_comps.py 已封装，自定义时参考）：

# SLOT_CONFIGS: 每种 compType 的槽位标签（严禁自行创建不存在的标签）
# 单系列: ['维度','数值']；多系列: ['分组','维度','数值']；仪表盘: ['总计','已用']
# 表格: ['名称','数值']；飞线: ['起点名称','终点名称']；卡片: ['内容']
# 详细映射见下方 SLOT_CONFIGS 表

# UI-only 不绑数据集
NO_BIND = {'JImg','JCarousel','JCustomIcon','JText','JCurrentTime','JIframe',
           'JDragEditor','JRadioButton','JForm','JPermanentCalendar','JSelectRadio',
           'JTabToggle','JCommon','JVideoPlay','JVideoJs'}

# 批量添加后保存（禁止 save_page，必须 queryById+edit 合并保存 template+desJson）
raw = bi_utils._request('GET', '/drag/page/queryById', params={'id': page_id})
p = raw.get('result') or {}
des = json.loads(p['desJson']) if isinstance(p.get('desJson'), str) else (p.get('desJson') or {})
des['height'] = total_height
bi_utils._request('POST', '/drag/page/edit', data={
    'id': page_id, 'name': p.get('name',''),
    'template': json.dumps(bi_utils._page_components[page_id], ensure_ascii=False),
    'updateCount': p.get('updateCount', 1), 'style': p.get('style','bigScreen'),
    'theme': p.get('theme','dark'), 'backgroundImage': p.get('backgroundImage',''),
    'designType': p.get('designType',100), 'desJson': json.dumps(des, ensure_ascii=False),
})

⚠️ 严禁在批量场景下自行构造 comp dict 并 insert 到 template（必须用 bi_utils.add_component() 处理结构转换）

反模式检查清单（关键禁止项）：

效率违规：

• cp 放在轮次1 而非与 py 同一命令链（轮次2）
• cp 目标路径用 C:/Users/ 格式（Git Bash 静默失败，必须用 /c/Users/... Unix 格式）
• cp 依赖文件和 Write 脚本串行执行（必须同轮并行）
• Bash 中用 shell 变量传参给 py 脚本（变量可能为空，必须内联字面值）
• 写自定义脚本用 bash heredoc（含单引号必报错，必须用 Write 工具）
• 脚本中用拼音替代中文字段名/组件名（显示乱码，必须直接写 Unicode）
• 执行 py 不加 PYTHONIOENCODING=utf-8（Windows GBK 中文必报错）
• comp_ops.py 子命令写在 API_BASE 后面（正确：子命令在最前）
• Python subprocess 用 /c/Users/... 路径（Windows 下无效，提前 cp 到当前目录）
• 多图表+联动场景逐个调 comp_ops.py（应用 multi_chart_linkage.py，节省80%）
• 全组件批量生成超过 2 轮（凭据已知 1 轮：cp+py+rm）
• 生成全组件大屏 Write 脚本（直接 cp gen_all_comps.py 执行）
• 询问数据源后才开始 Write 批量脚本（应在用户确认后同轮并行 Write+cp）
• SQL数据集创建单独一轮，批量图表再一轮（内嵌到批量脚本里）
• save_page() 后再 queryById+edit 更新高度（合并为1次edit，共3次API）
• Read 大型Controller文件直接全文（先 Grep 定位结构，再针对性 Read）
• 凭据已知时 Read 凭据文件（凭据在 MEMORY.md 上下文中）
• 使用预置脚本时读取 dataset-guide.md（已封装，无需读）
• 执行预置脚本前 --help 查看用法

逻辑违规：

• 🚨 singleFile 全流程脚本 add_component 前漏写 query_page + 缓存 _page_components（清空大屏所有组件）
• 🚨 地图组件手工构造 option/commonOption（必须从 default_configs.json 深拷贝）
• 🚨 地图 chartData 格式跨组件套用（各组件格式完全不同，详见 map-guide.md）
• 🚨 设计器表单端点盲猜（固定端点：/desform/api/list/options、/desform/api/fields/{tableName}）
• 🚨 Online表单全组件场景漏写 dataType=4（默认 dataType=0 静态数据，完全不读表单）
• 🚨 批量生成时用 compType 英文代码作 componentName（必须用中文名）
• singleFile 场景用 comp_ops.py --dataset-name 绑定（按索引映射导致字段错乱）
• singleFile 上传后用 result.tableName 提取表名（无此字段，从 result.dbUrl 的 name 取）
• singleFile code 字段去掉 jmf. 前缀（系统拼 SQL 时报错）
• singleFile 文件上传用 bi_utils._request()（不支持 files 参数，必须用 requests.post）
• 直接调用 bi_utils.add_xxx() + save_page() 添加组件（覆盖已有组件，必须用 comp_ops.py add）
• 批量生成 95 个组件逐个调 comp_ops.py（190 次 API vs 2 次，差 95 倍）
• 全局统一 dataMapping（每个组件必须用自己的 SLOT_CONFIGS[comp_type]）
• 批量绑定时用 GET /drag/view/getAllChartData（result 格式不同报 None 错误）
• 批量绑定时 dataMapping.filed 写字段名（filed 是槽位标签，mapping 才是字段名）
• 创建自定义API/Mock数据集后调 queryFieldByApi（字段已知直接传 datasetItemList）
• 全组件生成时为分类生成 JText 标题组件
• 全组件生成时包含 JDragBorder/JDragDecoration/JWeatherForecast
• Online表单全组件场景读取 online-design-form-chart-guide.md（已内联）
• YApi批量：Write脚本后看 yapi list 结果再 Edit（yapi复用逻辑必须内嵌到脚本，按路径完整匹配）
• 🚨 API_BASE 未知时用 curl 探测路径（直接询问用户）
• 用户已给出 API 地址时先探测已有数据集（直接 create-api → add）
• 创建 SQL 数据集时跳过询问数据源
• dataset_ops.py create-api 漏 --code 参数（必填4项：--name/--code/--url/--fields）
• 缺少 fieldOption（前端字段选项面板为空）
• 缺少 dataSetName/dataSetType/dataSetApi/dataSetMethod/dataSetIzAgent/paramOption/viewLoading

交互流程

Step 0: 解析用户需求

Step 0.1: 数据来源确认（强制，用户未明确指定时必须询问）

触发条件： 用户没有明确说明数据来自哪里（没有给出接口地址、没有指定数据集、没有说用 SQL/mock/自己写代码），则必须先问用户以下两个问题，不得擅自假设或跳过：

问题一：接口来源 使用 mock 系统 还是 自己编写代码？ - mock 系统：请提供 mock 服务地址 + 账号密码（如 YApi：https://xxx.com/login） - 自己编写代码：请提供代码存放路径（Java Controller 文件全路径） 问题二：接口需要实现什么业务需求？ 描述各组件要展示的数据内容（参考大屏中的静态数据格式设计接口）

跳过询问： 用户已给出 mock 地址/接口路径/数据集名/数据源，或任务不涉及数据集创建。

Step 0.5: 模板匹配（优先使用模板布局）

生成整个大屏时，必须先匹配模板，复用已有布局。

模板目录：references/templates/bigScreen/（10 个经典大屏模板 JSON）

模板名→文件名索引（直接使用，禁止 Glob 搜索）：

模板选择优先级（强制，按顺序匹配）：

1. 精确匹配 → 从上方关键词表找到直接对应的模板，使用「模板复制方式」创建大屏，保留布局和装饰，仅替换业务数据和标题文字
2. 备选三模板 → 没有精确匹配时，从以下三个模板中选最合适的：

- 北京科技数字化云平台（科技/工业/设备/IoT/能源类） - 北京市污水排放总量（环境/城市/数据监测类） - 医院实时数据监控（机构/人员/综合管理类）

1. 兜底模板 → 以上都不合适时，才选择 集团综合数据大屏

模板复制的详细流程（ID 映射、JTabToggle/JGroup 引用更新、边界检查等）见 references/template-copy-guide.md。

重要：只有在用户明确要求"不使用模板"或"从零创建"时，才跳过模板匹配，直接使用 bi_utils 默认组件函数逐个添加。

Step 1: 识别组件并选择类型

用户说组件名时直接查上方「图表查询与推荐」章节的表格获取 compType，禁止 Grep 搜索源码。所有组件均用 comp_ops.py add --comp <compType> 添加，变体组件加数字后缀（如 JStatsSummary_1/2/3、JScrollList_1/2/3、JCardScroll_1/2/3）。

特殊组件：

JWeatherForecast 天气预报组件（特殊组件，需自定义脚本）

comp_ops.py 不支持 JWeatherForecast，必须用自定义脚本直接操作 template 数组添加。 dataType 必须为 1（自动获取天气数据），不是 0。chartData 为 "[]"。

完整脚本见 references/weather-forecast-guide.md

JSelectRadio 选项卡组件（需自定义脚本实现组件关联）

选项卡的核心功能是「组件可见性控制」：点击不同选项卡，显示/隐藏关联的组件。 comp_ops.py 可以添加基础选项卡，但无法配置 compShowConfig（组件关联），需自定义脚本。 参考文档：https://help.jimureport.com/biScreen/componentconfig/other/tab/

两种显示风格：选项卡样式（默认）、下拉菜单样式

chartData 格式（定义选项卡标签）：

[
  {"label": "折线图", "value": "1"},
  {"label": "柱形图", "value": "2"}
]

核心配置：config.compShowConfig（控制组件显示/隐藏）：

[
  {"selectVal": "1", "compVals": ["目标组件ID_1"]},
  {"selectVal": "2", "compVals": ["目标组件ID_2", "目标组件ID_3"]}
]

显隐逻辑（源码 SelectRadio.vue）：

• 遍历 compShowConfig，对每条规则中 compVals 引用的组件设置 visible = (selectVal == 当前选中值)
• 支持组合组件（JGroup）内部的子组件查找
• 每个选项可关联多个组件同时显示

option 常用配置路径：

完整脚本见 references/select-radio-guide.md（新增关联组件 + 为已有组件添加关联两种场景）

⚠️ 易错点：

Step 2: 展示设计摘要并确认

跳过确认： 用户说「直接生成」/「不用确认」，或模板精确匹配，或同会话中已确认过。

快捷操作：comp_ops.py（增删改查）

⚠️ 添加/编辑/删除组件必须使用 comp_ops.py，严禁直接调用 bi_utils.add_xxx() + save_page()。 原因：bi_utils.add_component() 内部将 _page_components[page_id] 初始化为空列表，save_page 时会用空列表覆盖页面已有的全部组件，造成不可恢复的数据丢失。comp_ops.py 会先加载已有模板再操作，安全无损。

脚本位置：<skill_base_dir>/references/scripts/comp_ops.py

执行方式：直接在本 skill 的 references/scripts/ 目录下运行，无需 cp。bi_utils.py 位于上级目录，脚本会自动找到。Claude 执行时根据当前平台构建完整路径（macOS/Linux 用 python3，Windows 用 py）。

核心命令：

# 查看组件
py comp_ops.py list $API_BASE $TOKEN $PAGE_ID

# 删除组件
py comp_ops.py delete $API_BASE $TOKEN $PAGE_ID --name "组件名"

# 编辑组件属性（单属性）
py comp_ops.py edit $API_BASE $TOKEN $PAGE_ID --name "组件名" --set "option.title.text=新标题"

# 编辑组件属性（多属性：每个属性一个 --set）
py comp_ops.py edit $API_BASE $TOKEN $PAGE_ID --name "胶囊图" --set "option.showValue=true" --set "option.unit=333"

# 添加组件（静态数据）
py comp_ops.py add $API_BASE $TOKEN $PAGE_ID --comp "JBar" --title "柱形图" --x 50 --y 500 --w 450 --h 300

# 一键：创建SQL数据集 + 字典翻译 + 添加图表
py comp_ops.py add $API_BASE $TOKEN $PAGE_ID --comp "JPie" --title "男女比例" --x 735 --y 365 --w 450 --h 350 --create-sql "SELECT sex as name, COUNT(*) AS value FROM demo WHERE sex IS NOT NULL GROUP BY sex" --ds-name "男女比例统计" --fields "name:String,value:String" --dict "name=sex"

# 移动/缩放组件
py comp_ops.py move $API_BASE $TOKEN $PAGE_ID --name "组件名" --x 100 --y 200

⚠️ 数据集默认规则（强制）：用户添加图表时未指明数据集，必须使用静态数据（无额外参数），禁止自动绑定或创建数据集。

⚠️ 标题默认隐藏（强制）：添加图表时，option.title.show 必须设为 false，禁止默认展示标题。

四种数据模式：

⚠️ 带 FreeMarker 动态参数的 SQL 必须用 --sql-file，禁止通过 bash 命令行传递。 原因：${age} 会被 shell 解释为变量（值为空），<#if> 中的 > 会被解释为重定向，导致 SQL 被截断或参数丢失。

动态SQL查询参数完整示例（强制规范）：

# Step 1: 将含 FreeMarker 语法的 SQL 写入文件
cat > sql.txt << 'SQLEOF'
SELECT sex as name, COUNT(*) AS value FROM demo WHERE sex IS NOT NULL
<#if isNotEmpty(age)>
  AND age = '${age}'
</#if>
GROUP BY sex
SQLEOF

# Step 2: 用 --sql-file + --sql-params 创建
py comp_ops.py add $API_BASE $TOKEN $PAGE_ID \
  --comp "JPie" --title "男女比例" --x 735 --y 365 --w 450 --h 350 \
  --sql-file sql.txt --ds-name "男女比例统计" \
  --fields "name:String,value:String" --dict "name=sex" \
  --sql-params "age:年龄::"

# Step 3: 清理
rm sql.txt

FreeMarker 动态条件语法规则（强制）：

--sql-params 格式：paramName:paramTxt:defaultValue:dictCode（后三项可省略，多个逗号分隔）

SQL 含 != 等特殊字符时：同样禁止通过 bash 传递，必须用 --sql-file 或写 Python 脚本在内部定义 SQL。

🚨 组件编写核心原则（等同于人在界面操作，强制）

组件的创建、数据、配置三件事必须按以下方式处理，禁止凭感觉和想象构造任何字段。

原则一：创建组件 = 使用默认配置（先拷贝后定制）

人在界面拖出一个组件，得到的是系统默认配置。脚本中等价操作是：

d = copy.deepcopy(defaults[compType])   # 相当于从面板拖出

禁止跳过这一步直接手写 option dict。

原则二：动态数据格式必须与静态数据格式一致

default_configs.json 中的 chartData 就是该组件的静态数据格式。动态数据（API/SQL 返回的数据）必须与这个格式完全一致，否则组件无法渲染：

# 先看 defaults 里的静态格式
# JBreakRing: [{"value": 1048, "name": "oppo"}, ...]
# 动态数据也必须返回同样的字段名和结构

原则三：修改配置必须先查该组件支持的字段

不能凭感觉猜测字段名。修改任何组件的 option 字段前，必须先找到该组件的配置文档，按以下优先级查找：

1. 有独立配置文档的组件 → 查对应的 references/*-option-config.md（按需加载，上方「按需加载指南」表格中列出）

- 例：JBreakRing → references/break-ring-option-config.md - 例：JStatsSummary → references/stats-summary-option-config.md - 例：JScrollList → references/scroll-list-option-config.md - 例：JTabToggle → references/tab-toggle-option-config.md 等

1. 无独立文档的组件 → 查 references/bi-comp-option-config.md（通用配置速查）
2. 以上都没有 → 在界面操作该配置项，再用 comp_ops.py list 查看实际存储的字段名，或直接读组件的 *Option.vue 源文件确认

禁止：在不知道字段名的情况下凭感觉构造 option，这是导致配置无效或组件不显示的根本原因。

自定义脚本添加图表的强制规则：

1. 🚨 图表 config 必须先从 default_configs.json 深拷贝，再进行定制（强制两步顺序，不可颠倒）： # 第一步：深拷贝完整默认配置（option/chartData/dataMapping 全部来自此处） d = copy.deepcopy(defaults['JBreakRing']) opt = d['option'] # 第二步：在默认结构基础上覆盖需要定制的字段 opt['customColor'] = [...] opt['title']['show'] = False cfg['option'] = opt cfg['dataMapping'] = d['dataMapping'] 严禁跳过第一步直接手写 option dict（手写必然遗漏 series/tooltip/grid 等渲染必需字段，导致组件空白或报错）。default_configs.json 中存有所有组件的完整默认结构，必须以它为基础进行修改，而不是从零构建。
2. 字典翻译用 jimu_dict：/jmreport/dict/* API，不是 /sys/dict/*（系统字典需签名且表不同）
3. dictOptions 从 getAllChartData 获取：创建数据集后调 getAllChartData，将返回的 dictOptions 写入组件 config，禁止手动构建
4. datasetItemList 中绑定 dictCode：如 {'fieldName': 'name',..., 'dictCode': 'sex'} 实现字段级字典翻译

全部预置脚本一览

脚本目录：<skill_base_dir>\references\scripts\（<skill_base_dir> 为 skill 加载时显示的 Base directory for this skill 路径）

通用使用流程：直接在本 skill 的 references/scripts/ 目录下运行，无需 cp。bi_utils.py 位于上级目录，脚本自动找到。Claude 执行时根据平台构建完整路径（macOS/Linux 用 python3，Windows 用 py）。

Step 3: 调用 API 创建大屏

方式一（最优）： template_ops.py copy（cp+执行+rm，2轮） 方式二（复杂）： 自定义脚本，详见 references/template-copy-guide.md

大屏标题规则

• option.card.title 必须为空字符串（避免双重标题）
• 页面主标题用 add_text()，fontSize≥40，fontWeight='bold'，letterSpacing=5

组件字段映射机制三分类（必读，2026-04-21 实测）

判断规则：绑定数据集前先查 default_configs.json 对应组件，根据有无 dataMapping 字段 + option 内容，确定属于哪类。

第一类：dataMapping 槽位机制（标准图表 + 部分列表）

config.dataMapping 是数组，每项 {"filed":"槽位标签","mapping":"字段名"}。槽位标签来自 default_configs.json，禁止自行命名。

第二类：option 内嵌字段映射（无 dataMapping）

这些组件没有 dataMapping，字段映射配置在 option 内部专属字段：

第三类：直接格式消费（无任何显式字段映射）

没有 dataMapping 也没有 option 级字段映射，数据格式由组件固定消费：

常用组件配置路径速查（内联）

以下组件的 option 路径已内联，修改时直接使用，无需读取 bi-comp-option-config.md。

JStatsSummary（统计概览）

JCapsuleChart（胶囊图）

JGauge（仪表盘）

JProgress（进度条-ECharts）

JColorBlock（色块指标卡）

JScrollBoard（轮播表）

图层顺序机制

核心：template 数组索引决定 z-index，不是 orderNum。 索引 0 = 最顶层。

新增组件必须置顶（强制）

新添加的组件必须插入到 template 数组的索引 0 位置（即最顶层），确保不会被已有组件遮挡。 bi_utils.add_component() 已使用 insert(0, comp) 实现自动置顶。自定义脚本操作模板时也必须用 insert(0, comp) 而非 append(comp)。

# 置顶
element = tmpl.pop(target_idx)
tmpl.insert(0, element)
# 保存
bi_utils._page_components[PAGE_ID] = tmpl
save_page(PAGE_ID)

可用快捷函数（bi_utils.py）

页面管理： create_page, query_page, list_pages, save_page, delete_page, recover_page, copy_page

添加组件： add_number, add_chart(JBar/JLine/JPie/JRing/JRose/JFunnel/JRadar/JHorizontalBar/JSmoothLine/JStackBar/JMixLineBar), add_table, add_scroll_table, add_ranking, add_text, add_image, add_gauge, add_liquid, add_countdown, add_border, add_decoration, add_current_time, add_word_cloud, add_color_block, add_progress, add_total_progress, add_component

Step 4: 输出结果

必须将预览地址作为单独一行返回，并用 clip.exe 复制到剪贴板。

⚠️ 每次任务完成后必须输出总耗时（强制）：

• 脚本中：开头记录 import time; t0 = time.time()，末尾输出 print(f'耗时: {time.time()-t0:.1f}s')
• 多轮调用/纯API操作：在最终回复文字末尾补充一行 耗时：约 Xs
• 可利用 API 响应中的 timestamp 字段估算（首尾两次响应时间戳之差）
• 禁止输出每个步骤的耗时，只输出整个任务从开始到结束的总耗时

## 大屏创建成功

- 页面ID：{id}
- 页面名称：{name}
- 组件数量：{count} 个

预览地址：
{API_BASE}/drag/share/view/{id}?token={TOKEN}&tenantId=2

echo -n "{完整URL}" | clip.exe

⚠️ 写了 Java 接口时，脚本末尾必须额外输出（强制）：

# 脚本末尾固定追加此段输出，让用户知道后续操作
print("\n" + "="*60)
print("大屏组件已生成完成！")
print("="*60)
print("\n【API 接口地址】（需重启后端后生效）：")
print(f"  {API_BASE}/drag/mock/xxxFlow")           # 根据实际接口路径替换
print(f"  {API_BASE}/drag/mock/xxxFlowMulti")       # 如有多个接口逐行列出
print("\n【重要提示】请重启 Spring Boot 后端服务！")
print("  重启后 API 数据集将自动拉取接口数据，图表即可显示。")
print("\n【大屏预览地址】")
print(f"  {API_BASE}/drag/share/view/{PAGE_ID}?token={TOKEN}&tenantId=2")
print("="*60)

bi_utils 使用规则（强制）

初始化方式

# 正确：直接赋值模块级全局变量
bi_utils.API_BASE = 'http://...'
bi_utils.TOKEN = '...'

# 错误：没有 init() 方法
# bi_utils.init(API_BASE, TOKEN)  # ← AttributeError

页面数据与组件字段映射（query_page 返回值）

自定义脚本操作模板的正确模式

import bi_utils
bi_utils.API_BASE = '...'
bi_utils.TOKEN = '...'
PAGE_ID = '...'

page = bi_utils.query_page(PAGE_ID)
tmpl = page.get('template', [])  # 已经是 list，不需要 json.loads

# 按组件名查找（字段是 componentName，不是 label/name）
target_idx = next(i for i, c in enumerate(tmpl) if c.get('componentName') == '目标名称')

# 修改后保存
bi_utils._page_components[PAGE_ID] = tmpl
bi_utils.save_page(PAGE_ID)

Windows Python 命令

• 用 py 不是 python（Git Bash 下 python 找不到）
• 必须加 PYTHONIOENCODING=utf-8 前缀（Windows 默认 GBK 编码，脚本中含 emoji（✅⚠️等）或中文输出时报 UnicodeEncodeError: 'gbk' codec can't encode character。所有 py script.py 调用必须写成 PYTHONIOENCODING=utf-8 py script.py，且脚本内部 print 禁止使用 emoji 字符）

快捷操作：linkage_ops.py（组件联动/钻取）

组件联动 = 点击源组件，将参数传递给目标组件的数据集查询参数，目标组件自动刷新数据。

脚本位置：<skill_base_dir>/references/scripts/linkage_ops.py

执行方式：直接在本 skill 的 references/scripts/ 目录下运行，无需 cp。bi_utils.py 位于上级目录，脚本会自动找到。Claude 执行时根据当前平台构建完整路径（macOS/Linux 用 python3，Windows 用 py）。

核心命令：

# 查看页面所有联动配置
py linkage_ops.py show $API_BASE $TOKEN $PAGE_ID

# 添加联动（--mapping 格式：src=tgt，多个逗号分隔）
py linkage_ops.py add-linkage $API_BASE $TOKEN $PAGE_ID --source "源组件名" --target "目标组件名" --mapping "value=age"
py linkage_ops.py add-linkage $API_BASE $TOKEN $PAGE_ID --source "柱形图" --target "饼图" --mapping "name=name,value=keyword"

# 删除联动
py linkage_ops.py remove-linkage $API_BASE $TOKEN $PAGE_ID --source "源组件名" --target "目标组件名"

# 添加钻取（自刷新下钻，--comp 为源组件，无 --target；钻取是组件对自身的递归查询，不是跨组件）
py linkage_ops.py add-drill $API_BASE $TOKEN $PAGE_ID --comp "组件名" --mapping "name=year"
# 多级钻取（逗号分隔，第1级用 drillData[0]，第2级用 drillData[1]）
py linkage_ops.py add-drill $API_BASE $TOKEN $PAGE_ID --comp "组件名" --mapping "name=year,name=month"

# 删除钻取
py linkage_ops.py remove-drill $API_BASE $TOKEN $PAGE_ID --comp "组件名"

联动 vs 钻取核心区别（务必记住）：

三级钻取完整配置示例（年→月→日）：

# 1. API端点需根据参数返回不同层级数据：
#    无参数 → 年数据；?year=xxx → 月数据；?month=xxx → 日数据
# 2. 数据集 URL 含 FreeMarker 占位符
DRILL_API = f"{API_BASE}/drag/mock/drillYearMonthDay?year=${{year}}&month=${{month}}"
# 3. drillData 配置两级映射
cfg['drillData'] = [
    {'source': 'name', 'target': 'year'},   # 第1级：点击年份 → 传 year 参数
    {'source': 'name', 'target': 'month'},  # 第2级：点击月份 → 传 month 参数
]
# 4. paramOption 声明参数（供前端识别）
cfg['paramOption'] = [
    {'text': '年份', 'value': 'year',  'paramType': '3', 'paramTxt': '年份', 'paramValue': '', 'isRequired': '0'},
    {'text': '月份', 'value': 'month', 'paramType': '3', 'paramTxt': '月份', 'paramValue': '', 'isRequired': '0'},
]

⚠️ 上方多条 drillData 方案仅适用于 API 数据集。SQL 数据集三级钻取必须用下方「单参数编码值」方案，原因见踩坑。

🚨 SQL 数据集多级钻取：必须用单参数编码值方案（实测 2026-04-17）

根本原因： 前端点击时会同时触发所有 drillData 条目，而非按层级逐条执行。 配置 name→year, name→month 两条时，点击年份柱（如 2023）会同时设置 year="2023" 和 month="2023"，SQL 误判进入日级查询，sale_month=2023 无数据。

正确方案：单参数 drill_val + 编码值

SQL 模板（FreeMarker，实测可用）：

⚠️ 禁止用 drill_val?contains("-") 判断层级：日级值 "2024-06-01" 也含 -，点击日柱后 SUBSTRING_INDEX(...,'-',-1) 取到 "01"（日），被误当 sale_month=1，显示错误数据。必须用 drill_val?length 精确区分。

<#if isNotEmpty(drill_val) && drill_val?length gt 7>
-- 日级再点击（drill_val="2024-06-01"，length=10）→ 重新显示同月各日，停止下钻
SELECT CONCAT(SUBSTRING_INDEX('${drill_val}','-',2),'-',LPAD(sale_day,2,'0')) as name,
       ROUND(SUM(total_amount),0) as value
FROM sales_table
WHERE sale_year  = CAST(SUBSTRING_INDEX('${drill_val}','-',1) AS UNSIGNED)
  AND sale_month = CAST(SUBSTRING_INDEX(SUBSTRING_INDEX('${drill_val}','-',2),'-',-1) AS UNSIGNED)
GROUP BY sale_day ORDER BY sale_day
<#elseif isNotEmpty(drill_val) && drill_val?length gt 4>
-- 月级（drill_val="2024-06"，length=7）→ 显示该月各日
SELECT CONCAT('${drill_val}','-',LPAD(sale_day,2,'0')) as name,
       ROUND(SUM(total_amount),0) as value
FROM sales_table
WHERE sale_year  = CAST(SUBSTRING_INDEX('${drill_val}','-',1) AS UNSIGNED)
  AND sale_month = CAST(SUBSTRING_INDEX('${drill_val}','-',-1) AS UNSIGNED)
GROUP BY sale_day ORDER BY sale_day
<#elseif isNotEmpty(drill_val)>
-- 年级（drill_val="2024"，length=4）→ 显示该年各月
SELECT CONCAT('${drill_val}','-',LPAD(sale_month,2,'0')) as name,
       ROUND(SUM(total_amount),0) as value
FROM sales_table
WHERE sale_year = ${drill_val}
GROUP BY sale_month ORDER BY sale_month
<#else>
-- 初始（drill_val=""）→ 显示各年汇总
SELECT sale_year as name,
       ROUND(SUM(total_amount),0) as value
FROM sales_table
GROUP BY sale_year ORDER BY sale_year
</#if>

三个层级的 drill_val 长度规律（固定格式）：

drillData + paramOption 配置（单条）：

cfg['drillData'] = [{'source': 'name', 'target': 'drill_val'}]
cfg['paramOption'] = [
    {'text':'下钻键','value':'drill_val','paramType':'3',
     'paramTxt':'下钻键','paramValue':'','isRequired':'0'}
]

关键点：

• drill_val?contains("-") 是标准 FreeMarker 字符串内建，JimuBI 支持 ✅
• CONCAT 中必须用 '${drill_val}'（加引号），不能用裸 drill_val（会被当 SQL 列名报错）
• 年份上下文编码在值中（"2024-06" 同时含年和月），无需多参数传递

⚠️ 易错点（强制记忆）：

联动前提： 目标组件已绑定数据集且 SQL/URL 含对应查询参数。钻取前提： 自身数据集 URL 含 FreeMarker 参数，API 端点能返回不同层级数据。

快捷操作：组件连线（linesConfig.connectLine）

仅 JImg 支持连线，JCustomIcon 不支持。linesConfig 在 config 顶层（与 option 同级）。 完整结构、枚举值、脚本见 references/connect-line-guide.md

核心结构： config.linesConfig = {"connectLine": [{"sourceId","targetId","startPosition","endPosition","lineType","lineColor","lineWidth"}], "show": false}

默认值： startPosition/endPosition=AutoDefault，lineWidth=3，lineType=Straight，lineColor=#75cede

操作流程（2 轮）：

轮次1: cp bi_utils.py + Write connect_line.py（并行）
轮次2: PYTHONIOENCODING=utf-8 py connect_line.py && rm connect_line.py bi_utils.py

易错点： linesConfig 不在 option 内；config 必须 json.dumps() 序列化；targetId 用 UUID 不用组件名；必须含 "show": false

快捷操作：link_ops.py（外部链接跳转）

组件外部链接 = 点击图表跳转到外部 URL，并将点击参数带到链接地址上。

脚本位置：<skill_base_dir>/references/scripts/link_ops.py

执行方式：直接在本 skill 的 references/scripts/ 目录下运行，无需 cp。bi_utils.py 位于上级目录，脚本会自动找到。Claude 执行时根据当前平台构建完整路径（macOS/Linux 用 python3，Windows 用 py）。

核心命令：

# 查看页面所有外部链接配置
py link_ops.py show $API_BASE $TOKEN $PAGE_ID

# 设置外部链接（按名称/类型/ID 三选一定位组件）
py link_ops.py set $API_BASE $TOKEN $PAGE_ID --name "饼图名" --url "https://www.baidu.com/s?wd=\${name}&value=\${value}"
py link_ops.py set $API_BASE $TOKEN $PAGE_ID --type "JPie" --url "https://example.com/detail?category=\${name}"
py link_ops.py set $API_BASE $TOKEN $PAGE_ID --id "538804ec..." --url "https://www.baidu.com/s?wd=\${name}" --target "_self"

# 删除外部链接
py link_ops.py remove $API_BASE $TOKEN $PAGE_ID --name "饼图名"

URL 参数占位符（来自 ECharts 点击事件 params）：

打开方式（--target）： _blank（新窗口，默认）、_self（当前窗口）

原理： config.linkType='url' + turnConfig={url,type}，前端从 ECharts params 替换 ${...} 后跳转。

快捷操作：自定义JS脚本（config.jsConfig）

自定义JS脚本 = 点击组件时执行 JS 代码，实现自定义跳转、弹窗等逻辑。 参考文档：https://help.jimureport.com/biScreen/base/interactive/customJS

存储字段：config.jsConfig（字符串）。执行顺序：jsConfig → (return true?) → 外部链接 → 联动 → 钻取。return false 阻断后续。

脚本参数 params 常用属性（ECharts 图表）：

更多属性参考 ECharts 事件文档

设置方式（三种，按复杂度选择）：

# 方式1：link_ops.py set-js（推荐，支持多行脚本）
py link_ops.py set-js $API_BASE $TOKEN $PAGE_ID --name "基础柱形图" --js 'window.open("http://jeecg.com");return false;'

# 方式1b：从文件读取复杂脚本
py link_ops.py set-js $API_BASE $TOKEN $PAGE_ID --type "JBar" --js-file script.js

# 方式2：comp_ops.py edit（简单单行脚本）
py comp_ops.py edit $API_BASE $TOKEN $PAGE_ID --name "基础柱形图" --set "jsConfig=window.open(\"http://jeecg.com\");return false;"

# 方式3：自定义 Python 脚本（需要精确控制换行符等）
# cfg['jsConfig'] = 'window.open("http://jeecg.com");\nreturn false;'

# 查看页面所有自定义JS脚本配置
py link_ops.py show $API_BASE $TOKEN $PAGE_ID    # show 命令同时展示外部链接和JS脚本

# 删除自定义JS脚本
py link_ops.py remove-js $API_BASE $TOKEN $PAGE_ID --name "基础柱形图"

常用脚本示例：

// 跳转到外部网站（带点击参数）
window.open("https://example.com/detail?name=" + params.name + "&value=" + params.value);
return false;

// 条件跳转
if (params.value > 100) {
  window.open("https://example.com/high?name=" + params.name);
} else {
  window.open("https://example.com/low?name=" + params.name);
}
return false;

核心踩坑速查

完整踩坑记录见 references/pitfalls.md

JCustomIcon 图标组件说明

来源： 源码 customIcon.vue + constant.ts（maxJCustomIconNum=36）实测确认，2026-04-21

设计器左侧面板「图标」区域分两个 Tab，对应完全不同的组件类型：

JCustomIcon 正确配置方式

cfg = {
    'type': '05',       # 核心字段：01~36，决定显示哪个系统 iconfont 图标
    'dataType': 1,
    'option': {
        'color': '#ffffff',   # 图标颜色
        'opacity': 1,         # 不透明度 0~1
        'filter': 0,          # 模糊 0~20
    }
}

⚠️ 禁止在 JCustomIcon 上设置 option.icon/option.iconId/option.imageUrl 等字段 —— 这些字段在组件里完全不生效，组件只认 config.type。

图库图片应用 JImg 组件添加，不是 JCustomIcon。

图库管理（Icon Library）

接口清单

新增图标完整流程

⚠️ 必须用 urllib.request 直接调用，不能用 bi_utils._request（会 401）

import urllib.request, json
BASE = "<api_base>"; TOKEN = "<token>"
# Step 1: 上传图片（multipart）→ 取 result["message"] 得 image_url
boundary = "----FormBoundary7MA4YWxkTrZu0gW"
with open(r"图片路径.jpg", "rb") as f: file_data = f.read()
body = (f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"img.jpg\"\r\nContent-Type: image/jpeg\r\n\r\n").encode() + file_data + f"\r\n--{boundary}--\r\n".encode()
req = urllib.request.Request(f"{BASE}/jmreport/upload", data=body, headers={"X-Access-Token": TOKEN, "Content-Type": f"multipart/form-data; boundary={boundary}"}, method="POST")
image_url = json.loads(urllib.request.urlopen(req).read())["message"]
# Step 2: 新增到图标库
data = json.dumps({"imageUrl": image_url, "name": "图标名称", "type": "common"}).encode()
req2 = urllib.request.Request(f"{BASE}/drag/jimuReportIconLib/add", data=data, headers={"Content-Type": "application/json", "X-Access-Token": TOKEN}, method="POST")
print(json.loads(urllib.request.urlopen(req2).read()))

字段说明： imageUrl=上传返回的 message；name=用户提供；type=固定 "common"

错误处理

参考文档

• references/bi-component-types.md — 完整组件类型清单
• references/bi-comp-option-config.md — 组件样式配置路径
• references/bi_utils.py — 工具库源码
• references/core-configs/data.ts — 组件面板菜单树 + 初始化 config（原始源码，353KB）
• references/core-configs/optionData.ts — 组件属性面板配置项列表（原始源码，57KB）
• references/core-configs/component-defaults.md — 82+ 组件默认配置速查（尺寸/chartData/option/dataMapping）
• references/core-configs/addPageComp-logic.md — 组件创建流程（addPageComp 函数、newItem 结构、位置计算）
• references/core-configs/menu-hierarchy.md — 组件菜单分类树（完整层级 + 统计）
• references/templates/bigScreen/ — 10 个大屏模板 JSON
• references/scripts/ — 12 个预置操作脚本 + default_configs.json