@josephyan/qingflow-app-builder-mcp 0.2.0-beta.31 → 0.2.0-beta.32

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.31
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.32
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.31 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.32 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.31",
+  "version": "0.2.0-beta.32",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b31"
+version = "0.2.0b32"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b31"
+__version__ = "0.2.0b32"

package/src/qingflow_mcp/server.py

@@ -17,6 +17,7 @@ from .tools.qingbi_report_tools import QingbiReportTools
 from .tools.record_tools import RecordTools
 from .tools.role_tools import RoleTools
 from .tools.solution_tools import SolutionTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.view_tools import ViewTools
 from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
@@ -93,6 +94,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -115,6 +124,7 @@ Avoid builder-side app or schema changes here.""",
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_user.py

@@ -12,6 +12,7 @@ from .tools.auth_tools import AuthTools
 from .tools.directory_tools import DirectoryTools
 from .tools.file_tools import FileTools
 from .tools.record_tools import RecordTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
 
 
@@ -81,6 +82,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -221,6 +230,7 @@ Avoid builder-side app or schema changes here.""",
     )
 
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
 
     return server

package/src/qingflow_mcp/tools/approval_tools.py

@@ -611,9 +611,11 @@ class ApprovalTools(ToolBase):
         self._normalize_alias(body, "formId", "form_id")
 
         node_id = self._extract_node_id(body)
-        body["nodeId"] = node_id
+        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"))
+        if body.get("answers") is None:
+            body["answers"] = self._fetch_current_todo_answers(context, app_key, apply_id, body["nodeId"])
 
         self._validate_approval_payload(body)
         return body
@@ -672,6 +674,54 @@ class ApprovalTools(ToolBase):
         elif alias_value is not None and payload.get(canonical_key) != alias_value:
             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,
+            f"/app/{app_key}/apply/{apply_id}/auditInfo",
+            params={"type": 1},
+        )
+        if not isinstance(infos, list) or not infos:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"apply_id={apply_id} is not currently actionable for the logged-in user in todo list"
+                )
+            )
+        actionable_node_ids = {
+            candidate
+            for item in infos
+            if isinstance(item, dict)
+            for candidate in (item.get("auditNodeId"), item.get("nodeId"))
+            if isinstance(candidate, int) and candidate > 0
+        }
+        if node_id not in actionable_node_ids:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"payload.nodeId={node_id} is not an actionable todo node for apply_id={apply_id}"
+                )
+            )
+        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,
+            f"/app/{app_key}/apply/{apply_id}",
+            params={"role": 3, "listType": 1, "auditNodeId": node_id},
+        )
+        answers = detail.get("answers") if isinstance(detail, dict) else None
+        if not isinstance(answers, list):
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"cannot resolve current answers for apply_id={apply_id} nodeId={node_id}"
+                )
+            )
+        normalized_answers: list[dict[str, Any]] = []
+        for item in answers:
+            if isinstance(item, dict):
+                normalized_answers.append(dict(item))
+        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:
@@ -680,6 +730,9 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.applyId must be a positive integer"))
         if not isinstance(payload.get("nodeId"), int) or payload["nodeId"] <= 0:
             raise_tool_error(QingflowApiError.config_error("payload.nodeId must be a positive integer"))
+        answers = payload.get("answers")
+        if answers is not None and not isinstance(answers, list):
+            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)

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -0,0 +1,1063 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from mcp.server.fastmcp import FastMCP
+
+from ..backend_client import BackendRequestContext
+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 .qingbi_report_tools import _qingbi_base_url
+from .task_tools import TaskTools, _task_page_amount, _task_page_items, _task_page_total
+
+
+class TaskContextTools(ToolBase):
+    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)
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool()
+        def task_list(
+            profile: str = DEFAULT_PROFILE,
+            task_box: str = "todo",
+            flow_status: str = "all",
+            app_key: str | None = None,
+            workflow_node_id: int | None = None,
+            query: str | None = None,
+            page: int = 1,
+            page_size: int = 20,
+        ) -> dict[str, Any]:
+            return self.task_list(
+                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,
+            )
+
+        @mcp.tool()
+        def task_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            record_id: int = 0,
+            workflow_node_id: int = 0,
+            include_candidates: bool = True,
+            include_associated_reports: bool = True,
+        ) -> dict[str, Any]:
+            return self.task_get(
+                profile=profile,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                include_candidates=include_candidates,
+                include_associated_reports=include_associated_reports,
+            )
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="execute", target="workflow task action"))
+        def task_action_execute(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            record_id: int = 0,
+            workflow_node_id: int = 0,
+            action: str = "",
+            payload: dict[str, Any] | None = None,
+        ) -> dict[str, Any]:
+            return self.task_action_execute(
+                profile=profile,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                action=action,
+                payload=payload or {},
+            )
+
+        @mcp.tool()
+        def task_associated_report_detail_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            record_id: int = 0,
+            workflow_node_id: int = 0,
+            report_id: int = 0,
+            page: int = 1,
+            page_size: int = 20,
+        ) -> dict[str, Any]:
+            return self.task_associated_report_detail_get(
+                profile=profile,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                report_id=report_id,
+                page=page,
+                page_size=page_size,
+            )
+
+        @mcp.tool()
+        def task_workflow_log_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            record_id: int = 0,
+            workflow_node_id: int = 0,
+        ) -> dict[str, Any]:
+            return self.task_workflow_log_get(
+                profile=profile,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+            )
+
+    def task_list(
+        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,
+    ) -> 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(
+            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=None,
+        )
+        task_page = raw.get("page", {})
+        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)
+        ]
+        return {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": True,
+            "request_route": raw.get("request_route"),
+            "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),
+                },
+                "selection": {
+                    "task_box": task_box,
+                    "flow_status": flow_status,
+                    "app_key": app_key,
+                    "workflow_node_id": workflow_node_id,
+                    "query": query,
+                },
+            },
+        }
+
+    def task_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        workflow_node_id: int,
+        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):
+            data = self._build_task_context(
+                context,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                include_candidates=include_candidates,
+                include_associated_reports=include_associated_reports,
+            )
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": "normal",
+                "data": data,
+            }
+
+        return self._run(profile, runner)
+
+    def task_action_execute(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        workflow_node_id: int,
+        action: str,
+        payload: dict[str, Any],
+    ) -> 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"}:
+            raise_tool_error(
+                QingflowApiError.not_supported(
+                    "TASK_ACTION_UNSUPPORTED: action must be one of approve, reject, rollback, transfer, or urge"
+                )
+            )
+        body = dict(payload or {})
+        context_summary = self.task_get(
+            profile=profile,
+            app_key=app_key,
+            record_id=record_id,
+            workflow_node_id=workflow_node_id,
+            include_candidates=False,
+            include_associated_reports=False,
+        )
+        capabilities = ((context_summary.get("data") or {}).get("capabilities") or {})
+        available_actions = capabilities.get("available_actions") or []
+        if normalized_action not in available_actions:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"task action '{normalized_action}' is not currently available for app_key='{app_key}' record_id={record_id} workflow_node_id={workflow_node_id}"
+                )
+            )
+        feedback_required_for = capabilities.get("action_constraints", {}).get("feedback_required_for") or []
+        if normalized_action in feedback_required_for and not self._extract_audit_feedback(body):
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"payload.audit_feedback is required for action '{normalized_action}' on the current node"
+                )
+            )
+
+        if normalized_action == "approve":
+            action_payload = dict(body)
+            action_payload["nodeId"] = workflow_node_id
+            raw = self._approval_tools.record_approve(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                payload=action_payload,
+            )
+        elif normalized_action == "reject":
+            action_payload = dict(body)
+            action_payload["nodeId"] = workflow_node_id
+            if not self._extract_audit_feedback(action_payload):
+                raise_tool_error(QingflowApiError.config_error("payload.audit_feedback is required for reject"))
+            raw = self._approval_tools.record_reject(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                payload=action_payload,
+            )
+        elif normalized_action == "rollback":
+            target_node_id = self._extract_positive_int(body, "target_workflow_node_id", aliases=("targetAuditNodeId", "targetWorkflowNodeId"))
+            action_payload: JSONObject = {
+                "auditNodeId": workflow_node_id,
+                "targetAuditNodeId": target_node_id,
+            }
+            audit_feedback = self._extract_audit_feedback(body)
+            if audit_feedback:
+                action_payload["auditFeedback"] = audit_feedback
+            raw = self._approval_tools.record_rollback(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                payload=action_payload,
+            )
+        elif normalized_action == "transfer":
+            target_member_id = self._extract_positive_int(body, "target_member_id", aliases=("uid", "targetMemberId"))
+            action_payload = {
+                "auditNodeId": workflow_node_id,
+                "uid": target_member_id,
+            }
+            audit_feedback = self._extract_audit_feedback(body)
+            if audit_feedback:
+                action_payload["auditFeedback"] = audit_feedback
+            raw = self._approval_tools.record_transfer(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                payload=action_payload,
+            )
+        else:
+            raw = self._task_tools.task_urge(
+                profile=profile,
+                app_key=app_key,
+                row_record_id=record_id,
+            )
+
+        return {
+            "profile": raw.get("profile", profile),
+            "ws_id": raw.get("ws_id"),
+            "ok": bool(raw.get("ok", True)),
+            "request_route": raw.get("request_route"),
+            "warnings": [],
+            "output_profile": "normal",
+            "data": {
+                "action": normalized_action,
+                "resource": {
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "workflow_node_id": workflow_node_id,
+                },
+                "selection": {"action": normalized_action},
+                "result": raw.get("result"),
+                "human_review": True,
+            },
+        }
+
+    def task_associated_report_detail_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        workflow_node_id: int,
+        report_id: int,
+        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"))
+        if page <= 0 or page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page and page_size must be positive"))
+
+        def runner(session_profile, context):
+            task_context = self._build_task_context(
+                context,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                include_candidates=False,
+                include_associated_reports=True,
+            )
+            report_item = self._find_associated_report(task_context, report_id)
+            if report_item is None:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"report_id={report_id} is not visible for app_key='{app_key}' record_id={record_id} workflow_node_id={workflow_node_id}"
+                    )
+                )
+            association_query = self._build_association_query(
+                report_item["raw"],
+                task_context.get("record", {}).get("answers") or [],
+            )
+            selection = {
+                "app_key": app_key,
+                "record_id": record_id,
+                "workflow_node_id": workflow_node_id,
+                "report_id": report_id,
+                "target_app_key": report_item.get("target_app_key"),
+                "target_app_name": report_item.get("target_app_name"),
+                "chart_key": report_item.get("chart_key"),
+                "chart_name": report_item.get("chart_name"),
+            }
+            context_payload = {
+                "match_rules": report_item.get("match_rules") or [],
+                "resolved_filters": association_query.get("keyQueValues") or [],
+            }
+
+            if report_item.get("graph_type") == "view":
+                viewgraph_key = str(report_item.get("chart_key") or "")
+                body = {
+                    "filter": {},
+                    "viewgraphKey": viewgraph_key,
+                    "equipmentType": 0,
+                    "associationQuery": association_query,
+                }
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/view/{viewgraph_key}/apply/filter",
+                    json_body=body,
+                )
+                items = _task_page_items(result)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": True,
+                    "request_route": self._request_route_payload(context),
+                    "warnings": [],
+                    "output_profile": "normal",
+                    "data": {
+                        "result_type": "view_list",
+                        "result": {
+                            "items": items,
+                            "pagination": {
+                                "page": page,
+                                "page_size": page_size,
+                                "returned_items": len(items),
+                                "page_amount": _task_page_amount(result),
+                                "reported_total": _task_page_total(result),
+                            },
+                        },
+                        "selection": selection,
+                        "context": context_payload,
+                    },
+                }
+
+            chart_key = str(report_item.get("chart_key") or "")
+            source_type = report_item.get("source_type")
+            if source_type == "qingbi":
+                qingbi_context = BackendRequestContext(
+                    base_url=_qingbi_base_url(context.base_url),
+                    token=context.token,
+                    ws_id=context.ws_id,
+                    qf_request_id=context.qf_request_id,
+                    qf_version=context.qf_version,
+                    qf_version_source=context.qf_version_source,
+                )
+                chart_result = self.backend.request(
+                    "POST",
+                    qingbi_context,
+                    f"/qingbi/charts/data/{chart_key}",
+                    params={
+                        "qfUUID": uuid4().hex,
+                        "pageNum": page,
+                        "pageSize": page_size,
+                    },
+                    json_body={
+                        "asosChartId": report_id,
+                        "keyQueValues": association_query.get("keyQueValues") or [],
+                    },
+                )
+                request_route = {
+                    "base_url": qingbi_context.base_url,
+                    "qf_version": qingbi_context.qf_version,
+                    "qf_version_source": qingbi_context.qf_version_source or "context",
+                }
+            elif self._qingflow_chart_uses_apply_filter(context, chart_key):
+                chart_result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/chart/{chart_key}/apply/filter",
+                    json_body={
+                        "filter": {
+                            "pageNum": page,
+                            "pageSize": page_size,
+                        },
+                        "asosChartId": report_id,
+                        "keyQueValues": association_query.get("keyQueValues") or [],
+                    },
+                )
+                items = _task_page_items(chart_result)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": True,
+                    "request_route": self._request_route_payload(context),
+                    "warnings": [],
+                    "output_profile": "normal",
+                    "data": {
+                        "result_type": "view_list",
+                        "result": {
+                            "items": items,
+                            "pagination": {
+                                "page": page,
+                                "page_size": page_size,
+                                "returned_items": len(items),
+                                "page_amount": _task_page_amount(chart_result),
+                                "reported_total": _task_page_total(chart_result),
+                            },
+                        },
+                        "selection": selection,
+                        "context": context_payload,
+                    },
+                }
+            else:
+                chart_result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/chart/{chart_key}/chartData",
+                    json_body={
+                        "asosChartId": report_id,
+                        "keyQueValues": association_query.get("keyQueValues") or [],
+                    },
+                )
+                request_route = self._request_route_payload(context)
+
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": request_route,
+                "warnings": [],
+                "output_profile": "normal",
+                "data": {
+                    "result_type": "chart_data",
+                    "result": self._normalize_chart_result(chart_result),
+                    "selection": selection,
+                    "context": context_payload,
+                },
+            }
+
+        return self._run(profile, runner)
+
+    def task_workflow_log_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        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):
+            task_context = self._build_task_context(
+                context,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                include_candidates=False,
+                include_associated_reports=False,
+            )
+            visibility = task_context.get("visibility") or {}
+            if not visibility.get("audit_record_visible"):
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"workflow logs are not visible for app_key='{app_key}' record_id={record_id} workflow_node_id={workflow_node_id}"
+                    )
+                )
+            page = self.backend.request(
+                "POST",
+                context,
+                "/application/workflow/node/record",
+                json_body={
+                    "key": app_key,
+                    "rowRecordId": record_id,
+                    "nodeId": workflow_node_id,
+                    "role": 3,
+                    "pageNum": 1,
+                    "pageSize": 200,
+                },
+            )
+            items = self._normalize_workflow_logs(page)
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": "normal",
+                "data": {
+                    "selection": {
+                        "app_key": app_key,
+                        "record_id": record_id,
+                        "workflow_node_id": workflow_node_id,
+                    },
+                    "visibility": {
+                        "audit_record_visible": visibility.get("audit_record_visible"),
+                        "qrobot_record_visible": visibility.get("qrobot_record_visible"),
+                    },
+                    "items": items,
+                },
+            }
+
+        return self._run(profile, runner)
+
+    def _build_task_context(
+        self,
+        context: BackendRequestContext,
+        *,
+        app_key: str,
+        record_id: int,
+        workflow_node_id: int,
+        include_candidates: bool,
+        include_associated_reports: bool,
+    ) -> dict[str, Any]:
+        audit_infos = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{record_id}/auditInfo",
+            params={"type": 1},
+        )
+        node_info = self._select_task_node(audit_infos, workflow_node_id, app_key=app_key, record_id=record_id)
+        detail = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{record_id}",
+            params={"role": 3, "listType": 1, "auditNodeId": workflow_node_id},
+        )
+        associated_report_visible = self._resolve_associated_report_visible(node_info, detail)
+        associated_reports = {"visible": associated_report_visible, "count": 0, "items": []}
+        if include_associated_reports and associated_report_visible:
+            asos_chart_list = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/asosChart",
+                params={"role": 3, "auditNodeId": workflow_node_id, "beingDraft": False},
+            )
+            associated_items = [
+                self._normalize_associated_report(item)
+                for item in (asos_chart_list.get("asosCharts") or [])
+                if isinstance(item, dict)
+            ]
+            associated_reports = {
+                "visible": True,
+                "count": len(associated_items),
+                "items": associated_items,
+            }
+        rollback_items: list[dict[str, Any]] = []
+        transfer_items: list[dict[str, Any]] = []
+        if include_candidates:
+            rollback_result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{record_id}/revertNode",
+                params={"auditNodeId": workflow_node_id},
+            )
+            rollback_items = self._rollback_candidate_items(rollback_result)
+            transfer_result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{record_id}/transfer/member",
+                params={"pageNum": 1, "pageSize": 20, "auditNodeId": workflow_node_id},
+            )
+            transfer_items = _approval_page_items(transfer_result)
+
+        capabilities = self._build_capabilities(node_info)
+        visibility = self._build_visibility(node_info, detail)
+        return {
+            "task": {
+                "app_key": app_key,
+                "record_id": record_id,
+                "workflow_node_id": workflow_node_id,
+                "workflow_node_name": node_info.get("auditNodeName") or node_info.get("nodeName"),
+                "actionable": True,
+            },
+            "record": {
+                "apply_id": detail.get("applyId", record_id),
+                "apply_status": detail.get("applyStatus"),
+                "apply_num": detail.get("applyNum"),
+                "custom_apply_num": detail.get("customApplyNum"),
+                "apply_user": detail.get("applyUser"),
+                "apply_time": detail.get("applyTime"),
+                "last_update_time": detail.get("lastUpdateTime"),
+                "answers": detail.get("answers") or [],
+            },
+            "capabilities": capabilities,
+            "field_permissions": {
+                "que_auth_setting": node_info.get("queAuthSetting") or [],
+            },
+            "visibility": visibility,
+            "associated_reports": associated_reports,
+            "candidates": {
+                "rollback_nodes": rollback_items,
+                "transfer_members": transfer_items,
+            },
+            "workflow_log_summary": {
+                "visible": visibility["audit_record_visible"],
+                "available": visibility["audit_record_visible"],
+                "history_count": None,
+                "qrobot_log_visible": visibility["qrobot_record_visible"],
+            },
+        }
+
+    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")
+        apply_user = raw.get("applyUser")
+        if apply_user is None:
+            user_uid = raw.get("applyUserUid")
+            user_name = raw.get("applyUserName")
+            if user_uid is not None or user_name is not None:
+                apply_user = {"uid": user_uid, "name": user_name}
+        return {
+            "task_id": raw.get("id") or raw.get("taskId") or record_id,
+            "app_key": app_key,
+            "app_name": raw.get("formTitle") or raw.get("worksheetName") or raw.get("appName"),
+            "record_id": record_id,
+            "workflow_node_id": workflow_node_id,
+            "workflow_node_name": raw.get("nodeName") or raw.get("auditNodeName"),
+            "title": raw.get("title") or raw.get("applyTitle") or raw.get("name") or raw.get("formTitle"),
+            "apply_user": apply_user,
+            "apply_time": raw.get("applyTime") or raw.get("receiveTime"),
+            "task_box": task_box,
+            "flow_status": flow_status,
+            "actionable": task_box == "todo" and bool(record_id) and bool(workflow_node_id),
+        }
+
+    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(
+                    f"record_id={record_id} is not currently actionable for the logged-in user in app_key='{app_key}'"
+                )
+            )
+        for item in infos:
+            if not isinstance(item, dict):
+                continue
+            candidate = item.get("auditNodeId")
+            if not isinstance(candidate, int):
+                candidate = item.get("nodeId")
+            if candidate == workflow_node_id:
+                return item
+        raise_tool_error(
+            QingflowApiError.config_error(
+                f"workflow_node_id={workflow_node_id} is not an actionable todo node for app_key='{app_key}' record_id={record_id}"
+            )
+        )
+
+    def _build_capabilities(self, node_info: dict[str, Any]) -> dict[str, Any]:
+        available_actions = ["approve"]
+        if self._coerce_bool(node_info.get("rejectBtnStatus")):
+            available_actions.append("reject")
+        if self._coerce_bool(node_info.get("canRevert")):
+            available_actions.append("rollback")
+        if self._coerce_bool(node_info.get("canTransfer")):
+            available_actions.append("transfer")
+        if self._coerce_bool(node_info.get("canUrge")):
+            available_actions.append("urge")
+
+        visible_but_unimplemented_actions: list[str] = []
+        if self._coerce_bool(node_info.get("canRevoke")):
+            visible_but_unimplemented_actions.append("revoke")
+        if self._coerce_bool(node_info.get("beingEndWorkflow")):
+            visible_but_unimplemented_actions.append("end_workflow")
+        if self._coerce_bool(node_info.get("beingCanApplyAgain")):
+            visible_but_unimplemented_actions.append("apply_again")
+
+        feedback_required_for = []
+        raw_feedback_required = node_info.get("feedbackRequiredOperationType")
+        if isinstance(raw_feedback_required, list):
+            feedback_required_for = [str(item).strip().lower() for item in raw_feedback_required if str(item).strip()]
+
+        return {
+            "available_actions": available_actions,
+            "visible_but_unimplemented_actions": visible_but_unimplemented_actions,
+            "action_constraints": {
+                "feedback_required_for": feedback_required_for,
+                "submit_check_enabled": self._coerce_bool(node_info.get("beingSubmitCheck")),
+                "submit_preview_enabled": self._coerce_bool(node_info.get("beingSubmitPreview")),
+                "can_end_workflow": self._coerce_bool(node_info.get("beingEndWorkflow")),
+                "can_apply_again": self._coerce_bool(node_info.get("beingCanApplyAgain")),
+            },
+        }
+
+    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")),
+            "workflow_future_visible": self._coerce_bool(node_info.get("beingWorkflowNodeFutureListVisible")),
+            "qrobot_record_visible": self._coerce_bool(node_info.get("qrobotRecordBeingVisible")),
+            "associated_report_visible": self._resolve_associated_report_visible(node_info, detail),
+        }
+
+    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 {
+            "report_id": raw.get("id"),
+            "chart_key": raw.get("chartKey"),
+            "chart_name": raw.get("chartName"),
+            "graph_type": "view" if graph_type.endswith("view") or graph_type == "view" else "chart",
+            "source_type": source_type or "qingflow",
+            "target_app_key": raw.get("appKey"),
+            "target_app_name": raw.get("formTitle"),
+            "match_rules": raw.get("matchRules") or [],
+            "raw": dict(raw),
+        }
+
+    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):
+                return [item for item in revert_nodes if isinstance(item, dict)]
+        return [item for item in _approval_page_items(payload) if isinstance(item, dict)]
+
+    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:
+                return item
+        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:
+            if not isinstance(answer, dict):
+                continue
+            answer_que_id = answer.get("queId")
+            if isinstance(answer_que_id, int) and answer_que_id in key_que_ids:
+                extracted_values = self._extract_answer_values(answer)
+                key_values.append({"keyQueId": answer_que_id, "values": extracted_values or None})
+            table_values = answer.get("tableValues")
+            if not isinstance(table_values, list):
+                continue
+            for idx, row in enumerate(table_values, start=1):
+                if not isinstance(row, list):
+                    continue
+                for sub_answer in row:
+                    if not isinstance(sub_answer, dict):
+                        continue
+                    sub_que_id = sub_answer.get("queId")
+                    if isinstance(sub_que_id, int) and sub_que_id in key_que_ids:
+                        extracted_values = self._extract_answer_values(sub_answer)
+                        key_values.append(
+                            {
+                                "keyQueId": sub_que_id,
+                                "ordinal": idx,
+                                "values": extracted_values or None,
+                            }
+                        )
+        return {
+            "asosChart": self._sanitize_associated_chart(asos_chart),
+            "keyQueValues": key_values,
+        }
+
+    def _collect_match_rule_question_ids(self, match_rules: Any) -> set[int]:
+        question_ids: set[int] = set()
+
+        def visit(node: Any) -> None:
+            if isinstance(node, list):
+                for item in node:
+                    visit(item)
+                return
+            if not isinstance(node, dict):
+                return
+            for key in ("queId", "judgeQueId"):
+                value = node.get(key)
+                if isinstance(value, int):
+                    question_ids.add(value)
+            for value in node.values():
+                if isinstance(value, (list, dict)):
+                    visit(value)
+
+        visit(match_rules)
+        return question_ids
+
+    def _extract_answer_values(self, answer: dict[str, Any]) -> list[str]:
+        values = answer.get("values")
+        if not isinstance(values, list):
+            return []
+        normalized: list[str] = []
+        for item in values:
+            if item is None:
+                continue
+            if isinstance(item, (str, int, float, bool)):
+                normalized.append(str(item))
+                continue
+            if not isinstance(item, dict):
+                continue
+            for key in ("value", "id", "uid", "userId", "applyId", "phone", "email", "name", "title", "label"):
+                value = item.get(key)
+                if value not in (None, ""):
+                    normalized.append(str(value))
+                    break
+        deduped: list[str] = []
+        seen: set[str] = set()
+        for item in normalized:
+            if item in seen:
+                continue
+            deduped.append(item)
+            seen.add(item)
+        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"),
+            "formTitle": asos_chart.get("formTitle"),
+            "chartKey": asos_chart.get("chartKey"),
+            "chartName": asos_chart.get("chartName"),
+            "chartType": asos_chart.get("chartType"),
+            "matchRules": asos_chart.get("matchRules") or [],
+            "sourceType": asos_chart.get("sourceType"),
+            "graphType": asos_chart.get("graphType"),
+            "viewType": asos_chart.get("viewType"),
+        }
+
+    def _qingflow_chart_uses_apply_filter(self, context: BackendRequestContext, chart_key: str) -> bool:
+        if not chart_key:
+            return False
+        try:
+            auth = self.backend.request(
+                "GET",
+                context,
+                f"/chart/{chart_key}/auth",
+            )
+        except QingflowApiError:
+            return False
+        if not isinstance(auth, dict):
+            return False
+        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):
+                rows = payload.get("list") if isinstance(payload.get("list"), list) else []
+            series = payload.get("series")
+            if not isinstance(series, list):
+                series = payload.get("xAxis") if isinstance(payload.get("xAxis"), list) else []
+            metrics = payload.get("metrics")
+            if not isinstance(metrics, list):
+                metrics = payload.get("yAxis") if isinstance(payload.get("yAxis"), list) else []
+            summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
+            return {
+                "summary": summary,
+                "rows": rows or [],
+                "series": series or [],
+                "metrics": metrics or [],
+            }
+        if isinstance(payload, list):
+            return {"summary": {}, "rows": payload, "series": [], "metrics": []}
+        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):
+                nested = payload.get("data")
+                if isinstance(nested, dict):
+                    page = nested.get("list") if isinstance(nested.get("list"), list) else nested.get("rows")
+            if not isinstance(page, list):
+                page = []
+        elif isinstance(payload, list):
+            page = payload
+        else:
+            page = []
+
+        items: list[dict[str, Any]] = []
+        for node_record in page:
+            if not isinstance(node_record, dict):
+                continue
+            node_id = node_record.get("nodeId")
+            node_name = node_record.get("nodeName")
+            operation_record_list = node_record.get("operationRecordList")
+            if not isinstance(operation_record_list, list):
+                operation_record_list = []
+            for operation in operation_record_list:
+                if not isinstance(operation, dict):
+                    continue
+                detail = self._first_nested_operation_detail(operation)
+                items.append(
+                    {
+                        "log_id": operation.get("workflowNodeOperationRecordId")
+                        or node_record.get("workflowNodeProcessRecordId"),
+                        "node_id": node_id,
+                        "node_name": node_name,
+                        "operator": operation.get("operator"),
+                        "operation": operation.get("operationType"),
+                        "operation_result": detail,
+                        "operation_time": operation.get("operationTime"),
+                        "remark": self._extract_remark(detail),
+                        "signature_url": self._extract_signature_url(detail),
+                        "attachments": self._extract_attachments(detail),
+                        "qrobot_related": any(
+                            operation.get(key)
+                            for key in ("qRobotAdd", "qRobotUpdate", "qRobotSMS", "qRobotMail", "webhook")
+                        ),
+                    }
+                )
+        return 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:
+                return value
+        return None
+
+    def _extract_remark(self, detail: Any) -> Any:
+        if not isinstance(detail, dict):
+            return None
+        for key in ("remark", "feedback", "comment", "content"):
+            value = detail.get(key)
+            if value not in (None, ""):
+                return value
+        return None
+
+    def _extract_signature_url(self, detail: Any) -> Any:
+        if not isinstance(detail, dict):
+            return None
+        for key in ("signatureUrl", "handSignImageUrl"):
+            value = detail.get(key)
+            if value not in (None, ""):
+                return value
+        return None
+
+    def _extract_attachments(self, detail: Any) -> Any:
+        if not isinstance(detail, dict):
+            return []
+        for key in ("attachments", "files", "uploadFiles"):
+            value = detail.get(key)
+            if isinstance(value, list):
+                return value
+        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():
+                return value.strip()
+        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:
+            if candidate in payload:
+                value = payload.get(candidate)
+                break
+        if not isinstance(value, int) or value <= 0:
+            names = ", ".join(candidates)
+            raise_tool_error(QingflowApiError.config_error(f"one of [{names}] must be a positive integer"))
+        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:
+            raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
+        if workflow_node_id <= 0:
+            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):
+            return value != 0
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "y", "show", "visible", "enabled"}
+        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)
+            if isinstance(payload, dict):
+                return payload
+        return {
+            "base_url": context.base_url,
+            "qf_version": context.qf_version,
+            "qf_version_source": context.qf_version_source or ("context" if context.qf_version else "unknown"),
+        }