@josephyan/qingflow-app-builder-mcp 1.1.17 → 1.1.19

package/src/qingflow_mcp/builder_facade/models.py

@@ -2260,6 +2260,22 @@ class ChartApplyRequest(StrictModel):
         return self
 
 
+class PortalInlineChartPatch(ChartUpsertPatch):
+    app_key: str = Field(validation_alias=AliasChoices("app_key", "appKey"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_inline_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "chart_name" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chart_name")
+        if "chartName" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chartName")
+        return payload
+
+
 class PortalComponentPositionPatch(StrictModel):
     pc_x: int = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
     pc_y: int = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
@@ -2344,6 +2360,7 @@ class PortalSectionPatch(StrictModel):
     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)
     chart_ref: PortalChartRefPatch | None = None
+    chart: PortalInlineChartPatch | None = Field(default=None, validation_alias=AliasChoices("chart", "inline_chart", "inlineChart", "create_chart", "createChart"))
     view_ref: PortalViewRefPatch | None = None
     text: str | None = None
     url: str | None = None
@@ -2362,6 +2379,14 @@ class PortalSectionPatch(StrictModel):
             payload["role"] = raw_role.strip().lower()
         if "chartRef" in payload and "chart_ref" not in payload:
             payload["chart_ref"] = payload.pop("chartRef")
+        if "inlineChart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("inlineChart")
+        if "inline_chart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("inline_chart")
+        if "createChart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("createChart")
+        if "create_chart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("create_chart")
         if "viewRef" in payload and "view_ref" not in payload:
             payload["view_ref"] = payload.pop("viewRef")
         if "dashStyleConfigBO" in payload and "dash_style_config" not in payload:
@@ -2373,8 +2398,8 @@ 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.source_type == "chart" and self.chart_ref is None:
-            raise ValueError("chart section requires chart_ref")
+        if self.source_type == "chart" and self.chart_ref is None and self.chart is None:
+            raise ValueError("chart section requires chart_ref or chart")
         if self.source_type == "view" and self.view_ref is None:
             raise ValueError("view section requires view_ref")
         if self.source_type == "text" and self.text is None:
@@ -2662,6 +2687,14 @@ def _normalize_field_payload(value: Any) -> Any:
     if not isinstance(value, dict):
         return value
     payload = dict(value)
+    if "data_title" in payload and "as_data_title" not in payload and "asDataTitle" not in payload:
+        payload["as_data_title"] = payload.pop("data_title")
+    if "dataTitle" in payload and "as_data_title" not in payload and "asDataTitle" not in payload:
+        payload["as_data_title"] = payload.pop("dataTitle")
+    if "data_cover" in payload and "as_data_cover" not in payload and "asDataCover" not in payload:
+        payload["as_data_cover"] = payload.pop("data_cover")
+    if "dataCover" in payload and "as_data_cover" not in payload and "asDataCover" not in payload:
+        payload["as_data_cover"] = payload.pop("dataCover")
     if "fields" in payload and "subfields" not in payload:
         payload["subfields"] = payload.pop("fields")
     if "options" in payload:

package/src/qingflow_mcp/builder_facade/service.py

@@ -3155,7 +3155,7 @@ class AiBuilderFacade:
         return expanded, issues, results
 
     def app_custom_buttons_apply(self, *, profile: str, request: CustomButtonsApplyRequest) -> JSONObject:
-        normalized_args = request.model_dump(mode="json")
+        normalized_args = request.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
         app_key = request.app_key
         permission_outcomes: list[PermissionCheckOutcome] = []
         button_write_intent = bool(request.upsert_buttons or request.patch_buttons or request.remove_buttons)
@@ -3239,7 +3239,10 @@ class AiBuilderFacade:
                     )
                 )
             upsert_buttons.extend(expanded_buttons)
-            normalized_args["upsert_buttons"] = [patch.model_dump(mode="json") for patch in upsert_buttons]
+            normalized_args["upsert_buttons"] = [
+                patch.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
+                for patch in upsert_buttons
+            ]
             normalized_args["patch_results"] = patch_results
 
         compiled_add_data_configs, add_data_issues = self._compile_custom_button_semantic_add_data_configs(
@@ -10261,8 +10264,14 @@ class AiBuilderFacade:
             return CustomButtonsApplyRequest.model_validate(
                 {
                     "app_key": app_key,
-                    "upsert_buttons": [item.model_dump(mode="json") for item in upsert_buttons],
-                    "view_configs": [item.model_dump(mode="json") for item in view_configs],
+                    "upsert_buttons": [
+                        item.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
+                        for item in upsert_buttons
+                    ],
+                    "view_configs": [
+                        item.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
+                        for item in view_configs
+                    ],
                 }
             ), []
         except Exception as error:
@@ -13018,6 +13027,7 @@ class AiBuilderFacade:
         draft_readback_error: JSONObject | None = None
         live_readback_error: JSONObject | None = None
         update_payload: dict[str, Any] = {}
+        inline_chart_results: list[dict[str, Any]] = []
         try:
             layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
@@ -13065,10 +13075,11 @@ class AiBuilderFacade:
                 base_payload=base_payload,
             )
             if sections_requested:
-                component_payload, layout_metadata = self._build_portal_components_from_sections(
+                component_payload, layout_metadata, inline_chart_results = self._build_portal_components_from_sections(
                     profile=profile,
                     sections=request.sections,
                     layout_preset=request.layout_preset,
+                    inline_chart_results=inline_chart_results,
                 )
                 layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload, layout_metadata=layout_metadata)
                 update_payload["components"] = component_payload
@@ -13096,11 +13107,12 @@ class AiBuilderFacade:
                 draft_result = {}
         except (QingflowApiError, RuntimeError, ValueError) as error:
             api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
-            if write_executed:
+            inline_chart_write_executed = any(bool(item.get("write_executed")) for item in inline_chart_results)
+            if write_executed or inline_chart_write_executed:
                 transport_error = _transport_error_payload(api_error) if api_error is not None else None
                 warning = _warning(
                     "PORTAL_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
-                    "one or more portal write steps executed before a later write step failed",
+                    "one or more portal or inline-chart write steps executed before a later write step failed",
                 )
                 if transport_error is not None:
                     for key in ("backend_code", "http_status", "request_id"):
@@ -13121,6 +13133,7 @@ class AiBuilderFacade:
                             if api_error is not None
                             else {"message": str(error)}
                         ),
+                        **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
                     },
                     "request_id": api_error.request_id if api_error else None,
                     "backend_code": api_error.backend_code if api_error else None,
@@ -13136,6 +13149,7 @@ class AiBuilderFacade:
                         "published": False,
                         "publish_failed": False,
                         "write_incomplete": True,
+                        "inline_charts_verified": False if inline_chart_results else None,
                         "readback_unavailable": False,
                         "metadata_unverified": True,
                     },
@@ -13147,6 +13161,7 @@ class AiBuilderFacade:
                     "verified": False,
                     "write_executed": True,
                     "safe_to_retry": False,
+                    "inline_chart_results": deepcopy(inline_chart_results),
                 })
             return _failed(
                 "PORTAL_APPLY_FAILED",
@@ -13258,6 +13273,7 @@ class AiBuilderFacade:
                 "draft": draft_meta_mismatches,
                 "live": live_meta_mismatches,
             },
+            **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
             **({"publish_error": publish_error} if publish_error is not None else {}),
             **({"draft_readback_error": draft_readback_error} if draft_readback_error is not None else {}),
             **({"live_readback_error": live_readback_error} if live_readback_error is not None else {}),
@@ -13295,6 +13311,7 @@ class AiBuilderFacade:
             "noop": False,
             "warnings": warnings,
             "layout_diagnostics": layout_diagnostics,
+            "inline_chart_results": deepcopy(inline_chart_results),
             "verification": {
                 "draft_verified": draft_verified,
                 "draft_metadata_verified": draft_meta_verified,
@@ -13302,6 +13319,7 @@ class AiBuilderFacade:
                 "live_metadata_verified": live_meta_verified,
                 "published": published,
                 "publish_failed": publish_failed,
+                "inline_charts_verified": all(str(item.get("status") or "") in {"created", "updated"} and str(item.get("chart_id") or "").strip() for item in inline_chart_results),
                 "readback_unavailable": draft_readback_error is not None or live_readback_error is not None,
                 "metadata_unverified": draft_readback_error is not None or live_readback_error is not None,
             },
@@ -14055,9 +14073,11 @@ class AiBuilderFacade:
         profile: str,
         sections: list[PortalSectionPatch],
         layout_preset: str | None = None,
-    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        inline_chart_results: list[dict[str, Any]] | None = None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
         resolved_components: list[dict[str, Any]] = []
         layout_metadata: list[dict[str, Any]] = []
+        inline_chart_results = inline_chart_results if inline_chart_results is not None else []
         pc_x = 0
         pc_y = 0
         pc_row_height = 0
@@ -14084,11 +14104,53 @@ class AiBuilderFacade:
             dash_style = deepcopy(section.dash_style_config) if isinstance(section.dash_style_config, dict) else None
             component: dict[str, Any]
             if section.source_type == "chart":
-                resolved_chart = _resolve_chart_reference(
-                    charts=self.charts,
-                    profile=profile,
-                    ref=section.chart_ref,
-                )
+                if section.chart is not None:
+                    inline_chart_payload = section.chart.model_dump(mode="json", exclude={"app_key"})
+                    chart_request = ChartApplyRequest(
+                        app_key=section.chart.app_key,
+                        upsert_charts=[ChartUpsertPatch.model_validate(inline_chart_payload)],
+                        patch_charts=[],
+                        remove_chart_ids=[],
+                        reorder_chart_ids=[],
+                    )
+                    chart_apply = self.chart_apply(profile=profile, request=chart_request)
+                    chart_items = chart_apply.get("chart_results") if isinstance(chart_apply.get("chart_results"), list) else []
+                    successful_chart = next(
+                        (
+                            item
+                            for item in chart_items
+                            if isinstance(item, dict)
+                            and str(item.get("status") or "") in {"created", "updated"}
+                            and str(item.get("chart_id") or "").strip()
+                        ),
+                        None,
+                    )
+                    inline_chart_results.append({
+                        "title": section.title,
+                        "app_key": section.chart.app_key,
+                        "chart_name": section.chart.name,
+                        "chart_type": section.chart.chart_type.value,
+                        "status": str(successful_chart.get("status") or "") if isinstance(successful_chart, dict) else "failed",
+                        "chart_id": str(successful_chart.get("chart_id") or "") if isinstance(successful_chart, dict) else "",
+                        "chart_apply_status": chart_apply.get("status"),
+                        "write_executed": bool(chart_apply.get("write_executed")),
+                        **({"error_code": chart_apply.get("error_code")} if chart_apply.get("error_code") else {}),
+                        **({"message": chart_apply.get("message")} if chart_apply.get("message") else {}),
+                    })
+                    if not isinstance(successful_chart, dict):
+                        raise ValueError(f"inline chart '{section.chart.name}' could not be created or updated for portal section '{section.title}'")
+                    resolved_chart = {
+                        "chart_id": str(successful_chart.get("chart_id") or "").strip(),
+                        "chart_name": str(successful_chart.get("name") or section.chart.name).strip(),
+                        "app_key": section.chart.app_key,
+                        "chart_type": section.chart.chart_type.value,
+                    }
+                else:
+                    resolved_chart = _resolve_chart_reference(
+                        charts=self.charts,
+                        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"))
@@ -14148,7 +14210,7 @@ class AiBuilderFacade:
             if dash_style is not None:
                 component["dashStyleConfigBO"] = dash_style
             resolved_components.append(component)
-        return resolved_components, layout_metadata
+        return resolved_components, layout_metadata, inline_chart_results
 
     def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
@@ -17794,12 +17856,12 @@ def _portal_layout_diagnostics(
         if source_type == "chart" and role in {"metric", "metrics", "indicator", "kpi"} and not is_metric_chart:
             warnings.append(_warning(
                 "PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH",
-                "metric portal section must reference a target/indicator chart; create the missing metric chart before assembling the portal",
+                "metric portal section must reference a target/indicator chart; use inline_chart to create the missing metric chart while assembling the portal",
                 section_index=index,
                 title=title,
                 role=role,
                 chart_type=chart_type or None,
-                fix_hint="Use app_charts_apply with chart_type=target and metric='count(*)' or another metric expression, then reference that chart.",
+                fix_hint="Use section.inline_chart with chart_type=target or indicator and a metric expression, or change role away from metric.",
             ))
         if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
             warnings.append(_warning(
@@ -17859,7 +17921,7 @@ def _append_portal_standard_count_warnings(
             "standard portal metric area should contain 4-6 metric cards",
             actual_count=metric_count,
             expected_count="4-6",
-            fix_hint="Create missing target/indicator charts first, or keep 4 metric cards in one row with pc.cols=6, pc.rows=5.",
+            fix_hint="Use inline_chart for missing target/indicator metric cards, or keep 4 metric cards in one row with pc.cols=6, pc.rows=5.",
         ))
     if (bi_count or require_complete_standard) and not 2 <= bi_count <= 3:
         warnings.append(_warning(

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

@@ -214,7 +214,8 @@ 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=None)
-    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 对象；每项可带 client_key/app_name/form，支持 relation target_app_ref")
+    schema_apply_apply.add_argument("--form-file", help="单应用表单结构 JSON 数组；form[].rows[][] 同时声明字段和表单分组布局")
     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")
@@ -578,10 +579,10 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 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:
+        if args.app_key or args.app_name or args.app_title or args.form_file 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 plus --apps-file only; --create-if-missing is optional.",
-                fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
+                fix_hint="Use apps[].form inside --apps-file for batch mode, or remove --apps-file and use --form-file for a single app.",
             )
         if package_id is None:
             raise_config_error(
@@ -595,6 +596,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             create_if_missing=effective_create_if_missing,
             publish=effective_publish,
             apps=apps,
+            form=None,
             add_fields=[],
             update_fields=[],
             remove_fields=[],
@@ -631,6 +633,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
         create_if_missing=bool(args.create_if_missing),
         publish=True if args.publish is None else bool(args.publish),
+        form=load_list_arg(args.form_file, option_name="--form-file") if args.form_file else [],
         add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),
         update_fields=load_list_arg(args.update_fields_file, option_name="--update-fields-file"),
         remove_fields=load_list_arg(args.remove_fields_file, option_name="--remove-fields-file"),

package/src/qingflow_mcp/server_app_builder.py

@@ -428,16 +428,17 @@ def build_builder_server() -> FastMCP:
         visibility: dict | None = None,
         create_if_missing: bool | None = None,
         publish: bool = True,
+        form: list[dict] | None = None,
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
         apps: list[dict] | None = None,
     ) -> dict:
         if apps:
-            if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+            if app_key or app_name or app_title or form or add_fields or update_fields or remove_fields:
                 return _config_failure(
                     "app_schema_apply multi-app mode accepts package_id plus apps only; create_if_missing is optional.",
-                    fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                    fix_hint="Use apps[].form for batch mode, or use the single-app arguments without apps.",
                 )
             if package_id is None:
                 return _config_failure(
@@ -450,6 +451,7 @@ def build_builder_server() -> FastMCP:
                 visibility=visibility,
                 create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                 publish=publish,
+                form=None,
                 add_fields=[],
                 update_fields=[],
                 remove_fields=[],
@@ -482,10 +484,11 @@ def build_builder_server() -> FastMCP:
             visibility=visibility,
             create_if_missing=effective_create_if_missing,
             publish=publish,
+            form=form or [],
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
-            apps=[],
+            apps=None,
         )
 
     @server.tool()