@qingflow-tech/qingflow-app-user-mcp 1.0.3 → 1.0.4

package/src/qingflow_mcp/public_surface.py

@@ -91,6 +91,10 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_import_repair_local", ("record_import_repair_local",), ("import", "repair")),
     PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start")),
     PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status")),
+    PublicToolSpec(USER_DOMAIN, "record_export_start", ("record_export_start",), ("export", "start"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_status_get", ("record_export_status_get",), ("export", "status"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_get", ("record_export_get",), ("export", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_direct", ("record_export_direct",), ("export", "direct"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
@@ -130,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

@@ -666,7 +666,6 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
         "total_rows",
         "success_rows",
         "failed_rows",
-        "error_file_urls",
         "operate_time",
         "operate_user",
         "verification",
@@ -674,6 +673,10 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
         payload.pop(key, None)
 
 
+def _trim_export_payload(payload: JSONObject) -> None:
+    payload.pop("backend_export_id", None)
+
+
 def _summarize_import_issues(issues: list[Any]) -> dict[str, Any]:
     total = 0
     error_count = 0
@@ -756,6 +759,16 @@ _register_policy(
     ),
     _trim_import_schema,
 )
+_register_policy(
+    (USER_DOMAIN,),
+    (
+        "record_export_start",
+        "record_export_status_get",
+        "record_export_get",
+        "record_export_direct",
+    ),
+    _trim_export_payload,
+)
 _register_policy(
     (USER_DOMAIN,),
     (
@@ -818,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.py

@@ -10,6 +10,7 @@ from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.feedback_tools import FeedbackTools
+from .tools.export_tools import ExportTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
 from .tools.package_tools import PackageTools
@@ -50,6 +51,7 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
 If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+`view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
 ## Schema-First Rule
 
@@ -147,6 +149,25 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - Do not modify user-uploaded files unless the user explicitly authorizes repair.
 - If repair is authorized, keep the original file and repair a copy, then run `record_import_verify` again before `record_import_start`.
 
+## Export Path
+
+`view_get -> record_export_start -> record_export_status_get -> record_export_get`
+
+- `record_export_direct` is the one-shot export path that starts the export, waits for completion, downloads locally, and still returns remote download links.
+- Export v1 supports record views only and follows the same public `view_id` semantics as `record_list` (`system:*` and `custom:*`).
+- `record_export_start` / `record_export_direct` support frontend-like row selection:
+  - omit `record_ids` to export all rows in the selected view
+  - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support internal query selection:
+  - pass `where` to resolve matching `record_id` values first
+  - pass `order_by` to keep the internal query and export row order aligned with `record_list`
+  - then run native export as selected rows
+  - `where/order_by` and `record_ids` are mutually exclusive
+- `record_export_start` / `record_export_direct` also support frontend-like column selection:
+  - omit `columns` to export all current-view fields
+  - pass `columns` to export only selected fields, preserving the provided order
+- `include_workflow_log=true` maps to the native workflow-log export switch.
+
 ## Task Workflow Path
 
 `task_list -> task_get -> task_action_execute`
@@ -190,6 +211,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     ImportTools(sessions, backend).register(server)
+    ExportTools(sessions, backend).register(server)
     CodeBlockTools(sessions, backend).register(server)
     TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)

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/server_app_user.py

@@ -13,6 +13,7 @@ from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.directory_tools import DirectoryTools
+from .tools.export_tools import ExportTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
@@ -33,6 +34,7 @@ def build_user_server() -> FastMCP:
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
 If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+`view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
 ## Shared Helper
 
@@ -142,6 +144,25 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - Do not modify user-uploaded files unless the user explicitly authorizes repair.
 - If repair is authorized, keep the original file and repair a copy, then run `record_import_verify` again before `record_import_start`.
 
+## Export Path
+
+`view_get -> record_export_start -> record_export_status_get -> record_export_get`
+
+- `record_export_direct` is the one-shot path that starts export, waits, downloads locally, and still returns remote download links.
+- Export v1 supports record views only and follows the same public `view_id` semantics as `record_list`.
+- `record_export_start` / `record_export_direct` support frontend-like row selection:
+  - omit `record_ids` to export all rows in the selected view
+  - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support internal query selection:
+  - pass `where` to resolve matching `record_id` values first
+  - pass `order_by` to keep the internal query and export row order aligned with `record_list`
+  - then run native export as selected rows
+  - `where/order_by` and `record_ids` are mutually exclusive
+- `record_export_start` / `record_export_direct` also support frontend-like column selection:
+  - omit `columns` to export all current-view fields
+  - pass `columns` to export only selected fields, preserving the provided order
+- `include_workflow_log=true` maps to the native workflow-log export switch.
+
 ## Task Workflow Path
 
 `task_list -> task_get -> task_action_execute`
@@ -188,6 +209,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), USER_SERVER_METHOD_MAP)
     file_tools = wrap_trimmed_methods(FileTools(sessions, backend), USER_SERVER_METHOD_MAP)
     imports = wrap_trimmed_methods(ImportTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    exports = wrap_trimmed_methods(ExportTools(sessions, backend), USER_SERVER_METHOD_MAP)
     resources = wrap_trimmed_methods(ResourceReadTools(sessions, backend), USER_SERVER_METHOD_MAP)
     feedback = FeedbackTools(backend, mcp_side="App User MCP")
     code_block_tools = wrap_trimmed_methods(CodeBlockTools(sessions, backend), USER_SERVER_METHOD_MAP)
@@ -218,6 +240,73 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
         return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
 
+    @server.tool()
+    def record_export_start(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
+        order_by: list[dict] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
+    ) -> dict:
+        return exports.record_export_start(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            columns=columns or [],
+            where=where or [],
+            order_by=order_by or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
+        )
+
+    @server.tool()
+    def record_export_status_get(
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str = "",
+    ) -> dict:
+        return exports.record_export_status_get(profile=profile, export_handle=export_handle)
+
+    @server.tool()
+    def record_export_get(
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str = "",
+        download_to_path: str | None = None,
+    ) -> dict:
+        return exports.record_export_get(
+            profile=profile,
+            export_handle=export_handle,
+            download_to_path=download_to_path,
+        )
+
+    @server.tool()
+    def record_export_direct(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
+        order_by: list[dict] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
+        download_to_path: str | None = None,
+        wait_timeout_seconds: float | None = None,
+    ) -> dict:
+        return exports.record_export_direct(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            columns=columns or [],
+            where=where or [],
+            order_by=order_by or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
+            download_to_path=download_to_path,
+            wait_timeout_seconds=wait_timeout_seconds,
+        )
+
     @server.tool()
     def workspace_list(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/session_store.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import json
 import os
+from collections.abc import Callable
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 try:
@@ -82,6 +83,11 @@ class SessionStore:
         self._keyring = keyring_backend if keyring_backend is not None else keyring
         self._memory_sessions: dict[str, BackendSession] = {}
         self._logged_out_profiles: set[str] = set()
+        self._profile_refresher: Callable[[str, SessionProfile | None], bool] | None = None
+        self._refreshing_profiles: set[str] = set()
+
+    def set_profile_refresher(self, refresher: Callable[[str, SessionProfile | None], bool] | None) -> None:
+        self._profile_refresher = refresher
 
     def save_session(
         self,
@@ -148,9 +154,14 @@ class SessionStore:
     def get_profile(self, profile: str) -> SessionProfile | None:
         payload = self._load_profiles()
         raw_profile = payload.get("profiles", {}).get(profile)
-        if not raw_profile:
-            return None
-        return SessionProfile.from_dict(raw_profile)
+        session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
+        if profile in self._refreshing_profiles:
+            return session_profile
+        if self._should_refresh_profile(payload, session_profile) and self._refresh_profile(profile, session_profile):
+            payload = self._load_profiles()
+            raw_profile = payload.get("profiles", {}).get(profile)
+            session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
+        return session_profile
 
     def get_backend_session(self, profile: str) -> BackendSession | None:
         if profile in self._logged_out_profiles:
@@ -283,8 +294,48 @@ class SessionStore:
     def _load_profiles(self) -> JSONObject:
         if not self._profiles_path.exists():
             return {"profiles": {}}
-        with self._profiles_path.open("r", encoding="utf-8") as handle:
-            return json.load(handle)
+        try:
+            with self._profiles_path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            return {"profiles": {}}
+        if not isinstance(payload, dict):
+            return {"profiles": {}}
+        profiles = payload.get("profiles")
+        if not isinstance(profiles, dict):
+            payload["profiles"] = {}
+        return payload
+
+    def _should_refresh_profile(self, payload: JSONObject, session_profile: SessionProfile | None) -> bool:
+        if self._profile_refresher is None:
+            return False
+        profiles = payload.get("profiles")
+        if not isinstance(profiles, dict) or not profiles:
+            return True
+        if session_profile is None:
+            return True
+        return self._is_profile_stale(session_profile)
+
+    def _refresh_profile(self, profile: str, session_profile: SessionProfile | None) -> bool:
+        if self._profile_refresher is None:
+            return False
+        self._refreshing_profiles.add(profile)
+        try:
+            return bool(self._profile_refresher(profile, session_profile))
+        except Exception:
+            return False
+        finally:
+            self._refreshing_profiles.discard(profile)
+
+    def _is_profile_stale(self, session_profile: SessionProfile) -> bool:
+        timestamp_text = session_profile.updated_at or session_profile.created_at
+        try:
+            timestamp = datetime.fromisoformat(timestamp_text)
+        except (TypeError, ValueError):
+            return True
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.replace(tzinfo=timezone.utc)
+        return datetime.now(timezone.utc) - timestamp > timedelta(days=7)
 
     def _save_profiles(self, payload: JSONObject) -> None:
         self._profiles_path.parent.mkdir(parents=True, exist_ok=True)

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/auth_tools.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 from typing import Any
+import os
 
 from mcp.server.fastmcp import FastMCP
 
@@ -30,6 +31,7 @@ class AuthTools(ToolBase):
     def __init__(self, sessions: SessionStore, backend) -> None:
         """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
+        self.sessions.set_profile_refresher(self._refresh_profile_via_credential)
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
@@ -314,8 +316,12 @@ class AuthTools(ToolBase):
         mcporter_context = self._read_mcporter_qingflow_context()
         if not normalized_base_url:
             normalized_base_url = self._normalize_text(mcporter_context.get("base_url"))
+        if not normalized_base_url:
+            normalized_base_url = os.getenv("QINGFLOW_BASE_URL")
         if not normalized_credential:
             normalized_credential = self._normalize_text(mcporter_context.get("credential"))
+        if not normalized_credential:
+            normalized_credential = os.getenv("QINGFLOW_CREDENTIAL")
         return normalized_base_url, normalized_credential or ""
 
     def _read_mcporter_qingflow_context(self) -> dict[str, str]:
@@ -344,6 +350,26 @@ class AuthTools(ToolBase):
             "credential": str(credential or "").strip(),
         }
 
+    def _refresh_profile_via_credential(
+        self,
+        profile: str,
+        session_profile,
+    ) -> bool:
+        backend_session = self.sessions.get_backend_session(profile) if session_profile is not None else None
+        base_url = session_profile.base_url if session_profile is not None else None
+        credential = backend_session.credential if backend_session is not None else None
+        persist = bool(session_profile.persisted) if session_profile is not None else False
+        try:
+            self.auth_use_credential(
+                profile=profile,
+                base_url=base_url,
+                credential=credential,
+                persist=persist,
+            )
+        except (QingflowApiError, RuntimeError):
+            return False
+        return True
+
     @tool_cn_name("我的身份")
     def auth_whoami(self, *, profile: str = DEFAULT_PROFILE) -> dict[str, Any]:
         """执行认证与会话相关逻辑。"""

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"),