@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/src/qingflow_mcp/tools/approval_tools.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error, message_looks_like_invalid_token, raise_tool_error
 from ..json_types import JSONObject
 from ..list_type_labels import get_record_list_type_label
 from .base import ToolBase, tool_cn_name
@@ -172,15 +173,26 @@ class ApprovalTools(ToolBase):
         keyword: str | None = None,
     ) -> dict[str, Any]:
         """执行记录相关逻辑。"""
-        raw = self.record_comment_mention_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=record_id,
-            page_size=page_size,
-            page_num=page_num,
-            list_type=list_type,
-            keyword=keyword,
-        )
+        selection = {"app_key": app_key, "record_id": record_id, "list_type": list_type, "keyword": keyword}
+        try:
+            raw = self.record_comment_mention_candidates(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                page_size=page_size,
+                page_num=page_num,
+                list_type=list_type,
+                keyword=keyword,
+            )
+        except RuntimeError as exc:
+            if not _is_optional_approval_runtime_error(exc):
+                raise
+            return self._runtime_error_as_auxiliary_result(
+                exc,
+                error_code="RECORD_COMMENT_MENTIONS_UNAVAILABLE",
+                selection=selection,
+                fallback_hint="Mention candidates are unavailable in this permission context; write a plain comment or retry without mentions.",
+            )
         items = _approval_page_items(raw.get("page"))
         return self._public_page_response(
             raw,
@@ -192,7 +204,7 @@ class ApprovalTools(ToolBase):
                 "page_amount": _approval_page_amount(raw.get("page")),
                 "reported_total": _approval_page_total(raw.get("page")),
             },
-            selection={"app_key": app_key, "record_id": record_id, "list_type": list_type, "keyword": keyword},
+            selection=selection,
         )
 
     @tool_cn_name("任务通过")
@@ -242,13 +254,24 @@ class ApprovalTools(ToolBase):
     @tool_cn_name("任务退回候选")
     def task_rollback_candidates(self, *, profile: str, app_key: str, record_id: int, workflow_node_id: int) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        raw = self.record_rollback_candidates(profile=profile, app_key=app_key, apply_id=record_id, audit_node_id=workflow_node_id)
+        selection = {"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id}
+        try:
+            raw = self.record_rollback_candidates(profile=profile, app_key=app_key, apply_id=record_id, audit_node_id=workflow_node_id)
+        except RuntimeError as exc:
+            if not _is_optional_approval_runtime_error(exc):
+                raise
+            return self._runtime_error_as_auxiliary_result(
+                exc,
+                error_code="TASK_ROLLBACK_CANDIDATES_UNAVAILABLE",
+                selection=selection,
+                fallback_hint="Rollback candidates are unavailable in this permission context; use task get for current context or retry with a valid actionable node.",
+            )
         items = _approval_page_items(raw.get("result"))
         return self._public_page_response(
             raw,
             items=items,
             pagination={"returned_items": len(items)},
-            selection={"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id},
+            selection=selection,
         )
 
     @tool_cn_name("任务退回")
@@ -331,15 +354,26 @@ class ApprovalTools(ToolBase):
         keyword: str | None = None,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        raw = self.record_transfer_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=record_id,
-            page_size=page_size,
-            page_num=page_num,
-            audit_node_id=workflow_node_id,
-            keyword=keyword,
-        )
+        selection = {"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id, "keyword": keyword}
+        try:
+            raw = self.record_transfer_candidates(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                page_size=page_size,
+                page_num=page_num,
+                audit_node_id=workflow_node_id,
+                keyword=keyword,
+            )
+        except RuntimeError as exc:
+            if not _is_optional_approval_runtime_error(exc):
+                raise
+            return self._runtime_error_as_auxiliary_result(
+                exc,
+                error_code="TASK_TRANSFER_CANDIDATES_UNAVAILABLE",
+                selection=selection,
+                fallback_hint="Transfer candidates are unavailable in this permission context; use task get for current context or retry with a valid actionable node.",
+            )
         original_items = _approval_page_items(raw.get("page"))
         items = self._filter_self_transfer_candidates(profile=profile, items=original_items)
         filtered_count = max(len(original_items) - len(items), 0)
@@ -353,7 +387,7 @@ class ApprovalTools(ToolBase):
                 "page_amount": _approval_page_amount(raw.get("page")),
                 "reported_total": max(_approval_page_total(raw.get("page")) - filtered_count, 0),
             },
-            selection={"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id, "keyword": keyword},
+            selection=selection,
         )
 
     @tool_cn_name("新增评论")
@@ -763,9 +797,18 @@ class ApprovalTools(ToolBase):
         node_id = self._extract_node_id(body)
         body["nodeId"] = self._resolve_actionable_node_id(context, app_key, apply_id, node_id)
         body["applyId"] = self._match_or_fill_int(body, field_name="applyId", expected_value=apply_id)
-        body["formId"] = self._resolve_form_id(profile, context, app_key, explicit_form_id=body.get("formId"))
+        current_detail: dict[str, Any] | None = None
+        if body.get("answers") is None or body.get("formId") is None:
+            current_detail = self._fetch_current_todo_detail(context, app_key, apply_id, body["nodeId"])
+        body["formId"] = self._resolve_form_id(
+            profile,
+            context,
+            app_key,
+            explicit_form_id=body.get("formId"),
+            current_detail=current_detail,
+        )
         if body.get("answers") is None:
-            body["answers"] = self._fetch_current_todo_answers(context, app_key, apply_id, body["nodeId"])
+            body["answers"] = self._extract_current_todo_answers(current_detail, apply_id=apply_id, node_id=body["nodeId"])
 
         self._validate_approval_payload(body)
         return body
@@ -782,12 +825,27 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.nodeId or payload.auditNodeId must be a positive integer"))
         return node_id
 
-    def _resolve_form_id(self, profile: str, context, app_key: str, *, explicit_form_id: Any | None) -> int:  # type: ignore[no-untyped-def]
+    def _resolve_form_id(
+        self,
+        profile: str,
+        context,
+        app_key: str,
+        *,
+        explicit_form_id: Any | None,
+        current_detail: dict[str, Any] | None = None,
+    ) -> int:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
+        detail_form_id = self._extract_form_id_from_current_detail(current_detail)
         if explicit_form_id is not None:
             if not isinstance(explicit_form_id, int) or explicit_form_id <= 0:
                 raise_tool_error(QingflowApiError.config_error("payload.formId must be a positive integer"))
-            form_id = self._get_form_id(profile, context, app_key)
+            try:
+                form_id = detail_form_id or self._get_form_id(profile, context, app_key)
+            except QingflowApiError as exc:
+                if not _is_optional_approval_precheck_error(exc):
+                    raise
+                self._form_id_cache[f"{profile}:{app_key}"] = explicit_form_id
+                return explicit_form_id
             if form_id != explicit_form_id:
                 raise_tool_error(
                     QingflowApiError.config_error(
@@ -795,6 +853,9 @@ class ApprovalTools(ToolBase):
                     )
                 )
             return explicit_form_id
+        if detail_form_id is not None:
+            self._form_id_cache[f"{profile}:{app_key}"] = detail_form_id
+            return detail_form_id
         return self._get_form_id(profile, context, app_key)
 
     def _get_form_id(self, profile: str, context, app_key: str) -> int:  # type: ignore[no-untyped-def]
@@ -831,12 +892,18 @@ class ApprovalTools(ToolBase):
 
     def _resolve_actionable_node_id(self, context, app_key: str, apply_id: int, node_id: int) -> int:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
-        infos = self.backend.request(
-            "GET",
-            context,
-            f"/app/{app_key}/apply/{apply_id}/auditInfo",
-            params={"type": 1},
-        )
+        try:
+            infos = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{apply_id}/auditInfo",
+                params={"type": 1},
+            )
+        except QingflowApiError as exc:
+            if not _is_optional_approval_precheck_error(exc):
+                raise
+            self._fetch_current_todo_detail(context, app_key, apply_id, node_id)
+            return node_id
         if not isinstance(infos, list) or not infos:
             raise_tool_error(
                 QingflowApiError.config_error(
@@ -858,7 +925,7 @@ class ApprovalTools(ToolBase):
             )
         return node_id
 
-    def _fetch_current_todo_answers(self, context, app_key: str, apply_id: int, node_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+    def _fetch_current_todo_detail(self, context, app_key: str, apply_id: int, node_id: int) -> dict[str, Any]:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
         detail = self.backend.request(
             "GET",
@@ -866,6 +933,21 @@ class ApprovalTools(ToolBase):
             f"/app/{app_key}/apply/{apply_id}",
             params={"role": 3, "listType": 1, "auditNodeId": node_id},
         )
+        if not isinstance(detail, dict):
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"cannot resolve current todo detail for apply_id={apply_id} nodeId={node_id}"
+                )
+            )
+        return detail
+
+    def _fetch_current_todo_answers(self, context, app_key: str, apply_id: int, node_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
+        detail = self._fetch_current_todo_detail(context, app_key, apply_id, node_id)
+        return self._extract_current_todo_answers(detail, apply_id=apply_id, node_id=node_id)
+
+    def _extract_current_todo_answers(self, detail: dict[str, Any] | None, *, apply_id: int, node_id: int) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         answers = detail.get("answers") if isinstance(detail, dict) else None
         if not isinstance(answers, list):
             raise_tool_error(
@@ -879,6 +961,21 @@ class ApprovalTools(ToolBase):
                 normalized_answers.append(dict(item))
         return normalized_answers
 
+    def _extract_form_id_from_current_detail(self, detail: dict[str, Any] | None) -> int | None:
+        """执行内部辅助逻辑。"""
+        if not isinstance(detail, dict):
+            return None
+        for key in ("formId", "form_id"):
+            value = detail.get(key)
+            if isinstance(value, int) and value > 0:
+                return value
+        form = detail.get("form")
+        if isinstance(form, dict):
+            value = form.get("formId") or form.get("form_id")
+            if isinstance(value, int) and value > 0:
+                return value
+        return None
+
     def _validate_approval_payload(self, payload: dict[str, Any]) -> None:
         """执行内部辅助逻辑。"""
         self._reject_unsupported_fields(payload)
@@ -958,7 +1055,7 @@ class ApprovalTools(ToolBase):
         if node_id is None:
             node_payload = dict(payload or {})
             node_id = self._extract_node_id(node_payload)
-        delegated = TaskContextTools(self.sessions, self.backend).task_action_execute(
+        delegated = TaskContextTools(self.sessions, self.backend)._task_action_execute_with_locator(
             profile=profile,
             app_key=app_key,
             record_id=record_id,
@@ -995,6 +1092,48 @@ class ApprovalTools(ToolBase):
         }
         return response
 
+    def _runtime_error_as_auxiliary_result(
+        self,
+        error: RuntimeError,
+        *,
+        error_code: str,
+        selection: dict[str, Any],
+        fallback_hint: str,
+    ) -> dict[str, Any]:
+        """Return a structured failure for optional approval/comment helpers."""
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = {"message": str(error)}
+        details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
+        warning: dict[str, Any] = {
+            "code": error_code,
+            "message": fallback_hint,
+        }
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if payload.get(key) is not None:
+                warning[key] = payload.get(key)
+        response: dict[str, Any] = {
+            "ok": False,
+            "status": "failed",
+            "error_code": details.get("error_code") or error_code,
+            "message": payload.get("message") or str(error),
+            "warnings": [warning],
+            "output_profile": "normal",
+            "data": {
+                "items": [],
+                "pagination": {"returned_items": 0},
+                "selection": selection,
+                "fallback_hint": fallback_hint,
+            },
+        }
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if payload.get(key) is not None:
+                response[key] = payload.get(key)
+        if details:
+            response["details"] = details
+        return response
+
     def _public_action_response(
         self,
         raw: dict[str, Any],
@@ -1060,3 +1199,26 @@ def _approval_page_total(payload: Any) -> Any:
     if isinstance(payload, dict):
         return payload.get("total", payload.get("count"))
     return None
+
+
+def _is_optional_approval_precheck_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _is_optional_approval_runtime_error(error: RuntimeError) -> bool:
+    try:
+        payload = json.loads(str(error))
+    except json.JSONDecodeError:
+        return False
+    if not isinstance(payload, dict):
+        return False
+    if str(payload.get("category") or "").strip().lower() == "auth":
+        return False
+    if message_looks_like_invalid_token(payload.get("message")):
+        return False
+    if backend_code_value_int(payload.get("http_status")) == 401:
+        return False
+    return backend_code_value_int(payload.get("backend_code")) in {40002, 40027, 404} or backend_code_value_int(payload.get("http_status")) == 404

package/src/qingflow_mcp/tools/auth_tools.py

@@ -14,7 +14,7 @@ from ..config import (
     get_mcporter_config_path,
     normalize_base_url,
 )
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..session_store import SessionStore
 from .base import ToolBase, tool_cn_name
 
@@ -650,7 +650,9 @@ class AuthTools(ToolBase):
                 qf_version=qf_version,
                 qf_version_source=qf_version_source,
             )
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if is_auth_like_error(exc):
+                raise
             return None, None
 
     def _fetch_first_workspace(
@@ -765,7 +767,9 @@ class AuthTools(ToolBase):
                 qf_version=session_profile.qf_version,
                 qf_version_source=session_profile.qf_version_source,
             )
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if is_auth_like_error(exc):
+                raise
             return None
 
         ws_name = session_profile.selected_ws_name
@@ -823,6 +827,18 @@ class AuthTools(ToolBase):
         )
         payload = dict(default_payload)
         payload["permission_level"] = permission_level
+        warnings: list[dict[str, Any]] = []
+        if permission_level is None:
+            warnings.append(
+                {
+                    "code": "WORKSPACE_PERMISSION_LEVEL_UNAVAILABLE",
+                    "message": (
+                        "auth_whoami could not resolve the selected workspace permission level; "
+                        "do not infer the user is a basic member or an administrator from this null value."
+                    ),
+                    "ws_id": ws_id,
+                }
+            )
 
         context = BackendRequestContext(
             base_url=backend_session.base_url,
@@ -831,14 +847,17 @@ class AuthTools(ToolBase):
             qf_version=backend_session.qf_version,
             qf_version_source=backend_session.qf_version_source,
         )
+        member_lookup_warnings: list[dict[str, Any]] = []
         member = self._lookup_current_member(
             context=context,
             uid=session_profile.uid,
             email=session_profile.email,
             nick_name=session_profile.nick_name,
+            warnings=member_lookup_warnings,
         )
+        warnings.extend(member_lookup_warnings)
         if member is None:
-            return payload, [
+            warnings.append(
                 {
                     "code": "CURRENT_MEMBER_PROFILE_UNAVAILABLE",
                     "message": (
@@ -846,11 +865,12 @@ class AuthTools(ToolBase):
                         f"in workspace {ws_id}."
                     ),
                 }
-            ]
+            )
+            return payload, warnings
 
         payload["departments"] = self._compact_departments(member)
         payload["roles"] = self._compact_roles(member)
-        return payload, []
+        return payload, warnings
 
     def _workspace_permission_level(
         self,
@@ -882,7 +902,9 @@ class AuthTools(ToolBase):
         """执行内部辅助逻辑。"""
         try:
             workspace = self.backend.request("GET", context, f"/user/workspace/{ws_id}")
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_auth_lookup_error(exc):
+                raise
             return None
         if not isinstance(workspace, dict):
             return None
@@ -897,7 +919,9 @@ class AuthTools(ToolBase):
                 "/user/workspaceList/pageQuery",
                 json_body={"pageNum": 1, "pageSize": 100, "authList": [0, 1, 2, 3]},
             )
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_auth_lookup_error(exc):
+                raise
             return None
         workspaces = payload.get("list") if isinstance(payload, dict) else []
         if not isinstance(workspaces, list):
@@ -915,20 +939,21 @@ class AuthTools(ToolBase):
         uid: int | None,
         email: str | None,
         nick_name: str | None,
+        warnings: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any] | None:
         """执行内部辅助逻辑。"""
         candidates: list[dict[str, Any]] = []
         for keyword in (email, nick_name):
-            member = self._search_member_once(context, uid=uid, keyword=keyword)
+            member = self._search_member_once(context, uid=uid, keyword=keyword, warnings=warnings)
             if member is not None:
                 return member
             if keyword:
-                candidates.extend(self._search_member_items(context, keyword=keyword))
+                candidates.extend(self._search_member_items(context, keyword=keyword, warnings=warnings))
         if uid is not None and uid > 0:
             for item in candidates:
                 if self._same_member(item, uid=uid):
                     return item
-            return self._search_member_once(context, uid=uid, keyword=None)
+            return self._search_member_once(context, uid=uid, keyword=None, warnings=warnings)
         return None
 
     def _search_member_once(
@@ -937,14 +962,21 @@ class AuthTools(ToolBase):
         *,
         uid: int | None,
         keyword: str | None,
+        warnings: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any] | None:
         """执行内部辅助逻辑。"""
-        for item in self._search_member_items(context, keyword=keyword):
+        for item in self._search_member_items(context, keyword=keyword, warnings=warnings):
             if self._same_member(item, uid=uid):
                 return item
         return None
 
-    def _search_member_items(self, context: BackendRequestContext, *, keyword: str | None) -> list[dict[str, Any]]:
+    def _search_member_items(
+        self,
+        context: BackendRequestContext,
+        *,
+        keyword: str | None,
+        warnings: list[dict[str, Any]] | None = None,
+    ) -> list[dict[str, Any]]:
         """执行内部辅助逻辑。"""
         params: dict[str, Any] = {"pageNum": 1, "pageSize": 100, "containDisable": True}
         normalized_keyword = str(keyword or "").strip()
@@ -952,11 +984,38 @@ class AuthTools(ToolBase):
             params["keyword"] = normalized_keyword
         try:
             payload = self.backend.request("GET", context, "/contact", params=params)
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_auth_lookup_error(exc):
+                raise
+            if warnings is not None and _is_contact_directory_permission_denied(exc):
+                self._append_unique_warning(warnings, self._contact_directory_permission_warning(exc))
             return []
         items = self._extract_items(payload)
         return [item for item in items if isinstance(item, dict)]
 
+    def _append_unique_warning(self, warnings: list[dict[str, Any]], warning: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
+        code = self._normalize_text(warning.get("code"))
+        if code is not None and any(item.get("code") == code for item in warnings):
+            return
+        warnings.append(warning)
+
+    def _contact_directory_permission_warning(self, error: QingflowApiError) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
+        warning: dict[str, Any] = {
+            "code": "CONTACT_DIRECTORY_PERMISSION_DENIED",
+            "message": (
+                "auth_whoami could not read current member departments and roles because "
+                "the contact directory is not readable in this permission context; "
+                "permission_level still comes from the workspace auth route."
+            ),
+            "category": error.category,
+            "backend_code": backend_code_int(error),
+            "http_status": error.http_status,
+            "request_id": error.request_id,
+        }
+        return {key: value for key, value in warning.items() if value is not None}
+
     def _same_member(self, item: dict[str, Any], *, uid: int | None) -> bool:
         """执行内部辅助逻辑。"""
         if uid is None or uid <= 0:
@@ -1105,7 +1164,9 @@ class AuthTools(ToolBase):
                 qf_version=qf_version,
                 qf_version_source=qf_version_source,
             )
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if is_auth_like_error(exc):
+                raise
             workspace = None
         if isinstance(workspace, dict):
             workspace_name = str(workspace.get("workspaceName") or workspace.get("wsName") or "").strip()
@@ -1119,7 +1180,9 @@ class AuthTools(ToolBase):
                 qf_version=qf_version,
                 qf_version_source=qf_version_source,
             )
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if is_auth_like_error(exc):
+                raise
             fallback = None
         return fallback or workspace
 
@@ -1157,3 +1220,16 @@ class AuthTools(ToolBase):
             None,
         )
         return found if isinstance(found, dict) else None
+
+
+def _is_contact_directory_permission_denied(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
+def _is_optional_auth_lookup_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404