@wukongcrm/mcp-server 0.1.3

package/dist/tools.js

@@ -0,0 +1,858 @@
+import { CrmClient } from "./client.js";
+import { CRM_MODULES, ensureWritableModule, getModuleByKey } from "./modules.js";
+export function createToolHandlers(config = {}) {
+    const client = new CrmClient(config);
+    return {
+        crm_auth_status: async () => client.authStatus(),
+        crm_list_modules: () => ({
+            modules: CRM_MODULES.map(({ aliases: _aliases, ...moduleDefinition }) => moduleDefinition)
+        }),
+        crm_list_customer_pools: async (args) => listCustomerPools(client, args),
+        crm_get_module_schema: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            if (isPoolModule(moduleDefinition)) {
+                const poolContext = await resolvePoolContext(client, moduleDefinition, args);
+                const [fields, listHead] = await Promise.all([
+                    client.post(`${moduleDefinition.basePath}/queryPoolField`, undefined, cleanQuery({ poolId: poolContext.poolId, isFlat: args.isFlat ?? args.flat })),
+                    client.post(`${moduleDefinition.basePath}/queryPoolListHead`, undefined, { poolId: poolContext.poolId })
+                ]);
+                return { module: moduleDefinition.key, moduleName: moduleDefinition.name, pool: poolContext.pool, fields, listHead };
+            }
+            const id = args.id ?? args.recordId;
+            const [fields, listHead] = await Promise.all([
+                id
+                    ? client.post(`${moduleDefinition.basePath}/field/${id}`, undefined, cleanQuery({ type: args.type, poolId: args.poolId }))
+                    : client.post(`${moduleDefinition.basePath}/field`, undefined, cleanQuery({ type: args.type })),
+                client.post(`/crmField/queryListHead/${moduleDefinition.label}`, undefined, cleanQuery({ isHide: args.isHide ?? 0 }))
+            ]);
+            return { module: moduleDefinition.key, moduleName: moduleDefinition.name, fields, listHead };
+        },
+        crm_validate_field: async (args) => {
+            const path = args.contactDuplicateCheck ? "/crmField/contactDuplicateCheck" : "/crmField/verify";
+            return {
+                data: await client.post(path, args),
+                endpoint: path
+            };
+        },
+        crm_search_records: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const poolContext = isPoolModule(moduleDefinition) ? await resolvePoolContext(client, moduleDefinition, args) : undefined;
+            const searchList = buildSearchList(args, moduleDefinition);
+            const body = {
+                page: args.page ?? 1,
+                limit: args.limit ?? 15,
+                pageType: 1,
+                label: moduleDefinition.label,
+                poolId: poolContext?.poolId ?? args.poolId,
+                sortIds: args.sortIds,
+                searchList
+            };
+            return {
+                module: moduleDefinition.key,
+                moduleLabel: moduleDefinition.label,
+                pool: poolContext?.pool,
+                searchMode: searchList.length > 0 ? "advancedFilter" : "none",
+                data: await client.post(`${moduleDefinition.basePath}/queryPageList`, cleanObject(body))
+            };
+        },
+        crm_get_record: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const poolContext = isPoolModule(moduleDefinition) ? await resolvePoolContext(client, moduleDefinition, args) : undefined;
+            const recordModule = poolContext ? getPoolRecordModule(moduleDefinition) : moduleDefinition;
+            return {
+                module: moduleDefinition.key,
+                pool: poolContext?.pool,
+                data: await client.post(`${recordModule.basePath}/queryById/${args.id}`, undefined, cleanQuery({ poolId: poolContext?.poolId ?? args.poolId }))
+            };
+        },
+        crm_get_record_information: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const poolContext = isPoolModule(moduleDefinition) ? await resolvePoolContext(client, moduleDefinition, args) : undefined;
+            const recordModule = poolContext ? getPoolRecordModule(moduleDefinition) : moduleDefinition;
+            return {
+                module: moduleDefinition.key,
+                pool: poolContext?.pool,
+                data: await client.post(`${recordModule.basePath}/information/${args.id}`, undefined, cleanQuery({ poolId: poolContext?.poolId ?? args.poolId }))
+            };
+        },
+        crm_get_related_records: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            return callRelatedRecords(client, moduleDefinition, args);
+        },
+        crm_get_record_timeline: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const poolContext = isPoolModule(moduleDefinition) ? await resolvePoolContext(client, moduleDefinition, args) : undefined;
+            const activityModule = poolContext ? getPoolRecordModule(moduleDefinition) : moduleDefinition;
+            const body = {
+                page: args.page ?? 1,
+                limit: args.limit ?? 15,
+                pageType: 1,
+                label: activityModule.label,
+                typeId: args.id,
+                activityType: activityModule.label,
+                activityTypeId: args.id,
+                ...safeExtra(args.extra)
+            };
+            return {
+                module: moduleDefinition.key,
+                pool: poolContext?.pool,
+                data: await client.post("/crmActivity/queryActivityList", cleanObject(body))
+            };
+        },
+        crm_get_action_records: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const actionModule = isPoolModule(moduleDefinition) ? getPoolRecordModule(moduleDefinition) : moduleDefinition;
+            return {
+                module: moduleDefinition.key,
+                data: await client.post("/crmActionRecord/queryRecordList", undefined, {
+                    actionId: args.id,
+                    types: args.types ?? actionModule.label
+                })
+            };
+        },
+        crm_list_files: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            const poolContext = isPoolModule(moduleDefinition) ? await resolvePoolContext(client, moduleDefinition, args) : undefined;
+            const fileModule = poolContext ? getPoolRecordModule(moduleDefinition) : moduleDefinition;
+            return {
+                module: moduleDefinition.key,
+                pool: poolContext?.pool,
+                readonly: true,
+                data: await client.post(`${fileModule.basePath}/queryFileList`, undefined, cleanQuery({ id: args.id, fileType: args.fileType }))
+            };
+        },
+        crm_list_users: async (args) => ({
+            data: await client.post("/adminUser/queryUserList", cleanObject({
+                page: args.page ?? 1,
+                limit: args.limit ?? 15,
+                pageType: args.pageType ?? 1,
+                realname: args.realname,
+                username: args.username,
+                deptId: args.deptId,
+                status: args.status
+            }))
+        }),
+        crm_find_user_id: async (args) => {
+            const mode = args.mode ?? "realname";
+            const path = mode === "username" ? "/adminUser/getIdByUserName" : "/adminUser/getIdByRealName";
+            return {
+                mode,
+                data: await client.post(path, undefined, { userName: args.userName ?? args.name, companyId: args.companyId })
+            };
+        },
+        crm_list_departments: async (args) => ({
+            data: await client.post("/adminDept/queryDeptTree", cleanObject(args ?? {}))
+        }),
+        crm_find_dept_id: async (args) => ({
+            data: await client.post("/adminDept/getIdByDeptName", undefined, { deptName: args.deptName ?? args.name, companyId: args.companyId })
+        }),
+        crm_preview_write: (args) => previewWrite(args),
+        crm_update_customer: async (args) => {
+            const moduleDefinition = getModuleByKey("customer");
+            const targetPath = `${moduleDefinition.basePath}/updateInformation`;
+            const directId = args.customerId ?? args.id;
+            if (!args.confirm) {
+                return previewWrite({
+                    ...args,
+                    module: "customer",
+                    id: directId ?? "<需要通过客户查询唯一命中后填充>",
+                    operation: "updateInformation",
+                    targetPath
+                });
+            }
+            const resolvedRecord = directId ? undefined : await resolveUniqueRecord(client, moduleDefinition, args);
+            const id = directId ?? resolvedRecord?.[moduleDefinition.primaryKey] ?? resolvedRecord?.id;
+            const body = await buildUpdateInformationBody(client, moduleDefinition, { ...args, id });
+            const data = await client.post(targetPath, body);
+            const verification = args.verify === false ? undefined : await verifyInformationUpdate(client, moduleDefinition, body);
+            return cleanObject({
+                module: moduleDefinition.key,
+                targetPath,
+                resolvedRecord,
+                body,
+                data,
+                verification
+            });
+        },
+        crm_create_record: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            ensureWritableModule(moduleDefinition);
+            const targetPath = `${moduleDefinition.basePath}/add`;
+            if (!args.confirm) {
+                return previewWrite({ ...args, operation: "create", targetPath });
+            }
+            return {
+                module: moduleDefinition.key,
+                targetPath,
+                data: await client.post(targetPath, buildModelSaveBody(args))
+            };
+        },
+        crm_update_record_fields: async (args) => {
+            const moduleDefinition = getModuleByKey(args.module);
+            ensureWritableModule(moduleDefinition);
+            const targetPath = `${moduleDefinition.basePath}/updateInformation`;
+            if (!args.confirm) {
+                return previewWrite({ ...args, operation: "updateInformation", targetPath });
+            }
+            const body = await buildUpdateInformationBody(client, moduleDefinition, args);
+            const data = await client.post(targetPath, body);
+            const verification = args.verify === false ? undefined : await verifyInformationUpdate(client, moduleDefinition, body);
+            return {
+                module: moduleDefinition.key,
+                targetPath,
+                body,
+                data,
+                verification
+            };
+        },
+        crm_add_followup: async (args) => {
+            const targetPath = "/crmActivity/add";
+            if (!args.confirm) {
+                return previewWrite({ ...args, operation: "addFollowup", targetPath });
+            }
+            return {
+                module: "activity",
+                targetPath,
+                data: await client.post(targetPath, buildFollowupSaveBody(args))
+            };
+        },
+        crm_update_followup: async (args) => {
+            const targetPath = args.useInformationUpdate ? "/crmActivity/updateInformation" : "/crmActivity/update";
+            if (!args.confirm) {
+                return previewWrite({ ...args, operation: "updateFollowup", targetPath });
+            }
+            const body = args.useInformationUpdate
+                ? cleanObject({ id: args.id, label: 19, list: args.list ?? args.fields ?? [], batchId: args.batchId })
+                : buildFollowupSaveBody(args);
+            return {
+                module: "activity",
+                targetPath,
+                data: await client.post(targetPath, body)
+            };
+        }
+    };
+}
+const FIELD_SEARCH_CONTAINS = 3;
+const QUICK_SEARCH_FIELDS = {
+    leads: [
+        { fieldName: "leadsName", formType: "text" },
+        { fieldName: "mobile", formType: "mobile" },
+        { fieldName: "telephone", formType: "text" }
+    ],
+    leadsPool: [
+        { fieldName: "leadsName", formType: "text" },
+        { fieldName: "mobile", formType: "mobile" },
+        { fieldName: "telephone", formType: "text" }
+    ],
+    customer: [
+        { fieldName: "customerName", formType: "text" },
+        { fieldName: "mobile", formType: "mobile" },
+        { fieldName: "telephone", formType: "text" }
+    ],
+    customerPool: [
+        { fieldName: "customerName", formType: "text" },
+        { fieldName: "mobile", formType: "mobile" },
+        { fieldName: "telephone", formType: "text" }
+    ],
+    contacts: [
+        { fieldName: "name", formType: "text" },
+        { fieldName: "mainFieldValue", formType: "text" },
+        { fieldName: "mobile", formType: "mobile" },
+        { fieldName: "telephone", formType: "text" },
+        { fieldName: "email", formType: "email" }
+    ],
+    business: [{ fieldName: "businessName", formType: "text" }],
+    product: [{ fieldName: "name", formType: "text" }],
+    contract: [
+        { fieldName: "num", formType: "text" },
+        { fieldName: "name", formType: "text" },
+        { fieldName: "customerName", formType: "text" }
+    ],
+    receivables: [
+        { fieldName: "number", formType: "text" },
+        { fieldName: "customerName", formType: "text" }
+    ],
+    receivablesPlan: [
+        { fieldName: "customerName", formType: "text" },
+        { fieldName: "contractNum", formType: "text" }
+    ],
+    invoice: [
+        { fieldName: "invoiceApplyNumber", formType: "text" },
+        { fieldName: "invoiceNumber", formType: "text" },
+        { fieldName: "customerName", formType: "text" }
+    ],
+    activity: [{ fieldName: "content", formType: "text" }],
+    quotation: [
+        { fieldName: "name", formType: "text" },
+        { fieldName: "num", formType: "text" },
+        { fieldName: "customerName", formType: "text" }
+    ],
+    returnVisit: [
+        { fieldName: "customerName", formType: "text" },
+        { fieldName: "contractNum", formType: "text" }
+    ],
+    visitPlan: [
+        { fieldName: "customerName", formType: "text" },
+        { fieldName: "contactsName", formType: "text" }
+    ]
+};
+const NAME_FIELD_BY_MODULE = {
+    leads: { fieldName: "leadsName", formType: "text" },
+    leadsPool: { fieldName: "leadsName", formType: "text" },
+    customer: { fieldName: "customerName", formType: "text" },
+    customerPool: { fieldName: "customerName", formType: "text" },
+    contacts: { fieldName: "name", formType: "text" },
+    business: { fieldName: "businessName", formType: "text" },
+    product: { fieldName: "name", formType: "text" },
+    contract: { fieldName: "name", formType: "text" },
+    quotation: { fieldName: "name", formType: "text" }
+};
+function buildSearchList(args, moduleDefinition) {
+    const explicitSearchList = toArray(args.filters ?? args.searchList);
+    const semanticSearchList = buildSemanticSearchList(args, moduleDefinition);
+    if (explicitSearchList.length > 0 && semanticSearchList.length > 0) {
+        return [...explicitSearchList, ...semanticSearchList];
+    }
+    if (explicitSearchList.length > 0) {
+        return explicitSearchList;
+    }
+    return semanticSearchList;
+}
+function buildSemanticSearchList(args, moduleDefinition) {
+    const keyword = firstTextValue(args.keyword, args.query, args.q, args.search, args.searchText, args.text, args.term);
+    if (keyword) {
+        return containsFilters(QUICK_SEARCH_FIELDS[moduleDefinition.key] ?? [], keyword, 1);
+    }
+    const phone = firstTextValue(args.phone, args.mobile, args.telephone);
+    if (phone) {
+        const fields = (QUICK_SEARCH_FIELDS[moduleDefinition.key] ?? []).filter((field) => ["mobile", "telephone", "phone"].includes(field.fieldName));
+        return containsFilters(fields, phone, 1);
+    }
+    const name = firstTextValue(args.name, args.customerName, args.leadsName, args.contactsName, args.businessName, args.productName, args.contractName, args.quotationName);
+    const nameField = NAME_FIELD_BY_MODULE[moduleDefinition.key];
+    if (name && nameField) {
+        return containsFilters([nameField], name, 0);
+    }
+    const email = firstTextValue(args.email);
+    if (email) {
+        return containsFilters([{ fieldName: "email", formType: "email" }], email, 0);
+    }
+    return [];
+}
+function containsFilters(fields, value, startGroupId) {
+    return fields.map((field, index) => ({
+        fieldName: field.fieldName,
+        formType: field.formType,
+        type: FIELD_SEARCH_CONTAINS,
+        searchEnum: FIELD_SEARCH_CONTAINS,
+        values: [value],
+        groupId: fields.length > 1 ? startGroupId + index : startGroupId
+    }));
+}
+function firstTextValue(...values) {
+    for (const value of values) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const text = String(value).trim();
+        if (text) {
+            return text;
+        }
+    }
+    return undefined;
+}
+function toArray(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (value && typeof value === "object") {
+        return [value];
+    }
+    return [];
+}
+async function resolveUniqueRecord(client, moduleDefinition, args) {
+    const searchList = buildSearchList(args, moduleDefinition);
+    if (searchList.length === 0) {
+        throw new Error(`请提供可定位${moduleDefinition.name}的 customerId/id、phone/mobile、name/customerName 或 keyword。`);
+    }
+    const page = await client.post(`${moduleDefinition.basePath}/queryPageList`, cleanObject({
+        page: 1,
+        limit: 2,
+        pageType: 1,
+        label: moduleDefinition.label,
+        searchList
+    }));
+    const list = Array.isArray(page.list) ? page.list : [];
+    if (list.length !== 1) {
+        throw new Error(`需要唯一命中的${moduleDefinition.name}才能写入，当前命中 ${page.totalRow ?? list.length} 条，请先缩小查询条件或直接传入 ID。`);
+    }
+    return list[0];
+}
+async function buildUpdateInformationBody(client, moduleDefinition, args) {
+    const rawBody = buildUpdateInformationPreviewBody(moduleDefinition, args);
+    const fields = await fetchModuleFields(client, moduleDefinition, args);
+    const list = hydrateUpdateList(rawBody.list ?? [], fields);
+    const batchId = rawBody.batchId ?? await resolveUpdateBatchId(client, moduleDefinition, rawBody, list);
+    return {
+        ...rawBody,
+        batchId,
+        list
+    };
+}
+function buildUpdateInformationPreviewBody(moduleDefinition, args) {
+    return cleanObject({
+        id: args.id ?? args[moduleDefinition.primaryKey],
+        label: moduleDefinition.label,
+        list: rawUpdateList(args),
+        batchId: args.batchId,
+        idList: args.idList,
+        ownerUserSave: args.ownerUserSave
+    });
+}
+function rawUpdateList(args) {
+    const raw = args.list ?? args.fields ?? args.field;
+    const list = toArray(raw);
+    if (list.length > 0) {
+        return list;
+    }
+    const updates = args.updates;
+    if (!updates || typeof updates !== "object" || Array.isArray(updates)) {
+        return [];
+    }
+    return Object.entries(updates).map(([key, value]) => looksLikeFieldName(key) ? { fieldName: key, value } : { name: key, value });
+}
+function looksLikeFieldName(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+async function fetchModuleFields(client, moduleDefinition, args) {
+    const id = args.id ?? args[moduleDefinition.primaryKey];
+    const path = id ? `${moduleDefinition.basePath}/field/${id}` : `${moduleDefinition.basePath}/field`;
+    const data = await client.post(path, undefined, cleanQuery({ type: args.type, poolId: args.poolId }));
+    return flattenFieldDefinitions(data);
+}
+function flattenFieldDefinitions(input) {
+    const output = [];
+    const seen = new Set();
+    const visit = (value) => {
+        if (!value || typeof value !== "object" || seen.has(value)) {
+            return;
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        const record = value;
+        if (record.fieldName || record.fieldId || (record.name && (record.fieldType !== undefined || record.type !== undefined || record.formType))) {
+            output.push(record);
+        }
+        for (const child of Object.values(record)) {
+            if (child && typeof child === "object") {
+                visit(child);
+            }
+        }
+    };
+    visit(input);
+    return output;
+}
+function hydrateUpdateList(list, fields) {
+    return list.map((item) => hydrateUpdateItem(item, fields));
+}
+function hydrateUpdateItem(item, fields) {
+    const field = findFieldDefinition(item, fields);
+    if (!field && hasUpdateMetadata(item)) {
+        return normalizeUpdateItem(item);
+    }
+    if (!field) {
+        const fieldLabel = item.name ?? item.fieldName ?? item.fieldId ?? "<unknown>";
+        throw new Error(`未在字段 schema 中找到可写字段：${fieldLabel}。请先调用 crm_get_module_schema 确认字段名。`);
+    }
+    const merged = cleanObject({
+        fieldId: item.fieldId ?? field.fieldId ?? field.id,
+        fieldName: item.fieldName ?? field.fieldName,
+        name: item.name ?? field.name,
+        fieldType: item.fieldType ?? field.fieldType,
+        type: item.type ?? field.type,
+        formType: item.formType ?? field.formType,
+        value: normalizeOptionValue(item.value, field)
+    });
+    return normalizeUpdateItem(merged);
+}
+function hasUpdateMetadata(item) {
+    return Boolean(item.fieldName && item.fieldType !== undefined && item.type !== undefined);
+}
+function normalizeUpdateItem(item) {
+    return cleanObject({
+        fieldId: item.fieldId,
+        fieldName: item.fieldName,
+        name: item.name,
+        fieldType: item.fieldType,
+        type: item.type,
+        formType: item.formType,
+        value: item.value
+    });
+}
+async function resolveUpdateBatchId(client, moduleDefinition, body, list) {
+    if (body.batchId || !body.id || !updateNeedsBatchId(list)) {
+        return undefined;
+    }
+    const data = await client.post(`${moduleDefinition.basePath}/queryById/${body.id}`);
+    return findFirstValueByKey(data, "batchId");
+}
+function updateNeedsBatchId(list) {
+    return list.some((item) => {
+        const fieldType = Number(item.fieldType);
+        return fieldType === 0 || fieldType === 2;
+    });
+}
+function findFirstValueByKey(input, key) {
+    const seen = new Set();
+    const visit = (value) => {
+        if (!value || typeof value !== "object" || seen.has(value)) {
+            return undefined;
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = visit(item);
+                if (found !== undefined && found !== null && found !== "") {
+                    return found;
+                }
+            }
+            return undefined;
+        }
+        const record = value;
+        if (record[key] !== undefined && record[key] !== null && record[key] !== "") {
+            return record[key];
+        }
+        for (const child of Object.values(record)) {
+            const found = visit(child);
+            if (found !== undefined && found !== null && found !== "") {
+                return found;
+            }
+        }
+        return undefined;
+    };
+    return visit(input);
+}
+function findFieldDefinition(item, fields) {
+    const fieldId = item.fieldId !== undefined ? String(item.fieldId) : undefined;
+    const fieldName = normalizeText(item.fieldName);
+    const name = normalizeText(item.name);
+    return fields.find((field) => {
+        if (fieldId && String(field.fieldId ?? field.id) === fieldId) {
+            return true;
+        }
+        if (fieldName && normalizeText(field.fieldName) === fieldName) {
+            return true;
+        }
+        return Boolean(name && normalizeText(field.name) === name);
+    });
+}
+function normalizeOptionValue(value, field) {
+    const options = parseFieldOptions(field.options ?? field.setting ?? field.optionsData);
+    if (options.length === 0 || value === undefined || value === null || value === "") {
+        return value;
+    }
+    const valueText = normalizeText(value);
+    const match = options.find((option) => [option.value, option.name, option.label].some((candidate) => normalizeText(candidate) === valueText));
+    if (!match) {
+        const available = options.map((option) => option.name ?? option.label ?? option.value).filter((option) => option !== undefined);
+        throw new Error(`字段“${field.name ?? field.fieldName}”的可选值不包含“${value}”。可选值：${available.join("、")}`);
+    }
+    return value;
+}
+function parseFieldOptions(input) {
+    if (!input) {
+        return [];
+    }
+    if (Array.isArray(input)) {
+        return input.map((option) => (typeof option === "object" && option ? option : { value: option, name: option }));
+    }
+    if (typeof input === "string") {
+        const text = input.trim();
+        if (!text) {
+            return [];
+        }
+        try {
+            return parseFieldOptions(JSON.parse(text));
+        }
+        catch {
+            return text.split(",").map((option) => option.trim()).filter(Boolean).map((option) => ({ value: option, name: option }));
+        }
+    }
+    if (typeof input === "object") {
+        const object = input;
+        return parseFieldOptions(object.options ?? object.list ?? object.data ?? []);
+    }
+    return [];
+}
+async function verifyInformationUpdate(client, moduleDefinition, body) {
+    const endpoint = `${moduleDefinition.basePath}/information/${body.id}`;
+    const data = await client.post(endpoint);
+    const checked = (body.list ?? []).map((item) => {
+        const actualValue = findInformationValue(data, item);
+        return {
+            fieldName: item.fieldName,
+            name: item.name,
+            expectedValue: item.value,
+            actualValue,
+            matched: valuesMatch(item.value, actualValue)
+        };
+    });
+    return {
+        endpoint,
+        ok: checked.every((item) => item.matched),
+        checked
+    };
+}
+function findInformationValue(data, field) {
+    const direct = findDirectInformationValue(data, field);
+    if (direct.found) {
+        return direct.value;
+    }
+    const seen = new Set();
+    const wantedFieldName = normalizeText(field.fieldName);
+    const wantedName = normalizeText(field.name);
+    const visit = (value) => {
+        if (!value || typeof value !== "object" || seen.has(value)) {
+            return { found: false };
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const result = visit(item);
+                if (result.found) {
+                    return result;
+                }
+            }
+            return { found: false };
+        }
+        const record = value;
+        const recordFieldName = normalizeText(record.fieldName);
+        const recordName = normalizeText(record.name);
+        if ((wantedFieldName && recordFieldName === wantedFieldName) || (wantedName && recordName === wantedName)) {
+            return { found: true, value: extractInformationValue(record) };
+        }
+        for (const child of Object.values(record)) {
+            const result = visit(child);
+            if (result.found) {
+                return result;
+            }
+        }
+        return { found: false };
+    };
+    return visit(data).value;
+}
+function findDirectInformationValue(data, field) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return { found: false };
+    }
+    const record = data;
+    if (field.fieldName && Object.prototype.hasOwnProperty.call(record, field.fieldName)) {
+        return { found: true, value: record[field.fieldName] };
+    }
+    return { found: false };
+}
+function extractInformationValue(record) {
+    if (Object.prototype.hasOwnProperty.call(record, "value")) {
+        return record.value;
+    }
+    if (Object.prototype.hasOwnProperty.call(record, "valueDesc")) {
+        return record.valueDesc;
+    }
+    if (Object.prototype.hasOwnProperty.call(record, "fieldValue")) {
+        return record.fieldValue;
+    }
+    return undefined;
+}
+function valuesMatch(expected, actual) {
+    return normalizeComparableValue(expected) === normalizeComparableValue(actual);
+}
+function normalizeComparableValue(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "object") {
+        return JSON.stringify(value);
+    }
+    return String(value).trim();
+}
+function normalizeText(value) {
+    return value === undefined || value === null ? "" : String(value).trim().toLowerCase();
+}
+async function listCustomerPools(client, args) {
+    const pools = await client.post("/crmCustomerPool/queryPoolNameListByAuth");
+    const poolList = Array.isArray(pools) ? pools : [];
+    const includeSamples = Boolean(args.includeSamples);
+    const limit = includeSamples ? positiveInteger(args.sampleLimit ?? args.limit, 3) : 1;
+    const searchList = args.filters ?? args.searchList ?? [];
+    const poolSummaries = await Promise.all(poolList.map(async (pool) => {
+        const poolId = pool.poolId ?? pool.id;
+        if (!poolId) {
+            throw new Error("客户公海授权列表缺少 poolId，无法统计池内客户数量。");
+        }
+        const page = await client.post("/crmCustomerPool/queryPageList", cleanObject({
+            page: 1,
+            limit,
+            pageType: 1,
+            label: 9,
+            poolId,
+            searchList
+        }));
+        const summary = {
+            poolId,
+            poolName: pool.poolName ?? pool.name,
+            customerCount: page.totalRow ?? page.total ?? 0
+        };
+        if (includeSamples) {
+            const list = Array.isArray(page.list) ? page.list : [];
+            summary.samples = list.map((record) => ({
+                customerId: record.customerId ?? record.id,
+                customerName: record.customerName ?? record.name,
+                ownerUserName: record.ownerUserName,
+                createTime: record.createTime
+            }));
+        }
+        return summary;
+    }));
+    return {
+        module: "customerPool",
+        readonly: true,
+        poolCount: poolSummaries.length,
+        pools: poolSummaries
+    };
+}
+function positiveInteger(value, fallback) {
+    const numberValue = Number(value);
+    if (!Number.isInteger(numberValue) || numberValue < 1) {
+        return fallback;
+    }
+    return numberValue;
+}
+function isPoolModule(moduleDefinition) {
+    return moduleDefinition.key === "customerPool" || moduleDefinition.key === "leadsPool";
+}
+function getPoolRecordModule(moduleDefinition) {
+    return getModuleByKey(moduleDefinition.key === "customerPool" ? "customer" : "leads");
+}
+async function resolvePoolContext(client, moduleDefinition, args) {
+    if (!isPoolModule(moduleDefinition)) {
+        throw new Error(`Module ${moduleDefinition.key} is not a pool module.`);
+    }
+    if (args.poolId) {
+        return { poolId: args.poolId, pool: cleanObject({ poolId: args.poolId, poolName: args.poolName }) };
+    }
+    const pools = await client.post(`${moduleDefinition.basePath}/queryPoolNameListByAuth`);
+    const poolList = Array.isArray(pools) ? pools : [];
+    const selectedPool = args.poolName
+        ? poolList.find((pool) => String(pool.poolName ?? pool.name ?? "").trim() === String(args.poolName).trim())
+        : poolList[0];
+    if (!selectedPool) {
+        throw new Error(`当前账号没有可查询的${moduleDefinition.name}，请确认公海/线索池权限或传入 poolId。`);
+    }
+    const poolId = selectedPool.poolId ?? selectedPool.id;
+    if (!poolId) {
+        throw new Error(`${moduleDefinition.name}授权列表缺少 poolId，无法查询池内数据。`);
+    }
+    return { poolId, pool: selectedPool };
+}
+async function callRelatedRecords(client, moduleDefinition, args) {
+    const relation = String(args.relation ?? args.type ?? "").trim();
+    const pageBody = cleanObject({ page: args.page ?? 1, limit: args.limit ?? 15, pageType: 1, id: args.id, ...safeExtra(args.extra) });
+    if (moduleDefinition.key === "business" && relation === "product") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmBusiness/queryProduct", pageBody) };
+    }
+    if (moduleDefinition.key === "business" && relation === "contacts") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmBusiness/queryContacts", pageBody) };
+    }
+    if (moduleDefinition.key === "contacts" && relation === "business") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmContacts/queryBusiness", pageBody) };
+    }
+    if (moduleDefinition.key === "contract" && relation === "product") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmContract/queryProductListByContractId", pageBody) };
+    }
+    if (moduleDefinition.key === "contract" && relation === "receivablesPlan") {
+        return {
+            module: moduleDefinition.key,
+            relation,
+            data: await client.post("/crmContract/queryReceivablesPlansByContractId", undefined, {
+                contractId: args.id,
+                receivablesId: args.receivablesId,
+                productId: args.productId
+            })
+        };
+    }
+    if (moduleDefinition.key === "receivables" && relation === "product") {
+        return { module: moduleDefinition.key, relation, data: await client.post(`/crmReceivables/queryProductList/${args.id}`) };
+    }
+    if (moduleDefinition.key === "quotation" && relation === "product") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmQuotation/queryProductList", pageBody) };
+    }
+    if (moduleDefinition.key === "product" && relation === "saleProduct") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmProduct/querySaleProductPageList", pageBody) };
+    }
+    if (moduleDefinition.key === "receivablesPlan" && relation === "contractCustomer") {
+        return { module: moduleDefinition.key, relation, data: await client.post("/crmReceivablesPlan/queryByContractAndCustomer", pageBody) };
+    }
+    throw new Error(`当前 MCP 未配置“${moduleDefinition.name} / ${relation}”关联查询白名单。`);
+}
+function previewWrite(args) {
+    const moduleDefinition = args.module ? getModuleByKey(args.module) : undefined;
+    const targetPath = args.targetPath ?? (moduleDefinition ? `${moduleDefinition.basePath}/${args.operation === "create" ? "add" : "updateInformation"}` : "/crmActivity/add");
+    const body = args.updateBody
+        ?? (args.operation === "updateInformation" && moduleDefinition
+            ? buildUpdateInformationPreviewBody(moduleDefinition, args)
+            : args.useInformationUpdate
+                ? cleanObject({ id: args.id, label: 19, list: rawUpdateList(args), batchId: args.batchId })
+                : (args.operation === "addFollowup" || args.operation === "updateFollowup")
+                    ? buildFollowupSaveBody(args)
+                    : buildModelSaveBody(args));
+    return {
+        preview: true,
+        message: "写入前预览：未传 confirm=true，MCP 不会调用 72CRM 写接口。",
+        module: moduleDefinition?.key ?? args.module ?? "activity",
+        moduleName: moduleDefinition?.name ?? "跟进记录",
+        targetPath,
+        body
+    };
+}
+function buildModelSaveBody(args) {
+    return cleanObject({
+        entity: args.entity ?? {},
+        field: args.field ?? args.fields ?? [],
+        saveType: args.saveType,
+        fileId: args.fileId,
+        aiAnalysis: args.aiAnalysis,
+        member: args.member
+    });
+}
+function buildFollowupSaveBody(args) {
+    const body = buildModelSaveBody(args);
+    const sourceEntity = body.entity && typeof body.entity === "object" && !Array.isArray(body.entity)
+        ? body.entity
+        : {};
+    const entity = { ...sourceEntity };
+    if (!Array.isArray(entity.relateDataList)) {
+        entity.relateDataList = [];
+    }
+    return {
+        ...body,
+        entity
+    };
+}
+function cleanQuery(input) {
+    return cleanObject(input);
+}
+function cleanObject(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined && value !== null) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+function safeExtra(extra) {
+    return extra && typeof extra === "object" && !Array.isArray(extra) ? extra : {};
+}