@josephyan/qingflow-app-user-mcp 0.2.0-beta.994 → 0.2.0-beta.995

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.994",
+  "version": "0.2.0-beta.995",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b994"
+_FALLBACK_VERSION = "0.2.0b995"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/cli/commands/task.py

@@ -23,27 +23,40 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     list_parser.add_argument("--page-size", type=int, default=20)
     list_parser.set_defaults(handler=_handle_list, format_hint="task_list")
 
-    get = task_subparsers.add_parser("get", help="读取待办详情")
-    get.add_argument("--app-key", required=True)
-    get.add_argument("--record-id", required=True)
-    get.add_argument("--workflow-node-id", required=True, type=int)
+    get = task_subparsers.add_parser("get", help="读取待办详情；推荐直接传 --task-id")
+    get.add_argument("--task-id")
+    get.add_argument("--app-key")
+    get.add_argument("--record-id")
+    get.add_argument("--workflow-node-id", type=int)
     get.add_argument("--include-candidates", action=argparse.BooleanOptionalAction, default=True)
     get.add_argument("--include-associated-reports", action=argparse.BooleanOptionalAction, default=True)
     get.set_defaults(handler=_handle_get, format_hint="task_get")
 
     action = task_subparsers.add_parser("action", help="执行待办动作")
-    action.add_argument("--app-key", required=True)
-    action.add_argument("--record-id", required=True)
-    action.add_argument("--workflow-node-id", required=True, type=int)
+    action.add_argument("--task-id")
+    action.add_argument("--app-key")
+    action.add_argument("--record-id")
+    action.add_argument("--workflow-node-id", type=int)
     action.add_argument("--action", required=True)
     action.add_argument("--payload-file")
     action.add_argument("--fields-file")
     action.set_defaults(handler=_handle_action, format_hint="")
 
-    log = task_subparsers.add_parser("log", help="读取流程日志")
-    log.add_argument("--app-key", required=True)
-    log.add_argument("--record-id", required=True)
-    log.add_argument("--workflow-node-id", required=True, type=int)
+    report = task_subparsers.add_parser("report", help="读取待办关联报表详情；推荐直接传 --task-id")
+    report.add_argument("--task-id")
+    report.add_argument("--app-key")
+    report.add_argument("--record-id")
+    report.add_argument("--workflow-node-id", type=int)
+    report.add_argument("--report-id", required=True, type=int)
+    report.add_argument("--page", type=int, default=1)
+    report.add_argument("--page-size", type=int, default=20)
+    report.set_defaults(handler=_handle_report, format_hint="task_associated_report_detail_get")
+
+    log = task_subparsers.add_parser("log", help="读取流程日志；推荐直接传 --task-id")
+    log.add_argument("--task-id")
+    log.add_argument("--app-key")
+    log.add_argument("--record-id")
+    log.add_argument("--workflow-node-id", type=int)
     log.set_defaults(handler=_handle_log, format_hint="")
 
 
@@ -61,22 +74,32 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task get requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_get(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
         include_candidates=bool(args.include_candidates),
         include_associated_reports=bool(args.include_associated_reports),
     )
 
 
 def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task action requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_action_execute(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
         action=args.action,
         payload=load_object_arg(args.payload_file, option_name="--payload-file") or {},
         fields=load_object_arg(args.fields_file, option_name="--fields-file") or {},
@@ -84,9 +107,31 @@ def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task log requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_workflow_log_get(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+    )
+
+
+def _handle_report(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task report requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_associated_report_detail_get(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+        report_id=int(args.report_id),
+        page=int(args.page),
+        page_size=int(args.page_size),
     )

package/src/qingflow_mcp/cli/formatters.py

@@ -177,17 +177,15 @@ def _format_task_list(result: dict[str, Any]) -> str:
     for item in items:
         if not isinstance(item, dict):
             continue
-        lines.append(
-            "- "
-            + " / ".join(
-                [
-                    str(item.get("app_key") or "-"),
-                    str(item.get("record_id") or "-"),
-                    str(item.get("workflow_node_id") or "-"),
-                    str(item.get("workflow_node_name") or "-"),
-                ]
-            )
-        )
+        header_parts = [
+            str(item.get("task_id") or "-"),
+            str(item.get("app_name") or item.get("app_key") or "-"),
+            str(item.get("workflow_node_name") or "-"),
+        ]
+        apply_time = item.get("apply_time")
+        if apply_time not in (None, ""):
+            header_parts.append(str(apply_time))
+        lines.append("- " + " / ".join(header_parts))
         summary_fields = item.get("summary_fields") if isinstance(item.get("summary_fields"), list) else []
         for summary in summary_fields:
             if not isinstance(summary, dict):
@@ -206,15 +204,20 @@ def _format_task_get(result: dict[str, Any]) -> str:
     extras = data.get("extras") if isinstance(data.get("extras"), dict) else {}
     initiator = task.get("initiator") if isinstance(task.get("initiator"), dict) else {}
     initiator_label = initiator.get("displayName") or initiator.get("email") or "-"
-    lines = [
-        f"Task: {task.get('app_key') or '-'} / {task.get('record_id') or '-'} / {task.get('workflow_node_id') or '-'}",
-        f"Node: {task.get('workflow_node_name') or '-'}",
-        f"App: {task.get('app_name') or '-'}",
-        f"Initiator: {initiator_label}",
-        f"Apply Status: {record_summary.get('apply_status')}",
-        f"Available Actions: {', '.join(str(item) for item in available_actions) or '-'}",
-        f"Editable Fields: {len(editable_fields)}",
-    ]
+    lines = []
+    if task.get("task_id") not in (None, ""):
+        lines.append(f"Task ID: {task.get('task_id')}")
+    lines.extend(
+        [
+            f"Locator: {task.get('app_key') or '-'} / {task.get('record_id') or '-'} / {task.get('workflow_node_id') or '-'}",
+            f"Node: {task.get('workflow_node_name') or '-'}",
+            f"App: {task.get('app_name') or '-'}",
+            f"Initiator: {initiator_label}",
+            f"Apply Status: {record_summary.get('apply_status')}",
+            f"Available Actions: {', '.join(str(item) for item in available_actions) or '-'}",
+            f"Editable Fields: {len(editable_fields)}",
+        ]
+    )
     core_fields = record_summary.get("core_fields") if isinstance(record_summary.get("core_fields"), dict) else {}
     if core_fields:
         lines.append("Core Fields:")
@@ -246,6 +249,48 @@ def _format_task_get(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_task_associated_report_detail(result: dict[str, Any]) -> str:
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    selection = data.get("selection") if isinstance(data.get("selection"), dict) else {}
+    result_type = str(data.get("result_type") or "-")
+    context = data.get("context") if isinstance(data.get("context"), dict) else {}
+    lines = []
+    if selection.get("task_id") not in (None, ""):
+        lines.append(f"Task ID: {selection.get('task_id')}")
+    lines.extend(
+        [
+            f"Report: {selection.get('chart_name') or '-'} ({selection.get('report_id') or '-'})",
+            f"Type: {result_type}",
+        ]
+    )
+    if result_type == "view_list":
+        result_payload = data.get("result") if isinstance(data.get("result"), dict) else {}
+        items = result_payload.get("items") if isinstance(result_payload.get("items"), list) else []
+        lines.append(f"Returned Records: {len(items)}")
+        for item in items[:10]:
+            if isinstance(item, dict):
+                lines.append(json.dumps(item, ensure_ascii=False))
+        if len(items) > 10:
+            lines.append(f"... {len(items) - 10} more")
+    elif result_type == "chart_data":
+        result_payload = data.get("result") if isinstance(data.get("result"), dict) else {}
+        summary = result_payload.get("summary") if isinstance(result_payload.get("summary"), dict) else {}
+        rows = result_payload.get("rows") if isinstance(result_payload.get("rows"), list) else []
+        if summary:
+            lines.append(f"Summary: {json.dumps(summary, ensure_ascii=False)}")
+        lines.append(f"Rows: {len(rows)}")
+        for row in rows[:10]:
+            if isinstance(row, dict):
+                lines.append(json.dumps(row, ensure_ascii=False))
+        if len(rows) > 10:
+            lines.append(f"... {len(rows) - 10} more")
+    resolved_filters = context.get("resolved_filters") if isinstance(context.get("resolved_filters"), list) else []
+    if resolved_filters:
+        lines.append(f"Resolved Filters: {len(resolved_filters)}")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_import_verify(result: dict[str, Any]) -> str:
     lines = [
         f"App Key: {result.get('app_key') or '-'}",
@@ -381,6 +426,7 @@ _FORMATTERS = {
     "record_list": _format_record_list,
     "task_list": _format_task_list,
     "task_get": _format_task_get,
+    "task_associated_report_detail_get": _format_task_associated_report_detail,
     "import_verify": _format_import_verify,
     "import_status": _format_import_status,
     "builder_summary": _format_builder_summary,

package/src/qingflow_mcp/public_surface.py

@@ -94,7 +94,13 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False, cli_show_effective_context=True),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "task_associated_report_detail_get",
+        ("task_associated_report_detail_get",),
+        ("task", "report"),
+        cli_show_effective_context=True,
+    ),
     PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "directory_search", ("directory_search",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), cli_public=False),

package/src/qingflow_mcp/server.py

@@ -151,6 +151,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 `task_list -> task_get -> task_action_execute`
 
+- `task_list` returns task-card summaries keyed by `task_id`.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
+- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - 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`.

package/src/qingflow_mcp/server_app_user.py

@@ -146,6 +146,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 `task_list -> task_get -> task_action_execute`
 
+- `task_list` returns task-card summaries keyed by `task_id`.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
+- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - 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`.

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -10,7 +10,7 @@ from mcp.server.fastmcp import FastMCP
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
-from ..id_utils import ids_equal, normalize_positive_id_int, stringify_backend_id
+from ..id_utils import ids_equal, normalize_positive_id_int, normalize_positive_id_text, stringify_backend_id
 from ..json_types import JSONObject
 from .approval_tools import ApprovalTools, _approval_page_amount, _approval_page_items, _approval_page_total
 from .base import ToolBase, tool_cn_name
@@ -87,6 +87,7 @@ class TaskContextTools(ToolBase):
         @mcp.tool()
         def task_get(
             profile: str = DEFAULT_PROFILE,
+            task_id: str = "",
             app_key: str = "",
             record_id: str = "",
             workflow_node_id: int = 0,
@@ -95,6 +96,7 @@ class TaskContextTools(ToolBase):
         ) -> dict[str, Any]:
             return self.task_get(
                 profile=profile,
+                task_id=task_id,
                 app_key=app_key,
                 record_id=record_id,
                 workflow_node_id=workflow_node_id,
@@ -105,6 +107,7 @@ class TaskContextTools(ToolBase):
         @mcp.tool(description=self._high_risk_tool_description(operation="execute", target="workflow task action"))
         def task_action_execute(
             profile: str = DEFAULT_PROFILE,
+            task_id: str = "",
             app_key: str = "",
             record_id: str = "",
             workflow_node_id: int = 0,
@@ -114,6 +117,7 @@ class TaskContextTools(ToolBase):
         ) -> dict[str, Any]:
             return self.task_action_execute(
                 profile=profile,
+                task_id=task_id,
                 app_key=app_key,
                 record_id=record_id,
                 workflow_node_id=workflow_node_id,
@@ -125,6 +129,7 @@ class TaskContextTools(ToolBase):
         @mcp.tool()
         def task_associated_report_detail_get(
             profile: str = DEFAULT_PROFILE,
+            task_id: str = "",
             app_key: str = "",
             record_id: str = "",
             workflow_node_id: int = 0,
@@ -134,6 +139,7 @@ class TaskContextTools(ToolBase):
         ) -> dict[str, Any]:
             return self.task_associated_report_detail_get(
                 profile=profile,
+                task_id=task_id,
                 app_key=app_key,
                 record_id=record_id,
                 workflow_node_id=workflow_node_id,
@@ -145,12 +151,14 @@ class TaskContextTools(ToolBase):
         @mcp.tool()
         def task_workflow_log_get(
             profile: str = DEFAULT_PROFILE,
+            task_id: str = "",
             app_key: str = "",
             record_id: str = "",
             workflow_node_id: int = 0,
         ) -> dict[str, Any]:
             return self.task_workflow_log_get(
                 profile=profile,
+                task_id=task_id,
                 app_key=app_key,
                 record_id=record_id,
                 workflow_node_id=workflow_node_id,
@@ -170,25 +178,20 @@ class TaskContextTools(ToolBase):
         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(
+        response = self._list_normalized_task_items(
             profile=profile,
-            type=normalized_type,
-            process_status=normalized_status,
+            task_box=task_box,
+            flow_status=flow_status,
             app_key=app_key,
-            node_id=workflow_node_id,
-            search_key=query,
-            page_num=page,
+            workflow_node_id=workflow_node_id,
+            query=query,
+            page=page,
             page_size=page_size,
-            create_time_asc=None,
         )
-        task_page = raw.get("page", {})
         warnings: list[dict[str, Any]] = []
-        items = [self._normalize_task_item(item) 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)
+        items = response["items"] if isinstance(response.get("items"), list) else []
+        page_amount = response.get("page_amount")
+        reported_total = response.get("reported_total")
         if query and not items:
             fallback = self._task_list_local_query_fallback(
                 profile=profile,
@@ -214,19 +217,20 @@ class TaskContextTools(ToolBase):
                         ),
                     }
                 )
+        public_items = [self._public_task_item(item) for item in items]
         return {
             "profile": profile,
-            "ws_id": raw.get("ws_id"),
+            "ws_id": response.get("raw", {}).get("ws_id") if isinstance(response.get("raw"), dict) else None,
             "ok": True,
-            "request_route": raw.get("request_route"),
+            "request_route": response.get("raw", {}).get("request_route") if isinstance(response.get("raw"), dict) else None,
             "warnings": warnings,
             "output_profile": "normal",
             "data": {
-                "items": items,
+                "items": public_items,
                 "pagination": {
                     "page": page,
                     "page_size": page_size,
-                    "returned_items": returned_items,
+                    "returned_items": len(public_items),
                     "page_amount": page_amount,
                     "reported_total": reported_total,
                 },
@@ -243,28 +247,44 @@ class TaskContextTools(ToolBase):
         self,
         *,
         profile: str,
-        app_key: str,
-        record_id: Any,
-        workflow_node_id: int,
-        include_candidates: bool,
-        include_associated_reports: bool,
+        task_id: Any = None,
+        app_key: str = "",
+        record_id: Any = "",
+        workflow_node_id: int = 0,
+        include_candidates: bool = True,
+        include_associated_reports: bool = True,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
-        self._require_app_record_and_node(app_key, record_id_int, workflow_node_id)
+        if task_id in (None, ""):
+            normalize_positive_id_int(record_id, field_name="record_id")
 
         def runner(session_profile, context):
-            data = self._build_task_context(
+            locator = self._resolve_task_locator_input(
                 profile=profile,
-                context=context,
+                task_id=task_id,
                 app_key=app_key,
-                record_id=record_id_int,
+                record_id=record_id,
                 workflow_node_id=workflow_node_id,
+            )
+            task_id_text = locator["task_id"]
+            resolved_app_key = str(locator["app_key"])
+            resolved_record_id = int(locator["record_id"])
+            resolved_workflow_node_id = int(locator["workflow_node_id"])
+            self._require_app_record_and_node(resolved_app_key, resolved_record_id, resolved_workflow_node_id)
+            data = self._build_task_context(
+                profile=profile,
+                context=context,
+                app_key=resolved_app_key,
+                record_id=resolved_record_id,
+                workflow_node_id=resolved_workflow_node_id,
                 include_candidates=include_candidates,
                 include_associated_reports=include_associated_reports,
                 current_uid=session_profile.uid,
             )
             data = self._compact_task_get_context(data)
+            task_payload = data.get("task")
+            if isinstance(task_payload, dict) and task_id_text is not None:
+                task_payload["task_id"] = task_id_text
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -306,17 +326,18 @@ class TaskContextTools(ToolBase):
         self,
         *,
         profile: str,
-        app_key: str,
-        record_id: Any,
-        workflow_node_id: int,
+        task_id: Any = None,
+        app_key: str = "",
+        record_id: Any = "",
+        workflow_node_id: int = 0,
         action: str,
         payload: dict[str, Any],
         fields: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
-        record_id_text = stringify_backend_id(record_id_int)
-        self._require_app_record_and_node(app_key, record_id_int, workflow_node_id)
+        if task_id in (None, ""):
+            normalize_positive_id_int(record_id, field_name="record_id")
+
         normalized_action = (action or "").strip().lower()
         if normalized_action not in {"approve", "reject", "rollback", "transfer", "urge", "save_only"}:
             raise_tool_error(
@@ -334,13 +355,27 @@ class TaskContextTools(ToolBase):
             )
 
         def runner(session_profile, context):
+            locator = self._resolve_task_locator_input(
+                profile=profile,
+                task_id=task_id,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+            )
+            task_id_text = locator["task_id"]
+            resolved_app_key = str(locator["app_key"])
+            resolved_record_id = int(locator["record_id"])
+            resolved_record_id_text = str(locator["record_id_text"] or "")
+            resolved_workflow_node_id = int(locator["workflow_node_id"])
+            record_id_text = resolved_record_id_text
+            self._require_app_record_and_node(resolved_app_key, resolved_record_id, resolved_workflow_node_id)
             try:
                 task_context = self._build_task_context(
                     profile=profile,
                     context=context,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                     include_candidates=False,
                     include_associated_reports=False,
                     current_uid=session_profile.uid,
@@ -351,12 +386,13 @@ class TaskContextTools(ToolBase):
                         profile=profile,
                         session_profile=session_profile,
                         context=context,
-                        app_key=app_key,
-                        record_id=record_id_int,
-                        workflow_node_id=workflow_node_id,
+                        app_key=resolved_app_key,
+                        record_id=resolved_record_id,
+                        workflow_node_id=resolved_workflow_node_id,
                         action=normalized_action,
                         source_error=error,
                         before_apply_status=None,
+                        task_id=task_id_text,
                     )
                 raise
             if normalized_action == "save_only" and not field_updates:
@@ -385,7 +421,7 @@ class TaskContextTools(ToolBase):
                     raise_tool_error(QingflowApiError.config_error(message))
                 raise_tool_error(
                     QingflowApiError.config_error(
-                        f"task action '{normalized_action}' is not currently available for app_key='{app_key}' record_id={record_id_text} workflow_node_id={workflow_node_id}"
+                        f"task action '{normalized_action}' is not currently available for app_key='{resolved_app_key}' record_id={record_id_text} workflow_node_id={resolved_workflow_node_id}"
                     )
                 )
             feedback_required_for = capabilities.get("action_constraints", {}).get("feedback_required_for") or []
@@ -406,9 +442,9 @@ class TaskContextTools(ToolBase):
                 prepared_fields = self._prepare_task_field_update(
                     profile=profile,
                     context=context,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                     task_context=task_context,
                     fields=field_updates,
                 )
@@ -418,16 +454,16 @@ class TaskContextTools(ToolBase):
                 runtime_baseline = self._capture_task_runtime_baseline(
                     profile=profile,
                     context=context,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                 )
             try:
                 raw = self._execute_task_action(
                     profile=profile,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                     normalized_action=normalized_action,
                     payload=body,
                     prepared_fields=prepared_fields,
@@ -438,21 +474,22 @@ class TaskContextTools(ToolBase):
                         profile=profile,
                         session_profile=session_profile,
                         context=context,
-                        app_key=app_key,
-                        record_id=record_id_int,
-                        workflow_node_id=workflow_node_id,
+                        app_key=resolved_app_key,
+                        record_id=resolved_record_id,
+                        workflow_node_id=resolved_workflow_node_id,
                         action=normalized_action,
                         source_error=error,
                         before_apply_status=before_apply_status,
+                        task_id=task_id_text,
                     )
                 raise
 
             if normalized_action == "save_only":
                 verification, warnings = self._verify_task_save_only(
                     context=context,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                     before_apply_status=before_apply_status,
                     expected_answers=((prepared_fields or {}).get("normalized_answers") or []),
                     task_context=task_context,
@@ -464,9 +501,9 @@ class TaskContextTools(ToolBase):
                 verification, warnings = self._verify_task_action_runtime(
                     profile=profile,
                     context=context,
-                    app_key=app_key,
-                    record_id=record_id_int,
-                    workflow_node_id=workflow_node_id,
+                    app_key=resolved_app_key,
+                    record_id=resolved_record_id,
+                    workflow_node_id=resolved_workflow_node_id,
                     action=normalized_action,
                     before_apply_status=before_apply_status,
                     runtime_baseline=runtime_baseline,
@@ -474,7 +511,7 @@ class TaskContextTools(ToolBase):
                 runtime_verified = bool(verification.get("runtime_continuation_verified"))
                 status = "success" if runtime_verified else "partial_success"
                 error_code = None if runtime_verified else "WORKFLOW_CONTINUATION_UNVERIFIED"
-            return {
+            result = {
                 "profile": raw.get("profile", profile),
                 "ws_id": raw.get("ws_id", session_profile.selected_ws_id),
                 "ok": bool(raw.get("ok", True)) and status != "failed",
@@ -487,9 +524,9 @@ class TaskContextTools(ToolBase):
                 "data": {
                     "action": normalized_action,
                     "resource": {
-                        "app_key": app_key,
+                        "app_key": resolved_app_key,
                         "record_id": record_id_text,
-                        "workflow_node_id": workflow_node_id,
+                        "workflow_node_id": resolved_workflow_node_id,
                     },
                     "selection": {"action": normalized_action},
                     "result": raw.get("result"),
@@ -497,6 +534,11 @@ class TaskContextTools(ToolBase):
                     "field_update_applied": bool(field_updates),
                 },
             }
+            if task_id_text is not None:
+                resource = result["data"].get("resource")
+                if isinstance(resource, dict):
+                    resource["task_id"] = task_id_text
+            return result
 
         return self._run(profile, runner)
 
@@ -914,6 +956,7 @@ class TaskContextTools(ToolBase):
         action: str,
         source_error: QingflowApiError,
         before_apply_status: Any,
+        task_id: str | None = None,
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
         record_id_text = stringify_backend_id(record_id)
@@ -935,7 +978,7 @@ class TaskContextTools(ToolBase):
                     "message": "the task is no longer actionable in the current context; MCP found downstream workflow evidence and treats it as already processed by another actor.",
                 }
             )
-            return {
+            result = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
@@ -957,13 +1000,18 @@ class TaskContextTools(ToolBase):
                     "human_review": True,
                 },
             }
+            if task_id is not None:
+                resource = result["data"].get("resource")
+                if isinstance(resource, dict):
+                    resource["task_id"] = task_id
+            return result
         warnings.append(
             {
                 "code": "TASK_CONTEXT_VISIBILITY_UNVERIFIED",
                 "message": "the task is no longer actionable, and MCP could not verify from state or workflow logs whether it was already processed.",
             }
         )
-        return {
+        result = {
             "profile": profile,
             "ws_id": session_profile.selected_ws_id,
             "ok": False,
@@ -990,11 +1038,16 @@ class TaskContextTools(ToolBase):
                 },
             },
         }
+        if task_id is not None:
+            resource = result["data"].get("resource")
+            if isinstance(resource, dict):
+                resource["task_id"] = task_id
+        return result
 
     def _safe_task_list_items(self, *, profile: str, task_box: str, app_key: str) -> list[dict[str, Any]]:
         """执行内部辅助逻辑。"""
         try:
-            response = self.task_list(
+            response = self._list_normalized_task_items(
                 profile=profile,
                 task_box=task_box,
                 flow_status="all",
@@ -1006,12 +1059,44 @@ class TaskContextTools(ToolBase):
             )
         except QingflowApiError:
             return []
-        data = response.get("data") if isinstance(response, dict) else None
-        items = data.get("items") if isinstance(data, dict) else None
+        items = response.get("items") if isinstance(response, dict) else None
         if not isinstance(items, list):
             return []
         return [item for item in items if isinstance(item, dict)]
 
+    def _list_normalized_task_items(
+        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", {})
+        return {
+            "raw": raw,
+            "items": [self._normalize_task_item(item) for item in _task_page_items(task_page) if isinstance(item, dict)],
+            "page_amount": _task_page_amount(task_page),
+            "reported_total": _task_page_total(task_page),
+        }
+
     def _task_list_local_query_fallback(
         self,
         *,
@@ -1024,35 +1109,30 @@ class TaskContextTools(ToolBase):
         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(
+            response = self._list_normalized_task_items(
                 profile=profile,
-                type=normalized_type,
-                process_status=normalized_status,
+                task_box=task_box,
+                flow_status=flow_status,
                 app_key=app_key,
-                node_id=workflow_node_id,
-                search_key=None,
-                page_num=scan_page,
+                workflow_node_id=workflow_node_id,
+                query=None,
+                page=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) for item in raw_items if isinstance(item, dict)]
+            normalized_items = response.get("items") if isinstance(response.get("items"), list) else []
             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))
+                coerced_page_amount = _coerce_count(response.get("page_amount"))
                 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:
+            if not normalized_items or len(normalized_items) < scan_page_size:
                 break
             scan_page += 1
         if not matched_items:
@@ -1067,6 +1147,106 @@ class TaskContextTools(ToolBase):
             "reported_total": matched_total,
         }
 
+    def _resolve_todo_task_locator(self, *, profile: str, task_id: Any) -> dict[str, Any]:
+        task_id_text = normalize_positive_id_text(task_id, field_name="task_id")
+        page = 1
+        page_size = 100
+        page_amount: int | None = None
+        while True:
+            response = self._list_normalized_task_items(
+                profile=profile,
+                task_box="todo",
+                flow_status="all",
+                app_key=None,
+                workflow_node_id=None,
+                query=None,
+                page=page,
+                page_size=page_size,
+            )
+            items = response.get("items") if isinstance(response.get("items"), list) else []
+            for item in items:
+                if not isinstance(item, dict) or not ids_equal(item.get("task_id"), task_id_text):
+                    continue
+                app_key = str(item.get("app_key") or "").strip()
+                record_id = stringify_backend_id(item.get("record_id"))
+                workflow_node_id = int(item.get("workflow_node_id") or 0)
+                if not app_key or record_id is None or workflow_node_id <= 0:
+                    raise_tool_error(
+                        QingflowApiError.config_error(
+                            f"task_id={task_id_text} resolved to an incomplete task locator; please refresh the todo list and retry"
+                        )
+                    )
+                return {
+                    "task_id": task_id_text,
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "workflow_node_id": workflow_node_id,
+                }
+            if page_amount is None:
+                coerced_page_amount = _coerce_count(response.get("page_amount"))
+                if coerced_page_amount is not None and coerced_page_amount > 0:
+                    page_amount = coerced_page_amount
+            if page_amount is not None and page >= page_amount:
+                break
+            if not items or len(items) < page_size:
+                break
+            page += 1
+        raise_tool_error(
+            QingflowApiError.config_error(
+                f"task_id={task_id_text} was not found in the current todo list; task context tools currently resolve actionable todo tasks by task_id"
+            )
+        )
+
+    def _resolve_task_locator_input(
+        self,
+        *,
+        profile: str,
+        task_id: Any = None,
+        app_key: str = "",
+        record_id: Any = "",
+        workflow_node_id: int = 0,
+    ) -> dict[str, Any]:
+        task_id_text = normalize_positive_id_text(task_id, field_name="task_id") if task_id not in (None, "") else None
+        resolved_app_key = (app_key or "").strip()
+        resolved_record_id: int
+        resolved_workflow_node_id: int
+        if task_id_text is not None:
+            locator = self._resolve_todo_task_locator(profile=profile, task_id=task_id_text)
+            resolved_app_key = str(locator["app_key"])
+            resolved_record_id = normalize_positive_id_int(locator["record_id"], field_name="record_id")
+            resolved_workflow_node_id = int(locator["workflow_node_id"])
+            explicit_app_key = (app_key or "").strip()
+            if explicit_app_key and explicit_app_key != resolved_app_key:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"task_id={task_id_text} resolved to app_key='{resolved_app_key}', which does not match app_key='{explicit_app_key}'"
+                    )
+                )
+            if record_id not in (None, ""):
+                explicit_record_id = normalize_positive_id_text(record_id, field_name="record_id")
+                if explicit_record_id != stringify_backend_id(resolved_record_id):
+                    raise_tool_error(
+                        QingflowApiError.config_error(
+                            f"task_id={task_id_text} resolved to record_id={resolved_record_id}, which does not match record_id={explicit_record_id}"
+                        )
+                    )
+            if workflow_node_id not in (None, 0) and int(workflow_node_id) != resolved_workflow_node_id:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"task_id={task_id_text} resolved to workflow_node_id={resolved_workflow_node_id}, which does not match workflow_node_id={workflow_node_id}"
+                    )
+                )
+        else:
+            resolved_record_id = normalize_positive_id_int(record_id, field_name="record_id")
+            resolved_workflow_node_id = int(workflow_node_id)
+        return {
+            "task_id": task_id_text,
+            "app_key": resolved_app_key,
+            "record_id": resolved_record_id,
+            "record_id_text": stringify_backend_id(resolved_record_id),
+            "workflow_node_id": resolved_workflow_node_id,
+        }
+
     def _task_item_matches_query(self, item: dict[str, Any], query: str) -> bool:
         needle = str(query or "").strip().casefold()
         if not needle:
@@ -1088,29 +1268,43 @@ class TaskContextTools(ToolBase):
         self,
         *,
         profile: str,
-        app_key: str,
-        record_id: int,
-        workflow_node_id: int,
+        task_id: Any = None,
+        app_key: str = "",
+        record_id: Any = "",
+        workflow_node_id: int = 0,
         report_id: int,
         page: int,
         page_size: int,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
-        record_id_text = stringify_backend_id(record_id_int)
-        self._require_app_record_and_node(app_key, record_id_int, workflow_node_id)
+        if task_id in (None, ""):
+            normalize_positive_id_int(record_id, field_name="record_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(
+            locator = self._resolve_task_locator_input(
                 profile=profile,
-                context=context,
+                task_id=task_id,
                 app_key=app_key,
-                record_id=record_id_int,
+                record_id=record_id,
                 workflow_node_id=workflow_node_id,
+            )
+            task_id_text = locator["task_id"]
+            resolved_app_key = str(locator["app_key"])
+            resolved_record_id = int(locator["record_id"])
+            record_id_text = str(locator["record_id_text"] or "")
+            resolved_workflow_node_id = int(locator["workflow_node_id"])
+            self._require_app_record_and_node(resolved_app_key, resolved_record_id, resolved_workflow_node_id)
+            task_context = self._build_task_context(
+                profile=profile,
+                context=context,
+                app_key=resolved_app_key,
+                record_id=resolved_record_id,
+                workflow_node_id=resolved_workflow_node_id,
                 include_candidates=False,
                 include_associated_reports=True,
                 current_uid=session_profile.uid,
@@ -1119,7 +1313,7 @@ class TaskContextTools(ToolBase):
             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_text} workflow_node_id={workflow_node_id}"
+                        f"report_id={report_id} is not visible for app_key='{resolved_app_key}' record_id={record_id_text} workflow_node_id={resolved_workflow_node_id}"
                     )
                 )
             association_query = self._build_association_query(
@@ -1127,15 +1321,17 @@ class TaskContextTools(ToolBase):
                 task_context.get("record", {}).get("answers") or [],
             )
             selection = {
-                "app_key": app_key,
+                "app_key": resolved_app_key,
                 "record_id": record_id_text,
-                "workflow_node_id": workflow_node_id,
+                "workflow_node_id": resolved_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"),
             }
+            if task_id_text is not None:
+                selection["task_id"] = task_id_text
             context_payload = {
                 "match_rules": report_item.get("match_rules") or [],
                 "resolved_filters": association_query.get("keyQueValues") or [],
@@ -1282,22 +1478,35 @@ class TaskContextTools(ToolBase):
         self,
         *,
         profile: str,
-        app_key: str,
-        record_id: Any,
-        workflow_node_id: int,
+        task_id: Any = None,
+        app_key: str = "",
+        record_id: Any = "",
+        workflow_node_id: int = 0,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
-        record_id_text = stringify_backend_id(record_id_int)
-        self._require_app_record_and_node(app_key, record_id_int, workflow_node_id)
+        if task_id in (None, ""):
+            normalize_positive_id_int(record_id, field_name="record_id")
 
         def runner(session_profile, context):
-            task_context = self._build_task_context(
+            locator = self._resolve_task_locator_input(
                 profile=profile,
-                context=context,
+                task_id=task_id,
                 app_key=app_key,
-                record_id=record_id_int,
+                record_id=record_id,
                 workflow_node_id=workflow_node_id,
+            )
+            task_id_text = locator["task_id"]
+            resolved_app_key = str(locator["app_key"])
+            resolved_record_id = int(locator["record_id"])
+            record_id_text = str(locator["record_id_text"] or "")
+            resolved_workflow_node_id = int(locator["workflow_node_id"])
+            self._require_app_record_and_node(resolved_app_key, resolved_record_id, resolved_workflow_node_id)
+            task_context = self._build_task_context(
+                profile=profile,
+                context=context,
+                app_key=resolved_app_key,
+                record_id=resolved_record_id,
+                workflow_node_id=resolved_workflow_node_id,
                 include_candidates=False,
                 include_associated_reports=False,
                 current_uid=session_profile.uid,
@@ -1306,7 +1515,7 @@ class TaskContextTools(ToolBase):
             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_text} workflow_node_id={workflow_node_id}"
+                        f"workflow logs are not visible for app_key='{resolved_app_key}' record_id={record_id_text} workflow_node_id={resolved_workflow_node_id}"
                     )
                 )
             page = self.backend.request(
@@ -1314,16 +1523,16 @@ class TaskContextTools(ToolBase):
                 context,
                 "/application/workflow/node/record",
                 json_body={
-                    "key": app_key,
-                    "rowRecordId": record_id_int,
-                    "nodeId": workflow_node_id,
+                    "key": resolved_app_key,
+                    "rowRecordId": resolved_record_id,
+                    "nodeId": resolved_workflow_node_id,
                     "role": 3,
                     "pageNum": 1,
                     "pageSize": 200,
                 },
             )
             items = self._normalize_workflow_logs(page)
-            return {
+            result = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
@@ -1332,9 +1541,9 @@ class TaskContextTools(ToolBase):
                 "output_profile": "normal",
                 "data": {
                     "selection": {
-                        "app_key": app_key,
+                        "app_key": resolved_app_key,
                         "record_id": record_id_text,
-                        "workflow_node_id": workflow_node_id,
+                        "workflow_node_id": resolved_workflow_node_id,
                     },
                     "visibility": {
                         "audit_record_visible": visibility.get("audit_record_visible"),
@@ -1343,6 +1552,11 @@ class TaskContextTools(ToolBase):
                     "items": items,
                 },
             }
+            if task_id_text is not None:
+                selection = result["data"].get("selection")
+                if isinstance(selection, dict):
+                    selection["task_id"] = task_id_text
+            return result
 
         return self._run(profile, runner)
 
@@ -1732,6 +1946,15 @@ class TaskContextTools(ToolBase):
             "summary_fields": self._normalize_task_summary_fields(raw.get("dataSnapshot")),
         }
 
+    def _public_task_item(self, item: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "task_id": item.get("task_id"),
+            "app_name": item.get("app_name"),
+            "workflow_node_name": item.get("workflow_node_name"),
+            "apply_time": item.get("apply_time"),
+            "summary_fields": item.get("summary_fields") if isinstance(item.get("summary_fields"), list) else [],
+        }
+
     def _normalize_task_summary_fields(self, raw: Any) -> list[dict[str, Any]]:
         """执行内部辅助逻辑。"""
         if not isinstance(raw, list):