qingflow-mcp 0.3.22 → 0.3.24

package/README.md

@@ -13,6 +13,7 @@ This MCP server wraps Qingflow OpenAPI for:
 - `qf_form_get`
 - `qf_field_resolve`
 - `qf_query_plan`
+- `qf_write_plan`
 - `qf_records_list`
 - `qf_record_get`
 - `qf_records_batch_get`
@@ -117,7 +118,7 @@ npm i -g git+https://github.com/853046310/qingflow-mcp.git
 Install from npm (pinned version):
 
 ```bash
-npm i -g qingflow-mcp@0.3.22
+npm i -g qingflow-mcp@0.3.24
 ```
 
 Or one-click installer:
@@ -153,9 +154,10 @@ MCP client config example:
 ## Recommended Flow
 
 1. `qf_apps_list` to pick app.
-2. `qf_form_get` to inspect field ids/titles.
-3. `qf_record_create` or `qf_record_update`.
-4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
+2. `qf_form_get` to inspect field ids/titles and `field_summaries[].write_format`.
+3. For complex forms, run `qf_write_plan` first to surface static blockers and linked-field risks.
+4. `qf_record_create` or `qf_record_update`.
+5. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
 
 Directory / org flow:
 
@@ -180,6 +182,69 @@ Full calling contract (Chinese):
 
 - [MCP 调用规范](./docs/MCP_CALLING_SPEC.md)
 
+## Write Format Discovery
+
+For create/update, `0.3.24` now makes special write formats explicit:
+
+1. `qf_form_get`
+   - `field_summaries[].write_format` is populated for member/department fields.
+2. `qf_tool_spec_get`
+   - `qf_record_create` / `qf_record_update` include member/department examples in `limits.special_field_write_formats`.
+3. `qf_record_create` / `qf_record_update`
+   - invalid member/department values fail fast with `FIELD_VALUE_FORMAT_ERROR`.
+4. `qf_write_plan`
+   - performs static preflight only
+   - detects obvious missing required fields, option-linked fields, readonly/system field writes
+   - warns when `questionRelations` means final submit may still fail
+
+Examples:
+
+```json
+{
+  "fields": {
+    "归属销售": [
+      { "userId": "u_123", "userName": "张三" }
+    ],
+    "归属部门": [
+      { "deptId": 111, "deptName": "销售部" }
+    ]
+  }
+}
+```
+
+Invalid examples that will now fail:
+
+```json
+{
+  "fields": {
+    "归属销售": "张三",
+    "归属部门": "销售部"
+  }
+}
+```
+
+`qf_write_plan` example:
+
+```json
+{
+  "app_key": "21b3d559",
+  "operation": "create",
+  "fields": {
+    "客户名称": "测试客户",
+    "归属销售": [{ "userId": "u_123", "userName": "张三" }],
+    "报销类型": [{ "optionId": 1, "value": "出差" }]
+  }
+}
+```
+
+Use it when:
+
+1. the form has conditional required fields
+2. selected options may reveal linked fields
+3. you need a static blocker list before actual submit
+
+Do not treat `qf_write_plan` as a guarantee of successful submit. It is a static preflight built from OpenAPI-visible form metadata, not the full Qingflow frontend validation engine.
+
 ## Unified Query (`qf_query`)
 
 `qf_query` is the recommended read entry for agents.
@@ -429,7 +494,7 @@ If you see runtime errors around `Headers` or missing web APIs:
 2. Upgrade package to latest:
 
 ```bash
-npm i -g qingflow-mcp@latest
+npm i -g qingflow-mcp@0.3.24
 ```
 
 3. Verify runtime:

package/dist/server.js

@@ -68,7 +68,9 @@ const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
 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.22";
+const SERVER_VERSION = "0.3.24";
+const MEMBER_QUE_TYPE_KEYWORDS = ["member", "user", "成员", "人员"];
+const DEPARTMENT_QUE_TYPE_KEYWORDS = ["department", "dept", "部门"];
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -192,6 +194,15 @@ const fieldSummarySchema = z.object({
     que_id: z.union([z.number(), z.string(), z.null()]),
     que_title: z.string().nullable(),
     que_type: z.unknown(),
+    write_format: z
+        .object({
+        kind: z.enum(["member_list", "department_list"]),
+        description: z.string(),
+        item_shape: z.record(z.string()),
+        example: z.array(z.record(z.unknown())),
+        resolution_hint: z.string()
+    })
+        .nullable(),
     has_sub_fields: z.boolean(),
     sub_field_count: z.number().int().nonnegative()
 });
@@ -1334,6 +1345,108 @@ const queryPlanOutputSchema = z.object({
         generated_at: z.string()
     })
 });
+const writePlanInputPublicSchema = z.object({
+    operation: z.enum(["create", "update"]).optional(),
+    app_key: publicStringSchema,
+    apply_id: publicFieldSelectorSchema.optional(),
+    user_id: publicStringSchema.optional(),
+    force_refresh_form: z.boolean().optional(),
+    answers: z.array(publicAnswerInputSchema).optional(),
+    fields: z.record(z.unknown()).optional()
+});
+const writePlanInputSchema = z.preprocess(normalizeWritePlanInput, z
+    .object({
+    operation: z.enum(["create", "update"]).optional(),
+    app_key: z.string().min(1),
+    apply_id: z.union([z.string().min(1), z.number().int()]).optional(),
+    user_id: z.string().min(1).optional(),
+    force_refresh_form: z.boolean().optional(),
+    answers: z.array(answerInputSchema).optional(),
+    fields: z.record(fieldValueSchema).optional()
+})
+    .refine((value) => hasWritePayload(value.answers, value.fields), {
+    message: "Either answers or fields is required"
+}));
+const writePlanFieldRefSchema = z.object({
+    source: z.enum(["fields", "answers"]),
+    requested: z.string(),
+    resolved: z.boolean(),
+    que_id: z.union([z.string(), z.number(), z.null()]),
+    que_title: z.string().nullable(),
+    que_type: z.unknown().nullable(),
+    required: z.boolean().nullable(),
+    readonly: z.boolean().nullable(),
+    system: z.boolean().nullable(),
+    write_format: fieldSummarySchema.shape.write_format,
+    reason: z.string().nullable()
+});
+const writePlanFieldIssueSchema = z.object({
+    que_id: z.union([z.string(), z.number(), z.null()]),
+    que_title: z.string().nullable(),
+    que_type: z.unknown().nullable(),
+    reason: z.string()
+});
+const writePlanInvalidFieldSchema = z.object({
+    location: z.string().nullable(),
+    message: z.string(),
+    error_code: z.string().nullable(),
+    field: z
+        .object({
+        que_id: z.union([z.string(), z.number(), z.null()]),
+        que_title: z.string().nullable(),
+        que_type: z.unknown().nullable()
+    })
+        .nullable(),
+    expected_format: fieldSummarySchema.shape.write_format,
+    received_value: z.unknown().optional()
+});
+const writePlanOptionLinkSchema = z.object({
+    source_que_id: z.union([z.string(), z.number(), z.null()]),
+    source_que_title: z.string().nullable(),
+    option_id: z.union([z.string(), z.number(), z.null()]),
+    option_value: z.string().nullable(),
+    linked_fields: z.array(z.object({
+        que_id: z.union([z.string(), z.number(), z.null()]),
+        que_title: z.string().nullable(),
+        required: z.boolean().nullable(),
+        provided: z.boolean()
+    })),
+    missing_linked_fields: z.array(z.object({
+        que_id: z.union([z.string(), z.number(), z.null()]),
+        que_title: z.string().nullable(),
+        required: z.boolean().nullable()
+    }))
+});
+const writePlanOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        operation: z.enum(["create", "update"]),
+        app_key: z.string(),
+        apply_id: z.union([z.string(), z.number(), z.null()]),
+        normalized_answers: z.array(z.record(z.unknown())),
+        resolved_fields: z.array(writePlanFieldRefSchema),
+        validation: z.object({
+            valid: z.boolean(),
+            missing_required_fields: z.array(writePlanFieldIssueSchema),
+            likely_hidden_required_fields: z.array(writePlanFieldIssueSchema),
+            readonly_or_system_fields: z.array(writePlanFieldIssueSchema),
+            invalid_fields: z.array(writePlanInvalidFieldSchema),
+            warnings: z.array(z.string())
+        }),
+        dependencies: z.object({
+            question_relations_present: z.boolean(),
+            relation_count: z.number().int().nonnegative(),
+            option_links: z.array(writePlanOptionLinkSchema)
+        }),
+        ready_to_submit: z.boolean(),
+        blockers: z.array(z.string()),
+        recommended_next_actions: z.array(z.string())
+    }),
+    meta: z.object({
+        version: z.string(),
+        generated_at: z.string()
+    })
+});
 const batchGetInputPublicSchema = z
     .object({
     app_key: publicStringSchema,
@@ -2177,6 +2290,25 @@ server.registerTool("qf_query_plan", {
         return errorResult(error);
     }
 });
+server.registerTool("qf_write_plan", {
+    title: "Qingflow Write Plan",
+    description: "Static preflight for create/update payloads. Resolves fields, normalizes answers, checks obvious required/dependency risks, and warns when questionRelations make runtime validation uncertain.",
+    inputSchema: writePlanInputPublicSchema,
+    outputSchema: writePlanOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = writePlanInputSchema.parse(args);
+        const payload = await executeWritePlan(parsedArgs);
+        return okResult(payload, `Planned ${payload.data.operation} for ${parsedArgs.app_key}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
 server.registerTool("qf_records_list", {
     title: "Qingflow Records List",
     description: "List records with pagination, filters and sorting.",
@@ -2388,7 +2520,8 @@ server.registerTool("qf_record_create", {
 }, async (args) => {
     try {
         const parsedArgs = createInputSchema.parse(args);
-        const form = needsFormResolution(parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form)
+        const shouldFetchForm = hasWritePayload(parsedArgs.answers, parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form);
+        const form = shouldFetchForm
             ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
@@ -2464,16 +2597,18 @@ server.registerTool("qf_record_update", {
 }, async (args) => {
     try {
         const parsedArgs = updateInputSchema.parse(args);
-        const requiresForm = needsFormResolution(parsedArgs.fields);
-        if (requiresForm && !parsedArgs.app_key) {
+        const resolvedAppKey = parsedArgs.app_key ?? getCachedApplyAppKey(parsedArgs.apply_id);
+        const requiresFormByTitle = needsFormResolution(parsedArgs.fields);
+        if (requiresFormByTitle && !resolvedAppKey) {
             throw missingRequiredFieldError({
                 field: "app_key",
                 tool: "qf_record_update",
                 fixHint: "Provide app_key when fields uses title-based keys, or switch fields to numeric que_id."
             });
         }
-        const form = requiresForm && parsedArgs.app_key
-            ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
+        const form = (hasWritePayload(parsedArgs.answers, parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form)) &&
+            resolvedAppKey
+            ? await getFormCached(resolvedAppKey, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
             explicitAnswers: parsedArgs.answers,
@@ -3534,7 +3669,8 @@ function buildToolSpecCatalog() {
             tool: "qf_form_get",
             required: ["app_key"],
             limits: {
-                app_key: "required string"
+                app_key: "required string",
+                write_format_hint: "field_summaries[].write_format is populated for member/department fields so agents can discover exact create/update payload shapes before writing."
             },
             aliases: collectAliasHints(["app_key", "user_id", "force_refresh"], {}),
             minimal_example: {
@@ -3575,6 +3711,28 @@ function buildToolSpecCatalog() {
                 resolve_fields: true
             }
         },
+        {
+            tool: "qf_write_plan",
+            required: ["app_key", "answers or fields"],
+            limits: {
+                operation: "create|update (default create; auto-switches to update when apply_id is present)",
+                input_contract: "strict JSON only; answers must be array and fields must be object",
+                capability_boundary: "Static preflight only. Can detect obvious required/dependency risks, but cannot fully execute runtime visibility/validation rules from Qingflow frontend.",
+                special_field_write_formats: {
+                    member_list: [{ userId: "u_123", userName: "张三" }],
+                    department_list: [{ deptId: 111, deptName: "销售部" }]
+                }
+            },
+            aliases: {},
+            minimal_example: {
+                app_key: "21b3d559",
+                operation: "create",
+                fields: {
+                    客户名称: "测试客户",
+                    归属销售: [{ userId: "u_123", userName: "张三" }]
+                }
+            }
+        },
         {
             tool: "qf_records_list",
             required: ["app_key", "select_columns"],
@@ -3751,7 +3909,11 @@ function buildToolSpecCatalog() {
                 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"
+                input_contract: "strict JSON only; answers must be array and fields must be object",
+                special_field_write_formats: {
+                    member_list: [{ userId: "u_123", userName: "张三" }],
+                    department_list: [{ deptId: 111, deptName: "销售部" }]
+                }
             },
             aliases: {},
             minimal_example: {
@@ -3769,7 +3931,11 @@ function buildToolSpecCatalog() {
                 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"
+                input_contract: "strict JSON only; answers must be array and fields must be object",
+                special_field_write_formats: {
+                    member_list: [{ userId: "u_123", userName: "张三" }],
+                    department_list: [{ deptId: 111, deptName: "销售部" }]
+                }
             },
             aliases: {},
             minimal_example: {
@@ -3970,6 +4136,26 @@ function normalizeQueryPlanInput(raw) {
         probe: coerceBooleanLike(normalizedObj.probe)
     };
 }
+function normalizeWritePlanInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        ...COMMON_INPUT_ALIASES,
+        applyId: "apply_id",
+        forceRefreshForm: "force_refresh_form",
+        mode: "operation",
+        action: "operation"
+    });
+    return {
+        ...normalizedObj,
+        apply_id: coerceNumberLike(normalizeSelectorInputValue(normalizedObj.apply_id)) ?? coerceStringLike(normalizedObj.apply_id),
+        user_id: coerceStringLike(normalizedObj.user_id),
+        force_refresh_form: coerceBooleanLike(normalizedObj.force_refresh_form)
+    };
+}
 function normalizeBatchGetInput(raw) {
     const parsedRoot = parseJsonLikeDeep(raw);
     const obj = asObject(parsedRoot);
@@ -5694,6 +5880,456 @@ async function executeQueryPlan(args) {
         }
     };
 }
+async function executeWritePlan(args) {
+    const operation = args.operation ?? (args.apply_id !== undefined ? "update" : "create");
+    const form = await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh_form));
+    const formObj = asObject(form.result);
+    const index = buildFieldIndex(form.result);
+    const fields = Array.from(index.byId.values());
+    const resolvedFields = collectWritePlanFieldRefs({
+        fieldsInput: args.fields,
+        answersInput: args.answers,
+        index
+    });
+    const invalidFields = [];
+    const warnings = [];
+    let normalizedAnswers = [];
+    try {
+        normalizedAnswers = resolveAnswers({
+            explicitAnswers: args.answers,
+            fields: args.fields,
+            form: form.result,
+            tool: "qf_write_plan"
+        });
+    }
+    catch (error) {
+        invalidFields.push(...normalizeWritePlanErrors(error));
+    }
+    const providedFieldIds = new Set();
+    for (const ref of resolvedFields) {
+        if (ref.resolved && ref.que_id !== null) {
+            providedFieldIds.add(String(ref.que_id));
+        }
+    }
+    for (const answer of normalizedAnswers) {
+        const queId = answer.queId;
+        if (queId !== undefined && queId !== null) {
+            providedFieldIds.add(String(normalizeQueId(queId)));
+        }
+    }
+    const questionRelations = asArray(formObj?.questionRelations);
+    const relationReferencedFieldIds = extractRelationReferencedFieldIds(questionRelations);
+    const optionLinks = collectWritePlanOptionLinks({
+        normalizedAnswers,
+        index,
+        providedFieldIds
+    });
+    const optionLinkedMissingIds = new Set();
+    for (const item of optionLinks) {
+        for (const linked of item.missing_linked_fields) {
+            if (linked.que_id !== null) {
+                optionLinkedMissingIds.add(String(linked.que_id));
+            }
+        }
+    }
+    const missingRequiredFields = [];
+    const likelyHiddenRequiredFields = [];
+    const readonlyOrSystemFields = [];
+    for (const field of fields) {
+        if (field.queId === undefined || field.queId === null) {
+            continue;
+        }
+        const queId = normalizeQueId(field.queId);
+        const required = extractFieldRequiredFlag(field);
+        const readonly = extractFieldReadonlyFlag(field);
+        const system = extractFieldSystemFlag(field);
+        const provided = providedFieldIds.has(String(queId));
+        if (provided && (readonly === true || system === true)) {
+            readonlyOrSystemFields.push({
+                que_id: queId,
+                que_title: asNullableString(field.queTitle),
+                que_type: field.queType ?? null,
+                reason: readonly === true && system === true
+                    ? "field looks readonly and system-managed"
+                    : readonly === true
+                        ? "field looks readonly"
+                        : "field looks system-managed"
+            });
+        }
+        if (provided || required !== true) {
+            continue;
+        }
+        const issue = {
+            que_id: queId,
+            que_title: asNullableString(field.queTitle),
+            que_type: field.queType ?? null,
+            reason: optionLinkedMissingIds.has(String(queId))
+                ? "required field is linked by a selected option but not provided"
+                : relationReferencedFieldIds.has(String(queId))
+                    ? "required field participates in questionRelations; it may be runtime-hidden/linked"
+                    : "required field not provided"
+        };
+        if (optionLinkedMissingIds.has(String(queId)) ||
+            relationReferencedFieldIds.has(String(queId))) {
+            likelyHiddenRequiredFields.push(issue);
+        }
+        else {
+            missingRequiredFields.push(issue);
+        }
+    }
+    if (questionRelations.length > 0) {
+        warnings.push(`form contains ${questionRelations.length} questionRelations; qf_write_plan can only provide static preflight and cannot fully evaluate runtime visibility/required rules`);
+    }
+    if (optionLinks.some((item) => item.missing_linked_fields.length > 0)) {
+        warnings.push("selected options link to additional fields that are not yet provided");
+    }
+    if (normalizedAnswers.length === 0 && invalidFields.length === 0) {
+        warnings.push("no normalized answers were produced from the current payload");
+    }
+    const blockers = [];
+    if (invalidFields.length > 0) {
+        blockers.push(`invalid fields: ${invalidFields.map((item) => item.message).join("; ")}`);
+    }
+    if (missingRequiredFields.length > 0) {
+        blockers.push(`missing required fields: ${missingRequiredFields
+            .map((item) => item.que_title ?? String(item.que_id ?? "unknown"))
+            .join(", ")}`);
+    }
+    if (likelyHiddenRequiredFields.length > 0) {
+        blockers.push(`linked or runtime-dependent required fields may still be missing: ${likelyHiddenRequiredFields
+            .map((item) => item.que_title ?? String(item.que_id ?? "unknown"))
+            .join(", ")}`);
+    }
+    if (readonlyOrSystemFields.length > 0) {
+        blockers.push(`payload includes readonly/system fields: ${readonlyOrSystemFields
+            .map((item) => item.que_title ?? String(item.que_id ?? "unknown"))
+            .join(", ")}`);
+    }
+    const recommendedNextActions = [
+        "Use qf_form_get to inspect field_summaries and write_format before final submit."
+    ];
+    if (missingRequiredFields.length > 0 || likelyHiddenRequiredFields.length > 0) {
+        recommendedNextActions.push("Fill missing required fields before calling qf_record_create or qf_record_update.");
+    }
+    if (optionLinks.some((item) => item.missing_linked_fields.length > 0)) {
+        recommendedNextActions.push("Provide fields linked by the currently selected options, or change the option values.");
+    }
+    if (invalidFields.some((item) => item.expected_format?.kind === "member_list")) {
+        recommendedNextActions.push("Use qf_users_list or qf_department_users_list to resolve valid userId values.");
+    }
+    if (invalidFields.some((item) => item.expected_format?.kind === "department_list")) {
+        recommendedNextActions.push("Use qf_departments_list to resolve valid deptId values.");
+    }
+    if (questionRelations.length > 0) {
+        recommendedNextActions.push("Even when ready_to_submit=true, final submit can still fail because runtime questionRelations are not fully evaluable via OpenAPI.");
+    }
+    return {
+        ok: true,
+        data: {
+            operation,
+            app_key: args.app_key,
+            apply_id: args.apply_id ?? null,
+            normalized_answers: normalizedAnswers,
+            resolved_fields: resolvedFields,
+            validation: {
+                valid: invalidFields.length === 0 &&
+                    missingRequiredFields.length === 0 &&
+                    likelyHiddenRequiredFields.length === 0 &&
+                    readonlyOrSystemFields.length === 0,
+                missing_required_fields: missingRequiredFields,
+                likely_hidden_required_fields: likelyHiddenRequiredFields,
+                readonly_or_system_fields: readonlyOrSystemFields,
+                invalid_fields: invalidFields,
+                warnings: uniqueStringList(warnings)
+            },
+            dependencies: {
+                question_relations_present: questionRelations.length > 0,
+                relation_count: questionRelations.length,
+                option_links: optionLinks
+            },
+            ready_to_submit: invalidFields.length === 0 &&
+                missingRequiredFields.length === 0 &&
+                likelyHiddenRequiredFields.length === 0 &&
+                readonlyOrSystemFields.length === 0,
+            blockers: uniqueStringList(blockers),
+            recommended_next_actions: uniqueStringList(recommendedNextActions)
+        },
+        meta: {
+            version: SERVER_VERSION,
+            generated_at: new Date().toISOString()
+        }
+    };
+}
+function collectWritePlanFieldRefs(params) {
+    const refs = [];
+    for (const fieldKey of Object.keys(params.fieldsInput ?? {})) {
+        refs.push(resolveWritePlanFieldRef({
+            source: "fields",
+            requested: fieldKey,
+            index: params.index
+        }));
+    }
+    for (const item of params.answersInput ?? []) {
+        const requestedRaw = item.que_id ?? item.queId ?? item.que_title ?? item.queTitle;
+        if (requestedRaw === undefined || requestedRaw === null) {
+            continue;
+        }
+        refs.push(resolveWritePlanFieldRef({
+            source: "answers",
+            requested: String(requestedRaw),
+            index: params.index
+        }));
+    }
+    return refs;
+}
+function resolveWritePlanFieldRef(params) {
+    const requested = params.requested.trim();
+    let field = null;
+    let reason = null;
+    if (requested) {
+        if (isNumericKey(requested)) {
+            field = params.index.byId.get(String(Number(requested))) ?? null;
+            if (!field) {
+                reason = "field not found in form metadata";
+            }
+        }
+        else {
+            try {
+                field = resolveFieldSelectorStrict({
+                    fieldKey: requested,
+                    index: params.index,
+                    tool: "qf_write_plan",
+                    location: `${params.source}.${requested}`
+                });
+            }
+            catch (error) {
+                reason = error instanceof Error ? error.message : String(error);
+            }
+        }
+    }
+    return {
+        source: params.source,
+        requested,
+        resolved: Boolean(field && field.queId !== undefined && field.queId !== null),
+        que_id: field?.queId !== undefined && field.queId !== null ? normalizeQueId(field.queId) : null,
+        que_title: asNullableString(field?.queTitle),
+        que_type: field?.queType ?? null,
+        required: field ? extractFieldRequiredFlag(field) : null,
+        readonly: field ? extractFieldReadonlyFlag(field) : null,
+        system: field ? extractFieldSystemFlag(field) : null,
+        write_format: field ? inferFieldWriteFormat(field) : null,
+        reason
+    };
+}
+function normalizeWritePlanErrors(error) {
+    if (error instanceof InputValidationError) {
+        const details = asObject(error.details);
+        const field = asObject(details?.field);
+        return [
+            {
+                location: asNullableString(details?.location),
+                message: error.message,
+                error_code: error.errorCode,
+                field: field
+                    ? {
+                        que_id: field.que_id ?? null,
+                        que_title: asNullableString(field.que_title),
+                        que_type: field.que_type ?? null
+                    }
+                    : null,
+                expected_format: details?.expected_format ?? null,
+                received_value: details?.received_value
+            }
+        ];
+    }
+    if (error instanceof z.ZodError) {
+        return error.issues.map((issue) => ({
+            location: issue.path.length > 0 ? issue.path.join(".") : null,
+            message: issue.message,
+            error_code: "INVALID_ARGUMENTS",
+            field: null,
+            expected_format: null,
+            received_value: undefined
+        }));
+    }
+    return [
+        {
+            location: null,
+            message: error instanceof Error ? error.message : String(error),
+            error_code: "WRITE_PLAN_ERROR",
+            field: null,
+            expected_format: null,
+            received_value: undefined
+        }
+    ];
+}
+function collectWritePlanOptionLinks(params) {
+    const links = [];
+    for (const answer of params.normalizedAnswers) {
+        const queId = answer.queId;
+        if (queId === undefined || queId === null) {
+            continue;
+        }
+        const field = params.index.byId.get(String(normalizeQueId(queId)));
+        const fieldObj = asObject(field);
+        const options = asArray(fieldObj?.options);
+        if (options.length === 0) {
+            continue;
+        }
+        const selected = collectSelectedOptionKeys(asArray(answer.values));
+        for (const optionRaw of options) {
+            const option = asObject(optionRaw);
+            if (!option) {
+                continue;
+            }
+            const optionIdRaw = option.optId ?? option.optionId ?? option.id ?? null;
+            const optionId = typeof optionIdRaw === "number" && Number.isFinite(optionIdRaw)
+                ? Math.trunc(optionIdRaw)
+                : (asNullableString(optionIdRaw) ?? null);
+            const optionValue = asNullableString(option.optValue ?? option.value ?? option.label ?? option.name);
+            const isSelected = (optionId !== null && selected.ids.has(String(optionId))) ||
+                (optionValue !== null && selected.values.has(optionValue.trim().toLowerCase()));
+            if (!isSelected) {
+                continue;
+            }
+            const linkedFieldIds = uniqueStringList(asArray(option.linkQueIds)
+                .map((item) => typeof item === "number"
+                ? String(Math.trunc(item))
+                : (asNullableString(item)?.trim() ?? ""))
+                .filter((item) => item.length > 0));
+            if (linkedFieldIds.length === 0) {
+                continue;
+            }
+            const linkedFields = linkedFieldIds.map((fieldId) => {
+                const linked = params.index.byId.get(String(Number(fieldId))) ?? params.index.byId.get(fieldId) ?? null;
+                return {
+                    que_id: linked?.queId !== undefined && linked.queId !== null
+                        ? normalizeQueId(linked.queId)
+                        : (isNumericKey(fieldId) ? Number(fieldId) : fieldId),
+                    que_title: asNullableString(linked?.queTitle),
+                    required: linked ? extractFieldRequiredFlag(linked) : null,
+                    provided: params.providedFieldIds.has(fieldId) || params.providedFieldIds.has(String(Number(fieldId)))
+                };
+            });
+            links.push({
+                source_que_id: normalizeQueId(queId),
+                source_que_title: asNullableString(field?.queTitle),
+                option_id: optionId ?? null,
+                option_value: optionValue,
+                linked_fields: linkedFields,
+                missing_linked_fields: linkedFields
+                    .filter((item) => !item.provided)
+                    .map((item) => ({
+                    que_id: item.que_id,
+                    que_title: item.que_title,
+                    required: item.required
+                }))
+            });
+        }
+    }
+    return links;
+}
+function collectSelectedOptionKeys(values) {
+    const ids = new Set();
+    const texts = new Set();
+    for (const value of values) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            ids.add(String(value));
+            texts.add(String(value).trim().toLowerCase());
+            continue;
+        }
+        const obj = asObject(value);
+        if (!obj) {
+            continue;
+        }
+        for (const candidate of [obj.optionId, obj.optId, obj.id]) {
+            if (candidate === undefined || candidate === null) {
+                continue;
+            }
+            ids.add(String(candidate));
+        }
+        for (const candidate of [obj.value, obj.dataValue, obj.valueStr, obj.label, obj.name]) {
+            const normalized = asNullableString(candidate)?.trim().toLowerCase();
+            if (normalized) {
+                texts.add(normalized);
+            }
+        }
+    }
+    return { ids, values: texts };
+}
+function extractRelationReferencedFieldIds(relations) {
+    const ids = new Set();
+    const visit = (value, keyHint = "") => {
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                visit(item, keyHint);
+            }
+            return;
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            if (keyHint && /queid|linkqueids/i.test(keyHint)) {
+                ids.add(String(Math.trunc(value)));
+            }
+            return;
+        }
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (trimmed && keyHint && /queid|linkqueids/i.test(keyHint)) {
+                ids.add(isNumericKey(trimmed) ? String(Number(trimmed)) : trimmed);
+            }
+            return;
+        }
+        const obj = asObject(value);
+        if (!obj) {
+            return;
+        }
+        for (const [key, child] of Object.entries(obj)) {
+            visit(child, key);
+        }
+    };
+    visit(relations);
+    return ids;
+}
+function extractFieldRequiredFlag(field) {
+    const obj = asObject(field);
+    if (!obj) {
+        return null;
+    }
+    return firstBooleanFromKeys(obj, ["required", "isRequired", "verifyRequired", "mustFill", "must_fill"]);
+}
+function extractFieldReadonlyFlag(field) {
+    const obj = asObject(field);
+    if (!obj) {
+        return null;
+    }
+    const direct = firstBooleanFromKeys(obj, ["readonly", "readOnly", "isReadonly", "isReadOnly"]);
+    if (direct !== null) {
+        return direct;
+    }
+    const editable = firstBooleanFromKeys(obj, ["editable", "isEditable"]);
+    return editable === null ? null : !editable;
+}
+function extractFieldSystemFlag(field) {
+    const obj = asObject(field);
+    if (!obj) {
+        return null;
+    }
+    return firstBooleanFromKeys(obj, ["system", "isSystem", "systemField", "isSystemField"]);
+}
+function firstBooleanFromKeys(obj, keys) {
+    for (const key of keys) {
+        if (typeof obj[key] === "boolean") {
+            return obj[key];
+        }
+    }
+    return null;
+}
 async function executeRecordsBatchGet(args) {
     if (!args.app_key) {
         throw missingRequiredFieldError({
@@ -7533,8 +8169,9 @@ function normalizeRecordItem(raw, includeAnswers) {
     return normalized;
 }
 function resolveAnswers(params) {
-    const normalizedFromFields = resolveFieldAnswers(params.fields, params.form, params.tool);
-    const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers);
+    const index = params.form ? buildFieldIndex(params.form) : null;
+    const normalizedFromFields = resolveFieldAnswers(params.fields, index, params.tool);
+    const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers, index, params.tool);
     const merged = new Map();
     for (const answer of normalizedFromFields) {
         merged.set(String(answer.queId), answer);
@@ -7547,12 +8184,12 @@ function resolveAnswers(params) {
     }
     return Array.from(merged.values());
 }
-function normalizeExplicitAnswers(answers) {
+function normalizeExplicitAnswers(answers, index, tool = "qf_record_create") {
     if (!answers?.length) {
         return [];
     }
     const output = [];
-    for (const item of answers) {
+    for (const [itemIndex, item] of answers.entries()) {
         const queId = item.que_id ?? item.queId;
         if (queId === undefined || queId === null || String(queId).trim() === "") {
             throw new Error("answer item requires que_id or queId");
@@ -7578,27 +8215,32 @@ function normalizeExplicitAnswers(answers) {
         if (values === undefined) {
             throw new Error(`answer item ${String(queId)} requires values or table_values`);
         }
-        normalized.values = values.map((value) => normalizeAnswerValue(value));
+        const field = resolveExplicitAnswerField(item, index);
+        normalized.values = values.map((value, valueIndex) => normalizeAnswerValue(value, {
+            field,
+            tool,
+            location: `answers[${itemIndex}].values[${valueIndex}]`
+        }));
         output.push(normalized);
     }
     return output;
 }
-function resolveFieldAnswers(fields, form, tool = "qf_record_create") {
+function resolveFieldAnswers(fields, index, tool = "qf_record_create") {
     const entries = Object.entries(fields ?? {});
     if (entries.length === 0) {
         return [];
     }
-    const index = buildFieldIndex(form);
+    const resolvedIndex = index ?? { byId: new Map(), byTitle: new Map() };
     const answers = [];
     for (const [fieldKey, fieldValue] of entries) {
         let field;
         if (isNumericKey(fieldKey)) {
-            field = resolveFieldByKey(fieldKey, index);
+            field = resolveFieldByKey(fieldKey, resolvedIndex);
         }
         else {
             field = resolveFieldSelectorStrict({
                 fieldKey,
-                index,
+                index: resolvedIndex,
                 tool,
                 location: `fields.${fieldKey}`
             });
@@ -7612,15 +8254,15 @@ function resolveFieldAnswers(fields, form, tool = "qf_record_create") {
                     tool,
                     location: `fields.${fieldKey}`,
                     requested: fieldKey,
-                    suggestions: buildFieldSuggestions(fieldKey, index)
+                    suggestions: buildFieldSuggestions(fieldKey, resolvedIndex)
                 }
             });
         }
-        answers.push(makeAnswerFromField(field, fieldValue));
+        answers.push(makeAnswerFromField(field, fieldValue, tool));
     }
     return answers;
 }
-function makeAnswerFromField(field, value) {
+function makeAnswerFromField(field, value, tool = "qf_record_create") {
     const base = {
         queId: field.queId
     };
@@ -7641,7 +8283,11 @@ function makeAnswerFromField(field, value) {
         if ("values" in objectValue) {
             return {
                 ...base,
-                values: asArray(objectValue.values).map((item) => normalizeAnswerValue(item))
+                values: asArray(objectValue.values).map((item, index) => normalizeAnswerValue(item, {
+                    field,
+                    tool,
+                    location: `fields.${String(field.queTitle ?? field.queId ?? "field")}.values[${index}]`
+                }))
             };
         }
     }
@@ -7654,10 +8300,38 @@ function makeAnswerFromField(field, value) {
     const valueArray = Array.isArray(value) ? value : [value];
     return {
         ...base,
-        values: valueArray.map((item) => normalizeAnswerValue(item))
+        values: valueArray.map((item, index) => normalizeAnswerValue(item, {
+            field,
+            tool,
+            location: `fields.${String(field.queTitle ?? field.queId ?? "field")}.values[${index}]`
+        }))
     };
 }
-function normalizeAnswerValue(value) {
+function resolveExplicitAnswerField(item, index) {
+    if (index) {
+        const rawQueId = item.que_id ?? item.queId;
+        if (rawQueId !== undefined && rawQueId !== null) {
+            const hit = index.byId.get(String(normalizeQueId(rawQueId)));
+            if (hit) {
+                return hit;
+            }
+        }
+        const rawQueTitle = item.que_title ?? item.queTitle;
+        if (typeof rawQueTitle === "string" && rawQueTitle.trim()) {
+            const candidates = index.byTitle.get(rawQueTitle.trim().toLowerCase()) ?? [];
+            if (candidates.length === 1) {
+                return candidates[0];
+            }
+        }
+    }
+    return {
+        queId: item.que_id ?? item.queId,
+        queTitle: item.que_title ?? item.queTitle,
+        queType: item.que_type ?? item.queType
+    };
+}
+function normalizeAnswerValue(value, params) {
+    validateWriteValueShape(params?.field ?? null, value, params);
     if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return {
             value,
@@ -7666,6 +8340,70 @@ function normalizeAnswerValue(value) {
     }
     return value;
 }
+function validateWriteValueShape(field, value, params) {
+    const writeFormat = field ? inferFieldWriteFormat(field) : null;
+    if (!writeFormat) {
+        return;
+    }
+    const validatedField = field;
+    if (!validatedField) {
+        return;
+    }
+    if (writeFormat.kind === "member_list" && !isValidMemberWriteValue(value)) {
+        throw fieldValueFormatError({
+            field: validatedField,
+            writeFormat,
+            value,
+            tool: params?.tool,
+            location: params?.location
+        });
+    }
+    if (writeFormat.kind === "department_list" && !isValidDepartmentWriteValue(value)) {
+        throw fieldValueFormatError({
+            field: validatedField,
+            writeFormat,
+            value,
+            tool: params?.tool,
+            location: params?.location
+        });
+    }
+}
+function isValidMemberWriteValue(value) {
+    const obj = asObject(value);
+    return Boolean(obj && asNullableString(obj.userId)?.trim());
+}
+function isValidDepartmentWriteValue(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        return false;
+    }
+    const deptId = obj.deptId;
+    return ((typeof deptId === "string" && deptId.trim().length > 0) ||
+        (typeof deptId === "number" && Number.isFinite(deptId)));
+}
+function fieldValueFormatError(params) {
+    const fieldLabel = asNullableString(params.field.queTitle)?.trim() ||
+        String(params.field.queId ?? "unknown_field");
+    const formatName = params.writeFormat.kind === "member_list" ? "成员字段" : "部门字段";
+    return new InputValidationError({
+        message: `${formatName} "${fieldLabel}" 的写入值格式不正确`,
+        errorCode: "FIELD_VALUE_FORMAT_ERROR",
+        fixHint: params.writeFormat.kind === "member_list"
+            ? '传对象数组，例如 [{"userId":"u_123","userName":"张三"}]；不要传纯字符串或 user_id。'
+            : '传对象数组，例如 [{"deptId":111,"deptName":"销售部"}]；不要传纯字符串或 dept_id。',
+        details: {
+            tool: params.tool ?? "qf_record_create",
+            location: params.location ?? null,
+            field: {
+                que_id: params.field.queId ?? null,
+                que_title: asNullableString(params.field.queTitle),
+                que_type: params.field.queType ?? null
+            },
+            expected_format: params.writeFormat,
+            received_value: params.value
+        }
+    });
+}
 function needsFormResolution(fields) {
     const keys = Object.keys(fields ?? {});
     if (!keys.length) {
@@ -7697,11 +8435,95 @@ function extractFieldSummaries(form) {
             que_id: field.queId ?? null,
             que_title: asNullableString(field.queTitle),
             que_type: field.queType,
+            write_format: inferFieldWriteFormat(field),
             has_sub_fields: sub.length > 0,
             sub_field_count: sub.length
         };
     });
 }
+function inferFieldWriteFormat(field) {
+    const kind = inferFieldWriteFormatKind(field.queType);
+    if (kind === "member_list") {
+        return {
+            kind,
+            description: "Pass one or more member objects in values[]. Each item must contain userId.",
+            item_shape: {
+                userId: "string",
+                userName: "string? (recommended)",
+                name: "string? (accepted alias)"
+            },
+            example: [
+                {
+                    userId: "u_123",
+                    userName: "张三"
+                }
+            ],
+            resolution_hint: "Use qf_users_list or qf_department_users_list to resolve valid userId values before writing."
+        };
+    }
+    if (kind === "department_list") {
+        return {
+            kind,
+            description: "Pass one or more department objects in values[]. Each item must contain deptId.",
+            item_shape: {
+                deptId: "string|number",
+                deptName: "string? (recommended)",
+                name: "string? (accepted alias)"
+            },
+            example: [
+                {
+                    deptId: 111,
+                    deptName: "销售部"
+                }
+            ],
+            resolution_hint: "Use qf_departments_list to resolve valid deptId values before writing."
+        };
+    }
+    return null;
+}
+function inferFieldWriteFormatKind(queType) {
+    const tokens = collectQueTypeTokens(queType);
+    if (tokens.some((token) => MEMBER_QUE_TYPE_KEYWORDS.some((keyword) => token.includes(keyword)))) {
+        return "member_list";
+    }
+    if (tokens.some((token) => DEPARTMENT_QUE_TYPE_KEYWORDS.some((keyword) => token.includes(keyword)))) {
+        return "department_list";
+    }
+    return null;
+}
+function collectQueTypeTokens(queType) {
+    const tokens = new Set();
+    const queue = [queType];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === null || current === undefined) {
+            continue;
+        }
+        if (typeof current === "string") {
+            const normalized = current.trim().toLowerCase();
+            if (normalized) {
+                tokens.add(normalized);
+            }
+            continue;
+        }
+        if (typeof current === "number" || typeof current === "boolean") {
+            tokens.add(String(current));
+            continue;
+        }
+        if (Array.isArray(current)) {
+            queue.push(...current);
+            continue;
+        }
+        const obj = asObject(current);
+        if (!obj) {
+            continue;
+        }
+        for (const value of Object.values(obj)) {
+            queue.push(value);
+        }
+    }
+    return Array.from(tokens);
+}
 function buildFieldIndex(form) {
     const byId = new Map();
     const byTitle = new Map();
@@ -8442,6 +9264,48 @@ function buildErrorExampleCalls(params) {
             }
         ];
     }
+    if (errorCode === "FIELD_VALUE_FORMAT_ERROR") {
+        const expectedFormat = asObject(params.details?.expected_format);
+        const kind = asNullableString(expectedFormat?.kind);
+        if (kind === "member_list") {
+            return [
+                {
+                    tool: "qf_form_get",
+                    arguments: {
+                        app_key: appKey
+                    },
+                    note: "先查看字段 write_format，确认成员字段写入 shape"
+                },
+                {
+                    tool: "qf_department_users_list",
+                    arguments: {
+                        dept_id: 111,
+                        fetch_child: false
+                    },
+                    note: "查询有效成员 userId，再按 [{userId,userName}] 写入"
+                }
+            ];
+        }
+        if (kind === "department_list") {
+            return [
+                {
+                    tool: "qf_form_get",
+                    arguments: {
+                        app_key: appKey
+                    },
+                    note: "先查看字段 write_format，确认部门字段写入 shape"
+                },
+                {
+                    tool: "qf_departments_list",
+                    arguments: {
+                        keyword: "销售",
+                        limit: 20
+                    },
+                    note: "查询有效部门 deptId，再按 [{deptId,deptName}] 写入"
+                }
+            ];
+        }
+    }
     if (errorCode === "INTERNAL_ERROR" || errorCode === "UNKNOWN_ERROR") {
         return [
             {

package/package.json

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