@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/tools/feedback_tools.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP
+
+from ..backend_client import BackendClient
+from ..config import get_feedback_app_key, get_feedback_base_url, get_feedback_qsource_token, normalize_base_url
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import tool_cn_name
+
+
+CATEGORY_MAP = {
+    "feature_request": "功能需求",
+    "bug_report": "问题反馈",
+    "ux_feedback": "体验建议",
+    "unsupported_scenario": "不支持场景",
+    "other": "其他",
+}
+
+IMPACT_SCOPE_MAP = {
+    "personal": "仅个人",
+    "small_team": "小范围团队",
+    "cross_team": "跨团队",
+    "global": "全局",
+}
+
+
+@dataclass(slots=True)
+class FeedbackTools:
+    backend: BackendClient
+    mcp_side: str
+
+    def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def feedback_submit(
+            category: str = "",
+            title: str = "",
+            description: str = "",
+            expected_behavior: str | None = None,
+            actual_behavior: str | None = None,
+            impact_scope: str | None = None,
+            tool_name: str | None = None,
+            app_key: str | None = None,
+            record_id: str | int | None = None,
+            workflow_node_id: str | int | None = None,
+            note: str | None = None,
+        ) -> JSONObject:
+            """Submit product feedback to the Qingflow MCP team.
+
+            Use this when the current MCP capability is unsupported, awkward, or still cannot satisfy the user's need
+            after reasonable attempts. This helper writes through the internal q-source feedback intake, does not
+            require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+            """
+            return self.feedback_submit(
+                category=category,
+                title=title,
+                description=description,
+                expected_behavior=expected_behavior,
+                actual_behavior=actual_behavior,
+                impact_scope=impact_scope,
+                tool_name=tool_name,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                note=note,
+            )
+
+    @tool_cn_name("提交反馈")
+    def feedback_submit(
+        self,
+        *,
+        category: str,
+        title: str,
+        description: str,
+        expected_behavior: str | None,
+        actual_behavior: str | None,
+        impact_scope: str | None,
+        tool_name: str | None,
+        app_key: str | None,
+        record_id: str | int | None,
+        workflow_node_id: str | int | None,
+        note: str | None,
+    ) -> JSONObject:
+        """执行工具方法逻辑。"""
+        qsource_token = get_feedback_qsource_token()
+        if not qsource_token:
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message=(
+                        "feedback_submit is not configured. Set "
+                        "feedback.qsource_token or QINGFLOW_MCP_FEEDBACK_QSOURCE_TOKEN first."
+                    ),
+                    details={"error_code": "FEEDBACK_NOT_CONFIGURED"},
+                )
+            )
+
+        base_url = get_feedback_base_url()
+        if not base_url:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "feedback_submit requires a base_url. Configure feedback.base_url or default_base_url."
+                )
+            )
+
+        normalized_payload = self._build_payload(
+            category=category,
+            title=title,
+            description=description,
+            expected_behavior=expected_behavior,
+            actual_behavior=actual_behavior,
+            impact_scope=impact_scope,
+            tool_name=tool_name,
+            app_key=app_key,
+            record_id=record_id,
+            workflow_node_id=workflow_node_id,
+            note=note,
+        )
+
+        try:
+            response = self.backend.public_request_with_meta(
+                "POST",
+                base_url,
+                f"/qsource/{qsource_token}",
+                json_body=normalized_payload,
+                unwrap=True,
+                qf_version=None,
+            )
+        except QingflowApiError as exc:
+            raise_tool_error(exc)
+        result = response.data if isinstance(response.data, dict) else {}
+        feedback_request_id = result.get("requestId") if isinstance(result, dict) else None
+
+        return {
+            "ok": True,
+            "request_route": {
+                "base_url": normalize_base_url(base_url) or base_url,
+                "qf_version": None,
+                "qf_version_source": "not_applicable",
+            },
+            "submission_mode": "qsource_passive",
+            "feedback_target": {
+                "app_key": get_feedback_app_key(),
+                "mcp_side": self.mcp_side,
+            },
+            "normalized_payload": normalized_payload,
+            "feedback_request_id": feedback_request_id,
+        }
+
+    def _build_payload(
+        self,
+        *,
+        category: str,
+        title: str,
+        description: str,
+        expected_behavior: str | None,
+        actual_behavior: str | None,
+        impact_scope: str | None,
+        tool_name: str | None,
+        app_key: str | None,
+        record_id: str | int | None,
+        workflow_node_id: str | int | None,
+        note: str | None,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        payload: JSONObject = {
+            "title": self._require_text("title", title),
+            "category": self._normalize_label("category", category, CATEGORY_MAP, required=True),
+            "description": self._require_text("description", description),
+            "submit_method": "AI代提",
+            "status": "待处理",
+            "mcp_side": self.mcp_side,
+        }
+
+        optional_text = {
+            "expected_result": expected_behavior,
+            "actual_behavior": actual_behavior,
+            "tool_name": tool_name,
+            "app_key": app_key,
+            "note": note,
+        }
+        for key, value in optional_text.items():
+            normalized = self._normalize_optional_text(value)
+            if normalized is not None:
+                payload[key] = normalized
+
+        if impact_scope is not None and str(impact_scope).strip():
+            payload["impact_scope"] = self._normalize_label("impact_scope", impact_scope, IMPACT_SCOPE_MAP, required=False)
+
+        if record_id is not None and str(record_id).strip():
+            payload["record_id"] = str(record_id).strip()
+        if workflow_node_id is not None and str(workflow_node_id).strip():
+            payload["workflow_node_id"] = str(workflow_node_id).strip()
+
+        return payload
+
+    def _normalize_label(self, field: str, value: str, mapping: dict[str, str], *, required: bool) -> str:
+        """执行内部辅助逻辑。"""
+        text = str(value or "").strip()
+        if not text:
+            if required:
+                raise_tool_error(QingflowApiError.config_error(f"{field} is required"))
+            return ""
+
+        canonical = text.lower()
+        if canonical in mapping:
+            return mapping[canonical]
+        if text in mapping.values():
+            return text
+        supported_values = list(mapping.keys()) + list(mapping.values())
+        raise_tool_error(
+            QingflowApiError(
+                category="config",
+                message=f"{field} must be one of the supported canonical values or labels",
+                details={
+                    "error_code": "FEEDBACK_INVALID_INPUT",
+                    "field": field,
+                    "supported_values": supported_values,
+                },
+            )
+        )
+
+    def _require_text(self, field: str, value: str) -> str:
+        """执行内部辅助逻辑。"""
+        normalized = str(value or "").strip()
+        if not normalized:
+            raise_tool_error(QingflowApiError.config_error(f"{field} is required"))
+        return normalized
+
+    def _normalize_optional_text(self, value: str | None) -> str | None:
+        """执行内部辅助逻辑。"""
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None

package/src/qingflow_mcp/tools/file_tools.py

@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+import random
+import string
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from mcp.server.fastmcp import FastMCP
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import ToolBase, tool_cn_name
+
+
+ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES = {"40118", 40118}
+LEGACY_OSS_FORM_REQUIRED_KEYS = ("key", "policy", "signature", "ossAccessKeyId")
+
+
+class FileTools(ToolBase):
+    """文件工具（中文名：上传与下载中转）。
+
+    类型：文件传输工具。
+    主要职责：
+    1. 申请上传凭证与上传地址；
+    2. 支持本地路径、URL、Base64 内容三类上传输入；
+    3. 返回标准化文件元信息供导入与记录附件使用。
+    """
+
+    def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def file_get_upload_info(
+            profile: str = DEFAULT_PROFILE,
+            upload_kind: str = "attachment",
+            file_name: str = "",
+            file_size: int = 0,
+            upload_mark: str | None = None,
+            content_type: str | None = None,
+            bucket_type: str | None = None,
+            path_id: int | None = None,
+            file_related_url: str | None = None,
+        ) -> dict[str, Any]:
+            return self.file_get_upload_info(
+                profile=profile,
+                upload_kind=upload_kind,
+                file_name=file_name,
+                file_size=file_size,
+                upload_mark=upload_mark,
+                content_type=content_type,
+                bucket_type=bucket_type,
+                path_id=path_id,
+                file_related_url=file_related_url,
+            )
+
+        @mcp.tool()
+        def file_upload_local(
+            profile: str = DEFAULT_PROFILE,
+            upload_kind: str = "attachment",
+            file_path: str = "",
+            upload_mark: str | None = None,
+            content_type: str | None = None,
+            bucket_type: str | None = None,
+            path_id: int | None = None,
+            file_related_url: str | None = None,
+        ) -> dict[str, Any]:
+            return self.file_upload_local(
+                profile=profile,
+                upload_kind=upload_kind,
+                file_path=file_path,
+                upload_mark=upload_mark,
+                content_type=content_type,
+                bucket_type=bucket_type,
+                path_id=path_id,
+                file_related_url=file_related_url,
+            )
+
+    @tool_cn_name("文件上传信息")
+    def file_get_upload_info(
+        self,
+        *,
+        profile: str,
+        upload_kind: str,
+        file_name: str,
+        file_size: int,
+        upload_mark: str | None = None,
+        content_type: str | None = None,
+        bucket_type: str | None = None,
+        path_id: int | None = None,
+        file_related_url: str | None = None,
+    ) -> dict[str, Any]:
+        """执行文件处理相关逻辑。"""
+        def runner(session_profile, context):
+            upload_info = self._request_upload_info_with_fallback(
+                context,
+                upload_kind=upload_kind,
+                file_name=file_name,
+                file_size=file_size,
+                upload_mark=upload_mark,
+                content_type=content_type,
+                bucket_type=bucket_type,
+                path_id=path_id,
+                file_related_url=file_related_url,
+            )
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "upload_kind": upload_kind,
+                "requested_upload_kind": upload_info["requested_upload_kind"],
+                "effective_upload_kind": upload_info["effective_upload_kind"],
+                "upload_fallback_applied": upload_info["fallback_applied"],
+                "upload_fallback_reason": upload_info["fallback_reason"],
+                "file_name": file_name,
+                "file_size": file_size,
+                "request_route": self.backend.describe_route(context),
+                "result": upload_info["result"],
+            }
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("本地文件上传")
+    def file_upload_local(
+        self,
+        *,
+        profile: str,
+        upload_kind: str,
+        file_path: str,
+        upload_mark: str | None = None,
+        content_type: str | None = None,
+        bucket_type: str | None = None,
+        path_id: int | None = None,
+        file_related_url: str | None = None,
+    ) -> dict[str, Any]:
+        """执行文件处理相关逻辑。"""
+        path = Path(file_path).expanduser()
+        if not path.is_file():
+            raise_tool_error(QingflowApiError.config_error("file_path must point to an existing file"))
+        file_name = path.name
+        file_size = path.stat().st_size
+        resolved_content_type = content_type or mimetypes.guess_type(file_name)[0] or "application/octet-stream"
+
+        def runner(session_profile, context):
+            upload_info = self._request_upload_info_with_fallback(
+                context,
+                upload_kind=upload_kind,
+                file_name=file_name,
+                file_size=file_size,
+                upload_mark=upload_mark,
+                content_type=resolved_content_type,
+                bucket_type=bucket_type,
+                path_id=path_id,
+                file_related_url=file_related_url,
+            )
+            result = upload_info["result"]
+            if not isinstance(result, dict):
+                raise QingflowApiError.config_error("upload endpoint did not return a structured upload payload")
+            content = path.read_bytes()
+            upload_protocol = "binary_put"
+            if self._is_legacy_oss_form_upload(result):
+                upload_result = self._upload_legacy_oss_form(
+                    result,
+                    file_name=file_name,
+                    content=content,
+                    content_type=resolved_content_type,
+                )
+                upload_protocol = "oss_form_post"
+            else:
+                upload_url = str(result.get("uploadUrl") or "").strip()
+                if not upload_url:
+                    raise QingflowApiError.config_error("upload endpoint did not return uploadUrl")
+                upload_result = self.backend.upload_binary(upload_url, content, content_type=resolved_content_type)
+            download_url = result.get("downloadUrl")
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "upload_kind": upload_kind,
+                "requested_upload_kind": upload_info["requested_upload_kind"],
+                "effective_upload_kind": upload_info["effective_upload_kind"],
+                "upload_fallback_applied": upload_info["fallback_applied"],
+                "upload_fallback_reason": upload_info["fallback_reason"],
+                "file_name": file_name,
+                "file_size": file_size,
+                "content_type": resolved_content_type,
+                "request_route": self.backend.describe_route(context),
+                "upload_protocol": upload_protocol,
+                "result": result,
+                "upload_result": upload_result,
+                "download_url": download_url,
+                "attachment_value": {
+                    "value": download_url,
+                    "otherInfo": file_name,
+                    "name": file_name,
+                },
+                "comment_file_info": {
+                    "url": download_url,
+                    "name": file_name,
+                    "uploadFileSize": file_size,
+                },
+            }
+
+        return self._run(profile, runner)
+
+    def _build_file_upload_bo(
+        self,
+        *,
+        upload_kind: str,
+        file_name: str,
+        file_size: int,
+        upload_mark: str | None,
+        content_type: str | None,
+        bucket_type: str | None,
+        path_id: int | None,
+        file_related_url: str | None,
+    ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
+        if not file_name:
+            raise_tool_error(QingflowApiError.config_error("file_name is required"))
+        if file_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("file_size must be positive"))
+        if upload_kind == "attachment" and not upload_mark:
+            raise_tool_error(QingflowApiError.config_error("upload_mark is required for attachment uploads and should usually be the app_key"))
+        payload: dict[str, Any] = {
+            "fileName": file_name,
+            "fileSize": file_size,
+        }
+        if upload_mark:
+            payload["uploadMark"] = upload_mark
+        if content_type:
+            payload["contentType"] = content_type
+        if bucket_type:
+            payload["bucketType"] = bucket_type
+        if path_id is not None:
+            payload["pathId"] = path_id
+        if file_related_url:
+            payload["fileRelatedUrl"] = file_related_url
+        return payload
+
+    def _resolve_upload_endpoint(self, upload_kind: str) -> str:
+        """执行内部辅助逻辑。"""
+        normalized = upload_kind.strip().lower()
+        if normalized == "attachment":
+            return "/upload/puburl"
+        if normalized == "login":
+            return "/upload/url"
+        if normalized == "anonymous":
+            return "/upload/anonymousurl"
+        raise_tool_error(QingflowApiError.config_error("upload_kind must be one of: attachment, login, anonymous"))
+        raise AssertionError("unreachable")
+
+    def _encode_formula(self, formula: str) -> str:
+        """执行内部辅助逻辑。"""
+        encoded = base64.b64encode(quote(formula, safe="").encode("utf-8")).decode("utf-8")
+        return f"{self._random_string(16)}{encoded}{self._random_string(16)}"
+
+    def _random_string(self, length: int) -> str:
+        """执行内部辅助逻辑。"""
+        alphabet = string.ascii_letters + string.digits
+        return "".join(random.choice(alphabet) for _ in range(length))
+
+    def _request_upload_info_with_fallback(
+        self,
+        context,
+        *,
+        upload_kind: str,
+        file_name: str,
+        file_size: int,
+        upload_mark: str | None,
+        content_type: str | None,
+        bucket_type: str | None,
+        path_id: int | None,
+        file_related_url: str | None,
+    ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
+        requested_kind = upload_kind.strip().lower()
+        attempted_kinds = [requested_kind]
+        if requested_kind == "attachment":
+            attempted_kinds.append("login")
+        last_error: QingflowApiError | None = None
+        for current_kind in attempted_kinds:
+            try:
+                result = self._request_upload_info(
+                    context,
+                    upload_kind=current_kind,
+                    file_name=file_name,
+                    file_size=file_size,
+                    upload_mark=upload_mark,
+                    content_type=content_type,
+                    bucket_type=bucket_type,
+                    path_id=path_id,
+                    file_related_url=file_related_url,
+                )
+                return {
+                    "requested_upload_kind": requested_kind,
+                    "effective_upload_kind": current_kind,
+                    "fallback_applied": current_kind != requested_kind,
+                    "fallback_reason": (
+                        f"backend rejected '{requested_kind}' upload info; retried with '{current_kind}'"
+                        if current_kind != requested_kind
+                        else None
+                    ),
+                    "result": result,
+                }
+            except QingflowApiError as error:
+                last_error = error
+                if not self._should_retry_attachment_upload_info(requested_kind, current_kind, error):
+                    raise
+        assert last_error is not None
+        raise last_error
+
+    def _request_upload_info(
+        self,
+        context,
+        *,
+        upload_kind: str,
+        file_name: str,
+        file_size: int,
+        upload_mark: str | None,
+        content_type: str | None,
+        bucket_type: str | None,
+        path_id: int | None,
+        file_related_url: str | None,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        endpoint = self._resolve_upload_endpoint(upload_kind)
+        file_upload_bo = self._build_file_upload_bo(
+            upload_kind=upload_kind,
+            file_name=file_name,
+            file_size=file_size,
+            upload_mark=upload_mark,
+            content_type=content_type,
+            bucket_type=bucket_type,
+            path_id=path_id,
+            file_related_url=file_related_url,
+        )
+        encrypted_payload = {
+            "upload": self._encode_formula(json.dumps(file_upload_bo, ensure_ascii=False, separators=(",", ":"))),
+            "fileName": file_name,
+            "fileSize": file_size,
+        }
+        if path_id is not None:
+            encrypted_payload["pathId"] = path_id
+        if bucket_type:
+            encrypted_payload["bucketType"] = bucket_type
+        result = self.backend.request("POST", context, endpoint, json_body=encrypted_payload)
+        if not isinstance(result, dict):
+            raise QingflowApiError.config_error("upload endpoint did not return a structured upload payload")
+        return result
+
+    def _should_retry_attachment_upload_info(
+        self,
+        requested_kind: str,
+        attempted_kind: str,
+        error: QingflowApiError,
+    ) -> bool:
+        """执行内部辅助逻辑。"""
+        return (
+            requested_kind == "attachment"
+            and attempted_kind == "attachment"
+            and error.backend_code in ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES
+        )
+
+    def _is_legacy_oss_form_upload(self, payload: JSONObject) -> bool:
+        """执行内部辅助逻辑。"""
+        return all(str(payload.get(key) or "").strip() for key in LEGACY_OSS_FORM_REQUIRED_KEYS)
+
+    def _upload_legacy_oss_form(
+        self,
+        upload_info: JSONObject,
+        *,
+        file_name: str,
+        content: bytes,
+        content_type: str,
+    ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
+        upload_url = self._resolve_legacy_oss_form_url(upload_info)
+        if not upload_url:
+            raise QingflowApiError.config_error("legacy upload payload is missing host/uploadAccelerateHost")
+        form_fields = {
+            "key": str(upload_info["key"]),
+            "policy": str(upload_info["policy"]),
+            "signature": str(upload_info["signature"]),
+            "OSSAccessKeyId": str(upload_info["ossAccessKeyId"]),
+        }
+        callback = str(upload_info.get("callback") or "").strip()
+        if callback:
+            form_fields["callback"] = callback
+        return self.backend.upload_form_file(
+            upload_url,
+            form_fields=form_fields,
+            file_field="file",
+            file_name=file_name,
+            content=content,
+            content_type=content_type,
+        )
+
+    def _resolve_legacy_oss_form_url(self, upload_info: JSONObject) -> str:
+        """执行内部辅助逻辑。"""
+        for key in ("uploadAccelerateHost", "host", "uploadUrl"):
+            value = str(upload_info.get(key) or "").strip()
+            if not value:
+                continue
+            if value.startswith(("http://", "https://")):
+                return value
+            return f"https://{value.lstrip('/')}"
+        return ""