@yh-ui/ai-sdk 0.1.21

package/dist/observability.d.ts

@@ -0,0 +1,112 @@
+/**
+ * YH-UI AI SDK - 可观测性导出
+ *
+ * 支持 OpenTelemetry JSON 导出与 LangSmith 风格遥测。
+ */
+import type { TraceSpan, TraceEvent } from './future';
+/** OpenTelemetry Span 类型（兼容 OTLP） */
+export interface OTelSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+    startTimeUnixNano: number;
+    endTimeUnixNano?: number;
+    status?: {
+        code: 0 | 1 | 2;
+        message?: string;
+    };
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+            intValue?: number;
+            boolValue?: boolean;
+        };
+    }>;
+    events?: Array<{
+        timeUnixNano: number;
+        name: string;
+        attributes?: Array<{
+            key: string;
+            value: {
+                stringValue?: string;
+            };
+        }>;
+    }>;
+}
+/** OpenTelemetry Resource */
+export interface OTelResource {
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+        };
+    }>;
+}
+/** OpenTelemetry Export Payload */
+export interface OTelExportPayload {
+    resourceSpans: Array<{
+        resource: OTelResource;
+        scopeSpans: Array<{
+            spans: OTelSpan[];
+        }>;
+    }>;
+}
+/** LangSmith run 类型 */
+export type LangSmithRunType = 'llm' | 'chain' | 'tool' | 'retriever';
+/** LangSmith 遥测数据 */
+export interface LangSmithRun {
+    id: string;
+    name: string;
+    run_type: LangSmithRunType;
+    start_time: number;
+    end_time?: number;
+    inputs: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    error?: string;
+    parent_run_id?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** LangSmith 客户端配置 */
+export interface LangSmithClientConfig {
+    apiUrl?: string;
+    apiKey?: string;
+    projectName?: string;
+}
+/** 导出器接口 */
+export interface TraceExporter {
+    /** 导出 spans */
+    exportSpans(spans: OTelSpan[]): Promise<void>;
+    /** 导出事件 */
+    exportEvents?(events: TraceEvent[]): Promise<void>;
+}
+/**
+ * OpenTelemetry JSON Console Exporter（开发调试用）
+ */
+export declare function createOTelConsoleExporter(): TraceExporter;
+/**
+ * LangSmith Exporter（可对接官方 API）
+ */
+export declare function createLangSmithExporter(config: LangSmithClientConfig): TraceExporter;
+/**
+ * 将 internal TraceSpan 转换为 OTelSpan
+ */
+export declare function toOTelSpan(span: TraceSpan, traceId: string): OTelSpan;
+/**
+ * 创建可观测性管理器（整合 tracer + exporter）
+ */
+export interface ObservabilityManager {
+    /** 添加导出器 */
+    addExporter(exporter: TraceExporter): void;
+    /** 刷新所有导出器 */
+    flush(): Promise<void>;
+    /** 收集并导出当前 trace */
+    export(tracerSpans: TraceSpan[]): Promise<void>;
+}
+export declare function createObservabilityManager(config?: {
+    exporters?: TraceExporter[];
+    traceId?: string;
+}): ObservabilityManager;

package/dist/observability.mjs

@@ -0,0 +1,117 @@
+export function createOTelConsoleExporter() {
+  return {
+    async exportSpans(spans) {
+      const payload = {
+        resourceSpans: [
+          {
+            resource: {
+              attributes: [{ key: "service.name", value: { stringValue: "yh-ai-sdk" } }]
+            },
+            scopeSpans: [{ spans }]
+          }
+        ]
+      };
+      console.log("[OTel Export]", JSON.stringify(payload, null, 2));
+    }
+  };
+}
+export function createLangSmithExporter(config) {
+  const { apiUrl = "https://api.langsmith.com/v1/runs", apiKey, projectName = "yh-ai-sdk" } = config;
+  return {
+    async exportSpans(spans) {
+      if (!apiKey) {
+        console.warn("[LangSmith] No API key configured, skipping export");
+        return;
+      }
+      const runs = spans.map((span) => {
+        const inputs = {};
+        const outputs = {};
+        let runType = "chain";
+        for (const attr of span.attributes) {
+          const key = attr.key;
+          const val = attr.value.stringValue ?? attr.value.intValue ?? attr.value.boolValue;
+          if (key.startsWith("input.")) {
+            inputs[key.slice(6)] = val;
+          } else if (key.startsWith("output.")) {
+            outputs[key.slice(7)] = val;
+          } else if (key === "run_type") {
+            runType = val;
+          }
+        }
+        return {
+          id: span.spanId,
+          name: span.name,
+          run_type: runType,
+          start_time: span.startTimeUnixNano / 1e6,
+          end_time: span.endTimeUnixNano ? span.endTimeUnixNano / 1e6 : Date.now(),
+          inputs,
+          outputs: Object.keys(outputs).length ? outputs : void 0,
+          error: span.status?.code === 2 ? span.status.message : void 0,
+          parent_run_id: span.parentSpanId,
+          metadata: { project: projectName }
+        };
+      });
+      try {
+        await fetch(apiUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`
+          },
+          body: JSON.stringify({ runs })
+        });
+      } catch (err) {
+        console.error("[LangSmith] Export failed:", err);
+      }
+    }
+  };
+}
+export function toOTelSpan(span, traceId) {
+  const startNs = span.startTime.getTime() * 1e6;
+  const endNs = span.endTime ? span.endTime.getTime() * 1e6 : Date.now() * 1e6;
+  const attrs = Object.entries(span.attributes).map(([key, value]) => ({
+    key,
+    value: typeof value === "string" ? { stringValue: value } : typeof value === "number" ? { intValue: value } : { boolValue: Boolean(value) }
+  }));
+  const events = span.events.map((e) => ({
+    timeUnixNano: e.timestamp.getTime() * 1e6,
+    name: e.type,
+    attributes: Object.entries(e.data).map(([k, v]) => ({
+      key: k,
+      value: { stringValue: String(v) }
+    }))
+  }));
+  return {
+    traceId,
+    spanId: span.id,
+    name: span.name,
+    kind: "INTERNAL",
+    startTimeUnixNano: startNs,
+    endTimeUnixNano: endNs,
+    status: span.events.some((e) => e.type === "error") ? { code: 2, message: "Error occurred" } : { code: 0 },
+    attributes: attrs,
+    events
+  };
+}
+export function createObservabilityManager(config) {
+  const exporters = config?.exporters || [];
+  const traceId = config?.traceId || Math.random().toString(16).slice(2).padStart(32, "0");
+  return {
+    addExporter(exporter) {
+      exporters.push(exporter);
+    },
+    async flush() {
+      await Promise.all(
+        exporters.map(async (ex) => {
+          if ("flush" in ex && typeof ex.flush === "function") {
+            await ex.flush();
+          }
+        })
+      );
+    },
+    async export(tracerSpans) {
+      const otelSpans = tracerSpans.map((s) => toOTelSpan(s, traceId));
+      await Promise.all(exporters.map((ex) => ex.exportSpans(otelSpans)));
+    }
+  };
+}

package/dist/rag-production.cjs

@@ -0,0 +1,95 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createProductionRAG = createProductionRAG;
+function createProductionRAG(config) {
+  const {
+    namespace = "default",
+    topK = 5,
+    similarityThreshold = 0.5,
+    includeSources = true,
+    vectorStore,
+    embed
+  } = config;
+  async function addDocuments(documents) {
+    const vectors = [];
+    for (let i = 0; i < documents.length; i++) {
+      const doc = documents[i];
+      const embedding = await embed(doc.content);
+      vectors.push({
+        id: `chunk-${Date.now()}-${i}`,
+        content: doc.content,
+        embedding,
+        metadata: doc.metadata || {}
+      });
+    }
+    await vectorStore.add(vectors, namespace);
+    return vectors.map(v => ({
+      id: v.id,
+      content: v.content,
+      metadata: v.metadata,
+      embedding: v.embedding
+    }));
+  }
+  async function retrieve(query2, k = topK) {
+    const queryEmbedding = await embed(query2);
+    const results = await vectorStore.search(queryEmbedding, {
+      topK: k,
+      threshold: similarityThreshold,
+      namespace
+    });
+    return results.map(r => ({
+      id: r.id,
+      content: r.content,
+      metadata: r.metadata || {},
+      score: r.score,
+      embedding: r.embedding
+    }));
+  }
+  async function query(question, llm) {
+    const relevantDocs = await retrieve(question);
+    if (relevantDocs.length === 0) {
+      return {
+        answer: "\u62B1\u6B49\uFF0C\u77E5\u8BC6\u5E93\u4E2D\u6CA1\u6709\u627E\u5230\u76F8\u5173\u4FE1\u606F\u3002",
+        sources: [],
+        contextUsed: ""
+      };
+    }
+    const context = relevantDocs.map((doc, i) => `[\u6587\u6863 ${i + 1}]
+${doc.content}`).join("\n\n");
+    const prompt = `\u57FA\u4E8E\u4EE5\u4E0B\u77E5\u8BC6\u5E93\u5185\u5BB9\uFF0C\u7528\u4E2D\u6587\u56DE\u7B54\u7528\u6237\u7684\u95EE\u9898\u3002\u5982\u679C\u77E5\u8BC6\u5E93\u4E2D\u7684\u4FE1\u606F\u4E0D\u80FD\u56DE\u7B54\u95EE\u9898\uFF0C\u8BF7\u8BF4\u660E\u3002
+
+\u77E5\u8BC6\u5E93\u5185\u5BB9:
+${context}
+
+\u7528\u6237\u95EE\u9898: ${question}
+
+\u8BF7\u7ED9\u51FA\u56DE\u7B54\uFF1A`;
+    const answer = await llm(prompt);
+    return {
+      answer,
+      sources: includeSources ? relevantDocs.map(doc => ({
+        content: doc.content.slice(0, 200) + (doc.content.length > 200 ? "..." : ""),
+        metadata: doc.metadata,
+        score: doc.score ?? 0
+      })) : [],
+      contextUsed: context.slice(0, 500)
+    };
+  }
+  async function clear() {
+    await vectorStore.clear(namespace);
+  }
+  return {
+    addDocuments,
+    retrieve,
+    query,
+    clear,
+    config: {
+      topK,
+      similarityThreshold,
+      namespace
+    }
+  };
+}

package/dist/rag-production.d.ts

@@ -0,0 +1,43 @@
+/**
+ * YH-UI AI SDK - 生产级 RAG
+ *
+ * 依赖向量存储抽象与可选嵌入函数，可与文档加载器配合使用。
+ */
+import type { IVectorStore } from './vector-store';
+import type { RAGResult, DocumentChunk } from './future';
+export interface ProductionRAGConfig {
+    /** 知识库/命名空间 */
+    namespace?: string;
+    /** 检索数量 */
+    topK?: number;
+    /** 相似度阈值 */
+    similarityThreshold?: number;
+    /** 是否返回源信息 */
+    includeSources?: boolean;
+    /** 向量存储（必填） */
+    vectorStore: IVectorStore;
+    /** 嵌入函数（必填，用于 query 与 addDocuments） */
+    embed: (text: string) => Promise<number[]>;
+}
+/**
+ * 生产级 RAG：使用真实向量存储与嵌入
+ */
+export declare function createProductionRAG(config: ProductionRAGConfig): {
+    addDocuments: (documents: Array<{
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>) => Promise<{
+        id: string;
+        content: string;
+        metadata: Record<string, unknown> | undefined;
+        embedding: number[];
+    }[]>;
+    retrieve: (query: string, k?: number) => Promise<DocumentChunk[]>;
+    query: (question: string, llm: (prompt: string) => Promise<string>) => Promise<RAGResult>;
+    clear: () => Promise<void>;
+    config: {
+        topK: number;
+        similarityThreshold: number;
+        namespace: string;
+    };
+};

package/dist/rag-production.mjs

@@ -0,0 +1,85 @@
+export function createProductionRAG(config) {
+  const {
+    namespace = "default",
+    topK = 5,
+    similarityThreshold = 0.5,
+    includeSources = true,
+    vectorStore,
+    embed
+  } = config;
+  async function addDocuments(documents) {
+    const vectors = [];
+    for (let i = 0; i < documents.length; i++) {
+      const doc = documents[i];
+      const embedding = await embed(doc.content);
+      vectors.push({
+        id: `chunk-${Date.now()}-${i}`,
+        content: doc.content,
+        embedding,
+        metadata: doc.metadata || {}
+      });
+    }
+    await vectorStore.add(vectors, namespace);
+    return vectors.map((v) => ({
+      id: v.id,
+      content: v.content,
+      metadata: v.metadata,
+      embedding: v.embedding
+    }));
+  }
+  async function retrieve(query2, k = topK) {
+    const queryEmbedding = await embed(query2);
+    const results = await vectorStore.search(queryEmbedding, {
+      topK: k,
+      threshold: similarityThreshold,
+      namespace
+    });
+    return results.map((r) => ({
+      id: r.id,
+      content: r.content,
+      metadata: r.metadata || {},
+      score: r.score,
+      embedding: r.embedding
+    }));
+  }
+  async function query(question, llm) {
+    const relevantDocs = await retrieve(question);
+    if (relevantDocs.length === 0) {
+      return {
+        answer: "\u62B1\u6B49\uFF0C\u77E5\u8BC6\u5E93\u4E2D\u6CA1\u6709\u627E\u5230\u76F8\u5173\u4FE1\u606F\u3002",
+        sources: [],
+        contextUsed: ""
+      };
+    }
+    const context = relevantDocs.map((doc, i) => `[\u6587\u6863 ${i + 1}]
+${doc.content}`).join("\n\n");
+    const prompt = `\u57FA\u4E8E\u4EE5\u4E0B\u77E5\u8BC6\u5E93\u5185\u5BB9\uFF0C\u7528\u4E2D\u6587\u56DE\u7B54\u7528\u6237\u7684\u95EE\u9898\u3002\u5982\u679C\u77E5\u8BC6\u5E93\u4E2D\u7684\u4FE1\u606F\u4E0D\u80FD\u56DE\u7B54\u95EE\u9898\uFF0C\u8BF7\u8BF4\u660E\u3002
+
+\u77E5\u8BC6\u5E93\u5185\u5BB9:
+${context}
+
+\u7528\u6237\u95EE\u9898: ${question}
+
+\u8BF7\u7ED9\u51FA\u56DE\u7B54\uFF1A`;
+    const answer = await llm(prompt);
+    return {
+      answer,
+      sources: includeSources ? relevantDocs.map((doc) => ({
+        content: doc.content.slice(0, 200) + (doc.content.length > 200 ? "..." : ""),
+        metadata: doc.metadata,
+        score: doc.score ?? 0
+      })) : [],
+      contextUsed: context.slice(0, 500)
+    };
+  }
+  async function clear() {
+    await vectorStore.clear(namespace);
+  }
+  return {
+    addDocuments,
+    retrieve,
+    query,
+    clear,
+    config: { topK, similarityThreshold, namespace }
+  };
+}

package/dist/rate-limit.cjs

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createRateLimitMiddleware = createRateLimitMiddleware;
+exports.createRateLimiter = createRateLimiter;
+const defaultKey = "__default__";
+function createRateLimiter(config) {
+  const {
+    windowMs,
+    max,
+    keyBy = () => defaultKey,
+    message = "Too Many Requests"
+  } = config;
+  const store = /* @__PURE__ */new Map();
+  function getKey(cfg) {
+    if (typeof keyBy === "function") return keyBy(cfg) || defaultKey;
+    const h = cfg.headers || {};
+    if (keyBy === "userId") return cfg.userId ?? h["x-user-id"] ?? defaultKey;
+    if (keyBy === "apiKey") return h["x-api-key"] ?? h["authorization"] ?? defaultKey;
+    if (keyBy === "ip") return h["x-forwarded-for"] ?? h["x-real-ip"] ?? defaultKey;
+    return defaultKey;
+  }
+  function check(key) {
+    const now = Date.now();
+    let state = store.get(key);
+    if (!state || state.resetAt <= now) {
+      state = {
+        count: 0,
+        resetAt: now + windowMs
+      };
+      store.set(key, state);
+    }
+    state.count += 1;
+    const allowed = state.count <= max;
+    const remaining = Math.max(0, max - state.count);
+    return {
+      allowed,
+      remaining,
+      resetAt: state.resetAt
+    };
+  }
+  return {
+    check,
+    getKey,
+    /** 创建 XRequest 用的中间件 */
+    middleware() {
+      return {
+        name: "rate-limit",
+        async onRequest(requestConfig) {
+          const key = getKey(requestConfig);
+          const {
+            allowed,
+            remaining,
+            resetAt
+          } = check(key);
+          if (!allowed) {
+            const err = new Error(message);
+            err.statusCode = 429;
+            err.remaining = remaining;
+            err.resetAt = resetAt;
+            throw err;
+          }
+          return requestConfig;
+        }
+      };
+    }
+  };
+}
+function createRateLimitMiddleware(config) {
+  return createRateLimiter(config).middleware();
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,55 @@
+/**
+ * YH-UI AI SDK - 限流中间件
+ *
+ * 支持按用户/API Key 的令牌桶或滑动窗口，可与 AI Gateway 策略对齐。
+ */
+export interface RateLimitConfig {
+    /** 时间窗口（毫秒） */
+    windowMs: number;
+    /** 窗口内最大请求数 */
+    max: number;
+    /** 标识键：从 config 或 headers 中取，如 'userId' | 'apiKey'，默认同一 key 共享限额 */
+    keyBy?: 'userId' | 'apiKey' | 'ip' | ((config: {
+        headers?: Record<string, string>;
+        [k: string]: unknown;
+    }) => string);
+    /** 超限时返回的消息 */
+    message?: string;
+}
+/**
+ * 内存版限流器（单进程有效）
+ */
+export declare function createRateLimiter(config: RateLimitConfig): {
+    check: (key: string) => {
+        allowed: boolean;
+        remaining: number;
+        resetAt: number;
+    };
+    getKey: (cfg: {
+        headers?: Record<string, string>;
+        [k: string]: unknown;
+    }) => string;
+    /** 创建 XRequest 用的中间件 */
+    middleware(): {
+        name: string;
+        onRequest(requestConfig: {
+            headers?: Record<string, string>;
+            [k: string]: unknown;
+        }): Promise<{
+            [k: string]: unknown;
+            headers?: Record<string, string>;
+        }>;
+    };
+};
+/** 限流中间件（与 XRequest / registerMiddleware 兼容） */
+export interface RateLimitMiddleware {
+    name: string;
+    onRequest?: (config: {
+        headers?: Record<string, string>;
+        [k: string]: unknown;
+    }) => unknown | Promise<unknown>;
+}
+/**
+ * 创建限流中间件（便捷方法）
+ */
+export declare function createRateLimitMiddleware(config: RateLimitConfig): RateLimitMiddleware;

package/dist/rate-limit.mjs

@@ -0,0 +1,51 @@
+const defaultKey = "__default__";
+export function createRateLimiter(config) {
+  const { windowMs, max, keyBy = () => defaultKey, message = "Too Many Requests" } = config;
+  const store = /* @__PURE__ */ new Map();
+  function getKey(cfg) {
+    if (typeof keyBy === "function") return keyBy(cfg) || defaultKey;
+    const h = cfg.headers || {};
+    if (keyBy === "userId")
+      return cfg.userId ?? h["x-user-id"] ?? defaultKey;
+    if (keyBy === "apiKey") return h["x-api-key"] ?? h["authorization"] ?? defaultKey;
+    if (keyBy === "ip") return h["x-forwarded-for"] ?? h["x-real-ip"] ?? defaultKey;
+    return defaultKey;
+  }
+  function check(key) {
+    const now = Date.now();
+    let state = store.get(key);
+    if (!state || state.resetAt <= now) {
+      state = { count: 0, resetAt: now + windowMs };
+      store.set(key, state);
+    }
+    state.count += 1;
+    const allowed = state.count <= max;
+    const remaining = Math.max(0, max - state.count);
+    return { allowed, remaining, resetAt: state.resetAt };
+  }
+  return {
+    check,
+    getKey,
+    /** 创建 XRequest 用的中间件 */
+    middleware() {
+      return {
+        name: "rate-limit",
+        async onRequest(requestConfig) {
+          const key = getKey(requestConfig);
+          const { allowed, remaining, resetAt } = check(key);
+          if (!allowed) {
+            const err = new Error(message);
+            err.statusCode = 429;
+            err.remaining = remaining;
+            err.resetAt = resetAt;
+            throw err;
+          }
+          return requestConfig;
+        }
+      };
+    }
+  };
+}
+export function createRateLimitMiddleware(config) {
+  return createRateLimiter(config).middleware();
+}

package/dist/vector-store.cjs

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createInMemoryVectorStore = createInMemoryVectorStore;
+function createInMemoryVectorStore(_config) {
+  const store = /* @__PURE__ */new Map();
+  function cosineSimilarity(a, b) {
+    if (a.length !== b.length) return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+  }
+  return {
+    async add(documents, namespace = "default") {
+      const list = store.get(namespace) || [];
+      for (const doc of documents) {
+        const idx = list.findIndex(d => d.id === doc.id);
+        if (idx >= 0) list[idx] = doc;else list.push(doc);
+      }
+      store.set(namespace, list);
+    },
+    async search(queryEmbedding, options = {}) {
+      const topK = options.topK ?? 10;
+      const threshold = options.threshold ?? 0;
+      const namespaceOpt = options.namespace ?? "default";
+      const list = store.get(namespaceOpt) || [];
+      const scored = list.map(doc => ({
+        ...doc,
+        score: cosineSimilarity(doc.embedding, queryEmbedding)
+      })).filter(d => d.score >= threshold).sort((a, b) => b.score - a.score).slice(0, topK);
+      return scored.map(({
+        id,
+        content,
+        metadata,
+        score,
+        embedding
+      }) => ({
+        id,
+        content,
+        metadata,
+        score,
+        embedding
+      }));
+    },
+    async delete(ids, namespace = "default") {
+      const list = store.get(namespace) || [];
+      const set = new Set(ids);
+      store.set(namespace, list.filter(d => !set.has(d.id)));
+    },
+    async clear(namespace = "default") {
+      store.set(namespace, []);
+    }
+  };
+}