@qingflow-tech/qingflow-app-builder-mcp 1.0.10 → 1.0.11

package/src/qingflow_mcp/builder_facade/service.py

@@ -20,7 +20,7 @@ from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_T
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults
+from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults, workspace_icon_config
 from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import _build_viewgraph_questions, _compact_dict, extract_field_map
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
@@ -878,14 +878,21 @@ class AiBuilderFacade:
             "verification": {},
         }
 
-    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+    def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         listed = self.packages.package_list(profile=profile, trial_status=trial_status, include_raw=False)
+        raw_items = listed.get("items") if isinstance(listed.get("items"), list) else []
+        items = [_publicize_package_list_item(item) for item in raw_items if isinstance(item, dict)]
+        normalized_query = str(query or "").strip()
+        if normalized_query:
+            filtered_items = [item for item in items if _package_list_item_matches_query(item, normalized_query)]
+        else:
+            filtered_items = items
         return {
             "status": "success",
             "error_code": None,
             "recoverable": False,
             "message": "listed packages",
-            "normalized_args": {"trial_status": trial_status},
+            "normalized_args": {"trial_status": trial_status, "query": normalized_query},
             "missing_fields": [],
             "allowed_values": {},
             "details": {},
@@ -894,8 +901,12 @@ class AiBuilderFacade:
             "noop": False,
             "verification": {},
             "trial_status": trial_status,
-            "items": listed.get("items") if isinstance(listed.get("items"), list) else [],
-            "count": listed.get("count") or 0,
+            "query": normalized_query,
+            "items": filtered_items,
+            "count": len(filtered_items),
+            "matched_count": len(filtered_items),
+            "unfiltered_count": len(items),
+            "filter_mode": "local_packages",
             "source_shape": listed.get("source_shape"),
             "retried": bool(listed.get("retried", False)),
         }
@@ -2868,13 +2879,29 @@ class AiBuilderFacade:
             try:
                 write_executed = True
                 self.buttons.custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+                delete_readback = self._verify_custom_button_deleted_by_id(profile=profile, app_key=app_key, button_id=button_id)
                 removed.append(
                     {
                         "index": op["index"],
                         "operation": "remove",
-                        "status": "success",
+                        "status": delete_readback.get("status") or "readback_pending",
                         "button_id": button_id,
                         "button_text": selector.button_text or (existing_by_id.get(button_id) or {}).get("button_text"),
+                        "delete_executed": True,
+                        "readback_status": delete_readback.get("readback_status"),
+                        "safe_to_retry_delete": False,
+                        **(
+                            {
+                                "error_code": delete_readback.get("error_code"),
+                                "message": delete_readback.get("message"),
+                                "request_id": delete_readback.get("request_id"),
+                                "backend_code": delete_readback.get("backend_code"),
+                                "http_status": delete_readback.get("http_status"),
+                                "transport_error": delete_readback.get("transport_error"),
+                            }
+                            if delete_readback.get("readback_status") != "deleted"
+                            else {}
+                        ),
                     }
                 )
             except (QingflowApiError, RuntimeError) as error:
@@ -2892,12 +2919,14 @@ class AiBuilderFacade:
                     }
                 )
 
+        needs_button_list_readback = bool(created or updated or request.view_configs)
         readback_buttons: list[dict[str, Any]] = []
         readback_failed = False
-        try:
-            readback_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            readback_failed = True
+        if needs_button_list_readback:
+            try:
+                readback_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError):
+                readback_failed = True
         readback_ids = {
             button_id
             for item in readback_buttons
@@ -2918,10 +2947,12 @@ class AiBuilderFacade:
             for item in removed
             if _coerce_positive_int(item.get("button_id")) is not None
         ]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed)
+        remove_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed)
         verified = (
             not readback_failed
             and all(button_id in readback_ids for button_id in created_ids + updated_ids)
-            and all(button_id not in readback_ids for button_id in removed_ids)
+            and removed_verified
             and not failed
             and all(_coerce_positive_int(item.get("button_id")) is not None for item in created)
         )
@@ -2980,6 +3011,13 @@ class AiBuilderFacade:
                     else "custom button writes all failed or produced no confirmed result; application was not published",
                 )
             )
+        if remove_readback_pending:
+            warnings.append(
+                _warning(
+                    "CUSTOM_BUTTON_DELETE_READBACK_PENDING",
+                    "custom button delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -3009,7 +3047,9 @@ class AiBuilderFacade:
                 "readback_loaded": not readback_failed,
                 "created_verified": not readback_failed and all(button_id in readback_ids for button_id in created_ids),
                 "updated_verified": not readback_failed and all(button_id in readback_ids for button_id in updated_ids),
-                "removed_verified": not readback_failed and all(button_id not in readback_ids for button_id in removed_ids),
+                "removed_verified": removed_verified,
+                "remove_readback_pending": remove_readback_pending,
+                "removed_readback_results": deepcopy(removed),
                 "view_button_bindings_verified": view_config_verified,
             },
             "verified": verified,
@@ -3374,30 +3414,35 @@ class AiBuilderFacade:
             return finalize(edit_context_error)
 
         self.buttons.custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+        delete_readback = self._verify_custom_button_deleted_by_id(profile=profile, app_key=app_key, button_id=button_id)
+        verified = delete_readback.get("readback_status") == "deleted"
         return finalize(
             self._append_publish_result(
                 profile=profile,
                 app_key=app_key,
                 publish=True,
                 response={
-                    "status": "success",
-                    "error_code": None,
-                    "recoverable": False,
-                    "message": "deleted custom button",
+                    "status": "success" if verified else "partial_success",
+                    "error_code": None if verified else delete_readback.get("error_code") or "CUSTOM_BUTTON_DELETE_READBACK_PENDING",
+                    "recoverable": not verified,
+                    "message": "deleted custom button" if verified else "custom button delete completed; readback pending",
                     "normalized_args": normalized_args,
                     "missing_fields": [],
                     "allowed_values": {},
                     "details": {},
-                    "request_id": None,
-                    "suggested_next_call": None,
+                    "request_id": delete_readback.get("request_id"),
+                    "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
                     "noop": False,
-                    "warnings": [],
-                    "verification": {"custom_button_deleted": True},
-                    "verified": True,
+                    "warnings": [] if verified else [_warning("CUSTOM_BUTTON_DELETE_READBACK_PENDING", "custom button delete was sent, but deletion readback is not fully verified")],
+                    "verification": {"custom_button_deleted": verified, "delete_readback": delete_readback},
+                    "verified": verified,
                     "app_key": app_key,
                     "button_id": button_id,
                     "edit_version_no": edit_version_no,
-                    "deleted": True,
+                    "deleted": verified,
+                    "delete_executed": True,
+                    "readback_status": delete_readback.get("readback_status"),
+                    "safe_to_retry_delete": False,
                 },
             )
         )
@@ -3989,7 +4034,16 @@ class AiBuilderFacade:
             try:
                 write_executed = True
                 self._associated_resource_delete(profile=profile, app_key=app_key, associated_item_id=item_id)
-                removed.append({"associated_item_id": item_id, "status": "success"})
+                removed.append(
+                    {
+                        "associated_item_id": item_id,
+                        "operation": "remove",
+                        "status": "readback_pending",
+                        "delete_executed": True,
+                        "readback_status": "unavailable",
+                        "safe_to_retry_delete": False,
+                    }
+                )
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "remove", "associated_item_id": item_id, "status": "failed", "error_code": "ASSOCIATED_RESOURCE_WRITE_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
@@ -4003,10 +4057,16 @@ class AiBuilderFacade:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "reorder", "associated_item_ids": reorder_ids, "status": "failed", "error_code": "ASSOCIATED_RESOURCE_REORDER_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
 
-        try:
-            resources_after = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            resources_after = []
+        resources_after: list[dict[str, Any]] = []
+        resources_after_loaded = False
+        resources_after_readback_failed = False
+        if request.view_configs:
+            try:
+                resources_after = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+                resources_after_loaded = True
+            except (QingflowApiError, RuntimeError):
+                resources_after = []
+                resources_after_readback_failed = True
 
         for index, view_config in enumerate(request.view_configs):
             resolved_view_config_ids = resolved_associated_item_refs.get(f"view_configs[{index}].associated_item_ids", [])
@@ -4074,21 +4134,30 @@ class AiBuilderFacade:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "view_config", "index": index, "view_key": view_config.view_key, "view_name": view_name, "status": "failed", "error_code": "VIEW_ASSOCIATED_RESOURCES_WRITE_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
 
-        final_resources: list[dict[str, Any]] = []
-        readback_failed = False
-        try:
-            final_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            readback_failed = True
+        final_resources: list[dict[str, Any]] = resources_after if resources_after_loaded else []
+        readback_failed = resources_after_readback_failed
+        if not resources_after_loaded and not resources_after_readback_failed:
+            try:
+                final_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError):
+                readback_failed = True
         final_by_id = _associated_resource_index(final_resources)
+        if removed:
+            removed = self._verify_associated_resources_deleted_by_pool(
+                deleted_items=removed,
+                resources=final_resources,
+                readback_failed=readback_failed,
+            )
         created_ids = [int(item["associated_item_id"]) for item in created if _coerce_positive_int(item.get("associated_item_id")) is not None]
         updated_ids = [int(item["associated_item_id"]) for item in updated if _coerce_positive_int(item.get("associated_item_id")) is not None]
         unchanged_ids = [int(item["associated_item_id"]) for item in unchanged if _coerce_positive_int(item.get("associated_item_id")) is not None]
         removed_ids = [int(item["associated_item_id"]) for item in removed if _coerce_positive_int(item.get("associated_item_id")) is not None]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed)
+        remove_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed)
         pool_verified = (
             not readback_failed
             and all(item_id in final_by_id for item_id in created_ids + updated_ids + unchanged_ids)
-            and all(item_id not in final_by_id for item_id in removed_ids)
+            and removed_verified
             and not failed
             and all(_coerce_positive_int(item.get("associated_item_id")) is not None for item in created)
         )
@@ -4123,6 +4192,13 @@ class AiBuilderFacade:
                     else "associated resource writes all failed or produced no confirmed result; application was not published",
                 )
             )
+        if remove_readback_pending:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCE_DELETE_READBACK_PENDING",
+                    "associated resource delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -4145,7 +4221,14 @@ class AiBuilderFacade:
             "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": False,
             "warnings": warnings,
-            "verification": {"associated_resources_verified": pool_verified, "associated_resource_view_configs_verified": view_configs_verified, "readback_loaded": not readback_failed},
+            "verification": {
+                "associated_resources_verified": pool_verified,
+                "associated_resource_view_configs_verified": view_configs_verified,
+                "readback_loaded": not readback_failed,
+                "removed_verified": removed_verified,
+                "remove_readback_pending": remove_readback_pending,
+                "removed_readback_results": deepcopy(removed),
+            },
             "verified": verified,
             "app_key": app_key,
             "app_name": app_name,
@@ -4634,12 +4717,14 @@ class AiBuilderFacade:
             or base_result.get("name")
             or app_key
         ).strip() or app_key
+        app_icon = str(base_result.get("appIcon") or "").strip() or None
         response = AppReadSummaryResponse(
             app_key=app_key,
             app_name=app_name,
             name=app_name,
             title=app_name,
-            app_icon=str(base_result.get("appIcon") or "").strip() or None,
+            app_icon=app_icon,
+            icon_config=workspace_icon_config(app_icon),
             visibility=_public_visibility_from_member_auth(base_result.get("auth")),
             tag_ids=_coerce_int_list(base_result.get("tagIds")),
             publish_status=base_result.get("appPublishStatus"),
@@ -5023,10 +5108,32 @@ class AiBuilderFacade:
                 suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
             )
         parsed = state["parsed"]
+        warnings: list[dict[str, Any]] = []
+        field_lookup = _build_public_field_lookup(cast(list[dict[str, Any]], parsed["fields"]))
+        chart_fields: list[dict[str, Any]] = []
+        try:
+            qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
+            chart_fields = _compact_public_chart_fields_read(
+                app_key=app_key,
+                qingbi_fields=[item for item in qingbi_fields if isinstance(item, dict)],
+                field_lookup=field_lookup,
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            warnings.append(
+                _warning(
+                    "QINGBI_FIELDS_READ_FAILED",
+                    "form fields were read, but QingBI chart fields could not be read; chart configuration should use chart_fields when available",
+                    backend_code=api_error.backend_code,
+                    request_id=api_error.request_id,
+                )
+            )
         response = AppFieldsReadResponse(
             app_key=app_key,
             fields=[_compact_public_field_read(field=field, layout=parsed["layout"]) for field in parsed["fields"]],
             field_count=len(parsed["fields"]),
+            chart_fields=chart_fields,
+            chart_field_count=len(chart_fields),
             form_settings=_form_settings_from_schema(state["schema"], parsed["fields"]),
         )
         return {
@@ -5041,7 +5148,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "warnings": [],
+            "warnings": warnings,
             "verification": {"app_exists": True},
             "verified": True,
             **response.model_dump(mode="json"),
@@ -6034,6 +6141,7 @@ class AiBuilderFacade:
                 details={"dash_key": dash_key, "being_draft": being_draft},
                 suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
             )
+        dash_icon = str(result.get("dashIcon") or "").strip() or None
         response = PortalGetResponse(
             dash_key=dash_key,
             being_draft=being_draft,
@@ -6047,7 +6155,8 @@ class AiBuilderFacade:
                 )
                 if tag_id is not None
             ],
-            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            dash_icon=dash_icon,
+            icon_config=workspace_icon_config(dash_icon),
             hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
             visibility=_public_visibility_from_member_auth(result.get("auth")),
             auth=deepcopy(result.get("auth")) if isinstance(result.get("auth"), dict) else {},
@@ -6086,6 +6195,7 @@ class AiBuilderFacade:
                 details={"dash_key": dash_key, "being_draft": being_draft},
                 suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
             )
+        dash_icon = str(result.get("dashIcon") or "").strip() or None
         response = PortalReadSummaryResponse(
             dash_key=dash_key,
             being_draft=being_draft,
@@ -6099,7 +6209,8 @@ class AiBuilderFacade:
                 )
                 if tag_id is not None
             ],
-            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            dash_icon=dash_icon,
+            icon_config=workspace_icon_config(dash_icon),
             hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
             config_keys=sorted(str(key) for key in (result.get("config") or {}).keys()) if isinstance(result.get("config"), dict) else [],
             dash_global_config_keys=sorted(str(key) for key in (result.get("dashGlobalConfig") or {}).keys()) if isinstance(result.get("dashGlobalConfig"), dict) else [],
@@ -8404,13 +8515,56 @@ class AiBuilderFacade:
             if len(matches) == 1:
                 key = _extract_view_key(matches[0])
                 removed_name = _extract_view_name(matches[0]) or selector_text
-                self.views.view_delete(profile=profile, viewgraph_key=key)
-                removed.append(removed_name)
-                if key:
-                    removed_keys.add(key)
-                    existing_by_key.pop(key, None)
-                existing_by_name.pop(removed_name, None)
-                view_results.append({"name": removed_name, "view_key": key, "type": None, "status": "removed"})
+                try:
+                    self.views.view_delete(profile=profile, viewgraph_key=key)
+                    delete_readback = self._verify_view_deleted_by_key(profile=profile, view_key=key)
+                    removed.append(removed_name)
+                    if key:
+                        removed_keys.add(key)
+                        existing_by_key.pop(key, None)
+                    existing_by_name.pop(removed_name, None)
+                    view_results.append(
+                        {
+                            "name": removed_name,
+                            "view_key": key,
+                            "type": None,
+                            "status": delete_readback.get("status") or "readback_pending",
+                            "operation": "delete",
+                            "delete_executed": True,
+                            "readback_status": delete_readback.get("readback_status"),
+                            "safe_to_retry_delete": False,
+                            **(
+                                {
+                                    "error_code": delete_readback.get("error_code"),
+                                    "message": delete_readback.get("message"),
+                                    "request_id": delete_readback.get("request_id"),
+                                    "backend_code": delete_readback.get("backend_code"),
+                                    "http_status": delete_readback.get("http_status"),
+                                    "transport_error": delete_readback.get("transport_error"),
+                                }
+                                if delete_readback.get("readback_status") != "deleted"
+                                else {}
+                            ),
+                        }
+                    )
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    failed_view = {
+                        "name": removed_name,
+                        "view_key": key,
+                        "type": None,
+                        "status": "failed",
+                        "operation": "delete",
+                        "delete_executed": False,
+                        "safe_to_retry_delete": True,
+                        "error_code": "VIEW_DELETE_FAILED",
+                        "message": _public_error_message("VIEW_APPLY_FAILED", api_error),
+                        "request_id": api_error.request_id,
+                        "backend_code": api_error.backend_code,
+                        "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                    }
+                    failed_views.append(failed_view)
+                    view_results.append(deepcopy(failed_view))
         created: list[str] = []
         updated: list[str] = []
         existing_view_list = [
@@ -8950,17 +9104,21 @@ class AiBuilderFacade:
                 failed_views.append(failure_entry)
                 view_results.append(failure_entry)
                 continue
-        try:
-            verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return finalize(_failed_from_api_error(
-                "VIEWS_READ_FAILED",
-                api_error,
-                normalized_args=normalized_args,
-                details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
-                suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-            ))
+        needs_view_list_readback = bool(created or updated)
+        verified_view_result: list[dict[str, Any]] | None = []
+        verified_views_unavailable = False
+        if needs_view_list_readback:
+            try:
+                verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return finalize(_failed_from_api_error(
+                    "VIEWS_READ_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
+                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                ))
         verified_names = {
             _extract_view_name(item)
             for item in (verified_view_result or [])
@@ -9248,8 +9406,27 @@ class AiBuilderFacade:
                         "view_key": item.get("view_key"),
                         "type": item.get("type"),
                         "status": "removed",
-                        "present_in_readback": None if verified_views_unavailable else name in verified_names,
-                        "removed_verified": None if verified_views_unavailable else name not in verified_names,
+                        "present_in_readback": False,
+                        "removed_verified": True,
+                        "delete_executed": bool(item.get("delete_executed")),
+                        "readback_status": item.get("readback_status") or "deleted",
+                        "safe_to_retry_delete": False,
+                    }
+                )
+            elif status == "readback_pending" and item.get("operation") == "delete":
+                readback_status = str(item.get("readback_status") or "unavailable")
+                verification_by_view.append(
+                    {
+                        "name": name,
+                        "view_key": item.get("view_key"),
+                        "type": item.get("type"),
+                        "status": "readback_pending",
+                        "present_in_readback": True if readback_status == "still_exists" else None,
+                        "removed_verified": False,
+                        "delete_executed": bool(item.get("delete_executed")),
+                        "readback_status": readback_status,
+                        "safe_to_retry_delete": False,
+                        "error_code": item.get("error_code"),
                     }
                 )
             else:
@@ -9262,10 +9439,17 @@ class AiBuilderFacade:
                         "error_code": item.get("error_code"),
                     }
                 )
+        removed_delete_results = [
+            item
+            for item in view_results
+            if item.get("operation") == "delete" and bool(item.get("delete_executed"))
+        ]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed_delete_results)
+        delete_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed_delete_results)
         verified = (
             (not verified_views_unavailable)
             and all(name in verified_names for name in created + updated)
-            and all(name not in verified_names for name in removed)
+            and removed_verified
         )
         view_filters_verified = verified and not filter_readback_pending and not filter_mismatches
         view_query_conditions_verified = verified and not query_condition_readback_pending and not query_condition_mismatches
@@ -9360,6 +9544,13 @@ class AiBuilderFacade:
                     "system buttons verified, but draft custom button bindings are not fully visible through view readback yet",
                 )
             )
+        if delete_readback_pending:
+            warnings.append(
+                _warning(
+                    "VIEW_DELETE_READBACK_PENDING",
+                    "view delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
         all_verified = verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified
         response = {
             "status": "success" if all_verified else "partial_success",
@@ -9407,6 +9598,7 @@ class AiBuilderFacade:
                 "query_condition_readback_pending": query_condition_readback_pending,
                 "associated_resource_readback_pending": associated_resource_readback_pending,
                 "button_readback_pending": button_readback_pending,
+                "delete_readback_pending": delete_readback_pending,
                 "custom_button_readback_pending": custom_button_readback_pending,
                 "custom_button_readback_pending_entries": deepcopy(custom_button_readback_pending_entries),
                 "by_view": verification_by_view,
@@ -9671,6 +9863,159 @@ class AiBuilderFacade:
             )
         return expanded, issues, results
 
+    def _verify_view_deleted_by_key(self, *, profile: str, view_key: str) -> JSONObject:
+        try:
+            self.views.view_get_config(profile=profile, viewgraph_key=view_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _delete_readback_is_not_found(api_error):
+                return {
+                    "view_key": view_key,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "view_key": view_key,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "VIEW_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but view existence could not be verified by view_key readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "view_key": view_key,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "VIEW_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the view still exists during view_key readback",
+        }
+
+    def _verify_custom_button_deleted_by_id(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        try:
+            self.buttons.custom_button_get(profile=profile, app_key=app_key, button_id=button_id, being_draft=True, include_raw=False)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _delete_readback_is_not_found(api_error):
+                return {
+                    "button_id": button_id,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "button_id": button_id,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "CUSTOM_BUTTON_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but custom button existence could not be verified by button_id readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "button_id": button_id,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "CUSTOM_BUTTON_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the custom button still exists during button_id readback",
+        }
+
+    def _verify_associated_resources_deleted_by_pool(
+        self,
+        *,
+        deleted_items: list[JSONObject],
+        resources: list[dict[str, Any]],
+        readback_failed: bool,
+    ) -> list[JSONObject]:
+        existing_by_id = _associated_resource_index(resources) if not readback_failed else {}
+        verified_items: list[JSONObject] = []
+        for item in deleted_items:
+            associated_item_id = _coerce_positive_int(item.get("associated_item_id"))
+            verified = deepcopy(item)
+            verified["operation"] = "remove"
+            verified["delete_executed"] = True
+            verified["safe_to_retry_delete"] = False
+            if associated_item_id is None or readback_failed:
+                verified["status"] = "readback_pending"
+                verified["readback_status"] = "unavailable"
+                verified["error_code"] = "ASSOCIATED_RESOURCE_DELETE_READBACK_UNAVAILABLE"
+                verified["message"] = "delete request completed, but associated resource pool readback is unavailable"
+            elif associated_item_id in existing_by_id:
+                verified["status"] = "readback_pending"
+                verified["readback_status"] = "still_exists"
+                verified["error_code"] = "ASSOCIATED_RESOURCE_DELETE_READBACK_STILL_EXISTS"
+                verified["message"] = "delete request completed, but the associated resource still exists in pool readback"
+            else:
+                verified["status"] = "removed"
+                verified["readback_status"] = "deleted"
+                verified.pop("error_code", None)
+                verified.pop("message", None)
+            verified_items.append(verified)
+        return verified_items
+
+    def _verify_chart_deleted_by_id(self, *, profile: str, chart_id: str) -> JSONObject:
+        base_result: dict[str, Any] | None = None
+        try:
+            raw = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
+            base_result = raw if isinstance(raw, dict) else {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _chart_delete_readback_is_not_found(api_error):
+                return {
+                    "chart_id": chart_id,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "chart_id": chart_id,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "CHART_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but chart existence could not be verified by chart_id readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "chart_id": chart_id,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "CHART_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the chart still exists during chart_id readback",
+            "readback_name": base_result.get("chartName") or base_result.get("name") if isinstance(base_result, dict) else None,
+        }
+
     def chart_apply(self, *, profile: str, request: ChartApplyRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
         permission_outcomes: list[PermissionCheckOutcome] = []
@@ -9695,21 +10040,27 @@ class AiBuilderFacade:
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
-        try:
-            schema_state = self._load_base_schema_state(profile=profile, app_key=app_key)
-            parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
-            fields = parsed.get("fields") if isinstance(parsed.get("fields"), list) else []
-            qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
-            existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return finalize(_failed_from_api_error(
-                "CHART_APPLY_FAILED",
-                api_error,
-                normalized_args=normalized_args,
-                details=_with_state_read_blocked_details({"app_key": app_key}, resource="chart", error=api_error),
-                suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-            ))
+        fields: list[dict[str, Any]] = []
+        qingbi_fields: list[Any] = []
+        existing_chart_items: list[Any] = []
+        existing_chart_list_source: str | None = None
+        needs_chart_inventory = bool(request.upsert_charts or request.patch_charts or request.reorder_chart_ids)
+        if needs_chart_inventory:
+            try:
+                schema_state = self._load_base_schema_state(profile=profile, app_key=app_key)
+                parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
+                fields = parsed.get("fields") if isinstance(parsed.get("fields"), list) else []
+                qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
+                existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return finalize(_failed_from_api_error(
+                    "CHART_APPLY_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": app_key}, resource="chart", error=api_error),
+                    suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
+                ))
 
         field_lookup = _build_public_field_lookup(fields)
         qingbi_fields_by_id = {
@@ -9717,6 +10068,11 @@ class AiBuilderFacade:
             for item in qingbi_fields
             if isinstance(item, dict) and item.get("fieldId")
         }
+        chart_field_lookup = _build_qingbi_chart_field_lookup(
+            app_key=app_key,
+            qingbi_fields=[item for item in qingbi_fields if isinstance(item, dict)],
+            field_lookup=field_lookup,
+        )
         existing_by_id = {
             _extract_chart_identifier(item): deepcopy(item)
             for item in existing_chart_items
@@ -9759,8 +10115,12 @@ class AiBuilderFacade:
         updated_ids: list[str] = []
         removed_ids: list[str] = []
         failed_items: list[dict[str, Any]] = []
+        delete_readback_issues: list[dict[str, Any]] = []
 
         for patch in upsert_charts:
+            chart_id = ""
+            target_type = ""
+            config_payload: dict[str, Any] | None = None
             try:
                 dataset_source = _chart_patch_dataset_source_type(patch)
                 if dataset_source:
@@ -9799,6 +10159,14 @@ class AiBuilderFacade:
                         f"existing chart '{chart_id or patch.name}' uses dataset report source '{existing_source_type}' and is not supported for update yet. "
                         "Update it in QingBI directly, then attach the existing report with app_associated_resources_apply using report_source='dataset'."
                     )
+                if existing is None or config_update_requested:
+                    config_payload = _build_public_chart_config_payload(
+                        patch=patch,
+                        app_key=app_key,
+                        field_lookup=field_lookup,
+                        chart_field_lookup=chart_field_lookup,
+                        qingbi_fields_by_id=qingbi_fields_by_id,
+                    )
                 if existing is None:
                     temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
                     create_payload = {
@@ -9882,13 +10250,7 @@ class AiBuilderFacade:
 
                 config_updated = False
                 if existing is None or config_update_requested:
-                    config_payload = _build_public_chart_config_payload(
-                        patch=patch,
-                        app_key=app_key,
-                        field_lookup=field_lookup,
-                        qingbi_fields_by_id=qingbi_fields_by_id,
-                    )
-                    self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload)
+                    self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload or {})
                     config_updated = True
                 if existing is not None and chart_id not in updated_ids and config_updated:
                     updated_ids.append(chart_id)
@@ -9918,11 +10280,21 @@ class AiBuilderFacade:
                 )
             except (QingflowApiError, RuntimeError, ValueError, VisibilityResolutionError) as error:
                 api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
+                diagnostics = (
+                    error.diagnostics
+                    if isinstance(error, ChartRuleViolation)
+                    else _explain_chart_backend_validation_error(api_error=api_error, chart_type=target_type or patch.chart_type.value, payload=config_payload)
+                    if api_error is not None
+                    else None
+                )
                 failure = {
-                    "chart_id": str(locals().get("chart_id") or patch.chart_id or ""),
+                    "chart_id": str(chart_id or patch.chart_id or ""),
                     "name": patch.name,
+                    "chart_type": patch.chart_type.value,
                     "status": "failed",
-                    "message": str(error),
+                    "error_code": diagnostics.get("rule_code") if isinstance(diagnostics, dict) else "CHART_APPLY_FAILED",
+                    "message": str(diagnostics.get("message") if isinstance(diagnostics, dict) and diagnostics.get("message") else error),
+                    "diagnostics": diagnostics,
                     "request_id": api_error.request_id if api_error else None,
                     "backend_code": api_error.backend_code if api_error else None,
                     "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
@@ -9934,12 +10306,18 @@ class AiBuilderFacade:
             try:
                 self.charts.qingbi_report_delete(profile=profile, chart_id=chart_id)
                 removed_ids.append(chart_id)
-                chart_results.append({"chart_id": chart_id, "status": "removed"})
+                delete_result = self._verify_chart_deleted_by_id(profile=profile, chart_id=chart_id)
+                if delete_result.get("readback_status") != "deleted":
+                    delete_readback_issues.append(delete_result)
+                chart_results.append(delete_result)
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 failure = {
                     "chart_id": chart_id,
+                    "operation": "delete",
                     "status": "failed",
+                    "delete_executed": False,
+                    "safe_to_retry_delete": True,
                     "message": _public_error_message("CHART_APPLY_FAILED", api_error),
                     "request_id": api_error.request_id,
                     "backend_code": api_error.backend_code,
@@ -9974,30 +10352,37 @@ class AiBuilderFacade:
                 chart_results.append(failure)
 
         noop = not created_ids and not updated_ids and not removed_ids and not reordered and not failed_items
-        try:
-            readback_items, readback_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-            readback_ids = {
-                _extract_chart_identifier(item)
-                for item in readback_items
-                if isinstance(item, dict) and _extract_chart_identifier(item)
-            }
-            verified = (
-                all(chart_id in readback_ids for chart_id in created_ids + updated_ids)
-                and all(chart_id not in readback_ids for chart_id in removed_ids)
-            )
-            if request.reorder_chart_ids:
-                ordered_readback = [
+        needs_list_readback = bool(created_ids or updated_ids or reordered)
+        delete_readback_unavailable = any(item.get("readback_status") == "unavailable" for item in delete_readback_issues)
+        deletes_verified = not delete_readback_issues
+        readback_unavailable = False
+        readback_list_source: str | None = existing_chart_list_source
+        if needs_list_readback:
+            try:
+                readback_items, readback_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+                readback_ids = {
                     _extract_chart_identifier(item)
                     for item in readback_items
                     if isinstance(item, dict) and _extract_chart_identifier(item)
-                ]
-                requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
-                verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
-            readback_unavailable = False
-        except (QingflowApiError, RuntimeError):
-            verified = False
-            readback_unavailable = True
-            readback_list_source = None
+                }
+                verified = all(chart_id in readback_ids for chart_id in created_ids + updated_ids)
+                if request.reorder_chart_ids:
+                    ordered_readback = [
+                        _extract_chart_identifier(item)
+                        for item in readback_items
+                        if isinstance(item, dict) and _extract_chart_identifier(item)
+                    ]
+                    requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
+                    verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
+                readback_unavailable = False
+            except (QingflowApiError, RuntimeError):
+                verified = False
+                readback_unavailable = True
+                readback_list_source = None
+        else:
+            verified = True
+        verified = verified and deletes_verified
+        any_readback_unavailable = readback_unavailable or delete_readback_unavailable
 
         if failed_items:
             successful_changes = bool(created_ids or updated_ids or removed_ids or reordered)
@@ -10019,11 +10404,13 @@ class AiBuilderFacade:
                     failed_items=failed_items,
                     readback_unavailable=readback_unavailable,
                     verified=False if failed_items else verified,
+                    delete_readback_issues=delete_readback_issues,
                 ),
                 "verification": {
                     "charts_verified": False if failed_items else verified,
-                    "readback_unavailable": readback_unavailable,
-                    "chart_order_verified": False if request.reorder_chart_ids else (readback_list_source == "sorted"),
+                    "readback_unavailable": any_readback_unavailable,
+                    "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
+                    "chart_order_verified": False if request.reorder_chart_ids else True,
                     "chart_list_source": readback_list_source or existing_chart_list_source,
                 },
                 "app_key": app_key,
@@ -10032,27 +10419,37 @@ class AiBuilderFacade:
                 "verified": False if failed_items else verified,
             })
         result_verified = verified or noop
+        pending_delete = bool(delete_readback_issues)
+        pending_error_code = "CHART_DELETE_READBACK_PENDING" if pending_delete and not readback_unavailable else "CHART_READBACK_PENDING"
+        pending_message = "applied chart operations; delete readback pending" if pending_delete else "applied chart operations; readback pending"
+        pending_suggestion = (
+            {"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": str(delete_readback_issues[0].get("chart_id") or "CHART_ID")}}
+            if pending_delete
+            else {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}}
+        )
         return finalize({
             "status": "success" if result_verified else "partial_success",
-            "error_code": None if result_verified else "CHART_READBACK_PENDING",
+            "error_code": None if result_verified else pending_error_code,
             "recoverable": not result_verified,
-            "message": "no chart changes requested" if noop else ("applied chart operations" if verified else "applied chart operations; readback pending"),
+            "message": "no chart changes requested" if noop else ("applied chart operations" if verified else pending_message),
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
             "details": {},
             "request_id": None,
-            "suggested_next_call": None if result_verified else {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
+            "suggested_next_call": None if result_verified else pending_suggestion,
             "noop": noop,
             "warnings": _chart_apply_warnings(
                 failed_items=[],
                 readback_unavailable=False if noop else readback_unavailable,
                 verified=result_verified,
+                delete_readback_issues=delete_readback_issues,
             ),
             "verification": {
                 "charts_verified": result_verified,
-                "readback_unavailable": False if noop else readback_unavailable,
-                "chart_order_verified": True if noop and not request.reorder_chart_ids else (readback_list_source == "sorted" and result_verified if request.reorder_chart_ids else readback_list_source == "sorted"),
+                "readback_unavailable": False if noop else any_readback_unavailable,
+                "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
+                "chart_order_verified": (readback_list_source == "sorted" and result_verified) if request.reorder_chart_ids else True,
                 "chart_list_source": existing_chart_list_source if noop else readback_list_source,
             },
             "app_key": app_key,
@@ -10168,6 +10565,7 @@ class AiBuilderFacade:
                     suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                 )
         try:
+            layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
                 create_payload = _build_public_portal_base_payload(
                     dash_name=request.dash_name or "未命名门户",
@@ -10204,7 +10602,12 @@ class AiBuilderFacade:
                 base_payload=base_payload,
             )
             if sections_requested:
-                component_payload = self._build_portal_components_from_sections(profile=profile, sections=request.sections)
+                component_payload = 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)
                 update_payload["components"] = component_payload
                 self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
             self.portals.portal_update_base_info(
@@ -10307,6 +10710,7 @@ class AiBuilderFacade:
             live_meta_verified=live_meta_verified,
             publish_requested=request.publish,
         )
+        warnings.extend(_portal_layout_warning_items(layout_diagnostics))
         return finalize({
             "status": status,
             "error_code": error_code,
@@ -10333,6 +10737,7 @@ class AiBuilderFacade:
             "suggested_next_call": None if verified else {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
             "noop": False,
             "warnings": warnings,
+            "layout_diagnostics": layout_diagnostics,
             "verification": {
                 "draft_verified": draft_verified,
                 "draft_metadata_verified": draft_meta_verified,
@@ -10943,6 +11348,7 @@ class AiBuilderFacade:
         *,
         profile: str,
         sections: list[PortalSectionPatch],
+        layout_preset: str | None = None,
     ) -> list[dict[str, Any]]:
         resolved_components: list[dict[str, Any]] = []
         pc_x = 0
@@ -10959,9 +11365,15 @@ class AiBuilderFacade:
                     pc_y=pc_y,
                     pc_row_height=pc_row_height,
                     mobile_y=mobile_y,
+                    layout_preset=layout_preset,
                 )
             else:
-                position_payload = _portal_position_payload(section.position)
+                position_payload = _portal_position_payload(section.position, inferred_mobile_y=mobile_y)
+                mobile = position_payload.get("mobile") if isinstance(position_payload.get("mobile"), dict) else {}
+                mobile_y = max(
+                    mobile_y,
+                    int(mobile.get("y") or 0) + int(mobile.get("rows") or 0),
+                )
             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":
@@ -12360,6 +12772,28 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
     return mapping.get(error_code, "requested builder resource is unavailable in the current route")
 
 
+def _chart_delete_readback_is_not_found(error: QingflowApiError) -> bool:
+    return _delete_readback_is_not_found(error)
+
+
+def _delete_readback_is_not_found(error: QingflowApiError) -> bool:
+    backend_code = int(error.backend_code or 0) if str(error.backend_code or "").isdigit() else error.backend_code
+    if error.http_status == 404 or backend_code in {404, 40038, 81007}:
+        return True
+    message = str(error.message or "").lower()
+    return any(
+        marker in message
+        for marker in (
+            "object not exist",
+            "not found",
+            "not exist",
+            "does not exist",
+            "不存在",
+            "未找到",
+        )
+    )
+
+
 def _extract_edit_lock_owner(message: str) -> JSONObject:
     text = str(message or "").strip()
     if not text:
@@ -12664,18 +13098,20 @@ def _build_public_dimension_fields(
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
+    chart_type: str = "chart",
 ) -> list[dict[str, Any]]:
     dimensions: list[dict[str, Any]] = []
     for selector in selectors:
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(selector, chart_field_lookup=chart_field_lookup, chart_type=chart_type, role="dimension")
+        field_id = _chart_field_id(qingbi_field)
+        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         dimensions.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "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 "")),
                 "orderType": "default",
                 "alignType": "left",
                 "dateFormat": "yyyy-MM-dd",
@@ -12717,27 +13153,540 @@ def _default_public_total_metric() -> dict[str, Any]:
     }
 
 
+_QINGBI_TOTAL_FIELD_ID = ":-100"
+_QINGBI_DECIMAL_FIELD_TYPES = {"decimal", "number", "numeric", "amount", "integer", "int", "long", "double", "float"}
+
+
+class ChartRuleViolation(ValueError):
+    def __init__(self, diagnostics: dict[str, Any]) -> None:
+        self.diagnostics = diagnostics
+        super().__init__(str(diagnostics.get("message") or diagnostics.get("next_action") or "chart rule violation"))
+
+
+def _chart_field_id(field: dict[str, Any]) -> str:
+    return str(field.get("fieldId") or field.get("field_id") or "").strip()
+
+
+def _chart_field_name(field: dict[str, Any]) -> str | None:
+    name = str(field.get("fieldName") or field.get("field_name") or "").strip()
+    return name or None
+
+
+def _chart_fields(payload: dict[str, Any], key: str) -> list[dict[str, Any]]:
+    value = payload.get(key)
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _chart_field_summary(field: dict[str, Any]) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "field_id": _chart_field_id(field),
+            "field_name": _chart_field_name(field),
+            "field_type": field.get("fieldType") or field.get("field_type"),
+            "field_source": field.get("fieldSource") or field.get("field_source"),
+            "bi_formula_type": field.get("biFormulaType") or field.get("bi_formula_type"),
+            "aggre_field_id": field.get("aggreFieldId") or field.get("aggre_field_id"),
+        }
+    )
+
+
+def _chart_duplicate_fields(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: dict[str, dict[str, Any]] = {}
+    duplicates: dict[str, dict[str, Any]] = {}
+    for field in fields:
+        field_id = _chart_field_id(field)
+        if not field_id:
+            continue
+        if field_id in seen:
+            duplicates[field_id] = _chart_field_summary(field)
+        else:
+            seen[field_id] = field
+    return list(duplicates.values())
+
+
+def _chart_rule_diagnostics(
+    *,
+    rule_code: str,
+    chart_type: str,
+    message: str,
+    expected: str,
+    actual: dict[str, Any],
+    next_action: str,
+    offending_fields: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "rule_code": rule_code,
+            "chart_type": chart_type,
+            "message": message,
+            "expected": expected,
+            "actual": actual,
+            "offending_fields": offending_fields or [],
+            "next_action": next_action,
+        }
+    )
+
+
+def _raise_chart_rule(
+    *,
+    rule_code: str,
+    chart_type: str,
+    message: str,
+    expected: str,
+    actual: dict[str, Any],
+    next_action: str,
+    offending_fields: list[dict[str, Any]] | None = None,
+) -> None:
+    raise ChartRuleViolation(
+        _chart_rule_diagnostics(
+            rule_code=rule_code,
+            chart_type=chart_type,
+            message=message,
+            expected=expected,
+            actual=actual,
+            next_action=next_action,
+            offending_fields=offending_fields,
+        )
+    )
+
+
+_QINGBI_TOTAL_FIELD_ALIASES = {_QINGBI_TOTAL_FIELD_ID, "数据总量", "data_total", "total", "count"}
+
+
+def _qingbi_field_que_id(*, app_key: str, field_id: Any) -> int | None:
+    raw = str(field_id or "").strip()
+    if not raw or raw == _QINGBI_TOTAL_FIELD_ID:
+        return None
+    if raw.startswith("field_"):
+        return _coerce_positive_int(raw.removeprefix("field_"))
+    if raw.startswith(f"{app_key}:"):
+        return _coerce_positive_int(raw.split(":", 1)[1])
+    if ":" in raw:
+        return _coerce_positive_int(raw.rsplit(":", 1)[1])
+    return _coerce_positive_int(raw)
+
+
+def _dedupe_qingbi_fields(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    deduped: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for field in fields:
+        field_id = _chart_field_id(field)
+        key = field_id or json.dumps(field, sort_keys=True, ensure_ascii=False, default=str)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(field)
+    return deduped
+
+
+def _build_qingbi_chart_field_lookup(
+    *,
+    app_key: str,
+    qingbi_fields: list[dict[str, Any]],
+    field_lookup: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    by_selector: dict[str, list[dict[str, Any]]] = {}
+    form_by_que_id = field_lookup.get("by_que_id") or {}
+
+    def add_selector(key: Any, field: dict[str, Any]) -> None:
+        normalized = str(key or "").strip()
+        if not normalized:
+            return
+        by_selector.setdefault(normalized, []).append(field)
+        lower = normalized.lower()
+        if lower != normalized:
+            by_selector.setdefault(lower, []).append(field)
+
+    for raw_field in qingbi_fields:
+        if not isinstance(raw_field, dict):
+            continue
+        field_id = _chart_field_id(raw_field)
+        if not field_id:
+            continue
+        field = deepcopy(raw_field)
+        que_id = _qingbi_field_que_id(app_key=app_key, field_id=field_id)
+        form_field = form_by_que_id.get(que_id) if que_id is not None else None
+        if isinstance(form_field, dict):
+            field["_public_form_field"] = deepcopy(form_field)
+        if not _chart_field_name(field) and isinstance(form_field, dict) and form_field.get("name"):
+            field["fieldName"] = form_field.get("name")
+
+        add_selector(field_id, field)
+        if que_id is not None:
+            add_selector(que_id, field)
+            add_selector(f"field_{que_id}", field)
+            if isinstance(form_field, dict):
+                add_selector(form_field.get("field_id"), field)
+        title = _chart_field_name(field)
+        if title:
+            add_selector(title, field)
+    return {"by_selector": by_selector}
+
+
+def _compact_public_chart_fields_read(
+    *,
+    app_key: str,
+    qingbi_fields: list[dict[str, Any]],
+    field_lookup: dict[str, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    form_by_que_id = field_lookup.get("by_que_id") or {}
+    compact_fields: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for field in qingbi_fields:
+        if not isinstance(field, dict):
+            continue
+        bi_field_id = _chart_field_id(field)
+        if not bi_field_id or bi_field_id in seen:
+            continue
+        seen.add(bi_field_id)
+        que_id = _qingbi_field_que_id(app_key=app_key, field_id=bi_field_id)
+        form_field = form_by_que_id.get(que_id) if que_id is not None else None
+        public_field_id = (
+            str(form_field.get("field_id"))
+            if isinstance(form_field, dict) and form_field.get("field_id")
+            else f"field_{que_id}"
+            if que_id is not None
+            else bi_field_id
+        )
+        title = _chart_field_name(field) or (
+            str(form_field.get("name")) if isinstance(form_field, dict) and form_field.get("name") else bi_field_id
+        )
+        compact_fields.append(
+            _compact_dict(
+                {
+                    "field_id": public_field_id,
+                    "que_id": que_id,
+                    "bi_field_id": bi_field_id,
+                    "title": title,
+                    "field_type": field.get("fieldType") or field.get("field_type"),
+                    "system_field": bool(que_id is not None and not isinstance(form_field, dict)),
+                    "available_for_charts": True,
+                }
+            )
+        )
+    return compact_fields
+
+
+def _chart_field_candidates(
+    selector: Any,
+    *,
+    chart_field_lookup: dict[str, Any],
+) -> list[dict[str, Any]]:
+    raw = str(selector or "").strip()
+    if not raw:
+        return []
+    by_selector = chart_field_lookup.get("by_selector") if isinstance(chart_field_lookup.get("by_selector"), dict) else {}
+    return _dedupe_qingbi_fields(list(by_selector.get(raw) or by_selector.get(raw.lower()) or []))
+
+
+def _resolve_qingbi_chart_field(
+    selector: Any,
+    *,
+    chart_field_lookup: dict[str, Any],
+    chart_type: str,
+    role: str,
+) -> dict[str, Any]:
+    raw = str(selector or "").strip()
+    if not raw:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
+            chart_type=chart_type,
+            message="chart field selector cannot be empty",
+            expected="use a field from app_get_fields.chart_fields",
+            actual={"selector": raw, "role": role},
+            next_action="Call app_get_fields and choose a field from chart_fields for chart dimensions, metrics, filters, or query conditions.",
+        )
+    if raw in _QINGBI_TOTAL_FIELD_ALIASES or raw.lower() in _QINGBI_TOTAL_FIELD_ALIASES:
+        if role == "metric":
+            return _default_public_total_metric()
+        _raise_chart_rule(
+            rule_code="CHART_TOTAL_FIELD_NOT_ALLOWED",
+            chart_type=chart_type,
+            message="数据总量 is only valid as a metric field, not as a dimension/filter/query field",
+            expected="use 数据总量 only in indicator_field_ids or omit metrics for count-style charts",
+            actual={"selector": raw, "role": role},
+            next_action="Choose a real QingBI field from app_get_fields.chart_fields for dimensions, filters, and query conditions.",
+            offending_fields=[{"field_id": _QINGBI_TOTAL_FIELD_ID, "field_name": "数据总量"}],
+        )
+    candidates = _chart_field_candidates(raw, chart_field_lookup=chart_field_lookup)
+    if not candidates:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
+            chart_type=chart_type,
+            message=f"field '{raw}' was not found in QingBI datasource fields for this app",
+            expected="chart fields must come from app_get_fields.chart_fields, not record schema or form-only fields",
+            actual={"selector": raw, "role": role},
+            next_action="Call app_get_fields and choose a field from chart_fields; if the system field is absent there, QingBI cannot use it for this report.",
+        )
+    if len(candidates) > 1:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_AMBIGUOUS",
+            chart_type=chart_type,
+            message=f"field '{raw}' matched multiple QingBI datasource fields",
+            expected="use an unambiguous field selector such as bi_field_id or field_<queId>",
+            actual={"selector": raw, "role": role, "candidate_count": len(candidates)},
+            next_action="Use one of the returned candidate bi_field_id values or field_<queId> selectors.",
+            offending_fields=[_chart_field_summary(item) for item in candidates],
+        )
+    return deepcopy(candidates[0])
+
+
+def _check_chart_slot_duplicates(*, chart_type: str, payload: dict[str, Any], slot_names: list[str]) -> None:
+    for slot_name in slot_names:
+        duplicates = _chart_duplicate_fields(_chart_fields(payload, slot_name))
+        if duplicates:
+            _raise_chart_rule(
+                rule_code="CHART_FIELD_ID_REPEAT",
+                chart_type=chart_type,
+                message=f"{chart_type} chart has duplicate field ids in {slot_name}",
+                expected=f"{slot_name} must not contain duplicated fieldId values",
+                actual={"slot": slot_name, "duplicate_count": len(duplicates)},
+                offending_fields=duplicates,
+                next_action="Use different fields for this slot, or remove the duplicated field before retrying.",
+            )
+
+
+def _histogram_metric_issue(metric: dict[str, Any]) -> dict[str, Any] | None:
+    field_id = _chart_field_id(metric)
+    if field_id == _QINGBI_TOTAL_FIELD_ID:
+        return {
+            "rule_code": "HISTOGRAM_DEFAULT_TOTAL_METRIC_UNSUPPORTED",
+            "message": "histogram cannot use 数据总量 as its metric",
+            "next_action": "Pass one explicit numeric field in indicator_field_ids and set config.aggregate such as sum/avg.",
+        }
+    field_type = str(metric.get("fieldType") or metric.get("field_type") or "").strip().lower()
+    if field_type not in _QINGBI_DECIMAL_FIELD_TYPES:
+        return {
+            "rule_code": "HISTOGRAM_METRIC_FIELD_TYPE_UNSUPPORTED",
+            "message": "histogram metric must be a numeric field",
+            "next_action": "Choose one number/amount field as indicator_field_ids for histogram.",
+        }
+    field_source = str(metric.get("fieldSource") or metric.get("field_source") or "").strip().lower()
+    bi_formula_type = str(metric.get("biFormulaType") or metric.get("bi_formula_type") or "").strip().lower()
+    aggre_field_id = str(metric.get("aggreFieldId") or metric.get("aggre_field_id") or "").strip()
+    if field_source == "formula" and (bi_formula_type in {"chart_agg", "agg"} or aggre_field_id):
+        return {
+            "rule_code": "HISTOGRAM_AGG_FORMULA_METRIC_UNSUPPORTED",
+            "message": "histogram metric cannot be an aggregate formula field",
+            "next_action": "Choose a plain numeric field, not an aggregate formula field.",
+        }
+    return None
+
+
+def _validate_public_chart_payload_rules(payload: dict[str, Any]) -> None:
+    chart_type = str(payload.get("chartType") or "").strip().lower()
+    dimensions = _chart_fields(payload, "selectedDimensions")
+    metrics = _chart_fields(payload, "selectedMetrics")
+    _check_chart_slot_duplicates(
+        chart_type=chart_type,
+        payload=payload,
+        slot_names=[
+            "selectedDimensions",
+            "selectedMetrics",
+            "xDimensions",
+            "yDimensions",
+            "xMetrics",
+            "yMetrics",
+            "leftMetrics",
+            "rightMetrics",
+        ],
+    )
+
+    if chart_type == "gauge":
+        if dimensions:
+            _raise_chart_rule(
+                rule_code="GAUGE_DIMENSION_NOT_ALLOWED",
+                chart_type=chart_type,
+                message="gauge chart must not have dimensions",
+                expected="0 dimensions",
+                actual={"dimension_count": len(dimensions)},
+                offending_fields=[_chart_field_summary(field) for field in dimensions],
+                next_action="Remove dimension_field_ids for gauge. The CLI clears public dimensions, but custom selectedDimensions in config must also be removed.",
+            )
+        if len(metrics) != 2:
+            _raise_chart_rule(
+                rule_code="GAUGE_METRIC_COUNT_INVALID",
+                chart_type=chart_type,
+                message="gauge chart requires exactly two metrics",
+                expected="exactly 2 non-duplicated metrics; one real metric plus 数据总量 is allowed",
+                actual={"metric_count": len(metrics), "metric_field_ids": [_chart_field_id(field) for field in metrics]},
+                offending_fields=[_chart_field_summary(field) for field in metrics],
+                next_action="Pass two different indicator_field_ids, or pass one explicit real numeric metric so the CLI can pair it with 数据总量.",
+            )
+    elif chart_type == "histogram":
+        if len(dimensions) > 1:
+            _raise_chart_rule(
+                rule_code="HISTOGRAM_DIMENSION_COUNT_INVALID",
+                chart_type=chart_type,
+                message="histogram chart supports at most one dimension",
+                expected="0 or 1 dimension",
+                actual={"dimension_count": len(dimensions)},
+                offending_fields=[_chart_field_summary(field) for field in dimensions],
+                next_action="Keep at most one dimension_field_ids value for histogram.",
+            )
+        if len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="HISTOGRAM_METRIC_COUNT_INVALID",
+                chart_type=chart_type,
+                message="histogram chart requires exactly one explicit metric",
+                expected="exactly 1 plain numeric metric",
+                actual={"metric_count": len(metrics), "metric_field_ids": [_chart_field_id(field) for field in metrics]},
+                offending_fields=[_chart_field_summary(field) for field in metrics],
+                next_action="Pass exactly one numeric field in indicator_field_ids; histogram cannot rely on the default count metric.",
+            )
+        issue = _histogram_metric_issue(metrics[0])
+        if issue:
+            _raise_chart_rule(
+                rule_code=str(issue["rule_code"]),
+                chart_type=chart_type,
+                message=str(issue["message"]),
+                expected="one plain decimal metric; not 数据总量 and not aggregate formula",
+                actual={"metric": _chart_field_summary(metrics[0])},
+                offending_fields=[_chart_field_summary(metrics[0])],
+                next_action=str(issue["next_action"]),
+            )
+    elif chart_type == "heatmap":
+        if len(dimensions) != 2 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="HEATMAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="heatmap chart requires two dimensions and one metric",
+                expected="2 dimensions and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly two dimension_field_ids and one indicator_field_ids value for heatmap.",
+            )
+    elif chart_type == "waterfall":
+        if len(dimensions) != 1 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="WATERFALL_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="waterfall chart requires one dimension and one metric",
+                expected="1 dimension and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly one dimension_field_ids value and one indicator_field_ids value for waterfall.",
+            )
+    elif chart_type == "treemap":
+        if len(dimensions) < 1 or len(dimensions) > 2 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="TREEMAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="treemap chart requires one or two dimensions and one metric",
+                expected="1-2 dimensions and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass one or two dimension_field_ids values and exactly one indicator_field_ids value for treemap.",
+            )
+    elif chart_type == "map":
+        if len(dimensions) != 1 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="MAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="map chart requires one dimension and one metric",
+                expected="1 dimension and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly one location/address dimension and one metric for map.",
+            )
+    elif chart_type == "scatter":
+        x_metrics = _chart_fields(payload, "xMetrics")
+        y_metrics = _chart_fields(payload, "yMetrics")
+        if not dimensions or len(x_metrics) != 1 or len(y_metrics) != 1:
+            _raise_chart_rule(
+                rule_code="SCATTER_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="scatter chart requires at least one dimension, one x metric, and one y metric",
+                expected=">=1 dimensions, exactly 1 x metric and 1 y metric",
+                actual={"dimension_count": len(dimensions), "x_metric_count": len(x_metrics), "y_metric_count": len(y_metrics)},
+                next_action="Pass at least one dimension_field_ids value and one or two indicator_field_ids values for scatter.",
+            )
+    elif chart_type == "dualaxes":
+        left_metrics = _chart_fields(payload, "leftMetrics")
+        right_metrics = _chart_fields(payload, "rightMetrics")
+        if not dimensions or (not left_metrics and not right_metrics):
+            _raise_chart_rule(
+                rule_code="DUALAXES_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="dualaxes chart requires at least one dimension and at least one metric axis",
+                expected=">=1 dimensions and at least one left/right metric",
+                actual={"dimension_count": len(dimensions), "left_metric_count": len(left_metrics), "right_metric_count": len(right_metrics)},
+                next_action="Pass at least one dimension_field_ids value and one or two indicator_field_ids values for dualaxes.",
+            )
+
+
+def _explain_chart_backend_validation_error(
+    *,
+    api_error: QingflowApiError,
+    chart_type: str,
+    payload: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    backend_code = api_error.backend_code
+    if backend_code not in {81002, 81005}:
+        return None
+    chart_type = str(chart_type or (payload or {}).get("chartType") or "").strip().lower()
+    if isinstance(payload, dict):
+        try:
+            _validate_public_chart_payload_rules(payload)
+        except ChartRuleViolation as violation:
+            return violation.diagnostics
+    if backend_code == 81005:
+        duplicate_fields: list[dict[str, Any]] = []
+        if isinstance(payload, dict):
+            for slot_name in [
+                "selectedDimensions",
+                "selectedMetrics",
+                "xDimensions",
+                "yDimensions",
+                "xMetrics",
+                "yMetrics",
+                "leftMetrics",
+                "rightMetrics",
+            ]:
+                duplicate_fields.extend(_chart_duplicate_fields(_chart_fields(payload, slot_name)))
+        return _chart_rule_diagnostics(
+            rule_code="CHART_FIELD_ID_REPEAT",
+            chart_type=chart_type,
+            message="QingBI rejected the chart because one field id is repeated in a chart slot",
+            expected="field ids must be unique within each dimension/metric slot",
+            actual={"backend_code": backend_code},
+            offending_fields=duplicate_fields,
+            next_action="Remove duplicated fields or pass two different explicit metrics before retrying.",
+        )
+    return _chart_rule_diagnostics(
+        rule_code="WRONG_METRIC_COUNT_OR_TYPE",
+        chart_type=chart_type,
+        message="QingBI rejected the chart because metric count or metric type does not satisfy this chart type",
+        expected="use the chart-type metric count/type rules from builder charts documentation",
+        actual={"backend_code": backend_code},
+        next_action="Check indicator_field_ids count and field types; for histogram use exactly one plain numeric metric, and for gauge use two non-duplicated metrics.",
+    )
+
+
 def _build_public_metric_fields(
     selectors: list[str],
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
     aggregate: str,
+    chart_type: str = "chart",
 ) -> list[dict[str, Any]]:
     normalized_aggregate = str(aggregate or "count").strip().lower()
     if normalized_aggregate == "count" or not selectors:
         return [_default_public_total_metric()]
     metrics: list[dict[str, Any]] = []
     for selector in selectors:
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(selector, chart_field_lookup=chart_field_lookup, chart_type=chart_type, role="metric")
+        field_id = _chart_field_id(qingbi_field)
+        if field_id == _QINGBI_TOTAL_FIELD_ID:
+            metrics.append(qingbi_field)
+            continue
+        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         metrics.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "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 "")),
                 "orderType": "default",
                 "alignType": "left",
                 "dateFormat": "yyyy-MM-dd",
@@ -12754,6 +13703,8 @@ def _build_public_metric_fields(
                 "supId": qingbi_field.get("supId"),
                 "beingTable": bool(qingbi_field.get("beingTable", False)),
                 "returnType": qingbi_field.get("returnType"),
+                "biFormulaType": qingbi_field.get("biFormulaType"),
+                "aggreFieldId": qingbi_field.get("aggreFieldId"),
             }
         )
     return metrics or [_default_public_total_metric()]
@@ -12783,7 +13734,9 @@ def _build_public_chart_filter_matrix(
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
+    chart_type: str = "chart",
 ) -> list[list[dict[str, Any]]]:
     if not rules:
         return []
@@ -12799,16 +13752,21 @@ def _build_public_chart_filter_matrix(
         ViewFilterOperator.not_empty.value: 16,
     }
     for rule in rules:
-        field = _resolve_public_field(getattr(rule, "field_name", None), field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(
+            getattr(rule, "field_name", None),
+            chart_field_lookup=chart_field_lookup,
+            chart_type=chart_type,
+            role="filter",
+        )
+        field_id = _chart_field_id(qingbi_field)
+        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 [])
         group.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "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,
                 "matchType": 1,
@@ -12822,6 +13780,7 @@ def _build_public_chart_config_payload(
     patch: ChartUpsertPatch,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
 ) -> dict[str, Any]:
     config = deepcopy(patch.config)
@@ -12840,12 +13799,19 @@ def _build_public_chart_config_payload(
             patch.filters,
             app_key=app_key,
             field_lookup=field_lookup,
+            chart_field_lookup=chart_field_lookup,
             qingbi_fields_by_id=qingbi_fields_by_id,
+            chart_type=patch.chart_type.value,
         )
     query_condition_field_ids = []
     for selector in list(config.pop("query_condition_field_ids", []) or []):
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        query_condition_field_ids.append(_bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id))
+        field = _resolve_qingbi_chart_field(
+            selector,
+            chart_field_lookup=chart_field_lookup,
+            chart_type=patch.chart_type.value,
+            role="query_condition",
+        )
+        query_condition_field_ids.append(_chart_field_id(field))
     backend_chart_type = _map_public_chart_type_to_backend(patch.chart_type)
     if backend_chart_type == "gauge" and not patch.indicator_field_ids and "selectedMetrics" not in config:
         raise ValueError("gauge charts require at least one indicator_field_ids value; pass one metric and the CLI will pair it with 数据总量")
@@ -12853,14 +13819,18 @@ def _build_public_chart_config_payload(
         patch.dimension_field_ids,
         app_key=app_key,
         field_lookup=field_lookup,
+        chart_field_lookup=chart_field_lookup,
         qingbi_fields_by_id=qingbi_fields_by_id,
+        chart_type=patch.chart_type.value,
     )
     selected_metrics = _build_public_metric_fields(
         patch.indicator_field_ids,
         app_key=app_key,
         field_lookup=field_lookup,
+        chart_field_lookup=chart_field_lookup,
         qingbi_fields_by_id=qingbi_fields_by_id,
         aggregate=aggregate,
+        chart_type=patch.chart_type.value,
     )
     payload: dict[str, Any] = {
         "chartName": patch.name,
@@ -12914,6 +13884,7 @@ def _build_public_chart_config_payload(
         if key in config:
             payload[key] = deepcopy(config.pop(key))
     payload.update(config)
+    _validate_public_chart_payload_rules(payload)
     return payload
 
 
@@ -13089,7 +14060,9 @@ def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None =
     return deepcopy(candidates[-1])
 
 
-def _portal_position_payload(position: Any) -> dict[str, Any]:
+def _portal_position_payload(position: Any, *, inferred_mobile_y: int = 0) -> dict[str, Any]:
+    mobile_provided = bool(getattr(position, "mobile_provided", False))
+    mobile_rows = int(getattr(position, "mobile_h", 8)) if mobile_provided else int(getattr(position, "pc_h", 8))
     return {
         "pc": {
             "x": int(getattr(position, "pc_x", 0)),
@@ -13098,10 +14071,10 @@ def _portal_position_payload(position: Any) -> dict[str, Any]:
             "rows": int(getattr(position, "pc_h", 8)),
         },
         "mobile": {
-            "x": int(getattr(position, "mobile_x", 0)),
-            "y": int(getattr(position, "mobile_y", 0)),
-            "cols": int(getattr(position, "mobile_w", 12)),
-            "rows": int(getattr(position, "mobile_h", 8)),
+            "x": int(getattr(position, "mobile_x", 0)) if mobile_provided else 0,
+            "y": int(getattr(position, "mobile_y", 0)) if mobile_provided else int(inferred_mobile_y),
+            "cols": int(getattr(position, "mobile_w", 6)) if mobile_provided else 6,
+            "rows": mobile_rows,
         },
     }
 
@@ -13113,6 +14086,7 @@ def _portal_component_position_public(
     pc_y: int,
     pc_row_height: int,
     mobile_y: int,
+    layout_preset: str | None = None,
 ) -> tuple[dict[str, Any], int, int, int, int]:
     source_name = str(source_type or "").lower()
     if source_name == "filter":
@@ -13131,8 +14105,11 @@ def _portal_component_position_public(
         cols = 12
         rows = 2
     else:
-        cols = 8
-        rows = 4
+        if layout_preset == "dashboard_2col":
+            cols = 12
+        else:
+            cols = 8
+        rows = 6
     if cols == 24:
         if pc_x != 0:
             pc_y += pc_row_height
@@ -13155,6 +14132,73 @@ def _portal_component_position_public(
     return position, next_pc_x, next_pc_y, next_row_height, mobile_y + rows
 
 
+def _empty_portal_layout_diagnostics() -> dict[str, Any]:
+    return {
+        "pc_grid_columns": 24,
+        "mobile_grid_columns": 6,
+        "section_count": 0,
+        "explicit_position_count": 0,
+        "max_pc_right": None,
+        "safe_for_display": True,
+        "warnings": [],
+    }
+
+
+def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: list[dict[str, Any]]) -> 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)
+    diagnostics["explicit_position_count"] = explicit_count
+    pc_positions: list[dict[str, Any]] = []
+    warnings: list[dict[str, Any]] = []
+    for index, component in enumerate(components):
+        if not isinstance(component, dict):
+            continue
+        position = component.get("position") if isinstance(component.get("position"), dict) else {}
+        pc = position.get("pc") if isinstance(position.get("pc"), dict) else {}
+        if pc:
+            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 ""
+        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):
+            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",
+                section_index=index,
+                title=title,
+                pc=deepcopy(pc),
+            ))
+        if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
+            warnings.append(_warning(
+                "PORTAL_MOBILE_POSITION_MISSING",
+                "pc position was provided without mobile position; mobile layout was generated with 6-column grid",
+                section_index=index,
+                title=title,
+            ))
+    max_right = None
+    if pc_positions:
+        max_right = max(int(position.get("x") or 0) + int(position.get("cols") or 0) for position in pc_positions)
+    diagnostics["max_pc_right"] = max_right
+    if len(pc_positions) > 1 and max_right is not None and max_right <= 12:
+        warnings.append(_warning(
+            "PORTAL_LAYOUT_HALF_WIDTH",
+            "portal components only occupy the left half of the 24-column pc grid; this looks like a 12-column layout was used",
+            max_pc_right=max_right,
+            fix_hint="Use x=0/12 with cols=12 for two columns, x=0/8/16 with cols=8 for three columns, or omit position/use layout_preset.",
+        ))
+    diagnostics["warnings"] = warnings
+    diagnostics["safe_for_display"] = not any(item.get("code") in {"PORTAL_LAYOUT_HALF_WIDTH", "PORTAL_CHART_CARD_TOO_SMALL"} for item in warnings)
+    return diagnostics
+
+
+def _portal_layout_warning_items(layout_diagnostics: dict[str, Any]) -> list[dict[str, Any]]:
+    warnings = layout_diagnostics.get("warnings") if isinstance(layout_diagnostics, dict) else None
+    return [deepcopy(item) for item in warnings if isinstance(item, dict)] if isinstance(warnings, list) else []
+
+
 def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: Any) -> dict[str, Any]:
     app_key = str(getattr(ref, "app_key", "") or "").strip()
     chart_id = str(getattr(ref, "chart_id", "") or "").strip()
@@ -16768,13 +17812,38 @@ def _publish_verify_warnings(*, package_attached: bool | None, views_unavailable
     return warnings
 
 
-def _chart_apply_warnings(*, failed_items: list[dict[str, Any]], readback_unavailable: bool, verified: bool) -> list[dict[str, Any]]:
+def _chart_apply_warnings(
+    *,
+    failed_items: list[dict[str, Any]],
+    readback_unavailable: bool,
+    verified: bool,
+    delete_readback_issues: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
     warnings: list[dict[str, Any]] = []
+    delete_readback_issues = delete_readback_issues or []
     if failed_items:
         warnings.append(_warning("CHART_OPERATION_FAILED", "one or more chart operations failed", failed_count=len(failed_items)))
+    still_exists = [item for item in delete_readback_issues if item.get("readback_status") == "still_exists"]
+    unavailable = [item for item in delete_readback_issues if item.get("readback_status") == "unavailable"]
+    if still_exists:
+        warnings.append(
+            _warning(
+                "CHART_DELETE_READBACK_STILL_EXISTS",
+                "one or more delete requests completed, but chart_id readback still found the chart",
+                chart_ids=[item.get("chart_id") for item in still_exists if item.get("chart_id")],
+            )
+        )
+    if unavailable:
+        warnings.append(
+            _warning(
+                "CHART_DELETE_READBACK_UNAVAILABLE",
+                "one or more delete requests completed, but chart_id readback was unavailable",
+                chart_ids=[item.get("chart_id") for item in unavailable if item.get("chart_id")],
+            )
+        )
     if readback_unavailable:
         warnings.append(_warning("CHART_READBACK_PENDING", "chart readback is unavailable after apply"))
-    elif not verified and not failed_items:
+    elif not verified and not failed_items and not delete_readback_issues:
         warnings.append(_warning("CHART_VERIFICATION_INCOMPLETE", "chart apply completed but verification is incomplete"))
     return warnings
 
@@ -17273,6 +18342,56 @@ def _package_resource_signature(items: Any, *, public: bool) -> tuple[tuple[str,
     return tuple(sorted(_flatten_package_resource_identities(items, public=public)))
 
 
+def _publicize_package_list_item(item: dict[str, Any]) -> JSONObject:
+    package_id = _coerce_positive_int(item.get("package_id") or item.get("packageId") or item.get("tag_id") or item.get("tagId"))
+    raw_package_id = package_id if package_id is not None else item.get("package_id") or item.get("packageId") or item.get("tag_id") or item.get("tagId")
+    package_name = str(item.get("package_name") or item.get("packageName") or item.get("tag_name") or item.get("tagName") or "").strip()
+    raw_items = item.get("tagItems") if isinstance(item.get("tagItems"), list) else None
+    item_count = None
+    raw_item_count = item.get("item_count") if "item_count" in item else item.get("itemCount")
+    try:
+        if raw_item_count is not None:
+            coerced_count = int(raw_item_count)
+            if coerced_count >= 0:
+                item_count = coerced_count
+    except (TypeError, ValueError):
+        item_count = None
+    if item_count is None and raw_items is not None:
+        item_count = len(raw_items)
+    tag_icon = item.get("tag_icon") if "tag_icon" in item else item.get("tagIcon")
+    return {
+        "package_id": raw_package_id,
+        "package_name": package_name,
+        "tag_id": raw_package_id,
+        "tag_name": package_name,
+        "publish_status": item.get("publish_status") if "publish_status" in item else item.get("publishStatus"),
+        "being_trial": item.get("being_trial") if "being_trial" in item else item.get("beingTrial"),
+        "item_count": item_count,
+        "item_preview": deepcopy(item.get("item_preview") if "item_preview" in item else item.get("itemPreview") or []),
+        "tag_icon": tag_icon,
+        "icon_config": workspace_icon_config(str(tag_icon).strip() if tag_icon not in (None, "") else None),
+        "permissions": {
+            "can_add_app": item.get("can_add_app") if "can_add_app" in item else item.get("addAppStatus"),
+            "can_edit_app": item.get("can_edit_app") if "can_edit_app" in item else item.get("editAppStatus"),
+            "can_delete_app": item.get("can_delete_app") if "can_delete_app" in item else item.get("delAppStatus"),
+            "can_edit_package": item.get("can_edit_package") if "can_edit_package" in item else item.get("editTagStatus"),
+        },
+    }
+
+
+def _package_list_item_matches_query(item: dict[str, Any], query: str) -> bool:
+    needle = str(query or "").strip().casefold()
+    if not needle:
+        return True
+    haystacks = (
+        item.get("package_id"),
+        item.get("tag_id"),
+        item.get("package_name"),
+        item.get("tag_name"),
+    )
+    return any(needle in str(value or "").casefold() for value in haystacks)
+
+
 def _backend_package_items_from_public_items(items: list[dict[str, Any]], group_ids_by_path: dict[tuple[int, ...], int], *, path: tuple[int, ...] = ()) -> list[JSONObject]:
     backend_items: list[JSONObject] = []
     for index, item in enumerate(items):
@@ -19785,6 +20904,7 @@ def _normalize_portal_list_items(raw_items: Any) -> list[dict[str, Any]]:
                 "dash_key": dash_key or None,
                 "dash_name": dash_name or None,
                 "dash_icon": dash_icon,
+                "icon_config": workspace_icon_config(dash_icon),
                 "package_tag_ids": package_tag_ids,
             }
         )