mes-mcp 0.1.0 → 0.2.1

package/.env.example

@@ -2,3 +2,4 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=
 MES_TIMEOUT_MS=30000
+MES_REGISTER_DYNAMIC_TOOLS=false

package/README.md

@@ -1,6 +1,6 @@
 # MES MCP
 
-MES MCP 是 MES 开放集成体系的 MCP 协议适配层，用于 Marvis 或其他 AI Agent 调用 MES 的 Agent OpenAPI 合同。
+MES MCP 是 MES 开放集成体系的 MCP 协议适配层，用于 Marvis 或其他 AI Agent 调用 MES 的后端动态业务动作目录。
 
 ## 边界
 
@@ -18,8 +18,11 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
 MES_TIMEOUT_MS=30000
+MES_REGISTER_DYNAMIC_TOOLS=false
 ```
 
+`MES_REGISTER_DYNAMIC_TOOLS` 默认关闭。关闭时 MCP 只注册稳定接口工具，通过后端动作目录发现并执行全部授权业务能力；打开后会把所有授权页面动作额外展开成 `mes.<动作编码>` 工具，适合明确需要工具直出且客户端能承载大量工具的场景。
+
 ## 开发
 
 ```bash
@@ -30,26 +33,26 @@ npm run dev
 
 ## 工具
 
-工具名与 `mes-node` Agent 合同编码一致：
-
-- `document_intake.parse`
-- `customer.match`
-- `material.match`
-- `sale_order.create`
-- `sale_order.confirm`
-- `production_plan.create_from_sale_order`
-- `work_order.create_from_plan`
-- `work_order.release`
-- `sale_order.query`
-- `work_order.query`
-- `inventory.query`
-- `mes_api.read`：按当前 MES 账号权限读取普通业务接口，例如 `/sale-order/list`、`/material/detail`。后端只放行只读类接口，写入动作必须使用专门 Agent 工具；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。
+默认使用后端动态业务动作接口：
+
+- `mes_action.list`：查询当前凭证和当前账号权限允许调用的 MES 页面业务动作。
+- `mes_action.detail`：查看某个业务动作的路径、权限、DTO 名称和输入 schema。
+- `mes_action.execute`：按动作编码执行业务动作。
+- `mes.<动作编码>`：仅在 `MES_REGISTER_DYNAMIC_TOOLS=true` 时，从 `mes-node` 自动发现并注册的动态工具，例如 `mes.sale_order.create`、`mes.approval.handle`、`mes.quality_inspection.submit`、`mes.sale_delivery.confirm`。
+
+动态动作只调用 `mes-node` 的 `/integration/agent/actions/*` 接口。MCP 不保存字段 schema，不复制状态机，不做业务默认值；后端会复用页面 Controller、DTO、权限、租户、状态、审批、库存、质量和 AI 调用日志。默认不把全部动作展开成独立工具，是为了避免 MCP 客户端一次性加载数百个工具；能力覆盖仍以 `mes_action.list/detail/execute` 为准。
+
+写入类动作通过 `confirm_required` 或 `commit` 执行时需要幂等键。调用方没有显式传入时，`mes-mcp` 会为当前工具调用生成一条集成幂等键；需要跨重试严格复用同一幂等键的批处理场景，仍建议调用方显式传入 `idempotencyKey`。
+
+- `mes_api.read`：按当前 MES 账号权限读取普通业务接口，例如 `/sale-order/list`、`/material/detail`。后端只放行只读类接口，写入动作必须使用动态业务动作；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。
 
 写入类工具支持 `executionMode`：
 
 - `preview`：只预览，不写入。
-- `confirm_required`：返回待确认内容，不写入。
-- `commit`：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行。
+- `confirm_required`：生成待确认单，不写入；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。
+- `commit`：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。
+
+跨重试或批处理场景如果需要严格复用同一次业务请求，调用方应显式传入同一个 `idempotencyKey`；单次交互式调用可以依赖 MCP 自动生成。
 
 ## Marvis 接入建议
 
@@ -57,4 +60,4 @@ npm run dev
 2. `agentClientId` 建议填写 `marvis` 或具体渠道名。
 3. 授权范围建议先选“跟随账号权限”，最高执行模式建议先用 `confirm_required`；如果只想开放少量动作，再切换为“仅允许指定工具”。只读型 AI 凭证可以只选择 `mes_api.read`。
 4. 将返回的 JWT 配置为 `MES_AGENT_TOKEN`。
-5. Marvis 侧通过 MCP 调用工具；图片、PDF、Excel 可先由 Marvis 识别成结构化草稿，再调用 `document_intake.parse`、`customer.match`、`material.match` 和后续写入工具。
+5. Marvis 侧通过 MCP 调用工具；图片、PDF、Excel 可先由 Marvis 识别成结构化草稿，再用 `mes_api.read` 或动态列表动作查询客户、物料等主数据，最后通过 `mes_action.detail` 和 `mes_action.execute` 执行创建、审批、确认、排产、质检、出库等页面业务动作。

package/dist/clients/mes-agent-api.client.js

@@ -1,81 +1,6 @@
 export class MesAgentApiClient {
     config;
-    static WRITE_PATH_TOKENS = new Set([
-        "create",
-        "update",
-        "delete",
-        "remove",
-        "revoke",
-        "toggle",
-        "confirm",
-        "cancel",
-        "approve",
-        "reject",
-        "release",
-        "start",
-        "complete",
-        "close",
-        "submit",
-        "import",
-        "run",
-        "cleanup",
-        "rotate",
-        "test",
-        "retry",
-        "allocate",
-        "unallocate",
-        "reverse",
-        "convert",
-        "send",
-        "recall",
-        "scrap",
-        "activate",
-        "deprecate",
-        "purge",
-        "adjust",
-        "freeze",
-        "end",
-        "configure",
-        "generate",
-        "save",
-        "copy",
-        "archive",
-        "publish",
-        "restore",
-        "execute",
-        "handle",
-        "verify",
-        "pass",
-        "fail",
-        "lock",
-        "unlock",
-        "enable",
-        "disable",
-        "bind",
-        "unbind",
-        "link",
-        "unlink",
-        "upload",
-        "assign",
-        "claim",
-        "dispatch",
-        "receive",
-        "issue",
-        "return",
-        "split",
-        "mark",
-        "change",
-        "transfer",
-        "in",
-        "out",
-    ]);
-    static WRITE_PATH_SEGMENTS = new Set([
-        "report",
-        "quick-report",
-        "report-operation",
-        "report-direct",
-        "batch-report",
-    ]);
+    businessActionsPromise;
     constructor(config) {
         this.config = config;
     }
@@ -115,25 +40,39 @@ export class MesAgentApiClient {
         if (/^\/integration\/agent(\/|$)/i.test(normalized)) {
             throw new Error("Use dedicated Agent tools for /integration/agent paths");
         }
-        if (this.isWriteLikePath(normalized)) {
-            throw new Error("mes_api.read only supports read-only MES API paths");
-        }
         return this.post(normalized, payload);
     }
-    isWriteLikePath(path) {
-        const actionSegments = path
-            .toLowerCase()
-            .split(/[?#]/)[0]
-            .split("/")
-            .filter(Boolean);
-        const lastSegment = actionSegments[actionSegments.length - 1] ?? "";
-        if (MesAgentApiClient.WRITE_PATH_SEGMENTS.has(lastSegment)) {
-            return true;
+    async listBusinessActions(options = {}) {
+        if (!options.refresh && this.businessActionsPromise) {
+            return this.businessActionsPromise;
+        }
+        this.businessActionsPromise = this.fetchBusinessActions().catch((error) => {
+            this.businessActionsPromise = undefined;
+            throw error;
+        });
+        return this.businessActionsPromise;
+    }
+    async getBusinessAction(actionCode) {
+        const actions = await this.listBusinessActions();
+        const cached = actions.find((action) => action.actionCode === actionCode);
+        if (cached)
+            return cached;
+        const refreshedActions = await this.listBusinessActions({ refresh: true });
+        return (refreshedActions.find((action) => action.actionCode === actionCode) ??
+            null);
+    }
+    async fetchBusinessActions() {
+        const pageSize = 100;
+        const firstPage = await this.post("/integration/agent/actions/list", { page: 1, pageSize });
+        if (firstPage.total <= firstPage.list.length)
+            return firstPage.list;
+        const actions = [...firstPage.list];
+        const pageCount = Math.ceil(firstPage.total / pageSize);
+        for (let page = 2; page <= pageCount; page += 1) {
+            const nextPage = await this.post("/integration/agent/actions/list", { page, pageSize });
+            actions.push(...nextPage.list);
         }
-        return lastSegment
-            .split(/[._-]+/)
-            .filter(Boolean)
-            .some((token) => MesAgentApiClient.WRITE_PATH_TOKENS.has(token));
+        return actions;
     }
     buildUrl(path) {
         const normalizedPath = path.startsWith("/") ? path : `/${path}`;

package/dist/config.js

@@ -10,6 +10,16 @@ function requiredEnv(name) {
     }
     return value;
 }
+function optionalBooleanEnv(name, fallback) {
+    const value = process.env[name]?.trim().toLowerCase();
+    if (!value)
+        return fallback;
+    if (["1", "true", "yes", "on"].includes(value))
+        return true;
+    if (["0", "false", "no", "off"].includes(value))
+        return false;
+    throw new Error(`${name} must be a boolean`);
+}
 export function loadConfig() {
     const timeoutMs = Number(optionalEnv("MES_TIMEOUT_MS", "30000"));
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -20,5 +30,6 @@ export function loadConfig() {
         mesApiPrefix: optionalEnv("MES_API_PREFIX", "/api").replace(/\/+$/, ""),
         mesAgentToken: requiredEnv("MES_AGENT_TOKEN"),
         timeoutMs,
+        registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
     };
 }

package/dist/index.js

@@ -5,15 +5,17 @@ import { loadConfig } from "./config.js";
 import { MesAgentApiClient } from "./clients/mes-agent-api.client.js";
 import { registerMesPrompts } from "./prompts/register-prompts.js";
 import { registerMesResources } from "./resources/register-resources.js";
-import { registerAgentTools } from "./tools/register-tools.js";
+import { registerAllAgentTools } from "./tools/register-tools.js";
 async function main() {
     const config = loadConfig();
     const client = new MesAgentApiClient(config);
     const server = new McpServer({
         name: "mes-mcp",
-        version: "0.1.0",
+        version: "0.2.0",
+    });
+    await registerAllAgentTools(server, client, {
+        registerDynamicTools: config.registerDynamicTools,
     });
-    registerAgentTools(server, client);
     registerMesResources(server, client);
     registerMesPrompts(server);
     await server.connect(new StdioServerTransport());

package/dist/prompts/register-prompts.js

@@ -15,8 +15,9 @@ export function registerMesPrompts(server) {
                     text: [
                         "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
                         "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
-                        "推荐流程：document_intake.parse -> customer.match / material.match -> sale_order.create -> sale_order.confirm -> production_plan.create_from_sale_order -> work_order.create_from_plan -> work_order.release。",
-                        "写入类动作默认先使用 confirm_required 或 preview；用户明确确认后再使用 commit，并传 idempotencyKey。",
+                        "默认先用 mes_action.list 或 mes://agent/actions 发现当前账号能做的页面业务动作，再用 mes_action.detail 查看字段，最后用 mes_action.execute 执行；不要依赖工具列表里必须存在 mes.<动作编码>。",
+                        "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、发货出库。",
+                        "写入类动作默认先使用 confirm_required 或 preview；preview 不写入，confirm_required 生成待确认记录，commit 只有凭证允许时才真实提交。",
                         context ? `当前上下文：${context}` : "",
                     ]
                         .filter(Boolean)

package/dist/resources/register-resources.js

@@ -1,21 +1,60 @@
 export function registerMesResources(server, client) {
-    server.registerResource("mes_agent_contracts", "mes://agent/contracts", {
-        title: "MES Agent Contracts",
-        description: "当前 AI 凭证允许调用的 MES Agent 合同列表。",
+    server.registerResource("mes_business_actions", "mes://agent/actions", {
+        title: "MES Business Actions",
+        description: "当前 AI 凭证和账号权限可调用的 MES 页面业务动作目录，来源于 mes-node 后端 Controller、权限和 DTO 元数据。",
         mimeType: "application/json",
     }, async (uri) => {
-        const contracts = await client.post("/integration/agent/contracts/list", {
-            page: 1,
-            pageSize: 100,
-        });
+        const actions = await client.listBusinessActions();
         return {
             contents: [
                 {
                     uri: uri.href,
                     mimeType: "application/json",
-                    text: JSON.stringify(contracts, null, 2),
+                    text: JSON.stringify({
+                        list: actions,
+                        total: actions.length,
+                        page: 1,
+                        pageSize: actions.length,
+                    }, null, 2),
                 },
             ],
         };
     });
+    server.registerResource("mes_agent_context", "mes://agent/context", {
+        title: "MES Agent Context",
+        description: "MES AI Agent 操作边界、标准链路和安全规则摘要，用于提示客户端按受控接口完成业务闭环。",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: [
+                    "# MES Agent Context",
+                    "",
+                    "MES MCP 只做协议适配，业务事实、权限、租户隔离、状态机、库存、质量、幂等和审计均由 mes-node 负责。",
+                    "",
+                    "## 工具使用顺序",
+                    "",
+                    "1. 使用 `mes_action.list` 或 `mes://agent/actions` 发现当前凭证和账号权限允许的动作。",
+                    "2. 使用 `mes_action.detail` 查看目标动作的路径、权限、DTO 名称和输入 schema。",
+                    "3. 只读查询使用 `mes_api.read` 调用普通业务只读 POST 接口。",
+                    "4. 写入、确认、下达、报工、质检、出入库等动作使用 `mes_action.execute` 或可选的 `mes.<动作编码>`。",
+                    "",
+                    "## 写入规则",
+                    "",
+                    "- `preview` 不写入业务数据。",
+                    "- `confirm_required` 生成待确认调用，不直接写入。",
+                    "- `commit` 只有凭证最高执行模式允许时才真实提交。",
+                    "- 写入类 `confirm_required` 和 `commit` 必须有幂等键；MCP 会为单次工具调用自动生成，跨重试批处理应显式传入同一个 `idempotencyKey`。",
+                    "",
+                    "## 禁止事项",
+                    "",
+                    "- 不猜客户、物料、BOM、工艺路线、仓库、批次、数量、价格等关键业务事实。",
+                    "- 不通过 `mes_api.read` 调用创建、更新、删除、确认、下达等写入接口。",
+                    "- 不绕过当前账号权限、公司隔离、状态机、库存规则、质量规则和审计。",
+                ].join("\n"),
+            },
+        ],
+    }));
 }

package/dist/tools/register-tools.js

@@ -1,5 +1,23 @@
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { AGENT_TOOL_SPECS } from "./agent-tools.js";
+const ExecutionModeSchema = z
+    .enum(["preview", "confirm_required", "commit"])
+    .optional();
+const DynamicActionSchema = z
+    .object({
+    executionMode: ExecutionModeSchema.describe("写入动作执行模式；只读动作固定按 preview 执行。"),
+    idempotencyKey: z
+        .string()
+        .min(1)
+        .max(160)
+        .optional()
+        .describe("写入动作 confirm_required 或 commit 时用于后端幂等；不传时 MCP 会为本次工具调用自动生成。"),
+    payload: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("MES 页面业务动作请求体；也可以直接把 DTO 字段放在顶层。"),
+})
+    .passthrough();
 function formatToolResult(result) {
     return {
         structuredContent: result && typeof result === "object" && !Array.isArray(result)
@@ -14,21 +32,6 @@ function formatToolResult(result) {
     };
 }
 export function registerAgentTools(server, client) {
-    for (const spec of AGENT_TOOL_SPECS) {
-        server.registerTool(spec.name, {
-            title: spec.title,
-            description: spec.description,
-            inputSchema: spec.schema,
-            annotations: {
-                readOnlyHint: spec.readOnlyHint ?? false,
-                destructiveHint: spec.destructiveHint ?? false,
-                idempotentHint: true,
-            },
-        }, async (args) => {
-            const result = await client.post(spec.path, args ?? {});
-            return formatToolResult(result);
-        });
-    }
     server.registerTool("mes_api.read", {
         title: "Read MES API",
         description: "按当前 MES 账号权限读取系统内业务信息。仅用于 list/detail/view/read/export/stats/options 等只读类 POST 接口；创建、更新、删除、确认、下达等写入动作必须使用专门的 Agent 工具。",
@@ -60,3 +63,159 @@ export function registerAgentTools(server, client) {
         return formatToolResult(result);
     });
 }
+function normalizeDynamicArgs(args) {
+    const parsed = DynamicActionSchema.parse(args ?? {});
+    const { executionMode, idempotencyKey, payload, ...rest } = parsed;
+    return {
+        executionMode,
+        idempotencyKey,
+        payload: payload ?? rest,
+    };
+}
+function buildIdempotencyKey(actionCode) {
+    const normalizedActionCode = actionCode.replace(/[^a-zA-Z0-9._-]+/g, "_");
+    return `mcp-${normalizedActionCode}-${Date.now().toString(36)}-${randomUUID()}`.slice(0, 160);
+}
+function shouldEnsureIdempotencyKey(action, executionMode) {
+    return Boolean(action?.isWrite && executionMode !== "preview");
+}
+function actionDescription(action) {
+    const permissionText = action.permissions.length > 0
+        ? `需要权限：${action.permissions.join("、")}。`
+        : "按后端业务方法自行校验权限。";
+    const modeText = action.isWrite
+        ? "写入动作，confirm_required 会生成待确认单，commit 会真实写入 MES；两种模式可显式提供 idempotencyKey，不传时 MCP 会为本次工具调用自动生成，preview 不写入。"
+        : "只读动作，固定按 preview 执行。";
+    return [
+        action.description,
+        `页面接口：POST ${action.path}。`,
+        action.inputDto ? `请求 DTO：${action.inputDto}。` : undefined,
+        permissionText,
+        modeText,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function registerGenericActionTools(server, client) {
+    server.registerTool("mes_action.list", {
+        title: "List MES business actions",
+        description: "动态查询当前 AI 凭证和当前账号权限允许调用的 MES 页面业务动作。新业务页面只要后端有权限和 DTO 元数据，就会出现在这里。",
+        inputSchema: z
+            .object({
+            page: z.number().int().positive().optional(),
+            pageSize: z.number().int().positive().max(100).optional(),
+            keyword: z.string().optional(),
+            module: z.string().optional(),
+            resource: z.string().optional(),
+            operation: z.string().optional(),
+            write: z.boolean().optional(),
+        })
+            .passthrough(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        const result = await client.post("/integration/agent/actions/list", args ?? {});
+        return formatToolResult(result);
+    });
+    server.registerTool("mes_action.detail", {
+        title: "Get MES business action detail",
+        description: "查询单个 MES 页面业务动作的路径、权限、DTO 名称和后端提供的输入 schema。",
+        inputSchema: z.object({
+            actionCode: z.string().min(1),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        const result = await client.post("/integration/agent/actions/detail", args ?? {});
+        return formatToolResult(result);
+    });
+    server.registerTool("mes_action.execute", {
+        title: "Execute MES business action",
+        description: "执行一个由 mes_action.list 发现的 MES 页面业务动作。后端复用页面 Controller、DTO、权限、租户、状态机和调用日志。",
+        inputSchema: z
+            .object({
+            actionCode: z.string().min(1),
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: z.string().min(1).max(160).optional(),
+            payload: z.record(z.string(), z.unknown()).optional(),
+        })
+            .passthrough(),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        const parsed = z
+            .object({
+            actionCode: z.string().min(1),
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: z.string().min(1).max(160).optional(),
+            payload: z.record(z.string(), z.unknown()).optional(),
+        })
+            .passthrough()
+            .parse(args ?? {});
+        const { actionCode, executionMode, idempotencyKey, payload, ...rest } = parsed;
+        const action = await client.getBusinessAction(actionCode);
+        const result = await client.post("/integration/agent/actions/execute", {
+            actionCode,
+            executionMode,
+            idempotencyKey: idempotencyKey ??
+                (shouldEnsureIdempotencyKey(action, executionMode)
+                    ? buildIdempotencyKey(actionCode)
+                    : undefined),
+            payload: payload ?? rest,
+        });
+        return formatToolResult(result);
+    });
+}
+async function registerDynamicBusinessActionTools(server, client) {
+    const actions = await client.listBusinessActions();
+    const registeredNames = new Set();
+    for (const action of actions) {
+        const toolName = `mes.${action.actionCode}`;
+        if (registeredNames.has(toolName))
+            continue;
+        registeredNames.add(toolName);
+        server.registerTool(toolName, {
+            title: action.title,
+            description: actionDescription(action),
+            inputSchema: DynamicActionSchema,
+            annotations: {
+                readOnlyHint: !action.isWrite,
+                destructiveHint: action.isWrite,
+                idempotentHint: true,
+            },
+        }, async (args) => {
+            const normalized = normalizeDynamicArgs(args);
+            const result = await client.post("/integration/agent/actions/execute", {
+                actionCode: action.actionCode,
+                ...normalized,
+                idempotencyKey: normalized.idempotencyKey ??
+                    (shouldEnsureIdempotencyKey(action, normalized.executionMode)
+                        ? buildIdempotencyKey(action.actionCode)
+                        : undefined),
+            });
+            return formatToolResult(result);
+        });
+    }
+}
+export async function registerAllAgentTools(server, client, options = {}) {
+    registerAgentTools(server, client);
+    registerGenericActionTools(server, client);
+    if (!options.registerDynamicTools)
+        return;
+    try {
+        await registerDynamicBusinessActionTools(server, client);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`MES dynamic business actions unavailable: ${message}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mes-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "MES MCP adapter for Marvis and AI agents",
   "license": "UNLICENSED",
@@ -14,7 +14,7 @@
     ".env.example"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js"

package/dist/tools/agent-tools.js

@@ -1,209 +0,0 @@
-import { z } from "zod";
-const ExecutionModeSchema = z
-    .enum(["preview", "confirm_required", "commit"])
-    .optional();
-const IdempotencySchema = z.string().min(1).max(160).optional();
-const QuerySchema = z
-    .object({
-    page: z.number().int().positive().optional(),
-    pageSize: z.number().int().positive().max(100).optional(),
-    keyword: z.string().optional(),
-})
-    .passthrough();
-export const AGENT_TOOL_SPECS = [
-    {
-        name: "document_intake.parse",
-        title: "Parse order document",
-        description: "接收 Marvis/上游 AI 从图片、PDF、Excel、文本中识别出的订单资料，返回可确认的销售订单草稿。",
-        path: "/integration/agent/document-intake/parse",
-        readOnlyHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            rawText: z.string().optional(),
-            imageUrl: z.string().url().optional(),
-            fileUrl: z.string().url().optional(),
-            extractedOrder: z
-                .object({
-                orderNo: z.string().optional(),
-                customerId: z.string().uuid().optional(),
-                customerName: z.string().optional(),
-                deliveryDate: z.string().optional(),
-                remarks: z.string().optional(),
-                items: z
-                    .array(z
-                    .object({
-                    materialId: z.string().uuid().optional(),
-                    materialCode: z.string().optional(),
-                    materialName: z.string().optional(),
-                    quantity: z.number().positive().optional(),
-                    unitPrice: z.number().min(0).optional(),
-                    remarks: z.string().optional(),
-                })
-                    .passthrough())
-                    .optional(),
-            })
-                .passthrough()
-                .optional(),
-            sourceMeta: z.record(z.string(), z.unknown()).optional(),
-        })
-            .passthrough(),
-    },
-    {
-        name: "customer.match",
-        title: "Match customer",
-        description: "按当前 MES 账号权限匹配启用中的客户主数据；创建销售单前用于确认客户 ID，避免 AI 直接猜测客户。",
-        path: "/integration/agent/customer/match",
-        readOnlyHint: true,
-        schema: QuerySchema.extend({
-            customerCode: z.string().optional(),
-            name: z.string().optional(),
-            contactName: z.string().optional(),
-            contactPhone: z.string().optional(),
-        }).passthrough(),
-    },
-    {
-        name: "material.match",
-        title: "Match material",
-        description: "按当前 MES 账号权限匹配启用中的物料主数据；创建销售单前用于确认物料 ID，避免用图片识别文本直接写入。",
-        path: "/integration/agent/material/match",
-        readOnlyHint: true,
-        schema: QuerySchema.extend({
-            code: z.string().optional(),
-            name: z.string().optional(),
-            spec: z.string().optional(),
-            barcode: z.string().optional(),
-        }).passthrough(),
-    },
-    {
-        name: "sale_order.create",
-        title: "Create sale order",
-        description: "按当前 MES 账号权限创建销售订单；commit 才写入，preview/confirm_required 只返回待确认内容。",
-        path: "/integration/agent/sale-order/create",
-        destructiveHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            orderNo: z.string().optional(),
-            customerId: z.string().uuid().optional(),
-            salesRepId: z.string().uuid().optional(),
-            deliveryDate: z.string().optional(),
-            paymentTerms: z.string().optional(),
-            remarks: z.string().optional(),
-            items: z.array(z
-                .object({
-                materialId: z.string().uuid(),
-                quantity: z.number().positive(),
-                unitPrice: z.number().min(0).optional(),
-                customerMaterialCode: z.string().optional(),
-                customerMaterialName: z.string().optional(),
-                customerMaterialSpec: z.string().optional(),
-                remarks: z.string().optional(),
-            })
-                .passthrough()),
-        })
-            .passthrough(),
-    },
-    {
-        name: "sale_order.confirm",
-        title: "Confirm sale order",
-        description: "确认销售订单，复用 MES 的审批门控、状态规则和明细校验；销售订单转生产计划前必须先确认。",
-        path: "/integration/agent/sale-order/confirm",
-        destructiveHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            id: z.string().uuid(),
-        })
-            .passthrough(),
-    },
-    {
-        name: "production_plan.create_from_sale_order",
-        title: "Create production plan from sale order",
-        description: "将已确认销售订单转为生产计划，复用 MES 原有数量、BOM 和工艺校验。",
-        path: "/integration/agent/production-plan/create-from-sale-order",
-        destructiveHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            saleOrderId: z.string().uuid(),
-            planStartDate: z.string(),
-            planEndDate: z.string(),
-            priority: z.number().int().min(1).max(10).optional(),
-            description: z.string().optional(),
-            items: z.array(z
-                .object({
-                saleOrderItemId: z.string().uuid(),
-                requiredQty: z.number().positive().optional(),
-                plannedLossRate: z.number().min(0).optional(),
-                plannedQty: z.number().positive().optional(),
-                bomHeaderId: z.string().uuid().optional(),
-                routeId: z.string().uuid().optional(),
-            })
-                .passthrough()),
-        })
-            .passthrough(),
-    },
-    {
-        name: "work_order.create_from_plan",
-        title: "Create work order from production plan",
-        description: "确认生产计划并自动创建工单，复用 MES 的 BOM 展开和工艺工序生成规则。",
-        path: "/integration/agent/work-order/create-from-plan",
-        destructiveHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            planId: z.string().uuid(),
-            routeId: z.string().uuid().optional(),
-            bomHeaderId: z.string().uuid().optional(),
-            assigneeId: z.string().uuid().optional(),
-            receiptWarehouseId: z.string().uuid().optional(),
-        })
-            .passthrough(),
-    },
-    {
-        name: "work_order.release",
-        title: "Release work order",
-        description: "下达工单，复用 MES 状态机、审批门控、物料需求展开和事件推送。",
-        path: "/integration/agent/work-order/release",
-        destructiveHint: true,
-        schema: z
-            .object({
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: IdempotencySchema,
-            id: z.string().uuid(),
-            assigneeId: z.string().uuid().optional(),
-            receiptWarehouseId: z.string().uuid().optional(),
-        })
-            .passthrough(),
-    },
-    {
-        name: "sale_order.query",
-        title: "Query sale orders",
-        description: "按当前 MES 账号权限查询销售订单列表。",
-        path: "/integration/agent/sale-order/query",
-        readOnlyHint: true,
-        schema: QuerySchema,
-    },
-    {
-        name: "work_order.query",
-        title: "Query work orders",
-        description: "按当前 MES 账号权限查询工单列表。",
-        path: "/integration/agent/work-order/query",
-        readOnlyHint: true,
-        schema: QuerySchema,
-    },
-    {
-        name: "inventory.query",
-        title: "Query inventory",
-        description: "按当前 MES 账号权限查询库存现有量和可用量。",
-        path: "/integration/agent/inventory/query",
-        readOnlyHint: true,
-        schema: QuerySchema,
-    },
-];