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

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,14 +38,30 @@ 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.tool()
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool(
+            description=(
+                "List workflow tasks. `query` first uses backend task search; if the backend returns zero rows, "
+                "public task_list falls back to local matching on app_name, workflow_node_name, app_key, and record_id."
+            )
+        )
         def task_list(
             profile: str = DEFAULT_PROFILE,
             task_box: str = "todo",
@@ -139,6 +155,7 @@ class TaskContextTools(ToolBase):
                 workflow_node_id=workflow_node_id,
             )
 
+    @tool_cn_name("任务上下文列表")
     def task_list(
         self,
         *,
@@ -151,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(
@@ -165,26 +183,55 @@ class TaskContextTools(ToolBase):
             create_time_asc=None,
         )
         task_page = raw.get("page", {})
+        warnings: list[dict[str, Any]] = []
         items = [
             self._normalize_task_item(item, task_box=task_box, flow_status=flow_status)
             for item in _task_page_items(task_page)
             if isinstance(item, dict)
         ]
+        returned_items = len(items)
+        page_amount = _task_page_amount(task_page)
+        reported_total = _task_page_total(task_page)
+        if query and not items:
+            fallback = self._task_list_local_query_fallback(
+                profile=profile,
+                task_box=task_box,
+                flow_status=flow_status,
+                app_key=app_key,
+                workflow_node_id=workflow_node_id,
+                query=query,
+                page=page,
+                page_size=page_size,
+            )
+            if fallback is not None:
+                items = fallback["items"]
+                returned_items = len(items)
+                page_amount = fallback["page_amount"]
+                reported_total = fallback["reported_total"]
+                warnings.append(
+                    {
+                        "code": "TASK_LIST_QUERY_FALLBACK_APPLIED",
+                        "message": (
+                            "backend searchKey returned zero tasks; task_list fell back to local matching on "
+                            "app_name, workflow_node_name, app_key, and record_id."
+                        ),
+                    }
+                )
         return {
             "profile": profile,
             "ws_id": raw.get("ws_id"),
             "ok": True,
             "request_route": raw.get("request_route"),
-            "warnings": [],
+            "warnings": warnings,
             "output_profile": "normal",
             "data": {
                 "items": items,
                 "pagination": {
                     "page": page,
                     "page_size": page_size,
-                    "returned_items": len(items),
-                    "page_amount": _task_page_amount(task_page),
-                    "reported_total": _task_page_total(task_page),
+                    "returned_items": returned_items,
+                    "page_amount": page_amount,
+                    "reported_total": reported_total,
                 },
                 "selection": {
                     "task_box": task_box,
@@ -196,6 +243,7 @@ class TaskContextTools(ToolBase):
             },
         }
 
+    @tool_cn_name("任务上下文详情")
     def task_get(
         self,
         *,
@@ -206,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):
@@ -232,6 +281,7 @@ class TaskContextTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务仅保存")
     def task_save_only(
         self,
         *,
@@ -241,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"))
@@ -254,6 +305,7 @@ class TaskContextTools(ToolBase):
             fields=field_updates,
         )
 
+    @tool_cn_name("执行任务动作")
     def task_action_execute(
         self,
         *,
@@ -265,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"}:
@@ -460,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):
@@ -555,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",
@@ -656,6 +711,25 @@ class TaskContextTools(ToolBase):
             or verification.get("downstream_todo_changed")
             or verification.get("workflow_log_advanced")
         )
+        record_state_error = verification.get("record_state_error")
+        runtime_consumed_after_action = bool(
+            runtime_verified
+            and isinstance(record_state_error, dict)
+            and record_state_error.get("backend_code") == 46001
+        )
+        if runtime_consumed_after_action:
+            verification["record_state_scope"] = "current_node_runtime"
+            verification["record_state_unavailable_reason"] = "runtime_consumed_after_action"
+            verification["record_state_unavailability_expected"] = True
+            warnings.append(
+                {
+                    "code": "TASK_RUNTIME_CONSUMED_AFTER_ACTION",
+                    "message": (
+                        "the current workflow node runtime is no longer readable after the action (backend 46001), "
+                        "which usually means the node has been consumed and the workflow has already continued."
+                    ),
+                }
+            )
         verification["runtime_continuation_verified"] = runtime_verified
         if not runtime_verified:
             warnings.append(
@@ -677,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",
@@ -790,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,
@@ -841,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,
@@ -916,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,
@@ -935,6 +1013,82 @@ class TaskContextTools(ToolBase):
             return []
         return [item for item in items if isinstance(item, dict)]
 
+    def _task_list_local_query_fallback(
+        self,
+        *,
+        profile: str,
+        task_box: str,
+        flow_status: str,
+        app_key: str | None,
+        workflow_node_id: int | None,
+        query: str,
+        page: int,
+        page_size: int,
+    ) -> dict[str, Any] | None:
+        normalized_type = self._task_tools._task_box_to_type(task_box)
+        normalized_status = self._task_tools._flow_status_to_process_status(flow_status)
+        scan_page_size = max(page_size, 100)
+        scan_page = 1
+        page_amount: int | None = None
+        matched_items: list[dict[str, Any]] = []
+        while True:
+            raw = self._task_tools.task_list(
+                profile=profile,
+                type=normalized_type,
+                process_status=normalized_status,
+                app_key=app_key,
+                node_id=workflow_node_id,
+                search_key=None,
+                page_num=scan_page,
+                page_size=scan_page_size,
+                create_time_asc=None,
+            )
+            task_page = raw.get("page", {})
+            raw_items = _task_page_items(task_page)
+            normalized_items = [
+                self._normalize_task_item(item, task_box=task_box, flow_status=flow_status)
+                for item in raw_items
+                if isinstance(item, dict)
+            ]
+            matched_items.extend(item for item in normalized_items if self._task_item_matches_query(item, query))
+            if page_amount is None:
+                coerced_page_amount = _coerce_count(_task_page_amount(task_page))
+                if coerced_page_amount is not None and coerced_page_amount > 0:
+                    page_amount = coerced_page_amount
+            if page_amount is not None and scan_page >= page_amount:
+                break
+            if not raw_items or len(raw_items) < scan_page_size:
+                break
+            scan_page += 1
+        if not matched_items:
+            return None
+        start = max(page - 1, 0) * page_size
+        end = start + page_size
+        matched_total = len(matched_items)
+        matched_page_amount = (matched_total + page_size - 1) // page_size if page_size > 0 else 0
+        return {
+            "items": matched_items[start:end],
+            "page_amount": matched_page_amount,
+            "reported_total": matched_total,
+        }
+
+    def _task_item_matches_query(self, item: dict[str, Any], query: str) -> bool:
+        needle = str(query or "").strip().casefold()
+        if not needle:
+            return False
+        for candidate in (
+            item.get("app_name"),
+            item.get("workflow_node_name"),
+            item.get("app_key"),
+            item.get("record_id"),
+        ):
+            if candidate in (None, ""):
+                continue
+            if needle in str(candidate).casefold():
+                return True
+        return False
+
+    @tool_cn_name("任务关联报表详情")
     def task_associated_report_detail_get(
         self,
         *,
@@ -946,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"))
@@ -1125,6 +1280,7 @@ class TaskContextTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务流程日志")
     def task_workflow_log_get(
         self,
         *,
@@ -1133,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):
@@ -1202,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,
@@ -1416,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]:
@@ -1553,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")
@@ -1570,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(
@@ -1598,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")
@@ -1648,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:
@@ -1768,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 = {
@@ -1807,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(
@@ -1836,6 +2006,7 @@ class TaskContextTools(ToolBase):
         app_key: str,
         workflow_node_id: int,
     ) -> tuple[bool, list[JSONObject], str]:
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request(
                 "GET",
@@ -1855,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
@@ -1878,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()
@@ -1912,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 {}
@@ -1996,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]] = []
@@ -2045,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",
@@ -2064,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")),
@@ -2073,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 {
@@ -2094,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):
@@ -2101,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]] = []
@@ -2187,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:
@@ -2194,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:
@@ -2228,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:
@@ -2249,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 []
@@ -2276,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"),
@@ -2290,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:
@@ -2305,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):
@@ -2327,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):
@@ -2375,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:
@@ -2383,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:
@@ -2390,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"):
@@ -2399,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"):
@@ -2408,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"):
@@ -2417,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():
@@ -2424,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:
@@ -2436,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:
@@ -2444,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):
@@ -2453,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)