@wukongcrm/mcp-server 0.2.3 → 0.2.5

package/README.md

@@ -147,7 +147,7 @@ npm pack
 生成文件示例：
 
 ```text
-wukongcrm-mcp-server-0.2.3.tgz
+wukongcrm-mcp-server-0.2.4.tgz
 ```
 
 这个包只包含运行所需的 `dist`、`README.md` 和 `package.json`，不会携带源码、测试文件或用户 API Key。
@@ -155,7 +155,7 @@ wukongcrm-mcp-server-0.2.3.tgz
 使用者拿到 `.tgz` 后安装：
 
 ```powershell
-npm install -g .\wukongcrm-mcp-server-0.2.3.tgz
+npm install -g .\wukongcrm-mcp-server-0.2.4.tgz
 ```
 
 安装后可以直接用命令启动：
@@ -189,7 +189,7 @@ wukong-mcp
 无代码工具只调用源码中声明的固定接口，不提供任意 URL 透传。写工具保持既有 MCP 语义：未传 `confirm=true` 时返回将要调用的接口、请求体和查询参数；明确确认后才执行。
 
 - 应用与模块：`nocode_list_applications`、`nocode_get_application`、`nocode_list_modules`、`nocode_get_module`、`nocode_write_application`、`nocode_write_module`
-- 字段与数据：`nocode_get_module_schema`、`nocode_query_fields`、`nocode_search_records`、`nocode_get_record`、`nocode_query_records`、`nocode_calculate_formula`、`nocode_check_duplicate`、`nocode_write_field`、`nocode_write_record`
+- 字段与数据：`nocode_get_module_schema`、`nocode_query_fields`、`nocode_search_records`、`nocode_get_record`、`nocode_query_records`、`nocode_calculate_formula`、`nocode_check_duplicate`、`nocode_write_field`、`nocode_replace_field_with_relation`、`nocode_write_record`
 - 权限与团队：`nocode_list_team_members`、`nocode_get_permissions`、`nocode_write_team`、`nocode_write_role`
 - 场景与页面：`nocode_list_scenes`、`nocode_list_tabs`、`nocode_get_module_file`、`nocode_write_scene`、`nocode_write_tab`
 - 流程与阶段：`nocode_list_flows`、`nocode_list_stages`、`nocode_list_custom_buttons`、`nocode_query_workflow`、`nocode_write_flow`、`nocode_write_stage`、`nocode_write_custom_button`、`nocode_write_workflow`
@@ -201,8 +201,10 @@ wukong-mcp
 常见保存动作必须使用旧前端对应的聚合 BO，而不是把单个字段或单个值直接作为 `payload`：
 
 - 字段保存：`ModuleFieldSaveBO`，至少包含 `moduleId`、实际 `version`、`mainFieldId`/`tempMainFieldId` 和非空 `moduleFieldList`。
+- 普通字段改为数据关联：优先使用 `nocode_replace_field_with_relation`。它会按 `baseVersion` 读取完整字段聚合，阻断主字段、明细字段、已有关系、非空数据和删除依赖，保存草稿后再回读验证；不会自动发布。
 - 记录保存：`ModuleFieldDataSaveBO`，至少包含 `moduleId`、实际 `version` 和非空 `fieldDataList`；字段值使用 `fieldId`、`fieldName`、`name`、`type`、`value`，修改时增加 `dataId`。
 - 新建模块的实际版本通常从 `0` 开始，应先用 `nocode_get_module` 读取并显式传入，不能根据已发布老模块猜测为 `1`。
+- 发布模块时，`nocode_write_module(action=publish)` 必须显式传入预览确认过的最新草稿 `version`；旧后端发布接口虽不接收版本，MCP 会在调用前校验版本并在调用后校验激活状态。
 
 文件流仍有意不经 MCP 代理，因此应用导入/导出、Excel 导入/导出、跟进导出、打印 PDF/Word 下载不在工具中；打印内容生成和预览 JSON 接口仍可使用。内部测试接口 `/moduleMQ/send` 也不会暴露。
 
@@ -395,13 +397,34 @@ wukong-mcp
     {
       "fieldName": "ownerUserId",
       "formType": "user",
-      "type": 1,
+      "type": 3,
       "values": ["张三"]
     }
   ]
 }
 ```
 
+旧 CRM 的人员筛选只会处理操作 `3`（包含）、`4`（不包含）、`5`（为空）和 `6`（不为空）；其中按人员 ID 匹配必须使用 `type=3`。MCP 的人员便捷参数会固定生成操作 `3`，显式传入未实现的人员操作会在请求后端前报错，避免返回未按人员过滤的数据。
+
+日期字段必须明确传 `formType=date` 或 `formType=datetime`。固定范围使用操作 `14`，`values` 按开始、结束顺序提供两个值；`date` 使用 `YYYY-MM-DD`，`datetime` 使用 `YYYY-MM-DD HH:mm:ss`。查询完整自然日时，边界为当天 `00:00:00` 和 `23:59:59`，后端范围两端均包含：
+
+```json
+{
+  "module": "activity",
+  "createUserName": "<人员唯一昵称>",
+  "filters": [
+    {
+      "fieldName": "createTime",
+      "formType": "datetime",
+      "type": 14,
+      "values": ["YYYY-MM-DD 00:00:00", "YYYY-MM-DD 23:59:59"]
+    }
+  ]
+}
+```
+
+`filters` 和 `searchList` 是同一个高级筛选参数的两个名称，只能选一个。每项必须提供字段名和 `type`/`searchEnum`；两种操作码同时出现时必须相同。除操作 `5`/`6` 外必须提供非空 `values`。日期范围也可传后端已有的单个预设时间值（例如 `today`、`week`、`month`）；不支持的操作、无效日期、倒置边界和缺失值会明确报错。
+
 如需单独核对用户 ID，可调用 `crm_find_user_id`：
 
 ```json

package/dist/nocode.js

@@ -246,7 +246,7 @@ export const nocodeToolDefinitions = [
     },
     {
         name: "nocode_write_module",
-        description: "保存、启停、复制、发布、丢弃草稿、删除模块、保存页面布局或维护 BI Dashboard 模块；action=save 的 payload 使用旧 CRM ModuleSaveBO（常见普通模块包含 applicationId、name、moduleType=1、icon）；必须 confirm=true。",
+        description: "保存、启停、复制、发布、丢弃草稿、删除模块、保存页面布局或维护 BI Dashboard 模块；action=save 的 payload 使用旧 CRM ModuleSaveBO（常见普通模块包含 applicationId、name、moduleType=1、icon）；action=publish 必须显式传 version，工具会锁定当前最新草稿版本；必须 confirm=true。",
         schema: z.object({
             action: z.enum(["save", "status", "copy", "publish", "discardDraft", "delete", "layout", "deleteCancelledCompanyData", "dashboardSave", "dashboardRemove"]),
             moduleId: idSchema.optional(),
@@ -265,6 +265,21 @@ export const nocodeToolDefinitions = [
         access: "write",
         destructive: true
     },
+    {
+        name: "nocode_replace_field_with_relation",
+        description: "把无代码模块中的一个顶层普通自定义字段语义化替换为单选数据关联字段。工具会校验模块版本、主字段/明细/关联字段限制、当前账号可见数据、字段删除依赖和目标已发布状态；默认只预览，confirm=true 后保存为草稿并回读验证，不自动发布。",
+        schema: z.object({
+            moduleId: idSchema,
+            baseVersion: z.number().int().nonnegative(),
+            sourceFieldId: idSchema,
+            relationFieldName: z.string().trim().min(1, "关联字段名称不能为空。"),
+            targetModuleId: idSchema,
+            required: z.boolean().optional(),
+            confirm: confirmSchema
+        }),
+        access: "write",
+        destructive: true
+    },
     {
         name: "nocode_write_record",
         description: "新增/修改、删除、转移负责人或设置分组；action=save 的 payload 必须是 ModuleFieldDataSaveBO，包含 moduleId、实际 version、fieldDataList；每个字段值应包含 fieldId、fieldName、name、type、value，修改时再带 dataId；必须 confirm=true，否则只返回预览。",
@@ -542,6 +557,7 @@ export function createNocodeToolHandlers(config = {}, sharedClient) {
             fixedSort: "/moduleField/fixed/setFieldSort",
             fixedStyle: "/moduleField/fixed/setFieldStyle"
         }),
+        nocode_replace_field_with_relation: async (args) => executeRelationFieldReplacement(client, args),
         nocode_write_record: async (args) => executeRecordWrite(client, args, {
             save: "/moduleFieldData/save",
             delete: "/moduleFieldData/delete",
@@ -954,6 +970,9 @@ async function executeApplicationWrite(client, args) {
 }
 async function executeModuleWrite(client, args) {
     const action = String(args.action);
+    if (action === "publish") {
+        return publishModuleDraft(client, args);
+    }
     let targetPath;
     let body;
     let query;
@@ -969,9 +988,6 @@ async function executeModuleWrite(client, args) {
         case "copy":
             targetPath = `/moduleM/copy/${requiredId(args.moduleId, "moduleId")}/${requiredVersion(args.version)}`;
             break;
-        case "publish":
-            targetPath = `/moduleM/active/${requiredId(args.moduleId, "moduleId")}`;
-            break;
         case "discardDraft":
             targetPath = `/moduleM/discardDraft/${requiredId(args.moduleId, "moduleId")}`;
             break;
@@ -999,6 +1015,270 @@ async function executeModuleWrite(client, args) {
     }
     return confirmedPost(client, args, action, targetPath, body, query);
 }
+async function publishModuleDraft(client, args) {
+    const moduleId = requiredId(args.moduleId, "moduleId");
+    const version = requiredExplicitVersion(args.version, "version");
+    const targetPath = `/moduleM/active/${moduleId}`;
+    const latest = requiredObject(await client.post(`/moduleM/queryById/${moduleId}`, undefined, { isLatest: true }), "无法读取待发布模块的最新版本。");
+    const latestVersion = requiredExplicitVersion(latest.version, "latest.version");
+    // 发布接口本身不接收版本号；必须在调用前锁定调用方确认过的草稿版本，避免误发新草稿。
+    if (latestVersion !== version) {
+        throw new Error(`模块版本已变化：请求发布 version=${version}，当前最新 version=${latestVersion}。请重新预览。`);
+    }
+    if (latest.isActive !== false || Number(latest.status) !== 2) {
+        throw new Error(`version=${version} 不是可发布草稿，已拒绝调用无版本参数的发布接口。`);
+    }
+    if (args.confirm !== true) {
+        return {
+            preview: true,
+            message: "发布前预览：已锁定当前最新草稿版本；未传 confirm=true，不会调用发布接口。",
+            action: "publish",
+            targetPath,
+            version,
+            preflight: { latestVersion, status: latest.status, isActive: latest.isActive }
+        };
+    }
+    const published = requiredObject(await client.post(targetPath), "发布接口未返回模块信息，无法确认发布结果。");
+    const publishedVersion = requiredExplicitVersion(published.version, "published.version");
+    const verified = publishedVersion === version && published.isActive === true && Number(published.status) === 1;
+    return {
+        preview: false,
+        action: "publish",
+        targetPath,
+        version,
+        verified,
+        publishReady: verified,
+        message: verified ? "草稿已按确认版本发布，并完成返回值校验。" : "发布接口已调用，但返回值未通过版本/激活状态校验。",
+        data: published
+    };
+}
+async function executeRelationFieldReplacement(client, args) {
+    const moduleId = requiredId(args.moduleId, "moduleId");
+    const sourceFieldId = requiredId(args.sourceFieldId, "sourceFieldId");
+    const targetModuleId = requiredId(args.targetModuleId, "targetModuleId");
+    const baseVersion = requiredExplicitVersion(args.baseVersion, "baseVersion");
+    const relationFieldName = requiredText(args.relationFieldName, "relationFieldName");
+    const moduleDetail = requiredObject(await client.post(`/moduleM/queryById/${moduleId}`, undefined, { isLatest: true }), "无法读取来源模块的最新版本。");
+    const latestVersion = requiredExplicitVersion(moduleDetail.version, "module.version");
+    if (latestVersion !== baseVersion) {
+        throw new Error(`模块版本已变化：baseVersion=${baseVersion}，当前最新 version=${latestVersion}。请重新读取结构后再替换。`);
+    }
+    const moduleStatus = Number(moduleDetail.status);
+    if (![1, 2].includes(moduleStatus)
+        || (moduleStatus === 1 && moduleDetail.isActive !== true)
+        || (moduleStatus === 2 && moduleDetail.isActive === true)) {
+        throw new Error("来源模块不是可编辑的已发布版本或草稿版本，已拒绝字段替换。");
+    }
+    const mainFieldId = requiredId(moduleDetail.mainFieldId, "module.mainFieldId");
+    const fields = requiredObjectArray(await client.post("/moduleField/queryList", { moduleId: numericValue(moduleId), version: baseVersion }), "模块字段列表");
+    const sourceField = fields.find((field) => sameId(field.fieldId, sourceFieldId));
+    if (!sourceField) {
+        throw new Error(`sourceFieldId=${sourceFieldId} 不在模块 ${moduleId} 的 version=${baseVersion} 字段列表中。`);
+    }
+    // 该动作只负责“普通字段 -> 新建单选数据关联”；现有关系改目标会触发旧后端的非版本化关系配置风险。
+    if (sameId(sourceFieldId, mainFieldId)) {
+        throw new Error("主字段不能被语义化替换。请保留主字段并选择其他普通自定义字段。");
+    }
+    if (Number(sourceField.fieldType) !== 1) {
+        throw new Error("仅支持替换 fieldType=1 的自定义字段，系统字段不会被删除。");
+    }
+    if (sourceField.groupId !== undefined && sourceField.groupId !== null) {
+        throw new Error("明细表格内字段不能被此工具替换；仅支持顶层普通字段。");
+    }
+    // 布局、计算、唯一编号、树和关系字段都有额外配置，不能按普通值字段的删除语义处理。
+    if ([45, 49, 50, 51, 53, 56, 60, 63, 67, 68, 76, 81, 82, 83, 84, 100, 110].includes(Number(sourceField.type))) {
+        throw new Error("布局、计算、配置或已有关系字段不能作为替换来源；请选择顶层普通值字段。");
+    }
+    if ([1, 3].includes(Number(sourceField.operating))) {
+        throw new Error("该字段的 operating 配置不允许删除，已拒绝替换。");
+    }
+    if (fields.some((field) => !sameId(field.fieldId, sourceFieldId) && String(field.name ?? "").trim() === relationFieldName)) {
+        throw new Error(`模块中已存在名为“${relationFieldName}”的其他字段。`);
+    }
+    if (fields.some((field) => Number(field.type) === 68)) {
+        throw new Error("模块包含树字段；旧后端查询结果缺少聚合保存所需的临时展示字段 ID，已保守阻断替换。");
+    }
+    const defaultValueConfigs = requiredObjectArray(await client.post(`/moduleFieldDefault/list/${moduleId}/${baseVersion}`), "字段默认值配置");
+    const fieldStatisticConfigs = requiredObjectArray(await client.post(`/moduleFieldStatistic/query/${moduleId}/${baseVersion}`), "字段统计配置");
+    // /moduleField/save 会先清空再重建这两类配置；语义工具没有完整编辑上下文时宁可拒绝，也不能静默擦除。
+    if (defaultValueConfigs.length > 0 || fieldStatisticConfigs.length > 0) {
+        throw new Error(`模块包含 ${defaultValueConfigs.length} 条字段默认值配置和 ${fieldStatisticConfigs.length} 条字段统计配置，已保守阻断替换。`);
+    }
+    const sourceFieldName = requiredText(sourceField.fieldName, "sourceField.fieldName");
+    const sourceFormType = requiredText(sourceField.formType, "sourceField.formType");
+    const sourceDataQuery = {
+        page: 1,
+        limit: 1,
+        searchList: [{
+                fieldId: numericValue(sourceFieldId),
+                fieldName: sourceFieldName,
+                formType: sourceFormType,
+                type: 6,
+                values: [],
+                groupId: 0
+            }]
+    };
+    const sourceDataPage = await client.post(`/moduleData/queryPageList/${moduleId}`, sourceDataQuery);
+    if (pageHasRows(sourceDataPage)) {
+        throw new Error(`字段“${String(sourceField.name ?? sourceFieldName)}”存在非空数据，替换会在发布时丢失原值，已阻断。`);
+    }
+    const deleteImpact = requiredObject(await client.post("/moduleField/checkFieldDelete", {
+        moduleId: numericValue(moduleId),
+        fieldId: numericValue(sourceFieldId),
+        fieldName: sourceFieldName,
+        version: baseVersion
+    }), "字段删除依赖检查未返回有效结果。");
+    const dependentFields = requiredArray(deleteImpact.moduleFields, "deleteImpact.moduleFields");
+    const dependentFlows = requiredArray(deleteImpact.moduleFlows, "deleteImpact.moduleFlows");
+    if (dependentFields.length > 0 || dependentFlows.length > 0) {
+        throw new Error(`字段仍被 ${dependentFields.length} 个字段配置和 ${dependentFlows.length} 个流程配置引用，已阻断替换。`);
+    }
+    const targetModule = requiredObject(await client.post(`/moduleM/queryById/${targetModuleId}`, undefined, { isLatest: false }), "无法读取关联目标模块的已发布版本。");
+    if (targetModule.isActive !== true || Number(targetModule.status) !== 1) {
+        throw new Error("关联目标模块必须存在已发布激活版本。");
+    }
+    const requiredRelation = args.required === undefined ? Number(sourceField.isNull) === 1 : args.required === true;
+    const retainedFields = fields
+        .filter((field) => !sameId(field.fieldId, sourceFieldId))
+        .map((field) => ({
+        ...field,
+        tempFieldId: `existing-${requiredId(field.fieldId, "field.fieldId")}`
+    }));
+    const mainTempFieldId = `existing-${mainFieldId}`;
+    if (!retainedFields.some((field) => field.tempFieldId === mainTempFieldId)) {
+        throw new Error("字段聚合中未找到主字段，拒绝提交可能破坏主字段的保存请求。");
+    }
+    const replacementField = cleanObject({
+        tempFieldId: `relation-${sourceFieldId}-${targetModuleId}`,
+        name: relationFieldName,
+        type: 100,
+        fieldType: 1,
+        isNull: requiredRelation ? 1 : 0,
+        isHidden: 0,
+        formPosition: sourceField.formPosition,
+        stylePercent: sourceField.stylePercent,
+        optionsData: {
+            type: 1,
+            targetName: "module",
+            targetId: numericValue(targetModuleId)
+        }
+    });
+    const sourceIndex = fields.findIndex((field) => sameId(field.fieldId, sourceFieldId));
+    const moduleFieldList = [...retainedFields];
+    // 旧后端以数组下标重写 sorting；插回来源位置才能保持其他字段与表单的既有顺序。
+    moduleFieldList.splice(sourceIndex, 0, replacementField);
+    const saveBody = {
+        moduleId: numericValue(moduleId),
+        version: baseVersion,
+        mainFieldId: numericValue(mainFieldId),
+        tempMainFieldId: mainTempFieldId,
+        moduleFieldList
+    };
+    const preflight = {
+        latestVersion,
+        sourceDataEmpty: true,
+        dataQueryScope: "当前 MCP 账号可见数据（旧后端强制数据权限过滤）",
+        defaultValueConfigCount: 0,
+        fieldStatisticConfigCount: 0,
+        dependentFieldCount: 0,
+        dependentFlowCount: 0,
+        targetModule: {
+            moduleId: targetModuleId,
+            version: targetModule.version,
+            name: targetModule.name,
+            isActive: targetModule.isActive
+        }
+    };
+    if (args.confirm !== true) {
+        return {
+            preview: true,
+            message: "字段替换前预览：安全校验已通过；未传 confirm=true，不会保存字段草稿。",
+            action: "replaceFieldWithRelation",
+            targetPath: "/moduleField/save",
+            moduleId,
+            baseVersion,
+            sourceField: fieldSummary(sourceField),
+            replacementField,
+            preflight,
+            body: saveBody
+        };
+    }
+    const savedModule = requiredObject(await client.post("/moduleField/save", saveBody), "字段保存接口未返回模块信息，无法回读验证。");
+    const savedVersion = requiredExplicitVersion(savedModule.version, "savedModule.version");
+    const expectedSavedVersion = moduleDetail.isActive === true ? baseVersion + 1 : baseVersion;
+    const readbackFields = requiredObjectArray(await client.post("/moduleField/queryList", { moduleId: numericValue(moduleId), version: savedVersion }), "保存后字段列表");
+    const retainedFieldIds = retainedFields.map((field) => requiredId(field.fieldId, "retainedField.fieldId"));
+    const replacementMatches = readbackFields.filter((field) => {
+        const optionsData = isObject(field.optionsData) ? field.optionsData : {};
+        return String(field.name ?? "").trim() === relationFieldName
+            && Number(field.type) === 100
+            && Number(field.fieldType) === 1
+            && Number(optionsData.type) === 1
+            && optionsData.targetName === "module"
+            && sameId(optionsData.targetId, targetModuleId);
+    });
+    const verificationErrors = [];
+    if (savedVersion !== expectedSavedVersion) {
+        verificationErrors.push(`保存版本应为 ${expectedSavedVersion}，实际为 ${savedVersion}`);
+    }
+    if (Number(savedModule.status) !== 2 || savedModule.isActive !== false) {
+        verificationErrors.push("保存结果不是未激活草稿");
+    }
+    if (readbackFields.some((field) => sameId(field.fieldId, sourceFieldId))) {
+        verificationErrors.push("来源字段仍存在");
+    }
+    if (replacementMatches.length !== 1) {
+        verificationErrors.push(`匹配的新关联字段数量为 ${replacementMatches.length}`);
+    }
+    else {
+        if (Number(replacementMatches[0].isNull) !== (requiredRelation ? 1 : 0)) {
+            verificationErrors.push("新关联字段必填属性不一致");
+        }
+        if (readbackFields.indexOf(replacementMatches[0]) !== sourceIndex) {
+            verificationErrors.push("新关联字段未保留来源字段位置");
+        }
+        if (sourceField.formPosition !== undefined
+            && sourceField.formPosition !== null
+            && replacementMatches[0].formPosition !== sourceField.formPosition) {
+            verificationErrors.push("新关联字段表单位置不一致");
+        }
+    }
+    const missingRetainedIds = retainedFieldIds.filter((fieldId) => !readbackFields.some((field) => sameId(field.fieldId, fieldId)));
+    if (missingRetainedIds.length > 0) {
+        verificationErrors.push(`缺少 ${missingRetainedIds.length} 个应保留字段`);
+    }
+    if (!sameId(savedModule.mainFieldId, mainFieldId)) {
+        verificationErrors.push("主字段 ID 发生变化");
+    }
+    if (readbackFields.length !== fields.length) {
+        verificationErrors.push(`字段总数应为 ${fields.length}，实际为 ${readbackFields.length}`);
+    }
+    const verified = verificationErrors.length === 0;
+    const replacement = replacementMatches[0];
+    return {
+        preview: false,
+        action: "replaceFieldWithRelation",
+        targetPath: "/moduleField/save",
+        moduleId,
+        baseVersion,
+        savedVersion,
+        saved: true,
+        verified,
+        publishReady: verified,
+        message: verified
+            ? "字段已替换为单选数据关联并保存为草稿，回读验证通过；仍需显式发布该 savedVersion。"
+            : "字段草稿已保存，但回读验证未通过；请检查草稿，不要发布。",
+        preflight,
+        verification: {
+            errors: verificationErrors,
+            sourceRemoved: !readbackFields.some((field) => sameId(field.fieldId, sourceFieldId)),
+            retainedFieldsPresent: missingRetainedIds.length === 0,
+            replacementFieldId: replacement?.fieldId,
+            replacementTargetModuleId: targetModuleId
+        },
+        data: savedModule
+    };
+}
 async function executePayloadWrite(client, args, paths) {
     const action = String(args.action);
     const targetPath = paths[action];
@@ -1116,6 +1396,16 @@ function requiredVersion(value) {
     }
     return normalized;
 }
+function requiredExplicitVersion(value, field) {
+    if (value === undefined || value === null || value === "") {
+        throw new Error(`${field} 必须显式传入非负整数。`);
+    }
+    const normalized = Number(value);
+    if (!Number.isInteger(normalized) || normalized < 0) {
+        throw new Error(`${field} 必须是非负整数。`);
+    }
+    return normalized;
+}
 function requiredInteger(value, field) {
     const normalized = Number(value);
     if (!Number.isInteger(normalized)) {
@@ -1148,6 +1438,64 @@ function safePayload(value) {
     }
     return value;
 }
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requiredObject(value, message) {
+    if (!isObject(value)) {
+        throw new Error(message);
+    }
+    return value;
+}
+function requiredArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${field} 必须是数组；无法完成安全校验。`);
+    }
+    return value;
+}
+function requiredObjectArray(value, field) {
+    return requiredArray(value, field).map((item, index) => requiredObject(item, `${field}[${index}] 不是有效对象。`));
+}
+function requiredText(value, field) {
+    const normalized = typeof value === "string" ? value.trim() : "";
+    if (!normalized) {
+        throw new Error(`${field} 不能为空。`);
+    }
+    return normalized;
+}
+function sameId(value, expected) {
+    return value !== undefined && value !== null && String(value).trim() === expected;
+}
+function pageHasRows(value) {
+    const page = requiredObject(value, "字段存量数据检查未返回有效分页结果，已保守阻断。");
+    const rows = Array.isArray(page.list) ? page.list : undefined;
+    if (rows && rows.length > 0) {
+        return true;
+    }
+    if (page.totalRow !== undefined && page.totalRow !== null) {
+        const totalRow = Number(page.totalRow);
+        if (!Number.isInteger(totalRow) || totalRow < 0) {
+            throw new Error("字段存量数据检查返回了无效 totalRow，已保守阻断。");
+        }
+        return totalRow > 0;
+    }
+    if (rows) {
+        return false;
+    }
+    throw new Error("字段存量数据检查既没有 list 也没有 totalRow，已保守阻断。");
+}
+function fieldSummary(field) {
+    return cleanObject({
+        fieldId: field.fieldId,
+        fieldName: field.fieldName,
+        name: field.name,
+        type: field.type,
+        formType: field.formType,
+        isNull: field.isNull,
+        formPosition: field.formPosition,
+        stylePercent: field.stylePercent
+    });
+}
 function applicationPayload(value, action) {
     const payload = safePayload(value);
     const name = typeof payload.name === "string" ? payload.name.trim() : "";

package/dist/server.js

@@ -13,13 +13,16 @@ const idSchema = z.union([z.string(), z.number()]);
 const passthroughSchema = z.object({}).passthrough();
 const toolOutputSchema = z.object({ result: z.unknown() });
 const searchFilterSchema = z.object({
-    fieldName: z.string().optional(),
-    name: z.string().optional(),
-    formType: z.string().optional(),
-    type: z.number().optional(),
-    searchEnum: z.union([z.string(), z.number()]).optional(),
-    values: z.array(z.unknown()).optional(),
-    groupId: z.number().optional()
+    fieldName: z.string().optional().describe("后端字段名；与兼容字段 name 至少提供一个。"),
+    name: z.string().optional().describe("fieldName 的兼容别名。"),
+    formType: z.string().optional().describe("字段类型。人员用 user/single_user；日期用 date，日期时间用 datetime。"),
+    type: z.number().int().min(1).max(14).optional().describe("高级筛选操作码；与 searchEnum 同义，同时提供时必须一致。人员 ID 匹配用 3，日期范围用 14。"),
+    searchEnum: z.union([
+        z.number().int().min(1).max(14),
+        z.enum(["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14"])
+    ]).optional().describe("高级筛选操作码；与 type 同义，同时提供时必须一致。"),
+    values: z.array(z.unknown()).optional().describe("筛选值数组。除为空/不为空操作 5/6 外必须提供；datetime 范围 14 使用 [YYYY-MM-DD HH:mm:ss, YYYY-MM-DD HH:mm:ss]。"),
+    groupId: z.number().int().optional().describe("同组条件为 AND，不同组为 OR。")
 }).passthrough();
 const crmCreateRecordSchema = z.object({
     module: moduleSchema,
@@ -32,16 +35,16 @@ const crmCreateRecordSchema = z.object({
     confirm: z.boolean().optional()
 }).strict();
 const crmUserSearchShape = {
-    ownerUserId: idSchema.optional(),
-    ownerUserIds: z.array(idSchema).optional(),
-    ownerUserName: z.string().optional(),
-    ownerUserNames: z.array(z.string()).optional(),
-    createUserId: idSchema.optional(),
-    createUserIds: z.array(idSchema).optional(),
-    createUserName: z.string().optional(),
-    createUserNames: z.array(z.string()).optional(),
-    filters: z.array(searchFilterSchema).optional(),
-    searchList: z.array(searchFilterSchema).optional()
+    ownerUserId: idSchema.optional().describe("负责人用户 ID；MCP 转为后端支持的人员包含操作 3。"),
+    ownerUserIds: z.array(idSchema).optional().describe("多个负责人用户 ID。"),
+    ownerUserName: z.string().optional().describe("负责人唯一昵称；MCP 先解析为用户 ID，重名时报错。"),
+    ownerUserNames: z.array(z.string()).optional().describe("多个负责人唯一昵称。"),
+    createUserId: idSchema.optional().describe("创建人用户 ID；查询跟进记录时表示跟进人员。"),
+    createUserIds: z.array(idSchema).optional().describe("多个创建人用户 ID。"),
+    createUserName: z.string().optional().describe("创建人唯一昵称；查询跟进记录时表示跟进人员。"),
+    createUserNames: z.array(z.string()).optional().describe("多个创建人唯一昵称。"),
+    filters: z.array(searchFilterSchema).optional().describe("高级筛选列表；与 searchList 二选一。"),
+    searchList: z.array(searchFilterSchema).optional().describe("filters 的兼容别名；不能与 filters 同时提供。")
 };
 const toolDefinitions = [
     ["crm_auth_status", "使用 CRM_API_KEY 自动换取 Admin-Token 后检查当前登录态，异常时提示检查 API Key。", z.object({}).optional()],
@@ -49,7 +52,7 @@ const toolDefinitions = [
     ["crm_list_customer_pools", "查询当前账号有权限访问的客户公海，并统计每个公海下面有多少客户；只读，不领取、不分配、不流转。", z.object({ includeSamples: z.boolean().optional(), sampleLimit: z.number().optional() }).passthrough()],
     ["crm_get_module_schema", "获取模块字段结构和列表头，供本地 AI 判断字段怎么填。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]).optional() }).passthrough()],
     ["crm_validate_field", "调用固定字段校验接口，校验字段值或联系人查重。", passthroughSchema],
-    ["crm_search_records", "查询模块分页列表；支持 ownerUserId(s)/createUserId(s) 按用户 ID 筛选，也支持 ownerUserName(s)/createUserName(s) 将唯一昵称解析为用户 ID；用户类型 filters 的昵称值同样会先解析为 ID。", z.object({ module: moduleSchema, page: z.number().optional(), limit: z.number().optional(), ...crmUserSearchShape }).passthrough()],
+    ["crm_search_records", "查询模块分页列表。人员便捷参数和 user 筛选会解析为用户 ID，并使用后端支持的操作 3；日期/日期时间范围筛选必须使用操作 14。查询某人员某天的跟进记录时，module=activity，人员使用 createUserId(s)/createUserName(s)，createTime 使用 formType=datetime 和当天 00:00:00 至 23:59:59 的范围。", z.object({ module: moduleSchema, page: z.number().optional(), limit: z.number().optional(), ...crmUserSearchShape }).passthrough()],
     ["crm_get_record", "按模块和 ID 查询单条 CRM 记录详情。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
     ["crm_get_record_information", "查询详情页字段展示数据，包含字段中文名和值。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
     ["crm_get_related_records", "查询固定白名单内的关联数据，例如商机产品、联系人商机、合同回款计划、产品上架列表。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]).optional(), relation: z.string() }).passthrough()],
@@ -192,7 +195,7 @@ export function createWukongMcpServer(config = {}) {
     const { oauth, ...crmConfig } = config;
     const server = new McpServer({
         name: "wukong-mcp",
-        version: "0.2.3"
+        version: "0.2.5"
     }, {
         instructions: "先使用只读工具确认模块、记录和字段，再执行写入。所有写入必须显式传 confirm=true；不要尝试任意 URL 请求。"
     });

package/dist/tools.js

@@ -1746,6 +1746,10 @@ function extractSavedWorkorderId(data, prepared) {
     return data?.workorderId ?? prepared.body.entity?.workorderId;
 }
 const FIELD_SEARCH_CONTAINS = 3;
+const FIELD_SEARCH_NOT_CONTAINS = 4;
+const FIELD_SEARCH_IS_NULL = 5;
+const FIELD_SEARCH_IS_NOT_NULL = 6;
+const FIELD_SEARCH_RANGE = 14;
 const QUICK_SEARCH_FIELDS = {
     leads: [
         { fieldName: "leadsName", formType: "text" },
@@ -1822,6 +1826,42 @@ const NAME_FIELD_BY_MODULE = {
 };
 const USER_FILTER_FORM_TYPES = new Set(["user", "single_user"]);
 const USER_FILTER_FIELD_NAMES = new Set(["ownerUserId", "createUserId"]);
+const DATE_FILTER_FORM_TYPES = new Set(["date", "datetime"]);
+const NUMBER_RANGE_FORM_TYPES = new Set(["number", "floatnumber", "percent", "field_attention"]);
+const USER_FILTER_OPERATIONS = new Set([
+    FIELD_SEARCH_CONTAINS,
+    FIELD_SEARCH_NOT_CONTAINS,
+    FIELD_SEARCH_IS_NULL,
+    FIELD_SEARCH_IS_NOT_NULL
+]);
+const DATE_FILTER_OPERATIONS = new Set([1, 2, 5, 6, 7, 8, 9, 10, FIELD_SEARCH_RANGE]);
+const PRESET_DATE_RANGES = new Set([
+    "year",
+    "lastYear",
+    "quarter",
+    "lastQuarter",
+    "month",
+    "lastMonth",
+    "week",
+    "lastWeek",
+    "today",
+    "yesterday",
+    "nextYear",
+    "firstHalfYear",
+    "nextHalfYear",
+    "nextQuarter",
+    "nextMonth",
+    "nextWeek",
+    "tomorrow",
+    "previous7day",
+    "previous30day",
+    "future7day",
+    "future30day",
+    "recently7day",
+    "recently30day",
+    "recently60day",
+    "recentlyHalfYear"
+]);
 const USER_FILTER_ARGUMENTS = [
     {
         fieldName: "ownerUserId",
@@ -1837,9 +1877,13 @@ const USER_FILTER_ARGUMENTS = [
 async function buildResolvedSearchList(client, args, moduleDefinition) {
     const searchList = buildSearchList(args, moduleDefinition);
     const userSearchList = buildConvenienceUserSearchList(args);
-    return resolveUserSearchFilters(client, combineSearchLists(searchList, userSearchList), args.companyId);
+    const validatedSearchList = validateSearchFilters(combineSearchLists(searchList, userSearchList));
+    return resolveUserSearchFilters(client, validatedSearchList, args.companyId);
 }
 function buildSearchList(args, moduleDefinition) {
+    if (args.filters !== undefined && args.searchList !== undefined) {
+        throw new Error("filters 和 searchList 不能同时提供，请只使用其中一个高级筛选参数。");
+    }
     const explicitSearchList = toArray(args.filters ?? args.searchList);
     const semanticSearchList = buildSemanticSearchList(args, moduleDefinition);
     return combineSearchLists(explicitSearchList, semanticSearchList);
@@ -1853,12 +1897,126 @@ function buildConvenienceUserSearchList(args) {
         return [{
                 fieldName,
                 formType: "user",
-                type: 1,
-                searchEnum: 1,
+                // 旧 CRM 的 EsUtil.userSearch 只有 CONTAINS(3) 才会生成用户 ID terms 查询。
+                type: FIELD_SEARCH_CONTAINS,
+                searchEnum: FIELD_SEARCH_CONTAINS,
                 values
             }];
     });
 }
+function validateSearchFilters(filters) {
+    return filters.map((filter, index) => {
+        if (!isPlainObject(filter)) {
+            throw new Error(`高级筛选第 ${index + 1} 项必须是对象。`);
+        }
+        const fieldName = firstTextValue(filter.fieldName, filter.name);
+        if (!fieldName) {
+            throw new Error(`高级筛选第 ${index + 1} 项请提供 fieldName（或兼容字段 name）。`);
+        }
+        const typeOperation = parseSearchOperation(filter.type, "type", fieldName);
+        const enumOperation = parseSearchOperation(filter.searchEnum, "searchEnum", fieldName);
+        if (typeOperation !== undefined && enumOperation !== undefined && typeOperation !== enumOperation) {
+            throw new Error(`筛选“${fieldName}”的 type=${typeOperation} 与 searchEnum=${enumOperation} 冲突，请保持一致或只提供一个。`);
+        }
+        const operation = enumOperation ?? typeOperation;
+        if (operation === undefined) {
+            throw new Error(`筛选“${fieldName}”请提供 type 或 searchEnum。`);
+        }
+        if (filter.values !== undefined && !Array.isArray(filter.values)) {
+            throw new Error(`筛选“${fieldName}”的 values 必须是数组。`);
+        }
+        const values = valueArray(filter.values);
+        const isNullOperation = operation === FIELD_SEARCH_IS_NULL || operation === FIELD_SEARCH_IS_NOT_NULL;
+        if (!isNullOperation && values.length === 0) {
+            throw new Error(`筛选“${fieldName}”使用操作 ${operation} 时请提供 values。`);
+        }
+        const formType = String(filter.formType ?? "").trim().toLowerCase();
+        const userFilter = USER_FILTER_FORM_TYPES.has(formType) || USER_FILTER_FIELD_NAMES.has(fieldName);
+        if (userFilter && !USER_FILTER_OPERATIONS.has(operation)) {
+            throw new Error(`人员筛选“${fieldName}”使用了后端未实现的操作 ${operation}；仅支持 3、4、5、6。按人员 ID 匹配请使用操作 3。`);
+        }
+        if (DATE_FILTER_FORM_TYPES.has(formType)) {
+            validateDateFilter(fieldName, formType, operation, values);
+        }
+        else if (operation === FIELD_SEARCH_RANGE) {
+            if (!NUMBER_RANGE_FORM_TYPES.has(formType)) {
+                throw new Error(`筛选“${fieldName}”的范围操作 14 仅支持 date、datetime 或数字类型 formType。`);
+            }
+            if (values.length !== 2 || values.some((value) => !isFiniteNumberValue(value))) {
+                throw new Error(`数字筛选“${fieldName}”的范围操作 14 必须提供两个有效数字边界值。`);
+            }
+        }
+        // formType 大小写错误会让后端退回文本搜索；这里统一为契约中的小写值。
+        const normalizedFilter = formType ? { ...filter, formType } : filter;
+        return DATE_FILTER_FORM_TYPES.has(formType) && values.length > 0
+            ? { ...normalizedFilter, values: values.map((value) => String(value).trim()) }
+            : normalizedFilter;
+    });
+}
+function parseSearchOperation(value, key, fieldName) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new Error(`筛选“${fieldName}”的 ${key} 必须是 1 到 14 的整数操作码。`);
+    }
+    const operation = Number(text);
+    if (!Number.isInteger(operation) || operation < 1 || operation > 14) {
+        throw new Error(`筛选“${fieldName}”的 ${key}=${text} 不受支持；操作码范围为 1 到 14。`);
+    }
+    return operation;
+}
+function validateDateFilter(fieldName, formType, operation, values) {
+    if (!DATE_FILTER_OPERATIONS.has(operation)) {
+        throw new Error(`日期筛选“${fieldName}”的操作 ${operation} 不受后端支持；范围筛选请使用操作 14。`);
+    }
+    if (operation === FIELD_SEARCH_IS_NULL || operation === FIELD_SEARCH_IS_NOT_NULL) {
+        return;
+    }
+    if (operation === FIELD_SEARCH_RANGE && values.length === 1) {
+        const preset = typeof values[0] === "string" ? values[0].trim() : "";
+        if (PRESET_DATE_RANGES.has(preset)) {
+            return;
+        }
+        throw new Error(`日期筛选“${fieldName}”的范围操作 14 请提供两个边界值，或单个受支持的预设时间值。`);
+    }
+    const expectedValueCount = operation === FIELD_SEARCH_RANGE ? 2 : 1;
+    if (values.length !== expectedValueCount) {
+        throw new Error(`日期筛选“${fieldName}”的操作 ${operation} 必须提供 ${expectedValueCount} 个时间值。`);
+    }
+    const normalizedValues = values.map((value) => typeof value === "string" ? value.trim() : "");
+    if (normalizedValues.some((value) => !isValidDateValue(value, formType))) {
+        const format = formType === "datetime" ? "YYYY-MM-DD HH:mm:ss" : "YYYY-MM-DD";
+        throw new Error(`日期筛选“${fieldName}”的 values 必须使用 ${format} 格式，并且是有效日期。`);
+    }
+    if (operation === FIELD_SEARCH_RANGE && normalizedValues[0] > normalizedValues[1]) {
+        throw new Error(`日期筛选“${fieldName}”的开始值不能晚于结束值。`);
+    }
+}
+function isValidDateValue(value, formType) {
+    const match = formType === "datetime"
+        ? /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/.exec(value)
+        : /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const [, yearText, monthText, dayText, hourText = "0", minuteText = "0", secondText = "0"] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const maxDay = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    return day >= 1 && day <= maxDay && hour <= 23 && minute <= 59 && second <= 59;
+}
+function isFiniteNumberValue(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value));
+}
 function argumentValues(args, keys) {
     return keys.flatMap((key) => valueArray(args[key]));
 }
@@ -1922,7 +2080,9 @@ async function resolveUserSearchFilters(client, searchList, companyId) {
         }
         resolvedFilters.push({
             ...filter,
-            formType: filter.formType ?? "user",
+            formType: USER_FILTER_FORM_TYPES.has(String(filter.formType ?? "").trim().toLowerCase())
+                ? String(filter.formType).trim().toLowerCase()
+                : "user",
             values: [...new Set(values)]
         });
     }
@@ -2051,7 +2211,7 @@ function toArray(value) {
     return [];
 }
 async function resolveUniqueRecord(client, moduleDefinition, args) {
-    const searchList = await resolveUserSearchFilters(client, buildSearchList(args, moduleDefinition), args.companyId);
+    const searchList = await resolveUserSearchFilters(client, validateSearchFilters(buildSearchList(args, moduleDefinition)), args.companyId);
     if (searchList.length === 0) {
         throw new Error(`请提供可定位${moduleDefinition.name}的 customerId/id、phone/mobile、name/customerName 或 keyword。`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wukongcrm/mcp-server",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Local and remote MCP server for fixed 72CRM API access.",
   "type": "module",
   "main": "./dist/index.js",