@josephyan/qingflow-cli 0.2.0-beta.984 → 0.2.0-beta.986

package/src/qingflow_mcp/tools/approval_tools.py

@@ -8,15 +8,26 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from ..list_type_labels import get_record_list_type_label
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class ApprovalTools(ToolBase):
+    """审批工具（中文名：审批数据与候选范围）。
+
+    类型：审批辅助工具。
+    主要职责：
+    1. 查询审批相关列表与详情；
+    2. 提供审批节点候选范围与运行时上下文辅助；
+    3. 为任务执行类工具提供审批侧数据支撑。
+    """
+
     def __init__(self, sessions, backend) -> None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._form_id_cache: dict[str, int] = {}
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def record_comment_write(
             profile: str = DEFAULT_PROFILE,
@@ -137,7 +148,9 @@ class ApprovalTools(ToolBase):
                 keyword=keyword,
             )
 
+    @tool_cn_name("写评论")
     def record_comment_write(self, *, profile: str, app_key: str, record_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         raw = self.record_comment_add(profile=profile, app_key=app_key, apply_id=record_id, payload=payload)
         return self._public_action_response(
             raw,
@@ -146,6 +159,7 @@ class ApprovalTools(ToolBase):
             selection={},
         )
 
+    @tool_cn_name("评论提及")
     def record_comment_mentions(
         self,
         *,
@@ -157,6 +171,7 @@ class ApprovalTools(ToolBase):
         list_type: int | None = None,
         keyword: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         raw = self.record_comment_mention_candidates(
             profile=profile,
             app_key=app_key,
@@ -180,7 +195,9 @@ class ApprovalTools(ToolBase):
             selection={"app_key": app_key, "record_id": record_id, "list_type": list_type, "keyword": keyword},
         )
 
+    @tool_cn_name("任务通过")
     def task_approve(self, *, profile: str, app_key: str, record_id: int, payload: dict[str, Any], fields: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if fields:
             return self._delegate_task_action(
                 profile=profile,
@@ -200,7 +217,9 @@ class ApprovalTools(ToolBase):
             human_review=True,
         )
 
+    @tool_cn_name("任务拒绝")
     def task_reject(self, *, profile: str, app_key: str, record_id: int, payload: dict[str, Any], fields: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if fields:
             return self._delegate_task_action(
                 profile=profile,
@@ -220,7 +239,9 @@ class ApprovalTools(ToolBase):
             human_review=True,
         )
 
+    @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)
         items = _approval_page_items(raw.get("result"))
         return self._public_page_response(
@@ -230,7 +251,9 @@ class ApprovalTools(ToolBase):
             selection={"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id},
         )
 
+    @tool_cn_name("任务退回")
     def task_rollback(self, *, profile: str, app_key: str, record_id: int, payload: dict[str, Any], fields: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if fields:
             return self._delegate_task_action(
                 profile=profile,
@@ -250,7 +273,9 @@ class ApprovalTools(ToolBase):
             human_review=True,
         )
 
+    @tool_cn_name("任务转交")
     def task_transfer(self, *, profile: str, app_key: str, record_id: int, payload: dict[str, Any], fields: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if fields:
             return self._delegate_task_action(
                 profile=profile,
@@ -271,6 +296,7 @@ class ApprovalTools(ToolBase):
             human_review=True,
         )
 
+    @tool_cn_name("任务仅保存")
     def task_save_only(
         self,
         *,
@@ -280,6 +306,7 @@ class ApprovalTools(ToolBase):
         workflow_node_id: int,
         fields: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         return self._delegate_task_action(
             profile=profile,
             app_key=app_key,
@@ -291,6 +318,7 @@ class ApprovalTools(ToolBase):
             workflow_node_id=workflow_node_id,
         )
 
+    @tool_cn_name("任务转交候选")
     def task_transfer_candidates(
         self,
         *,
@@ -302,6 +330,7 @@ class ApprovalTools(ToolBase):
         workflow_node_id: int = 0,
         keyword: str | None = None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         raw = self.record_transfer_candidates(
             profile=profile,
             app_key=app_key,
@@ -327,7 +356,9 @@ class ApprovalTools(ToolBase):
             selection={"app_key": app_key, "record_id": record_id, "workflow_node_id": workflow_node_id, "keyword": keyword},
         )
 
+    @tool_cn_name("新增评论")
     def record_comment_add(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         self._validate_comment_payload(payload)
 
@@ -344,7 +375,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("评论列表")
     def record_comment_list(self, *, profile: str, app_key: str, apply_id: int, page_size: int = 20, list_type: int | None = None, page_num: int | None = 1) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -380,6 +413,7 @@ class ApprovalTools(ToolBase):
             selection={"app_key": app_key, "record_id": apply_id, "list_type": list_type},
         )
 
+    @tool_cn_name("评论提及候选")
     def record_comment_mention_candidates(
         self,
         *,
@@ -391,6 +425,7 @@ class ApprovalTools(ToolBase):
         list_type: int | None = None,
         keyword: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -413,7 +448,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("评论标记已读")
     def record_comment_mark_read(self, *, profile: str, app_key: str, apply_id: int) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -435,7 +472,9 @@ class ApprovalTools(ToolBase):
             selection={},
         )
 
+    @tool_cn_name("评论统计")
     def record_comment_stats(self, *, profile: str, app_key: str, apply_id: int) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -451,7 +490,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录通过")
     def record_approve(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
 
@@ -471,7 +512,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录拒绝")
     def record_reject(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
 
@@ -491,7 +534,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录退回候选")
     def record_rollback_candidates(self, *, profile: str, app_key: str, apply_id: int, audit_node_id: int) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         if audit_node_id <= 0:
             raise_tool_error(QingflowApiError.config_error("audit_node_id must be positive"))
@@ -514,7 +559,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录退回")
     def record_rollback(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
         self._validate_audit_payload(body)
@@ -532,7 +579,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录转交")
     def record_transfer(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
         self._validate_audit_payload(body, require_uid=True)
@@ -550,6 +599,7 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录转交候选")
     def record_transfer_candidates(
         self,
         *,
@@ -561,6 +611,7 @@ class ApprovalTools(ToolBase):
         audit_node_id: int = 0,
         keyword: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         if audit_node_id <= 0:
             raise_tool_error(QingflowApiError.config_error("audit_node_id must be positive"))
@@ -581,7 +632,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录改派信息")
     def record_reassign_get(self, *, profile: str, app_key: str, apply_id: int) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -597,7 +650,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("记录改派")
     def record_reassign(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
 
@@ -614,6 +669,7 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("会签候选")
     def record_countersign_candidates(
         self,
         *,
@@ -625,6 +681,7 @@ class ApprovalTools(ToolBase):
         audit_node_id: int = 0,
         search_key: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         if audit_node_id <= 0:
             raise_tool_error(QingflowApiError.config_error("audit_node_id must be positive"))
@@ -645,7 +702,9 @@ class ApprovalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("会签")
     def record_countersign(self, *, profile: str, app_key: str, apply_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         self._require_app_and_apply(app_key, apply_id)
         body = self._require_dict(payload)
         self._validate_countersign_payload(body)
@@ -664,6 +723,7 @@ class ApprovalTools(ToolBase):
         return self._run(profile, runner)
 
     def _request_route_payload(self, context) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)
@@ -676,12 +736,14 @@ class ApprovalTools(ToolBase):
         }
 
     def _require_app_and_apply(self, app_key: str, apply_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if apply_id <= 0:
             raise_tool_error(QingflowApiError.config_error("apply_id must be positive"))
 
     def _validate_comment_payload(self, payload: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
         comment_detail = payload.get("commentDetail")
         if not isinstance(comment_detail, dict):
             raise_tool_error(QingflowApiError.config_error("payload.commentDetail must be an object"))
@@ -689,6 +751,7 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.commentDetail.commentMsg is required"))
 
     def _normalize_approval_payload(self, profile: str, context, app_key: str, apply_id: int, payload: dict[str, Any]) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         body: JSONObject = dict(payload)
         self._normalize_alias(body, "auditFeedback", "audit_feedback")
         self._normalize_alias(body, "uploadFileSize", "upload_file_size")
@@ -708,6 +771,7 @@ class ApprovalTools(ToolBase):
         return body
 
     def _extract_node_id(self, payload: JSONObject) -> int:
+        """执行内部辅助逻辑。"""
         node_id = payload.get("nodeId")
         audit_node_id = payload.pop("auditNodeId", None)
         if node_id is None:
@@ -719,6 +783,7 @@ class ApprovalTools(ToolBase):
         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]
+        """执行内部辅助逻辑。"""
         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"))
@@ -733,6 +798,7 @@ class ApprovalTools(ToolBase):
         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]
+        """执行内部辅助逻辑。"""
         cache_key = f"{profile}:{app_key}"
         cached = self._form_id_cache.get(cache_key)
         if cached is not None:
@@ -745,6 +811,7 @@ class ApprovalTools(ToolBase):
         return form_id
 
     def _match_or_fill_int(self, payload: JSONObject, *, field_name: str, expected_value: int) -> int:
+        """执行内部辅助逻辑。"""
         current = payload.get(field_name)
         if current is None:
             return expected_value
@@ -755,6 +822,7 @@ class ApprovalTools(ToolBase):
         return current
 
     def _normalize_alias(self, payload: JSONObject, canonical_key: str, alias_key: str) -> None:
+        """执行内部辅助逻辑。"""
         alias_value = payload.pop(alias_key, None)
         if canonical_key not in payload and alias_value is not None:
             payload[canonical_key] = alias_value
@@ -762,6 +830,7 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error(f"payload.{canonical_key} and payload.{alias_key} must match when both are provided"))
 
     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,
@@ -790,6 +859,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]
+        """执行内部辅助逻辑。"""
         detail = self.backend.request(
             "GET",
             context,
@@ -810,6 +880,7 @@ class ApprovalTools(ToolBase):
         return normalized_answers
 
     def _validate_approval_payload(self, payload: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
         self._reject_unsupported_fields(payload)
         if not isinstance(payload.get("formId"), int) or payload["formId"] <= 0:
             raise_tool_error(QingflowApiError.config_error("payload.formId must be a positive integer"))
@@ -822,21 +893,25 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.answers must be an array when provided"))
 
     def _validate_audit_payload(self, payload: dict[str, Any], *, require_uid: bool = False) -> None:
+        """执行内部辅助逻辑。"""
         self._reject_unsupported_fields(payload)
         if require_uid and not payload.get("uid"):
             raise_tool_error(QingflowApiError.config_error("payload.uid is required"))
 
     def _validate_countersign_payload(self, payload: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
         self._reject_unsupported_fields(payload)
         members = payload.get("countersignMembers")
         if not isinstance(members, list) or not members:
             raise_tool_error(QingflowApiError.config_error("payload.countersignMembers must be a non-empty array"))
 
     def _reject_unsupported_fields(self, payload: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
         if payload.get("handSignImageUrl"):
             raise_tool_error(QingflowApiError.not_supported("NOT_SUPPORTED_IN_V1: handSignImageUrl is not supported"))
 
     def _extract_transfer_target_uid(self, payload: dict[str, Any]) -> int | None:
+        """执行内部辅助逻辑。"""
         for key in ("uid", "target_member_id", "targetMemberId"):
             value = payload.get(key)
             if isinstance(value, int) and value > 0:
@@ -844,6 +919,7 @@ class ApprovalTools(ToolBase):
         return None
 
     def _raise_if_self_transfer(self, *, profile: str, payload: dict[str, Any]) -> None:
+        """执行内部辅助逻辑。"""
         target_uid = self._extract_transfer_target_uid(payload)
         if target_uid is None:
             return
@@ -856,6 +932,7 @@ class ApprovalTools(ToolBase):
             )
 
     def _filter_self_transfer_candidates(self, *, profile: str, items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         session_profile = self.sessions.get_profile(profile)
         if session_profile is None:
             return items
@@ -874,6 +951,7 @@ class ApprovalTools(ToolBase):
         public_action: str,
         workflow_node_id: int | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         from .task_context_tools import TaskContextTools
 
         node_id = workflow_node_id
@@ -905,6 +983,7 @@ class ApprovalTools(ToolBase):
         pagination: dict[str, Any],
         selection: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
         response["warnings"] = []
@@ -925,6 +1004,7 @@ class ApprovalTools(ToolBase):
         selection: dict[str, Any],
         human_review: bool = False,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
         response["warnings"] = []
@@ -939,6 +1019,7 @@ class ApprovalTools(ToolBase):
         return response
 
     def _request_route_payload(self, context) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)