@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/tools/workflow_tools.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+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, 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)
+
+        @mcp.tool()
+        def workflow_get_node_detail(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
+            return self.workflow_get_node_detail(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
+
+        @mcp.tool()
+        def workflow_get_global_settings(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.workflow_get_global_settings(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def workflow_get_future_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> JSONObject:
+            return self.workflow_get_future_nodes(profile=profile, app_key=app_key, apply_id=apply_id)
+
+        @mcp.tool()
+        def workflow_get_future_nodes_app(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            apply_id: int = 0,
+            role: int = 1,
+            audit_node_id: int | None = None,
+        ) -> JSONObject:
+            return self.workflow_get_future_nodes_app(
+                profile=profile,
+                app_key=app_key,
+                apply_id=apply_id,
+                role=role,
+                audit_node_id=audit_node_id,
+            )
+
+        @mcp.tool()
+        def workflow_get_qsource_active(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
+            return self.workflow_get_qsource_active(profile=profile, app_key=app_key, qsource_id=qsource_id)
+
+        @mcp.tool()
+        def workflow_get_qsource_passive(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
+            return self.workflow_get_qsource_passive(profile=profile, app_key=app_key, qsource_id=qsource_id)
+
+        @mcp.tool()
+        def workflow_get_editable_question_ids(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
+            return self.workflow_get_editable_question_ids(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
+
+        @mcp.tool()
+        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(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/auditNodes",
+            json_body=body,
+            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)
+        return self._request_with_post_fallbacks(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/auditNodes/{audit_node_id}",
+            json_body=body,
+            alternate_paths=[f"/app/{app_key}/auditNode/{audit_node_id}"],
+            risk_operation="update",
+            risk_target="workflow node configuration",
+            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(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/workflow/global/setting",
+            json_body=body,
+            alternate_paths=[],
+            risk_operation="update",
+            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(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/publish",
+            json_body=body,
+            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,
+        *,
+        profile: str,
+        app_key: str,
+        apply_id: int,
+        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}
+        if audit_node_id is not None:
+            self._require_positive("audit_node_id", audit_node_id)
+            params["auditNodeId"] = audit_node_id
+        return self._request(
+            profile,
+            "GET",
+            f"/app/{app_key}/auditNode/appFutureListV2/{apply_id}",
+            app_key=app_key,
+            apply_id=apply_id,
+            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(
+            profile,
+            "GET",
+            f"/app/{app_key}/auditNode/{audit_node_id}/editableQueIds",
+            app_key=app_key,
+            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)
+
+    def _request(
+        self,
+        profile: str,
+        method: str,
+        path: str,
+        *,
+        app_key: str,
+        json_body: JSONValue = None,
+        params: JSONObject | None = None,
+        risk_operation: str | None = None,
+        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}
+            response.update(extra)
+            if risk_operation and risk_target:
+                return self._attach_human_review_notice(response, operation=risk_operation, target=risk_target)
+            return response
+
+        return self._run(profile, runner)
+
+    def _request_with_post_fallbacks(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        path: str,
+        json_body: JSONObject,
+        alternate_paths: list[str],
+        risk_operation: str | None = None,
+        risk_target: str | None = None,
+        **extra: JSONValue,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        def runner(session_profile, context):
+            attempted_contexts = [context]
+            if context.qf_version is not None:
+                attempted_contexts.append(
+                    BackendRequestContext(
+                        base_url=context.base_url,
+                        token=context.token,
+                        ws_id=context.ws_id,
+                        qf_version=None,
+                        qf_version_source="workflow_retry_without_qf_version",
+                    )
+                )
+            paths = [path, *alternate_paths]
+            last_error: QingflowApiError | None = None
+            for call_context in attempted_contexts:
+                for candidate_path in paths:
+                    try:
+                        result = self.backend.request("POST", call_context, candidate_path, json_body=json_body)
+                        response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+                        response.update(extra)
+                        if risk_operation and risk_target:
+                            return self._attach_human_review_notice(response, operation=risk_operation, target=risk_target)
+                        return response
+                    except QingflowApiError as error:
+                        last_error = error
+                        if error.http_status != 404:
+                            raise
+            assert last_error is not None
+            raise last_error
+
+        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

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from typing import Any
+
+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, tool_cn_name
+
+
+class WorkspaceTools(ToolBase):
+    """工作区工具（中文名：工作区与插件管理）。
+
+    类型：基础上下文工具。
+    主要职责：
+    1. 查询当前用户可见工作区列表；
+    2. 管理工作区插件安装状态。
+    """
+
+    def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def workspace_list(
+            profile: str = DEFAULT_PROFILE,
+            page_num: int = 1,
+            page_size: int = 20,
+            include_external: bool = False,
+        ) -> dict[str, Any]:
+            return self.workspace_list(
+                profile=profile,
+                page_num=page_num,
+                page_size=page_size,
+                include_external=include_external,
+            )
+
+        @mcp.tool()
+        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_select(
+            profile: str = DEFAULT_PROFILE,
+            ws_id: int = 0,
+        ) -> dict[str, Any]:
+            return self.workspace_select(
+                profile=profile,
+                ws_id=ws_id,
+            )
+
+        @mcp.tool()
+        def workspace_set_plugin_status(
+            profile: str = DEFAULT_PROFILE,
+            plugin_id: int = 0,
+            being_installed: bool = True,
+        ) -> dict[str, Any]:
+            return self.workspace_set_plugin_status(
+                profile=profile,
+                plugin_id=plugin_id,
+                being_installed=being_installed,
+            )
+
+    @tool_cn_name("工作区列表")
+    def workspace_list(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        page_num: int = 1,
+        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"))
+
+        def runner(_, context):
+            path = "/user/allWorkspaceList/pageQuery" if include_external else "/user/workspaceList/pageQuery"
+            result = self.backend.request(
+                "POST",
+                context,
+                path,
+                json_body={"pageNum": page_num, "pageSize": page_size, "authList": [0, 1, 2]},
+            )
+            normalized = result if isinstance(result, dict) else {"list": result if isinstance(result, list) else []}
+            workspace_list = normalized.get("list") if isinstance(normalized.get("list"), list) else []
+            selected_ws_id = _.selected_ws_id if _ is not None else None
+            if selected_ws_id and not any(isinstance(item, dict) and item.get("wsId") == selected_ws_id for item in workspace_list):
+                try:
+                    selected_workspace = self.backend.request("GET", context, f"/user/workspace/{selected_ws_id}")
+                except QingflowApiError:
+                    selected_workspace = {
+                        "wsId": selected_ws_id,
+                        "workspaceName": _.selected_ws_name if _ is not None else None,
+                    }
+                if isinstance(selected_workspace, dict):
+                    workspace_list.append(selected_workspace)
+                    normalized["list"] = workspace_list
+                    total = normalized.get("total")
+                    if isinstance(total, int):
+                        normalized["total"] = total + 1
+            return {
+                "profile": profile,
+                "include_external": include_external,
+                "page": normalized,
+            }
+
+        return self._run(profile, runner, require_workspace=False)
+
+    @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,
+                "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)
+
+    @tool_cn_name("切换工作区")
+    def workspace_select(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int,
+    ) -> dict[str, Any]:
+        """切换当前 profile 选中的工作区，并尽量同步真实 systemVersion。"""
+        if ws_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("ws_id must be positive"))
+
+        def runner(_, context):
+            workspace = self._fetch_workspace_with_fallback(context, ws_id=ws_id)
+            workspace_name = str(workspace.get("workspaceName") or workspace.get("wsName") or workspace.get("remark") or "").strip() or None
+            selected = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=workspace_name)
+            system_version = self._workspace_system_version(workspace)
+            qf_version_source = "workspace_system_version" if system_version else "unverified"
+            if system_version:
+                selected = self.sessions.update_route(
+                    profile,
+                    qf_version=system_version,
+                    qf_version_source=qf_version_source,
+                )
+            return {
+                "profile": profile,
+                "ws_id": ws_id,
+                "qf_version": selected.qf_version,
+                "qf_version_source": selected.qf_version_source or qf_version_source,
+                "workspace": workspace,
+                "selected": {
+                    "ws_id": selected.selected_ws_id,
+                    "workspace_name": selected.selected_ws_name,
+                },
+            }
+
+        return self._run(profile, runner, require_workspace=False)
+
+    @tool_cn_name("设置工作区插件状态")
+    def workspace_set_plugin_status(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        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"))
+
+        def runner(_, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                "/ws/plugin",
+                json_body={
+                    "pluginId": plugin_id,
+                    "beingInstalled": being_installed,
+                },
+            )
+            return {
+                "profile": profile,
+                "plugin_id": plugin_id,
+                "being_installed": being_installed,
+                "result": result,
+            }
+
+        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