@josephyan/qingflow-app-user-mcp 0.2.0-beta.987 → 0.2.0-beta.989

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.987",
+  "version": "0.2.0-beta.989",
   "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.0b987"
+version = "0.2.0b989"
 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.0b987"
+_FALLBACK_VERSION = "0.2.0b989"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/service.py

@@ -13454,6 +13454,7 @@ def _canonicalize_reference_questions_for_save(
     source: dict[str, Any],
     field: dict[str, Any],
 ) -> list[dict[str, Any]]:
+    relation_config_explicit = bool(field.get("_relation_config_explicit"))
     normalized_source_questions = [
         item
         for item in (
@@ -13462,6 +13463,8 @@ def _canonicalize_reference_questions_for_save(
         )
         if item is not None
     ]
+    if not relation_config_explicit:
+        return normalized_source_questions
 
     display_field = field.get("display_field") if isinstance(field.get("display_field"), dict) else None
     visible_fields = [item for item in cast(list[Any], field.get("visible_fields") or []) if isinstance(item, dict)]
@@ -13498,14 +13501,19 @@ def _canonicalize_reference_questions_for_save(
         if matched_index is not None:
             used_source_indexes.add(matched_index)
 
-    next_ordinal = len(canonical_questions) + 1
-    for index, item in enumerate(normalized_source_questions):
-        if index in used_source_indexes:
-            continue
-        remaining_item = deepcopy(item)
-        remaining_item["ordinal"] = next_ordinal
-        next_ordinal += 1
-        canonical_questions.append(remaining_item)
+    source_target_app_key = str(source.get("referAppKey") or "").strip()
+    target_app_key = str(field.get("target_app_key") or "").strip()
+    preserve_remaining_source_questions = not source_target_app_key or source_target_app_key == target_app_key
+
+    if preserve_remaining_source_questions:
+        next_ordinal = len(canonical_questions) + 1
+        for index, item in enumerate(normalized_source_questions):
+            if index in used_source_indexes:
+                continue
+            remaining_item = deepcopy(item)
+            remaining_item["ordinal"] = next_ordinal
+            next_ordinal += 1
+            canonical_questions.append(remaining_item)
 
     return canonical_questions
 
@@ -13514,6 +13522,7 @@ def _canonicalize_reference_auth_questions_for_save(
     *,
     source: dict[str, Any],
     refer_questions: list[dict[str, Any]],
+    relation_config_explicit: bool,
 ) -> list[dict[str, Any]]:
     source_auth_questions = [
         item
@@ -13530,6 +13539,40 @@ def _canonicalize_reference_auth_questions_for_save(
             continue
         source_auth_by_que_id[que_id] = item
 
+    if not relation_config_explicit:
+        auth_questions: list[dict[str, Any]] = []
+        seen_que_ids: set[int] = set()
+        refer_question_auth_by_que_id: dict[int, int] = {}
+        for item in refer_questions:
+            que_id = _coerce_any_int(item.get("queId"))
+            que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+            if que_id is None or que_auth is None or que_id in refer_question_auth_by_que_id:
+                continue
+            refer_question_auth_by_que_id[que_id] = que_auth
+
+        for item in source_auth_questions:
+            que_id = _coerce_any_int(item.get("queId"))
+            if que_id is None or que_id in seen_que_ids:
+                continue
+            payload = deepcopy(item)
+            if que_id in refer_question_auth_by_que_id:
+                payload["queAuth"] = refer_question_auth_by_que_id[que_id]
+            auth_questions.append(payload)
+            seen_que_ids.add(que_id)
+
+        for item in refer_questions:
+            que_id = _coerce_any_int(item.get("queId"))
+            que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+            if que_id is None or que_auth is None or que_id in seen_que_ids:
+                continue
+            payload = deepcopy(source_auth_by_que_id.get(que_id) or {"queId": que_id})
+            payload["queId"] = que_id
+            payload["queAuth"] = que_auth
+            auth_questions.append(payload)
+            seen_que_ids.add(que_id)
+
+        return _dedupe_reference_auth_questions(auth_questions)
+
     auth_questions: list[dict[str, Any]] = []
     for item in refer_questions:
         que_id = _coerce_any_int(item.get("queId"))
@@ -13548,6 +13591,7 @@ def _enforce_reference_config_consistency_for_save(
     *,
     field: dict[str, Any],
 ) -> dict[str, Any]:
+    relation_config_explicit = bool(field.get("_relation_config_explicit"))
     refer_questions = [
         item
         for item in (
@@ -13583,28 +13627,29 @@ def _enforce_reference_config_consistency_for_save(
         if display_field_que_id is not None:
             payload["referQueId"] = display_field_que_id
 
-    if display_field_que_id is not None and not any(
-        _coerce_any_int(item.get("queId")) == display_field_que_id for item in refer_questions
-    ):
-        display_selector = field.get("display_field") if isinstance(field.get("display_field"), dict) else None
-        display_question = (
-            _build_reference_question_from_visible_selector(display_selector, ordinal=1)
-            if display_selector is not None
-            else None
-        )
-        if display_question is not None:
-            display_question["queId"] = display_field_que_id
-            display_question["queAuth"] = _REFERENCE_FIELD_VISIBLE_AUTH
-            refer_questions = [display_question, *refer_questions]
+    if relation_config_explicit:
+        if display_field_que_id is not None and not any(
+            _coerce_any_int(item.get("queId")) == display_field_que_id for item in refer_questions
+        ):
+            display_selector = field.get("display_field") if isinstance(field.get("display_field"), dict) else None
+            display_question = (
+                _build_reference_question_from_visible_selector(display_selector, ordinal=1)
+                if display_selector is not None
+                else None
+            )
+            if display_question is not None:
+                display_question["queId"] = display_field_que_id
+                display_question["queAuth"] = _REFERENCE_FIELD_VISIBLE_AUTH
+                refer_questions = [display_question, *refer_questions]
 
-    if display_field_que_id is not None:
-        display_questions = [
-            item for item in refer_questions if _coerce_any_int(item.get("queId")) == display_field_que_id
-        ]
-        trailing_questions = [
-            item for item in refer_questions if _coerce_any_int(item.get("queId")) != display_field_que_id
-        ]
-        refer_questions = [*display_questions, *trailing_questions]
+        if display_field_que_id is not None:
+            display_questions = [
+                item for item in refer_questions if _coerce_any_int(item.get("queId")) == display_field_que_id
+            ]
+            trailing_questions = [
+                item for item in refer_questions if _coerce_any_int(item.get("queId")) != display_field_que_id
+            ]
+            refer_questions = [*display_questions, *trailing_questions]
 
     for ordinal, item in enumerate(refer_questions, start=1):
         que_id = _coerce_any_int(item.get("queId"))
@@ -13622,6 +13667,7 @@ def _enforce_reference_config_consistency_for_save(
     payload["referAuthQues"] = _canonicalize_reference_auth_questions_for_save(
         source={"referAuthQues": refer_auth_ques},
         refer_questions=refer_questions,
+        relation_config_explicit=relation_config_explicit,
     )
     return payload
 
@@ -13661,7 +13707,11 @@ def _normalize_reference_config_for_save(
     if refer_fill_rules or "referFillRules" in source:
         payload["referFillRules"] = refer_fill_rules
 
-    refer_auth_ques = _canonicalize_reference_auth_questions_for_save(source=source, refer_questions=refer_questions)
+    refer_auth_ques = _canonicalize_reference_auth_questions_for_save(
+        source=source,
+        refer_questions=refer_questions,
+        relation_config_explicit=bool(field.get("_relation_config_explicit")),
+    )
     if not refer_auth_ques:
         refer_auth_ques = _synthesize_reference_auth_questions_for_save(source=source, field=field)
     if refer_auth_ques or "referAuthQues" in source:
@@ -13917,6 +13967,13 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
                 if isinstance(built_question.get("referenceConfig"), dict)
                 else {}
             )
+            original_target_app_key = str(existing_reference.get("referAppKey") or "").strip()
+            next_target_app_key = str(field.get("target_app_key") or "").strip()
+            preserve_existing_reference_questions = (
+                relation_config_explicit
+                and bool(original_target_app_key)
+                and original_target_app_key == next_target_app_key
+            )
             if relation_config_explicit:
                 for stale_key in ("customButtonText", "customAdvancedSetting", "configShowForm", "dataShowForm"):
                     reference.pop(stale_key, None)
@@ -13928,7 +13985,7 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
                 "fieldNameShow",
                 "_targetFieldId",
             ):
-                if relation_config_explicit and key in {"referQuestions", "referAuthQues"}:
+                if preserve_existing_reference_questions and key in {"referQuestions", "referAuthQues"}:
                     continue
                 if key in built_reference:
                     reference[key] = deepcopy(built_reference[key])

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

@@ -32,7 +32,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     schema_update = schema_subparsers.add_parser("update", help="读取更新记录表结构")
     schema_update.add_argument("--app-key", required=True)
-    schema_update.add_argument("--record-id", required=True, type=int)
+    schema_update.add_argument("--record-id", required=True)
     schema_update.set_defaults(handler=_handle_schema_update, format_hint="")
 
     schema_import = schema_subparsers.add_parser("import", help="读取导入表结构")
@@ -59,7 +59,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     get = record_subparsers.add_parser("get", help="读取单条记录")
     get.add_argument("--app-key", required=True)
-    get.add_argument("--record-id", required=True, type=int)
+    get.add_argument("--record-id", required=True)
     get.add_argument("--column", dest="columns", action="append", type=int, default=[])
     get.add_argument("--columns-file")
     get.add_argument("--view-id")
@@ -73,7 +73,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     update = record_subparsers.add_parser("update", help="更新记录")
     update.add_argument("--app-key", required=True)
-    update.add_argument("--record-id", type=int)
+    update.add_argument("--record-id")
     update.add_argument("--fields-file")
     update.add_argument("--items-file")
     update.add_argument("--dry-run", action=argparse.BooleanOptionalAction, default=False)
@@ -82,7 +82,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     delete = record_subparsers.add_parser("delete", help="删除记录")
     delete.add_argument("--app-key", required=True)
-    delete.add_argument("--record-id", type=int)
+    delete.add_argument("--record-id")
     delete.add_argument("--record-ids-file")
     delete.set_defaults(handler=_handle_delete, format_hint="")
 
@@ -102,7 +102,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     code_block = record_subparsers.add_parser("code-block-run", help="执行代码块字段")
     code_block.add_argument("--app-key", required=True)
-    code_block.add_argument("--record-id", required=True, type=int)
+    code_block.add_argument("--record-id", required=True)
     code_block.add_argument("--code-block-field", required=True)
     code_block.add_argument("--role", type=int, default=1)
     code_block.add_argument("--workflow-node-id", type=int)

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

@@ -25,7 +25,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     get = task_subparsers.add_parser("get", help="读取待办详情")
     get.add_argument("--app-key", required=True)
-    get.add_argument("--record-id", required=True, type=int)
+    get.add_argument("--record-id", required=True)
     get.add_argument("--workflow-node-id", required=True, type=int)
     get.add_argument("--include-candidates", action=argparse.BooleanOptionalAction, default=True)
     get.add_argument("--include-associated-reports", action=argparse.BooleanOptionalAction, default=True)
@@ -33,7 +33,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     action = task_subparsers.add_parser("action", help="执行待办动作")
     action.add_argument("--app-key", required=True)
-    action.add_argument("--record-id", required=True, type=int)
+    action.add_argument("--record-id", required=True)
     action.add_argument("--workflow-node-id", required=True, type=int)
     action.add_argument("--action", required=True)
     action.add_argument("--payload-file")
@@ -42,7 +42,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     log = task_subparsers.add_parser("log", help="读取流程日志")
     log.add_argument("--app-key", required=True)
-    log.add_argument("--record-id", required=True, type=int)
+    log.add_argument("--record-id", required=True)
     log.add_argument("--workflow-node-id", required=True, type=int)
     log.set_defaults(handler=_handle_log, format_hint="")
 

package/src/qingflow_mcp/id_utils.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import QingflowApiError
+
+
+JS_MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+
+def stringify_backend_id(value: Any) -> str | None:
+    """Return an exact public id string for backend-originated identifiers."""
+    if value in (None, ""):
+        return None
+    if isinstance(value, bool):
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def normalize_positive_id_text(value: Any, *, field_name: str) -> str:
+    """Normalize a user-supplied id while rejecting JS-unsafe numeric input."""
+    if value in (None, "") or isinstance(value, bool):
+        raise QingflowApiError.config_error(f"{field_name} must be positive")
+    if isinstance(value, int):
+        if value <= 0:
+            raise QingflowApiError.config_error(f"{field_name} must be positive")
+        if value > JS_MAX_SAFE_INTEGER:
+            raise QingflowApiError.config_error(
+                f"{field_name} exceeds JavaScript's safe integer range; pass it as a string to avoid precision loss"
+            )
+        return str(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text.isdecimal() or int(text) <= 0:
+            raise QingflowApiError.config_error(f"{field_name} must be a positive integer string")
+        return text
+    raise QingflowApiError.config_error(f"{field_name} must be a positive integer string")
+
+
+def normalize_positive_id_int(value: Any, *, field_name: str) -> int:
+    """Normalize an id to Python int after the public boundary preserves it as text."""
+    return int(normalize_positive_id_text(value, field_name=field_name))
+
+
+def ids_equal(left: Any, right: Any) -> bool:
+    left_text = stringify_backend_id(left)
+    right_text = stringify_backend_id(right)
+    return left_text is not None and right_text is not None and left_text == right_text

package/src/qingflow_mcp/response_trim.py

@@ -263,6 +263,15 @@ def _trim_workspace_list(payload: JSONObject) -> None:
         _trim_item_list(page, "list", allowed=("wsId", "workspaceName", "remark"))
 
 
+def _trim_workspace_get(payload: JSONObject) -> None:
+    workspace = payload.get("workspace")
+    if isinstance(workspace, dict):
+        payload["workspace"] = _pick(
+            workspace,
+            allowed=("wsId", "workspaceName", "remark", "systemVersion", "auth"),
+        )
+
+
 def _trim_app_search_like(payload: JSONObject) -> None:
     payload.pop("apps", None)
     _trim_item_list(payload, "items", allowed=("app_key", "app_name", "package_name"))
@@ -728,6 +737,7 @@ def _register_policy(domains: tuple[str, ...], names: tuple[str, ...], transform
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_use_credential", "auth_whoami"), _trim_auth_payload)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_logout",), _trim_auth_logout)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_list",), _trim_workspace_list)
+_register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_get",), _trim_workspace_get)
 _register_policy((USER_DOMAIN,), ("app_list", "app_search"), _trim_app_search_like)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("app_get",), _trim_app_get)
 _register_policy((BUILDER_DOMAIN,), ("app_repair_code_blocks",), _trim_builder_list_like)

package/src/qingflow_mcp/server_app_builder.py

@@ -93,6 +93,16 @@ def build_builder_server() -> FastMCP:
             include_external=include_external,
         )
 
+    @server.tool()
+    def workspace_get(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict:
+        return workspace.workspace_get(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
     @server.tool()
     def file_upload_local(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/server_app_user.py

@@ -228,6 +228,16 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             include_external=include_external,
         )
 
+    @server.tool()
+    def workspace_get(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict:
+        return workspace.workspace_get(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
     @server.tool()
     def app_list(profile: str = DEFAULT_PROFILE) -> dict:
         return apps.app_list(profile=profile)

package/src/qingflow_mcp/tools/code_block_tools.py

@@ -91,7 +91,7 @@ class CodeBlockTools(RecordTools):
         def record_code_block_run(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             code_block_field: str = "",
             role: int = 1,
             workflow_node_id: int | None = None,
@@ -197,7 +197,7 @@ class CodeBlockTools(RecordTools):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: int | str,
         code_block_field: str,
         role: int = 1,
         workflow_node_id: int | None = None,

package/src/qingflow_mcp/tools/record_tools.py

@@ -13,6 +13,7 @@ from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 from ..errors import QingflowApiError, raise_tool_error
+from ..id_utils import normalize_positive_id_int, stringify_backend_id
 from ..json_types import JSONObject, JSONScalar, JSONValue
 from ..list_type_labels import (
     SYSTEM_VIEW_DEFINITIONS,
@@ -284,7 +285,7 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             field_id: int = 0,
-            record_id: int | None = None,
+            record_id: str | None = None,
             workflow_node_id: int | None = None,
             fields: JSONObject | None = None,
             keyword: str = "",
@@ -315,7 +316,7 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             field_id: int = 0,
-            record_id: int | None = None,
+            record_id: str | None = None,
             workflow_node_id: int | None = None,
             fields: JSONObject | None = None,
             keyword: str = "",
@@ -407,7 +408,7 @@ class RecordTools(ToolBase):
         def record_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             columns: list[JSONObject | int] | None = None,
             view_id: str | None = None,
             workflow_node_id: int | None = None,
@@ -439,7 +440,7 @@ class RecordTools(ToolBase):
         @mcp.tool()
         def record_update_schema_get(
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             output_profile: str = "normal",
         ) -> JSONObject:
             return self.record_update_schema_get_public(
@@ -479,7 +480,7 @@ class RecordTools(ToolBase):
         )
         def record_update(
             app_key: str = "",
-            record_id: int | None = None,
+            record_id: str | None = None,
             fields: JSONObject | None = None,
             items: list[JSONObject] | None = None,
             dry_run: bool = False,
@@ -505,8 +506,8 @@ class RecordTools(ToolBase):
         )
         def record_delete(
             app_key: str = "",
-            record_id: int | None = None,
-            record_ids: list[int] | None = None,
+            record_id: str | None = None,
+            record_ids: list[str] | None = None,
             output_profile: str = "normal",
         ) -> JSONObject:
             return self.record_delete_public(
@@ -784,14 +785,13 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         output_profile: str = "normal",
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         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 is required"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
 
         def runner(session_profile, context):
@@ -815,7 +815,7 @@ class RecordTools(ToolBase):
             probes = self._probe_candidate_record_contexts(
                 context,
                 app_key=app_key,
-                apply_id=record_id,
+                apply_id=record_id_int,
                 candidate_routes=candidate_routes,
             )
             probe_summary: list[JSONObject] = []
@@ -906,7 +906,7 @@ class RecordTools(ToolBase):
                     ws_id=ws_id,
                     request_route=request_route,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     blockers=blockers,
                     warnings=warnings,
                     recommended_next_actions=recommended_next_actions,
@@ -949,7 +949,7 @@ class RecordTools(ToolBase):
                     ws_id=ws_id,
                     request_route=request_route,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     blockers=["NO_WRITABLE_FIELDS_FOR_RECORD"],
                     warnings=[item["message"] for item in warnings if isinstance(item.get("message"), str)],
                     recommended_next_actions=[
@@ -969,7 +969,7 @@ class RecordTools(ToolBase):
                 "request_route": request_route,
                 "warnings": warnings,
                 "app_key": app_key,
-                "record_id": record_id,
+                "record_id": stringify_backend_id(record_id_int),
                 "schema_scope": "update_ready",
                 "writable_fields": writable_fields,
                 "payload_template": {
@@ -1009,7 +1009,7 @@ class RecordTools(ToolBase):
             "request_route": request_route,
             "warnings": [{"code": "PREFLIGHT_WARNING", "message": item} for item in warnings],
             "app_key": app_key,
-            "record_id": record_id,
+            "record_id": stringify_backend_id(record_id),
             "schema_scope": "update_ready",
             "blockers": blockers,
             "writable_fields": [],
@@ -1281,7 +1281,7 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         field_id: int,
-        record_id: int | None = None,
+        record_id: Any | None = None,
         workflow_node_id: int | None = None,
         fields: JSONObject | None = None,
         keyword: str,
@@ -1297,6 +1297,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
         if page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        record_id_int = (
+            normalize_positive_id_int(record_id, field_name="record_id")
+            if record_id is not None
+            else None
+        )
+        record_id_text = stringify_backend_id(record_id_int) if record_id_int is not None else None
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -1316,7 +1322,7 @@ class RecordTools(ToolBase):
                 )
             normalized_fields = fields if isinstance(fields, dict) else {}
             runtime_lookup = self._candidate_lookup_uses_runtime_scope(
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 fields=normalized_fields,
             )
@@ -1327,7 +1333,7 @@ class RecordTools(ToolBase):
                     profile,
                     context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     fields=normalized_fields,
                 )
@@ -1366,7 +1372,7 @@ class RecordTools(ToolBase):
                         "app_key": app_key,
                         "field_id": field.que_id,
                         "field_title": field.que_title,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                         "fields_present": bool(normalized_fields),
                         "keyword": keyword,
@@ -1385,7 +1391,7 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         field_id: int,
-        record_id: int | None = None,
+        record_id: Any | None = None,
         workflow_node_id: int | None = None,
         fields: JSONObject | None = None,
         keyword: str,
@@ -1401,6 +1407,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
         if page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        record_id_int = (
+            normalize_positive_id_int(record_id, field_name="record_id")
+            if record_id is not None
+            else None
+        )
+        record_id_text = stringify_backend_id(record_id_int) if record_id_int is not None else None
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -1420,7 +1432,7 @@ class RecordTools(ToolBase):
                 )
             normalized_fields = fields if isinstance(fields, dict) else {}
             runtime_lookup = self._candidate_lookup_uses_runtime_scope(
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 fields=normalized_fields,
             )
@@ -1431,7 +1443,7 @@ class RecordTools(ToolBase):
                     profile,
                     context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     fields=normalized_fields,
                 )
@@ -1487,7 +1499,7 @@ class RecordTools(ToolBase):
                         "app_key": app_key,
                         "field_id": field.que_id,
                         "field_title": field.que_title,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                         "fields_present": bool(normalized_fields),
                         "keyword": keyword,
@@ -1753,7 +1765,7 @@ class RecordTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         columns: list[JSONObject | int],
         view_id: str | None = None,
         workflow_node_id: int | None = None,
@@ -1761,8 +1773,7 @@ class RecordTools(ToolBase):
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile, allow_normalized=True)
-        if record_id <= 0:
-            raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         normalized_columns = _normalize_public_column_selectors(columns)
 
         def runner(session_profile, context):
@@ -1791,7 +1802,7 @@ class RecordTools(ToolBase):
                 result = self.backend.request(
                     "GET",
                     context,
-                    f"/view/{resolved_view.view_selection.view_key}/apply/{record_id}",
+                    f"/view/{resolved_view.view_selection.view_key}/apply/{record_id_int}",
                 )
                 used_list_type = None
             else:
@@ -1808,7 +1819,7 @@ class RecordTools(ToolBase):
                         result = self.backend.request(
                             "GET",
                             context,
-                            f"/app/{app_key}/apply/{record_id}",
+                            f"/app/{app_key}/apply/{record_id_int}",
                             params={"role": 1, "listType": lt},
                         )
                         used_list_type = lt
@@ -1823,7 +1834,7 @@ class RecordTools(ToolBase):
                         raise last_error
                     raise_tool_error(QingflowApiError.config_error("record_get failed: no accessible listType"))
             answer_list = result.get("answers") if isinstance(result, dict) and isinstance(result.get("answers"), list) else []
-            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id_int)
             normalized_record, normalized_ambiguous_fields = _build_normalized_row_from_answers(
                 cast(list[JSONValue], answer_list),
                 selected_fields,
@@ -1851,7 +1862,7 @@ class RecordTools(ToolBase):
                     if normalized_columns
                     else list(index.by_id.values())
                 )
-                row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+                row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id_int)
                 normalized_record, normalized_ambiguous_fields = _build_normalized_row_from_answers(
                     cast(list[JSONValue], answer_list),
                     selected_fields,
@@ -1874,7 +1885,7 @@ class RecordTools(ToolBase):
                 "output_profile": normalized_output_profile,
                 "data": {
                     "app_key": app_key,
-                    "record_id": _public_record_id_text(record_id),
+                    "record_id": _public_record_id_text(record_id_int),
                     "record": row,
                     "selection": {
                         "columns": [_column_selector_payload(field_id) for field_id in normalized_columns] if normalized_columns else [],
@@ -1975,7 +1986,7 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int | None,
+        record_id: Any | None,
         fields: JSONObject | None = None,
         items: list[JSONObject] | None = None,
         dry_run: bool = False,
@@ -2004,14 +2015,15 @@ class RecordTools(ToolBase):
             )
         if dry_run:
             raise_tool_error(QingflowApiError.config_error("dry_run currently requires items"))
-        if record_id is None or record_id <= 0:
+        if record_id is None:
             raise_tool_error(QingflowApiError.config_error("record_id is required"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         if fields is not None and not isinstance(fields, dict):
             raise_tool_error(QingflowApiError.config_error("fields must be an object map keyed by field title"))
         return self._record_update_public_single(
             profile=profile,
             app_key=app_key,
-            record_id=record_id,
+            record_id=record_id_int,
             fields=cast(JSONObject, fields or {}),
             verify_write=verify_write,
             output_profile=normalized_output_profile,
@@ -2201,7 +2213,7 @@ class RecordTools(ToolBase):
     def _normalize_public_record_update_batch_items(
         self,
         *,
-        record_id: int | None,
+        record_id: Any | None,
         fields: JSONObject | None,
         items: list[JSONObject] | None,
     ) -> list[JSONObject]:
@@ -2217,9 +2229,10 @@ class RecordTools(ToolBase):
         for index, item in enumerate(items):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"items[{index}] must be an object"))
-            normalized_record_id = _coerce_count(item.get("record_id"))
-            if normalized_record_id is None or normalized_record_id <= 0:
-                raise_tool_error(QingflowApiError.config_error(f"items[{index}].record_id must be a positive integer"))
+            normalized_record_id = normalize_positive_id_int(
+                item.get("record_id"),
+                field_name=f"items[{index}].record_id",
+            )
             if normalized_record_id in seen_record_ids:
                 raise_tool_error(
                     QingflowApiError.config_error(f"duplicate record_id in items: {normalized_record_id}")
@@ -3069,22 +3082,26 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int | None = None,
-        record_ids: list[int] | None = None,
+        record_id: Any | None = None,
+        record_ids: list[Any] | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        normalized_record_ids = [item for item in (record_ids or []) if isinstance(item, int) and item > 0]
-        delete_ids = normalized_record_ids or ([record_id] if record_id is not None and record_id > 0 else [])
+        normalized_record_ids: list[int] = []
+        for index, item in enumerate(record_ids or []):
+            normalized_record_ids.append(normalize_positive_id_int(item, field_name=f"record_ids[{index}]"))
+        delete_ids = normalized_record_ids
+        if not delete_ids and record_id is not None:
+            delete_ids = [normalize_positive_id_int(record_id, field_name="record_id")]
         if not delete_ids:
             raise_tool_error(QingflowApiError.config_error("record_id or record_ids is required"))
         normalized_payload = {
             "operation": "delete",
-            "record_id": record_id,
-            "record_ids": delete_ids,
+            "record_id": stringify_backend_id(record_id) if record_id is not None else None,
+            "record_ids": [stringify_backend_id(item) for item in delete_ids],
             "answers": [],
             "submit_type": 1,
         }
@@ -8527,8 +8544,8 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "operation": operation,
-            "record_id": record_id,
-            "record_ids": record_ids,
+            "record_id": stringify_backend_id(record_id) if record_id is not None else None,
+            "record_ids": [stringify_backend_id(item) for item in record_ids],
             "answers": normalized_answers,
             "submit_type": submit_type,
         }
@@ -8727,7 +8744,7 @@ class RecordTools(ToolBase):
             "output_profile": output_profile,
             "data": {
                 "action": {"operation": operation, "executed": True},
-                "resource": raw_apply.get("resource"),
+                "resource": _public_record_resource(raw_apply.get("resource")),
                 "verification": raw_apply.get("verification"),
                 "normalized_payload": normalized_payload,
                 "blockers": [],
@@ -10072,8 +10089,9 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        normalized_apply_id = _coerce_count(apply_id)
-        if normalized_apply_id is None or normalized_apply_id <= 0:
+        try:
+            normalized_apply_id = normalize_positive_id_int(apply_id, field_name="apply_id")
+        except QingflowApiError:
             raise_tool_error(QingflowApiError.config_error("apply_id must be positive"))
         return normalized_apply_id
 
@@ -11084,10 +11102,14 @@ def _build_flat_row(answer_list: list[JSONValue], fields: list[FormField], *, ap
     return row
 
 
-def _public_record_id_text(record_id: int | None) -> str | None:
-    if record_id is None or record_id <= 0:
+def _public_record_id_text(record_id: Any) -> str | None:
+    if record_id is None or isinstance(record_id, bool):
         return None
-    return str(record_id)
+    if isinstance(record_id, int) and record_id <= 0:
+        return None
+    if isinstance(record_id, str) and (not record_id.strip() or not record_id.strip().isdecimal()):
+        return None
+    return stringify_backend_id(record_id)
 
 
 def _normalize_public_record_rows(rows: list[JSONValue]) -> list[JSONObject]:
@@ -11640,10 +11662,29 @@ def _field_mapping_entry(role: str, field: FormField | None, *, requested: str)
     }
 
 
-def _record_resource_payload(record_id: int | None) -> JSONObject | None:
-    if record_id is None or record_id <= 0:
+def _record_resource_payload(record_id: Any) -> JSONObject | None:
+    public_record_id = _public_record_id_text(record_id)
+    if public_record_id is None:
         return None
-    return {"type": "record", "record_id": record_id, "apply_id": record_id}
+    return {"type": "record", "record_id": public_record_id, "apply_id": public_record_id}
+
+
+def _public_record_resource(resource: Any) -> Any:
+    if not isinstance(resource, dict) or resource.get("type") != "record":
+        return resource
+    payload = dict(resource)
+    if "record_id" in payload:
+        payload["record_id"] = _public_record_id_text(payload.get("record_id"))
+    if "apply_id" in payload:
+        payload["apply_id"] = _public_record_id_text(payload.get("apply_id"))
+    record_ids = payload.get("record_ids")
+    if isinstance(record_ids, list):
+        payload["record_ids"] = [
+            stringify_backend_id(item)
+            for item in record_ids
+            if stringify_backend_id(item) is not None
+        ]
+    return payload
 
 
 def _query_id() -> str:

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -10,6 +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 ..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,7 +88,7 @@ class TaskContextTools(ToolBase):
         def task_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             workflow_node_id: int = 0,
             include_candidates: bool = True,
             include_associated_reports: bool = True,
@@ -105,7 +106,7 @@ class TaskContextTools(ToolBase):
         def task_action_execute(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             workflow_node_id: int = 0,
             action: str = "",
             payload: dict[str, Any] | None = None,
@@ -125,7 +126,7 @@ class TaskContextTools(ToolBase):
         def task_associated_report_detail_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             workflow_node_id: int = 0,
             report_id: int = 0,
             page: int = 1,
@@ -145,7 +146,7 @@ class TaskContextTools(ToolBase):
         def task_workflow_log_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             workflow_node_id: int = 0,
         ) -> dict[str, Any]:
             return self.task_workflow_log_get(
@@ -249,20 +250,21 @@ class TaskContextTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         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)
+        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)
 
         def runner(session_profile, context):
             data = self._build_task_context(
                 profile=profile,
                 context=context,
                 app_key=app_key,
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 include_candidates=include_candidates,
                 include_associated_reports=include_associated_reports,
@@ -287,7 +289,7 @@ class TaskContextTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         workflow_node_id: int,
         fields: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
@@ -311,14 +313,16 @@ class TaskContextTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         workflow_node_id: int,
         action: str,
         payload: dict[str, Any],
         fields: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        self._require_app_record_and_node(app_key, record_id, workflow_node_id)
+        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)
         normalized_action = (action or "").strip().lower()
         if normalized_action not in {"approve", "reject", "rollback", "transfer", "urge", "save_only"}:
             raise_tool_error(
@@ -341,7 +345,7 @@ class TaskContextTools(ToolBase):
                     profile=profile,
                     context=context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     include_candidates=False,
                     include_associated_reports=False,
@@ -354,7 +358,7 @@ class TaskContextTools(ToolBase):
                         session_profile=session_profile,
                         context=context,
                         app_key=app_key,
-                        record_id=record_id,
+                        record_id=record_id_int,
                         workflow_node_id=workflow_node_id,
                         action=normalized_action,
                         source_error=error,
@@ -387,7 +391,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} workflow_node_id={workflow_node_id}"
+                        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}"
                     )
                 )
             feedback_required_for = capabilities.get("action_constraints", {}).get("feedback_required_for") or []
@@ -409,7 +413,7 @@ class TaskContextTools(ToolBase):
                     profile=profile,
                     context=context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     task_context=task_context,
                     fields=field_updates,
@@ -421,14 +425,14 @@ class TaskContextTools(ToolBase):
                     profile=profile,
                     context=context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                 )
             try:
                 raw = self._execute_task_action(
                     profile=profile,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     normalized_action=normalized_action,
                     payload=body,
@@ -441,7 +445,7 @@ class TaskContextTools(ToolBase):
                         session_profile=session_profile,
                         context=context,
                         app_key=app_key,
-                        record_id=record_id,
+                        record_id=record_id_int,
                         workflow_node_id=workflow_node_id,
                         action=normalized_action,
                         source_error=error,
@@ -453,7 +457,7 @@ class TaskContextTools(ToolBase):
                 verification, warnings = self._verify_task_save_only(
                     context=context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     before_apply_status=before_apply_status,
                     expected_answers=((prepared_fields or {}).get("normalized_answers") or []),
@@ -467,7 +471,7 @@ class TaskContextTools(ToolBase):
                     profile=profile,
                     context=context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     action=normalized_action,
                     before_apply_status=before_apply_status,
@@ -490,7 +494,7 @@ class TaskContextTools(ToolBase):
                     "action": normalized_action,
                     "resource": {
                         "app_key": app_key,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                     },
                     "selection": {"action": normalized_action},
@@ -507,7 +511,7 @@ class TaskContextTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         workflow_node_id: int,
         normalized_action: str,
         payload: dict[str, Any],
@@ -671,12 +675,12 @@ class TaskContextTools(ToolBase):
         todo_items = self._safe_task_list_items(profile=profile, task_box="todo", app_key=app_key)
         initiated_items = self._safe_task_list_items(profile=profile, task_box="initiated", app_key=app_key)
         downstream_todo_detected = any(
-            int(item.get("record_id") or 0) == record_id and int(item.get("workflow_node_id") or 0) != workflow_node_id
+            ids_equal(item.get("record_id"), record_id) and int(item.get("workflow_node_id") or 0) != workflow_node_id
             for item in todo_items
             if isinstance(item, dict)
         )
         initiated_visible = any(
-            int(item.get("record_id") or 0) == record_id
+            ids_equal(item.get("record_id"), record_id)
             for item in initiated_items
             if isinstance(item, dict)
         )
@@ -693,7 +697,7 @@ class TaskContextTools(ToolBase):
             int(item.get("workflow_node_id") or 0)
             for item in todo_items
             if isinstance(item, dict)
-            and int(item.get("record_id") or 0) == record_id
+            and ids_equal(item.get("record_id"), record_id)
             and int(item.get("workflow_node_id") or 0) != workflow_node_id
         }
         workflow_log_digest = self._workflow_log_digest(log_items)
@@ -898,7 +902,7 @@ class TaskContextTools(ToolBase):
                 int(item.get("workflow_node_id") or 0)
                 for item in todo_items
                 if isinstance(item, dict)
-                and int(item.get("record_id") or 0) == record_id
+                and ids_equal(item.get("record_id"), record_id)
                 and int(item.get("workflow_node_id") or 0) != workflow_node_id
             }
         )
@@ -918,6 +922,7 @@ class TaskContextTools(ToolBase):
         before_apply_status: Any,
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
+        record_id_text = stringify_backend_id(record_id)
         verification, warnings = self._verify_task_action_runtime(
             profile=profile,
             context=context,
@@ -950,7 +955,7 @@ class TaskContextTools(ToolBase):
                     "action": action,
                     "resource": {
                         "app_key": app_key,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                     },
                     "selection": {"action": action},
@@ -978,7 +983,7 @@ class TaskContextTools(ToolBase):
                 "action": action,
                 "resource": {
                     "app_key": app_key,
-                    "record_id": record_id,
+                    "record_id": record_id_text,
                     "workflow_node_id": workflow_node_id,
                 },
                 "selection": {"action": action},
@@ -1101,7 +1106,9 @@ class TaskContextTools(ToolBase):
         page_size: int,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        self._require_app_record_and_node(app_key, record_id, workflow_node_id)
+        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 report_id <= 0:
             raise_tool_error(QingflowApiError.config_error("report_id must be positive"))
         if page <= 0 or page_size <= 0:
@@ -1112,7 +1119,7 @@ class TaskContextTools(ToolBase):
                 profile=profile,
                 context=context,
                 app_key=app_key,
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 include_candidates=False,
                 include_associated_reports=True,
@@ -1122,7 +1129,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} workflow_node_id={workflow_node_id}"
+                        f"report_id={report_id} is not visible for app_key='{app_key}' record_id={record_id_text} workflow_node_id={workflow_node_id}"
                     )
                 )
             association_query = self._build_association_query(
@@ -1131,7 +1138,7 @@ class TaskContextTools(ToolBase):
             )
             selection = {
                 "app_key": app_key,
-                "record_id": record_id,
+                "record_id": record_id_text,
                 "workflow_node_id": workflow_node_id,
                 "report_id": report_id,
                 "target_app_key": report_item.get("target_app_key"),
@@ -1286,18 +1293,20 @@ class TaskContextTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         workflow_node_id: int,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        self._require_app_record_and_node(app_key, record_id, workflow_node_id)
+        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)
 
         def runner(session_profile, context):
             task_context = self._build_task_context(
                 profile=profile,
                 context=context,
                 app_key=app_key,
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 include_candidates=False,
                 include_associated_reports=False,
@@ -1307,7 +1316,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} workflow_node_id={workflow_node_id}"
+                        f"workflow logs are not visible for app_key='{app_key}' record_id={record_id_text} workflow_node_id={workflow_node_id}"
                     )
                 )
             page = self.backend.request(
@@ -1316,7 +1325,7 @@ class TaskContextTools(ToolBase):
                 "/application/workflow/node/record",
                 json_body={
                     "key": app_key,
-                    "rowRecordId": record_id,
+                    "rowRecordId": record_id_int,
                     "nodeId": workflow_node_id,
                     "role": 3,
                     "pageNum": 1,
@@ -1334,7 +1343,7 @@ class TaskContextTools(ToolBase):
                 "data": {
                     "selection": {
                         "app_key": app_key,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                     },
                     "visibility": {
@@ -1443,11 +1452,12 @@ class TaskContextTools(ToolBase):
             save_only_source=save_only_source,
         )
         visibility = self._build_visibility(node_info, detail)
+        record_id_text = stringify_backend_id(record_id)
         return {
             "task": {
                 "app_key": app_key,
                 "app_name": app_name,
-                "record_id": record_id,
+                "record_id": record_id_text,
                 "workflow_node_id": workflow_node_id,
                 "workflow_node_name": node_info.get("auditNodeName") or node_info.get("nodeName"),
                 "actionable": True,
@@ -1458,7 +1468,7 @@ class TaskContextTools(ToolBase):
                 "raw": dict(node_info),
             },
             "record": {
-                "apply_id": detail.get("applyId", record_id),
+                "apply_id": stringify_backend_id(detail.get("applyId") or record_id),
                 "apply_status": detail.get("applyStatus"),
                 "apply_num": detail.get("applyNum"),
                 "custom_apply_num": detail.get("customApplyNum"),
@@ -1526,7 +1536,7 @@ class TaskContextTools(ToolBase):
             "task": {
                 "app_key": task.get("app_key"),
                 "app_name": task.get("app_name"),
-                "record_id": task.get("record_id"),
+                "record_id": stringify_backend_id(task.get("record_id")),
                 "workflow_node_id": task.get("workflow_node_id"),
                 "workflow_node_name": task.get("workflow_node_name"),
                 "initiator": self._compact_initiator(record.get("apply_user")),
@@ -1722,10 +1732,10 @@ class TaskContextTools(ToolBase):
         record_id = raw.get("rowRecordId") or raw.get("recordId") or raw.get("applyId")
         workflow_node_id = raw.get("nodeId") or raw.get("auditNodeId")
         return {
-            "task_id": raw.get("id") or raw.get("taskId") or record_id,
+            "task_id": stringify_backend_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,
+            "record_id": stringify_backend_id(record_id),
             "workflow_node_id": workflow_node_id,
             "workflow_node_name": raw.get("nodeName") or raw.get("auditNodeName"),
             "apply_time": raw.get("applyTime") or raw.get("receiveTime"),
@@ -1816,6 +1826,7 @@ class TaskContextTools(ToolBase):
         current_answers: Any,
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
+        record_id_text = stringify_backend_id(record_id)
         try:
             app_schema = self._record_tools._get_form_schema(profile, context, app_key, force_refresh=False)
         except QingflowApiError as error:
@@ -1832,7 +1843,7 @@ class TaskContextTools(ToolBase):
                 ],
                 "selection": {
                     "app_key": app_key,
-                    "record_id": record_id,
+                    "record_id": record_id_text,
                     "workflow_node_id": workflow_node_id,
                 },
                 "transport_error": {
@@ -1917,7 +1928,7 @@ class TaskContextTools(ToolBase):
             "warnings": schema_warnings,
             "selection": {
                 "app_key": app_key,
-                "record_id": record_id,
+                "record_id": record_id_text,
                 "workflow_node_id": workflow_node_id,
             },
         }