@josephyan/qingflow-app-user-mcp 0.2.0-beta.30 → 0.2.0-beta.32

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.30",
+  "version": "0.2.0-beta.32",
   "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.0b30"
+version = "0.2.0b32"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -19,16 +19,20 @@ Route to exactly one of these specialized paths:
 1. Record CRUD  
    Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
 
-2. Analysis  
+2. Task workflow operations  
+   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+3. Analysis  
    Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 
-3. MCP connection / auth / workspace selection  
+4. MCP connection / auth / workspace selection  
    Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
 
 ## Routing Rules
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
+- If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
 - If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
 

package/skills/qingflow-record-crud/SKILL.md

@@ -60,7 +60,9 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 ## Record Read Rules
 
 - Use `record_list` for browse/export/sample inspection only
-- For `columns`, prefer `[{ "field_id": 12 }]`; bare integer field ids are accepted for compatibility
+- For `columns`, use `[{ "field_id": 12 }]`
+- For `where`, use `{ "field_id": 12, "op": "eq", "value": "进行中" }`
+- For `order_by`, use `{ "field_id": 18, "direction": "desc" }`
 - Use `record_get` when `record_id` is known
 - `record_get` without explicit `columns` still returns only applicant-node visible fields; do not assume it exposes the full builder-side record
 - `record_list` and `record_get` may reject hidden-field `field_id`s because record tools now validate against the applicant-node visible schema only

package/skills/qingflow-record-crud/references/record-patterns.md

@@ -15,9 +15,9 @@ Remember that `record_schema_get` only exposes the current user's applicant-node
 
 Keep the browse DSL simple:
 
-- `columns`: prefer `[{ "field_id": 12 }]`; bare integers are accepted for compatibility
-- `where`: flat AND filters only
-- `order_by`: field sorting only
+- `columns`: use `[{ "field_id": 12 }]`
+- `where`: flat AND filters only, using `{ "field_id": 12, "op": "eq", "value": "进行中" }`
+- `order_by`: field sorting only, using `{ "field_id": 18, "direction": "desc" }`
 - `limit` and `page`: browsing intent only
 
 Do not use `record_list` for grouped conclusions, ratios, rankings, trends, or any final statistical claim.

package/skills/qingflow-task-ops/SKILL.md

@@ -1,82 +1,62 @@
 ---
 name: qingflow-task-ops
-description: Use Qingflow task center, workflow usage actions, comments, and directory lookup after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
+description: Use Qingflow todo discovery, workflow task context, associated approval context, workflow logs, and unified task actions after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
 metadata:
-  short-description: Qingflow task center and workflow operations
+  short-description: Qingflow task workflow context and actions
 ---
 
 # Qingflow Task Ops
 
 ## Overview
 
-This skill is for task-center and workflow usage operations only.
+This skill is for task workflow operations only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
 
 ## Default Paths
 
 Use exactly one of these default paths:
 
-1. Task headline counts  
-   `task_summary`
-
-2. Flat task browsing  
+1. Find target todos  
    `task_list`
 
-3. Grouped workload buckets  
-   `task_facets`
+2. Read one task context  
+   `task_list -> exact target -> task_get`
 
-4. Task or workflow action  
-   `task_list / task_facets -> exact target -> task_* action`
+3. Read associated approval context  
+   `task_get -> task_associated_report_detail_get` or `task_workflow_log_get`
 
-5. Comments and directory support  
-   `record_get -> record_comment_*` or `directory_*`
+4. Execute workflow action  
+   `task_list -> exact target -> task_get -> task_action_execute`
 
 ## Core Tools
 
-- `task_summary`
 - `task_list`
-- `task_facets`
-- `task_mark_read`
-- `task_mark_all_cc_read`
-- `task_urge`
-- `task_approve`
-- `task_reject`
-- `task_rollback_candidates`
-- `task_rollback`
-- `task_transfer_candidates`
-- `task_transfer`
-- `record_comment_write`
-- `record_comment_list`
-- `record_comment_mentions`
-- `record_comment_mark_read`
+- `task_get`
+- `task_action_execute`
+- `task_associated_report_detail_get`
+- `task_workflow_log_get`
 
 ## Supporting Tools
 
-- `directory_search`
-- `directory_list_internal_users`
-- `directory_list_all_internal_users`
-- `directory_list_internal_departments`
-- `directory_list_all_departments`
-- `directory_list_sub_departments`
-- `directory_list_external_members`
-- `record_get`
+- `app_list`
+- `app_search`
 
 ## Standard Operating Order
 
 1. Ensure auth exists
 2. Ensure workspace is selected
-3. Confirm target app and whether the task is task browse / grouped workload / comment / workflow action
-4. Use `task_summary`, `task_list`, or `task_facets` to locate the exact target first
-5. If a workflow action is required, identify the exact `task_id`, `record_id`, and `workflow_node_id` whenever practical
-6. Use directory tools only when member/department lookup is needed to support the action
-7. For production actions, read current task or record state first whenever practical
-8. After actions, report the affected `task_id`, `record_id`, or returned item count
+3. Discover the exact target with `task_list`
+4. Read node context with `task_get`
+5. Before giving any approval recommendation, read `task_workflow_log_get`
+6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
+7. Give an approval recommendation only after reviewing the node context, workflow log, and associated report details
+8. Wait for explicit user confirmation before `task_action_execute`
+9. Execute through `task_action_execute`
+10. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, and executed action
 
 ## Task-Center Rules
 
-- Use `task_summary` for headline counts
 - Use `task_list` for flat browsing
-- Use `task_facets` for grouped worksheet or workflow-node buckets
 - `task_box` must be one of:
   - `todo`
   - `initiated`
@@ -93,30 +73,39 @@ Use exactly one of these default paths:
   - `due_soon`
   - `unread`
   - `ended`
-- Task counts are task-center counts, not record counts
-- If the user asks for workload by worksheet or node, use `task_facets`
-- If a result set is truncated, describe it as `已返回分组中` or `主要分组`
+- `task_list` is the only public task discovery path in this MCP surface
+- Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
+- Default box usage:
+  - `todo`: `task_list -> task_get -> task_workflow_log_get / task_associated_report_detail_get -> recommendation -> explicit user confirmation -> task_action_execute`
+  - `initiated`: `task_list -> record_get`
+  - `done`: `task_list -> record_get`
+  - `cc`: `task_list -> record_get`
+- Treat `initiated`, `done`, and `cc` primarily as list-plus-record-detail flows, not task action flows
 
 ## Workflow Usage Actions
 
-- Find the exact target first
-- For approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info
-- Avoid workflow actions on ambiguous tasks or records
-- For rollback or transfer, fetch candidates first
-- Summarize the final action and target task ids or record ids
-
-## Comments and Directory
-
-- Use `record_comment_write` only after the exact `record_id` is known
-- Use `record_comment_mentions` to resolve mention candidates before building complex comment payloads
-- Use `directory_search` for fuzzy member/department lookup
-- Use `directory_list_all_internal_users` and `directory_list_all_departments` only when the user explicitly wants a complete export
+- `task_get.capabilities.available_actions` is the source of truth for v1 executable actions
+- Current public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+- Before any approve/reject/rollback/transfer recommendation, always review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
+- If `task_get` returns visible `associated_reports`, review each one with `task_associated_report_detail_get`; do not rely on report summary alone
+- Do not give an approval recommendation based only on `task_get`
+- Do not execute `task_action_execute` until the user explicitly confirms the chosen action
+- Avoid actions on ambiguous tasks or records
+- Summarize the final action and the exact `app_key / record_id / workflow_node_id`
 
 ## Response Interpretation
 
-- `task_summary` gives headline counts only
-- `task_list` returns flat task rows, not grouped workload conclusions
-- `task_facets` is the only default grouped workload path
+- `task_list` returns normalized todo rows and is the only default discovery path
+- `task_get` returns node context summary, not full historical report data
+- `task_associated_report_detail_get` may return either:
+  - `result_type=view_list`
+  - `result_type=chart_data`
+- `task_workflow_log_get` returns workflow log detail only when the node grants log visibility
 - Treat `request_route` as the source of truth for live route debugging
 - If only part of the requested work is completed, explicitly disclose which parts are done and which are not
 

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -17,6 +17,7 @@ from .tools.qingbi_report_tools import QingbiReportTools
 from .tools.record_tools import RecordTools
 from .tools.role_tools import RoleTools
 from .tools.solution_tools import SolutionTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.view_tools import ViewTools
 from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
@@ -78,7 +79,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `record_schema_get -> record_list / record_get / record_write`
 
-- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+- Use `columns` as `[{{field_id}}]`
+- Use `where` items as `{{field_id, op, value}}`
+- Use `order_by` items as `{{field_id, direction}}`
+- Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
 `record_write` uses SQL-like JSON clauses:
 
@@ -90,6 +94,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -112,6 +124,7 @@ Avoid builder-side app or schema changes here.""",
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_user.py

@@ -12,6 +12,7 @@ from .tools.auth_tools import AuthTools
 from .tools.directory_tools import DirectoryTools
 from .tools.file_tools import FileTools
 from .tools.record_tools import RecordTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
 
 
@@ -66,7 +67,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `record_schema_get -> record_list / record_get / record_write`
 
-- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+- Use `columns` as `[{{field_id}}]`
+- Use `where` items as `{{field_id, op, value}}`
+- Use `order_by` items as `{{field_id, direction}}`
+- Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
 `record_write` uses SQL-like JSON clauses:
 
@@ -78,6 +82,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -218,6 +230,7 @@ Avoid builder-side app or schema changes here.""",
     )
 
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
 
     return server

package/src/qingflow_mcp/tools/approval_tools.py

@@ -611,9 +611,11 @@ class ApprovalTools(ToolBase):
         self._normalize_alias(body, "formId", "form_id")
 
         node_id = self._extract_node_id(body)
-        body["nodeId"] = node_id
+        body["nodeId"] = self._resolve_actionable_node_id(context, app_key, apply_id, node_id)
         body["applyId"] = self._match_or_fill_int(body, field_name="applyId", expected_value=apply_id)
         body["formId"] = self._resolve_form_id(profile, context, app_key, explicit_form_id=body.get("formId"))
+        if body.get("answers") is None:
+            body["answers"] = self._fetch_current_todo_answers(context, app_key, apply_id, body["nodeId"])
 
         self._validate_approval_payload(body)
         return body
@@ -672,6 +674,54 @@ class ApprovalTools(ToolBase):
         elif alias_value is not None and payload.get(canonical_key) != alias_value:
             raise_tool_error(QingflowApiError.config_error(f"payload.{canonical_key} and payload.{alias_key} must match when both are provided"))
 
+    def _resolve_actionable_node_id(self, context, app_key: str, apply_id: int, node_id: int) -> int:  # type: ignore[no-untyped-def]
+        infos = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{apply_id}/auditInfo",
+            params={"type": 1},
+        )
+        if not isinstance(infos, list) or not infos:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"apply_id={apply_id} is not currently actionable for the logged-in user in todo list"
+                )
+            )
+        actionable_node_ids = {
+            candidate
+            for item in infos
+            if isinstance(item, dict)
+            for candidate in (item.get("auditNodeId"), item.get("nodeId"))
+            if isinstance(candidate, int) and candidate > 0
+        }
+        if node_id not in actionable_node_ids:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"payload.nodeId={node_id} is not an actionable todo node for apply_id={apply_id}"
+                )
+            )
+        return node_id
+
+    def _fetch_current_todo_answers(self, context, app_key: str, apply_id: int, node_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        detail = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{apply_id}",
+            params={"role": 3, "listType": 1, "auditNodeId": node_id},
+        )
+        answers = detail.get("answers") if isinstance(detail, dict) else None
+        if not isinstance(answers, list):
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"cannot resolve current answers for apply_id={apply_id} nodeId={node_id}"
+                )
+            )
+        normalized_answers: list[dict[str, Any]] = []
+        for item in answers:
+            if isinstance(item, dict):
+                normalized_answers.append(dict(item))
+        return normalized_answers
+
     def _validate_approval_payload(self, payload: dict[str, Any]) -> None:
         self._reject_unsupported_fields(payload)
         if not isinstance(payload.get("formId"), int) or payload["formId"] <= 0:
@@ -680,6 +730,9 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.applyId must be a positive integer"))
         if not isinstance(payload.get("nodeId"), int) or payload["nodeId"] <= 0:
             raise_tool_error(QingflowApiError.config_error("payload.nodeId must be a positive integer"))
+        answers = payload.get("answers")
+        if answers is not None and not isinstance(answers, list):
+            raise_tool_error(QingflowApiError.config_error("payload.answers must be an array when provided"))
 
     def _validate_audit_payload(self, payload: dict[str, Any], *, require_uid: bool = False) -> None:
         self._reject_unsupported_fields(payload)

package/src/qingflow_mcp/tools/record_tools.py

@@ -565,6 +565,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if limit <= 0:
             raise_tool_error(QingflowApiError.config_error("limit must be positive"))
+        legacy_warnings = _detect_analyze_legacy_warnings(
+            dimensions=dimensions,
+            metrics=metrics,
+            filters=filters,
+            sort=sort,
+        )
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -594,6 +600,7 @@ class RecordTools(ToolBase):
                 limit=limit,
                 strict_full=strict_full,
                 output_profile=output_profile,
+                extra_warnings=legacy_warnings,
             )
 
         return self._run_record_tool(profile, runner)
@@ -615,6 +622,7 @@ class RecordTools(ToolBase):
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        legacy_warnings = _detect_record_list_legacy_warnings(columns=columns, where=where, order_by=order_by)
         normalized_columns = _normalize_public_column_selectors(columns)
         if not normalized_columns:
             raise_tool_error(QingflowApiError.config_error("columns is required"))
@@ -651,6 +659,7 @@ class RecordTools(ToolBase):
         list_data = cast(JSONObject, cast(JSONObject, raw["data"])["list"])
         pagination = cast(JSONObject, list_data["pagination"])
         warnings: list[JSONObject] = []
+        warnings.extend(legacy_warnings)
         warning = _normalize_optional_text(list_data.get("analysis_warning"))
         if warning:
             warnings.append({"code": "BROWSE_ONLY", "message": warning})
@@ -1906,6 +1915,7 @@ class RecordTools(ToolBase):
         limit: int,
         strict_full: bool,
         output_profile: str,
+        extra_warnings: list[JSONObject] | None = None,
     ) -> JSONObject:
         started_at = time.perf_counter()
         analysis_paging = _fixed_analysis_scan_policy()
@@ -2068,7 +2078,11 @@ class RecordTools(ToolBase):
                 for idx, row in enumerate(rows, start=1)
             ]
 
-        warnings = self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated)
+        warnings = self._build_analyze_warnings(
+            local_filtering=local_filtering,
+            rows_truncated=rows_truncated,
+            extra_warnings=extra_warnings or [],
+        )
         completeness: JSONObject = {
             "status": completeness_status,
             "safe_for_final_conclusion": completeness_status == "complete",
@@ -2230,8 +2244,15 @@ class RecordTools(ToolBase):
             )
         return sorted_rows
 
-    def _build_analyze_warnings(self, *, local_filtering: bool, rows_truncated: bool) -> list[JSONObject]:
+    def _build_analyze_warnings(
+        self,
+        *,
+        local_filtering: bool,
+        rows_truncated: bool,
+        extra_warnings: list[JSONObject],
+    ) -> list[JSONObject]:
         warnings: list[JSONObject] = []
+        warnings.extend(extra_warnings)
         if local_filtering:
             warnings.append({"code": "LOCAL_VIEW_FILTERING"})
         if rows_truncated:
@@ -3734,18 +3755,23 @@ class RecordTools(ToolBase):
         for idx, item in enumerate(where):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"where[{idx}] must be an object"))
+            _ensure_allowed_record_list_keys(
+                item,
+                location=f"where[{idx}]",
+                allowed_keys={"field_id", "fieldId", "op", "operator", "value", "values"},
+                example="{'field_id': 12, 'op': 'eq', 'value': '进行中'}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
             if field_id is None:
                 raise_tool_error(QingflowApiError.config_error(f"where[{idx}] requires field_id"))
             payload: JSONObject = {"field_id": field_id}
-            if "op" in item:
-                payload["op"] = item["op"]
-            if "operator" in item:
-                payload["operator"] = item["operator"]
+            op = item.get("op", item.get("operator"))
+            if op is not None:
+                payload["op"] = op
             if "value" in item:
                 payload["value"] = item["value"]
             elif "values" in item:
-                payload["values"] = item["values"]
+                payload["value"] = item["values"]
             normalized.append(payload)
         return normalized
 
@@ -3754,6 +3780,12 @@ class RecordTools(ToolBase):
         for idx, item in enumerate(order_by):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] must be an object"))
+            _ensure_allowed_record_list_keys(
+                item,
+                location=f"order_by[{idx}]",
+                allowed_keys={"field_id", "fieldId", "direction", "order"},
+                example="{'field_id': 18, 'direction': 'desc'}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
             if field_id is None:
                 raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] requires field_id"))
@@ -5361,6 +5393,12 @@ def _normalize_public_column_selectors(columns: list[JSONObject | int]) -> list[
         if isinstance(item, int):
             field_id = item
         elif isinstance(item, dict):
+            _ensure_allowed_record_list_keys(
+                item,
+                location="columns[]",
+                allowed_keys={"field_id", "fieldId"},
+                example="{'field_id': 12}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
         if field_id is None or field_id < 0:
             raise_tool_error(
@@ -5376,6 +5414,92 @@ def _column_selector_payload(field_id: int) -> JSONObject:
     return {"field_id": field_id}
 
 
+def _ensure_allowed_record_list_keys(
+    item: JSONObject,
+    *,
+    location: str,
+    allowed_keys: set[str],
+    example: str,
+) -> None:
+    unexpected_keys = sorted(str(key) for key in item.keys() if str(key) not in allowed_keys)
+    if unexpected_keys:
+        raise_tool_error(
+            QingflowApiError.config_error(
+                f"{location} contains unsupported keys: {unexpected_keys}. Use {example}."
+            )
+        )
+
+
+def _detect_record_list_legacy_warnings(
+    *,
+    columns: list[JSONObject | int],
+    where: list[JSONObject],
+    order_by: list[JSONObject],
+) -> list[JSONObject]:
+    warnings: list[JSONObject] = []
+    if any(isinstance(item, int) or (isinstance(item, dict) and "fieldId" in item) for item in columns):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_COLUMNS_DSL",
+                "message": "Use columns as [{field_id}] objects. Bare integers and fieldId are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "operator", "values")) for item in where):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_FILTER_DSL",
+                "message": "Use where items as {field_id, op, value}. fieldId/operator/values are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "order")) for item in order_by):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_SORT_DSL",
+                "message": "Use order_by items as {field_id, direction}. fieldId/order are compatibility-only.",
+            }
+        )
+    return warnings
+
+
+def _detect_analyze_legacy_warnings(
+    *,
+    dimensions: list[JSONObject],
+    metrics: list[JSONObject],
+    filters: list[JSONObject],
+    sort: list[JSONObject],
+) -> list[JSONObject]:
+    warnings: list[JSONObject] = []
+    if any(isinstance(item, dict) and "fieldId" in item for item in dimensions):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_DIMENSION_DSL",
+                "message": "Use dimensions as {field_id, alias, bucket}. fieldId is compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "type", "agg", "aggregation")) for item in metrics):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_METRIC_DSL",
+                "message": "Use metrics as {op, field_id, alias}. fieldId/type/agg/aggregation are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "operator", "values")) for item in filters):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_FILTER_DSL",
+                "message": "Use filters as {field_id, op, value}. fieldId/operator/values are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and "direction" in item for item in sort):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_SORT_DSL",
+                "message": "Use sort items as {by, order}. direction is compatibility-only.",
+            }
+        )
+    return warnings
+
+
 def _resolve_sort_ascend(item: JSONObject) -> bool:
     if "isAscend" in item:
         return bool(item["isAscend"])