@qingflow-tech/qingflow-cli 1.0.38 → 1.0.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,13 +3,13 @@
3
3
  Install:
4
4
 
5
5
  ```bash
6
- npm install @qingflow-tech/qingflow-cli@1.0.38
6
+ npm install @qingflow-tech/qingflow-cli@1.0.40
7
7
  ```
8
8
 
9
9
  Run:
10
10
 
11
11
  ```bash
12
- npx -y -p @qingflow-tech/qingflow-cli@1.0.38 qingflow
12
+ npx -y -p @qingflow-tech/qingflow-cli@1.0.40 qingflow
13
13
  ```
14
14
 
15
15
  Environment:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.0.38",
3
+ "version": "1.0.40",
4
4
  "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "qingflow-mcp"
7
- version = "1.0.38"
7
+ version = "1.0.40"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -26,7 +26,7 @@ description: |
26
26
  | [reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) | **搭建侧·应用交付 SOP**(**创建/改造应用底色**:解析包与应用、读写字段布局流程、一键改 schema·layout·flow、按钮与关联资源、**`publish verify`**):`app_get` 应用地图 → `app_resolve` → `app_read_*` → **`schema`/`layout`/`flow apply`** / **`app_custom_buttons_apply`** / **`app_associated_resources_apply`**;字段 JSON 支持 **`as_data_title` / `as_data_cover`** |
27
27
  | [reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md) | **搭建侧·工作区图标**:`builder icon catalog`;新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color`,CLI 只校验候选,不按业务名自动映射 |
28
28
  | [reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md) | **搭建侧·业务视图 SOP**:`app_get` / `app get fields|views` → **`builder views apply`**;区分 `filters` 与 **`query_conditions`**;关联视图/报表走 **`app_associated_resources_apply`**,按钮走 **`app_custom_buttons_apply`** |
29
- | [reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md) | **搭建侧·门户工作台 SOP**(**工作台/门户页面搭建、发布与删除**):**`portal list/get/apply/delete`**、**`--publish`**;删除结果要区分 `delete_executed` 与 `readback_status`;**`filter`** 的 CLI 限制见该文 §3.4;示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json);契约 **`builder contract --tool-name portal_apply` / `portal_delete`** |
29
+ | [reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md) | **搭建侧·门户工作台 SOP**(**工作台/门户页面搭建、发布与删除**):**`portal list/get/apply/delete`**、**`--publish`**;删除结果要区分 `delete_executed` 与 `readback_status`;**`filter`** 的 CLI 限制见该文 §3.4;推荐模板示例 [portal_sections_standard_workbench.example.json](./reference/portal_sections_standard_workbench.example.json),稳定五类示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json);契约 **`builder contract --tool-name portal_apply` / `portal_delete`** |
30
30
  | [reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) | **搭建侧·报表 QingBI/BI SOP**(**系统内报表/图表的创建、改配与排序**):**`charts apply`**;应用源报表创建/更新、数据集报表仅关联已有、扩展图表类型与特殊字段映射、**immediate-live** 与 **`publish verify`** 关系见该文;示例 [charts_upsert_minimal.example.json](./reference/charts_upsert_minimal.example.json) 等 |
31
31
  | [reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md) | **搭建侧·字段匹配规则**:按钮新增数据 `field_mappings`、关联视图/报表 `match_mappings`、`数据ID(-17)` / `编号(0)`、类型兼容与 `associated_item_id` 口径。 |
32
32
  | [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**:默认转交 `qingflow-record-insert`;标准链路 `record_insert_schema_get -> record_insert(items)`,CLI 用 **`record insert --items-file`**;成员/部门/关联优先自然语言输入 |
@@ -419,7 +419,7 @@ qingflow auth logout --forget-persisted
419
419
  | **app / portal / view / chart** | `app list [--query 关键词]` → **`app get --app-key`**(`accessible_views` / `view_id`、`import_capability`)· `builder package list [--query 关键词]` → `builder package get --package-id` · `portal list` · `portal get --dash-key` · `view get --view-id`(只读视图元信息;`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级,非权限类后端错误不隐藏;解析 app 仅依赖同源 view/form 与可见应用树,不回退旧应用搜索)· `chart get --chart-id`(图表 `baseInfo` / 数据 / 配置分阶段读取;单个辅助阶段 40002 / 40027 / 404 只作为 warning,非权限类后端错误不隐藏) |
420
420
  | **record** | `record schema insert`(新建记录 insert-ready schema,仅 `--app-key`)· **`browse`/`list`/`access`:`--app-key` + `--view-id`(缺一常 CONFIG)** · `record list --query ... [--query-field FIELD_ID] [--page-size N]` 用于候选定位/样本浏览 · `record get --record-id` 读详情页首屏上下文 · `record logs --record-id` 读完整数据/流程日志 JSONL · `record insert --items-file`(单条也是 items 一行)· `schema update --record-id [--view-id]` / **`update`**(单条 `--fields-file` **或** 批量 `--items-file`/`--dry-run`,二者勿混)· `export start/direct --view-id` 仅用于明确导出文件 · **`delete`/大 schema**:先 **[FIELD_DATA_TYPES](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**,再 `-h` |
421
421
  | **import** | `record schema import?` · `import template` → `verify` → `repair?` → `start`(**`being-enter-auditing` 必填**)→ `status`(**三者 selector 只选一**);导入权限预检的 `baseInfo` 只有 40002 / 40027 / 404 可降级为 unknown,非权限错误不能当成无导入权或继续执行;**链路与本机目录**只靠本节不够 → **[RECORD_IMPORT](./reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
422
- | **builder** | **搭建/系统化配置**:先读 `builder contract`。**完整系统/应用包**:`builder package apply --config-file` → `builder schema apply --apps-file`(`--apps-file` 可为数组或 `{package_id, apps}` 对象;同批 relation 用 `target_app_ref` 或 `target_app`)→ layout/views/flow/portal/charts。**单应用**:`app resolve/get` → `schema/layout/flow/views apply`。图标可用 `icon/color`、`icon_name/icon_color`、`icon_config` 或 `icon:{name,color}`;选择字段 `options` 可用字符串数组或 `{label,value}` 对象数组。与普通读数/`record insert` 不是同一路径 → **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**、[ICONS](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md)、[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)、[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)、[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) |
422
+ | **builder** | **搭建/系统化配置**:先读 `builder contract`。**完整系统/应用包**:`builder package apply --config-file` → `builder schema apply --apps-file`(主写法为 `{package_id, apps}` 对象;raw apps array / singleton wrapper array 仅兼容;同批 relation 用 `target_app_ref` 或 `target_app`)→ layout/views/flow/portal/charts。**单应用**:`app resolve/get` → `schema/layout/flow/views apply`。图标主写 `icon/color`;`icon_name/icon_color`、`icon_config`、`icon:{name,color}` 仅兼容/读回。选择字段 `options` 可用字符串数组或 `{label,value}` 对象数组。与普通读数/`record insert` 不是同一路径 → **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**、[ICONS](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md)、[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)、[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)、[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) |
423
423
  | **task**(须落盘见上文) | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`(**枚举、`--query`、与 `record` 视图口径勿混**:见上文 SOP · **[TASK_CONTEXT](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**)· **`get`/`log`/`report`/`action`**:默认只传 `task list` 返回的 **`data.items[].task_id`**;`report` 另须必选 **`--report-id`**;`action` **无 `--dry-run`** |
424
424
 
425
425
  **高发必败**:旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
@@ -138,37 +138,43 @@ qingflow builder schema apply \
138
138
  --apps-file tmp/apps.json
139
139
  ```
140
140
 
141
- `apps.json` 可以是数组,也可以是 `{ "package_id": 123, "apps": [...] }` 对象。每个 `apps[]` 是一个应用 schema 配置;同批应用之间的关联字段用 `target_app_ref` 指向另一个应用的 `client_key`,或用 `target_app` 指向另一个 `app_name`:
141
+ `apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`。CLI 兼容 raw apps array 和 singleton wrapper array,但不作为智能体主示例;不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置,写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields`;同批应用之间的关联字段用 `target_app_ref` 指向另一个应用的 `client_key`,或用 `target_app` 指向另一个 `app_name`:
142
142
 
143
143
  ```json
144
- [
145
- {
146
- "client_key": "employee",
147
- "app_name": "员工花名册",
148
- "icon": {"name": "business-personalcard", "color": "emerald"},
149
- "add_fields": [
150
- {"name": "员工名称", "type": "text", "as_data_title": true}
151
- ]
152
- },
153
- {
154
- "client_key": "worklog",
155
- "app_name": "工时表",
156
- "icon": {"name": "clock", "color": "blue"},
157
- "add_fields": [
158
- {"name": "工时标题", "type": "text", "as_data_title": true},
159
- {
160
- "name": "关联员工",
161
- "type": "relation",
162
- "target_app_ref": "employee",
163
- "display_field": {"name": "员工名称"},
164
- "visible_fields": [{"name": "员工名称"}]
165
- }
166
- ]
167
- }
168
- ]
144
+ {
145
+ "package_id": 123,
146
+ "apps": [
147
+ {
148
+ "client_key": "employee",
149
+ "app_name": "员工花名册",
150
+ "icon": "business-personalcard",
151
+ "color": "emerald",
152
+ "add_fields": [
153
+ {"name": "员工名称", "type": "text", "as_data_title": true}
154
+ ]
155
+ },
156
+ {
157
+ "client_key": "worklog",
158
+ "app_name": "工时表",
159
+ "icon": "clock",
160
+ "color": "blue",
161
+ "add_fields": [
162
+ {"name": "工时标题", "type": "text", "as_data_title": true},
163
+ {
164
+ "name": "关联员工",
165
+ "type": "relation",
166
+ "target_app_ref": "employee",
167
+ "display_field": {"name": "员工名称"},
168
+ "visible_fields": [{"name": "员工名称"}]
169
+ }
170
+ ]
171
+ }
172
+ ]
173
+ }
169
174
  ```
170
175
 
171
176
  - 返回里看 `mode=multi_app`、`apps[].app_key`、`created_app_keys` 和 `apps[].status`。
177
+ - 如果 CLI 看到 `[{ "package_id": 123, "apps": [...] }]`,会自动展开并返回 `APPS_FILE_WRAPPER_ARRAY_UNWRAPPED` warning;这是兼容路径,后续仍应改回对象形态。
172
178
  - 多应用 schema apply 不做事务回滚;如果部分失败,只补失败的 `apps[].row_number`,不要整批重复提交。
173
179
  - 这个模式只负责应用壳与字段;视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
174
180
  - 同批 `relation` 优先用 `target_app_ref` 指向 `client_key`;也可用 `target_app` 指向同批 `app_name`。不要先分别建应用、再为了补 `target_app_key` 做第二轮字段修补。
@@ -65,6 +65,8 @@ qingflow --json builder charts apply \
65
65
 
66
66
  **报表筛选 operator**:推荐使用 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`;兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名。CLI 会自动转成 QingBI 字符串判断符(如 `equal`、`anyMatch`、`isNull`)和 BI 前端需要的 `judgeValue` 文本值;单选/多选筛选入参可传选项文本或 option id,CLI 会按 QingBI 路径转成文本。智能体不要手写 `judgeType`、`judgeValue`、`beforeAggregationFilterMatrix`。
67
67
 
68
+ **读回语义**:`builder chart get` / `chart_get` 会返回语义化 `filters`(`field_name` / `operator` / `values`);`config.beforeAggregationFilterMatrix` 仅作为 raw 诊断,不作为智能体更新主输入。
69
+
68
70
  示例:
69
71
 
70
72
  ```json
@@ -89,14 +89,57 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
89
89
  | 场景 | PC 写法 |
90
90
  |------|---------|
91
91
  | 不确定布局 | **省略 `position`**,或传 **`--layout-preset auto`** |
92
- | 两列大屏 | **`x=0/12, cols=12`**,图表 **`rows >= 6`** |
93
- | 三列大屏 | **`x=0/8/16, cols=8`**,图表 **`rows >= 6`** |
94
- | 四个指标卡 | **`x=0/6/12/18, cols=6`**,指标卡可较矮 |
95
- | 趋势图 / 表格 / 明细视图 | 优先 **`cols=12`** 或 **`cols=24`** |
92
+ | 两列可视化图表 | **`x=0/12, cols=12`**,图表 **`rows >= 7`** |
93
+ | 三列可视化图表 | **`x=0/8/16, cols=8`**,图表 **`rows >= 7`** |
94
+ | 四个指标卡 | **`x=0/6/12/18, cols=6, rows=5`** |
95
+ | 具体数据视图 / 明细表 | 优先 **`cols=12`** 或 **`cols=24`**,视图 **`rows >= 11`** |
96
96
 
97
97
  mobile 写法固定按 **6 栅格**:通常 **`x=0, cols=6`**。如果只写了 PC position,CLI 会自动补 mobile position,并返回 **`PORTAL_MOBILE_POSITION_MISSING`** 提醒。
98
98
 
99
- 图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**;普通图表建议 **`pc.cols >= 8` 且 `pc.rows >= 6`**。
99
+ 图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**;指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验,普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。
100
+
101
+ ### 3.1.2 推荐门户模板:业务工作台
102
+
103
+ 默认按 **业务入口 → 核心指标 → BI 可视化 → 业务视图** 搭建。门户首屏应直接呈现可用工作台,不要做营销页、说明页或大面积装饰区。
104
+
105
+ | 区域 | 推荐组件 | PC 布局 | 要点 |
106
+ |------|----------|---------|------|
107
+ | 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`;待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口;待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`,不要伪造;见下方边界说明。 |
108
+ | 核心指标 | **`chart`** 指标卡 | 4 张:`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`,所以一行 4 张最稳;如果要 5 个指标,拆成两行。 |
109
+ | BI 可视化 | **`chart`** 图表 | 3 张:`x=0/8/16,y=9,cols=8,rows=7`;或 2 张:`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**,一行 2-3 个,1-2 行。 |
110
+ | 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`;或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**,一行 1-2 个,1-2 行。只挂业务视图,不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
111
+
112
+ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols=6`,`y` 按 PC 顺序递增。若顶部同时有 `grid + task`,mobile 建议先业务入口 `y=0,rows=4`,再待办 `y=4,rows=4`,核心指标从 `y=8` 开始;若当前公开 CLI 只能写 `grid`,核心指标可从 `y=4` 开始。
113
+
114
+ **当前工具边界**:
115
+
116
+ - 公开 `sections-file` 稳定支持:**`grid` / `chart` / `view` / `text` / `link`**;`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理,不作为主路径。
117
+ - **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状,不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`;只有工具后续显式支持 `task`,或维护者走 raw 门户写入链路时,才使用待办槽位。
118
+ - 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件,顶部先用一个业务入口 `grid` 占满 24 栅格;如果工具已支持待办组件,再把顶部拆成 `grid cols=12 + task cols=12`。
119
+
120
+ **待办组件 raw 形状参考**(仅用于工具实现对齐,当前不要作为 `--sections-file` 输入):
121
+
122
+ ```json
123
+ {
124
+ "type": 8,
125
+ "position": {
126
+ "pc": {"x": 12, "y": 0, "cols": 12, "rows": 4},
127
+ "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 4}
128
+ },
129
+ "taskConfig": {
130
+ "beingShowTitle": true,
131
+ "componentTaskTitle": "待办",
132
+ "beingShowHint": true,
133
+ "componentTaskHint": "及时处理待办,可以有效提升流程效率",
134
+ "dashTaskConfigList": [
135
+ {"type": 1, "title": "all.taskTodo", "beingCheck": true, "ordinal": 0},
136
+ {"type": 2, "title": "all.taskTimeout", "beingCheck": true, "ordinal": 1},
137
+ {"type": 3, "title": "all.taskUpcomingTimeout", "beingCheck": true, "ordinal": 2},
138
+ {"type": 4, "title": "all.taskRemind", "beingCheck": true, "ordinal": 3}
139
+ ]
140
+ }
141
+ }
142
+ ```
100
143
 
101
144
  ### 3.2 `source_type` ↔ 回读 `components[].type`(搭建侧)
102
145
 
@@ -190,6 +233,8 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
190
233
  | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
191
234
  | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
192
235
 
236
+ **推荐工作台模板示例**:[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)
237
+
193
238
  **含 `filter` 的六类示例(`filter` 是否落库视环境/后端而定)**:[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
194
239
 
195
240
  ---
@@ -160,6 +160,7 @@ CLI 将参数与文件内容拼装为服务层载荷,**顶层键**如下:
160
160
  - `view_configs[].view_key` 使用 raw `view_key`,不要加 `custom:`。
161
161
  - `view_configs[].mode` 默认 `merge`;merge 模式必须带 `buttons`,不要只传 `view_key`。清空绑定用 `mode: "replace"` 或显式 `buttons: []`。
162
162
  - 对外入参仍写 `placement=list`;CLI 会映射为后端 `INSIDE` 行内/列表按钮。
163
+ - 按钮显示条件 `button_limit` 使用统一条件写法:`field_name + operator + value/values`。不要手写后端 `judgeType` / `judgeValues`。
163
164
  - 权限分界:按钮本体增删改需要 **EditAppAuth**;只要同次包含 `view_configs` 写视图按钮位置,还需要 **ViewManagementAuth**(未开启高级应用权限时回落到 **DataManageAuth**)。
164
165
 
165
166
  `app_views_apply.buttons` 仅作为旧配置维护兼容:
@@ -17,7 +17,8 @@ qingflow --json builder icon catalog
17
17
  ## 关键规则
18
18
 
19
19
  - CLI 不会根据业务名称自动猜图标。
20
- - 智能体必须自己选择业务贴合的图标和颜色;CLI/MCP 可接受 `icon + color`、`icon_name + icon_color`、`icon_config` 或 `icon: {name, color}`,最终都会归一化为 `icon/color`。
20
+ - 智能体必须自己选择业务贴合的图标和颜色;主写法只有 `icon + color`,例如 `"icon": "table", "color": "blue"`。
21
+ - CLI/MCP 继续兼容 `icon_name + icon_color`、`icon_config` 或 `icon: {name, color}`,但这些只用于历史载荷和读回适配,不作为新提示词示例。
21
22
  - 创建应用包、应用、门户时缺少 `icon` 或 `color` 会失败。
22
23
  - 同批多应用创建时,每个新应用应使用不同 `icon`。
23
24
  - 编辑已有资源时,不传 `icon/color` 会保留现状;显式传入时仍会校验合法性。
@@ -1,7 +1,7 @@
1
1
  # `app_schema_apply` / `builder schema apply`:字段类型与场景总表
2
2
 
3
3
  > **口径**:`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**(及包内 `PublicFieldType`)为准;**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**(`builder_facade/models.py`)与 **`app_schema_apply` 编排**(`builder_facade/service.py`)为准。
4
- > **CLI**:`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用数组] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`;**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀,并把 `--profile` 放在 `builder` 之前。
4
+ > **CLI**:`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用对象] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`;**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀,并把 `--profile` 放在 `builder` 之前。
5
5
  > **新建应用主规则**:`add_fields[]` 里必须有且仅有一个顶层字段标记 `as_data_title: true`;数据封面可选,只能在顶层 `attachment` 字段标记 `as_data_cover: true`。
6
6
  > **权限**:包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**;已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
7
7
 
@@ -58,7 +58,7 @@
58
58
  |------|----------------|------|
59
59
  | 编辑已有应用 | `--app-key`;可选 `--no-publish` | **不要**与 `--package-id`、`--create-if-missing` 同用 |
60
60
  | 包内新建应用 | `--package-id`、`--app-name`(或 title 映射)、**`--create-if-missing`**;初始 `add-fields-file` 至少包含一个 `as_data_title: true` 字段 | 创建后可得到新 **`app_key`**(以响应为准) |
61
- | 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用,或同批应用之间有 `relation` 时使用;`--apps-file` 可为数组或 `{package_id, apps}` 对象;`apps[].client_key` 可被 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用 |
61
+ | 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用,或同批应用之间有 `relation` 时使用;`--apps-file` 主写法为 `{package_id, apps}` 对象,raw apps array / singleton wrapper array 仅兼容;`apps[].client_key` 可被 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用 |
62
62
  | 仅增字段 | `--add-fields-file`(JSON 数组) | 与 **`update_fields`/`remove_fields`** 可同次组合(以契约为准) |
63
63
  | 改字段 | `--update-fields-file` | 每项 **`selector`**(`name`/`que_id`/`field_id`)+ **`set`** |
64
64
  | 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
@@ -82,7 +82,7 @@
82
82
 
83
83
  **一次性新建应用**:`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json) 是当前推荐示例;它已包含唯一数据标题和可选数据封面(`q_linker` 使用 `https://httpbin.org/get`,`relation` 指向可读模板应用 `ead8ims5i401`)。
84
84
 
85
- **一次性新建多个应用**:用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`;`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用,工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径,尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景;不要为了拿 `app_key` 先逐个创建再二次补关联字段。
85
+ **一次性新建多个应用**:用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`,其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`,每个 `apps[]` 写顶层 `icon + color`;`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用,工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径,尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景;不要为了拿 `app_key` 先逐个创建再二次补关联字段。
86
86
 
87
87
  **限制(平台硬性)**:每应用 **至多一个** `relation`;`--app-key` 向已有应用追加时须 **字段名不重复**、且 **不能**在已有 relation 上再增第二个。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**,本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`,须修复或删除该题。
88
88
 
@@ -0,0 +1,124 @@
1
+ [
2
+ {
3
+ "title": "业务入口",
4
+ "source_type": "grid",
5
+ "position": {
6
+ "pc": {"x": 0, "y": 0, "cols": 24, "rows": 4},
7
+ "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 4}
8
+ },
9
+ "config": {
10
+ "gridTitle": "业务入口",
11
+ "beingShowTitle": true,
12
+ "items": [
13
+ {
14
+ "type": 1,
15
+ "jumpMode": 1,
16
+ "linkAppKey": "APP_KEY_DEVICE",
17
+ "linkFormType": 1,
18
+ "title": "设备台账",
19
+ "customTitle": "设备台账",
20
+ "beingCustomTitle": false
21
+ },
22
+ {
23
+ "type": 1,
24
+ "jumpMode": 1,
25
+ "linkAppKey": "APP_KEY_REPAIR",
26
+ "linkFormType": 1,
27
+ "title": "故障报修",
28
+ "customTitle": "故障报修",
29
+ "beingCustomTitle": false
30
+ },
31
+ {
32
+ "type": 1,
33
+ "jumpMode": 1,
34
+ "linkAppKey": "APP_KEY_MAINTENANCE",
35
+ "linkFormType": 1,
36
+ "title": "保养管理",
37
+ "customTitle": "保养管理",
38
+ "beingCustomTitle": false
39
+ }
40
+ ]
41
+ }
42
+ },
43
+ {
44
+ "title": "设备总数",
45
+ "source_type": "chart",
46
+ "position": {
47
+ "pc": {"x": 0, "y": 4, "cols": 6, "rows": 5},
48
+ "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 5}
49
+ },
50
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_TOTAL"}
51
+ },
52
+ {
53
+ "title": "正常设备",
54
+ "source_type": "chart",
55
+ "position": {
56
+ "pc": {"x": 6, "y": 4, "cols": 6, "rows": 5},
57
+ "mobile": {"x": 0, "y": 9, "cols": 6, "rows": 5}
58
+ },
59
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_NORMAL"}
60
+ },
61
+ {
62
+ "title": "维修中设备",
63
+ "source_type": "chart",
64
+ "position": {
65
+ "pc": {"x": 12, "y": 4, "cols": 6, "rows": 5},
66
+ "mobile": {"x": 0, "y": 14, "cols": 6, "rows": 5}
67
+ },
68
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_REPAIRING"}
69
+ },
70
+ {
71
+ "title": "本月报修",
72
+ "source_type": "chart",
73
+ "position": {
74
+ "pc": {"x": 18, "y": 4, "cols": 6, "rows": 5},
75
+ "mobile": {"x": 0, "y": 19, "cols": 6, "rows": 5}
76
+ },
77
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_REPAIR_MONTH"}
78
+ },
79
+ {
80
+ "title": "设备状态分布",
81
+ "source_type": "chart",
82
+ "position": {
83
+ "pc": {"x": 0, "y": 9, "cols": 8, "rows": 7},
84
+ "mobile": {"x": 0, "y": 24, "cols": 6, "rows": 7}
85
+ },
86
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_STATUS_DIST"}
87
+ },
88
+ {
89
+ "title": "故障类型分布",
90
+ "source_type": "chart",
91
+ "position": {
92
+ "pc": {"x": 8, "y": 9, "cols": 8, "rows": 7},
93
+ "mobile": {"x": 0, "y": 31, "cols": 6, "rows": 7}
94
+ },
95
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_FAULT_DIST"}
96
+ },
97
+ {
98
+ "title": "维修完成趋势",
99
+ "source_type": "chart",
100
+ "position": {
101
+ "pc": {"x": 16, "y": 9, "cols": 8, "rows": 7},
102
+ "mobile": {"x": 0, "y": 38, "cols": 6, "rows": 7}
103
+ },
104
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_REPAIR_TREND"}
105
+ },
106
+ {
107
+ "title": "异常设备",
108
+ "source_type": "view",
109
+ "position": {
110
+ "pc": {"x": 0, "y": 16, "cols": 12, "rows": 11},
111
+ "mobile": {"x": 0, "y": 45, "cols": 6, "rows": 11}
112
+ },
113
+ "view_ref": {"app_key": "APP_KEY_DEVICE", "view_key": "VIEW_KEY_ABNORMAL_DEVICES"}
114
+ },
115
+ {
116
+ "title": "待处理工单",
117
+ "source_type": "view",
118
+ "position": {
119
+ "pc": {"x": 12, "y": 16, "cols": 12, "rows": 11},
120
+ "mobile": {"x": 0, "y": 56, "cols": 6, "rows": 11}
121
+ },
122
+ "view_ref": {"app_key": "APP_KEY_REPAIR", "view_key": "VIEW_KEY_PENDING_WORK_ORDERS"}
123
+ }
124
+ ]
@@ -2215,6 +2215,7 @@ class ChartGetResponse(StrictModel):
2215
2215
  chart_id: str
2216
2216
  base: dict[str, Any] = Field(default_factory=dict)
2217
2217
  visibility: dict[str, Any] = Field(default_factory=dict)
2218
+ filters: list[list[dict[str, Any]]] = Field(default_factory=list)
2218
2219
  config: dict[str, Any] = Field(default_factory=dict)
2219
2220
 
2220
2221
 
@@ -7184,6 +7184,7 @@ class AiBuilderFacade:
7184
7184
  chart_id=chart_id,
7185
7185
  base=deepcopy(base) if isinstance(base, dict) else {},
7186
7186
  visibility=_public_visibility_from_chart_visible_auth(base.get("visibleAuth")),
7187
+ filters=_public_chart_filter_groups_from_qingbi_config(config) if isinstance(config, dict) else [],
7187
7188
  config=deepcopy(config) if isinstance(config, dict) else {},
7188
7189
  )
7189
7190
  return {
@@ -11612,12 +11613,12 @@ class AiBuilderFacade:
11612
11613
  base_payload=base_payload,
11613
11614
  )
11614
11615
  if sections_requested:
11615
- component_payload = self._build_portal_components_from_sections(
11616
+ component_payload, layout_metadata = self._build_portal_components_from_sections(
11616
11617
  profile=profile,
11617
11618
  sections=request.sections,
11618
11619
  layout_preset=request.layout_preset,
11619
11620
  )
11620
- layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload)
11621
+ layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload, layout_metadata=layout_metadata)
11621
11622
  update_payload["components"] = component_payload
11622
11623
  self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
11623
11624
  write_executed = True
@@ -12563,8 +12564,9 @@ class AiBuilderFacade:
12563
12564
  profile: str,
12564
12565
  sections: list[PortalSectionPatch],
12565
12566
  layout_preset: str | None = None,
12566
- ) -> list[dict[str, Any]]:
12567
+ ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
12567
12568
  resolved_components: list[dict[str, Any]] = []
12569
+ layout_metadata: list[dict[str, Any]] = []
12568
12570
  pc_x = 0
12569
12571
  pc_y = 0
12570
12572
  pc_row_height = 0
@@ -12596,6 +12598,11 @@ class AiBuilderFacade:
12596
12598
  profile=profile,
12597
12599
  ref=section.chart_ref,
12598
12600
  )
12601
+ chart_type = str(
12602
+ resolved_chart.get("chart_type")
12603
+ or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
12604
+ or ""
12605
+ ).strip()
12599
12606
  chart_config = {
12600
12607
  "biChartId": resolved_chart["chart_id"],
12601
12608
  "chartComponentTitle": section.title,
@@ -12603,6 +12610,7 @@ class AiBuilderFacade:
12603
12610
  **deepcopy(section.config),
12604
12611
  }
12605
12612
  component = {"type": 9, "position": position_payload, "chartConfig": _compact_dict(chart_config)}
12613
+ layout_metadata.append({"source_type": section.source_type, "chart_type": chart_type})
12606
12614
  elif section.source_type == "view":
12607
12615
  resolved_view = _resolve_view_reference(
12608
12616
  facade=self,
@@ -12625,26 +12633,31 @@ class AiBuilderFacade:
12625
12633
  **deepcopy(section.config),
12626
12634
  }
12627
12635
  component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
12636
+ layout_metadata.append({"source_type": section.source_type})
12628
12637
  elif section.source_type == "grid":
12629
12638
  component = {
12630
12639
  "type": 2,
12631
12640
  "position": position_payload,
12632
12641
  "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
12633
12642
  }
12643
+ layout_metadata.append({"source_type": section.source_type})
12634
12644
  elif section.source_type == "filter":
12635
12645
  component = {"type": 6, "position": position_payload, "filterConfig": deepcopy(section.config)}
12646
+ layout_metadata.append({"source_type": section.source_type})
12636
12647
  elif section.source_type == "text":
12637
12648
  component = {"type": 5, "position": position_payload, "textConfig": {"text": section.text or "", **deepcopy(section.config)}}
12649
+ layout_metadata.append({"source_type": section.source_type})
12638
12650
  else:
12639
12651
  component = {
12640
12652
  "type": 4,
12641
12653
  "position": position_payload,
12642
12654
  "linkConfig": {"url": section.url or "", "beingLoginAuth": False, **deepcopy(section.config)},
12643
12655
  }
12656
+ layout_metadata.append({"source_type": section.source_type})
12644
12657
  if dash_style is not None:
12645
12658
  component["dashStyleConfigBO"] = dash_style
12646
12659
  resolved_components.append(component)
12647
- return resolved_components
12660
+ return resolved_components, layout_metadata
12648
12661
 
12649
12662
  def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
12650
12663
  session_profile = self.apps.sessions.get_profile(profile)
@@ -15212,6 +15225,103 @@ def _qingbi_chart_filter_value_to_text(*, value: Any, form_field: dict[str, Any]
15212
15225
  reject(value)
15213
15226
 
15214
15227
 
15228
+ def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> list[list[dict[str, Any]]]:
15229
+ groups: list[list[dict[str, Any]]] = []
15230
+ raw_groups = config.get("beforeAggregationFilterMatrix")
15231
+ if not isinstance(raw_groups, list):
15232
+ return groups
15233
+ for raw_group in raw_groups:
15234
+ if not isinstance(raw_group, list):
15235
+ continue
15236
+ group: list[dict[str, Any]] = []
15237
+ for raw_rule in raw_group:
15238
+ if not isinstance(raw_rule, dict):
15239
+ continue
15240
+ operator = _public_chart_filter_operator_from_judge_type(raw_rule.get("judgeType"))
15241
+ field_id = raw_rule.get("fieldId") or raw_rule.get("field_id")
15242
+ field_name = (
15243
+ raw_rule.get("fieldName")
15244
+ or raw_rule.get("field_name")
15245
+ or raw_rule.get("queTitle")
15246
+ or raw_rule.get("title")
15247
+ or field_id
15248
+ )
15249
+ public_rule: dict[str, Any] = {
15250
+ "field_name": _stringify_condition_value(field_name).strip(),
15251
+ "operator": operator,
15252
+ }
15253
+ if field_id is not None:
15254
+ public_rule["field_id"] = _stringify_condition_value(field_id).strip()
15255
+ values = _public_chart_filter_values_from_rule(raw_rule, operator=operator)
15256
+ if values:
15257
+ public_rule["values"] = values
15258
+ group.append(public_rule)
15259
+ if group:
15260
+ groups.append(group)
15261
+ return groups
15262
+
15263
+
15264
+ def _public_chart_filter_operator_from_judge_type(judge_type: Any) -> str:
15265
+ normalized = _stringify_condition_value(judge_type).strip()
15266
+ mapping = {
15267
+ "equal": "eq",
15268
+ "equals": "eq",
15269
+ "=": "eq",
15270
+ "unequal": "neq",
15271
+ "notEqual": "neq",
15272
+ "!=": "neq",
15273
+ "anyMatch": "in",
15274
+ "oneOf": "in",
15275
+ "include": "contains",
15276
+ "contains": "contains",
15277
+ "greaterOrEqual": "gte",
15278
+ "gte": "gte",
15279
+ "lessOrEqual": "lte",
15280
+ "lte": "lte",
15281
+ "isNull": "is_empty",
15282
+ "empty": "is_empty",
15283
+ "notNull": "not_empty",
15284
+ "not_empty": "not_empty",
15285
+ }
15286
+ if normalized in mapping:
15287
+ return mapping[normalized]
15288
+ numeric = _coerce_nonnegative_int(judge_type)
15289
+ if numeric is not None:
15290
+ return _public_view_filter_operator_from_judge_type(numeric)
15291
+ return f"judge_type:{judge_type}"
15292
+
15293
+
15294
+ def _public_chart_filter_values_from_rule(rule: dict[str, Any], *, operator: str) -> list[str]:
15295
+ if operator in {"is_empty", "not_empty"}:
15296
+ return []
15297
+ raw_value = rule.get("judgeValue")
15298
+ if raw_value is None and "judgeValues" in rule:
15299
+ raw_value = rule.get("judgeValues")
15300
+ values: list[str] = []
15301
+ if isinstance(raw_value, list):
15302
+ values = [_stringify_condition_value(value).strip() for value in raw_value]
15303
+ elif isinstance(raw_value, str) and "<&&>" in raw_value:
15304
+ values = [value.strip() for value in raw_value.split("<&&>")]
15305
+ elif raw_value is not None:
15306
+ values = [_stringify_condition_value(raw_value).strip()]
15307
+ values = [value for value in values if value]
15308
+ if values:
15309
+ return values
15310
+ for detail_key in ("judgeValueDetailList", "judgeValueDetails"):
15311
+ details = rule.get(detail_key)
15312
+ if not isinstance(details, list):
15313
+ continue
15314
+ for detail in details:
15315
+ if not isinstance(detail, dict):
15316
+ continue
15317
+ for value_key in ("value", "label", "name", "title", "dataValue", "id"):
15318
+ value = _stringify_condition_value(detail.get(value_key)).strip()
15319
+ if value:
15320
+ values.append(value)
15321
+ break
15322
+ return values
15323
+
15324
+
15215
15325
  def _build_public_chart_config_payload(
15216
15326
  *,
15217
15327
  patch: ChartUpsertPatch,
@@ -15421,6 +15531,17 @@ def _extract_chart_identifier(chart: Any) -> str:
15421
15531
  ).strip()
15422
15532
 
15423
15533
 
15534
+ def _chart_type_from_item(chart: Any) -> str:
15535
+ if not isinstance(chart, dict):
15536
+ return ""
15537
+ return _public_chart_type_from_backend(
15538
+ chart.get("chartType")
15539
+ or chart.get("chart_type")
15540
+ or chart.get("chartGraphType")
15541
+ or chart.get("type")
15542
+ )
15543
+
15544
+
15424
15545
  def _normalize_backend_chart_type(value: Any) -> str:
15425
15546
  raw = str(value or "").strip()
15426
15547
  if not raw:
@@ -15537,7 +15658,7 @@ def _portal_component_position_public(
15537
15658
  rows = 2
15538
15659
  elif source_name == "view":
15539
15660
  cols = 24
15540
- rows = 8
15661
+ rows = 11
15541
15662
  elif source_name == "link":
15542
15663
  cols = 12
15543
15664
  rows = 2
@@ -15546,7 +15667,7 @@ def _portal_component_position_public(
15546
15667
  cols = 12
15547
15668
  else:
15548
15669
  cols = 8
15549
- rows = 6
15670
+ rows = 7
15550
15671
  if cols == 24:
15551
15672
  if pc_x != 0:
15552
15673
  pc_y += pc_row_height
@@ -15581,7 +15702,12 @@ def _empty_portal_layout_diagnostics() -> dict[str, Any]:
15581
15702
  }
15582
15703
 
15583
15704
 
15584
- def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: list[dict[str, Any]]) -> dict[str, Any]:
15705
+ def _portal_layout_diagnostics(
15706
+ sections: list[PortalSectionPatch],
15707
+ components: list[dict[str, Any]],
15708
+ *,
15709
+ layout_metadata: list[dict[str, Any]] | None = None,
15710
+ ) -> dict[str, Any]:
15585
15711
  diagnostics = _empty_portal_layout_diagnostics()
15586
15712
  diagnostics["section_count"] = len(sections)
15587
15713
  explicit_count = sum(1 for section in sections if section.position is not None)
@@ -15596,16 +15722,26 @@ def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: l
15596
15722
  if pc:
15597
15723
  pc_positions.append(pc)
15598
15724
  section = sections[index] if index < len(sections) else None
15725
+ metadata = layout_metadata[index] if isinstance(layout_metadata, list) and index < len(layout_metadata) and isinstance(layout_metadata[index], dict) else {}
15599
15726
  source_type = str(getattr(section, "source_type", "") or "").lower() if section is not None else ""
15600
15727
  title = str(getattr(section, "title", "") or "").strip() if section is not None else None
15601
15728
  cols = int(pc.get("cols") or 0)
15602
15729
  rows = int(pc.get("rows") or 0)
15603
- if source_type == "chart" and (cols < 8 or rows < 5):
15730
+ chart_type = str(metadata.get("chart_type") or "").strip().lower()
15731
+ is_metric_chart = chart_type in {"target", "indicator"}
15732
+ min_chart_cols = 6 if is_metric_chart else 8
15733
+ min_chart_rows = 5 if is_metric_chart else 7
15734
+ if source_type == "chart" and (cols < min_chart_cols or rows < min_chart_rows):
15604
15735
  warnings.append(_warning(
15605
15736
  "PORTAL_CHART_CARD_TOO_SMALL",
15606
- "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 5, preferably rows >= 6",
15737
+ (
15738
+ "metric chart portal card is too small; use at least pc.cols >= 6 and pc.rows >= 5"
15739
+ if is_metric_chart
15740
+ else "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 7 for non-metric charts"
15741
+ ),
15607
15742
  section_index=index,
15608
15743
  title=title,
15744
+ chart_type=chart_type or None,
15609
15745
  pc=deepcopy(pc),
15610
15746
  ))
15611
15747
  if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
@@ -15648,7 +15784,7 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
15648
15784
  item_id = _extract_chart_identifier(item)
15649
15785
  item_name = str(item.get("chartName") or "").strip()
15650
15786
  if item_id == chart_id:
15651
- return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key}
15787
+ return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key, "chart_type": _chart_type_from_item(item)}
15652
15788
  raise ValueError(f"chart ref chart_id '{chart_id}' could not be resolved under app '{app_key}'")
15653
15789
  matches = _find_charts_by_name(items, chart_name=chart_name)
15654
15790
  if len(matches) > 1:
@@ -15659,6 +15795,7 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
15659
15795
  "chart_id": _extract_chart_identifier(item),
15660
15796
  "chart_name": str(item.get("chartName") or "").strip(),
15661
15797
  "app_key": app_key,
15798
+ "chart_type": _chart_type_from_item(item),
15662
15799
  }
15663
15800
  raise ValueError(f"chart ref could not be resolved under app '{app_key}'")
15664
15801
 
@@ -24719,7 +24856,7 @@ def _public_view_filter_groups_from_match_rules(
24719
24856
 
24720
24857
 
24721
24858
  def _public_view_filter_operator_from_judge_type(judge_type: Any) -> str:
24722
- normalized = _coerce_positive_int(judge_type)
24859
+ normalized = _coerce_nonnegative_int(judge_type)
24723
24860
  if normalized == JUDGE_EQUAL:
24724
24861
  return "eq"
24725
24862
  if normalized == JUDGE_UNEQUAL:
@@ -1,10 +1,11 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import argparse
4
+ from copy import deepcopy
4
5
 
5
6
  from ..context import CliContext
6
- from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
7
7
  from ..json_io import load_json_value
8
+ from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
8
9
 
9
10
 
10
11
  def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -479,6 +480,7 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
479
480
  def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
480
481
  apps_payload = _load_apps_file_arg(args.apps_file)
481
482
  apps = apps_payload["apps"]
483
+ apps_warnings = apps_payload.get("warnings") or []
482
484
  package_id = args.package_id
483
485
  if package_id is None and apps_payload.get("package_id") is not None:
484
486
  package_id = int(apps_payload["package_id"])
@@ -487,6 +489,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
487
489
  raise_config_error(
488
490
  "schema apply multi-app mode requires a non-empty --apps-file.",
489
491
  fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
492
+ error_code="APPS_FILE_EMPTY",
490
493
  )
491
494
  if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
492
495
  raise_config_error(
@@ -498,7 +501,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
498
501
  "schema apply multi-app mode requires --package-id.",
499
502
  fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
500
503
  )
501
- return context.builder.app_schema_apply(
504
+ result = context.builder.app_schema_apply(
502
505
  profile=args.profile,
503
506
  package_id=package_id,
504
507
  visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -509,6 +512,11 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
509
512
  update_fields=[],
510
513
  remove_fields=[],
511
514
  )
515
+ if apps_warnings and isinstance(result, dict):
516
+ result_warnings = list(result.get("warnings") or [])
517
+ result_warnings.extend(deepcopy(apps_warnings))
518
+ result["warnings"] = result_warnings
519
+ return result
512
520
  has_app_key = bool((args.app_key or "").strip())
513
521
  has_app_name = bool((args.app_name or "").strip())
514
522
  has_app_title = bool((args.app_title or "").strip())
@@ -545,8 +553,56 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
545
553
  def _load_apps_file_arg(path: str | None) -> dict[str, object]:
546
554
  if not path:
547
555
  return {"apps": []}
556
+ expected_shape = {
557
+ "package_id": 1001,
558
+ "apps": [
559
+ {
560
+ "client_key": "employee",
561
+ "app_name": "员工花名册",
562
+ "icon": "business-personalcard",
563
+ "color": "emerald",
564
+ "add_fields": [],
565
+ }
566
+ ],
567
+ }
568
+ expected_shape_details = {
569
+ "expected_shape": expected_shape,
570
+ "expected_shape_json": (
571
+ '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
572
+ '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
573
+ ),
574
+ }
548
575
  payload = load_json_value(path, option_name="--apps-file")
549
576
  if isinstance(payload, list):
577
+ if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
578
+ wrapper = payload[0]
579
+ apps = wrapper.get("apps")
580
+ if not isinstance(apps, list):
581
+ raise_config_error(
582
+ "--apps-file wrapper object requires an apps array.",
583
+ fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw apps array like [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}].",
584
+ error_code="APPS_FILE_SHAPE_INVALID",
585
+ details=expected_shape_details,
586
+ )
587
+ result: dict[str, object] = {
588
+ "apps": apps,
589
+ "warnings": [
590
+ {
591
+ "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
592
+ "message": "--apps-file was a singleton wrapper array; normalized it to {package_id, apps}.",
593
+ }
594
+ ],
595
+ }
596
+ if wrapper.get("package_id") is not None:
597
+ result["package_id"] = wrapper.get("package_id")
598
+ return result
599
+ if any(isinstance(item, dict) and "apps" in item for item in payload):
600
+ raise_config_error(
601
+ "--apps-file root array items must be app items, not package wrapper objects.",
602
+ fix_hint="Use one object {\"package_id\":1001,\"apps\":[...]} or a raw app array [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}]. Do not wrap multiple {package_id, apps} objects in an array.",
603
+ error_code="APPS_FILE_SHAPE_INVALID",
604
+ details=expected_shape_details,
605
+ )
550
606
  return {"apps": payload}
551
607
  if isinstance(payload, dict):
552
608
  apps = payload.get("apps")
@@ -554,6 +610,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
554
610
  raise_config_error(
555
611
  "--apps-file JSON object requires an apps array.",
556
612
  fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
613
+ error_code="APPS_FILE_SHAPE_INVALID",
614
+ details=expected_shape_details,
557
615
  )
558
616
  result: dict[str, object] = {"apps": apps}
559
617
  if payload.get("package_id") is not None:
@@ -562,6 +620,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
562
620
  raise_config_error(
563
621
  "--apps-file must be a JSON array or an object containing apps.",
564
622
  fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
623
+ error_code="APPS_FILE_SHAPE_INVALID",
624
+ details=expected_shape_details,
565
625
  )
566
626
 
567
627
 
@@ -48,14 +48,23 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
48
48
  raise QingflowApiError.config_error(f"{label} is required")
49
49
 
50
50
 
51
- def raise_config_error(message: str, *, fix_hint: str) -> None:
51
+ def raise_config_error(
52
+ message: str,
53
+ *,
54
+ fix_hint: str | None = None,
55
+ error_code: str = "CONFIG_ERROR",
56
+ details: dict[str, Any] | None = None,
57
+ ) -> None:
58
+ error_details: dict[str, Any] = {"fix_hint": fix_hint or message}
59
+ if details:
60
+ error_details.update(details)
52
61
  raise RuntimeError(
53
62
  json.dumps(
54
63
  {
55
64
  "category": "config",
56
65
  "message": message,
57
- "error_code": "CONFIG_ERROR",
58
- "details": {"fix_hint": fix_hint},
66
+ "error_code": error_code,
67
+ "details": error_details,
59
68
  },
60
69
  ensure_ascii=False,
61
70
  )
@@ -383,7 +383,7 @@ class AiBuilderTools(ToolBase):
383
383
  remove_fields: list[JSONObject] | None = None,
384
384
  apps: list[JSONObject] | None = None,
385
385
  ) -> JSONObject:
386
- if apps:
386
+ if apps is not None:
387
387
  if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
388
388
  return _config_failure(
389
389
  tool_name="app_schema_apply",
@@ -1718,8 +1718,18 @@ class AiBuilderTools(ToolBase):
1718
1718
  icon_color=icon_color,
1719
1719
  icon_config=icon_config,
1720
1720
  )
1721
- if apps:
1722
- apps = [_normalize_schema_app_item(item) if isinstance(item, dict) else item for item in apps]
1721
+ if apps is not None:
1722
+ normalized_apps_payload = _normalize_schema_apps_argument(
1723
+ tool_name="app_schema_apply",
1724
+ package_id=package_id,
1725
+ apps=apps,
1726
+ )
1727
+ failure = normalized_apps_payload.get("failure")
1728
+ if isinstance(failure, dict):
1729
+ return _attach_builder_apply_envelope("app_schema_apply", failure)
1730
+ package_id = normalized_apps_payload.get("package_id") # type: ignore[assignment]
1731
+ apps = normalized_apps_payload.get("apps") # type: ignore[assignment]
1732
+ input_warnings = list(normalized_apps_payload.get("warnings") or [])
1723
1733
  result = self._app_schema_apply_multi(
1724
1734
  profile=profile,
1725
1735
  package_id=package_id,
@@ -1728,6 +1738,10 @@ class AiBuilderTools(ToolBase):
1728
1738
  publish=publish,
1729
1739
  apps=apps,
1730
1740
  )
1741
+ if input_warnings:
1742
+ result_warnings = list(result.get("warnings") or [])
1743
+ result_warnings.extend(deepcopy(input_warnings))
1744
+ result["warnings"] = result_warnings
1731
1745
  return _attach_builder_apply_envelope("app_schema_apply", result)
1732
1746
  result = self._app_schema_apply_once(
1733
1747
  profile=profile,
@@ -1803,9 +1817,13 @@ class AiBuilderTools(ToolBase):
1803
1817
  if not apps:
1804
1818
  return _config_failure(
1805
1819
  tool_name="app_schema_apply",
1820
+ error_code="APPS_FILE_EMPTY",
1806
1821
  message="app_schema_apply multi-app mode requires non-empty apps.",
1807
1822
  fix_hint="Pass apps as a non-empty list of app schema items.",
1808
1823
  )
1824
+ shape_failure = _schema_apps_shape_failure(tool_name="app_schema_apply", apps=apps)
1825
+ if shape_failure is not None:
1826
+ return shape_failure
1809
1827
  icon_errors: list[JSONObject] = []
1810
1828
  seen_new_app_icons: dict[str, int] = {}
1811
1829
  for index, raw_item in enumerate(apps):
@@ -2932,6 +2950,109 @@ def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
2932
2950
  return normalized
2933
2951
 
2934
2952
 
2953
+ def _schema_apps_expected_shape() -> JSONObject:
2954
+ return {
2955
+ "package_id": 1001,
2956
+ "apps": [
2957
+ {
2958
+ "client_key": "employee",
2959
+ "app_name": "员工花名册",
2960
+ "icon": "business-personalcard",
2961
+ "color": "emerald",
2962
+ "add_fields": [{"name": "员工名称", "type": "text", "as_data_title": True}],
2963
+ }
2964
+ ],
2965
+ }
2966
+
2967
+
2968
+ def _schema_apps_expected_shape_json() -> str:
2969
+ return (
2970
+ '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
2971
+ '"icon":"business-personalcard","color":"emerald","add_fields":[{"name":"员工名称","type":"text","as_data_title":true}]}]}'
2972
+ )
2973
+
2974
+
2975
+ def _is_schema_apps_wrapper_item(item: object) -> bool:
2976
+ return isinstance(item, dict) and "apps" in item
2977
+
2978
+
2979
+ def _schema_apps_shape_failure(*, tool_name: str, apps: list[JSONObject]) -> JSONObject | None:
2980
+ for index, item in enumerate(apps):
2981
+ if _is_schema_apps_wrapper_item(item):
2982
+ return _config_failure(
2983
+ tool_name=tool_name,
2984
+ error_code="APPS_FILE_SHAPE_INVALID",
2985
+ message="apps[] items must be app schema items, not package wrapper objects.",
2986
+ fix_hint=(
2987
+ "For MCP pass package_id separately and apps=[{app_name, icon, color, add_fields}]. "
2988
+ 'For CLI use --apps-file with {"package_id":1001,"apps":[...]}. '
2989
+ "Do not pass multiple {package_id, apps} wrapper objects inside apps[]."
2990
+ ),
2991
+ details={
2992
+ "index": index,
2993
+ "row_number": index + 1,
2994
+ "expected_shape": _schema_apps_expected_shape(),
2995
+ "expected_shape_json": _schema_apps_expected_shape_json(),
2996
+ },
2997
+ )
2998
+ return None
2999
+
3000
+
3001
+ def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, apps: list[JSONObject]) -> JSONObject:
3002
+ normalized_package_id = package_id
3003
+ normalized_apps: list[JSONObject] = apps
3004
+ warnings: list[JSONObject] = []
3005
+
3006
+ if len(apps) == 1 and _is_schema_apps_wrapper_item(apps[0]):
3007
+ wrapper = apps[0]
3008
+ wrapper_apps = wrapper.get("apps")
3009
+ if not isinstance(wrapper_apps, list):
3010
+ return {
3011
+ "failure": _config_failure(
3012
+ tool_name=tool_name,
3013
+ error_code="APPS_FILE_SHAPE_INVALID",
3014
+ message="apps singleton wrapper requires an apps array.",
3015
+ fix_hint='Use {"package_id":1001,"apps":[...]} in CLI, or pass MCP package_id=1001 and apps=[...].',
3016
+ details={
3017
+ "expected_shape": _schema_apps_expected_shape(),
3018
+ "expected_shape_json": _schema_apps_expected_shape_json(),
3019
+ },
3020
+ )
3021
+ }
3022
+ if normalized_package_id is None and wrapper.get("package_id") is not None:
3023
+ try:
3024
+ normalized_package_id = int(wrapper.get("package_id"))
3025
+ except (TypeError, ValueError):
3026
+ return {
3027
+ "failure": _config_failure(
3028
+ tool_name=tool_name,
3029
+ error_code="APPS_FILE_SHAPE_INVALID",
3030
+ message="apps singleton wrapper package_id must be an integer.",
3031
+ fix_hint="Pass package_id as a number at the top level.",
3032
+ details={
3033
+ "expected_shape": _schema_apps_expected_shape(),
3034
+ "expected_shape_json": _schema_apps_expected_shape_json(),
3035
+ },
3036
+ )
3037
+ }
3038
+ normalized_apps = wrapper_apps
3039
+ warnings.append(
3040
+ {
3041
+ "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
3042
+ "message": "apps was a singleton wrapper array; normalized it to package_id + apps.",
3043
+ }
3044
+ )
3045
+ else:
3046
+ failure = _schema_apps_shape_failure(tool_name=tool_name, apps=apps)
3047
+ if failure is not None:
3048
+ return {"failure": failure}
3049
+
3050
+ normalized_items: list[JSONObject] = []
3051
+ for item in normalized_apps:
3052
+ normalized_items.append(_normalize_schema_app_item(item) if isinstance(item, dict) else item)
3053
+ return {"package_id": normalized_package_id, "apps": normalized_items, "warnings": warnings}
3054
+
3055
+
2935
3056
  def _compile_multi_app_schema_item_refs(
2936
3057
  item: JSONObject,
2937
3058
  client_key_to_app_key: dict[str, str],
@@ -4438,7 +4559,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
4438
4559
  "execution_notes": [
4439
4560
  "create or update package metadata, visibility, grouping, and ordering in one call",
4440
4561
  "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
4441
- "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
4562
+ "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
4442
4563
  "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
4443
4564
  "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
4444
4565
  "metadata keys omitted on update are preserved",
@@ -5024,12 +5145,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
5024
5145
  "create mode: package_id + app_name + create_if_missing=true",
5025
5146
  "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
5026
5147
  "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
5148
+ "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
5027
5149
  "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
5028
5150
  "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
5029
5151
  "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
5030
5152
  "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
5031
5153
  "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
5032
- "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
5154
+ "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
5033
5155
  "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
5034
5156
  "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
5035
5157
  "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",