@josephyan/qingflow-cli 0.2.0-beta.55

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -0,0 +1,2063 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+import time
+
+from pydantic import ValidationError
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError
+from ..json_types import JSONObject
+from ..builder_facade.models import (
+    ChartApplyRequest,
+    FIELD_TYPE_ID_ALIASES,
+    FieldPatch,
+    FieldRemovePatch,
+    FieldUpdatePatch,
+    FlowPreset,
+    FlowNodePatch,
+    FlowPlanRequest,
+    FlowTransitionPatch,
+    LayoutApplyMode,
+    LayoutPlanRequest,
+    LayoutPreset,
+    LayoutSectionPatch,
+    PortalApplyRequest,
+    PublicFieldType,
+    PublicRelationMode,
+    PublicChartType,
+    PublicViewType,
+    SchemaPlanRequest,
+    ViewFilterOperator,
+    ViewUpsertPatch,
+    ViewsPreset,
+    ViewsPlanRequest,
+)
+from ..builder_facade.service import AiBuilderFacade
+from .app_tools import AppTools
+from .base import ToolBase
+from .directory_tools import DirectoryTools
+from .package_tools import PackageTools
+from .portal_tools import PortalTools
+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"]
+
+
+class AiBuilderTools(ToolBase):
+    def __init__(self, sessions, backend) -> None:
+        super().__init__(sessions, backend)
+        self._facade = AiBuilderFacade(
+            apps=AppTools(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),
+            directory=DirectoryTools(sessions, backend),
+            solutions=SolutionTools(sessions, backend),
+        )
+
+    def register(self, mcp) -> None:
+        @mcp.tool()
+        def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all") -> JSONObject:
+            return self.package_list(profile=profile, trial_status=trial_status)
+
+        @mcp.tool()
+        def package_resolve(profile: str = DEFAULT_PROFILE, package_name: str = "") -> JSONObject:
+            return self.package_resolve(profile=profile, package_name=package_name)
+
+        @mcp.tool()
+        def builder_tool_contract(tool_name: str = "") -> JSONObject:
+            return self.builder_tool_contract(tool_name=tool_name)
+
+        @mcp.tool()
+        def package_create(profile: str = DEFAULT_PROFILE, package_name: str = "") -> JSONObject:
+            return self.package_create(profile=profile, package_name=package_name)
+
+        @mcp.tool()
+        def member_search(
+            profile: str = DEFAULT_PROFILE,
+            query: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+            contain_disable: bool = False,
+        ) -> JSONObject:
+            return self.member_search(
+                profile=profile,
+                query=query,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            )
+
+        @mcp.tool()
+        def role_search(
+            profile: str = DEFAULT_PROFILE,
+            keyword: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+        ) -> JSONObject:
+            return self.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+        @mcp.tool()
+        def role_create(
+            profile: str = DEFAULT_PROFILE,
+            role_name: str = "",
+            member_uids: list[int] | None = None,
+            member_emails: list[str] | None = None,
+            member_names: list[str] | None = None,
+            role_icon: str = "ex-user-outlined",
+        ) -> JSONObject:
+            return self.role_create(
+                profile=profile,
+                role_name=role_name,
+                member_uids=member_uids or [],
+                member_emails=member_emails or [],
+                member_names=member_names or [],
+                role_icon=role_icon,
+            )
+
+        @mcp.tool()
+        def package_attach_app(
+            profile: str = DEFAULT_PROFILE,
+            tag_id: int = 0,
+            app_key: str = "",
+            app_title: str = "",
+        ) -> JSONObject:
+            return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
+
+        @mcp.tool()
+        def app_release_edit_lock_if_mine(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            lock_owner_email: str = "",
+            lock_owner_name: str = "",
+        ) -> JSONObject:
+            return self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+
+        @mcp.tool()
+        def app_resolve(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            app_name: str = "",
+            package_tag_id: int | None = None,
+        ) -> JSONObject:
+            return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
+
+        @mcp.tool()
+        def app_read_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_summary(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_read_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_fields(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_read_layout_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_layout_summary(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_read_views_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_views_summary(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_read_flow_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_flow_summary(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_read_charts_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_read_charts_summary(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def portal_read_summary(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+            being_draft: bool = True,
+        ) -> JSONObject:
+            return self.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft)
+
+        @mcp.tool()
+        def app_schema_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            package_tag_id: int | None = None,
+            app_name: str = "",
+            app_title: str = "",
+            create_if_missing: bool = False,
+            publish: bool = True,
+            add_fields: list[JSONObject] | None = None,
+            update_fields: list[JSONObject] | None = None,
+            remove_fields: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.app_schema_apply(
+                profile=profile,
+                app_key=app_key,
+                package_tag_id=package_tag_id,
+                app_name=app_name,
+                app_title=app_title,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=add_fields or [],
+                update_fields=update_fields or [],
+                remove_fields=remove_fields or [],
+            )
+
+        @mcp.tool()
+        def app_layout_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            mode: str = "merge",
+            publish: bool = True,
+            sections: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
+
+        @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,
+        ) -> JSONObject:
+            return self.app_flow_apply(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                nodes=nodes or [],
+                transitions=transitions or [],
+            )
+
+        @mcp.tool()
+        def app_views_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            publish: bool = True,
+            upsert_views: list[JSONObject] | None = None,
+            remove_views: list[str] | None = None,
+        ) -> JSONObject:
+            return self.app_views_apply(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                upsert_views=upsert_views or [],
+                remove_views=remove_views or [],
+            )
+
+        @mcp.tool()
+        def app_charts_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            upsert_charts: list[JSONObject] | None = None,
+            remove_chart_ids: list[str] | None = None,
+            reorder_chart_ids: list[str] | None = None,
+        ) -> JSONObject:
+            return self.app_charts_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_charts=upsert_charts or [],
+                remove_chart_ids=remove_chart_ids or [],
+                reorder_chart_ids=reorder_chart_ids or [],
+            )
+
+        @mcp.tool()
+        def portal_apply(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+            dash_name: str = "",
+            package_tag_id: int | None = None,
+            publish: bool = True,
+            sections: list[JSONObject] | None = None,
+            auth: JSONObject | None = None,
+            icon: str | None = None,
+            color: str | None = None,
+            hide_copyright: bool | None = None,
+            dash_global_config: JSONObject | None = None,
+            config: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.portal_apply(
+                profile=profile,
+                dash_key=dash_key,
+                dash_name=dash_name,
+                package_tag_id=package_tag_id,
+                publish=publish,
+                sections=sections or [],
+                auth=auth,
+                icon=icon,
+                color=color,
+                hide_copyright=hide_copyright,
+                dash_global_config=dash_global_config,
+                config=config or {},
+            )
+
+        @mcp.tool()
+        def app_publish_verify(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            expected_package_tag_id: int | None = None,
+        ) -> JSONObject:
+            return self.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_tag_id=expected_package_tag_id,
+            )
+
+    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+        normalized_args = {"trial_status": trial_status}
+        return _safe_tool_call(
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            error_code="PACKAGE_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+        )
+
+    def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_resolve(profile=profile, package_name=package_name),
+            error_code="PACKAGE_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": package_name}},
+        )
+
+    def builder_tool_contract(self, *, tool_name: str) -> JSONObject:
+        requested = str(tool_name or "").strip()
+        public_tool_names = sorted(
+            name
+            for name in _BUILDER_TOOL_CONTRACTS.keys()
+            if name not in _PRIVATE_BUILDER_TOOL_CONTRACTS and name not in _BUILDER_TOOL_CONTRACT_ALIASES
+        )
+        if requested in _PRIVATE_BUILDER_TOOL_CONTRACTS:
+            lookup_name = ""
+        elif requested in _BUILDER_TOOL_CONTRACTS:
+            lookup_name = requested
+        else:
+            lookup_name = _BUILDER_TOOL_CONTRACT_ALIASES.get(requested, requested)
+        contract = _BUILDER_TOOL_CONTRACTS.get(lookup_name)
+        if contract is None:
+            return {
+                "status": "failed",
+                "error_code": "TOOL_CONTRACT_NOT_FOUND",
+                "recoverable": True,
+                "message": "tool contract is not defined for the requested public builder tool",
+                "normalized_args": {"tool_name": requested},
+                "missing_fields": [],
+                "allowed_values": {"tool_name": public_tool_names},
+                "details": {"reason_path": "tool_name"},
+                "suggested_next_call": None,
+            "request_id": None,
+            "backend_code": None,
+            "http_status": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {},
+            "verified": False,
+        }
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "loaded builder tool contract",
+            "normalized_args": {"tool_name": requested},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "suggested_next_call": None,
+            "request_id": None,
+            "backend_code": None,
+            "http_status": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {},
+            "verified": True,
+            "tool_name": requested,
+            "contract": contract,
+        }
+
+    def package_create(self, *, profile: str, package_name: str) -> JSONObject:
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_create(profile=profile, package_name=package_name),
+            error_code="PACKAGE_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_create", "arguments": {"profile": profile, "package_name": package_name}},
+        )
+
+    def member_search(
+        self,
+        *,
+        profile: str,
+        query: str,
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> JSONObject:
+        normalized_args = {
+            "query": query,
+            "page_num": page_num,
+            "page_size": page_size,
+            "contain_disable": contain_disable,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.member_search(
+                profile=profile,
+                query=query,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            ),
+            error_code="MEMBER_SEARCH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
+        normalized_args = {"keyword": keyword, "page_num": page_num, "page_size": page_size}
+        return _safe_tool_call(
+            lambda: self._facade.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size),
+            error_code="ROLE_SEARCH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def role_create(
+        self,
+        *,
+        profile: str,
+        role_name: str,
+        member_uids: list[int],
+        member_emails: list[str],
+        member_names: list[str],
+        role_icon: str = "ex-user-outlined",
+    ) -> JSONObject:
+        normalized_args = {
+            "role_name": role_name,
+            "member_uids": member_uids,
+            "member_emails": member_emails,
+            "member_names": member_names,
+            "role_icon": role_icon,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.role_create(
+                profile=profile,
+                role_name=role_name,
+                member_uids=member_uids,
+                member_emails=member_emails,
+                member_names=member_names,
+                role_icon=role_icon,
+            ),
+            error_code="ROLE_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "role_create", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
+        normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
+        result = _safe_tool_call(
+            lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
+            error_code="PACKAGE_ATTACH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.package_attach_app(
+                profile=profile,
+                tag_id=tag_id,
+                app_key=app_key,
+                app_title=app_title,
+            ),
+        )
+
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            ),
+            error_code="EDIT_LOCK_RELEASE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_resolve(self, *, profile: str, app_key: str = "", app_name: str = "", package_tag_id: int | None = None) -> JSONObject:
+        normalized_args = {"app_key": app_key, "app_name": app_name, "package_tag_id": package_tag_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id),
+            error_code="APP_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
+            error_code="APP_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_fields(profile=profile, app_key=app_key),
+            error_code="FIELDS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_layout_summary(profile=profile, app_key=app_key),
+            error_code="LAYOUT_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_views_summary(profile=profile, app_key=app_key),
+            error_code="VIEWS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
+            error_code="FLOW_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_read_charts_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_charts_summary(profile=profile, app_key=app_key),
+            error_code="CHARTS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_charts_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
+        return _safe_tool_call(
+            lambda: self._facade.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft),
+            error_code="PORTAL_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "portal_read_summary", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_schema_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        package_tag_id: int | None = None,
+        app_name: str = "",
+        create_if_missing: bool = False,
+        add_fields: list[JSONObject],
+        update_fields: list[JSONObject],
+        remove_fields: list[JSONObject],
+    ) -> JSONObject:
+        try:
+            request = SchemaPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "package_tag_id": package_tag_id,
+                    "app_name": app_name,
+                    "create_if_missing": create_if_missing,
+                    "add_fields": add_fields,
+                    "update_fields": update_fields,
+                    "remove_fields": remove_fields,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_schema_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_schema_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "package_tag_id": package_tag_id,
+                        "app_name": app_name,
+                        "create_if_missing": create_if_missing,
+                        "add_fields": [{"name": "字段名称", "type": "text"}],
+                        "update_fields": [],
+                        "remove_fields": [],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_schema_plan(profile=profile, request=request),
+            error_code="SCHEMA_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
+    def app_layout_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "merge",
+        sections: list[JSONObject] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        try:
+            request = LayoutPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "mode": mode,
+                    "sections": sections or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_layout_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_layout_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "mode": "merge",
+                        "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_plan(profile=profile, request=request),
+            error_code="LAYOUT_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
+    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")}},
+        )
+
+    def app_views_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_views: list[JSONObject] | None = None,
+        remove_views: list[str] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        try:
+            request = ViewsPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "upsert_views": upsert_views or [],
+                    "remove_views": remove_views or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_views_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_views_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "preset": "default_table",
+                        "upsert_views": [],
+                        "remove_views": [],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_views_plan(profile=profile, request=request),
+            error_code="VIEWS_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
+    def app_schema_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        package_tag_id: int | None = None,
+        app_name: str = "",
+        app_title: str = "",
+        create_if_missing: bool = False,
+        publish: bool = True,
+        add_fields: list[JSONObject],
+        update_fields: list[JSONObject],
+        remove_fields: list[JSONObject],
+    ) -> JSONObject:
+        result = self._app_schema_apply_once(
+            profile=profile,
+            app_key=app_key,
+            package_tag_id=package_tag_id,
+            app_name=app_name,
+            app_title=app_title,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            add_fields=add_fields,
+            update_fields=update_fields,
+            remove_fields=remove_fields,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_schema_apply_once(
+                profile=profile,
+                app_key=app_key,
+                package_tag_id=package_tag_id,
+                app_name=app_name,
+                app_title=app_title,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=add_fields,
+                update_fields=update_fields,
+                remove_fields=remove_fields,
+            ),
+        )
+
+    def _app_schema_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        package_tag_id: int | None = None,
+        app_name: str = "",
+        app_title: str = "",
+        create_if_missing: bool = False,
+        publish: bool = True,
+        add_fields: list[JSONObject],
+        update_fields: list[JSONObject],
+        remove_fields: list[JSONObject],
+    ) -> JSONObject:
+        effective_app_name = app_name or app_title
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_schema_plan(
+                profile=profile,
+                app_key=app_key,
+                package_tag_id=package_tag_id,
+                app_name=effective_app_name,
+                create_if_missing=create_if_missing,
+                add_fields=add_fields,
+                update_fields=update_fields,
+                remove_fields=remove_fields,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_schema_plan",
+            apply_tool_name="app_schema_apply",
+        )
+        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:
+            parsed_add = [FieldPatch.model_validate(item) for item in plan_args.get("add_fields") or []]
+            parsed_update = [FieldUpdatePatch.model_validate(item) for item in plan_args.get("update_fields") or []]
+            parsed_remove = [FieldRemovePatch.model_validate(item) for item in plan_args.get("remove_fields") or []]
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_schema_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_schema_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
+                        "app_name": str(plan_args.get("app_name") or effective_app_name),
+                        "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+                        "publish": publish,
+                        "add_fields": plan_args.get("add_fields") or [{"name": "字段名称", "type": "text", "required": False}],
+                        "update_fields": plan_args.get("update_fields") or [],
+                        "remove_fields": plan_args.get("remove_fields") or [],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
+            "app_name": str(plan_args.get("app_name") or effective_app_name),
+            "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+            "publish": publish,
+            "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
+            "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
+            "remove_fields": [patch.model_dump(mode="json") for patch in parsed_remove],
+        }
+        result = _safe_tool_call(
+            lambda: self._facade.app_schema_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                package_tag_id=plan_args.get("package_tag_id", package_tag_id),
+                app_name=str(plan_args.get("app_name") or effective_app_name),
+                create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
+                publish=publish,
+                add_fields=parsed_add,
+                update_fields=parsed_update,
+                remove_fields=parsed_remove,
+            ),
+            error_code="SCHEMA_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return result
+
+    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        result = self._app_layout_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            sections=sections,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_layout_apply_once(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                sections=sections,
+            ),
+        )
+
+    def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_layout_plan(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                sections=sections,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_layout_plan",
+            apply_tool_name="app_layout_apply",
+        )
+        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:
+            parsed_mode = LayoutApplyMode(str(plan_args.get("mode") or mode))
+            parsed_sections = [LayoutSectionPatch.model_validate(item) for item in plan_args.get("sections") or []]
+        except (ValueError, ValidationError) as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_layout_apply",
+                exc=exc if isinstance(exc, ValidationError) else None,
+                suggested_next_call={
+                    "tool_name": "app_layout_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "mode": str(plan_args.get("mode") or "merge"),
+                        "publish": publish,
+                        "sections": plan_args.get("sections") or [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "mode": parsed_mode.value,
+            "publish": publish,
+            "sections": [section.model_dump(mode="json") for section in parsed_sections],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                mode=parsed_mode,
+                publish=publish,
+                sections=parsed_sections,
+            ),
+            error_code="LAYOUT_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_flow_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[JSONObject],
+        transitions: list[JSONObject],
+    ) -> JSONObject:
+        result = self._app_flow_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            nodes=nodes,
+            transitions=transitions,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_flow_apply_once(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                nodes=nodes,
+                transitions=transitions,
+            ),
+        )
+
+    def _app_flow_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[JSONObject],
+        transitions: list[JSONObject],
+    ) -> JSONObject:
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_flow_plan(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                nodes=nodes,
+                transitions=transitions,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_flow_plan",
+            apply_tool_name="app_flow_apply",
+        )
+        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}},
+        )
+
+    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(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_views_apply_once(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                remove_views=remove_views,
+                upsert_views=upsert_views,
+            ),
+        )
+
+    def _app_views_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        publish: bool = True,
+        upsert_views: list[JSONObject],
+        remove_views: list[str],
+    ) -> JSONObject:
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_views_plan(
+                profile=profile,
+                app_key=app_key,
+                upsert_views=upsert_views,
+                remove_views=remove_views,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_views_plan",
+            apply_tool_name="app_views_apply",
+        )
+        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:
+            parsed_views = [ViewUpsertPatch.model_validate(item) for item in plan_args.get("upsert_views") or []]
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_views_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_views_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "publish": publish,
+                        "upsert_views": plan_args.get("upsert_views") or [{"name": "全部数据", "type": "table", "columns": ["字段A"]}],
+                        "remove_views": plan_args.get("remove_views") or [],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "publish": publish,
+            "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+            "remove_views": list(plan_args.get("remove_views") or remove_views),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_views_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                publish=publish,
+                upsert_views=parsed_views,
+                remove_views=list(plan_args.get("remove_views") or remove_views),
+            ),
+            error_code="VIEWS_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def chart_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_charts: list[JSONObject],
+        remove_chart_ids: list[str],
+        reorder_chart_ids: list[str],
+    ) -> JSONObject:
+        return self.app_charts_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_charts=upsert_charts,
+            remove_chart_ids=remove_chart_ids,
+            reorder_chart_ids=reorder_chart_ids,
+        )
+
+    def app_charts_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_charts: list[JSONObject],
+        remove_chart_ids: list[str],
+        reorder_chart_ids: list[str],
+    ) -> JSONObject:
+        try:
+            request = ChartApplyRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "upsert_charts": upsert_charts or [],
+                    "remove_chart_ids": remove_chart_ids or [],
+                    "reorder_chart_ids": reorder_chart_ids or [],
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_charts_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_charts_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "upsert_charts": [{"name": "销售总量", "chart_type": "target", "indicator_field_ids": []}],
+                        "remove_chart_ids": [],
+                        "reorder_chart_ids": [],
+                    },
+                },
+            )
+        normalized_args = request.model_dump(mode="json")
+        return _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}},
+        )
+
+    def portal_apply(
+        self,
+        *,
+        profile: str,
+        dash_key: str = "",
+        dash_name: str = "",
+        package_tag_id: int | None = None,
+        publish: bool = True,
+        sections: list[JSONObject],
+        auth: JSONObject | None = None,
+        icon: str | None = None,
+        color: str | None = None,
+        hide_copyright: bool | None = None,
+        dash_global_config: JSONObject | None = None,
+        config: 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_tag_id,
+                    "publish": publish,
+                    "sections": sections or [],
+                    "auth": auth,
+                    "icon": icon,
+                    "color": color,
+                    "hide_copyright": hide_copyright,
+                    "dash_global_config": dash_global_config,
+                    "config": config or {},
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="portal_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "portal_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "dash_name": dash_name or "业务门户",
+                        "package_tag_id": package_tag_id or 1001,
+                        "publish": True,
+                        "sections": [
+                            {
+                                "title": "经营概览",
+                                "source_type": "text",
+                                "text": "欢迎使用业务门户",
+                            }
+                        ],
+                    },
+                },
+            )
+        normalized_args = request.model_dump(mode="json")
+        return _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}},
+        )
+
+    def app_publish_verify(self, *, profile: str, app_key: str, expected_package_tag_id: int | None = None) -> JSONObject:
+        normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
+        result = _safe_tool_call(
+            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id),
+            error_code="PUBLISH_VERIFY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_tag_id=expected_package_tag_id,
+            ),
+        )
+
+    def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
+        if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
+            return result
+        suggested = result.get("suggested_next_call")
+        if not isinstance(suggested, dict) or suggested.get("tool_name") != "app_release_edit_lock_if_mine":
+            return result
+        arguments = suggested.get("arguments")
+        if not isinstance(arguments, dict):
+            return result
+        app_key = str(arguments.get("app_key") or "")
+        lock_owner_email = str(arguments.get("lock_owner_email") or "")
+        lock_owner_name = str(arguments.get("lock_owner_name") or "")
+        release_attempts: list[JSONObject] = []
+        retried: JSONObject = result
+        for _ in range(3):
+            release_result = self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+            release_attempts.append(release_result)
+            if not isinstance(release_result, dict) or release_result.get("status") != "success":
+                result.setdefault("details", {})
+                if isinstance(result["details"], dict):
+                    result["details"]["edit_lock_release_result"] = release_result
+                    result["details"]["edit_lock_release_attempts"] = release_attempts
+                return result
+            retried = retry_call()
+            if not (
+                isinstance(retried, dict)
+                and retried.get("status") == "failed"
+                and retried.get("error_code") == "APP_EDIT_LOCKED"
+            ):
+                break
+            time.sleep(0.2)
+        if (
+            isinstance(retried, dict)
+            and retried.get("status") == "failed"
+            and retried.get("error_code") == "APP_EDIT_LOCKED"
+        ):
+            retried = {
+                **retried,
+                "error_code": "PERSISTENT_SELF_LOCK",
+                "message": "app remains locked by the current user's active editor session after repeated forced release attempts",
+                "recoverable": True,
+                "suggested_next_call": None,
+            }
+        if isinstance(retried, dict):
+            retried.setdefault("details", {})
+            if isinstance(retried["details"], dict):
+                retried["details"]["edit_lock_release_result"] = release_attempts[-1] if release_attempts else None
+                retried["details"]["edit_lock_release_attempts"] = release_attempts
+            retried["edit_lock_released"] = bool(release_attempts)
+            retried["retried_after_edit_lock_release"] = True
+        return retried
+
+    def _rewrite_plan_result_for_apply(
+        self,
+        *,
+        result: JSONObject,
+        profile: str,
+        publish: bool,
+        plan_tool_name: str,
+        apply_tool_name: str,
+    ) -> JSONObject:
+        if not isinstance(result, dict):
+            return result
+        rewritten = dict(result)
+        if rewritten.get("error_code") == "VALIDATION_ERROR":
+            contract = _BUILDER_TOOL_CONTRACTS.get(apply_tool_name)
+            details = rewritten.get("details")
+            if not isinstance(details, dict):
+                details = {}
+                rewritten["details"] = details
+            if isinstance(contract, dict):
+                rewritten["allowed_values"] = deepcopy(contract.get("allowed_values", {}))
+                details["allowed_keys"] = deepcopy(contract.get("allowed_keys", []))
+                details["section_allowed_keys"] = deepcopy(contract.get("section_allowed_keys", []))
+                details["section_aliases"] = deepcopy(contract.get("section_aliases", {}))
+                details["minimal_section_example"] = deepcopy(contract.get("minimal_section_example"))
+        suggested_next_call = rewritten.get("suggested_next_call")
+        if isinstance(suggested_next_call, dict):
+            if suggested_next_call.get("tool_name") == plan_tool_name:
+                arguments = suggested_next_call.get("arguments")
+                normalized_arguments = dict(arguments) if isinstance(arguments, dict) else {}
+                normalized_arguments.setdefault("profile", profile)
+                normalized_arguments["publish"] = publish
+                rewritten["suggested_next_call"] = {
+                    **suggested_next_call,
+                    "tool_name": apply_tool_name,
+                    "arguments": normalized_arguments,
+                }
+                return rewritten
+            if rewritten.get("error_code") == "VALIDATION_ERROR" and suggested_next_call.get("tool_name") == apply_tool_name:
+                arguments = suggested_next_call.get("arguments")
+                normalized_arguments = dict(arguments) if isinstance(arguments, dict) else {}
+                normalized_arguments.setdefault("profile", profile)
+                normalized_arguments["publish"] = publish
+                if isinstance(details, dict):
+                    details["canonical_arguments"] = normalized_arguments
+                rewritten["suggested_next_call"] = {
+                    **suggested_next_call,
+                    "arguments": normalized_arguments,
+                }
+        if rewritten.get("status") == "success":
+            normalized_args = rewritten.get("normalized_args")
+            if isinstance(normalized_args, dict):
+                rewritten["suggested_next_call"] = {
+                    "tool_name": apply_tool_name,
+                    "arguments": {"profile": profile, **normalized_args, "publish": publish},
+                }
+        return rewritten
+
+
+def _validation_failure(
+    detail: str,
+    *,
+    tool_name: str | None = None,
+    exc: ValidationError | None = None,
+    suggested_next_call: JSONObject | None = None,
+) -> JSONObject:
+    contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    reason_path = None
+    if exc is not None:
+        errors = exc.errors()
+        if errors:
+            loc = errors[0].get("loc")
+            if isinstance(loc, (tuple, list)):
+                reason_path = ".".join(str(part) for part in loc)
+    canonical_arguments = None
+    if isinstance(suggested_next_call, dict):
+        arguments = suggested_next_call.get("arguments")
+        if isinstance(arguments, dict):
+            canonical_arguments = arguments
+    return {
+        "status": "failed",
+        "error_code": "VALIDATION_ERROR",
+        "recoverable": True,
+        "message": detail,
+        "normalized_args": {},
+        "missing_fields": [],
+        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
+        "details": {
+            "validation_detail": detail,
+            "reason_path": reason_path,
+            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+            "canonical_arguments": canonical_arguments,
+            "section_allowed_keys": deepcopy(contract.get("section_allowed_keys", [])) if isinstance(contract, dict) else [],
+            "section_aliases": deepcopy(contract.get("section_aliases", {})) if isinstance(contract, dict) else {},
+            "minimal_section_example": deepcopy(contract.get("minimal_section_example")) if isinstance(contract, dict) else None,
+        },
+        "suggested_next_call": suggested_next_call,
+        "request_id": None,
+        "backend_code": None,
+        "http_status": None,
+        "noop": False,
+        "verification": {},
+    }
+
+
+def _safe_tool_call(
+    call,
+    *,
+    error_code: str,
+    normalized_args: JSONObject,
+    suggested_next_call: JSONObject | None,
+) -> JSONObject:
+    try:
+        return call()
+    except (QingflowApiError, RuntimeError) as error:
+        api_error = _coerce_api_error(error)
+        public_http_status = None if api_error.http_status == 404 else api_error.http_status
+        return {
+            "status": "failed",
+            "error_code": error_code,
+            "recoverable": True,
+            "message": _public_error_message(error_code, api_error),
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "transport_error": {
+                    "http_status": api_error.http_status,
+                    "backend_code": api_error.backend_code,
+                    "category": api_error.category,
+                }
+            },
+            "suggested_next_call": suggested_next_call,
+            "request_id": api_error.request_id,
+            "backend_code": api_error.backend_code,
+            "http_status": public_http_status,
+            "noop": False,
+            "verification": {},
+        }
+
+
+def _coerce_api_error(error: Exception) -> QingflowApiError:
+    if isinstance(error, QingflowApiError):
+        return error
+    if isinstance(error, RuntimeError):
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("category") and payload.get("message"):
+            details = payload.get("details")
+            return QingflowApiError(
+                category=str(payload.get("category")),
+                message=str(payload.get("message")),
+                backend_code=payload.get("backend_code"),
+                request_id=payload.get("request_id"),
+                http_status=payload.get("http_status"),
+                details=details if isinstance(details, dict) else None,
+            )
+    return QingflowApiError(category="runtime", message=str(error))
+
+
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+        return "app is currently locked by another active editor session"
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
+        "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
+        "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
+        "APP_RESOLVE_FAILED": "app resolution is unavailable in the current route",
+        "APP_READ_FAILED": "app base or schema is unavailable in the current route",
+        "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
+        "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_PLAN_FAILED": "schema planning could not load the required app state in the current route",
+        "LAYOUT_PLAN_FAILED": "layout planning could not load the required app state in the current route",
+        "FLOW_PLAN_FAILED": "flow planning could not load the required app state in the current route",
+        "VIEWS_PLAN_FAILED": "views planning could not load the required app state in the current route",
+        "SCHEMA_APPLY_FAILED": "schema apply could not complete because the app route or readback is unavailable",
+        "LAYOUT_APPLY_FAILED": "layout apply could not complete because the layout route or readback is unavailable",
+        "FLOW_APPLY_FAILED": "flow apply could not complete because the workflow route or readback is unavailable",
+        "VIEWS_APPLY_FAILED": "views apply could not complete because the views route or readback is unavailable",
+        "CHART_APPLY_FAILED": "chart apply could not complete because the QingBI route or readback is unavailable",
+        "PORTAL_APPLY_FAILED": "portal apply could not complete because the portal route or readback is unavailable",
+        "PUBLISH_VERIFY_FAILED": "publish verification is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")
+
+
+_BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
+    "member_search": {
+        "allowed_keys": ["query", "page_num", "page_size", "contain_disable"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "query": "严琪东",
+            "page_num": 1,
+            "page_size": 20,
+            "contain_disable": False,
+        },
+    },
+    "role_search": {
+        "allowed_keys": ["keyword", "page_num", "page_size"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "keyword": "项目经理",
+            "page_num": 1,
+            "page_size": 20,
+        },
+    },
+    "role_create": {
+        "allowed_keys": ["role_name", "member_uids", "member_emails", "member_names", "role_icon"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "role_name": "研发负责人",
+            "member_names": ["严琪东"],
+            "member_uids": [],
+            "member_emails": [],
+            "role_icon": "ex-user-outlined",
+        },
+    },
+    "app_schema_plan": {
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "field.title": "field.name",
+            "field.label": "field.name",
+            "field.fields": "field.subfields",
+            "field.type_id": "field.type",
+            "field.relationMode": "field.relation_mode",
+            "field.selection_mode": "field.relation_mode",
+            "field.selectionMode": "field.relation_mode",
+            "field.multiple": "field.relation_mode",
+            "field.allow_multiple": "field.relation_mode",
+            "field.optional_data_num": "field.relation_mode",
+            "field.optionalDataNum": "field.relation_mode",
+        },
+        "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()),
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+            "create_if_missing": True,
+            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+        "relation_example": {
+            "profile": "default",
+            "app_key": "APP_ITERATION",
+            "add_fields": [
+                {
+                    "name": "需求反馈引用",
+                    "type": "relation",
+                    "target_app_key": "APP_FEEDBACK",
+                    "relation_mode": "multiple",
+                    "display_field": {"name": "反馈标题"},
+                    "visible_fields": [{"name": "反馈标题"}, {"name": "优先级判断"}],
+                }
+            ],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+    },
+    "app_schema_apply": {
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "field.title": "field.name",
+            "field.label": "field.name",
+            "field.fields": "field.subfields",
+            "field.type_id": "field.type",
+            "field.relationMode": "field.relation_mode",
+            "field.selection_mode": "field.relation_mode",
+            "field.selectionMode": "field.relation_mode",
+            "field.multiple": "field.relation_mode",
+            "field.allow_multiple": "field.relation_mode",
+            "field.optional_data_num": "field.relation_mode",
+            "field.optionalDataNum": "field.relation_mode",
+        },
+        "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()),
+        },
+        "execution_notes": [
+            "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",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+            "create_if_missing": True,
+            "publish": True,
+            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+        "relation_example": {
+            "profile": "default",
+            "app_key": "APP_ITERATION",
+            "publish": True,
+            "add_fields": [
+                {
+                    "name": "需求反馈引用",
+                    "type": "relation",
+                    "target_app_key": "APP_FEEDBACK",
+                    "relation_mode": "multiple",
+                    "display_field": {"name": "反馈标题"},
+                    "visible_fields": [{"name": "反馈标题"}, {"name": "优先级判断"}],
+                }
+            ],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+    },
+    "app_layout_plan": {
+        "allowed_keys": ["app_key", "mode", "sections", "preset"],
+        "aliases": {"overwrite": "replace", "sectionId": "section_id"},
+        "section_allowed_keys": ["section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "sectionId": "section_id",
+            "fields": "rows",
+            "field_ids": "rows",
+            "columns": "rows_chunk_size",
+        },
+        "allowed_values": {"mode": [member.value for member in LayoutApplyMode], "preset": [member.value for member in LayoutPreset]},
+        "minimal_section_example": {"title": "基础信息", "rows": [["字段A", "字段B"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+        },
+        "preset_example": {"profile": "default", "app_key": "APP_KEY", "mode": "merge", "preset": "balanced", "sections": []},
+    },
+    "app_layout_apply": {
+        "allowed_keys": ["app_key", "mode", "publish", "sections"],
+        "aliases": {"overwrite": "replace", "sectionId": "section_id"},
+        "section_allowed_keys": ["section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "sectionId": "section_id",
+            "fields": "rows",
+            "field_ids": "rows",
+            "columns": "rows_chunk_size",
+        },
+        "allowed_values": {"mode": [member.value for member in LayoutApplyMode]},
+        "execution_notes": [
+            "layout verification is split into layout_verified and layout_summary_verified",
+            "LAYOUT_SUMMARY_UNVERIFIED means raw form readback is stronger than the compact summary",
+        ],
+        "minimal_section_example": {"title": "基础信息", "rows": [["字段A", "字段B"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "publish": True,
+            "sections": [{"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,
+        },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
+        "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",
+        ],
+        "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"],
+        "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,
+        },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
+        "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",
+        ],
+        "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"}],
+        },
+    },
+    "app_views_plan": {
+        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key"],
+        "aliases": {
+            "fields": "columns",
+            "column_names": "columns",
+            "columnNames": "columns",
+            "viewKey": "view_key",
+            "tableView": "table",
+            "cardView": "card",
+            "kanban": "board",
+            "filter_rules": "filters",
+            "filterRules": "filters",
+            "startField": "start_field",
+            "endField": "end_field",
+            "titleField": "title_field",
+        },
+        "allowed_values": {
+            "preset": [member.value for member in ViewsPreset],
+            "view.type": [member.value for member in PublicViewType],
+            "view.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "remove_views": [],
+        },
+        "gantt_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "项目甘特图",
+                    "type": "gantt",
+                    "columns": ["项目名称", "开始日期", "结束日期"],
+                    "start_field": "开始日期",
+                    "end_field": "结束日期",
+                    "title_field": "项目名称",
+                    "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
+                }
+            ],
+            "remove_views": [],
+        },
+    },
+    "app_views_apply": {
+        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key"],
+        "aliases": {
+            "fields": "columns",
+            "column_names": "columns",
+            "columnNames": "columns",
+            "viewKey": "view_key",
+            "tableView": "table",
+            "cardView": "card",
+            "kanban": "board",
+            "filter_rules": "filters",
+            "filterRules": "filters",
+            "startField": "start_field",
+            "endField": "end_field",
+            "titleField": "title_field",
+        },
+        "allowed_values": {
+            "view.type": [member.value for member in PublicViewType],
+            "view.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "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_read_views_summary 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",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "remove_views": [],
+        },
+        "gantt_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "项目甘特图",
+                    "type": "gantt",
+                    "columns": ["项目名称", "开始日期", "结束日期"],
+                    "start_field": "开始日期",
+                    "end_field": "结束日期",
+                    "title_field": "项目名称",
+                    "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
+                }
+            ],
+            "remove_views": [],
+        },
+    },
+    "app_read_charts_summary": {
+        "allowed_keys": ["app_key"],
+        "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",
+            "chart summaries do not include full qingbi config payloads",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_charts_apply": {
+        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids"],
+        "aliases": {
+            "chart.id": "chart.chart_id",
+            "chart.type": "chart.chart_type",
+            "chart.dimension_fields": "chart.dimension_field_ids",
+            "chart.indicator_fields": "chart.indicator_field_ids",
+            "chart.metric_field_ids": "chart.indicator_field_ids",
+            "chart.filter.op": "chart.filter.operator",
+        },
+        "allowed_values": {
+            "chart.chart_type": [member.value for member in PublicChartType],
+            "chart.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "execution_notes": [
+            "app_charts_apply is immediate-live and does not publish",
+            "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",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": []}],
+            "remove_chart_ids": [],
+            "reorder_chart_ids": [],
+        },
+    },
+    "chart_apply": {
+        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids"],
+        "aliases": {
+            "legacy_tool_name": "app_charts_apply",
+        },
+        "allowed_values": {
+            "chart.chart_type": [member.value for member in PublicChartType],
+            "chart.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "execution_notes": [
+            "legacy compatibility alias; prefer app_charts_apply in new builder flows",
+            "behavior matches app_charts_apply exactly",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": []}],
+            "remove_chart_ids": [],
+            "reorder_chart_ids": [],
+        },
+    },
+    "portal_read_summary": {
+        "allowed_keys": ["dash_key", "being_draft"],
+        "aliases": {"beingDraft": "being_draft"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns a compact portal summary instead of the raw dash payload",
+            "being_draft=true reads the current draft view; being_draft=false reads live",
+            "use this before portal_apply when you need the current section inventory or target dash metadata",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_key": "DASH_KEY",
+            "being_draft": True,
+        },
+    },
+    "portal_apply": {
+        "allowed_keys": ["dash_key", "dash_name", "package_tag_id", "publish", "sections", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "aliases": {
+            "sourceType": "source_type",
+            "chartRef": "chart_ref",
+            "viewRef": "view_ref",
+            "dashStyleConfigBO": "dash_style_config",
+        },
+        "section_allowed_keys": ["title", "source_type", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
+        "section_aliases": {
+            "sourceType": "source_type",
+            "chartRef": "chart_ref",
+            "viewRef": "view_ref",
+            "dashStyleConfigBO": "dash_style_config",
+        },
+        "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
+        "execution_notes": [
+            "portal_apply uses replace semantics for sections",
+            "remove a section by omitting it from the new sections list",
+            "package_tag_id is required when creating a new portal",
+            "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
+            "chart_ref resolves by chart_id first, then exact unique chart_name",
+            "view_ref resolves by view_key first, then exact unique view_name",
+            "position.pc/mobile is the canonical portal layout shape",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_name": "经营门户",
+            "package_tag_id": 1001,
+            "publish": True,
+            "sections": [
+                {
+                    "title": "经营概览",
+                    "source_type": "chart",
+                    "chart_ref": {"app_key": "APP_KEY", "chart_name": "数据总量"},
+                    "position": {
+                        "pc": {"x": 0, "y": 0, "cols": 12, "rows": 6},
+                        "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 6},
+                    },
+                }
+            ],
+        },
+        "minimal_section_example": {
+            "title": "订单概览",
+            "source_type": "view",
+            "view_ref": {"app_key": "APP_KEY", "view_key": "VIEW_KEY"},
+            "position": {
+                "pc": {"x": 0, "y": 0, "cols": 24, "rows": 8},
+                "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 8},
+            },
+        },
+    },
+}
+
+_PRIVATE_BUILDER_TOOL_CONTRACTS = {
+    "app_schema_plan",
+    "app_layout_plan",
+    "app_flow_plan",
+    "app_views_plan",
+}
+
+_BUILDER_TOOL_CONTRACT_ALIASES = {
+    "chart_apply": "app_charts_apply",
+}