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

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from copy import deepcopy
 import json
 import time
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -49,6 +50,15 @@ from ..builder_facade.models import (
     ViewsPlanRequest,
 )
 from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
+from ..solution.compiler.icon_utils import (
+    GENERIC_WORKSPACE_ICON_NAMES,
+    WORKSPACE_ICON_COLORS,
+    WORKSPACE_ICON_NAMES,
+    normalize_workspace_icon_name,
+    validate_workspace_icon_choice,
+    workspace_icon_catalog_payload,
+    workspace_icon_config,
+)
 from .app_tools import AppTools
 from .base import ToolBase, tool_cn_name
 from .custom_button_tools import CustomButtonTools
@@ -70,6 +80,19 @@ def _normalize_builder_view_key(value: str) -> str:
 
 
 PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
+BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
+BUILDER_APPLY_TOOL_NAMES = {
+    "package_apply",
+    "app_schema_apply",
+    "app_layout_apply",
+    "app_flow_apply",
+    "app_views_apply",
+    "app_custom_buttons_apply",
+    "app_associated_resources_apply",
+    "app_charts_apply",
+    "portal_apply",
+    "app_publish_verify",
+}
 
 
 class AiBuilderTools(ToolBase):
@@ -104,6 +127,14 @@ class AiBuilderTools(ToolBase):
         def builder_tool_contract(tool_name: str = "") -> JSONObject:
             return self.builder_tool_contract(tool_name=tool_name)
 
+        @mcp.tool()
+        def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.workspace_icon_catalog_get(profile=profile)
+
+        @mcp.tool()
+        def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", query: str = "") -> JSONObject:
+            return self.package_list(profile=profile, trial_status=trial_status, query=query)
+
         @mcp.tool()
         def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> JSONObject:
             return self.package_get(profile=profile, package_id=package_id)
@@ -340,7 +371,32 @@ class AiBuilderTools(ToolBase):
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
+            if apps:
+                if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                        fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                    )
+                if package_id is None:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply multi-app mode requires package_id.",
+                        fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+                    )
+                return self.app_schema_apply(
+                    profile=profile,
+                    package_id=package_id,
+                    visibility=visibility,
+                    create_if_missing=create_if_missing,
+                    publish=publish,
+                    apps=apps,
+                    add_fields=[],
+                    update_fields=[],
+                    remove_fields=[],
+                )
             has_app_key = bool((app_key or "").strip())
             has_app_name = bool((app_name or "").strip())
             has_app_title = bool((app_title or "").strip())
@@ -372,6 +428,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
+                apps=[],
             )
 
         @mcp.tool()
@@ -443,9 +500,12 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             dash_key: str = "",
             dash_name: str = "",
+            name: str = "",
             package_id: int | None = None,
             publish: bool = True,
             sections: list[JSONObject] | None = None,
+            pages: list[JSONObject] | None = None,
+            layout_preset: str = "",
             visibility: JSONObject | None = None,
             auth: JSONObject | None = None,
             icon: str | None = None,
@@ -453,10 +513,14 @@ class AiBuilderTools(ToolBase):
             hide_copyright: bool | None = None,
             dash_global_config: JSONObject | None = None,
             config: JSONObject | None = None,
+            payload: JSONObject | None = None,
         ) -> JSONObject:
+            payload = payload if isinstance(payload, dict) else {}
             has_dash_key = bool((dash_key or "").strip())
-            has_dash_name = bool((dash_name or "").strip())
-            has_package_id = package_id is not None
+            effective_dash_name = (dash_name or name or str(payload.get("dash_name") or payload.get("dashName") or payload.get("name") or "")).strip()
+            has_dash_name = bool(effective_dash_name)
+            effective_package_id = package_id if package_id is not None else payload.get("package_id") or payload.get("packageId") or payload.get("package_tag_id")
+            has_package_id = effective_package_id is not None
             if has_dash_key and has_package_id:
                 return _config_failure(
                     tool_name="portal_apply",
@@ -473,9 +537,12 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 dash_key=dash_key,
                 dash_name=dash_name,
+                name=name,
                 package_id=package_id,
                 publish=publish,
                 sections=sections or [],
+                pages=pages or [],
+                layout_preset=layout_preset,
                 visibility=visibility,
                 auth=auth,
                 icon=icon,
@@ -483,6 +550,7 @@ class AiBuilderTools(ToolBase):
                 hide_copyright=hide_copyright,
                 dash_global_config=dash_global_config,
                 config=config or {},
+                payload=payload,
             )
 
         @mcp.tool()
@@ -498,14 +566,14 @@ class AiBuilderTools(ToolBase):
             )
 
     @tool_cn_name("分组列表查询")
-    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+    def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         """执行分组与包相关逻辑。"""
-        normalized_args = {"trial_status": trial_status}
+        normalized_args = {"trial_status": trial_status, "query": query}
         return _safe_tool_call(
-            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status, query=query),
             error_code="PACKAGE_LIST_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status, "query": query}},
         )
 
     @tool_cn_name("分组解析")
@@ -550,6 +618,7 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": False,
         }
+        contract = _builder_contract_with_apply_output(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -571,6 +640,27 @@ class AiBuilderTools(ToolBase):
             "contract": contract,
         }
 
+    @tool_cn_name("工作区图标目录")
+    def workspace_icon_catalog_get(self, *, profile: str = DEFAULT_PROFILE) -> JSONObject:
+        """读取应用、应用包、门户可用的工作区图标候选。"""
+        catalog = workspace_icon_catalog_payload()
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "loaded workspace icon catalog",
+            "profile": profile,
+            "icon_names": catalog["icon_names"],
+            "icon_colors": catalog["icon_colors"],
+            "generic_icon_names": catalog["generic_icon_names"],
+            "common_examples": catalog["common_examples"],
+            "notes": catalog["notes"],
+            "count": len(catalog["icon_names"]),
+            "color_count": len(catalog["icon_colors"]),
+            "warnings": [],
+            "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
+        }
+
     @tool_cn_name("分组创建")
     def package_create(
         self,
@@ -647,7 +737,18 @@ class AiBuilderTools(ToolBase):
             try:
                 visibility_patch = VisibilityPatch.model_validate(visibility)
             except ValidationError as exc:
-                return _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc)
+                return _attach_builder_apply_envelope(
+                    "package_apply",
+                    _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc),
+                )
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="package_apply",
+            icon=icon,
+            color=color,
+            creating=package_id is None and bool(create_if_missing),
+        )
+        if icon_failure is not None:
+            return _attach_builder_apply_envelope("package_apply", icon_failure)
         normalized_args = {
             "package_id": package_id,
             **({"package_name": package_name} if str(package_name or "").strip() else {}),
@@ -658,7 +759,7 @@ class AiBuilderTools(ToolBase):
             **({"items": deepcopy(items)} if items is not None else {}),
             "allow_detach": bool(allow_detach),
         }
-        return _publicize_package_fields(_safe_tool_call(
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.package_apply(
                 profile=profile,
                 package_id=package_id,
@@ -674,6 +775,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
+        return _attach_builder_apply_envelope("package_apply", result)
 
     @tool_cn_name("分组更新")
     def package_update(
@@ -914,7 +1016,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = CustomButtonsApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _validation_failure(
+            return _attach_builder_apply_envelope("app_custom_buttons_apply", _validation_failure(
                 str(exc),
                 tool_name="app_custom_buttons_apply",
                 exc=exc,
@@ -936,14 +1038,14 @@ class AiBuilderTools(ToolBase):
                         "view_configs": [],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_custom_buttons_apply", _safe_tool_call(
             lambda: self._facade.app_custom_buttons_apply(profile=profile, request=request),
             error_code="CUSTOM_BUTTONS_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_custom_buttons_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("应用关联资源声明式应用")
     def app_associated_resources_apply(
@@ -969,7 +1071,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = AssociatedResourcesApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _validation_failure(
+            return _attach_builder_apply_envelope("app_associated_resources_apply", _validation_failure(
                 str(exc),
                 tool_name="app_associated_resources_apply",
                 exc=exc,
@@ -996,14 +1098,14 @@ class AiBuilderTools(ToolBase):
                         ],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json", exclude_none=True)
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_associated_resources_apply", _safe_tool_call(
             lambda: self._facade.app_associated_resources_apply(profile=profile, request=request),
             error_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_associated_resources_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("应用按钮列表")
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
@@ -1534,8 +1636,19 @@ class AiBuilderTools(ToolBase):
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        if apps:
+            result = self._app_schema_apply_multi(
+                profile=profile,
+                package_id=package_id,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                apps=apps,
+            )
+            return _attach_builder_apply_envelope("app_schema_apply", result)
         result = self._app_schema_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1551,7 +1664,7 @@ class AiBuilderTools(ToolBase):
             update_fields=update_fields,
             remove_fields=remove_fields,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_schema_apply_once(
@@ -1570,6 +1683,291 @@ class AiBuilderTools(ToolBase):
                 remove_fields=remove_fields,
             ),
         )
+        return _attach_builder_apply_envelope("app_schema_apply", result)
+
+    def _app_schema_apply_multi(
+        self,
+        *,
+        profile: str,
+        package_id: int | None,
+        visibility: JSONObject | None,
+        create_if_missing: bool,
+        publish: bool,
+        apps: list[JSONObject],
+    ) -> JSONObject:
+        normalized_args: JSONObject = {
+            "package_id": package_id,
+            "create_if_missing": create_if_missing,
+            "publish": publish,
+            "apps": deepcopy(apps),
+        }
+        if visibility is not None:
+            normalized_args["visibility"] = deepcopy(visibility)
+        if package_id is None:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                message="app_schema_apply multi-app mode requires package_id.",
+                fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+            )
+        if not apps:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                message="app_schema_apply multi-app mode requires non-empty apps.",
+                fix_hint="Pass apps as a non-empty list of app schema items.",
+            )
+        icon_errors: list[JSONObject] = []
+        seen_new_app_icons: dict[str, int] = {}
+        for index, raw_item in enumerate(apps):
+            if not isinstance(raw_item, dict):
+                continue
+            app_key = str(raw_item.get("app_key") or raw_item.get("appKey") or "").strip()
+            creating_item = not app_key
+            icon_failure = _validate_workspace_icon_for_builder(
+                tool_name="app_schema_apply",
+                icon=str(raw_item.get("icon") or ""),
+                color=str(raw_item.get("color") or ""),
+                creating=creating_item,
+            )
+            if icon_failure is not None:
+                icon_errors.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "error_code": icon_failure.get("error_code"),
+                        "message": icon_failure.get("message"),
+                        "details": icon_failure.get("details"),
+                    }
+                )
+                continue
+            _ok, _error_code, _message, icon_details = validate_workspace_icon_choice(
+                icon=str(raw_item.get("icon") or ""),
+                color=str(raw_item.get("color") or ""),
+                require_explicit=creating_item,
+                disallow_generic=creating_item,
+            )
+            normalized_icon = str(icon_details.get("normalized_icon") or "").strip()
+            if creating_item and normalized_icon:
+                if normalized_icon in seen_new_app_icons:
+                    icon_errors.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "error_code": "DUPLICATE_WORKSPACE_ICON_IN_BATCH",
+                            "message": f"apps[{index}] reuses icon '{normalized_icon}' from apps[{seen_new_app_icons[normalized_icon]}]",
+                            "details": {
+                                "icon": normalized_icon,
+                                "first_index": seen_new_app_icons[normalized_icon],
+                                "duplicate_index": index,
+                                "icon_catalog_command": "qingflow --json builder icon catalog",
+                            },
+                        }
+                    )
+                else:
+                    seen_new_app_icons[normalized_icon] = index
+        if icon_errors:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                error_code="WORKSPACE_ICON_BATCH_INVALID",
+                message="one or more apps have invalid workspace icon configuration",
+                fix_hint="Call `qingflow --json builder icon catalog`, choose a distinct non-template icon and color for each new app, then retry.",
+                details={"icon_errors": icon_errors},
+                allowed_values={
+                    "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+                    "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+                    "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+                },
+            )
+
+        client_key_to_app_key: dict[str, str] = {}
+        created_app_keys: list[str] = []
+        results: list[JSONObject] = []
+        any_write_executed = False
+        client_keys: set[str] = set()
+
+        for index, raw_item in enumerate(apps):
+            if not isinstance(raw_item, dict):
+                results.append(_multi_app_item_failure(index, raw_item, "INVALID_APP_ITEM", "apps[] items must be objects"))
+                continue
+            item = deepcopy(raw_item)
+            client_key = str(item.get("client_key") or item.get("clientKey") or "").strip()
+            app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip()
+            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
+            if client_key:
+                if client_key in client_keys:
+                    results.append(_multi_app_item_failure(index, item, "DUPLICATE_CLIENT_KEY", f"duplicate client_key '{client_key}'"))
+                    continue
+                client_keys.add(client_key)
+            if not app_key and not app_name:
+                results.append(_multi_app_item_failure(index, item, "APP_SELECTOR_REQUIRED", "apps[] requires app_key or app_name"))
+                continue
+
+            initial_add_fields, deferred_add_fields = _split_multi_app_initial_add_fields(item, is_new_app=not bool(app_key))
+            item["_deferred_add_fields"] = deferred_add_fields
+            shell = self._app_schema_apply_once(
+                profile=profile,
+                app_key=app_key,
+                package_id=package_id if not app_key else None,
+                app_name=app_name,
+                app_title="",
+                icon=str(item.get("icon") or ""),
+                color=str(item.get("color") or ""),
+                visibility=item.get("visibility", visibility),
+                create_if_missing=create_if_missing and not app_key,
+                publish=publish and not deferred_add_fields,
+                add_fields=initial_add_fields,
+                update_fields=[],
+                remove_fields=[],
+            )
+            public_shell = _publicize_package_fields(shell)
+            resolved_key = str(public_shell.get("app_key") or "").strip()
+            if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
+                results.append({
+                    "index": index,
+                    "row_number": index + 1,
+                    "client_key": client_key or None,
+                    "app_name": app_name or None,
+                    "app_key": resolved_key or app_key or None,
+                    "status": "failed",
+                    "stage": "resolve_or_create_shell",
+                    "error_code": public_shell.get("error_code") or "APP_SHELL_APPLY_FAILED",
+                    "message": public_shell.get("message") or "app shell resolve/create failed",
+                    "safe_to_retry": not any_write_executed,
+                })
+                continue
+            if bool(public_shell.get("created")):
+                created_app_keys.append(resolved_key)
+            if _schema_apply_result_has_write(public_shell):
+                any_write_executed = True
+            if client_key:
+                client_key_to_app_key[client_key] = resolved_key
+            results.append({
+                "index": index,
+                "row_number": index + 1,
+                "client_key": client_key or None,
+                "app_name": str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip() or None,
+                "app_key": resolved_key,
+                "status": "shell_ready",
+                "created": bool(public_shell.get("created")),
+                "shell_result": public_shell,
+                "shell_field_diff": public_shell.get("field_diff") or {},
+                "shell_field_diff_details": public_shell.get("field_diff_details") or {},
+                "deferred_add_fields": deferred_add_fields,
+            })
+
+        final_items: list[JSONObject] = []
+        for index, raw_item in enumerate(apps):
+            existing = next((item for item in results if item.get("index") == index), None)
+            if not existing or existing.get("status") != "shell_ready":
+                if existing:
+                    final_items.append(existing)
+                continue
+            item = deepcopy(raw_item)
+            app_key = str(existing.get("app_key") or "").strip()
+            try:
+                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key)
+            except ValueError as error:
+                final_items.append({
+                    **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                    "status": "failed",
+                    "stage": "compile_relation_refs",
+                    "error_code": "TARGET_APP_REF_NOT_FOUND",
+                    "message": str(error),
+                    "safe_to_retry": False,
+                })
+                any_write_executed = True
+                continue
+
+            deferred_add_fields = (
+                _compiled_multi_app_deferred_add_fields(compiled_item, existing)
+                if bool(existing.get("created"))
+                else list(compiled_item.get("add_fields") or [])
+            )
+            update_fields = list(compiled_item.get("update_fields") or [])
+            remove_fields = list(compiled_item.get("remove_fields") or [])
+            if bool(existing.get("created")) and not deferred_add_fields and not update_fields and not remove_fields:
+                shell_result = existing.get("shell_result") if isinstance(existing.get("shell_result"), dict) else {}
+                item_status = shell_result.get("status") if shell_result.get("status") in {"success", "partial_success"} else "failed"
+                shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
+                shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
+                final_items.append({
+                    **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                    "status": item_status,
+                    "stage": "schema_apply",
+                    "field_diff": shell_field_diff,
+                    "field_diff_details": shell_field_diff_details,
+                    "shell_field_diff": shell_field_diff,
+                    "shell_field_diff_details": shell_field_diff_details,
+                    "published": bool(shell_result.get("published")),
+                    "verified": bool(shell_result.get("verified")),
+                    "error_code": shell_result.get("error_code"),
+                    "message": shell_result.get("message"),
+                    "safe_to_retry": False,
+                })
+                continue
+
+            field_result = self._app_schema_apply_once(
+                profile=profile,
+                app_key=app_key,
+                package_id=None,
+                app_name=str(compiled_item.get("app_name") or compiled_item.get("appTitle") or compiled_item.get("app_title") or ""),
+                app_title="",
+                icon=str(compiled_item.get("icon") or ""),
+                color=str(compiled_item.get("color") or ""),
+                visibility=compiled_item.get("visibility"),
+                create_if_missing=False,
+                publish=publish,
+                add_fields=deferred_add_fields,
+                update_fields=update_fields,
+                remove_fields=remove_fields,
+            )
+            public_result = _publicize_package_fields(field_result)
+            if _schema_apply_result_has_write(public_result):
+                any_write_executed = True
+            item_status = public_result.get("status") if public_result.get("status") in {"success", "partial_success"} else "failed"
+            shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
+            shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
+            field_diff = _merge_schema_field_diffs(shell_field_diff, public_result.get("field_diff") or {})
+            field_diff_details = _merge_schema_field_diffs(shell_field_diff_details, public_result.get("field_diff_details") or {})
+            final_items.append({
+                **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                "status": item_status,
+                "stage": "schema_apply",
+                "field_diff": field_diff,
+                "field_diff_details": field_diff_details,
+                "shell_field_diff": shell_field_diff,
+                "shell_field_diff_details": shell_field_diff_details,
+                "published": bool(public_result.get("published")),
+                "verified": bool(public_result.get("verified")),
+                "error_code": public_result.get("error_code"),
+                "message": public_result.get("message"),
+                "safe_to_retry": False,
+            })
+
+        succeeded = sum(1 for item in final_items if item.get("status") in {"success", "partial_success"})
+        failed = len(final_items) - succeeded
+        overall_status = "success" if failed == 0 else ("partial_success" if succeeded > 0 or any_write_executed else "failed")
+        return {
+            "status": overall_status,
+            "mode": "multi_app",
+            "total": len(apps),
+            "succeeded": succeeded,
+            "failed": failed,
+            "created_app_keys": created_app_keys,
+            "write_executed": any_write_executed,
+            "safe_to_retry": not any_write_executed,
+            "package_id": package_id,
+            "publish_requested": publish,
+            "apps": final_items,
+            "normalized_args": normalized_args,
+            "verification": {
+                "all_apps_succeeded": failed == 0,
+                "created_app_count": len(created_app_keys),
+            },
+            "request_id": None,
+            "error_code": None if overall_status != "failed" else "MULTI_APP_SCHEMA_APPLY_FAILED",
+            "recoverable": overall_status != "success",
+            "message": "multi-app schema apply completed" if overall_status != "failed" else "multi-app schema apply failed",
+        }
 
     def _app_schema_apply_once(
         self,
@@ -1590,6 +1988,14 @@ class AiBuilderTools(ToolBase):
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="app_schema_apply",
+            icon=icon,
+            color=color,
+            creating=not bool(str(app_key or "").strip()) and bool(create_if_missing),
+        )
+        if icon_failure is not None:
+            return icon_failure
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_schema_plan(
                 profile=profile,
@@ -1685,7 +2091,7 @@ class AiBuilderTools(ToolBase):
             publish=publish,
             sections=sections,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_layout_apply_once(
@@ -1696,6 +2102,7 @@ class AiBuilderTools(ToolBase):
                 sections=sections,
             ),
         )
+        return _attach_builder_apply_envelope("app_layout_apply", result)
 
     def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -1775,7 +2182,7 @@ class AiBuilderTools(ToolBase):
             nodes=nodes,
             transitions=transitions,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_flow_apply_once(
@@ -1787,6 +2194,7 @@ class AiBuilderTools(ToolBase):
                 transitions=transitions,
             ),
         )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
 
     def _app_flow_apply_once(
         self,
@@ -1886,7 +2294,7 @@ class AiBuilderTools(ToolBase):
             patch_views=patch_views or [],
             remove_views=remove_views,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_views_apply_once(
@@ -1898,6 +2306,7 @@ class AiBuilderTools(ToolBase):
                 patch_views=patch_views or [],
             ),
         )
+        return _attach_builder_apply_envelope("app_views_apply", result)
 
     def _app_views_apply_once(
         self,
@@ -2053,7 +2462,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _visibility_validation_failure(
+            return _attach_builder_apply_envelope("app_charts_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="app_charts_apply",
                 exc=exc,
@@ -2067,14 +2476,14 @@ class AiBuilderTools(ToolBase):
                         "reorder_chart_ids": [],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_charts_apply", _safe_tool_call(
             lambda: self._facade.chart_apply(profile=profile, request=request),
             error_code="CHART_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("门户配置应用")
     def portal_apply(
@@ -2083,9 +2492,12 @@ class AiBuilderTools(ToolBase):
         profile: str,
         dash_key: str = "",
         dash_name: str = "",
+        name: str = "",
         package_id: int | None = None,
         publish: bool = True,
         sections: list[JSONObject] | None = None,
+        pages: list[JSONObject] | None = None,
+        layout_preset: str = "",
         visibility: JSONObject | None = None,
         auth: JSONObject | None = None,
         icon: str | None = None,
@@ -2093,27 +2505,46 @@ class AiBuilderTools(ToolBase):
         hide_copyright: bool | None = None,
         dash_global_config: JSONObject | None = None,
         config: JSONObject | None = None,
+        payload: JSONObject | None = None,
     ) -> JSONObject:
         """执行门户相关逻辑。"""
+        request_payload: dict[str, Any] = dict(payload) if isinstance(payload, dict) else {}
+        if dash_key:
+            request_payload["dash_key"] = dash_key
+        if dash_name:
+            request_payload["dash_name"] = dash_name
+        elif name:
+            request_payload["name"] = name
+        if package_id is not None:
+            request_payload["package_id"] = package_id
+        if "publish" not in request_payload or publish is False:
+            request_payload["publish"] = publish
+        if sections:
+            request_payload["sections"] = sections
+        if pages:
+            request_payload["pages"] = pages
+        if layout_preset:
+            request_payload["layout_preset"] = layout_preset
+        if visibility is not None:
+            request_payload["visibility"] = visibility
+        if auth is not None:
+            request_payload["auth"] = auth
+        if icon is not None:
+            request_payload["icon"] = icon
+        if color is not None:
+            request_payload["color"] = color
+        if hide_copyright is not None:
+            request_payload["hide_copyright"] = hide_copyright
+        if dash_global_config is not None:
+            request_payload["dash_global_config"] = dash_global_config
+        if config:
+            merged_config = dict(request_payload.get("config") or {}) if isinstance(request_payload.get("config"), dict) else {}
+            merged_config.update(config)
+            request_payload["config"] = merged_config
         try:
-            request = PortalApplyRequest.model_validate(
-                {
-                    "dash_key": dash_key or None,
-                    "dash_name": dash_name or None,
-                    "package_tag_id": package_id,
-                    "publish": publish,
-                    "sections": sections or [],
-                    "visibility": visibility,
-                    "auth": auth,
-                    "icon": icon,
-                    "color": color,
-                    "hide_copyright": hide_copyright,
-                    "dash_global_config": dash_global_config,
-                    "config": config or {},
-                }
-            )
+            request = PortalApplyRequest.model_validate(request_payload)
         except ValidationError as exc:
-            return _visibility_validation_failure(
+            return _attach_builder_apply_envelope("portal_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="portal_apply",
                 exc=exc,
@@ -2124,6 +2555,7 @@ class AiBuilderTools(ToolBase):
                         "dash_name": dash_name or "业务门户",
                         "package_id": package_id or 1001,
                         "publish": True,
+                        "layout_preset": "dashboard_2col",
                         "sections": [
                             {
                                 "title": "经营概览",
@@ -2133,15 +2565,24 @@ class AiBuilderTools(ToolBase):
                         ],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
         normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
-        return _publicize_package_fields(_safe_tool_call(
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="portal_apply",
+            icon=str(request.icon or ""),
+            color=str(request.color or ""),
+            creating=not bool(str(request.dash_key or "").strip()),
+        )
+        if icon_failure is not None:
+            return _attach_builder_apply_envelope("portal_apply", icon_failure)
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_apply(profile=profile, request=request),
             error_code="PORTAL_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
+        return _attach_builder_apply_envelope("portal_apply", result)
 
     @tool_cn_name("应用发布校验")
     def app_publish_verify(
@@ -2159,7 +2600,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
         ))
-        return _publicize_package_fields(self._retry_after_self_lock_release(
+        result = _publicize_package_fields(self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._facade.app_publish_verify(
@@ -2168,6 +2609,7 @@ class AiBuilderTools(ToolBase):
                 expected_package_tag_id=expected_package_id,
             ),
         ))
+        return _attach_builder_apply_envelope("app_publish_verify", result)
 
     def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -2286,6 +2728,128 @@ class AiBuilderTools(ToolBase):
         return rewritten
 
 
+def _multi_app_item_failure(index: int, item: object, error_code: str, message: str) -> JSONObject:
+    app_name = None
+    client_key = None
+    app_key = None
+    if isinstance(item, dict):
+        app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip() or None
+        client_key = str(item.get("client_key") or item.get("clientKey") or "").strip() or None
+        app_key = str(item.get("app_key") or item.get("appKey") or "").strip() or None
+    return {
+        "index": index,
+        "row_number": index + 1,
+        "client_key": client_key,
+        "app_name": app_name,
+        "app_key": app_key,
+        "status": "failed",
+        "stage": "validate_item",
+        "error_code": error_code,
+        "message": message,
+        "safe_to_retry": True,
+    }
+
+
+def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key: dict[str, str]) -> JSONObject:
+    compiled = deepcopy(item)
+
+    def visit(value):
+        if isinstance(value, list):
+            return [visit(entry) for entry in value]
+        if not isinstance(value, dict):
+            return value
+        payload = {key: visit(entry) for key, entry in value.items()}
+        ref = (
+            payload.pop("target_app_ref", None)
+            or payload.pop("targetAppRef", None)
+            or payload.pop("target_app_client_key", None)
+            or payload.pop("targetAppClientKey", None)
+        )
+        if ref is not None:
+            ref_key = str(ref or "").strip()
+            target_app_key = client_key_to_app_key.get(ref_key)
+            if not target_app_key:
+                raise ValueError(f"target_app_ref '{ref_key}' did not match any apps[].client_key")
+            payload["target_app_key"] = target_app_key
+        return payload
+
+    return visit(compiled)
+
+
+def _split_multi_app_initial_add_fields(item: JSONObject, *, is_new_app: bool) -> tuple[list[JSONObject], list[JSONObject]]:
+    add_fields = _multi_app_list_value(item, "add_fields", "addFields")
+    if not is_new_app:
+        return [], add_fields
+    initial: list[JSONObject] = []
+    deferred: list[JSONObject] = []
+    for field in add_fields:
+        if _contains_multi_app_target_ref(field):
+            deferred.append(field)
+        else:
+            initial.append(field)
+    return initial, deferred
+
+
+def _compiled_multi_app_deferred_add_fields(compiled_item: JSONObject, existing_result: JSONObject) -> list[JSONObject]:
+    deferred = existing_result.get("deferred_add_fields")
+    if not isinstance(deferred, list):
+        return list(compiled_item.get("add_fields") or [])
+    deferred_names = {str(item.get("name") or item.get("title") or item.get("label") or "").strip() for item in deferred if isinstance(item, dict)}
+    if not deferred_names:
+        return []
+    return [
+        deepcopy(field)
+        for field in list(compiled_item.get("add_fields") or [])
+        if isinstance(field, dict)
+        and str(field.get("name") or field.get("title") or field.get("label") or "").strip() in deferred_names
+    ]
+
+
+def _multi_app_list_value(item: JSONObject, *keys: str) -> list[JSONObject]:
+    for key in keys:
+        value = item.get(key)
+        if isinstance(value, list):
+            return [deepcopy(entry) for entry in value if isinstance(entry, dict)]
+    return []
+
+
+def _contains_multi_app_target_ref(value: object) -> bool:
+    if isinstance(value, list):
+        return any(_contains_multi_app_target_ref(item) for item in value)
+    if not isinstance(value, dict):
+        return False
+    for key, entry in value.items():
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
+            return True
+        if _contains_multi_app_target_ref(entry):
+            return True
+    return False
+
+
+def _merge_schema_field_diffs(*diffs: object) -> JSONObject:
+    merged: JSONObject = {"added": [], "updated": [], "removed": []}
+    for diff in diffs:
+        if not isinstance(diff, dict):
+            continue
+        for key in ("added", "updated", "removed"):
+            values = diff.get(key)
+            if not isinstance(values, list):
+                continue
+            for value in values:
+                if value not in merged[key]:
+                    merged[key].append(value)
+    return merged
+
+
+def _schema_apply_result_has_write(result: JSONObject) -> bool:
+    if bool(result.get("created")) or bool(result.get("published")) or bool(result.get("app_base_updated")):
+        return True
+    field_diff = result.get("field_diff")
+    if isinstance(field_diff, dict):
+        return any(bool(field_diff.get(key)) for key in ("added", "updated", "removed"))
+    return False
+
+
 def _validation_failure(
     detail: str,
     *,
@@ -2366,20 +2930,34 @@ def _visibility_validation_failure(
     return result
 
 
-def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObject:
+def _config_failure(
+    *,
+    tool_name: str,
+    message: str,
+    fix_hint: str,
+    error_code: str = "CONFIG_ERROR",
+    details: JSONObject | None = None,
+    allowed_values: JSONObject | None = None,
+) -> JSONObject:
     contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    public_allowed_values = deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {}
+    if allowed_values:
+        public_allowed_values.update(deepcopy(allowed_values))
+    public_details: JSONObject = {
+        "fix_hint": fix_hint,
+        "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+    }
+    if details:
+        public_details.update(deepcopy(details))
     return {
         "status": "failed",
-        "error_code": "CONFIG_ERROR",
+        "error_code": error_code,
         "recoverable": True,
         "message": message,
         "normalized_args": {},
         "missing_fields": [],
-        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
-        "details": {
-            "fix_hint": fix_hint,
-            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
-        },
+        "allowed_values": public_allowed_values,
+        "details": public_details,
         "suggested_next_call": None,
         "request_id": None,
         "backend_code": None,
@@ -2389,6 +2967,52 @@ def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObjec
     }
 
 
+def _workspace_icon_config_failure(
+    *,
+    tool_name: str,
+    error_code: str,
+    message: str,
+    details: JSONObject,
+) -> JSONObject:
+    return _config_failure(
+        tool_name=tool_name,
+        error_code=error_code,
+        message=message,
+        fix_hint="Call `qingflow --json builder icon catalog`, choose an explicit non-template icon and color, then retry.",
+        details=details,
+        allowed_values={
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
+    )
+
+
+def _validate_workspace_icon_for_builder(
+    *,
+    tool_name: str,
+    icon: str | None,
+    color: str | None,
+    creating: bool,
+) -> JSONObject | None:
+    if not creating and not (str(icon or "").strip() or str(color or "").strip()):
+        return None
+    ok, error_code, message, details = validate_workspace_icon_choice(
+        icon=icon,
+        color=color,
+        require_explicit=creating,
+        disallow_generic=creating,
+    )
+    if ok:
+        return None
+    return _workspace_icon_config_failure(
+        tool_name=tool_name,
+        error_code=error_code or "WORKSPACE_ICON_INVALID",
+        message=message or "invalid workspace icon configuration",
+        details=details,
+    )
+
+
 def _safe_tool_call(
     call,
     *,
@@ -2437,6 +3061,7 @@ def _publicize_package_fields(value):
         "tag_ids_after": "package_ids_after",
         "tag_name": "package_name",
         "tag_icon": "icon",
+        "iconConfig": "icon_config",
         "package_tag_id": "package_id",
         "package_tag_ids": "package_ids",
         "expected_package_tag_id": "expected_package_id",
@@ -2448,6 +3073,742 @@ def _publicize_package_fields(value):
     return public
 
 
+def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) -> JSONObject:
+    public = deepcopy(contract)
+    if tool_name not in BUILDER_APPLY_TOOL_NAMES:
+        return public
+    notes = public.setdefault("execution_notes", [])
+    if isinstance(notes, list):
+        note = "apply/write output includes schema_version, operation, summary, and resources[]; UI and agents should read resources[].id/key/name first and use legacy fields only for compatibility/debugging"
+        if note not in notes:
+            notes.append(note)
+    public["output_contract"] = {
+        "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
+        "preferred_ui_fields": ["operation", "summary", "resources"],
+        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
+        "legacy_fields_preserved": True,
+    }
+    return public
+
+
+def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
+    if not isinstance(payload, dict):
+        return payload
+    resources = _builder_apply_resources(tool_name, payload)
+    payload["schema_version"] = BUILDER_APPLY_SCHEMA_VERSION
+    payload["operation"] = tool_name
+    payload["resources"] = resources
+    payload["summary"] = _builder_apply_summary(payload, resources)
+    return payload
+
+
+def _builder_apply_summary(payload: JSONObject, resources: list[JSONObject]) -> JSONObject:
+    status = str(payload.get("status") or "")
+    failed = sum(1 for item in resources if str(item.get("status") or "") == "failed")
+    created = sum(1 for item in resources if str(item.get("operation") or "") == "created" and str(item.get("status") or "") != "failed")
+    removed = sum(1 for item in resources if str(item.get("operation") or "") == "removed" and str(item.get("status") or "") != "failed")
+    updated = sum(
+        1
+        for item in resources
+        if str(item.get("status") or "") != "failed"
+        and str(item.get("operation") or "") in {"updated", "layout_updated", "workflow_updated", "verified", "published"}
+    )
+    published_value = payload.get("published")
+    if published_value is None:
+        publish_requested = payload.get("publish_requested")
+        published_value = bool(publish_requested) and status in {"success", "partial_success"}
+    verified_value = payload.get("verified")
+    if verified_value is None:
+        verification = payload.get("verification")
+        verified_value = status == "success" and failed == 0 and _builder_verification_truthy(verification)
+    summary: JSONObject = {
+        "total": len(resources),
+        "created": created,
+        "updated": updated,
+        "removed": removed,
+        "failed": failed,
+        "published": bool(published_value),
+        "verified": bool(verified_value),
+    }
+    if "write_executed" in payload:
+        summary["write_executed"] = bool(payload.get("write_executed"))
+    if "safe_to_retry" in payload:
+        summary["safe_to_retry"] = bool(payload.get("safe_to_retry"))
+    return summary
+
+
+def _builder_verification_truthy(value: object) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, dict):
+        booleans = [item for item in value.values() if isinstance(item, bool)]
+        return all(booleans) if booleans else True
+    return True
+
+
+def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONObject]:
+    resources: list[JSONObject]
+    if tool_name == "package_apply":
+        resources = _builder_package_resources(payload)
+    elif tool_name == "app_schema_apply":
+        resources = _builder_schema_resources(payload)
+    elif tool_name == "app_layout_apply":
+        resources = [_builder_app_resource(payload, operation="layout_updated")]
+    elif tool_name == "app_flow_apply":
+        resources = [_builder_app_resource(payload, operation="workflow_updated")]
+    elif tool_name == "app_views_apply":
+        resources = _builder_view_resources(payload)
+    elif tool_name == "app_charts_apply":
+        resources = _builder_chart_resources(payload)
+    elif tool_name == "portal_apply":
+        resources = _builder_portal_resources(payload)
+    elif tool_name == "app_custom_buttons_apply":
+        resources = _builder_button_resources(payload)
+    elif tool_name == "app_associated_resources_apply":
+        resources = _builder_associated_resource_resources(payload)
+    elif tool_name == "app_publish_verify":
+        resources = [_builder_app_resource(payload, operation="verified")]
+    else:
+        resources = []
+    if not resources and _builder_status(payload, "") == "failed" and _builder_apply_tool_is_app_scoped(tool_name):
+        app_key = _builder_payload_app_key(payload)
+        if app_key not in (None, ""):
+            resources = [_builder_app_resource(payload, operation="failed")]
+    return resources
+
+
+def _builder_apply_tool_is_app_scoped(tool_name: str) -> bool:
+    return tool_name in {
+        "app_schema_apply",
+        "app_layout_apply",
+        "app_flow_apply",
+        "app_views_apply",
+        "app_custom_buttons_apply",
+        "app_associated_resources_apply",
+        "app_charts_apply",
+        "app_publish_verify",
+    }
+
+
+def _builder_status(payload_or_item: JSONObject, fallback: str = "success") -> str:
+    status = str(payload_or_item.get("status") or fallback or "success")
+    return status
+
+
+def _builder_operation(value: object, fallback: str = "updated") -> str:
+    raw = str(value or fallback or "updated").strip()
+    mapping = {
+        "create": "created",
+        "created": "created",
+        "add": "created",
+        "update": "updated",
+        "updated": "updated",
+        "patch": "updated",
+        "remove": "removed",
+        "removed": "removed",
+        "delete": "removed",
+        "deleted": "removed",
+        "unchanged": "unchanged",
+        "failed": "failed",
+    }
+    return mapping.get(raw, raw)
+
+
+def _builder_parent(resource_type: str, *, key: object = None, name: object = None, id_value: object = None) -> JSONObject:
+    return {
+        "resource_type": resource_type,
+        "id": id_value,
+        "key": str(key) if key not in (None, "") else None,
+        "name": str(name) if name not in (None, "") else None,
+    }
+
+
+def _builder_app_parent(payload: JSONObject) -> JSONObject | None:
+    app_key = payload.get("app_key") or payload.get("appKey")
+    app_name = payload.get("app_name_after") or payload.get("app_name") or payload.get("appTitle") or payload.get("app_title")
+    if app_key in (None, "") and app_name in (None, ""):
+        return None
+    return _builder_parent("app", key=app_key, name=app_name)
+
+
+def _builder_icon_config(raw_icon: object = None, *, icon: object = None, color: object = None) -> JSONObject | None:
+    raw = str(raw_icon).strip() if raw_icon not in (None, "") else ""
+    explicit_icon = str(icon).strip() if icon not in (None, "") else ""
+    explicit_color = str(color).strip() if color not in (None, "") else ""
+    if raw:
+        if raw.startswith("{") and raw.endswith("}"):
+            config = workspace_icon_config(raw)
+        else:
+            config = {
+                "icon_name": normalize_workspace_icon_name(raw),
+                "icon_color": explicit_color or None,
+                "icon_text": None,
+                "raw": raw,
+            }
+        if any(config.get(key) for key in ("icon_name", "icon_color", "icon_text", "raw")):
+            return config
+    if explicit_icon or explicit_color:
+        return {
+            "icon_name": normalize_workspace_icon_name(explicit_icon) if explicit_icon else None,
+            "icon_color": explicit_color or None,
+            "icon_text": None,
+            "raw": None,
+        }
+    return None
+
+
+def _builder_container_icon_config(container: object, *, raw_keys: tuple[str, ...], icon_keys: tuple[str, ...] = ("icon",), color_keys: tuple[str, ...] = ("color",)) -> JSONObject | None:
+    if not isinstance(container, dict):
+        return None
+    raw_icon = next((container.get(key) for key in raw_keys if container.get(key) not in (None, "")), None)
+    icon = next((container.get(key) for key in icon_keys if container.get(key) not in (None, "")), None)
+    color = next((container.get(key) for key in color_keys if container.get(key) not in (None, "")), None)
+    return _builder_icon_config(raw_icon, icon=icon, color=color)
+
+
+def _builder_resource(
+    *,
+    resource_type: str,
+    operation: str,
+    status: str,
+    id_value: object = None,
+    key: object = None,
+    name: object = None,
+    ids: JSONObject | None = None,
+    parent: JSONObject | None = None,
+    icon_config: JSONObject | None = None,
+    error_code: object = None,
+    message: object = None,
+) -> JSONObject:
+    resource = {
+        "resource_type": resource_type,
+        "operation": operation,
+        "status": status,
+        "id": id_value,
+        "key": str(key) if key not in (None, "") else None,
+        "name": str(name) if name not in (None, "") else None,
+        "ids": ids or {},
+        "parent": parent,
+        "error_code": str(error_code) if error_code not in (None, "") else None,
+        "message": str(message) if message not in (None, "") else None,
+    }
+    if icon_config:
+        resource["icon_config"] = icon_config
+    return resource
+
+
+def _builder_app_resource(payload: JSONObject, *, operation: str) -> JSONObject:
+    status = _builder_status(payload, "success")
+    if status == "failed":
+        operation = "failed"
+    app_key = _builder_payload_app_key(payload)
+    app_name = _builder_payload_app_name(payload)
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("app_icon", "appIcon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("app_icon", "appIcon", "icon"))
+    )
+    return _builder_resource(
+        resource_type="app",
+        operation=operation,
+        status=status,
+        key=app_key,
+        name=app_name,
+        ids={"app_key": app_key} if app_key not in (None, "") else {},
+        icon_config=icon_config,
+        error_code=payload.get("error_code"),
+        message=payload.get("message") if status == "failed" else None,
+    )
+
+
+def _builder_payload_app_key(payload: JSONObject) -> object:
+    return _builder_payload_identity_value(payload, ("app_key", "appKey"))
+
+
+def _builder_payload_app_name(payload: JSONObject) -> object:
+    return _builder_payload_identity_value(payload, ("app_name_after", "app_name", "appName", "appTitle", "app_title", "name", "title"))
+
+
+def _builder_payload_identity_value(payload: JSONObject, keys: tuple[str, ...]) -> object:
+    for key in keys:
+        value = payload.get(key)
+        if value not in (None, ""):
+            return value
+    for container_key in ("normalized_args", "canonical_arguments"):
+        container = payload.get(container_key)
+        if isinstance(container, dict):
+            for key in keys:
+                value = container.get(key)
+                if value not in (None, ""):
+                    return value
+    details = payload.get("details")
+    if isinstance(details, dict):
+        for container_key in ("normalized_args", "canonical_arguments"):
+            container = details.get(container_key)
+            if isinstance(container, dict):
+                for key in keys:
+                    value = container.get(key)
+                    if value not in (None, ""):
+                        return value
+    return None
+
+
+def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
+    package_id = payload.get("package_id") or payload.get("id")
+    package_name = payload.get("package_name") or payload.get("name")
+    status = _builder_status(payload, "success")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("icon", "tagIcon", "tag_icon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "tagIcon", "tag_icon"))
+    )
+    return [
+        _builder_resource(
+            resource_type="package",
+            operation=operation,
+            status=status,
+            id_value=package_id,
+            key=str(package_id) if package_id not in (None, "") else None,
+            name=package_name,
+            ids={"package_id": package_id} if package_id not in (None, "") else {},
+            icon_config=icon_config,
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+
+
+def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
+    if payload.get("mode") == "multi_app" and isinstance(payload.get("apps"), list):
+        resources: list[JSONObject] = []
+        package_id = payload.get("package_id")
+        package_parent = _builder_parent("package", id_value=package_id, key=package_id) if package_id not in (None, "") else None
+        for item in payload.get("apps") or []:
+            if not isinstance(item, dict):
+                continue
+            status = _builder_status(item, "success")
+            operation = "failed" if status == "failed" else ("created" if bool(item.get("created")) else "updated")
+            parent = _builder_parent("app", key=item.get("app_key"), name=item.get("app_name"))
+            icon_config = (
+                _builder_container_icon_config(item, raw_keys=("app_icon", "appIcon", "icon"))
+                or _builder_container_icon_config(item.get("shell_result"), raw_keys=("app_icon", "appIcon", "icon"))
+            )
+            resources.append(
+                _builder_resource(
+                    resource_type="app",
+                    operation=operation,
+                    status=status,
+                    key=item.get("app_key"),
+                    name=item.get("app_name"),
+                    ids={
+                        **({"app_key": item.get("app_key")} if item.get("app_key") else {}),
+                        **({"package_id": package_id} if package_id not in (None, "") else {}),
+                    },
+                    parent=package_parent,
+                    icon_config=icon_config,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+            resources.extend(_builder_field_resources(item.get("field_diff_details") or item.get("field_diff"), parent=parent))
+        return resources
+
+    status = _builder_status(payload, "success")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    app_key = payload.get("app_key")
+    app_name = payload.get("app_name_after") or payload.get("app_name")
+    parent = _builder_parent("app", key=app_key, name=app_name)
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("app_icon", "appIcon", "icon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "app_icon", "appIcon"))
+    )
+    resources = [
+        _builder_resource(
+            resource_type="app",
+            operation=operation,
+            status=status,
+            key=app_key,
+            name=app_name,
+            ids={"app_key": app_key} if app_key else {},
+            icon_config=icon_config,
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+    resources.extend(_builder_field_resources(payload.get("field_diff_details") or payload.get("field_diff"), parent=parent))
+    return resources
+
+
+def _builder_field_resources(field_diff: object, *, parent: JSONObject | None) -> list[JSONObject]:
+    if not isinstance(field_diff, dict):
+        return []
+    resources: list[JSONObject] = []
+    for key, operation in (("added", "created"), ("updated", "updated"), ("removed", "removed")):
+        for field in field_diff.get(key) or []:
+            if isinstance(field, dict):
+                name = field.get("name") or field.get("title") or field.get("field_name") or field.get("queTitle")
+                field_id = field.get("field_id") or field.get("queId")
+                que_id = field.get("que_id") or field.get("queId")
+            else:
+                name = field
+                field_id = None
+                que_id = None
+            resource_id = que_id if que_id not in (None, "") else field_id
+            resources.append(
+                _builder_resource(
+                    resource_type="field",
+                    operation=operation,
+                    status="success",
+                    id_value=resource_id,
+                    key=field_id if field_id not in (None, "") else name,
+                    name=name,
+                    ids={
+                        **({"field_id": field_id} if field_id not in (None, "") else {}),
+                        **({"que_id": que_id} if que_id not in (None, "") else {}),
+                        **({"app_key": parent.get("key")} if isinstance(parent, dict) and parent.get("key") else {}),
+                    },
+                    parent=parent,
+                )
+            )
+    return resources
+
+
+def _builder_view_resources(payload: JSONObject) -> list[JSONObject]:
+    diff = payload.get("views_diff") if isinstance(payload.get("views_diff"), dict) else {}
+    verification_by_name = _builder_view_verification_by_name(payload)
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (("created", "created"), ("updated", "updated"), ("removed", "removed")):
+        for item in diff.get(key) or []:
+            name, view_key, status, error_code, message = _builder_view_identity(item, verification_by_name)
+            resources.append(
+                _builder_resource(
+                    resource_type="view",
+                    operation=operation,
+                    status=status,
+                    key=view_key,
+                    name=name,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=error_code,
+                    message=message,
+                )
+            )
+    for item in diff.get("failed") or []:
+        name, view_key, _status, error_code, message = _builder_view_identity(item, verification_by_name)
+        resources.append(
+            _builder_resource(
+                resource_type="view",
+                operation="failed",
+                status="failed",
+                key=view_key,
+                name=name,
+                ids={
+                    **({"view_key": view_key} if view_key else {}),
+                    **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                },
+                parent=parent,
+                error_code=error_code,
+                message=message,
+            )
+        )
+    return resources
+
+
+def _builder_view_verification_by_name(payload: JSONObject) -> dict[str, JSONObject]:
+    verification = payload.get("verification")
+    by_view = verification.get("by_view") if isinstance(verification, dict) else None
+    result: dict[str, JSONObject] = {}
+    if isinstance(by_view, list):
+        for item in by_view:
+            if isinstance(item, dict):
+                name = str(item.get("name") or "").strip()
+                if name:
+                    result[name] = item
+    return result
+
+
+def _builder_view_identity(item: object, verification_by_name: dict[str, JSONObject]) -> tuple[str | None, str | None, str, object, object]:
+    verification: JSONObject | None = None
+    if isinstance(item, dict):
+        name = item.get("name") or item.get("view_name") or item.get("viewName")
+        view_key = item.get("view_key") or item.get("viewKey")
+        status = str(item.get("status") or "success")
+        error_code = item.get("error_code")
+        message = item.get("message")
+    else:
+        name = str(item) if item not in (None, "") else None
+        view_key = None
+        status = "success"
+        error_code = None
+        message = None
+    if name and not view_key:
+        verification = verification_by_name.get(str(name))
+        if isinstance(verification, dict):
+            view_key = verification.get("view_key") or verification.get("viewKey")
+            if not view_key:
+                matching = verification.get("matching_view_keys")
+                if isinstance(matching, list) and matching:
+                    view_key = matching[0]
+    if name and verification is None:
+        verification = verification_by_name.get(str(name))
+    if isinstance(verification, dict):
+        verification_status = str(verification.get("status") or "").strip()
+        if verification_status in {"removed", "readback_pending"}:
+            status = "readback_pending"
+            if verification_status == "removed":
+                status = "removed"
+        error_code = error_code or verification.get("error_code")
+        message = message or verification.get("message")
+    return (
+        str(name) if name not in (None, "") else None,
+        str(view_key) if view_key not in (None, "") else None,
+        status,
+        error_code,
+        message,
+    )
+
+
+def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for item in payload.get("chart_results") or []:
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status") or "success")
+        operation = _builder_operation(item.get("operation") or status, fallback="updated")
+        if status == "failed":
+            operation = "failed"
+        resource_status = "failed" if status == "failed" else ("readback_pending" if status == "readback_pending" else "success")
+        chart_id = item.get("chart_id") or item.get("chartId")
+        chart_key = item.get("chart_key") or item.get("chartKey")
+        resources.append(
+            _builder_resource(
+                resource_type="chart",
+                operation=operation,
+                status=resource_status,
+                id_value=chart_id,
+                key=chart_key or chart_id,
+                name=item.get("name") or item.get("chart_name") or item.get("chartName"),
+                ids={
+                    **({"chart_id": chart_id} if chart_id not in (None, "") else {}),
+                    **({"chart_key": chart_key} if chart_key else {}),
+                    **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    **({"chart_type": item.get("chart_type")} if item.get("chart_type") else {}),
+                },
+                parent=parent,
+                error_code=item.get("error_code"),
+                message=item.get("message") if status in {"failed", "readback_pending"} else None,
+            )
+        )
+    return resources
+
+
+def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
+    status = _builder_status(payload, "success")
+    draft_result = payload.get("draft_result") if isinstance(payload.get("draft_result"), dict) else {}
+    live_result = payload.get("live_result") if isinstance(payload.get("live_result"), dict) else {}
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    dash_key = (
+        payload.get("dash_key")
+        or payload.get("dashKey")
+        or draft_result.get("dashKey")
+        or draft_result.get("dash_key")
+        or live_result.get("dashKey")
+        or live_result.get("dash_key")
+    )
+    dash_name = (
+        payload.get("dash_name")
+        or payload.get("dashName")
+        or payload.get("name")
+        or draft_result.get("dashName")
+        or draft_result.get("dash_name")
+        or draft_result.get("name")
+        or live_result.get("dashName")
+        or live_result.get("dash_name")
+        or live_result.get("name")
+        or normalized_args.get("dash_name")
+        or normalized_args.get("dashName")
+    )
+    package_id = payload.get("package_id") or normalized_args.get("package_id") or normalized_args.get("package_tag_id")
+    if package_id in (None, "") and isinstance(draft_result.get("tags"), list) and draft_result.get("tags"):
+        first_tag = draft_result.get("tags")[0]
+        if isinstance(first_tag, dict):
+            package_id = first_tag.get("tagId") or first_tag.get("tag_id") or first_tag.get("id")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    parent = None
+    if package_id:
+        parent = _builder_parent("package", id_value=package_id, key=package_id)
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("dash_icon", "dashIcon", "icon"))
+        or _builder_container_icon_config(draft_result, raw_keys=("dashIcon", "dash_icon", "icon"))
+        or _builder_container_icon_config(live_result, raw_keys=("dashIcon", "dash_icon", "icon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "dash_icon", "dashIcon"))
+    )
+    return [
+        _builder_resource(
+            resource_type="portal",
+            operation=operation,
+            status=status,
+            key=dash_key,
+            name=dash_name,
+            ids={
+                **({"dash_key": dash_key} if dash_key else {}),
+                **({"package_id": package_id} if package_id else {}),
+            },
+            parent=parent,
+            icon_config=icon_config,
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+
+
+def _builder_button_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (("created", "created"), ("updated", "updated"), ("removed", "removed"), ("failed", "failed")):
+        for item in payload.get(key) or []:
+            if not isinstance(item, dict):
+                continue
+            status = "failed" if operation == "failed" or item.get("status") == "failed" else str(item.get("status") or "success")
+            button_id = item.get("button_id") or item.get("buttonId")
+            resources.append(
+                _builder_resource(
+                    resource_type="button",
+                    operation=operation if operation != "failed" else "failed",
+                    status=status,
+                    id_value=button_id,
+                    key=button_id,
+                    name=item.get("button_text") or item.get("buttonText"),
+                    ids={
+                        **({"button_id": button_id} if button_id not in (None, "") else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
+                )
+            )
+    for item in payload.get("view_configs") or []:
+        if isinstance(item, dict):
+            status = str(item.get("status") or "success")
+            view_key = item.get("view_key") or item.get("viewKey")
+            resources.append(
+                _builder_resource(
+                    resource_type="button_binding",
+                    operation="updated" if status != "failed" else "failed",
+                    status=status,
+                    key=view_key,
+                    name=item.get("view_name") or item.get("viewName") or view_key,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
+                )
+            )
+    return resources
+
+
+def _builder_associated_resource_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    readback_by_id = _builder_associated_resource_readback_by_id(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (
+        ("created", "created"),
+        ("updated", "updated"),
+        ("unchanged", "unchanged"),
+        ("removed", "removed"),
+        ("failed", "failed"),
+    ):
+        for item in payload.get(key) or []:
+            if not isinstance(item, dict):
+                continue
+            status = "failed" if operation == "failed" or item.get("status") == "failed" else str(item.get("status") or "success")
+            associated_item_id = item.get("associated_item_id") or item.get("associatedItemId")
+            readback = readback_by_id.get(str(associated_item_id)) if associated_item_id not in (None, "") else None
+            view_key = item.get("view_key") or item.get("viewKey") or (readback or {}).get("view_key") or (readback or {}).get("viewKey")
+            chart_key = item.get("chart_key") or item.get("chartKey") or (readback or {}).get("chart_key") or (readback or {}).get("chartKey")
+            target_app_key = item.get("target_app_key") or (readback or {}).get("target_app_key")
+            name = item.get("name") or item.get("resource_name") or (readback or {}).get("name") or view_key or chart_key
+            resources.append(
+                _builder_resource(
+                    resource_type="associated_resource",
+                    operation=operation if operation != "failed" else "failed",
+                    status=status,
+                    id_value=associated_item_id,
+                    key=view_key or chart_key or associated_item_id,
+                    name=name,
+                    ids={
+                        **({"associated_item_id": associated_item_id} if associated_item_id not in (None, "") else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                        **({"target_app_key": target_app_key} if target_app_key else {}),
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"chart_key": chart_key} if chart_key else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
+                )
+            )
+    for item in payload.get("view_configs") or []:
+        if isinstance(item, dict):
+            status = str(item.get("status") or "success")
+            view_key = item.get("view_key") or item.get("viewKey")
+            resources.append(
+                _builder_resource(
+                    resource_type="associated_resource_binding",
+                    operation="updated" if status != "failed" else "failed",
+                    status=status,
+                    key=view_key,
+                    name=item.get("view_name") or item.get("viewName") or view_key,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+    return resources
+
+
+def _builder_associated_resource_readback_by_id(payload: JSONObject) -> dict[str, JSONObject]:
+    result: dict[str, JSONObject] = {}
+
+    def collect(items: object) -> None:
+        if not isinstance(items, list):
+            return
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            associated_item_id = item.get("associated_item_id") or item.get("associatedItemId")
+            if associated_item_id in (None, ""):
+                continue
+            result[str(associated_item_id)] = item
+
+    collect(payload.get("associated_resources"))
+    for config in payload.get("view_configs") or []:
+        if not isinstance(config, dict):
+            continue
+        for key in ("actual", "expected"):
+            value = config.get(key)
+            if isinstance(value, dict):
+                collect(value.get("items"))
+    return result
+
+
 def _coerce_api_error(error: Exception) -> QingflowApiError:
     if isinstance(error, QingflowApiError):
         return error
@@ -2596,6 +3957,40 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "tool_name": "chart_get",
         },
     },
+    "workspace_icon_catalog_get": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {
+            "icon": list(WORKSPACE_ICON_NAMES),
+            "color": list(WORKSPACE_ICON_COLORS),
+            "generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
+        "execution_notes": [
+            "read this before creating app packages, apps, or portals when choosing supported workspace icons",
+            "the CLI validates icon/color candidates but does not infer business defaults from resource names",
+            "new app/package/portal creation requires explicit non-template icon + color",
+        ],
+        "minimal_example": {
+            "profile": "default",
+        },
+    },
+    "package_list": {
+        "allowed_keys": ["trial_status", "query"],
+        "aliases": {"trialStatus": "trial_status", "keyword": "query"},
+        "allowed_values": {"trial_status": ["all"]},
+        "execution_notes": [
+            "lists app packages visible to the current builder profile by calling backend GET /tag?trialStatus=...",
+            "query is applied locally to package_id/tag_id/package_name/tag_name after /tag returns",
+            "does not fall back to app list because app list cannot represent empty packages, duplicate package names, or package-level permissions",
+            "returns package_id/package_name plus compatible tag_id/tag_name; use package_get for package detail before editing",
+            "permission failures are returned as PACKAGE_LIST_FAILED with backend transport details",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "trial_status": "all",
+            "query": "产品研发",
+        },
+    },
     "package_get": {
         "allowed_keys": ["package_id"],
         "aliases": {"packageId": "package_id"},
@@ -2620,9 +4015,17 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "iconColor": "color",
             "allowDetach": "allow_detach",
         },
-        "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        "allowed_values": {
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
+            "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
+            "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
+            "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
             "package_id maps internally to backend tagId; do not use tag_id in public calls",
             "items is a full package layout tree; omitting existing app/portal items is blocked unless allow_detach=true",
@@ -2646,7 +4049,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "package_name": "项目管理",
             "create_if_missing": True,
-            "icon": "files-folder",
+            "icon": "briefcase",
             "color": "azure",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
         },
@@ -2759,7 +4162,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "use this read-only tool before button writes when an agent needs a supported icon or color choice",
-            "current frontend only supports template icons and template colors from this catalog",
+            "current frontend only supports button icons and button colors from this catalog",
             "text/icon color is unified through text_color; there is no separate icon_color",
         ],
         "minimal_example": {
@@ -2861,6 +4264,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "default placements are header and detail; header maps to frontend top buttons",
             "placement=list configures backend INSIDE row/list buttons; header maps to TOP and detail maps to DETAIL",
             "remove_buttons supports button_id or exact unique button_text",
+            "after a remove_buttons DELETE is sent, the tool verifies deletion by single button_id readback; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
+            "if a removed button returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "all operations share one edit context and publish after at least one write succeeds; there is no draft-only mode for this tool",
             "background_color and text_color cannot both be white",
         ],
@@ -3003,6 +4408,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "match_mappings.source_field accepts source schema fields plus system fields 数据ID(-17) and 编号(0); match_mappings compiles to backend matchRules",
             "do not write raw match_rules unless preserving a legacy backend config; match_mappings and match_rules are mutually exclusive",
             "client_key only lets a view_config reference a resource created earlier in the same apply call through associated_item_refs; it is not persisted and cannot deduplicate later apply calls",
+            "remove_associated_item_ids sends DELETE and verifies deletion with one associated-resource pool readback because the backend has no confirmed single-item GET; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
+            "if an associated resource delete returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "this tool publishes after at least one write succeeds; there is no draft-only mode",
             "visible=false hides the associated-resource area without clearing previous selected ids; visible=true with limit_type=all shows the whole app-level pool",
         ],
@@ -3069,17 +4476,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.type": [member.value for member in PublicFieldType],
             "field.relation_mode": [member.value for member in PublicRelationMode],
             "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
             "create mode may set visibility for the new app; edit mode may update visibility on an existing app",
+            "create mode should include explicit non-template icon + color; apply mode enforces this before writing",
+            "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_id": 1001,
-            "icon": "template",
+            "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
@@ -3105,11 +4517,40 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_apply": {
-        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": [
+            "app_key",
+            "package_id",
+            "app_name",
+            "icon",
+            "color",
+            "visibility",
+            "create_if_missing",
+            "publish",
+            "add_fields",
+            "update_fields",
+            "remove_fields",
+            "apps",
+            "apps[].client_key",
+            "apps[].app_key",
+            "apps[].app_name",
+            "apps[].icon",
+            "apps[].color",
+            "apps[].visibility",
+            "apps[].add_fields",
+            "apps[].update_fields",
+            "apps[].remove_fields",
+            "apps[].add_fields[].target_app_ref",
+        ],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
             "packageId": "package_id",
+            "apps[].clientKey": "apps[].client_key",
+            "apps[].appKey": "apps[].app_key",
+            "apps[].appName": "apps[].app_name",
+            "apps[].appTitle": "apps[].app_name",
+            "field.targetAppRef": "field.target_app_ref",
+            "field.targetAppClientKey": "field.target_app_ref",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -3146,7 +4587,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use exactly one resource mode",
             "edit mode: app_key, optional app_name to rename the existing app",
             "create mode: package_id + app_name + create_if_missing=true",
+            "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
+            "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
+            "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
+            "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
+            "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
+            "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             *_VISIBILITY_EXECUTION_NOTES,
             "update_fields is the field-level partial update path; it reads current form schema and preserves untouched field config",
             "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
@@ -3171,7 +4619,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_id": 1001,
-            "icon": "template",
+            "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
@@ -3183,6 +4631,40 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "update_fields": [],
             "remove_fields": [],
         },
+        "multi_app_example": {
+            "profile": "default",
+            "package_id": 1001,
+            "create_if_missing": True,
+            "publish": True,
+            "apps": [
+                {
+                    "client_key": "employee",
+                    "app_name": "员工花名册",
+                    "icon": "business-personalcard",
+                    "color": "emerald",
+                    "add_fields": [
+                        {"name": "员工名称", "type": "text", "as_data_title": True},
+                        {"name": "员工照片", "type": "attachment", "as_data_cover": True},
+                    ],
+                },
+                {
+                    "client_key": "worklog",
+                    "app_name": "工时表",
+                    "icon": "clock",
+                    "color": "blue",
+                    "add_fields": [
+                        {"name": "工时标题", "type": "text", "as_data_title": True},
+                        {
+                            "name": "关联员工",
+                            "type": "relation",
+                            "target_app_ref": "employee",
+                            "display_field": {"name": "员工名称"},
+                            "visible_fields": [{"name": "员工名称"}],
+                        },
+                    ],
+                },
+            ],
+        },
         "rename_example": {
             "profile": "default",
             "app_key": "APP_PROJECT",
@@ -3451,7 +4933,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "patch_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
+        "allowed_keys": [
+            "app_key",
+            "upsert_views",
+            "patch_views",
+            "remove_views",
+            "preset",
+            "upsert_views[].view_key",
+            "upsert_views[].name",
+            "upsert_views[].type",
+            "upsert_views[].columns",
+            "upsert_views[].filters",
+            "upsert_views[].buttons",
+            "upsert_views[].visibility",
+            "upsert_views[].query_conditions",
+            "patch_views[].view_key",
+            "patch_views[].name",
+            "patch_views[].set",
+            "patch_views[].unset",
+        ],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3483,7 +4983,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
-            "view.buttons.config_type": ["TOP", "DETAIL"],
+            "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -3491,7 +4991,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
-            "view associated report/view display is now configured through app_associated_resources_apply, not app_views_apply",
+            "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
+            "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply only keeps legacy associated_resources input compatible",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3554,7 +5057,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "patch_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
+        "allowed_keys": [
+            "app_key",
+            "publish",
+            "upsert_views",
+            "patch_views",
+            "remove_views",
+            "upsert_views[].view_key",
+            "upsert_views[].name",
+            "upsert_views[].type",
+            "upsert_views[].columns",
+            "upsert_views[].filters",
+            "upsert_views[].buttons",
+            "upsert_views[].visibility",
+            "upsert_views[].query_conditions",
+            "patch_views[].view_key",
+            "patch_views[].name",
+            "patch_views[].set",
+            "patch_views[].unset",
+        ],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3585,7 +5106,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
-            "view.buttons.config_type": ["TOP", "DETAIL"],
+            "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -3598,7 +5119,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
-            "view associated report/view display is now configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
+            "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
+            "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3690,6 +5214,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns compact current field configuration for one app",
             "use this before app_schema_apply when you need exact field definitions",
+            "also returns chart_fields from QingBI datasource fields; app_charts_apply field selectors should use chart_fields because record/schema-visible fields and QingBI fields are not the same schema",
+            "chart_fields[].field_id supports field_<queId> selectors, while chart_fields[].bi_field_id is the raw QingBI fieldId accepted by report configs",
             "subtable fields include nested subfields using the same compact field shape",
         ],
         "minimal_example": {
@@ -3811,6 +5337,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "successful create results must return a real backend chart_id",
                 "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
                 "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
+                "chart dimension/metric/filter/query fields are resolved from app_get_fields.chart_fields (QingBI datasource fields), not record schema or form-only fields",
+                "system fields such as 申请人/申请时间/编号 are usable only when they appear in chart_fields; otherwise app_charts_apply returns CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
+                "low-frequency chart types have local prevalidation: gauge requires 0 dimensions and 2 non-duplicated metrics; histogram requires at most 1 dimension and exactly 1 plain numeric metric",
+                "chart rule failures return chart_results[].diagnostics with rule_code, expected, actual, offending_fields, and next_action; backend 81002/81005 are translated when possible",
+                "remove_chart_ids deletes by chart_id and verifies each deleted chart with single chart_id readback; pure delete does not read the full chart list",
+                "if delete readback is unavailable or still finds the chart, chart_results[] returns delete_executed=true, readback_status, and safe_to_retry_delete=false; do not blindly repeat delete",
                 *_VISIBILITY_EXECUTION_NOTES,
             ],
         "minimal_example": {
@@ -3854,9 +5386,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "portal_apply": {
-        "allowed_keys": ["dash_key", "dash_name", "package_id", "publish", "sections", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "allowed_keys": ["dash_key", "dash_name", "name", "package_id", "publish", "sections", "pages", "payload", "layout_preset", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
         "aliases": {
             "packageId": "package_id",
+            "name": "dash_name",
             "sourceType": "source_type",
             "chartRef": "chart_ref",
             "viewRef": "view_ref",
@@ -3869,20 +5402,34 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
-            "execution_notes": [
-                "use exactly one resource mode",
-                "update mode: dash_key",
-                "create mode: package_id + dash_name",
-                "portal_apply uses replace semantics for sections",
-                "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
-                "portal section-level patch is not exposed; supplying sections means full sections replacement",
-                "remove a section by omitting it from the new sections list",
-                "package_id is required when creating a new portal",
-                "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
+        "allowed_values": {
+            "section.source_type": ["chart", "view", "grid", "filter", "text", "link"],
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "use exactly one resource mode",
+            "update mode: dash_key",
+            "create mode: package_id + dash_name",
+            "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
+            "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
+            "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
+            "portal_apply uses replace semantics for sections",
+            "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
+            "portal section-level patch is not exposed; supplying sections means full sections replacement",
+            "remove a section by omitting it from the new sections list",
+            "package_id is required when creating a new portal",
+            "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
             "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
+            "pc layout uses a 24-column grid; mobile layout uses a 6-column grid",
+            "if unsure about layout, omit position or use layout_preset=auto/dashboard_2col/dashboard_3col",
+            "two-column pc layout should use x=0/12 with cols=12; three-column pc layout should use x=0/8/16 with cols=8",
+            "x=0/6 with cols=6 only occupies the left half of the pc portal and triggers PORTAL_LAYOUT_HALF_WIDTH",
             "position.pc/mobile is the canonical portal layout shape",
+            "compat payload accepts name -> dash_name and single pages[0].components -> sections",
             "visibility is the canonical public auth shape; auth is kept only as a deprecated compatibility alias",
             "passing visibility and auth together is rejected as VISIBILITY_CONFLICT",
             *_VISIBILITY_EXECUTION_NOTES,
@@ -3891,7 +5438,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "dash_name": "经营门户",
             "package_id": 1001,
+            "icon": "view-grid",
+            "color": "blue",
             "publish": True,
+            "layout_preset": "dashboard_2col",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "sections": [
                 {
@@ -3905,6 +5455,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
+        "compat_payload_example": {
+            "name": "经营门户",
+            "package_id": 1001,
+            "layout_preset": "dashboard_2col",
+            "pages": [
+                {
+                    "title": "经营总览",
+                    "components": [
+                        {
+                            "title": "销售趋势",
+                            "source_type": "chart",
+                            "chart_ref": {"app_key": "APP_KEY", "chart_id": "CHART_ID"},
+                        }
+                    ],
+                }
+            ],
+        },
         "minimal_section_example": {
             "title": "订单概览",
             "source_type": "view",