@qingflow-tech/qingflow-cli 1.1.61-beta.6 → 1.1.61-beta.8

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
@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
7
7
  ## 安装
8
8
 
9
9
  ```bash
10
- npm install @qingflow-tech/qingflow-cli@1.1.61-beta.6
10
+ npm install @qingflow-tech/qingflow-cli@1.1.61-beta.8
11
11
  ```
12
12
 
13
13
  推荐从官网复制这一条一键安装 Qingflow CLI:
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
21
21
  ## 运行
22
22
 
23
23
  ```bash
24
- npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.6 qingflow
24
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.8 qingflow
25
25
  ```
26
26
 
27
27
  全局安装后可以直接运行:
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
62
62
  如果你通过一次性 `npx -p` 执行 skills 安装,建议加 `--copy`,避免 symlink 指向 npm 临时执行缓存:
63
63
 
64
64
  ```bash
65
- npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.6 qingflow-skills install --agent codex --scope user --copy
65
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.8 qingflow-skills install --agent codex --scope user --copy
66
66
  ```
67
67
 
68
68
  `qingflow-skills install` 默认使用 symlink,且遇到同名 skill 不会覆盖;只有显式传入 `--force` 才会替换。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.1.61-beta.6",
3
+ "version": "1.1.61-beta.8",
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.1.61b6"
7
+ version = "1.1.61b8"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -47,7 +47,7 @@ Start from the portal job, then choose the section strategy. A portal is an asse
47
47
  | Show BI visualizations | Use chart sections | `rows=7`; same-row components share the same `rows` |
48
48
  | Show concrete data views | Use view sections | Use business views, not `全部数据` / `我的数据`; `rows=11` |
49
49
  | Update one existing portal block | Prefer `patch_sections[]` | Do not replace the whole `sections` list unless intentional |
50
- | Need a filter bar | Avoid automation by default | `source_type: "filter"` is raw/unstable and not part of the unified filter DSL |
50
+ | Need a filter bar | Use `source_type: "filter"` with non-empty `config.rules` | Empty-rules filters are rejected (backend read face enumerates filter components by their rule groups); see §3.4 |
51
51
 
52
52
  Short rule: **portal rows are 24-grid layout rows, not form-field rows. Same `y` = same row, same `rows`, `cols` sum 24.**
53
53
 
@@ -63,7 +63,7 @@ Before `portal apply`, verify this short list:
63
63
  | Standard heights | Metric cards `rows=5`; BI charts `rows=7`; data views `rows=11`. Do not mix different heights in one row. |
64
64
  | Standard order | Business entry -> metrics -> BI charts -> data views. Do not put data views before metrics/charts in a dashboard-style portal. |
65
65
  | Default/system views | Do not use `全部数据` / `我的数据` as the main business portal views. Use concrete business views. |
66
- | Filter component | Do not use `source_type: "filter"` as the main automation path; it is raw/unstable and not part of the unified filter DSL. |
66
+ | Filter component | `config.rules` must contain at least one rule group (empty-rules filters are written but invisible in readback; blocked at validation). Rule keys: filterGroupName/filterGroupConfig/filterItemName/que/judge, see §3.4. |
67
67
  | Readback | After apply, run `portal get` and compare section count, refs, and positions before claiming frontend visibility. |
68
68
 
69
69
  Inline QingBI chart creation uses one chart job per section and runs with an internal concurrency limit of 10. If two sections declare the same `app_key + name + chart_type` with identical config, CLI creates/updates once and reuses the chart id. If their config differs, CLI rejects the portal write as a duplicate inline chart conflict.
@@ -90,7 +90,7 @@ Recommended standard workbench skeleton:
90
90
 
91
91
  搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`** / **`delete`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
92
92
 
93
- 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter`(`type:6`)经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
93
+ 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter` 声明式写入受控支持(rules 非空,历史「不落库」实测为空规则读面不可见,见 §3.4)**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
94
94
 
95
95
  > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
96
96
 
@@ -214,7 +214,7 @@ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols
214
214
 
215
215
  **当前工具边界**:
216
216
 
217
- - 声明式(`--file` / complete 档)支持**九类组件**:**`grid` / `chart` / `view` / `text` / `link`**(summary 档稳定面)+ **`carousel` / `task` / `favourite`**(complete 档,配置键见专项 Schema)+ **`filter`**(complete 档受控承载,仍按 **§3.4** raw 边界处理,不作为主路径)。
217
+ - 声明式(`--file` / complete 档)支持**九类组件**:**`grid` / `chart` / `view` / `text` / `link`**(summary 档稳定面)+ **`carousel` / `task` / `favourite`**(complete 档,配置键见专项 Schema)+ **`filter`**(complete 档受控承载:`config.rules` 至少 1 组,空规则读面不可见、模型层阻断,见 **§3.4**)。
218
218
  - **`task`(一个门户最多 1 个)与 `favourite`(一个门户最多 1 个)** 已进入 v1alpha1 complete 声明面(`task`/`favourite` 类型化 config 键),不要再按后端 raw 形状(`taskConfig`/`favouriteConfig`)手拼;声明形态见 `qingflow --json builder portal schema --schema-kind task|favourite`。旧文档中的「task/favorite 不在公开合约里」已过时。
219
219
  - 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。这是唯一推荐复制的业务工作台布局模板:每一行 `cols_sum=24`,同行 `rows` 一致,下一行 `y` 连续。顶部先用一个业务入口 `grid` 占满 24 栅格;如果工具已支持待办组件,再把顶部拆成 `grid cols=12 + task cols=12`。
220
220
  - **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)** 和 **[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)** 仅用于组件能力探针,不作为业务门户布局模板;搭建正式门户时不要从这些探针推导布局。
@@ -253,7 +253,7 @@ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols
253
253
  | **`grid`** | **2** | 九宫格 | summary |
254
254
  | **`text`** | **5** | 富文本说明 | summary |
255
255
  | **`link`** | **4** | 外链 | summary |
256
- | **`filter`** | **6** | 筛选条 | complete(raw/unstable) |
256
+ | **`filter`** | **6** | 筛选条 | complete(rules 必须非空) |
257
257
  | **`carousel`** | **3** | 轮播(数据源应用 + 标题/图片/链接字段) | complete |
258
258
  | **`task`** | **8** | 待办(一个门户最多 1 个) | complete |
259
259
  | **`favourite`** | **7** | 收藏(一个门户最多 1 个) | complete |
@@ -292,18 +292,33 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_re
292
292
  }
293
293
  ```
294
294
 
295
- ### 3.4 **`filter`**:`config` **整包**即接口里的 **`filterConfig`**
295
+ ### 3.4 **`filter`**:声明式筛选条(支持,**rules 必须非空**)
296
296
 
297
- 实现:组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
297
+ 声明形态:**`config.graphs`**(受筛选作用的图表引用)+ **`config.rules`**(筛选规则组,至少 1 组),编译为后端 `ComponentFilter`(`graphList` + `filterConfig`)。规则键集:`filterGroupName`(组名)/`filterGroupConfig`(筛选项:`filterItemName` + `que{queId}` + `judge{judgeType,judgeValues}`);代理键 `filterGroupId`/`filterItemId` 为后端自增位移键,声明里不要携带。
298
298
 
299
- - **理论上**与 solution 编译器一致:外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**;**`graphList`** 常含 **`graphType`**(如 **`CHART`**)、**`graphKey`** 或 **`graphRef`(`entity_id` / `chart_id`)** 等。
300
- - **本环境 CLI 直写实测(多次 `--publish`)**:在已验证 **chart / view / grid / text / link** 均可落库的前提下,**`source_type: filter` 始终未出现在 `draft_result.components` 中**;尝试过:**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块(chart+filter)** 等,回读仍 **只有 chart(`count: 1`)** 或 **五类缺 `type: 6`**。
301
- **结论**:当前宜 **在搭建界面创建筛选条**,再 **`builder portal get` 反抓** 原始 `filterConfig` 形状;或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
302
- - portal `filter` 组件仍按 raw `filterConfig` 处理,不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
299
+ ```json
300
+ {
301
+ "source_type": "filter",
302
+ "position": {"pc": {"x": 0, "y": 0, "cols": 24, "rows": 3}},
303
+ "config": {
304
+ "graphs": [{"chart_key": "CHART_KEY_1001"}],
305
+ "rules": [
306
+ {
307
+ "filterGroupName": "区域",
308
+ "filterGroupConfig": [
309
+ {"filterItemName": "城市", "que": {"queId": 123456}, "judge": {"judgeType": 3, "judgeValues": ["上海"]}}
310
+ ]
311
+ }
312
+ ]
313
+ }
314
+ }
315
+ ```
316
+
317
+ **关键边界(旧实测记录的真相)**:`rules` 为空的 filter **会被模型层直接拒绝**——后端读面按筛选组(dash_filter_group 行)反查筛选组件,空规则的组件行虽写入但读面枚举不到,表现为「apply 成功、回读缺 type:6」。历史上「filter 不落库」的实测记录(命令式 raw 直传时代、全部空规则组合)即此机制,不是后端拒绝 type:6。存量筛选组件合法无标题(提取产物不带 `title`,不要合成);round-trip 重放已验证(ws40013 基准 337 个 filter 组件一致率 100%)。专项 Schema:`qingflow --json builder portal schema --schema-kind filter`。
303
318
 
304
319
  ### 3.5 **`grid` / `text` / `link` / `view`**
305
320
 
306
- - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
321
+ - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`——**`linkFormType` 缺省时编译器按 1(数据列表)补齐**(缺失会让前端跳转目标为空、入口无法点击);1=数据列表、2=表单页。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
307
322
  - **text** / **link**:**`text`** / **`url`** 必填。
308
323
  - **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
309
324
 
@@ -360,8 +375,8 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
360
375
  | 步骤 | 命令要点 | 结果 |
361
376
  |------|-----------|------|
362
377
  | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
363
- | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;**`filter` 仍不落库** → **`partial_success`**,**`components expected 6, got 5`**(与 **§3.4** 一致) |
364
- | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块(仅 `type: 9`)** |
378
+ | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;当时 filter 组合全部**空 rules** → 读面不可见(**§3.4** 机制,非后端拒绝;现空 rules 已被模型层阻断) |
379
+ | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合(历史记录,全部空 rules) | **回读恒为 1 块(仅 `type: 9`)**——空规则读面不可见;含 rules 的声明式写入已由 ws40013 基准验证 |
365
380
  | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
366
381
  | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
367
382
 
@@ -376,7 +391,7 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
376
391
  | 现象 | 处理 |
377
392
  |------|------|
378
393
  | `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
379
- | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;若多写了 **`filter`** 而回读少一块,见 **§3.4**(**CLI 写 filter 可能整体不生效**);也可能是 **异步回读**,可再 **`get`** 一次。 |
394
+ | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;`filter` 回读缺失多为 **空 rules**(模型层已阻断,检查报错)或 **异步回读**(可再 **`get`** 一次);含规则的 filter 写入正常(见 **§3.4**)。 |
380
395
  | **`published: true` 但 `verified: false`** | 读 **§7**;用 **`get` 草稿+线上**对照。 |
381
396
  | **503** | 网关/运维;稍后重试。 |
382
397
  | 缺 **chart** | 在对应 portal section 写 **`chart`**;或换用已有报表的 **`chart: {"chart_id": "..."}`** / 兼容旧 **`chart_ref`**。 |
@@ -2724,6 +2724,18 @@ class PortalSectionPatch(StrictModel):
2724
2724
  raise ValueError("task section requires task")
2725
2725
  if self.source_type == "favourite" and self.favourite is None:
2726
2726
  raise ValueError("favourite section requires favourite")
2727
+ if self.source_type == "filter":
2728
+ # 后端读面(DashSvcImpl#getComponentFilter)按筛选组(dash_filter_group 行)
2729
+ # 反查筛选组件:空规则的 filter 组件行虽会写入,但读面枚举不到——表现为
2730
+ # 「apply 成功但回读缺 type:6」(实测反馈「filter 不落库」的真身)。
2731
+ # 在模型咽喉(apply/validate 共同路径)阻断,不给静默不可见留门。
2732
+ filter_payload = self.config or {}
2733
+ rule_groups = filter_payload.get("rules", filter_payload.get("filterConfig"))
2734
+ if not isinstance(rule_groups, list) or not rule_groups:
2735
+ raise ValueError(
2736
+ "filter section requires config.rules with at least one rule group; "
2737
+ "an empty-rules filter is written but invisible in portal get readback"
2738
+ )
2727
2739
  return self
2728
2740
 
2729
2741
 
@@ -2762,6 +2774,14 @@ class PortalApplyRequest(StrictModel):
2762
2774
  payload = dict(value)
2763
2775
  payload.pop("schema_version", None)
2764
2776
  payload.pop("schemaVersion", None)
2777
+ # 不发布场景已移除(负责人决策):apply 一律发布。显式 false 明确拒绝,
2778
+ # true/缺省按键消费走默认行为(publish 字段恒 true,仅保留内部默认)。
2779
+ if payload.get("publish") is False:
2780
+ raise ValueError(
2781
+ "portal apply always publishes; the draft-only (publish=false) scenario has been "
2782
+ "removed — delete the publish field from the declaration"
2783
+ )
2784
+ payload.pop("publish", None)
2765
2785
  # schema 文档声明的别名补全(dashKey/dashName):此前条件判断里出现了 dashName
2766
2786
  # 却从未消费,别名声明撞上 StrictModel 被拒,形成 validate 提示与 apply 行为
2767
2787
  # 不一致的观感(实测反馈失败二)。canonical 键优先;别名始终被消费(与 canonical
@@ -50,7 +50,7 @@
50
50
  "publish": {
51
51
  "type": "boolean",
52
52
  "default": true,
53
- "publishCompleteDescription": "apply 后是否发布(true=写后发布并回读线上态;false=仅落草稿)。这是生命周期动作参数,不属于声明内容,幂等重放时用 false。注意:对已发布门户用 false 更新会把发布状态降回草稿——需要保留线上态时不要用 false 试写。"
53
+ "publishCompleteDescription": "apply 一律自动发布(写后发布并回读线上态),不存在草稿-only 门户。本字段已废弃:显式 false 会被拒绝,true/缺省等同默认行为。"
54
54
  },
55
55
  "icon": {
56
56
  "type": "string",
@@ -944,7 +944,7 @@
944
944
  "FilterConfig": {
945
945
  "type": "object",
946
946
  "additionalProperties": false,
947
- "filterConfigShapeDescription": "筛选组件配置(受控键集;filter 组件语义 raw/unstable,不建议作为主自动化路径)。graphs 为受影响的图表引用,rules 为筛选规则组(键集以 ws40013 dataset 实测形态定稿)。",
947
+ "filterConfigShapeDescription": "筛选组件配置(受控键集)。graphs 为受影响的图表引用;rules 为筛选规则组,键集 filterGroupName/filterGroupConfig/filterItemName/que/judge 系(受控透传,dataset 实测形态定稿;代理键 filterGroupId/filterItemId 剔除)。rules 必须至少 1 组——后端读面按筛选组反查筛选组件,空规则的 filter 写入后读面不可见(模型层已阻断)。",
948
948
  "properties": {
949
949
  "graphs": {
950
950
  "type": "array",
@@ -965,7 +965,7 @@
965
965
  },
966
966
  "rules": {
967
967
  "type": "array",
968
- "filterRulesDescription": "筛选规则组(受控透传;dataset 校准后开放规范键)。",
968
+ "filterRulesDescription": "筛选规则组(至少 1 组;空规则组件读面不可见)。组键 filterGroupName(必填)/filterGroupConfig(筛选项:filterItemName/que{queId}/judge{judgeType,judgeValues})。",
969
969
  "x-backend": "ComponentFilter.filterConfig(List<FilterConfig>)"
970
970
  }
971
971
  }
@@ -1119,7 +1119,7 @@
1119
1119
  "integer",
1120
1120
  "null"
1121
1121
  ],
1122
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
1122
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
1123
1123
  "x-backend": "ComponentGridItemInfo.linkFormType"
1124
1124
  },
1125
1125
  "linkDashKey": {
@@ -57,9 +57,9 @@
57
57
  "type": "object",
58
58
  "additionalProperties": false,
59
59
  "required": [
60
- "groups"
60
+ "rules"
61
61
  ],
62
- "filterConfigShapeDescription": "筛选组件配置。筛选语义 raw/unstable,不建议作为主自动化路径;条件明细为受控透传(键集以 ws40013 dataset 实测形态定稿)。",
62
+ "filterConfigShapeDescription": "筛选组件配置。rules 必须非空——后端读面(DashSvcImpl#getComponentFilter)按筛选组(dash_filter_group 行)反查筛选组件,空规则的 filter 组件行虽会写入但读面枚举不到,表现为「apply 成功、回读缺该组件」;规则键集为受控透传(filterGroupName/filterGroupConfig/filterItemName/que/judge 系,以 ws40013 dataset 实测形态定稿)。",
63
63
  "properties": {
64
64
  "graphs": {
65
65
  "type": "array",
@@ -69,12 +69,12 @@
69
69
  },
70
70
  "x-backend": "ComponentFilter.graphList(GraphVO.graphKey/graphName/graphType)"
71
71
  },
72
- "groups": {
72
+ "rules": {
73
73
  "type": "array",
74
74
  "minItems": 1,
75
- "filterGroupsShapeDescription": "筛选规则组。",
75
+ "filterRulesShapeDescription": "筛选规则组(至少 1 组)。组键:filterGroupName(组名,必填)、filterGroupConfig(组内筛选项列表);项键:filterItemName、que{queId}(绑定字段)、judge{judgeType,judgeValues}(默认条件)。代理键 filterGroupId/filterItemId 为后端自增位移键,读写两侧均剔除,不要携带。",
76
76
  "items": {
77
- "$ref": "#/$defs/FilterGroup"
77
+ "$ref": "#/$defs/FilterRuleGroup"
78
78
  },
79
79
  "x-backend": "ComponentFilter.filterConfig(List<FilterConfig>)"
80
80
  }
@@ -109,71 +109,49 @@
109
109
  }
110
110
  }
111
111
  },
112
- "FilterGroup": {
112
+ "FilterRuleGroup": {
113
113
  "type": "object",
114
- "additionalProperties": false,
115
114
  "required": [
116
- "items"
115
+ "filterGroupName"
117
116
  ],
118
- "filterGroupShapeDescription": "筛选规则组。",
117
+ "filterRuleGroupShapeDescription": "筛选规则组。组内筛选项走 filterGroupConfig;其余后端键受控透传。",
119
118
  "properties": {
120
- "group_id": {
121
- "type": "integer",
122
- "filterGroupIdShapeDescription": "组 id(更新已有组时锚定;缺省新建)。",
123
- "x-backend": "FilterConfig.filterGroupId"
124
- },
125
- "name": {
119
+ "filterGroupName": {
126
120
  "type": "string",
127
- "filterGroupNameShapeDescription": "组名称。",
121
+ "filterRuleGroupNameShapeDescription": "组名称(读面渲染为分组标题)。",
128
122
  "x-backend": "FilterConfig.filterGroupName"
129
123
  },
130
- "items": {
124
+ "filterGroupConfig": {
131
125
  "type": "array",
132
- "minItems": 1,
133
- "filterGroupItemsShapeDescription": "组内筛选项。",
126
+ "filterRuleGroupItemsShapeDescription": "组内筛选项(绑定字段与默认条件)。",
134
127
  "items": {
135
- "$ref": "#/$defs/FilterItem"
136
- }
128
+ "$ref": "#/$defs/FilterRuleItem"
129
+ },
130
+ "x-backend": "FilterConfig.filterGroupConfig(List<FilterGroupConfig>)"
137
131
  }
138
132
  }
139
133
  },
140
- "FilterItem": {
134
+ "FilterRuleItem": {
141
135
  "type": "object",
142
- "additionalProperties": false,
143
136
  "required": [
144
- "name"
137
+ "filterItemName"
145
138
  ],
146
- "filterItemShapeDescription": "单个筛选项(绑定一个字段)。",
139
+ "filterRuleItemShapeDescription": "单个筛选项(绑定一个字段)。que/judge 为后端受控透传形态;条件表达式(关联图表/字段)键集以 dataset 实测形态为准。",
147
140
  "properties": {
148
- "item_id": {
149
- "type": "integer",
150
- "filterItemIdShapeDescription": "筛选项 id(更新锚定)。",
151
- "x-backend": "FilterGroupConfig.filterItemId"
152
- },
153
- "name": {
141
+ "filterItemName": {
154
142
  "type": "string",
155
- "filterItemNameShapeDescription": "筛选项名称。",
143
+ "filterRuleItemNameShapeDescription": "筛选项名称。",
156
144
  "x-backend": "FilterGroupConfig.filterItemName"
157
145
  },
158
- "conditions": {
159
- "type": "array",
160
- "filterItemConditionsShapeDescription": "筛选条件(受控透传;条件表达式键集以 dataset 实测形态定稿后开放规范键)。",
161
- "x-backend": "FilterGroupConfig.filterCondition(List<FilterCondition>)"
162
- },
163
- "default_judge_type": {
164
- "type": "integer",
165
- "filterItemDftJudgeTypeShapeDescription": "默认比较符。",
166
- "x-backend": "FilterGroupConfig.dftJudgeType"
167
- },
168
- "default_values": {
169
- "type": "array",
170
- "filterItemDftValuesShapeDescription": "默认比较值(受控透传)。",
171
- "x-backend": "FilterGroupConfig.dftJudgeValue(List<AnswerValue>)"
146
+ "que": {
147
+ "type": "object",
148
+ "filterRuleItemQueShapeDescription": "绑定的字段引用(queId 为字段唯一键)。",
149
+ "x-backend": "FilterGroupConfig.que(Question)"
172
150
  },
173
- "filter_type": {
174
- "type": "string",
175
- "filterItemTypeShapeDescription": "筛选项交互类型(受控枚举,dataset 校准)。",
176
- "x-backend": "FilterGroupConfig.filterType"
151
+ "judge": {
152
+ "type": "object",
153
+ "filterRuleItemJudgeShapeDescription": "默认筛选条件:judgeType(比较符)+judgeValues(比较值列表)。",
154
+ "x-backend": "FilterGroupConfig.dftJudgeType/dftJudgeValue"
177
155
  }
178
156
  }
179
157
  },
@@ -181,16 +159,14 @@
181
159
  "type": "object",
182
160
  "additionalProperties": false,
183
161
  "required": [
184
- "title",
185
162
  "source_type",
186
163
  "config"
187
164
  ],
188
165
  "properties": {
189
166
  "title": {
190
167
  "type": "string",
191
- "minLength": 1,
192
- "sectionTitleShapeDescription": "组件标题(渲染在组件头部)。",
193
- "x-backend": "组件标题(DashChartInfo.title / gridConfig.gridTitle 等)"
168
+ "sectionTitleShapeDescription": "组件标题(可选)。存量筛选组件合法无标题——后端筛选组件无标题存储,提取产物不带 title,不要合成(如「组件 N」)。",
169
+ "x-backend": "组件标题(筛选组件无标题存储;其余组件见 DashChartInfo.title / gridConfig.gridTitle 等)"
194
170
  },
195
171
  "source_type": {
196
172
  "const": "filter",
@@ -211,7 +187,7 @@
211
187
  },
212
188
  "config": {
213
189
  "$ref": "#/$defs/FilterConfig",
214
- "filterConfigPropDescription": "筛选配置(必填,groups 非空)。"
190
+ "filterConfigPropDescription": "筛选配置(必填,rules 至少 1 组)。"
215
191
  }
216
192
  }
217
193
  }
@@ -230,7 +206,6 @@
230
206
  },
231
207
  "examples": [
232
208
  {
233
- "title": "数据筛选",
234
209
  "source_type": "filter",
235
210
  "position": {
236
211
  "pc": {
@@ -249,15 +224,21 @@
249
224
  "chart_name": "故障类型分布"
250
225
  }
251
226
  ],
252
- "groups": [
227
+ "rules": [
253
228
  {
254
- "name": "默认组",
255
- "items": [
229
+ "filterGroupName": "区域",
230
+ "filterGroupConfig": [
256
231
  {
257
- "name": "报修日期",
258
- "default_judge_type": 1,
259
- "default_values": [],
260
- "filter_type": "dateRange"
232
+ "filterItemName": "城市",
233
+ "que": {
234
+ "queId": 123456
235
+ },
236
+ "judge": {
237
+ "judgeType": 3,
238
+ "judgeValues": [
239
+ "上海"
240
+ ]
241
+ }
261
242
  }
262
243
  ]
263
244
  }
@@ -112,7 +112,7 @@
112
112
  "integer",
113
113
  "null"
114
114
  ],
115
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
115
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
116
116
  "x-backend": "ComponentGridItemInfo.linkFormType"
117
117
  },
118
118
  "linkDashKey": {
@@ -49,7 +49,7 @@
49
49
  "publish": {
50
50
  "type": "boolean",
51
51
  "default": true,
52
- "publishDescription": "apply 后是否发布(true=写后发布并回读线上态;false=仅落草稿)。这是生命周期动作参数,不属于声明内容,幂等重放时用 false。注意:对已发布门户用 false 更新会把发布状态降回草稿——需要保留线上态时不要用 false 试写。",
52
+ "publishDescription": "apply 一律自动发布(写后发布并回读线上态),不存在草稿-only 门户。本字段已废弃:显式 false 会被拒绝,true/缺省等同默认行为。",
53
53
  "x-backend": "(编排层,不落库)"
54
54
  }
55
55
  }
@@ -607,7 +607,7 @@
607
607
  "integer",
608
608
  "null"
609
609
  ],
610
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
610
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
611
611
  "x-backend": "ComponentGridItemInfo.linkFormType"
612
612
  },
613
613
  "linkDashKey": {
@@ -15534,6 +15534,7 @@ class AiBuilderFacade:
15534
15534
  suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
15535
15535
  )
15536
15536
  write_executed = False
15537
+ sections_write_completed = False
15537
15538
  draft_readback_error: JSONObject | None = None
15538
15539
  live_readback_error: JSONObject | None = None
15539
15540
  update_payload: dict[str, Any] = {}
@@ -15605,6 +15606,7 @@ class AiBuilderFacade:
15605
15606
  self._portal_writer.update_portal(profile=profile, dash_key=dash_key, payload=update_payload)
15606
15607
  portal_update_ms = _duration_ms(portal_update_started_at)
15607
15608
  write_executed = True
15609
+ sections_write_completed = True
15608
15610
  else:
15609
15611
  portal_component_build_ms = 0
15610
15612
  portal_update_ms = 0
@@ -15656,6 +15658,52 @@ class AiBuilderFacade:
15656
15658
  except (QingflowApiError, RuntimeError, ValueError) as error:
15657
15659
  api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
15658
15660
  inline_chart_write_executed = any(bool(item.get("write_executed")) for item in inline_chart_results)
15661
+ # 本次 apply 创建的空壳回收:创建成功但 sections 未写入且无内联图表写入时,
15662
+ # 删除刚建的门户壳,阻断「失败重试 → 0 组件空门户堆积」(实测反馈 3 个空壳)。
15663
+ # 更新语义(dash_key 定位)与已有真实写入的场景不回收。
15664
+ if creating and dash_key and not sections_write_completed and not inline_chart_write_executed:
15665
+ cleanup: dict[str, Any] | None = None
15666
+ try:
15667
+ self.portals.portal_delete(profile=profile, dash_key=dash_key)
15668
+ cleanup = {"status": "deleted", "dash_key": dash_key}
15669
+ except (QingflowApiError, RuntimeError) as cleanup_error:
15670
+ cleanup = {
15671
+ "status": "failed",
15672
+ "dash_key": dash_key,
15673
+ "message": _coerce_api_error(cleanup_error).message,
15674
+ }
15675
+ if cleanup.get("status") == "deleted":
15676
+ return finalize(
15677
+ {
15678
+ "status": "failed",
15679
+ "error_code": "PORTAL_APPLY_FAILED",
15680
+ "recoverable": True,
15681
+ "message": (
15682
+ "portal apply failed before sections were written; the empty portal shell "
15683
+ "created in this call was cleaned up — retry the same declaration safely"
15684
+ ),
15685
+ "normalized_args": normalized_args,
15686
+ "missing_fields": [],
15687
+ "allowed_values": {},
15688
+ "details": {
15689
+ "created_portal_cleanup": cleanup,
15690
+ "write_error": (
15691
+ {"message": api_error.message, "transport_error": _transport_error_payload(api_error)}
15692
+ if api_error is not None
15693
+ else {"message": str(error)}
15694
+ ),
15695
+ **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
15696
+ },
15697
+ "request_id": api_error.request_id if api_error else None,
15698
+ "backend_code": api_error.backend_code if api_error else None,
15699
+ "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
15700
+ "suggested_next_call": {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
15701
+ "noop": False,
15702
+ "warnings": [],
15703
+ "verification": {"write_incomplete": True, "created_portal_cleaned_up": True},
15704
+ }
15705
+ )
15706
+ # 清理失败:空壳仍在,带 dash_key 走 partial 语义交人工处理
15659
15707
  if write_executed or inline_chart_write_executed:
15660
15708
  transport_error = _transport_error_payload(api_error) if api_error is not None else None
15661
15709
  warning = _warning(
@@ -17034,12 +17082,22 @@ class AiBuilderFacade:
17034
17082
  component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
17035
17083
  layout_metadata.append({"source_type": section.source_type, "role": section.role})
17036
17084
  elif section.source_type == "grid":
17085
+ # 应用入口跳转页面缺省:声明未给 linkFormType 的 type=1 条目按 1(数据列表)
17086
+ # 补齐——缺失时前端渲染的跳转目标为空、入口无法点击(实测反馈)。其余
17087
+ # 入口类型(2=门户/3=应用包/4=外链)不走该键,显式值一律保留。
17088
+ grid_config_payload = deepcopy(section.config)
17089
+ grid_items = grid_config_payload.get("items") if isinstance(grid_config_payload, dict) else None
17090
+ if isinstance(grid_items, list):
17091
+ for grid_item in grid_items:
17092
+ if isinstance(grid_item, dict) and _coerce_positive_int(grid_item.get("type")) == 1:
17093
+ if _coerce_positive_int(grid_item.get("linkFormType")) is None:
17094
+ grid_item["linkFormType"] = 1
17037
17095
  component = {
17038
17096
  "type": 2,
17039
17097
  "position": position_payload,
17040
17098
  # gridTitle=None(存量空标题)剔除不落库;beingShowTitle 缺省 True、声明 config 内
17041
17099
  # beingShowTitle 键后置覆盖(提取侧 grid config 保留该键,存量 false 保真)。
17042
- "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
17100
+ "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **(grid_config_payload if isinstance(grid_config_payload, dict) else {})}),
17043
17101
  }
17044
17102
  layout_metadata.append({"source_type": section.source_type, "role": section.role})
17045
17103
  elif section.source_type == "filter":
@@ -293,7 +293,6 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
293
293
  portal_apply.add_argument("--dash-key", default="")
294
294
  portal_apply.add_argument("--dash-name", default="")
295
295
  portal_apply.add_argument("--package-id", type=int)
296
- portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=None, help="发布开关;--file 声明模式下缺省尊重声明内 publish 字段(再缺省 true),显式传参时覆盖声明值")
297
296
  portal_apply.add_argument("--payload-file", help="兼容:完整门户 payload JSON(裸 DTO 透传);新代码改用 --file")
298
297
  portal_apply.add_argument("--sections-file")
299
298
  portal_apply.add_argument("--layout-preset", default="")
@@ -1470,22 +1469,12 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1470
1469
  file_declaration.setdefault("package_tag_id", args.package_id)
1471
1470
  if getattr(args, "dash_key", ""):
1472
1471
  file_declaration["dash_key"] = args.dash_key
1473
- # publish 三态对齐 MCP(声明值优先、显式 flag 最高):声明内 publish 弹出后由 flag 解析——
1474
- # flag 未传时尊重声明值(含幂等重放的 publish:false),声明也未写时才缺省 true。
1475
- flag_publish = getattr(args, "publish", None)
1476
- declaration_publish = file_declaration.pop("publish", None)
1477
- effective_publish = (
1478
- bool(flag_publish)
1479
- if flag_publish is not None
1480
- else (bool(declaration_publish) if declaration_publish is not None else True)
1481
- )
1482
1472
  file_schema_version = str(file_declaration.pop("schema_version", None) or file_declaration.pop("schemaVersion", None) or "").strip() or None
1483
1473
  effective_schema_version = getattr(args, "schema_version", None) or file_schema_version
1484
1474
  return context.builder.portal_apply(
1485
1475
  profile=args.profile,
1486
1476
  payload=file_declaration,
1487
1477
  schema_version=effective_schema_version,
1488
- publish=effective_publish,
1489
1478
  )
1490
1479
  # deprecation 提示仅在实际使用 patch 参数时打印(review §5 噪声收敛):
1491
1480
  # 纯 flag 调用(--dash-key/--publish/--schema-version/--package-id 定位或发布
@@ -1539,7 +1528,6 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1539
1528
  dash_key=args.dash_key,
1540
1529
  dash_name=args.dash_name,
1541
1530
  package_id=args.package_id,
1542
- publish=bool(args.publish if args.publish is not None else True),
1543
1531
  sections=sections,
1544
1532
  layout_preset=args.layout_preset,
1545
1533
  visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -637,7 +637,6 @@ def build_builder_server() -> PolicyAwareFastMCP:
637
637
  dash_name: str = "",
638
638
  name: str = "",
639
639
  package_id: int | None = None,
640
- publish: bool = True,
641
640
  sections: list[dict] | None = None,
642
641
  pages: list[dict] | None = None,
643
642
  layout_preset: str = "",
@@ -677,7 +676,6 @@ def build_builder_server() -> PolicyAwareFastMCP:
677
676
  dash_name=dash_name,
678
677
  name=name,
679
678
  package_id=package_id,
680
- publish=publish,
681
679
  sections=sections or [],
682
680
  pages=pages or [],
683
681
  layout_preset=layout_preset,
@@ -858,7 +858,6 @@ class AiBuilderTools(ToolBase):
858
858
  dash_name: str = "",
859
859
  name: str = "",
860
860
  package_id: int | None = None,
861
- publish: bool = True,
862
861
  sections: list[JSONObject] | None = None,
863
862
  pages: list[JSONObject] | None = None,
864
863
  layout_preset: str = "",
@@ -900,7 +899,6 @@ class AiBuilderTools(ToolBase):
900
899
  dash_name=dash_name,
901
900
  name=name,
902
901
  package_id=package_id,
903
- publish=publish,
904
902
  sections=sections or [],
905
903
  pages=pages or [],
906
904
  layout_preset=layout_preset,
@@ -4296,7 +4294,6 @@ class AiBuilderTools(ToolBase):
4296
4294
  dash_name: str = "",
4297
4295
  name: str = "",
4298
4296
  package_id: int | None = None,
4299
- publish: bool = True,
4300
4297
  sections: list[JSONObject] | None = None,
4301
4298
  pages: list[JSONObject] | None = None,
4302
4299
  layout_preset: str = "",
@@ -4318,7 +4315,6 @@ class AiBuilderTools(ToolBase):
4318
4315
  if patch_sections is not None:
4319
4316
  normalized_args = {
4320
4317
  "dash_key": dash_key,
4321
- "publish": publish,
4322
4318
  "patch_sections": patch_sections,
4323
4319
  }
4324
4320
  return self._attach_apply_envelope(profile, "portal_apply", _publicize_package_fields(_safe_tool_call(
@@ -4326,7 +4322,6 @@ class AiBuilderTools(ToolBase):
4326
4322
  profile=profile,
4327
4323
  dash_key=dash_key,
4328
4324
  patch_sections=patch_sections,
4329
- publish=publish,
4330
4325
  ),
4331
4326
  error_code="PORTAL_PATCH_FAILED",
4332
4327
  normalized_args=normalized_args,
@@ -4341,8 +4336,6 @@ class AiBuilderTools(ToolBase):
4341
4336
  request_payload["name"] = name
4342
4337
  if package_id is not None:
4343
4338
  request_payload["package_id"] = package_id
4344
- if "publish" not in request_payload or publish is False:
4345
- request_payload["publish"] = publish
4346
4339
  if sections:
4347
4340
  request_payload["sections"] = sections
4348
4341
  if pages:
@@ -4386,7 +4379,6 @@ class AiBuilderTools(ToolBase):
4386
4379
  "profile": profile,
4387
4380
  "dash_name": dash_name or "业务门户",
4388
4381
  "package_id": package_id or 1001,
4389
- "publish": True,
4390
4382
  "layout_preset": "dashboard_2col",
4391
4383
  "sections": [
4392
4384
  {