@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+from copy import deepcopy
 import json
+import time
 
 from pydantic import ValidationError
 
@@ -8,36 +10,61 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
+    ChartApplyRequest,
+    CustomButtonPatch,
+    FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
+    FlowPreset,
     FlowNodePatch,
     FlowPlanRequest,
     FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
+    LayoutPreset,
     LayoutSectionPatch,
+    PortalApplyRequest,
+    PublicButtonTriggerAction,
+    PublicFieldType,
+    PublicRelationMode,
+    PublicChartType,
+    PublicViewType,
     SchemaPlanRequest,
+    ViewFilterOperator,
     ViewUpsertPatch,
+    ViewsPreset,
     ViewsPlanRequest,
 )
-from ..builder_facade.service import AiBuilderFacade
+from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
 from .app_tools import AppTools
 from .base import ToolBase
+from .custom_button_tools import CustomButtonTools
+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),
+            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),
+            directory=DirectoryTools(sessions, backend),
             solutions=SolutionTools(sessions, backend),
         )
 
@@ -50,14 +77,69 @@ class AiBuilderTools(ToolBase):
         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 = "",
+            icon: str | None = None,
+            color: str | None = None,
+        ) -> JSONObject:
+            return self.package_create(profile=profile, package_name=package_name, icon=icon, color=color)
+
+        @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)
+            return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key)
 
         @mcp.tool()
         def app_release_edit_lock_if_mine(
@@ -80,8 +162,52 @@ class AiBuilderTools(ToolBase):
             app_name: str = "",
             package_tag_id: int | None = None,
         ) -> JSONObject:
+            has_app_key = bool((app_key or "").strip())
+            has_app_name = bool((app_name or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_app_key and (has_app_name or has_package_tag_id):
+                return _config_failure(
+                    tool_name="app_resolve",
+                    message="app_resolve accepts exactly one selector mode.",
+                    fix_hint="Use only `app_key`, or use `app_name` together with `package_tag_id`.",
+                )
+            if not has_app_key and not (has_app_name and has_package_tag_id):
+                return _config_failure(
+                    tool_name="app_resolve",
+                    message="app_resolve requires either app_key, or app_name together with package_tag_id.",
+                    fix_hint="For an existing known app, pass `app_key`. For package-scoped lookup, pass both `app_name` and `package_tag_id`.",
+                )
             return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
 
+        @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(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            payload: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+
+        @mcp.tool()
+        def app_custom_button_update(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            button_id: int = 0,
+            payload: 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)
+
         @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)
@@ -103,75 +229,51 @@ class AiBuilderTools(ToolBase):
             return self.app_read_flow_summary(profile=profile, app_key=app_key)
 
         @mcp.tool()
-        def app_schema_plan(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            package_tag_id: int | None = None,
-            app_name: str = "",
-            create_if_missing: bool = False,
-            add_fields: list[JSONObject] | None = None,
-            update_fields: list[JSONObject] | None = None,
-            remove_fields: list[JSONObject] | None = None,
-        ) -> JSONObject:
-            return self.app_schema_plan(
-                profile=profile,
-                app_key=app_key,
-                package_tag_id=package_tag_id,
-                app_name=app_name,
-                create_if_missing=create_if_missing,
-                add_fields=add_fields or [],
-                update_fields=update_fields or [],
-                remove_fields=remove_fields or [],
-            )
+        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_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.portal_list(profile=profile)
 
         @mcp.tool()
-        def app_layout_plan(
+        def portal_get(
             profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            mode: str = "merge",
-            sections: list[JSONObject] | None = None,
-            preset: str | None = None,
+            dash_key: str = "",
+            being_draft: bool = True,
         ) -> JSONObject:
-            return self.app_layout_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                sections=sections or [],
-                preset=preset,
-            )
+            return self.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
 
         @mcp.tool()
-        def app_flow_plan(
+        def portal_read_summary(
             profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            mode: str = "replace",
-            nodes: list[JSONObject] | None = None,
-            transitions: list[JSONObject] | None = None,
-            preset: str | None = None,
+            dash_key: str = "",
+            being_draft: bool = True,
         ) -> JSONObject:
-            return self.app_flow_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                nodes=nodes or [],
-                transitions=transitions or [],
-                preset=preset,
-            )
+            return self.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft)
 
         @mcp.tool()
-        def app_views_plan(
+        def view_get(profile: str = DEFAULT_PROFILE, viewgraph_key: str = "") -> JSONObject:
+            return self.view_get(profile=profile, viewgraph_key=viewgraph_key)
+
+        @mcp.tool()
+        def chart_get(
             profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            upsert_views: list[JSONObject] | None = None,
-            remove_views: list[str] | None = None,
-            preset: str | None = None,
+            chart_id: str = "",
+            data_payload: JSONObject | None = None,
+            page_num: int | None = None,
+            page_size: int | None = None,
+            page_num_y: int | None = None,
+            page_size_y: int | None = None,
         ) -> JSONObject:
-            return self.app_views_plan(
+            return self.chart_get(
                 profile=profile,
-                app_key=app_key,
-                upsert_views=upsert_views or [],
-                remove_views=remove_views or [],
-                preset=preset,
+                chart_id=chart_id,
+                data_payload=data_payload or {},
+                page_num=page_num,
+                page_size=page_size,
+                page_num_y=page_num_y,
+                page_size_y=page_size_y,
             )
 
         @mcp.tool()
@@ -181,18 +283,39 @@ class AiBuilderTools(ToolBase):
             package_tag_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
+            icon: str = "",
+            color: 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:
+            has_app_key = bool((app_key or "").strip())
+            has_app_name = bool((app_name or "").strip())
+            has_app_title = bool((app_title or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_app_key:
+                if create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply edit mode only accepts app_key as the resource selector.",
+                        fix_hint="For existing apps, pass `app_key` only. For create mode, use `package_tag_id + app_name + create_if_missing=true`.",
+                    )
+            elif not (create_if_missing and has_package_tag_id and has_app_name):
+                return _config_failure(
+                    tool_name="app_schema_apply",
+                    message="app_schema_apply create mode requires package_tag_id, app_name, and create_if_missing=true.",
+                    fix_hint="Use `app_key` for existing apps, or pass `package_tag_id + app_name + create_if_missing=true` to create a new app.",
+                )
             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,
+                icon=icon,
+                color=color,
                 create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields or [],
@@ -244,6 +367,67 @@ class AiBuilderTools(ToolBase):
                 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:
+            has_dash_key = bool((dash_key or "").strip())
+            has_dash_name = bool((dash_name or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_dash_key and has_package_tag_id:
+                return _config_failure(
+                    tool_name="portal_apply",
+                    message="portal_apply accepts exactly one selector mode.",
+                    fix_hint="Use `dash_key` to update an existing portal, or use `package_tag_id + dash_name` to create a new portal.",
+                )
+            if not has_dash_key and not (has_package_tag_id and has_dash_name):
+                return _config_failure(
+                    tool_name="portal_apply",
+                    message="portal_apply requires either dash_key, or package_tag_id together with dash_name.",
+                    fix_hint="Use `dash_key` for an existing portal. For create mode, pass `package_tag_id + dash_name`.",
+                )
+            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,
@@ -274,14 +458,174 @@ class AiBuilderTools(ToolBase):
             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,
+        icon: str | None = None,
+        color: str | None = None,
+    ) -> JSONObject:
+        normalized_args = {
+            "package_name": package_name,
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.package_create(profile=profile, package_name=package_name, icon=icon, color=color),
+            error_code="PACKAGE_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={
+                "tool_name": "package_create",
+                "arguments": {
+                    "profile": profile,
+                    "package_name": package_name,
+                    **({"icon": icon} if icon else {}),
+                    **({"color": color} if color else {}),
+                },
+            },
+        )
+
+    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}
-        return _safe_tool_call(
+        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,
@@ -317,6 +661,98 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_list(profile=profile, app_key=app_key),
+            error_code="CUSTOM_BUTTON_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_get(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id),
+            error_code="CUSTOM_BUTTON_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        try:
+            request = CustomButtonPatch.model_validate(payload)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_custom_button_create",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_button_create",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "payload": {
+                            "button_text": "新增记录",
+                            "background_color": "#FFFFFF",
+                            "text_color": "#494F57",
+                            "button_icon": "ex-add-outlined",
+                            "trigger_action": "addData",
+                            "trigger_add_data_config": {"related_app_key": "TARGET_APP_KEY", "que_relation": []},
+                        },
+                    },
+                },
+            )
+        normalized_args = {"app_key": app_key, "payload": request.model_dump(mode="json")}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_create(profile=profile, app_key=app_key, payload=request),
+            error_code="CUSTOM_BUTTON_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_create", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        try:
+            request = CustomButtonPatch.model_validate(payload)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_custom_button_update",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_button_update",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "button_id": button_id,
+                        "payload": {
+                            "button_text": "新增记录",
+                            "background_color": "#FFFFFF",
+                            "text_color": "#494F57",
+                            "button_icon": "ex-add-outlined",
+                            "trigger_action": "link",
+                            "trigger_link_url": "https://example.com",
+                        },
+                    },
+                },
+            )
+        normalized_args = {"app_key": app_key, "button_id": button_id, "payload": request.model_dump(mode="json")}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=request),
+            error_code="CUSTOM_BUTTON_UPDATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_update", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id),
+            error_code="CUSTOM_BUTTON_DELETE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_delete", "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(
@@ -362,6 +798,84 @@ class AiBuilderTools(ToolBase):
             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_list(self, *, profile: str) -> JSONObject:
+        return _safe_tool_call(
+            lambda: self._facade.portal_list(profile=profile),
+            error_code="PORTAL_LIST_FAILED",
+            normalized_args={},
+            suggested_next_call={"tool_name": "portal_list", "arguments": {"profile": profile}},
+        )
+
+    def portal_get(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_get(profile=profile, dash_key=dash_key, being_draft=being_draft),
+            error_code="PORTAL_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    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 view_get(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        normalized_args = {"viewgraph_key": viewgraph_key}
+        return _safe_tool_call(
+            lambda: self._facade.view_get(profile=profile, viewgraph_key=viewgraph_key),
+            error_code="VIEW_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def chart_get(
+        self,
+        *,
+        profile: str,
+        chart_id: str,
+        data_payload: JSONObject | None = None,
+        page_num: int | None = None,
+        page_size: int | None = None,
+        page_num_y: int | None = None,
+        page_size_y: int | None = None,
+    ) -> JSONObject:
+        normalized_args = {
+            "chart_id": chart_id,
+            "data_payload": deepcopy(data_payload) if isinstance(data_payload, dict) else {},
+            "page_num": page_num,
+            "page_size": page_size,
+            "page_num_y": page_num_y,
+            "page_size_y": page_size_y,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.chart_get(
+                profile=profile,
+                chart_id=chart_id,
+                data_payload=normalized_args["data_payload"],
+                page_num=page_num,
+                page_size=page_size,
+                page_num_y=page_num_y,
+                page_size_y=page_size_y,
+            ),
+            error_code="CHART_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+        )
+
     def app_schema_plan(
         self,
         *,
@@ -369,6 +883,8 @@ class AiBuilderTools(ToolBase):
         app_key: str = "",
         package_tag_id: int | None = None,
         app_name: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
@@ -380,6 +896,8 @@ class AiBuilderTools(ToolBase):
                     "app_key": app_key,
                     "package_tag_id": package_tag_id,
                     "app_name": app_name,
+                    "icon": icon,
+                    "color": color,
                     "create_if_missing": create_if_missing,
                     "add_fields": add_fields,
                     "update_fields": update_fields,
@@ -389,6 +907,8 @@ class AiBuilderTools(ToolBase):
         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": {
@@ -396,6 +916,8 @@ class AiBuilderTools(ToolBase):
                         "app_key": app_key,
                         "package_tag_id": package_tag_id,
                         "app_name": app_name,
+                        "icon": icon,
+                        "color": color,
                         "create_if_missing": create_if_missing,
                         "add_fields": [{"name": "字段名称", "type": "text"}],
                         "update_fields": [],
@@ -431,22 +953,29 @@ class AiBuilderTools(ToolBase):
         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",
-                        "preset": "balanced",
-                        "sections": [],
+                        "sections": [{
+                            "type": "paragraph",
+                            "paragraph_id": "basic",
+                            "title": "基础信息",
+                            "rows": [["字段A", "字段B", "字段C", "字段D"]],
+                        }],
                     },
                 },
             )
+        normalized_request = request.model_dump(mode="json", exclude_none=True)
         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")}},
+            normalized_args=normalized_request,
+            suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
     def app_flow_plan(
@@ -472,6 +1001,8 @@ class AiBuilderTools(ToolBase):
         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": {
@@ -512,6 +1043,8 @@ class AiBuilderTools(ToolBase):
         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": {
@@ -538,6 +1071,57 @@ class AiBuilderTools(ToolBase):
         package_tag_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
+        icon: str = "",
+        color: 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,
+            icon=icon,
+            color=color,
+            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,
+                icon=icon,
+                color=color,
+                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 = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
@@ -545,44 +1129,76 @@ class AiBuilderTools(ToolBase):
         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,
+                icon=icon,
+                color=color,
+                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 add_fields]
-            parsed_update = [FieldUpdatePatch.model_validate(item) for item in update_fields]
-            parsed_remove = [FieldRemovePatch.model_validate(item) for item in remove_fields]
+            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": app_key,
-                        "package_tag_id": package_tag_id,
-                        "app_name": effective_app_name,
-                        "create_if_missing": create_if_missing,
-                        "add_fields": [{"name": "字段名称", "type": "text", "required": False}],
-                        "update_fields": [],
-                        "remove_fields": [],
+                        "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),
+                        "icon": str(plan_args.get("icon") or icon),
+                        "color": str(plan_args.get("color") or color),
+                        "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": app_key,
-            "package_tag_id": package_tag_id,
-            "app_name": effective_app_name,
-            "create_if_missing": create_if_missing,
+            "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),
+            "icon": str(plan_args.get("icon") or icon or ""),
+            "color": str(plan_args.get("color") or color or ""),
+            "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],
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_schema_apply(
                 profile=profile,
-                app_key=app_key,
-                package_tag_id=package_tag_id,
-                app_name=effective_app_name,
-                create_if_missing=create_if_missing,
+                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),
+                icon=str(plan_args.get("icon") or icon or ""),
+                color=str(plan_args.get("color") or color or ""),
+                create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
                 publish=publish,
                 add_fields=parsed_add,
                 update_fields=parsed_update,
@@ -592,48 +1208,80 @@ class AiBuilderTools(ToolBase):
             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:
-            normalized_mode = str(mode or "merge").strip().lower()
-            if normalized_mode in {"overwrite"}:
-                normalized_mode = "replace"
-            parsed_mode = LayoutApplyMode(normalized_mode)
-            parsed_sections = [LayoutSectionPatch.model_validate(item) for item in sections]
-        except ValueError:
-            return _validation_failure(
-                "mode must be one of: merge, replace",
-                suggested_next_call={
-                    "tool_name": "app_layout_apply",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": app_key,
-                        "mode": "merge",
-                        "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
-                    },
-                },
-            )
-        except ValidationError as exc:
+            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": app_key,
-                        "mode": "merge",
-                        "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+                        "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": app_key,
+            "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],
+            "sections": [section.model_dump(mode="json", exclude_none=True) for section in parsed_sections],
         }
         return _safe_tool_call(
-            lambda: self._facade.app_layout_apply(profile=profile, app_key=app_key, mode=parsed_mode, publish=publish, sections=parsed_sections),
+            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}},
@@ -649,27 +1297,80 @@ class AiBuilderTools(ToolBase):
         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": app_key,
-                    "mode": mode,
-                    "nodes": nodes,
-                    "transitions": transitions,
+                    "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": app_key,
-                        "mode": "replace",
-                        "nodes": [{"id": "start", "type": "start", "name": "发起"}],
-                        "transitions": [],
+                        "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 [],
                     },
                 },
             )
@@ -703,45 +1404,363 @@ class AiBuilderTools(ToolBase):
         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 upsert_views]
+            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": app_key,
-                        "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["字段A"]}],
-                        "remove_views": [],
+                        "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": app_key,
+            "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(remove_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=app_key, publish=publish, upsert_views=parsed_views, remove_views=remove_views),
+            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}
-        return _safe_tool_call(
+        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, *, suggested_next_call: JSONObject | None = None) -> JSONObject:
+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",
@@ -749,8 +1768,16 @@ def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None =
         "message": detail,
         "normalized_args": {},
         "missing_fields": [],
-        "allowed_values": {},
-        "details": {"validation_detail": detail},
+        "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,
@@ -760,6 +1787,29 @@ def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None =
     }
 
 
+def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObject:
+    contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    return {
+        "status": "failed",
+        "error_code": "CONFIG_ERROR",
+        "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 [],
+        },
+        "suggested_next_call": None,
+        "request_id": None,
+        "backend_code": None,
+        "http_status": None,
+        "noop": False,
+        "verification": {},
+    }
+
+
 def _safe_tool_call(
     call,
     *,
@@ -827,6 +1877,11 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
         "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",
+        "CUSTOM_BUTTON_LIST_FAILED": "custom button list is unavailable in the current route",
+        "CUSTOM_BUTTON_GET_FAILED": "custom button detail is unavailable in the current route",
+        "CUSTOM_BUTTON_CREATE_FAILED": "custom button create could not complete because the route or readback is unavailable",
+        "CUSTOM_BUTTON_UPDATE_FAILED": "custom button update could not complete because the route or readback is unavailable",
+        "CUSTOM_BUTTON_DELETE_FAILED": "custom button delete could not complete because the route is unavailable",
         "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",
@@ -840,6 +1895,856 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
         "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] = {
+    "package_list": {
+        "allowed_keys": ["trial_status"],
+        "aliases": {"trialStatus": "trial_status"},
+        "allowed_values": {"trial_status": ["all", "trial", "formal"]},
+        "minimal_example": {
+            "profile": "default",
+            "trial_status": "all",
+        },
+    },
+    "package_resolve": {
+        "allowed_keys": ["package_name"],
+        "aliases": {"packageName": "package_name"},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "package_name": "PLM（备用，施工中）",
+        },
+    },
+    "package_create": {
+        "allowed_keys": ["package_name", "icon", "color"],
+        "aliases": {
+            "packageName": "package_name",
+            "iconName": "icon",
+            "iconColor": "color",
+        },
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "package_name": "项目管理",
+            "icon": "files-folder",
+            "color": "azure",
+        },
+    },
+    "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",
+        },
+    },
+    "package_attach_app": {
+        "allowed_keys": ["tag_id", "app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "attach one existing app to one existing package",
+            "app_title is no longer accepted as a public selector; resolve the app first and pass app_key",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "tag_id": 1001,
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_resolve": {
+        "allowed_keys": ["app_key", "app_name", "package_tag_id"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "use exactly one selector mode",
+            "mode 1: app_key",
+            "mode 2: app_name + package_tag_id",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+        "package_scoped_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+        },
+    },
+    "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"],
+        "aliases": {
+            "payload.buttonText": "payload.button_text",
+            "payload.backgroundColor": "payload.background_color",
+            "payload.textColor": "payload.text_color",
+            "payload.buttonIcon": "payload.button_icon",
+            "payload.iconColor": "payload.icon_color",
+            "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",
+        },
+        "allowed_values": {
+            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "payload": {
+                "button_text": "新增记录",
+                "background_color": "#FFFFFF",
+                "text_color": "#494F57",
+                "button_icon": "ex-add-outlined",
+                "icon_color": "#494F57",
+                "trigger_action": "link",
+                "trigger_link_url": "https://example.com",
+            },
+        },
+    },
+    "app_custom_button_update": {
+        "allowed_keys": ["app_key", "button_id", "payload"],
+        "aliases": {
+            "buttonId": "button_id",
+            "payload.buttonText": "payload.button_text",
+            "payload.backgroundColor": "payload.background_color",
+            "payload.textColor": "payload.text_color",
+            "payload.buttonIcon": "payload.button_icon",
+            "payload.iconColor": "payload.icon_color",
+            "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",
+        },
+        "allowed_values": {
+            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "button_id": 1001,
+            "payload": {
+                "button_text": "查看详情",
+                "background_color": "#FFFFFF",
+                "text_color": "#494F57",
+                "button_icon": "ex-link-outlined",
+                "icon_color": "#494F57",
+                "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,
+        },
+    },
+    "app_schema_plan": {
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "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",
+            "field.remoteLookupConfig": "field.remote_lookup_config",
+            "field.qLinkerBinding": "field.q_linker_binding",
+            "field.codeBlockConfig": "field.code_block_config",
+            "field.codeBlockBinding": "field.code_block_binding",
+            "field.autoTrigger": "field.auto_trigger",
+            "field.customBtnTextStatus": "field.custom_button_text_enabled",
+            "field.customBtnText": "field.custom_button_text",
+        },
+        "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,
+            "icon": "template",
+            "color": "emerald",
+            "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", "icon", "color", "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",
+            "field.remoteLookupConfig": "field.remote_lookup_config",
+            "field.qLinkerBinding": "field.q_linker_binding",
+            "field.codeBlockConfig": "field.code_block_config",
+            "field.codeBlockBinding": "field.code_block_binding",
+            "field.autoTrigger": "field.auto_trigger",
+            "field.customBtnTextStatus": "field.custom_button_text_enabled",
+            "field.customBtnText": "field.custom_button_text",
+        },
+        "allowed_values": {
+            "field.type": [member.value for member in PublicFieldType],
+            "field.relation_mode": [member.value for member in PublicRelationMode],
+            "field.code_block_binding.outputs.target_field.type": list(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES),
+            "field.q_linker_binding.outputs.target_field.type": list(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES),
+            "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+        },
+        "execution_notes": [
+            "use exactly one resource mode",
+            "edit mode: app_key",
+            "create mode: package_tag_id + app_name + create_if_missing=true",
+            "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",
+            "if relation target metadata lookup is blocked by 40161/40002/40027, explicit display_field.name and visible_fields[].name let builder degrade verification and still continue schema write",
+            "q_linker_binding lets you declare request config, dynamic inputs, alias parsing, and target-field bindings in one step; builder writes remoteLookupConfig plus the existing backend relation-default and questionRelations structures",
+            "code_block_binding lets you declare inputs, code, alias parsing, and target-field bindings in one step; builder writes codeBlockConfig plus the existing backend relation-default and questionRelations structures",
+            "builder configures code blocks only; it does not execute or trigger code blocks",
+            "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",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+            "icon": "template",
+            "color": "emerald",
+            "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": [],
+        },
+        "code_block_example": {
+            "profile": "default",
+            "app_key": "APP_SCRIPT",
+            "publish": True,
+            "add_fields": [
+                {"name": "客户等级", "type": "text"},
+                {
+                    "name": "查询代码块",
+                    "type": "code_block",
+                    "code_block_binding": {
+                        "inputs": [
+                            {"field": {"name": "客户名称"}, "var": "customerName"},
+                            {"field": {"name": "预算金额"}, "var": "budget"},
+                        ],
+                        "code": "qf_output = {}; qf_output.customerLevel = budget > 100000 ? 'A' : 'B';",
+                        "auto_trigger": True,
+                        "custom_button_text_enabled": True,
+                        "custom_button_text": "评估客户",
+                        "outputs": [
+                            {"alias": "customerLevel", "path": "$.customerLevel", "target_field": {"name": "客户等级"}},
+                        ],
+                    },
+                }
+            ],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+        "q_linker_example": {
+            "profile": "default",
+            "app_key": "APP_CUSTOMER",
+            "publish": True,
+            "add_fields": [
+                {"name": "客户名称", "type": "text"},
+                {"name": "企业名称", "type": "text"},
+                {"name": "统一社会信用代码", "type": "text"},
+                {
+                    "name": "企业信息查询",
+                    "type": "q_linker",
+                    "q_linker_binding": {
+                        "inputs": [
+                            {"field": {"name": "客户名称"}, "key": "keyword", "source": "query_param"},
+                        ],
+                        "request": {
+                            "url": "https://example.com/company/search",
+                            "method": "GET",
+                            "headers": [],
+                            "query_params": [],
+                            "body_type": 1,
+                            "url_encoded_value": [],
+                            "result_type": 1,
+                            "auto_trigger": True,
+                            "custom_button_text_enabled": True,
+                            "custom_button_text": "查询企业信息",
+                        },
+                        "outputs": [
+                            {"alias": "company_name", "path": "$.data.name", "target_field": {"name": "企业名称"}},
+                            {"alias": "credit_code", "path": "$.data.creditCode", "target_field": {"name": "统一社会信用代码"}},
+                        ],
+                    },
+                },
+            ],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+    },
+    "app_layout_plan": {
+        "allowed_keys": ["app_key", "mode", "sections", "preset"],
+        "aliases": {"overwrite": "replace", "sectionId": "section_id"},
+        "section_allowed_keys": ["type", "paragraph_id", "section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "paragraphId": "paragraph_id",
+            "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": {"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B", "字段C", "字段D"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B", "字段C", "字段D"]]}],
+        },
+        "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": ["type", "paragraph_id", "section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "paragraphId": "paragraph_id",
+            "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": {"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B", "字段C", "字段D"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "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,
+        },
+        "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", "upsert_views[].buttons"],
+        "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",
+            "buttons[].buttonType": "buttons[].button_type",
+            "buttons[].configType": "buttons[].config_type",
+            "buttons[].buttonId": "buttons[].button_id",
+            "buttons[].beingMain": "buttons[].being_main",
+            "buttons[].buttonLimit": "buttons[].button_limit",
+            "buttons[].buttonFormula": "buttons[].button_formula",
+            "buttons[].buttonFormulaType": "buttons[].button_formula_type",
+            "buttons[].printTpls": "buttons[].print_tpls",
+        },
+        "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],
+            "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
+            "view.buttons.config_type": ["TOP", "DETAIL"],
+        },
+        "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", "upsert_views[].buttons"],
+        "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",
+            "buttons[].buttonType": "buttons[].button_type",
+            "buttons[].configType": "buttons[].config_type",
+            "buttons[].buttonId": "buttons[].button_id",
+            "buttons[].beingMain": "buttons[].being_main",
+            "buttons[].buttonLimit": "buttons[].button_limit",
+            "buttons[].buttonFormula": "buttons[].button_formula",
+            "buttons[].buttonFormulaType": "buttons[].button_formula_type",
+            "buttons[].printTpls": "buttons[].print_tpls",
+        },
+        "allowed_values": {
+            "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"],
+        },
+        "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",
+            "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
+        ],
+        "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",
+        },
+    },
+    "portal_list": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns the current user's accessible portal list",
+            "use this as the portal discovery path before portal_get",
+            "results are compact list items, not raw dash payloads",
+        ],
+        "minimal_example": {
+            "profile": "default",
+        },
+    },
+    "portal_get": {
+        "allowed_keys": ["dash_key", "being_draft"],
+        "aliases": {"beingDraft": "being_draft"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns portal-level detail plus a component inventory",
+            "chart and view components are returned as refs only; use chart_get or view_get for more detail",
+            "being_draft=true reads the current draft view; being_draft=false reads live",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_key": "DASH_KEY",
+            "being_draft": True,
+        },
+    },
+    "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,
+        },
+    },
+    "view_get": {
+        "allowed_keys": ["viewgraph_key"],
+        "aliases": {"viewKey": "viewgraph_key"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns one view's definition detail",
+            "does not return record data; use record_list with app_key + view_id for rows",
+            "use this after portal_get when a component references a view_ref.view_key",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "viewgraph_key": "VIEW_KEY",
+        },
+    },
+    "chart_get": {
+        "allowed_keys": ["chart_id", "data_payload", "page_num", "page_size", "page_num_y", "page_size_y"],
+        "aliases": {"payload": "data_payload"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns chart base info, chart config, and chart data together",
+            "chart_id is required; chart names are not accepted here",
+            "data_payload defaults to {} so chart_get queries concrete chart data by default",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "chart_id": "CHART_ID",
+            "data_payload": {},
+        },
+    },
+    "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": [
+            "use exactly one resource mode",
+            "update mode: dash_key",
+            "create mode: package_tag_id + dash_name",
+            "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",
+}