@josephyan/qingflow-app-builder-mcp 0.2.0-beta.1016 → 0.2.0-beta.1018

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.1016
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.1018
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.1016 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.1018 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.1016",
+  "version": "0.2.0-beta.1018",
   "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 = "0.2.0b1016"
+version = "0.2.0b1018"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1016"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/button_style_catalog.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+BUTTON_BACKGROUND_COLORS: tuple[str, ...] = (
+    "transparent",
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#FFFFFF",
+)
+
+BUTTON_TEXT_COLORS: tuple[str, ...] = (
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#494F57",
+    "#FFFFFF",
+)
+
+BUTTON_ICONS: tuple[str, ...] = (
+    "ex-print",
+    "ex-attachment",
+    "ex-handoff",
+    "ex-delete",
+    "ex-copy",
+    "ex-share",
+    "ex-edit2",
+    "ex-admin-outlined",
+    "ex-stamp",
+    "ex-kanban",
+    "ex-update",
+    "ex-tickincircle-outlined",
+    "ex-crossincircle-outlined",
+    "ex-plus-circle",
+    "ex-logout",
+    "ex-check",
+    "ex-rename",
+    "ex-locked",
+    "ex-shift",
+    "ex-new-tabpage",
+    "ex-cross",
+    "ex-switch",
+    "ex-layer",
+    "ex-import",
+    "ex-pin-outlined",
+    "ex-disabled",
+    "ex-duplicate",
+    "ex-heart-outlined",
+    "ex-plus",
+    "ex-save",
+    "ex-upload",
+    "ex-upgrade1",
+    "ex-downgrade",
+    "ex-unfold",
+    "ex-fold",
+    "ex-sort",
+    "ex-menu-control",
+    "ex-download",
+    "ex-insert-below",
+    "ex-left-outlined-double",
+    "ex-right-outlined-double",
+    "ex-recovery",
+    "ex-layout",
+    "ex-search",
+    "ex-preview",
+    "ex-invisible",
+    "ex-carboncopy",
+    "ex-basicInfo",
+    "ex-fillIn",
+    "ex-refresh",
+    "ex-display",
+    "ex-message",
+    "ex-edit",
+    "ex-heart-filled",
+    "ex-pin-filled",
+    "ex-transfer",
+    "ex-cross-circle",
+    "ex-clock",
+    "ex-admin-filled",
+    "ex-tickincircle-circle",
+    "ex-all-application",
+    "ex-help-filled",
+    "ex-streamline",
+    "ex-table",
+    "ex-rowheight-short",
+    "ex-rowheight-medium",
+    "ex-rowheight-tall",
+    "ex-rowheight-tallest",
+)
+
+BUTTON_STYLE_PRESETS: tuple[dict[str, Any], ...] = (
+    {
+        "key": "primary_blue",
+        "label": "Primary Blue",
+        "button_type": "default",
+        "background_color": "#268BFB",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-plus-circle", "ex-plus"],
+    },
+    {
+        "key": "text_blue",
+        "label": "Text Blue",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#268BFB",
+        "recommended_icons": ["ex-share", "ex-new-tabpage"],
+    },
+    {
+        "key": "warning_orange",
+        "label": "Warning Orange",
+        "button_type": "default",
+        "background_color": "#FB9337",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-message", "ex-clock"],
+    },
+    {
+        "key": "danger_red",
+        "label": "Danger Red",
+        "button_type": "default",
+        "background_color": "#FB4B51",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-delete", "ex-cross-circle"],
+    },
+    {
+        "key": "neutral_outline",
+        "label": "Neutral Outline",
+        "button_type": "default",
+        "background_color": "#FFFFFF",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+    {
+        "key": "secondary_gray",
+        "label": "Secondary Gray",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+)
+
+_PRESET_BY_KEY: dict[str, dict[str, Any]] = {
+    str(item["key"]).strip(): dict(item) for item in BUTTON_STYLE_PRESETS
+}
+
+_COLOR_FAMILY_BY_VALUE: dict[str, str] = {
+    "transparent": "neutral",
+    "#FB9337": "orange",
+    "#FA6F32": "orange",
+    "#FAB300": "yellow",
+    "#67C200": "green",
+    "#00BD77": "green",
+    "#00C5FB": "cyan",
+    "#268BFB": "blue",
+    "#001A72": "blue",
+    "#9E64FB": "purple",
+    "#D164FB": "purple",
+    "#FB4B51": "red",
+    "#FFFFFF": "white",
+    "#494F57": "gray",
+}
+
+
+def _normalize_color_value(value: str | None) -> str | None:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return None
+    lowered = normalized.lower().replace(" ", "")
+    if lowered == "transparent":
+        return "transparent"
+    if lowered in {
+        "#fff",
+        "#ffffff",
+        "white",
+        "rgb(255,255,255)",
+        "rgba(255,255,255,1)",
+    }:
+        return "#FFFFFF"
+    if normalized.startswith("#"):
+        return normalized.upper()
+    return normalized
+
+
+def button_style_catalog_payload() -> dict[str, Any]:
+    return {
+        "icons": [{"value": icon, "label": icon} for icon in BUTTON_ICONS],
+        "background_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_BACKGROUND_COLORS
+        ],
+        "text_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_TEXT_COLORS
+        ],
+        "presets": [deepcopy(item) for item in BUTTON_STYLE_PRESETS],
+    }
+
+
+def resolve_button_style(
+    *,
+    style_preset: str | None,
+    button_icon: str | None,
+    background_color: str | None,
+    text_color: str | None,
+    require_complete_style: bool,
+) -> dict[str, str | None]:
+    preset_key = str(style_preset or "").strip() or None
+    resolved_icon = str(button_icon or "").strip() or None
+    resolved_background = _normalize_color_value(background_color)
+    resolved_text = _normalize_color_value(text_color)
+
+    if preset_key is not None:
+        preset = _PRESET_BY_KEY.get(preset_key)
+        if preset is None:
+            raise ValueError(
+                "unsupported style_preset; use button_style_catalog_get to inspect available presets"
+            )
+        if resolved_background is None:
+            resolved_background = str(preset["background_color"])
+        if resolved_text is None:
+            resolved_text = str(preset["text_color"])
+        if resolved_icon is None:
+            recommended = preset.get("recommended_icons") or []
+            if recommended:
+                resolved_icon = str(recommended[0]).strip() or None
+
+    if require_complete_style:
+        missing: list[str] = []
+        if resolved_icon is None:
+            missing.append("button_icon")
+        if resolved_background is None:
+            missing.append("background_color")
+        if resolved_text is None:
+            missing.append("text_color")
+        if missing:
+            raise ValueError(f"button style requires {', '.join(missing)}")
+
+    if resolved_icon is not None and resolved_icon not in BUTTON_ICONS:
+        raise ValueError(
+            "unsupported button_icon; use button_style_catalog_get to inspect available icons"
+        )
+    if resolved_background is not None and resolved_background not in BUTTON_BACKGROUND_COLORS:
+        raise ValueError(
+            "unsupported background_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+    if resolved_text is not None and resolved_text not in BUTTON_TEXT_COLORS:
+        raise ValueError(
+            "unsupported text_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+
+    return {
+        "style_preset": preset_key,
+        "button_icon": resolved_icon,
+        "background_color": resolved_background,
+        "text_color": resolved_text,
+    }

package/src/qingflow_mcp/builder_facade/models.py

@@ -5,6 +5,7 @@ from typing import Any
 
 from pydantic import AliasChoices, Field, model_validator
 
+from .button_style_catalog import resolve_button_style
 from ..solution.spec_models import StrictModel
 
 
@@ -1180,10 +1181,10 @@ def _is_white_button_color(value: str | None) -> bool:
 
 class CustomButtonPatch(StrictModel):
     button_text: str = Field(validation_alias=AliasChoices("button_text", "buttonText"))
-    background_color: str = Field(validation_alias=AliasChoices("background_color", "backgroundColor"))
-    text_color: str = Field(validation_alias=AliasChoices("text_color", "textColor"))
-    button_icon: str = Field(validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    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"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
     trigger_action: PublicButtonTriggerAction = Field(validation_alias=AliasChoices("trigger_action", "triggerAction"))
     trigger_link_url: str | None = Field(default=None, validation_alias=AliasChoices("trigger_link_url", "triggerLinkUrl"))
     trigger_add_data_config: CustomButtonAddDataConfigPatch | None = Field(
@@ -1204,8 +1205,29 @@ class CustomButtonPatch(StrictModel):
         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)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "CustomButtonPatch":
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=True,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.trigger_action == PublicButtonTriggerAction.link and not str(self.trigger_link_url or "").strip():
             raise ValueError("link buttons require trigger_link_url")
         if self.trigger_action == PublicButtonTriggerAction.add_data and self.trigger_add_data_config is None:
@@ -1225,7 +1247,7 @@ class ViewButtonBindingPatch(StrictModel):
     button_id: int = Field(validation_alias=AliasChoices("button_id", "buttonId", "id"))
     button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText"))
     button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    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"))
     trigger_action: str | None = Field(default=None, validation_alias=AliasChoices("trigger_action", "triggerAction"))
@@ -1244,6 +1266,8 @@ class ViewButtonBindingPatch(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
         raw_button_type = payload.get("button_type", payload.get("buttonType"))
         if isinstance(raw_button_type, str):
             normalized_type = raw_button_type.strip().lower()
@@ -1265,6 +1289,21 @@ class ViewButtonBindingPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "ViewButtonBindingPatch":
+        require_complete_style = self.button_type == PublicViewButtonType.system or any(
+            str(value or "").strip()
+            for value in (self.style_preset, self.button_icon, self.background_color, self.text_color)
+        )
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=require_complete_style,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.button_type == PublicViewButtonType.system:
             missing = [
                 field_name

package/src/qingflow_mcp/builder_facade/service.py

@@ -34,6 +34,7 @@ from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
 from ..tools.workflow_tools import WorkflowTools
+from .button_style_catalog import button_style_catalog_payload
 from .models import (
     AppChartsReadResponse,
     AppFieldsReadResponse,
@@ -2353,6 +2354,26 @@ class AiBuilderFacade:
             **match,
         }
 
+    def button_style_catalog_get(self, *, profile: str) -> JSONObject:
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read button style catalog",
+            "normalized_args": {},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"button_style_catalog_verified": True},
+            "verified": True,
+            "profile": profile,
+            **button_style_catalog_payload(),
+        }
+
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
         permission_outcomes: list[PermissionCheckOutcome] = []
@@ -8035,8 +8056,6 @@ def _serialize_custom_button_payload(payload: CustomButtonPatch) -> dict[str, An
         "buttonIcon": data["button_icon"],
         "triggerAction": data["trigger_action"],
     }
-    if str(data.get("icon_color") or "").strip():
-        serialized["iconColor"] = data["icon_color"]
     if str(data.get("trigger_link_url") or "").strip():
         serialized["triggerLinkUrl"] = data["trigger_link_url"]
     trigger_add_data_config = data.get("trigger_add_data_config")
@@ -8126,7 +8145,6 @@ def _normalize_custom_button_summary(item: dict[str, Any]) -> dict[str, Any]:
         "button_id": _coerce_positive_int(item.get("button_id") or item.get("buttonId") or item.get("id")),
         "button_text": str(item.get("button_text") or item.get("buttonText") or "").strip() or None,
         "button_icon": str(item.get("button_icon") or item.get("buttonIcon") or "").strip() or None,
-        "icon_color": str(item.get("icon_color") or item.get("iconColor") or "").strip() or None,
         "background_color": str(item.get("background_color") or item.get("backgroundColor") or "").strip() or None,
         "text_color": str(item.get("text_color") or item.get("textColor") or "").strip() or None,
         "used_in_chart_count": _coerce_nonnegative_int(item.get("used_in_chart_count") or item.get("userInChartCount")),
@@ -14887,7 +14905,6 @@ def _normalize_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
     for public_key, source_key in (
         ("default_button_text", "defaultButtonText"),
         ("button_icon", "buttonIcon"),
-        ("icon_color", "iconColor"),
         ("background_color", "backgroundColor"),
         ("text_color", "textColor"),
         ("trigger_link_url", "triggerLinkUrl"),
@@ -14925,7 +14942,6 @@ def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
                 "button_id": normalized.get("button_id") if is_custom else None,
                 "button_text": normalized.get("button_text"),
                 "button_icon": normalized.get("button_icon"),
-                "icon_color": normalized.get("icon_color"),
                 "background_color": normalized.get("background_color"),
                 "text_color": normalized.get("text_color"),
                 "trigger_action": normalized.get("trigger_action"),
@@ -15000,7 +15016,6 @@ def _normalize_expected_view_buttons_for_compare(
                 for key in (
                     "button_text",
                     "button_icon",
-                    "icon_color",
                     "background_color",
                     "text_color",
                     "trigger_action",
@@ -15183,8 +15198,6 @@ def _serialize_view_button_binding(
     if binding.button_type in {PublicViewButtonType.system, PublicViewButtonType.custom}:
         dto["buttonText"] = binding.button_text
         dto["buttonIcon"] = binding.button_icon
-        if str(binding.icon_color or "").strip():
-            dto["iconColor"] = binding.icon_color
         dto["backgroundColor"] = binding.background_color
         dto["textColor"] = binding.text_color
         dto["triggerAction"] = binding.trigger_action

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

@@ -120,6 +120,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button = builder_subparsers.add_parser("button", help="自定义按钮")
     button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
 
+    button_catalog = button_subparsers.add_parser("catalog", help="读取按钮样式目录")
+    button_catalog.set_defaults(handler=_handle_button_catalog, format_hint="builder_summary")
+
     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")
@@ -362,6 +365,10 @@ 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_catalog(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.button_style_catalog_get(profile=args.profile)
+
+
 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)
 

package/src/qingflow_mcp/public_surface.py

@@ -134,6 +134,7 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "button_style_catalog_get", ("button_style_catalog_get",), ("builder", "button", "catalog"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/response_trim.py

@@ -831,6 +831,7 @@ _register_policy(
         "role_create",
         "app_release_edit_lock_if_mine",
         "app_resolve",
+        "button_style_catalog_get",
         "app_custom_button_list",
         "app_custom_button_get",
         "app_custom_button_create",

package/src/qingflow_mcp/server_app_builder.py

@@ -290,6 +290,10 @@ def build_builder_server() -> FastMCP:
             )
         return ai_builder.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_id)
 
+    @server.tool()
+    def button_style_catalog_get(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.button_style_catalog_get(profile=profile)
+
     @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)

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -6,6 +6,12 @@ import time
 
 from pydantic import ValidationError
 
+from ..builder_facade.button_style_catalog import (
+    BUTTON_BACKGROUND_COLORS,
+    BUTTON_ICONS,
+    BUTTON_STYLE_PRESETS,
+    BUTTON_TEXT_COLORS,
+)
 from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
@@ -209,6 +215,10 @@ class AiBuilderTools(ToolBase):
                 )
             return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_id)
 
+        @mcp.tool()
+        def button_style_catalog_get(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.button_style_catalog_get(profile=profile)
+
         @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)
@@ -846,6 +856,17 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("按钮样式目录")
+    def button_style_catalog_get(self, *, profile: str) -> JSONObject:
+        """执行按钮样式相关逻辑。"""
+        normalized_args: dict[str, object] = {}
+        return _safe_tool_call(
+            lambda: self._facade.button_style_catalog_get(profile=profile),
+            error_code="BUTTON_STYLE_CATALOG_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "button_style_catalog_get", "arguments": {"profile": profile}},
+        )
+
     @tool_cn_name("应用按钮列表")
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -885,9 +906,8 @@ class AiBuilderTools(ToolBase):
                         "app_key": app_key,
                         "payload": {
                             "button_text": "新增记录",
-                            "background_color": "#FFFFFF",
-                            "text_color": "#494F57",
-                            "button_icon": "ex-add-outlined",
+                            "style_preset": "primary_blue",
+                            "button_icon": "ex-plus-circle",
                             "trigger_action": "addData",
                             "trigger_add_data_config": {"related_app_key": "TARGET_APP_KEY", "que_relation": []},
                         },
@@ -920,9 +940,8 @@ class AiBuilderTools(ToolBase):
                         "button_id": button_id,
                         "payload": {
                             "button_text": "新增记录",
-                            "background_color": "#FFFFFF",
-                            "text_color": "#494F57",
-                            "button_icon": "ex-add-outlined",
+                            "style_preset": "neutral_outline",
+                            "button_icon": "ex-edit",
                             "trigger_action": "link",
                             "trigger_link_url": "https://example.com",
                         },
@@ -2535,6 +2554,24 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "lock_owner_name": "当前用户",
         },
     },
+    "button_style_catalog_get": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {
+            "preset.key": [item["key"] for item in BUTTON_STYLE_PRESETS],
+            "icon": list(BUTTON_ICONS),
+            "background_color": list(BUTTON_BACKGROUND_COLORS),
+            "text_color": list(BUTTON_TEXT_COLORS),
+        },
+        "execution_notes": [
+            "use this read-only tool before button writes when an agent needs a supported icon or color choice",
+            "current frontend only supports template icons and template colors from this catalog",
+            "text/icon color is unified through text_color; there is no separate icon_color",
+        ],
+        "minimal_example": {
+            "profile": "default",
+        },
+    },
     "app_custom_button_list": {
         "allowed_keys": ["app_key"],
         "aliases": {},
@@ -2558,10 +2595,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_keys": ["app_key", "payload"],
         "aliases": {
             "payload.buttonText": "payload.button_text",
+            "payload.stylePreset": "payload.style_preset",
             "payload.backgroundColor": "payload.background_color",
             "payload.textColor": "payload.text_color",
             "payload.buttonIcon": "payload.button_icon",
-            "payload.iconColor": "payload.icon_color",
             "payload.triggerAction": "payload.trigger_action",
             "payload.triggerLinkUrl": "payload.trigger_link_url",
             "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
@@ -2571,10 +2608,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {
             "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
+            "payload.button_icon": list(BUTTON_ICONS),
+            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
+            "payload.text_color": list(BUTTON_TEXT_COLORS),
         },
         "execution_notes": [
             "custom button writes now auto-publish the current app draft as a fixed closing step",
             "background_color and text_color cannot both be white",
+            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
             "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
         ],
         "minimal_example": {
@@ -2582,10 +2624,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_key": "APP_KEY",
             "payload": {
                 "button_text": "新增记录",
-                "background_color": "#FFFFFF",
-                "text_color": "#494F57",
-                "button_icon": "ex-add-outlined",
-                "icon_color": "#494F57",
+                "style_preset": "primary_blue",
+                "button_icon": "ex-plus-circle",
                 "trigger_action": "link",
                 "trigger_link_url": "https://example.com",
             },
@@ -2596,10 +2636,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {
             "buttonId": "button_id",
             "payload.buttonText": "payload.button_text",
+            "payload.stylePreset": "payload.style_preset",
             "payload.backgroundColor": "payload.background_color",
             "payload.textColor": "payload.text_color",
             "payload.buttonIcon": "payload.button_icon",
-            "payload.iconColor": "payload.icon_color",
             "payload.triggerAction": "payload.trigger_action",
             "payload.triggerLinkUrl": "payload.trigger_link_url",
             "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
@@ -2609,10 +2649,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {
             "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
+            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
+            "payload.button_icon": list(BUTTON_ICONS),
+            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
+            "payload.text_color": list(BUTTON_TEXT_COLORS),
         },
         "execution_notes": [
             "custom button writes now auto-publish the current app draft as a fixed closing step",
             "background_color and text_color cannot both be white",
+            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
             "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
         ],
         "minimal_example": {
@@ -2621,10 +2666,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "button_id": 1001,
             "payload": {
                 "button_text": "查看详情",
-                "background_color": "#FFFFFF",
-                "text_color": "#494F57",
-                "button_icon": "ex-link-outlined",
-                "icon_color": "#494F57",
+                "style_preset": "neutral_outline",
+                "button_icon": "ex-edit",
                 "trigger_action": "link",
                 "trigger_link_url": "https://example.com/detail",
             },

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -169,7 +169,6 @@ class CustomButtonTools(ToolBase):
             "button_id": item.get("buttonId"),
             "button_text": item.get("buttonText"),
             "button_icon": item.get("buttonIcon"),
-            "icon_color": item.get("iconColor"),
             "background_color": item.get("backgroundColor"),
             "text_color": item.get("textColor"),
             "creator_user_info": {
@@ -189,7 +188,6 @@ class CustomButtonTools(ToolBase):
             "button_id": item.get("buttonId"),
             "button_text": item.get("buttonText"),
             "button_icon": item.get("buttonIcon"),
-            "icon_color": item.get("iconColor"),
             "background_color": item.get("backgroundColor"),
             "text_color": item.get("textColor"),
             "trigger_action": item.get("triggerAction"),

package/src/qingflow_mcp/tools/export_tools.py

@@ -11,6 +11,7 @@ from uuid import uuid4
 
 from mcp.server.fastmcp import FastMCP
 
+from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 from ..errors import QingflowApiError
 from ..export_store import ExportJobStore
@@ -213,6 +214,10 @@ class ExportTools(ToolBase):
                 {
                     "created_at": started_at,
                     "profile": profile,
+                    "base_url": context.base_url,
+                    "ws_id": context.ws_id,
+                    "qf_version": context.qf_version,
+                    "qf_version_source": context.qf_version_source,
                     "app_key": normalized_app_key,
                     "view_id": resolved_view.view_id,
                     "backend_export_id": str(socket_result.get("backend_export_id") or ""),
@@ -280,7 +285,7 @@ class ExportTools(ToolBase):
                 extra={"status": "failed"},
             )
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             local_job = self._job_store.get(normalized_handle)
             if local_job is None:
                 return self._failed_export_result(
@@ -288,7 +293,13 @@ class ExportTools(ToolBase):
                     message="export_handle is missing or expired",
                     extra={"export_handle": normalized_handle, "status": "failed"},
                 )
-            snapshot = self._resolve_export_snapshot(context, local_job)
+            lookup_context = self._build_export_lookup_context(
+                profile=profile,
+                session_profile=session_profile,
+                current_context=context,
+                local_job=local_job,
+            )
+            snapshot = self._resolve_export_snapshot(lookup_context, local_job)
             return self._status_payload_from_snapshot(local_job, normalized_handle, snapshot)
 
         try:
@@ -316,7 +327,7 @@ class ExportTools(ToolBase):
                 extra={"status": "failed"},
             )
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             local_job = self._job_store.get(normalized_handle)
             if local_job is None:
                 return self._failed_export_result(
@@ -324,7 +335,13 @@ class ExportTools(ToolBase):
                     message="export_handle is missing or expired",
                     extra={"export_handle": normalized_handle, "status": "failed"},
                 )
-            snapshot = self._resolve_export_snapshot(context, local_job)
+            lookup_context = self._build_export_lookup_context(
+                profile=profile,
+                session_profile=session_profile,
+                current_context=context,
+                local_job=local_job,
+            )
+            snapshot = self._resolve_export_snapshot(lookup_context, local_job)
             normalized_status = str(snapshot.get("status") or "unknown")
             if normalized_status not in {"succeeded", "failed"}:
                 return self._failed_export_result(
@@ -414,7 +431,7 @@ class ExportTools(ToolBase):
                 "downloaded_files": downloaded_files,
                 "warnings": snapshot.get("warnings") or [],
                 "verification": snapshot.get("verification") or {},
-                "request_route": self.backend.describe_route(context),
+                "request_route": self.backend.describe_route(lookup_context),
             }
 
         try:
@@ -451,7 +468,7 @@ class ExportTools(ToolBase):
             )
         timeout_seconds = self._normalize_timeout_seconds(wait_timeout_seconds)
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             start_result = self.record_export_start(
                 profile=profile,
                 app_key=normalized_app_key,
@@ -475,7 +492,13 @@ class ExportTools(ToolBase):
                         message="export_handle is missing or expired",
                         extra={"status": "failed", "export_handle": export_handle},
                     )
-                snapshot = self._resolve_export_snapshot(context, local_job)
+                lookup_context = self._build_export_lookup_context(
+                    profile=profile,
+                    session_profile=session_profile,
+                    current_context=context,
+                    local_job=local_job,
+                )
+                snapshot = self._resolve_export_snapshot(lookup_context, local_job)
                 last_snapshot = snapshot
                 normalized_status = str(snapshot.get("status") or "unknown")
                 if normalized_status == "succeeded":
@@ -583,6 +606,49 @@ class ExportTools(ToolBase):
                 extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
             )
 
+    def _build_export_lookup_context(
+        self,
+        *,
+        profile: str,
+        session_profile,
+        current_context: BackendRequestContext,
+        local_job: dict[str, Any],
+    ) -> BackendRequestContext:
+        stored_profile = str(local_job.get("profile") or "").strip()
+        if stored_profile and stored_profile != profile:
+            raise QingflowApiError.config_error(
+                "export_handle was created under a different profile",
+                details={
+                    "error_code": "EXPORT_HANDLE_PROFILE_MISMATCH",
+                    "expected_profile": stored_profile,
+                    "received_profile": profile,
+                },
+            )
+        stored_uid = _coerce_positive_int(local_job.get("uid"))
+        if stored_uid is not None and stored_uid != session_profile.uid:
+            raise QingflowApiError.config_error(
+                "export_handle belongs to a different authenticated user",
+                details={
+                    "error_code": "EXPORT_HANDLE_OWNER_MISMATCH",
+                    "expected_uid": stored_uid,
+                    "current_uid": session_profile.uid,
+                },
+            )
+        stored_base_url = str(local_job.get("base_url") or "").strip() or current_context.base_url
+        stored_ws_id = _coerce_positive_int(local_job.get("ws_id"))
+        stored_qf_version = str(local_job.get("qf_version") or "").strip() or current_context.qf_version
+        stored_qf_version_source = (
+            str(local_job.get("qf_version_source") or "").strip() or current_context.qf_version_source
+        )
+        return BackendRequestContext(
+            base_url=stored_base_url,
+            token=current_context.token,
+            ws_id=stored_ws_id if stored_ws_id is not None else current_context.ws_id,
+            qf_request_id=current_context.qf_request_id,
+            qf_version=stored_qf_version,
+            qf_version_source=stored_qf_version_source,
+        )
+
     def _resolve_export_record_scope(
         self,
         *,

package/src/qingflow_mcp/tools/record_tools.py

@@ -2920,12 +2920,14 @@ class RecordTools(ToolBase):
             payload["category"] = error.category
         if error.backend_code is not None:
             payload["backend_code"] = error.backend_code
+        if error.request_id is not None:
+            payload["request_id"] = error.request_id
         if error.http_status is not None:
             payload["http_status"] = error.http_status
         return payload
 
     def _is_record_context_route_miss(self, error: QingflowApiError) -> bool:
-        if error.backend_code in {40002, 40027, 40038, 404}:
+        if error.backend_code in {40002, 40023, 40027, 40038, 404}:
             return True
         if error.http_status == 404:
             return True
@@ -3059,6 +3061,107 @@ class RecordTools(ToolBase):
             f"({get_record_list_type_label(used_list_type)})."
         ]
 
+    def _looks_like_generic_record_update_backend_failure(self, exc: QingflowApiError) -> bool:
+        if exc.backend_code == 500:
+            return True
+        if exc.http_status is not None and exc.http_status >= 500:
+            return True
+        normalized_message = exc.message.strip().lower()
+        return normalized_message in {"unknown error", "internal server error"}
+
+    def _remap_record_update_target_context_error(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        exc: QingflowApiError,
+    ) -> None:
+        if not self._looks_like_generic_record_update_backend_failure(exc):
+            return
+        try:
+            candidate_routes = self._candidate_update_views(profile, context, app_key)
+            probes = self._probe_candidate_record_contexts(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                candidate_routes=candidate_routes,
+            )
+        except (QingflowApiError, RuntimeError):
+            return
+        if not probes or any(probe.readable for probe in probes):
+            return
+
+        blocker = (
+            "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            if all(probe.transport_error for probe in probes)
+            else "NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"
+        )
+        recommended_next_actions = (
+            [
+                "Retry after the record becomes readable in the current workspace/profile context.",
+                "If the issue persists, verify that the current profile still has read access to this record.",
+            ]
+            if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            else [
+                "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                "Call record_update_schema_get to inspect whether any accessible view still matches this record.",
+            ]
+        )
+        first_error_payload = next(
+            (
+                cast(JSONObject, probe.error_payload)
+                for probe in probes
+                if isinstance(probe.error_payload, dict)
+            ),
+            None,
+        )
+        backend_code = (
+            cast(int, first_error_payload.get("backend_code"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("backend_code"), int)
+            else exc.backend_code
+        )
+        request_id = (
+            _normalize_optional_text(first_error_payload.get("request_id"))
+            if isinstance(first_error_payload, dict)
+            else None
+        ) or exc.request_id
+        http_status = (
+            cast(int, first_error_payload.get("http_status"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("http_status"), int)
+            else exc.http_status
+        )
+        raise_tool_error(
+            QingflowApiError(
+                category="backend",
+                message=(
+                    "Direct record edit was blocked because the current record context could not be loaded from any candidate route."
+                    if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+                    else "Direct record edit was blocked because the target record is no longer accessible in any readable view for the current profile."
+                ),
+                backend_code=backend_code,
+                request_id=request_id,
+                http_status=http_status,
+                details={
+                    "error_code": blocker,
+                    "operation": "update",
+                    "app_key": app_key,
+                    "record_id": apply_id,
+                    "blockers": [blocker],
+                    "request_route": self._request_route_payload(context),
+                    "view_probe_summary": [
+                        self._record_context_probe_summary_payload(probe)
+                        for probe in probes
+                    ],
+                    "recommended_next_actions": recommended_next_actions,
+                    "fix_hint": (
+                        "Confirm the target record still exists and remains visible in at least one accessible view before retrying the update."
+                    ),
+                },
+            )
+        )
+
     def _record_matches_accessible_view(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -6355,12 +6458,22 @@ class RecordTools(ToolBase):
                 force_refresh_form=force_refresh_form,
             )
             self._validate_record_write(app_key, normalized_answers, apply_id=normalized_apply_id)
-            result = self.backend.request(
-                "POST",
-                context,
-                f"/app/{app_key}/apply/{normalized_apply_id}",
-                json_body={"role": role, "answers": normalized_answers},
-            )
+            try:
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/app/{app_key}/apply/{normalized_apply_id}",
+                    json_body={"role": role, "answers": normalized_answers},
+                )
+            except QingflowApiError as exc:
+                self._remap_record_update_target_context_error(
+                    profile,
+                    context,
+                    app_key=app_key,
+                    apply_id=normalized_apply_id,
+                    exc=exc,
+                )
+                raise
             verification = self._verify_record_write_result(
                 context,
                 app_key=app_key,
@@ -8810,6 +8923,8 @@ class RecordTools(ToolBase):
                     error_payload["request_id"] = parsed.get("request_id")
                 if isinstance(parsed.get("request_route"), dict):
                     request_route = cast(JSONObject, parsed.get("request_route"))
+                elif details_payload is not None and isinstance(details_payload.get("request_route"), dict):
+                    request_route = cast(JSONObject, details_payload.get("request_route"))
         response: JSONObject = {
             "profile": profile,
             "ws_id": None,

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -96,7 +96,9 @@ class ResourceReadTools(ToolBase):
                 )
             )
         if system_view is not None:
-            export_capability = _view_export_capability_payload(supported=True)
+            export_capability = _view_export_capability_payload(
+                supported=_export_supported_for_view_type(system_view["view_type"])
+            )
             return self._run(
                 profile,
                 lambda session_profile, _context: {
@@ -133,13 +135,11 @@ class ResourceReadTools(ToolBase):
             )
 
         def runner(session_profile, context):
-            export_capability = _view_export_capability_payload(supported=True)
+            raw_view_type = None
             warnings: list[JSONObject] = []
             verification = {
                 "view_exists": True,
                 "questions_verified": True,
-                "export_route_supported": export_capability["supported"],
-                "export_permission_verified": export_capability["permission_verified"],
             }
             config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
             base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
@@ -161,6 +161,11 @@ class ResourceReadTools(ToolBase):
                 str(base_info.get("viewgraphType") or "").strip()
                 or str(config.get("viewgraphType") or config.get("viewType") or "").strip()
             )
+            export_capability = _view_export_capability_payload(
+                supported=_export_supported_for_view_type(raw_view_type or None)
+            )
+            verification["export_route_supported"] = export_capability["supported"]
+            verification["export_permission_verified"] = export_capability["permission_verified"]
             resolved_app_key = str(base_info.get("appKey") or config.get("appKey") or "").strip() or None
             if not resolved_app_key:
                 resolved_app_key = self._resolve_app_key_from_view_form(context=context, view_key=view_key)
@@ -176,12 +181,13 @@ class ResourceReadTools(ToolBase):
                         "message": f"view_get could not resolve app_key for `{view_id}` from view metadata; keep using the app_key from the parent app or portal context.",
                     }
                 )
-                warnings.append(
-                    {
-                        "code": "VIEW_EXPORT_APP_CONTEXT_REQUIRED",
-                        "message": f"view_get supports exporting `{view_id}`, but the export call still needs an explicit `app_key` from the parent app context.",
-                    }
-                )
+                if export_capability["supported"]:
+                    warnings.append(
+                        {
+                            "code": "VIEW_EXPORT_APP_CONTEXT_REQUIRED",
+                            "message": f"view_get supports exporting `{view_id}`, but the export call still needs an explicit `app_key` from the parent app context.",
+                        }
+                    )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -493,6 +499,10 @@ def _view_export_capability_payload(*, supported: bool) -> JSONObject:
     }
 
 
+def _export_supported_for_view_type(view_type: str | None) -> bool:
+    return _analysis_supported_for_view_type(view_type)
+
+
 def _normalize_view_type(view_type: Any) -> str | None:
     value = str(view_type or "").strip()
     if not value: