@qingflow-tech/qingflow-app-builder-mcp 1.0.3 → 1.0.5

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
@@ -32,7 +33,8 @@ 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.
+If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access 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
 
@@ -47,7 +49,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 Call `record_insert_schema_get` before `record_insert`.
 Call `record_update_schema_get` before `record_update`.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -58,7 +60,9 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
 Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
 `record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
-`record_browse_schema_get(view_id=...)` returns browse-schema fields for the selected accessible view.
+`record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
+`record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema; a missing field means it is not readable in that view.
+`searchQueIds` is a backend full-text search scope, not an output-column/projection mechanism.
 `record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
 `record_import_schema_get` returns import-ready column metadata.
 
@@ -68,16 +72,19 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 
 ## Analytics Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_analyze`
+`app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python`
 
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
-Use this DSL shape:
+Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`. CSV columns are readable and field-id anchored, such as `项目状态__field_343283094`, and `fields[]` is the compact metadata source.
+For analysis-style tasks, prefer an explicit time range or business filter. If `record_access.status == "needs_scope"`, do not treat it as a failure; ask for a time/business scope or retry with a user-provided period using `scope.suggested_time_fields` / `scope.recommended_where_examples`. If `record_access.status == "partial"`, read the returned files only as a limited subset and do not give a final full-population conclusion.
+Use `chart_get` only when the user provides a report URL / chart_id or explicitly asks to read an existing report. Do not use QingBI as the default analysis route.
 
-- `dimensions`: `{{field_id, alias, bucket}}`
-- `metrics`: `{{op, field_id, alias}}`
-- `filters`: `{{field_id, op, value}}`
-- `sort`: `{{by, order}}`
+Use this data-access DSL shape:
+
+- `columns`: `[{{field_id}}]`
+- `where`: `[{{field_id, op, value}}]`
+- `order_by`: `[{{field_id, direction}}]`
 
 Important key rules:
 
@@ -87,6 +94,10 @@ Important key rules:
 - Do **not** use `aggregation`
 - Do **not** use `operator`
 
+`record_list` is for browsing and sample checks, not final analysis conclusions.
+For fuzzy single-record lookup, use `record_list(query=..., query_fields=[{{field_id}}])` to find candidates, read `lookup.next_action`, and only call `record_get` after one candidate is clear.
+`record_list.query_fields` maps to backend full-text search scope (`searchQueIds`); `record_list.columns` only controls displayed fields.
+
 Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
 
 ## Record CRUD Path
@@ -100,6 +111,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `portal_get -> view_get -> record_list`
 
 - Use `columns` as `[{{field_id}}]`
+- Use `query` plus optional `query_fields` when the user provides fuzzy record-identifying text
 - Use `where` items as `{{field_id, op, value}}`
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
@@ -113,7 +125,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
 - `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
 - `record_delete` deletes by `record_id` or `record_ids`.
-- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+- `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
+- When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
@@ -142,6 +157,28 @@ 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
+
+Use export only when the user explicitly asks to export/download/generate an Excel or export file.
+
+`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.
+- Do not use `record_export_direct` as the default analysis path; use `record_access -> Python` instead.
+- 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 +225,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 +256,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"),