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

package/src/qingflow_mcp/session_store.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -77,6 +78,7 @@ class SessionStore:
         profiles_path = get_profiles_path() if base_dir is None else Path(base_dir) / "profiles.json"
         self._profiles_path = profiles_path
         self._profiles_path.parent.mkdir(parents=True, exist_ok=True)
+        self._secrets_path = self._profiles_path.parent / "secrets.json"
         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()
@@ -290,26 +292,78 @@ class SessionStore:
             json.dump(payload, handle, ensure_ascii=False, indent=2)
 
     def _set_secret(self, key: str, value: str) -> bool:
-        if self._keyring is None:
-            return False
+        if self._keyring is not None:
+            try:
+                self._keyring.set_password(KEYRING_SERVICE_NAME, key, value)
+                self._delete_file_secret(key)
+                return True
+            except Exception:
+                pass
+        return self._set_file_secret(key, value)
+
+    def _get_secret(self, key: str) -> str | None:
+        if self._keyring is not None:
+            try:
+                value = self._keyring.get_password(KEYRING_SERVICE_NAME, key)
+            except Exception:
+                value = None
+            if value:
+                return value
+        return self._get_file_secret(key)
+
+    def _delete_secret(self, key: str) -> None:
+        if self._keyring is not None:
+            try:
+                self._keyring.delete_password(KEYRING_SERVICE_NAME, key)
+            except Exception:
+                pass
+        self._delete_file_secret(key)
+
+    def _load_file_secrets(self) -> dict[str, str]:
+        if not self._secrets_path.exists():
+            return {}
+        try:
+            with self._secrets_path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            return {}
+        if not isinstance(payload, dict):
+            return {}
+        return {str(key): str(value) for key, value in payload.items() if isinstance(value, str)}
+
+    def _save_file_secrets(self, payload: dict[str, str]) -> bool:
+        self._secrets_path.parent.mkdir(parents=True, exist_ok=True)
         try:
-            self._keyring.set_password(KEYRING_SERVICE_NAME, key, value)
+            fd = os.open(self._secrets_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(payload, handle, ensure_ascii=False, indent=2)
+            try:
+                os.chmod(self._secrets_path, 0o600)
+            except OSError:
+                pass
             return True
-        except Exception:
+        except OSError:
             return False
 
-    def _get_secret(self, key: str) -> str | None:
-        if self._keyring is None:
-            return None
-        try:
-            return self._keyring.get_password(KEYRING_SERVICE_NAME, key)
-        except Exception:
-            return None
+    def _set_file_secret(self, key: str, value: str) -> bool:
+        payload = self._load_file_secrets()
+        payload[key] = value
+        return self._save_file_secrets(payload)
 
-    def _delete_secret(self, key: str) -> None:
-        if self._keyring is None:
+    def _get_file_secret(self, key: str) -> str | None:
+        return self._load_file_secrets().get(key)
+
+    def _delete_file_secret(self, key: str) -> None:
+        payload = self._load_file_secrets()
+        if key not in payload:
+            return
+        payload.pop(key, None)
+        if payload:
+            self._save_file_secrets(payload)
             return
         try:
-            self._keyring.delete_password(KEYRING_SERVICE_NAME, key)
-        except Exception:
+            self._secrets_path.unlink()
+        except FileNotFoundError:
+            return
+        except OSError:
             return

package/src/qingflow_mcp/solution/compiler/form_compiler.py

@@ -307,7 +307,7 @@ def build_reference_config(field: dict[str, Any], temp_id: int) -> dict[str, Any
                 "queId": que_id,
                 "queTitle": label,
                 "queType": _normalize_reference_que_type(raw_type) or "2",
-                "queAuth": 1,
+                "queAuth": 3,
                 "ordinal": ordinal,
                 "quoteId": temp_id,
                 "_field_id": field_id,
@@ -320,7 +320,7 @@ def build_reference_config(field: dict[str, Any], temp_id: int) -> dict[str, Any
         auth_ques = []
         for ordinal, field_id in enumerate(auth_field_ids, start=1):
             que_id = auth_field_que_ids[ordinal - 1] if ordinal - 1 < len(auth_field_que_ids) else 0
-            auth_ques.append({"queId": que_id, "queAuth": 1, "_field_id": field_id})
+            auth_ques.append({"queId": que_id, "queAuth": 3, "_field_id": field_id})
     return {
         "referAppKey": "__TARGET_APP_KEY__",
         "referQueId": display_field_que_id,

package/src/qingflow_mcp/solution/executor.py

@@ -857,12 +857,12 @@ class SolutionExecutor:
                 if refer_que_id is None:
                     continue
                 resolved["queId"] = refer_que_id
-                resolved["queAuth"] = int(resolved.get("queAuth", 1))
+                resolved["queAuth"] = int(resolved.get("queAuth", 3))
                 auth_ques.append(resolved)
             if not auth_ques:
                 fallback_que_id = target_meta.get("by_field_id", {}).get(target_field_id)
                 if fallback_que_id is not None:
-                    auth_ques.append({"queId": fallback_que_id, "queAuth": 1})
+                    auth_ques.append({"queId": fallback_que_id, "queAuth": 3})
             reference_config["referAuthQues"] = auth_ques
             reference_config["fieldNameShow"] = bool(reference_config.get("fieldNameShow", True))
             fill_rules = []

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1873,7 +1873,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,
@@ -2665,6 +2665,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 +2731,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 +2753,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 +2803,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 +3174,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 +3191,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 +3297,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 +3361,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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
@@ -9,6 +10,7 @@ from ..config import (
     DEFAULT_PROFILE,
     get_default_base_url,
     get_default_qf_version,
+    get_mcporter_config_path,
     normalize_base_url,
 )
 from ..errors import QingflowApiError, raise_tool_error
@@ -77,15 +79,24 @@ class AuthTools(ToolBase):
         profile: str = DEFAULT_PROFILE,
         base_url: str | None = None,
         qf_version: str | None = None,
-        credential: str,
+        credential: str | None = None,
         persist: bool = False,
     ) -> dict[str, Any]:
         """执行认证与会话相关逻辑。"""
-        normalized_base_url = self._normalize_base_url(base_url)
+        resolved_base_url, resolved_credential = self._resolve_mcporter_auth_inputs(
+            base_url=base_url,
+            credential=credential,
+        )
+        normalized_base_url = self._normalize_base_url(resolved_base_url)
         normalized_qf_version, qf_version_source = self._resolve_qf_version_input(qf_version)
-        normalized_credential = str(credential).strip()
+        normalized_credential = str(resolved_credential).strip()
         if not normalized_credential:
-            raise_tool_error(QingflowApiError.config_error("credential is required"))
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "credential is required or configure ~/.openclaw/workspace/config/mcporter.json "
+                    "with mcpServers.qingflow.headers.x-qingflow-client-id"
+                )
+            )
 
         context_payload, detected_qf_version = self._fetch_auth_context(
             normalized_base_url,
@@ -153,6 +164,186 @@ 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)
+        normalized_credential = self._normalize_text(credential)
+        if normalized_base_url and normalized_credential:
+            return normalized_base_url, normalized_credential
+
+        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_credential:
+            normalized_credential = self._normalize_text(mcporter_context.get("credential"))
+        return normalized_base_url, normalized_credential or ""
+
+    def _read_mcporter_qingflow_context(self) -> dict[str, str]:
+        """读取 OpenClaw mcporter 中的 Qingflow MCP 上下文。"""
+        path = get_mcporter_config_path()
+        if not path.exists():
+            return {}
+        try:
+            with path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise_tool_error(QingflowApiError.config_error(f"failed to read mcporter config '{path}': {exc}"))
+
+        if not isinstance(payload, dict):
+            raise_tool_error(QingflowApiError.config_error(f"mcporter config '{path}' must be a JSON object"))
+        mcp_servers = payload.get("mcpServers")
+        qingflow = mcp_servers.get("qingflow") if isinstance(mcp_servers, dict) else None
+        if not isinstance(qingflow, dict):
+            return {}
+        headers = qingflow.get("headers")
+        credential = None
+        if isinstance(headers, dict):
+            credential = headers.get("x-qingflow-client-id")
+        return {
+            "base_url": str(qingflow.get("url") or "").strip(),
+            "credential": str(credential or "").strip(),
+        }
+
     @tool_cn_name("我的身份")
     def auth_whoami(self, *, profile: str = DEFAULT_PROFILE) -> dict[str, Any]:
         """执行认证与会话相关逻辑。"""
@@ -161,6 +352,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,
@@ -173,8 +394,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,
@@ -461,6 +682,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)
@@ -552,6 +791,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,
@@ -559,12 +805,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,
@@ -586,6 +826,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,