mcp-xdx-schema-ctx 1.1.9

package/dist/tools/table-tools.js

@@ -0,0 +1,1322 @@
+import { z } from "zod";
+import { envDb } from "../db.js";
+import { T, userName, WARNING, escapeSql, escapeLike, paginate, envelope, ok, sqlPagination, } from "../shared.js";
+import { getTableColumns, getTableInfo, tableExists, pickCols, hasCol, resolveSelect, tryQuery, } from "../schema-compat.js";
+import { buildWhere, buildOrderBy, buildPagedQuery, } from "../sql-build.js";
+export function registerTableTools(server) {
+    // ============================================================
+    // list_tables
+    // ============================================================
+    server.registerTool("list_tables", {
+        description: WARNING +
+            "\n\n列出环境库中所有已定义的表。可选按模块或关键词过滤。数据来源: XDWmsCommon.dbo.TableSetTB",
+        inputSchema: {
+            modular: z.string().max(50).optional().describe("模块: SC/CK/CW"),
+            keyword: z.string().max(200).optional().describe("表名/描述关键词"),
+            scope: z
+                .enum(["registered", "system", "all"])
+                .optional()
+                .default("registered")
+                .describe("registered=TableSetTB 登记表（默认）；system=环境库自身物理表；all=两者合并"),
+            limit: z
+                .number()
+                .optional()
+                .default(50)
+                .describe("已废弃：本工具已改为 SQL 端分页，请用 page/pageSize"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ modular, keyword, scope, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        // ---- scope=system / all：环境库自身物理表（INFORMATION_SCHEMA） ----
+        if (scope === "system" || scope === "all") {
+            const sysTable = `[${envDb()}].INFORMATION_SCHEMA.TABLES`;
+            const sysWhere = " WHERE TABLE_SCHEMA='dbo' AND TABLE_TYPE='BASE TABLE'" +
+                (keyword
+                    ? ` AND TABLE_NAME LIKE N'%${escapeLike(keyword)}%' ESCAPE '\\'`
+                    : "");
+            const sysRows = await tryQuery("list_tables.system", `SELECT TOP 2000 [TABLE_NAME] FROM ${sysTable}${sysWhere} ORDER BY [TABLE_NAME]`, warnings);
+            // 登记表名集合（用于标记 registered）
+            let registeredSet = new Set();
+            let regRows = [];
+            if (await tableExists(T("tableDef"))) {
+                const tCols = await getTableColumns(T("tableDef"));
+                const selCols = pickCols(tCols, [
+                    "TableName",
+                    "TableDesc",
+                    "TableType",
+                    "Modular1",
+                ]);
+                if (selCols.length > 0 && hasCol(tCols, "TableName")) {
+                    const groups = [];
+                    if (keyword) {
+                        const filters = ["TableName", "TableDesc"]
+                            .filter((c) => hasCol(tCols, c))
+                            .map((c) => ({ col: c, op: "like", value: keyword }));
+                        if (filters.length > 0)
+                            groups.push({ logic: "or", filters });
+                    }
+                    if (modular)
+                        groups.push({
+                            filters: [{ col: "Modular1", op: "eq", value: modular }],
+                        });
+                    const { where } = buildWhere(tCols, groups);
+                    const order = buildOrderBy(tCols, ["TableName"]);
+                    regRows = (await tryQuery("list_tables.registered", `SELECT TOP 2000 ${selCols
+                        .map((c) => `[${c}]`)
+                        .join(", ")} FROM ${T("tableDef")}${where}${order.orderBy}`, warnings));
+                    registeredSet = new Set(regRows.map((r) => String(r.TableName)));
+                }
+            }
+            const merged = [
+                ...regRows.map((r) => ({
+                    ...r,
+                    registered: true,
+                    source: "TableSetTB",
+                })),
+                ...sysRows
+                    .filter((r) => !registeredSet.has(String(r.TABLE_NAME)))
+                    .map((r) => ({
+                    TableName: r.TABLE_NAME,
+                    TableType: "BASE TABLE",
+                    registered: false,
+                    source: "INFORMATION_SCHEMA",
+                })),
+            ].sort((a, b) => String(a.TableName ?? "").localeCompare(String(b.TableName ?? "")));
+            const { page: paged, pagination } = paginate(merged, page, pageSize);
+            return ok(envelope({
+                items: paged,
+                pagination,
+                warnings,
+                scope,
+            }));
+        }
+        const tableDefCols = await getTableColumns(T("tableDef"));
+        const cols = pickCols(tableDefCols, [
+            "TableName",
+            "TableDesc",
+            "TableType",
+            "Modular1",
+            "Modular2",
+            "Code",
+            "EnglishDesc",
+        ]);
+        if (cols.length === 0) {
+            return ok(envelope({
+                items: [],
+                pagination: sqlPagination(page, pageSize, 0),
+                warnings: [
+                    { module: "list_tables", message: "环境库 TableSetTB 无可用字段" },
+                ],
+            }));
+        }
+        const groups = [];
+        if (keyword) {
+            const filters = ["TableName", "TableDesc", "EnglishDesc"]
+                .filter((c) => hasCol(tableDefCols, c))
+                .map((c) => ({ col: c, op: "like", value: keyword }));
+            if (filters.length > 0)
+                groups.push({ logic: "or", filters });
+        }
+        if (modular)
+            groups.push({
+                filters: [{ col: "Modular1", op: "eq", value: modular }],
+            });
+        const { where, skipped } = buildWhere(tableDefCols, groups);
+        const order = buildOrderBy(tableDefCols, ["TableName"]);
+        if (skipped.length > 0) {
+            warnings.push({
+                module: "list_tables",
+                message: `以下列在本环境库不存在，条件已跳过: ${skipped.join(", ")}`,
+                hint: "可用 describe_table 查看环境库实际字段",
+            });
+        }
+        if (order.skipped.length > 0) {
+            warnings.push({
+                module: "list_tables",
+                message: `排序列不存在，已忽略: ${order.skipped.join(", ")}`,
+            });
+        }
+        const table = T("tableDef");
+        const { countSql, sql } = buildPagedQuery({
+            table,
+            cols,
+            where,
+            orderBy: order.orderBy,
+            page,
+            pageSize,
+        });
+        const countRows = await tryQuery("list_tables.count", countSql, warnings);
+        const total = Number(countRows[0]?.Total ?? 0);
+        const items = total > 0 ? await tryQuery("list_tables", sql, warnings) : [];
+        return ok(envelope({
+            items,
+            pagination: sqlPagination(page, pageSize, total),
+            warnings,
+            totalItems: total,
+        }));
+    });
+    // ============================================================
+    // describe_table
+    // ============================================================
+    server.registerTool("describe_table", {
+        description: WARNING +
+            "\n\n获取指定表的完整字段定义。数据来源: XDWmsCommon.dbo.TableSetTB + TableFieldSetTB",
+        inputSchema: {
+            tableName: z.string().max(128).describe("表名，如 SaleOrderHedTB"),
+            fieldKeyword: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("按字段名/字段描述模糊过滤（大表时用于避免输出被截断）"),
+            columns: z
+                .string()
+                .max(500)
+                .optional()
+                .describe("按需返回的字段名，逗号分隔（如 FieldName,FieldType,FieldDesc）"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ tableName, fieldKeyword, columns, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        const safeName = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        const wantedCols = columns
+            ? columns
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => /^[A-Za-z0-9_]+$/.test(s))
+            : [];
+        // ---- 1) 登记表（TableSetTB） ----
+        const tableDefCols = await getTableColumns(T("tableDef"));
+        const tCols = pickCols(tableDefCols, [
+            "TableName",
+            "TableDesc",
+            "TableType",
+            "ParentTable",
+            "Modular1",
+            "Modular2",
+            "Code",
+            "EnglishDesc",
+            "OtherDesc",
+            "Remark",
+        ]);
+        let table = null;
+        if (tCols.length > 0 && hasCol(tableDefCols, "TableName")) {
+            const rows = await tryQuery("describe_table.table", `SELECT ${tCols
+                .map((c) => `[${c}]`)
+                .join(", ")} FROM ${T("tableDef")} WHERE [TableName]='${escapeSql(safeName)}'`, warnings);
+            table = rows[0] ?? null;
+        }
+        if (table) {
+            const fieldDefCols = await getTableColumns(T("fieldDef"));
+            const defaultWanted = [
+                "iLineNo",
+                "FieldName",
+                "FieldDesc",
+                "FieldType",
+                "iPrecision",
+                "iScale",
+                "DefaultValue",
+                "bAllowNull",
+                "bVirtual",
+                "bSearchField",
+                "bUnique",
+                "cLinkTable",
+                "cLinkField",
+                "cDstField",
+                "EnglishDesc",
+                "OtherDesc",
+                "Remark",
+            ];
+            const wanted = wantedCols.length > 0
+                ? wantedCols.filter((c) => hasCol(fieldDefCols, c))
+                : defaultWanted;
+            if (wantedCols.length > 0 && wanted.length === 0) {
+                warnings.push({
+                    module: "describe_table",
+                    message: `指定的 columns 在本环境库均不存在: ${wantedCols.join(", ")}`,
+                });
+            }
+            const rs = await resolveSelect(T("fieldDef"), wanted.length > 0 ? wanted : ["FieldName", "FieldDesc", "FieldType"]);
+            if (rs.missing.length > 0) {
+                warnings.push({
+                    module: "describe_table",
+                    message: `以下列在本环境库不存在，已置空: ${rs.missing.join(", ")}`,
+                });
+            }
+            const groups = [
+                { filters: [{ col: "TableName", op: "eq", value: safeName }] },
+            ];
+            if (fieldKeyword) {
+                const filters = ["FieldName", "FieldDesc"]
+                    .filter((c) => hasCol(fieldDefCols, c))
+                    .map((c) => ({ col: c, op: "like", value: fieldKeyword }));
+                if (filters.length > 0)
+                    groups.push({ logic: "or", filters });
+            }
+            const { where, skipped } = buildWhere(fieldDefCols, groups);
+            if (skipped.length > 0) {
+                warnings.push({
+                    module: "describe_table",
+                    message: `以下列在本环境库不存在，条件已跳过: ${skipped.join(", ")}`,
+                });
+            }
+            const order = buildOrderBy(fieldDefCols, ["iLineNo", "FieldName"]);
+            const q = buildPagedQuery({
+                table: T("fieldDef"),
+                cols: rs.present.length > 0
+                    ? rs.present.map((c) => `[${c}]`)
+                    : ["[FieldName]"],
+                where,
+                orderBy: order.orderBy,
+                page,
+                pageSize,
+            });
+            const cnt = await tryQuery("describe_table.fields.count", q.countSql, warnings);
+            const total = Number(cnt[0]?.Total ?? 0);
+            const items = total > 0
+                ? await tryQuery("describe_table.fields", q.sql, warnings)
+                : [];
+            // 全量字段名（不含属性）— 截断后模型仍能知道有哪些字段可查
+            let fieldNames = [];
+            const nameSel = pickCols(fieldDefCols, ["FieldName"]);
+            if (nameSel.length > 0) {
+                const nameList = nameSel.map((c) => `[${c}]`).join(", ");
+                const nameWhere = buildWhere(fieldDefCols, [
+                    { filters: [{ col: "TableName", op: "eq", value: safeName }] },
+                ]).where;
+                const nameRows = await tryQuery("describe_table.fieldNames", `SELECT ${nameList} FROM ${T("fieldDef")}${nameWhere} ORDER BY ${nameList}`, warnings);
+                fieldNames = nameRows
+                    .map((r) => String(r.FieldName ?? ""))
+                    .filter(Boolean)
+                    .slice(0, 500);
+            }
+            return ok(envelope({
+                items,
+                pagination: sqlPagination(page, pageSize, total),
+                warnings,
+                table,
+                registered: true,
+                source: "TableSetTB",
+                fieldCount: total,
+                remainingFields: Math.max(0, total - items.length),
+                fieldNames,
+            }));
+        }
+        // ---- 2) 未登记在 TableSetTB：回退到物理表（环境库 → 用户库） ----
+        const dbs = [envDb(), userName].filter(Boolean);
+        let physical = [];
+        let sourceDb = "";
+        for (const db of dbs) {
+            const rows = await tryQuery("describe_table.physical", `SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE, COLUMN_DEFAULT FROM [${db}].INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA='dbo' AND TABLE_NAME='${escapeSql(safeName)}' ORDER BY ORDINAL_POSITION`, warnings);
+            if (rows.length > 0) {
+                physical = rows;
+                sourceDb = db;
+                break;
+            }
+        }
+        if (physical.length > 0) {
+            const { page: paged, pagination } = paginate(physical, page, pageSize);
+            return ok(envelope({
+                items: paged,
+                pagination,
+                warnings,
+                table: { TableName: safeName },
+                registered: false,
+                source: "INFORMATION_SCHEMA",
+                sourceDb,
+                fieldCount: physical.length,
+                fieldNames: physical
+                    .map((r) => String(r.COLUMN_NAME ?? ""))
+                    .filter(Boolean)
+                    .slice(0, 500),
+                hint: `该表未登记在 TableSetTB，返回的是 ${sourceDb} 中的物理列定义`,
+            }));
+        }
+        // ---- 3) 都不存在：给出模糊候选，便于定位 ----
+        let candidates = [];
+        if (tCols.length > 0 && hasCol(tableDefCols, "TableDesc")) {
+            const filters = ["TableName", "TableDesc"]
+                .filter((c) => hasCol(tableDefCols, c))
+                .map((c) => ({ col: c, op: "like", value: tableName }));
+            const candWhere = buildWhere(tableDefCols, [
+                { logic: "or", filters },
+            ]).where;
+            if (candWhere) {
+                candidates = await tryQuery("describe_table.candidates", `SELECT TOP 10 ${pickCols(tableDefCols, [
+                    "TableName",
+                    "TableDesc",
+                    "TableType",
+                ])
+                    .map((c) => `[${c}]`)
+                    .join(", ")} FROM ${T("tableDef")}${candWhere}`, warnings);
+            }
+        }
+        warnings.push({
+            module: "describe_table",
+            message: `表 "${tableName}" 既未登记在 TableSetTB，也不是环境库/用户库中的物理表`,
+            hint: "可用 resolve_table(nameOrKeyword=...) 或 list_forms(keyword=...) 按中文名定位",
+            fallback: "resolve_table",
+        });
+        return ok(envelope({
+            items: [],
+            pagination: sqlPagination(page, pageSize, 0),
+            warnings,
+            table: null,
+            registered: false,
+            candidates,
+        }));
+    });
+    // ============================================================
+    // search_schema
+    // ============================================================
+    server.registerTool("search_schema", {
+        description: WARNING +
+            "\n\n全局搜索表名/字段名/描述/字段使用追踪。返回匹配的表和字段。usage 模式可追踪字段在哪些表和窗体中使用。",
+        inputSchema: {
+            keyword: z.string().max(200).describe("搜索关键词"),
+            searchIn: z
+                .enum(["all", "tables", "fields", "usage"])
+                .optional()
+                .default("all")
+                .describe("all/tables/fields/usage(字段使用追踪)"),
+            limit: z.number().optional().default(30).describe("返回条数上限"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ keyword, searchIn, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        if (searchIn === "usage") {
+            const safeName = keyword.replace(/[^a-zA-Z0-9_]/g, "");
+            const fieldDefCols = await getTableColumns(T("fieldDef"));
+            const fdCols = pickCols(fieldDefCols, [
+                "TableName",
+                "FieldName",
+                "FieldDesc",
+                "FieldType",
+                "cLinkTable",
+                "cLinkField",
+            ]);
+            const fieldDefs = fdCols.length > 0 && hasCol(fieldDefCols, "FieldName")
+                ? await tryQuery("search_schema.usage.fieldDefs", `SELECT ${fdCols.map((c) => `[${c}]`).join(", ")} FROM ${T("fieldDef")} WHERE FieldName='${escapeSql(safeName)}'` +
+                    (hasCol(fieldDefCols, "TableName") ? " ORDER BY [TableName]" : ""), warnings)
+                : [];
+            const tableNames = [
+                ...new Set(fieldDefs
+                    .map((f) => f.TableName)
+                    .filter(Boolean)),
+            ];
+            let tableInfos = [];
+            if (tableNames.length > 0) {
+                const tableDefCols = await getTableColumns(T("tableDef"));
+                const tCols = pickCols(tableDefCols, [
+                    "TableName",
+                    "TableDesc",
+                    "TableType",
+                    "Modular1",
+                ]);
+                if (tCols.length > 0) {
+                    const names = tableNames
+                        .map((n) => `'${escapeSql(String(n))}'`)
+                        .join(",");
+                    tableInfos = await tryQuery("search_schema.usage.tables", `SELECT ${tCols.map((c) => `[${c}]`).join(", ")} FROM ${T("tableDef")} WHERE TableName IN (${names})`, warnings);
+                }
+            }
+            const formUsage = await tryQuery("search_schema.usage.forms", `SELECT DISTINCT f.FormID, f.FormName, f.LinkTable
+           FROM ${T("formDef")} f
+           INNER JOIN ${T("formRuleHed")} rh ON f.FormID = rh.FormID
+           INNER JOIN ${T("formRuleDet")} rd ON rh.XDID = rd.PXDID
+           WHERE rd.FieldName='${escapeSql(safeName)}'
+           ORDER BY f.FormID`, warnings);
+            const { page: pagedTables, pagination: pagTables } = paginate(tableInfos, page, pageSize);
+            return ok(envelope({
+                items: pagedTables,
+                fieldDefs,
+                formUsage,
+                pagination: { tables: pagTables },
+                warnings,
+                fieldName: safeName,
+                usageCount: fieldDefs.length,
+            }));
+        }
+        // ---- tables / fields：SQL 端 COUNT + OFFSET/FETCH 真实分页 ----
+        const tableDefCols = await getTableColumns(T("tableDef"));
+        const fieldDefCols = await getTableColumns(T("fieldDef"));
+        const result = {};
+        const pagination = {};
+        if (searchIn === "all" || searchIn === "tables") {
+            const tCols = pickCols(tableDefCols, [
+                "TableName",
+                "TableDesc",
+                "TableType",
+                "Modular1",
+                "EnglishDesc",
+            ]);
+            const filters = ["TableName", "TableDesc", "EnglishDesc"]
+                .filter((c) => hasCol(tableDefCols, c))
+                .map((c) => ({ col: c, op: "like", value: keyword }));
+            const { where, skipped } = buildWhere(tableDefCols, filters.length > 0 ? [{ logic: "or", filters }] : []);
+            const order = buildOrderBy(tableDefCols, ["TableName"]);
+            if (skipped.length > 0) {
+                warnings.push({
+                    module: "search_schema.tables",
+                    message: `以下列在本环境库不存在，条件已跳过: ${skipped.join(", ")}`,
+                });
+            }
+            if (tCols.length > 0 && where) {
+                const q = buildPagedQuery({
+                    table: T("tableDef"),
+                    cols: tCols,
+                    where,
+                    orderBy: order.orderBy,
+                    page,
+                    pageSize,
+                });
+                const cnt = await tryQuery("search_schema.tables.count", q.countSql, warnings);
+                const total = Number(cnt[0]?.Total ?? 0);
+                result.tables =
+                    total > 0
+                        ? await tryQuery("search_schema.tables", q.sql, warnings)
+                        : [];
+                pagination.tables = sqlPagination(page, pageSize, total);
+            }
+            else {
+                result.tables = [];
+                pagination.tables = sqlPagination(page, pageSize, 0);
+                if (!where) {
+                    warnings.push({
+                        module: "search_schema.tables",
+                        message: "环境库 TableSetTB 无可用搜索列（TableName/TableDesc/EnglishDesc 均不存在）",
+                        hint: "可用 describe_table 查看实际字段",
+                    });
+                }
+            }
+        }
+        if (searchIn === "all" || searchIn === "fields") {
+            const fCols = pickCols(fieldDefCols, [
+                "TableName",
+                "FieldName",
+                "FieldDesc",
+                "FieldType",
+                "EnglishDesc",
+            ]);
+            const filters = ["FieldName", "FieldDesc", "EnglishDesc"]
+                .filter((c) => hasCol(fieldDefCols, c))
+                .map((c) => ({ col: c, op: "like", value: keyword }));
+            const { where, skipped } = buildWhere(fieldDefCols, filters.length > 0 ? [{ logic: "or", filters }] : []);
+            const order = buildOrderBy(fieldDefCols, ["TableName", "iLineNo"]);
+            if (skipped.length > 0) {
+                warnings.push({
+                    module: "search_schema.fields",
+                    message: `以下列在本环境库不存在，条件已跳过: ${skipped.join(", ")}`,
+                });
+            }
+            if (fCols.length > 0 && where) {
+                const q = buildPagedQuery({
+                    table: T("fieldDef"),
+                    cols: fCols,
+                    where,
+                    orderBy: order.orderBy,
+                    page,
+                    pageSize,
+                });
+                const cnt = await tryQuery("search_schema.fields.count", q.countSql, warnings);
+                const total = Number(cnt[0]?.Total ?? 0);
+                result.fields =
+                    total > 0
+                        ? await tryQuery("search_schema.fields", q.sql, warnings)
+                        : [];
+                pagination.fields = sqlPagination(page, pageSize, total);
+            }
+            else {
+                result.fields = [];
+                pagination.fields = sqlPagination(page, pageSize, 0);
+                if (!where) {
+                    warnings.push({
+                        module: "search_schema.fields",
+                        message: "环境库 TableFieldSetTB 无可用搜索列（FieldName/FieldDesc/EnglishDesc 均不存在）",
+                        hint: "可用 describe_table 查看实际字段",
+                    });
+                }
+            }
+        }
+        return ok(envelope({
+            items: result.tables ?? [],
+            fields: result.fields ?? [],
+            pagination,
+            warnings,
+            searchIn,
+            keyword,
+        }));
+    });
+    // ============================================================
+    // get_table_relations
+    // ============================================================
+    server.registerTool("get_table_relations", {
+        description: WARNING + "\n\n分析表的主从关系和外键关联。返回父表、子表、关联字段。",
+        inputSchema: { tableName: z.string().max(128).describe("表名") },
+    }, async ({ tableName }) => {
+        const warnings = [];
+        const safeName = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        if (!(await tableExists(T("tableDef")))) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    {
+                        module: "get_table_relations",
+                        message: `环境库缺少 ${T("tableDef")}`,
+                        fallback: "get_capabilities",
+                    },
+                ],
+            }));
+        }
+        const rs = await resolveSelect(T("tableDef"), [
+            "TableName",
+            "TableDesc",
+            "TableType",
+            "ParentTable",
+        ]);
+        const parentTables = await tryQuery("get_table_relations.parents", `SELECT ${rs.select} FROM ${T("tableDef")} WHERE [TableName]='${escapeSql(safeName)}' AND [ParentTable] IS NOT NULL AND [ParentTable] != ''`, warnings);
+        const childTables = await tryQuery("get_table_relations.children", `SELECT ${rs.select} FROM ${T("tableDef")} WHERE [ParentTable]='${escapeSql(safeName)}' ORDER BY [TableName]`, warnings);
+        let fieldLinks;
+        if (await tableExists(T("fieldDef"))) {
+            const frs = await resolveSelect(T("fieldDef"), [
+                "TableName",
+                "FieldName",
+                "FieldDesc",
+                "cLinkTable",
+                "cLinkField",
+                "cDstField",
+            ]);
+            fieldLinks = {
+                module: "fieldLinks",
+                available: true,
+                items: await tryQuery("get_table_relations.fieldLinks", `SELECT ${frs.select} FROM ${T("fieldDef")} WHERE [TableName]='${escapeSql(safeName)}' AND [cLinkTable] IS NOT NULL AND [cLinkTable] != ''`, warnings),
+            };
+        }
+        else {
+            fieldLinks = {
+                module: "fieldLinks",
+                available: false,
+                reason: `环境库缺少 ${T("fieldDef")}`,
+            };
+        }
+        return ok(envelope({
+            items: parentTables,
+            pagination: null,
+            warnings,
+            table: safeName,
+            children: childTables,
+            fieldLinks,
+        }));
+    });
+    // ============================================================
+    // check_user_table
+    // ============================================================
+    server.registerTool("check_user_table", {
+        description: WARNING +
+            "\n\n检查用户库中表是否实际存在，返回实际字段列表并与环境库定义对比。",
+        inputSchema: {
+            tableName: z.string().max(128).describe("表名"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ tableName, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        const safeName = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        if (!userName) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    {
+                        module: "check_user_table",
+                        message: "用户库未配置(DB_TARGET_DATABASES 为空)",
+                    },
+                ],
+            }));
+        }
+        const existsRows = await tryQuery("check_user_table.exists", `SELECT TABLE_NAME FROM [${userName}].INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA='dbo' AND TABLE_NAME='${escapeSql(safeName)}'`, warnings);
+        if (existsRows.length === 0) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings,
+                table: safeName,
+                exists: false,
+                userDb: userName,
+                hint: `表 "${tableName}" 在用户库 ${userName} 中不存在`,
+            }));
+        }
+        const actualFields = await tryQuery("check_user_table.actual", `SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE, COLUMN_DEFAULT FROM [${userName}].INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA='dbo' AND TABLE_NAME='${escapeSql(safeName)}' ORDER BY ORDINAL_POSITION`, warnings);
+        let definedFields = [];
+        let definedModule = {
+            module: "definedFields",
+            available: true,
+            items: [],
+        };
+        if (await tableExists(T("fieldDef"))) {
+            const info = await getTableInfo(T("fieldDef"));
+            const rs = await resolveSelect(T("fieldDef"), [
+                "iLineNo",
+                "FieldName",
+                "FieldType",
+                "bAllowNull",
+                "DefaultValue",
+            ]);
+            const where = buildWhere(info.columns, [
+                { filters: [{ col: "TableName", op: "eq", value: safeName }] },
+            ]).where;
+            const order = buildOrderBy(info.columns, ["iLineNo", "FieldName"]);
+            definedFields = await tryQuery("check_user_table.defined", `SELECT ${rs.select} FROM ${T("fieldDef")}${where}${order.orderBy}`, warnings);
+            definedModule = {
+                module: "definedFields",
+                available: true,
+                missing: rs.missing,
+            };
+        }
+        else {
+            definedModule = {
+                module: "definedFields",
+                available: false,
+                reason: `环境库缺少 ${T("fieldDef")}`,
+            };
+        }
+        const { page: pagedActual, pagination: pagActual } = paginate(actualFields, page, pageSize);
+        return ok(envelope({
+            items: pagedActual,
+            pagination: pagActual,
+            warnings,
+            table: safeName,
+            exists: true,
+            userDb: userName,
+            actualFieldCount: actualFields.length,
+            definedFieldCount: definedFields.length,
+            definedFields,
+            definedFieldsModule: definedModule,
+        }));
+    });
+    // ============================================================
+    // get_table_indexes
+    // ============================================================
+    server.registerTool("get_table_indexes", {
+        description: WARNING +
+            "\n\n查询指定表的索引和外键信息。数据来源: 用户库 sys.indexes + sys.foreign_keys",
+        inputSchema: {
+            tableName: z.string().max(128).describe("表名"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ tableName, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        const safeName = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        if (!userName) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    {
+                        module: "get_table_indexes",
+                        message: "用户库未配置(DB_TARGET_DATABASES 为空)",
+                    },
+                ],
+            }));
+        }
+        const indexes = await tryQuery("get_table_indexes.indexes", `
+        SELECT 
+          i.name AS IndexName,
+          i.type_desc AS IndexType,
+          i.is_unique AS IsUnique,
+          i.is_primary_key AS IsPrimaryKey,
+          c.name AS ColumnName,
+          ic.is_included_column AS IsIncluded,
+          ic.key_ordinal AS KeyOrdinal
+        FROM [${userName}].sys.indexes i
+        INNER JOIN [${userName}].sys.index_columns ic ON i.object_id = ic.object_id AND i.index_id = ic.index_id
+        INNER JOIN [${userName}].sys.columns c ON ic.object_id = c.object_id AND ic.column_id = c.column_id
+        INNER JOIN [${userName}].sys.tables t ON i.object_id = t.object_id
+        WHERE t.name = '${escapeSql(safeName)}'
+        ORDER BY i.name, ic.key_ordinal
+      `, warnings);
+        const foreignKeys = await tryQuery("get_table_indexes.foreignKeys", `
+        SELECT 
+          fk.name AS FKName,
+          OBJECT_NAME(fk.parent_object_id) AS ParentTable,
+          col.name AS ParentColumn,
+          OBJECT_NAME(fk.referenced_object_id) AS ReferencedTable,
+          rcol.name AS ReferencedColumn
+        FROM [${userName}].sys.foreign_keys fk
+        INNER JOIN [${userName}].sys.foreign_key_columns fkc ON fk.object_id = fkc.constraint_object_id
+        INNER JOIN [${userName}].sys.columns col ON fkc.parent_object_id = col.object_id AND fkc.parent_column_id = col.column_id
+        INNER JOIN [${userName}].sys.columns rcol ON fkc.referenced_object_id = rcol.object_id AND fkc.referenced_column_id = rcol.column_id
+        WHERE OBJECT_NAME(fk.parent_object_id) = '${escapeSql(safeName)}'
+           OR OBJECT_NAME(fk.referenced_object_id) = '${escapeSql(safeName)}'
+        ORDER BY fk.name
+      `, warnings);
+        const { page: pagedIndexes, pagination: pag } = paginate(indexes, page, pageSize);
+        return ok(envelope({
+            items: pagedIndexes,
+            pagination: pag,
+            warnings,
+            tableName: safeName,
+            foreignKeys,
+            indexCount: indexes.length,
+        }));
+    });
+    // ============================================================
+    // suggest_indexes
+    // ============================================================
+    server.registerTool("suggest_indexes", {
+        description: WARNING +
+            "\n\n基于环境库字段定义，对指定表进行索引建议分析。根据字段类型(bSearchField/bUnique/cLinkTable/bVirtual等)给出索引优化建议。数据来源: XDWmsCommon.dbo.TableFieldSetTB",
+        inputSchema: {
+            tableName: z.string().max(128).describe("表名"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ tableName, page = 1, pageSize = 50 }) => {
+        const safeName = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        const warnings = [];
+        if (!(await tableExists(T("fieldDef")))) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    {
+                        module: "suggest_indexes",
+                        message: `环境库缺少 ${T("fieldDef")}`,
+                        fallback: "get_capabilities",
+                    },
+                ],
+            }));
+        }
+        const rs = await resolveSelect(T("fieldDef"), [
+            "FieldName",
+            "FieldDesc",
+            "FieldType",
+            "bSearchField",
+            "bUnique",
+            "bAllowNull",
+            "cLinkTable",
+            "cLinkField",
+            "bVirtual",
+        ]);
+        const info = await getTableInfo(T("fieldDef"));
+        const where = buildWhere(info.columns, [
+            { filters: [{ col: "TableName", op: "eq", value: safeName }] },
+        ]).where;
+        const fields = await tryQuery("suggest_indexes.fields", `SELECT ${rs.select} FROM ${T("fieldDef")}${where}`, warnings);
+        if (fields.length === 0) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings,
+                tableName: safeName,
+                hint: `表 "${tableName}" 在环境库中未定义，无法给出索引建议`,
+            }));
+        }
+        const suggestions = [];
+        const singleColIndexes = [];
+        const compositeCandidate = [];
+        for (const f of fields) {
+            if (f.bSearchField && f.cLinkTable) {
+                suggestions.push(`外键关联字段 ${f.FieldName}(${f.FieldDesc}) → ${f.cLinkTable}.${f.cLinkField}，建议建非聚集索引`);
+                singleColIndexes.push(f.FieldName);
+            }
+            else if (f.bSearchField) {
+                suggestions.push(`搜索字段 ${f.FieldName}(${f.FieldDesc})，建议建非聚集索引`);
+                singleColIndexes.push(f.FieldName);
+            }
+            if (f.bUnique) {
+                suggestions.push(`唯一字段 ${f.FieldName}(${f.FieldDesc})，建议建唯一索引`);
+            }
+            if (f.bVirtual) {
+                suggestions.push(`虚拟字段 ${f.FieldName}(${f.FieldDesc})，不建议建索引（计算字段）`);
+            }
+            if (f.cLinkTable) {
+                compositeCandidate.push(f.FieldName);
+            }
+        }
+        if (compositeCandidate.length >= 2) {
+            suggestions.push(`复合索引候选: (${compositeCandidate.join(", ")})`);
+        }
+        const fieldDetails = fields.map((f) => ({
+            FieldName: f.FieldName,
+            FieldDesc: f.FieldDesc,
+            bSearchField: f.bSearchField,
+            bUnique: f.bUnique,
+            cLinkTable: f.cLinkTable,
+            bVirtual: f.bVirtual,
+        }));
+        const { page: pagedFields, pagination: pag } = paginate(fieldDetails, page, pageSize);
+        return ok(envelope({
+            items: pagedFields,
+            pagination: pag,
+            warnings,
+            tableName: safeName,
+            fieldCount: fields.length,
+            suggestions,
+        }));
+    });
+    // ============================================================
+    // get_virtual_tables
+    // ============================================================
+    server.registerTool("get_virtual_tables", {
+        description: WARNING +
+            "\n\n查询系统虚拟表定义及其关联的物理表。虚拟表通过SQL动态生成表结构。数据来源: XDWmsCommon.dbo.VirtualTableTB",
+        inputSchema: {
+            tableName: z
+                .string()
+                .max(128)
+                .optional()
+                .describe("虚拟表名，精确查询"),
+            keyword: z.string().max(200).optional().describe("按表名模糊搜索"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ tableName, keyword, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        if (!(await tableExists(T("virtualTable")))) {
+            return ok(envelope({
+                items: [],
+                pagination: sqlPagination(page, pageSize, 0),
+                warnings: [
+                    {
+                        module: "get_virtual_tables",
+                        message: `环境库缺少 ${T("virtualTable")}`,
+                        fallback: "get_capabilities",
+                    },
+                ],
+            }));
+        }
+        const info = await getTableInfo(T("virtualTable"));
+        const rs = await resolveSelect(T("virtualTable"), [
+            "TableName",
+            "VirtualTable",
+            "FixTableName",
+        ]);
+        const groups = [];
+        if (tableName)
+            groups.push({ filters: [{ col: "TableName", op: "eq", value: tableName }] });
+        if (keyword)
+            groups.push({ filters: [{ col: "TableName", op: "like", value: keyword }] });
+        const { where } = buildWhere(info.columns, groups);
+        const order = buildOrderBy(info.columns, ["TableName"]);
+        const q = buildPagedQuery({
+            table: T("virtualTable"),
+            cols: rs.present.length > 0
+                ? rs.present.map((c) => `[${c}]`)
+                : ["[TableName]"],
+            where,
+            orderBy: order.orderBy,
+            page,
+            pageSize,
+        });
+        const cnt = await tryQuery("get_virtual_tables.count", q.countSql, warnings);
+        const total = Number(cnt[0]?.Total ?? 0);
+        const items = total > 0 ? await tryQuery("get_virtual_tables", q.sql, warnings) : [];
+        return ok(envelope({
+            items,
+            pagination: sqlPagination(page, pageSize, total),
+            warnings,
+        }));
+    });
+    // ============================================================
+    // get_module_tree
+    // ============================================================
+    server.registerTool("get_module_tree", {
+        description: WARNING +
+            "\n\n获取系统模块树结构。ModuleManageTB 定义了系统的模块层次(如销售管理→销售订单→销售出库)。",
+        inputSchema: {
+            keyword: z.string().max(200).optional().describe("按模块名称搜索"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ keyword, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        // 环境库可能没有 ModuleManageTB，缺失时优雅降级而非报错
+        if (!(await tableExists(T("moduleManage")))) {
+            return ok(envelope({
+                items: [],
+                pagination: sqlPagination(page, pageSize, 0),
+                warnings: [
+                    {
+                        module: "get_module_tree",
+                        message: `环境库缺少 ${T("moduleManage")}`,
+                        hint: "可用 get_capabilities 查看本环境支持的元数据表",
+                        fallback: "get_capabilities",
+                    },
+                ],
+            }));
+        }
+        const info = await getTableInfo(T("moduleManage"));
+        const rs = await resolveSelect(T("moduleManage"), [
+            "XDID",
+            "Name",
+            "ModuleDesc",
+            "ModuleAlias",
+            "Code",
+            "ID",
+            "ParentXDID",
+            "LevelCode",
+            "HelpCode",
+        ]);
+        if (rs.present.length === 0) {
+            return ok(envelope({
+                items: [],
+                pagination: sqlPagination(page, pageSize, 0),
+                warnings: [
+                    {
+                        module: "get_module_tree",
+                        message: "ModuleManageTB 无可用字段",
+                    },
+                ],
+            }));
+        }
+        const groups = [];
+        if (keyword) {
+            const filters = ["Name", "ModuleDesc"]
+                .filter((c) => hasCol(info.columns, c))
+                .map((c) => ({ col: c, op: "like", value: keyword }));
+            if (filters.length > 0)
+                groups.push({ logic: "or", filters });
+        }
+        const { where } = buildWhere(info.columns, groups);
+        const order = buildOrderBy(info.columns, ["LevelCode"]);
+        const q = buildPagedQuery({
+            table: T("moduleManage"),
+            cols: rs.present.map((c) => `[${c}]`),
+            where,
+            orderBy: order.orderBy,
+            page,
+            pageSize,
+        });
+        const cnt = await tryQuery("get_module_tree.count", q.countSql, warnings);
+        const total = Number(cnt[0]?.Total ?? 0);
+        const modules = total > 0 ? await tryQuery("get_module_tree", q.sql, warnings) : [];
+        const moduleNames = [
+            ...new Set(modules
+                .map((m) => m.Name)
+                .filter((name) => typeof name === "string")
+                .map((name) => `'${escapeSql(String(name))}'`)),
+        ];
+        let funcCounts = [];
+        if (moduleNames.length > 0 && (await tableExists(T("function")))) {
+            funcCounts = await tryQuery("get_module_tree.funcCounts", `SELECT [ParentFName] AS ModuleName, COUNT(*) AS funcCount FROM ${T("function")} WHERE [ParentFName] IN (${moduleNames.join(",")}) GROUP BY [ParentFName]`, warnings);
+        }
+        return ok(envelope({
+            items: modules,
+            pagination: sqlPagination(page, pageSize, total),
+            warnings,
+            funcCounts,
+        }));
+    });
+    // ============================================================
+    // get_inoutkind_detail
+    // ============================================================
+    server.registerTool("get_inoutkind_detail", {
+        description: WARNING +
+            "\n\n查看出入库类型表(InOutKindTB)的完整定义与明细数据。返回表头、字段定义，以及按编号排序的实际数据行。数据来源: XDWmsCommon.dbo.InOutKindTB。",
+        inputSchema: {
+            keyword: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("按编号/名称/助记码模糊筛选"),
+            includeData: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("是否返回实际数据行"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ keyword, includeData = true, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        // 表头定义（TableSetTB 可能没有 InOutKindTB 登记）
+        let tableDef = null;
+        if (await tableExists(T("tableDef"))) {
+            const trs = await resolveSelect(T("tableDef"), [
+                "TableName",
+                "TableDesc",
+                "TableType",
+                "ParentTable",
+                "Modular1",
+                "Modular2",
+                "Remark",
+            ]);
+            const rows = await tryQuery("get_inoutkind_detail.tableDef", `SELECT ${trs.select} FROM ${T("tableDef")} WHERE [TableName]='InOutKindTB'`, warnings);
+            tableDef = rows[0] ?? null;
+        }
+        // 字段定义
+        let fields = { module: "fields", available: true, items: [] };
+        if (await tableExists(T("fieldDef"))) {
+            const info = await getTableInfo(T("fieldDef"));
+            const rs = await resolveSelect(T("fieldDef"), [
+                "iLineNo",
+                "FieldName",
+                "FieldDesc",
+                "FieldType",
+                "iPrecision",
+                "iScale",
+                "DefaultValue",
+                "bAllowNull",
+                "bVirtual",
+                "bSearchField",
+                "bUnique",
+                "cLinkTable",
+                "cLinkField",
+                "cDstField",
+            ]);
+            const where = buildWhere(info.columns, [
+                { filters: [{ col: "TableName", op: "eq", value: "InOutKindTB" }] },
+            ]).where;
+            const order = buildOrderBy(info.columns, ["iLineNo", "FieldName"]);
+            fields = {
+                module: "fields",
+                available: true,
+                items: await tryQuery("get_inoutkind_detail.fields", `SELECT ${rs.select} FROM ${T("fieldDef")}${where}${order.orderBy}`, warnings),
+            };
+        }
+        else {
+            fields = {
+                module: "fields",
+                available: false,
+                reason: `环境库缺少 ${T("fieldDef")}`,
+            };
+        }
+        // 实际数据行（InOutKindTB 可能不存在）
+        let data = [];
+        let dataModule = { module: "data", available: true, items: [] };
+        let pagination = null;
+        if (includeData) {
+            if (await tableExists(T("inOutKind"))) {
+                const info = await getTableInfo(T("inOutKind"));
+                const rs = await resolveSelect(T("inOutKind"), [
+                    "ID",
+                    "Code",
+                    "Name",
+                    "XDFormID",
+                    "IOFlag",
+                    "IsOther",
+                    "IsInOther",
+                    "IsChangePrice",
+                    "bDefault",
+                    "IoAcc",
+                    "bEnableDet",
+                    "DefaultPState",
+                    "Prefix",
+                    "bZZ",
+                    "IoAccName",
+                    "bIoPzShow",
+                    "ParentID",
+                    "LevelCode",
+                    "HelpCode",
+                    "MakeMan",
+                    "MakeDate",
+                    "EditMan",
+                    "EditDate",
+                    "Remark",
+                ]);
+                const groups = [];
+                if (keyword) {
+                    const filters = ["Code", "Name", "HelpCode"]
+                        .filter((c) => hasCol(info.columns, c))
+                        .map((c) => ({ col: c, op: "like", value: keyword }));
+                    if (filters.length > 0)
+                        groups.push({ logic: "or", filters });
+                }
+                const { where } = buildWhere(info.columns, groups);
+                const order = buildOrderBy(info.columns, ["Code"]);
+                const q = buildPagedQuery({
+                    table: T("inOutKind"),
+                    cols: rs.present.length > 0
+                        ? rs.present.map((c) => `[${c}]`)
+                        : ["[Code]"],
+                    where,
+                    orderBy: order.orderBy,
+                    page,
+                    pageSize,
+                });
+                const cnt = await tryQuery("get_inoutkind_detail.count", q.countSql, warnings);
+                const total = Number(cnt[0]?.Total ?? 0);
+                data =
+                    total > 0
+                        ? await tryQuery("get_inoutkind_detail.data", q.sql, warnings)
+                        : [];
+                pagination = sqlPagination(page, pageSize, total);
+                dataModule = { module: "data", available: true };
+            }
+            else {
+                dataModule = {
+                    module: "data",
+                    available: false,
+                    reason: `环境库缺少 ${T("inOutKind")}`,
+                };
+                warnings.push({
+                    module: "get_inoutkind_detail.data",
+                    message: `环境库缺少 ${T("inOutKind")}`,
+                    fallback: "get_capabilities",
+                });
+                pagination = sqlPagination(page, pageSize, 0);
+            }
+        }
+        return ok(envelope({
+            items: data,
+            pagination,
+            warnings,
+            table: tableDef,
+            fields,
+            dataModule,
+            totalData: data.length,
+        }));
+    });
+    // ============================================================
+    // resolve_table（中文别名 / 关键词 → 实际表名）
+    // ============================================================
+    server.registerTool("resolve_table", {
+        description: WARNING +
+            "\n\n把中文表名/关键词解析为实际表名。先精确匹配 TableName，未命中再按 TableName/TableDesc/EnglishDesc 模糊匹配，返回带 matchType=exact|fuzzy 的候选。",
+        inputSchema: {
+            nameOrKeyword: z.string().max(200).describe("表名或中文关键词，如 发货通知"),
+            page: z.number().int().min(1).default(1).describe("页码"),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("每页数量"),
+        },
+    }, async ({ nameOrKeyword, page = 1, pageSize = 50 }) => {
+        const warnings = [];
+        if (!(await tableExists(T("tableDef")))) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    {
+                        module: "resolve_table",
+                        message: `环境库缺少 ${T("tableDef")}`,
+                        fallback: "get_capabilities",
+                    },
+                ],
+            }));
+        }
+        const tCols = await getTableColumns(T("tableDef"));
+        const sel = pickCols(tCols, [
+            "TableName",
+            "TableDesc",
+            "TableType",
+            "Modular1",
+            "EnglishDesc",
+        ]);
+        if (sel.length === 0) {
+            return ok(envelope({
+                items: [],
+                pagination: null,
+                warnings: [
+                    { module: "resolve_table", message: "TableSetTB 无可用字段" },
+                ],
+            }));
+        }
+        const selectList = sel.map((c) => `[${c}]`).join(", ");
+        const safe = nameOrKeyword.replace(/[^a-zA-Z0-9_]/g, "");
+        // 1) 精确匹配 TableName
+        let matchType = "exact";
+        let rows = [];
+        if (safe && hasCol(tCols, "TableName")) {
+            const { where } = buildWhere(tCols, [
+                { filters: [{ col: "TableName", op: "eq", value: safe }] },
+            ]);
+            rows = await tryQuery("resolve_table.exact", `SELECT TOP 50 ${selectList} FROM ${T("tableDef")}${where} ORDER BY [TableName]`, warnings);
+        }
+        // 2) 未命中 → 模糊匹配
+        if (rows.length === 0) {
+            matchType = "fuzzy";
+            const filters = ["TableName", "TableDesc", "EnglishDesc"]
+                .filter((c) => hasCol(tCols, c))
+                .map((c) => ({ col: c, op: "like", value: nameOrKeyword }));
+            const { where } = buildWhere(tCols, filters.length > 0 ? [{ logic: "or", filters }] : []);
+            if (where) {
+                rows = await tryQuery("resolve_table.fuzzy", `SELECT TOP 50 ${selectList} FROM ${T("tableDef")}${where} ORDER BY [TableName]`, warnings);
+            }
+        }
+        const items = rows.map((r) => ({
+            ...r,
+            matchType,
+        }));
+        if (items.length === 0) {
+            warnings.push({
+                module: "resolve_table",
+                message: `未找到与 "${nameOrKeyword}" 匹配的表`,
+                hint: "可用 list_tables(keyword=...) 或 search_schema(keyword=...) 进一步查找",
+                fallback: "list_tables",
+            });
+        }
+        const { page: paged, pagination } = paginate(items, page, pageSize);
+        return ok(envelope({
+            items: paged,
+            pagination,
+            warnings,
+            query: nameOrKeyword,
+            matchType,
+        }));
+    });
+}
+//# sourceMappingURL=table-tools.js.map