@axiom-lattice/examples-deep_research 1.0.93 → 1.0.94

package/src/agents/sap_b1/tools.ts

@@ -18,6 +18,28 @@ interface ApiEntry {
   fields: string[];
 }
 
+// ============================================================
+// 支持 $expand 的文档类实体
+// ============================================================
+
+const EXPAND_FIELDS: Record<string, string[]> = {
+  "DocumentLines": [
+    "LineNum", "ItemCode", "ItemDescription", "Quantity", "UnitPrice",
+    "WarehouseCode", "Total", "Currency", "TaxCode", "PriceAfterVAT",
+    "UoMEntry", "UoMCode",
+  ],
+  "DocumentAdditionalExpenses": [
+    "LineNum", "ExpenseCode", "LineTotal", "TaxCode", "VatGroup",
+  ],
+};
+
+const ENTITIES_WITH_LINES = new Set([
+  "Orders", "DeliveryNotes", "Invoices", "Quotations", "CreditNotes",
+  "Returns", "Drafts", "PurchaseOrders", "PurchaseDeliveryNotes",
+  "PurchaseInvoices", "PurchaseReturns", "PurchaseQuotations",
+  "DownPayments", "InventoryGenEntries", "InventoryGenExits",
+]);
+
 const API_LIST: ApiEntry[] = [
   // ========== Business Partner ==========
   {
@@ -30,9 +52,11 @@ const API_LIST: ApiEntry[] = [
     fields: [
       "CardCode", "CardName", "CardType", "GroupCode", "Currency",
       "Phone1", "Phone2", "EmailAddress", "Address", "City", "Country",
-      "SalesPersonCode", "PriceListNum", "CreditLimit", "Balance",
+      "SalesPersonCode", "PriceListNum", "CreditLimit",
+      "CurrentAccountBalance", "OpenOrdersBalance", "OpenDeliveryNotesBalance",
       "PayTermsGrpCode", "VatGroup", "VatLiable", "FederalTaxID",
-      "Valid", "Frozen", "CompanyPrivate", "CreateDate", "UpdateDate",
+      "Valid", "Frozen", "CompanyPrivate", "CreateDate", "CreateTime", "UpdateDate", "UpdateTime",
+      "BPAddresses", "ContactEmployees",
     ],
   },
   {
@@ -70,6 +94,7 @@ const API_LIST: ApiEntry[] = [
       "ManageSerialNumbers", "ManageBatchNumbers",
       "SalesVATGroup", "PurchaseVATGroup",
       "Valid", "Frozen", "CreateDate", "UpdateDate",
+      "ItemPrices", "ItemWarehouseInfoCollection",
     ],
   },
   {
@@ -120,6 +145,7 @@ const API_LIST: ApiEntry[] = [
       "Comments", "Reference1", "Reference2", "NumAtCard",
       "VatSum", "RoundDif", "DiscountPercent",
       "PaymentGroupCode", "Project",
+      "DocumentLines",
     ],
   },
   {
@@ -134,6 +160,7 @@ const API_LIST: ApiEntry[] = [
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "SalesPersonCode", "Confirmed", "Cancelled", "DocumentStatus",
       "Comments", "NumAtCard",
+      "DocumentLines",
     ],
   },
   {
@@ -148,6 +175,7 @@ const API_LIST: ApiEntry[] = [
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "SalesPersonCode", "Confirmed", "Cancelled", "DocumentStatus",
       "Comments", "NumAtCard", "VatSum",
+      "DocumentLines",
     ],
   },
   {
@@ -161,6 +189,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate", "DocDueDate",
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "SalesPersonCode", "Comments", "DocumentStatus",
+      "DocumentLines",
     ],
   },
   {
@@ -174,6 +203,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "Comments",
+      "DocumentLines",
     ],
   },
   {
@@ -187,6 +217,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "Comments",
+      "DocumentLines",
     ],
   },
   {
@@ -200,6 +231,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "DownPaymentType", "DownPaymentAmount",
+      "DocumentLines",
     ],
   },
   {
@@ -231,6 +263,7 @@ const API_LIST: ApiEntry[] = [
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "SalesPersonCode", "Confirmed", "Cancelled", "DocumentStatus",
       "Comments", "NumAtCard",
+      "DocumentLines",
     ],
   },
   {
@@ -243,6 +276,7 @@ const API_LIST: ApiEntry[] = [
     fields: [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "Comments",
+      "DocumentLines",
     ],
   },
   {
@@ -256,6 +290,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate", "DocDueDate",
       "CardCode", "CardName", "DocTotal", "DocCurrency",
       "Comments",
+      "DocumentLines",
     ],
   },
   {
@@ -268,6 +303,7 @@ const API_LIST: ApiEntry[] = [
     fields: [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "Comments",
+      "DocumentLines",
     ],
   },
   {
@@ -280,6 +316,7 @@ const API_LIST: ApiEntry[] = [
     fields: [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "CardCode", "CardName", "DocTotal", "Comments",
+      "DocumentLines",
     ],
   },
 
@@ -295,6 +332,7 @@ const API_LIST: ApiEntry[] = [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "Comments", "JournalMemo", "Reference1", "Reference2",
       "WareHouseUpdateType",
+      "DocumentLines",
     ],
   },
   {
@@ -307,6 +345,7 @@ const API_LIST: ApiEntry[] = [
     fields: [
       "DocEntry", "DocNum", "DocType", "DocDate",
       "Comments", "JournalMemo", "Reference1", "Reference2",
+      "DocumentLines",
     ],
   },
   {
@@ -573,20 +612,51 @@ const API_LIST: ApiEntry[] = [
 // Tool 1: sap_api_search
 // ============================================================
 
+function mapResult(e: ApiEntry): Record<string, unknown> {
+  const r: Record<string, unknown> = {
+    name: e.name,
+    kind: e.kind,
+    domain: e.domain,
+    description: e.description,
+    primaryKey: e.primaryKey || null,
+    fields: e.fields,
+    readySelect: e.fields.length > 0 ? `$select=${e.fields.join(",")}` : undefined,
+    hint:
+      e.kind === "EntitySet"
+        ? `${e.name} — ${e.description}。主键: ${e.primaryKey}。调用 sap_api_call 进行 CRUD 操作。`
+        : `${e.name} — ${e.description}。调用 sap_api_call 执行此方法。`,
+  };
+  if (ENTITIES_WITH_LINES.has(e.name)) {
+    r.expand = ["DocumentLines", "DocumentAdditionalExpenses"];
+    r.lineFields = ["LineNum", "ItemCode", "ItemDescription", "Quantity", "UnitPrice", "Price", "WarehouseCode", "UoMEntry", "UoMCode", "VatGroup", "Currency", "TaxCode", "PriceAfterVAT"];
+  }
+  if (e.name === "Items") {
+    r.expand = ["ItemPrices", "ItemWarehouseInfoCollection"];
+  }
+  if (e.name === "BusinessPartners") {
+    r.expand = ["BPAddresses", "ContactEmployees"];
+  }
+  return r;
+}
+
 registerToolLattice(
   "sap_api_search",
   {
     name: "sap_api_search",
     description:
-      "搜索 SAP B1 Service Layer API 接口。覆盖业务伙伴(BP)、物料(Item)、销售/采购订单(Document/Order)、" +
-      "库存(Inventory/Warehouse) 四大领域。返回接口名称、主键、常用字段列表及描述。",
+      "搜索 SAP B1 Service Layer API 接口元数据，覆盖 BP/物料/订单/库存四大领域。" +
+      "返回接口名、主键、字段列表、可选 expand 导航。" +
+      "可用 discover 模式发现关联接口（如搜 SalesPerson 也能找到 SalesPersons API）。" +
+      "搜索结果中的 readySelect 可直接复制到 $select。",
     needUserApprove: false,
     schema: z.object({
       query: z
         .string()
+        .optional()
         .describe(
-          "搜索关键词。可以是 API 名称（如 'BusinessPartners', 'Orders', 'Items', 'PurchaseOrders'）" +
-            "或业务描述（如 '客户', '订单', '物料', '库存', '采购', '仓库'）"
+          "搜索关键词（可选，不传则返回全部接口）。" +
+            "API 名称如 'BusinessPartners', 'Orders', 'Items', 'PurchaseOrders'，" +
+            "或中文描述如 '客户', '订单', '物料', '库存', '采购', '仓库'"
         ),
       domain: z
         .string()
@@ -594,14 +664,15 @@ registerToolLattice(
         .describe(
           "按领域过滤: 'BusinessPartner'(BP), 'Item / Product'(物料), 'Document'(订单/发票), 'Inventory / Warehouse'(库存/仓库)"
         ),
-      maxResults: z.number().optional().default(10).describe("最大返回条数"),
+      maxResults: z.number().optional().default(20).describe("最大返回条数"),
     }),
   },
   async (input) => {
-    const q = input.query.toLowerCase();
-    const max = input.maxResults ?? 10;
+    const q = input.query?.toLowerCase();
+    const max = input.maxResults ?? 20;
+
+    const hasQuery = q && q.trim().length > 0;
 
-    // 中文关键词映射到领域
     const domainHints: Record<string, string> = {
       "客户": "BusinessPartner",
       "供应商": "BusinessPartner",
@@ -617,6 +688,8 @@ registerToolLattice(
       "交货": "Document",
       "报价": "Document",
       "草稿": "Document",
+      "draft": "Document",
+      "暂存": "Document",
       "库存": "Inventory / Warehouse",
       "仓库": "Inventory / Warehouse",
       "库位": "Inventory / Warehouse",
@@ -633,13 +706,29 @@ registerToolLattice(
       "到岸": "Document",
     };
 
-    const hintedDomain = domainHints[q] || undefined;
+    const hintedDomain = q ? (domainHints[q] || undefined) : undefined;
     const effectiveDomain = input.domain || hintedDomain;
 
-    const scored = API_LIST.filter((e) => {
+    const filtered = API_LIST.filter((e) => {
       if (effectiveDomain && e.domain !== effectiveDomain) return false;
       return true;
-    }).map((e) => {
+    });
+
+    if (!q) {
+      const top = filtered.slice(0, max);
+      const domainCounts: Record<string, number> = {};
+      for (const e of top) domainCounts[e.domain] = (domainCounts[e.domain] || 0) + 1;
+      return {
+        query: input.query || null,
+        domainFilter: effectiveDomain || null,
+        totalMatches: filtered.length,
+        domainsFound: domainCounts,
+        results: top.map(mapResult),
+        suggestion: undefined,
+      };
+    }
+
+    const scored = filtered.map((e) => {
       let score = 0;
       const nameLo = e.name.toLowerCase();
       const descLo = e.description.toLowerCase();
@@ -668,22 +757,11 @@ registerToolLattice(
     for (const e of top) domainCounts[e.domain] = (domainCounts[e.domain] || 0) + 1;
 
     return {
-      query: input.query,
+      query: input.query!,
       domainFilter: effectiveDomain || null,
       totalMatches: scored.filter((e) => e.score > 0).length,
       domainsFound: domainCounts,
-      results: top.map((e) => ({
-        name: e.name,
-        kind: e.kind,
-        domain: e.domain,
-        description: e.description,
-        primaryKey: e.primaryKey || null,
-        fields: e.fields,
-        hint:
-          e.kind === "EntitySet"
-            ? `${e.name} — ${e.description}。主键: ${e.primaryKey}。调用 sap_api_call 进行 CRUD 操作。`
-            : `${e.name} — ${e.description}。调用 sap_api_call 执行此方法。`,
-      })),
+      results: top.map(mapResult),
       suggestion:
         top.length === 0
           ? `未找到匹配 "${input.query}" 的接口。可用领域: BusinessPartner(客户/供应商), Item / Product(物料), Document(订单/发票), Inventory / Warehouse(库存/仓库)。尝试用英文名称搜索。`
@@ -705,9 +783,24 @@ registerToolLattice(
   {
     name: "sap_api_call",
     description:
-      "执行对 SAP B1 Service Layer 的 OData API 调用。直接发起 HTTP 请求并返回响应数据。" +
-      `当前 Base URL: ${BASE_URL}。` +
-      "GET 请求通常无需认证，POST/PATCH/DELETE 需设置环境变量 SAP_B1SESSION。",
+      "执行 SAP B1 Service Layer 的 OData API 查询/创建/更新/删除。" +
+      `Base: ${BASE_URL}。` +
+      "⚠️ 先确认是否已通过 sap_api_search 查过字段列表，勿凭记忆编字段名。\n" +
+      "⚠️ 草稿/draft/暂存 → 用 Drafts 接口，不是 Orders/Invoices 等正式单据。" +
+      "Drafts 通过 DocObjectCode 区分单据类型(17=订单,13=发票,16=交货单,23=采购订单)。\n" +
+      "$filter 操作符: eq/ne/gt/lt/ge/le/contains(f,'v')/startswith(f,'v')/endswith(f,'v')，多条件用 and/or。" +
+      "字符串值必须单引号包裹。$orderby=Field desc 排序。\n\n" +
+      "⚠️ SAP B1 实战经验:\n" +
+      "1. 不要用 $expand！$expand 极易触发 400/500。改用 $select 包含嵌套字段，如 $select=DocEntry,DocNum,DocumentLines，\n" +
+      "   DocumentLines 会自动作为嵌套 JSON 返回。ItemPrices、BPAddresses 等同理。\n" +
+      "2. 不要用主键路径 /Orders('1173')，易 500。用 $filter=DocEntry eq 1173 代替。\n" +
+      "3. 查单条记录时优先 $filter，而非传 id 参数。\n" +
+      "400 多为特殊字符未编码(引号用 %27)；500 多为字段不存在或用错了 $expand；无结果则放宽 filter。\n" +
+      "POST 创建: sap_api_search 返回的 lineFields 是 DocumentLines 子字段。" +
+      "body 必含 DocObjectCode(DocType)、CardCode、DocDate；DocumentLines 为数组，每项必含 ItemCode、Quantity。" +
+      "PATCH 只传变更字段；DELETE 需传 id。\n" +
+      "GET 自动注入 $select+$top=20，手动传入可覆盖。嵌套集合(DocumentLines等)自动裁剪只保留常用字段，防 token 爆炸。" +
+      "认证需 SAP_B1SESSION 环境变量。",
     needUserApprove: false,
     schema: z.object({
       entitySet: z
@@ -722,18 +815,18 @@ registerToolLattice(
         .string()
         .optional()
         .describe(
-          "OData 查询参数（不含 `?` 前缀）。常用: " +
-            "$top=10, $skip=20, " +
-            "$select=CardCode,CardName, " +
-            "$filter=contains(CardName,'清华'), " +
-            "$orderby=DocDate desc, " +
-            "$expand=DocumentLines"
+          "OData 查询参数（不含 `?` 前缀）。" +
+            "常用: $top=10, $select=CardCode,CardName, " +
+            "$filter=CardName eq 'xxx' or contains(CardName,'xxx'), " +
+            "$orderby=DocDate desc, $expand=DocumentLines。字符串值用单引号。" +
+            "sap_api_search 返回的 readySelect 可直接复制到 $select。"
         ),
       body: z.record(z.unknown()).optional().describe("POST/PATCH 时的 JSON 请求体"),
     }),
   },
   async (input) => {
-    const url = buildUrl(input.entitySet, input.method, input.id, input.queryOptions);
+    const queryOptions = applyDefaultSelect(input.entitySet, input.method, input.id, input.queryOptions);
+    const url = buildUrl(input.entitySet, input.method, input.id, queryOptions);
     const method = input.method;
 
     const headers: Record<string, string> = {
@@ -749,7 +842,8 @@ registerToolLattice(
 
     try {
       const res = await fetch(url, fetchOptions);
-      const text = await res.text();
+      const buffer = await res.arrayBuffer();
+      const text = new TextDecoder("utf-8", { fatal: false }).decode(buffer);
 
       let data: unknown;
       try {
@@ -758,6 +852,8 @@ registerToolLattice(
         data = text;
       }
 
+      cleanODataNoise(data);
+
       const result: Record<string, unknown> = {
         ok: res.ok,
         status: res.status,
@@ -792,6 +888,74 @@ registerToolLattice(
 // Helpers
 // ============================================================
 
+function applyDefaultSelect(entitySet: string, method: string, id?: string, queryOptions?: string): string | undefined {
+  if (method !== "GET") return queryOptions;
+
+  const parts: string[] = [];
+
+  if (!id && (!queryOptions || !/\$top\s*=/.test(queryOptions))) {
+    parts.push("$top=20");
+  }
+
+  if (!queryOptions || !/\$select\s*=/.test(queryOptions)) {
+    const entry = API_LIST.find(
+      (e) => e.kind === "EntitySet" && e.name === entitySet
+    );
+    if (entry && entry.fields.length > 0) {
+      parts.push(`$select=${entry.fields.join(",")}`);
+    }
+  }
+
+  if (queryOptions) {
+    parts.push(queryOptions);
+  }
+
+  return parts.length > 0 ? parts.join("&").replace(/'/g, "%27") : undefined;
+}
+
+function cleanODataNoise(data: unknown): void {
+  if (!data || typeof data !== "object") return;
+  if (Array.isArray(data)) {
+    for (const item of data) cleanODataNoise(item);
+    return;
+  }
+  const obj = data as Record<string, unknown>;
+
+  delete obj["odata.metadata"];
+  delete obj["odata.etag"];
+  delete obj["odata.nextLink"];
+
+  if (Array.isArray(obj.value)) {
+    for (const record of obj.value) {
+      if (record && typeof record === "object") {
+        trimNestedCollections(record as Record<string, unknown>);
+        delete (record as Record<string, unknown>)["odata.etag"];
+      }
+    }
+  }
+
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === "object") cleanODataNoise(v);
+  }
+}
+
+function trimNestedCollections(obj: Record<string, unknown>): void {
+  for (const [key, val] of Object.entries(obj)) {
+    if (Array.isArray(val) && EXPAND_FIELDS[key]) {
+      const keep = new Set(EXPAND_FIELDS[key]);
+      for (const item of val) {
+        if (item && typeof item === "object") {
+          const record = item as Record<string, unknown>;
+          for (const k of Object.keys(record)) {
+            if (!keep.has(k)) delete record[k];
+          }
+          cleanODataNoise(item);
+        }
+      }
+    }
+  }
+}
+
 function buildUrl(
   entitySet: string,
   method: string,