@qingflow-tech/qingflow-app-builder-mcp 1.0.38 → 1.0.40

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.38
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.40
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.38 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.40 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-app-builder/SKILL.md

@@ -36,15 +36,15 @@ Default modeling rules:
 
 Before any builder write, classify the request:
 
-- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
 - **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
 - **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
 
-For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide.
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
 
 Builder schema inputs should follow agent-intuitive semantics:
 
-- icons may be `icon/color`, `icon_name/icon_color`, `icon_config`, or `icon: {name, color}`
+- primary icon syntax is `icon + color`, for example `icon: "table", color: "blue"`; `icon_name/icon_color`, `icon_config`, and `icon: {name, color}` are compatibility aliases only
 - `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
 - relation fields need a target plus `display_field` and `visible_fields`
 - do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
@@ -67,7 +67,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_get(package_id=...)` to read one known package
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
-  - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
   - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
@@ -127,7 +128,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
 2. Confirm whether the task is read-only or write-impacting
 3. Classify the build scope:
-   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(apps=[...])`
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(package_id=..., apps=[...])`
    - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
    - record/task/data request -> leave builder and use the matching record/task skill
 4. Resolve the smallest stable target:

package/skills/qingflow-app-builder/references/create-app.md

@@ -6,7 +6,7 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create the related apps in one `app_schema_apply(apps=[...])` call
+2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
 4. add same-call relation fields with `target_app_ref` when one new app references another new app
 5. choose explicit non-template `icon + color` for each new package/app
@@ -38,7 +38,7 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
 ## Example
@@ -54,7 +54,8 @@ Create a new package only after the user confirms package creation:
     "profile": "default",
     "package_name": "研发项目管理",
     "create_if_missing": true,
-    "icon": {"name": "briefcase", "color": "azure"}
+    "icon": "briefcase",
+    "color": "azure"
   }
 }
 ```
@@ -80,7 +81,8 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
-    "icon": {"name": "delivery-box-1", "color": "emerald"},
+    "icon": "delivery-box-1",
+    "color": "emerald",
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
@@ -110,7 +112,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
-        "icon": {"name": "business-personalcard", "color": "emerald"},
+        "icon": "business-personalcard",
+        "color": "emerald",
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
         ]
@@ -118,7 +121,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "order",
         "app_name": "订单",
-        "icon": {"name": "delivery-box-1", "color": "blue"},
+        "icon": "delivery-box-1",
+        "color": "blue",
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -21,7 +21,7 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 Use this split consistently:
 
-- Complete system/package: `package_apply` first, then one `app_schema_apply(apps=[...])`.
+- Complete system/package: `package_apply` first, then one `app_schema_apply(package_id=..., apps=[...])`.
 - Single app: `app_resolve/app_get` first, then app-scoped apply tools.
 - Record/task/data operation: leave builder and use record/task skills.
 
@@ -103,4 +103,4 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
-- Do not force agent-authored schema into backend-internal names when public aliases exist: icons may use `icon_config` / `icon:{name,color}`, options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.
+- Do not force agent-authored schema into backend-internal names when public keys exist: write icons as `icon + color` first; `icon_config` / `icon:{name,color}` are compatibility aliases only. Options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

package/src/qingflow_mcp/builder_facade/models.py

@@ -2215,6 +2215,7 @@ class ChartGetResponse(StrictModel):
     chart_id: str
     base: dict[str, Any] = Field(default_factory=dict)
     visibility: dict[str, Any] = Field(default_factory=dict)
+    filters: list[list[dict[str, Any]]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)
 
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -7184,6 +7184,7 @@ class AiBuilderFacade:
             chart_id=chart_id,
             base=deepcopy(base) if isinstance(base, dict) else {},
             visibility=_public_visibility_from_chart_visible_auth(base.get("visibleAuth")),
+            filters=_public_chart_filter_groups_from_qingbi_config(config) if isinstance(config, dict) else [],
             config=deepcopy(config) if isinstance(config, dict) else {},
         )
         return {
@@ -11612,12 +11613,12 @@ class AiBuilderFacade:
                 base_payload=base_payload,
             )
             if sections_requested:
-                component_payload = self._build_portal_components_from_sections(
+                component_payload, layout_metadata = self._build_portal_components_from_sections(
                     profile=profile,
                     sections=request.sections,
                     layout_preset=request.layout_preset,
                 )
-                layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload)
+                layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload, layout_metadata=layout_metadata)
                 update_payload["components"] = component_payload
                 self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
                 write_executed = True
@@ -12563,8 +12564,9 @@ class AiBuilderFacade:
         profile: str,
         sections: list[PortalSectionPatch],
         layout_preset: str | None = None,
-    ) -> list[dict[str, Any]]:
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
         resolved_components: list[dict[str, Any]] = []
+        layout_metadata: list[dict[str, Any]] = []
         pc_x = 0
         pc_y = 0
         pc_row_height = 0
@@ -12596,6 +12598,11 @@ class AiBuilderFacade:
                     profile=profile,
                     ref=section.chart_ref,
                 )
+                chart_type = str(
+                    resolved_chart.get("chart_type")
+                    or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
+                    or ""
+                ).strip()
                 chart_config = {
                     "biChartId": resolved_chart["chart_id"],
                     "chartComponentTitle": section.title,
@@ -12603,6 +12610,7 @@ class AiBuilderFacade:
                     **deepcopy(section.config),
                 }
                 component = {"type": 9, "position": position_payload, "chartConfig": _compact_dict(chart_config)}
+                layout_metadata.append({"source_type": section.source_type, "chart_type": chart_type})
             elif section.source_type == "view":
                 resolved_view = _resolve_view_reference(
                     facade=self,
@@ -12625,26 +12633,31 @@ class AiBuilderFacade:
                     **deepcopy(section.config),
                 }
                 component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
+                layout_metadata.append({"source_type": section.source_type})
             elif section.source_type == "grid":
                 component = {
                     "type": 2,
                     "position": position_payload,
                     "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
                 }
+                layout_metadata.append({"source_type": section.source_type})
             elif section.source_type == "filter":
                 component = {"type": 6, "position": position_payload, "filterConfig": deepcopy(section.config)}
+                layout_metadata.append({"source_type": section.source_type})
             elif section.source_type == "text":
                 component = {"type": 5, "position": position_payload, "textConfig": {"text": section.text or "", **deepcopy(section.config)}}
+                layout_metadata.append({"source_type": section.source_type})
             else:
                 component = {
                     "type": 4,
                     "position": position_payload,
                     "linkConfig": {"url": section.url or "", "beingLoginAuth": False, **deepcopy(section.config)},
                 }
+                layout_metadata.append({"source_type": section.source_type})
             if dash_style is not None:
                 component["dashStyleConfigBO"] = dash_style
             resolved_components.append(component)
-        return resolved_components
+        return resolved_components, layout_metadata
 
     def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
@@ -15212,6 +15225,103 @@ def _qingbi_chart_filter_value_to_text(*, value: Any, form_field: dict[str, Any]
     reject(value)
 
 
+def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> list[list[dict[str, Any]]]:
+    groups: list[list[dict[str, Any]]] = []
+    raw_groups = config.get("beforeAggregationFilterMatrix")
+    if not isinstance(raw_groups, list):
+        return groups
+    for raw_group in raw_groups:
+        if not isinstance(raw_group, list):
+            continue
+        group: list[dict[str, Any]] = []
+        for raw_rule in raw_group:
+            if not isinstance(raw_rule, dict):
+                continue
+            operator = _public_chart_filter_operator_from_judge_type(raw_rule.get("judgeType"))
+            field_id = raw_rule.get("fieldId") or raw_rule.get("field_id")
+            field_name = (
+                raw_rule.get("fieldName")
+                or raw_rule.get("field_name")
+                or raw_rule.get("queTitle")
+                or raw_rule.get("title")
+                or field_id
+            )
+            public_rule: dict[str, Any] = {
+                "field_name": _stringify_condition_value(field_name).strip(),
+                "operator": operator,
+            }
+            if field_id is not None:
+                public_rule["field_id"] = _stringify_condition_value(field_id).strip()
+            values = _public_chart_filter_values_from_rule(raw_rule, operator=operator)
+            if values:
+                public_rule["values"] = values
+            group.append(public_rule)
+        if group:
+            groups.append(group)
+    return groups
+
+
+def _public_chart_filter_operator_from_judge_type(judge_type: Any) -> str:
+    normalized = _stringify_condition_value(judge_type).strip()
+    mapping = {
+        "equal": "eq",
+        "equals": "eq",
+        "=": "eq",
+        "unequal": "neq",
+        "notEqual": "neq",
+        "!=": "neq",
+        "anyMatch": "in",
+        "oneOf": "in",
+        "include": "contains",
+        "contains": "contains",
+        "greaterOrEqual": "gte",
+        "gte": "gte",
+        "lessOrEqual": "lte",
+        "lte": "lte",
+        "isNull": "is_empty",
+        "empty": "is_empty",
+        "notNull": "not_empty",
+        "not_empty": "not_empty",
+    }
+    if normalized in mapping:
+        return mapping[normalized]
+    numeric = _coerce_nonnegative_int(judge_type)
+    if numeric is not None:
+        return _public_view_filter_operator_from_judge_type(numeric)
+    return f"judge_type:{judge_type}"
+
+
+def _public_chart_filter_values_from_rule(rule: dict[str, Any], *, operator: str) -> list[str]:
+    if operator in {"is_empty", "not_empty"}:
+        return []
+    raw_value = rule.get("judgeValue")
+    if raw_value is None and "judgeValues" in rule:
+        raw_value = rule.get("judgeValues")
+    values: list[str] = []
+    if isinstance(raw_value, list):
+        values = [_stringify_condition_value(value).strip() for value in raw_value]
+    elif isinstance(raw_value, str) and "<&&>" in raw_value:
+        values = [value.strip() for value in raw_value.split("<&&>")]
+    elif raw_value is not None:
+        values = [_stringify_condition_value(raw_value).strip()]
+    values = [value for value in values if value]
+    if values:
+        return values
+    for detail_key in ("judgeValueDetailList", "judgeValueDetails"):
+        details = rule.get(detail_key)
+        if not isinstance(details, list):
+            continue
+        for detail in details:
+            if not isinstance(detail, dict):
+                continue
+            for value_key in ("value", "label", "name", "title", "dataValue", "id"):
+                value = _stringify_condition_value(detail.get(value_key)).strip()
+                if value:
+                    values.append(value)
+                    break
+    return values
+
+
 def _build_public_chart_config_payload(
     *,
     patch: ChartUpsertPatch,
@@ -15421,6 +15531,17 @@ def _extract_chart_identifier(chart: Any) -> str:
     ).strip()
 
 
+def _chart_type_from_item(chart: Any) -> str:
+    if not isinstance(chart, dict):
+        return ""
+    return _public_chart_type_from_backend(
+        chart.get("chartType")
+        or chart.get("chart_type")
+        or chart.get("chartGraphType")
+        or chart.get("type")
+    )
+
+
 def _normalize_backend_chart_type(value: Any) -> str:
     raw = str(value or "").strip()
     if not raw:
@@ -15537,7 +15658,7 @@ def _portal_component_position_public(
         rows = 2
     elif source_name == "view":
         cols = 24
-        rows = 8
+        rows = 11
     elif source_name == "link":
         cols = 12
         rows = 2
@@ -15546,7 +15667,7 @@ def _portal_component_position_public(
             cols = 12
         else:
             cols = 8
-        rows = 6
+        rows = 7
     if cols == 24:
         if pc_x != 0:
             pc_y += pc_row_height
@@ -15581,7 +15702,12 @@ def _empty_portal_layout_diagnostics() -> dict[str, Any]:
     }
 
 
-def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: list[dict[str, Any]]) -> dict[str, Any]:
+def _portal_layout_diagnostics(
+    sections: list[PortalSectionPatch],
+    components: list[dict[str, Any]],
+    *,
+    layout_metadata: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     diagnostics = _empty_portal_layout_diagnostics()
     diagnostics["section_count"] = len(sections)
     explicit_count = sum(1 for section in sections if section.position is not None)
@@ -15596,16 +15722,26 @@ def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: l
         if pc:
             pc_positions.append(pc)
         section = sections[index] if index < len(sections) else None
+        metadata = layout_metadata[index] if isinstance(layout_metadata, list) and index < len(layout_metadata) and isinstance(layout_metadata[index], dict) else {}
         source_type = str(getattr(section, "source_type", "") 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):
+        chart_type = str(metadata.get("chart_type") or "").strip().lower()
+        is_metric_chart = chart_type in {"target", "indicator"}
+        min_chart_cols = 6 if is_metric_chart else 8
+        min_chart_rows = 5 if is_metric_chart else 7
+        if source_type == "chart" and (cols < min_chart_cols or rows < min_chart_rows):
             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",
+                (
+                    "metric chart portal card is too small; use at least pc.cols >= 6 and pc.rows >= 5"
+                    if is_metric_chart
+                    else "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 7 for non-metric charts"
+                ),
                 section_index=index,
                 title=title,
+                chart_type=chart_type 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)):
@@ -15648,7 +15784,7 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
             item_id = _extract_chart_identifier(item)
             item_name = str(item.get("chartName") or "").strip()
             if item_id == chart_id:
-                return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key}
+                return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key, "chart_type": _chart_type_from_item(item)}
         raise ValueError(f"chart ref chart_id '{chart_id}' could not be resolved under app '{app_key}'")
     matches = _find_charts_by_name(items, chart_name=chart_name)
     if len(matches) > 1:
@@ -15659,6 +15795,7 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
             "chart_id": _extract_chart_identifier(item),
             "chart_name": str(item.get("chartName") or "").strip(),
             "app_key": app_key,
+            "chart_type": _chart_type_from_item(item),
         }
     raise ValueError(f"chart ref could not be resolved under app '{app_key}'")
 
@@ -24719,7 +24856,7 @@ def _public_view_filter_groups_from_match_rules(
 
 
 def _public_view_filter_operator_from_judge_type(judge_type: Any) -> str:
-    normalized = _coerce_positive_int(judge_type)
+    normalized = _coerce_nonnegative_int(judge_type)
     if normalized == JUDGE_EQUAL:
         return "eq"
     if normalized == JUDGE_UNEQUAL:

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

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import argparse
+from copy import deepcopy
 
 from ..context import CliContext
-from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 from ..json_io import load_json_value
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -479,6 +480,7 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     apps_payload = _load_apps_file_arg(args.apps_file)
     apps = apps_payload["apps"]
+    apps_warnings = apps_payload.get("warnings") or []
     package_id = args.package_id
     if package_id is None and apps_payload.get("package_id") is not None:
         package_id = int(apps_payload["package_id"])
@@ -487,6 +489,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
                 fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
+                error_code="APPS_FILE_EMPTY",
             )
         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(
@@ -498,7 +501,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 "schema apply multi-app mode requires --package-id.",
                 fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
             )
-        return context.builder.app_schema_apply(
+        result = context.builder.app_schema_apply(
             profile=args.profile,
             package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -509,6 +512,11 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             update_fields=[],
             remove_fields=[],
         )
+        if apps_warnings and isinstance(result, dict):
+            result_warnings = list(result.get("warnings") or [])
+            result_warnings.extend(deepcopy(apps_warnings))
+            result["warnings"] = result_warnings
+        return result
     has_app_key = bool((args.app_key or "").strip())
     has_app_name = bool((args.app_name or "").strip())
     has_app_title = bool((args.app_title or "").strip())
@@ -545,8 +553,56 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
 def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     if not path:
         return {"apps": []}
+    expected_shape = {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [],
+            }
+        ],
+    }
+    expected_shape_details = {
+        "expected_shape": expected_shape,
+        "expected_shape_json": (
+            '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+            '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
+        ),
+    }
     payload = load_json_value(path, option_name="--apps-file")
     if isinstance(payload, list):
+        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
+            wrapper = payload[0]
+            apps = wrapper.get("apps")
+            if not isinstance(apps, list):
+                raise_config_error(
+                    "--apps-file wrapper object requires an apps array.",
+                    fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw apps array like [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}].",
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    details=expected_shape_details,
+                )
+            result: dict[str, object] = {
+                "apps": apps,
+                "warnings": [
+                    {
+                        "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                        "message": "--apps-file was a singleton wrapper array; normalized it to {package_id, apps}.",
+                    }
+                ],
+            }
+            if wrapper.get("package_id") is not None:
+                result["package_id"] = wrapper.get("package_id")
+            return result
+        if any(isinstance(item, dict) and "apps" in item for item in payload):
+            raise_config_error(
+                "--apps-file root array items must be app items, not package wrapper objects.",
+                fix_hint="Use one object {\"package_id\":1001,\"apps\":[...]} or a raw app array [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}]. Do not wrap multiple {package_id, apps} objects in an array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
+            )
         return {"apps": payload}
     if isinstance(payload, dict):
         apps = payload.get("apps")
@@ -554,6 +610,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             raise_config_error(
                 "--apps-file JSON object requires an apps array.",
                 fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
             )
         result: dict[str, object] = {"apps": apps}
         if payload.get("package_id") is not None:
@@ -562,6 +620,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     raise_config_error(
         "--apps-file must be a JSON array or an object containing apps.",
         fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
+        error_code="APPS_FILE_SHAPE_INVALID",
+        details=expected_shape_details,
     )
 
 

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

@@ -48,14 +48,23 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
     raise QingflowApiError.config_error(f"{label} is required")
 
 
-def raise_config_error(message: str, *, fix_hint: str) -> None:
+def raise_config_error(
+    message: str,
+    *,
+    fix_hint: str | None = None,
+    error_code: str = "CONFIG_ERROR",
+    details: dict[str, Any] | None = None,
+) -> None:
+    error_details: dict[str, Any] = {"fix_hint": fix_hint or message}
+    if details:
+        error_details.update(details)
     raise RuntimeError(
         json.dumps(
             {
                 "category": "config",
                 "message": message,
-                "error_code": "CONFIG_ERROR",
-                "details": {"fix_hint": fix_hint},
+                "error_code": error_code,
+                "details": error_details,
             },
             ensure_ascii=False,
         )

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -383,7 +383,7 @@ class AiBuilderTools(ToolBase):
             remove_fields: list[JSONObject] | None = None,
             apps: list[JSONObject] | None = None,
         ) -> JSONObject:
-            if apps:
+            if apps is not None:
                 if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
@@ -1718,8 +1718,18 @@ class AiBuilderTools(ToolBase):
             icon_color=icon_color,
             icon_config=icon_config,
         )
-        if apps:
-            apps = [_normalize_schema_app_item(item) if isinstance(item, dict) else item for item in apps]
+        if apps is not None:
+            normalized_apps_payload = _normalize_schema_apps_argument(
+                tool_name="app_schema_apply",
+                package_id=package_id,
+                apps=apps,
+            )
+            failure = normalized_apps_payload.get("failure")
+            if isinstance(failure, dict):
+                return _attach_builder_apply_envelope("app_schema_apply", failure)
+            package_id = normalized_apps_payload.get("package_id")  # type: ignore[assignment]
+            apps = normalized_apps_payload.get("apps")  # type: ignore[assignment]
+            input_warnings = list(normalized_apps_payload.get("warnings") or [])
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -1728,6 +1738,10 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 apps=apps,
             )
+            if input_warnings:
+                result_warnings = list(result.get("warnings") or [])
+                result_warnings.extend(deepcopy(input_warnings))
+                result["warnings"] = result_warnings
             return _attach_builder_apply_envelope("app_schema_apply", result)
         result = self._app_schema_apply_once(
             profile=profile,
@@ -1803,9 +1817,13 @@ class AiBuilderTools(ToolBase):
         if not apps:
             return _config_failure(
                 tool_name="app_schema_apply",
+                error_code="APPS_FILE_EMPTY",
                 message="app_schema_apply multi-app mode requires non-empty apps.",
                 fix_hint="Pass apps as a non-empty list of app schema items.",
             )
+        shape_failure = _schema_apps_shape_failure(tool_name="app_schema_apply", apps=apps)
+        if shape_failure is not None:
+            return shape_failure
         icon_errors: list[JSONObject] = []
         seen_new_app_icons: dict[str, int] = {}
         for index, raw_item in enumerate(apps):
@@ -2932,6 +2950,109 @@ def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
     return normalized
 
 
+def _schema_apps_expected_shape() -> JSONObject:
+    return {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [{"name": "员工名称", "type": "text", "as_data_title": True}],
+            }
+        ],
+    }
+
+
+def _schema_apps_expected_shape_json() -> str:
+    return (
+        '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+        '"icon":"business-personalcard","color":"emerald","add_fields":[{"name":"员工名称","type":"text","as_data_title":true}]}]}'
+    )
+
+
+def _is_schema_apps_wrapper_item(item: object) -> bool:
+    return isinstance(item, dict) and "apps" in item
+
+
+def _schema_apps_shape_failure(*, tool_name: str, apps: list[JSONObject]) -> JSONObject | None:
+    for index, item in enumerate(apps):
+        if _is_schema_apps_wrapper_item(item):
+            return _config_failure(
+                tool_name=tool_name,
+                error_code="APPS_FILE_SHAPE_INVALID",
+                message="apps[] items must be app schema items, not package wrapper objects.",
+                fix_hint=(
+                    "For MCP pass package_id separately and apps=[{app_name, icon, color, add_fields}]. "
+                    'For CLI use --apps-file with {"package_id":1001,"apps":[...]}. '
+                    "Do not pass multiple {package_id, apps} wrapper objects inside apps[]."
+                ),
+                details={
+                    "index": index,
+                    "row_number": index + 1,
+                    "expected_shape": _schema_apps_expected_shape(),
+                    "expected_shape_json": _schema_apps_expected_shape_json(),
+                },
+            )
+    return None
+
+
+def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, apps: list[JSONObject]) -> JSONObject:
+    normalized_package_id = package_id
+    normalized_apps: list[JSONObject] = apps
+    warnings: list[JSONObject] = []
+
+    if len(apps) == 1 and _is_schema_apps_wrapper_item(apps[0]):
+        wrapper = apps[0]
+        wrapper_apps = wrapper.get("apps")
+        if not isinstance(wrapper_apps, list):
+            return {
+                "failure": _config_failure(
+                    tool_name=tool_name,
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    message="apps singleton wrapper requires an apps array.",
+                    fix_hint='Use {"package_id":1001,"apps":[...]} in CLI, or pass MCP package_id=1001 and apps=[...].',
+                    details={
+                        "expected_shape": _schema_apps_expected_shape(),
+                        "expected_shape_json": _schema_apps_expected_shape_json(),
+                    },
+                )
+            }
+        if normalized_package_id is None and wrapper.get("package_id") is not None:
+            try:
+                normalized_package_id = int(wrapper.get("package_id"))
+            except (TypeError, ValueError):
+                return {
+                    "failure": _config_failure(
+                        tool_name=tool_name,
+                        error_code="APPS_FILE_SHAPE_INVALID",
+                        message="apps singleton wrapper package_id must be an integer.",
+                        fix_hint="Pass package_id as a number at the top level.",
+                        details={
+                            "expected_shape": _schema_apps_expected_shape(),
+                            "expected_shape_json": _schema_apps_expected_shape_json(),
+                        },
+                    )
+                }
+        normalized_apps = wrapper_apps
+        warnings.append(
+            {
+                "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                "message": "apps was a singleton wrapper array; normalized it to package_id + apps.",
+            }
+        )
+    else:
+        failure = _schema_apps_shape_failure(tool_name=tool_name, apps=apps)
+        if failure is not None:
+            return {"failure": failure}
+
+    normalized_items: list[JSONObject] = []
+    for item in normalized_apps:
+        normalized_items.append(_normalize_schema_app_item(item) if isinstance(item, dict) else item)
+    return {"package_id": normalized_package_id, "apps": normalized_items, "warnings": warnings}
+
+
 def _compile_multi_app_schema_item_refs(
     item: JSONObject,
     client_key_to_app_key: dict[str, str],
@@ -4438,7 +4559,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
             "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
-            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
+            "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
             "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
@@ -5024,12 +5145,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode: package_id + app_name + create_if_missing=true",
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
             "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
-            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
+            "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
             "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
             "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",