qingflow-mcp 0.3.15 → 0.3.16

package/dist/server.js

@@ -63,7 +63,9 @@ const ADAPTIVE_TARGET_PAGE_MS = toPositiveInt(process.env.QINGFLOW_ADAPTIVE_TARG
 const MAX_LIST_ITEMS_BYTES = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_BYTES) ?? 400000;
 const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS) ?? 18000;
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
-const SERVER_VERSION = "0.3.14";
+const WAIT_RESULT_DEFAULT_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_TIMEOUT_MS) ?? 5000;
+const WAIT_RESULT_POLL_INTERVAL_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_POLL_INTERVAL_MS) ?? 500;
+const SERVER_VERSION = "0.3.16";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -174,6 +176,7 @@ const queryContractFields = {
     output_profile: outputProfileSchema.optional(),
     completeness: completenessSchema.optional(),
     evidence: z.record(z.unknown()).optional(),
+    resolved_mappings: z.record(z.unknown()).optional(),
     error_code: z.null().optional(),
     fix_hint: z.null().optional(),
     next_page_token: z.string().nullable().optional()
@@ -484,6 +487,8 @@ const createInputPublicSchema = z
     app_key: publicStringSchema,
     user_id: publicStringSchema.optional(),
     force_refresh_form: z.boolean().optional(),
+    wait_result: z.boolean().optional(),
+    wait_timeout_ms: z.number().int().positive().max(20000).optional(),
     apply_user: publicApplyUserSchema.optional(),
     answers: z.array(publicAnswerInputSchema).optional(),
     fields: z.record(z.unknown()).optional()
@@ -493,6 +498,8 @@ const createInputSchema = z
     app_key: z.string().min(1),
     user_id: z.string().min(1).optional(),
     force_refresh_form: z.boolean().optional(),
+    wait_result: z.boolean().optional(),
+    wait_timeout_ms: z.number().int().positive().max(20000).optional(),
     apply_user: z
         .object({
         email: z.string().optional(),
@@ -512,6 +519,9 @@ const createSuccessOutputSchema = z.object({
     data: z.object({
         request_id: z.string().nullable(),
         apply_id: z.union([z.string(), z.number(), z.null()]),
+        resolved: z.boolean().optional(),
+        timed_out: z.boolean().optional(),
+        operation_result: z.unknown().optional(),
         async_hint: z.string()
     }),
     meta: apiMetaSchema
@@ -523,6 +533,8 @@ const updateInputPublicSchema = z
     app_key: publicStringSchema.optional(),
     user_id: publicStringSchema.optional(),
     force_refresh_form: z.boolean().optional(),
+    wait_result: z.boolean().optional(),
+    wait_timeout_ms: z.number().int().positive().max(20000).optional(),
     answers: z.array(publicAnswerInputSchema).optional(),
     fields: z.record(z.unknown()).optional()
 });
@@ -532,6 +544,8 @@ const updateInputSchema = z
     app_key: z.string().min(1).optional(),
     user_id: z.string().min(1).optional(),
     force_refresh_form: z.boolean().optional(),
+    wait_result: z.boolean().optional(),
+    wait_timeout_ms: z.number().int().positive().max(20000).optional(),
     answers: z.array(answerInputSchema).optional(),
     fields: z.record(fieldValueSchema).optional()
 })
@@ -542,6 +556,10 @@ const updateSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         request_id: z.string().nullable(),
+        apply_id: z.union([z.string(), z.number(), z.null()]).optional(),
+        resolved: z.boolean().optional(),
+        timed_out: z.boolean().optional(),
+        operation_result: z.unknown().optional(),
         async_hint: z.string()
     }),
     meta: apiMetaSchema
@@ -592,7 +610,7 @@ const queryInputPublicSchema = z
     max_rows: z.number().int().positive().max(200).optional(),
     max_items: z.number().int().positive().max(200).optional(),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
-    select_columns: z.array(publicFieldSelectorSchema).min(1).max(MAX_COLUMN_LIMIT),
+    select_columns: z.array(publicFieldSelectorSchema).min(1).max(MAX_COLUMN_LIMIT).optional(),
     include_answers: z.boolean().optional(),
     amount_column: publicFieldSelectorSchema.optional(),
     time_range: publicTimeRangeSchema.optional(),
@@ -694,6 +712,7 @@ const querySummaryOutputSchema = z.object({
     rows: z.array(z.record(z.unknown())),
     completeness: completenessSchema.optional(),
     evidence: evidenceSchema.optional(),
+    resolved_mappings: z.record(z.unknown()).optional(),
     meta: z.object({
         field_mapping: z.array(z.object({
             role: z.enum(["row", "amount", "time"]),
@@ -773,7 +792,7 @@ const aggregateInputPublicSchema = z
     sort: z.array(publicSortItemSchema).optional(),
     filters: z.array(publicFilterItemSchema).optional(),
     time_range: publicTimeRangeSchema.optional(),
-    group_by: z.array(publicFieldSelectorSchema).min(1).max(20),
+    group_by: z.array(publicFieldSelectorSchema).max(20).optional(),
     amount_column: publicFieldSelectorSchema.optional(),
     amount_columns: z.array(publicFieldSelectorSchema).min(1).max(5).optional(),
     metrics: z.array(z.enum(["count", "sum", "avg", "min", "max"])).min(1).max(5).optional(),
@@ -838,7 +857,7 @@ const aggregateInputSchema = z
         timezone: z.string().optional()
     })
         .optional(),
-    group_by: z.array(z.union([z.string().min(1), z.number().int()])).min(1).max(20),
+    group_by: z.array(z.union([z.string().min(1), z.number().int()])).max(20).optional(),
     amount_column: z.union([z.string().min(1), z.number().int()]).optional(),
     amount_columns: z
         .array(z.union([z.string().min(1), z.number().int()]))
@@ -1308,7 +1327,7 @@ server.registerTool("qf_field_resolve", {
 });
 server.registerTool("qf_query_plan", {
     title: "Qingflow Query Plan",
-    description: "Preflight query arguments: normalize inputs, validate required fields, resolve mappings and estimate scan limits before execution.",
+    description: "Debug/explain tool: preflight query arguments, validate required fields, resolve field mappings and estimate scan pages before actual execution. Use for complex queries or when troubleshooting. For normal queries, use qf_query directly.",
     inputSchema: queryPlanInputPublicSchema,
     outputSchema: queryPlanOutputSchema,
     annotations: {
@@ -1422,7 +1441,7 @@ server.registerTool("qf_export_json", {
 });
 server.registerTool("qf_query", {
     title: "Qingflow Unified Query",
-    description: "Unified read entry for list/record/summary. Use query_mode=auto to route automatically.",
+    description: "Unified read entry for list/record/summary modes. Use query_mode=auto to route: apply_id→record; amount_column/time_range/stat_policy→summary; otherwise→list. In summary mode, select_columns is optional (auto-derived from amount_column/time_range). Field titles are accepted everywhere—que_id resolution is automatic.",
     inputSchema: queryInputPublicSchema,
     outputSchema: queryOutputSchema,
     annotations: {
@@ -1474,6 +1493,7 @@ server.registerTool("qf_query", {
                     summary: executed.data
                 },
                 output_profile: executed.outputProfile,
+                resolved_mappings: executed.resolvedMappings,
                 ...(isVerboseProfile(executed.outputProfile)
                     ? {
                         completeness,
@@ -1502,6 +1522,7 @@ server.registerTool("qf_query", {
                 list: executed.payload.data
             },
             output_profile: executed.outputProfile,
+            resolved_mappings: executed.resolvedMappings,
             ...(isVerboseProfile(executed.outputProfile)
                 ? {
                     completeness,
@@ -1524,7 +1545,7 @@ server.registerTool("qf_query", {
 });
 server.registerTool("qf_record_create", {
     title: "Qingflow Record Create",
-    description: "Create one record. Supports explicit answers and ergonomic fields mapping (title or queId).",
+    description: "Create one record. Supports fields{} mapping by title or queId, and explicit answers[]. Set wait_result=true to poll until the record is resolved (returns apply_id directly instead of requiring a follow-up qf_operation_get call).",
     inputSchema: createInputPublicSchema,
     outputSchema: createOutputSchema,
     annotations: {
@@ -1540,7 +1561,8 @@ server.registerTool("qf_record_create", {
         const normalizedAnswers = resolveAnswers({
             explicitAnswers: parsedArgs.answers,
             fields: parsedArgs.fields,
-            form: form?.result
+            form: form?.result,
+            tool: "qf_record_create"
         });
         const payload = {
             answers: normalizedAnswers
@@ -1552,12 +1574,34 @@ server.registerTool("qf_record_create", {
             userId: parsedArgs.user_id
         });
         const result = asObject(response.result);
+        const requestId = asNullableString(result?.requestId);
+        const immediateApplyId = result?.applyId ?? null;
+        const shouldWaitForResult = (parsedArgs.wait_result ?? false) && requestId !== null && immediateApplyId === null;
+        let finalApplyId = immediateApplyId;
+        let isResolved = immediateApplyId !== null;
+        let isTimedOut = false;
+        let operationResult = null;
+        if (shouldWaitForResult) {
+            const waited = await waitForOperationResolution({
+                requestId: requestId,
+                timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
+            });
+            isResolved = waited.resolved;
+            isTimedOut = waited.timedOut;
+            operationResult = waited.operationResult;
+            finalApplyId = waited.applyId;
+        }
         return okResult({
             ok: true,
             data: {
-                request_id: asNullableString(result?.requestId),
-                apply_id: result?.applyId ?? null,
-                async_hint: "Use qf_operation_get with request_id when apply_id is null."
+                request_id: requestId,
+                apply_id: finalApplyId,
+                resolved: isResolved,
+                ...(isTimedOut ? { timed_out: true } : {}),
+                ...(operationResult !== null ? { operation_result: operationResult } : {}),
+                async_hint: isResolved
+                    ? "Record created and resolved."
+                    : "Use qf_operation_get with request_id to fetch the result."
             },
             meta: buildMeta(response)
         }, `Create request sent for app ${parsedArgs.app_key}`);
@@ -1568,7 +1612,7 @@ server.registerTool("qf_record_create", {
 });
 server.registerTool("qf_record_update", {
     title: "Qingflow Record Update",
-    description: "Patch one record by applyId with explicit answers or ergonomic fields mapping.",
+    description: "Patch one record by applyId with explicit answers or ergonomic fields mapping (title or queId). Set wait_result=true to poll until the update is confirmed instead of requiring a follow-up qf_operation_get call.",
     inputSchema: updateInputPublicSchema,
     outputSchema: updateOutputSchema,
     annotations: {
@@ -1588,15 +1632,38 @@ server.registerTool("qf_record_update", {
         const normalizedAnswers = resolveAnswers({
             explicitAnswers: parsedArgs.answers,
             fields: parsedArgs.fields,
-            form: form?.result
+            form: form?.result,
+            tool: "qf_record_update"
         });
         const response = await client.updateRecord(String(parsedArgs.apply_id), { answers: normalizedAnswers }, { userId: parsedArgs.user_id });
         const result = asObject(response.result);
+        const updateRequestId = asNullableString(result?.requestId);
+        const shouldWaitForUpdate = (parsedArgs.wait_result ?? false) && updateRequestId !== null;
+        let updateIsResolved = false;
+        let updateIsTimedOut = false;
+        let updateOperationResult = null;
+        let updateApplyId = null;
+        if (shouldWaitForUpdate) {
+            const waited = await waitForOperationResolution({
+                requestId: updateRequestId,
+                timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
+            });
+            updateIsResolved = waited.resolved;
+            updateIsTimedOut = waited.timedOut;
+            updateOperationResult = waited.operationResult;
+            updateApplyId = waited.applyId;
+        }
         return okResult({
             ok: true,
             data: {
-                request_id: asNullableString(result?.requestId),
-                async_hint: "Use qf_operation_get with request_id to fetch update result when needed."
+                request_id: updateRequestId,
+                ...(updateApplyId !== null ? { apply_id: updateApplyId } : {}),
+                resolved: updateIsResolved,
+                ...(updateIsTimedOut ? { timed_out: true } : {}),
+                ...(updateOperationResult !== null ? { operation_result: updateOperationResult } : {}),
+                async_hint: updateIsResolved
+                    ? "Record updated and resolved."
+                    : "Use qf_operation_get with request_id to fetch the update result."
             },
             meta: buildMeta(response)
         }, `Update request sent for apply ${String(parsedArgs.apply_id)}`);
@@ -1632,7 +1699,7 @@ server.registerTool("qf_operation_get", {
 });
 server.registerTool("qf_records_aggregate", {
     title: "Qingflow Records Aggregate",
-    description: "Aggregate records by group_by columns with optional amount metrics. Designed for deterministic, auditable statistics.",
+    description: "Aggregate records with optional group_by columns and amount metrics. Omit group_by for total-only summary (count/sum/avg across all records). Field titles are resolved automatically. Designed for deterministic, auditable statistics.",
     inputSchema: aggregateInputPublicSchema,
     outputSchema: aggregateOutputSchema,
     annotations: {
@@ -2068,7 +2135,8 @@ function buildToolSpecCatalog() {
             required: ["tool"],
             limits: {
                 tool: "qf_records_list|qf_record_get|qf_query|qf_records_aggregate|qf_records_batch_get|qf_export_csv|qf_export_json",
-                input_contract: "strict JSON only; arguments must be a native JSON object"
+                input_contract: "strict JSON only; arguments must be a native JSON object",
+                usage_hint: "Debug/explain only. For normal queries use qf_query directly."
             },
             aliases: {},
             minimal_example: {
@@ -2185,9 +2253,9 @@ function buildToolSpecCatalog() {
         {
             tool: "qf_query",
             required: [
-                "record mode: apply_id + select_columns",
+                "record mode: apply_id (select_columns recommended)",
                 "list mode: app_key + select_columns",
-                "summary mode: app_key + select_columns"
+                "summary mode: app_key only (select_columns auto-derived from amount_column/time_range)"
             ],
             limits: {
                 query_mode: "auto|list|record|summary",
@@ -2219,7 +2287,7 @@ function buildToolSpecCatalog() {
         },
         {
             tool: "qf_records_aggregate",
-            required: ["app_key", "group_by"],
+            required: ["app_key"],
             limits: {
                 page_size_max: 200,
                 requested_pages_max: 500,
@@ -2255,6 +2323,8 @@ function buildToolSpecCatalog() {
             required: ["app_key", "answers or fields"],
             limits: {
                 write_mode: "Provide either answers[] or fields{}",
+                wait_result: "optional boolean; when true, polls qf_operation_get internally and returns resolved apply_id directly",
+                wait_timeout_ms: "optional int (max 20000); default 5000ms",
                 input_contract: "strict JSON only; answers must be array and fields must be object"
             },
             aliases: {},
@@ -2271,6 +2341,8 @@ function buildToolSpecCatalog() {
             required: ["apply_id", "answers or fields"],
             limits: {
                 write_mode: "Provide either answers[] or fields{}",
+                wait_result: "optional boolean; when true, polls qf_operation_get internally and returns resolved result directly",
+                wait_timeout_ms: "optional int (max 20000); default 5000ms",
                 input_contract: "strict JSON only; answers must be array and fields must be object"
             },
             aliases: {},
@@ -3590,6 +3662,149 @@ function scoreFieldMatches(requested, fields, fuzzy, topK) {
     }
     return scored.sort((a, b) => b.score - a.score).slice(0, topK);
 }
+function buildFieldCandidateList(fields) {
+    return fields
+        .filter((field) => field.queId !== undefined && field.queId !== null)
+        .map((field) => ({
+        que_id: normalizeQueId(field.queId),
+        que_title: asNullableString(field.queTitle),
+        que_type: field.queType
+    }));
+}
+function buildFieldSuggestions(requested, index, topK = 3) {
+    return scoreFieldMatches(requested, Array.from(index.byId.values()), true, topK);
+}
+function buildResolvedMappingEntry(params) {
+    const field = params.field ?? null;
+    return {
+        requested: params.requested,
+        resolved: params.resolved,
+        que_id: field?.queId !== undefined && field?.queId !== null ? normalizeQueId(field.queId) : null,
+        que_title: asNullableString(field?.queTitle),
+        que_type: field?.queType ?? null,
+        ...(params.reason ? { reason: params.reason } : {}),
+        ...(params.auto_selected ? { auto_selected: true } : {})
+    };
+}
+function resolveFieldSelectorStrict(params) {
+    const requested = String(params.fieldKey ?? "").trim();
+    if (!requested) {
+        throw new InputValidationError({
+            message: `${params.location} contains an empty field selector`,
+            errorCode: "EMPTY_FIELD_SELECTOR",
+            fixHint: "Pass a non-empty field title or que_id.",
+            details: {
+                tool: params.tool,
+                location: params.location
+            }
+        });
+    }
+    let resolved = null;
+    if (isNumericKey(requested)) {
+        resolved = params.index.byId.get(String(Number(requested))) ?? null;
+        if (!resolved) {
+            throw new InputValidationError({
+                message: `${params.location} references unknown que_id "${requested}"`,
+                errorCode: "FIELD_NOT_FOUND",
+                fixHint: "Use qf_form_get or qf_field_resolve to confirm the exact field que_id before retrying.",
+                details: {
+                    tool: params.tool,
+                    location: params.location,
+                    requested,
+                    suggestions: buildFieldSuggestions(requested, params.index)
+                }
+            });
+        }
+    }
+    else {
+        const matches = params.index.byTitle.get(requested.toLowerCase()) ?? [];
+        if (matches.length === 1) {
+            resolved = matches[0];
+        }
+        else if (matches.length > 1) {
+            throw new InputValidationError({
+                message: `${params.location} field "${requested}" is ambiguous`,
+                errorCode: "AMBIGUOUS_FIELD",
+                fixHint: "Use numeric que_id, or call qf_field_resolve first to disambiguate the field title.",
+                details: {
+                    tool: params.tool,
+                    location: params.location,
+                    requested,
+                    candidates: buildFieldCandidateList(matches)
+                }
+            });
+        }
+        else {
+            throw new InputValidationError({
+                message: `${params.location} cannot resolve field "${requested}"`,
+                errorCode: "FIELD_NOT_FOUND",
+                fixHint: "Use qf_form_get or qf_field_resolve to confirm the exact field title before retrying.",
+                details: {
+                    tool: params.tool,
+                    location: params.location,
+                    requested,
+                    suggestions: buildFieldSuggestions(requested, params.index)
+                }
+            });
+        }
+    }
+    if (params.expectDateType && !isDateLikeQueType(resolved.queType)) {
+        throw new InputValidationError({
+            message: `Field "${requested}" is not a date field and cannot be used in ${params.location}`,
+            errorCode: "TIME_RANGE_FIELD_TYPE_MISMATCH",
+            fixHint: "Use qf_form_get to pick a date field (queType=4), then retry time_range with that field.",
+            details: {
+                tool: params.tool,
+                location: params.location,
+                requested,
+                resolved_field: buildResolvedMappingEntry({
+                    requested,
+                    field: resolved,
+                    resolved: true
+                })
+            }
+        });
+    }
+    return resolved;
+}
+function resolveOutputColumn(column, index, label, tool) {
+    const requested = String(column).trim();
+    if (!requested) {
+        throw new InputValidationError({
+            message: `${label} contains an empty column selector`,
+            errorCode: "EMPTY_FIELD_SELECTOR",
+            fixHint: "Pass a non-empty field title or que_id.",
+            details: {
+                tool,
+                location: label
+            }
+        });
+    }
+    if (isNumericKey(requested)) {
+        const hit = index.byId.get(String(Number(requested)));
+        return {
+            requested,
+            que_id: hit?.queId !== undefined && hit?.queId !== null ? normalizeQueId(hit.queId) : Number(requested),
+            que_title: asNullableString(hit?.queTitle),
+            que_type: hit?.queType ?? null
+        };
+    }
+    const hit = resolveFieldSelectorStrict({
+        fieldKey: requested,
+        index,
+        tool,
+        location: label
+    });
+    return {
+        requested,
+        que_id: normalizeQueId(hit.queId),
+        que_title: asNullableString(hit.queTitle),
+        que_type: hit.queType
+    };
+}
+function resolveOutputColumns(columns, index, label, tool) {
+    return normalizeColumnSelectors(columns).map((requested) => resolveOutputColumn(requested, index, label, tool));
+}
 function normalizedTextSimilarity(left, right) {
     if (!left || !right) {
         return 0;
@@ -4139,6 +4354,18 @@ async function executeRecordsExport(format, args) {
         });
     }
     const outputProfile = resolveOutputProfile(args.output_profile);
+    const form = await getFormCached(args.app_key, args.user_id, false);
+    const index = buildFieldIndex(form.result);
+    const selectResolution = resolveSelectColumnsWithIndex(args.select_columns, index, `qf_export_${format}`);
+    const filterResolution = resolveFiltersWithIndex(args.filters, index, `qf_export_${format}`);
+    const timeRangeResolution = resolveTimeRangeWithIndex(args.time_range, index, `qf_export_${format}`);
+    const sortResolution = resolveSortWithIndex(args.sort, index, `qf_export_${format}`);
+    const resolvedMappings = {
+        select_columns: selectResolution.mappings,
+        ...(filterResolution.mappings.length > 0 ? { filters: filterResolution.mappings } : {}),
+        ...(sortResolution.mappings.length > 0 ? { sort: sortResolution.mappings } : {}),
+        ...(timeRangeResolution.mapping ? { time_range: timeRangeResolution.mapping } : {})
+    };
     const queryId = randomUUID();
     const pageNum = resolveStartPage(args.page_num, args.page_token, args.app_key);
     const requestedPages = args.requested_pages ?? EXPORT_DEFAULT_PAGES;
@@ -4146,14 +4373,12 @@ async function executeRecordsExport(format, args) {
     const maxRows = Math.min(args.max_rows ?? EXPORT_MAX_ROWS, EXPORT_MAX_ROWS);
     const startedAt = Date.now();
     const adaptivePaging = createAdaptivePagingState(args.page_size ?? DEFAULT_PAGE_SIZE);
-    const effectiveFilters = appendTimeRangeFilter(args.filters, args.time_range);
-    assertTimeRangeFilterApplied(`qf_export_${format}`, args.time_range, effectiveFilters);
+    const effectiveFilters = appendTimeRangeFilter(filterResolution.filters, timeRangeResolution.time_range);
+    assertTimeRangeFilterApplied(`qf_export_${format}`, timeRangeResolution.time_range, effectiveFilters);
     if (hasDateLikeRangeFilters(effectiveFilters)) {
-        const form = await getFormCached(args.app_key, args.user_id, false);
-        const index = buildFieldIndex(form.result);
         validateDateRangeFilters(effectiveFilters, index, `qf_export_${format}`);
     }
-    const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
+    const normalizedSort = sortResolution.sort;
     let currentPage = pageNum;
     let fetchedPages = 0;
     let hasMore = false;
@@ -4220,27 +4445,29 @@ async function executeRecordsExport(format, args) {
         throw new Error(`Failed to export ${format}: empty response`);
     }
     const normalizedItems = rawItems.map((raw) => normalizeRecordItem(raw, true));
+    const requestedSelectColumns = selectResolution.columns.map((item) => item.requested);
     const projection = projectRecordItemsColumns({
         items: normalizedItems,
         includeAnswers: true,
         maxColumns: args.max_columns,
-        selectColumns: args.select_columns
+        selectColumns: requestedSelectColumns
     });
     if (normalizedItems.length > 0 && projection.matchedAnswersCount === 0) {
         throw new InputValidationError({
-            message: `No answers matched select_columns (${args.select_columns
+            message: `No answers matched select_columns (${requestedSelectColumns
                 .map((item) => String(item))
                 .join(", ")}).`,
             errorCode: "COLUMN_SELECTOR_NOT_FOUND",
-            fixHint: "Use qf_form_get to confirm que_id/que_title. If parameters were stringified, pass native JSON arrays (or plain arrays) for select_columns.",
+            fixHint: "Use qf_form_get or qf_field_resolve to confirm the exact field title/que_id before retrying.",
             details: {
-                select_columns: args.select_columns
+                select_columns: requestedSelectColumns,
+                resolved_mappings: selectResolution.mappings
             }
         });
     }
     const selectedColumnsForRows = args.max_columns !== undefined
-        ? projection.selectedColumns.slice(0, args.max_columns)
-        : projection.selectedColumns;
+        ? requestedSelectColumns.slice(0, args.max_columns)
+        : requestedSelectColumns;
     const rows = buildFlatRowsFromItems({
         items: normalizedItems,
         selectedColumns: selectedColumnsForRows
@@ -4320,6 +4547,7 @@ async function executeRecordsExport(format, args) {
                 ? {
                     completeness,
                     evidence,
+                    resolved_mappings: resolvedMappings,
                     execution: {
                         scanned_pages: fetchedPages,
                         requested_pages: requestedPages,
@@ -4347,7 +4575,8 @@ async function executeRecordsExport(format, args) {
     };
     return {
         payload,
-        message: `Exported ${rows.length} rows to ${filePath}`
+        message: `Exported ${rows.length} rows to ${filePath}`,
+        resolvedMappings
     };
 }
 async function executeRecordsList(args) {
@@ -4366,20 +4595,30 @@ async function executeRecordsList(args) {
         });
     }
     const outputProfile = resolveOutputProfile(args.output_profile);
+    const form = await getFormCached(args.app_key, args.user_id, false);
+    const index = buildFieldIndex(form.result);
+    const selectResolution = resolveSelectColumnsWithIndex(args.select_columns, index, "qf_records_list");
+    const filterResolution = resolveFiltersWithIndex(args.filters, index, "qf_records_list");
+    const timeRangeResolution = resolveTimeRangeWithIndex(args.time_range, index, "qf_records_list");
+    const sortResolution = resolveSortWithIndex(args.sort, index, "qf_records_list");
+    const resolvedMappings = {
+        select_columns: selectResolution.mappings,
+        ...(filterResolution.mappings.length > 0 ? { filters: filterResolution.mappings } : {}),
+        ...(sortResolution.mappings.length > 0 ? { sort: sortResolution.mappings } : {}),
+        ...(timeRangeResolution.mapping ? { time_range: timeRangeResolution.mapping } : {})
+    };
     const queryId = randomUUID();
     const pageNum = resolveStartPage(args.page_num, args.page_token, args.app_key);
     const pageSize = args.page_size ?? DEFAULT_PAGE_SIZE;
     const adaptivePaging = createAdaptivePagingState(pageSize);
     const requestedPages = args.requested_pages ?? 1;
     const scanMaxPages = args.scan_max_pages ?? requestedPages;
-    const effectiveFilters = appendTimeRangeFilter(args.filters, args.time_range);
-    assertTimeRangeFilterApplied("qf_records_list", args.time_range, effectiveFilters);
+    const effectiveFilters = appendTimeRangeFilter(filterResolution.filters, timeRangeResolution.time_range);
+    assertTimeRangeFilterApplied("qf_records_list", timeRangeResolution.time_range, effectiveFilters);
     if (hasDateLikeRangeFilters(effectiveFilters)) {
-        const form = await getFormCached(args.app_key, args.user_id, false);
-        const index = buildFieldIndex(form.result);
         validateDateRangeFilters(effectiveFilters, index, "qf_records_list");
     }
-    const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
+    const normalizedSort = sortResolution.sort;
     const includeAnswers = true;
     const startedAt = Date.now();
     let currentPage = pageNum;
@@ -4451,27 +4690,29 @@ async function executeRecordsList(args) {
         .slice(0, listLimit.limit)
         .map((raw) => normalizeRecordItem(raw, includeAnswers));
     const sourceItemsForRows = items.slice();
+    const requestedSelectColumns = selectResolution.columns.map((item) => item.requested);
     const columnProjection = projectRecordItemsColumns({
         items,
         includeAnswers,
         maxColumns: args.max_columns,
-        selectColumns: args.select_columns
+        selectColumns: requestedSelectColumns
     });
     if (items.length > 0 && columnProjection.matchedAnswersCount === 0) {
         throw new InputValidationError({
-            message: `No answers matched select_columns (${args.select_columns
+            message: `No answers matched select_columns (${requestedSelectColumns
                 .map((item) => String(item))
                 .join(", ")}).`,
             errorCode: "COLUMN_SELECTOR_NOT_FOUND",
-            fixHint: "Use qf_form_get to confirm que_id/que_title. If parameters were stringified, pass native JSON arrays (or plain arrays) for select_columns.",
+            fixHint: "Use qf_form_get or qf_field_resolve to confirm the exact field title/que_id before retrying.",
             details: {
-                select_columns: args.select_columns
+                select_columns: requestedSelectColumns,
+                resolved_mappings: selectResolution.mappings
             }
         });
     }
     const selectedColumnsForRows = args.max_columns !== undefined
-        ? columnProjection.selectedColumns.slice(0, args.max_columns)
-        : columnProjection.selectedColumns;
+        ? requestedSelectColumns.slice(0, args.max_columns)
+        : requestedSelectColumns;
     const rows = buildFlatRowsFromItems({
         items: sourceItemsForRows,
         selectedColumns: selectedColumnsForRows
@@ -4509,14 +4750,14 @@ async function executeRecordsList(args) {
     const listState = {
         query_id: queryId,
         app_key: args.app_key,
-        selected_columns: columnProjection.selectedColumns,
+        selected_columns: requestedSelectColumns,
         filters: echoFilters(effectiveFilters),
-        time_range: args.time_range
+        time_range: timeRangeResolution.mapping
             ? {
-                column: String(args.time_range.column),
-                from: args.time_range.from ?? null,
-                to: args.time_range.to ?? null,
-                timezone: args.time_range.timezone ?? null
+                column: String(args.time_range?.column ?? timeRangeResolution.mapping.requested ?? ""),
+                from: timeRangeResolution.time_range?.from ?? null,
+                to: timeRangeResolution.time_range?.to ?? null,
+                timezone: timeRangeResolution.time_range?.timezone ?? null
             }
             : null
     };
@@ -4553,6 +4794,7 @@ async function executeRecordsList(args) {
                 : {})
         },
         output_profile: outputProfile,
+        resolved_mappings: resolvedMappings,
         ...(isVerboseProfile(outputProfile)
             ? {
                 completeness,
@@ -4577,7 +4819,8 @@ async function executeRecordsList(args) {
         }),
         completeness,
         evidence,
-        outputProfile
+        outputProfile,
+        resolvedMappings
     };
 }
 async function executeRecordGet(args) {
@@ -4772,13 +5015,6 @@ async function executeRecordsSummary(args) {
             fixHint: "Provide app_key, for example: {\"query_mode\":\"summary\",\"app_key\":\"21b3d559\",...}"
         });
     }
-    if (!args.select_columns?.length) {
-        throw missingRequiredFieldError({
-            field: "select_columns",
-            tool: "qf_query(summary)",
-            fixHint: "Provide select_columns as an array (<=2), for example: {\"select_columns\":[\"客户全称\"]}"
-        });
-    }
     const outputProfile = resolveOutputProfile(args.output_profile);
     const strictFull = args.strict_full ?? true;
     const includeNegative = args.stat_policy?.include_negative ?? true;
@@ -4793,7 +5029,10 @@ async function executeRecordsSummary(args) {
     const timezone = args.time_range?.timezone ?? "Asia/Shanghai";
     const form = await getFormCached(args.app_key, args.user_id, false);
     const index = buildFieldIndex(form.result);
-    const selectedColumns = resolveSummaryColumns(args.select_columns, index, "select_columns");
+    const selectResolution = args.select_columns && args.select_columns.length > 0
+        ? resolveSelectColumnsWithIndex(args.select_columns, index, "qf_query(summary)")
+        : buildDefaultSummarySelectColumns(args, index);
+    const selectedColumns = selectResolution.columns;
     const effectiveColumns = args.max_columns !== undefined ? selectedColumns.slice(0, args.max_columns) : selectedColumns;
     if (effectiveColumns.length === 0) {
         throw new Error("No output columns remain after max_columns cap");
@@ -4801,14 +5040,28 @@ async function executeRecordsSummary(args) {
     const amountColumn = args.amount_column !== undefined
         ? resolveSummaryColumn(args.amount_column, index, "amount_column")
         : null;
-    const timeColumn = args.time_range ? resolveSummaryColumn(args.time_range.column, index, "time_range.column") : null;
-    const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
-    const summaryFilters = [...(args.filters ?? [])];
-    if (timeColumn && (args.time_range?.from || args.time_range?.to)) {
+    const timeRangeResolution = resolveTimeRangeWithIndex(args.time_range, index, "qf_query(summary)");
+    const timeColumn = timeRangeResolution.time_range
+        ? resolveSummaryColumn(timeRangeResolution.time_range.column, index, "time_range.column")
+        : null;
+    const filterResolution = resolveFiltersWithIndex(args.filters, index, "qf_query(summary)");
+    const sortResolution = resolveSortWithIndex(args.sort, index, "qf_query(summary)");
+    const resolvedMappings = {
+        select_columns: selectResolution.mappings,
+        ...(amountColumn
+            ? { amount_column: buildResolvedMappingFromSummaryColumn(amountColumn) }
+            : {}),
+        ...(filterResolution.mappings.length > 0 ? { filters: filterResolution.mappings } : {}),
+        ...(sortResolution.mappings.length > 0 ? { sort: sortResolution.mappings } : {}),
+        ...(timeRangeResolution.mapping ? { time_range: timeRangeResolution.mapping } : {})
+    };
+    const normalizedSort = sortResolution.sort;
+    const summaryFilters = [...(filterResolution.filters ?? [])];
+    if (timeColumn && (timeRangeResolution.time_range?.from || timeRangeResolution.time_range?.to)) {
         summaryFilters.push({
             que_id: timeColumn.que_id,
-            ...(args.time_range.from ? { min_value: args.time_range.from } : {}),
-            ...(args.time_range.to ? { max_value: args.time_range.to } : {})
+            ...(timeRangeResolution.time_range.from ? { min_value: timeRangeResolution.time_range.from } : {}),
+            ...(timeRangeResolution.time_range.to ? { max_value: timeRangeResolution.time_range.to } : {})
         });
     }
     validateDateRangeFilters(summaryFilters, index, "qf_query(summary)");
@@ -4824,7 +5077,7 @@ async function executeRecordsSummary(args) {
         select_columns: effectiveColumns,
         amount_column: amountColumn,
         time_column: timeColumn,
-        time_range: args.time_range,
+        time_range: timeRangeResolution.time_range,
         stat_policy: {
             include_negative: includeNegative,
             include_null: includeNull
@@ -4841,8 +5094,8 @@ async function executeRecordsSummary(args) {
         time_range: timeColumn
             ? {
                 column: timeColumn.requested,
-                from: args.time_range?.from ?? null,
-                to: args.time_range?.to ?? null,
+                from: timeRangeResolution.time_range?.from ?? null,
+                to: timeRangeResolution.time_range?.to ?? null,
                 timezone
             }
             : null
@@ -5061,6 +5314,7 @@ async function executeRecordsSummary(args) {
             },
             rows,
             completeness,
+            resolved_mappings: resolvedMappings,
             ...(isVerboseProfile(outputProfile)
                 ? {
                     evidence,
@@ -5071,8 +5325,8 @@ async function executeRecordsSummary(args) {
                             time_range: timeColumn
                                 ? {
                                     column: timeColumn.requested,
-                                    from: args.time_range?.from ?? null,
-                                    to: args.time_range?.to ?? null,
+                                    from: timeRangeResolution.time_range?.from ?? null,
+                                    to: timeRangeResolution.time_range?.to ?? null,
                                     timezone
                                 }
                                 : null
@@ -5099,7 +5353,8 @@ async function executeRecordsSummary(args) {
             : `Summarized ${scannedRecords}/${knownResultAmount} records (partial)`,
         completeness,
         evidence,
-        outputProfile
+        outputProfile,
+        resolvedMappings
     };
 }
 async function executeRecordsAggregate(args) {
@@ -5118,7 +5373,12 @@ async function executeRecordsAggregate(args) {
     const timeBucket = args.time_bucket ?? null;
     const form = await getFormCached(args.app_key, args.user_id, false);
     const index = buildFieldIndex(form.result);
-    const groupColumns = resolveSummaryColumns(args.group_by, index, "group_by");
+    const filterResolution = resolveFiltersWithIndex(args.filters, index, "qf_records_aggregate");
+    const sortResolution = resolveSortWithIndex(args.sort, index, "qf_records_aggregate");
+    const timeRangeResolution = resolveTimeRangeWithIndex(args.time_range, index, "qf_records_aggregate");
+    const groupColumns = args.group_by && args.group_by.length > 0
+        ? resolveSummaryColumns(args.group_by, index, "group_by")
+        : [];
     const amountSelectors = args.amount_columns && args.amount_columns.length > 0
         ? args.amount_columns
         : args.amount_column !== undefined
@@ -5129,14 +5389,25 @@ async function executeRecordsAggregate(args) {
         : [];
     const primaryAmountColumn = amountColumns[0] ?? null;
     const metrics = resolveAggregateMetrics(args.metrics, amountColumns.length > 0);
-    const timeColumn = args.time_range ? resolveSummaryColumn(args.time_range.column, index, "time_range.column") : null;
-    const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
-    const aggregateFilters = [...(args.filters ?? [])];
-    if (timeColumn && (args.time_range?.from || args.time_range?.to)) {
+    const timeColumn = timeRangeResolution.time_range
+        ? resolveSummaryColumn(timeRangeResolution.time_range.column, index, "time_range.column")
+        : null;
+    const resolvedMappings = {
+        group_by: groupColumns.map((item) => buildResolvedMappingFromSummaryColumn(item)),
+        ...(amountColumns.length > 0
+            ? { amount_columns: amountColumns.map((item) => buildResolvedMappingFromSummaryColumn(item)) }
+            : {}),
+        ...(filterResolution.mappings.length > 0 ? { filters: filterResolution.mappings } : {}),
+        ...(sortResolution.mappings.length > 0 ? { sort: sortResolution.mappings } : {}),
+        ...(timeRangeResolution.mapping ? { time_range: timeRangeResolution.mapping } : {})
+    };
+    const normalizedSort = sortResolution.sort;
+    const aggregateFilters = [...(filterResolution.filters ?? [])];
+    if (timeColumn && (timeRangeResolution.time_range?.from || timeRangeResolution.time_range?.to)) {
         aggregateFilters.push({
             que_id: timeColumn.que_id,
-            ...(args.time_range.from ? { min_value: args.time_range.from } : {}),
-            ...(args.time_range.to ? { max_value: args.time_range.to } : {})
+            ...(timeRangeResolution.time_range.from ? { min_value: timeRangeResolution.time_range.from } : {}),
+            ...(timeRangeResolution.time_range.to ? { max_value: timeRangeResolution.time_range.to } : {})
         });
     }
     validateDateRangeFilters(aggregateFilters, index, "qf_records_aggregate");
@@ -5153,7 +5424,7 @@ async function executeRecordsAggregate(args) {
         amount_columns: amountColumns,
         metrics,
         time_column: timeColumn,
-        time_range: args.time_range,
+        time_range: timeRangeResolution.time_range,
         time_bucket: timeBucket,
         stat_policy: {
             include_negative: includeNegative,
@@ -5174,8 +5445,8 @@ async function executeRecordsAggregate(args) {
         time_range: timeColumn
             ? {
                 column: timeColumn.requested,
-                from: args.time_range?.from ?? null,
-                to: args.time_range?.to ?? null,
+                from: timeRangeResolution.time_range?.from ?? null,
+                to: timeRangeResolution.time_range?.to ?? null,
                 timezone
             }
             : null
@@ -5441,6 +5712,7 @@ async function executeRecordsAggregate(args) {
                     : {})
             },
             output_profile: outputProfile,
+            resolved_mappings: resolvedMappings,
             ...(isVerboseProfile(outputProfile)
                 ? {
                     completeness,
@@ -5466,25 +5738,12 @@ function resolveSummaryColumns(columns, index, label) {
 }
 function resolveSummaryColumn(column, index, label) {
     const requested = String(column).trim();
-    if (!requested) {
-        throw new Error(`${label} contains an empty column selector`);
-    }
-    if (isNumericKey(requested)) {
-        const hit = index.byId.get(String(Number(requested)));
-        if (!hit) {
-            throw new Error(`${label} references unknown que_id "${requested}"`);
-        }
-        return {
-            requested,
-            que_id: normalizeQueId(hit.queId),
-            que_title: asNullableString(hit.queTitle),
-            que_type: hit.queType
-        };
-    }
-    const hit = resolveFieldByKey(requested, index);
-    if (!hit || hit.queId === undefined || hit.queId === null) {
-        throw new Error(`${label} cannot resolve field "${requested}"`);
-    }
+    const hit = resolveFieldSelectorStrict({
+        fieldKey: requested,
+        index,
+        tool: label.startsWith("group_by") ? "qf_records_aggregate" : "qf_query",
+        location: label
+    });
     return {
         requested,
         que_id: normalizeQueId(hit.queId),
@@ -5762,7 +6021,7 @@ function normalizeRecordItem(raw, includeAnswers) {
     return normalized;
 }
 function resolveAnswers(params) {
-    const normalizedFromFields = resolveFieldAnswers(params.fields, params.form);
+    const normalizedFromFields = resolveFieldAnswers(params.fields, params.form, params.tool);
     const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers);
     const merged = new Map();
     for (const answer of normalizedFromFields) {
@@ -5812,7 +6071,7 @@ function normalizeExplicitAnswers(answers) {
     }
     return output;
 }
-function resolveFieldAnswers(fields, form) {
+function resolveFieldAnswers(fields, form, tool = "qf_record_create") {
     const entries = Object.entries(fields ?? {});
     if (entries.length === 0) {
         return [];
@@ -5820,9 +6079,30 @@ function resolveFieldAnswers(fields, form) {
     const index = buildFieldIndex(form);
     const answers = [];
     for (const [fieldKey, fieldValue] of entries) {
-        const field = resolveFieldByKey(fieldKey, index);
+        let field;
+        if (isNumericKey(fieldKey)) {
+            field = resolveFieldByKey(fieldKey, index);
+        }
+        else {
+            field = resolveFieldSelectorStrict({
+                fieldKey,
+                index,
+                tool,
+                location: `fields.${fieldKey}`
+            });
+        }
         if (!field) {
-            throw new Error(`Cannot resolve field key "${fieldKey}" from form metadata`);
+            throw new InputValidationError({
+                message: `Cannot resolve field key "${fieldKey}" from form metadata`,
+                errorCode: "FIELD_NOT_FOUND",
+                fixHint: "Use qf_form_get or qf_field_resolve to confirm the exact field title before retrying.",
+                details: {
+                    tool,
+                    location: `fields.${fieldKey}`,
+                    requested: fieldKey,
+                    suggestions: buildFieldSuggestions(fieldKey, index)
+                }
+            });
         }
         answers.push(makeAnswerFromField(field, fieldValue));
     }
@@ -5971,15 +6251,227 @@ async function normalizeListSort(sort, appKey, userId) {
     const index = buildFieldIndex(form.result);
     return sort.map((item) => {
         const rawKey = String(item.que_id).trim();
-        const resolved = resolveFieldByKey(rawKey, index);
-        if (!resolved || resolved.queId === undefined || resolved.queId === null) {
-            throw new Error(`Cannot resolve sort.que_id "${rawKey}". Use numeric que_id or exact field title from qf_form_get.`);
+        const resolved = resolveFieldSelectorStrict({
+            fieldKey: rawKey,
+            index,
+            tool: "qf_records_list",
+            location: "sort[].que_id"
+        });
+        return {
+            que_id: normalizeQueId(resolved.queId),
+            ...(item.ascend !== undefined ? { ascend: item.ascend } : {})
+        };
+    });
+}
+function buildResolvedMappingFromSummaryColumn(column, extra = {}) {
+    return {
+        requested: column.requested,
+        resolved: true,
+        que_id: column.que_id,
+        que_title: column.que_title,
+        que_type: column.que_type ?? null,
+        ...extra
+    };
+}
+function resolveFiltersWithIndex(filters, index, tool) {
+    if (!filters?.length) {
+        return {
+            filters,
+            mappings: []
+        };
+    }
+    const mappings = [];
+    const resolvedFilters = filters.map((filter, indexInArray) => {
+        if (filter.que_id === undefined || filter.que_id === null) {
+            return filter;
         }
+        const resolved = resolveFieldSelectorStrict({
+            fieldKey: filter.que_id,
+            index,
+            tool,
+            location: `filters[${indexInArray}].que_id`
+        });
+        mappings.push(buildResolvedMappingEntry({
+            requested: String(filter.que_id),
+            field: resolved,
+            resolved: true
+        }));
+        return {
+            ...filter,
+            que_id: normalizeQueId(resolved.queId)
+        };
+    });
+    return {
+        filters: resolvedFilters,
+        mappings
+    };
+}
+function resolveSortWithIndex(sort, index, tool) {
+    if (!sort?.length) {
+        return {
+            sort,
+            mappings: []
+        };
+    }
+    const mappings = [];
+    const resolvedSort = sort.map((item, indexInArray) => {
+        const resolved = resolveFieldSelectorStrict({
+            fieldKey: item.que_id,
+            index,
+            tool,
+            location: `sort[${indexInArray}].que_id`
+        });
+        mappings.push(buildResolvedMappingEntry({
+            requested: String(item.que_id),
+            field: resolved,
+            resolved: true
+        }));
         return {
             que_id: normalizeQueId(resolved.queId),
             ...(item.ascend !== undefined ? { ascend: item.ascend } : {})
         };
     });
+    return {
+        sort: resolvedSort,
+        mappings
+    };
+}
+function resolveTimeRangeWithIndex(timeRange, index, tool) {
+    if (!timeRange) {
+        return {
+            time_range: undefined,
+            mapping: null
+        };
+    }
+    const resolved = resolveFieldSelectorStrict({
+        fieldKey: timeRange.column,
+        index,
+        tool,
+        location: "time_range.column",
+        expectDateType: true
+    });
+    return {
+        time_range: {
+            ...timeRange,
+            column: normalizeQueId(resolved.queId)
+        },
+        mapping: buildResolvedMappingEntry({
+            requested: String(timeRange.column),
+            field: resolved,
+            resolved: true
+        })
+    };
+}
+function resolveSelectColumnsWithIndex(selectColumns, index, tool) {
+    const columns = resolveOutputColumns(selectColumns, index, "select_columns", tool);
+    return {
+        columns,
+        mappings: columns.map((column) => buildResolvedMappingFromSummaryColumn(column))
+    };
+}
+function buildDefaultSummarySelectColumns(args, index) {
+    const candidates = [];
+    if (args.time_range?.column !== undefined) {
+        candidates.push({
+            selector: args.time_range.column,
+            reason: "auto-selected from time_range.column"
+        });
+    }
+    if (args.amount_column !== undefined) {
+        candidates.push({
+            selector: args.amount_column,
+            reason: "auto-selected from amount_column"
+        });
+    }
+    const idZero = index.byId.get("0");
+    if (idZero?.queId !== undefined && idZero.queId !== null) {
+        candidates.push({
+            selector: normalizeQueId(idZero.queId),
+            reason: "auto-selected default row preview column"
+        });
+    }
+    else {
+        const firstBusinessField = Array.from(index.byId.values()).find((field) => {
+            const normalized = field.queId !== undefined && field.queId !== null ? normalizeQueId(field.queId) : null;
+            return typeof normalized === "number" ? normalized > 0 : Boolean(normalized);
+        });
+        if (firstBusinessField?.queId !== undefined && firstBusinessField.queId !== null) {
+            candidates.push({
+                selector: normalizeQueId(firstBusinessField.queId),
+                reason: "auto-selected first business field for row preview"
+            });
+        }
+    }
+    const deduped = new Set();
+    const selectedCandidates = [];
+    for (const candidate of candidates) {
+        const key = normalizeColumnSelector(candidate.selector);
+        if (deduped.has(key)) {
+            continue;
+        }
+        deduped.add(key);
+        selectedCandidates.push(candidate);
+        if (selectedCandidates.length >= MAX_COLUMN_LIMIT) {
+            break;
+        }
+    }
+    const columns = selectedCandidates.map((candidate) => resolveOutputColumn(candidate.selector, index, "select_columns", "qf_query(summary)"));
+    return {
+        columns,
+        mappings: columns.map((column, indexInArray) => buildResolvedMappingFromSummaryColumn(column, {
+            auto_selected: true,
+            reason: selectedCandidates[indexInArray]?.reason ?? "auto-selected"
+        }))
+    };
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function extractOperationStatus(operationResult) {
+    const obj = asObject(operationResult);
+    const rawStatus = asNullableString(obj?.status ?? obj?.operationStatus ?? obj?.operation_status ?? obj?.resultStatus ?? null);
+    return rawStatus ? rawStatus.trim().toUpperCase() : null;
+}
+function isPendingOperationStatus(status) {
+    if (!status) {
+        return false;
+    }
+    return ["PENDING", "PROCESSING", "RUNNING", "IN_PROGRESS", "QUEUED"].includes(status);
+}
+function extractOperationApplyId(operationResult) {
+    const obj = asObject(operationResult);
+    return obj?.applyId ?? obj?.apply_id ?? null;
+}
+async function waitForOperationResolution(params) {
+    const deadline = Date.now() + Math.max(1, params.timeoutMs);
+    let lastResult = null;
+    while (Date.now() <= deadline) {
+        const response = await client.getOperation(params.requestId);
+        lastResult = response.result;
+        const status = extractOperationStatus(lastResult);
+        const applyId = extractOperationApplyId(lastResult);
+        if ((status && !isPendingOperationStatus(status)) || applyId !== null) {
+            return {
+                resolved: true,
+                timedOut: false,
+                operationResult: lastResult,
+                applyId
+            };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            break;
+        }
+        await delay(Math.min(WAIT_RESULT_POLL_INTERVAL_MS, remaining));
+    }
+    return {
+        resolved: false,
+        timedOut: true,
+        operationResult: lastResult,
+        applyId: extractOperationApplyId(lastResult)
+    };
 }
 function resolveListItemLimit(params) {
     if (params.total <= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "private": false,
   "license": "MIT",
   "type": "module",