@josephyan/qingflow-cli 1.1.2 → 1.1.4

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.1.2
+npm install @josephyan/qingflow-cli@1.1.4
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.1.2 qingflow
+npx -y -p @josephyan/qingflow-cli@1.1.4 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.2"
+version = "1.1.4"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md

@@ -428,6 +428,7 @@ qingflow builder button apply \
 默认使用 `qingflow builder associated-resource apply` 管理应用级关联资源池与视图展示配置。
 
 - 权限分层：`upsert_resources` / `patch_resources` / 删除 / 排序应用级关联资源池走 **EditAppAuth**；`view_configs` 修改某个视图里的关联资源展示配置，还需要视图配置侧的 **ViewManagementAuth**（未开启高级应用权限时回落到 **DataManageAuth**）。
+- 多应用批量配置时可用 `--apps-file`，文件为 JSON 数组，每项写 `{ "app_key": "...", "upsert_resources": [...], "patch_resources": [...], "remove_associated_item_ids": [...], "reorder_associated_item_ids": [...], "view_configs": [...] }`；不要和单应用的 `--app-key` / `--*-file` 混用。
 
 ```bash
 qingflow builder associated-resource apply \
@@ -436,6 +437,11 @@ qingflow builder associated-resource apply \
   --view-configs-file tmp/associated_view_configs.json
 ```
 
+```bash
+qingflow builder associated-resource apply \
+  --apps-file tmp/associated_resource_apps.json
+```
+
 - Shell 退出码为 0、重定向成功或 `echo OK` 只表示命令执行完，不表示业务成功。必须读取输出 JSON，检查顶层 `status`、`error_code`、`warnings`、`blocking_issues`；`status: failed`、`partial_success`、`ASSOCIATED_RESOURCES_APPLY_BLOCKED` 都不能当作完成。
 - 关联资源要生效必须同时处理两层：应用级资源池（`upsert_resources` / `patch_resources`）和视图详情展示绑定（`view_configs`）。只传 `--upsert-resources-file` 往往只是在资源池准备资源，不会让按钮或视图详情里看到关联资源。
 - `builder views apply` 新建视图会默认打开详情页关联查看（展示全部应用级关联资源）；若只需要默认展示全部资源，创建视图时不用额外写 `view_configs`。需要指定部分资源、关闭展示或配置匹配筛选时，仍必须使用本工具的 `view_configs` / `match_mappings`。

package/src/qingflow_mcp/builder_facade/models.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from enum import Enum
 from typing import Any
 
@@ -1762,6 +1763,70 @@ class ChartFilterRulePatch(StrictModel):
         return self
 
 
+_CHART_METRIC_RE = re.compile(r"^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*)\)\s*$")
+
+
+def _normalize_chart_string_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple)):
+        return [str(item).strip() for item in value if item is not None and str(item).strip()]
+    raw = str(value).strip()
+    return [raw] if raw else []
+
+
+def _parse_chart_metric_item(value: Any) -> tuple[list[str], str | None]:
+    if value is None:
+        return [], None
+    if isinstance(value, dict):
+        op = str(value.get("op") or value.get("agg") or value.get("aggregate") or value.get("aggregation") or "").strip().lower()
+        field = value.get("field", value.get("field_name", value.get("name", value.get("selector"))))
+        selectors = _normalize_chart_string_list(field)
+        return selectors, op or ("count" if not selectors else None)
+    raw = str(value).strip()
+    if not raw:
+        return [], None
+    matched = _CHART_METRIC_RE.match(raw)
+    if matched:
+        op = matched.group(1).strip().lower()
+        field = matched.group(2).strip()
+        if field in {"*", ""}:
+            return [], op
+        return [field], op
+    if raw.lower() in {"count", "count(*)"}:
+        return [], "count"
+    return [raw], None
+
+
+def _apply_semantic_chart_metric_aliases(payload: dict[str, Any]) -> None:
+    raw_metrics: list[Any] = []
+    if "metric" in payload:
+        raw_metrics.append(payload.pop("metric"))
+    if "metrics" in payload:
+        metrics = payload.pop("metrics")
+        raw_metrics.extend(metrics if isinstance(metrics, list) else [metrics])
+    if not raw_metrics:
+        return
+    selectors: list[str] = []
+    aggregates: list[str] = []
+    for metric in raw_metrics:
+        metric_selectors, aggregate = _parse_chart_metric_item(metric)
+        selectors.extend(metric_selectors)
+        if aggregate:
+            aggregates.append(aggregate)
+    if selectors and "indicator_field_ids" not in payload:
+        payload["indicator_field_ids"] = selectors
+    if aggregates:
+        normalized_aggregate = aggregates[0]
+        config = payload.get("config")
+        if not isinstance(config, dict):
+            config = {}
+        else:
+            config = dict(config)
+        config.setdefault("aggregate", normalized_aggregate)
+        payload["config"] = config
+
+
 class ChartUpsertPatch(StrictModel):
     chart_id: str | None = None
     name: str
@@ -1790,6 +1855,15 @@ class ChartUpsertPatch(StrictModel):
             payload["indicator_field_ids"] = payload.pop("indicator_fields")
         if "metric_field_ids" in payload and "indicator_field_ids" not in payload:
             payload["indicator_field_ids"] = payload.pop("metric_field_ids")
+        if "group_by" in payload and "dimension_field_ids" not in payload:
+            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("group_by"))
+        if "groupBy" in payload and "dimension_field_ids" not in payload:
+            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("groupBy"))
+        if "where" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("where")
+        else:
+            payload.pop("where", None)
+        _apply_semantic_chart_metric_aliases(payload)
         raw_type = payload.get("chart_type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -1980,6 +2054,7 @@ class PortalViewRefPatch(StrictModel):
 class PortalSectionPatch(StrictModel):
     title: str
     source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
+    role: str | None = None
     position: PortalComponentPositionPatch | None = None
     dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
     config: dict[str, Any] = Field(default_factory=dict)
@@ -2010,6 +2085,13 @@ class PortalSectionPatch(StrictModel):
         supported = {"chart", "view", "grid", "filter", "text", "link"}
         if self.source_type not in supported:
             raise ValueError(f"unsupported portal source_type '{self.source_type}'")
+        if self.role is not None:
+            normalized_role = str(self.role or "").strip().lower()
+            if normalized_role not in {"metric"}:
+                raise ValueError(f"unsupported portal section role '{self.role}'")
+            self.role = normalized_role
+            if self.source_type != "chart":
+                raise ValueError("portal section role is only supported for chart sections")
         if self.source_type == "chart" and self.chart_ref is None:
             raise ValueError("chart section requires chart_ref")
         if self.source_type == "view" and self.view_ref is None:

package/src/qingflow_mcp/builder_facade/service.py

@@ -1184,6 +1184,24 @@ class AiBuilderFacade:
                 suggested_next_call=None,
             )
 
+        if not normalized_items and not current_resources and not current_group_specs:
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "package items already empty; skipped package sort",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {"group_operations": [], "sort_skipped": True},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": True,
+                "warnings": [],
+                "verification": {"layout_verified": True, "sort_skipped": True},
+                "verified": True,
+            }
+
         duplicate_resources = _find_duplicate_package_resources(normalized_items)
         if duplicate_resources:
             return _failed(
@@ -5344,7 +5362,7 @@ class AiBuilderFacade:
         for app_key in app_keys:
             try:
                 result = single_reader(profile=profile, app_key=app_key)
-                status = result.get("status", "")
+                status = str(result.get("status") or "").strip().lower()
                 if status in {"success", "partial_success"}:
                     app_results.append(_batch_read_app_item(app_key=app_key, result=result, data_key=data_key))
                 else:
@@ -5429,7 +5447,7 @@ class AiBuilderFacade:
                 details={"app_key": app_key},
                 suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, "app_key": app_key}},
             )
-        if current.get("status") != "success":
+        if str(current.get("status") or "").strip().lower() != "success":
             return _failed(
                 "FLOW_READ_FAILED",
                 current.get("message") or "failed to read current flow",
@@ -5473,6 +5491,16 @@ class AiBuilderFacade:
                 normalized_args={"app_key": app_key, "not_found_ids": not_found},
                 suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
             )
+        edge_container = spec.get("edges") if isinstance(spec.get("edges"), dict) else {}
+        edges = edge_container.get("edges") if isinstance(edge_container, dict) else None
+        transitions = spec.get("transitions") if isinstance(spec.get("transitions"), list) else None
+        if not edges and not transitions:
+            return _failed(
+                "FLOW_PATCH_EMPTY_GRAPH_UNSUPPORTED",
+                "current flow spec has no edges; patch_nodes cannot safely save this backend shape. Use full app_flow_apply to create a workflow with edges first.",
+                normalized_args={"app_key": app_key, "patch_nodes": patch_nodes},
+                suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         return self.flow_apply(
             profile=profile,
             app_key=app_key,
@@ -5486,6 +5514,9 @@ class AiBuilderFacade:
         result = []
         for c in components:
             item = {k: v for k, v in c.items() if k != "order"}
+            position = item.get("position")
+            if isinstance(position, dict):
+                item["position"] = _portal_component_position_for_request(position)
             result.append(item)
         return result
 
@@ -13830,6 +13861,73 @@ def _two_gauge_metric_fields(metrics: list[dict[str, Any]], *, requested_metric_
     return [deepcopy(metrics[0]), deepcopy(metrics[1])]
 
 
+def _qingbi_filter_judge_type(operator: str) -> str:
+    return {
+        ViewFilterOperator.eq.value: "equal",
+        ViewFilterOperator.neq.value: "notEqual",
+        ViewFilterOperator.gte.value: "greaterOrEqual",
+        ViewFilterOperator.lte.value: "lessOrEqual",
+        ViewFilterOperator.in_.value: "anyMatch",
+        ViewFilterOperator.contains.value: "contains",
+        ViewFilterOperator.is_empty.value: "isNull",
+        ViewFilterOperator.not_empty.value: "isNotNull",
+    }.get(operator, "equal")
+
+
+def _qingbi_option_label_lookup(*, form_field: dict[str, Any], qingbi_field: dict[str, Any]) -> dict[str, str]:
+    labels: dict[str, str] = {}
+
+    def add_option(raw_option: Any) -> None:
+        if isinstance(raw_option, dict):
+            label = raw_option.get("value")
+            if label is None:
+                label = raw_option.get("label") or raw_option.get("name") or raw_option.get("title") or raw_option.get("optValue")
+            label_text = str(label).strip() if label is not None else ""
+            for key in ("id", "optionId", "option_id", "optId", "value", "label", "name", "title", "optValue"):
+                raw_key = raw_option.get(key)
+                if raw_key is not None and str(raw_key).strip() and label_text:
+                    labels[str(raw_key).strip()] = label_text
+        elif raw_option is not None:
+            label_text = str(raw_option).strip()
+            if label_text:
+                labels[label_text] = label_text
+
+    for option in form_field.get("option_details") or []:
+        add_option(option)
+    for option in form_field.get("options") or []:
+        add_option(option)
+    for option in qingbi_field.get("options") or qingbi_field.get("option_details") or []:
+        add_option(option)
+    return labels
+
+
+def _qingbi_filter_text_values(values: list[Any], *, form_field: dict[str, Any], qingbi_field: dict[str, Any]) -> list[str]:
+    labels = _qingbi_option_label_lookup(form_field=form_field, qingbi_field=qingbi_field)
+    normalized: list[str] = []
+    for value in values:
+        if isinstance(value, dict):
+            raw_label = value.get("value") or value.get("label") or value.get("name") or value.get("title") or value.get("optValue")
+            if raw_label is not None and str(raw_label).strip():
+                normalized.append(str(raw_label).strip())
+                continue
+            raw_id = value.get("id") or value.get("optionId") or value.get("option_id") or value.get("optId")
+            raw_text = str(raw_id).strip() if raw_id is not None else ""
+        else:
+            raw_text = str(value).strip()
+        if not raw_text:
+            continue
+        normalized.append(labels.get(raw_text, raw_text))
+    return normalized
+
+
+def _qingbi_filter_judge_value(values: list[str]) -> Any:
+    if not values:
+        return ""
+    if len(values) == 1:
+        return values[0]
+    return values
+
+
 def _build_public_chart_filter_matrix(
     rules: list[Any],
     *,
@@ -13842,16 +13940,6 @@ def _build_public_chart_filter_matrix(
     if not rules:
         return []
     group: list[dict[str, Any]] = []
-    judge_map = {
-        ViewFilterOperator.eq.value: 0,
-        ViewFilterOperator.neq.value: 1,
-        ViewFilterOperator.gte.value: 5,
-        ViewFilterOperator.lte.value: 7,
-        ViewFilterOperator.in_.value: 9,
-        ViewFilterOperator.contains.value: 19,
-        ViewFilterOperator.is_empty.value: 15,
-        ViewFilterOperator.not_empty.value: 16,
-    }
     for rule in rules:
         qingbi_field = _resolve_qingbi_chart_field(
             getattr(rule, "field_name", None),
@@ -13863,13 +13951,15 @@ def _build_public_chart_filter_matrix(
         form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         operator = str(getattr(rule, "operator", ViewFilterOperator.eq.value).value if hasattr(getattr(rule, "operator", None), "value") else getattr(rule, "operator", ViewFilterOperator.eq.value))
         values = list(getattr(rule, "values", []) or [])
+        text_values = _qingbi_filter_text_values(values, form_field=form_field, qingbi_field=qingbi_field)
         group.append(
             {
                 "fieldId": field_id,
                 "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
                 "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
-                "judgeType": judge_map.get(operator, 0),
-                "judgeValues": values,
+                "judgeType": _qingbi_filter_judge_type(operator),
+                "judgeValue": _qingbi_filter_judge_value(text_values),
+                "judgeValues": text_values,
                 "matchType": 1,
             }
         )
@@ -14180,6 +14270,27 @@ def _portal_position_payload(position: Any, *, inferred_mobile_y: int = 0) -> di
     }
 
 
+def _portal_component_position_for_request(position: dict[str, Any]) -> dict[str, Any]:
+    """Normalize portal_get component positions into PortalSectionPatch input shape."""
+    payload = deepcopy(position)
+    if isinstance(payload.get("pc"), dict) or isinstance(payload.get("mobile"), dict):
+        return payload
+    pc_keys = {"x", "y", "cols", "rows"}
+    if any(key in payload for key in pc_keys):
+        pc = {
+            "x": int(payload.get("x") or 0),
+            "y": int(payload.get("y") or 0),
+            "cols": int(payload.get("cols") or payload.get("w") or 12),
+            "rows": int(payload.get("rows") or payload.get("h") or 8),
+        }
+        normalized: dict[str, Any] = {"pc": pc}
+        mobile = payload.get("mobile")
+        if isinstance(mobile, dict):
+            normalized["mobile"] = mobile
+        return normalized
+    return payload
+
+
 def _portal_component_position_public(
     source_type: Any,
     *,
@@ -14261,15 +14372,26 @@ def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: l
             pc_positions.append(pc)
         section = sections[index] if index < len(sections) else None
         source_type = str(getattr(section, "source_type", "") or "").lower() if section is not None else ""
+        role = str(getattr(section, "role", "") or "").lower() if section is not None else ""
         title = str(getattr(section, "title", "") or "").strip() if section is not None else None
         cols = int(pc.get("cols") or 0)
         rows = int(pc.get("rows") or 0)
-        if source_type == "chart" and (cols < 8 or rows < 5):
+        if source_type == "chart" and role == "metric" and (cols < 6 or rows < 5):
+            warnings.append(_warning(
+                "PORTAL_CHART_CARD_TOO_SMALL",
+                "metric portal card is too small; use at least pc.cols >= 6 and pc.rows >= 5",
+                section_index=index,
+                title=title,
+                role=role,
+                pc=deepcopy(pc),
+            ))
+        elif source_type == "chart" and role != "metric" and (cols < 8 or rows < 7):
             warnings.append(_warning(
                 "PORTAL_CHART_CARD_TOO_SMALL",
-                "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 5, preferably rows >= 6",
+                "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 7",
                 section_index=index,
                 title=title,
+                role=role or None,
                 pc=deepcopy(pc),
             ))
         if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
@@ -21059,6 +21181,9 @@ def _normalize_portal_components(components: Any) -> list[dict[str, Any]]:
                 "chart_key": chart_key,
                 "chart_name": str(config.get("chartComponentTitle") or title or "").strip() or None,
             }
+            backend_chart_type = _normalize_backend_chart_type(config.get("biChartType") or config.get("chartType"))
+            if backend_chart_type in {"indicator", PublicChartType.target.value}:
+                summary["role"] = "metric"
             section_config = _portal_section_config_for_roundtrip(config, source_type="chart")
             if section_config:
                 summary["config"] = section_config
@@ -21794,10 +21919,11 @@ _BATCH_READ_ENVELOPE_KEYS = {
 
 
 def _batch_read_app_item(*, app_key: str, result: dict[str, Any], data_key: str) -> dict[str, Any]:
+    status = str(result.get("status") or "").strip()
     item: dict[str, Any] = {
         "app_key": app_key,
         "status": result.get("status"),
-        "verified": bool(result.get("verified", result.get("status") == "success")),
+        "verified": bool(result.get("verified", status.lower() == "success")),
     }
     for key, value in result.items():
         if key in _BATCH_READ_ENVELOPE_KEYS or key in {"status", "app_key", "verified"}:

package/src/qingflow_mcp/cli/commands/builder.py

@@ -4,6 +4,7 @@ import argparse
 from typing import Any
 
 from ..context import CliContext
+from ..json_io import load_json_value
 from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 
 
@@ -15,6 +16,55 @@ def _parse_app_keys_arg(raw: Any) -> list[str] | None:
     return keys if keys else None
 
 
+def _load_schema_apps_payload(path: str | None, *, cli_package_id: int | None) -> tuple[list[Any], int | None]:
+    """Load schema --apps-file.
+
+    Public docs recommend {"package_id": 123, "apps": [...]}; older payloads used
+    a raw apps array, and some agents accidentally wrapped the object in a
+    singleton array. Keep all three shapes on the same multi-app path.
+    """
+    if not path:
+        return [], cli_package_id
+    payload = load_json_value(path, option_name="--apps-file")
+    package_id = cli_package_id
+    if isinstance(payload, dict):
+        if package_id is None:
+            raw_package_id = payload.get("package_id")
+            if isinstance(raw_package_id, int):
+                package_id = raw_package_id
+            elif raw_package_id is not None and str(raw_package_id).strip().isdigit():
+                package_id = int(str(raw_package_id).strip())
+        apps = payload.get("apps")
+    elif isinstance(payload, list):
+        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
+            wrapper = payload[0]
+            if package_id is None:
+                raw_package_id = wrapper.get("package_id")
+                if isinstance(raw_package_id, int):
+                    package_id = raw_package_id
+                elif raw_package_id is not None and str(raw_package_id).strip().isdigit():
+                    package_id = int(str(raw_package_id).strip())
+            apps = wrapper.get("apps")
+        elif any(isinstance(item, dict) and "apps" in item for item in payload):
+            raise_config_error(
+                "APPS_FILE_SHAPE_INVALID: --apps-file may be {package_id, apps}, a raw apps array, or a singleton wrapper array only.",
+                fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+            )
+        else:
+            apps = payload
+    else:
+        raise_config_error(
+            "APPS_FILE_SHAPE_INVALID: --apps-file must be {package_id, apps} or a JSON array of app items.",
+            fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+        )
+    if not isinstance(apps, list):
+        raise_config_error(
+            "APPS_FILE_SHAPE_INVALID: --apps-file apps must be a JSON array.",
+            fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+        )
+    return apps, package_id
+
+
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
     builder_subparsers = parser.add_subparsers(dest="builder_command", required=True)
@@ -166,12 +216,13 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     associated_resource_get.set_defaults(handler=_handle_associated_resource_get, format_hint="builder_summary")
 
     associated_resource_apply = associated_resource_subparsers.add_parser("apply", help="声明式管理应用关联资源池和视图展示配置")
-    associated_resource_apply.add_argument("--app-key", required=True)
+    associated_resource_apply.add_argument("--app-key", default="")
     associated_resource_apply.add_argument("--upsert-resources-file")
     associated_resource_apply.add_argument("--patch-resources-file")
     associated_resource_apply.add_argument("--remove-associated-item-ids-file")
     associated_resource_apply.add_argument("--reorder-associated-item-ids-file")
     associated_resource_apply.add_argument("--view-configs-file")
+    associated_resource_apply.add_argument("--apps-file", help="多应用批量关联资源 JSON 数组，每项含 app_key + upsert_resources/patch_resources/remove_associated_item_ids/reorder_associated_item_ids/view_configs")
     associated_resource_apply.set_defaults(handler=_handle_associated_resource_apply, format_hint="builder_summary", force_json_output=True)
 
     portal = builder_subparsers.add_parser("portal", help="门户")
@@ -214,7 +265,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--visibility-file")
     schema_apply_apply.add_argument("--create-if-missing", action="store_true")
     schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    schema_apply_apply.add_argument("--apps-file", help="多应用 schema JSON 数组；每项可带 client_key/app_name/add_fields，支持 relation target_app_ref")
+    schema_apply_apply.add_argument("--apps-file", help="多应用 schema JSON；推荐对象 {package_id, apps}，兼容 raw apps 数组；支持 relation target_app_ref")
     schema_apply_apply.add_argument("--add-fields-file", help="字段 JSON 数组；字段可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--update-fields-file", help="字段更新 JSON 数组；set 内可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--remove-fields-file")
@@ -456,6 +507,36 @@ def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_associated_resource_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [
+            a for a in [
+                "--app-key" if args.app_key else None,
+                "--upsert-resources-file" if getattr(args, "upsert_resources_file", None) else None,
+                "--patch-resources-file" if getattr(args, "patch_resources_file", None) else None,
+                "--remove-associated-item-ids-file" if getattr(args, "remove_associated_item_ids_file", None) else None,
+                "--reorder-associated-item-ids-file" if getattr(args, "reorder_associated_item_ids_file", None) else None,
+                "--view-configs-file" if getattr(args, "view_configs_file", None) else None,
+            ] if a
+        ]
+        if single_app_args:
+            raise_config_error(
+                f"associated-resource apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_associated_resources_apply(
+            profile=args.profile,
+            app_key="",
+            upsert_resources=[],
+            patch_resources=[],
+            remove_associated_item_ids=[],
+            reorder_associated_item_ids=[],
+            view_configs=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("associated-resource apply requires --app-key or --apps-file", fix_hint="Pass --app-key APP_KEY for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_associated_resources_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -524,6 +605,7 @@ def _handle_app_get(args: argparse.Namespace, context: CliContext) -> dict:
         return context.builder.app_get_associated_resources(profile=args.profile, app_key=app_key)
     if app_keys:
         batch_handlers = {
+            "summary": context.builder.app_get,
             "fields": context.builder.app_get_fields,
             "layout": context.builder.app_get_layout,
             "views": context.builder.app_get_views,
@@ -531,7 +613,7 @@ def _handle_app_get(args: argparse.Namespace, context: CliContext) -> dict:
             "charts": context.builder.app_get_charts,
         }
         if section not in batch_handlers:
-            raise_config_error(f"app get --app-keys does not support section '{section}'", fix_hint="Batch reads support: fields, layout, views, flow, charts, buttons, associated-resources")
+            raise_config_error(f"app get --app-keys does not support section '{section}'", fix_hint="Batch reads support: summary, fields, layout, views, flow, charts, buttons, associated-resources")
         return batch_handlers[section](profile=args.profile, app_keys=app_keys)
     handlers = {
         "summary": context.builder.app_get,
@@ -570,26 +652,26 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    apps = load_list_arg(args.apps_file, option_name="--apps-file")
+    apps, apps_package_id = _load_schema_apps_payload(args.apps_file, cli_package_id=args.package_id)
     if args.apps_file:
         if not apps:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
-                fix_hint="Pass a JSON array with at least one app item.",
+                fix_hint='Pass {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
             )
         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:
             raise_config_error(
                 "schema apply multi-app mode accepts --package-id/--create-if-missing plus --apps-file only.",
                 fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
             )
-        if args.package_id is None:
+        if apps_package_id is None:
             raise_config_error(
                 "schema apply multi-app mode requires --package-id.",
-                fix_hint="Pass `--package-id` and app names inside --apps-file.",
+                fix_hint="Pass root `--package-id`, or include package_id in the --apps-file object.",
             )
         return context.builder.app_schema_apply(
             profile=args.profile,
-            package_id=args.package_id,
+            package_id=apps_package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
             create_if_missing=bool(args.create_if_missing),
             publish=bool(args.publish),

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -284,6 +284,7 @@ class AiBuilderTools(ToolBase):
             remove_associated_item_ids: list[int] | None = None,
             reorder_associated_item_ids: list[int] | None = None,
             view_configs: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.app_associated_resources_apply(
                 profile=profile,
@@ -293,10 +294,13 @@ class AiBuilderTools(ToolBase):
                 remove_associated_item_ids=remove_associated_item_ids or [],
                 reorder_associated_item_ids=reorder_associated_item_ids or [],
                 view_configs=view_configs or [],
+                apps=apps,
             )
 
         @mcp.tool()
-        def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get, data_key="summary", tool_name="app_get")
             return self.app_get(profile=profile, app_key=app_key)
 
         @mcp.tool()
@@ -1120,8 +1124,24 @@ class AiBuilderTools(ToolBase):
         reorder_associated_item_ids: list[int],
         view_configs: list[JSONObject],
         patch_resources: list[JSONObject] | None = None,
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用关联资源 apply 逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
+                profile=profile,
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_associated_resources_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    upsert_resources=kw.get("upsert_resources", []),
+                    patch_resources=kw.get("patch_resources", []),
+                    remove_associated_item_ids=kw.get("remove_associated_item_ids", []),
+                    reorder_associated_item_ids=kw.get("reorder_associated_item_ids", []),
+                    view_configs=kw.get("view_configs", []),
+                ),
+                tool_name="app_associated_resources_apply",
+            )
         raw_request = {
             "app_key": app_key,
             "upsert_resources": upsert_resources,
@@ -1284,8 +1304,12 @@ class AiBuilderTools(ToolBase):
         ))
 
     @tool_cn_name("应用详情查询")
-    def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return _publicize_package_fields(
+                self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get, data_key="summary", tool_name="app_get")
+            )
         normalized_args = {"app_key": app_key}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_get(profile=profile, app_key=app_key),
@@ -4458,6 +4482,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_associated_resources_apply": {
         "allowed_keys": [
             "app_key",
+            "apps",
             "upsert_resources",
             "patch_resources",
             "remove_associated_item_ids",
@@ -4527,6 +4552,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "if an associated resource delete returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "this tool publishes after at least one write succeeds; there is no draft-only mode",
             "visible=false hides the associated-resource area without clearing previous selected ids; visible=true with limit_type=all shows the whole app-level pool",
+            "accepts apps[] for multi-app batch; each item is {app_key, upsert_resources?, patch_resources?, remove_associated_item_ids?, reorder_associated_item_ids?, view_configs?}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -4557,6 +4583,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
+        "batch_example": {
+            "profile": "default",
+            "apps": [
+                {
+                    "app_key": "APP_1",
+                    "upsert_resources": [
+                        {"client_key": "orders_view", "graph_type": "view", "target_app_key": "ORDER_APP", "view_key": "ORDER_VIEW"}
+                    ],
+                    "view_configs": [{"view_key": "MAIN_VIEW", "limit_type": "select", "associated_item_refs": ["orders_view"]}],
+                },
+                {
+                    "app_key": "APP_2",
+                    "view_configs": [{"view_key": "MAIN_VIEW", "visible": True, "limit_type": "all"}],
+                },
+            ],
+        },
     },
     "app_schema_plan": {
         "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
@@ -5287,7 +5329,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
@@ -5299,6 +5341,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
             "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
+            "accepts app_keys[] for batch summary read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single app_get summary fields",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5529,7 +5572,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "section_allowed_keys": ["title", "source_type", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
+        "section_allowed_keys": ["title", "source_type", "role", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
         "section_aliases": {
             "sourceType": "source_type",
             "chartRef": "chart_ref",
@@ -5538,6 +5581,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {
             "section.source_type": ["chart", "view", "grid", "filter", "text", "link"],
+            "section.role": ["metric"],
             "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
             "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
             "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
@@ -5552,7 +5596,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "portal_apply uses replace semantics for sections",
             "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
-            "use patch_sections[] for targeted section updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
+            "use patch_sections[] for section-level patch updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
             "when sections[] is supplied without patch_sections[], it uses replace semantics for all sections",
             "remove a section by omitting it from the sections list (replace mode) or by unset in patch_sections (patch mode)",
             "package_id is required when creating a new portal",
@@ -5560,6 +5604,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "chart_ref resolves by chart_id/chart_key first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
             "pc layout uses a 24-column grid; mobile layout uses a 6-column grid",
+            "set section.role=metric only for target/indicator chart cards; metric cards use pc.rows >= 5 and pc.cols >= 6, while ordinary BI charts use pc.rows >= 7 and pc.cols >= 8",
             "if unsure about layout, omit position or use layout_preset=auto/dashboard_2col/dashboard_3col",
             "two-column pc layout should use x=0/12 with cols=12; three-column pc layout should use x=0/8/16 with cols=8",
             "x=0/6 with cols=6 only occupies the left half of the pc portal and triggers PORTAL_LAYOUT_HALF_WIDTH",