@qingflow-tech/qingflow-app-user-mcp 1.0.4 → 1.0.6

package/skills/qingflow-record-analysis/references/data-access-playbook.md

@@ -0,0 +1,106 @@
+# Data Access Playbook
+
+This file is the operational state machine for `record_access`.
+
+## Required Sequence
+
+1. `app_get`
+2. choose `view_id` from `accessible_views`
+3. `record_browse_schema_get(app_key, view_id)`
+4. build `record_access.columns / where / order_by` from field ids
+5. run `record_access`
+6. read every CSV shard with Python
+
+Do not call `record_access` with field titles, guessed ids, page controls, row limits, or profile.
+CSV columns are readable and field-id anchored, for example `项目状态__field_343283094`; do not look for extra `schema.json` or README files.
+
+## Finding `record_access`
+
+`record_access` can be available as an MCP tool or as a CLI subcommand. If the MCP surface does not show a top-level `record_access` tool, look under the Qingflow CLI record group before choosing any other path:
+
+```bash
+qingflow record --help
+qingflow record access --help
+```
+
+The CLI call is:
+
+```bash
+qingflow record access \
+  --app-key APP_KEY \
+  --view-id VIEW_ID \
+  --columns-file columns.json \
+  --where-file where.json \
+  --order-by-file order_by.json \
+  --json
+```
+
+This is the same analysis path: it writes CSV shards and metadata for Python. Do not replace it with list browsing, export, QingBI, or aggregate helpers just because the MCP tool is not visible.
+
+## Request Patterns
+
+### Count or distribution
+
+Fetch the grouping field and any time/business filter field.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "view_id": "system:all",
+  "columns": [{ "field_id": 18 }],
+  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
+  "order_by": []
+}
+```
+
+### Trend
+
+Fetch the date/time field plus metric fields.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "view_id": "system:all",
+  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
+  "where": [{ "field_id": 2, "op": "between", "value": ["2026-01-01", "2026-12-31"] }],
+  "order_by": [{ "field_id": 2, "direction": "asc" }]
+}
+```
+
+### Ratio
+
+If numerator and denominator use different filters, run separate `record_access` calls. Only compute the ratio after both source datasets are complete and compatible.
+
+## Status Decisions
+
+| Status | Meaning | Agent action |
+|---|---|---|
+| `success` + `safe_for_final_conclusion=true` | Full retrieved scope is reliable | Give final conclusion |
+| `needs_scope` | Tool refused large unbounded scan, no CSV | Ask for scope or retry with explicit period/business filter |
+| `partial` | Some CSV files written, but not full data | Give only subset observation |
+| `complete=false` | Not all requested data is available | Do not present full-population conclusion |
+| `truncated=true` | Tool had to stop before full scope | Disclose and narrow scope |
+
+## `needs_scope` Recovery
+
+Use the returned `scope` object:
+
+- `reported_total`: explain why scope is needed
+- `suggested_time_fields`: choose likely date fields
+- `recommended_where_examples`: reuse if they match the user request
+
+If the user already provided a concrete month/quarter/year, retry with that period. If no business boundary is available, ask one short clarification.
+
+## `partial` Recovery
+
+You may read the files, but must label output as partial:
+
+- say which files/rows were analyzed
+- do not use `全部`, `所有`, `整体`, or `全量`
+- suggest narrowing time or business scope before final conclusion
+
+## View Scope
+
+For custom views, the result is scoped to that saved view. If `verification.view_filter_verified=false`, disclose that the saved-filter scope could not be fully verified.
+
+For board/gantt views, switch to a table-style view or `system:all` plus explicit filters.

package/skills/qingflow-record-analysis/references/pandas-recipes.md

@@ -0,0 +1,172 @@
+# Pandas Recipes
+
+Use Python to read returned CSV shards. Never paste raw CSV into the model context.
+
+## Load All Shards
+
+```python
+import pandas as pd
+
+files = [
+    "/absolute/path/records-0001.csv",
+    # include every record_access.files[].local_path
+]
+
+frames = [pd.read_csv(path, dtype=str, keep_default_na=False) for path in files]
+df = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+
+# Columns are readable and field-id anchored, e.g. 项目状态__field_343283094.
+fields = []  # optionally paste record_access.fields here if you need field-id metadata
+field_by_id = {int(item["field_id"]): item for item in fields if "field_id" in item}
+title_by_col = {item["column_name"]: item["title"] for item in fields if item.get("column_name")}
+```
+
+## Field Quality Profile
+
+Run this before choosing final grouping dimensions.
+
+```python
+def field_quality(frame: pd.DataFrame, *, date_col: str | None = None) -> pd.DataFrame:
+    rows = []
+    for col in frame.columns:
+        blank = frame[col].astype(str).eq("")
+        item = {
+            "column": col,
+            "row_count": len(frame),
+            "blank_count": int(blank.sum()),
+            "blank_rate": float(blank.mean()) if len(frame) else 0.0,
+            "distinct_count": int(frame[col].replace("", pd.NA).nunique(dropna=True)),
+        }
+        rows.append(item)
+    quality = pd.DataFrame(rows).sort_values(["blank_rate", "distinct_count"], ascending=[False, False])
+    if date_col and date_col in frame.columns:
+        tmp = frame.copy()
+        tmp["_period"] = pd.to_datetime(tmp[date_col], errors="coerce").dt.to_period("M").astype(str)
+        period_quality = []
+        for col in frame.columns:
+            if col == date_col:
+                continue
+            by_period = tmp.groupby("_period")[col].apply(lambda s: float(s.astype(str).eq("").mean()))
+            period_quality.append({"column": col, "max_period_blank_rate": float(by_period.max()) if len(by_period) else 0.0})
+        quality = quality.merge(pd.DataFrame(period_quality), on="column", how="left")
+    return quality
+```
+
+Quality gates:
+
+- `blank_rate > 0.4`: do not use as the primary conclusion dimension.
+- `max_period_blank_rate > 0.8`: do not use for period comparison.
+- Very high `distinct_count` fields are usually identifiers or descriptions, not grouping dimensions.
+- High-missing dimensions may still be reported as `已填写样本观察`.
+
+## Column Selection
+
+Prefer exact readable CSV columns. Use suffix matching only when you need to address a field id programmatically.
+
+```python
+def col_by_field_id(frame, field_id: int) -> str:
+    suffix = f"__field_{field_id}"
+    matches = [col for col in frame.columns if col.endswith(suffix)]
+    if not matches:
+        raise KeyError(f"field_id not in CSV: {field_id}")
+    return matches[0]
+```
+
+## Count Distribution
+
+```python
+col = "项目状态__field_18"
+quality = field_quality(df)
+blank_rate = quality.loc[quality["column"].eq(col), "blank_rate"].iloc[0]
+if blank_rate > 0.4:
+    print(f"Use only as filled-sample observation: {col} blank_rate={blank_rate:.1%}")
+dist = (
+    df[col]
+    .replace("", pd.NA)
+    .fillna("未填写")
+    .value_counts(dropna=False)
+    .rename_axis("group")
+    .reset_index(name="count")
+)
+dist["share"] = dist["count"] / dist["count"].sum()
+```
+
+## Numeric Aggregation
+
+```python
+group_col = "项目状态__field_18"
+amount_col = "金额__field_25"
+tmp = df.copy()
+tmp[amount_col] = (
+    tmp[amount_col]
+    .str.replace(",", "", regex=False)
+    .str.replace("￥", "", regex=False)
+    .pipe(pd.to_numeric, errors="coerce")
+)
+summary = (
+    tmp.groupby(group_col, dropna=False)[amount_col]
+    .agg(count="count", total="sum", avg="mean")
+    .reset_index()
+    .sort_values("total", ascending=False)
+)
+```
+
+## Date Trend
+
+```python
+date_col = "申请时间__field_2"
+tmp = df.copy()
+tmp[date_col] = pd.to_datetime(tmp[date_col], errors="coerce")
+tmp = tmp.dropna(subset=[date_col])
+tmp["month"] = tmp[date_col].dt.to_period("M").astype(str)
+trend = tmp.groupby("month").size().reset_index(name="count")
+```
+
+## Year-Over-Year Month Comparison
+
+```python
+date_col = "申请时间__field_2"
+tmp = df.copy()
+tmp[date_col] = pd.to_datetime(tmp[date_col], errors="coerce")
+tmp = tmp.dropna(subset=[date_col])
+tmp["year"] = tmp[date_col].dt.year
+tmp["month"] = tmp[date_col].dt.month
+monthly = tmp.groupby(["year", "month"]).size().reset_index(name="count")
+```
+
+## Ratio
+
+```python
+numerator = len(df[df["项目状态__field_18"].eq("已成交")])
+denominator = len(df)
+ratio = numerator / denominator if denominator else None
+```
+
+Always report numerator and denominator.
+
+## Multi-Select Cells
+
+If values are serialized with delimiters, inspect samples first. For simple comma-separated values:
+
+```python
+col = "标签__field_30"
+exploded = (
+    df.assign(_value=df[col].str.split(","))
+    .explode("_value")
+)
+exploded["_value"] = exploded["_value"].str.strip()
+multi_dist = exploded["_value"].value_counts().reset_index(name="count")
+```
+
+## Business Mapping
+
+```python
+mapping = {
+    "烈焰组": "北斗部门",
+    "飓风组": "北斗部门",
+}
+department_col = "部门__field_40"
+df["department_normalized"] = df[department_col].replace(mapping)
+```
+
+State the mapping in the final answer.

package/skills/qingflow-record-analysis/references/report-format.md

@@ -0,0 +1,76 @@
+# Report Format
+
+Use this for user-facing analysis reports.
+
+## Short Answer
+
+```text
+结论：
+- ...
+
+关键数据：
+- 指标 A：...
+- 指标 B：...
+
+口径与范围：
+- 应用 / 视图：...
+- 时间范围：...
+- 字段：...
+- 字段质量：...
+- 业务映射：...
+- 数据完整性：...
+
+限制：
+- ...
+```
+
+## Detailed Report
+
+```text
+1. 分析范围
+   - app / view
+   - time range
+   - filters
+   - rows analyzed
+
+2. 核心结论
+   - concrete numbers first
+   - no vague adjectives without numbers
+
+3. 分项数据
+   - distribution / trend / ranking tables
+   - percentages with numerator and denominator
+
+4. 解释与建议
+   - separate facts from hypotheses
+
+5. 口径与可信度
+   - fields used
+   - field-quality gates and downgraded dimensions
+   - mapping rules
+   - completeness
+   - partial or unverified scope warnings
+```
+
+## Wording Rules
+
+- Use `全量可信结论` only when the accessed scope is complete and safe.
+- Use `初步观察` for partial or unverified data.
+- Do not say `全部`, `所有`, `整体`, or `完整` when `safe_for_final_conclusion=false`.
+- For ratios, always show `numerator / denominator`.
+- For comparisons, show both periods' absolute values and the delta.
+
+## Comparison Template
+
+```text
+今年5月 vs 去年5月：
+- 记录数：今年 X，去年 Y，变化 +Z（+P%）
+- 金额：今年 X，去年 Y，变化 +Z（+P%）
+- 结构变化：...
+
+口径：
+- 时间字段：...
+- 部门字段：...
+- 部门映射：...
+- 数据完整性：...
+```

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

@@ -9,7 +9,9 @@ metadata:
 
 ## Default Path
 
-`record_insert_schema_get -> (optional candidate lookup / confirmation) -> record_insert`
+`record_insert_schema_get -> record_insert(items) -> optional record_get/readback`
+
+Default to batch-shaped insert. A single new record is `items` with one row.
 
 ## Core Tools
 
@@ -25,19 +27,20 @@ metadata:
 2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
 3. Inside every field bucket, read field-level `linkage` first when present; it is the canonical static hint for linked visibility, reference-driven auto fill, or formula-driven fields
 4. Inside `optional_fields`, pay special attention to any field with `may_become_required=true`; these are writable fields that can become required when linked visibility or option-driven rules activate
-5. Build `fields` from the manually-supplied required/optional fields in that schema
+5. Build `items` as `[{"fields": {...}}]`, where each `fields` map uses field titles from the insert schema
 6. Treat `runtime_linked_required_fields` as required-but-not-directly-writable runtime/upstream dependencies, not as fields to hand-fill blindly
 7. For `linkage.kind=logic_visibility`, read `sources` as upstream trigger fields and treat `role=manual_input_after_activation` as "fill this only after the upstream condition is satisfied"
 8. For `linkage.kind=reference_fill`, prefer filling the source field first; treat target fields with `role=auto_fill_preferred` or `auto_fill_only` as reference-driven outputs rather than blind manual inputs
 9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
-10. If insert succeeds and readback shape matters, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`
+10. If insert succeeds and single-record detail/readback matters, prefer `record_get`; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
 11. Keep subtable payloads under the parent field as a row array
-12. Member / department / relation fields may accept natural strings directly
+12. Member / department / relation fields may accept natural strings directly, such as `"张三"`, `"直销部"`, or `"海军军医大学"`; do not pre-query ids by default
 13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
-14. Retry with explicit ids / objects only after the user confirms
+14. Retry failed rows only with explicit ids / objects after the user confirms
 15. Keep `verify_write=true` for production inserts
-16. If post-write readback consistency matters, prefer `record_get(..., output_profile="normalized")` and surface `normalized_ambiguous_fields` instead of pretending same-title columns are unambiguous
+16. If post-write detail context matters, read `record_get.fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy `data.normalized_record`
 17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
+18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
 
 ## Field Notes
 
@@ -51,11 +54,29 @@ metadata:
 - `linkage.affects_fields` lists downstream field titles that may change when this field changes
 - `linkage.role=auto_fill_only` means "normally do not hand-fill this unless the product explicitly requires it"
 - `requires_upload=true` means upload the file first, then write the returned value
+- `failed_fields[].next_action` tells the next repair step for that row
+
+## CLI Pattern
+
+Use a JSON array file:
+
+```bash
+qingflow record insert --app-key APP_KEY --items-file records.json --json
+```
+
+`records.json`:
+
+```json
+[
+  { "fields": { "客户名称": "测试客户", "负责人": "张三" } }
+]
+```
 
 ## Do Not
 
 - Do not skip `record_insert_schema_get`
 - Do not invent missing required fields
 - Do not flatten subtable leaf fields to the top level
-- Do not silently guess member / department / relation ids
+- Do not pre-query or silently guess member / department / relation ids when a natural string is enough
+- Do not retry a whole batch after `created_record_ids` is non-empty
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

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

@@ -34,7 +34,7 @@ metadata:
 12. Do not assume any arbitrary combination of writable fields will succeed; one single matched accessible view still has to cover the payload
 13. Do not look for any extra context bucket in update schema; lookup behavior stays inline on the field definitions themselves
 14. When update context feels unstable, trust `record_update_schema_get`'s route-aware matched-view result over guessed `view_id` or remembered UI scope
-15. If readback consistency matters, prefer `record_get(..., output_profile="normalized")` after the write and surface `normalized_ambiguous_fields` instead of hiding same-title conflicts
+15. If single-record detail/readback matters, prefer `record_get` after the write and read top-level `fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
 
 ## Do Not
 

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)
@@ -57,17 +63,27 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     list_parser.add_argument("--view-name", dest="legacy_view_name", help=argparse.SUPPRESS)
     list_parser.set_defaults(handler=_handle_list, format_hint="record_list")
 
+    access_parser = record_subparsers.add_parser("access", help="访问记录并写入本地 CSV 分片")
+    access_parser.add_argument("--app-key", required=True)
+    access_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
+    access_parser.add_argument("--columns-file")
+    access_parser.add_argument("--where-file")
+    access_parser.add_argument("--order-by-file")
+    access_parser.add_argument("--view-id", required=True)
+    access_parser.set_defaults(handler=_handle_access, format_hint="record_access")
+
     get = record_subparsers.add_parser("get", help="读取单条记录")
     get.add_argument("--app-key", required=True)
     get.add_argument("--record-id", required=True)
     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)
-    insert.add_argument("--fields-file", required=True)
+    insert.add_argument("--fields-file")
+    insert.add_argument("--items-file")
     insert.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
     insert.set_defaults(handler=_handle_insert, format_hint="")
 
@@ -86,7 +102,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")
@@ -122,6 +143,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:
@@ -216,14 +244,26 @@ 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,
     )
 
 
+def _handle_access(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_access(
+        profile=args.profile,
+        app_key=args.app_key,
+        columns=_columns(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"),
+        view_id=args.view_id,
+    )
+
+
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
     return context.record.record_get_public(
         profile=args.profile,
@@ -235,6 +275,23 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.items_file:
+        if args.fields_file:
+            raise_config_error(
+                "record insert batch mode does not accept --fields-file.",
+                fix_hint="Use `record insert --app-key APP_KEY --items-file ITEMS.json` for batch inserts.",
+            )
+        return context.record.record_insert_public(
+            profile=args.profile,
+            app_key=args.app_key,
+            items=require_list_arg(args.items_file, option_name="--items-file"),
+            verify_write=bool(args.verify_write),
+        )
+    if not args.fields_file:
+        raise_config_error(
+            "record insert requires --items-file or --fields-file.",
+            fix_hint="Prefer `record insert --app-key APP_KEY --items-file ITEMS.json`; use --fields-file only for legacy single inserts.",
+        )
     return context.record.record_insert_public(
         profile=args.profile,
         app_key=args.app_key,