@josephyan/qingflow-cli 0.2.0-beta.55 → 0.2.0-beta.57

package/src/qingflow_mcp/cli/main.py

@@ -1,23 +1,23 @@
 from __future__ import annotations
 
 import argparse
-import json
 import sys
 from typing import Any, Callable, TextIO
 
 from ..errors import QingflowApiError
+from ..ops.base import normalize_exception
+from .commands import register_all_commands
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
-from .commands import register_all_commands
 
 
 Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI")
+    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI 2.0")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
-    parser.add_argument("--json", action="store_true", help="输出原始 JSON")
+    parser.add_argument("--json", action="store_true", help="输出结构化 JSON")
     subparsers = parser.add_subparsers(dest="command", required=True)
     register_all_commands(subparsers)
     return parser
@@ -46,15 +46,16 @@ def run(
     if handler is None:
         parser.print_help(out)
         return 2
+
     context = context_factory()
     try:
         result = handler(args, context)
     except RuntimeError as exc:
-        payload = _parse_error_payload(exc)
-        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+        result = normalize_exception(exc)
     except QingflowApiError as exc:
-        payload = exc.to_dict()
-        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+        result = normalize_exception(exc)
+    except Exception as exc:  # noqa: BLE001
+        result = normalize_exception(exc)
     finally:
         context.close()
 
@@ -94,53 +95,17 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
     return global_args + remaining
 
 
-def _parse_error_payload(exc: RuntimeError) -> dict[str, Any]:
-    raw = str(exc)
-    try:
-        payload = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"category": "runtime", "message": raw}
-    return payload if isinstance(payload, dict) else {"category": "runtime", "message": raw}
-
-
-def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, stderr: TextIO) -> int:
-    exit_code = _error_exit_code(payload)
-    if json_mode:
-        emit_json_result(payload, stream=stdout)
-        return exit_code
-    lines = [
-        f"Category: {payload.get('category') or 'error'}",
-        f"Message: {payload.get('message') or 'Unknown error'}",
-    ]
-    if payload.get("backend_code") is not None:
-        lines.append(f"Backend Code: {payload.get('backend_code')}")
-    if payload.get("request_id"):
-        lines.append(f"Request ID: {payload.get('request_id')}")
-    details = payload.get("details")
-    if isinstance(details, dict):
-        for key, value in details.items():
-            if isinstance(value, (str, int, float, bool)) or value is None:
-                lines.append(f"{key}: {value}")
-    stderr.write("\n".join(lines) + "\n")
-    return exit_code
-
-
-def _error_exit_code(payload: dict[str, Any]) -> int:
-    category = str(payload.get("category") or "").lower()
-    if category in {"auth", "workspace"}:
-        return 3
-    return 4
-
-
 def _result_exit_code(result: dict[str, Any]) -> int:
     if not isinstance(result, dict):
         return 0
-    if result.get("ok") is False:
-        return 4
-    status = str(result.get("status") or "").lower()
-    if status in {"failed", "blocked"}:
-        return 4
-    return 0
+    if result.get("ok") is not False:
+        return 0
+    code = str(result.get("code") or "").upper()
+    if code in {"AUTH_REQUIRED", "WORKSPACE_NOT_SELECTED"}:
+        return 3
+    if code in {"INVALID_ARGUMENT", "CONFIG"}:
+        return 2
+    return 4
 
 
 if __name__ == "__main__":

package/src/qingflow_mcp/ops/__init__.py

@@ -0,0 +1,3 @@
+from .context import OperationsRuntime, build_operations_runtime
+
+__all__ = ["OperationsRuntime", "build_operations_runtime"]

package/src/qingflow_mcp/ops/apps.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import normalize_exception, success_result
+
+
+class AppOperations:
+    def __init__(self, tools: Any) -> None:
+        self._tools = tools
+
+    def list(self, *, profile: str) -> dict:
+        try:
+            raw = self._tools.app.app_list(profile=profile)
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        items = raw.get("items") if isinstance(raw.get("items"), list) else []
+        return success_result(
+            "APPS_LISTED",
+            "已读取应用列表",
+            data={"items": items, "count": raw.get("count", len(items))},
+            meta={"profile": profile, "workspace_id": raw.get("ws_id")},
+            legacy=raw,
+        )
+
+    def find(self, *, profile: str, keyword: str, page_num: int, page_size: int) -> dict:
+        try:
+            raw = self._tools.app.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        return success_result(
+            "APPS_FOUND",
+            "已完成应用搜索",
+            data={
+                "items": raw.get("items") if isinstance(raw.get("items"), list) else [],
+                "total": raw.get("total"),
+                "keyword": keyword,
+                "page_num": page_num,
+                "page_size": page_size,
+            },
+            meta={"profile": profile, "workspace_id": raw.get("ws_id")},
+            legacy=raw,
+        )
+
+    def show(self, *, profile: str, app_key: str) -> dict:
+        try:
+            raw = self._tools.app.app_get(profile=profile, app_key=app_key)
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        data = raw.get("data") if isinstance(raw.get("data"), dict) else {}
+        return success_result(
+            "APP_SHOWN",
+            "已读取应用信息",
+            data={
+                "app_key": data.get("app_key", app_key),
+                "app_name": data.get("app_name"),
+                "can_create": data.get("can_create"),
+                "import_capability": data.get("import_capability"),
+                "accessible_views": data.get("accessible_views") if isinstance(data.get("accessible_views"), list) else [],
+            },
+            warnings=raw.get("warnings") if isinstance(raw.get("warnings"), list) else [],
+            meta={"profile": profile, "workspace_id": raw.get("ws_id"), "request_route": raw.get("request_route")},
+            legacy=raw,
+        )

package/src/qingflow_mcp/ops/auth.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import normalize_exception, success_result
+
+
+class AuthOperations:
+    def __init__(self, tools: Any) -> None:
+        self._tools = tools
+
+    def login(
+        self,
+        *,
+        profile: str,
+        base_url: str | None,
+        qf_version: str | None,
+        email: str,
+        password: str,
+        persist: bool,
+    ) -> dict:
+        try:
+            raw = self._tools.auth.auth_login(
+                profile=profile,
+                base_url=base_url,
+                qf_version=qf_version,
+                email=email,
+                password=password,
+                persist=persist,
+            )
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        return success_result(
+            "AUTHENTICATED",
+            "登录成功",
+            data=_auth_payload(raw),
+            meta={"profile": profile},
+            legacy=raw,
+        )
+
+    def use_token(
+        self,
+        *,
+        profile: str,
+        base_url: str | None,
+        qf_version: str | None,
+        token: str,
+        ws_id: int | None,
+        persist: bool,
+    ) -> dict:
+        try:
+            raw = self._tools.auth.auth_use_token(
+                profile=profile,
+                base_url=base_url,
+                qf_version=qf_version,
+                token=token,
+                ws_id=ws_id,
+                persist=persist,
+            )
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        return success_result(
+            "TOKEN_ACCEPTED",
+            "已接入会话令牌",
+            data=_auth_payload(raw),
+            meta={"profile": profile},
+            legacy=raw,
+        )
+
+    def me(self, *, profile: str) -> dict:
+        try:
+            raw = self._tools.auth.auth_whoami(profile=profile)
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        return success_result(
+            "SESSION_READY",
+            "当前会话已就绪",
+            data=_auth_payload(raw),
+            meta={"profile": profile},
+            legacy=raw,
+        )
+
+    def logout(self, *, profile: str, forget_persisted: bool) -> dict:
+        try:
+            raw = self._tools.auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
+        except Exception as error:  # noqa: BLE001
+            return normalize_exception(error)
+        return success_result(
+            "SESSION_CLEARED",
+            "已退出当前会话",
+            data={
+                "profile": raw.get("profile", profile),
+                "logged_out": bool(raw.get("logged_out", True)),
+                "forgot_persisted": bool(raw.get("forgot_persisted", forget_persisted)),
+            },
+            meta={"profile": profile},
+            legacy=raw,
+        )
+
+
+def _auth_payload(raw: dict) -> dict:
+    return {
+        "profile": raw.get("profile"),
+        "base_url": raw.get("base_url"),
+        "qf_version": raw.get("qf_version"),
+        "qf_version_source": raw.get("qf_version_source"),
+        "user": {
+            "uid": raw.get("uid"),
+            "email": raw.get("email"),
+            "nick_name": raw.get("nick_name"),
+        },
+        "workspace": {
+            "ws_id": raw.get("selected_ws_id"),
+            "name": raw.get("selected_ws_name"),
+        },
+        "suggested_workspace": {
+            "ws_id": raw.get("suggested_ws_id"),
+            "name": raw.get("suggested_ws_name"),
+        },
+        "persisted": bool(raw.get("persisted")),
+    }

package/src/qingflow_mcp/ops/base.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..errors import QingflowApiError
+from ..json_types import JSONObject
+
+
+_COMMON_KEYS = {
+    "ok",
+    "status",
+    "message",
+    "error_code",
+    "details",
+    "warnings",
+    "verification",
+    "profile",
+    "ws_id",
+    "request_id",
+    "request_route",
+    "output_profile",
+    "recoverable",
+    "missing_fields",
+    "allowed_values",
+    "suggested_next_call",
+    "noop",
+    "compact",
+    "summary",
+}
+
+_INTERNAL_LEGACY_KEY = "__legacy__"
+
+
+def success_result(
+    code: str,
+    message: str,
+    *,
+    data: Any = None,
+    warnings: list[Any] | None = None,
+    meta: JSONObject | None = None,
+    legacy: Any = None,
+) -> JSONObject:
+    payload: JSONObject = {
+        "ok": True,
+        "code": code,
+        "message": message,
+        "data": data if data is not None else {},
+        "warnings": list(warnings or []),
+        "meta": dict(meta or {}),
+    }
+    if legacy is not None:
+        payload[_INTERNAL_LEGACY_KEY] = legacy
+    return payload
+
+
+def error_result(
+    code: str,
+    message: str,
+    *,
+    details: Any = None,
+    suggested_next: Any = None,
+    meta: JSONObject | None = None,
+    legacy: Any = None,
+) -> JSONObject:
+    payload: JSONObject = {
+        "ok": False,
+        "code": code,
+        "message": message,
+        "details": details if details is not None else {},
+        "meta": dict(meta or {}),
+    }
+    if suggested_next is not None:
+        payload["suggested_next"] = suggested_next
+    if legacy is not None:
+        payload[_INTERNAL_LEGACY_KEY] = legacy
+    return payload
+
+
+def build_meta(raw: Any, *, extra: JSONObject | None = None) -> JSONObject:
+    meta: JSONObject = {}
+    if isinstance(raw, dict):
+        if raw.get("profile") is not None:
+            meta["profile"] = raw.get("profile")
+        if raw.get("ws_id") is not None:
+            meta["workspace_id"] = raw.get("ws_id")
+        if raw.get("request_id") is not None:
+            meta["request_id"] = raw.get("request_id")
+        if isinstance(raw.get("request_route"), dict):
+            meta["request_route"] = raw.get("request_route")
+        if isinstance(raw.get("verification"), dict) and raw.get("verification"):
+            meta["verification"] = raw.get("verification")
+    if extra:
+        meta.update(extra)
+    return meta
+
+
+def collect_warnings(raw: Any) -> list[Any]:
+    warnings: list[Any] = []
+    if isinstance(raw, dict):
+        if isinstance(raw.get("warnings"), list):
+            warnings.extend(raw["warnings"])
+        status = str(raw.get("status") or "").lower()
+        if status == "partial_success":
+            warnings.append(
+                {
+                    "code": "PARTIAL_SUCCESS",
+                    "message": str(raw.get("message") or "operation completed with warnings"),
+                }
+            )
+    return warnings
+
+
+def tool_payload(raw: Any) -> Any:
+    if not isinstance(raw, dict):
+        return raw
+    if "data" in raw:
+        return raw.get("data")
+    if "items" in raw:
+        return {
+            "items": raw.get("items") if isinstance(raw.get("items"), list) else [],
+            "count": raw.get("count"),
+        }
+    if "page" in raw:
+        page = raw.get("page")
+        if isinstance(page, dict):
+            return {
+                "items": page.get("list") if isinstance(page.get("list"), list) else [],
+                "page": page,
+            }
+    if "result" in raw:
+        return raw.get("result")
+    return {key: value for key, value in raw.items() if key not in _COMMON_KEYS}
+
+
+def is_failed_tool_result(raw: Any) -> bool:
+    if not isinstance(raw, dict):
+        return False
+    if raw.get("ok") is False:
+        return True
+    status = str(raw.get("status") or "").lower()
+    return status in {"failed", "blocked"}
+
+
+def tool_result_to_cli(
+    raw: Any,
+    *,
+    code: str,
+    message: str,
+    data: Any = None,
+    meta: JSONObject | None = None,
+) -> JSONObject:
+    if is_failed_tool_result(raw):
+        payload = normalize_tool_error(raw)
+        payload["meta"] = build_meta(raw, extra=meta)
+        return payload
+    return success_result(
+        code,
+        message,
+        data=tool_payload(raw) if data is None else data,
+        warnings=collect_warnings(raw),
+        meta=build_meta(raw, extra=meta),
+    )
+
+
+def normalize_tool_error(raw: Any) -> JSONObject:
+    if isinstance(raw, dict):
+        details = raw.get("details")
+        if not isinstance(details, dict):
+            details = {}
+        if raw.get("backend_code") is not None:
+            details.setdefault("backend_code", raw.get("backend_code"))
+        if raw.get("request_id") is not None:
+            details.setdefault("request_id", raw.get("request_id"))
+        if raw.get("verification") not in (None, {}):
+            details.setdefault("verification", raw.get("verification"))
+        return error_result(
+            str(raw.get("error_code") or raw.get("code") or raw.get("category") or "OPERATION_FAILED"),
+            str(raw.get("message") or "operation failed"),
+            details=details,
+            suggested_next=raw.get("suggested_next_call"),
+            legacy=raw,
+        )
+    return error_result("OPERATION_FAILED", str(raw))
+
+
+def coerce_runtime_error(exc: RuntimeError) -> QingflowApiError:
+    raw = str(exc)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return QingflowApiError(category="runtime", message=raw)
+    if not isinstance(payload, dict):
+        return QingflowApiError(category="runtime", message=raw)
+    return QingflowApiError(
+        category=str(payload.get("category") or "runtime"),
+        message=str(payload.get("message") or raw),
+        backend_code=payload.get("backend_code"),
+        request_id=payload.get("request_id"),
+        details=payload.get("details") if isinstance(payload.get("details"), dict) else None,
+    )
+
+
+def normalize_exception(error: Exception) -> JSONObject:
+    if isinstance(error, RuntimeError):
+        api_error = coerce_runtime_error(error)
+    elif isinstance(error, QingflowApiError):
+        api_error = error
+    else:
+        return error_result("RUNTIME_ERROR", str(error))
+
+    details = dict(api_error.details or {})
+    if api_error.backend_code is not None:
+        details.setdefault("backend_code", api_error.backend_code)
+    if api_error.request_id is not None:
+        details.setdefault("request_id", api_error.request_id)
+    code = str(details.pop("error_code", None) or api_error.category or "OPERATION_FAILED").upper()
+    if code == "CONFIG":
+        code = "INVALID_ARGUMENT"
+    elif code == "AUTH":
+        code = "AUTH_REQUIRED"
+    elif code == "WORKSPACE":
+        code = "WORKSPACE_NOT_SELECTED"
+    legacy_payload = None
+    if isinstance(error, RuntimeError):
+        raw = str(error)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            parsed = None
+        if isinstance(parsed, dict):
+            legacy_payload = parsed
+    return error_result(code, api_error.message, details=details, legacy=legacy_payload)
+
+
+def public_result(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        return {
+            key: public_result(value)
+            for key, value in payload.items()
+            if key != _INTERNAL_LEGACY_KEY
+        }
+    if isinstance(payload, list):
+        return [public_result(item) for item in payload]
+    return payload
+
+
+def mcp_result_from_operation(result: Any) -> Any:
+    if not isinstance(result, dict):
+        return result
+    legacy = result.get(_INTERNAL_LEGACY_KEY)
+    if isinstance(legacy, dict):
+        return legacy
+    meta = result.get("meta") if isinstance(result.get("meta"), dict) else {}
+    if result.get("ok") is False:
+        payload: JSONObject = {
+            "ok": False,
+            "status": "failed",
+            "error_code": result.get("code") or "OPERATION_FAILED",
+            "message": result.get("message") or "operation failed",
+            "details": result.get("details") if isinstance(result.get("details"), dict) else {},
+            "warnings": result.get("warnings") if isinstance(result.get("warnings"), list) else [],
+        }
+        if isinstance(meta.get("request_route"), dict):
+            payload["request_route"] = meta["request_route"]
+        if isinstance(meta.get("verification"), dict):
+            payload["verification"] = meta["verification"]
+        if meta.get("profile") is not None:
+            payload["profile"] = meta.get("profile")
+        if meta.get("workspace_id") is not None:
+            payload["ws_id"] = meta.get("workspace_id")
+        if result.get("suggested_next") is not None:
+            payload["suggested_next_call"] = result.get("suggested_next")
+        return payload
+    payload = {
+        "ok": True,
+        "status": "success",
+        "message": result.get("message") or "ok",
+        "data": result.get("data"),
+        "warnings": result.get("warnings") if isinstance(result.get("warnings"), list) else [],
+    }
+    if isinstance(meta.get("request_route"), dict):
+        payload["request_route"] = meta["request_route"]
+    if isinstance(meta.get("verification"), dict):
+        payload["verification"] = meta["verification"]
+    if meta.get("profile") is not None:
+        payload["profile"] = meta.get("profile")
+    if meta.get("workspace_id") is not None:
+        payload["ws_id"] = meta.get("workspace_id")
+    return payload