@josephyan/qingflow-cli 1.0.11 → 1.1.2

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
 
@@ -17,21 +18,20 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
+    AssociatedResourcesApplyRequest,
     ChartApplyRequest,
+    CustomButtonsApplyRequest,
     CustomButtonPatch,
     FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
-    FlowPreset,
-    FlowNodePatch,
-    FlowPlanRequest,
-    FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutPreset,
     LayoutSectionPatch,
     PortalApplyRequest,
+    PublicButtonPlacement,
     PublicButtonTriggerAction,
     PublicFieldType,
     PublicRelationMode,
@@ -40,11 +40,21 @@ from ..builder_facade.models import (
     SchemaPlanRequest,
     VisibilityPatch,
     ViewFilterOperator,
+    ViewPartialPatch,
     ViewUpsertPatch,
     ViewsPreset,
     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
@@ -55,9 +65,28 @@ from .qingbi_report_tools import QingbiReportTools
 from .role_tools import RoleTools
 from .solution_tools import SolutionTools
 from .view_tools import ViewTools
-from .workflow_tools import WorkflowTools
 
-PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
+
+def _normalize_builder_view_key(value: str) -> str:
+    raw = str(value or "").strip()
+    if raw.startswith("custom:"):
+        return raw.split(":", 1)[1].strip()
+    return raw
+
+
+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):
@@ -78,7 +107,6 @@ class AiBuilderTools(ToolBase):
             buttons=CustomButtonTools(sessions, backend),
             packages=PackageTools(sessions, backend),
             views=ViewTools(sessions, backend),
-            workflows=WorkflowTools(sessions, backend),
             portals=PortalTools(sessions, backend),
             charts=QingbiReportTools(sessions, backend),
             roles=RoleTools(sessions, backend),
@@ -92,6 +120,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)
@@ -220,40 +256,53 @@ class AiBuilderTools(ToolBase):
             return self.button_style_catalog_get(profile=profile)
 
         @mcp.tool()
-        def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.app_custom_button_list(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
-            return self.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
-
-        @mcp.tool()
-        def app_custom_button_create(
+        def app_custom_buttons_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            payload: JSONObject | None = None,
+            upsert_buttons: list[JSONObject] | None = None,
+            patch_buttons: list[JSONObject] | None = None,
+            remove_buttons: list[JSONObject] | None = None,
+            view_configs: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
-            return self.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+            return self.app_custom_buttons_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_buttons=upsert_buttons or [],
+                patch_buttons=patch_buttons or [],
+                remove_buttons=remove_buttons or [],
+                view_configs=view_configs or [],
+                apps=apps,
+            )
 
         @mcp.tool()
-        def app_custom_button_update(
+        def app_associated_resources_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            button_id: int = 0,
-            payload: JSONObject | None = None,
+            upsert_resources: list[JSONObject] | None = None,
+            patch_resources: list[JSONObject] | None = None,
+            remove_associated_item_ids: list[int] | None = None,
+            reorder_associated_item_ids: list[int] | None = None,
+            view_configs: list[JSONObject] | None = None,
         ) -> JSONObject:
-            return self.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
-
-        @mcp.tool()
-        def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
-            return self.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+            return self.app_associated_resources_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_resources=upsert_resources or [],
+                patch_resources=patch_resources or [],
+                remove_associated_item_ids=remove_associated_item_ids or [],
+                reorder_associated_item_ids=reorder_associated_item_ids or [],
+                view_configs=view_configs or [],
+            )
 
         @mcp.tool()
         def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_get(profile=profile, app_key=app_key)
 
         @mcp.tool()
-        def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_fields, data_key="fields", tool_name="app_get_fields")
             return self.app_get_fields(profile=profile, app_key=app_key)
 
         @mcp.tool()
@@ -266,21 +315,41 @@ class AiBuilderTools(ToolBase):
             return self.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply)
 
         @mcp.tool()
-        def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_layout, data_key="sections", tool_name="app_get_layout")
             return self.app_get_layout(profile=profile, app_key=app_key)
 
         @mcp.tool()
-        def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_views, data_key="views", tool_name="app_get_views")
             return self.app_get_views(profile=profile, app_key=app_key)
 
         @mcp.tool()
-        def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_flow, data_key="spec", tool_name="app_get_flow")
             return self.app_get_flow(profile=profile, app_key=app_key)
 
         @mcp.tool()
-        def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+        def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_charts, data_key="charts", tool_name="app_get_charts")
             return self.app_get_charts(profile=profile, app_key=app_key)
 
+        @mcp.tool()
+        def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_buttons, data_key="buttons", tool_name="app_get_buttons")
+            return self._facade.app_get_buttons(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_get_associated_resources(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_associated_resources, data_key="associated_resources", tool_name="app_get_associated_resources")
+            return self._facade.app_get_associated_resources(profile=profile, app_key=app_key)
+
         @mcp.tool()
         def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
             return self.portal_list(profile=profile)
@@ -319,7 +388,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())
@@ -351,6 +445,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
+                apps=[],
             )
 
         @mcp.tool()
@@ -360,25 +455,40 @@ class AiBuilderTools(ToolBase):
             mode: str = "merge",
             publish: bool = True,
             sections: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [], apps=apps)
+
+        @mcp.tool()
+        def app_flow_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            version_id: str = "",
         ) -> JSONObject:
-            return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
+            return self.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
+
+        @mcp.tool()
+        def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> JSONObject:
+            return self.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
 
         @mcp.tool()
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            mode: str = "replace",
             publish: bool = True,
-            nodes: list[JSONObject] | None = None,
-            transitions: list[JSONObject] | None = None,
+            spec: JSONObject | None = None,
+            idempotency_key: str = "",
+            schema_version: str = "",
+            patch_nodes: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
                 publish=publish,
-                nodes=nodes or [],
-                transitions=transitions or [],
+                spec=spec or {},
+                idempotency_key=idempotency_key or None,
+                schema_version=schema_version or None,
+                patch_nodes=patch_nodes,
             )
 
         @mcp.tool()
@@ -387,14 +497,18 @@ class AiBuilderTools(ToolBase):
             app_key: str = "",
             publish: bool = True,
             upsert_views: list[JSONObject] | None = None,
+            patch_views: list[JSONObject] | None = None,
             remove_views: list[str] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.app_views_apply(
                 profile=profile,
                 app_key=app_key,
                 publish=publish,
                 upsert_views=upsert_views or [],
+                patch_views=patch_views or [],
                 remove_views=remove_views or [],
+                apps=apps,
             )
 
         @mcp.tool()
@@ -402,15 +516,19 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             upsert_charts: list[JSONObject] | None = None,
+            patch_charts: list[JSONObject] | None = None,
             remove_chart_ids: list[str] | None = None,
             reorder_chart_ids: list[str] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.app_charts_apply(
                 profile=profile,
                 app_key=app_key,
                 upsert_charts=upsert_charts or [],
+                patch_charts=patch_charts or [],
                 remove_chart_ids=remove_chart_ids or [],
                 reorder_chart_ids=reorder_chart_ids or [],
+                apps=apps,
             )
 
         @mcp.tool()
@@ -418,9 +536,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,
@@ -428,10 +549,15 @@ class AiBuilderTools(ToolBase):
             hide_copyright: bool | None = None,
             dash_global_config: JSONObject | None = None,
             config: JSONObject | None = None,
+            payload: JSONObject | None = None,
+            patch_sections: list[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",
@@ -448,9 +574,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,
@@ -458,14 +587,25 @@ class AiBuilderTools(ToolBase):
                 hide_copyright=hide_copyright,
                 dash_global_config=dash_global_config,
                 config=config or {},
+                payload=payload,
+                patch_sections=patch_sections,
             )
 
         @mcp.tool()
         def app_publish_verify(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
+            app_keys: list[str] | None = None,
             expected_package_id: int | None = None,
         ) -> JSONObject:
+            if app_keys:
+                return self._facade._batch_read_app_keys(
+                    profile=profile,
+                    app_keys=app_keys,
+                    single_reader=lambda profile, app_key: self.app_publish_verify(profile=profile, app_key=app_key, expected_package_id=expected_package_id),
+                    data_key="verification",
+                    tool_name="app_publish_verify",
+                )
             return self.app_publish_verify(
                 profile=profile,
                 app_key=app_key,
@@ -473,14 +613,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("分组解析")
@@ -525,6 +665,7 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": False,
         }
+        contract = _builder_contract_with_apply_output(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -546,6 +687,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,
@@ -622,7 +784,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 {}),
@@ -633,7 +806,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,
@@ -649,6 +822,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(
@@ -867,6 +1041,134 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "button_style_catalog_get", "arguments": {"profile": profile}},
         )
 
+    @tool_cn_name("应用按钮声明式应用")
+    def app_custom_buttons_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_buttons: list[JSONObject],
+        patch_buttons: list[JSONObject] | None = None,
+        remove_buttons: list[JSONObject],
+        view_configs: list[JSONObject] | None = None,
+        apps: list[JSONObject] | None = None,
+    ) -> JSONObject:
+        """执行应用按钮 apply 逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
+                profile=profile,
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_custom_buttons_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    upsert_buttons=kw.get("upsert_buttons", []),
+                    patch_buttons=kw.get("patch_buttons", []),
+                    remove_buttons=kw.get("remove_buttons", []),
+                    view_configs=kw.get("view_configs", []),
+                ),
+                tool_name="app_custom_buttons_apply",
+            )
+        raw_request = {
+            "app_key": app_key,
+            "upsert_buttons": upsert_buttons,
+            "patch_buttons": patch_buttons or [],
+            "remove_buttons": remove_buttons,
+            "view_configs": view_configs or [],
+        }
+        try:
+            request = CustomButtonsApplyRequest.model_validate(raw_request)
+        except ValidationError as exc:
+            return _attach_builder_apply_envelope("app_custom_buttons_apply", _validation_failure(
+                str(exc),
+                tool_name="app_custom_buttons_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_buttons_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key or "APP_KEY",
+                        "upsert_buttons": [
+                            {
+                                "button_text": "同步客户",
+                                "style_preset": "primary_blue",
+                                "button_icon": "ex-switch",
+                                "trigger_action": "link",
+                                "trigger_link_url": "https://example.com",
+                            }
+                        ],
+                        "remove_buttons": [],
+                        "view_configs": [],
+                    },
+                },
+            ))
+        normalized_args = request.model_dump(mode="json")
+        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(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_resources: list[JSONObject],
+        remove_associated_item_ids: list[int],
+        reorder_associated_item_ids: list[int],
+        view_configs: list[JSONObject],
+        patch_resources: list[JSONObject] | None = None,
+    ) -> JSONObject:
+        """执行应用关联资源 apply 逻辑。"""
+        raw_request = {
+            "app_key": app_key,
+            "upsert_resources": upsert_resources,
+            "patch_resources": patch_resources or [],
+            "remove_associated_item_ids": remove_associated_item_ids,
+            "reorder_associated_item_ids": reorder_associated_item_ids,
+            "view_configs": view_configs,
+        }
+        try:
+            request = AssociatedResourcesApplyRequest.model_validate(raw_request)
+        except ValidationError as exc:
+            return _attach_builder_apply_envelope("app_associated_resources_apply", _validation_failure(
+                str(exc),
+                tool_name="app_associated_resources_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_associated_resources_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key or "APP_KEY",
+                        "upsert_resources": [
+                            {
+                                "client_key": "customer_view",
+                                "graph_type": "view",
+                                "target_app_key": "TARGET_APP",
+                                "view_key": "VIEW_KEY",
+                            }
+                        ],
+                        "view_configs": [
+                            {
+                                "view_key": "MAIN_VIEW",
+                                "visible": True,
+                                "limit_type": "select",
+                                "associated_item_refs": ["customer_view"],
+                            }
+                        ],
+                    },
+                },
+            ))
+        normalized_args = request.model_dump(mode="json", exclude_none=True)
+        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:
         """执行应用相关逻辑。"""
@@ -909,7 +1211,10 @@ class AiBuilderTools(ToolBase):
                             "style_preset": "primary_blue",
                             "button_icon": "ex-plus-circle",
                             "trigger_action": "addData",
-                            "trigger_add_data_config": {"related_app_key": "TARGET_APP_KEY", "que_relation": []},
+                            "trigger_add_data_config": {
+                                "target_app_key": "TARGET_APP_KEY",
+                                "field_mappings": [{"source_field": "客户名称", "target_field": "客户"}],
+                            },
                         },
                     },
                 },
@@ -1001,8 +1306,10 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用字段详情查询")
-    def app_get_fields(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get_fields(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_fields, data_key="fields", tool_name="app_get_fields")
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_fields(profile=profile, app_key=app_key),
@@ -1041,8 +1348,10 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用布局详情查询")
-    def app_get_layout(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get_layout(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_layout, data_key="sections", tool_name="app_get_layout")
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_layout(profile=profile, app_key=app_key),
@@ -1063,8 +1372,10 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用视图详情查询")
-    def app_get_views(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get_views(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_views, data_key="views", tool_name="app_get_views")
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_views(profile=profile, app_key=app_key),
@@ -1073,26 +1384,27 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    @tool_cn_name("应用流程摘要读取")
-    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+    @tool_cn_name("Workflow Spec Schema")
+    def app_flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
+        normalized_args = {"schema_version": schema_version}
         return _safe_tool_call(
-            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
-            error_code="FLOW_READ_FAILED",
+            lambda: self._facade.flow_get_schema(profile=profile, schema_version=schema_version),
+            error_code="FLOW_SPEC_SCHEMA_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
         )
 
-    @tool_cn_name("应用流程详情查询")
-    def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
+    @tool_cn_name("Workflow Spec 读取")
+    def app_get_flow(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None, version_id: str | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_flow, data_key="spec", tool_name="app_get_flow")
+        normalized_args = {"app_key": app_key, "version_id": version_id}
         return _safe_tool_call(
-            lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
+            lambda: self._facade.flow_get(profile=profile, app_key=app_key, version_id=version_id),
             error_code="APP_GET_FLOW_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
     @tool_cn_name("应用图表摘要读取")
@@ -1107,8 +1419,10 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用图表详情查询")
-    def app_get_charts(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get_charts(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_charts, data_key="charts", tool_name="app_get_charts")
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_charts(profile=profile, app_key=app_key),
@@ -1117,6 +1431,32 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("自定义按钮读取")
+    def app_get_buttons(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+        """执行按钮相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_buttons, data_key="buttons", tool_name="app_get_buttons")
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_buttons(profile=profile, app_key=app_key),
+            error_code="APP_GET_BUTTONS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_buttons", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("关联资源读取")
+    def app_get_associated_resources(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+        """执行关联资源相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_associated_resources, data_key="associated_resources", tool_name="app_get_associated_resources")
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_associated_resources(profile=profile, app_key=app_key),
+            error_code="APP_GET_ASSOCIATED_RESOURCES_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_associated_resources", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
     @tool_cn_name("门户列表查询")
     def portal_list(self, *, profile: str) -> JSONObject:
         """执行门户相关逻辑。"""
@@ -1152,7 +1492,7 @@ class AiBuilderTools(ToolBase):
     @tool_cn_name("视图详情查询")
     def view_get(self, *, profile: str, view_key: str = "", viewgraph_key: str = "") -> JSONObject:
         """执行视图相关逻辑。"""
-        resolved_view_key = str(view_key or viewgraph_key or "").strip()
+        resolved_view_key = _normalize_builder_view_key(str(view_key or viewgraph_key or "").strip())
         normalized_args = {"view_key": resolved_view_key}
         return _safe_tool_call(
             lambda: self._facade.view_get(profile=profile, view_key=resolved_view_key),
@@ -1287,52 +1627,6 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
-    @tool_cn_name("应用流程规划")
-    def app_flow_plan(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        mode: str = "replace",
-        nodes: list[JSONObject] | None = None,
-        transitions: list[JSONObject] | None = None,
-        preset: str | None = None,
-    ) -> JSONObject:
-        """执行应用相关逻辑。"""
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": app_key,
-                    "mode": mode,
-                    "nodes": nodes or [],
-                    "transitions": transitions or [],
-                    "preset": preset,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
-                tool_name="app_flow_plan",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_plan",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": app_key,
-                        "mode": "replace",
-                        "preset": "basic_approval",
-                        "nodes": [],
-                        "transitions": [],
-                    },
-                },
-            )
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_plan(profile=profile, request=request),
-            error_code="FLOW_PLAN_FAILED",
-            normalized_args=request.model_dump(mode="json"),
-            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
-        )
-
     @tool_cn_name("应用视图规划")
     def app_views_plan(
         self,
@@ -1393,8 +1687,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,
@@ -1410,7 +1715,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(
@@ -1429,6 +1734,325 @@ 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,
+            })
+
+        # Inline layout: apply layout for each successful app that included a layout field.
+        for index, raw_item in enumerate(apps):
+            if not isinstance(raw_item, dict):
+                continue
+            layout_spec = raw_item.get("layout")
+            if not isinstance(layout_spec, dict) or not layout_spec:
+                continue
+            final_item = next((it for it in final_items if it.get("index") == index), None)
+            if not final_item or final_item.get("status") not in {"success", "partial_success"}:
+                continue
+            resolved_app_key = str(final_item.get("app_key") or "").strip()
+            if not resolved_app_key:
+                continue
+            layout_mode = str(layout_spec.get("mode") or "merge").strip() or "merge"
+            layout_sections = layout_spec.get("sections") or []
+            try:
+                layout_result = self.app_layout_apply(
+                    profile=profile,
+                    app_key=resolved_app_key,
+                    mode=layout_mode,
+                    publish=publish,
+                    sections=list(layout_sections),
+                )
+                layout_ok = layout_result.get("status") in {"success", "partial_success"}
+            except Exception as layout_error:
+                layout_ok = False
+                layout_result = {"status": "failed", "message": str(layout_error)}
+            if layout_ok:
+                final_item["layout_applied"] = True
+                final_item["layout_status"] = layout_result.get("status")
+            else:
+                final_item["layout_warning"] = layout_result.get("error_code") or "LAYOUT_APPLY_FAILED"
+                final_item["layout_message"] = layout_result.get("message")
+
+        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,
@@ -1449,6 +2073,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,
@@ -1535,8 +2167,21 @@ class AiBuilderTools(ToolBase):
         return _publicize_package_fields(result)
 
     @tool_cn_name("应用布局应用")
-    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject], apps: list[JSONObject] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
+                profile=profile,
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_layout_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    mode=kw.get("mode", mode),
+                    publish=kw.get("publish", publish),
+                    sections=kw.get("sections", []),
+                ),
+                tool_name="app_layout_apply",
+            )
         result = self._app_layout_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1544,7 +2189,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(
@@ -1555,6 +2200,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:
         """执行内部辅助逻辑。"""
@@ -1620,130 +2266,104 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
+        spec: JSONObject,
         publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
+        patch_nodes: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        result = self._app_flow_apply_once(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            publish=publish,
-            nodes=nodes,
-            transitions=transitions,
+        if patch_nodes:
+            result = _safe_tool_call(
+                lambda: self._facade.flow_patch_nodes(
+                    profile=profile,
+                    app_key=app_key,
+                    patch_nodes=patch_nodes,
+                    publish=publish,
+                    idempotency_key=idempotency_key,
+                    schema_version=schema_version,
+                ),
+                error_code="FLOW_APPLY_FAILED",
+                normalized_args={"app_key": app_key, "patch_nodes": patch_nodes, "publish": publish},
+                suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, "app_key": app_key, "patch_nodes": patch_nodes}},
+            )
+            return _attach_builder_apply_envelope("app_flow_apply", result)
+        if not isinstance(spec, dict) or not spec:
+            return _config_failure(
+                tool_name="app_flow_apply",
+                message="app_flow_apply requires a non-empty WorkflowSpecDTO `spec` object.",
+                fix_hint="Call app_flow_get_schema, then app_flow_get for GET-first baseline, patch spec, and apply.",
+            )
+        normalized_args = {
+            "app_key": app_key,
+            "publish": publish,
+            "spec": spec,
+            "idempotency_key": idempotency_key,
+            "schema_version": schema_version,
+        }
+        result = _safe_tool_call(
+            lambda: self._facade.flow_apply(
+                profile=profile,
+                app_key=app_key,
+                spec=spec,
+                publish=publish,
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
+            ),
+            error_code="FLOW_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
-        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(
+            retry_call=lambda: self._facade.flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
+                spec=spec,
                 publish=publish,
-                nodes=nodes,
-                transitions=transitions,
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
             ),
         )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
 
-    def _app_flow_apply_once(
+    @tool_cn_name("应用视图应用")
+    def app_views_apply(
         self,
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
         publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
+        upsert_views: list[JSONObject],
+        patch_views: list[JSONObject] | None = None,
+        remove_views: list[str],
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
-        """执行内部辅助逻辑。"""
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_flow_plan(
+        """执行应用相关逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
                 profile=profile,
-                app_key=app_key,
-                mode=mode,
-                nodes=nodes,
-                transitions=transitions,
-                preset=None,
-            ),
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_views_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    publish=kw.get("publish", publish),
+                    upsert_views=kw.get("upsert_views", []),
+                    patch_views=kw.get("patch_views", []),
+                    remove_views=kw.get("remove_views", []),
+                ),
+                tool_name="app_views_apply",
+            )
+        result = self._app_views_apply_once(
             profile=profile,
+            app_key=app_key,
             publish=publish,
-            plan_tool_name="app_flow_plan",
-            apply_tool_name="app_flow_apply",
+            upsert_views=upsert_views,
+            patch_views=patch_views or [],
+            remove_views=remove_views,
         )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": plan_args.get("app_key") or app_key,
-                    "mode": plan_args.get("mode") or mode,
-                    "nodes": plan_args.get("nodes") or [],
-                    "transitions": plan_args.get("transitions") or [],
-                    "preset": None,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
-                tool_name="app_flow_apply",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_apply",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "mode": str(plan_args.get("mode") or "replace"),
-                        "publish": publish,
-                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
-                        "transitions": plan_args.get("transitions") or [],
-                    },
-                },
-            )
-        normalized_args = {
-            "app_key": request.app_key,
-            "mode": request.mode,
-            "publish": publish,
-            "nodes": [node.model_dump(mode="json") for node in request.nodes],
-            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
-        }
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_apply(
-                profile=profile,
-                app_key=request.app_key,
-                mode=request.mode,
-                publish=publish,
-                nodes=[node.model_dump(mode="json") for node in request.nodes],
-                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
-            ),
-            error_code="FLOW_APPLY_FAILED",
-            normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
-
-    @tool_cn_name("应用视图应用")
-    def app_views_apply(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        publish: bool = True,
-        upsert_views: list[JSONObject],
-        remove_views: list[str],
-    ) -> JSONObject:
-        """执行应用相关逻辑。"""
-        result = self._app_views_apply_once(
-            profile=profile,
-            app_key=app_key,
-            publish=publish,
-            upsert_views=upsert_views,
-            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(
@@ -1752,8 +2372,10 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 remove_views=remove_views,
                 upsert_views=upsert_views,
+                patch_views=patch_views or [],
             ),
         )
+        return _attach_builder_apply_envelope("app_views_apply", result)
 
     def _app_views_apply_once(
         self,
@@ -1762,9 +2384,53 @@ class AiBuilderTools(ToolBase):
         app_key: str,
         publish: bool = True,
         upsert_views: list[JSONObject],
+        patch_views: list[JSONObject],
         remove_views: list[str],
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
+        if patch_views:
+            try:
+                parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
+                parsed_patch_views = [ViewPartialPatch.model_validate(item) for item in patch_views]
+            except ValidationError as exc:
+                return _visibility_validation_failure(
+                    str(exc),
+                    tool_name="app_views_apply",
+                    exc=exc,
+                    suggested_next_call={
+                        "tool_name": "app_views_apply",
+                        "arguments": {
+                            "profile": profile,
+                            "app_key": app_key,
+                            "publish": publish,
+                            "upsert_views": upsert_views or [],
+                            "patch_views": [
+                                {"view_key": "VIEW_KEY", "set": {"query_conditions": {"enabled": True, "rows": [["字段A"]]}}},
+                            ],
+                            "remove_views": remove_views or [],
+                        },
+                    },
+                )
+            normalized_args = {
+                "app_key": app_key,
+                "publish": publish,
+                "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+                "patch_views": [patch.model_dump(mode="json") for patch in parsed_patch_views],
+                "remove_views": list(remove_views or []),
+            }
+            return _safe_tool_call(
+                lambda: self._facade.app_views_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    publish=publish,
+                    upsert_views=parsed_views,
+                    patch_views=parsed_patch_views,
+                    remove_views=list(remove_views or []),
+                ),
+                error_code="VIEWS_APPLY_FAILED",
+                normalized_args=normalized_args,
+                suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+            )
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_views_plan(
                 profile=profile,
@@ -1813,6 +2479,7 @@ class AiBuilderTools(ToolBase):
                 app_key=str(plan_args.get("app_key") or app_key),
                 publish=publish,
                 upsert_views=parsed_views,
+                patch_views=[],
                 remove_views=list(plan_args.get("remove_views") or remove_views),
             ),
             error_code="VIEWS_APPLY_FAILED",
@@ -1827,6 +2494,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         upsert_charts: list[JSONObject],
+        patch_charts: list[JSONObject] | None = None,
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
     ) -> JSONObject:
@@ -1835,6 +2503,7 @@ class AiBuilderTools(ToolBase):
             profile=profile,
             app_key=app_key,
             upsert_charts=upsert_charts,
+            patch_charts=patch_charts or [],
             remove_chart_ids=remove_chart_ids,
             reorder_chart_ids=reorder_chart_ids,
         )
@@ -1848,19 +2517,36 @@ class AiBuilderTools(ToolBase):
         upsert_charts: list[JSONObject],
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
+        patch_charts: list[JSONObject] | None = None,
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
+                profile=profile,
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_charts_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    upsert_charts=kw.get("upsert_charts", []),
+                    patch_charts=kw.get("patch_charts", []),
+                    remove_chart_ids=kw.get("remove_chart_ids", []),
+                    reorder_chart_ids=kw.get("reorder_chart_ids", []),
+                ),
+                tool_name="app_charts_apply",
+            )
         try:
             request = ChartApplyRequest.model_validate(
                 {
                     "app_key": app_key,
                     "upsert_charts": upsert_charts or [],
+                    "patch_charts": patch_charts or [],
                     "remove_chart_ids": remove_chart_ids or [],
                     "reorder_chart_ids": reorder_chart_ids or [],
                 }
             )
         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,
@@ -1874,14 +2560,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(
@@ -1890,9 +2576,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,
@@ -1900,27 +2589,66 @@ class AiBuilderTools(ToolBase):
         hide_copyright: bool | None = None,
         dash_global_config: JSONObject | None = None,
         config: JSONObject | None = None,
+        payload: JSONObject | None = None,
+        patch_sections: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行门户相关逻辑。"""
-        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 {},
-                }
+        if patch_sections:
+            if not dash_key:
+                return _attach_builder_apply_envelope("portal_apply", _config_failure(
+                    tool_name="portal_apply",
+                    message="patch_sections requires dash_key to identify the portal",
+                    fix_hint="Provide dash_key from portal_list or portal_get",
+                ))
+            result = _safe_tool_call(
+                lambda: self._facade.portal_patch_sections(
+                    profile=profile,
+                    dash_key=dash_key,
+                    patch_sections=patch_sections,
+                    publish=publish,
+                ),
+                error_code="PORTAL_APPLY_FAILED",
+                normalized_args={"dash_key": dash_key, "patch_sections": patch_sections, "publish": publish},
+                suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, "dash_key": dash_key, "patch_sections": patch_sections}},
             )
+            return _attach_builder_apply_envelope("portal_apply", result)
+        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(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,
@@ -1931,6 +2659,7 @@ class AiBuilderTools(ToolBase):
                         "dash_name": dash_name or "业务门户",
                         "package_id": package_id or 1001,
                         "publish": True,
+                        "layout_preset": "dashboard_2col",
                         "sections": [
                             {
                                 "title": "经营概览",
@@ -1940,25 +2669,43 @@ 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(
         self,
         *,
         profile: str,
-        app_key: str,
+        app_key: str = "",
+        app_keys: list[str] | None = None,
         expected_package_id: int | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        if app_keys:
+            return self._facade._batch_read_app_keys(
+                profile=profile,
+                app_keys=app_keys,
+                single_reader=lambda profile, app_key: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
+                data_key="verification",
+                tool_name="app_publish_verify",
+            )
         normalized_args = {"app_key": app_key, "expected_package_id": expected_package_id}
         result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
@@ -1966,7 +2713,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(
@@ -1975,6 +2722,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:
         """执行内部辅助逻辑。"""
@@ -2093,6 +2841,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,
     *,
@@ -2173,20 +3043,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,
@@ -2196,6 +3080,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,
     *,
@@ -2244,6 +3174,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",
@@ -2255,6 +3186,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
@@ -2403,6 +4070,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"},
@@ -2427,9 +4128,18 @@ _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",
             "item shapes: {type:'app', app_key}, {type:'portal', dash_key}, or {type:'group', group_id?, name, items:[...]}",
@@ -2452,7 +4162,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),
         },
@@ -2565,122 +4275,287 @@ _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": {
             "profile": "default",
         },
     },
-    "app_custom_button_list": {
-        "allowed_keys": ["app_key"],
-        "aliases": {},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-        },
-    },
-    "app_custom_button_get": {
-        "allowed_keys": ["app_key", "button_id"],
-        "aliases": {"buttonId": "button_id"},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "button_id": 1001,
-        },
-    },
-    "app_custom_button_create": {
-        "allowed_keys": ["app_key", "payload"],
+    "app_custom_buttons_apply": {
+        "allowed_keys": [
+            "app_key",
+            "apps",
+            "upsert_buttons",
+            "patch_buttons",
+            "remove_buttons",
+            "view_configs",
+            "upsert_buttons[].client_key",
+            "upsert_buttons[].button_id",
+            "upsert_buttons[].button_text",
+            "upsert_buttons[].style_preset",
+            "upsert_buttons[].background_color",
+            "upsert_buttons[].text_color",
+            "upsert_buttons[].button_icon",
+            "upsert_buttons[].trigger_action",
+            "upsert_buttons[].trigger_link_url",
+            "upsert_buttons[].trigger_add_data_config",
+            "upsert_buttons[].trigger_add_data_config.target_app_key",
+            "upsert_buttons[].trigger_add_data_config.field_mappings",
+            "upsert_buttons[].trigger_add_data_config.field_mappings[].source_field",
+            "upsert_buttons[].trigger_add_data_config.field_mappings[].target_field",
+            "upsert_buttons[].trigger_add_data_config.default_values",
+            "patch_buttons[].button_id",
+            "patch_buttons[].button_text",
+            "patch_buttons[].set",
+            "patch_buttons[].unset",
+            "view_configs[].view_key",
+            "view_configs[].mode",
+            "view_configs[].buttons",
+            "view_configs[].buttons[].button_ref",
+            "view_configs[].buttons[].placement",
+            "view_configs[].buttons[].primary",
+            "view_configs[].buttons[].button_limit",
+            "view_configs[].buttons[].button_formula",
+            "view_configs[].buttons[].button_formula_type",
+            "view_configs[].buttons[].print_tpls",
+            "remove_buttons[].button_id",
+            "remove_buttons[].button_text",
+        ],
         "aliases": {
-            "payload.buttonText": "payload.button_text",
-            "payload.stylePreset": "payload.style_preset",
-            "payload.backgroundColor": "payload.background_color",
-            "payload.textColor": "payload.text_color",
-            "payload.buttonIcon": "payload.button_icon",
-            "payload.triggerAction": "payload.trigger_action",
-            "payload.triggerLinkUrl": "payload.trigger_link_url",
-            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
-            "payload.externalQrobotConfig": "payload.external_qrobot_config",
-            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
-            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+            "upsertButtons": "upsert_buttons",
+            "patchButtons": "patch_buttons",
+            "removeButtons": "remove_buttons",
+            "viewConfigs": "view_configs",
+            "clientKey": "client_key",
+            "buttonId": "button_id",
+            "buttonText": "button_text",
+            "stylePreset": "style_preset",
+            "backgroundColor": "background_color",
+            "textColor": "text_color",
+            "buttonIcon": "button_icon",
+            "triggerAction": "trigger_action",
+            "triggerLinkUrl": "trigger_link_url",
+            "triggerAddDataConfig": "trigger_add_data_config",
+            "targetAppKey": "trigger_add_data_config.target_app_key",
+            "fieldMappings": "trigger_add_data_config.field_mappings",
+            "defaultValues": "trigger_add_data_config.default_values",
+            "mode": "view_configs[].mode",
+            "applyMode": "view_configs[].mode",
+            "buttonRef": "view_configs[].buttons[].button_ref",
+            "beingMain": "view_configs[].buttons[].primary",
+            "buttonLimit": "view_configs[].buttons[].button_limit",
+            "visibleWhen": "view_configs[].buttons[].button_limit",
+            "buttonFormula": "view_configs[].buttons[].button_formula",
+            "buttonFormulaType": "view_configs[].buttons[].button_formula_type",
+            "printTpls": "view_configs[].buttons[].print_tpls",
+            "externalQrobotConfig": "external_qrobot_config",
+            "customButtonExternalQRobotRelationVO": "external_qrobot_config",
+            "triggerWingsConfig": "trigger_wings_config",
         },
         "allowed_values": {
-            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
-            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
-            "payload.button_icon": list(BUTTON_ICONS),
-            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
-            "payload.text_color": list(BUTTON_TEXT_COLORS),
+            "upsert_buttons[].trigger_action": [member.value for member in PublicButtonTriggerAction],
+            "upsert_buttons[].style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
+            "upsert_buttons[].button_icon": list(BUTTON_ICONS),
+            "upsert_buttons[].background_color": list(BUTTON_BACKGROUND_COLORS),
+            "upsert_buttons[].text_color": list(BUTTON_TEXT_COLORS),
+            "view_configs[].mode": ["merge", "replace"],
+            "view_configs[].buttons[].placement": [member.value for member in PublicButtonPlacement],
         },
         "execution_notes": [
-            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "this is the default custom-button write path; old list/get/create/update/delete tools are hidden from the public agent surface",
+            "use patch_buttons for partial parameter replacement on existing buttons; the tool reads current button detail, merges patch_buttons[].set/unset, then submits the backend full-save payload internally",
+            "button_id targets an existing button; without button_id, button_text is used as an exact unique upsert key, otherwise a new button is created",
+            "for addData buttons, use trigger_add_data_config.target_app_key plus field_mappings/default_values; field_mappings compiles to backend queRelation",
+            "field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id maps to current record id (-17), 编号/record_number maps to visible record number (0)",
+            "to fill a target relation field with the current source record, map source_field='数据ID' to the target relation field; default_values is for static constants, not dynamic current-record values",
+            "do not write raw que_relation unless maintaining a legacy config; field_mappings/default_values and que_relation are mutually exclusive",
+            "view_configs binds custom buttons into views in the same apply call; button_ref may be a same-call client_key, a button_id, or an exact unique existing button_text",
+            "view_configs[].view_key is the raw builder view key from app_get.views[].view_key; do not pass record-data view_id values like custom:VIEW_KEY",
+            "view_configs[].buttons is required in merge mode; omitting buttons is blocked to avoid no-op writes and accidental publish",
+            "view_configs[].mode defaults to merge; use mode=replace or an explicit empty buttons list to replace/clear a view's custom button bindings",
+            "advanced view button binding supports button_limit, button_formula, button_formula_type, and print_tpls when visibility or print-template behavior is required",
+            "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",
-            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
-            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+            "accepts apps[] for multi-app batch; each item is {app_key, upsert_buttons?, patch_buttons?, remove_buttons?, view_configs?}",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "payload": {
-                "button_text": "新增记录",
-                "style_preset": "primary_blue",
-                "button_icon": "ex-plus-circle",
-                "trigger_action": "link",
-                "trigger_link_url": "https://example.com",
-            },
+            "upsert_buttons": [
+                {
+                    "button_text": "同步客户",
+                    "style_preset": "primary_blue",
+                    "button_icon": "ex-switch",
+                    "trigger_action": "link",
+                    "trigger_link_url": "https://example.com",
+                }
+            ],
+            "patch_buttons": [
+                {
+                    "button_text": "同步客户",
+                    "set": {"trigger_link_url": "https://example.com/new"},
+                }
+            ],
+            "remove_buttons": [{"button_text": "旧按钮"}],
+            "view_configs": [],
+        },
+        "add_data_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_buttons": [
+                {
+                    "client_key": "add_order",
+                    "button_text": "新增订单",
+                    "style_preset": "neutral_outline",
+                    "button_icon": "ex-plus-circle",
+                    "trigger_action": "addData",
+                    "trigger_add_data_config": {
+                        "target_app_key": "TARGET_APP",
+                        "field_mappings": [{"source_field": "客户名称", "target_field": "客户"}],
+                        "default_values": {"状态": "待提交"},
+                    },
+                }
+            ],
+            "remove_buttons": [],
+            "view_configs": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "buttons": [{"button_ref": "add_order", "placement": "detail", "primary": True}],
+                }
+            ],
+        },
+        "relation_current_record_example": {
+            "profile": "default",
+            "app_key": "EMPLOYEE_APP",
+            "upsert_buttons": [
+                {
+                    "client_key": "add_worklog",
+                    "button_text": "快捷添加工时",
+                    "style_preset": "neutral_outline",
+                    "button_icon": "ex-plus-circle",
+                    "trigger_action": "addData",
+                    "trigger_add_data_config": {
+                        "target_app_key": "WORKLOG_APP",
+                        "field_mappings": [{"source_field": "数据ID", "target_field": "关联员工"}],
+                        "default_values": {"状态": "待提交"},
+                    },
+                }
+            ],
+            "view_configs": [
+                {
+                    "view_key": "RAW_VIEW_KEY",
+                    "buttons": [{"button_ref": "add_worklog", "placement": "detail", "primary": True}],
+                }
+            ],
         },
     },
-    "app_custom_button_update": {
-        "allowed_keys": ["app_key", "button_id", "payload"],
+    "app_associated_resources_apply": {
+        "allowed_keys": [
+            "app_key",
+            "upsert_resources",
+            "patch_resources",
+            "remove_associated_item_ids",
+            "reorder_associated_item_ids",
+            "view_configs",
+            "upsert_resources[].client_key",
+            "upsert_resources[].associated_item_id",
+            "upsert_resources[].graph_type",
+            "upsert_resources[].target_app_key",
+            "upsert_resources[].view_key",
+            "upsert_resources[].chart_key",
+            "upsert_resources[].report_source",
+            "upsert_resources[].match_mappings",
+            "upsert_resources[].match_mappings[].target_field",
+            "upsert_resources[].match_mappings[].source_field",
+            "upsert_resources[].match_mappings[].value",
+            "upsert_resources[].match_mappings[].operator",
+            "upsert_resources[].match_rules",
+            "patch_resources[].associated_item_id",
+            "patch_resources[].set",
+            "patch_resources[].unset",
+            "view_configs[].view_key",
+            "view_configs[].visible",
+            "view_configs[].limit_type",
+            "view_configs[].associated_item_ids",
+            "view_configs[].associated_item_refs",
+        ],
         "aliases": {
-            "buttonId": "button_id",
-            "payload.buttonText": "payload.button_text",
-            "payload.stylePreset": "payload.style_preset",
-            "payload.backgroundColor": "payload.background_color",
-            "payload.textColor": "payload.text_color",
-            "payload.buttonIcon": "payload.button_icon",
-            "payload.triggerAction": "payload.trigger_action",
-            "payload.triggerLinkUrl": "payload.trigger_link_url",
-            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
-            "payload.externalQrobotConfig": "payload.external_qrobot_config",
-            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
-            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+            "upsertResources": "upsert_resources",
+            "patchResources": "patch_resources",
+            "resources": "upsert_resources",
+            "removeAssociatedItemIds": "remove_associated_item_ids",
+            "reorderAssociatedItemIds": "reorder_associated_item_ids",
+            "viewConfigs": "view_configs",
+            "associatedItemId": "associated_item_id",
+            "graphType": "graph_type",
+            "targetAppKey": "target_app_key",
+            "chartKey": "chart_key",
+            "chartId": "chart_key",
+            "viewKey": "view_key",
+            "viewgraphKey": "view_key",
+            "reportSource": "report_source",
+            "matchMappings": "match_mappings",
+            "matchRules": "match_rules",
+            "associatedItemRefs": "associated_item_refs",
+            "associatedItemIds": "associated_item_ids",
         },
         "allowed_values": {
-            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
-            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
-            "payload.button_icon": list(BUTTON_ICONS),
-            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
-            "payload.text_color": list(BUTTON_TEXT_COLORS),
+            "upsert_resources[].graph_type": ["chart", "view"],
+            "upsert_resources[].report_source": ["app", "dataset"],
+            "view_configs[].limit_type": ["all", "select"],
         },
         "execution_notes": [
-            "custom button writes now auto-publish the current app draft as a fixed closing step",
-            "background_color and text_color cannot both be white",
-            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
-            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+            "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
+            "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
+            "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
+            "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
+            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
+            "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
+            "graph_type=view uses view_key and internally compiles to the Qingflow view source; graph_type=chart uses chart_key and defaults to report_source=app",
+            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET for associating an existing dataset report; do not pass raw backend sourceType",
+            "use match_mappings for associated view/report filtering; dynamic conditions use source_field and static conditions use value",
+            "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",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "button_id": 1001,
-            "payload": {
-                "button_text": "查看详情",
-                "style_preset": "neutral_outline",
-                "button_icon": "ex-edit",
-                "trigger_action": "link",
-                "trigger_link_url": "https://example.com/detail",
-            },
-        },
-    },
-    "app_custom_button_delete": {
-        "allowed_keys": ["app_key", "button_id"],
-        "aliases": {"buttonId": "button_id"},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "button_id": 1001,
+            "upsert_resources": [
+                {
+                    "client_key": "customer_view",
+                    "graph_type": "view",
+                    "target_app_key": "TARGET_APP",
+                    "view_key": "VIEW_KEY",
+                    "match_mappings": [{"target_field": "关联员工", "source_field": "数据ID"}],
+                }
+            ],
+            "patch_resources": [
+                {
+                    "associated_item_id": 123,
+                    "set": {"match_mappings": [{"target_field": "状态", "value": "待提交"}]},
+                }
+            ],
+            "remove_associated_item_ids": [],
+            "reorder_associated_item_ids": [],
+            "view_configs": [
+                {
+                    "view_key": "MAIN_VIEW",
+                    "visible": True,
+                    "limit_type": "select",
+                    "associated_item_refs": ["customer_view"],
+                }
+            ],
         },
     },
     "app_schema_plan": {
@@ -2709,26 +4584,33 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
             "field.subfieldUpdates": "field.subfield_updates",
+            "field.asDataTitle": "field.as_data_title",
+            "field.asDataCover": "field.as_data_cover",
         },
         "allowed_values": {
             "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,
-            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "add_fields": [{"name": "项目名称", "type": "text", "as_data_title": True}],
             "update_fields": [],
             "remove_fields": [],
         },
@@ -2750,11 +4632,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",
@@ -2775,6 +4686,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
             "field.subfieldUpdates": "field.subfield_updates",
+            "field.asDataTitle": "field.as_data_title",
+            "field.asDataCover": "field.as_data_cover",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2789,8 +4702,16 @@ _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",
             "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
@@ -2806,20 +4727,59 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "code block outputs must be emitted through qf_output assignment; use qf_output = {...} or assign qf_output after building the result object, never const/let qf_output =",
             "builder automatically normalizes const/let qf_output assignments on write and rejects output-bound code blocks that still do not contain a valid qf_output assignment",
             "code_block_binding and q_linker_binding target fields are limited to text, long_text, number, amount, date, datetime, single_select, multi_select, and boolean",
+            "data title is required: mark exactly one top-level field with as_data_title=true; use a readable name/number/date-like field",
+            "data cover is optional: mark at most one top-level attachment field with as_data_cover=true",
         ],
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_id": 1001,
-            "icon": "template",
+            "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
             "publish": True,
-            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "add_fields": [
+                {"name": "项目名称", "type": "text", "as_data_title": True},
+                {"name": "项目封面", "type": "attachment", "as_data_cover": True},
+            ],
             "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",
@@ -2972,7 +4932,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "preset_example": {"profile": "default", "app_key": "APP_KEY", "mode": "merge", "preset": "balanced", "sections": []},
     },
     "app_layout_apply": {
-        "allowed_keys": ["app_key", "mode", "publish", "sections"],
+        "allowed_keys": ["app_key", "mode", "publish", "sections", "apps"],
         "aliases": {"overwrite": "replace", "sectionId": "section_id"},
         "section_allowed_keys": ["type", "paragraph_id", "section_id", "title", "rows"],
         "section_aliases": {
@@ -2985,8 +4945,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {"mode": [member.value for member in LayoutApplyMode]},
         "execution_notes": [
+            "mode=merge is the layout partial update path: mentioned sections are merged and unmentioned fields are preserved",
+            "mode=replace is full layout replacement and should be used only when intentionally rewriting all sections",
             "layout verification is split into layout_verified and layout_summary_verified",
             "LAYOUT_SUMMARY_UNVERIFIED means raw form readback is stronger than the compact summary",
+            "accepts apps[] for multi-app batch; each item is {app_key, mode?, sections, publish?}; top-level publish is used as default for items that omit publish",
         ],
         "minimal_section_example": {"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B", "字段C", "字段D"]]},
         "minimal_example": {
@@ -2996,96 +4959,95 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "publish": True,
             "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["项目名称", "项目负责人", "项目阶段", "优先级"]]}],
         },
-    },
-    "app_flow_plan": {
-        "allowed_keys": ["app_key", "mode", "nodes", "transitions", "preset"],
-        "aliases": {
-            "overwrite": "replace",
-            "base_preset": "preset",
-            "default_approval": "basic_approval",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-            "default_approval": "basic_approval",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "preset": [member.value for member in FlowPreset],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
+        "batch_example": {
+            "profile": "default",
+            "publish": True,
+            "apps": [
+                {"app_key": "APP_KEY_1", "mode": "merge", "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B"]]}]},
+                {"app_key": "APP_KEY_2", "mode": "merge", "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段C", "字段D"]]}]},
+            ],
         },
-        "dependency_hints": [
-            "approval-style workflows require an explicit status field",
-            "approve/fill/copy nodes require at least one assignee",
+    },
+    "app_flow_get_schema": {
+        "allowed_keys": ["schema_version"],
+        "aliases": {"schemaVersion": "schema_version"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns WorkflowSpec JSON Schema from /workflow/spec/schema",
+            "call this before authoring a new spec or validating spec shape",
+            "worksheet-level approval deduplication toggles (legacy global settings) are not yet part of WorkflowSpec",
         ],
+        "minimal_example": {
+            "profile": "default",
+            "schema_version": "vnext-2026-06",
+        },
+    },
+    "app_flow_get": {
+        "allowed_keys": ["app_key", "version_id"],
+        "aliases": {"versionId": "version_id"},
+        "allowed_values": {},
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "returns current WorkflowSpecDTO for one app via GET /workflow/spec",
+            "use GET-first before patching and app_flow_apply",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
-            "preset": "basic_approval",
-            "nodes": [
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                }
-            ],
-            "transitions": [],
         },
     },
     "app_flow_apply": {
-        "allowed_keys": ["app_key", "mode", "publish", "nodes", "transitions"],
+        "allowed_keys": ["app_key", "publish", "spec", "idempotency_key", "schema_version", "patch_nodes"],
         "aliases": {
-            "overwrite": "replace",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
+            "schemaVersion": "schema_version",
+            "idempotencyKey": "idempotency_key",
         },
+        "allowed_values": {},
         "dependency_hints": [
-            "approval-style workflows require an explicit status field",
-            "approve/fill/copy nodes require at least one assignee",
+            "when using spec: must be a complete WorkflowSpecDTO object (replace-only apply); when using patch_nodes[]: spec is not required",
+            "use patch_nodes[] instead of spec when updating only specific nodes; patch_nodes reads current flow, merges set/unset, then writes back — spec is not needed when patch_nodes is supplied",
         ],
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
-            "workflow verification only covers linear node structure in the public tool surface",
+            "posts to /workflow/spec:apply with appKey, idempotencyKey, schemaVersion, and spec",
+            "verification uses appliedSpec, diffSummary, and semanticLint from the apply response",
+            "publish=false keeps changes in draft when supported by the backend",
+            "patch_nodes[] items are {id, set, unset}; id must match an existing node id from app_get_flow.spec.nodes; FLOW_NODE_NOT_FOUND is returned if id is missing",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
             "publish": True,
-            "nodes": [
-                {"id": "start", "type": "start", "name": "发起"},
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                },
-                {"id": "end", "type": "end", "name": "结束"},
-            ],
-            "transitions": [{"from": "start", "to": "approve_1"}, {"from": "approve_1", "to": "end"}],
+            "spec": {
+                "nodes": [{"id": "n1", "type": "APPLICANT", "name": "发起"}],
+                "transitions": [],
+            },
+        },
+        "patch_nodes_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "patch_nodes": [{"id": "approve_1", "set": {"name": "总监审批", "assignees": {"role_names": ["总监"]}}}],
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
+        "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",
@@ -3096,6 +5058,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3113,11 +5079,18 @@ _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": [
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "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",
+            "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,
         ],
@@ -3127,6 +5100,41 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
+        "query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "patch_views": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "set": {
+                        "query_conditions": {
+                            "enabled": True,
+                            "rows": [["客户名称", "负责人"], ["创建时间"]],
+                        }
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
+        "full_upsert_query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "客户查询视图",
+                    "type": "table",
+                    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+                    "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
+                    "query_conditions": {
+                        "enabled": True,
+                        "exact": False,
+                        "hide_before_query": False,
+                        "rows": [["客户名称", "负责人"], ["创建时间"]],
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3145,7 +5153,26 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
+        "allowed_keys": [
+            "app_key",
+            "apps",
+            "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",
@@ -3156,6 +5183,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3172,17 +5203,25 @@ _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": [
             "apply may return partial_success when some views land and others fail",
             "when duplicate view names exist, supply view_key to target the exact view",
-            "read back app_get_views after any failed or partial view apply",
+            "read back app_get after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "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",
+            "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",
+            "accepts apps[] for multi-app batch; each item is {app_key, upsert_views?, patch_views?, remove_views?, publish?}; top-level publish is used as default for items that omit publish",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
@@ -3192,6 +5231,43 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
+        "query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "patch_views": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "set": {
+                        "query_conditions": {
+                            "enabled": True,
+                            "rows": [["客户名称", "负责人"], ["创建时间"]],
+                        }
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
+        "full_upsert_query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "客户查询视图",
+                    "type": "table",
+                    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+                    "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
+                    "query_conditions": {
+                        "enabled": True,
+                        "exact": False,
+                        "hide_before_query": False,
+                        "rows": [["客户名称", "负责人"], ["创建时间"]],
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3215,12 +5291,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns builder-side app configuration summary and editability",
-            "use this as the default builder discovery read before fields/layout/views/flow/charts detail reads",
+            "returns builder-side app map: base summary, editability, field/view/chart/button counts, compact views, compact charts, custom_buttons, and app-level associated_resources",
+            "use this as the default builder discovery read before view_get/chart_get/apply detail work",
             "editability is route-aware builder capability summary, not end-user data visibility",
             "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility",
             "can_edit_form covers form/schema routes only and does not imply app base-info writes",
             "returns normalized app visibility when backend auth is readable",
+            "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
+            "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3228,13 +5306,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_fields": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "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",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, fields}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3242,12 +5323,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_layout": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
             "returns compact current layout configuration for one app",
             "use this before app_layout_apply when you need paragraph and row structure",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, sections}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3255,13 +5337,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_views": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
             "returns compact current view inventory for one app",
-            "use this before app_views_apply when you need exact current view keys",
+            "compatibility/specialized inventory tool; default builder discovery should start with app_get",
+            "use this before app_views_apply only when you need an exact current view inventory beyond app_get",
             "view items include visibility_summary when backend view auth is readable",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, views}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3269,12 +5353,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_flow": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns workflow configuration summary for one app",
-            "use this before app_flow_apply when you need the current node structure",
+            "returns WorkflowSpecDTO for one app (alias of app_flow_get)",
+            "use app_flow_get_schema then app_flow_get before app_flow_apply",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, spec}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3282,14 +5367,46 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_charts": {
-        "allowed_keys": ["app_key"],
+        "allowed_keys": ["app_key", "app_keys"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
             "returns a compact current chart inventory for one app",
-            "use this before app_charts_apply when you need exact current chart_id values",
+            "compatibility/specialized inventory tool; default builder discovery should start with app_get",
+            "use this before app_charts_apply when you need exact current chart_id values beyond the app_get summary",
             "chart summaries do not include full qingbi config payloads",
             "chart items include visibility_summary when QingBI base info is readable",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, charts}",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_buttons": {
+        "allowed_keys": ["app_key", "app_keys"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns custom button list (draft state) for one app",
+            "also returns view_configs read from view bindings, so app_custom_buttons_apply view_configs can be patched from the same read result",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single-read fields such as {app_key, buttons, view_configs, warnings, verification}",
+            "use before app_custom_buttons_apply when you need current button_id values",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_associated_resources": {
+        "allowed_keys": ["app_key", "app_keys"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns associated resource pool (draft state) for one app",
+            "also returns view_configs read from view bindings, so app_associated_resources_apply view_configs can be patched from the same read result",
+            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single-read fields such as {app_key, associated_resources, view_configs, warnings, verification}",
+            "use before app_associated_resources_apply when you need current associated_item_id values",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3326,8 +5443,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_charts_apply": {
-        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids", "upsert_charts[].visibility"],
+        "allowed_keys": ["app_key", "apps", "upsert_charts", "patch_charts", "remove_chart_ids", "reorder_chart_ids", "upsert_charts[].visibility", "patch_charts[].chart_id", "patch_charts[].name", "patch_charts[].set", "patch_charts[].unset"],
         "aliases": {
+            "patchCharts": "patch_charts",
             "chart.id": "chart.chart_id",
             "chart.type": "chart.chart_type",
             "chart.dimension_fields": "chart.dimension_field_ids",
@@ -3341,18 +5459,31 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
             "execution_notes": [
+                "this tool manages QingBI report bodies/configs; it does not attach reports to Qingflow app associated-resource display",
+                "app_charts_apply creates/updates app-source QingBI reports only; generated payloads use dataSourceType=qingflow",
+                "dataset BI reports are not created or edited by this tool yet; create them in QingBI first, then attach the existing report with app_associated_resources_apply report_source=dataset",
+                "after creating or updating an app-source report body, use app_associated_resources_apply when the report should appear inside a Qingflow app/view",
                 "app_charts_apply is immediate-live and does not publish",
+                "use patch_charts for partial parameter replacement on existing charts; the tool reads current chart base/config, merges patch_charts[].set/unset, then submits full QingBI base/config payloads internally",
                 "chart matching precedence is chart_id first, then exact unique chart name",
                 "when chart names are not unique, supply chart_id instead of guessing by name",
                 "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",
+                "accepts apps[] for multi-app batch; each item is {app_key, upsert_charts?, patch_charts?, remove_chart_ids?, reorder_chart_ids?}",
                 *_VISIBILITY_EXECUTION_NOTES,
             ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
             "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "patch_charts": [{"chart_id": "CHART_ID", "set": {"name": "数据总量-新版"}}],
             "remove_chart_ids": [],
             "reorder_chart_ids": [],
         },
@@ -3364,6 +5495,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns one builder-side view definition detail",
             "does not return record data; use user-side view_get or record_list for runtime rows",
+            "view_key is a raw builder view key; if a record-data custom:VIEW_KEY value is passed, the tool normalizes it to VIEW_KEY",
             "use this after builder portal_get when a component references a view_ref.view_key",
             "returns normalized view visibility when backend auth is readable",
         ],
@@ -3388,9 +5520,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", "patch_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",
@@ -3403,19 +5536,35 @@ _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",
-                "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",
+        "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",
+            "use patch_sections[] for targeted section updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
+            "when sections[] is supplied without patch_sections[], it uses replace semantics for all sections",
+            "remove a section by omitting it from the sections list (replace mode) or by unset in patch_sections (patch mode)",
+            "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/chart_key first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
+            "pc layout uses a 24-column grid; mobile layout uses a 6-column grid",
+            "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,
@@ -3424,7 +5573,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": [
                 {
@@ -3438,6 +5590,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",
@@ -3447,6 +5616,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 8},
             },
         },
+        "patch_sections_example": {
+            "profile": "default",
+            "dash_key": "DASH_KEY",
+            "publish": True,
+            "patch_sections": [
+                {"chart_ref": {"chart_id": "CHART_ID"}, "set": {"title": "销售总览-新版"}},
+                {"order": 2, "set": {"title": "任务列表-新版"}},
+            ],
+        },
     },
     "app_publish_verify": {
         "allowed_keys": ["app_key", "expected_package_id"],
@@ -3485,7 +5663,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
 _PRIVATE_BUILDER_TOOL_CONTRACTS = {
     "app_schema_plan",
     "app_layout_plan",
-    "app_flow_plan",
     "app_views_plan",
 }