@josephyan/qingflow-app-user-mcp 0.2.0-beta.20 → 0.2.0-beta.21

package/src/qingflow_mcp/tools/task_tools.py

@@ -9,6 +9,26 @@ from ..errors import QingflowApiError, raise_tool_error
 from ..list_type_labels import get_record_list_type_label, get_task_type_label
 from .base import ToolBase
 
+TASK_BOX_TO_TYPE = {
+    "todo": 1,
+    "initiated": 2,
+    "cc": 3,
+    "done": 5,
+}
+
+FLOW_STATUS_TO_PROCESS_STATUS = {
+    "all": 1,
+    "in_progress": 2,
+    "approved": 3,
+    "rejected": 4,
+    "pending_fix": 5,
+    "urged": 6,
+    "overdue": 7,
+    "due_soon": 8,
+    "unread": 9,
+    "ended": 10,
+}
+
 
 class TaskTools(ToolBase):
     """任务中心（待办/已办）相关工具
@@ -40,276 +60,278 @@ class TaskTools(ToolBase):
 
     def register(self, mcp: FastMCP) -> None:
         @mcp.tool()
-        def task_list(
+        def task_summary(
             profile: str = DEFAULT_PROFILE,
-            type: int = 1,
-            process_status: int = 1,
             app_key: str | None = None,
-            node_id: int | None = None,
-            search_key: str | None = None,
-            page_num: int = 1,
-            page_size: int = 20,
-            create_time_asc: bool | None = None,
         ) -> dict[str, Any]:
-            """查询任务列表（待办/已办/我发起的/抄送）
-
-            Args:
-                profile: 配置文件名
-                type: 消息类型 (1=待办, 2=我发起的, 3=抄送, 5=已办)
-                process_status: 流程状态 (1=全部, 2=流程中, 3=已通过, 4=已拒绝, 5=待完善, 6=催办, 7=超时, 8=即将超时, 9=未读)
-                app_key: 应用key（可选，用于筛选特定应用）
-                node_id: 节点ID（可选，用于筛选特定节点）
-                search_key: 搜索关键词
-                page_num: 页码，从1开始
-                page_size: 每页数量
-                create_time_asc: 是否按创建时间升序（None表示默认排序）
-            """
-            return self.task_list(
+            return self.task_summary(
                 profile=profile,
-                type=type,
-                process_status=process_status,
                 app_key=app_key,
-                node_id=node_id,
-                search_key=search_key,
-                page_num=page_num,
-                page_size=page_size,
-                create_time_asc=create_time_asc,
             )
 
         @mcp.tool()
-        def task_list_grouped(
+        def task_list(
             profile: str = DEFAULT_PROFILE,
-            type: int = 1,
-            process_status: int = 1,
+            task_box: str = "todo",
+            flow_status: str = "all",
             app_key: str | None = None,
-            node_id: int | None = None,
-            search_key: str | None = None,
-            page_num: int = 1,
+            workflow_node_id: int | None = None,
+            query: str | None = None,
+            page: int = 1,
             page_size: int = 20,
+            sort_by: str | None = None,
+            sort_direction: str = "desc",
         ) -> dict[str, Any]:
-            """查询任务列表（带分组信息）
-
-            返回按表单分组的任务列表，适用于需要分组展示的场景。
-
-            Args:
-                profile: 配置文件名
-                type: 消息类型 (1=待办, 2=我发起的, 3=抄送, 5=已办)
-                process_status: 流程状态 (1=全部, 2=流程中, 3=已通过, 4=已拒绝, 5=待完善, 6=催办, 7=超时, 8=即将超时, 9=未读)
-                app_key: 应用key（可选，用于筛选特定应用）
-                node_id: 节点ID（可选，用于筛选特定节点）
-                search_key: 搜索关键词
-                page_num: 页码，从1开始
-                page_size: 每页数量
-            """
-            return self.task_list_grouped(
+            return self.task_list_public(
                 profile=profile,
-                type=type,
-                process_status=process_status,
+                task_box=task_box,
+                flow_status=flow_status,
                 app_key=app_key,
-                node_id=node_id,
-                search_key=search_key,
-                page_num=page_num,
+                workflow_node_id=workflow_node_id,
+                query=query,
+                page=page,
                 page_size=page_size,
+                sort_by=sort_by,
+                sort_direction=sort_direction,
             )
 
         @mcp.tool()
-        def task_statistics(
+        def task_facets(
             profile: str = DEFAULT_PROFILE,
+            task_box: str = "todo",
+            flow_status: str = "all",
+            dimension: str = "worksheet",
             app_key: str | None = None,
+            query: str | None = None,
+            limit: int = 50,
         ) -> dict[str, Any]:
-            """查询任务中心统计信息
-
-            获取当前用户的任务统计数量，包括：
-            - 待办数量
-            - 超时数量
-            - 即将超时数量
-            - 催办数量
-            - 抄送未读数量
-            - 我发起的流程中数量
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key（可选，用于统计特定应用）
-            """
-            return self.task_statistics(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def task_workflow_nodes(
-            profile: str = DEFAULT_PROFILE,
-            type: int = 1,
-            status: str | None = None,
-            app_key_list: list[str] | None = None,
-            search_key: str | None = None,
-            page_num: int = 1,
-            page_size: int = 20,
-        ) -> dict[str, Any]:
-            """查询流程节点列表
-
-            获取工作流节点信息，可用于了解当前有哪些流程节点。
-
-            Args:
-                profile: 配置文件名
-                type: 消息类型 (1=待办, 2=我发起的, 3=抄送, 5=已办)
-                status: 流程状态
-                app_key_list: 应用key列表（用于筛选特定应用）
-                search_key: 节点名称搜索关键词
-                page_num: 页码
-                page_size: 每页数量
-            """
-            return self.task_workflow_nodes(
-                profile=profile,
-                type=type,
-                status=status,
-                app_key_list=app_key_list,
-                search_key=search_key,
-                page_num=page_num,
-                page_size=page_size,
-            )
-
-        @mcp.tool()
-        def task_node_statistics(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            type: int = 1,
-            search_key: str | None = None,
-        ) -> dict[str, Any]:
-            """查询表单下节点的分组统计信息
-
-            获取指定应用下各节点的任务数量统计。
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key
-                type: 消息类型 (1=待办, 2=我发起的, 3=抄送, 5=已办)
-                search_key: 节点名称搜索关键词
-            """
-            return self.task_node_statistics(
+            return self.task_facets(
                 profile=profile,
+                task_box=task_box,
+                flow_status=flow_status,
+                dimension=dimension,
                 app_key=app_key,
-                type=type,
-                search_key=search_key,
-            )
-
-        @mcp.tool()
-        def task_worksheet_statistics(
-            profile: str = DEFAULT_PROFILE,
-            type: int = 1,
-            worksheet_name: str | None = None,
-            page_num: int = 1,
-            page_size: int = 20,
-        ) -> dict[str, Any]:
-            """查询表单分组统计信息
-
-            获取各表单的任务数量统计。
-
-            Args:
-                profile: 配置文件名
-                type: 消息类型 (1=待办, 2=我发起的, 3=抄送, 5=已办)
-                worksheet_name: 表单名称搜索关键词
-                page_num: 页码
-                page_size: 每页数量
-            """
-            return self.task_worksheet_statistics(
-                profile=profile,
-                type=type,
-                worksheet_name=worksheet_name,
-                page_num=page_num,
-                page_size=page_size,
+                query=query,
+                limit=limit,
             )
 
         @mcp.tool()
         def task_mark_read(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            id: int = 0,
-            type: int = 1,
+            task_id: int = 0,
+            task_box: str = "todo",
         ) -> dict[str, Any]:
-            """标记任务为已读
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key
-                id: 任务ID
-                type: 消息类型
-            """
-            return self.task_mark_read(profile=profile, app_key=app_key, id=id, type=type)
+            return self.task_mark_read_public(profile=profile, app_key=app_key, task_id=task_id, task_box=task_box)
 
         @mcp.tool()
         def task_mark_all_cc_read(
             profile: str = DEFAULT_PROFILE,
-            type: int = 3,
-            process_status: int = 1,
+            flow_status: str = "all",
         ) -> dict[str, Any]:
-            """标记所有抄送为已读
-
-            Args:
-                profile: 配置文件名
-                type: 消息类型（默认为3=抄送）
-                process_status: 流程状态
-            """
-            return self.task_mark_all_cc_read(
-                profile=profile,
-                type=type,
-                process_status=process_status,
-            )
+            return self.task_mark_all_cc_read_public(profile=profile, flow_status=flow_status)
 
         @mcp.tool()
         def task_urge(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            row_record_id: int = 0,
-        ) -> dict[str, Any]:
-            """催办任务
-
-            对指定记录发起催办，提醒处理人尽快处理。
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key
-                row_record_id: 记录ID（原applyId）
-            """
-            return self.task_urge(profile=profile, app_key=app_key, row_record_id=row_record_id)
-
-        @mcp.tool()
-        def task_group_detail(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            group_id: int = 0,
-        ) -> dict[str, Any]:
-            """查询分组详情
-
-            获取指定分组的详细信息。
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key
-                group_id: 分组ID
-            """
-            return self.task_group_detail(profile=profile, app_key=app_key, group_id=group_id)
-
-        @mcp.tool()
-        def task_batch_processing_amount(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            list_type: int = 0,
-            task_center_filter: dict[str, Any] | None = None,
+            record_id: int = 0,
         ) -> dict[str, Any]:
-            """查询批量处理数量
+            return self.task_urge_public(profile=profile, app_key=app_key, record_id=record_id)
 
-            获取符合筛选条件的任务数量，用于批量操作前的数量确认。
-
-            Args:
-                profile: 配置文件名
-                app_key: 应用key
-                list_type: 操作类型
-                task_center_filter: 筛选条件
-            """
-            return self.task_batch_processing_amount(
+    def task_summary(
+        self,
+        *,
+        profile: str,
+        app_key: str | None,
+    ) -> dict[str, Any]:
+        raw = self.task_statistics(profile=profile, app_key=app_key)
+        statistics = raw.get("statistics", {})
+        summary = self._normalize_task_summary_payload(statistics)
+        return {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": True,
+            "request_route": raw.get("request_route"),
+            "warnings": [],
+            "output_profile": "normal",
+            "data": {
+                "summary": summary,
+            },
+        }
+
+    def task_list_public(
+        self,
+        *,
+        profile: str,
+        task_box: str,
+        flow_status: str,
+        app_key: str | None,
+        workflow_node_id: int | None,
+        query: str | None,
+        page: int,
+        page_size: int,
+        sort_by: str | None,
+        sort_direction: str,
+    ) -> dict[str, Any]:
+        normalized_type = self._task_box_to_type(task_box)
+        normalized_status = self._flow_status_to_process_status(flow_status)
+        create_time_asc = self._task_sort_to_create_time_asc(sort_by, sort_direction)
+        raw = self.task_list(
+            profile=profile,
+            type=normalized_type,
+            process_status=normalized_status,
+            app_key=app_key,
+            node_id=workflow_node_id,
+            search_key=query,
+            page_num=page,
+            page_size=page_size,
+            create_time_asc=create_time_asc,
+        )
+        task_page = raw.get("page", {})
+        return {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": True,
+            "request_route": raw.get("request_route"),
+            "warnings": [],
+            "output_profile": "normal",
+            "data": {
+                "items": _task_page_items(task_page),
+                "pagination": {
+                    "page": page,
+                    "page_size": page_size,
+                    "returned_items": len(_task_page_items(task_page)),
+                    "page_amount": _task_page_amount(task_page),
+                    "reported_total": _task_page_total(task_page),
+                },
+                "selection": {
+                    "task_box": task_box,
+                    "flow_status": flow_status,
+                    "app_key": app_key,
+                    "workflow_node_id": workflow_node_id,
+                    "query": query,
+                    "applied_sort": self._task_applied_sort(sort_by, sort_direction),
+                },
+            },
+        }
+
+    def task_facets(
+        self,
+        *,
+        profile: str,
+        task_box: str,
+        flow_status: str,
+        dimension: str,
+        app_key: str | None,
+        query: str | None,
+        limit: int,
+    ) -> dict[str, Any]:
+        normalized_type = self._task_box_to_type(task_box)
+        normalized_status = self._flow_status_to_process_status(flow_status)
+        if dimension not in {"worksheet", "workflow_node"}:
+            raise_tool_error(QingflowApiError.config_error("dimension must be worksheet or workflow_node"))
+        if limit <= 0:
+            raise_tool_error(QingflowApiError.config_error("limit must be positive"))
+
+        if dimension == "worksheet":
+            raw = self.task_worksheet_statistics(
+                profile=profile,
+                type=normalized_type,
+                worksheet_name=query,
+                page_num=1,
+                page_size=max(limit, 20),
+            )
+            source = raw.get("page", {})
+        elif app_key:
+            raw = self.task_node_statistics(
                 profile=profile,
                 app_key=app_key,
-                list_type=list_type,
-                task_center_filter=task_center_filter,
+                type=normalized_type,
+                search_key=query,
             )
+            source = raw.get("nodes", {})
+        else:
+            raw = self.task_workflow_nodes(
+                profile=profile,
+                type=normalized_type,
+                status=str(normalized_status),
+                app_key_list=None,
+                search_key=query,
+                page_num=1,
+                page_size=max(limit, 20),
+            )
+            source = raw.get("page", {})
+
+        groups = self._normalize_task_facets(source)
+        rows_truncated = len(groups) > limit
+        returned_groups = groups[:limit]
+        return {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": True,
+            "request_route": raw.get("request_route"),
+            "warnings": [],
+            "output_profile": "normal",
+            "data": {
+                "groups": returned_groups,
+                "rows_truncated": rows_truncated,
+                "statement_scope": "returned_groups_only" if rows_truncated else "full_population",
+                "selection": {
+                    "task_box": task_box,
+                    "flow_status": flow_status,
+                    "dimension": dimension,
+                    "app_key": app_key,
+                    "query": query,
+                    "limit": limit,
+                },
+            },
+        }
+
+    def task_mark_read_public(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        task_id: int,
+        task_box: str,
+    ) -> dict[str, Any]:
+        raw = self.task_mark_read(profile=profile, app_key=app_key, id=task_id, type=self._task_box_to_type(task_box))
+        return self._public_task_action_response(
+            raw,
+            action="mark_read",
+            resource={"app_key": app_key, "task_id": task_id},
+            selection={"task_box": task_box},
+        )
+
+    def task_mark_all_cc_read_public(
+        self,
+        *,
+        profile: str,
+        flow_status: str,
+    ) -> dict[str, Any]:
+        raw = self.task_mark_all_cc_read(profile=profile, type=TASK_BOX_TO_TYPE["cc"], process_status=self._flow_status_to_process_status(flow_status))
+        return self._public_task_action_response(
+            raw,
+            action="mark_all_cc_read",
+            resource={},
+            selection={"task_box": "cc", "flow_status": flow_status},
+        )
+
+    def task_urge_public(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+    ) -> dict[str, Any]:
+        raw = self.task_urge(profile=profile, app_key=app_key, row_record_id=record_id)
+        return self._public_task_action_response(
+            raw,
+            action="urge",
+            resource={"app_key": app_key, "record_id": record_id},
+            selection={},
+        )
 
     def task_list(
         self,
@@ -347,6 +369,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "type": type,
                 "type_label": get_task_type_label(type),
                 "list_type_label": get_task_type_label(type),
@@ -389,6 +412,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "type": type,
                 "type_label": get_task_type_label(type),
                 "list_type_label": get_task_type_label(type),
@@ -413,6 +437,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "statistics": result,
             }
 
@@ -448,6 +473,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "type": type,
                 "type_label": get_task_type_label(type),
                 "list_type_label": get_task_type_label(type),
@@ -480,6 +506,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "app_key": app_key,
                 "type": type,
                 "type_label": get_task_type_label(type),
@@ -513,6 +540,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "type": type,
                 "type_label": get_task_type_label(type),
                 "list_type_label": get_task_type_label(type),
@@ -544,6 +572,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "app_key": app_key,
                 "id": id,
                 "type": type,
@@ -573,6 +602,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "type": type,
                 "type_label": get_task_type_label(type),
                 "list_type_label": get_task_type_label(type),
@@ -603,6 +633,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "app_key": app_key,
                 "row_record_id": row_record_id,
                 "result": result,
@@ -631,6 +662,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "app_key": app_key,
                 "group_id": group_id,
                 "detail": result,
@@ -665,6 +697,7 @@ class TaskTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "app_key": app_key,
                 "list_type": list_type,
                 "list_type_label": get_record_list_type_label(list_type),
@@ -690,3 +723,121 @@ class TaskTools(ToolBase):
                     f"Invalid process_status: {process_status}. Must be one of {valid_statuses}"
                 )
             )
+
+    def _task_box_to_type(self, task_box: str) -> int:
+        normalized = (task_box or "").strip().lower()
+        if normalized not in TASK_BOX_TO_TYPE:
+            raise_tool_error(QingflowApiError.config_error("task_box must be todo, initiated, cc, or done"))
+        return TASK_BOX_TO_TYPE[normalized]
+
+    def _flow_status_to_process_status(self, flow_status: str) -> int:
+        normalized = (flow_status or "").strip().lower()
+        if normalized not in FLOW_STATUS_TO_PROCESS_STATUS:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "flow_status must be all, in_progress, approved, rejected, pending_fix, urged, overdue, due_soon, unread, or ended"
+                )
+            )
+        return FLOW_STATUS_TO_PROCESS_STATUS[normalized]
+
+    def _task_sort_to_create_time_asc(self, sort_by: str | None, sort_direction: str) -> bool | None:
+        normalized_sort_by = (sort_by or "").strip().lower() if sort_by is not None else ""
+        normalized_direction = (sort_direction or "desc").strip().lower()
+        if normalized_direction not in {"asc", "desc"}:
+            raise_tool_error(QingflowApiError.config_error("sort_direction must be asc or desc"))
+        if not normalized_sort_by:
+            return None
+        if normalized_sort_by not in {"created_at", "create_time"}:
+            raise_tool_error(QingflowApiError.config_error("task_list only supports sort_by=created_at"))
+        return normalized_direction == "asc"
+
+    def _task_applied_sort(self, sort_by: str | None, sort_direction: str) -> list[dict[str, Any]]:
+        if not sort_by:
+            return []
+        return [{"by": "created_at", "order": (sort_direction or "desc").strip().lower()}]
+
+    def _normalize_task_summary_payload(self, payload: Any) -> dict[str, Any]:
+        if not isinstance(payload, dict):
+            return {}
+        return {
+            "todo_count": payload.get("todoCount", payload.get("todo_count")),
+            "overdue_count": payload.get("timeoutCount", payload.get("timeout_count")),
+            "due_soon_count": payload.get("preTimeoutCount", payload.get("pre_timeout_count")),
+            "urged_count": payload.get("urgedCount", payload.get("urged_count")),
+            "cc_unread_count": payload.get("ccUnreadCount", payload.get("cc_unread_count")),
+            "in_progress_initiated_count": payload.get("processingCount", payload.get("processing_count")),
+        }
+
+    def _normalize_task_facets(self, payload: Any) -> list[dict[str, Any]]:
+        items = _task_page_items(payload)
+        groups: list[dict[str, Any]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            key = item.get("worksheetId", item.get("groupId", item.get("nodeId", item.get("id", item.get("key")))))
+            label = item.get("worksheetName", item.get("groupName", item.get("nodeName", item.get("name", item.get("label", item.get("title"))))))
+            count = item.get("count", item.get("taskCount", item.get("amount", item.get("todoCount", item.get("num")))))
+            groups.append({"key": key if key is not None else label, "label": label, "count": count})
+        return groups
+
+    def _public_task_action_response(
+        self,
+        raw: dict[str, Any],
+        *,
+        action: str,
+        resource: dict[str, Any],
+        selection: dict[str, Any],
+    ) -> dict[str, Any]:
+        response = dict(raw)
+        response["ok"] = bool(raw.get("ok", True))
+        response["warnings"] = []
+        response["output_profile"] = "normal"
+        response["data"] = {
+            "action": action,
+            "resource": resource,
+            "selection": selection,
+            "result": raw.get("result"),
+        }
+        return response
+
+    def _request_route_payload(self, context) -> dict[str, Any]:  # type: ignore[no-untyped-def]
+        describe_route = getattr(self.backend, "describe_route", None)
+        if callable(describe_route):
+            payload = describe_route(context)
+            if isinstance(payload, dict):
+                return payload
+        return {
+            "base_url": getattr(context, "base_url", None),
+            "qf_version": getattr(context, "qf_version", None),
+            "qf_version_source": getattr(context, "qf_version_source", None) or ("context" if getattr(context, "qf_version", None) else "unknown"),
+        }
+
+
+def _task_page_items(payload: Any) -> list[Any]:
+    if isinstance(payload, list):
+        return payload
+    if not isinstance(payload, dict):
+        return []
+    for key in ("list", "items", "rows", "result"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return value
+    for container_key in ("page", "data"):
+        nested = payload.get(container_key)
+        if isinstance(nested, dict):
+            nested_items = _task_page_items(nested)
+            if nested_items:
+                return nested_items
+    return []
+
+
+def _task_page_amount(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        return payload.get("pageAmount", payload.get("page_amount"))
+    return None
+
+
+def _task_page_total(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        return payload.get("total", payload.get("count"))
+    return None