@josephyan/qingflow-app-user-mcp 1.0.6 → 1.0.8

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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.6"
+version = "1.0.8"
 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
@@ -73,9 +73,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[]` metadata to map titles and types.
+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 `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.

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

@@ -94,6 +94,7 @@ Examples of the right recovery question:
 - Do not invent `page_size`
 - Do not invent `requested_pages`
 - Do not invent `scan_max_pages`
+- Do not rename CSV columns before analysis; use `metadata_files.schema` / `metadata_files.readme` to interpret `field_<id>` columns.
 - Do not invent `auto_expand_pages`
 - Do not invent `max_rows`
 

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

@@ -28,11 +28,12 @@ Result reading order:
 1. `record_access.complete`
 2. `record_access.safe_for_final_conclusion`
 3. `record_access.files[].local_path`
-4. Python outputs
-5. `record_access.fields`
-6. `record_access.warnings`
+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.
+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/src/qingflow_mcp/response_trim.py

@@ -455,11 +455,13 @@ def _trim_record_access(payload: JSONObject) -> None:
         "app_key",
         "view_id",
         "format",
+        "local_dir",
         "row_count",
         "complete",
         "truncated",
         "safe_for_final_conclusion",
         "files",
+        "metadata_files",
         "fields",
         "warnings",
         "verification",

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.
 
@@ -74,7 +76,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 `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.
 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

@@ -602,7 +602,7 @@ class RecordTools(ToolBase):
                             ),
                         }
                     )
-                browse_scope = self._build_browse_write_scope(
+                browse_scope = self._build_browse_read_scope(
                     profile,
                     context,
                     app_key,
@@ -1848,25 +1848,20 @@ 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(
+            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
@@ -1932,6 +1927,7 @@ class RecordTools(ToolBase):
             current_page = 1
             has_more = False
             reported_total: int | None = None
+            created_at = datetime.now(UTC).isoformat()
             try:
                 while True:
                     if used_list_type is None:
@@ -1948,7 +1944,7 @@ class RecordTools(ToolBase):
                                     query_key=None,
                                     match_rules=match_rules,
                                     sorts=sort_rules,
-                                    search_que_ids=primary_search_que_ids,
+                                    search_que_ids=None,
                                     list_type=candidate_list_type,
                                 )
                                 used_list_type = None if view_selection is not None else candidate_list_type
@@ -1975,7 +1971,7 @@ class RecordTools(ToolBase):
                             query_key=None,
                             match_rules=match_rules,
                             sorts=sort_rules,
-                            search_que_ids=primary_search_que_ids,
+                            search_que_ids=None,
                             list_type=used_list_type,
                         )
                     page_rows = page.get("list")
@@ -1995,34 +1991,6 @@ 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, []))
                     if not has_more:
@@ -2049,6 +2017,25 @@ class RecordTools(ToolBase):
             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,
+                "list_type_used": used_list_type,
+            }
+            metadata_files = _write_record_access_metadata_files(
+                run_dir=run_dir,
+                created_at=created_at,
+                app_key=app_key,
+                view_route=view_route,
+                row_count=row_count,
+                complete=complete,
+                safe_for_final_conclusion=safe_for_final_conclusion,
+                files=files,
+                fields=fields_payload,
+                warnings=warnings,
+                verification=verification_payload,
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -2057,18 +2044,16 @@ class RecordTools(ToolBase):
                 "app_key": app_key,
                 "view_id": view_route.view_id,
                 "format": "csv",
+                "local_dir": str(run_dir),
                 "row_count": row_count,
                 "complete": complete,
                 "truncated": not complete,
                 "safe_for_final_conclusion": safe_for_final_conclusion,
                 "files": files,
-                "fields": [_record_access_field_payload(field) for field in selected_fields],
+                "metadata_files": metadata_files,
+                "fields": fields_payload,
                 "warnings": warnings,
-                "verification": {
-                    **_view_filter_verification_payload(view_route),
-                    "reported_total": reported_total,
-                    "list_type_used": used_list_type,
-                },
+                "verification": verification_payload,
                 "request_route": self._request_route_payload(context),
             }
 
@@ -7409,6 +7394,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))
@@ -7451,6 +7469,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,
@@ -9520,6 +9612,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],
@@ -11277,6 +11407,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)
@@ -11503,6 +11665,133 @@ def _record_access_field_payload(field: FormField) -> JSONObject:
     }
 
 
+def _write_record_access_metadata_files(
+    *,
+    run_dir: Path,
+    created_at: str,
+    app_key: str,
+    view_route: AccessibleViewRoute,
+    row_count: int,
+    complete: bool,
+    safe_for_final_conclusion: bool,
+    files: list[JSONObject],
+    fields: list[JSONObject],
+    warnings: list[JSONObject],
+    verification: JSONObject,
+) -> JSONObject:
+    schema_path = run_dir / "schema.json"
+    readme_path = run_dir / "README.md"
+    schema_payload: JSONObject = {
+        "created_at": created_at,
+        "app_key": app_key,
+        "view_id": view_route.view_id,
+        "view_name": view_route.name,
+        "view_type": view_route.view_type,
+        "format": "csv",
+        "row_count": row_count,
+        "complete": complete,
+        "truncated": not complete,
+        "safe_for_final_conclusion": safe_for_final_conclusion,
+        "files": files,
+        "fields": fields,
+        "warnings": warnings,
+        "verification": verification,
+        "csv_columns": ["record_id"] + [str(field["column_name"]) for field in fields if field.get("column_name")],
+    }
+    schema_path.write_text(json.dumps(schema_payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    readme_path.write_text(
+        _record_access_readme(
+            created_at=created_at,
+            app_key=app_key,
+            view_route=view_route,
+            row_count=row_count,
+            complete=complete,
+            safe_for_final_conclusion=safe_for_final_conclusion,
+            files=files,
+            fields=fields,
+            warnings=warnings,
+        ),
+        encoding="utf-8",
+    )
+    return {
+        "schema": str(schema_path),
+        "readme": str(readme_path),
+    }
+
+
+def _record_access_readme(
+    *,
+    created_at: str,
+    app_key: str,
+    view_route: AccessibleViewRoute,
+    row_count: int,
+    complete: bool,
+    safe_for_final_conclusion: bool,
+    files: list[JSONObject],
+    fields: list[JSONObject],
+    warnings: list[JSONObject],
+) -> str:
+    lines = [
+        "# Qingflow Record Access",
+        "",
+        f"- Created at: {created_at}",
+        f"- App key: `{app_key}`",
+        f"- View: {view_route.name} (`{view_route.view_id}`)",
+        f"- Format: CSV",
+        f"- Rows: {row_count}",
+        f"- Complete: {str(complete).lower()}",
+        f"- Safe for final conclusion: {str(safe_for_final_conclusion).lower()}",
+        "",
+        "## Data Files",
+        "",
+    ]
+    if files:
+        for file_info in files:
+            local_path = _normalize_optional_text(file_info.get("local_path")) or ""
+            part = file_info.get("part")
+            file_rows = file_info.get("row_count")
+            lines.append(f"- `{Path(local_path).name}`: part {part}, {file_rows} rows")
+    else:
+        lines.append("- No CSV shard files were written because the query returned 0 rows.")
+    lines.extend(
+        [
+            "",
+            "## Columns",
+            "",
+            "| CSV column | Field ID | Title | Type |",
+            "|---|---:|---|---|",
+            "| `record_id` | - | Record ID | record_id |",
+        ]
+    )
+    for field in fields:
+        column_name = _markdown_escape(str(field.get("column_name", "")))
+        field_id = field.get("field_id", "")
+        title = _markdown_escape(str(field.get("title", "")))
+        field_type = _markdown_escape(str(field.get("type", "")))
+        lines.append(f"| `{column_name}` | {field_id} | {title} | {field_type} |")
+    if warnings:
+        lines.extend(["", "## Warnings", ""])
+        for warning in warnings:
+            code = _normalize_optional_text(warning.get("code")) or "WARNING"
+            message = _normalize_optional_text(warning.get("message")) or ""
+            lines.append(f"- `{code}`: {message}")
+    lines.extend(
+        [
+            "",
+            "## Usage Notes",
+            "",
+            "- Use `records-*.csv` for Python or pandas processing; column names are stable and field-id based.",
+            "- Use `schema.json` or this README to map `field_<field_id>` columns back to Qingflow field titles and types.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _markdown_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ")
+
+
 def _record_access_field_type(field: FormField) -> str:
     if field.que_type in DATE_QUE_TYPES:
         return "datetime"