@josephyan/qingflow-app-builder-mcp 1.1.16 → 1.1.17

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.16
+npm install @josephyan/qingflow-app-builder-mcp@1.1.17
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.16 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.17 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "1.1.16",
+  "version": "1.1.17",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.16"
+version = "1.1.17"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/builder_facade/models.py

@@ -1105,6 +1105,91 @@ class ViewAssociatedResourcesPatch(StrictModel):
     )
 
 
+class ViewActionButtonPatch(StrictModel):
+    button_id: int | None = Field(default=None, validation_alias=AliasChoices("button_id", "buttonId", "id"))
+    client_key: str | None = Field(default=None, validation_alias=AliasChoices("client_key", "clientKey"))
+    text: str = Field(validation_alias=AliasChoices("text", "button_text", "buttonText", "name"))
+    action: PublicButtonTriggerAction = Field(validation_alias=AliasChoices("action", "trigger_action", "triggerAction"))
+    url: str | None = Field(default=None, validation_alias=AliasChoices("url", "link_url", "linkUrl", "trigger_link_url", "triggerLinkUrl"))
+    target_app_key: str | None = Field(default=None, validation_alias=AliasChoices("target_app_key", "targetAppKey", "related_app_key", "relatedAppKey"))
+    target_app_name: str | None = Field(default=None, validation_alias=AliasChoices("target_app_name", "targetAppName", "related_app_name", "relatedAppName"))
+    field_mappings: list[dict[str, Any]] = Field(default_factory=list, validation_alias=AliasChoices("field_mappings", "fieldMappings", "mappings"))
+    default_values: dict[str, Any] = Field(default_factory=dict, validation_alias=AliasChoices("default_values", "defaultValues", "defaults"))
+    placement: PublicButtonPlacement = Field(default=PublicButtonPlacement.detail, validation_alias=AliasChoices("placement", "position"))
+    primary: bool = Field(default=False, validation_alias=AliasChoices("primary", "being_main", "beingMain"))
+    visible_when: list[list[ViewFilterRulePatch]] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("visible_when", "visibleWhen", "button_limit", "buttonLimit"),
+    )
+    button_formula: str | None = Field(default=None, validation_alias=AliasChoices("button_formula", "buttonFormula"))
+    button_formula_type: int = Field(default=1, validation_alias=AliasChoices("button_formula_type", "buttonFormulaType"))
+    print_tpls: list[Any] = Field(default_factory=list, validation_alias=AliasChoices("print_tpls", "printTpls"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
+    background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
+    text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
+    button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
+    external_qrobot_config: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "external_qrobot_config",
+            "externalQrobotConfig",
+            "externalQRobotConfig",
+            "custom_button_external_qrobot_relation_vo",
+            "customButtonExternalQRobotRelationVO",
+        ),
+    )
+    trigger_wings_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("trigger_wings_config", "triggerWingsConfig"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        raw_action = payload.get("action", payload.get("trigger_action", payload.get("triggerAction")))
+        if isinstance(raw_action, str):
+            normalized = raw_action.strip()
+            aliases = {
+                "add_data": PublicButtonTriggerAction.add_data.value,
+                "add-data": PublicButtonTriggerAction.add_data.value,
+                "adddata": PublicButtonTriggerAction.add_data.value,
+                "addData": PublicButtonTriggerAction.add_data.value,
+                "link": PublicButtonTriggerAction.link.value,
+                "url": PublicButtonTriggerAction.link.value,
+                "qrobot": PublicButtonTriggerAction.qrobot.value,
+                "qRobot": PublicButtonTriggerAction.qrobot.value,
+                "wings": PublicButtonTriggerAction.wings.value,
+            }
+            payload["action"] = aliases.get(normalized, aliases.get(normalized.lower(), normalized))
+        raw_placement = payload.get("placement", payload.get("position", payload.get("config_type", payload.get("configType"))))
+        if isinstance(raw_placement, str):
+            normalized = raw_placement.strip().lower()
+            if normalized in {"top", "header"}:
+                payload["placement"] = PublicButtonPlacement.header.value
+            elif normalized in {"detail", "data_detail"}:
+                payload["placement"] = PublicButtonPlacement.detail.value
+            elif normalized in {"list", "row", "row_action", "inside"}:
+                payload["placement"] = PublicButtonPlacement.list.value
+        raw_limits = payload.get("visible_when", payload.get("visibleWhen", payload.get("button_limit", payload.get("buttonLimit"))))
+        if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
+            payload["visible_when"] = [raw_limits]
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewActionButtonPatch":
+        if not str(self.text or "").strip():
+            raise ValueError("action_buttons[].text is required")
+        if self.action == PublicButtonTriggerAction.link and not str(self.url or "").strip():
+            raise ValueError("link action_buttons require url")
+        if self.action == PublicButtonTriggerAction.add_data and not str(self.target_app_key or "").strip():
+            raise ValueError("add_data action_buttons require target_app_key")
+        if self.action == PublicButtonTriggerAction.qrobot and self.external_qrobot_config is None:
+            raise ValueError("qRobot action_buttons require external_qrobot_config")
+        if self.action == PublicButtonTriggerAction.wings and self.trigger_wings_config is None:
+            raise ValueError("wings action_buttons require trigger_wings_config")
+        return self
+
+
 class ViewUpsertPatch(StrictModel):
     name: str
     view_key: str | None = Field(default=None, validation_alias=AliasChoices("view_key", "viewKey"))
@@ -1116,6 +1201,8 @@ class ViewUpsertPatch(StrictModel):
     end_field: str | None = Field(default=None, validation_alias=AliasChoices("end_field", "endField"))
     title_field: str | None = Field(default=None, validation_alias=AliasChoices("title_field", "titleField"))
     buttons: list["ViewButtonBindingPatch"] | None = None
+    action_buttons: list[ViewActionButtonPatch] | None = Field(default=None, validation_alias=AliasChoices("action_buttons", "actionButtons"))
+    action_buttons_mode: str = Field(default="merge", validation_alias=AliasChoices("action_buttons_mode", "actionButtonsMode", "button_mode", "buttonMode"))
     visibility: VisibilityPatch | None = None
     query_conditions: ViewQueryConditionsPatch | None = Field(default=None, validation_alias=AliasChoices("query_conditions", "queryConditions", "query_condition", "queryCondition"))
     associated_resources: ViewAssociatedResourcesPatch | None = Field(
@@ -1165,6 +1252,12 @@ class ViewUpsertPatch(StrictModel):
             payload["associated_resources"] = payload.pop("associatedReports")
         if "asosChartConfig" in payload and "associated_resources" not in payload:
             payload["associated_resources"] = payload.pop("asosChartConfig")
+        if "actionButtons" in payload and "action_buttons" not in payload:
+            payload["action_buttons"] = payload.pop("actionButtons")
+        if "actionButtonsMode" in payload and "action_buttons_mode" not in payload:
+            payload["action_buttons_mode"] = payload.pop("actionButtonsMode")
+        if "buttonMode" in payload and "action_buttons_mode" not in payload:
+            payload["action_buttons_mode"] = payload.pop("buttonMode")
         raw_type = payload.get("type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -1186,6 +1279,10 @@ class ViewUpsertPatch(StrictModel):
             raise ValueError("board view requires group_by")
         if self.type == PublicViewType.gantt and not (self.start_field and self.end_field):
             raise ValueError("gantt view requires start_field and end_field")
+        normalized_mode = str(self.action_buttons_mode or "merge").strip().lower()
+        if normalized_mode not in {"merge", "replace"}:
+            raise ValueError("action_buttons_mode must be merge or replace")
+        self.action_buttons_mode = normalized_mode
         return self
 
 
@@ -1211,6 +1308,76 @@ class ViewPartialPatch(StrictModel):
         return self
 
 
+def public_button_trigger_action_value(value: Any) -> str:
+    raw = value.value if isinstance(value, PublicButtonTriggerAction) else str(value or "").strip()
+    normalized = raw.lower()
+    if raw == PublicButtonTriggerAction.add_data.value or normalized in {"add_data", "add-data", "adddata"}:
+        return "add_data"
+    if normalized in {PublicButtonTriggerAction.link.value, "url"}:
+        return "link"
+    if raw == PublicButtonTriggerAction.qrobot.value or normalized == "qrobot":
+        return "qRobot"
+    if normalized == PublicButtonTriggerAction.wings.value:
+        return "wings"
+    return raw
+
+
+def _drop_empty_public_payload_values(payload: dict[str, Any]) -> dict[str, Any]:
+    compact: dict[str, Any] = {}
+    for key, item in payload.items():
+        if item is None or item == "" or item == [] or item == {}:
+            continue
+        if key == "primary" and item is False:
+            continue
+        compact[key] = item
+    return compact
+
+
+def public_view_action_button_payload(button: Any, *, compact: bool = False) -> dict[str, Any]:
+    if isinstance(button, ViewActionButtonPatch):
+        payload = button.model_dump(mode="json")
+    elif isinstance(button, dict):
+        payload = dict(button)
+    else:
+        return {}
+    raw_action = payload.get("action", payload.get("trigger_action", payload.get("triggerAction")))
+    if raw_action is not None:
+        payload["action"] = public_button_trigger_action_value(raw_action)
+        payload.pop("trigger_action", None)
+        payload.pop("triggerAction", None)
+    if compact:
+        return _drop_empty_public_payload_values(payload)
+    return payload
+
+
+def public_view_upsert_payload(view: ViewUpsertPatch) -> dict[str, Any]:
+    payload = view.model_dump(mode="json")
+    if view.action_buttons is not None:
+        payload["action_buttons"] = [
+            public_view_action_button_payload(button, compact=True)
+            for button in view.action_buttons
+        ]
+    return payload
+
+
+def public_view_partial_payload(patch: ViewPartialPatch) -> dict[str, Any]:
+    payload = patch.model_dump(mode="json")
+    patch_set = payload.get("set")
+    if isinstance(patch_set, dict):
+        raw_buttons = patch_set.get("action_buttons")
+        if raw_buttons is None:
+            raw_buttons = patch_set.get("actionButtons")
+        if isinstance(raw_buttons, list):
+            patch_set = dict(patch_set)
+            patch_set.pop("actionButtons", None)
+            patch_set["action_buttons"] = [
+                public_view_action_button_payload(button, compact=True)
+                for button in raw_buttons
+            ]
+            payload["set"] = patch_set
+    return payload
+
+
 class CustomButtonJudgeValuePatch(StrictModel):
     id: int | str | None = None
     value: Any | None = None

package/src/qingflow_mcp/builder_facade/service.py

@@ -90,6 +90,7 @@ from .models import (
     SchemaPlanRequest,
     VisibilityPatch,
     ViewAssociatedResourcesPatch,
+    ViewActionButtonPatch,
     ViewButtonBindingPatch,
     ViewPartialPatch,
     ViewUpsertPatch,
@@ -99,6 +100,9 @@ from .models import (
     ViewsPreset,
     FlowPreset,
     FlowNodePermissionsPatch,
+    public_view_action_button_payload,
+    public_view_partial_payload,
+    public_view_upsert_payload,
 )
 
 BUILDER_PORTAL_LIST_DETAIL_VERIFY_LIMIT = 50
@@ -8264,7 +8268,8 @@ class AiBuilderFacade:
             for field in current_fields
             if isinstance(field, dict) and str(field.get("name") or "")
         }
-        upsert_views = [view.model_dump(mode="json") for view in request.upsert_views]
+        upsert_views = [public_view_upsert_payload(view) for view in request.upsert_views]
+        patch_views = [public_view_partial_payload(patch) for patch in request.patch_views]
         if request.preset is not None:
             upsert_views = _build_views_preset(request.preset, list(field_names))
         blocking_issues: list[dict[str, Any]] = []
@@ -8326,6 +8331,7 @@ class AiBuilderFacade:
         normalized_args = {
             "app_key": request.app_key,
             "upsert_views": upsert_views,
+            "patch_views": patch_views,
             "remove_views": list(request.remove_views),
         }
         return {
@@ -8344,6 +8350,7 @@ class AiBuilderFacade:
             "request_id": None,
             "views_diff_preview": {
                 "upsert": [view.get("name") for view in upsert_views],
+                "patch": [view.get("view_key") or view.get("name") for view in patch_views],
                 "remove": list(request.remove_views),
             },
             "blocking_issues": blocking_issues,
@@ -9980,6 +9987,406 @@ class AiBuilderFacade:
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
+    def _extract_view_action_button_patch_intents(
+        self,
+        *,
+        existing_by_key: dict[str, dict[str, Any]],
+        existing_by_name: dict[str, list[dict[str, Any]]],
+        patch_views: list[ViewPartialPatch],
+    ) -> tuple[list[ViewPartialPatch], list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+        action_keys = {"action_buttons", "actionButtons"}
+        mode_keys = {"action_buttons_mode", "actionButtonsMode", "button_mode", "buttonMode"}
+        sanitized: list[ViewPartialPatch] = []
+        intents: list[dict[str, Any]] = []
+        issues: list[dict[str, Any]] = []
+        results: list[dict[str, Any]] = []
+        sentinel = object()
+        for index, patch in enumerate(patch_views):
+            raw_set = dict(patch.set or {})
+            action_buttons_raw: Any = sentinel
+            for key in action_keys:
+                if key in raw_set:
+                    action_buttons_raw = raw_set.pop(key)
+                    break
+            mode_raw: Any = sentinel
+            for key in mode_keys:
+                if key in raw_set:
+                    mode_raw = raw_set.pop(key)
+                    break
+            if action_buttons_raw is not sentinel:
+                requires_view_write = bool(raw_set or patch.unset)
+                if not isinstance(action_buttons_raw, list):
+                    issue = {
+                        "error_code": "INVALID_VIEW_ACTION_BUTTONS",
+                        "reason_path": f"patch_views[{index}].set.action_buttons",
+                        "message": "action_buttons must be a list",
+                    }
+                    issues.append(issue)
+                    results.append({"index": index, "status": "failed", **issue})
+                else:
+                    mode = str(mode_raw if mode_raw is not sentinel else "merge").strip().lower() or "merge"
+                    if mode not in {"merge", "replace"}:
+                        issue = {
+                            "error_code": "INVALID_VIEW_ACTION_BUTTONS_MODE",
+                            "reason_path": f"patch_views[{index}].set.action_buttons_mode",
+                            "message": "action_buttons_mode must be merge or replace",
+                        }
+                        issues.append(issue)
+                        results.append({"index": index, "status": "failed", **issue})
+                    else:
+                        try:
+                            action_buttons = [
+                                ViewActionButtonPatch.model_validate(item)
+                                for item in action_buttons_raw
+                            ]
+                        except Exception as error:
+                            issue = {
+                                "error_code": "INVALID_VIEW_ACTION_BUTTONS",
+                                "reason_path": f"patch_views[{index}].set.action_buttons",
+                                "message": str(error),
+                            }
+                            issues.append(issue)
+                            results.append({"index": index, "status": "failed", **issue})
+                        else:
+                            view_key = str(patch.view_key or "").strip()
+                            view_name = str(patch.name or "").strip()
+                            matched_view: dict[str, Any] | None = None
+                            if view_key:
+                                matched_view = existing_by_key.get(view_key)
+                                if matched_view is None:
+                                    issue = {
+                                        "error_code": "UNKNOWN_VIEW",
+                                        "reason_path": f"patch_views[{index}].view_key",
+                                        "view_key": view_key,
+                                        "message": "view_key does not exist on this app",
+                                    }
+                                    issues.append(issue)
+                                    results.append({"index": index, "status": "failed", **issue})
+                            else:
+                                matches = existing_by_name.get(view_name, [])
+                                if len(matches) != 1:
+                                    issue = {
+                                        "error_code": "AMBIGUOUS_VIEW" if matches else "UNKNOWN_VIEW",
+                                        "reason_path": f"patch_views[{index}].name",
+                                        "view_name": view_name,
+                                        "matches": [
+                                            {"name": _extract_view_name(view), "view_key": _extract_view_key(view), "type": _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))}
+                                            for view in matches
+                                        ],
+                                        "message": "patch_views[].set.action_buttons must target a single existing view; use view_key when names are duplicated",
+                                    }
+                                    issues.append(issue)
+                                    results.append({"index": index, "status": "failed", **issue})
+                                else:
+                                    matched_view = matches[0]
+                                    view_key = _extract_view_key(matched_view)
+                            if matched_view is not None or view_key:
+                                view_name = _extract_view_name(matched_view or {}) or view_name or view_key
+                                intents.append(
+                                    {
+                                        "source": "patch_views",
+                                        "index": index,
+                                        "view_key": view_key,
+                                        "view_name": view_name,
+                                        "action_buttons": action_buttons,
+                                        "mode": mode,
+                                        "requires_view_write": requires_view_write,
+                                    }
+                                )
+                                results.append(
+                                    {
+                                        "index": index,
+                                        "status": "action_buttons_extracted",
+                                        "view_key": view_key,
+                                        "view_name": view_name,
+                                        "action_buttons_count": len(action_buttons),
+                                        "action_buttons_mode": mode,
+                                    }
+                                )
+            elif mode_raw is not sentinel:
+                issue = {
+                    "error_code": "ACTION_BUTTONS_MODE_WITHOUT_ACTION_BUTTONS",
+                    "reason_path": f"patch_views[{index}].set.action_buttons_mode",
+                    "message": "action_buttons_mode is only valid together with action_buttons",
+                }
+                issues.append(issue)
+                results.append({"index": index, "status": "failed", **issue})
+            if raw_set or patch.unset:
+                sanitized.append(
+                    ViewPartialPatch.model_validate(
+                        {
+                            "view_key": patch.view_key,
+                            "name": patch.name,
+                            "set": raw_set,
+                            "unset": list(patch.unset or []),
+                        }
+                    )
+                )
+        return sanitized, intents, issues, results
+
+    def _view_action_button_to_custom_button_payload(self, *, button: ViewActionButtonPatch, client_key: str | None) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "button_text": button.text,
+            "trigger_action": button.action.value,
+            "style_preset": button.style_preset or "primary_blue",
+        }
+        if button.button_id is not None:
+            payload["button_id"] = button.button_id
+        if client_key:
+            payload["client_key"] = client_key
+        if button.background_color:
+            payload["background_color"] = button.background_color
+        if button.text_color:
+            payload["text_color"] = button.text_color
+        if button.button_icon:
+            payload["button_icon"] = button.button_icon
+        if button.action == PublicButtonTriggerAction.link:
+            payload["trigger_link_url"] = button.url
+        elif button.action == PublicButtonTriggerAction.add_data:
+            add_data_config: dict[str, Any] = {
+                "related_app_key": button.target_app_key,
+                "related_app_name": button.target_app_name,
+                "field_mappings": deepcopy(button.field_mappings),
+                "default_values": deepcopy(button.default_values),
+            }
+            payload["trigger_add_data_config"] = _compact_dict(add_data_config)
+        elif button.action == PublicButtonTriggerAction.qrobot:
+            payload["external_qrobot_config"] = deepcopy(button.external_qrobot_config)
+        elif button.action == PublicButtonTriggerAction.wings:
+            payload["trigger_wings_config"] = deepcopy(button.trigger_wings_config)
+        return payload
+
+    def _view_action_button_binding_payload(self, *, button: ViewActionButtonPatch, button_ref: Any) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "button_ref": button_ref,
+            "placement": button.placement.value,
+            "primary": button.primary,
+            "button_limit": [
+                [rule.model_dump(mode="json") for rule in group]
+                for group in button.visible_when
+            ],
+            "button_formula_type": button.button_formula_type,
+            "print_tpls": deepcopy(button.print_tpls),
+        }
+        if button.button_formula:
+            payload["button_formula"] = button.button_formula
+        return payload
+
+    def _compile_view_action_buttons_request(
+        self,
+        *,
+        app_key: str,
+        intents: list[dict[str, Any]],
+    ) -> tuple[CustomButtonsApplyRequest | None, list[dict[str, Any]]]:
+        upsert_buttons: list[CustomButtonUpsertPatch] = []
+        view_configs: list[CustomButtonViewConfigPatch] = []
+        issues: list[dict[str, Any]] = []
+        seen_button_payloads: dict[str, dict[str, Any]] = {}
+        seen_button_refs: dict[str, Any] = {}
+        used_client_keys: set[str] = set()
+        for intent_index, intent in enumerate(intents):
+            view_key = str(intent.get("view_key") or "").strip()
+            mode = str(intent.get("mode") or "merge").strip().lower() or "merge"
+            action_buttons = [
+                item for item in (intent.get("action_buttons") or [])
+                if isinstance(item, ViewActionButtonPatch)
+            ]
+            bindings: list[dict[str, Any]] = []
+            for button_index, button in enumerate(action_buttons):
+                identity = f"id:{button.button_id}" if button.button_id is not None else f"text:{str(button.text or '').strip()}"
+                explicit_client_key = str(button.client_key or "").strip() or None
+                generated_client_key = explicit_client_key or f"view_action_{_slugify(str(button.text or ''), default='button')}"
+                client_key = generated_client_key
+                payload = self._view_action_button_to_custom_button_payload(
+                    button=button,
+                    client_key=None if button.button_id is not None else client_key,
+                )
+                compare_payload = deepcopy(payload)
+                compare_payload.pop("client_key", None)
+                existing_payload = seen_button_payloads.get(identity)
+                if existing_payload is not None:
+                    if existing_payload != compare_payload:
+                        issues.append(
+                            {
+                                "error_code": "DUPLICATE_ACTION_BUTTON_CONFLICT",
+                                "reason_path": f"{intent.get('source') or 'views'}[{intent.get('index', intent_index)}].action_buttons[{button_index}]",
+                                "button_text": button.text,
+                                "message": "the same app cannot declare two action_buttons with the same button text or id but different button body config in one app_views_apply call",
+                            }
+                        )
+                        continue
+                    button_ref = seen_button_refs[identity]
+                else:
+                    seen_button_payloads[identity] = compare_payload
+                    if button.button_id is not None:
+                        button_ref = button.button_id
+                    else:
+                        unique_client_key = client_key
+                        if unique_client_key in used_client_keys:
+                            unique_client_key = f"{unique_client_key}_{len(used_client_keys) + 1}"
+                            payload["client_key"] = unique_client_key
+                        used_client_keys.add(unique_client_key)
+                        button_ref = unique_client_key
+                        payload["client_key"] = unique_client_key
+                        try:
+                            upsert_buttons.append(CustomButtonUpsertPatch.model_validate(payload))
+                        except Exception as error:
+                            issues.append(
+                                {
+                                    "error_code": "INVALID_VIEW_ACTION_BUTTON",
+                                    "reason_path": f"{intent.get('source') or 'views'}[{intent.get('index', intent_index)}].action_buttons[{button_index}]",
+                                    "message": str(error),
+                                }
+                            )
+                            continue
+                    seen_button_refs[identity] = button_ref
+                bindings.append(self._view_action_button_binding_payload(button=button, button_ref=button_ref))
+            if mode == "replace" or bindings:
+                try:
+                    view_configs.append(CustomButtonViewConfigPatch.model_validate({"view_key": view_key, "mode": mode, "buttons": bindings}))
+                except Exception as error:
+                    issues.append(
+                        {
+                            "error_code": "INVALID_VIEW_ACTION_BUTTON_BINDING",
+                            "reason_path": f"{intent.get('source') or 'views'}[{intent.get('index', intent_index)}].action_buttons",
+                            "view_key": view_key,
+                            "message": str(error),
+                        }
+                    )
+        if issues:
+            return None, issues
+        if not upsert_buttons and not view_configs:
+            return None, []
+        try:
+            return CustomButtonsApplyRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "upsert_buttons": [item.model_dump(mode="json") for item in upsert_buttons],
+                    "view_configs": [item.model_dump(mode="json") for item in view_configs],
+                }
+            ), []
+        except Exception as error:
+            return None, [{"error_code": "INVALID_VIEW_ACTION_BUTTONS", "message": str(error)}]
+
+    def _view_action_buttons_retry_payload(self, *, profile: str, app_key: str, intents: list[dict[str, Any]]) -> dict[str, Any]:
+        return {
+            "tool_name": "app_views_apply",
+            "arguments": {
+                "profile": profile,
+                "app_key": app_key,
+                "publish": True,
+                "upsert_views": [],
+                "patch_views": [
+                    {
+                        "view_key": intent.get("view_key"),
+                        "set": {
+                            "action_buttons": [
+                                public_view_action_button_payload(button, compact=True)
+                                for button in (intent.get("action_buttons") or [])
+                                if isinstance(button, ViewActionButtonPatch)
+                            ],
+                            "action_buttons_mode": intent.get("mode") or "merge",
+                        },
+                    }
+                    for intent in intents
+                    if str(intent.get("view_key") or "").strip()
+                ],
+                "remove_views": [],
+            },
+        }
+
+    def _failed_view_action_button_intents(self, *, intents: list[dict[str, Any]], result: dict[str, Any]) -> list[dict[str, Any]]:
+        failed_view_keys: set[str] = set()
+        failed_button_texts: set[str] = set()
+        for item in result.get("failed") or []:
+            if not isinstance(item, dict):
+                continue
+            view_key = str(item.get("view_key") or item.get("viewgraph_key") or "").strip()
+            if view_key:
+                failed_view_keys.add(view_key)
+            button_text = str(item.get("button_text") or item.get("text") or "").strip()
+            if button_text:
+                failed_button_texts.add(button_text)
+        for item in result.get("view_configs") or []:
+            if not isinstance(item, dict):
+                continue
+            status = str(item.get("status") or "").strip()
+            if status and status not in {"success", "noop", "skipped"}:
+                view_key = str(item.get("view_key") or item.get("viewgraph_key") or "").strip()
+                if view_key:
+                    failed_view_keys.add(view_key)
+        if failed_view_keys:
+            return [
+                intent
+                for intent in intents
+                if str(intent.get("view_key") or "").strip() in failed_view_keys
+            ]
+        if failed_button_texts:
+            return [
+                intent
+                for intent in intents
+                if any(
+                    isinstance(button, ViewActionButtonPatch) and str(button.text or "").strip() in failed_button_texts
+                    for button in (intent.get("action_buttons") or [])
+                )
+            ]
+        if str(result.get("status") or "").strip() == "failed" or (result.get("write_succeeded") is False and bool(result.get("write_executed"))):
+            return list(intents)
+        return []
+
+    def _apply_view_action_buttons(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        intents: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        if not intents:
+            return {
+                "status": "success",
+                "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "verification": {
+                    "action_buttons_verified": True,
+                    "view_button_bindings_verified": True,
+                },
+                "retry_payload": None,
+            }
+        request, issues = self._compile_view_action_buttons_request(app_key=app_key, intents=intents)
+        if issues:
+            return {
+                "status": "failed",
+                "error_code": "DUPLICATE_ACTION_BUTTON_CONFLICT" if any(item.get("error_code") == "DUPLICATE_ACTION_BUTTON_CONFLICT" for item in issues) else "VIEW_ACTION_BUTTONS_INVALID",
+                "recoverable": True,
+                "message": "view action_buttons could not be compiled; view writes may already have completed",
+                "details": {"blocking_issues": issues},
+                "verification": {
+                    "action_buttons_verified": False,
+                    "view_button_bindings_verified": False,
+                },
+                "verified": False,
+                "write_executed": False,
+                "write_succeeded": False,
+                "retry_payload": self._view_action_buttons_retry_payload(profile=profile, app_key=app_key, intents=intents),
+            }
+        if request is None:
+            return {
+                "status": "success",
+                "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "verification": {
+                    "action_buttons_verified": True,
+                    "view_button_bindings_verified": True,
+                },
+                "retry_payload": None,
+            }
+        result = self.app_custom_buttons_apply(profile=profile, request=request)
+        retry_intents = [] if result.get("verified") else self._failed_view_action_button_intents(intents=intents, result=result)
+        result["retry_payload"] = self._view_action_buttons_retry_payload(profile=profile, app_key=app_key, intents=retry_intents) if retry_intents else None
+        return result
+
     def app_views_apply(
         self,
         *,
@@ -9993,11 +10400,27 @@ class AiBuilderFacade:
         patch_views = patch_views or []
         normalized_args = {
             "app_key": app_key,
-            "upsert_views": [patch.model_dump(mode="json") for patch in upsert_views],
-            "patch_views": [patch.model_dump(mode="json") for patch in patch_views],
+            "upsert_views": [public_view_upsert_payload(patch) for patch in upsert_views],
+            "patch_views": [public_view_partial_payload(patch) for patch in patch_views],
             "remove_views": list(remove_views),
             "publish": publish,
         }
+        has_action_button_intent = any(patch.action_buttons is not None for patch in upsert_views) or any(
+            any(key in (patch.set or {}) for key in ("action_buttons", "actionButtons"))
+            for patch in patch_views
+        )
+        if has_action_button_intent and not publish:
+            return _failed(
+                "VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH",
+                "app_views_apply action_buttons require publish=true because the underlying custom button writer may publish after successful button writes",
+                normalized_args=normalized_args,
+                details={
+                    "app_key": app_key,
+                    "required_publish": True,
+                    "reason": "action_buttons are compiled through app_custom_buttons_apply",
+                },
+                suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **{**normalized_args, "publish": True}}},
+            )
         if not upsert_views and not patch_views and not remove_views:
             response = {
                 "status": "success",
@@ -10104,6 +10527,28 @@ class AiBuilderFacade:
             if name and key:
                 existing_by_key[key] = view
                 existing_by_name.setdefault(name, []).append(view)
+        patch_action_button_intents: list[dict[str, Any]] = []
+        action_button_patch_results: list[dict[str, Any]] = []
+        if patch_views:
+            sanitized_patch_views, patch_action_button_intents, action_button_patch_issues, action_button_patch_results = self._extract_view_action_button_patch_intents(
+                existing_by_key=existing_by_key,
+                existing_by_name=existing_by_name,
+                patch_views=patch_views,
+            )
+            if action_button_patch_results:
+                normalized_args["action_button_patch_results"] = action_button_patch_results
+            if action_button_patch_issues:
+                return finalize(
+                    _failed(
+                        "VIEW_ACTION_BUTTON_PATCH_FAILED",
+                        "one or more patch_views action_buttons entries could not be resolved; no write was executed",
+                        normalized_args=normalized_args,
+                        details={"patch_results": action_button_patch_results, "blocking_issues": action_button_patch_issues},
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+                )
+            patch_views = sanitized_patch_views
+            normalized_args["patch_views"] = [public_view_partial_payload(patch) for patch in patch_views]
         creating_view_names = [
             patch.name
             for patch in upsert_views
@@ -10155,7 +10600,7 @@ class AiBuilderFacade:
                     )
                 )
             upsert_views = [*upsert_views, *expanded_views]
-            normalized_args["upsert_views"] = [patch.model_dump(mode="json") for patch in upsert_views]
+            normalized_args["upsert_views"] = [public_view_upsert_payload(patch) for patch in upsert_views]
             normalized_args["patch_results"] = patch_results
         current_fields_by_name = {
             str(field.get("name") or ""): field
@@ -10250,6 +10695,22 @@ class AiBuilderFacade:
         removed_keys: set[str] = set()
         view_results: list[dict[str, Any]] = []
         failed_views: list[dict[str, Any]] = []
+        action_button_intents: list[dict[str, Any]] = list(patch_action_button_intents)
+
+        def record_action_button_intent(*, patch: ViewUpsertPatch, view_key: str | None, index: int) -> None:
+            if patch.action_buttons is None:
+                return
+            action_button_intents.append(
+                {
+                    "source": "upsert_views",
+                    "index": index,
+                    "view_key": str(view_key or "").strip(),
+                    "view_name": patch.name,
+                    "action_buttons": list(patch.action_buttons),
+                    "mode": patch.action_buttons_mode,
+                }
+            )
+
         for selector in remove_views:
             selector_text = str(selector or "").strip()
             if not selector_text:
@@ -10644,6 +11105,7 @@ class AiBuilderFacade:
                                 "apply_columns": deepcopy(apply_columns),
                             }
                         )
+                    record_action_button_intent(patch=patch, view_key=existing_key, index=ordinal - 1)
                 else:
                     template_key = _pick_view_template_key(existing_view_list, desired_type=patch.type.value)
                     should_copy_template = patch.type.value == "table" and template_key and not translated_filters
@@ -10698,6 +11160,7 @@ class AiBuilderFacade:
                                 "expected_associated_resources": deepcopy(expected_associated_resources_for_verify),
                             }
                         )
+                    record_action_button_intent(patch=patch, view_key=created_key, index=ordinal - 1)
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 should_retry_minimal = operation_phase != "default_view_apply_config_sync" and (
@@ -10790,6 +11253,7 @@ class AiBuilderFacade:
                                         "apply_columns": deepcopy(apply_columns),
                                     }
                                 )
+                                record_action_button_intent(patch=patch, view_key=existing_key, index=ordinal - 1)
                             else:
                                 created.append(patch.name)
                                 view_results.append(
@@ -10807,6 +11271,7 @@ class AiBuilderFacade:
                                         "apply_columns": deepcopy(apply_columns),
                                     }
                                 )
+                                record_action_button_intent(patch=patch, view_key=created_key, index=ordinal - 1)
                             continue
                         fallback_payload = _build_minimal_view_payload(
                             app_key=app_key,
@@ -10834,6 +11299,7 @@ class AiBuilderFacade:
                                 "expected_associated_resources": deepcopy(expected_associated_resources_for_verify),
                             }
                         )
+                        record_action_button_intent(patch=patch, view_key=created_key, index=ordinal - 1)
                         continue
                     except (QingflowApiError, RuntimeError) as fallback_error:
                         api_error = _coerce_api_error(fallback_error)
@@ -10881,6 +11347,56 @@ class AiBuilderFacade:
                 failed_views.append(failure_entry)
                 view_results.append(failure_entry)
                 continue
+        successful_action_view_keys = {
+            str(item.get("view_key") or "").strip()
+            for item in view_results
+            if str(item.get("status") or "") in {"created", "updated"} and str(item.get("view_key") or "").strip()
+        }
+        successful_action_view_names = {
+            str(item.get("name") or "").strip()
+            for item in view_results
+            if str(item.get("status") or "") in {"created", "updated"} and str(item.get("name") or "").strip()
+        }
+        skipped_action_button_intents = [
+            intent
+            for intent in action_button_intents
+            if bool(intent.get("requires_view_write"))
+            and str(intent.get("view_key") or "").strip() not in successful_action_view_keys
+            and str(intent.get("view_name") or "").strip() not in successful_action_view_names
+        ]
+        skipped_action_button_intent_ids = {id(intent) for intent in skipped_action_button_intents}
+        runnable_action_button_intents = [
+            intent for intent in action_button_intents if id(intent) not in skipped_action_button_intent_ids
+        ]
+        action_buttons_result = self._apply_view_action_buttons(
+            profile=profile,
+            app_key=app_key,
+            intents=runnable_action_button_intents,
+        )
+        if skipped_action_button_intents:
+            action_buttons_result.setdefault("skipped_due_to_view_write_failure", [])
+            if isinstance(action_buttons_result["skipped_due_to_view_write_failure"], list):
+                action_buttons_result["skipped_due_to_view_write_failure"].extend(
+                    {
+                        "source": intent.get("source"),
+                        "index": intent.get("index"),
+                        "view_key": intent.get("view_key"),
+                        "view_name": intent.get("view_name"),
+                        "action_buttons_count": len(intent.get("action_buttons") or []),
+                    }
+                    for intent in skipped_action_button_intents
+                )
+        action_button_write_executed = bool(action_buttons_result.get("write_executed"))
+        action_button_write_succeeded = bool(action_buttons_result.get("write_succeeded"))
+        action_buttons_verification = action_buttons_result.get("verification") if isinstance(action_buttons_result.get("verification"), dict) else {}
+        action_buttons_verified = (
+            bool(action_buttons_result.get("verified", True))
+            and bool(action_buttons_verification.get("custom_buttons_verified", action_buttons_verification.get("action_buttons_verified", True)))
+            and not skipped_action_button_intents
+        )
+        view_action_button_bindings_verified = bool(action_buttons_verification.get("view_button_bindings_verified", True)) and not skipped_action_button_intents
+        action_buttons_failed = bool(action_button_intents) and not (action_buttons_verified and view_action_button_bindings_verified)
+        action_buttons_retry_payload = action_buttons_result.get("retry_payload") if isinstance(action_buttons_result.get("retry_payload"), dict) else None
         needs_view_list_readback = bool(created or updated)
         verified_view_result: list[dict[str, Any]] | None = []
         verified_views_unavailable = False
@@ -11251,9 +11767,9 @@ class AiBuilderFacade:
         view_query_conditions_verified = verified and not query_condition_readback_pending and not query_condition_mismatches
         view_associated_resources_verified = verified and not associated_resource_readback_pending and not associated_resource_mismatches
         view_buttons_verified = verified and not button_readback_pending and not button_mismatches and not custom_button_readback_pending
-        noop = not created and not updated and not removed
+        noop = not created and not updated and not removed and not action_button_write_executed
         if failed_views:
-            successful_changes = bool(created or updated or removed)
+            successful_changes = bool(created or updated or removed or action_button_write_succeeded)
             first_failure = failed_views[0]
             response = {
                 "status": "partial_success" if successful_changes else "failed",
@@ -11269,6 +11785,7 @@ class AiBuilderFacade:
                     "query_condition_mismatches": query_condition_mismatches,
                     "associated_resource_mismatches": associated_resource_mismatches,
                     "button_mismatches": button_mismatches,
+                    **({"action_buttons_result": action_buttons_result} if action_button_intents else {}),
                     **(
                         {"custom_button_readback_pending": deepcopy(custom_button_readback_pending_entries)}
                         if custom_button_readback_pending_entries
@@ -11301,6 +11818,11 @@ class AiBuilderFacade:
                         if (button_readback_pending or button_mismatches)
                         else []
                     )
+                    + (
+                        [_warning("VIEW_ACTION_BUTTONS_UNVERIFIED", "view definitions may exist, but inline action button creation or binding is not fully verified")]
+                        if action_buttons_failed
+                        else []
+                    )
                     + (
                         [_warning("VIEW_CUSTOM_BUTTON_READBACK_PENDING", "system buttons verified, but draft custom button bindings are not fully visible through view readback yet")]
                         if custom_button_readback_pending
@@ -11313,6 +11835,8 @@ class AiBuilderFacade:
                     "view_query_conditions_verified": view_query_conditions_verified,
                     "view_associated_resources_verified": view_associated_resources_verified,
                     "view_buttons_verified": view_buttons_verified,
+                    "action_buttons_verified": action_buttons_verified,
+                    "view_button_bindings_verified": view_action_button_bindings_verified,
                     "views_read_unavailable": verified_views_unavailable,
                     "by_view": verification_by_view,
                     "custom_button_readback_pending": custom_button_readback_pending,
@@ -11321,10 +11845,10 @@ class AiBuilderFacade:
                 "app_key": app_key,
                 "app_name": app_name,
                 "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
-                "verified": verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified,
-                "write_executed": bool(created or updated or removed),
-                "write_succeeded": bool(created or updated or removed),
-                "safe_to_retry": not bool(created or updated or removed),
+                "verified": verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified and action_buttons_verified and view_action_button_bindings_verified,
+                "write_executed": bool(created or updated or removed or action_button_write_executed),
+                "write_succeeded": bool(created or updated or removed or action_button_write_succeeded),
+                "safe_to_retry": not bool(created or updated or removed or action_button_write_executed),
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         warnings: list[dict[str, Any]] = []
@@ -11336,6 +11860,8 @@ class AiBuilderFacade:
             warnings.append(_warning("VIEW_ASSOCIATED_RESOURCES_UNVERIFIED", "view definitions were applied, but associated resource visibility is not fully verified"))
         if button_readback_pending or button_mismatches:
             warnings.append(_warning("VIEW_BUTTONS_UNVERIFIED", "view definitions were applied, but saved button behavior is not fully verified"))
+        if action_buttons_failed:
+            warnings.append(_warning("VIEW_ACTION_BUTTONS_UNVERIFIED", "view definitions were applied, but inline action button creation or binding is not fully verified"))
         if custom_button_readback_pending:
             warnings.append(
                 _warning(
@@ -11350,14 +11876,25 @@ class AiBuilderFacade:
                     "view delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
                 )
             )
-        all_verified = verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified
+        all_verified = (
+            verified
+            and view_filters_verified
+            and view_query_conditions_verified
+            and view_associated_resources_verified
+            and view_buttons_verified
+            and action_buttons_verified
+            and view_action_button_bindings_verified
+        )
+        action_buttons_error_code = str(action_buttons_result.get("error_code") or "VIEW_ACTION_BUTTONS_APPLY_FAILED") if action_buttons_failed else None
         response = {
             "status": "success" if all_verified else "partial_success",
-            "error_code": None if all_verified else ("VIEW_BUTTON_READBACK_MISMATCH" if button_mismatches else "VIEW_ASSOCIATED_RESOURCE_READBACK_MISMATCH" if associated_resource_mismatches else "VIEW_QUERY_CONDITION_READBACK_MISMATCH" if query_condition_mismatches else "VIEW_FILTER_READBACK_MISMATCH" if filter_mismatches else "VIEWS_READBACK_PENDING"),
+            "error_code": None if all_verified else (action_buttons_error_code if action_buttons_failed else "VIEW_BUTTON_READBACK_MISMATCH" if button_mismatches else "VIEW_ASSOCIATED_RESOURCE_READBACK_MISMATCH" if associated_resource_mismatches else "VIEW_QUERY_CONDITION_READBACK_MISMATCH" if query_condition_mismatches else "VIEW_FILTER_READBACK_MISMATCH" if filter_mismatches else "VIEWS_READBACK_PENDING"),
             "recoverable": not all_verified,
             "message": (
                 "applied view patch"
                 if all_verified
+                else "applied view patch; inline action buttons did not fully verify"
+                if action_buttons_failed
                 else "applied view patch; buttons did not fully verify"
                 if button_mismatches
                 else "applied view patch; associated resources did not fully verify"
@@ -11376,6 +11913,7 @@ class AiBuilderFacade:
                 **({"query_condition_mismatches": query_condition_mismatches} if query_condition_mismatches else {}),
                 **({"associated_resource_mismatches": associated_resource_mismatches} if associated_resource_mismatches else {}),
                 **({"button_mismatches": button_mismatches} if button_mismatches else {}),
+                **({"action_buttons_result": action_buttons_result} if action_button_intents else {}),
                 **(
                     {"custom_button_readback_pending": deepcopy(custom_button_readback_pending_entries)}
                     if custom_button_readback_pending_entries
@@ -11383,7 +11921,7 @@ class AiBuilderFacade:
                 ),
             },
             "request_id": None,
-            "suggested_next_call": None if all_verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+            "suggested_next_call": None if all_verified else (action_buttons_retry_payload if action_buttons_failed and action_buttons_retry_payload else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}}),
             "noop": noop,
             "warnings": warnings,
             "verification": {
@@ -11392,6 +11930,8 @@ class AiBuilderFacade:
                 "view_query_conditions_verified": view_query_conditions_verified,
                 "view_associated_resources_verified": view_associated_resources_verified,
                 "view_buttons_verified": view_buttons_verified,
+                "action_buttons_verified": action_buttons_verified,
+                "view_button_bindings_verified": view_action_button_bindings_verified,
                 "views_read_unavailable": verified_views_unavailable,
                 "filter_readback_pending": filter_readback_pending,
                 "query_condition_readback_pending": query_condition_readback_pending,
@@ -11406,9 +11946,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": all_verified,
-            "write_executed": bool(created or updated or removed),
-            "write_succeeded": bool(created or updated or removed),
-            "safe_to_retry": not bool(created or updated or removed),
+            "write_executed": bool(created or updated or removed or action_button_write_executed),
+            "write_succeeded": bool(created or updated or removed or action_button_write_succeeded),
+            "safe_to_retry": not bool(created or updated or removed or action_button_write_executed),
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -49,6 +49,8 @@ from ..builder_facade.models import (
     ViewUpsertPatch,
     ViewsPreset,
     ViewsPlanRequest,
+    public_view_partial_payload,
+    public_view_upsert_payload,
 )
 from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
 from ..solution.compiler.icon_utils import (
@@ -2018,6 +2020,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         upsert_views: list[JSONObject] | None = None,
+        patch_views: list[JSONObject] | None = None,
         remove_views: list[str] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
@@ -2036,6 +2039,7 @@ class AiBuilderTools(ToolBase):
                 {
                     "app_key": app_key,
                     "upsert_views": upsert_views or [],
+                    "patch_views": patch_views or [],
                     "remove_views": remove_views or [],
                     "preset": preset,
                 }
@@ -2052,6 +2056,7 @@ class AiBuilderTools(ToolBase):
                         "app_key": app_key,
                         "preset": "default_table",
                         "upsert_views": [],
+                        "patch_views": [],
                         "remove_views": [],
                     },
                 },
@@ -2059,8 +2064,24 @@ class AiBuilderTools(ToolBase):
         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")}},
+            normalized_args={
+                "app_key": request.app_key,
+                "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
+                "remove_views": list(request.remove_views),
+                "preset": request.preset.value if request.preset is not None else None,
+            },
+            suggested_next_call={
+                "tool_name": "app_views_plan",
+                "arguments": {
+                    "profile": profile,
+                    "app_key": request.app_key,
+                    "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                    "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
+                    "remove_views": list(request.remove_views),
+                    "preset": request.preset.value if request.preset is not None else None,
+                },
+            },
         )
 
     @tool_cn_name("应用结构应用")
@@ -2990,7 +3011,7 @@ class AiBuilderTools(ToolBase):
         )
         if reserved_failure is not None:
             return reserved_failure
-        if patch_views:
+        if patch_views or _view_payload_has_action_buttons(upsert_views=upsert_views, patch_views=patch_views):
             try:
                 parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
                 parsed_patch_views = [ViewPartialPatch.model_validate(item) for item in patch_views]
@@ -3016,8 +3037,8 @@ class AiBuilderTools(ToolBase):
             normalized_args = {
                 "app_key": app_key,
                 "publish": publish,
-                "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
-                "patch_views": [patch.model_dump(mode="json") for patch in parsed_patch_views],
+                "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
+                "patch_views": [public_view_partial_payload(patch) for patch in parsed_patch_views],
                 "remove_views": list(remove_views or []),
             }
             return _safe_tool_call(
@@ -3072,7 +3093,8 @@ class AiBuilderTools(ToolBase):
         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],
+            "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
+            "patch_views": [],
             "remove_views": list(plan_args.get("remove_views") or remove_views),
         }
         return _safe_tool_call(
@@ -4278,6 +4300,23 @@ def _reserved_system_view_name_failure(
     return None
 
 
+def _view_payload_has_action_buttons(
+    *,
+    upsert_views: list[JSONObject] | None = None,
+    patch_views: list[JSONObject] | None = None,
+) -> bool:
+    for item in upsert_views or []:
+        if isinstance(item, dict) and any(key in item for key in ("action_buttons", "actionButtons")):
+            return True
+    for item in patch_views or []:
+        if not isinstance(item, dict):
+            continue
+        raw_set = item.get("set")
+        if isinstance(raw_set, dict) and any(key in raw_set for key in ("action_buttons", "actionButtons")):
+            return True
+    return False
+
+
 def _config_failure(
     *,
     tool_name: str,
@@ -4986,6 +5025,15 @@ def _builder_view_resources(payload: JSONObject) -> list[JSONObject]:
                 message=message,
             )
         )
+    details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
+    action_buttons_result = details.get("action_buttons_result") if isinstance(details, dict) else None
+    if isinstance(action_buttons_result, dict):
+        nested_payload = {
+            **action_buttons_result,
+            "app_key": payload.get("app_key"),
+            "app_name": payload.get("app_name"),
+        }
+        resources.extend(_builder_button_resources(nested_payload))
     return resources
 
 
@@ -6460,11 +6508,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].columns",
             "upsert_views[].filters",
             "upsert_views[].buttons",
+            "upsert_views[].action_buttons",
+            "upsert_views[].action_buttons_mode",
             "upsert_views[].visibility",
             "upsert_views[].query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
+            "patch_views[].set.action_buttons",
+            "patch_views[].set.action_buttons_mode",
             "patch_views[].unset",
         ],
         "aliases": {
@@ -6492,6 +6544,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons[].buttonFormula": "buttons[].button_formula",
             "buttons[].buttonFormulaType": "buttons[].button_formula_type",
             "buttons[].printTpls": "buttons[].print_tpls",
+            "actionButtons": "action_buttons",
+            "actionButtonsMode": "action_buttons_mode",
+            "action_buttons[].button_text": "action_buttons[].text",
+            "action_buttons[].trigger_action": "action_buttons[].action",
+            "action_buttons[].trigger_link_url": "action_buttons[].url",
+            "action_buttons[].visibleWhen": "action_buttons[].visible_when",
+            "action_buttons[].fieldMappings": "action_buttons[].field_mappings",
+            "action_buttons[].defaultValues": "action_buttons[].default_values",
         },
         "allowed_values": {
             "preset": [member.value for member in ViewsPreset],
@@ -6499,6 +6559,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
+            "view.action_buttons.action": ["add_data", "link", "qRobot", "wings"],
+            "view.action_buttons.placement": [member.value for member in PublicButtonPlacement],
+            "view.action_buttons_mode": ["merge", "replace"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -6508,6 +6571,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
             "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
+            "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
+            "action_buttons_mode defaults to merge; replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears this view's custom button bindings without deleting button bodies",
+            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
             "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
@@ -6538,6 +6604,27 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "action_buttons_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "生产工单执行视图",
+                    "type": "table",
+                    "columns": ["工单编号", "产品", "状态", "负责人"],
+                    "action_buttons": [
+                        {
+                            "text": "开始生产",
+                            "action": "link",
+                            "url": "https://example.com/start",
+                            "placement": "list",
+                            "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
+                        }
+                    ],
+                }
+            ],
+            "remove_views": [],
+        },
         "full_upsert_query_conditions_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6595,11 +6682,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].columns",
             "upsert_views[].filters",
             "upsert_views[].buttons",
+            "upsert_views[].action_buttons",
+            "upsert_views[].action_buttons_mode",
             "upsert_views[].visibility",
             "upsert_views[].query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
+            "patch_views[].set.action_buttons",
+            "patch_views[].set.action_buttons_mode",
             "patch_views[].unset",
         ],
         "aliases": {
@@ -6627,12 +6718,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons[].buttonFormula": "buttons[].button_formula",
             "buttons[].buttonFormulaType": "buttons[].button_formula_type",
             "buttons[].printTpls": "buttons[].print_tpls",
+            "actionButtons": "action_buttons",
+            "actionButtonsMode": "action_buttons_mode",
+            "action_buttons[].button_text": "action_buttons[].text",
+            "action_buttons[].trigger_action": "action_buttons[].action",
+            "action_buttons[].trigger_link_url": "action_buttons[].url",
+            "action_buttons[].visibleWhen": "action_buttons[].visible_when",
+            "action_buttons[].fieldMappings": "action_buttons[].field_mappings",
+            "action_buttons[].defaultValues": "action_buttons[].default_values",
         },
         "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", "INSIDE"],
+            "view.action_buttons.action": ["add_data", "link", "qRobot", "wings"],
+            "view.action_buttons.placement": [member.value for member in PublicButtonPlacement],
+            "view.action_buttons_mode": ["merge", "replace"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -6642,6 +6744,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "read back app_get 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",
+            "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
+            "patch_views[].set.action_buttons can add buttons to an existing view without rewriting columns/filters; action_buttons_mode defaults to merge, replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears bindings without deleting button bodies",
+            "publish=false with action_buttons is blocked as VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH because the underlying custom button writer may publish after successful button writes",
+            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
             "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",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
@@ -6679,6 +6785,51 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "action_buttons_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "生产工单执行视图",
+                    "type": "table",
+                    "columns": ["工单编号", "产品", "状态", "负责人"],
+                    "action_buttons": [
+                        {
+                            "text": "开始生产",
+                            "action": "link",
+                            "url": "https://example.com/start",
+                            "placement": "list",
+                            "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
+                        }
+                    ],
+                }
+            ],
+            "remove_views": [],
+        },
+        "action_buttons_patch_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "patch_views": [
+                {
+                    "view_key": "RAW_VIEW_KEY",
+                    "set": {
+                        "action_buttons": [
+                            {
+                                "text": "创建验收单",
+                                "action": "add_data",
+                                "target_app_key": "ARRIVAL_APP",
+                                "field_mappings": [{"source_field": "数据ID", "target_field": "关联工单"}],
+                                "default_values": {"状态": "待验收"},
+                                "placement": "detail",
+                            }
+                        ]
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "full_upsert_query_conditions_example": {
             "profile": "default",
             "app_key": "APP_KEY",