@josephyan/qingflow-app-builder-mcp 0.2.0-beta.2 → 0.2.0-beta.20

package/src/qingflow_mcp/tools/record_tools.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import re
+import time
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import cast
@@ -16,14 +17,17 @@ from .base import ToolBase
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
+DEFAULT_LIST_PAGE_SIZE = 200
+DEFAULT_ANALYSIS_PAGE_SIZE = 1000
 DEFAULT_SCAN_MAX_PAGES = 10
+DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
+DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP = 100
 DEFAULT_ROW_LIMIT = 200
 DEFAULT_OUTPUT_PROFILE = "compact"
 MAX_LIST_COLUMN_LIMIT = 20
 MAX_RECORD_COLUMN_LIMIT = 20
 MAX_SUMMARY_PREVIEW_COLUMN_LIMIT = 6
 BACKEND_LIST_SEARCH_FIELD_LIMIT = 10
-SUPPORTED_QUERY_TOOLS = {"record_query", "record_aggregate", "record_get"}
 MEMBER_QUE_TYPES = {5}
 DEPARTMENT_QUE_TYPES = {22}
 DATE_QUE_TYPES = {4}
@@ -136,36 +140,55 @@ class RecordTools(ToolBase):
 
     def register(self, mcp: FastMCP) -> None:
         @mcp.tool()
-        def record_field_resolve(
+        def record_schema_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            query: str | int | None = None,
-            queries: list[str | int] | None = None,
-            top_k: int = 3,
-            fuzzy: bool = True,
+            view_key: str | None = None,
+            view_name: str | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_field_resolve(
+            return self.record_schema_get(
                 profile=profile,
                 app_key=app_key,
-                query=query,
-                queries=queries,
-                top_k=top_k,
-                fuzzy=fuzzy,
+                view_key=view_key,
+                view_name=view_name,
+                output_profile=output_profile,
             )
 
         @mcp.tool(
             description=(
-                "Preflight complex read requests before actual execution. Resolves field selectors, validates required arguments, "
-                "and estimates scan scope. Prefer this when the agent is unsure about query shape."
+                "Run schema-first analytics on a Qingflow app using a restricted DSL. "
+                "Use record_schema_get first, then let the model build a DSL with field_id references only. "
+                "dimensions=[] means whole-table summary; dimensions!=[] means grouped analysis. "
+                "This route hides paging and scan-budget controls from callers."
             )
         )
-        def record_query_plan(
+        def record_analyze(
             profile: str = DEFAULT_PROFILE,
-            tool: str = "record_query",
-            arguments: JSONObject | None = None,
-            resolve_fields: bool = True,
+            app_key: str = "",
+            dimensions: list[JSONObject] | None = None,
+            metrics: list[JSONObject] | None = None,
+            filters: list[JSONObject] | None = None,
+            sort: list[JSONObject] | None = None,
+            limit: int = 50,
+            strict_full: bool = True,
+            view_key: str | None = None,
+            view_name: str | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_query_plan(profile=profile, tool=tool, arguments=arguments or {}, resolve_fields=resolve_fields)
+            return self.record_analyze(
+                profile=profile,
+                app_key=app_key,
+                dimensions=dimensions or [],
+                metrics=metrics or [],
+                filters=filters or [],
+                sort=sort or [],
+                limit=limit,
+                strict_full=strict_full,
+                view_key=view_key,
+                view_name=view_name,
+                output_profile=output_profile,
+            )
 
         @mcp.tool(
             description=(
@@ -194,9 +217,10 @@ class RecordTools(ToolBase):
 
         @mcp.tool(
             description=(
-                "Unified read entry for record list / record detail / summary analysis. "
-                "List mode returns flattened wide-table rows only. Use query_mode=auto to route: "
-                "apply_id -> record, amount_column/time_range/stat_policy -> summary, otherwise -> list."
+                "Unified read entry for record list / record detail. "
+                "Use query_mode=auto to route: apply_id -> record, otherwise -> list. "
+                "query_mode only supports auto, list, or record. "
+                "For statistical analysis use record_schema_get and record_analyze."
             )
         )
         def record_query(
@@ -205,94 +229,38 @@ class RecordTools(ToolBase):
             app_key: str = "",
             apply_id: int | None = None,
             page_num: int = 1,
-            page_size: int = DEFAULT_QUERY_PAGE_SIZE,
-            requested_pages: int = 1,
-            scan_max_pages: int = DEFAULT_SCAN_MAX_PAGES,
             query_key: str | None = None,
             filters: list[JSONObject] | None = None,
             sorts: list[JSONObject] | None = None,
             max_rows: int = DEFAULT_ROW_LIMIT,
             max_columns: int | None = None,
             select_columns: list[str | int] | None = None,
-            amount_column: str | int | None = None,
-            time_range: JSONObject | None = None,
-            stat_policy: JSONObject | None = None,
-            strict_full: bool = False,
             output_profile: str = DEFAULT_OUTPUT_PROFILE,
             list_type: int = DEFAULT_RECORD_LIST_TYPE,
             view_key: str | None = None,
             view_name: str | None = None,
         ) -> JSONObject:
+            paging = _fixed_list_scan_policy()
             return self.record_query(
                 profile=profile,
                 query_mode=query_mode,
                 app_key=app_key,
                 apply_id=apply_id,
                 page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
+                page_size=int(paging["page_size"]),
+                requested_pages=int(paging["requested_pages"]),
+                scan_max_pages=int(paging["scan_max_pages"]),
+                auto_expand_pages=bool(paging["auto_expand_pages"]),
                 query_key=query_key,
                 filters=filters or [],
                 sorts=sorts or [],
                 max_rows=max_rows,
                 max_columns=max_columns,
                 select_columns=select_columns or [],
-                amount_column=amount_column,
-                time_range=time_range or {},
-                stat_policy=stat_policy or {},
-                strict_full=strict_full,
-                output_profile=output_profile,
-                list_type=list_type,
-                view_key=view_key,
-                view_name=view_name,
-            )
-
-        @mcp.tool(
-            description=(
-                "Grouped record analysis endpoint. Aggregates record counts and numeric metrics by selected dimensions. "
-                "Use strict_full=true when the result will be used as a final conclusion."
-            )
-        )
-        def record_aggregate(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            group_by: list[str | int] | None = None,
-            amount_column: str | int | None = None,
-            metrics: list[str] | None = None,
-            page_num: int = 1,
-            page_size: int = DEFAULT_QUERY_PAGE_SIZE,
-            requested_pages: int = 1,
-            scan_max_pages: int = DEFAULT_SCAN_MAX_PAGES,
-            query_key: str | None = None,
-            filters: list[JSONObject] | None = None,
-            sorts: list[JSONObject] | None = None,
-            time_range: JSONObject | None = None,
-            time_bucket: str | None = None,
-            max_groups: int = 200,
-            strict_full: bool = False,
-            output_profile: str = DEFAULT_OUTPUT_PROFILE,
-            list_type: int = DEFAULT_RECORD_LIST_TYPE,
-            view_key: str | None = None,
-            view_name: str | None = None,
-        ) -> JSONObject:
-            return self.record_aggregate(
-                profile=profile,
-                app_key=app_key,
-                group_by=group_by or [],
-                amount_column=amount_column,
-                metrics=metrics or [],
-                page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
-                query_key=query_key,
-                filters=filters or [],
-                sorts=sorts or [],
-                time_range=time_range or {},
-                time_bucket=time_bucket,
-                max_groups=max_groups,
-                strict_full=strict_full,
+                amount_column=None,
+                time_range={},
+                stat_policy={},
+                strict_full=False,
                 output_profile=output_profile,
                 list_type=list_type,
                 view_key=view_key,
@@ -373,95 +341,911 @@ class RecordTools(ToolBase):
         ) -> JSONObject:
             return self.record_delete(profile=profile, app_key=app_key, apply_id=apply_id, list_type=list_type)
 
-    def record_field_resolve(
+    def record_schema_get(
         self,
         *,
         profile: str,
         app_key: str,
-        query: str | int | None,
-        queries: list[str | int] | None,
-        top_k: int,
-        fuzzy: bool,
+        view_key: str | None,
+        view_name: str | None,
+        output_profile: str,
     ) -> JSONObject:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        requested = [item for item in (queries or []) if item is not None]
-        if query is not None:
-            requested = [query]
-        if not requested:
-            raise_tool_error(QingflowApiError.config_error("query or queries is required"))
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
-            results = []
-            for item in requested:
-                text = str(item).strip()
-                if not text:
-                    continue
-                results.append({"requested": text, "matches": self._score_field_matches(text, index, fuzzy=fuzzy, top_k=top_k)})
-            return {
+            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
+            fields = [self._schema_field_payload(field) for field in index.by_id.values()]
+            suggested_dimensions = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("dimension_candidate"))
+            ]
+            suggested_metrics = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("metric_candidate"))
+            ]
+            suggested_time_fields = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("time_candidate"))
+            ]
+            response: JSONObject = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
+                "status": "success",
                 "request_route": self._request_route_payload(context),
                 "data": {
                     "app_key": app_key,
-                    "query_count": len(results),
-                    "results": results,
+                    "view_resolution": _view_selection_payload(view_selection),
+                    "fields": fields,
+                    "suggested_dimensions": suggested_dimensions,
+                    "suggested_metrics": suggested_metrics,
+                    "suggested_time_fields": suggested_time_fields,
                 },
             }
+            if output_profile == "verbose":
+                response["data"]["field_count"] = len(fields)
+            return response
 
         return self._run_record_tool(profile, runner)
 
-    def record_query_plan(self, *, profile: str, tool: str, arguments: JSONObject, resolve_fields: bool) -> JSONObject:
-        if tool not in SUPPORTED_QUERY_TOOLS:
-            raise_tool_error(QingflowApiError.config_error(f"tool must be one of {sorted(SUPPORTED_QUERY_TOOLS)}"))
-        normalized = _normalize_plan_arguments(tool, arguments)
-        validation = self._validate_plan_arguments(tool, normalized)
+    def record_analyze(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+        filters: list[JSONObject],
+        sort: list[JSONObject],
+        limit: int,
+        strict_full: bool,
+        view_key: str | None,
+        view_name: str | None,
+        output_profile: str,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if limit <= 0:
+            raise_tool_error(QingflowApiError.config_error("limit must be positive"))
 
         def runner(session_profile, context):
-            field_mapping: list[JSONObject] = []
-            view_resolution: JSONObject | None = None
-            if resolve_fields and isinstance(normalized.get("app_key"), str) and normalized.get("app_key"):
-                index = self._get_field_index(profile, context, cast(str, normalized["app_key"]), force_refresh=False)
-                for candidate in _collect_plan_field_candidates(tool, normalized):
-                    field_mapping.append(self._resolve_plan_candidate(candidate, index))
-                view_selection = self._resolve_view_selection(
-                    profile,
-                    context,
-                    cast(str, normalized["app_key"]),
-                    view_key=_normalize_optional_text(normalized.get("view_key")),
-                    view_name=_normalize_optional_text(normalized.get("view_name")),
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
+            compiled_dimensions = self._compile_analyze_dimensions(index, dimensions)
+            compiled_metrics = self._compile_analyze_metrics(index, metrics)
+            duplicate_aliases = {str(item["alias"]) for item in compiled_dimensions} & {str(item["alias"]) for item in compiled_metrics}
+            if duplicate_aliases:
+                raise RecordInputError(
+                    message=f"dimensions and metrics cannot share aliases: {sorted(duplicate_aliases)}",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use distinct aliases across dimensions and metrics.",
                 )
-                if view_selection is not None:
-                    view_resolution = {
-                        "resolved": True,
-                        "view_key": view_selection.view_key,
-                        "view_name": view_selection.view_name,
-                        "local_filtering": bool(view_selection.conditions),
-                        "condition_group_count": len(view_selection.conditions),
-                    }
-            estimate = _build_plan_estimate(tool, normalized)
-            readiness = _assess_plan_readiness(tool, normalized, validation, field_mapping, estimate)
-            return {
-                "profile": profile,
-                "ws_id": session_profile.selected_ws_id,
-                "ok": True,
-                "request_route": self._request_route_payload(context),
-                "data": {
-                    "tool": tool,
-                    "normalized_arguments": normalized,
-                    "validation": validation,
-                    "field_mapping": field_mapping,
-                    "view_resolution": view_resolution,
-                    "estimate": estimate,
-                    "ready_for_final_conclusion": readiness["ready_for_final_conclusion"],
-                    "final_conclusion_blockers": readiness["final_conclusion_blockers"],
-                    "recommended_next_actions": readiness["recommended_next_actions"],
+            compiled_filters = self._compile_analyze_filters(index, filters)
+            compiled_sort = self._compile_analyze_sort(sort, compiled_dimensions, compiled_metrics)
+            return self._execute_record_analyze(
+                profile=profile,
+                session_profile=session_profile,
+                context=context,
+                app_key=app_key,
+                index=index,
+                view_selection=view_selection,
+                dimensions=compiled_dimensions,
+                metrics=compiled_metrics,
+                filters=compiled_filters,
+                sort=compiled_sort,
+                limit=limit,
+                strict_full=strict_full,
+                output_profile=output_profile,
+            )
+
+        return self._run_record_tool(profile, runner)
+
+    def _schema_field_payload(self, field: FormField) -> JSONObject:
+        return {
+            "field_id": field.que_id,
+            "title": field.que_title,
+            "que_type": field.que_type,
+            "system": field.system,
+            "readonly": field.readonly,
+            "options": field.options,
+            "aliases": field.aliases,
+            "role_hints": self._schema_role_hints(field),
+        }
+
+    def _schema_role_hints(self, field: FormField) -> JSONObject:
+        field_family = self._schema_field_family(field)
+        time_candidate = field.que_type in DATE_QUE_TYPES
+        identifier_like = self._schema_is_identifier_like(field, field_family=field_family)
+        metric_candidate = bool(field.que_type == 8 and not field.system and not field.readonly and not identifier_like)
+        dimension_candidate = bool(
+            field.que_type not in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES | VERIFY_UNSUPPORTED_WRITE_QUE_TYPES
+            and not field.system
+        )
+        return {
+            "dimension_candidate": dimension_candidate,
+            "metric_candidate": metric_candidate,
+            "time_candidate": time_candidate,
+            "field_family": field_family,
+            "supported_metric_ops": self._schema_supported_metric_ops(field, field_family=field_family),
+            "semantic_hints": self._schema_semantic_hint(field, field_family=field_family),
+        }
+
+    def _schema_field_family(self, field: FormField) -> str:
+        if self._schema_is_identifier_like(field):
+            return "text"
+        que_type = field.que_type
+        if que_type == 8:
+            return "number"
+        if que_type in DATE_QUE_TYPES:
+            return "date"
+        if que_type in SINGLE_SELECT_QUE_TYPES | MULTI_SELECT_QUE_TYPES:
+            return "category"
+        if que_type in MEMBER_QUE_TYPES:
+            return "member"
+        if que_type in DEPARTMENT_QUE_TYPES:
+            return "department"
+        if que_type in BOOLEAN_QUE_TYPES:
+            return "boolean"
+        if que_type in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES:
+            return "unknown"
+        if que_type is None:
+            return "unknown"
+        return "text"
+
+    def _schema_is_identifier_like(self, field: FormField, *, field_family: str | None = None) -> bool:
+        normalized_title = _normalize_field_lookup_key(field.que_title)
+        if field.que_id == 0:
+            return True
+        if any(
+            token in normalized_title for token in ("编号", "单号", "流水号", "编码", "序号", "uid", "id", "code")
+        ):
+            return True
+        return False
+
+    def _schema_supported_metric_ops(self, field: FormField, *, field_family: str) -> list[str]:
+        if field.que_type in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES:
+            return []
+        if self._schema_is_identifier_like(field, field_family=field_family):
+            return ["distinct_count"]
+        if field_family == "number":
+            return ["sum", "avg", "min", "max", "distinct_count"]
+        if field_family in {"date", "category", "member", "department", "text", "boolean", "unknown"}:
+            return ["distinct_count"]
+        return []
+
+    def _schema_semantic_hint(self, field: FormField, *, field_family: str) -> str:
+        if self._schema_is_identifier_like(field, field_family=field_family):
+            return "unknown"
+        if field_family != "number":
+            return "unknown"
+        normalized_title = _normalize_field_lookup_key(field.que_title)
+        if any(token in normalized_title for token in ("比例", "比率", "占比", "转化率", "渗透率", "毛利率", "折扣率", "百分比")):
+            return "ratio_like"
+        if any(token in normalized_title for token in ("金额", "arr", "mrr", "收入", "成本", "价格", "单价", "费用", "预算", "报价", "应收", "实收", "总额", "价税")):
+            return "money_like"
+        if any(token in normalized_title for token in ("数量", "人数", "单量", "个数", "次数", "件数", "台数", "天数", "笔数", "数")):
+            return "quantity_like"
+        return "unknown"
+
+    def _resolve_field_by_id(self, field_id: int | None, index: FieldIndex, *, location: str) -> FormField:
+        if field_id is None:
+            raise RecordInputError(
+                message=f"{location} requires field_id",
+                error_code="MISSING_FIELD_ID",
+                fix_hint="Use record_schema_get and pass a valid field_id from the schema response.",
+            )
+        field = index.by_id.get(str(field_id))
+        if field is None:
+            raise RecordInputError(
+                message=f"{location} references unknown field_id '{field_id}'",
+                error_code="FIELD_NOT_FOUND",
+                fix_hint="Use record_schema_get to confirm the exact field_id before calling record_analyze.",
+                details={"location": location, "field_id": field_id},
+            )
+        return field
+
+    def _ensure_allowed_analyze_keys(
+        self,
+        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 RecordInputError(
+                message=f"{location} contains unsupported keys: {unexpected_keys}",
+                error_code="UNSUPPORTED_ANALYZE_DSL_KEY",
+                fix_hint=f"Use {location} in the documented DSL shape only, for example {example}.",
+                details={
+                    "location": location,
+                    "unexpected_keys": unexpected_keys,
+                    "allowed_keys": sorted(allowed_keys),
                 },
+            )
+
+    def _validate_analyze_filter_value(
+        self,
+        *,
+        field: FormField,
+        op: str,
+        value: JSONValue,
+        location: str,
+    ) -> JSONValue:
+        if op in {"is_null", "not_null"}:
+            if value is not None:
+                raise RecordInputError(
+                    message=f"{location} with op '{op}' must omit value",
+                    error_code="INVALID_ANALYZE_FILTER_VALUE",
+                    fix_hint="Remove value when using is_null or not_null.",
+                    details={"location": location, "op": op, "field": _field_ref_payload(field)},
+                )
+            return None
+
+        if op in {"in", "not_in"}:
+            if not isinstance(value, list) or not value:
+                raise RecordInputError(
+                    message=f"{location} with op '{op}' requires a non-empty array value",
+                    error_code="INVALID_ANALYZE_FILTER_VALUE",
+                    fix_hint="Use an array for in/not_in, for example ['A', 'B'].",
+                    details={"location": location, "op": op, "field": _field_ref_payload(field), "received_value": value},
+                )
+            if field.que_type in DATE_QUE_TYPES:
+                for idx, item in enumerate(value):
+                    self._validate_strict_date_filter_value(item, location=f"{location}.value[{idx}]")
+            return value
+
+        if op == "between":
+            lower, upper = _coerce_filter_range(value)
+            if lower is None and upper is None:
+                raise RecordInputError(
+                    message=f"{location} with op 'between' requires a two-bound range",
+                    error_code="INVALID_ANALYZE_FILTER_VALUE",
+                    fix_hint="Use value like ['2026-03-01', '2026-03-31'] or [100, 200].",
+                    details={"location": location, "op": op, "field": _field_ref_payload(field), "received_value": value},
+                )
+            if field.que_type == 8:
+                lower_amount = _coerce_amount(lower) if lower is not None else None
+                upper_amount = _coerce_amount(upper) if upper is not None else None
+                if lower is not None and lower_amount is None:
+                    raise RecordInputError(
+                        message=f"{location} lower bound is not a valid numeric value",
+                        error_code="INVALID_ANALYZE_FILTER_VALUE",
+                        fix_hint="Use numeric bounds when filtering a numeric field.",
+                        details={"location": location, "bound": "lower", "field": _field_ref_payload(field), "received_value": lower},
+                    )
+                if upper is not None and upper_amount is None:
+                    raise RecordInputError(
+                        message=f"{location} upper bound is not a valid numeric value",
+                        error_code="INVALID_ANALYZE_FILTER_VALUE",
+                        fix_hint="Use numeric bounds when filtering a numeric field.",
+                        details={"location": location, "bound": "upper", "field": _field_ref_payload(field), "received_value": upper},
+                    )
+                if lower_amount is not None and upper_amount is not None and lower_amount > upper_amount:
+                    raise RecordInputError(
+                        message=f"{location} lower bound cannot be greater than upper bound",
+                        error_code="INVALID_ANALYZE_FILTER_RANGE",
+                        fix_hint="Swap the between bounds so the lower value comes first.",
+                        details={"location": location, "field": _field_ref_payload(field), "received_value": value},
+                    )
+                return [lower, upper]
+            if field.que_type in DATE_QUE_TYPES:
+                lower_dt = self._validate_strict_date_filter_value(lower, location=f"{location}.value[0]") if lower is not None else None
+                upper_dt = self._validate_strict_date_filter_value(upper, location=f"{location}.value[1]") if upper is not None else None
+                if lower_dt is not None and upper_dt is not None and lower_dt > upper_dt:
+                    raise RecordInputError(
+                        message=f"{location} lower bound cannot be later than upper bound",
+                        error_code="INVALID_ANALYZE_FILTER_RANGE",
+                        fix_hint="Swap the date bounds so the earlier date comes first.",
+                        details={"location": location, "field": _field_ref_payload(field), "received_value": value},
+                    )
+                return [lower, upper]
+            raise RecordInputError(
+                message=f"{location} with op 'between' requires a numeric or date/time field",
+                error_code="INVALID_ANALYZE_FILTER_FIELD_TYPE",
+                fix_hint="Use between only on numeric or date/time fields.",
+                details={"location": location, "field": _field_ref_payload(field), "op": op},
+            )
+
+        if op in {"gt", "gte", "lt", "lte"}:
+            if value is None or isinstance(value, (list, dict)):
+                raise RecordInputError(
+                    message=f"{location} with op '{op}' requires a single scalar value",
+                    error_code="INVALID_ANALYZE_FILTER_VALUE",
+                    fix_hint="Use a single number or date string for comparison filters.",
+                    details={"location": location, "op": op, "field": _field_ref_payload(field), "received_value": value},
+                )
+            if field.que_type == 8:
+                if _coerce_amount(value) is None:
+                    raise RecordInputError(
+                        message=f"{location} requires a numeric comparison value",
+                        error_code="INVALID_ANALYZE_FILTER_VALUE",
+                        fix_hint="Use numeric values with gt/gte/lt/lte on numeric fields.",
+                        details={"location": location, "field": _field_ref_payload(field), "received_value": value},
+                    )
+                return value
+            if field.que_type in DATE_QUE_TYPES:
+                self._validate_strict_date_filter_value(value, location=f"{location}.value")
+                return value
+            raise RecordInputError(
+                message=f"{location} with op '{op}' requires a numeric or date/time field",
+                error_code="INVALID_ANALYZE_FILTER_FIELD_TYPE",
+                fix_hint="Use gt/gte/lt/lte only on numeric or date/time fields.",
+                details={"location": location, "field": _field_ref_payload(field), "op": op},
+            )
+
+        if value is None:
+            raise RecordInputError(
+                message=f"{location} with op '{op}' requires value",
+                error_code="INVALID_ANALYZE_FILTER_VALUE",
+                fix_hint="Provide value for this filter, or use is_null / not_null.",
+                details={"location": location, "op": op, "field": _field_ref_payload(field)},
+            )
+
+        if op == "contains" and isinstance(value, (list, dict)):
+            raise RecordInputError(
+                message=f"{location} with op 'contains' requires a single text value",
+                error_code="INVALID_ANALYZE_FILTER_VALUE",
+                fix_hint="Use a single string for contains filters.",
+                details={"location": location, "field": _field_ref_payload(field), "received_value": value},
+            )
+
+        if field.que_type in DATE_QUE_TYPES and op in {"eq", "neq"}:
+            if isinstance(value, list):
+                raise RecordInputError(
+                    message=f"{location} with op '{op}' requires a single date value",
+                    error_code="INVALID_ANALYZE_FILTER_VALUE",
+                    fix_hint="Use a single date string for eq/neq on date fields.",
+                    details={"location": location, "field": _field_ref_payload(field), "received_value": value},
+                )
+            self._validate_strict_date_filter_value(value, location=f"{location}.value")
+        return value
+
+    def _validate_strict_date_filter_value(self, value: JSONValue, *, location: str) -> datetime:
+        text = _normalize_optional_text(value)
+        if text is None:
+            raise RecordInputError(
+                message=f"{location} requires a concrete date or datetime string",
+                error_code="INVALID_DATE_FILTER_VALUE",
+                fix_hint="Use a valid ISO-like date such as 2026-03-01 or 2026-03-01 00:00:00.",
+                details={"location": location, "received_value": value},
+            )
+        parsed = _parse_datetime_like(text)
+        if parsed is None:
+            raise RecordInputError(
+                message=f"{location} uses an invalid date value '{text}'",
+                error_code="INVALID_DATE_FILTER_VALUE",
+                fix_hint="Normalize relative time phrases into a real date range, and avoid impossible dates like 2026-02-29.",
+                details={"location": location, "received_value": value},
+            )
+        return parsed
+
+    def _compile_analyze_dimensions(self, index: FieldIndex, dimensions: list[JSONObject]) -> list[JSONObject]:
+        supported_buckets = {None, "day", "week", "month", "quarter", "year"}
+        compiled: list[JSONObject] = []
+        used_aliases: set[str] = set()
+        for idx, item in enumerate(dimensions):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_DIMENSION",
+                    fix_hint="Pass dimensions like {'field_id': 2, 'alias': '状态'}",
+                )
+            self._ensure_allowed_analyze_keys(
+                item,
+                location=f"dimensions[{idx}]",
+                allowed_keys={"field_id", "fieldId", "alias", "bucket"},
+                example="{'field_id': 2, 'alias': '状态', 'bucket': 'month'}",
+            )
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            field = self._resolve_field_by_id(field_id, index, location=f"dimensions[{idx}]")
+            bucket = _normalize_optional_text(item.get("bucket"))
+            if bucket not in supported_buckets:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] uses unsupported bucket '{bucket}'",
+                    error_code="UNSUPPORTED_TIME_BUCKET",
+                    fix_hint="Use one of day/week/month/quarter/year, or omit bucket.",
+                )
+            if bucket is not None and field.que_type not in DATE_QUE_TYPES:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] bucket requires a date/time field",
+                    error_code="INVALID_TIME_BUCKET_FIELD",
+                    fix_hint="Use bucket only on fields returned in suggested_time_fields by record_schema_get.",
+                    details={"field": _field_ref_payload(field), "bucket": bucket},
+                )
+            alias = _normalize_optional_text(item.get("alias")) or field.que_title
+            if alias in used_aliases:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] alias '{alias}' is duplicated",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use unique aliases across dimensions and metrics.",
+                )
+            used_aliases.add(alias)
+            compiled.append({"field": field, "alias": alias, "bucket": bucket})
+        return compiled
+
+    def _compile_analyze_metrics(self, index: FieldIndex, metrics: list[JSONObject]) -> list[JSONObject]:
+        requested_metrics = metrics or [{"op": "count", "alias": "记录数"}]
+        supported_ops = {"count", "sum", "avg", "min", "max", "distinct_count"}
+        compiled: list[JSONObject] = []
+        used_aliases: set[str] = set()
+        for idx, item in enumerate(requested_metrics):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"metrics[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_METRIC",
+                    fix_hint="Pass metrics like {'op': 'count', 'alias': '记录数'}",
+                )
+            self._ensure_allowed_analyze_keys(
+                item,
+                location=f"metrics[{idx}]",
+                allowed_keys={"op", "field_id", "fieldId", "alias"},
+                example="{'op': 'sum', 'field_id': 7, 'alias': '总金额'}",
+            )
+            op = _normalize_optional_text(item.get("op"))
+            if op not in supported_ops:
+                raise RecordInputError(
+                    message=f"metrics[{idx}] uses unsupported op '{op}'",
+                    error_code="UNSUPPORTED_ANALYZE_METRIC",
+                    fix_hint="Use one of count/sum/avg/min/max/distinct_count.",
+                )
+            field: FormField | None = None
+            if op != "count":
+                field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+                field = self._resolve_field_by_id(field_id, index, location=f"metrics[{idx}]")
+                if op in {"sum", "avg", "min", "max"} and field.que_type != 8:
+                    raise RecordInputError(
+                        message=f"metrics[{idx}] with op '{op}' requires a numeric field",
+                        error_code="INVALID_METRIC_FIELD_TYPE",
+                        fix_hint="Use sum/avg/min/max only on numeric fields returned by record_schema_get.",
+                        details={"location": f"metrics[{idx}]", "field": _field_ref_payload(field), "op": op},
+                    )
+            elif item.get("field_id", item.get("fieldId")) is not None:
+                raise RecordInputError(
+                    message=f"metrics[{idx}] with op 'count' must not include field_id",
+                    error_code="INVALID_ANALYZE_METRIC",
+                    fix_hint="Remove field_id from count metrics.",
+                    details={"location": f"metrics[{idx}]", "op": op},
+                )
+            alias = _normalize_optional_text(item.get("alias"))
+            if alias is None:
+                if op == "count":
+                    alias = "count"
+                elif field is not None:
+                    alias = f"{field.que_title}_{op}"
+                else:
+                    alias = op
+            if alias in used_aliases:
+                raise RecordInputError(
+                    message=f"metrics[{idx}] alias '{alias}' is duplicated",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use unique aliases across dimensions and metrics.",
+                )
+            used_aliases.add(alias)
+            compiled.append({"op": op, "field": field, "alias": alias})
+        return compiled
+
+    def _compile_analyze_filters(self, index: FieldIndex, filters: list[JSONObject]) -> list[JSONObject]:
+        supported_ops = {"eq", "neq", "in", "not_in", "gt", "gte", "lt", "lte", "between", "contains", "is_null", "not_null"}
+        compiled: list[JSONObject] = []
+        for idx, item in enumerate(filters):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"filters[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_FILTER",
+                    fix_hint="Pass filters like {'field_id': 2, 'op': 'eq', 'value': '进行中'}.",
+                )
+            self._ensure_allowed_analyze_keys(
+                item,
+                location=f"filters[{idx}]",
+                allowed_keys={"field_id", "fieldId", "op", "operator", "value", "values"},
+                example="{'field_id': 2, 'op': 'eq', 'value': '进行中'}",
+            )
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            op = _normalize_optional_text(item.get("op", item.get("operator"))) or "eq"
+            if op not in supported_ops:
+                raise RecordInputError(
+                    message=f"filters[{idx}] uses unsupported op '{op}'",
+                    error_code="UNSUPPORTED_ANALYZE_FILTER_OP",
+                    fix_hint="Use one of eq/neq/in/not_in/gt/gte/lt/lte/between/contains/is_null/not_null.",
+                )
+            field = self._resolve_field_by_id(field_id, index, location=f"filters[{idx}]")
+            normalized_value = self._validate_analyze_filter_value(
+                field=field,
+                op=op,
+                value=item.get("value", item.get("values")),
+                location=f"filters[{idx}]",
+            )
+            compiled.append({"field": field, "field_id": field_id, "op": op, "value": normalized_value})
+        return compiled
+
+    def _compile_analyze_sort(self, sort: list[JSONObject], dimensions: list[JSONObject], metrics: list[JSONObject]) -> list[JSONObject]:
+        dimension_aliases = {str(item["alias"]) for item in dimensions}
+        metric_aliases = {str(item["alias"]) for item in metrics}
+        compiled: list[JSONObject] = []
+        for idx, item in enumerate(sort):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"sort[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_SORT",
+                    fix_hint="Pass sort like {'by': '记录数', 'order': 'desc'}.",
+                )
+            self._ensure_allowed_analyze_keys(
+                item,
+                location=f"sort[{idx}]",
+                allowed_keys={"by", "order"},
+                example="{'by': '记录数', 'order': 'desc'}",
+            )
+            by = _normalize_optional_text(item.get("by"))
+            if by is None:
+                raise RecordInputError(
+                    message=f"sort[{idx}] requires by",
+                    error_code="MISSING_SORT_KEY",
+                    fix_hint="Use a dimension alias or metric alias in sort.by.",
+                )
+            order = (_normalize_optional_text(item.get("order")) or "asc").lower()
+            if order not in {"asc", "desc"}:
+                raise RecordInputError(
+                    message=f"sort[{idx}] uses unsupported order '{order}'",
+                    error_code="INVALID_SORT_ORDER",
+                    fix_hint="Use asc or desc.",
+                )
+            if by in dimension_aliases:
+                compiled.append({"by": by, "order": order, "kind": "dimension"})
+                continue
+            if by in metric_aliases:
+                compiled.append({"by": by, "order": order, "kind": "metric"})
+                continue
+            raise RecordInputError(
+                message=f"sort[{idx}] references unknown alias '{by}'",
+                error_code="UNKNOWN_ANALYZE_SORT_KEY",
+                fix_hint="Use a dimension alias or metric alias defined in the same record_analyze request.",
+            )
+        return compiled
+
+    def _execute_record_analyze(
+        self,
+        *,
+        profile: str,
+        session_profile,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        index: FieldIndex,
+        view_selection: ViewSelection | None,
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+        filters: list[JSONObject],
+        sort: list[JSONObject],
+        limit: int,
+        strict_full: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        started_at = time.perf_counter()
+        analysis_paging = _fixed_analysis_scan_policy()
+        page_size = int(analysis_paging["page_size"])
+        requested_pages = int(analysis_paging["requested_pages"])
+        scan_max_pages = int(analysis_paging["scan_max_pages"])
+        auto_expand_pages = bool(analysis_paging["auto_expand_pages"])
+        query_id = _query_id()
+        pages_to_scan = min(max(requested_pages, 1), max(scan_max_pages, 1))
+        current_page = 1
+        scanned_pages = 0
+        source_pages: list[int] = []
+        result_amount: int | None = None
+        has_more = False
+        dept_member_cache: dict[int, set[int]] = {}
+        local_filtering = bool(filters) or bool(view_selection is not None and view_selection.conditions)
+        group_stats: dict[tuple[tuple[str, object], ...], JSONObject] = {}
+        overall_metrics = self._initialize_metric_states(metrics)
+        matched_rows = 0
+        scan_control: JSONObject = {
+            "requested_pages": max(requested_pages, 1),
+            "scan_max_pages": max(scan_max_pages, 1),
+            "auto_expand_pages": auto_expand_pages,
+            "auto_expand_applied": False,
+            "auto_expand_target_pages": pages_to_scan,
+            "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+        }
+
+        while scanned_pages < pages_to_scan:
+            page = self._search_page(
+                context,
+                app_key=app_key,
+                page_num=current_page,
+                page_size=page_size,
+                query_key=None,
+                match_rules=[],
+                sorts=[],
+                search_que_ids=None,
+                list_type=DEFAULT_RECORD_LIST_TYPE,
+            )
+            scanned_pages += 1
+            source_pages.append(current_page)
+            items = page.get("list") if isinstance(page.get("list"), list) else []
+            if result_amount is None:
+                result_amount = _effective_total(page, page_size)
+                pages_to_scan, scan_control = _compute_scan_limit(
+                    requested_pages=requested_pages,
+                    scan_max_pages=scan_max_pages,
+                    auto_expand_pages=auto_expand_pages,
+                    page=page,
+                    page_size=page_size,
+                )
+            has_more = _page_has_more(page, current_page, page_size, len(items))
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                answers = item.get("answers")
+                answer_list = answers if isinstance(answers, list) else []
+                if not self._matches_view_selection(
+                    context,
+                    answer_list,
+                    view_selection=view_selection,
+                    dept_member_cache=dept_member_cache,
+                ):
+                    continue
+                if not self._matches_analyze_filters(answer_list, filters):
+                    continue
+                matched_rows += 1
+                self._apply_metric_states(overall_metrics, metrics, answer_list)
+                if not dimensions:
+                    continue
+                group_payload = self._build_analyze_group_payload(answer_list, dimensions)
+                group_key = self._analysis_group_key(group_payload)
+                bucket = group_stats.get(group_key)
+                if bucket is None:
+                    bucket = {
+                        "dimensions": group_payload,
+                        "metrics_state": self._initialize_metric_states(metrics),
+                    }
+                    group_stats[group_key] = bucket
+                bucket_metrics = cast(dict[str, JSONObject], bucket["metrics_state"])
+                self._apply_metric_states(bucket_metrics, metrics, answer_list)
+            if not has_more:
+                break
+            current_page += 1
+
+        metric_totals = self._render_metric_values(overall_metrics, metrics)
+        if dimensions:
+            all_rows = [
+                {
+                    "dimensions": cast(JSONObject, bucket["dimensions"]),
+                    "metrics": self._render_metric_values(cast(dict[str, JSONObject], bucket["metrics_state"]), metrics),
+                }
+                for bucket in group_stats.values()
+            ]
+            all_rows = self._sort_analyze_rows(all_rows, sort, dimensions, metrics)
+            rows_truncated = len(all_rows) > limit
+            limited_rows = all_rows[:limit]
+            rows = limited_rows
+            rows_returned = len(limited_rows)
+            group_count = len(all_rows)
+            statement_scope = "returned_groups_only" if rows_truncated else "full_population"
+        else:
+            rows_truncated = False
+            rows = [{"dimensions": {}, "metrics": metric_totals}]
+            rows_returned = 1
+            group_count = 1
+            statement_scope = "full_population"
+        raw_scan_complete = not has_more
+        completeness_status = "complete" if raw_scan_complete else "incomplete"
+        reason_code = "LOCAL_VIEW_FILTERING" if local_filtering and raw_scan_complete else ("SOURCE_EXHAUSTED" if raw_scan_complete else "SCAN_LIMIT_HIT")
+        totals = {
+            "scanned_count": matched_rows,
+            "group_count": group_count,
+            "metric_totals": metric_totals,
+        }
+        data: JSONObject = {
+            "query": {
+                "app_key": app_key,
+                "dimensions": [
+                    {
+                        "field_id": cast(FormField, item["field"]).que_id,
+                        "title": cast(FormField, item["field"]).que_title,
+                        "alias": item["alias"],
+                        "bucket": item["bucket"],
+                    }
+                    for item in dimensions
+                ],
+                "metrics": [
+                    {
+                        "op": item["op"],
+                        "field_id": cast(FormField | None, item["field"]).que_id if item["field"] is not None else None,
+                        "title": cast(FormField | None, item["field"]).que_title if item["field"] is not None else None,
+                        "alias": item["alias"],
+                    }
+                    for item in metrics
+                ],
+                "filters": [
+                    {
+                        "field_id": cast(FormField, item["field"]).que_id,
+                        "title": cast(FormField, item["field"]).que_title,
+                        "op": item["op"],
+                        "value": item.get("value"),
+                    }
+                    for item in filters
+                ],
+                "applied_sort": [{"by": item["by"], "order": item["order"]} for item in sort],
+                "view": _view_selection_payload(view_selection),
+            },
+            "rows": rows,
+            "totals": totals,
+            "completeness": {
+                "status": completeness_status,
+                "reason_code": reason_code,
+                "local_filtering_applied": local_filtering,
+                "safe_for_final_conclusion": completeness_status == "complete",
+            },
+            "presentation": {
+                "row_limit": limit,
+                "rows_returned": rows_returned,
+                "rows_truncated": rows_truncated,
+                "statement_scope": statement_scope,
+            },
+            "warnings": self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated),
+        }
+        response: JSONObject = {
+            "profile": profile,
+            "ws_id": session_profile.selected_ws_id,
+            "ok": True,
+            "status": "success" if raw_scan_complete else "partial",
+            "query_id": query_id,
+            "request_route": self._request_route_payload(context),
+            "data": data,
+        }
+        if strict_full and not raw_scan_complete:
+            response["ok"] = False
+            response["status"] = "error"
+            response["error"] = {
+                "code": "INCOMPLETE_SCAN",
+                "message": "record_analyze could not complete the scan within the fixed internal analysis budget.",
+                "fix_hint": "Narrow the scope with view/filter constraints, or retry after reducing the dataset size.",
+            }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {
+                "elapsed_ms": int((time.perf_counter() - started_at) * 1000),
+                "backend_total_hint": scan_control.get("backend_total_count", result_amount),
+                "backend_page_amount": scan_control.get("backend_page_amount"),
+                "source_pages": source_pages,
+                "raw_scan_complete": raw_scan_complete,
+                "scan_control": scan_control,
+            }
+        return response
+
+    def _build_analyze_group_payload(self, answer_list: list[JSONValue], dimensions: list[JSONObject]) -> JSONObject:
+        if not dimensions:
+            return {}
+        payload: JSONObject = {}
+        for item in dimensions:
+            field = cast(FormField, item["field"])
+            alias = cast(str, item["alias"])
+            bucket = cast(str | None, item["bucket"])
+            value = _extract_field_value(answer_list, field)
+            if bucket is not None:
+                value = _to_time_bucket(value, bucket)
+            payload[alias] = value
+        return payload
+
+    def _initialize_metric_states(self, metrics: list[JSONObject]) -> dict[str, JSONObject]:
+        states: dict[str, JSONObject] = {}
+        for item in metrics:
+            states[str(item["alias"])] = {
+                "count": 0,
+                "sum": 0.0,
+                "min": None,
+                "max": None,
+                "seen": set(),
             }
+        return states
 
-        return self._run_record_tool(profile, runner)
+    def _analysis_group_key(self, payload: JSONObject) -> tuple[tuple[str, object], ...]:
+        return tuple((key, self._freeze_group_key_value(value)) for key, value in payload.items())
+
+    def _freeze_group_key_value(self, value: JSONValue) -> object:
+        if isinstance(value, dict):
+            return tuple((key, self._freeze_group_key_value(item)) for key, item in sorted(value.items()))
+        if isinstance(value, list):
+            return tuple(self._freeze_group_key_value(item) for item in value)
+        return value
+
+    def _apply_metric_states(self, states: dict[str, JSONObject], metrics: list[JSONObject], answer_list: list[JSONValue]) -> None:
+        for item in metrics:
+            alias = cast(str, item["alias"])
+            op = cast(str, item["op"])
+            field = cast(FormField | None, item["field"])
+            state = states[alias]
+            if op == "count":
+                state["count"] = int(state["count"]) + 1
+                continue
+            value = _extract_field_value(answer_list, field)
+            if op == "distinct_count":
+                for entry in _flatten_distinct_values(value):
+                    cast(set[str], state["seen"]).add(entry)
+                continue
+            amount = _coerce_amount(value)
+            if amount is None:
+                continue
+            state["count"] = int(state["count"]) + 1
+            state["sum"] = float(state["sum"]) + amount
+            state["min"] = amount if state["min"] is None else min(float(state["min"]), amount)
+            state["max"] = amount if state["max"] is None else max(float(state["max"]), amount)
+
+    def _render_metric_values(self, states: dict[str, JSONObject], metrics: list[JSONObject]) -> JSONObject:
+        rendered: JSONObject = {}
+        for item in metrics:
+            alias = cast(str, item["alias"])
+            op = cast(str, item["op"])
+            state = states[alias]
+            count = int(state["count"] or 0)
+            amount_sum = float(state["sum"] or 0.0)
+            if op == "count":
+                rendered[alias] = count
+            elif op == "sum":
+                rendered[alias] = amount_sum
+            elif op == "avg":
+                rendered[alias] = (amount_sum / count) if count else None
+            elif op == "min":
+                rendered[alias] = state["min"]
+            elif op == "max":
+                rendered[alias] = state["max"]
+            elif op == "distinct_count":
+                rendered[alias] = len(cast(set[str], state["seen"]))
+        return rendered
+
+    def _matches_analyze_filters(self, answer_list: list[JSONValue], filters: list[JSONObject]) -> bool:
+        for item in filters:
+            field = cast(FormField, item["field"])
+            if not _match_analyze_filter(_extract_field_value(answer_list, field), cast(str, item["op"]), item.get("value")):
+                return False
+        return True
+
+    def _sort_analyze_rows(
+        self,
+        rows: list[JSONObject],
+        sort: list[JSONObject],
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+    ) -> list[JSONObject]:
+        if not rows or not sort:
+            if dimensions and any(item.get("bucket") for item in dimensions):
+                return sorted(rows, key=lambda item: json.dumps(item.get("dimensions", {}), ensure_ascii=False, sort_keys=True))
+            return rows
+        sorted_rows = list(rows)
+        for sort_item in reversed(sort):
+            by = cast(str, sort_item["by"])
+            reverse = cast(str, sort_item["order"]) == "desc"
+            kind = cast(str, sort_item["kind"])
+            sorted_rows.sort(
+                key=lambda item: _sortable_value(
+                    cast(JSONObject, item["metrics" if kind == "metric" else "dimensions"]).get(by)
+                ),
+                reverse=reverse,
+            )
+        return sorted_rows
+
+    def _build_analyze_warnings(self, *, local_filtering: bool, rows_truncated: bool) -> list[JSONObject]:
+        warnings: list[JSONObject] = []
+        if local_filtering:
+            warnings.append(
+                {
+                    "code": "LOCAL_FILTERING_APPLIED",
+                    "message": "Current analysis applies local filtering after scanning source pages.",
+                }
+            )
+        if rows_truncated:
+            warnings.append(
+                {
+                    "code": "ROWS_TRUNCATED",
+                    "message": "Result rows were truncated by limit; totals remain based on the full analyzed result set.",
+                }
+            )
+        return warnings
 
     def record_write_plan(
         self,
@@ -558,7 +1342,7 @@ class RecordTools(ToolBase):
                 blockers.append("payload writes readonly or system-managed fields")
             if question_relations:
                 validation["warnings"].append("form contains questionRelations; linked visibility and runtime required rules may differ at submit time.")
-            actions = ["Use record_field_resolve when field titles are ambiguous."]
+            actions = ["Use record_schema_get when field titles or field ids are ambiguous."]
             if support_matrix["restricted"]:
                 actions.append("Review write_format.required_presteps for restricted fields before submit.")
             if invalid_fields:
@@ -606,6 +1390,7 @@ class RecordTools(ToolBase):
         page_size: int,
         requested_pages: int,
         scan_max_pages: int,
+        auto_expand_pages: bool = False,
         query_key: str | None,
         filters: list[JSONObject],
         sorts: list[JSONObject],
@@ -622,6 +1407,24 @@ class RecordTools(ToolBase):
         view_name: str | None = None,
     ) -> JSONObject:
         resolved_mode = _resolve_query_mode(query_mode, apply_id=apply_id, amount_column=amount_column, time_range=time_range, stat_policy=stat_policy)
+        if resolved_mode == "summary":
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message="query_mode='summary' is not supported",
+                    details={
+                        "error_code": "UNSUPPORTED_QUERY_MODE",
+                        "allowed_modes": ["auto", "list", "record"],
+                        "fix_hint": "Use record_schema_get followed by record_analyze for any statistical analysis.",
+                    },
+                )
+            )
+        if resolved_mode == "list":
+            list_paging = _fixed_list_scan_policy()
+            page_size = int(list_paging["page_size"])
+            requested_pages = int(list_paging["requested_pages"])
+            scan_max_pages = int(list_paging["scan_max_pages"])
+            auto_expand_pages = bool(list_paging["auto_expand_pages"])
         if resolved_mode == "record":
             return self._record_query_record(
                 profile=profile,
@@ -632,259 +1435,25 @@ class RecordTools(ToolBase):
                 output_profile=output_profile,
                 list_type=list_type,
             )
-        if resolved_mode == "summary":
-            return self._record_query_summary(
-                profile=profile,
-                app_key=app_key,
-                page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
-                query_key=query_key,
-                filters=filters,
-                sorts=sorts,
-                max_rows=max_rows,
-                max_columns=max_columns,
-                select_columns=select_columns,
-                amount_column=amount_column,
-                time_range=time_range,
-                stat_policy=stat_policy,
-                strict_full=strict_full,
-                output_profile=output_profile,
-                list_type=list_type,
-                view_key=view_key,
-                view_name=view_name,
-            )
         return self._record_query_list(
             profile=profile,
-            app_key=app_key,
-            page_num=page_num,
-            page_size=page_size,
-            requested_pages=requested_pages,
-            scan_max_pages=scan_max_pages,
-            query_key=query_key,
-            filters=filters,
-            sorts=sorts,
-            max_rows=max_rows,
-            max_columns=max_columns,
-            select_columns=select_columns,
-            time_range=time_range,
-            output_profile=output_profile,
-            list_type=list_type,
-            view_key=view_key,
-            view_name=view_name,
-        )
-
-    def record_aggregate(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        group_by: list[str | int],
-        amount_column: str | int | None,
-        metrics: list[str],
-        page_num: int,
-        page_size: int,
-        requested_pages: int,
-        scan_max_pages: int,
-        query_key: str | None,
-        filters: list[JSONObject],
-        sorts: list[JSONObject],
-        time_range: JSONObject,
-        time_bucket: str | None,
-        max_groups: int,
-        strict_full: bool,
-        output_profile: str,
-        list_type: int,
-        view_key: str | None = None,
-        view_name: str | None = None,
-    ) -> JSONObject:
-        if not app_key:
-            raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        if max_groups <= 0:
-            raise_tool_error(QingflowApiError.config_error("max_groups must be positive"))
-
-        def runner(session_profile, context):
-            index = self._get_field_index(profile, context, app_key, force_refresh=False)
-            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            dept_member_cache: dict[int, set[int]] = {}
-            group_fields = [self._resolve_field_selector(item, index, location="group_by") for item in group_by]
-            amount_field = self._resolve_field_selector(amount_column, index, location="amount_column") if amount_column is not None else None
-            time_field = self._resolve_time_range_column(time_range, index)
-            match_rules = self._resolve_match_rules(context, filters, index)
-            sort_rules = self._resolve_sorts(sorts, index)
-            match_rules = self._append_time_range_filter(match_rules, time_range, time_field)
-            metric_names = _normalize_metrics(metrics, include_sum=amount_field is not None)
-            query_id = _query_id()
-            pages_to_scan = min(max(requested_pages, 1), max(scan_max_pages, 1))
-            current_page = max(page_num, 1)
-            scanned_pages = 0
-            scanned_records = 0
-            source_pages: list[int] = []
-            result_amount: int | None = None
-            has_more = False
-            group_stats: dict[str, JSONObject] = {}
-            total_amount = 0.0
-            while scanned_pages < pages_to_scan:
-                page = self._search_page(
-                    context,
-                    app_key=app_key,
-                    page_num=current_page,
-                    page_size=page_size,
-                    query_key=query_key,
-                    match_rules=match_rules,
-                    sorts=sort_rules,
-                    search_que_ids=None,
-                    list_type=list_type,
-                )
-                scanned_pages += 1
-                source_pages.append(current_page)
-                rows = page.get("list")
-                items = rows if isinstance(rows, list) else []
-                if result_amount is None:
-                    result_amount = _effective_total(page, page_size)
-                has_more = _page_has_more(page, current_page, page_size, len(items))
-                for item in items:
-                    if not isinstance(item, dict):
-                        continue
-                    answers = item.get("answers")
-                    answer_list = answers if isinstance(answers, list) else []
-                    if not self._matches_view_selection(
-                        context,
-                        answer_list,
-                        view_selection=view_selection,
-                        dept_member_cache=dept_member_cache,
-                    ):
-                        continue
-                    scanned_records += 1
-                    group_payload = {
-                        field.que_title: _extract_field_value(answer_list, field)
-                        for field in group_fields
-                    }
-                    if time_bucket and time_field is not None:
-                        group_payload["time_bucket"] = _to_time_bucket(_extract_field_value(answer_list, time_field), time_bucket)
-                    group_key = json.dumps(group_payload, ensure_ascii=False, sort_keys=True)
-                    bucket = group_stats.get(group_key)
-                    if bucket is None:
-                        bucket = {"group": group_payload, "count": 0, "amount_total": None, "metrics": {}}
-                        group_stats[group_key] = bucket
-                    bucket["count"] = int(bucket["count"]) + 1
-                    amount_value = _coerce_amount(_extract_field_value(answer_list, amount_field)) if amount_field is not None else None
-                    if amount_value is not None:
-                        total_amount += amount_value
-                        bucket["amount_total"] = float(bucket.get("amount_total") or 0.0) + amount_value
-                    metrics_payload = bucket["metrics"] if isinstance(bucket.get("metrics"), dict) else {}
-                    for metric in metric_names:
-                        current_metric = metrics_payload.get(metric)
-                        metric_state = current_metric if isinstance(current_metric, dict) else {"count": 0, "sum": 0.0, "min": None, "max": None}
-                        metric_state["count"] = int(metric_state["count"]) + 1
-                        if amount_value is not None:
-                            metric_state["sum"] = float(metric_state["sum"]) + amount_value
-                            metric_state["min"] = amount_value if metric_state["min"] is None else min(float(metric_state["min"]), amount_value)
-                            metric_state["max"] = amount_value if metric_state["max"] is None else max(float(metric_state["max"]), amount_value)
-                        metrics_payload[metric] = metric_state
-                    bucket["metrics"] = metrics_payload
-                    if len(group_stats) >= max_groups:
-                        break
-                if len(group_stats) >= max_groups or not has_more:
-                    break
-                current_page += 1
-
-            groups = []
-            for bucket in group_stats.values():
-                metrics_payload = bucket["metrics"] if isinstance(bucket.get("metrics"), dict) else {}
-                rendered_metrics: JSONObject = {}
-                for metric_name, metric_state in metrics_payload.items():
-                    if not isinstance(metric_state, dict):
-                        continue
-                    count = int(metric_state.get("count", 0) or 0)
-                    amount_sum = float(metric_state.get("sum", 0.0) or 0.0)
-                    metric_result: JSONObject = {}
-                    if metric_name == "count":
-                        metric_result["value"] = count
-                    else:
-                        if metric_name == "sum":
-                            metric_result["value"] = amount_sum
-                        elif metric_name == "avg":
-                            metric_result["value"] = (amount_sum / count) if count else None
-                        elif metric_name == "min":
-                            metric_result["value"] = metric_state.get("min")
-                        elif metric_name == "max":
-                            metric_result["value"] = metric_state.get("max")
-                    rendered_metrics[metric_name] = metric_result
-                groups.append(
-                    {
-                        "group": bucket["group"],
-                        "count": bucket["count"],
-                        "count_ratio": (int(bucket["count"]) / scanned_records) if scanned_records else 0,
-                        "amount_total": None if amount_field is None else _coerce_amount(bucket.get("amount_total")),
-                        "amount_ratio": None,
-                        "metrics": rendered_metrics,
-                    }
-                )
-            groups.sort(key=lambda item: int(item["count"]), reverse=True)
-            if amount_field is not None and total_amount > 0:
-                for item in groups:
-                    amount_total = _coerce_amount(item.get("amount_total"))
-                    item["amount_ratio"] = (amount_total / total_amount) if amount_total is not None else None
-            effective_result_amount = scanned_records if view_selection is not None else (result_amount or scanned_records)
-            completeness = _build_completeness(
-                result_amount=effective_result_amount,
-                returned_items=len(groups),
-                fetched_pages=scanned_pages,
-                requested_pages=pages_to_scan,
-                has_more=has_more,
-                next_page_token=None,
-                is_complete=not has_more and len(groups) < max_groups,
-                omitted_items=max(0, effective_result_amount - len(groups)),
-                extra={
-                    "raw_scan_complete": not has_more,
-                    "scan_limit_hit": has_more,
-                    "scanned_pages": scanned_pages,
-                    "scan_limit": pages_to_scan,
-                    "output_page_complete": len(groups) < max_groups,
-                    "raw_next_page_token": None,
-                    "output_next_page_token": None,
-                    "stop_reason": "source_exhausted" if not has_more else "scan_limit",
-                },
-            )
-            evidence = {
-                "query_id": query_id,
-                "app_key": app_key,
-                "filters": _echo_filters(match_rules),
-                "selected_columns": [field.que_title for field in group_fields],
-                "time_range": time_range or None,
-                "source_pages": source_pages,
-                "view": _view_selection_payload(view_selection),
-            }
-            if strict_full and not bool(completeness.get("raw_scan_complete")):
-                self._raise_need_more_data(completeness, evidence, "Aggregate result is incomplete; increase requested_pages or scan_max_pages.")
-            response: JSONObject = {
-                "profile": profile,
-                "ws_id": session_profile.selected_ws_id,
-                "ok": True,
-                "request_route": self._request_route_payload(context),
-                "data": {
-                    "app_key": app_key,
-                    "view": _view_selection_payload(view_selection),
-                    "summary": {
-                        "total_count": scanned_records,
-                        "total_amount": total_amount if amount_field is not None else None,
-                    },
-                    "groups": groups,
-                    "completeness": completeness,
-                },
-            }
-            if output_profile == "verbose":
-                response["completeness"] = completeness
-                response["evidence"] = evidence
-                response["resolved_mappings"] = {
-                    "group_by": [_field_mapping_entry("group_by", field, requested=field.que_title) for field in group_fields],
-                    "amount_column": _field_mapping_entry("amount", amount_field, requested=amount_field.que_title) if amount_field is not None else None,
-                }
-            return response
-
-        return self._run_record_tool(profile, runner)
+            app_key=app_key,
+            page_num=page_num,
+            page_size=page_size,
+            requested_pages=requested_pages,
+            scan_max_pages=scan_max_pages,
+            query_key=query_key,
+            filters=filters,
+            sorts=sorts,
+            max_rows=max_rows,
+            max_columns=max_columns,
+            select_columns=select_columns,
+            time_range=time_range,
+            output_profile=output_profile,
+            list_type=list_type,
+            view_key=view_key,
+            view_name=view_name,
+        )
 
     def record_create(
         self,
@@ -1391,6 +1960,18 @@ class RecordTools(ToolBase):
                     "view": _view_selection_payload(view_selection),
                     "list": {
                         "rows": rows,
+                        "row_cap_hit": _list_row_cap_hit(returned_items=len(rows), row_cap=max_rows),
+                        "sample_only": _list_sample_only(
+                            returned_items=len(rows),
+                            row_cap=max_rows,
+                            result_amount=effective_result_amount,
+                        ),
+                        "safe_for_final_conclusion": False,
+                        "analysis_warning": _list_sample_warning(
+                            returned_items=len(rows),
+                            row_cap=max_rows,
+                            result_amount=effective_result_amount,
+                        ),
                         "pagination": {
                             "page_num": page_num,
                             "page_size": page_size,
@@ -1421,187 +2002,6 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
-    def _record_query_summary(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        page_num: int,
-        page_size: int,
-        requested_pages: int,
-        scan_max_pages: int,
-        query_key: str | None,
-        filters: list[JSONObject],
-        sorts: list[JSONObject],
-        max_rows: int,
-        max_columns: int | None,
-        select_columns: list[str | int],
-        amount_column: str | int | None,
-        time_range: JSONObject,
-        stat_policy: JSONObject,
-        strict_full: bool,
-        output_profile: str,
-        list_type: int,
-        view_key: str | None = None,
-        view_name: str | None = None,
-    ) -> JSONObject:
-        if not app_key:
-            raise_tool_error(QingflowApiError.config_error("app_key is required"))
-
-        def runner(session_profile, context):
-            index = self._get_field_index(profile, context, app_key, force_refresh=False)
-            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            dept_member_cache: dict[int, set[int]] = {}
-            amount_field = self._resolve_field_selector(amount_column, index, location="amount_column") if amount_column is not None else None
-            time_field = self._resolve_time_range_column(time_range, index)
-            resolved_column_cap = _bounded_column_limit(
-                max_columns,
-                default_limit=MAX_SUMMARY_PREVIEW_COLUMN_LIMIT,
-                hard_limit=MAX_SUMMARY_PREVIEW_COLUMN_LIMIT,
-            )
-            preview_fields = self._resolve_summary_preview_fields(select_columns, index, amount_field, time_field, max_columns=max_columns)
-            match_rules = self._resolve_match_rules(context, filters, index)
-            sort_rules = self._resolve_sorts(sorts, index)
-            match_rules = self._append_time_range_filter(match_rules, time_range, time_field)
-            include_negative = bool(stat_policy.get("include_negative", True))
-            include_null = bool(stat_policy.get("include_null", False))
-            scan_limit = min(max(requested_pages, 1), max(scan_max_pages, 1))
-            current_page = max(page_num, 1)
-            scanned_pages = 0
-            scanned_records = 0
-            result_amount: int | None = None
-            has_more = False
-            source_pages: list[int] = []
-            preview_rows: list[JSONObject] = []
-            total_amount = 0.0
-            missing_count = 0
-            by_day: dict[str, JSONObject] = {}
-            while scanned_pages < scan_limit:
-                page = self._search_page(
-                    context,
-                    app_key=app_key,
-                    page_num=current_page,
-                    page_size=page_size,
-                    query_key=query_key,
-                    match_rules=match_rules,
-                    sorts=sort_rules,
-                    search_que_ids=None,
-                    list_type=list_type,
-                )
-                scanned_pages += 1
-                source_pages.append(current_page)
-                page_rows = page.get("list")
-                items = page_rows if isinstance(page_rows, list) else []
-                if result_amount is None:
-                    result_amount = _effective_total(page, page_size)
-                has_more = _page_has_more(page, current_page, page_size, len(items))
-                for item in items:
-                    if not isinstance(item, dict):
-                        continue
-                    answers = item.get("answers")
-                    answer_list = answers if isinstance(answers, list) else []
-                    if not self._matches_view_selection(
-                        context,
-                        answer_list,
-                        view_selection=view_selection,
-                        dept_member_cache=dept_member_cache,
-                    ):
-                        continue
-                    scanned_records += 1
-                    if len(preview_rows) < max_rows:
-                        apply_id = _coerce_count(item.get("applyId")) or _coerce_count(item.get("id"))
-                        preview_rows.append(_build_flat_row(answer_list, preview_fields, apply_id=apply_id))
-                    amount_value = _coerce_amount(_extract_field_value(answer_list, amount_field)) if amount_field is not None else None
-                    if amount_field is not None:
-                        if amount_value is None:
-                            if not include_null:
-                                missing_count += 1
-                        elif include_negative or amount_value >= 0:
-                            total_amount += amount_value
-                    day_key = _to_time_bucket(_extract_field_value(answer_list, time_field), "day") if time_field is not None else "all"
-                    bucket = by_day.get(day_key)
-                    if bucket is None:
-                        bucket = {"day": day_key, "count": 0, "amount_total": 0.0 if amount_field is not None else None}
-                        by_day[day_key] = bucket
-                    bucket["count"] = int(bucket["count"]) + 1
-                    if amount_field is not None and amount_value is not None and (include_negative or amount_value >= 0):
-                        bucket["amount_total"] = float(bucket.get("amount_total") or 0.0) + amount_value
-                if not has_more:
-                    break
-                current_page += 1
-            raw_scan_complete = not has_more
-            effective_result_amount = scanned_records if view_selection is not None else max(result_amount or 0, scanned_records)
-            completeness = _build_completeness(
-                result_amount=effective_result_amount,
-                returned_items=len(preview_rows),
-                fetched_pages=scanned_pages,
-                requested_pages=scan_limit,
-                has_more=has_more,
-                next_page_token=None,
-                is_complete=raw_scan_complete and len(preview_rows) < max_rows,
-                omitted_items=max(0, effective_result_amount - len(preview_rows)),
-                extra={
-                    "raw_scan_complete": raw_scan_complete,
-                    "scan_limit_hit": has_more,
-                    "scanned_pages": scanned_pages,
-                    "scan_limit": scan_limit,
-                    "output_page_complete": len(preview_rows) < max_rows,
-                    "raw_next_page_token": None,
-                    "output_next_page_token": None,
-                    "stop_reason": "source_exhausted" if raw_scan_complete else "scan_limit",
-                },
-            )
-            evidence = {
-                "query_id": _query_id(),
-                "app_key": app_key,
-                "filters": _echo_filters(match_rules),
-                "selected_columns": [field.que_title for field in preview_fields],
-                "time_range": time_range or None,
-                "source_pages": source_pages,
-                "view": _view_selection_payload(view_selection),
-            }
-            if strict_full and not raw_scan_complete:
-                self._raise_need_more_data(completeness, evidence, "Summary is incomplete; increase requested_pages or scan_max_pages.")
-            response: JSONObject = {
-                "profile": profile,
-                "ws_id": session_profile.selected_ws_id,
-                "ok": True,
-                "request_route": self._request_route_payload(context),
-                "data": {
-                    "mode": "summary",
-                    "source_tool": "record_search",
-                    "view": _view_selection_payload(view_selection),
-                    "summary": {
-                        "summary": {
-                            "total_count": scanned_records,
-                            "total_amount": total_amount if amount_field is not None else None,
-                            "by_day": sorted(by_day.values(), key=lambda item: str(item.get("day"))),
-                            "missing_count": missing_count,
-                        },
-                        "rows": preview_rows,
-                        "completeness": completeness,
-                        "applied_limits": {
-                            "row_cap": max_rows,
-                            "column_cap": resolved_column_cap,
-                            "selected_columns": [field.que_title for field in preview_fields],
-                        },
-                    },
-                },
-                "output_profile": output_profile,
-                "next_page_token": None,
-            }
-            if output_profile == "verbose":
-                response["completeness"] = completeness
-                response["evidence"] = evidence
-                response["resolved_mappings"] = {
-                    "select_columns": [_field_mapping_entry("row", field, requested=field.que_title) for field in preview_fields],
-                    "amount_column": _field_mapping_entry("amount", amount_field, requested=amount_field.que_title) if amount_field is not None else None,
-                    "time_range": _field_mapping_entry("time", time_field, requested=time_field.que_title) if time_field is not None else None,
-                }
-            return response
-
-        return self._run_record_tool(profile, runner)
-
     def _get_form_schema(self, profile: str, context, app_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
         cache_key = (profile, app_key)
         if not force_refresh and cache_key in self._form_cache:
@@ -1721,6 +2121,60 @@ class RecordTools(ToolBase):
                 return True
         return False
 
+    def _build_analysis_probe(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        arguments: JSONObject,
+        view_selection: ViewSelection | None,
+    ) -> JSONObject:
+        routed_mode = _resolve_query_mode(
+            str(arguments.get("query_mode", "auto")),
+            apply_id=_coerce_count(arguments.get("apply_id")),
+            amount_column=arguments.get("amount_column"),
+            time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
+            stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
+        )
+        fixed_policy = _fixed_analysis_scan_policy() if routed_mode == "summary" else _fixed_list_scan_policy()
+        page_size = int(fixed_policy["page_size"])
+        query_key = _normalize_optional_text(arguments.get("query_key"))
+        filters = _as_object_list(arguments.get("filters"))
+        sorts = _as_object_list(arguments.get("sorts"))
+        app_form = self._get_field_index(profile, context, app_key, force_refresh=False)
+        time_range = cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {})
+        match_rules = self._resolve_match_rules(context, filters, app_form)
+        sort_rules = self._resolve_sorts(sorts, app_form)
+        time_field = self._resolve_time_range_column(time_range, app_form)
+        match_rules = self._append_time_range_filter(match_rules, time_range, time_field)
+        probe_page = self._search_page(
+            context,
+            app_key=app_key,
+            page_num=max(_coerce_count(arguments.get("page_num")) or 1, 1),
+            page_size=page_size,
+            query_key=query_key,
+            match_rules=match_rules,
+            sorts=sort_rules,
+            search_que_ids=None,
+            list_type=_coerce_count(arguments.get("list_type")) or DEFAULT_RECORD_LIST_TYPE,
+        )
+        backend_total_count = _effective_total(probe_page, page_size)
+        page_amount = _coerce_count(probe_page.get("pageAmount"))
+        estimated_full_scan_pages = page_amount
+        if estimated_full_scan_pages is None and backend_total_count > 0:
+            estimated_full_scan_pages = (backend_total_count + page_size - 1) // page_size
+        current_budget = min(int(fixed_policy["requested_pages"]), int(fixed_policy["scan_max_pages"]))
+        return {
+            "page_size": page_size,
+            "backend_total_count": backend_total_count,
+            "backend_page_amount": page_amount,
+            "estimated_full_scan_pages": estimated_full_scan_pages,
+            "current_scan_budget": current_budget,
+            "would_exceed_current_budget": bool(estimated_full_scan_pages is not None and estimated_full_scan_pages > current_budget),
+            "local_filtering": bool(view_selection.conditions) if view_selection is not None else False,
+        }
+
     def _search_page(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -2121,7 +2575,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} references unknown queId '{requested}'",
                 error_code="FIELD_NOT_FOUND",
-                fix_hint="Use record_field_resolve to confirm the exact field id.",
+                fix_hint="Use record_schema_get to confirm the exact field_id.",
                 details={"location": location, "requested": requested, "requested_key": requested_key},
             )
         matches = index.by_title.get(requested_key, [])
@@ -2131,7 +2585,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} field '{requested}' is ambiguous",
                 error_code="AMBIGUOUS_FIELD",
-                fix_hint="Use numeric queId, or resolve the field first with record_field_resolve.",
+                fix_hint="Use numeric queId, or inspect record_schema_get output to disambiguate the field.",
                 details={
                     "location": location,
                     "requested": requested,
@@ -2147,7 +2601,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} field '{requested}' is ambiguous",
                 error_code="AMBIGUOUS_FIELD",
-                fix_hint="Use a more specific field title, or run record_field_resolve to inspect the alias candidates.",
+                fix_hint="Use a more specific field title, or inspect record_schema_get aliases to disambiguate the field.",
                 details={
                     "location": location,
                     "requested": requested,
@@ -2159,7 +2613,7 @@ class RecordTools(ToolBase):
         raise RecordInputError(
             message=f"{location} cannot resolve field '{requested}'",
             error_code="FIELD_NOT_FOUND",
-            fix_hint="Use record_field_resolve to confirm the exact field title.",
+            fix_hint="Use record_schema_get to confirm the exact field title or field_id.",
             details={
                 "location": location,
                 "requested": requested,
@@ -2536,56 +2990,6 @@ class RecordTools(ToolBase):
                 "reason": error.message,
             }
 
-    def _resolve_plan_candidate(self, candidate: JSONObject, index: FieldIndex) -> JSONObject:
-        requested = str(candidate.get("requested", "")).strip()
-        role = str(candidate.get("role", "field"))
-        try:
-            field = self._resolve_field_selector(requested, index, location=role)
-            return {
-                "role": role,
-                "requested": requested,
-                "resolved": True,
-                "que_id": field.que_id,
-                "que_title": field.que_title,
-                "que_type": field.que_type,
-                "reason": None,
-            }
-        except RecordInputError as error:
-            return {
-                "role": role,
-                "requested": requested,
-                "resolved": False,
-                "que_id": None,
-                "que_title": None,
-                "que_type": None,
-                "reason": error.message,
-            }
-
-    def _validate_plan_arguments(self, tool: str, arguments: JSONObject) -> JSONObject:
-        missing_required: list[str] = []
-        warnings: list[str] = []
-        if tool in {"record_query", "record_aggregate"} and not arguments.get("app_key"):
-            missing_required.append("app_key")
-        if tool == "record_get":
-            if not arguments.get("app_key"):
-                missing_required.append("app_key")
-            if not arguments.get("apply_id"):
-                missing_required.append("apply_id")
-            if not arguments.get("select_columns"):
-                missing_required.append("select_columns")
-        query_mode = _resolve_query_mode(
-            str(arguments.get("query_mode", "auto")),
-            apply_id=_coerce_count(arguments.get("apply_id")),
-            amount_column=arguments.get("amount_column"),
-            time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
-            stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
-        ) if tool == "record_query" else None
-        if tool == "record_query" and query_mode in {"list", "record"} and not arguments.get("select_columns"):
-            missing_required.append("select_columns")
-        if tool == "record_query" and query_mode == "summary" and not arguments.get("amount_column") and not arguments.get("time_range"):
-            warnings.append("summary mode without amount_column or time_range only returns row counts")
-        return {"valid": not missing_required, "missing_required": missing_required, "warnings": warnings}
-
     def _validate_app_and_record(self, app_key: str, apply_id: int | str) -> int:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -2910,143 +3314,44 @@ def _extract_question_options(question: JSONObject) -> list[str]:
     return values
 
 
-def _normalize_plan_arguments(tool: str, arguments: JSONObject) -> JSONObject:
-    normalized = cast(JSONObject, _parse_json_like(arguments))
-    alias_map = {
-        "appKey": "app_key",
-        "applyId": "apply_id",
-        "queryMode": "query_mode",
-        "pageNum": "page_num",
-        "pageSize": "page_size",
-        "requestedPages": "requested_pages",
-        "scanMaxPages": "scan_max_pages",
-        "queryKey": "query_key",
-        "maxRows": "max_rows",
-        "maxColumns": "max_columns",
-        "selectColumns": "select_columns",
-        "amountColumn": "amount_column",
-        "timeRange": "time_range",
-        "strictFull": "strict_full",
-        "outputProfile": "output_profile",
-        "listType": "list_type",
-        "viewKey": "view_key",
-        "viewName": "view_name",
-        "groupBy": "group_by",
-        "timeBucket": "time_bucket",
-        "maxGroups": "max_groups",
-        "forceRefreshForm": "force_refresh_form",
-    }
-    result = dict(normalized)
-    for alias, canonical in alias_map.items():
-        if alias in result and canonical not in result:
-            result[canonical] = result[alias]
-    if tool == "record_get" and "query_mode" not in result:
-        result["query_mode"] = "record"
-    return result
-
-
-def _collect_plan_field_candidates(tool: str, arguments: JSONObject) -> list[JSONObject]:
-    candidates: list[JSONObject] = []
-    if tool in {"record_query", "record_get"}:
-        for item in _as_selector_list(arguments.get("select_columns")):
-            candidates.append({"role": "select_columns", "requested": str(item)})
-        amount = arguments.get("amount_column")
-        if amount is not None:
-            candidates.append({"role": "amount_column", "requested": str(amount)})
-        time_range = arguments.get("time_range")
-        if isinstance(time_range, dict) and time_range.get("column") is not None:
-            candidates.append({"role": "time_range.column", "requested": str(time_range["column"])})
-    if tool == "record_aggregate":
-        for item in _as_selector_list(arguments.get("group_by")):
-            candidates.append({"role": "group_by", "requested": str(item)})
-        amount = arguments.get("amount_column")
-        if amount is not None:
-            candidates.append({"role": "amount_column", "requested": str(amount)})
-        time_range = arguments.get("time_range")
-        if isinstance(time_range, dict) and time_range.get("column") is not None:
-            candidates.append({"role": "time_range.column", "requested": str(time_range["column"])})
-    for item in _as_object_list(arguments.get("filters")):
-        selector = _extract_filter_selector(item)
-        if selector is not None:
-            candidates.append({"role": "filter", "requested": str(selector)})
-    for item in _as_object_list(arguments.get("sorts", arguments.get("sort"))):
-        selector = _extract_sort_selector(item)
-        if selector is not None:
-            candidates.append({"role": "sort", "requested": str(selector)})
-    return candidates
-
-
-def _build_plan_estimate(tool: str, arguments: JSONObject) -> JSONObject:
-    page_size = _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE
-    requested_pages = _coerce_count(arguments.get("requested_pages")) or 1
-    scan_max_pages = _coerce_count(arguments.get("scan_max_pages")) or requested_pages
-    estimated_scan_pages = min(requested_pages, scan_max_pages)
-    may_hit_limits = estimated_scan_pages > DEFAULT_SCAN_MAX_PAGES
-    reasons = []
-    if may_hit_limits:
-        reasons.append("requested scan pages exceed the default analysis budget")
-    if tool == "record_query":
-        routed_mode = _resolve_query_mode(
-            str(arguments.get("query_mode", "auto")),
-            apply_id=_coerce_count(arguments.get("apply_id")),
-            amount_column=arguments.get("amount_column"),
-            time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
-            stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
-        )
-        if routed_mode == "list":
-            reasons.append("list mode is not a safe final-analysis endpoint")
+def _fixed_list_scan_policy() -> JSONObject:
     return {
-        "page_size": page_size,
-        "requested_pages": requested_pages,
-        "scan_max_pages": scan_max_pages,
-        "estimated_scan_pages": estimated_scan_pages,
-        "estimated_items_upper_bound": page_size * estimated_scan_pages,
-        "may_hit_limits": may_hit_limits,
-        "reasons": reasons,
-        "probe": None,
+        "page_size": DEFAULT_LIST_PAGE_SIZE,
+        "requested_pages": 1,
+        "scan_max_pages": 1,
+        "auto_expand_pages": False,
+        "public_inputs_exposed": False,
     }
 
 
-def _assess_plan_readiness(
-    tool: str,
-    arguments: JSONObject,
-    validation: JSONObject,
-    field_mapping: list[JSONObject],
-    estimate: JSONObject,
-) -> JSONObject:
-    blockers: list[str] = []
-    actions: list[str] = []
-    if not bool(validation.get("valid")):
-        blockers.append("arguments are not valid")
-        actions.append("Fix missing_required before execution.")
-    unresolved = [item for item in field_mapping if not bool(item.get("resolved"))]
-    if unresolved:
-        blockers.append("one or more fields are unresolved")
-        actions.append("Use record_field_resolve to resolve field ids before execution.")
-    if tool == "record_query":
-        routed_mode = _resolve_query_mode(
-            str(arguments.get("query_mode", "auto")),
-            apply_id=_coerce_count(arguments.get("apply_id")),
-            amount_column=arguments.get("amount_column"),
-            time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
-            stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
-        )
-        if routed_mode == "list":
-            blockers.append("list mode is not a safe final-analysis endpoint")
-            actions.append("Use record_query(summary) or record_aggregate for final statistics.")
-        if routed_mode == "record":
-            blockers.append("record mode is a detail endpoint, not a final-analysis endpoint")
-    if tool in {"record_query", "record_aggregate"} and not bool(arguments.get("strict_full")):
-        blockers.append("strict_full should be true for final conclusions")
-        actions.append("Set strict_full=true so incomplete scans block final conclusions.")
-    actions.append("After execution, verify completeness before using the result as a final conclusion.")
+def _fixed_analysis_scan_policy() -> JSONObject:
     return {
-        "ready_for_final_conclusion": not blockers,
-        "final_conclusion_blockers": blockers,
-        "recommended_next_actions": actions,
+        "page_size": DEFAULT_ANALYSIS_PAGE_SIZE,
+        "requested_pages": DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
+        "scan_max_pages": DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
+        "auto_expand_pages": True,
+        "public_inputs_exposed": False,
     }
 
 
+def _list_row_cap_hit(*, returned_items: int, row_cap: int) -> bool:
+    return row_cap > 0 and returned_items >= row_cap
+
+
+def _list_sample_only(*, returned_items: int, row_cap: int, result_amount: int | None) -> bool:
+    if _list_row_cap_hit(returned_items=returned_items, row_cap=row_cap):
+        return True
+    if result_amount is None:
+        return False
+    return result_amount > returned_items
+
+
+def _list_sample_warning(*, returned_items: int, row_cap: int, result_amount: int | None) -> str:
+    if _list_sample_only(returned_items=returned_items, row_cap=row_cap, result_amount=result_amount):
+        return "当前仅返回样本，不适合最终统计结论。"
+    return "record_query(list) 适合浏览或导出明细；最终统计结论请改用 record_schema_get -> record_analyze。"
+
+
 def _resolve_query_mode(
     query_mode: str,
     *,
@@ -3059,8 +3364,6 @@ def _resolve_query_mode(
         return query_mode
     if apply_id is not None and apply_id > 0:
         return "record"
-    if amount_column is not None or time_range or stat_policy:
-        return "summary"
     return "list"
 
 
@@ -3154,6 +3457,69 @@ def _view_selection_payload(view_selection: ViewSelection | None) -> JSONObject
     }
 
 
+def _compute_scan_limit(
+    *,
+    requested_pages: int,
+    scan_max_pages: int,
+    auto_expand_pages: bool,
+    page: JSONObject | None = None,
+    page_size: int | None = None,
+) -> tuple[int, JSONObject]:
+    base_requested = max(requested_pages, 1)
+    base_scan_max = max(scan_max_pages, 1)
+    initial_limit = min(base_requested, base_scan_max)
+    meta: JSONObject = {
+        "requested_pages": base_requested,
+        "scan_max_pages": base_scan_max,
+        "auto_expand_pages": auto_expand_pages,
+        "auto_expand_applied": False,
+        "auto_expand_target_pages": initial_limit,
+        "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+    }
+    if not auto_expand_pages or not isinstance(page, dict):
+        return initial_limit, meta
+    effective_page_size = max(page_size or 0, 1)
+    backend_total = _effective_total(page, effective_page_size)
+    page_amount = _coerce_count(page.get("pageAmount"))
+    target_pages = page_amount
+    if target_pages is None and backend_total > 0:
+        target_pages = (backend_total + effective_page_size - 1) // effective_page_size
+    if target_pages is None:
+        return initial_limit, meta
+    expanded_limit = min(max(initial_limit, target_pages), DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP)
+    if expanded_limit > initial_limit:
+        meta["auto_expand_applied"] = True
+    meta["auto_expand_target_pages"] = target_pages
+    meta["backend_total_count"] = backend_total
+    meta["backend_page_amount"] = page_amount
+    return expanded_limit, meta
+
+
+def _build_analysis_counts(
+    *,
+    backend_total_count: int | None,
+    scanned_count: int,
+    grouped_count: int,
+    local_filtering: bool,
+) -> JSONObject:
+    unscanned_count: int | None = None
+    if backend_total_count is not None and not local_filtering:
+        unscanned_count = max(backend_total_count - scanned_count, 0)
+    return {
+        "backend_total_count": backend_total_count,
+        "scanned_count": scanned_count,
+        "grouped_count": grouped_count,
+        "unscanned_count": unscanned_count,
+        "local_filtering": local_filtering,
+    }
+
+
+def _analysis_status_from_completeness(completeness: JSONObject) -> tuple[str, bool]:
+    raw_scan_complete = bool(completeness.get("raw_scan_complete"))
+    status = "success" if raw_scan_complete else "partial_success"
+    return status, raw_scan_complete
+
+
 def _build_completeness(
     *,
     result_amount: int,
@@ -3277,6 +3643,11 @@ def _to_time_bucket(value: JSONValue, bucket: str) -> str:
     if bucket == "week":
         iso_year, iso_week, _ = parsed.isocalendar()
         return f"{iso_year}-W{iso_week:02d}"
+    if bucket == "quarter":
+        quarter = ((parsed.month - 1) // 3) + 1
+        return f"{parsed.year}-Q{quarter}"
+    if bucket == "year":
+        return parsed.strftime("%Y")
     return parsed.strftime("%Y-%m-%d")
 
 
@@ -3290,6 +3661,117 @@ def _parse_datetime_like(text: str) -> datetime | None:
     return None
 
 
+def _flatten_distinct_values(value: JSONValue) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        items = value
+    else:
+        items = [value]
+    flattened: list[str] = []
+    for item in items:
+        if item is None:
+            continue
+        if isinstance(item, (dict, list)):
+            flattened.append(json.dumps(item, ensure_ascii=False, sort_keys=True))
+        else:
+            flattened.append(_stringify_json(item))
+    return flattened
+
+
+def _coerce_comparable(value: JSONValue) -> JSONValue:
+    amount = _coerce_amount(value)
+    if amount is not None:
+        return amount
+    text = _normalize_optional_text(value)
+    if text is None:
+        return None
+    parsed = _parse_datetime_like(text)
+    if parsed is not None:
+        return parsed
+    return text
+
+
+def _match_analyze_filter(field_value: JSONValue, op: str, expected: JSONValue) -> bool:
+    if op == "is_null":
+        return field_value is None or field_value == [] or field_value == ""
+    if op == "not_null":
+        return not _match_analyze_filter(field_value, "is_null", expected)
+
+    values = field_value if isinstance(field_value, list) else [field_value]
+    normalized_values = [_coerce_comparable(item) for item in values if item is not None]
+
+    if op == "contains":
+        needle = _normalize_optional_text(expected)
+        if needle is None:
+            return False
+        return any(needle in _stringify_json(item) for item in values if item is not None)
+
+    if op in {"in", "not_in"}:
+        expected_values = expected if isinstance(expected, list) else [expected]
+        matched = any(
+            _analyze_values_equal(actual=item, expected=expected_item)
+            for item in values
+            if item is not None
+            for expected_item in expected_values
+            if expected_item is not None
+        )
+        return matched if op == "in" else not matched
+
+    if op in {"eq", "neq"}:
+        matched = any(_analyze_values_equal(actual=item, expected=expected) for item in values if item is not None)
+        return matched if op == "eq" else not matched
+
+    if op == "between":
+        lower, upper = _coerce_filter_range(expected)
+        lower_value = _coerce_comparable(lower)
+        upper_value = _coerce_comparable(upper)
+        for item in normalized_values:
+            if item is None:
+                continue
+            try:
+                if lower_value is not None and item < lower_value:
+                    continue
+                if upper_value is not None and item > upper_value:
+                    continue
+                return True
+            except TypeError:
+                continue
+        return False
+
+    target = _coerce_comparable(expected)
+    for item in normalized_values:
+        if item is None or target is None:
+            continue
+        try:
+            if op == "gt" and item > target:
+                return True
+            if op == "gte" and item >= target:
+                return True
+            if op == "lt" and item < target:
+                return True
+            if op == "lte" and item <= target:
+                return True
+        except TypeError:
+            continue
+    return False
+
+
+def _analyze_values_equal(*, actual: JSONValue, expected: JSONValue) -> bool:
+    actual_comparable = _coerce_comparable(actual)
+    expected_comparable = _coerce_comparable(expected)
+    if actual_comparable is not None and expected_comparable is not None and type(actual_comparable) is type(expected_comparable):
+        return actual_comparable == expected_comparable
+    return _stringify_json(actual) == _stringify_json(expected)
+
+
+def _sortable_value(value: JSONValue) -> tuple[int, JSONValue]:
+    if value is None:
+        return (1, "")
+    comparable = _coerce_comparable(value)
+    return (0, comparable if comparable is not None else "")
+
+
 def _echo_filters(filters: list[JSONObject]) -> list[JSONObject]:
     return [dict(item) for item in filters]
 
@@ -3850,7 +4332,7 @@ def _option_value(raw_value: JSONValue, field: FormField) -> JSONObject:
         raise RecordInputError(
             message=f"field '{field.que_title}' uses unknown option '{text}'",
             error_code="OPTION_NOT_FOUND",
-            fix_hint="Use record_field_resolve or inspect the form to confirm allowed option values.",
+            fix_hint="Use record_schema_get or inspect the form to confirm allowed option values.",
             details={"field": _field_ref_payload(field), "expected_format": _write_format_for_field(field), "received_value": raw_value},
         )
     return {"value": text}