@josephyan/qingflow-app-user-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1,27 +1,43 @@
 from __future__ import annotations
 
+from copy import deepcopy
+import json
+import time
+
 from pydantic import ValidationError
 
 from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
+    FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
+    FlowConditionOperator,
+    FlowPreset,
     FlowNodePatch,
     FlowPlanRequest,
     FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
+    LayoutPreset,
     LayoutSectionPatch,
+    PublicFieldType,
+    PublicFlowNodeType,
+    PublicViewType,
     SchemaPlanRequest,
+    ViewFilterOperator,
     ViewUpsertPatch,
+    ViewsPreset,
     ViewsPlanRequest,
 )
 from ..builder_facade.service import AiBuilderFacade
 from .app_tools import AppTools
 from .base import ToolBase
+from .directory_tools import DirectoryTools
 from .package_tools import PackageTools
+from .role_tools import RoleTools
 from .solution_tools import SolutionTools
 from .view_tools import ViewTools
 from .workflow_tools import WorkflowTools
@@ -35,6 +51,8 @@ class AiBuilderTools(ToolBase):
             packages=PackageTools(sessions, backend),
             views=ViewTools(sessions, backend),
             workflows=WorkflowTools(sessions, backend),
+            roles=RoleTools(sessions, backend),
+            directory=DirectoryTools(sessions, backend),
             solutions=SolutionTools(sessions, backend),
         )
 
@@ -47,6 +65,57 @@ class AiBuilderTools(ToolBase):
         def package_resolve(profile: str = DEFAULT_PROFILE, package_name: str = "") -> JSONObject:
             return self.package_resolve(profile=profile, package_name=package_name)
 
+        @mcp.tool()
+        def builder_tool_contract(tool_name: str = "") -> JSONObject:
+            return self.builder_tool_contract(tool_name=tool_name)
+
+        @mcp.tool()
+        def package_create(profile: str = DEFAULT_PROFILE, package_name: str = "") -> JSONObject:
+            return self.package_create(profile=profile, package_name=package_name)
+
+        @mcp.tool()
+        def member_search(
+            profile: str = DEFAULT_PROFILE,
+            query: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+            contain_disable: bool = False,
+        ) -> JSONObject:
+            return self.member_search(
+                profile=profile,
+                query=query,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            )
+
+        @mcp.tool()
+        def role_search(
+            profile: str = DEFAULT_PROFILE,
+            keyword: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+        ) -> JSONObject:
+            return self.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+        @mcp.tool()
+        def role_create(
+            profile: str = DEFAULT_PROFILE,
+            role_name: str = "",
+            member_uids: list[int] | None = None,
+            member_emails: list[str] | None = None,
+            member_names: list[str] | None = None,
+            role_icon: str = "ex-user-outlined",
+        ) -> JSONObject:
+            return self.role_create(
+                profile=profile,
+                role_name=role_name,
+                member_uids=member_uids or [],
+                member_emails=member_emails or [],
+                member_names=member_names or [],
+                role_icon=role_icon,
+            )
+
         @mcp.tool()
         def package_attach_app(
             profile: str = DEFAULT_PROFILE,
@@ -56,6 +125,20 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
 
+        @mcp.tool()
+        def app_release_edit_lock_if_mine(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            lock_owner_email: str = "",
+            lock_owner_name: str = "",
+        ) -> JSONObject:
+            return self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+
         @mcp.tool()
         def app_resolve(
             profile: str = DEFAULT_PROFILE,
@@ -165,6 +248,7 @@ class AiBuilderTools(ToolBase):
             app_name: str = "",
             app_title: str = "",
             create_if_missing: bool = False,
+            publish: bool = True,
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
@@ -176,6 +260,7 @@ class AiBuilderTools(ToolBase):
                 app_name=app_name,
                 app_title=app_title,
                 create_if_missing=create_if_missing,
+                publish=publish,
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
@@ -186,15 +271,17 @@ class AiBuilderTools(ToolBase):
             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, sections=sections or [])
+            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:
@@ -202,6 +289,7 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 app_key=app_key,
                 mode=mode,
+                publish=publish,
                 nodes=nodes or [],
                 transitions=transitions or [],
             )
@@ -210,12 +298,14 @@ class AiBuilderTools(ToolBase):
         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 [],
             )
@@ -233,31 +323,236 @@ class AiBuilderTools(ToolBase):
             )
 
     def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
-        return self._facade.package_list(profile=profile, trial_status=trial_status)
+        normalized_args = {"trial_status": trial_status}
+        return _safe_tool_call(
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            error_code="PACKAGE_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+        )
 
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
-        return self._facade.package_resolve(profile=profile, package_name=package_name)
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_resolve(profile=profile, package_name=package_name),
+            error_code="PACKAGE_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": package_name}},
+        )
+
+    def builder_tool_contract(self, *, tool_name: str) -> JSONObject:
+        requested = str(tool_name or "").strip()
+        contract = _BUILDER_TOOL_CONTRACTS.get(requested)
+        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": sorted(_BUILDER_TOOL_CONTRACTS.keys())},
+                "details": {"reason_path": "tool_name"},
+                "suggested_next_call": None,
+                "request_id": None,
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "verification": {},
+            }
+        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,
+            "verification": {},
+            "tool_name": requested,
+            "contract": contract,
+        }
+
+    def package_create(self, *, profile: str, package_name: str) -> JSONObject:
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_create(profile=profile, package_name=package_name),
+            error_code="PACKAGE_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_create", "arguments": {"profile": profile, "package_name": package_name}},
+        )
+
+    def member_search(
+        self,
+        *,
+        profile: str,
+        query: str,
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> JSONObject:
+        normalized_args = {
+            "query": query,
+            "page_num": page_num,
+            "page_size": page_size,
+            "contain_disable": contain_disable,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.member_search(
+                profile=profile,
+                query=query,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            ),
+            error_code="MEMBER_SEARCH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
+        normalized_args = {"keyword": keyword, "page_num": page_num, "page_size": page_size}
+        return _safe_tool_call(
+            lambda: self._facade.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size),
+            error_code="ROLE_SEARCH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def role_create(
+        self,
+        *,
+        profile: str,
+        role_name: str,
+        member_uids: list[int],
+        member_emails: list[str],
+        member_names: list[str],
+        role_icon: str = "ex-user-outlined",
+    ) -> JSONObject:
+        normalized_args = {
+            "role_name": role_name,
+            "member_uids": member_uids,
+            "member_emails": member_emails,
+            "member_names": member_names,
+            "role_icon": role_icon,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.role_create(
+                profile=profile,
+                role_name=role_name,
+                member_uids=member_uids,
+                member_emails=member_emails,
+                member_names=member_names,
+                role_icon=role_icon,
+            ),
+            error_code="ROLE_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "role_create", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
-        return self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
+        normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
+        result = _safe_tool_call(
+            lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
+            error_code="PACKAGE_ATTACH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.package_attach_app(
+                profile=profile,
+                tag_id=tag_id,
+                app_key=app_key,
+                app_title=app_title,
+            ),
+        )
+
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            ),
+            error_code="EDIT_LOCK_RELEASE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_resolve(self, *, profile: str, app_key: str = "", app_name: str = "", package_tag_id: int | None = None) -> JSONObject:
-        return self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
+        normalized_args = {"app_key": app_key, "app_name": app_name, "package_tag_id": package_tag_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id),
+            error_code="APP_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
+            error_code="APP_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_fields(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_fields(profile=profile, app_key=app_key),
+            error_code="FIELDS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_layout_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_layout_summary(profile=profile, app_key=app_key),
+            error_code="LAYOUT_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_views_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_views_summary(profile=profile, app_key=app_key),
+            error_code="VIEWS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_flow_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
+            error_code="FLOW_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_schema_plan(
         self,
@@ -286,6 +581,8 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_schema_plan",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_schema_plan",
                     "arguments": {
@@ -300,7 +597,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_schema_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_schema_plan(profile=profile, request=request),
+            error_code="SCHEMA_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_layout_plan(
         self,
@@ -323,18 +625,24 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_layout_plan",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_layout_plan",
                     "arguments": {
                         "profile": profile,
                         "app_key": app_key,
                         "mode": "merge",
-                        "preset": "balanced",
-                        "sections": [],
+                        "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
                     },
                 },
             )
-        return self._facade.app_layout_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_plan(profile=profile, request=request),
+            error_code="LAYOUT_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_flow_plan(
         self,
@@ -359,6 +667,8 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_flow_plan",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_flow_plan",
                     "arguments": {
@@ -371,7 +681,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_flow_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_plan(profile=profile, request=request),
+            error_code="FLOW_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_views_plan(
         self,
@@ -394,6 +709,8 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_views_plan",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_views_plan",
                     "arguments": {
@@ -405,7 +722,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_views_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_views_plan(profile=profile, request=request),
+            error_code="VIEWS_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_schema_apply(
         self,
@@ -416,6 +738,7 @@ class AiBuilderTools(ToolBase):
         app_name: str = "",
         app_title: str = "",
         create_if_missing: bool = False,
+        publish: bool = True,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
@@ -428,6 +751,8 @@ class AiBuilderTools(ToolBase):
         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": {
@@ -442,18 +767,45 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_schema_apply(
+        normalized_args = {
+            "app_key": app_key,
+            "package_tag_id": package_tag_id,
+            "app_name": effective_app_name,
+            "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=app_key,
+                package_tag_id=package_tag_id,
+                app_name=effective_app_name,
+                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 self._retry_after_self_lock_release(profile=profile, result=result, retry_call=lambda: self._facade.app_schema_apply(
             profile=profile,
             app_key=app_key,
             package_tag_id=package_tag_id,
             app_name=effective_app_name,
             create_if_missing=create_if_missing,
+            publish=publish,
             add_fields=parsed_add,
             update_fields=parsed_update,
             remove_fields=parsed_remove,
-        )
+        ))
 
-    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", sections: list[JSONObject]) -> JSONObject:
+    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         try:
             normalized_mode = str(mode or "merge").strip().lower()
             if normalized_mode in {"overwrite"}:
@@ -463,6 +815,7 @@ class AiBuilderTools(ToolBase):
         except ValueError:
             return _validation_failure(
                 "mode must be one of: merge, replace",
+                tool_name="app_layout_apply",
                 suggested_next_call={
                     "tool_name": "app_layout_apply",
                     "arguments": {
@@ -476,6 +829,8 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_layout_apply",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_layout_apply",
                     "arguments": {
@@ -486,7 +841,29 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_layout_apply(profile=profile, app_key=app_key, mode=parsed_mode, sections=parsed_sections)
+        normalized_args = {
+            "app_key": app_key,
+            "mode": parsed_mode.value,
+            "publish": publish,
+            "sections": [section.model_dump(mode="json") for section in parsed_sections],
+        }
+        result = _safe_tool_call(
+            lambda: self._facade.app_layout_apply(profile=profile, app_key=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}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_layout_apply(
+                profile=profile,
+                app_key=app_key,
+                mode=parsed_mode,
+                publish=publish,
+                sections=parsed_sections,
+            ),
+        )
 
     def app_flow_apply(
         self,
@@ -494,6 +871,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         mode: str = "replace",
+        publish: bool = True,
         nodes: list[JSONObject],
         transitions: list[JSONObject],
     ) -> JSONObject:
@@ -510,6 +888,8 @@ class AiBuilderTools(ToolBase):
         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": {
@@ -521,12 +901,37 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_flow_apply(
+        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],
+        }
+        result = _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}},
+        )
+        return self._retry_after_self_lock_release(
             profile=profile,
-            app_key=request.app_key,
-            mode=request.mode,
-            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],
+            result=result,
+            retry_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],
+            ),
         )
 
     def app_views_apply(
@@ -534,6 +939,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
+        publish: bool = True,
         upsert_views: list[JSONObject],
         remove_views: list[str],
     ) -> JSONObject:
@@ -542,6 +948,8 @@ class AiBuilderTools(ToolBase):
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
+                tool_name="app_views_apply",
+                exc=exc,
                 suggested_next_call={
                     "tool_name": "app_views_apply",
                     "arguments": {
@@ -552,13 +960,126 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_views_apply(profile=profile, app_key=app_key, upsert_views=parsed_views, remove_views=remove_views)
+        normalized_args = {
+            "app_key": app_key,
+            "publish": publish,
+            "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+            "remove_views": list(remove_views),
+        }
+        result = _safe_tool_call(
+            lambda: self._facade.app_views_apply(profile=profile, app_key=app_key, publish=publish, upsert_views=parsed_views, remove_views=remove_views),
+            error_code="VIEWS_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_views_apply(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                upsert_views=parsed_views,
+                remove_views=remove_views,
+            ),
+        )
 
     def app_publish_verify(self, *, profile: str, app_key: str, expected_package_tag_id: int | None = None) -> JSONObject:
-        return self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id)
+        normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
+        result = _safe_tool_call(
+            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id),
+            error_code="PUBLISH_VERIFY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
+        )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_tag_id=expected_package_tag_id,
+            ),
+        )
+
+    def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
+        if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
+            return result
+        suggested = result.get("suggested_next_call")
+        if not isinstance(suggested, dict) or suggested.get("tool_name") != "app_release_edit_lock_if_mine":
+            return result
+        arguments = suggested.get("arguments")
+        if not isinstance(arguments, dict):
+            return result
+        app_key = str(arguments.get("app_key") or "")
+        lock_owner_email = str(arguments.get("lock_owner_email") or "")
+        lock_owner_name = str(arguments.get("lock_owner_name") or "")
+        release_attempts: list[JSONObject] = []
+        retried: JSONObject = result
+        for _ in range(3):
+            release_result = self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+            release_attempts.append(release_result)
+            if not isinstance(release_result, dict) or release_result.get("status") != "success":
+                result.setdefault("details", {})
+                if isinstance(result["details"], dict):
+                    result["details"]["edit_lock_release_result"] = release_result
+                    result["details"]["edit_lock_release_attempts"] = release_attempts
+                return result
+            retried = retry_call()
+            if not (
+                isinstance(retried, dict)
+                and retried.get("status") == "failed"
+                and retried.get("error_code") == "APP_EDIT_LOCKED"
+            ):
+                break
+            time.sleep(0.2)
+        if (
+            isinstance(retried, dict)
+            and retried.get("status") == "failed"
+            and retried.get("error_code") == "APP_EDIT_LOCKED"
+        ):
+            retried = {
+                **retried,
+                "error_code": "PERSISTENT_SELF_LOCK",
+                "message": "app remains locked by the current user's active editor session after repeated forced release attempts",
+                "recoverable": True,
+                "suggested_next_call": None,
+            }
+        if isinstance(retried, dict):
+            retried.setdefault("details", {})
+            if isinstance(retried["details"], dict):
+                retried["details"]["edit_lock_release_result"] = release_attempts[-1] if release_attempts else None
+                retried["details"]["edit_lock_release_attempts"] = release_attempts
+            retried["edit_lock_released"] = bool(release_attempts)
+            retried["retried_after_edit_lock_release"] = True
+        return retried
 
 
-def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None = None) -> JSONObject:
+def _validation_failure(
+    detail: str,
+    *,
+    tool_name: str | None = None,
+    exc: ValidationError | None = None,
+    suggested_next_call: JSONObject | None = None,
+) -> JSONObject:
+    contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    reason_path = None
+    if exc is not None:
+        errors = exc.errors()
+        if errors:
+            loc = errors[0].get("loc")
+            if isinstance(loc, (tuple, list)):
+                reason_path = ".".join(str(part) for part in loc)
+    canonical_arguments = None
+    if isinstance(suggested_next_call, dict):
+        arguments = suggested_next_call.get("arguments")
+        if isinstance(arguments, dict):
+            canonical_arguments = arguments
     return {
         "status": "failed",
         "error_code": "VALIDATION_ERROR",
@@ -566,8 +1087,16 @@ def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None =
         "message": detail,
         "normalized_args": {},
         "missing_fields": [],
-        "allowed_values": {},
-        "details": {"validation_detail": detail},
+        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
+        "details": {
+            "validation_detail": detail,
+            "reason_path": reason_path,
+            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+            "canonical_arguments": canonical_arguments,
+            "section_allowed_keys": deepcopy(contract.get("section_allowed_keys", [])) if isinstance(contract, dict) else [],
+            "section_aliases": deepcopy(contract.get("section_aliases", {})) if isinstance(contract, dict) else {},
+            "minimal_section_example": deepcopy(contract.get("minimal_section_example")) if isinstance(contract, dict) else None,
+        },
         "suggested_next_call": suggested_next_call,
         "request_id": None,
         "backend_code": None,
@@ -575,3 +1104,482 @@ def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None =
         "noop": False,
         "verification": {},
     }
+
+
+def _safe_tool_call(
+    call,
+    *,
+    error_code: str,
+    normalized_args: JSONObject,
+    suggested_next_call: JSONObject | None,
+) -> JSONObject:
+    try:
+        return call()
+    except (QingflowApiError, RuntimeError) as error:
+        api_error = _coerce_api_error(error)
+        public_http_status = None if api_error.http_status == 404 else api_error.http_status
+        return {
+            "status": "failed",
+            "error_code": error_code,
+            "recoverable": True,
+            "message": _public_error_message(error_code, api_error),
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "transport_error": {
+                    "http_status": api_error.http_status,
+                    "backend_code": api_error.backend_code,
+                    "category": api_error.category,
+                }
+            },
+            "suggested_next_call": suggested_next_call,
+            "request_id": api_error.request_id,
+            "backend_code": api_error.backend_code,
+            "http_status": public_http_status,
+            "noop": False,
+            "verification": {},
+        }
+
+
+def _coerce_api_error(error: Exception) -> QingflowApiError:
+    if isinstance(error, QingflowApiError):
+        return error
+    if isinstance(error, RuntimeError):
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("category") and payload.get("message"):
+            details = payload.get("details")
+            return QingflowApiError(
+                category=str(payload.get("category")),
+                message=str(payload.get("message")),
+                backend_code=payload.get("backend_code"),
+                request_id=payload.get("request_id"),
+                http_status=payload.get("http_status"),
+                details=details if isinstance(details, dict) else None,
+            )
+    return QingflowApiError(category="runtime", message=str(error))
+
+
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+        return "app is currently locked by another active editor session"
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
+        "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
+        "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
+        "APP_RESOLVE_FAILED": "app resolution is unavailable in the current route",
+        "APP_READ_FAILED": "app base or schema is unavailable in the current route",
+        "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
+        "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_PLAN_FAILED": "schema planning could not load the required app state in the current route",
+        "LAYOUT_PLAN_FAILED": "layout planning could not load the required app state in the current route",
+        "FLOW_PLAN_FAILED": "flow planning could not load the required app state in the current route",
+        "VIEWS_PLAN_FAILED": "views planning could not load the required app state in the current route",
+        "SCHEMA_APPLY_FAILED": "schema apply could not complete because the app route or readback is unavailable",
+        "LAYOUT_APPLY_FAILED": "layout apply could not complete because the layout route or readback is unavailable",
+        "FLOW_APPLY_FAILED": "flow apply could not complete because the workflow route or readback is unavailable",
+        "VIEWS_APPLY_FAILED": "views apply could not complete because the views route or readback is unavailable",
+        "PUBLISH_VERIFY_FAILED": "publish verification is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")
+
+
+_BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
+    "member_search": {
+        "allowed_keys": ["query", "page_num", "page_size", "contain_disable"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "query": "严琪东",
+            "page_num": 1,
+            "page_size": 20,
+            "contain_disable": False,
+        },
+    },
+    "role_search": {
+        "allowed_keys": ["keyword", "page_num", "page_size"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "keyword": "项目经理",
+            "page_num": 1,
+            "page_size": 20,
+        },
+    },
+    "role_create": {
+        "allowed_keys": ["role_name", "member_uids", "member_emails", "member_names", "role_icon"],
+        "aliases": {},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "role_name": "研发负责人",
+            "member_names": ["严琪东"],
+            "member_uids": [],
+            "member_emails": [],
+            "role_icon": "ex-user-outlined",
+        },
+    },
+    "app_schema_plan": {
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "field.title": "field.name",
+            "field.label": "field.name",
+            "field.fields": "field.subfields",
+            "field.type_id": "field.type",
+        },
+        "allowed_values": {
+            "field.type": [member.value for member in PublicFieldType],
+            "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+            "create_if_missing": True,
+            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+    },
+    "app_schema_apply": {
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "aliases": {
+            "app_title": "app_name",
+            "title": "app_name",
+            "field.title": "field.name",
+            "field.label": "field.name",
+            "field.fields": "field.subfields",
+            "field.type_id": "field.type",
+        },
+        "allowed_values": {
+            "field.type": [member.value for member in PublicFieldType],
+            "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+            "create_if_missing": True,
+            "publish": True,
+            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "update_fields": [],
+            "remove_fields": [],
+        },
+    },
+    "app_layout_plan": {
+        "allowed_keys": ["app_key", "mode", "sections", "preset"],
+        "aliases": {"overwrite": "replace", "sectionId": "section_id"},
+        "section_allowed_keys": ["section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "sectionId": "section_id",
+            "fields": "rows",
+            "field_ids": "rows",
+            "columns": "rows_chunk_size",
+        },
+        "allowed_values": {"mode": [member.value for member in LayoutApplyMode], "preset": [member.value for member in LayoutPreset]},
+        "minimal_section_example": {"title": "基础信息", "rows": [["字段A", "字段B"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+        },
+        "preset_example": {"profile": "default", "app_key": "APP_KEY", "mode": "merge", "preset": "balanced", "sections": []},
+    },
+    "app_layout_apply": {
+        "allowed_keys": ["app_key", "mode", "publish", "sections"],
+        "aliases": {"overwrite": "replace", "sectionId": "section_id"},
+        "section_allowed_keys": ["section_id", "title", "rows"],
+        "section_aliases": {
+            "name": "title",
+            "sectionId": "section_id",
+            "fields": "rows",
+            "field_ids": "rows",
+            "columns": "rows_chunk_size",
+        },
+        "allowed_values": {"mode": [member.value for member in LayoutApplyMode]},
+        "minimal_section_example": {"title": "基础信息", "rows": [["字段A", "字段B"]]},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "merge",
+            "publish": True,
+            "sections": [{"title": "基础信息", "rows": [["项目名称", "项目负责人"]]}],
+        },
+    },
+    "app_flow_plan": {
+        "allowed_keys": ["app_key", "mode", "nodes", "transitions", "preset"],
+        "aliases": {
+            "overwrite": "replace",
+            "base_preset": "preset",
+            "default_approval": "basic_approval",
+            "node.role_names": "node.assignees.role_names",
+            "node.role_ids": "node.assignees.role_ids",
+            "node.member_names": "node.assignees.member_names",
+            "node.member_emails": "node.assignees.member_emails",
+            "node.member_uids": "node.assignees.member_uids",
+            "node.editable_fields": "node.permissions.editable_fields",
+            "node.filters": "node.conditions",
+            "node.rules": "node.conditions",
+            "node.conditionRules": "node.condition_groups",
+            "node.condition.field": "node.conditions[].field_name",
+            "node.condition.name": "node.conditions[].field_name",
+            "node.condition.op": "node.conditions[].operator",
+            "default_approval": "basic_approval",
+        },
+        "allowed_values": {
+            "mode": ["replace"],
+            "preset": [member.value for member in FlowPreset],
+            "node.type": [member.value for member in PublicFlowNodeType],
+            "node.condition.operator": [member.value for member in FlowConditionOperator],
+        },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
+        "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": [],
+        },
+        "branch_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "replace",
+            "nodes": [
+                {"id": "start", "type": "start", "name": "发起"},
+                {"id": "route", "type": "branch", "name": "金额分支"},
+                {
+                    "id": "high_amount",
+                    "type": "condition",
+                    "name": "金额大于等于一万",
+                    "conditions": [{"field_name": "预计金额", "operator": "gte", "value": 10000}],
+                },
+                {
+                    "id": "approve_finance",
+                    "type": "approve",
+                    "name": "财务审批",
+                    "assignees": {"role_names": ["财务负责人"]},
+                },
+                {"id": "default_lane", "type": "condition", "name": "其他情况"},
+                {
+                    "id": "approve_manager",
+                    "type": "approve",
+                    "name": "部门审批",
+                    "assignees": {"role_names": ["项目经理"]},
+                },
+                {"id": "end", "type": "end", "name": "结束"},
+            ],
+            "transitions": [
+                {"from": "start", "to": "route"},
+                {"from": "route", "to": "high_amount"},
+                {"from": "high_amount", "to": "approve_finance"},
+                {"from": "route", "to": "default_lane"},
+                {"from": "default_lane", "to": "approve_manager"},
+                {"from": "approve_finance", "to": "end"},
+                {"from": "approve_manager", "to": "end"},
+            ],
+        },
+    },
+    "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",
+            "node.filters": "node.conditions",
+            "node.rules": "node.conditions",
+            "node.conditionRules": "node.condition_groups",
+            "node.condition.field": "node.conditions[].field_name",
+            "node.condition.name": "node.conditions[].field_name",
+            "node.condition.op": "node.conditions[].operator",
+        },
+        "allowed_values": {
+            "mode": ["replace"],
+            "node.type": [member.value for member in PublicFlowNodeType],
+            "node.condition.operator": [member.value for member in FlowConditionOperator],
+        },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
+        "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"}],
+        },
+        "branch_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "mode": "replace",
+            "publish": True,
+            "nodes": [
+                {"id": "start", "type": "start", "name": "发起"},
+                {"id": "route", "type": "branch", "name": "金额分支"},
+                {
+                    "id": "high_amount",
+                    "type": "condition",
+                    "name": "金额大于等于一万",
+                    "conditions": [{"field_name": "预计金额", "operator": "gte", "value": 10000}],
+                },
+                {
+                    "id": "approve_finance",
+                    "type": "approve",
+                    "name": "财务审批",
+                    "assignees": {"role_names": ["财务负责人"]},
+                },
+                {"id": "default_lane", "type": "condition", "name": "其他情况"},
+                {
+                    "id": "approve_manager",
+                    "type": "approve",
+                    "name": "部门审批",
+                    "assignees": {"role_names": ["项目经理"]},
+                },
+                {"id": "end", "type": "end", "name": "结束"},
+            ],
+            "transitions": [
+                {"from": "start", "to": "route"},
+                {"from": "route", "to": "high_amount"},
+                {"from": "high_amount", "to": "approve_finance"},
+                {"from": "route", "to": "default_lane"},
+                {"from": "default_lane", "to": "approve_manager"},
+                {"from": "approve_finance", "to": "end"},
+                {"from": "approve_manager", "to": "end"},
+            ],
+        },
+    },
+    "app_views_plan": {
+        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key"],
+        "aliases": {
+            "fields": "columns",
+            "column_names": "columns",
+            "columnNames": "columns",
+            "viewKey": "view_key",
+            "tableView": "table",
+            "cardView": "card",
+            "kanban": "board",
+            "filter_rules": "filters",
+            "filterRules": "filters",
+            "startField": "start_field",
+            "endField": "end_field",
+            "titleField": "title_field",
+        },
+        "allowed_values": {
+            "preset": [member.value for member in ViewsPreset],
+            "view.type": [member.value for member in PublicViewType],
+            "view.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "remove_views": [],
+        },
+        "gantt_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "项目甘特图",
+                    "type": "gantt",
+                    "columns": ["项目名称", "开始日期", "结束日期"],
+                    "start_field": "开始日期",
+                    "end_field": "结束日期",
+                    "title_field": "项目名称",
+                    "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
+                }
+            ],
+            "remove_views": [],
+        },
+    },
+    "app_views_apply": {
+        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key"],
+        "aliases": {
+            "fields": "columns",
+            "column_names": "columns",
+            "columnNames": "columns",
+            "viewKey": "view_key",
+            "tableView": "table",
+            "cardView": "card",
+            "kanban": "board",
+            "filter_rules": "filters",
+            "filterRules": "filters",
+            "startField": "start_field",
+            "endField": "end_field",
+            "titleField": "title_field",
+        },
+        "allowed_values": {
+            "view.type": [member.value for member in PublicViewType],
+            "view.filter.operator": [member.value for member in ViewFilterOperator],
+        },
+        "execution_notes": [
+            "apply may return partial_success when some views land and others fail",
+            "when duplicate view names exist, supply view_key to target the exact view",
+            "read back app_read_views_summary after any failed or partial view apply",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "remove_views": [],
+        },
+        "gantt_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "项目甘特图",
+                    "type": "gantt",
+                    "columns": ["项目名称", "开始日期", "结束日期"],
+                    "start_field": "开始日期",
+                    "end_field": "结束日期",
+                    "title_field": "项目名称",
+                    "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
+                }
+            ],
+            "remove_views": [],
+        },
+    },
+}