agentlink-sdk 1.0.7 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # AgentLink SDK
 
-AgentLink 客户端 SDK，用于跨域数据同步，通过 URL hash 传递数据，支持 Token 验证和白名单机制。
+AgentLink 客户端 SDK，用于跨域数据同步，通过 URL hash 传递数据，支持 Token 验证和白名单机制。同时提供 Base64 隔离、Schema 推断等工具函数，便于与 LLM 流程集成。
 
 ## 安装
 
@@ -278,6 +278,63 @@ interface WhitelistResponse {
 }
 ```
 
+## 工具函数（LLM 相关）
+
+以下函数可从 `agentlink-sdk` 直接导入，用于在发送给 LLM 前处理数据（如替换 base64、生成精简 schema）。
+
+### inferSchema
+
+从原始数据推断出体积受控的 schema（先替换 base64 为占位符，再按深度/长度/项数截断），便于作为 LLM 输入。
+
+```typescript
+import { inferSchema, type InferredSchema, type InferSchemaOptions } from 'agentlink-sdk';
+
+const schema = inferSchema(rawData, {
+  maxDepth: 5,           // 最大递归深度，默认 5
+  maxStringLength: 500,   // 单段字符串最大字符数，默认 500
+  maxTotalTextLength: 3000,  // 所有字符串总字符数上限，默认 3000
+  maxArrayItems: 5,       // 数组最多保留项数，默认 5
+  maxKeys: 20,            // 对象每层最多键数，默认 20
+});
+```
+
+### extractAndReplaceBase64 / restoreBase64
+
+将数据中的 base64 图片替换为占位符（如 `_IMG_0_`），或根据映射表恢复。
+
+```typescript
+import { extractAndReplaceBase64, restoreBase64 } from 'agentlink-sdk';
+
+const { processedData, replacements } = extractAndReplaceBase64(rawData);
+// 将 processedData 发给 LLM，replacements 用于后续恢复
+
+const restored = restoreBase64(processedData, replacements);
+```
+
+### extractImages
+
+从数据中递归提取所有 base64 图片（data URL），去重后返回数组。
+
+```typescript
+import { extractImages } from 'agentlink-sdk';
+
+const images = extractImages(rawData);
+// 可与 inferSchema 配合：先发 schema 给 LLM，再在结果中回填 images
+```
+
+## 开发与测试
+
+本包使用 [Vitest](https://vitest.dev/) 做单元测试。
+
+| 命令 | 说明 |
+|------|------|
+| `npm run test` | 以 watch 模式运行单元测试 |
+| `npm run test:run` | 单次运行全部单元测试 |
+| `npm run test:llm-schema` | 运行 Schema + LLM 集成测试（需配置 `AGENTLINK_SERVER_URL` 或 `LLM_API_URL` + `LLM_API_KEY`） |
+
+- **单元测试**：覆盖 `base64`、`schema`、`compression`、`url` 等工具，无需网络，可直接执行 `npm run test:run`。
+- **LLM Schema 测试**：脚本位于 `scripts/test-llm-schema.ts`，会调用真实 LLM 验证「inferSchema + 回填 images」的端到端流程，适合手动或 CI 可选执行。
+
 ## 特性
 
 - ✅ **跨域数据同步**: 通过 URL hash 实现跨域数据传输
@@ -285,6 +342,8 @@ interface WhitelistResponse {
 - ✅ **白名单机制**: 支持域名白名单验证
 - ✅ **数据压缩**: 自动压缩大型数据，优化 URL 长度
 - ✅ **缓存优化**: Token 和白名单验证结果缓存，减少服务器请求
+- ✅ **LLM 工具**: `inferSchema`、`extractAndReplaceBase64`、`restoreBase64`、`extractImages` 便于与 LLM 流程集成
+- ✅ **自动化测试**: Vitest 单元测试（base64 / schema / compression / url），可选 LLM Schema 集成测试
 - ✅ **TypeScript 支持**: 完整的 TypeScript 类型定义
 - ✅ **窗口复用**: 支持复用窗口，避免频繁打开新窗口
 
@@ -376,5 +435,7 @@ MIT
 ## 相关链接
 
 - [示例文件](./example.html)
+- [单元测试](src/utils/)（`*.test.ts`）
+- [LLM Schema 集成测试脚本](scripts/test-llm-schema.ts)
 - [GitHub 仓库](https://github.com/your-org/AgentLink)
 

package/dist/index.d.mts

@@ -120,4 +120,59 @@ declare function verifyWhitelist(serverUrl: string, origin?: string): Promise<bo
  */
 declare function fetchWhitelistInfo(serverUrl: string, includeAll?: boolean): Promise<any>;
 
-export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };
+/**
+ * 自动遍历 rawData 推断出体积受控的 schema，供 LLM 使用
+ */
+/** 推断出的 schema：与 rawData 同构但被截断的树（字符串截断、base64 占位符、数组/对象可带截断标记） */
+type InferredSchema = string | number | boolean | null | {
+    _truncated?: boolean;
+    _length?: number;
+    _depth?: number;
+    _keysTotal?: number;
+    [key: string]: InferredSchema | number | boolean | undefined;
+} | InferredSchema[];
+interface InferSchemaOptions {
+    /** 最大递归深度，默认 5 */
+    maxDepth?: number;
+    /** 单段字符串最大字符数，默认 500 */
+    maxStringLength?: number;
+    /** 所有字符串总字符数上限，默认 3000 */
+    maxTotalTextLength?: number;
+    /** 数组最多保留项数，默认 5 */
+    maxArrayItems?: number;
+    /** 对象每层最多键数，默认 20 */
+    maxKeys?: number;
+}
+/**
+ * 从 rawData 推断出体积受控的 schema：先替换 base64，再按深度/长度/项数递归截断
+ */
+declare function inferSchema(rawData: any, options?: InferSchemaOptions): InferredSchema;
+
+/**
+ * Base64 数据隔离和替换工具
+ * 用于在 LLM 处理前替换 base64 图片数据，减少输入大小
+ */
+/**
+ * 提取并替换 base64 数据
+ * @param data 原始数据（可以是对象、数组、字符串等）
+ * @returns 处理后的数据和替换映射表
+ */
+declare function extractAndReplaceBase64(data: any): {
+    processedData: any;
+    replacements: Map<string, string>;
+};
+/**
+ * 恢复 base64 数据
+ * @param data 包含占位符的数据
+ * @param replacements 替换映射表
+ * @returns 恢复后的数据
+ */
+declare function restoreBase64(data: any, replacements: Map<string, string>): any;
+/**
+ * 从数据中提取所有 base64 图片
+ * @param data 原始数据
+ * @returns 图片数组（base64 data URL 格式）
+ */
+declare function extractImages(data: any): string[];
+
+export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type InferSchemaOptions, type InferredSchema, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, extractAndReplaceBase64, extractImages, fetchWhitelistInfo, inferSchema, restoreBase64, uint8ArrayToBase64, verifyWhitelist };

package/dist/index.d.ts

@@ -120,4 +120,59 @@ declare function verifyWhitelist(serverUrl: string, origin?: string): Promise<bo
  */
 declare function fetchWhitelistInfo(serverUrl: string, includeAll?: boolean): Promise<any>;
 
-export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };
+/**
+ * 自动遍历 rawData 推断出体积受控的 schema，供 LLM 使用
+ */
+/** 推断出的 schema：与 rawData 同构但被截断的树（字符串截断、base64 占位符、数组/对象可带截断标记） */
+type InferredSchema = string | number | boolean | null | {
+    _truncated?: boolean;
+    _length?: number;
+    _depth?: number;
+    _keysTotal?: number;
+    [key: string]: InferredSchema | number | boolean | undefined;
+} | InferredSchema[];
+interface InferSchemaOptions {
+    /** 最大递归深度，默认 5 */
+    maxDepth?: number;
+    /** 单段字符串最大字符数，默认 500 */
+    maxStringLength?: number;
+    /** 所有字符串总字符数上限，默认 3000 */
+    maxTotalTextLength?: number;
+    /** 数组最多保留项数，默认 5 */
+    maxArrayItems?: number;
+    /** 对象每层最多键数，默认 20 */
+    maxKeys?: number;
+}
+/**
+ * 从 rawData 推断出体积受控的 schema：先替换 base64，再按深度/长度/项数递归截断
+ */
+declare function inferSchema(rawData: any, options?: InferSchemaOptions): InferredSchema;
+
+/**
+ * Base64 数据隔离和替换工具
+ * 用于在 LLM 处理前替换 base64 图片数据，减少输入大小
+ */
+/**
+ * 提取并替换 base64 数据
+ * @param data 原始数据（可以是对象、数组、字符串等）
+ * @returns 处理后的数据和替换映射表
+ */
+declare function extractAndReplaceBase64(data: any): {
+    processedData: any;
+    replacements: Map<string, string>;
+};
+/**
+ * 恢复 base64 数据
+ * @param data 包含占位符的数据
+ * @param replacements 替换映射表
+ * @returns 恢复后的数据
+ */
+declare function restoreBase64(data: any, replacements: Map<string, string>): any;
+/**
+ * 从数据中提取所有 base64 图片
+ * @param data 原始数据
+ * @returns 图片数组（base64 data URL 格式）
+ */
+declare function extractImages(data: any): string[];
+
+export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type InferSchemaOptions, type InferredSchema, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, extractAndReplaceBase64, extractImages, fetchWhitelistInfo, inferSchema, restoreBase64, uint8ArrayToBase64, verifyWhitelist };

package/dist/index.js

@@ -27,7 +27,11 @@ __export(index_exports, {
   decodeDataFromUrl: () => decodeDataFromUrl,
   decompress: () => decompress,
   encodeDataToUrl: () => encodeDataToUrl,
+  extractAndReplaceBase64: () => extractAndReplaceBase64,
+  extractImages: () => extractImages,
   fetchWhitelistInfo: () => fetchWhitelistInfo,
+  inferSchema: () => inferSchema,
+  restoreBase64: () => restoreBase64,
   uint8ArrayToBase64: () => uint8ArrayToBase64,
   verifyWhitelist: () => verifyWhitelist
 });
@@ -339,4 +343,169 @@ _AgentLinkClient.whitelistCache = /* @__PURE__ */ new Map();
 // 缓存过期时间：1 小时
 _AgentLinkClient.CACHE_TTL = 60 * 60 * 1e3;
 var AgentLinkClient = _AgentLinkClient;
+
+// src/utils/base64.ts
+var DATA_URL_REGEX = /data:image\/[^;]+;base64,[A-Za-z0-9+/=]+/gi;
+function extractAndReplaceBase64(data) {
+  const replacements = /* @__PURE__ */ new Map();
+  let imgIndex = 0;
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return value.replace(DATA_URL_REGEX, (match) => {
+        const placeholder = `_IMG_${imgIndex}_`;
+        replacements.set(placeholder, match);
+        imgIndex++;
+        return placeholder;
+      });
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => processValue(item));
+    }
+    if (typeof value === "object") {
+      const processed = {};
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processed[key] = processValue(value[key]);
+        }
+      }
+      return processed;
+    }
+    return value;
+  }
+  const processedData = processValue(data);
+  return { processedData, replacements };
+}
+function restoreBase64(data, replacements) {
+  if (!replacements || replacements.size === 0) {
+    return data;
+  }
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (typeof value === "string") {
+      let result = value;
+      for (const [placeholder, original] of replacements.entries()) {
+        result = result.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), original);
+      }
+      return result;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => processValue(item));
+    }
+    if (typeof value === "object") {
+      const processed = {};
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processed[key] = processValue(value[key]);
+        }
+      }
+      return processed;
+    }
+    return value;
+  }
+  return processValue(data);
+}
+function extractImages(data) {
+  const images = [];
+  const seen = /* @__PURE__ */ new Set();
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return;
+    }
+    if (typeof value === "string") {
+      const matches = value.matchAll(DATA_URL_REGEX);
+      for (const match of matches) {
+        if (!seen.has(match[0])) {
+          images.push(match[0]);
+          seen.add(match[0]);
+        }
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item) => processValue(item));
+      return;
+    }
+    if (typeof value === "object") {
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processValue(value[key]);
+        }
+      }
+    }
+  }
+  processValue(data);
+  return images;
+}
+
+// src/utils/schema.ts
+var DEFAULTS = {
+  maxDepth: 5,
+  maxStringLength: 500,
+  maxTotalTextLength: 3e3,
+  maxArrayItems: 5,
+  maxKeys: 20
+};
+var TRUNCATED_SUFFIX = "...(truncated)";
+function inferSchema(rawData, options) {
+  const opts = { ...DEFAULTS, ...options };
+  const { processedData } = extractAndReplaceBase64(rawData);
+  let totalTextLength = 0;
+  function processValue(value, depth) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (depth > opts.maxDepth) {
+      return { _truncated: true, _depth: depth };
+    }
+    if (typeof value === "string") {
+      const maxForThis = Math.min(
+        opts.maxStringLength,
+        opts.maxTotalTextLength - totalTextLength
+      );
+      if (value.length <= maxForThis) {
+        totalTextLength += value.length;
+        return value;
+      }
+      totalTextLength += maxForThis;
+      return value.slice(0, maxForThis) + TRUNCATED_SUFFIX;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return [];
+      const keep = Math.min(value.length, opts.maxArrayItems);
+      const items = [];
+      for (let i = 0; i < keep; i++) {
+        items.push(processValue(value[i], depth + 1));
+      }
+      if (value.length > keep) {
+        items.push({ _truncated: true, _length: value.length });
+      }
+      return items;
+    }
+    if (typeof value === "object") {
+      const keys = Object.keys(value).filter(
+        (k) => Object.prototype.hasOwnProperty.call(value, k)
+      );
+      const keepKeys = keys.slice(0, opts.maxKeys);
+      const out = {};
+      for (const key of keepKeys) {
+        out[key] = processValue(value[key], depth + 1);
+      }
+      if (keys.length > opts.maxKeys) {
+        out._truncated = true;
+        out._keysTotal = keys.length;
+      }
+      return out;
+    }
+    return value;
+  }
+  return processValue(processedData, 0);
+}
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -304,6 +304,171 @@ _AgentLinkClient.whitelistCache = /* @__PURE__ */ new Map();
 // 缓存过期时间：1 小时
 _AgentLinkClient.CACHE_TTL = 60 * 60 * 1e3;
 var AgentLinkClient = _AgentLinkClient;
+
+// src/utils/base64.ts
+var DATA_URL_REGEX = /data:image\/[^;]+;base64,[A-Za-z0-9+/=]+/gi;
+function extractAndReplaceBase64(data) {
+  const replacements = /* @__PURE__ */ new Map();
+  let imgIndex = 0;
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return value.replace(DATA_URL_REGEX, (match) => {
+        const placeholder = `_IMG_${imgIndex}_`;
+        replacements.set(placeholder, match);
+        imgIndex++;
+        return placeholder;
+      });
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => processValue(item));
+    }
+    if (typeof value === "object") {
+      const processed = {};
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processed[key] = processValue(value[key]);
+        }
+      }
+      return processed;
+    }
+    return value;
+  }
+  const processedData = processValue(data);
+  return { processedData, replacements };
+}
+function restoreBase64(data, replacements) {
+  if (!replacements || replacements.size === 0) {
+    return data;
+  }
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (typeof value === "string") {
+      let result = value;
+      for (const [placeholder, original] of replacements.entries()) {
+        result = result.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), original);
+      }
+      return result;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => processValue(item));
+    }
+    if (typeof value === "object") {
+      const processed = {};
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processed[key] = processValue(value[key]);
+        }
+      }
+      return processed;
+    }
+    return value;
+  }
+  return processValue(data);
+}
+function extractImages(data) {
+  const images = [];
+  const seen = /* @__PURE__ */ new Set();
+  function processValue(value) {
+    if (value === null || value === void 0) {
+      return;
+    }
+    if (typeof value === "string") {
+      const matches = value.matchAll(DATA_URL_REGEX);
+      for (const match of matches) {
+        if (!seen.has(match[0])) {
+          images.push(match[0]);
+          seen.add(match[0]);
+        }
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item) => processValue(item));
+      return;
+    }
+    if (typeof value === "object") {
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          processValue(value[key]);
+        }
+      }
+    }
+  }
+  processValue(data);
+  return images;
+}
+
+// src/utils/schema.ts
+var DEFAULTS = {
+  maxDepth: 5,
+  maxStringLength: 500,
+  maxTotalTextLength: 3e3,
+  maxArrayItems: 5,
+  maxKeys: 20
+};
+var TRUNCATED_SUFFIX = "...(truncated)";
+function inferSchema(rawData, options) {
+  const opts = { ...DEFAULTS, ...options };
+  const { processedData } = extractAndReplaceBase64(rawData);
+  let totalTextLength = 0;
+  function processValue(value, depth) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (depth > opts.maxDepth) {
+      return { _truncated: true, _depth: depth };
+    }
+    if (typeof value === "string") {
+      const maxForThis = Math.min(
+        opts.maxStringLength,
+        opts.maxTotalTextLength - totalTextLength
+      );
+      if (value.length <= maxForThis) {
+        totalTextLength += value.length;
+        return value;
+      }
+      totalTextLength += maxForThis;
+      return value.slice(0, maxForThis) + TRUNCATED_SUFFIX;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return [];
+      const keep = Math.min(value.length, opts.maxArrayItems);
+      const items = [];
+      for (let i = 0; i < keep; i++) {
+        items.push(processValue(value[i], depth + 1));
+      }
+      if (value.length > keep) {
+        items.push({ _truncated: true, _length: value.length });
+      }
+      return items;
+    }
+    if (typeof value === "object") {
+      const keys = Object.keys(value).filter(
+        (k) => Object.prototype.hasOwnProperty.call(value, k)
+      );
+      const keepKeys = keys.slice(0, opts.maxKeys);
+      const out = {};
+      for (const key of keepKeys) {
+        out[key] = processValue(value[key], depth + 1);
+      }
+      if (keys.length > opts.maxKeys) {
+        out._truncated = true;
+        out._keysTotal = keys.length;
+      }
+      return out;
+    }
+    return value;
+  }
+  return processValue(processedData, 0);
+}
 export {
   AgentLinkClient,
   DEFAULT_SERVER_URL,
@@ -312,7 +477,11 @@ export {
   decodeDataFromUrl,
   decompress,
   encodeDataToUrl,
+  extractAndReplaceBase64,
+  extractImages,
   fetchWhitelistInfo,
+  inferSchema,
+  restoreBase64,
   uint8ArrayToBase64,
   verifyWhitelist
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "agentlink-sdk",
-    "version": "1.0.7",
+    "version": "1.0.8",
     "description": "AgentLink client SDK for cross-domain data synchronization via URL hash",
     "main": "dist/index.js",
     "module": "dist/index.esm.js",
@@ -14,7 +14,10 @@
     },
     "scripts": {
         "build": "tsup",
-        "clean": "rimraf dist"
+        "clean": "rimraf dist",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:llm-schema": "tsx scripts/test-llm-schema.ts"
     },
     "keywords": [
         "agentlink",
@@ -27,7 +30,9 @@
     "devDependencies": {
         "@types/node": "^20.0.0",
         "rimraf": "^4.4.0",
+        "vitest": "^2.0.0",
         "tsup": "^8.0.0",
+        "tsx": "^4.21.0",
         "typescript": "^5.0.2"
     },
     "peerDependencies": {}

package/scripts/test-llm-schema.ts

@@ -0,0 +1,246 @@
+/**
+ * LLM Schema 真实测试（agentlink-sdk）
+ * 复用包内 inferSchema、extractImages，仅发送 schema 请求 LLM，再按前端方式回填拼接。
+ *
+ * LLM 配置（二选一，在脚本内通过环境变量配置）：
+ * - 方式 A：AGENTLINK_SERVER_URL  — 请求该地址的 /api/memory/llm/process（需先启动 apps/server）
+ * - 方式 B：LLM_API_URL + LLM_API_KEY（及可选 LLM_MODEL）— 直接请求 OpenAI 兼容 API
+ *
+ * 运行：npm run test:llm-schema  或  npx tsx scripts/test-llm-schema.ts
+ */
+
+import { inferSchema, type InferredSchema } from '../src/utils/schema';
+import { extractImages } from '../src/utils/base64';
+
+interface AIProcessedData {
+  source: string;
+  category: string;
+  content: string;
+  tags: string[];
+  images?: string[];
+  metadata?: any;
+}
+
+function getApiUrl(): string {
+  const serverUrl = process.env.AGENTLINK_SERVER_URL;
+  const llmUrl = process.env.LLM_API_URL;
+  if (serverUrl) return `${serverUrl.replace(/\/$/, '')}/api/memory/llm/process`;
+  if (llmUrl) return ''; // 表示用方式 B，脚本内直接调 LLM
+  throw new Error(
+    '请配置 LLM：设置 AGENTLINK_SERVER_URL（方式 A）或 LLM_API_URL + LLM_API_KEY（方式 B）'
+  );
+}
+
+async function postSchemaToServer(
+  apiUrl: string,
+  schema: InferredSchema,
+  options?: { systemPrompt?: string; temperature?: number }
+): Promise<Response> {
+  const body: { schema: any; systemPrompt?: string; temperature?: number } = { schema };
+  if (options?.systemPrompt != null) body.systemPrompt = options.systemPrompt;
+  if (options?.temperature != null) body.temperature = options.temperature;
+  return fetch(apiUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+async function callLlmDirect(
+  schema: InferredSchema
+): Promise<AIProcessedData> {
+  const url = process.env.LLM_API_URL;
+  const key = process.env.LLM_API_KEY;
+  const model = process.env.LLM_MODEL || 'gpt-4o-mini';
+  if (!url || !key) throw new Error('LLM_API_URL 与 LLM_API_KEY 必填');
+  const systemPrompt =
+    '你是一个专业的信息整理助手。根据 schema 将内容归类到 source、category、content、tags、metadata 中返回 JSON，不要返回 images。';
+  const userPrompt = `schema:\n${JSON.stringify(schema, null, 2)}\n\n请返回 JSON：{"source":"","category":"","content":"","tags":[],"metadata":{}}`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${key}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: 'system', content: systemPrompt }, { role: 'user', content: userPrompt }],
+      temperature: 0.7,
+    }),
+  });
+  if (!res.ok) throw new Error(`LLM 请求失败: ${res.status}`);
+  const data = await res.json();
+  const content = data.choices?.[0]?.message?.content;
+  if (!content) throw new Error('LLM 未返回 content');
+  const parsed = JSON.parse(content.replace(/```json\s*|\s*```/g, '').trim());
+  return {
+    source: String(parsed.source ?? ''),
+    category: String(parsed.category ?? ''),
+    content: String(parsed.content ?? ''),
+    tags: Array.isArray(parsed.tags) ? parsed.tags.map(String) : [],
+    metadata: parsed.metadata ?? {},
+  };
+}
+
+function readSSEResult(res: Response): Promise<AIProcessedData> {
+  return res.text().then((text) => {
+    const lines = text.split('\n').filter((l) => l.startsWith('data: '));
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const data = lines[i].replace(/^data: /, '').trim();
+      try {
+        const json = JSON.parse(data);
+        if (json.result) return json.result as AIProcessedData;
+        if (json.error) throw new Error(json.error);
+      } catch (e) {
+        if (e instanceof Error && e.message !== 'Unexpected end of JSON input') throw e;
+      }
+    }
+    throw new Error('No result in SSE stream');
+  });
+}
+
+function mergeWithRawData(apiResult: AIProcessedData, rawData: any): AIProcessedData {
+  const images = extractImages(rawData);
+  return {
+    ...apiResult,
+    images: images.length > 0 ? images : undefined,
+  };
+}
+
+function hasImageInRawData(rawData: any): boolean {
+  return extractImages(rawData).length > 0;
+}
+
+function hasSubstantialContent(schema: any): boolean {
+  if (schema === null || schema === undefined) return false;
+  if (typeof schema === 'string') return schema.length > 0;
+  if (typeof schema === 'number' || typeof schema === 'boolean') return true;
+  if (Array.isArray(schema)) return schema.some(hasSubstantialContent);
+  if (typeof schema === 'object') return Object.values(schema).some(hasSubstantialContent);
+  return false;
+}
+
+function isMinimalSchema(schema: any): boolean {
+  return !hasSubstantialContent(schema);
+}
+
+function normalizeResult(result: AIProcessedData): AIProcessedData {
+  return {
+    source: String(result.source ?? ''),
+    category: String(result.category ?? ''),
+    content: String(result.content ?? ''),
+    tags: Array.isArray(result.tags) ? result.tags.map(String) : [],
+    metadata: result.metadata ?? {},
+  };
+}
+
+const fixtures: { name: string; rawData: any }[] = [
+  { name: '简单扁平对象', rawData: { title: '一篇笔记', content: '今天学习了 Next.js 和 LLM 集成，收获很大。', type: 'note' } },
+  { name: '深层嵌套对象', rawData: { a: { b: { c: { d: { e: { f: 'deep' } } } } } } },
+  { name: '长字符串', rawData: { text: '很长的正文。'.repeat(200), title: '长文' } },
+  { name: '长数组', rawData: { list: Array.from({ length: 15 }, (_, i) => ({ id: i, name: `item${i}` })) } },
+  {
+    name: '含 base64 图片',
+    rawData: {
+      title: '带图笔记',
+      content: '有一张图',
+      image: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+    },
+  },
+  { name: '空对象', rawData: {} },
+  { name: '空数组', rawData: { items: [] } },
+  {
+    name: '混合：嵌套+数组+长文本',
+    rawData: {
+      meta: { app: 'Test', version: 1 },
+      sections: [
+        { heading: 'A', paragraphs: ['段落一。', '段落二。'.repeat(100)] },
+        { heading: 'B', paragraphs: ['段落三'] },
+      ],
+      url: 'https://example.com',
+    },
+  },
+  { name: '根级数组', rawData: [{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 3, name: 'c' }] },
+  { name: '数字与布尔', rawData: { count: 42, active: true, label: '状态' } },
+];
+
+async function run(): Promise<void> {
+  console.log('LLM Schema 真实测试（agentlink-sdk inferSchema + extractImages）\n');
+  const apiUrl = getApiUrl();
+  const useServer = Boolean(process.env.AGENTLINK_SERVER_URL);
+  if (useServer) console.log('模式 A: AGENTLINK_SERVER_URL\n');
+  else console.log('模式 B: LLM_API_URL + LLM_API_KEY\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const { name, rawData } of fixtures) {
+    process.stdout.write(`[${name}] ... `);
+    try {
+      const schema = inferSchema(rawData);
+      let apiResult: AIProcessedData;
+
+      if (useServer) {
+        const res = await postSchemaToServer(apiUrl, schema);
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({}));
+          throw new Error((err as { error?: string }).error || res.statusText);
+        }
+        apiResult = await readSSEResult(res);
+      } else {
+        apiResult = await callLlmDirect(schema);
+      }
+
+      const minimal = isMinimalSchema(schema);
+      if (minimal) {
+        const normalized = normalizeResult(apiResult);
+        if (
+          typeof normalized.source !== 'string' ||
+          typeof normalized.category !== 'string' ||
+          typeof normalized.content !== 'string' ||
+          !Array.isArray(normalized.tags)
+        ) {
+          throw new Error('API 返回缺少必需字段结构: source, category, content, tags');
+        }
+      } else {
+        if (
+          !apiResult.source ||
+          !apiResult.category ||
+          !apiResult.content ||
+          !Array.isArray(apiResult.tags)
+        ) {
+          throw new Error('API 返回缺少必需字段: source, category, content, tags');
+        }
+      }
+      if (apiResult.images !== undefined) {
+        throw new Error('API 不应返回 images（应由前端回填）');
+      }
+
+      const resultForMerge = minimal ? normalizeResult(apiResult) : apiResult;
+      const final = mergeWithRawData(resultForMerge, rawData);
+      if (
+        typeof final.source !== 'string' ||
+        typeof final.category !== 'string' ||
+        typeof final.content !== 'string' ||
+        !Array.isArray(final.tags)
+      ) {
+        throw new Error('回填后仍缺少必需字段');
+      }
+      if (hasImageInRawData(rawData) && (!final.images || final.images.length === 0)) {
+        throw new Error('rawData 含图片但回填后 final.images 为空');
+      }
+
+      console.log('通过');
+      passed++;
+    } catch (e) {
+      console.log('失败:', e instanceof Error ? e.message : e);
+      failed++;
+    }
+  }
+
+  console.log('\n--- 汇总 ---');
+  console.log(`通过: ${passed}, 失败: ${failed}, 总计: ${fixtures.length}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+run();

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
+  },
+});