@josephyan/qingflow-cli 1.0.9 → 1.0.11

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.0.9
+npm install @josephyan/qingflow-cli@1.0.11
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.0.9 qingflow
+npx -y -p @josephyan/qingflow-cli@1.0.11 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.9"
+version = "1.0.11"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,7 @@ dependencies = [
   "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "pypdf>=5.0,<6.0",
   "python-socketio[client]>=5.11,<6.0",
 ]
 

package/src/qingflow_mcp/backend_client.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from threading import Event
 from time import sleep
 from typing import Any
-from urllib.parse import urlsplit, urlunsplit
+from urllib.parse import urljoin, urlsplit, urlunsplit
 from uuid import uuid4
 
 import httpx
@@ -33,6 +33,15 @@ class BackendResponse:
     qf_response_version: str | None = None
 
 
+@dataclass(slots=True)
+class BackendBinaryResponse:
+    content: bytes
+    headers: dict[str, str]
+    http_status: int
+    final_url: str
+    redirected: bool
+
+
 class BackendClient:
     def __init__(self, timeout: float | None = None, client: httpx.Client | None = None) -> None:
         self._owns_client = client is None
@@ -290,6 +299,51 @@ class BackendClient:
             )
         return response.content
 
+    def download_binary_with_cookie(
+        self,
+        context: BackendRequestContext,
+        url: str,
+        *,
+        cookie_name: str,
+        headers: dict[str, str] | None = None,
+    ) -> BackendBinaryResponse:
+        qf_version, _source = self._resolve_qf_version(context.qf_version)
+        request_headers = {
+            "User-Agent": DEFAULT_USER_AGENT,
+            "Qf-Request-Id": context.qf_request_id or str(uuid4()),
+        }
+        if headers:
+            request_headers.update({key: value for key, value in headers.items() if value is not None})
+        cookie_parts = [f"{cookie_name}={context.token}"]
+        if qf_version:
+            cookie_parts.append(f"qfVersion={qf_version}")
+        request_headers["Cookie"] = "; ".join(cookie_parts)
+        try:
+            response = self._client.get(url, headers=request_headers, follow_redirects=False)
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        redirected = 300 <= response.status_code < 400 and bool(response.headers.get("location"))
+        if redirected:
+            redirect_headers = {key: value for key, value in request_headers.items() if key.lower() != "cookie"}
+            redirect_url = urljoin(str(response.url), response.headers["location"])
+            try:
+                response = self._client.get(redirect_url, headers=redirect_headers)
+            except httpx.RequestError as exc:
+                raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        return BackendBinaryResponse(
+            content=response.content,
+            headers=dict(response.headers),
+            http_status=response.status_code,
+            final_url=str(response.url),
+            redirected=redirected or bool(response.history) or str(response.url) != url,
+        )
+
     def request_multipart(
         self,
         method: str,

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

@@ -10,7 +10,11 @@ from .common import load_list_arg, load_object_arg, raise_config_error, require_
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("record", help="记录与表结构")
-    record_subparsers = parser.add_subparsers(dest="record_command", required=True)
+    record_subparsers = parser.add_subparsers(
+        dest="record_command",
+        required=True,
+        metavar="{schema,list,access,get,insert,update,delete,code-block-run}",
+    )
 
     schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
     schema.add_argument("--mode", dest="legacy_mode", help=argparse.SUPPRESS)
@@ -47,9 +51,11 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     list_parser.add_argument("--app-key", required=True)
     list_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
     list_parser.add_argument("--columns-file")
+    list_parser.add_argument("--query")
+    list_parser.add_argument("--query-field", dest="query_fields", action="append", type=int, default=[])
+    list_parser.add_argument("--query-fields-file")
     list_parser.add_argument("--where-file")
     list_parser.add_argument("--order-by-file")
-    list_parser.add_argument("--limit", type=int, default=20)
     list_parser.add_argument("--page", type=int, default=1)
     list_parser.add_argument("--view-id")
     list_parser.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
@@ -72,7 +78,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     get.add_argument("--column", dest="columns", action="append", type=int, default=[])
     get.add_argument("--columns-file")
     get.add_argument("--view-id")
-    get.set_defaults(handler=_handle_get, format_hint="")
+    get.set_defaults(handler=_handle_get, format_hint="record_get")
 
     insert = record_subparsers.add_parser("insert", help="新增记录")
     insert.add_argument("--app-key", required=True)
@@ -95,7 +101,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     delete.add_argument("--record-ids-file")
     delete.set_defaults(handler=_handle_delete, format_hint="")
 
-    analyze = record_subparsers.add_parser("analyze", help="分析记录数据")
+    analyze = record_subparsers.add_parser("analyze", help=argparse.SUPPRESS)
+    record_subparsers._choices_actions = [  # type: ignore[attr-defined]
+        action
+        for action in record_subparsers._choices_actions  # type: ignore[attr-defined]
+        if getattr(action, "dest", None) != "analyze"
+    ]
     analyze.add_argument("--app-key", required=True)
     analyze.add_argument("--dimensions-file")
     analyze.add_argument("--metrics-file")
@@ -131,6 +142,13 @@ def _columns(args: argparse.Namespace) -> list[Any]:
     return columns
 
 
+def _query_fields(args: argparse.Namespace) -> list[Any]:
+    query_fields: list[Any] = list(getattr(args, "query_fields", None) or [])
+    if getattr(args, "query_fields_file", None):
+        query_fields.extend(require_list_arg(args.query_fields_file, option_name="--query-fields-file"))
+    return query_fields
+
+
 def _handle_schema_root(args: argparse.Namespace, _context: CliContext) -> dict:
     mode = (args.legacy_mode or "").strip()
     if mode:
@@ -225,9 +243,10 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
         profile=args.profile,
         app_key=args.app_key,
         columns=_columns(args),
+        query=args.query,
+        query_fields=_query_fields(args),
         where=load_list_arg(args.where_file, option_name="--where-file"),
         order_by=load_list_arg(args.order_by_file, option_name="--order-by-file"),
-        limit=args.limit,
         page=args.page,
         view_id=args.view_id,
     )

package/src/qingflow_mcp/cli/formatters.py

@@ -183,7 +183,17 @@ def _format_app_get(result: dict[str, Any]) -> str:
 def _format_record_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 []
-    lines = [f"Returned Records: {len(items)}"]
+    lines: list[str] = []
+    lookup = result.get("lookup") if isinstance(result.get("lookup"), dict) else {}
+    if lookup:
+        lines.append("Lookup:")
+        lines.append(f"- query: {lookup.get('query')}")
+        lines.append(f"- confidence: {lookup.get('confidence')}")
+        lines.append(f"- next_action: {lookup.get('next_action')}")
+        lines.append(f"- total_count: {lookup.get('total_count')}")
+        lines.append(f"- returned_count: {lookup.get('returned_count')}")
+        lines.append(f"- truncated: {lookup.get('truncated')}")
+    lines.append(f"Returned Records: {len(items)}")
     for item in items[:10]:
         if isinstance(item, dict):
             lines.append(json.dumps(item, ensure_ascii=False))
@@ -224,6 +234,64 @@ def _format_record_access(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_get(result: dict[str, Any]) -> str:
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    app = result.get("app") if isinstance(result.get("app"), dict) else {}
+    view = result.get("view") if isinstance(result.get("view"), dict) else {}
+    fields = result.get("fields") if isinstance(result.get("fields"), list) else []
+    data_logs = result.get("data_logs") if isinstance(result.get("data_logs"), dict) else {}
+    workflow_logs = result.get("workflow_logs") if isinstance(result.get("workflow_logs"), dict) else {}
+    media_assets = result.get("media_assets") if isinstance(result.get("media_assets"), dict) else {}
+    media_items = media_assets.get("items") if isinstance(media_assets.get("items"), list) else []
+    downloaded_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    file_assets = result.get("file_assets") if isinstance(result.get("file_assets"), dict) else {}
+    file_items = file_assets.get("items") if isinstance(file_assets.get("items"), list) else []
+    downloaded_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    extracted_files = [
+        item
+        for item in downloaded_files
+        if isinstance(item.get("extraction"), dict) and item["extraction"].get("status") == "ok"
+    ]
+    associated_resources = result.get("associated_resources") if isinstance(result.get("associated_resources"), list) else []
+    unavailable_context = result.get("unavailable_context") if isinstance(result.get("unavailable_context"), list) else []
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"App: {app.get('app_name') or app.get('app_key') or '-'} ({app.get('app_key') or '-'})",
+        f"View: {view.get('name') or view.get('view_id') or '-'}",
+        f"Record: {record.get('title') or '-'} ({record.get('record_id') or '-'})",
+        f"Fields: {len(fields)}",
+        f"Data logs: {data_logs.get('status') or '-'} / loaded={data_logs.get('items_loaded')}",
+        f"Workflow logs: {workflow_logs.get('status') or '-'} / loaded={workflow_logs.get('items_loaded')}",
+        f"Media assets: {media_assets.get('status') or '-'} / downloaded={len(downloaded_media)} / failed={len(failed_media)}",
+        f"File assets: {file_assets.get('status') or '-'} / downloaded={len(downloaded_files)} / extracted={len(extracted_files)} / failed={len(failed_files)}",
+        f"Associated resources: {len(associated_resources)}",
+        f"Unavailable contexts: {len(unavailable_context)}",
+    ]
+    if media_assets.get("local_dir"):
+        lines.append(f"Media dir: {media_assets.get('local_dir')}")
+    if file_assets.get("local_dir"):
+        lines.append(f"File dir: {file_assets.get('local_dir')}")
+    if failed_media:
+        failure_counts: dict[str, int] = {}
+        for item in failed_media:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("Media failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    if failed_files:
+        failure_counts = {}
+        for item in failed_files:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("File failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    summary = result.get("summary") if isinstance(result.get("summary"), dict) else {}
+    if summary.get("text"):
+        lines.append(f"Summary: {summary.get('text')}")
+    _append_warnings(lines, result.get("warnings"))
+    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 []
@@ -724,6 +792,7 @@ _FORMATTERS = {
     "app_get": _format_app_get,
     "record_list": _format_record_list,
     "record_access": _format_record_access,
+    "record_get": _format_record_get,
     "task_list": _format_task_list,
     "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,

package/src/qingflow_mcp/public_surface.py

@@ -80,7 +80,7 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     ),
     PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze")),
+    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze"), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_access", ("record_access",), ("record", "access"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),

package/src/qingflow_mcp/response_trim.py

@@ -65,7 +65,10 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
     if not isinstance(payload, dict):
         return payload
     trimmed = deepcopy(payload)
-    _drop_top_keys(trimmed, COMMON_SUCCESS_DROP_TOP)
+    drop_keys = COMMON_SUCCESS_DROP_TOP
+    if tool_name == "user:record_get":
+        drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
+    _drop_top_keys(trimmed, drop_keys)
     transformer = SUCCESS_POLICY_BY_TOOL.get(tool_name or "")
     if transformer is not None:
         transformer(trimmed)
@@ -395,6 +398,9 @@ def _trim_record_write(payload: JSONObject) -> None:
 
 
 def _trim_record_get(payload: JSONObject) -> None:
+    if payload.get("fields") is not None or payload.get("semantic_context") is not None:
+        _trim_detail_context_record_get(payload)
+        return
     data = payload.get("data")
     if not isinstance(data, dict):
         return
@@ -417,22 +423,142 @@ def _trim_record_get(payload: JSONObject) -> None:
     payload["data"] = compact
 
 
+def _trim_detail_context_record_get(payload: JSONObject) -> None:
+    _trim_item_list(
+        payload,
+        "fields",
+        allowed=("field_id", "title", "type", "value", "display_value", "requested_focus", "asset_ids", "file_asset_ids"),
+    )
+    references = payload.get("references")
+    if isinstance(references, list):
+        compact_refs: list[JSONObject] = []
+        for item in references:
+            if not isinstance(item, dict):
+                continue
+            compact = _pick(
+                item,
+                (
+                    "field_id",
+                    "field_title",
+                    "target_app_key",
+                    "target_record_id",
+                    "target_title",
+                    "target_detail_completeness",
+                    "self_reference",
+                ),
+            )
+            target_fields = item.get("target_fields") if isinstance(item.get("target_fields"), list) else []
+            if target_fields:
+                compact["target_fields"] = [
+                    _pick(field, ("field_id", "title", "type", "value", "display_value", "asset_ids", "file_asset_ids"))
+                    for field in target_fields
+                    if isinstance(field, dict)
+                ]
+            compact_refs.append(compact)
+        payload["references"] = compact_refs
+    media_assets = payload.get("media_assets")
+    if isinstance(media_assets, dict):
+        compact_media = _pick(media_assets, ("status", "local_dir", "warnings"))
+        items = media_assets.get("items") if isinstance(media_assets.get("items"), list) else []
+        compact_media["items"] = [
+            _pick(
+                item,
+                (
+                    "asset_id",
+                    "kind",
+                    "source",
+                    "field_id",
+                    "field_title",
+                    "local_path",
+                    "access_status",
+                    "readable_by_agent",
+                    "mime_type",
+                    "size_bytes",
+                    "download_strategy",
+                    "storage_auth_type",
+                    "storage_cookie_prefix",
+                    "redirected",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+        payload["media_assets"] = compact_media
+    file_assets = payload.get("file_assets")
+    if isinstance(file_assets, dict):
+        compact_files = _pick(file_assets, ("status", "local_dir", "warnings"))
+        items = file_assets.get("items") if isinstance(file_assets.get("items"), list) else []
+        compact_files["items"] = [
+            _pick(
+                item,
+                (
+                    "file_asset_id",
+                    "media_asset_id",
+                    "kind",
+                    "source",
+                    "field_id",
+                    "field_title",
+                    "file_name",
+                    "local_path",
+                    "access_status",
+                    "readable_by_agent",
+                    "mime_type",
+                    "size_bytes",
+                    "download_strategy",
+                    "storage_auth_type",
+                    "storage_cookie_prefix",
+                    "redirected",
+                    "extraction",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+        payload["file_assets"] = compact_files
+    for key in ("data_logs", "workflow_logs"):
+        node = payload.get(key)
+        if not isinstance(node, dict):
+            continue
+        compact_node = _pick(
+            node,
+            (
+                "status",
+                "visible",
+                "reason",
+                "page",
+                "page_size",
+                "items_loaded",
+                "reported_total",
+                "has_more",
+                "complete",
+                "items",
+            ),
+        )
+        payload[key] = compact_node
+    associated_resources = payload.get("associated_resources")
+    if isinstance(associated_resources, list):
+        payload["associated_resources"] = [
+            _pick(item, ("type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "data_access"))
+            for item in associated_resources
+            if isinstance(item, dict)
+        ]
+    _drop_deep_keys(payload, {"raw", "debug"})
+
+
 def _trim_record_list(payload: JSONObject) -> None:
     data = payload.get("data")
     if not isinstance(data, dict):
         return
     pagination = data.get("pagination") if isinstance(data.get("pagination"), dict) else {}
-    returned_items = pagination.get("returned_items")
-    result_amount = pagination.get("result_amount")
-    limit = pagination.get("limit")
-    truncated = False
-    if isinstance(result_amount, int) and isinstance(returned_items, int):
+    returned_items = pagination.get("returned_count", pagination.get("returned_items"))
+    result_amount = pagination.get("total_count", pagination.get("result_amount"))
+    truncated = bool(pagination.get("truncated"))
+    if not truncated and isinstance(result_amount, int) and isinstance(returned_items, int):
         truncated = result_amount > returned_items
     compact_pagination = {
         "loaded": True,
-        "page_size": limit,
-        "fetched_pages": 1,
-        "reported_total": result_amount,
+        "returned_count": returned_items,
+        "total_count": result_amount,
         "truncated": truncated,
     }
     selection = data.get("selection") if isinstance(data.get("selection"), dict) else {}
@@ -445,6 +571,17 @@ def _trim_record_list(payload: JSONObject) -> None:
     if view:
         compact["view"] = _pick(view, ("view_id", "name"))
     payload["data"] = compact
+    lookup = payload.get("lookup") if isinstance(payload.get("lookup"), dict) else {}
+    if lookup:
+        payload["lookup"] = {
+            "mode": lookup.get("mode"),
+            "query": lookup.get("query"),
+            "total_count": lookup.get("total_count", lookup.get("reported_total")),
+            "returned_count": lookup.get("returned_count"),
+            "truncated": lookup.get("truncated"),
+            "confidence": lookup.get("confidence"),
+            "next_action": lookup.get("next_action"),
+        }
 
 
 def _trim_record_access(payload: JSONObject) -> None:
@@ -461,7 +598,6 @@ def _trim_record_access(payload: JSONObject) -> None:
         "truncated",
         "safe_for_final_conclusion",
         "files",
-        "metadata_files",
         "fields",
         "warnings",
         "verification",

package/src/qingflow_mcp/server.py

@@ -50,7 +50,7 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
-If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
 `view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
 ## Schema-First Rule
@@ -58,7 +58,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 Call `record_insert_schema_get` before `record_insert`.
 Call `record_update_schema_get` before `record_update`.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -68,7 +68,8 @@ 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`.
 `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` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema.
 `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.
 
@@ -78,16 +79,17 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 
 ## Analytics Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_analyze`
+`app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python`
 
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
+Use `record_access` to write local CSV shard files for analysis, then use Python to compute counts, rankings, ratios, trends, and final conclusions.
+
 Use this DSL shape:
 
-- `dimensions`: `{{field_id, alias, bucket}}`
-- `metrics`: `{{op, field_id, alias}}`
-- `filters`: `{{field_id, op, value}}`
-- `sort`: `{{by, order}}`
+- `columns`: `[{{field_id}}]`
+- `where`: `[{{field_id, op, value}}]`
+- `order_by`: `[{{field_id, direction}}]`
 
 Important key rules:
 
@@ -108,6 +110,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `record_code_block_schema_get -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
+- Use `record_list(query=..., query_fields=[{{field_id}}])` for fuzzy single-record lookup, then follow `lookup.next_action`; `query_fields` is search scope and `columns` is display shape.
 - Use `where` items as `{{field_id, op, value}}`
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
@@ -121,7 +124,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
 - `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
 - `record_delete` deletes by `record_id` or `record_ids`.
-- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+- `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
+- When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.

package/src/qingflow_mcp/server_app_user.py

@@ -33,7 +33,7 @@ def build_user_server() -> FastMCP:
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
-If an accessible view has `analysis_supported=false`, do not use it for `record_access`, `record_list`, or `record_analyze`. `boardView` and `ganttView` are special UI views, not data-access targets.
+If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
 `view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
 ## Shared Helper
@@ -49,7 +49,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 Call `record_insert_schema_get` before `record_insert`.
 Call `record_update_schema_get` before `record_update`.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, `record_get`, or `record_analyze`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -61,7 +61,7 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 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 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.
+`record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` 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.
@@ -76,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 `fields[]` and the same-directory `metadata_files.schema` / `metadata_files.readme` to map stable `field_<id>` CSV columns back to titles and types.
+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`. CSV columns are readable and field-id anchored, such as `项目状态__field_343283094`, and `fields[]` is the compact metadata source.
 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.
 
@@ -94,7 +94,9 @@ Important key rules:
 - Do **not** use `aggregation`
 - Do **not** use `operator`
 
-`record_analyze` is a lightweight non-default statistics helper. Use it only when a compact grouped result is clearly sufficient. `record_list` is for browsing and sample checks, not final analysis conclusions.
+`record_list` is for browsing and sample checks, not final analysis conclusions.
+For fuzzy single-record lookup, use `record_list(query=..., query_fields=[{{field_id}}])` to find candidates, read `lookup.next_action`, and only call `record_get` after one candidate is clear.
+`record_list.query_fields` maps to backend full-text search scope (`searchQueIds`); `record_list.columns` only controls displayed fields.
 
 Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
 
@@ -109,6 +111,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `portal_get -> view_get -> record_list`
 
 - Use `columns` as `[{{field_id}}]`
+- Use `query` plus optional `query_fields` when the user provides fuzzy record-identifying text
 - Use `where` items as `{{field_id, op, value}}`
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
@@ -122,7 +125,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
 - `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
 - `record_delete` deletes by `record_id` or `record_ids`.
-- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+- `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
+- When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.