@josephyan/qingflow-cli 1.1.3 → 1.1.4

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.1.3
+npm install @josephyan/qingflow-cli@1.1.4
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.1.3 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.3",
+  "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.3"
+version = "1.1.4"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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,
@@ -13833,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],
     *,
@@ -13845,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),
@@ -13866,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,
             }
         )
@@ -14285,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)):
@@ -21083,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
@@ -21818,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)
@@ -215,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")
@@ -555,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,
@@ -562,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,
@@ -601,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

@@ -298,7 +298,9 @@ class AiBuilderTools(ToolBase):
             )
 
         @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()
@@ -1302,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),
@@ -5323,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": [
@@ -5335,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",
@@ -5565,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",
@@ -5574,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),
@@ -5596,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",