@josephyan/qingflow-cli 0.2.0-beta.985 → 0.2.0-beta.987

package/src/qingflow_mcp/tools/auth_tools.py

@@ -1,154 +1,145 @@
 from __future__ import annotations
 
-import base64
+import json
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
-from Crypto.PublicKey import RSA
-from Crypto.Cipher import PKCS1_v1_5
 
 from ..backend_client import BackendRequestContext, BackendResponse
 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
 from ..session_store import SessionStore
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class AuthTools(ToolBase):
+    """认证类工具（中文名：身份与会话工具）。
+
+    主要职责：
+    1. 使用 credential 调用 /mcp/auth/context 建立会话；
+    2. 查询当前登录身份与工作区成员信息；
+    3. 退出并清理当前 profile 会话。
+    """
+
     def __init__(self, sessions: SessionStore, backend) -> None:
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
 
     def register(self, mcp: FastMCP) -> None:
-        @mcp.tool()
-        def auth_login(
-            profile: str = DEFAULT_PROFILE,
-            base_url: str | None = None,
-            qf_version: str | None = None,
-            email: str = "",
-            password: str = "",
-            persist: bool = True,
-        ) -> dict[str, Any]:
-            return self.auth_login(profile=profile, base_url=base_url, qf_version=qf_version, email=email, password=password, persist=persist)
-
-        @mcp.tool()
-        def auth_use_token(
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool(
+            description=(
+                "类型：认证工具；中文名：凭证登录。"
+                "用途：使用 createClaw 提供的 credential 交换上下文并建立本地会话。"
+            )
+        )
+        def auth_use_credential(
             profile: str = DEFAULT_PROFILE,
             base_url: str | None = None,
             qf_version: str | None = None,
-            token: str = "",
-            ws_id: int | None = None,
+            credential: str = "",
             persist: bool = False,
         ) -> dict[str, Any]:
-            return self.auth_use_token(profile=profile, base_url=base_url, qf_version=qf_version, token=token, ws_id=ws_id, persist=persist)
+            return self.auth_use_credential(
+                profile=profile,
+                base_url=base_url,
+                qf_version=qf_version,
+                credential=credential,
+                persist=persist,
+            )
 
-        @mcp.tool()
+        @mcp.tool(
+            description=(
+                "类型：认证工具；中文名：我的身份。"
+                "用途：查看当前 profile 的登录身份、工作区与权限信息。"
+            )
+        )
         def auth_whoami(profile: str = DEFAULT_PROFILE) -> dict[str, Any]:
             return self.auth_whoami(profile=profile)
 
-        @mcp.tool()
+        @mcp.tool(
+            description=(
+                "类型：认证工具；中文名：退出登录。"
+                "用途：退出当前 profile，并可选清理持久化会话。"
+            )
+        )
         def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict[str, Any]:
             return self.auth_logout(profile=profile, forget_persisted=forget_persisted)
 
-    def auth_login(
+    @tool_cn_name("凭证登录")
+    def auth_use_credential(
         self,
         *,
         profile: str = DEFAULT_PROFILE,
         base_url: str | None = None,
         qf_version: str | None = None,
-        email: str,
-        password: str,
-        persist: bool,
+        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)
-        if not email or not password:
-            raise_tool_error(QingflowApiError.config_error("email and password are required"))
-
-        # Try to fetch public key and encrypt password
-        public_key_str = self._fetch_public_key(normalized_base_url, qf_version=normalized_qf_version)
-        encrypted_password = self._encrypt_password(password, public_key_str) if public_key_str else password
-
-        try:
-            # Try 'email' first (aPaas/Public Cloud style)
-            login_response = self.backend.public_request_with_meta(
-                "POST",
-                normalized_base_url,
-                "/user/login",
-                json_body={"email": email, "password": encrypted_password},
-                qf_version=normalized_qf_version,
-            )
-        except QingflowApiError as error:
-            # If failed, try 'account' (QMC/Private Cloud style)
-            try:
-                login_response = self.backend.public_request_with_meta(
-                    "POST",
-                    normalized_base_url,
-                    "/user/login",
-                    json_body={"account": email, "password": encrypted_password},
-                    qf_version=normalized_qf_version,
-                )
-            except QingflowApiError:
-                # If both failed, raise the original error
-                self._handle_error(profile, error)
-                raise AssertionError("unreachable")
-        login_result = login_response.data
-        if not isinstance(login_result, dict):
-            raise_tool_error(QingflowApiError(category="auth", message="Login did not return a valid result"))
-
-        token = login_result.get("token")
-        login_token = login_result.get("loginToken")
-        
-        if not token and login_token:
+        normalized_credential = str(resolved_credential).strip()
+        if not normalized_credential:
             raise_tool_error(
-                QingflowApiError.not_supported(
-                    "Current environment requires an additional login challenge. Qingflow MCP v1 only supports direct token login."
+                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,
+            normalized_credential,
+            qf_version=normalized_qf_version,
+        )
+        token = self._normalize_text(context_payload.get("token"))
         if not token:
-            raise_tool_error(QingflowApiError(category="auth", message="Login did not return a valid Qingflow token"))
-        detected_qf_version = login_response.qf_response_version
+            raise_tool_error(QingflowApiError(category="auth", message="Credential context did not return a valid Qingflow token"))
+
+        response_qf_version = self._normalize_text(context_payload.get("qfVersion"))
         resolved_qf_version, resolved_qf_version_source = self._resolve_backend_qf_version(
-            detected_qf_version,
+            response_qf_version or detected_qf_version,
             fallback_qf_version=normalized_qf_version,
             fallback_source=qf_version_source,
         )
-
-        user_info = login_result.get("userVO") or login_result.get("userInfo") or {}
-        if not isinstance(user_info, dict):
-            user_info = {}
-        verified_user_info, verified_qf_version = self._try_fetch_user_info(
-            normalized_base_url,
-            token,
-            qf_version=resolved_qf_version,
-            qf_version_source=resolved_qf_version_source,
-        )
-        if verified_qf_version:
-            resolved_qf_version, resolved_qf_version_source = self._resolve_backend_qf_version(
-                verified_qf_version,
-                fallback_qf_version=resolved_qf_version,
-                fallback_source=resolved_qf_version_source,
-            )
-        if isinstance(verified_user_info, dict):
-            user_info = verified_user_info
-        last_ws_info = user_info.get("lastWsInfo") or {}
+        resolved_base_url = self._normalize_text(context_payload.get("baseUrl")) or normalized_base_url
+        selected_ws_id = self._coerce_int(context_payload.get("wsId"))
+        if selected_ws_id is None or selected_ws_id <= 0:
+            raise_tool_error(QingflowApiError(category="auth", message="Credential context did not return a valid wsId"))
+        selected_ws_name = self._normalize_text(context_payload.get("wsName"))
+        uid = self._coerce_int(context_payload.get("uid"))
+        if uid is None:
+            raise_tool_error(QingflowApiError(category="auth", message="Credential context did not return valid user info"))
         session_profile = self.sessions.save_session(
             profile=profile,
-            base_url=normalized_base_url,
+            base_url=resolved_base_url,
             qf_version=resolved_qf_version,
             qf_version_source=resolved_qf_version_source,
             token=token,
-            login_token=login_token,
-            uid=int(user_info.get("uid")),
-            email=user_info.get("email"),
-            nick_name=user_info.get("nickName"),
+            login_token=None,
+            credential=normalized_credential,
+            uid=uid,
+            email=self._normalize_text(context_payload.get("email")),
+            nick_name=self._normalize_text(
+                context_payload.get("nickName")
+                or context_payload.get("displayName")
+                or context_payload.get("name")
+            ),
             persist=persist,
         )
+        session_profile = self.sessions.select_workspace(profile, ws_id=selected_ws_id, ws_name=selected_ws_name)
+
         return {
             "profile": session_profile.profile,
             "base_url": session_profile.base_url,
@@ -159,8 +150,8 @@ class AuthTools(ToolBase):
             "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": last_ws_info.get("wsId"),
-            "suggested_ws_name": last_ws_info.get("wsName") or last_ws_info.get("workspaceName"),
+            "suggested_ws_id": session_profile.selected_ws_id,
+            "suggested_ws_name": session_profile.selected_ws_name,
             "persisted": session_profile.persisted,
             "request_route": self._request_route_payload(
                 BackendRequestContext(
@@ -173,176 +164,170 @@ class AuthTools(ToolBase):
             ),
         }
 
-    def auth_use_token(
-        self,
-        *,
-        profile: str = DEFAULT_PROFILE,
-        base_url: str | None = None,
-        qf_version: str | None = None,
-        token: str,
-        ws_id: int | None = None,
-        persist: bool = False,
-    ) -> dict[str, Any]:
-        normalized_base_url = self._normalize_base_url(base_url)
-        normalized_qf_version, qf_version_source = self._resolve_qf_version_input(qf_version)
-        qf_version_explicit = qf_version is not None and bool(str(qf_version).strip())
-        if not token:
-            raise_tool_error(QingflowApiError.config_error("token is required"))
-        if ws_id is not None and ws_id <= 0:
-            raise_tool_error(QingflowApiError.config_error("ws_id must be positive"))
+    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:
-            user_info, detected_qf_version = self._fetch_user_info(
-                normalized_base_url,
-                token,
-                ws_id,
-                qf_version=normalized_qf_version,
-                qf_version_source=qf_version_source,
-            )
-            resolved_qf_version, resolved_qf_version_source = self._resolve_backend_qf_version(
-                detected_qf_version,
-                fallback_qf_version=normalized_qf_version,
-                fallback_source=qf_version_source,
+            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]:
+        """执行认证与会话相关逻辑。"""
+        def build_response(
+            session_profile,  # type: ignore[no-untyped-def]
+            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,
             )
-            uid = user_info.get("uid")
-            if uid is None:
-                raise_tool_error(QingflowApiError(category="auth", message="Token validation did not return valid user info"))
-            last_ws_info = user_info.get("lastWsInfo") or {}
-            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=token,
-                login_token=None,
-                uid=int(uid),
-                email=user_info.get("email"),
-                nick_name=user_info.get("nickName") or user_info.get("displayName") or user_info.get("name"),
-                persist=persist,
+            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
             )
-            selected_ws_name = None
-            if ws_id is not None:
-                workspace = self._fetch_workspace(
-                    normalized_base_url,
-                    token,
-                    ws_id,
-                    qf_version=resolved_qf_version,
-                    qf_version_source=resolved_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"
                 )
-                workspace_qf_version = self._workspace_system_version(workspace)
-                if not qf_version_explicit and workspace_qf_version is not None and workspace_qf_version != resolved_qf_version:
-                    resolved_qf_version = workspace_qf_version
-                    resolved_qf_version_source = "workspace_system_version"
-                    session_profile = self.sessions.update_route(
-                        profile,
-                        qf_version=resolved_qf_version,
-                        qf_version_source=resolved_qf_version_source,
-                    )
-                selected_ws_name = workspace.get("workspaceName") or workspace.get("wsName") or workspace.get("remark")
-                session_profile = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=selected_ws_name)
-            return {
+            ):
+                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,
+                    session_profile=session_profile,
+                    backend_session=backend_session,
+                    context=context,
+                )
+                if refreshed_profile is not None:
+                    session_profile = refreshed_profile
+            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,
                 "selected_ws_id": session_profile.selected_ws_id,
                 "selected_ws_name": session_profile.selected_ws_name,
-                "suggested_ws_id": last_ws_info.get("wsId"),
-                "suggested_ws_name": last_ws_info.get("wsName") or last_ws_info.get("workspaceName"),
                 "persisted": session_profile.persisted,
-                "request_route": self._request_route_payload(
-                    BackendRequestContext(
-                        base_url=session_profile.base_url,
-                        token=token,
-                        ws_id=session_profile.selected_ws_id,
-                        qf_version=session_profile.qf_version,
-                        qf_version_source=session_profile.qf_version_source,
-                    )
-                ),
+                "request_route": self._request_route_payload(context),
             }
-        except QingflowApiError as error:
-            if self._should_allow_provisional_token_session(error):
-                session_profile = self.sessions.save_session(
-                    profile=profile,
-                    base_url=normalized_base_url,
-                    qf_version=normalized_qf_version,
-                    qf_version_source=qf_version_source,
-                    token=token,
-                    login_token=None,
-                    uid=0,
-                    email=None,
-                    nick_name=None,
-                    persist=persist,
-                )
-                if ws_id is not None:
-                    session_profile = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=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": ws_id,
-                    "suggested_ws_name": None,
-                    "persisted": session_profile.persisted,
-                    "provisional": True,
-                    "request_route": self._request_route_payload(
-                        BackendRequestContext(
-                            base_url=session_profile.base_url,
-                            token=token,
-                            ws_id=session_profile.selected_ws_id,
-                            qf_version=session_profile.qf_version,
-                            qf_version_source=session_profile.qf_version_source,
-                        )
-                    ),
-                }
-            self._handle_error(profile, error)
-            raise AssertionError("unreachable")
+            member_info, member_warnings = self._workspace_member_info(
+                session_profile=session_profile,
+                backend_session=backend_session,
+            )
+            response.update(member_info)
+            if member_warnings:
+                response["warnings"] = member_warnings
+            return response
 
-    def auth_whoami(self, *, profile: str = DEFAULT_PROFILE) -> dict[str, Any]:
+        session_profile = None
+        backend_session = None
         try:
             session_profile, backend_session, context = self._require_context(profile, require_workspace=False)
+            if backend_session.credential:
+                self._probe_token_validity(
+                    session_profile=session_profile,
+                    backend_session=backend_session,
+                )
+            return build_response(session_profile, backend_session, context)
         except QingflowApiError as error:
+            if (
+                error.looks_like_invalid_token()
+                and session_profile is not None
+                and backend_session is not None
+                and self._refresh_session_from_credential(
+                    profile,
+                    session_profile=session_profile,
+                    backend_session=backend_session,
+                )
+            ):
+                try:
+                    refreshed_profile, refreshed_backend_session, refreshed_context = self._require_context(
+                        profile,
+                        require_workspace=False,
+                    )
+                    return build_response(refreshed_profile, refreshed_backend_session, refreshed_context)
+                except QingflowApiError as refreshed_error:
+                    self._handle_error(profile, refreshed_error)
             self._handle_error(profile, error)
             raise AssertionError("unreachable")
-        if self._should_refresh_identity_metadata(session_profile):
-            refreshed_profile = self._refresh_identity_metadata(
-                profile=profile,
-                session_profile=session_profile,
-                backend_session=backend_session,
-                context=context,
-            )
-            if refreshed_profile is not None:
-                session_profile = refreshed_profile
-        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,
-            "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,
-            "persisted": session_profile.persisted,
-            "request_route": self._request_route_payload(context),
-        }
-        member_info, member_warnings = self._workspace_member_info(
-            session_profile=session_profile,
-            backend_session=backend_session,
+
+    def _probe_token_validity(
+        self,
+        *,
+        session_profile,  # type: ignore[no-untyped-def]
+        backend_session,  # type: ignore[no-untyped-def]
+    ) -> None:
+        """执行内部辅助逻辑。"""
+        probe_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,
         )
-        response.update(member_info)
-        if member_warnings:
-            response["warnings"] = member_warnings
-        return response
+        try:
+            self.backend.request("GET", probe_context, "/user")
+        except QingflowApiError as error:
+            if error.looks_like_invalid_token():
+                raise
 
+    @tool_cn_name("退出登录")
     def auth_logout(self, *, profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict[str, Any]:
+        """执行认证与会话相关逻辑。"""
         if not self.sessions.has_profile(profile):
             raise_tool_error(QingflowApiError.auth_required(profile))
         self.sessions.logout(profile, forget_persisted=forget_persisted)
@@ -353,6 +338,7 @@ class AuthTools(ToolBase):
         }
 
     def _normalize_base_url(self, base_url: str | None) -> str:
+        """执行内部辅助逻辑。"""
         normalized_base_url = normalize_base_url(base_url) or get_default_base_url()
         if not normalized_base_url:
             raise_tool_error(
@@ -363,12 +349,14 @@ class AuthTools(ToolBase):
         return normalized_base_url
 
     def _normalize_qf_version(self, qf_version: str | None) -> str | None:
+        """执行内部辅助逻辑。"""
         if qf_version is not None:
             normalized = str(qf_version).strip()
             return normalized or None
         return get_default_qf_version()
 
     def _resolve_qf_version_input(self, qf_version: str | None) -> tuple[str | None, str]:
+        """执行内部辅助逻辑。"""
         if qf_version is not None:
             normalized = self._normalize_qf_version(qf_version)
             return normalized, "explicit" if normalized else "unset"
@@ -377,11 +365,6 @@ class AuthTools(ToolBase):
             return normalized, "default_config"
         return None, "unset"
 
-    def _should_allow_provisional_token_session(self, error: QingflowApiError) -> bool:
-        if error.looks_like_invalid_token():
-            return False
-        return error.http_status == 404 and error.category in {"http", "auth", "workspace"}
-
     def _resolve_backend_qf_version(
         self,
         backend_qf_version: str | None,
@@ -389,11 +372,41 @@ class AuthTools(ToolBase):
         fallback_qf_version: str | None,
         fallback_source: str,
     ) -> tuple[str | None, str]:
+        """执行内部辅助逻辑。"""
         if backend_qf_version:
             return backend_qf_version, "backend_response"
         return fallback_qf_version, fallback_source
 
+    def _fetch_auth_context(
+        self,
+        base_url: str,
+        credential: str,
+        *,
+        qf_version: str | None,
+    ) -> tuple[dict[str, Any], str | None]:
+        """执行内部辅助逻辑。"""
+        response = self.backend.public_request_with_meta(
+            "POST",
+            base_url,
+            "/mcp/auth/context",
+            json_body={"credential": credential},
+            qf_version=qf_version,
+        )
+        payload = self._unwrap_auth_context_payload(response.data)
+        return payload, response.qf_response_version
+
+    def _unwrap_auth_context_payload(self, payload: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
+        if not isinstance(payload, dict):
+            raise_tool_error(QingflowApiError(category="auth", message="Credential context did not return a valid result"))
+        for key in ("data", "result"):
+            nested = payload.get(key)
+            if isinstance(nested, dict):
+                return nested
+        return payload
+
     def _workspace_system_version(self, workspace: Any) -> str | None:
+        """执行内部辅助逻辑。"""
         if not isinstance(workspace, dict):
             return None
         value = workspace.get("systemVersion")
@@ -411,6 +424,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> tuple[dict[str, Any], str | None]:
+        """执行内部辅助逻辑。"""
         request_context = BackendRequestContext(
             base_url=base_url,
             token=token,
@@ -461,6 +475,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> tuple[dict[str, Any] | None, str | None]:
+        """执行内部辅助逻辑。"""
         try:
             return self._fetch_user_info(
                 base_url,
@@ -480,6 +495,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> tuple[dict[str, Any] | None, str | None]:
+        """执行内部辅助逻辑。"""
         page_response = self.backend.request_with_meta(
             "POST",
             BackendRequestContext(
@@ -510,6 +526,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         workspace = self.backend.request(
             "GET",
             BackendRequestContext(
@@ -525,7 +542,26 @@ 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)
         if callable(describe_route):
             payload = describe_route(context)
@@ -538,6 +574,7 @@ class AuthTools(ToolBase):
         }
 
     def _should_refresh_identity_metadata(self, session_profile) -> bool:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return (
             session_profile.uid == 0
             or session_profile.email is None
@@ -553,6 +590,7 @@ class AuthTools(ToolBase):
         backend_session,  # type: ignore[no-untyped-def]
         context: BackendRequestContext,
     ):
+        """执行内部辅助逻辑。"""
         try:
             user_info, _ = self._fetch_user_info(
                 session_profile.base_url,
@@ -603,6 +641,7 @@ class AuthTools(ToolBase):
         session_profile,  # type: ignore[no-untyped-def]
         backend_session,  # type: ignore[no-untyped-def]
     ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """执行内部辅助逻辑。"""
         default_payload = {
             "departments": [],
             "roles": [],
@@ -647,12 +686,14 @@ class AuthTools(ToolBase):
         return payload, []
 
     def _workspace_auth(self, context: BackendRequestContext, *, ws_id: int) -> int | None:
+        """执行内部辅助逻辑。"""
         workspace = self._fetch_workspace_auth_from_detail(context, ws_id=ws_id)
         if workspace is not None:
             return workspace
         return self._fetch_workspace_auth_from_list(context, ws_id=ws_id)
 
     def _fetch_workspace_auth_from_detail(self, context: BackendRequestContext, *, ws_id: int) -> int | None:
+        """执行内部辅助逻辑。"""
         try:
             workspace = self.backend.request("GET", context, f"/user/workspace/{ws_id}")
         except QingflowApiError:
@@ -662,6 +703,7 @@ class AuthTools(ToolBase):
         return self._coerce_auth_value(workspace.get("auth"))
 
     def _fetch_workspace_auth_from_list(self, context: BackendRequestContext, *, ws_id: int) -> int | None:
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request(
                 "POST",
@@ -688,6 +730,7 @@ class AuthTools(ToolBase):
         email: str | None,
         nick_name: str | None,
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         candidates: list[dict[str, Any]] = []
         for keyword in (email, nick_name):
             member = self._search_member_once(context, uid=uid, keyword=keyword)
@@ -709,12 +752,14 @@ class AuthTools(ToolBase):
         uid: int | None,
         keyword: str | None,
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         for item in self._search_member_items(context, keyword=keyword):
             if self._same_member(item, uid=uid):
                 return item
         return None
 
     def _search_member_items(self, context: BackendRequestContext, *, keyword: str | None) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         params: dict[str, Any] = {"pageNum": 1, "pageSize": 100, "containDisable": True}
         normalized_keyword = str(keyword or "").strip()
         if normalized_keyword:
@@ -727,6 +772,7 @@ class AuthTools(ToolBase):
         return [item for item in items if isinstance(item, dict)]
 
     def _same_member(self, item: dict[str, Any], *, uid: int | None) -> bool:
+        """执行内部辅助逻辑。"""
         if uid is None or uid <= 0:
             return False
         for key in ("uid", "id", "userId"):
@@ -741,6 +787,7 @@ class AuthTools(ToolBase):
         return False
 
     def _compact_departments(self, member: dict[str, Any]) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         items: list[dict[str, Any]] = []
         seen: set[tuple[int | None, str | None]] = set()
         for depart in self._walk_nested_items(member.get("departs")):
@@ -761,6 +808,7 @@ class AuthTools(ToolBase):
         return items
 
     def _compact_roles(self, member: dict[str, Any]) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         items: list[dict[str, Any]] = []
         seen: set[tuple[int | None, str | None]] = set()
         for role in self._walk_nested_items(member.get("roles")):
@@ -777,6 +825,7 @@ class AuthTools(ToolBase):
         return items
 
     def _resolve_permission_level(self, auth_code: int | None) -> str | None:
+        """执行内部辅助逻辑。"""
         mapping = {
             2: "超级管理",
             1: "系统管理员",
@@ -786,6 +835,7 @@ class AuthTools(ToolBase):
         return mapping.get(auth_code)
 
     def _coerce_auth_value(self, value: Any) -> int | None:
+        """执行内部辅助逻辑。"""
         coerced = self._coerce_int(value)
         if coerced is not None:
             return coerced
@@ -804,6 +854,7 @@ class AuthTools(ToolBase):
         return None
 
     def _extract_items(self, payload: Any) -> list[Any]:
+        """执行内部辅助逻辑。"""
         if isinstance(payload, list):
             return payload
         if not isinstance(payload, dict):
@@ -824,6 +875,7 @@ class AuthTools(ToolBase):
         return []
 
     def _walk_nested_items(self, value: Any) -> list[Any]:
+        """执行内部辅助逻辑。"""
         if isinstance(value, list):
             items: list[Any] = []
             for item in value:
@@ -832,6 +884,7 @@ class AuthTools(ToolBase):
         return [value]
 
     def _coerce_int(self, value: Any) -> int | None:
+        """执行内部辅助逻辑。"""
         if isinstance(value, bool) or value is None:
             return None
         if isinstance(value, int):
@@ -842,6 +895,7 @@ class AuthTools(ToolBase):
             return None
 
     def _normalize_text(self, value: Any) -> str | None:
+        """执行内部辅助逻辑。"""
         if value is None:
             return None
         text = str(value).strip()
@@ -856,6 +910,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         try:
             workspace = self._fetch_workspace(
                 base_url,
@@ -891,6 +946,7 @@ class AuthTools(ToolBase):
         qf_version: str | None,
         qf_version_source: str | None,
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         payload = self.backend.request(
             "POST",
             BackendRequestContext(
@@ -915,41 +971,3 @@ class AuthTools(ToolBase):
             None,
         )
         return found if isinstance(found, dict) else None
-
-    def _fetch_public_key(self, base_url: str, *, qf_version: str | None) -> str | None:
-        # Endpoints to try (order matters, lowercase 'pubkey' is for Public Cloud)
-        endpoints = ["/user/pubkey", "/api/user/pubkey", "/user/publicKey", "/api/user/publicKey"]
-        for endpoint in endpoints:
-            try:
-                # We use unwrap=False to handle various response formats
-                result = self.backend.public_request("GET", base_url, endpoint, unwrap=False, qf_version=qf_version)
-                if isinstance(result, dict):
-                    # Try various common response structures
-                    data = result.get("data") or result.get("result") or result
-                    if isinstance(data, dict):
-                        # Try case-insensitive keys
-                        for key in ["pubkey", "publicKey", "pubKey"]:
-                            if key in data:
-                                return str(data[key])
-                    if isinstance(data, str) and not data.startswith("{"):
-                        return data
-            except Exception:
-                continue
-        
-        return None
-
-    def _encrypt_password(self, password: str, public_key_str: str) -> str:
-        try:
-            if not public_key_str.startswith("-----BEGIN"):
-                key_content = public_key_str.strip()
-                formatted_key = f"-----BEGIN PUBLIC KEY-----\n{key_content}\n-----END PUBLIC KEY-----"
-            else:
-                formatted_key = public_key_str
-            
-            key = RSA.import_key(formatted_key)
-            cipher = PKCS1_v1_5.new(key)
-            encrypted = cipher.encrypt(password.encode("utf-8"))
-            return base64.b64encode(encrypted).decode("utf-8")
-        except Exception as e:
-            # If encryption fails, fallback to plain text (might be a legacy or custom environment)
-            return password