@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -0,0 +1,3449 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+import time
+
+from pydantic import ValidationError
+
+from ..public_surface import public_builder_contract_tool_names
+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,
+    VisibilityPatch,
+    ViewFilterOperator,
+    ViewUpsertPatch,
+    ViewsPreset,
+    ViewsPlanRequest,
+)
+from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
+from .app_tools import AppTools
+from .base import ToolBase, tool_cn_name
+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):
+    """AI Builder 工具（中文名：AI 搭建编排）。
+
+    类型：应用搭建编排工具。
+    主要职责：
+    1. 编排 schema/layout/views/flow/charts 的计划与应用；
+    2. 聚合 builder 侧读写与校验能力；
+    3. 将复杂搭建流程收敛为可执行步骤。
+    """
+
+    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),
+        )
+
+    def register(self, mcp) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def builder_tool_contract(tool_name: str = "") -> JSONObject:
+            return self.builder_tool_contract(tool_name=tool_name)
+
+        @mcp.tool()
+        def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> JSONObject:
+            return self.package_get(profile=profile, package_id=package_id)
+
+        @mcp.tool()
+        def package_apply(
+            profile: str = DEFAULT_PROFILE,
+            package_id: int | None = None,
+            package_name: str | None = None,
+            create_if_missing: bool = False,
+            icon: str | None = None,
+            color: str | None = None,
+            visibility: JSONObject | None = None,
+            items: list[dict] | None = None,
+            allow_detach: bool = False,
+        ) -> JSONObject:
+            return self.package_apply(
+                profile=profile,
+                package_id=package_id,
+                package_name=package_name,
+                create_if_missing=create_if_missing,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+                items=items or None,
+                allow_detach=allow_detach,
+            )
+
+        @mcp.tool()
+        def solution_install(
+            profile: str = DEFAULT_PROFILE,
+            solution_key: str = "",
+            being_copy_data: bool = True,
+            solution_source: str = "solutionDetail",
+        ) -> JSONObject:
+            return self.solution_install(
+                profile=profile,
+                solution_key=solution_key,
+                being_copy_data=being_copy_data,
+                solution_source=solution_source,
+            )
+
+        @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 app_release_edit_lock_if_mine(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            lock_owner_email: str = "",
+            lock_owner_name: str = "",
+        ) -> JSONObject:
+            return self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+
+        @mcp.tool()
+        def app_resolve(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            app_name: str = "",
+            package_id: int | None = None,
+        ) -> JSONObject:
+            has_app_key = bool((app_key or "").strip())
+            has_app_name = bool((app_name or "").strip())
+            has_package_id = package_id is not None
+            if has_app_key and (has_app_name or has_package_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_id`.",
+                )
+            if not has_app_key and not (has_app_name and has_package_id):
+                return _config_failure(
+                    tool_name="app_resolve",
+                    message="app_resolve requires either app_key, or app_name together with package_id.",
+                    fix_hint="For an existing known app, pass `app_key`. For package-scoped lookup, pass both `app_name` and `package_id`.",
+                )
+            return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_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_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get_fields(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_repair_code_blocks(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            field: str | None = None,
+            apply: bool = False,
+        ) -> JSONObject:
+            return self.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply)
+
+        @mcp.tool()
+        def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get_layout(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get_views(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get_flow(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get_charts(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 portal_get(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+            being_draft: bool = True,
+        ) -> JSONObject:
+            return self.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
+
+        @mcp.tool()
+        def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> JSONObject:
+            return self.view_get(profile=profile, view_key=view_key)
+
+        @mcp.tool()
+        def chart_get(
+            profile: str = DEFAULT_PROFILE,
+            chart_id: str = "",
+        ) -> JSONObject:
+            return self.chart_get(profile=profile, chart_id=chart_id)
+
+        @mcp.tool()
+        def app_schema_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            package_id: int | None = None,
+            app_name: str = "",
+            app_title: str = "",
+            icon: str = "",
+            color: str = "",
+            visibility: JSONObject | None = None,
+            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_id = package_id is not None
+            if has_app_key:
+                if create_if_missing or has_package_id:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply edit mode accepts app_key and optional app_name rename only.",
+                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
+                    )
+            elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
+                return _config_failure(
+                    tool_name="app_schema_apply",
+                    message="app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
+                    fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
+                )
+            return self.app_schema_apply(
+                profile=profile,
+                app_key=app_key,
+                package_id=package_id,
+                app_name=app_name,
+                app_title=app_title,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=add_fields or [],
+                update_fields=update_fields or [],
+                remove_fields=remove_fields or [],
+            )
+
+        @mcp.tool()
+        def app_layout_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            mode: str = "merge",
+            publish: bool = True,
+            sections: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
+
+        @mcp.tool()
+        def app_flow_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            mode: str = "replace",
+            publish: bool = True,
+            nodes: list[JSONObject] | None = None,
+            transitions: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.app_flow_apply(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                nodes=nodes or [],
+                transitions=transitions or [],
+            )
+
+        @mcp.tool()
+        def app_views_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            publish: bool = True,
+            upsert_views: list[JSONObject] | None = None,
+            remove_views: list[str] | None = None,
+        ) -> JSONObject:
+            return self.app_views_apply(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                upsert_views=upsert_views or [],
+                remove_views=remove_views or [],
+            )
+
+        @mcp.tool()
+        def app_charts_apply(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            upsert_charts: list[JSONObject] | None = None,
+            remove_chart_ids: list[str] | None = None,
+            reorder_chart_ids: list[str] | None = None,
+        ) -> JSONObject:
+            return self.app_charts_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_charts=upsert_charts or [],
+                remove_chart_ids=remove_chart_ids or [],
+                reorder_chart_ids=reorder_chart_ids or [],
+            )
+
+        @mcp.tool()
+        def portal_apply(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+            dash_name: str = "",
+            package_id: int | None = None,
+            publish: bool = True,
+            sections: list[JSONObject] | None = None,
+            visibility: 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_id = package_id is not None
+            if has_dash_key and has_package_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_id + dash_name` to create a new portal.",
+                )
+            if not has_dash_key and not (has_package_id and has_dash_name):
+                return _config_failure(
+                    tool_name="portal_apply",
+                    message="portal_apply requires either dash_key, or package_id together with dash_name.",
+                    fix_hint="Use `dash_key` for an existing portal. For create mode, pass `package_id + dash_name`.",
+                )
+            return self.portal_apply(
+                profile=profile,
+                dash_key=dash_key,
+                dash_name=dash_name,
+                package_id=package_id,
+                publish=publish,
+                sections=sections or [],
+                visibility=visibility,
+                auth=auth,
+                icon=icon,
+                color=color,
+                hide_copyright=hide_copyright,
+                dash_global_config=dash_global_config,
+                config=config or {},
+            )
+
+        @mcp.tool()
+        def app_publish_verify(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            expected_package_id: int | None = None,
+        ) -> JSONObject:
+            return self.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_id=expected_package_id,
+            )
+
+    @tool_cn_name("分组列表查询")
+    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        normalized_args = {"trial_status": trial_status}
+        return _safe_tool_call(
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            error_code="PACKAGE_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+        )
+
+    @tool_cn_name("分组解析")
+    def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_resolve(profile=profile, package_name=package_name),
+            error_code="PACKAGE_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": package_name}},
+        )
+
+    @tool_cn_name("搭建工具契约查询")
+    def builder_tool_contract(self, *, tool_name: str) -> JSONObject:
+        """执行工具方法逻辑。"""
+        requested = str(tool_name or "").strip()
+        public_tool_names = public_builder_contract_tool_names()
+        if requested in _PRIVATE_BUILDER_TOOL_CONTRACTS:
+            lookup_name = ""
+        else:
+            lookup_name = _BUILDER_TOOL_CONTRACT_ALIASES.get(requested, requested)
+            if lookup_name not in public_tool_names:
+                lookup_name = ""
+        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,
+        }
+
+    @tool_cn_name("分组创建")
+    def package_create(
+        self,
+        *,
+        profile: str,
+        package_name: str,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: JSONObject | None = None,
+    ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        visibility_patch = None
+        if visibility is not None:
+            try:
+                visibility_patch = VisibilityPatch.model_validate(visibility)
+            except ValidationError as exc:
+                return _visibility_validation_failure(str(exc), tool_name="package_create", exc=exc)
+        normalized_args = {
+            "package_name": package_name,
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.package_create(
+                profile=profile,
+                package_name=package_name,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+            ),
+            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 {}),
+                    **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+                },
+            },
+        )
+
+    @tool_cn_name("分组详情查询")
+    def package_get(self, *, profile: str, package_id: int | None = None) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        normalized_args = {"package_id": package_id}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.package_get(profile=profile, package_id=package_id),
+            error_code="PACKAGE_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+        ))
+
+    @tool_cn_name("分组配置应用")
+    def package_apply(
+        self,
+        *,
+        profile: str,
+        package_id: int | None = None,
+        package_name: str | None = None,
+        create_if_missing: bool = False,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: JSONObject | None = None,
+        items: list[dict] | None = None,
+        allow_detach: bool = False,
+    ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        visibility_patch = None
+        if visibility is not None:
+            try:
+                visibility_patch = VisibilityPatch.model_validate(visibility)
+            except ValidationError as exc:
+                return _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc)
+        normalized_args = {
+            "package_id": package_id,
+            **({"package_name": package_name} if str(package_name or "").strip() else {}),
+            "create_if_missing": bool(create_if_missing),
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+            **({"items": deepcopy(items)} if items is not None else {}),
+            "allow_detach": bool(allow_detach),
+        }
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.package_apply(
+                profile=profile,
+                package_id=package_id,
+                package_name=package_name,
+                create_if_missing=create_if_missing,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+                items=items,
+                allow_detach=allow_detach,
+            ),
+            error_code="PACKAGE_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
+        ))
+
+    @tool_cn_name("分组更新")
+    def package_update(
+        self,
+        *,
+        profile: str,
+        tag_id: int,
+        package_name: str | None = None,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: JSONObject | None = None,
+    ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        visibility_patch = None
+        if visibility is not None:
+            try:
+                visibility_patch = VisibilityPatch.model_validate(visibility)
+            except ValidationError as exc:
+                return _visibility_validation_failure(str(exc), tool_name="package_update", exc=exc)
+        normalized_args = {
+            "tag_id": tag_id,
+            **({"package_name": package_name} if str(package_name or "").strip() else {}),
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.package_update(
+                profile=profile,
+                tag_id=tag_id,
+                package_name=package_name,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+            ),
+            error_code="PACKAGE_UPDATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_update", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("方案安装")
+    def solution_install(
+        self,
+        *,
+        profile: str,
+        solution_key: str,
+        being_copy_data: bool = True,
+        solution_source: str = "solutionDetail",
+    ) -> JSONObject:
+        """执行方案相关逻辑。"""
+        normalized_args = {
+            "solution_key": solution_key,
+            "being_copy_data": being_copy_data,
+            "solution_source": solution_source,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.solution_install(
+                profile=profile,
+                solution_key=solution_key,
+                being_copy_data=being_copy_data,
+                solution_source=solution_source,
+            ),
+            error_code="SOLUTION_INSTALL_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("成员检索")
+    def member_search(
+        self,
+        *,
+        profile: str,
+        query: str,
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> JSONObject:
+        """执行工具方法逻辑。"""
+        normalized_args = {
+            "query": query,
+            "page_num": page_num,
+            "page_size": page_size,
+            "contain_disable": contain_disable,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.member_search(
+                profile=profile,
+                query=query,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            ),
+            error_code="MEMBER_SEARCH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("角色检索")
+    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}},
+        )
+
+    @tool_cn_name("角色创建")
+    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}},
+        )
+
+    @tool_cn_name("分组挂载应用")
+    def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
+        result = _safe_tool_call(
+            lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
+            error_code="PACKAGE_ATTACH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.package_attach_app(
+                profile=profile,
+                tag_id=tag_id,
+                app_key=app_key,
+                app_title=app_title,
+            ),
+        )
+
+    @tool_cn_name("释放应用编辑锁")
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            ),
+            error_code="EDIT_LOCK_RELEASE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用解析")
+    def app_resolve(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        app_name: str = "",
+        package_id: int | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key, "app_name": app_name, "package_id": package_id}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_id),
+            error_code="APP_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
+        ))
+
+    @tool_cn_name("应用按钮列表")
+    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}},
+        )
+
+    @tool_cn_name("应用按钮详情")
+    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}},
+        )
+
+    @tool_cn_name("应用按钮创建")
+    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}},
+        )
+
+    @tool_cn_name("应用按钮更新")
+    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}},
+        )
+
+    @tool_cn_name("应用按钮删除")
+    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}},
+        )
+
+    @tool_cn_name("应用摘要读取")
+    def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
+            error_code="APP_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+        ))
+
+    @tool_cn_name("应用详情查询")
+    def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_get(profile=profile, app_key=app_key),
+            error_code="APP_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+        ))
+
+    @tool_cn_name("应用字段摘要读取")
+    def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_fields(profile=profile, app_key=app_key),
+            error_code="FIELDS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用字段详情查询")
+    def app_get_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_fields(profile=profile, app_key=app_key),
+            error_code="APP_GET_FIELDS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("修复代码块字段")
+    def app_repair_code_blocks(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        field: str | None = None,
+        apply: bool = False,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key, "field": field, "apply": apply}
+        return _safe_tool_call(
+            lambda: self._facade.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply),
+            error_code="APP_REPAIR_CODE_BLOCKS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_repair_code_blocks", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用布局摘要读取")
+    def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_layout_summary(profile=profile, app_key=app_key),
+            error_code="LAYOUT_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用布局详情查询")
+    def app_get_layout(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_layout(profile=profile, app_key=app_key),
+            error_code="APP_GET_LAYOUT_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用视图摘要读取")
+    def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_views_summary(profile=profile, app_key=app_key),
+            error_code="VIEWS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用视图详情查询")
+    def app_get_views(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_views(profile=profile, app_key=app_key),
+            error_code="APP_GET_VIEWS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用流程摘要读取")
+    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
+            error_code="FLOW_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用流程详情查询")
+    def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
+            error_code="APP_GET_FLOW_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用图表摘要读取")
+    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_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用图表详情查询")
+    def app_get_charts(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_charts(profile=profile, app_key=app_key),
+            error_code="APP_GET_CHARTS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("门户列表查询")
+    def portal_list(self, *, profile: str) -> JSONObject:
+        """执行门户相关逻辑。"""
+        return _publicize_package_fields(_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}},
+        ))
+
+    @tool_cn_name("门户详情查询")
+    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 _publicize_package_fields(_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}},
+        ))
+
+    @tool_cn_name("门户摘要读取")
+    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 _publicize_package_fields(_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_get", "arguments": {"profile": profile, **normalized_args}},
+        ))
+
+    @tool_cn_name("视图详情查询")
+    def view_get(self, *, profile: str, view_key: str = "", viewgraph_key: str = "") -> JSONObject:
+        """执行视图相关逻辑。"""
+        resolved_view_key = str(view_key or viewgraph_key or "").strip()
+        normalized_args = {"view_key": resolved_view_key}
+        return _safe_tool_call(
+            lambda: self._facade.view_get(profile=profile, view_key=resolved_view_key),
+            error_code="VIEW_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("图表详情查询")
+    def chart_get(
+        self,
+        *,
+        profile: str,
+        chart_id: str,
+    ) -> JSONObject:
+        """执行图表相关逻辑。"""
+        normalized_args = {"chart_id": chart_id}
+        return _safe_tool_call(
+            lambda: self._facade.chart_get(profile=profile, chart_id=chart_id),
+            error_code="CHART_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+        )
+
+    @tool_cn_name("应用结构规划")
+    def app_schema_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        package_id: int | None = None,
+        app_name: str = "",
+        icon: str = "",
+        color: str = "",
+        visibility: JSONObject | None = None,
+        create_if_missing: bool = False,
+        add_fields: list[JSONObject],
+        update_fields: list[JSONObject],
+        remove_fields: list[JSONObject],
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        try:
+            request = SchemaPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "package_tag_id": package_id,
+                    "app_name": app_name,
+                    "icon": icon,
+                    "color": color,
+                    "visibility": visibility,
+                    "create_if_missing": create_if_missing,
+                    "add_fields": add_fields,
+                    "update_fields": update_fields,
+                    "remove_fields": remove_fields,
+                }
+            )
+        except ValidationError as exc:
+            return _visibility_validation_failure(
+                str(exc),
+                tool_name="app_schema_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_schema_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "package_id": package_id,
+                        "app_name": app_name,
+                        "icon": icon,
+                        "color": color,
+                        "visibility": visibility,
+                        "create_if_missing": create_if_missing,
+                        "add_fields": [{"name": "字段名称", "type": "text"}],
+                        "update_fields": [],
+                        "remove_fields": [],
+                    },
+                },
+            )
+        normalized_args = _publicize_package_fields(request.model_dump(mode="json"))
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_schema_plan(profile=profile, request=request),
+            error_code="SCHEMA_PLAN_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **normalized_args}},
+        ))
+
+    @tool_cn_name("应用布局规划")
+    def app_layout_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "merge",
+        sections: list[JSONObject] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        try:
+            request = LayoutPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "mode": mode,
+                    "sections": sections or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_layout_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_layout_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "mode": "merge",
+                        "sections": [{
+                            "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=normalized_request,
+            suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
+        )
+
+    @tool_cn_name("应用流程规划")
+    def app_flow_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        nodes: list[JSONObject] | None = None,
+        transitions: list[JSONObject] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        try:
+            request = FlowPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "mode": mode,
+                    "nodes": nodes or [],
+                    "transitions": transitions or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_flow_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_flow_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "mode": "replace",
+                        "preset": "basic_approval",
+                        "nodes": [],
+                        "transitions": [],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_plan(profile=profile, request=request),
+            error_code="FLOW_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
+    @tool_cn_name("应用视图规划")
+    def app_views_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_views: list[JSONObject] | None = None,
+        remove_views: list[str] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        try:
+            request = ViewsPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "upsert_views": upsert_views or [],
+                    "remove_views": remove_views or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _visibility_validation_failure(
+                str(exc),
+                tool_name="app_views_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_views_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "preset": "default_table",
+                        "upsert_views": [],
+                        "remove_views": [],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_views_plan(profile=profile, request=request),
+            error_code="VIEWS_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
+    @tool_cn_name("应用结构应用")
+    def app_schema_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        package_id: int | None = None,
+        app_name: str = "",
+        app_title: str = "",
+        icon: str = "",
+        color: str = "",
+        visibility: JSONObject | None = None,
+        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_id=package_id,
+            app_name=app_name,
+            app_title=app_title,
+            icon=icon,
+            color=color,
+            visibility=visibility,
+            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_id=package_id,
+                app_name=app_name,
+                app_title=app_title,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+                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_id: int | None = None,
+        app_name: str = "",
+        app_title: str = "",
+        icon: str = "",
+        color: str = "",
+        visibility: JSONObject | None = None,
+        create_if_missing: bool = False,
+        publish: bool = True,
+        add_fields: list[JSONObject],
+        update_fields: list[JSONObject],
+        remove_fields: list[JSONObject],
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        effective_app_name = app_name or app_title
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_schema_plan(
+                profile=profile,
+                app_key=app_key,
+                package_id=package_id,
+                app_name=effective_app_name,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                add_fields=add_fields,
+                update_fields=update_fields,
+                remove_fields=remove_fields,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_schema_plan",
+            apply_tool_name="app_schema_apply",
+        )
+        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
+            return plan_result
+        plan_args = plan_result.get("normalized_args")
+        if not isinstance(plan_args, dict):
+            plan_args = {}
+        try:
+            parsed_add = [FieldPatch.model_validate(item) for item in plan_args.get("add_fields") or []]
+            parsed_update = [FieldUpdatePatch.model_validate(item) for item in plan_args.get("update_fields") or []]
+            parsed_remove = [FieldRemovePatch.model_validate(item) for item in plan_args.get("remove_fields") or []]
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_schema_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_schema_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "package_id": plan_args.get("package_id", package_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),
+                        "visibility": plan_args.get("visibility") or visibility,
+                        "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+                        "publish": publish,
+                        "add_fields": plan_args.get("add_fields") or [{"name": "字段名称", "type": "text", "required": False}],
+                        "update_fields": plan_args.get("update_fields") or [],
+                        "remove_fields": plan_args.get("remove_fields") or [],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "package_id": plan_args.get("package_id", package_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 ""),
+            "visibility": plan_args.get("visibility") or visibility,
+            "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+            "publish": publish,
+            "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
+            "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
+            "remove_fields": [patch.model_dump(mode="json") for patch in parsed_remove],
+        }
+        result = _safe_tool_call(
+            lambda: self._facade.app_schema_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                package_tag_id=plan_args.get("package_id", package_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 ""),
+                visibility=VisibilityPatch.model_validate(plan_args.get("visibility")) if plan_args.get("visibility") is not None else None,
+                create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
+                publish=publish,
+                add_fields=parsed_add,
+                update_fields=parsed_update,
+                remove_fields=parsed_remove,
+            ),
+            error_code="SCHEMA_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return _publicize_package_fields(result)
+
+    @tool_cn_name("应用布局应用")
+    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        """执行应用相关逻辑。"""
+        result = self._app_layout_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            sections=sections,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_layout_apply_once(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                sections=sections,
+            ),
+        )
+
+    def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_layout_plan(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                sections=sections,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_layout_plan",
+            apply_tool_name="app_layout_apply",
+        )
+        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
+            return plan_result
+        plan_args = plan_result.get("normalized_args")
+        if not isinstance(plan_args, dict):
+            plan_args = {}
+        try:
+            parsed_mode = LayoutApplyMode(str(plan_args.get("mode") or mode))
+            parsed_sections = [LayoutSectionPatch.model_validate(item) for item in plan_args.get("sections") or []]
+        except (ValueError, ValidationError) as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_layout_apply",
+                exc=exc if isinstance(exc, ValidationError) else None,
+                suggested_next_call={
+                    "tool_name": "app_layout_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "mode": str(plan_args.get("mode") or "merge"),
+                        "publish": publish,
+                        "sections": plan_args.get("sections") or [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "mode": parsed_mode.value,
+            "publish": publish,
+            "sections": [section.model_dump(mode="json", exclude_none=True) for section in parsed_sections],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                mode=parsed_mode,
+                publish=publish,
+                sections=parsed_sections,
+            ),
+            error_code="LAYOUT_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用流程应用")
+    def app_flow_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[JSONObject],
+        transitions: list[JSONObject],
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        result = self._app_flow_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            nodes=nodes,
+            transitions=transitions,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_flow_apply_once(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                nodes=nodes,
+                transitions=transitions,
+            ),
+        )
+
+    def _app_flow_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[JSONObject],
+        transitions: list[JSONObject],
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_flow_plan(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                nodes=nodes,
+                transitions=transitions,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_flow_plan",
+            apply_tool_name="app_flow_apply",
+        )
+        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
+            return plan_result
+        plan_args = plan_result.get("normalized_args")
+        if not isinstance(plan_args, dict):
+            plan_args = {}
+        try:
+            request = FlowPlanRequest.model_validate(
+                {
+                    "app_key": plan_args.get("app_key") or app_key,
+                    "mode": plan_args.get("mode") or mode,
+                    "nodes": plan_args.get("nodes") or [],
+                    "transitions": plan_args.get("transitions") or [],
+                    "preset": None,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_flow_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_flow_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "mode": str(plan_args.get("mode") or "replace"),
+                        "publish": publish,
+                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
+                        "transitions": plan_args.get("transitions") or [],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": request.app_key,
+            "mode": request.mode,
+            "publish": publish,
+            "nodes": [node.model_dump(mode="json") for node in request.nodes],
+            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_apply(
+                profile=profile,
+                app_key=request.app_key,
+                mode=request.mode,
+                publish=publish,
+                nodes=[node.model_dump(mode="json") for node in request.nodes],
+                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+            ),
+            error_code="FLOW_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用视图应用")
+    def app_views_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        publish: bool = True,
+        upsert_views: list[JSONObject],
+        remove_views: list[str],
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        result = self._app_views_apply_once(
+            profile=profile,
+            app_key=app_key,
+            publish=publish,
+            upsert_views=upsert_views,
+            remove_views=remove_views,
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_views_apply_once(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                remove_views=remove_views,
+                upsert_views=upsert_views,
+            ),
+        )
+
+    def _app_views_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        publish: bool = True,
+        upsert_views: list[JSONObject],
+        remove_views: list[str],
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        plan_result = self._rewrite_plan_result_for_apply(
+            result=self.app_views_plan(
+                profile=profile,
+                app_key=app_key,
+                upsert_views=upsert_views,
+                remove_views=remove_views,
+                preset=None,
+            ),
+            profile=profile,
+            publish=publish,
+            plan_tool_name="app_views_plan",
+            apply_tool_name="app_views_apply",
+        )
+        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
+            return plan_result
+        plan_args = plan_result.get("normalized_args")
+        if not isinstance(plan_args, dict):
+            plan_args = {}
+        try:
+            parsed_views = [ViewUpsertPatch.model_validate(item) for item in plan_args.get("upsert_views") or []]
+        except ValidationError as exc:
+            return _visibility_validation_failure(
+                str(exc),
+                tool_name="app_views_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_views_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "publish": publish,
+                        "upsert_views": plan_args.get("upsert_views") or [{"name": "全部数据", "type": "table", "columns": ["字段A"]}],
+                        "remove_views": plan_args.get("remove_views") or [],
+                    },
+                },
+            )
+        normalized_args = {
+            "app_key": str(plan_args.get("app_key") or app_key),
+            "publish": publish,
+            "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+            "remove_views": list(plan_args.get("remove_views") or remove_views),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_views_apply(
+                profile=profile,
+                app_key=str(plan_args.get("app_key") or app_key),
+                publish=publish,
+                upsert_views=parsed_views,
+                remove_views=list(plan_args.get("remove_views") or remove_views),
+            ),
+            error_code="VIEWS_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("图表配置应用")
+    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,
+        )
+
+    @tool_cn_name("应用图表应用")
+    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 _visibility_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}},
+        )
+
+    @tool_cn_name("门户配置应用")
+    def portal_apply(
+        self,
+        *,
+        profile: str,
+        dash_key: str = "",
+        dash_name: str = "",
+        package_id: int | None = None,
+        publish: bool = True,
+        sections: list[JSONObject] | None = None,
+        visibility: 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:
+        """执行门户相关逻辑。"""
+        try:
+            request = PortalApplyRequest.model_validate(
+                {
+                    "dash_key": dash_key or None,
+                    "dash_name": dash_name or None,
+                    "package_tag_id": package_id,
+                    "publish": publish,
+                    "sections": sections or [],
+                    "visibility": visibility,
+                    "auth": auth,
+                    "icon": icon,
+                    "color": color,
+                    "hide_copyright": hide_copyright,
+                    "dash_global_config": dash_global_config,
+                    "config": config or {},
+                }
+            )
+        except ValidationError as exc:
+            return _visibility_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_id": package_id or 1001,
+                        "publish": True,
+                        "sections": [
+                            {
+                                "title": "经营概览",
+                                "source_type": "text",
+                                "text": "欢迎使用业务门户",
+                            }
+                        ],
+                    },
+                },
+            )
+        normalized_args = request.model_dump(mode="json")
+        normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
+        return _publicize_package_fields(_safe_tool_call(
+            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}},
+        ))
+
+    @tool_cn_name("应用发布校验")
+    def app_publish_verify(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        expected_package_id: int | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key, "expected_package_id": expected_package_id}
+        result = _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
+            error_code="PUBLISH_VERIFY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
+        ))
+        return _publicize_package_fields(self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_tag_id=expected_package_id,
+            ),
+        ))
+
+    def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
+            return result
+        suggested = result.get("suggested_next_call")
+        if not isinstance(suggested, dict) or suggested.get("tool_name") != "app_release_edit_lock_if_mine":
+            return result
+        arguments = suggested.get("arguments")
+        if not isinstance(arguments, dict):
+            return result
+        app_key = str(arguments.get("app_key") or "")
+        lock_owner_email = str(arguments.get("lock_owner_email") or "")
+        lock_owner_name = str(arguments.get("lock_owner_name") or "")
+        release_attempts: list[JSONObject] = []
+        retried: JSONObject = result
+        for _ in range(3):
+            release_result = self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+            release_attempts.append(release_result)
+            if not isinstance(release_result, dict) or release_result.get("status") != "success":
+                result.setdefault("details", {})
+                if isinstance(result["details"], dict):
+                    result["details"]["edit_lock_release_result"] = release_result
+                    result["details"]["edit_lock_release_attempts"] = release_attempts
+                return result
+            retried = retry_call()
+            if not (
+                isinstance(retried, dict)
+                and retried.get("status") == "failed"
+                and retried.get("error_code") == "APP_EDIT_LOCKED"
+            ):
+                break
+            time.sleep(0.2)
+        if (
+            isinstance(retried, dict)
+            and retried.get("status") == "failed"
+            and retried.get("error_code") == "APP_EDIT_LOCKED"
+        ):
+            retried = {
+                **retried,
+                "error_code": "PERSISTENT_SELF_LOCK",
+                "message": "app remains locked by the current user's active editor session after repeated forced release attempts",
+                "recoverable": True,
+                "suggested_next_call": None,
+            }
+        if isinstance(retried, dict):
+            retried.setdefault("details", {})
+            if isinstance(retried["details"], dict):
+                retried["details"]["edit_lock_release_result"] = release_attempts[-1] if release_attempts else None
+                retried["details"]["edit_lock_release_attempts"] = release_attempts
+            retried["edit_lock_released"] = bool(release_attempts)
+            retried["retried_after_edit_lock_release"] = True
+        return retried
+
+    def _rewrite_plan_result_for_apply(
+        self,
+        *,
+        result: JSONObject,
+        profile: str,
+        publish: bool,
+        plan_tool_name: str,
+        apply_tool_name: str,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        if not isinstance(result, dict):
+            return result
+        rewritten = dict(result)
+        if rewritten.get("error_code") == "VALIDATION_ERROR":
+            contract = _BUILDER_TOOL_CONTRACTS.get(apply_tool_name)
+            details = rewritten.get("details")
+            if not isinstance(details, dict):
+                details = {}
+                rewritten["details"] = details
+            if isinstance(contract, dict):
+                rewritten["allowed_values"] = deepcopy(contract.get("allowed_values", {}))
+                details["allowed_keys"] = deepcopy(contract.get("allowed_keys", []))
+                details["section_allowed_keys"] = deepcopy(contract.get("section_allowed_keys", []))
+                details["section_aliases"] = deepcopy(contract.get("section_aliases", {}))
+                details["minimal_section_example"] = deepcopy(contract.get("minimal_section_example"))
+        suggested_next_call = rewritten.get("suggested_next_call")
+        if isinstance(suggested_next_call, dict):
+            if suggested_next_call.get("tool_name") == plan_tool_name:
+                arguments = suggested_next_call.get("arguments")
+                normalized_arguments = dict(arguments) if isinstance(arguments, dict) else {}
+                normalized_arguments.setdefault("profile", profile)
+                normalized_arguments["publish"] = publish
+                rewritten["suggested_next_call"] = {
+                    **suggested_next_call,
+                    "tool_name": apply_tool_name,
+                    "arguments": normalized_arguments,
+                }
+                return rewritten
+            if rewritten.get("error_code") == "VALIDATION_ERROR" and suggested_next_call.get("tool_name") == apply_tool_name:
+                arguments = suggested_next_call.get("arguments")
+                normalized_arguments = dict(arguments) if isinstance(arguments, dict) else {}
+                normalized_arguments.setdefault("profile", profile)
+                normalized_arguments["publish"] = publish
+                if isinstance(details, dict):
+                    details["canonical_arguments"] = normalized_arguments
+                rewritten["suggested_next_call"] = {
+                    **suggested_next_call,
+                    "arguments": normalized_arguments,
+                }
+        if rewritten.get("status") == "success":
+            normalized_args = rewritten.get("normalized_args")
+            if isinstance(normalized_args, dict):
+                rewritten["suggested_next_call"] = {
+                    "tool_name": apply_tool_name,
+                    "arguments": {"profile": profile, **normalized_args, "publish": publish},
+                }
+        return rewritten
+
+
+def _validation_failure(
+    detail: str,
+    *,
+    tool_name: str | None = None,
+    exc: ValidationError | None = None,
+    suggested_next_call: JSONObject | None = None,
+) -> JSONObject:
+    contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    reason_path = None
+    if exc is not None:
+        errors = exc.errors()
+        if errors:
+            loc = errors[0].get("loc")
+            if isinstance(loc, (tuple, list)):
+                reason_path = ".".join(str(part) for part in loc)
+    canonical_arguments = None
+    if isinstance(suggested_next_call, dict):
+        arguments = suggested_next_call.get("arguments")
+        if isinstance(arguments, dict):
+            canonical_arguments = arguments
+    return {
+        "status": "failed",
+        "error_code": "VALIDATION_ERROR",
+        "recoverable": True,
+        "message": detail,
+        "normalized_args": {},
+        "missing_fields": [],
+        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
+        "details": {
+            "validation_detail": detail,
+            "reason_path": reason_path,
+            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+            "canonical_arguments": canonical_arguments,
+            "section_allowed_keys": deepcopy(contract.get("section_allowed_keys", [])) if isinstance(contract, dict) else [],
+            "section_aliases": deepcopy(contract.get("section_aliases", {})) if isinstance(contract, dict) else {},
+            "minimal_section_example": deepcopy(contract.get("minimal_section_example")) if isinstance(contract, dict) else None,
+        },
+        "suggested_next_call": suggested_next_call,
+        "request_id": None,
+        "backend_code": None,
+        "http_status": None,
+        "noop": False,
+        "verification": {},
+    }
+
+
+def _visibility_validation_failure(
+    detail: str,
+    *,
+    tool_name: str,
+    exc: ValidationError | None,
+    suggested_next_call: JSONObject | None = None,
+) -> JSONObject:
+    result = _validation_failure(
+        detail,
+        tool_name=tool_name,
+        exc=exc,
+        suggested_next_call=suggested_next_call,
+    )
+    lowered = detail.lower()
+    code_by_fragment = [
+        ("visibility and auth cannot be provided together", "VISIBILITY_CONFLICT"),
+        ("specific visibility requires selectors", "VISIBILITY_SELECTOR_REQUIRED"),
+        ("selectors are only allowed when mode=specific", "VISIBILITY_SELECTOR_UNEXPECTED"),
+        ("external_mode=specific requires external_selectors", "EXTERNAL_VISIBILITY_SELECTOR_REQUIRED"),
+        ("external_selectors are only allowed when external_mode=specific", "EXTERNAL_VISIBILITY_SELECTOR_UNEXPECTED"),
+        ("mode=everyone requires external_mode=workspace", "VISIBILITY_EXTERNAL_MODE_CONFLICT"),
+        ("external_selectors are not allowed when mode=everyone", "VISIBILITY_SELECTOR_UNEXPECTED"),
+    ]
+    for fragment, error_code in code_by_fragment:
+        if fragment in lowered:
+            result["error_code"] = error_code
+            result["message"] = fragment
+            details = result.get("details")
+            if isinstance(details, dict):
+                details["visibility_error"] = True
+            break
+    return result
+
+
+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,
+    *,
+    error_code: str,
+    normalized_args: JSONObject,
+    suggested_next_call: JSONObject | None,
+) -> JSONObject:
+    try:
+        return call()
+    except (QingflowApiError, RuntimeError) as error:
+        api_error = _coerce_api_error(error)
+        public_http_status = None if api_error.http_status == 404 else api_error.http_status
+        return {
+            "status": "failed",
+            "error_code": error_code,
+            "recoverable": True,
+            "message": _public_error_message(error_code, api_error),
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "transport_error": {
+                    "http_status": api_error.http_status,
+                    "backend_code": api_error.backend_code,
+                    "category": api_error.category,
+                }
+            },
+            "suggested_next_call": suggested_next_call,
+            "request_id": api_error.request_id,
+            "backend_code": api_error.backend_code,
+            "http_status": public_http_status,
+            "noop": False,
+            "verification": {},
+        }
+
+
+def _publicize_package_fields(value):
+    if isinstance(value, list):
+        return [_publicize_package_fields(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+    key_map = {
+        "tag_id": "package_id",
+        "tag_ids": "package_ids",
+        "tag_ids_before": "package_ids_before",
+        "tag_ids_after": "package_ids_after",
+        "tag_name": "package_name",
+        "tag_icon": "icon",
+        "package_tag_id": "package_id",
+        "package_tag_ids": "package_ids",
+        "expected_package_tag_id": "expected_package_id",
+    }
+    public: JSONObject = {}
+    for key, item in value.items():
+        public_key = key_map.get(key, key)
+        public[public_key] = _publicize_package_fields(item)
+    return public
+
+
+def _coerce_api_error(error: Exception) -> QingflowApiError:
+    if isinstance(error, QingflowApiError):
+        return error
+    if isinstance(error, RuntimeError):
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("category") and payload.get("message"):
+            details = payload.get("details")
+            return QingflowApiError(
+                category=str(payload.get("category")),
+                message=str(payload.get("message")),
+                backend_code=payload.get("backend_code"),
+                request_id=payload.get("request_id"),
+                http_status=payload.get("http_status"),
+                details=details if isinstance(details, dict) else None,
+            )
+    return QingflowApiError(category="runtime", message=str(error))
+
+
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+        return "app is currently locked by another active editor session"
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
+        "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
+        "SOLUTION_INSTALL_FAILED": "solution install could not complete because the app creation route or solution source is unavailable",
+        "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",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_PLAN_FAILED": "schema planning could not load the required app state in the current route",
+        "LAYOUT_PLAN_FAILED": "layout planning could not load the required app state in the current route",
+        "FLOW_PLAN_FAILED": "flow planning could not load the required app state in the current route",
+        "VIEWS_PLAN_FAILED": "views planning could not load the required app state in the current route",
+        "SCHEMA_APPLY_FAILED": "schema apply could not complete because the app route or readback is unavailable",
+        "LAYOUT_APPLY_FAILED": "layout apply could not complete because the layout route or readback is unavailable",
+        "FLOW_APPLY_FAILED": "flow apply could not complete because the workflow route or readback is unavailable",
+        "VIEWS_APPLY_FAILED": "views apply could not complete because the views route or readback is unavailable",
+        "CHART_APPLY_FAILED": "chart apply could not complete because the QingBI route or readback is unavailable",
+        "PORTAL_APPLY_FAILED": "portal apply could not complete because the portal route or readback is unavailable",
+        "PUBLISH_VERIFY_FAILED": "publish verification is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")
+
+
+_VISIBILITY_ALLOWED_VALUES: JSONObject = {
+    "visibility.mode": ["workspace", "everyone", "specific"],
+    "visibility.external_mode": ["not", "workspace", "specific"],
+    "visibility.selectors": [
+        "member_uids",
+        "member_emails",
+        "member_names",
+        "dept_ids",
+        "dept_names",
+        "role_ids",
+        "role_names",
+        "include_sub_departs",
+    ],
+    "visibility.external_selectors": ["member_ids", "member_emails", "dept_ids"],
+}
+
+
+_VISIBILITY_EXECUTION_NOTES = [
+    "visibility is the canonical public auth shape for packages, apps, views, charts, and portals",
+    "mode=workspace means internal workspace members; mode=everyone means all users; mode=specific requires selectors",
+    "external_mode defaults to not and controls external-user visibility independently unless mode=everyone",
+    "name selectors must resolve to exactly one member, department, or role; ambiguous names fail instead of guessing",
+    "when updating an existing resource, omit visibility to preserve the current backend auth",
+]
+
+
+_VISIBILITY_WORKSPACE_EXAMPLE: JSONObject = {
+    "mode": "workspace",
+    "selectors": {},
+    "external_mode": "not",
+    "external_selectors": {},
+}
+
+
+_VISIBILITY_SPECIFIC_EXAMPLE: JSONObject = {
+    "mode": "specific",
+    "selectors": {
+        "member_emails": ["owner@example.com"],
+        "role_names": ["项目经理"],
+        "include_sub_departs": False,
+    },
+    "external_mode": "not",
+    "external_selectors": {},
+}
+
+
+_BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
+    "file_upload_local": {
+        "allowed_keys": ["upload_kind", "file_path", "upload_mark", "content_type", "bucket_type", "path_id", "file_related_url"],
+        "aliases": {},
+        "allowed_values": {"upload_kind": ["attachment", "login"]},
+        "execution_notes": [
+            "returns upload metadata plus attachment-ready values for later builder or user writes",
+            "upload_kind=attachment may fall back to login upload info when the backend rejects attachment upload info",
+            "upload_mark is recommended for attachment uploads because it affects the remote storage path",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "upload_kind": "attachment",
+            "file_path": "/absolute/path/to/local-file.txt",
+            "upload_mark": "APP_KEY",
+        },
+    },
+    "feedback_submit": {
+        "allowed_keys": [
+            "category",
+            "title",
+            "description",
+            "expected_behavior",
+            "actual_behavior",
+            "impact_scope",
+            "tool_name",
+            "app_key",
+            "record_id",
+            "workflow_node_id",
+            "note",
+        ],
+        "aliases": {},
+        "allowed_values": {"category": ["bug", "missing_capability", "awkward_workflow", "ux", "docs"]},
+        "execution_notes": [
+            "submit feedback only after explicit user confirmation",
+            "use this when the current builder capability is unsupported or awkward after reasonable attempts",
+            "requires feedback qsource configuration but does not require Qingflow login or workspace selection",
+        ],
+        "minimal_example": {
+            "category": "missing_capability",
+            "title": "builder chart data read gap",
+            "description": "The current builder capability cannot satisfy the requested workflow.",
+            "tool_name": "chart_get",
+        },
+    },
+    "package_get": {
+        "allowed_keys": ["package_id"],
+        "aliases": {"packageId": "package_id"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns complete public package schema with package_id, package_name, icon, visibility, and items",
+            "package_id maps internally to backend tagId; do not use tag_id in public calls",
+            "visibility is normalized from backend MemberAuthInfoVO auth",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "package_id": 1001,
+        },
+    },
+    "package_apply": {
+        "allowed_keys": ["package_id", "package_name", "create_if_missing", "icon", "color", "visibility", "items", "allow_detach"],
+        "aliases": {
+            "packageId": "package_id",
+            "packageName": "package_name",
+            "createIfMissing": "create_if_missing",
+            "iconName": "icon",
+            "iconColor": "color",
+            "allowDetach": "allow_detach",
+        },
+        "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        "execution_notes": [
+            "create or update package metadata, visibility, grouping, and ordering in one call",
+            "package_id maps internally to backend tagId; do not use tag_id in public calls",
+            "items is a full package layout tree; omitting existing app/portal items is blocked unless allow_detach=true",
+            "item shapes: {type:'app', app_key}, {type:'portal', dash_key}, or {type:'group', group_id?, name, items:[...]}",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "package_id": 1001,
+            "package_name": "项目管理",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+            "items": [{"type": "app", "app_key": "APP_KEY", "title": "项目台账"}],
+            "allow_detach": False,
+        },
+        "specific_visibility_example": {
+            "profile": "default",
+            "package_id": 1001,
+            "visibility": deepcopy(_VISIBILITY_SPECIFIC_EXAMPLE),
+        },
+        "create_example": {
+            "profile": "default",
+            "package_name": "项目管理",
+            "create_if_missing": True,
+            "icon": "files-folder",
+            "color": "azure",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+        },
+    },
+    "solution_install": {
+        "allowed_keys": ["solution_key", "being_copy_data", "solution_source"],
+        "aliases": {
+            "solutionKey": "solution_key",
+            "beingCopyData": "being_copy_data",
+            "copy_data": "being_copy_data",
+            "copyData": "being_copy_data",
+            "solutionSource": "solution_source",
+            "source": "solution_source",
+        },
+        "allowed_values": {
+            "being_copy_data": [True, False],
+            "solution_source": ["solutionDetail"],
+        },
+        "execution_notes": [
+            "solution_install calls the backend app creation route with a solutionKey payload",
+            "this is a write operation that may create multiple apps at once",
+            "app_keys are verified from the backend response when available",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "solution_key": "cfqrhth99401",
+            "being_copy_data": True,
+            "solution_source": "solutionDetail",
+        },
+    },
+    "member_search": {
+        "allowed_keys": ["query", "page_num", "page_size", "contain_disable"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "query": "严琪东",
+            "page_num": 1,
+            "page_size": 20,
+            "contain_disable": False,
+        },
+    },
+    "role_search": {
+        "allowed_keys": ["keyword", "page_num", "page_size"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "keyword": "项目经理",
+            "page_num": 1,
+            "page_size": 20,
+        },
+    },
+    "role_create": {
+        "allowed_keys": ["role_name", "member_uids", "member_emails", "member_names", "role_icon"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "role_name": "研发负责人",
+            "member_names": ["严琪东"],
+            "member_uids": [],
+            "member_emails": [],
+            "role_icon": "ex-user-outlined",
+        },
+    },
+    "app_resolve": {
+        "allowed_keys": ["app_key", "app_name", "package_id"],
+        "aliases": {"packageId": "package_id"},
+        "allowed_values": {},
+        "execution_notes": [
+            "use exactly one selector mode",
+            "mode 1: app_key",
+            "mode 2: app_name + package_id",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+        "package_scoped_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_id": 1001,
+        },
+    },
+    "app_release_edit_lock_if_mine": {
+        "allowed_keys": ["app_key", "lock_owner_email", "lock_owner_name"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "use this only after a builder write fails with APP_EDIT_LOCKED and the lock belongs to the current user",
+            "supply the lock owner details from the failed write result for a safe release attempt",
+            "after a successful release, retry the blocked builder write or publish verification call",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "lock_owner_email": "user@example.com",
+            "lock_owner_name": "当前用户",
+        },
+    },
+    "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],
+        },
+        "execution_notes": [
+            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "background_color and text_color cannot both be white",
+            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+        ],
+        "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],
+        },
+        "execution_notes": [
+            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "background_color and text_color cannot both be white",
+            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+        ],
+        "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_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "packageId": "package_id",
+            "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.departmentScope": "field.department_scope",
+            "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",
+            "field.subfieldUpdates": "field.subfield_updates",
+        },
+        "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()),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "create mode may set visibility for the new app; edit mode may update visibility on an existing app",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_id": 1001,
+            "icon": "template",
+            "color": "emerald",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+            "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_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "packageId": "package_id",
+            "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.departmentScope": "field.department_scope",
+            "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",
+            "field.subfieldUpdates": "field.subfield_updates",
+        },
+        "allowed_values": {
+            "field.type": [member.value for member in PublicFieldType],
+            "field.relation_mode": [member.value for member in PublicRelationMode],
+            "field.department_scope.mode": ["all", "custom"],
+            "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()),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "use exactly one resource mode",
+            "edit mode: app_key, optional app_name to rename the existing app",
+            "create mode: package_id + app_name + create_if_missing=true",
+            "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
+            *_VISIBILITY_EXECUTION_NOTES,
+            "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
+            "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
+            "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
+            "relation fields now require both display_field and visible_fields in MCP/CLI payloads",
+            "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",
+            "update_fields[].set.subfield_updates is the safe patch path for editing existing subtable child fields without rebuilding the entire subtable",
+            "subfield_updates only supports safe child overlays: name, required, description, and nested subfield_updates",
+            "set.subfields remains the full replace/rebuild path for a subtable and is higher risk when hidden relation/reference children exist",
+            "department fields accept department_scope with mode=all or mode=custom; custom scope requires explicit departments[].dept_id and optional include_sub_departs",
+            "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 outputs must be emitted through qf_output assignment; use qf_output = {...} or assign qf_output after building the result object, never const/let qf_output =",
+            "builder automatically normalizes const/let qf_output assignments on write and rejects output-bound code blocks that still do not contain a valid qf_output assignment",
+            "code_block_binding and q_linker_binding target fields are limited to text, long_text, number, amount, date, datetime, single_select, multi_select, and boolean",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_id": 1001,
+            "icon": "template",
+            "color": "emerald",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+            "create_if_missing": True,
+            "publish": True,
+            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+        "rename_example": {
+            "profile": "default",
+            "app_key": "APP_PROJECT",
+            "app_name": "项目主数据",
+            "publish": True,
+            "add_fields": [],
+            "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": [],
+        },
+        "subfield_update_example": {
+            "profile": "default",
+            "app_key": "APP_REWARD",
+            "publish": True,
+            "add_fields": [],
+            "update_fields": [
+                {
+                    "selector": {"que_id": 441305044},
+                    "set": {
+                        "subfield_updates": [
+                            {
+                                "selector": {"que_id": 441305045},
+                                "set": {"name": "景品名"},
+                            }
+                        ]
+                    },
+                }
+            ],
+            "remove_fields": [],
+        },
+        "department_scope_example": {
+            "profile": "default",
+            "app_key": "APP_LEAD",
+            "publish": True,
+            "add_fields": [
+                {
+                    "name": "归属部门",
+                    "type": "department",
+                    "department_scope": {
+                        "mode": "custom",
+                        "departments": [{"dept_id": 334952, "dept_name": "生产"}],
+                        "include_sub_departs": False,
+                    },
+                }
+            ],
+            "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", "upsert_views[].visibility"],
+        "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"],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "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", "upsert_views[].visibility"],
+        "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"],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "apply may return partial_success when some views land and others fail",
+            "when duplicate view names exist, supply view_key to target the exact view",
+            "read back app_get_views after any failed or partial view apply",
+            "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
+            "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
+            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "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_get": {
+        "allowed_keys": ["app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns builder-side app configuration summary and editability",
+            "use this as the default builder discovery read before fields/layout/views/flow/charts detail reads",
+            "editability is route-aware builder capability summary, not end-user data visibility",
+            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility",
+            "can_edit_form covers form/schema routes only and does not imply app base-info writes",
+            "returns normalized app visibility when backend auth is readable",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_fields": {
+        "allowed_keys": ["app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns compact current field configuration for one app",
+            "use this before app_schema_apply when you need exact field definitions",
+            "subtable fields include nested subfields using the same compact field shape",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_layout": {
+        "allowed_keys": ["app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns compact current layout configuration for one app",
+            "use this before app_layout_apply when you need paragraph and row structure",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_views": {
+        "allowed_keys": ["app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns compact current view inventory for one app",
+            "use this before app_views_apply when you need exact current view keys",
+            "view items include visibility_summary when backend view auth is readable",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_flow": {
+        "allowed_keys": ["app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns workflow configuration summary for one app",
+            "use this before app_flow_apply when you need the current node structure",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_get_charts": {
+        "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",
+            "chart items include visibility_summary when QingBI base info is readable",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "portal_list": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns builder-configurable portal list items only",
+            "use this as the builder 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 builder-side portal configuration detail plus a normalized component inventory",
+            "chart and view components are returned as refs only; use builder chart_get or builder view_get for configuration detail",
+            "being_draft=true reads the current draft view; being_draft=false reads live",
+            "returns normalized portal visibility when backend auth is readable",
+        ],
+        "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", "upsert_charts[].visibility"],
+        "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],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+            "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",
+                "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
+                "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
+                *_VISIBILITY_EXECUTION_NOTES,
+            ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "remove_chart_ids": [],
+            "reorder_chart_ids": [],
+        },
+    },
+    "view_get": {
+        "allowed_keys": ["view_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns one builder-side view definition detail",
+            "does not return record data; use user-side view_get or record_list for runtime rows",
+            "use this after builder portal_get when a component references a view_ref.view_key",
+            "returns normalized view visibility when backend auth is readable",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "view_key": "VIEW_KEY",
+        },
+    },
+    "chart_get": {
+        "allowed_keys": ["chart_id"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns builder-side chart base info and chart config only",
+            "chart_id is required; chart names are not accepted here",
+            "does not return chart data; use user-side chart_get for runtime data access",
+            "returns normalized chart visibility from QingBI visibleAuth when readable",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "chart_id": "CHART_ID",
+        },
+    },
+    "portal_apply": {
+        "allowed_keys": ["dash_key", "dash_name", "package_id", "publish", "sections", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "aliases": {
+            "packageId": "package_id",
+            "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"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
+            "execution_notes": [
+                "use exactly one resource mode",
+                "update mode: dash_key",
+                "create mode: package_id + dash_name",
+                "portal_apply uses replace semantics for sections",
+                "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
+                "remove a section by omitting it from the new sections list",
+                "package_id is required when creating a new portal",
+                "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
+            "chart_ref resolves by chart_id first, then exact unique chart_name",
+            "view_ref resolves by view_key first, then exact unique view_name",
+            "position.pc/mobile is the canonical portal layout shape",
+            "visibility is the canonical public auth shape; auth is kept only as a deprecated compatibility alias",
+            "passing visibility and auth together is rejected as VISIBILITY_CONFLICT",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_name": "经营门户",
+            "package_id": 1001,
+            "publish": True,
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+            "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},
+            },
+        },
+    },
+    "app_publish_verify": {
+        "allowed_keys": ["app_key", "expected_package_id"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "verifies that the current app draft has been published and is readable through the builder surface",
+            "expected_package_id is optional and adds an extra package consistency check",
+            "when verification fails because of an edit lock owned by the current user, retry after app_release_edit_lock_if_mine",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "expected_package_id": 1001,
+        },
+    },
+    "app_repair_code_blocks": {
+        "allowed_keys": ["app_key", "field", "apply"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "scan existing code_block fields for qf_output shadowing, missing output assignment, and broken writeback defaults",
+            "apply=false is a dry-run and returns a repair plan without writing builder config",
+            "apply=true rewrites only safe cases: const/let qf_output shadowing and stale relation-default output bindings reconstructed from readable code_block_binding config",
+            "this tool does not invent missing output aliases or guess missing target bindings when only low-level codeBlockConfig is present",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "field": "线索价值评估",
+            "apply": False,
+        },
+    },
+}
+
+_PRIVATE_BUILDER_TOOL_CONTRACTS = {
+    "app_schema_plan",
+    "app_layout_plan",
+    "app_flow_plan",
+    "app_views_plan",
+}
+
+_BUILDER_TOOL_CONTRACT_ALIASES = {}