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

package/src/qingflow_mcp/tools/workflow_tools.py

@@ -6,11 +6,21 @@ from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONValue
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class WorkflowTools(ToolBase):
+    """流程工具（中文名：流程节点与规则管理）。
+
+    类型：流程配置工具。
+    主要职责：
+    1. 查询流程节点与流程图配置；
+    2. 读取与更新流程规则；
+    3. 支持流程发布与流程调试辅助能力。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def workflow_list_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.workflow_list_nodes(profile=profile, app_key=app_key)
@@ -59,16 +69,22 @@ class WorkflowTools(ToolBase):
         def workflow_get_print_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.workflow_get_print_nodes(profile=profile, app_key=app_key)
 
+    @tool_cn_name("流程节点列表")
     def workflow_list_nodes(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/app/{app_key}/auditNodes", app_key=app_key)
 
+    @tool_cn_name("流程节点详情")
     def workflow_get_node_detail(self, *, profile: str, app_key: str, audit_node_id: int) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("audit_node_id", audit_node_id)
         return self._request(profile, "GET", f"/app/{app_key}/auditNodes/{audit_node_id}", app_key=app_key, audit_node_id=audit_node_id)
 
+    @tool_cn_name("新增流程节点")
     def workflow_add_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request_with_post_fallbacks(
@@ -79,7 +95,9 @@ class WorkflowTools(ToolBase):
             alternate_paths=[f"/app/{app_key}/auditNode"],
         )
 
+    @tool_cn_name("更新流程节点")
     def workflow_update_node(self, *, profile: str, app_key: str, audit_node_id: int, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("audit_node_id", audit_node_id)
         body = self._require_dict(payload)
@@ -94,36 +112,50 @@ class WorkflowTools(ToolBase):
             audit_node_id=audit_node_id,
         )
 
+    @tool_cn_name("删除流程节点")
     def workflow_delete_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "DELETE", f"/app/{app_key}/auditNode", app_key=app_key, json_body=body, risk_operation="delete", risk_target="workflow node configuration")
 
+    @tool_cn_name("复制粘贴流程节点")
     def workflow_copy_paste_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/copyAndPaste", app_key=app_key, json_body=body)
 
+    @tool_cn_name("剪切粘贴流程节点")
     def workflow_cut_paste_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/cutAndPaste", app_key=app_key, json_body=body)
 
+    @tool_cn_name("创建流程分支")
     def workflow_create_sub_branch(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/subBranch", app_key=app_key, json_body=body)
 
+    @tool_cn_name("删除流程分支")
     def workflow_delete_sub_branch(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "DELETE", f"/app/{app_key}/auditNode/subBranch", app_key=app_key, json_body=body, risk_operation="delete", risk_target="workflow branch configuration")
 
+    @tool_cn_name("流程全局设置")
     def workflow_get_global_settings(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/app/{app_key}/workflow/global/setting", app_key=app_key)
 
+    @tool_cn_name("更新流程全局设置")
     def workflow_update_global_settings(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request_with_post_fallbacks(
@@ -136,7 +168,9 @@ class WorkflowTools(ToolBase):
             risk_target="workflow global settings",
         )
 
+    @tool_cn_name("发布流程")
     def workflow_publish(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request_with_post_fallbacks(
@@ -147,11 +181,14 @@ class WorkflowTools(ToolBase):
             alternate_paths=[],
         )
 
+    @tool_cn_name("流程后续节点")
     def workflow_get_future_nodes(self, *, profile: str, app_key: str, apply_id: int) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("apply_id", apply_id)
         return self._request(profile, "GET", f"/app/{app_key}/auditNode/futureList/{apply_id}", app_key=app_key, apply_id=apply_id)
 
+    @tool_cn_name("流程后续节点（应用）")
     def workflow_get_future_nodes_app(
         self,
         *,
@@ -161,6 +198,7 @@ class WorkflowTools(ToolBase):
         role: int,
         audit_node_id: int | None,
     ) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("apply_id", apply_id)
         params: JSONObject = {"role": role}
@@ -176,52 +214,72 @@ class WorkflowTools(ToolBase):
             params=params,
         )
 
+    @tool_cn_name("流程 Webhook 测试")
     def workflow_webhook_test(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/webhookTest", app_key=app_key, json_body=body)
 
+    @tool_cn_name("流程 QSource 查询")
     def workflow_qsource_query(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/qSourceQuery", app_key=app_key, json_body=body)
 
+    @tool_cn_name("流程 QSource 测试")
     def workflow_qsource_test(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/qSourceQueryTest", app_key=app_key, json_body=body)
 
+    @tool_cn_name("流程主动 QSource 配置")
     def workflow_get_qsource_active(self, *, profile: str, app_key: str, qsource_id: int) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("qsource_id", qsource_id)
         return self._request(profile, "GET", f"/app/{app_key}/auditNode/active/qsource", app_key=app_key, params={"qSourceId": qsource_id})
 
+    @tool_cn_name("更新主动 QSource 配置")
     def workflow_upsert_qsource_active(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/active/qsource", app_key=app_key, json_body=body)
 
+    @tool_cn_name("流程被动 QSource 配置")
     def workflow_get_qsource_passive(self, *, profile: str, app_key: str, qsource_id: int) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("qsource_id", qsource_id)
         return self._request(profile, "GET", f"/app/{app_key}/auditNode/passive/qsource", app_key=app_key, params={"qSourceId": qsource_id})
 
+    @tool_cn_name("更新被动 QSource 配置")
     def workflow_upsert_qsource_passive(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/passive/qsource", app_key=app_key, json_body=body)
 
+    @tool_cn_name("切换 QSource 状态")
     def workflow_switch_qsource_status(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/auditNode/source/status", app_key=app_key, json_body=body)
 
+    @tool_cn_name("删除 QSource 配置")
     def workflow_delete_qsource(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "DELETE", f"/app/{app_key}/auditNode/qsource", app_key=app_key, json_body=body, risk_operation="delete", risk_target="workflow qsource configuration")
 
+    @tool_cn_name("节点可编辑字段")
     def workflow_get_editable_question_ids(self, *, profile: str, app_key: str, audit_node_id: int) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         self._require_positive("audit_node_id", audit_node_id)
         return self._request(
@@ -232,7 +290,9 @@ class WorkflowTools(ToolBase):
             audit_node_id=audit_node_id,
         )
 
+    @tool_cn_name("流程打印节点")
     def workflow_get_print_nodes(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行流程相关逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/app/{app_key}/auditNode/printNodes", app_key=app_key)
 
@@ -249,6 +309,7 @@ class WorkflowTools(ToolBase):
         risk_target: str | None = None,
         **extra: JSONValue,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request(method, context, path, json_body=json_body, params=params)
             response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "app_key": app_key, "result": result}
@@ -271,6 +332,7 @@ class WorkflowTools(ToolBase):
         risk_target: str | None = None,
         **extra: JSONValue,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             attempted_contexts = [context]
             if context.qf_version is not None:
@@ -304,9 +366,11 @@ class WorkflowTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_app_key(self, app_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
     def _require_positive(self, field_name: str, value: int) -> None:
+        """执行内部辅助逻辑。"""
         if value <= 0:
             raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))

package/src/qingflow_mcp/tools/workspace_tools.py

@@ -7,11 +7,20 @@ from mcp.server.fastmcp import FastMCP
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class WorkspaceTools(ToolBase):
+    """工作区工具（中文名：工作区与插件管理）。
+
+    类型：基础上下文工具。
+    主要职责：
+    1. 查询当前用户可见工作区列表；
+    2. 管理工作区插件安装状态。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def workspace_list(
             profile: str = DEFAULT_PROFILE,
@@ -27,8 +36,14 @@ class WorkspaceTools(ToolBase):
             )
 
         @mcp.tool()
-        def workspace_select(profile: str = DEFAULT_PROFILE, ws_id: int = 0) -> dict[str, Any]:
-            return self.workspace_select(profile=profile, ws_id=ws_id)
+        def workspace_get(
+            profile: str = DEFAULT_PROFILE,
+            ws_id: int = 0,
+        ) -> dict[str, Any]:
+            return self.workspace_get(
+                profile=profile,
+                ws_id=ws_id if ws_id > 0 else None,
+            )
 
         @mcp.tool()
         def workspace_set_plugin_status(
@@ -42,6 +57,7 @@ class WorkspaceTools(ToolBase):
                 being_installed=being_installed,
             )
 
+    @tool_cn_name("工作区列表")
     def workspace_list(
         self,
         *,
@@ -50,6 +66,7 @@ class WorkspaceTools(ToolBase):
         page_size: int = 20,
         include_external: bool = False,
     ) -> dict[str, Any]:
+        """执行工作区相关逻辑。"""
         if page_num <= 0 or page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_num and page_size must be positive"))
 
@@ -86,226 +103,32 @@ class WorkspaceTools(ToolBase):
 
         return self._run(profile, runner, require_workspace=False)
 
-    def workspace_select(self, *, profile: str = DEFAULT_PROFILE, ws_id: int) -> dict[str, Any]:
-        if ws_id <= 0:
-            raise_tool_error(QingflowApiError.config_error("ws_id must be positive"))
-
-        def runner(_, context):
-            # Create a context with the target ws_id for the API call
-            # This is necessary because the API requires wsId header even when getting workspace details
-            call_context = BackendRequestContext(
-                base_url=context.base_url,
-                token=context.token,
-                ws_id=ws_id,
-                qf_version=context.qf_version,
-                qf_version_source=context.qf_version_source,
-            )
-            
-            try:
-                result = self.backend.request("GET", call_context, f"/user/workspace/{ws_id}")
-            except QingflowApiError as e:
-                if e.http_status == 404:
-                    result = self._workspace_from_list(call_context, ws_id) or {"wsId": ws_id, "workspaceName": f"Workspace {ws_id}"}
-                else:
-                    raise
-
-            if isinstance(result, dict):
-                ws_name = (
-                    str(result.get("workspaceName") or result.get("wsName") or "").strip()
-                    or None
-                )
-                if ws_name is None:
-                    fallback_workspace = self._workspace_from_list(call_context, ws_id)
-                    if isinstance(fallback_workspace, dict):
-                        result = fallback_workspace
-                        ws_name = (
-                            str(result.get("workspaceName") or result.get("wsName") or "").strip()
-                            or None
-                        )
-            else:
-                ws_name = None
-            if ws_name is None:
-                ws_name = f"Workspace {ws_id}"
-            session_profile = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=ws_name)
-            workspace_qf_version = self._workspace_system_version(result)
-            should_refresh_route = (
-                workspace_qf_version is not None
-                and (context.qf_version_source or "unset") != "explicit"
-                and workspace_qf_version != session_profile.qf_version
-            )
-            if should_refresh_route:
-                session_profile = self.sessions.update_route(
-                    profile,
-                    qf_version=workspace_qf_version,
-                    qf_version_source="workspace_system_version",
-                )
-            active_context = BackendRequestContext(
-                base_url=session_profile.base_url,
-                token=context.token,
-                ws_id=session_profile.selected_ws_id,
-                qf_version=session_profile.qf_version,
-                qf_version_source=session_profile.qf_version_source,
-            )
-            workspace_version = self._workspace_version_summary(
-                self._fetch_workspace_account_info(active_context),
-                workspace_base_info=self._fetch_workspace_base_info(active_context),
-                workspace_detail=result,
-            )
+    @tool_cn_name("工作区详情")
+    def workspace_get(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict[str, Any]:
+        """读取单个工作区详情，并尽量补齐真实 systemVersion。"""
+
+        def runner(session_profile, context):
+            target_ws_id = ws_id or (session_profile.selected_ws_id if session_profile is not None else None)
+            if target_ws_id is None or target_ws_id <= 0:
+                raise_tool_error(QingflowApiError.workspace_not_selected(profile))
+            workspace = self._fetch_workspace_with_fallback(context, ws_id=target_ws_id)
+            system_version = self._workspace_system_version(workspace)
             return {
                 "profile": profile,
-                "selected_ws_id": session_profile.selected_ws_id,
-                "selected_ws_name": session_profile.selected_ws_name,
-                "workspace": result,
-                "workspace_version": workspace_version,
-                "qf_version": session_profile.qf_version,
-                "qf_version_source": session_profile.qf_version_source,
-                "request_route": self.backend.describe_route(
-                    active_context
-                ),
+                "ws_id": target_ws_id,
+                "qf_version": system_version,
+                "qf_version_source": "workspace_system_version" if system_version else "unverified",
+                "workspace": workspace,
             }
 
         return self._run(profile, runner, require_workspace=False)
 
-    def _workspace_from_list(self, context: BackendRequestContext, ws_id: int) -> dict[str, Any] | None:
-        try:
-            payload = self.backend.request(
-                "POST",
-                context,
-                "/user/workspaceList/pageQuery",
-                json_body={"pageNum": 1, "pageSize": 100, "authList": [0, 1, 2]},
-            )
-        except Exception:
-            return None
-        workspaces = payload.get("list", []) if isinstance(payload, dict) else []
-        found = next(
-            (
-                item
-                for item in workspaces
-                if isinstance(item, dict) and item.get("wsId") == ws_id
-            ),
-            None,
-        )
-        return found if isinstance(found, dict) else None
-
-    def _workspace_system_version(self, workspace: Any) -> str | None:
-        if not isinstance(workspace, dict):
-            return None
-        value = workspace.get("systemVersion")
-        if value is None:
-            return None
-        normalized = str(value).strip()
-        return normalized or None
-
-    def _fetch_workspace_base_info(self, context: BackendRequestContext) -> dict[str, Any] | None:
-        try:
-            payload = self.backend.request("GET", context, "/ws/baseInfo")
-        except QingflowApiError:
-            return None
-        return payload if isinstance(payload, dict) else None
-
-    def _fetch_workspace_account_info(self, context: BackendRequestContext) -> dict[str, Any] | None:
-        try:
-            payload = self.backend.request("GET", context, "/ws/account")
-        except QingflowApiError:
-            return None
-        return payload if isinstance(payload, dict) else None
-
-    def _workspace_version_summary(
-        self,
-        payload: Any,
-        *,
-        workspace_base_info: Any,
-        workspace_detail: Any,
-    ) -> dict[str, Any]:
-        account_info = payload if isinstance(payload, dict) else {}
-        base_info = workspace_base_info if isinstance(workspace_base_info, dict) else {}
-        detail_info = workspace_detail if isinstance(workspace_detail, dict) else {}
-        level_code = self._first_present_int(
-            account_info.get("accountLevel"),
-            base_info.get("accountLevel"),
-            detail_info.get("accountLevel"),
-        )
-        level_name = self._account_level_name(level_code)
-        return {
-            "level_code": level_code,
-            "level_name": level_name,
-            "display_name": self._account_level_display_name(level_name),
-            "being_trial": self._first_present_bool(
-                account_info.get("trial"),
-                base_info.get("trial"),
-                detail_info.get("trial"),
-            ),
-            "expire_date": self._first_present_value(
-                account_info.get("expireDate"),
-                base_info.get("expireDate"),
-                detail_info.get("expireDate"),
-            ),
-        }
-
-    def _account_level_name(self, level_code: int | None) -> str | None:
-        mapping = {
-            0: "FREE",
-            10: "AIR",
-            20: "BASIC",
-            30: "TEAM",
-            35: "PROFESSIONAL",
-            40: "ENTERPRISE",
-        }
-        return mapping.get(level_code)
-
-    def _account_level_display_name(self, level_name: str | None) -> str | None:
-        mapping = {
-            "FREE": "免费版",
-            "AIR": "Air版",
-            "BASIC": "Pro版",
-            "TEAM": "团队版",
-            "PROFESSIONAL": "专业版",
-            "ENTERPRISE": "企业版",
-        }
-        return mapping.get(level_name)
-
-    def _coerce_int(self, value: Any) -> int | None:
-        if isinstance(value, bool) or value is None:
-            return None
-        if isinstance(value, int):
-            return value
-        try:
-            return int(str(value).strip())
-        except (TypeError, ValueError):
-            return None
-
-    def _coerce_bool(self, value: Any) -> bool | None:
-        if isinstance(value, bool):
-            return value
-        if value is None:
-            return None
-        normalized = str(value).strip().lower()
-        if normalized in {"true", "1"}:
-            return True
-        if normalized in {"false", "0"}:
-            return False
-        return None
-
-    def _first_present_int(self, *values: Any) -> int | None:
-        for value in values:
-            coerced = self._coerce_int(value)
-            if coerced is not None:
-                return coerced
-        return None
-
-    def _first_present_bool(self, *values: Any) -> bool | None:
-        for value in values:
-            coerced = self._coerce_bool(value)
-            if coerced is not None:
-                return coerced
-        return None
-
-    def _first_present_value(self, *values: Any) -> Any:
-        for value in values:
-            if value is not None:
-                return value
-        return None
-
+    @tool_cn_name("设置工作区插件状态")
     def workspace_set_plugin_status(
         self,
         *,
@@ -313,6 +136,7 @@ class WorkspaceTools(ToolBase):
         plugin_id: int,
         being_installed: bool = True,
     ) -> dict[str, Any]:
+        """执行工作区相关逻辑。"""
         if plugin_id <= 0:
             raise_tool_error(QingflowApiError.config_error("plugin_id must be positive"))
 
@@ -334,3 +158,62 @@ class WorkspaceTools(ToolBase):
             }
 
         return self._run(profile, runner)
+
+    def _fetch_workspace_with_fallback(
+        self,
+        context: BackendRequestContext,
+        *,
+        ws_id: int,
+    ) -> dict[str, Any]:
+        workspace = self.backend.request("GET", context, f"/user/workspace/{ws_id}")
+        if not isinstance(workspace, dict):
+            raise_tool_error(QingflowApiError(category="workspace", message=f"Workspace {ws_id} is not accessible"))
+        if self._workspace_needs_list_fallback(workspace):
+            fallback = self._fetch_workspace_from_list(context, ws_id=ws_id)
+            if isinstance(fallback, dict):
+                merged = dict(workspace)
+                for key, value in fallback.items():
+                    if merged.get(key) in (None, "") and value not in (None, ""):
+                        merged[key] = value
+                workspace = merged
+        return workspace
+
+    def _fetch_workspace_from_list(self, context: BackendRequestContext, *, ws_id: int) -> dict[str, Any] | None:
+        payload = self.backend.request(
+            "POST",
+            BackendRequestContext(
+                base_url=context.base_url,
+                token=context.token,
+                ws_id=None,
+                qf_version=context.qf_version,
+                qf_version_source=context.qf_version_source,
+            ),
+            "/user/workspaceList/pageQuery",
+            json_body={"pageNum": 1, "pageSize": 100, "authList": [0, 1, 2, 3]},
+        )
+        workspaces = payload.get("list") if isinstance(payload, dict) else []
+        if not isinstance(workspaces, list):
+            return None
+        found = next(
+            (
+                item
+                for item in workspaces
+                if isinstance(item, dict) and item.get("wsId") == ws_id
+            ),
+            None,
+        )
+        return found if isinstance(found, dict) else None
+
+    def _workspace_needs_list_fallback(self, workspace: dict[str, Any]) -> bool:
+        workspace_name = str(workspace.get("workspaceName") or workspace.get("wsName") or "").strip()
+        system_version = self._workspace_system_version(workspace)
+        return not workspace_name or system_version is None
+
+    def _workspace_system_version(self, workspace: Any) -> str | None:
+        if not isinstance(workspace, dict):
+            return None
+        value = workspace.get("systemVersion")
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None