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

package/src/qingflow_mcp/response_trim.py

@@ -57,6 +57,13 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict
     if not isinstance(payload, dict):
         return payload
     if _looks_like_failure_payload(payload):
+        status = str(payload.get("status") or "").lower()
+        if tool_name in {"user:record_insert", "user:record_update"} and status in {
+            "blocked",
+            "needs_confirmation",
+            "partial_success",
+        }:
+            return trim_success_response(tool_name, payload)
         return _trim_returned_failure(payload)
     return trim_success_response(tool_name, payload)
 
@@ -65,7 +72,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)
@@ -137,7 +147,7 @@ def _looks_like_failure_payload(payload: dict[str, Any]) -> bool:
     if payload.get("ok") is False:
         return True
     status = str(payload.get("status") or "").lower()
-    return status in {"failed", "blocked", "verification_failed"}
+    return status in {"failed", "blocked"}
 
 
 def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
@@ -365,6 +375,9 @@ def _trim_record_write(payload: JSONObject) -> None:
     data = payload.get("data")
     if not isinstance(data, dict):
         return
+    if payload.get("mode") == "batch" or data.get("mode") == "batch":
+        _trim_record_write_batch(payload, data)
+        return
     data.pop("debug", None)
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
@@ -394,7 +407,48 @@ def _trim_record_write(payload: JSONObject) -> None:
             data.pop(key, None)
 
 
+def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
+    data.pop("items", None)
+    data.pop("debug", None)
+    for key in ("summary", "created_record_ids", "app_key", "mode"):
+        if data.get(key) in (None, [], {}, ""):
+            data.pop(key, None)
+    items = payload.get("items")
+    if isinstance(items, list):
+        payload["items"] = [
+            _pick(
+                item,
+                (
+                    "index",
+                    "row_number",
+                    "status",
+                    "record_id",
+                    "apply_id",
+                    "write_executed",
+                    "verification_status",
+                    "safe_to_retry",
+                    "failed_fields",
+                    "confirmation_requests",
+                    "blockers",
+                    "error",
+                    "warnings",
+                    "resource",
+                    "verification",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+    for key in ("items", "created_record_ids"):
+        value = payload.get(key)
+        if value in (None, [], {}, ""):
+            payload.pop(key, 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 +471,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 +619,43 @@ 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:
+    compact: dict[str, Any] = {}
+    for key in (
+        "ok",
+        "status",
+        "app_key",
+        "view_id",
+        "format",
+        "local_dir",
+        "row_count",
+        "complete",
+        "truncated",
+        "safe_for_final_conclusion",
+        "files",
+        "fields",
+        "warnings",
+        "verification",
+        "scope",
+    ):
+        value = payload.get(key)
+        if value is not None:
+            compact[key] = value
+    payload.clear()
+    payload.update(compact)
 
 
 def _trim_record_analyze(payload: JSONObject) -> None:
@@ -567,6 +778,19 @@ def _compact_schema_field(item: Any, *, template_map: dict[str, Any] | None) ->
         compact["required"] = bool(item.get("required"))
     if template_map is not None and isinstance(title, str) and title in template_map:
         compact["template"] = template_map.get(title)
+    for key in (
+        "format_hint",
+        "example_value",
+        "linkage",
+        "may_become_required",
+        "activation_sources",
+        "requirement_reason",
+        "accepts_natural_input",
+        "requires_upload",
+    ):
+        value = item.get(key)
+        if value not in (None, [], {}, ""):
+            compact[key] = value
     candidate_hint = item.get("candidate_hint")
     if isinstance(candidate_hint, dict):
         compact["candidate_hint"] = candidate_hint
@@ -783,6 +1007,7 @@ _register_policy(
 _register_policy((USER_DOMAIN,), ("record_insert", "record_update"), _trim_record_write)
 _register_policy((USER_DOMAIN,), ("record_get",), _trim_record_get)
 _register_policy((USER_DOMAIN,), ("record_list",), _trim_record_list)
+_register_policy((USER_DOMAIN,), ("record_access",), _trim_record_access)
 _register_policy((USER_DOMAIN,), ("record_analyze",), _trim_record_analyze)
 _register_policy((USER_DOMAIN,), ("record_code_block_run",), _trim_code_block_run)
 _register_policy((USER_DOMAIN,), ("task_list",), _trim_task_list)

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:
 
@@ -102,17 +104,18 @@ Analysis answers must include concrete numbers. When applicable, include percent
 ## Record CRUD Path
 
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
+`record_insert_schema_get -> record_insert(items)`
 `record_update_schema_get -> record_update`
 `record_list / record_get -> record_delete`
 `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
 
-- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
 - `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
@@ -121,10 +124,14 @@ 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.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Code Block Path

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_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.
 
 ## 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_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.
@@ -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` / 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.
 
@@ -70,16 +72,19 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 
 ## 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 this DSL shape:
+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.
 
-- `dimensions`: `{{field_id, alias, bucket}}`
-- `metrics`: `{{op, field_id, alias}}`
-- `filters`: `{{field_id, op, value}}`
-- `sort`: `{{by, order}}`
+Use this data-access DSL shape:
+
+- `columns`: `[{{field_id}}]`
+- `where`: `[{{field_id, op, value}}]`
+- `order_by`: `[{{field_id, direction}}]`
 
 Important key rules:
 
@@ -89,12 +94,16 @@ Important key rules:
 - Do **not** use `aggregation`
 - Do **not** use `operator`
 
+`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.
 
 ## Record CRUD Path
 
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
+`record_insert_schema_get -> record_insert(items)`
 `record_update_schema_get -> record_update`
 `record_list / record_get -> record_delete`
 `record_code_block_schema_get -> record_code_block_run`
@@ -102,11 +111,12 @@ 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
 
-- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
 - `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
@@ -115,10 +125,14 @@ 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.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - When candidate browsing must match a real update/write scope, pass `record_id`, `workflow_node_id`, and any pending `fields` context to the candidate tool; otherwise the candidate result is only a static applicant-node preview.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
@@ -146,9 +160,12 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 ## Export Path
 
+Use export only when the user explicitly asks to export/download/generate an Excel or export file.
+
 `view_get -> record_export_start -> record_export_status_get -> record_export_get`
 
 - `record_export_direct` is the one-shot path that starts export, waits, downloads locally, and still returns remote download links.
+- Do not use `record_export_direct` as the default analysis path; use `record_access -> Python` instead.
 - Export v1 supports record views only and follows the same public `view_id` semantics as `record_list`.
 - `record_export_start` / `record_export_direct` support frontend-like row selection:
   - omit `record_ids` to export all rows in the selected view