@josephyan/qingflow-cli 0.2.0-beta.985 → 0.2.0-beta.987

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -12,7 +12,7 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from .approval_tools import ApprovalTools, _approval_page_amount, _approval_page_items, _approval_page_total
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .qingbi_report_tools import _qingbi_base_url
 from .record_tools import (
     FieldIndex,
@@ -38,13 +38,24 @@ from .task_tools import TaskTools, _task_page_amount, _task_page_items, _task_pa
 
 
 class TaskContextTools(ToolBase):
+    """任务上下文工具（中文名：任务上下文与审批执行）。
+
+    类型：任务深度上下文工具。
+    主要职责：
+    1. 聚合任务详情、候选人、关联报表与流程日志；
+    2. 执行审批动作（通过、驳回、转交等）；
+    3. 为任务处理过程提供可执行上下文而非仅列表数据。
+    """
+
     def __init__(self, sessions, backend) -> None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._task_tools = TaskTools(sessions, backend)
         self._approval_tools = ApprovalTools(sessions, backend)
         self._record_tools = RecordTools(sessions, backend)
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool(
             description=(
                 "List workflow tasks. `query` first uses backend task search; if the backend returns zero rows, "
@@ -144,6 +155,7 @@ class TaskContextTools(ToolBase):
                 workflow_node_id=workflow_node_id,
             )
 
+    @tool_cn_name("任务上下文列表")
     def task_list(
         self,
         *,
@@ -156,6 +168,7 @@ class TaskContextTools(ToolBase):
         page: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         normalized_type = self._task_tools._task_box_to_type(task_box)
         normalized_status = self._task_tools._flow_status_to_process_status(flow_status)
         raw = self._task_tools.task_list(
@@ -230,6 +243,7 @@ class TaskContextTools(ToolBase):
             },
         }
 
+    @tool_cn_name("任务上下文详情")
     def task_get(
         self,
         *,
@@ -240,6 +254,7 @@ class TaskContextTools(ToolBase):
         include_candidates: bool,
         include_associated_reports: bool,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._require_app_record_and_node(app_key, record_id, workflow_node_id)
 
         def runner(session_profile, context):
@@ -266,6 +281,7 @@ class TaskContextTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务仅保存")
     def task_save_only(
         self,
         *,
@@ -275,6 +291,7 @@ class TaskContextTools(ToolBase):
         workflow_node_id: int,
         fields: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         field_updates = dict(fields or {})
         if not field_updates:
             raise_tool_error(QingflowApiError.config_error("fields is required and must be non-empty for task_save_only"))
@@ -288,6 +305,7 @@ class TaskContextTools(ToolBase):
             fields=field_updates,
         )
 
+    @tool_cn_name("执行任务动作")
     def task_action_execute(
         self,
         *,
@@ -299,6 +317,7 @@ class TaskContextTools(ToolBase):
         payload: dict[str, Any],
         fields: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._require_app_record_and_node(app_key, record_id, workflow_node_id)
         normalized_action = (action or "").strip().lower()
         if normalized_action not in {"approve", "reject", "rollback", "transfer", "urge", "save_only"}:
@@ -494,6 +513,7 @@ class TaskContextTools(ToolBase):
         payload: dict[str, Any],
         prepared_fields: dict[str, Any] | None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         merged_answers = None
         normalized_answers = None
         if isinstance(prepared_fields, dict):
@@ -589,6 +609,7 @@ class TaskContextTools(ToolBase):
         before_apply_status: Any,
         runtime_baseline: dict[str, Any] | None = None,
     ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """执行内部辅助逻辑。"""
         verification: dict[str, Any] = {
             "action_executed": True,
             "runtime_continuation_verified": action == "urge",
@@ -730,6 +751,7 @@ class TaskContextTools(ToolBase):
         expected_answers: list[dict[str, Any]],
         task_context: dict[str, Any],
     ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """执行内部辅助逻辑。"""
         verification: dict[str, Any] = {
             "action_executed": True,
             "scope": "task_field_save",
@@ -843,6 +865,7 @@ class TaskContextTools(ToolBase):
         record_id: int,
         workflow_node_id: int,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         baseline: dict[str, Any] = {
             "workflow_log_visible": False,
             "workflow_log_count": None,
@@ -894,6 +917,7 @@ class TaskContextTools(ToolBase):
         source_error: QingflowApiError,
         before_apply_status: Any,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         verification, warnings = self._verify_task_action_runtime(
             profile=profile,
             context=context,
@@ -969,6 +993,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _safe_task_list_items(self, *, profile: str, task_box: str, app_key: str) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         try:
             response = self.task_list(
                 profile=profile,
@@ -1063,6 +1088,7 @@ class TaskContextTools(ToolBase):
                 return True
         return False
 
+    @tool_cn_name("任务关联报表详情")
     def task_associated_report_detail_get(
         self,
         *,
@@ -1074,6 +1100,7 @@ class TaskContextTools(ToolBase):
         page: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._require_app_record_and_node(app_key, record_id, workflow_node_id)
         if report_id <= 0:
             raise_tool_error(QingflowApiError.config_error("report_id must be positive"))
@@ -1253,6 +1280,7 @@ class TaskContextTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务流程日志")
     def task_workflow_log_get(
         self,
         *,
@@ -1261,6 +1289,7 @@ class TaskContextTools(ToolBase):
         record_id: int,
         workflow_node_id: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._require_app_record_and_node(app_key, record_id, workflow_node_id)
 
         def runner(session_profile, context):
@@ -1330,6 +1359,7 @@ class TaskContextTools(ToolBase):
         include_associated_reports: bool,
         current_uid: int | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         audit_infos = self.backend.request(
             "GET",
             context,
@@ -1544,6 +1574,12 @@ class TaskContextTools(ToolBase):
                 },
             },
         }
+        action_metadata = self._compact_task_action_metadata(capabilities)
+        if action_metadata:
+            compact["action_metadata"] = action_metadata
+        editable_metadata = self._compact_task_editable_metadata(update_schema)
+        if editable_metadata:
+            compact["editable_metadata"] = editable_metadata
         return compact
 
     def _compact_task_action_metadata(self, capabilities: dict[str, Any]) -> dict[str, Any]:
@@ -1681,6 +1717,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _normalize_task_item(self, raw: dict[str, Any], *, task_box: str, flow_status: str) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         app_key = raw.get("appKey") or raw.get("app_key")
         record_id = raw.get("rowRecordId") or raw.get("recordId") or raw.get("applyId")
         workflow_node_id = raw.get("nodeId") or raw.get("auditNodeId")
@@ -1698,6 +1735,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _select_task_node(self, infos: Any, workflow_node_id: int, *, app_key: str, record_id: int) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         if not isinstance(infos, list) or not infos:
             raise_tool_error(
                 QingflowApiError.config_error(
@@ -1726,6 +1764,7 @@ class TaskContextTools(ToolBase):
         warnings: list[JSONObject] | None = None,
         save_only_source: str = "workflow_editable_que_ids",
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         available_actions = ["approve"]
         if self._coerce_bool(node_info.get("rejectBtnStatus")):
             available_actions.append("reject")
@@ -1776,6 +1815,7 @@ class TaskContextTools(ToolBase):
         node_info: dict[str, Any],
         current_answers: Any,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         try:
             app_schema = self._record_tools._get_form_schema(profile, context, app_key, force_refresh=False)
         except QingflowApiError as error:
@@ -1896,6 +1936,7 @@ class TaskContextTools(ToolBase):
         current_answers: Any,
         editable_question_ids: set[int],
     ) -> tuple[FieldIndex, list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         if not editable_question_ids:
             return index, []
         missing_field_ids = {
@@ -1935,6 +1976,7 @@ class TaskContextTools(ToolBase):
         workflow_node_id: int,
         node_info: dict[str, Any],
     ) -> tuple[set[int], list[JSONObject], str]:
+        """执行内部辅助逻辑。"""
         warnings: list[JSONObject] = []
         try:
             payload = self.backend.request(
@@ -1964,6 +2006,7 @@ class TaskContextTools(ToolBase):
         app_key: str,
         workflow_node_id: int,
     ) -> tuple[bool, list[JSONObject], str]:
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request(
                 "GET",
@@ -1983,6 +2026,7 @@ class TaskContextTools(ToolBase):
         return bool(self._extract_question_ids(payload)), [], "workflow_editable_que_ids"
 
     def _extract_question_ids(self, payload: Any) -> set[int]:
+        """执行内部辅助逻辑。"""
         candidates: list[Any] = []
         if isinstance(payload, list):
             candidates = payload
@@ -2006,6 +2050,7 @@ class TaskContextTools(ToolBase):
         return question_ids
 
     def _editable_ids_from_que_auth_setting(self, payload: Any) -> set[int]:
+        """执行内部辅助逻辑。"""
         if not isinstance(payload, list):
             return set()
         editable_ids: set[int] = set()
@@ -2040,6 +2085,7 @@ class TaskContextTools(ToolBase):
         task_context: dict[str, Any],
         fields: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         record = task_context.get("record") if isinstance(task_context.get("record"), dict) else {}
         current_answers = record.get("answers") if isinstance(record.get("answers"), list) else []
         node = task_context.get("node") if isinstance(task_context.get("node"), dict) else {}
@@ -2124,6 +2170,7 @@ class TaskContextTools(ToolBase):
         index: Any,
         effective_editable_ids: set[int],
     ) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         if index is None:
             return []
         field_errors: list[dict[str, Any]] = []
@@ -2173,6 +2220,7 @@ class TaskContextTools(ToolBase):
         workflow_node_id: int,
         apply_answers: list[dict[str, Any]],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request(
                 "POST",
@@ -2192,6 +2240,7 @@ class TaskContextTools(ToolBase):
         return self._run(profile, runner)
 
     def _build_visibility(self, node_info: dict[str, Any], detail: dict[str, Any]) -> dict[str, bool]:
+        """执行内部辅助逻辑。"""
         return {
             "comment_visible": self._coerce_bool(node_info.get("commentStatus")),
             "audit_record_visible": self._coerce_bool(node_info.get("auditRecordVisible")),
@@ -2201,12 +2250,14 @@ class TaskContextTools(ToolBase):
         }
 
     def _resolve_associated_report_visible(self, node_info: dict[str, Any], detail: dict[str, Any]) -> bool:
+        """执行内部辅助逻辑。"""
         node_visible = node_info.get("asosChartVisible")
         if node_visible is not None:
             return self._coerce_bool(node_visible)
         return self._coerce_bool(detail.get("viewAsosChartVisible"))
 
     def _normalize_associated_report(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         graph_type = str(raw.get("graphType") or "").strip().lower()
         source_type = str(raw.get("sourceType") or "").strip().lower()
         return {
@@ -2222,6 +2273,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _rollback_candidate_items(self, payload: Any) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         if isinstance(payload, dict):
             revert_nodes = payload.get("revertNodes")
             if isinstance(revert_nodes, list):
@@ -2229,6 +2281,7 @@ class TaskContextTools(ToolBase):
         return [item for item in _approval_page_items(payload) if isinstance(item, dict)]
 
     def _filter_transfer_members(self, items: Any, *, current_uid: int | None) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         if not isinstance(items, list):
             return []
         filtered: list[dict[str, Any]] = []
@@ -2315,6 +2368,7 @@ class TaskContextTools(ToolBase):
         return json.dumps(item, ensure_ascii=False, sort_keys=True, default=str)
 
     def _find_associated_report(self, task_context: dict[str, Any], report_id: int) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         associated_reports = ((task_context.get("associated_reports") or {}).get("items") or [])
         for item in associated_reports:
             if isinstance(item, dict) and item.get("report_id") == report_id:
@@ -2322,6 +2376,7 @@ class TaskContextTools(ToolBase):
         return None
 
     def _build_association_query(self, asos_chart: dict[str, Any], answers: list[dict[str, Any]]) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         key_que_ids = self._collect_match_rule_question_ids(asos_chart.get("matchRules") or [])
         key_values: list[dict[str, Any]] = []
         for answer in answers:
@@ -2356,6 +2411,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _collect_match_rule_question_ids(self, match_rules: Any) -> set[int]:
+        """执行内部辅助逻辑。"""
         question_ids: set[int] = set()
 
         def visit(node: Any) -> None:
@@ -2377,6 +2433,7 @@ class TaskContextTools(ToolBase):
         return question_ids
 
     def _extract_answer_values(self, answer: dict[str, Any]) -> list[str]:
+        """执行内部辅助逻辑。"""
         values = answer.get("values")
         if not isinstance(values, list):
             return []
@@ -2404,6 +2461,7 @@ class TaskContextTools(ToolBase):
         return deduped
 
     def _sanitize_associated_chart(self, asos_chart: dict[str, Any]) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         return {
             "id": asos_chart.get("id"),
             "appKey": asos_chart.get("appKey"),
@@ -2418,6 +2476,7 @@ class TaskContextTools(ToolBase):
         }
 
     def _qingflow_chart_uses_apply_filter(self, context: BackendRequestContext, chart_key: str) -> bool:
+        """执行内部辅助逻辑。"""
         if not chart_key:
             return False
         try:
@@ -2433,6 +2492,7 @@ class TaskContextTools(ToolBase):
         return self._coerce_bool(auth.get("detailedViewStatus")) and auth.get("lastViewType") == 1
 
     def _normalize_chart_result(self, payload: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         if isinstance(payload, dict):
             rows = payload.get("rows")
             if not isinstance(rows, list):
@@ -2455,6 +2515,7 @@ class TaskContextTools(ToolBase):
         return {"summary": {}, "rows": [], "series": [], "metrics": []}
 
     def _normalize_workflow_logs(self, payload: Any) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         if isinstance(payload, dict):
             page = payload.get("list") if isinstance(payload.get("list"), list) else payload.get("rows")
             if not isinstance(page, list):
@@ -2503,6 +2564,7 @@ class TaskContextTools(ToolBase):
         return items
 
     def _workflow_log_digest(self, items: list[dict[str, Any]]) -> str | None:
+        """执行内部辅助逻辑。"""
         if not items:
             return None
         try:
@@ -2511,6 +2573,7 @@ class TaskContextTools(ToolBase):
             return str(items)
 
     def _first_nested_operation_detail(self, operation: dict[str, Any]) -> Any:
+        """执行内部辅助逻辑。"""
         for key in ("approval", "filling", "cc", "applicant", "qRobotAdd", "qRobotUpdate", "webhook", "qRobotSMS", "qRobotMail"):
             value = operation.get(key)
             if value is not None:
@@ -2518,6 +2581,7 @@ class TaskContextTools(ToolBase):
         return None
 
     def _extract_remark(self, detail: Any) -> Any:
+        """执行内部辅助逻辑。"""
         if not isinstance(detail, dict):
             return None
         for key in ("remark", "feedback", "comment", "content"):
@@ -2527,6 +2591,7 @@ class TaskContextTools(ToolBase):
         return None
 
     def _extract_signature_url(self, detail: Any) -> Any:
+        """执行内部辅助逻辑。"""
         if not isinstance(detail, dict):
             return None
         for key in ("signatureUrl", "handSignImageUrl"):
@@ -2536,6 +2601,7 @@ class TaskContextTools(ToolBase):
         return None
 
     def _extract_attachments(self, detail: Any) -> Any:
+        """执行内部辅助逻辑。"""
         if not isinstance(detail, dict):
             return []
         for key in ("attachments", "files", "uploadFiles"):
@@ -2545,6 +2611,7 @@ class TaskContextTools(ToolBase):
         return []
 
     def _extract_audit_feedback(self, payload: dict[str, Any]) -> str | None:
+        """执行内部辅助逻辑。"""
         for key in ("audit_feedback", "auditFeedback"):
             value = payload.get(key)
             if isinstance(value, str) and value.strip():
@@ -2552,6 +2619,7 @@ class TaskContextTools(ToolBase):
         return None
 
     def _extract_positive_int(self, payload: dict[str, Any], key: str, *, aliases: tuple[str, ...] = ()) -> int:
+        """执行内部辅助逻辑。"""
         candidates = (key, *aliases)
         value: Any = None
         for candidate in candidates:
@@ -2564,6 +2632,7 @@ class TaskContextTools(ToolBase):
         return value
 
     def _require_app_record_and_node(self, app_key: str, record_id: int, workflow_node_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if record_id <= 0:
@@ -2572,6 +2641,7 @@ class TaskContextTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("workflow_node_id must be positive"))
 
     def _coerce_bool(self, value: Any) -> bool:
+        """执行内部辅助逻辑。"""
         if isinstance(value, bool):
             return value
         if isinstance(value, int):
@@ -2581,6 +2651,7 @@ class TaskContextTools(ToolBase):
         return bool(value)
 
     def _request_route_payload(self, context: BackendRequestContext) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)