@josephyan/qingflow-app-user-mcp 1.0.7 → 1.0.9

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.0.7
+npm install @josephyan/qingflow-app-user-mcp@1.0.9
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.0.7 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.0.9 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

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

package/pyproject.toml

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

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -8,6 +8,7 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 ### User data
 
 - Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `schema.json` must stay aligned with it.
 - Standard flows:
   - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
   - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`

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

@@ -9,7 +9,7 @@ metadata:
 
 This skill is for final statistical conclusions only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
+Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. `record_browse_schema_get.fields` is the selected Qingflow table view's readable header schema and is the same field source used by `record_access.fields` / `schema.json`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
 If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_access`, `record_list`, or `record_analyze`. `boardView` and `ganttView` are special UI views, not data-access targets.
 
 ## Step 1: `app_get` → Step 2: `record_browse_schema_get(view_id=...)` → Step 3: `record_access` → Step 4: Python
@@ -17,6 +17,7 @@ If `app_get.accessible_views` marks a view with `analysis_supported=false`, do n
 This is the default execution order. Never skip `app_get` when the browse range is unclear. Never call `record_access` without a browse schema.
 
 Core tools: `app_get`, `record_browse_schema_get`, `record_access`, Python. Use field_id-based DSLs only for columns, filters, sort clauses, and any optional lightweight `record_analyze` helper. Use `record_list`/`record_get` only for browse samples. Use `record_analyze` only as a lightweight non-default statistics helper when a compact grouped result is enough. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
+For analysis-style tasks, prefer a concrete time range or business filter. If the user did not give one and the data could be large, ask for scope instead of trying an unbounded historical scan.
 
 ## Execution Modes
 
@@ -76,7 +77,10 @@ Use `record_access` to fetch detail rows into local CSV shards. It does not anal
 Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` plus `metadata_files.schema` / `metadata_files.readme` in the same output directory to map titles and types, especially when reusing the CSV later.
 
 - Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally and follows the backend's native paging capability.
+- Never treat backend `searchQueIds` as column selection; it is only a full-text search scope.
 - If multiple CSV files are returned, read them all.
+- If `status=needs_scope`, no CSV was written; use `scope.suggested_time_fields` / `scope.recommended_where_examples` to ask for or apply a time/business range, then call `record_access` again.
+- If `status=partial`, read the returned files only as a limited subset; state the limitation and do not present a full-population final conclusion.
 - If `complete=false` or `safe_for_final_conclusion=false`, downgrade the answer and disclose the limitation.
 - `record_export_direct` is only for explicit export/download/Excel requests, not default analysis.
 - QingBI/report reads are only for user-provided report URLs or `chart_id`; do not create or use reports as the default analysis path.

package/skills/qingflow-record-analysis/references/analysis-gotchas.md

@@ -125,6 +125,8 @@ If the user asked for several outputs and only part of them is stable:
 - say which parts are still unresolved
 - do not present the answer as fully finished
 
+If `record_access.status=needs_scope`, stop and ask for a time/business range; no CSV was written. If `record_access.status=partial`, read the returned CSV only as a partial subset and name the limitation before any numbers.
+
 ## Do not send unsupported formula or div-style metrics into `record_analyze`.
 
 Examples to avoid:

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

@@ -25,15 +25,19 @@ Use this skill when the user asks for:
 
 Result reading order:
 
-1. `record_access.complete`
-2. `record_access.safe_for_final_conclusion`
-3. `record_access.files[].local_path`
-4. `record_access.metadata_files.schema`
-5. Python outputs
-6. `record_access.fields`
-7. `record_access.warnings`
-
-Treat `record_browse_schema_get` as the browse-schema source of truth. Missing fields are permission boundaries, not invitations to guess hidden ids.
+1. `record_access.status`
+2. `record_access.complete`
+3. `record_access.safe_for_final_conclusion`
+4. `record_access.files[].local_path`
+5. `record_access.metadata_files.schema`
+6. Python outputs
+7. `record_access.fields`
+8. `record_access.warnings`
+9. `record_access.scope`
+
+If `record_access.status=needs_scope`, no CSV was written; ask for a time/business range or retry with a user-provided period from `scope.suggested_time_fields`. If `status=partial`, use the CSV files only as a limited subset and do not make a full-population conclusion.
+
+Treat `record_browse_schema_get` as the browse-schema source of truth. It matches the selected Qingflow table view header and is the same schema source used by `record_access.fields` and `schema.json`. Missing fields are permission boundaries, not invitations to guess hidden ids.
 
 ## Lightweight `record_analyze` helper sequence
 

package/skills/qingflow-record-analysis/references/confidence-reporting.md

@@ -27,6 +27,8 @@ Put evidence into `样本观察` when:
 - the tool reports `row_cap_hit`
 - the tool reports `sample_only`
 - the result is compact/capped and not complete
+- `record_access.status=needs_scope`
+- `record_access.status=partial`
 - `record_access.complete=false` or `record_access.truncated=true`
 
 ## Downgrade rule

package/src/qingflow_mcp/cli/formatters.py

@@ -194,6 +194,36 @@ def _format_record_list(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_access(result: dict[str, Any]) -> str:
+    status = result.get("status") or "-"
+    lines = [
+        f"Status: {status}",
+        f"Rows: {result.get('row_count')}",
+        f"Complete: {result.get('complete')}",
+        f"Safe for final conclusion: {result.get('safe_for_final_conclusion')}",
+    ]
+    if result.get("local_dir"):
+        lines.append(f"Local dir: {result.get('local_dir')}")
+    files = result.get("files") if isinstance(result.get("files"), list) else []
+    if files:
+        lines.append("Files:")
+        for item in files:
+            if isinstance(item, dict):
+                lines.append(f"- part {item.get('part')}: {item.get('local_path')} ({item.get('row_count')} rows)")
+    scope = result.get("scope") if isinstance(result.get("scope"), dict) else {}
+    if status == "needs_scope" and scope:
+        lines.append("Scope required:")
+        lines.append(f"- reported_total: {scope.get('reported_total')}")
+        lines.append(f"- estimated_pages: {scope.get('estimated_pages')}")
+        suggested = scope.get("suggested_time_fields") if isinstance(scope.get("suggested_time_fields"), list) else []
+        if suggested:
+            names = ", ".join(str(item.get("title") or item.get("field_id")) for item in suggested if isinstance(item, dict))
+            lines.append(f"- suggested_time_fields: {names}")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_task_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
@@ -693,6 +723,7 @@ _FORMATTERS = {
     "app_search": _format_app_items,
     "app_get": _format_app_get,
     "record_list": _format_record_list,
+    "record_access": _format_record_access,
     "task_list": _format_task_list,
     "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,

package/src/qingflow_mcp/response_trim.py

@@ -465,6 +465,7 @@ def _trim_record_access(payload: JSONObject) -> None:
         "fields",
         "warnings",
         "verification",
+        "scope",
     ):
         value = payload.get(key)
         if value is not None:

package/src/qingflow_mcp/server_app_user.py

@@ -60,7 +60,9 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
 Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
 `record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
-`record_browse_schema_get(view_id=...)` returns browse-schema fields for the selected accessible view.
+`record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
+`record_access.fields` and its `schema.json` use that exact same view schema; a missing field means it is not readable in that view.
+`searchQueIds` is a backend full-text search scope, not an output-column/projection mechanism.
 `record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
 `record_import_schema_get` returns import-ready column metadata.
 
@@ -75,6 +77,7 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
 Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`. Use `fields[]` and the same-directory `metadata_files.schema` / `metadata_files.readme` to map stable `field_<id>` CSV columns back to titles and types.
+For analysis-style tasks, prefer an explicit time range or business filter. If `record_access.status == "needs_scope"`, do not treat it as a failure; ask for a time/business scope or retry with a user-provided period using `scope.suggested_time_fields` / `scope.recommended_where_examples`. If `record_access.status == "partial"`, read the returned files only as a limited subset and do not give a final full-population conclusion.
 Use `chart_get` only when the user provides a report URL / chart_id or explicitly asks to read an existing report. Do not use QingBI as the default analysis route.
 
 Use this data-access DSL shape:

package/src/qingflow_mcp/tools/record_tools.py

@@ -7,7 +7,7 @@ import re
 import time
 from copy import deepcopy
 from dataclasses import dataclass
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from decimal import Decimal, InvalidOperation
 from pathlib import Path
 from typing import Any, cast
@@ -34,6 +34,9 @@ DEFAULT_QUERY_PAGE_SIZE = 50
 DEFAULT_LIST_PAGE_SIZE = 200
 BACKEND_RECORD_ACCESS_PAGE_SIZE = 1000
 DEFAULT_RECORD_ACCESS_SHARD_ROWS = 5000
+RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD = 20_000
+RECORD_ACCESS_TIME_BUDGET_SECONDS = 55.0
+RECORD_ACCESS_MIN_REMAINING_SECONDS = 8.0
 DEFAULT_ANALYSIS_PAGE_SIZE = 1000
 DEFAULT_SCAN_MAX_PAGES = 10
 DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
@@ -602,7 +605,7 @@ class RecordTools(ToolBase):
                             ),
                         }
                     )
-                browse_scope = self._build_browse_write_scope(
+                browse_scope = self._build_browse_read_scope(
                     profile,
                     context,
                     app_key,
@@ -1848,25 +1851,21 @@ class RecordTools(ToolBase):
         sorts = self._normalize_record_list_order_by(order_by)
 
         def runner(session_profile, context):
-            index = self._get_field_index(profile, context, app_key, force_refresh=False)
-            selected_fields = self._resolve_select_columns(
+            created_at = datetime.now(UTC).isoformat()
+            browse_scope = self._build_browse_read_scope(
+                profile,
+                context,
+                app_key,
+                view_route,
+                force_refresh=False,
+            )
+            index = cast(FieldIndex, browse_scope["index"])
+            selected_fields = self._resolve_record_access_columns(
                 normalized_columns,
                 index,
-                max_columns=len(normalized_columns),
-                default_limit=MAX_LIST_COLUMN_LIMIT,
+                view_route=view_route,
             )
-            selected_field_batches = _chunk_fields(selected_fields, BACKEND_LIST_SEARCH_FIELD_LIMIT)
-            primary_search_que_ids: list[int] | None = [field.que_id for field in selected_field_batches[0]]
             view_selection = view_route.view_selection
-            if view_selection is not None and not _view_selection_supported_by_search_ids(
-                view_selection,
-                primary_search_que_ids,
-            ):
-                primary_search_que_ids = None
-                remaining_field_batches: list[list[FormField]] = []
-            else:
-                remaining_field_batches = selected_field_batches[1:]
-                primary_search_que_ids = primary_search_que_ids or None
             match_rules = self._resolve_match_rules(context, filters, index)
             sort_rules = self._resolve_sorts(sorts, index)
             used_list_type: int | None = None
@@ -1875,6 +1874,106 @@ class RecordTools(ToolBase):
                 if view_selection is not None or view_route.list_type is not None
                 else [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
             )
+            fields_payload = [_record_access_field_payload(field) for field in selected_fields]
+            scope_status = _record_access_scope_status(filters, view_route, index)
+
+            def fetch_page(page_num: int, page_size: int) -> JSONObject:
+                nonlocal used_list_type
+                if used_list_type is None:
+                    last_error: QingflowApiError | None = None
+                    page: JSONObject | None = None
+                    for candidate_list_type in fallback_list_types:
+                        try:
+                            page = self._search_page(
+                                context,
+                                app_key=app_key,
+                                view_selection=view_selection,
+                                page_num=page_num,
+                                page_size=page_size,
+                                query_key=None,
+                                match_rules=match_rules,
+                                sorts=sort_rules,
+                                search_que_ids=None,
+                                list_type=candidate_list_type,
+                            )
+                            used_list_type = None if view_selection is not None else candidate_list_type
+                            break
+                        except QingflowApiError as exc:
+                            last_error = exc
+                            if self._should_retry_list_type_fallback(exc) and candidate_list_type != fallback_list_types[-1]:
+                                continue
+                            raise
+                    if page is None:
+                        if last_error is not None:
+                            raise last_error
+                        raise_tool_error(QingflowApiError.config_error("record_access failed: no accessible listType"))
+                    return page
+                return self._search_page(
+                    context,
+                    app_key=app_key,
+                    view_selection=view_selection,
+                    page_num=page_num,
+                    page_size=page_size,
+                    query_key=None,
+                    match_rules=match_rules,
+                    sorts=sort_rules,
+                    search_que_ids=None,
+                    list_type=used_list_type,
+                )
+
+            probe_page_size = 1 if _record_access_light_probe_recommended(scope_status) else BACKEND_RECORD_ACCESS_PAGE_SIZE
+            probe_page = fetch_page(1, probe_page_size)
+            reported_total = _effective_total(probe_page, probe_page_size)
+            estimated_pages = _record_access_estimated_pages(probe_page, reported_total, page_size=probe_page_size)
+            scope_payload = _record_access_scope_payload(
+                scope_status=scope_status,
+                reported_total=reported_total,
+                estimated_pages=estimated_pages,
+                index=index,
+            )
+            warnings: list[JSONObject] = []
+            warnings.extend(legacy_warnings)
+            warnings.extend(compatibility_warnings)
+            warnings.extend(_view_filter_trust_warnings(view_route))
+            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
+                warnings.append(
+                    {
+                        "code": "LIST_TYPE_FALLBACK",
+                        "message": (
+                            f"record_access not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; "
+                            f"fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)})."
+                        ),
+                    }
+                )
+            if _record_access_needs_scope(scope_status=scope_status, reported_total=reported_total):
+                warnings.append(_record_access_unbounded_scan_warning(reported_total=reported_total, estimated_pages=estimated_pages))
+                verification_payload: JSONObject = {
+                    **_view_filter_verification_payload(view_route),
+                    "reported_total": reported_total,
+                    "estimated_pages": estimated_pages,
+                    "fetched_pages": 1,
+                    "stopped_reason": "UNBOUNDED_SCAN_TOO_LARGE",
+                    "list_type_used": used_list_type,
+                }
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": True,
+                    "status": "needs_scope",
+                    "app_key": app_key,
+                    "view_id": view_route.view_id,
+                    "format": "csv",
+                    "row_count": 0,
+                    "complete": False,
+                    "truncated": True,
+                    "safe_for_final_conclusion": False,
+                    "files": [],
+                    "fields": fields_payload,
+                    "warnings": warnings,
+                    "verification": verification_payload,
+                    "scope": scope_payload,
+                    "request_route": self._request_route_payload(context),
+                }
 
             run_dir = _record_access_run_dir()
             run_dir.mkdir(parents=True, exist_ok=True)
@@ -1931,58 +2030,14 @@ class RecordTools(ToolBase):
 
             current_page = 1
             has_more = False
-            reported_total: int | None = None
-            created_at = datetime.now(UTC).isoformat()
+            fetched_pages = 0
+            stopped_reason: str | None = None
+            deadline = time.monotonic() + RECORD_ACCESS_TIME_BUDGET_SECONDS
+            page = probe_page if probe_page_size == BACKEND_RECORD_ACCESS_PAGE_SIZE else fetch_page(1, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             try:
                 while True:
-                    if used_list_type is None:
-                        last_error: QingflowApiError | None = None
-                        page: JSONObject | None = None
-                        for candidate_list_type in fallback_list_types:
-                            try:
-                                page = self._search_page(
-                                    context,
-                                    app_key=app_key,
-                                    view_selection=view_selection,
-                                    page_num=current_page,
-                                    page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                                    query_key=None,
-                                    match_rules=match_rules,
-                                    sorts=sort_rules,
-                                    search_que_ids=primary_search_que_ids,
-                                    list_type=candidate_list_type,
-                                )
-                                used_list_type = None if view_selection is not None else candidate_list_type
-                                break
-                            except QingflowApiError as exc:
-                                last_error = exc
-                                if (
-                                    self._should_retry_list_type_fallback(exc)
-                                    and candidate_list_type != fallback_list_types[-1]
-                                ):
-                                    continue
-                                raise
-                        if page is None:
-                            if last_error is not None:
-                                raise last_error
-                            raise_tool_error(QingflowApiError.config_error("record_access failed: no accessible listType"))
-                    else:
-                        page = self._search_page(
-                            context,
-                            app_key=app_key,
-                            view_selection=view_selection,
-                            page_num=current_page,
-                            page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                            query_key=None,
-                            match_rules=match_rules,
-                            sorts=sort_rules,
-                            search_que_ids=primary_search_que_ids,
-                            list_type=used_list_type,
-                        )
                     page_rows = page.get("list")
                     items = page_rows if isinstance(page_rows, list) else []
-                    if reported_total is None:
-                        reported_total = _effective_total(page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
                     has_more = _page_has_more(page, current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE, len(items))
                     page_apply_order: list[int] = []
                     page_answer_map: dict[int, list[JSONValue]] = {}
@@ -1996,64 +2051,35 @@ class RecordTools(ToolBase):
                             continue
                         page_apply_order.append(apply_id)
                         page_answer_map[apply_id] = cast(list[JSONValue], answer_list)
-                    if page_apply_order and remaining_field_batches:
-                        for batch in remaining_field_batches:
-                            extra_page = self._search_page(
-                                context,
-                                app_key=app_key,
-                                view_selection=view_selection,
-                                page_num=current_page,
-                                page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                                query_key=None,
-                                match_rules=match_rules,
-                                sorts=sort_rules,
-                                search_que_ids=[field.que_id for field in batch],
-                                list_type=used_list_type or DEFAULT_RECORD_LIST_TYPE,
-                            )
-                            extra_rows = extra_page.get("list")
-                            extra_items = extra_rows if isinstance(extra_rows, list) else []
-                            for extra_item in extra_items:
-                                if not isinstance(extra_item, dict):
-                                    continue
-                                apply_id = _coerce_count(extra_item.get("applyId")) or _coerce_count(extra_item.get("id"))
-                                if apply_id is None or apply_id not in page_answer_map:
-                                    continue
-                                extra_answers = extra_item.get("answers")
-                                extra_answer_list = extra_answers if isinstance(extra_answers, list) else []
-                                page_answer_map[apply_id] = _merge_answer_lists_by_field_id(
-                                    page_answer_map.get(apply_id, []),
-                                    cast(list[JSONValue], extra_answer_list),
-                                )
                     for apply_id in page_apply_order:
                         write_record(apply_id, page_answer_map.get(apply_id, []))
+                    fetched_pages += 1
                     if not has_more:
                         break
                     current_page += 1
+                    if _record_access_time_budget_exceeded(
+                        deadline,
+                        fetched_pages=fetched_pages,
+                        estimated_pages=estimated_pages,
+                    ):
+                        stopped_reason = "TIME_BUDGET_EXCEEDED"
+                        break
+                    page = fetch_page(current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             finally:
                 close_shard()
 
-            warnings: list[JSONObject] = []
-            warnings.extend(legacy_warnings)
-            warnings.extend(compatibility_warnings)
-            warnings.extend(_view_filter_trust_warnings(view_route))
-            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
-                warnings.append(
-                    {
-                        "code": "LIST_TYPE_FALLBACK",
-                        "message": (
-                            f"record_access not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; "
-                            f"fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)})."
-                        ),
-                    }
-                )
-            complete = not has_more
+            if stopped_reason == "TIME_BUDGET_EXCEEDED":
+                warnings.append(_record_access_time_budget_warning(reported_total=reported_total, fetched_pages=fetched_pages))
+            complete = stopped_reason is None and not has_more
             safe_for_final_conclusion = complete and not any(
                 warning.get("code") == "CUSTOM_VIEW_FILTER_UNVERIFIED" for warning in warnings
             )
-            fields_payload = [_record_access_field_payload(field) for field in selected_fields]
             verification_payload: JSONObject = {
                 **_view_filter_verification_payload(view_route),
                 "reported_total": reported_total,
+                "estimated_pages": estimated_pages,
+                "fetched_pages": fetched_pages,
+                "stopped_reason": stopped_reason,
                 "list_type_used": used_list_type,
             }
             metadata_files = _write_record_access_metadata_files(
@@ -2068,6 +2094,7 @@ class RecordTools(ToolBase):
                 fields=fields_payload,
                 warnings=warnings,
                 verification=verification_payload,
+                scope=scope_payload,
             )
             return {
                 "profile": profile,
@@ -2087,6 +2114,7 @@ class RecordTools(ToolBase):
                 "fields": fields_payload,
                 "warnings": warnings,
                 "verification": verification_payload,
+                "scope": scope_payload,
                 "request_route": self._request_route_payload(context),
             }
 
@@ -7427,6 +7455,39 @@ class RecordTools(ToolBase):
         self._form_cache[cache_key] = normalized
         return normalized
 
+    def _get_system_browse_base_info_schema(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        *,
+        list_type: int,
+        force_refresh: bool,
+    ) -> JSONObject:
+        """Return system view apply/baseInfo without falling back to app form metadata."""
+        cache_key = (profile, app_key, "browse_system_base_info", list_type)
+        if not force_refresh and cache_key in self._form_cache:
+            return self._form_cache[cache_key]
+        payload = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/baseInfo",
+            params={"type": list_type},
+        )
+        normalized = _normalize_data_list_base_info_schema(payload)
+        self._form_cache[cache_key] = normalized
+        return normalized
+
+    def _get_custom_view_browse_schema(self, profile: str, context, view_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
+        """Return the same baseInfo schema used by the Qingflow table view UI."""
+        cache_key = (profile, f"view:{view_key}", "browse_view_base_info", None)
+        if not force_refresh and cache_key in self._form_cache:
+            return self._form_cache[cache_key]
+        payload = self.backend.request("GET", context, f"/view/{view_key}/apply/baseInfo")
+        normalized = _normalize_data_list_base_info_schema(payload)
+        self._form_cache[cache_key] = normalized
+        return normalized
+
     def _get_view_field_index(self, profile: str, context, view_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
         return _build_field_index(self._get_view_form_schema(profile, context, view_key, force_refresh=force_refresh))
@@ -7469,6 +7530,80 @@ class RecordTools(ToolBase):
             force_refresh=force_refresh,
         )["index"]
 
+    def _build_browse_read_scope(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        resolved_view: AccessibleViewRoute | None,
+        *,
+        force_refresh: bool,
+    ) -> JSONObject:
+        """Build the UI/table-view readable field scope from apply/baseInfo."""
+        applicant_index: FieldIndex | None
+        applicant_writable_field_ids: set[int]
+        try:
+            applicant_index = self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=force_refresh)
+        except QingflowApiError as exc:
+            if exc.backend_code != 40002:
+                raise
+            applicant_index = None
+            applicant_writable_field_ids = set()
+        else:
+            applicant_writable_field_ids = {
+                field.que_id
+                for field in applicant_index.by_id.values()
+                if bool(self._schema_write_hints(field)["writable"])
+            }
+
+        if resolved_view is not None and resolved_view.kind == "custom" and resolved_view.view_selection is not None:
+            schema = self._get_custom_view_browse_schema(
+                profile,
+                context,
+                resolved_view.view_selection.view_key,
+                force_refresh=force_refresh,
+            )
+            index = _build_top_level_field_index(schema)
+        elif resolved_view is not None and resolved_view.kind == "system" and resolved_view.list_type is not None:
+            schema = self._get_system_browse_base_info_schema(
+                profile,
+                context,
+                app_key,
+                list_type=resolved_view.list_type,
+                force_refresh=force_refresh,
+            )
+            index = _build_top_level_field_index(schema)
+        else:
+            index = applicant_index or _build_top_level_field_index(
+                self._get_form_schema(profile, context, app_key, force_refresh=force_refresh)
+            )
+
+        if applicant_index is not None and index.by_id:
+            enriched_fields = [
+                _enrich_read_field_from_applicant(field, applicant_index.by_id.get(str(field.que_id)))
+                for field in index.by_id.values()
+            ]
+            index = _build_top_level_field_index({"formQues": [[_form_field_to_question(field) for field in enriched_fields]]})
+
+        visible_question_ids = {field.que_id for field in index.by_id.values()}
+        if applicant_index is None:
+            writable_field_ids = {
+                field.que_id
+                for field in index.by_id.values()
+                if bool(self._schema_write_hints(field)["writable"])
+            }
+        else:
+            writable_field_ids = {
+                field_id
+                for field_id in visible_question_ids
+                if field_id in applicant_writable_field_ids
+            }
+        return {
+            "index": index,
+            "writable_field_ids": writable_field_ids,
+            "visible_question_ids": visible_question_ids,
+        }
+
     def _build_browse_write_scope(
         self,
         profile: str,
@@ -9538,6 +9673,44 @@ class RecordTools(ToolBase):
                 break
         return fields
 
+    def _resolve_record_access_columns(
+        self,
+        selectors: list[int],
+        index: FieldIndex,
+        *,
+        view_route: AccessibleViewRoute,
+    ) -> list[FormField]:
+        """Resolve record_access columns against the selected view's baseInfo schema."""
+        if not selectors:
+            raise_tool_error(QingflowApiError.config_error("columns is required"))
+        fields: list[FormField] = []
+        seen: set[int] = set()
+        for selector in selectors:
+            try:
+                field = self._resolve_field_selector(selector, index, location="record_access.columns")
+            except RecordInputError as exc:
+                if exc.error_code == "FIELD_NOT_FOUND":
+                    raise RecordInputError(
+                        message=(
+                            f"record_access column field_id '{selector}' is not in the selected view schema "
+                            f"({view_route.view_id})."
+                        ),
+                        error_code="FIELD_NOT_IN_VIEW_SCHEMA",
+                        fix_hint="Call record_browse_schema_get for this exact view_id and pass only field_id values from its fields[].",
+                        details={
+                            "location": "record_access.columns",
+                            "requested": selector,
+                            "view_id": view_route.view_id,
+                            "view_name": view_route.name,
+                        },
+                    ) from exc
+                raise
+            if field.que_id in seen:
+                continue
+            fields.append(field)
+            seen.add(field.que_id)
+        return fields
+
     def _resolve_summary_preview_fields(
         self,
         selectors: list[str | int],
@@ -11295,6 +11468,38 @@ def _clone_form_field(field: FormField, *, readonly: bool | None = None) -> Form
     )
 
 
+def _enrich_read_field_from_applicant(field: FormField, applicant_field: FormField | None) -> FormField:
+    if applicant_field is None:
+        return field
+    raw = dict(applicant_field.raw) if isinstance(applicant_field.raw, dict) else {}
+    raw.update(dict(field.raw) if isinstance(field.raw, dict) else {})
+    raw["queId"] = field.que_id
+    raw["queTitle"] = field.que_title
+    que_type = field.que_type if field.que_type is not None else applicant_field.que_type
+    if que_type is not None:
+        raw["queType"] = que_type
+    readonly_source = field if any(key in field.raw for key in ("readonly", "beingReadonly", "canEdit")) else applicant_field
+    enriched = FormField(
+        que_id=field.que_id,
+        que_title=field.que_title,
+        que_type=que_type,
+        required=field.required or applicant_field.required,
+        readonly=readonly_source.readonly,
+        system=field.system or applicant_field.system,
+        options=list(field.options or applicant_field.options),
+        aliases=[],
+        target_app_key=field.target_app_key or applicant_field.target_app_key,
+        target_app_name_hint=field.target_app_name_hint or applicant_field.target_app_name_hint,
+        member_select_scope_type=field.member_select_scope_type if field.member_select_scope_type is not None else applicant_field.member_select_scope_type,
+        member_select_scope=field.member_select_scope or applicant_field.member_select_scope,
+        dept_select_scope_type=field.dept_select_scope_type if field.dept_select_scope_type is not None else applicant_field.dept_select_scope_type,
+        dept_select_scope=field.dept_select_scope or applicant_field.dept_select_scope,
+        raw=raw,
+    )
+    enriched.aliases = sorted(_field_alias_candidates(enriched))
+    return enriched
+
+
 def _form_field_to_question(field: FormField) -> JSONObject:
     question = dict(field.raw) if isinstance(field.raw, dict) else {}
     question.setdefault("queId", field.que_id)
@@ -11521,6 +11726,148 @@ def _record_access_field_payload(field: FormField) -> JSONObject:
     }
 
 
+def _record_access_scope_status(filters: list[JSONObject], view_route: AccessibleViewRoute, index: FieldIndex) -> JSONObject:
+    has_time_filter = False
+    has_explicit_business_filter = False
+    for item in filters:
+        if not isinstance(item, dict):
+            continue
+        field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+        field = index.by_id.get(str(field_id)) if field_id is not None else None
+        if field is not None and field.que_type in DATE_QUE_TYPES:
+            has_time_filter = True
+        else:
+            has_explicit_business_filter = True
+    view_selection = view_route.view_selection
+    has_saved_view_filter = bool(view_selection is not None and view_selection.conditions)
+    return {
+        "filter_count": len(filters),
+        "has_explicit_where": bool(filters),
+        "has_time_filter": has_time_filter,
+        "has_business_filter": bool(has_explicit_business_filter or has_saved_view_filter),
+        "has_saved_view_filter": has_saved_view_filter,
+    }
+
+
+def _record_access_light_probe_recommended(scope_status: JSONObject) -> bool:
+    return not bool(scope_status.get("has_time_filter")) and not bool(scope_status.get("has_business_filter"))
+
+
+def _record_access_estimated_pages(page: JSONObject, reported_total: int | None, *, page_size: int) -> int | None:
+    page_amount = _coerce_count(page.get("pageAmount"))
+    if page_size == BACKEND_RECORD_ACCESS_PAGE_SIZE and page_amount is not None:
+        return page_amount
+    if reported_total is None or reported_total <= 0:
+        return page_amount
+    return (reported_total + BACKEND_RECORD_ACCESS_PAGE_SIZE - 1) // BACKEND_RECORD_ACCESS_PAGE_SIZE
+
+
+def _record_access_suggested_time_fields(index: FieldIndex) -> list[JSONObject]:
+    fields: list[JSONObject] = []
+    for field in index.by_id.values():
+        if field.que_type in DATE_QUE_TYPES:
+            fields.append(_record_access_field_payload(field))
+    return fields
+
+
+def _record_access_recommended_where_examples(suggested_time_fields: list[JSONObject]) -> list[JSONObject]:
+    if not suggested_time_fields:
+        return []
+    now = datetime.now(UTC)
+    month_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    if month_start.month == 12:
+        next_month = month_start.replace(year=month_start.year + 1, month=1)
+    else:
+        next_month = month_start.replace(month=month_start.month + 1)
+    month_end = next_month - timedelta(seconds=1)
+    examples: list[JSONObject] = []
+    for field in suggested_time_fields[:3]:
+        field_id = field.get("field_id")
+        examples.append(
+            {
+                "field_id": field_id,
+                "title": field.get("title"),
+                "where": [
+                    {
+                        "field_id": field_id,
+                        "op": "between",
+                        "value": [
+                            month_start.strftime("%Y-%m-%d"),
+                            month_end.strftime("%Y-%m-%d %H:%M:%S"),
+                        ],
+                    }
+                ],
+            }
+        )
+    return examples
+
+
+def _record_access_scope_payload(
+    *,
+    scope_status: JSONObject,
+    reported_total: int | None,
+    estimated_pages: int | None,
+    index: FieldIndex,
+) -> JSONObject:
+    suggested_time_fields = _record_access_suggested_time_fields(index)
+    return {
+        "reported_total": reported_total,
+        "estimated_pages": estimated_pages,
+        "has_time_filter": bool(scope_status.get("has_time_filter")),
+        "has_business_filter": bool(scope_status.get("has_business_filter")),
+        "suggested_time_fields": suggested_time_fields,
+        "recommended_where_examples": _record_access_recommended_where_examples(suggested_time_fields),
+    }
+
+
+def _record_access_needs_scope(*, scope_status: JSONObject, reported_total: int | None) -> bool:
+    if reported_total is None or reported_total <= RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD:
+        return False
+    return not bool(scope_status.get("has_time_filter")) and not bool(scope_status.get("has_business_filter"))
+
+
+def _record_access_unbounded_scan_warning(*, reported_total: int | None, estimated_pages: int | None) -> JSONObject:
+    page_text = f" across about {estimated_pages} pages" if estimated_pages else ""
+    return {
+        "code": "UNBOUNDED_SCAN_TOO_LARGE",
+        "message": (
+            "record_access stopped before writing CSV because this query has no time/business boundary "
+            f"and the backend reports {reported_total or 'unknown'} rows{page_text}. "
+            "Add a where filter, preferably on a time field, then retry."
+        ),
+        "row_threshold": RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD,
+        "reported_total": reported_total,
+        "estimated_pages": estimated_pages,
+    }
+
+
+def _record_access_time_budget_exceeded(
+    deadline: float,
+    *,
+    fetched_pages: int,
+    estimated_pages: int | None,
+) -> bool:
+    now = time.monotonic()
+    if now >= deadline:
+        return True
+    if estimated_pages is not None and estimated_pages - fetched_pages <= 1:
+        return False
+    return now + RECORD_ACCESS_MIN_REMAINING_SECONDS >= deadline
+
+
+def _record_access_time_budget_warning(*, reported_total: int | None, fetched_pages: int) -> JSONObject:
+    return {
+        "code": "TIME_BUDGET_EXCEEDED",
+        "message": (
+            "record_access stopped early to return partial CSV files before the caller timeout. "
+            "Narrow the query with a time or business filter for a complete result."
+        ),
+        "reported_total": reported_total,
+        "fetched_pages": fetched_pages,
+        "time_budget_seconds": RECORD_ACCESS_TIME_BUDGET_SECONDS,
+    }
+
+
 def _write_record_access_metadata_files(
     *,
     run_dir: Path,
@@ -11534,6 +11881,7 @@ def _write_record_access_metadata_files(
     fields: list[JSONObject],
     warnings: list[JSONObject],
     verification: JSONObject,
+    scope: JSONObject | None = None,
 ) -> JSONObject:
     schema_path = run_dir / "schema.json"
     readme_path = run_dir / "README.md"
@@ -11554,6 +11902,8 @@ def _write_record_access_metadata_files(
         "verification": verification,
         "csv_columns": ["record_id"] + [str(field["column_name"]) for field in fields if field.get("column_name")],
     }
+    if scope is not None:
+        schema_payload["scope"] = scope
     schema_path.write_text(json.dumps(schema_payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
     readme_path.write_text(
         _record_access_readme(
@@ -11566,6 +11916,7 @@ def _write_record_access_metadata_files(
             files=files,
             fields=fields,
             warnings=warnings,
+            scope=scope,
         ),
         encoding="utf-8",
     )
@@ -11586,6 +11937,7 @@ def _record_access_readme(
     files: list[JSONObject],
     fields: list[JSONObject],
     warnings: list[JSONObject],
+    scope: JSONObject | None = None,
 ) -> str:
     lines = [
         "# Qingflow Record Access",
@@ -11631,6 +11983,18 @@ def _record_access_readme(
             code = _normalize_optional_text(warning.get("code")) or "WARNING"
             message = _normalize_optional_text(warning.get("message")) or ""
             lines.append(f"- `{code}`: {message}")
+    if scope:
+        lines.extend(
+            [
+                "",
+                "## Scope",
+                "",
+                f"- Reported total: {scope.get('reported_total')}",
+                f"- Estimated pages: {scope.get('estimated_pages')}",
+                f"- Has time filter: {str(bool(scope.get('has_time_filter'))).lower()}",
+                f"- Has business filter: {str(bool(scope.get('has_business_filter'))).lower()}",
+            ]
+        )
     lines.extend(
         [
             "",