@josephyan/qingflow-cli 0.2.0-beta.62 → 0.2.0-beta.64

package/src/qingflow_mcp/cli/commands/builder.py

@@ -7,7 +7,7 @@ from .common import load_list_arg, load_object_arg, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    parser = subparsers.add_parser("builder", help="稳定 builder 命令")
+    parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
     builder_subparsers = parser.add_subparsers(dest="builder_command", required=True)
 
     package = builder_subparsers.add_parser("package", help="应用包")
@@ -25,6 +25,34 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_resolve.add_argument("--package-tag-id", type=int)
     app_resolve.set_defaults(handler=_handle_app_resolve, format_hint="builder_summary")
 
+    button = builder_subparsers.add_parser("button", help="自定义按钮")
+    button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
+
+    button_list = button_subparsers.add_parser("list", help="列出自定义按钮")
+    button_list.add_argument("--app-key", required=True)
+    button_list.set_defaults(handler=_handle_button_list, format_hint="builder_summary")
+
+    button_get = button_subparsers.add_parser("get", help="读取自定义按钮")
+    button_get.add_argument("--app-key", required=True)
+    button_get.add_argument("--button-id", type=int, required=True)
+    button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
+
+    button_create = button_subparsers.add_parser("create", help="创建自定义按钮")
+    button_create.add_argument("--app-key", required=True)
+    button_create.add_argument("--payload-file", required=True)
+    button_create.set_defaults(handler=_handle_button_create, format_hint="builder_summary")
+
+    button_update = button_subparsers.add_parser("update", help="更新自定义按钮")
+    button_update.add_argument("--app-key", required=True)
+    button_update.add_argument("--button-id", type=int, required=True)
+    button_update.add_argument("--payload-file", required=True)
+    button_update.set_defaults(handler=_handle_button_update, format_hint="builder_summary")
+
+    button_delete = button_subparsers.add_parser("delete", help="删除自定义按钮")
+    button_delete.add_argument("--app-key", required=True)
+    button_delete.add_argument("--button-id", type=int, required=True)
+    button_delete.set_defaults(handler=_handle_button_delete, format_hint="builder_summary")
+
     for name, help_text, handler in [
         ("read-summary", "读取应用摘要", _handle_app_read_summary),
         ("read-fields", "读取字段摘要", _handle_app_read_fields),
@@ -102,6 +130,35 @@ def _handle_app_resolve(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_button_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_list(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_get(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
+
+
+def _handle_button_create(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_create(
+        profile=args.profile,
+        app_key=args.app_key,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file"),
+    )
+
+
+def _handle_button_update(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_update(
+        profile=args.profile,
+        app_key=args.app_key,
+        button_id=args.button_id,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file"),
+    )
+
+
+def _handle_button_delete(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_delete(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
+
+
 def _handle_app_read_summary(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_read_summary(profile=args.profile, app_key=args.app_key)
 

package/src/qingflow_mcp/server_app_builder.py

@@ -216,6 +216,31 @@ def build_builder_server() -> FastMCP:
     ) -> dict:
         return ai_builder.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
 
+    @server.tool()
+    def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
+
+    @server.tool()
+    def app_custom_button_create(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: dict | None = None) -> dict:
+        return ai_builder.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_update(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        button_id: int = 0,
+        payload: dict | None = None,
+    ) -> dict:
+        return ai_builder.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+
     @server.tool()
     def app_read_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
         return ai_builder.app_read_summary(profile=profile, app_key=app_key)

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -11,6 +11,7 @@ from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     ChartApplyRequest,
+    CustomButtonPatch,
     FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
@@ -24,6 +25,7 @@ from ..builder_facade.models import (
     LayoutPreset,
     LayoutSectionPatch,
     PortalApplyRequest,
+    PublicButtonTriggerAction,
     PublicFieldType,
     PublicRelationMode,
     PublicChartType,
@@ -37,6 +39,7 @@ from ..builder_facade.models import (
 from ..builder_facade.service import AiBuilderFacade
 from .app_tools import AppTools
 from .base import ToolBase
+from .custom_button_tools import CustomButtonTools
 from .directory_tools import DirectoryTools
 from .package_tools import PackageTools
 from .portal_tools import PortalTools
@@ -54,6 +57,7 @@ class AiBuilderTools(ToolBase):
         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),
@@ -156,6 +160,35 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
 
+        @mcp.tool()
+        def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_custom_button_list(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
+            return self.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
+
+        @mcp.tool()
+        def app_custom_button_create(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            payload: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+
+        @mcp.tool()
+        def app_custom_button_update(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            button_id: int = 0,
+            payload: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+
+        @mcp.tool()
+        def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
+            return self.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+
         @mcp.tool()
         def app_read_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_read_summary(profile=profile, app_key=app_key)
@@ -518,6 +551,98 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_list(profile=profile, app_key=app_key),
+            error_code="CUSTOM_BUTTON_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_get(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id),
+            error_code="CUSTOM_BUTTON_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        try:
+            request = CustomButtonPatch.model_validate(payload)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_custom_button_create",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_button_create",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "payload": {
+                            "button_text": "新增记录",
+                            "background_color": "#FFFFFF",
+                            "text_color": "#494F57",
+                            "button_icon": "ex-add-outlined",
+                            "trigger_action": "addData",
+                            "trigger_add_data_config": {"related_app_key": "TARGET_APP_KEY", "que_relation": []},
+                        },
+                    },
+                },
+            )
+        normalized_args = {"app_key": app_key, "payload": request.model_dump(mode="json")}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_create(profile=profile, app_key=app_key, payload=request),
+            error_code="CUSTOM_BUTTON_CREATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_create", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        try:
+            request = CustomButtonPatch.model_validate(payload)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_custom_button_update",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_button_update",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "button_id": button_id,
+                        "payload": {
+                            "button_text": "新增记录",
+                            "background_color": "#FFFFFF",
+                            "text_color": "#494F57",
+                            "button_icon": "ex-add-outlined",
+                            "trigger_action": "link",
+                            "trigger_link_url": "https://example.com",
+                        },
+                    },
+                },
+            )
+        normalized_args = {"app_key": app_key, "button_id": button_id, "payload": request.model_dump(mode="json")}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=request),
+            error_code="CUSTOM_BUTTON_UPDATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_update", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def app_custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id),
+            error_code="CUSTOM_BUTTON_DELETE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_button_delete", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
@@ -1531,6 +1656,11 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
         "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
         "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
         "APP_RESOLVE_FAILED": "app resolution is unavailable in the current route",
+        "CUSTOM_BUTTON_LIST_FAILED": "custom button list is unavailable in the current route",
+        "CUSTOM_BUTTON_GET_FAILED": "custom button detail is unavailable in the current route",
+        "CUSTOM_BUTTON_CREATE_FAILED": "custom button create could not complete because the route or readback is unavailable",
+        "CUSTOM_BUTTON_UPDATE_FAILED": "custom button update could not complete because the route or readback is unavailable",
+        "CUSTOM_BUTTON_DELETE_FAILED": "custom button delete could not complete because the route is unavailable",
         "APP_READ_FAILED": "app base or schema is unavailable in the current route",
         "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
         "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
@@ -1588,6 +1718,97 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "role_icon": "ex-user-outlined",
         },
     },
+    "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.triggerAction": "payload.trigger_action",
+            "payload.triggerLinkUrl": "payload.trigger_link_url",
+            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
+            "payload.externalQrobotConfig": "payload.external_qrobot_config",
+            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
+            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+        },
+        "allowed_values": {
+            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "payload": {
+                "button_text": "新增记录",
+                "background_color": "#FFFFFF",
+                "text_color": "#494F57",
+                "button_icon": "ex-add-outlined",
+                "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.triggerAction": "payload.trigger_action",
+            "payload.triggerLinkUrl": "payload.trigger_link_url",
+            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
+            "payload.externalQrobotConfig": "payload.external_qrobot_config",
+            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
+            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+        },
+        "allowed_values": {
+            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+        },
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "button_id": 1001,
+            "payload": {
+                "button_text": "查看详情",
+                "background_color": "#FFFFFF",
+                "text_color": "#494F57",
+                "button_icon": "ex-link-outlined",
+                "trigger_action": "link",
+                "trigger_link_url": "https://example.com/detail",
+            },
+        },
+    },
+    "app_custom_button_delete": {
+        "allowed_keys": ["app_key", "button_id"],
+        "aliases": {"buttonId": "button_id"},
+        "allowed_values": {},
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "button_id": 1001,
+        },
+    },
     "app_schema_plan": {
         "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
@@ -1825,7 +2046,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key"],
+        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -1839,11 +2060,21 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
+            "buttons[].buttonType": "buttons[].button_type",
+            "buttons[].configType": "buttons[].config_type",
+            "buttons[].buttonId": "buttons[].button_id",
+            "buttons[].beingMain": "buttons[].being_main",
+            "buttons[].buttonLimit": "buttons[].button_limit",
+            "buttons[].buttonFormula": "buttons[].button_formula",
+            "buttons[].buttonFormulaType": "buttons[].button_formula_type",
+            "buttons[].printTpls": "buttons[].print_tpls",
         },
         "allowed_values": {
             "preset": [member.value for member in ViewsPreset],
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
+            "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
+            "view.buttons.config_type": ["TOP", "DETAIL"],
         },
         "minimal_example": {
             "profile": "default",
@@ -1869,7 +2100,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key"],
+        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -1883,16 +2114,27 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
+            "buttons[].buttonType": "buttons[].button_type",
+            "buttons[].configType": "buttons[].config_type",
+            "buttons[].buttonId": "buttons[].button_id",
+            "buttons[].beingMain": "buttons[].being_main",
+            "buttons[].buttonLimit": "buttons[].button_limit",
+            "buttons[].buttonFormula": "buttons[].button_formula",
+            "buttons[].buttonFormulaType": "buttons[].button_formula_type",
+            "buttons[].printTpls": "buttons[].print_tpls",
         },
         "allowed_values": {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
+            "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
+            "view.buttons.config_type": ["TOP", "DETAIL"],
         },
         "execution_notes": [
             "apply may return partial_success when some views land and others fail",
             "when duplicate view names exist, supply view_key to target the exact view",
             "read back app_read_views_summary after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
+            "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
         ],
         "minimal_example": {
             "profile": "default",

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import ToolBase
+
+
+class CustomButtonTools(ToolBase):
+    def custom_button_list(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        being_draft: bool = True,
+        include_raw: bool = False,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/customButton",
+                params={"beingDraft": being_draft},
+            )
+            items = []
+            raw_items = result.get("result") if isinstance(result, dict) and isinstance(result.get("result"), list) else []
+            for item in raw_items:
+                if not isinstance(item, dict):
+                    continue
+                items.append(self._compact_button_base_info(item))
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "being_draft": being_draft,
+                "items": result if include_raw else items,
+                "count": len(items),
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = items
+            return response
+
+        return self._run(profile, runner)
+
+    def custom_button_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        button_id: int,
+        being_draft: bool = True,
+        include_raw: bool = False,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+
+        def runner(session_profile, context):
+            params = {"beingDraft": being_draft}
+            result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "button_id": button_id,
+                "being_draft": being_draft,
+                "result": result if include_raw else self._compact_button_detail(result if isinstance(result, dict) else {}),
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = self._compact_button_detail(result if isinstance(result, dict) else {})
+            return response
+
+        return self._run(profile, runner)
+
+    def custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        self._require_app_key(app_key)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, f"/app/{app_key}/customButton", json_body=deepcopy(body))
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "app_key": app_key, "result": result}
+
+        return self._run(profile, runner)
+
+    def custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                f"/app/{app_key}/customButton/{button_id}",
+                json_body=deepcopy(body),
+            )
+            return self._attach_human_review_notice(
+                {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "result": result,
+                },
+                operation="update",
+                target="custom button configuration",
+            )
+
+        return self._run(profile, runner)
+
+    def custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("DELETE", context, f"/app/{app_key}/customButton/{button_id}")
+            return self._attach_human_review_notice(
+                {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "result": result,
+                },
+                operation="delete",
+                target="custom button configuration",
+            )
+
+        return self._run(profile, runner)
+
+    def _require_app_key(self, app_key: str) -> None:
+        if not str(app_key or "").strip():
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
+    def _require_button_id(self, button_id: int) -> None:
+        if not isinstance(button_id, int) or isinstance(button_id, bool) or button_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("button_id must be a positive integer"))
+
+    def _compact_button_base_info(self, item: dict[str, object]) -> JSONObject:
+        creator = item.get("creatorUserInfo") if isinstance(item.get("creatorUserInfo"), dict) else {}
+        return {
+            "button_id": item.get("buttonId"),
+            "button_text": item.get("buttonText"),
+            "button_icon": item.get("buttonIcon"),
+            "background_color": item.get("backgroundColor"),
+            "text_color": item.get("textColor"),
+            "creator_user_info": {
+                "uid": creator.get("uid"),
+                "name": creator.get("name"),
+                "email": creator.get("email"),
+            }
+            if creator
+            else None,
+            "used_in_chart_count": item.get("userInChartCount"),
+            "being_effective_external_qrobot": item.get("beingEffectiveExternalQRobot"),
+        }
+
+    def _compact_button_detail(self, item: dict[str, object]) -> JSONObject:
+        return {
+            "button_id": item.get("buttonId"),
+            "button_text": item.get("buttonText"),
+            "button_icon": item.get("buttonIcon"),
+            "background_color": item.get("backgroundColor"),
+            "text_color": item.get("textColor"),
+            "trigger_action": item.get("triggerAction"),
+            "trigger_link_url": item.get("triggerLinkUrl"),
+            "trigger_add_data_config": deepcopy(item.get("triggerAddDataConfig")) if isinstance(item.get("triggerAddDataConfig"), dict) else None,
+            "external_qrobot_config": deepcopy(item.get("customButtonExternalQRobotRelationVO"))
+            if isinstance(item.get("customButtonExternalQRobotRelationVO"), dict)
+            else None,
+            "trigger_wings_config": deepcopy(item.get("triggerWingsConfig")) if isinstance(item.get("triggerWingsConfig"), dict) else None,
+        }