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

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",
                         },
@@ -1873,7 +1892,7 @@ class AiBuilderTools(ToolBase):
         dash_name: str = "",
         package_id: int | None = None,
         publish: bool = True,
-        sections: list[JSONObject],
+        sections: list[JSONObject] | None = None,
         visibility: JSONObject | None = None,
         auth: JSONObject | None = None,
         icon: str | None = None,
@@ -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",
             },
@@ -2665,6 +2708,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.autoTrigger": "field.auto_trigger",
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
+            "field.subfieldUpdates": "field.subfield_updates",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2730,6 +2774,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.autoTrigger": "field.auto_trigger",
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
+            "field.subfieldUpdates": "field.subfield_updates",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2751,6 +2796,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
             "relation fields now require both display_field and visible_fields in MCP/CLI payloads",
             "if relation target metadata lookup is blocked by 40161/40002/40027, explicit display_field.name and visible_fields[].name let builder degrade verification and still continue schema write",
+            "update_fields[].set.subfield_updates is the safe patch path for editing existing subtable child fields without rebuilding the entire subtable",
+            "subfield_updates only supports safe child overlays: name, required, description, and nested subfield_updates",
+            "set.subfields remains the full replace/rebuild path for a subtable and is higher risk when hidden relation/reference children exist",
             "department fields accept department_scope with mode=all or mode=custom; custom scope requires explicit departments[].dept_id and optional include_sub_departs",
             "q_linker_binding lets you declare request config, dynamic inputs, alias parsing, and target-field bindings in one step; builder writes remoteLookupConfig plus the existing backend relation-default and questionRelations structures",
             "code_block_binding lets you declare inputs, code, alias parsing, and target-field bindings in one step; builder writes codeBlockConfig plus the existing backend relation-default and questionRelations structures",
@@ -2798,6 +2846,26 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "update_fields": [],
             "remove_fields": [],
         },
+        "subfield_update_example": {
+            "profile": "default",
+            "app_key": "APP_REWARD",
+            "publish": True,
+            "add_fields": [],
+            "update_fields": [
+                {
+                    "selector": {"que_id": 441305044},
+                    "set": {
+                        "subfield_updates": [
+                            {
+                                "selector": {"que_id": 441305045},
+                                "set": {"name": "景品名"},
+                            }
+                        ]
+                    },
+                }
+            ],
+            "remove_fields": [],
+        },
         "department_scope_example": {
             "profile": "default",
             "app_key": "APP_LEAD",
@@ -3149,7 +3217,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns builder-side app configuration summary and editability",
             "use this as the default builder discovery read before fields/layout/views/flow/charts detail reads",
-            "editability reflects builder permissions, not end-user data visibility",
+            "editability is route-aware builder capability summary, not end-user data visibility",
+            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility",
+            "can_edit_form covers form/schema routes only and does not imply app base-info writes",
             "returns normalized app visibility when backend auth is readable",
         ],
         "minimal_example": {
@@ -3164,6 +3234,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns compact current field configuration for one app",
             "use this before app_schema_apply when you need exact field definitions",
+            "subtable fields include nested subfields using the same compact field shape",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3269,14 +3340,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "chart.filter.operator": [member.value for member in ViewFilterOperator],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
-        "execution_notes": [
-            "app_charts_apply is immediate-live and does not publish",
-            "chart matching precedence is chart_id first, then exact unique chart name",
-            "when chart names are not unique, supply chart_id instead of guessing by name",
-            "successful create results must return a real backend chart_id",
-            "upsert_charts[].visibility compiles to QingBI visibleAuth; omit it on updates to preserve the existing visibleAuth",
-            *_VISIBILITY_EXECUTION_NOTES,
-        ],
+            "execution_notes": [
+                "app_charts_apply is immediate-live and does not publish",
+                "chart matching precedence is chart_id first, then exact unique chart name",
+                "when chart names are not unique, supply chart_id instead of guessing by name",
+                "successful create results must return a real backend chart_id",
+                "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
+                "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
+                *_VISIBILITY_EXECUTION_NOTES,
+            ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3332,14 +3404,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "dashStyleConfigBO": "dash_style_config",
         },
         "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
-        "execution_notes": [
-            "use exactly one resource mode",
-            "update mode: dash_key",
-            "create mode: package_id + dash_name",
-            "portal_apply uses replace semantics for sections",
-            "remove a section by omitting it from the new sections list",
-            "package_id is required when creating a new portal",
-            "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
+            "execution_notes": [
+                "use exactly one resource mode",
+                "update mode: dash_key",
+                "create mode: package_id + dash_name",
+                "portal_apply uses replace semantics for sections",
+                "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
+                "remove a section by omitting it from the new sections list",
+                "package_id is required when creating a new portal",
+                "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
             "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
             "position.pc/mobile is the canonical portal layout shape",

package/src/qingflow_mcp/tools/app_tools.py

@@ -729,6 +729,7 @@ class AppTools(ToolBase):
         tag_ids = item.get("tagIds") if isinstance(item.get("tagIds"), list) else []
         compact = {
             "app_key": app_key,
+            "app_name": title,
             "title": title,
             "form_id": item.get("formId"),
             "tag_id": package_tag_id,

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 服务。"""
@@ -93,7 +95,7 @@ class AuthTools(ToolBase):
         if not normalized_credential:
             raise_tool_error(
                 QingflowApiError.config_error(
-                    "credential is required or configure /root/.openclaw/workspace/config/mcporter.json "
+                    "credential is required or configure ~/.openclaw/workspace/config/mcporter.json "
                     "with mcpServers.qingflow.headers.x-qingflow-client-id"
                 )
             )
@@ -164,6 +166,146 @@ class AuthTools(ToolBase):
             ),
         }
 
+    def auth_use_token(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        token: str | None = None,
+        login_token: str | None = None,
+        persist: bool = False,
+        user_info: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """使用已获得的 Qingflow token 建立本地会话。"""
+        normalized_base_url = self._normalize_base_url(base_url)
+        normalized_qf_version, qf_version_source = self._resolve_qf_version_input(qf_version)
+        normalized_token = self._normalize_text(token)
+        normalized_login_token = self._normalize_text(login_token)
+        if not normalized_token:
+            raise_tool_error(QingflowApiError.config_error("token is required"))
+
+        resolved_user_info = user_info if isinstance(user_info, dict) else None
+        response_qf_version: str | None = None
+        if resolved_user_info is None:
+            resolved_user_info, response_qf_version = self._fetch_user_info(
+                normalized_base_url,
+                normalized_token,
+                None,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+
+        last_workspace = resolved_user_info.get("lastWsInfo")
+        selected_ws_id = self._coerce_positive_int(
+            last_workspace.get("wsId") if isinstance(last_workspace, dict) else None
+        )
+        selected_ws_name = self._normalize_text(
+            (last_workspace.get("wsName") if isinstance(last_workspace, dict) else None)
+            or (last_workspace.get("workspaceName") if isinstance(last_workspace, dict) else None)
+            or (last_workspace.get("remark") if isinstance(last_workspace, dict) else None)
+        )
+        workspace_qf_version = (
+            self._workspace_system_version(last_workspace) if isinstance(last_workspace, dict) else None
+        )
+        if selected_ws_id is None:
+            fallback_workspace, fallback_qf_version = self._fetch_first_workspace(
+                normalized_base_url,
+                normalized_token,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+            if isinstance(fallback_workspace, dict):
+                selected_ws_id = self._coerce_positive_int(fallback_workspace.get("wsId"))
+                selected_ws_name = self._normalize_text(
+                    fallback_workspace.get("workspaceName")
+                    or fallback_workspace.get("wsName")
+                    or fallback_workspace.get("remark")
+                ) or selected_ws_name
+                workspace_qf_version = self._workspace_system_version(fallback_workspace) or fallback_qf_version
+        elif selected_ws_name is None or workspace_qf_version is None:
+            workspace = self._fetch_workspace_with_name_fallback(
+                normalized_base_url,
+                normalized_token,
+                selected_ws_id,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+            if isinstance(workspace, dict):
+                selected_ws_name = self._normalize_text(
+                    workspace.get("workspaceName")
+                    or workspace.get("wsName")
+                    or workspace.get("remark")
+                ) or selected_ws_name
+                workspace_qf_version = self._workspace_system_version(workspace) or workspace_qf_version
+
+        if workspace_qf_version is not None:
+            resolved_qf_version, resolved_qf_version_source = workspace_qf_version, "workspace_system_version"
+        else:
+            resolved_qf_version, resolved_qf_version_source = self._resolve_backend_qf_version(
+                response_qf_version,
+                fallback_qf_version=normalized_qf_version,
+                fallback_source=qf_version_source,
+            )
+
+        uid = self._coerce_positive_int(resolved_user_info.get("uid"))
+        if uid is None:
+            raise_tool_error(QingflowApiError(category="auth", message="Token validation did not return valid user info"))
+
+        session_profile = self.sessions.save_session(
+            profile=profile,
+            base_url=normalized_base_url,
+            qf_version=resolved_qf_version,
+            qf_version_source=resolved_qf_version_source,
+            token=normalized_token,
+            login_token=normalized_login_token,
+            credential=None,
+            uid=uid,
+            email=self._normalize_text(resolved_user_info.get("email")),
+            nick_name=self._normalize_text(
+                resolved_user_info.get("nickName")
+                or resolved_user_info.get("displayName")
+                or resolved_user_info.get("name")
+            ),
+            persist=persist,
+        )
+        if selected_ws_id is not None:
+            session_profile = self.sessions.select_workspace(profile, ws_id=selected_ws_id, ws_name=selected_ws_name)
+        backend_session = self.sessions.get_backend_session(profile)
+        permission_level = (
+            self._workspace_permission_level(
+                session_profile=session_profile,
+                backend_session=backend_session,
+            )
+            if backend_session is not None
+            else None
+        )
+
+        return {
+            "profile": session_profile.profile,
+            "base_url": session_profile.base_url,
+            "qf_version": session_profile.qf_version,
+            "qf_version_source": session_profile.qf_version_source,
+            "uid": session_profile.uid,
+            "email": session_profile.email,
+            "nick_name": session_profile.nick_name,
+            "selected_ws_id": session_profile.selected_ws_id,
+            "selected_ws_name": session_profile.selected_ws_name,
+            "suggested_ws_id": session_profile.selected_ws_id,
+            "suggested_ws_name": session_profile.selected_ws_name,
+            "permission_level": permission_level,
+            "persisted": session_profile.persisted,
+            "request_route": self._request_route_payload(
+                BackendRequestContext(
+                    base_url=session_profile.base_url,
+                    token=normalized_token,
+                    ws_id=session_profile.selected_ws_id,
+                    qf_version=session_profile.qf_version,
+                    qf_version_source=session_profile.qf_version_source,
+                )
+            ),
+        }
+
     def _resolve_mcporter_auth_inputs(self, *, base_url: str | None, credential: str | None) -> tuple[str | None, str]:
         """从参数或 mcporter 配置解析登录所需 base_url 与 credential。"""
         normalized_base_url = self._normalize_text(base_url)
@@ -174,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]:
@@ -204,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]:
         """执行认证与会话相关逻辑。"""
@@ -212,6 +378,36 @@ class AuthTools(ToolBase):
             backend_session,  # type: ignore[no-untyped-def]
             context: BackendRequestContext,
         ) -> dict[str, Any]:
+            workspace, workspace_qf_version = self._selected_workspace_snapshot(
+                session_profile=session_profile,
+                backend_session=backend_session,
+            )
+            resolved_qf_version = workspace_qf_version or session_profile.qf_version
+            resolved_qf_version_source = (
+                "workspace_system_version"
+                if workspace_qf_version is not None
+                else session_profile.qf_version_source
+            )
+            if (
+                workspace_qf_version is not None
+                and (
+                    workspace_qf_version != session_profile.qf_version
+                    or session_profile.qf_version_source != "workspace_system_version"
+                )
+            ):
+                session_profile = self.sessions.update_route(
+                    profile,
+                    qf_version=workspace_qf_version,
+                    qf_version_source="workspace_system_version",
+                )
+                backend_session = self.sessions.get_backend_session(profile) or backend_session
+                context = BackendRequestContext(
+                    base_url=backend_session.base_url,
+                    token=backend_session.token,
+                    ws_id=session_profile.selected_ws_id,
+                    qf_version=backend_session.qf_version,
+                    qf_version_source=backend_session.qf_version_source,
+                )
             if self._should_refresh_identity_metadata(session_profile):
                 refreshed_profile = self._refresh_identity_metadata(
                     profile=profile,
@@ -224,8 +420,8 @@ class AuthTools(ToolBase):
             response = {
                 "profile": session_profile.profile,
                 "base_url": session_profile.base_url,
-                "qf_version": session_profile.qf_version,
-                "qf_version_source": session_profile.qf_version_source,
+                "qf_version": resolved_qf_version,
+                "qf_version_source": resolved_qf_version_source,
                 "uid": session_profile.uid,
                 "email": session_profile.email,
                 "nick_name": session_profile.nick_name,
@@ -512,6 +708,24 @@ class AuthTools(ToolBase):
             raise_tool_error(QingflowApiError(category="workspace", message=f"Workspace {ws_id} is not accessible"))
         return workspace
 
+    def _selected_workspace_snapshot(
+        self,
+        *,
+        session_profile,  # type: ignore[no-untyped-def]
+        backend_session,  # type: ignore[no-untyped-def]
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        ws_id = session_profile.selected_ws_id
+        if ws_id is None:
+            return None, None
+        workspace = self._fetch_workspace_with_name_fallback(
+            session_profile.base_url,
+            backend_session.token,
+            ws_id,
+            qf_version=session_profile.qf_version,
+            qf_version_source=session_profile.qf_version_source,
+        )
+        return workspace, self._workspace_system_version(workspace)
+
     def _request_route_payload(self, context: BackendRequestContext) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
@@ -603,6 +817,13 @@ class AuthTools(ToolBase):
         if ws_id is None:
             return default_payload, []
 
+        permission_level = self._workspace_permission_level(
+            session_profile=session_profile,
+            backend_session=backend_session,
+        )
+        payload = dict(default_payload)
+        payload["permission_level"] = permission_level
+
         context = BackendRequestContext(
             base_url=backend_session.base_url,
             token=backend_session.token,
@@ -610,12 +831,6 @@ class AuthTools(ToolBase):
             qf_version=backend_session.qf_version,
             qf_version_source=backend_session.qf_version_source,
         )
-        permission_level = self._resolve_permission_level(
-            self._workspace_auth(context, ws_id=ws_id)
-        )
-        payload = dict(default_payload)
-        payload["permission_level"] = permission_level
-
         member = self._lookup_current_member(
             context=context,
             uid=session_profile.uid,
@@ -637,6 +852,25 @@ class AuthTools(ToolBase):
         payload["roles"] = self._compact_roles(member)
         return payload, []
 
+    def _workspace_permission_level(
+        self,
+        *,
+        session_profile,  # type: ignore[no-untyped-def]
+        backend_session,  # type: ignore[no-untyped-def]
+    ) -> str | None:
+        """Resolve the selected workspace permission label without requiring member lookup."""
+        ws_id = session_profile.selected_ws_id
+        if ws_id is None:
+            return None
+        context = BackendRequestContext(
+            base_url=backend_session.base_url,
+            token=backend_session.token,
+            ws_id=ws_id,
+            qf_version=backend_session.qf_version,
+            qf_version_source=backend_session.qf_version_source,
+        )
+        return self._resolve_permission_level(self._workspace_auth(context, ws_id=ws_id))
+
     def _workspace_auth(self, context: BackendRequestContext, *, ws_id: int) -> int | None:
         """执行内部辅助逻辑。"""
         workspace = self._fetch_workspace_auth_from_detail(context, ws_id=ws_id)

package/src/qingflow_mcp/tools/base.py

@@ -47,7 +47,11 @@ class ToolBase:
         context = BackendRequestContext(
             base_url=backend_session.base_url,
             token=backend_session.token,
-            ws_id=session_profile.selected_ws_id if require_workspace else None,
+            # Keep the selected workspace in context whenever we know it.
+            # Some top-level tools (for example workspace browsing) do not
+            # require a workspace to execute, but credit metering still needs
+            # a stable wsId when the profile already has one selected.
+            ws_id=session_profile.selected_ws_id,
             qf_version=backend_session.qf_version,
             qf_version_source=backend_session.qf_version_source,
         )
@@ -96,7 +100,7 @@ class ToolBase:
             self.sessions.invalidate(profile)
             error = QingflowApiError(
                 category="auth",
-                message=f"Qingflow session for profile '{profile}' has expired. Run auth_use_credential again.",
+                message=f"Qingflow session for profile '{profile}' has expired. Run auth login or auth_use_credential again.",
                 backend_code=error.backend_code,
                 request_id=error.request_id,
                 http_status=error.http_status,