# @dooor-ai/toolkit 中文文档

规范地址：https://npmcn.com/package/%40dooor-ai/toolkit/

版本：0\.1\.62
npm 元数据更新时间：2026-10-07T12:32:09.227Z
中文译文更新时间：2026-11-12T16:30:15.566Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dooor-ai/toolkit
原文对照：https://npmcn.com/package/%40dooor-ai/toolkit/?lang=original
项目主页：https://github.com/dooor-ai/toolkit#readme
源码仓库：https://github.com/dooor-ai/toolkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：274 kB，96 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@langchain/core ^0\.3\.0 \|\| ^1\.0\.0
- 首次发布：2025-11-10T18:50:06.784Z
- 最新版本发布：2026-04-20T15:00:54.940Z
- 近 30 天下载量：3101（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 20 个）

## 中文简介

Guards, Evals & Observative for AI 应用程序的可观察性——与LangChain/LangGraph无缝合作

## 安装

```sh
npm install @dooor-ai/toolkit
```

也可以使用：`pnpm add @dooor-ai/toolkit`、`yarn add @dooor-ai/toolkit`、`bun add @dooor-ai/toolkit`

## README

# DOOOR AI 工具包

```
██████╗  ██████╗  ██████╗  ██████╗ ██████╗ 
██╔══██╗██╔═══██╗██╔═══██╗██╔═══██╗██╔══██╗
██║  ██║██║   ██║██║   ██║██║   ██║██████╔╝
██║  ██║██║   ██║██║   ██║██║   ██║██╔══██╗
██████╔╝╚██████╔╝╚██████╔╝╚██████╔╝██║  ██║
╚═════╝  ╚═════╝  ╚═════╝  ╚═════╝ ╚═╝  ╚═╝
```

**AI 应用程序的守护者、 Evals 和可观察性**

[![npm version](https://img.shields.io/npm/v/@dooor-ai/toolkit.svg)](https://www.npmjs.com/package/@dooor-ai/toolkit) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40dooor-ai/toolkit/LICENSE)

* * *

保障、评价和监测AI应用程序的全能框架。 与LangChain/LangGraph无缝合作.

## 安装

```bash
npm install @dooor-ai/toolkit
```

要求数 `@langchain/core` (0.3.x或1.x)作为对等依赖.

## V0.1.61中的新内容

-   **记录 `logTrace` 函数**: 没有 LangChain 的手动跟踪记录的综合文件 – 与 OpenAI SDK, Anthropic SDK, 双子座 SDK 或任何自定义的 HTTP LLM 调用合作
-   **会话支持示例**: 如何使用 `sessionId`
-   **TraceData 参考表**: 完整的实地文件

[查看完整的更改日志](https://github.com/dooor-ai/toolkit/releases)

## 快速启动

```typescript
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
import { dooorChatGuard } from "@dooor-ai/toolkit";
import { PromptInjectionGuard, ToxicityGuard } from "@dooor-ai/toolkit/guards";
import { LatencyEval, CostEval } from "@dooor-ai/toolkit/evals";

// 1. Create your LangChain provider normally
const baseProvider = new ChatGoogleGenerativeAI({
  model: "gemini-2.0-flash-exp",
  apiKey: process.env.GEMINI_API_KEY,
  temperature: 0,
});

// 2. Instrument with DOOOR Toolkit
const llm = dooorChatGuard(baseProvider, {
  apiKey: "cortexdb://your_api_key@your-host:8000/my_evals",
  providerName: "gemini",
  guards: [
    new PromptInjectionGuard({ threshold: 0.8 }),
    new ToxicityGuard({ threshold: 0.7 })
  ],
  evals: [
    new LatencyEval({ threshold: 3000 }),
    new CostEval({ budgetLimitUsd: 0.10 })
  ],
  observability: true,
});

// 3. Use normally - Guards + Evals work automatically
const response = await llm.invoke("What is the capital of France?");
```

## 特征

### 警卫(执行前)

保护您的 LLM 在它们到达模型前不被恶意输入:

-   **提示注射保护** - 侦测越狱企图并迅速注射
-   **毒性保障** - 通过AI节制屏蔽有毒/有害内容
-   **PII 守护** - 检测和口罩个人信息

### Evals (后执行)

自动评价响应质量 :

-   **莱滕特-埃瓦尔** - 跟踪反应时间和对缓慢反应的警报
-   **成本评估** - 在超过预算限额时监测费用并发出警报
-   **相关性** - 措施答复相关性(即将到来)
-   **幻觉Eval** - 发现幻觉(即将到来)

### 观察性

完全可见于您的 LLM 呼叫 :

-   带有独特痕量标识的自动跟踪
-   延迟和信号跟踪
-   按请求估算的费用
-   警卫和保镖记录结果
-   持久存储的 CortexDB 集成

## 手动追踪日志( M)`logTrace`(中文(简体) )

狦琌 **不使用兰彩** 或需要记录自定义 LLM 调用中的痕迹( raw HTTP, OpenAI SDK, Anthropic SDK等), 使用 `logTrace` 函数可以直接向 CortexDB 港湾发送痕迹.

### 设置

```typescript
import { configureCortexDBFromConnectionString, logTrace } from "@dooor-ai/toolkit";

// Configure once at app startup
configureCortexDBFromConnectionString(
  "cortexdb://YOUR_API_KEY@YOUR_HOST:8000/YOUR_DATABASE"
);
```

或者使用环境变量 :

```typescript
configureCortexDBFromConnectionString(process.env.CORTEXDB_CONNECTION!);
```

### 基本用途

```typescript
import { logTrace } from "@dooor-ai/toolkit";

// After any LLM call, log the trace:
const startedAt = Date.now();
const response = await callYourLLM(prompt);
const latency = Date.now() - startedAt;

await logTrace(
  {
    input: prompt,
    output: response.text,
    model: "gpt-4o",
    latency,
    tokens: {
      prompt: response.usage.prompt_tokens,
      completion: response.usage.completion_tokens,
      total: response.usage.total_tokens,
    },
    timestamp: new Date(),
  },
  {
    project: "my-app",  // Shows up in Harbor dashboard
  }
);
```

### 带有 OpenAI SDK

```typescript
import OpenAI from "openai";
import { configureCortexDBFromConnectionString, logTrace } from "@dooor-ai/toolkit";

configureCortexDBFromConnectionString(process.env.CORTEXDB_CONNECTION!);

const openai = new OpenAI();

async function chat(userMessage: string) {
  const startedAt = Date.now();

  const completion = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: userMessage }],
  });

  const output = completion.choices[0]?.message?.content || "";

  await logTrace(
    {
      input: userMessage,
      output,
      model: "gpt-4o",
      latency: Date.now() - startedAt,
      tokens: {
        prompt: completion.usage?.prompt_tokens || 0,
        completion: completion.usage?.completion_tokens || 0,
        total: completion.usage?.total_tokens || 0,
      },
      timestamp: new Date(),
    },
    { project: "my-openai-app" }
  );

  return output;
}
```

### 与 Anthropic SDK 游戏

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { configureCortexDBFromConnectionString, logTrace } from "@dooor-ai/toolkit";

configureCortexDBFromConnectionString(process.env.CORTEXDB_CONNECTION!);

const anthropic = new Anthropic();

async function chat(userMessage: string) {
  const startedAt = Date.now();

  const message = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: userMessage }],
  });

  const output = message.content[0].type === "text" ? message.content[0].text : "";

  await logTrace(
    {
      input: userMessage,
      output,
      model: "claude-sonnet-4-20250514",
      latency: Date.now() - startedAt,
      tokens: {
        prompt: message.usage.input_tokens,
        completion: message.usage.output_tokens,
        total: message.usage.input_tokens + message.usage.output_tokens,
      },
      timestamp: new Date(),
    },
    { project: "my-anthropic-app" }
  );

  return output;
}
```

### 与谷歌双子座 SDK

```typescript
import { GoogleGenerativeAI } from "@google/generative-ai";
import { configureCortexDBFromConnectionString, logTrace } from "@dooor-ai/toolkit";

configureCortexDBFromConnectionString(process.env.CORTEXDB_CONNECTION!);

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);

async function chat(userMessage: string) {
  const model = genAI.getGenerativeModel({ model: "gemini-2.0-flash" });
  const startedAt = Date.now();

  const result = await model.generateContent(userMessage);
  const output = result.response.text();
  const usage = result.response.usageMetadata;

  await logTrace(
    {
      input: userMessage,
      output,
      model: "gemini-2.0-flash",
      latency: Date.now() - startedAt,
      tokens: {
        prompt: usage?.promptTokenCount || 0,
        completion: usage?.candidatesTokenCount || 0,
        total: usage?.totalTokenCount || 0,
      },
      timestamp: new Date(),
    },
    { project: "my-gemini-app" }
  );

  return output;
}
```

### 与会(会)

使用 `sessionId`数字 :

```typescript
import { v4 as uuidv4 } from "uuid";
import { logTrace } from "@dooor-ai/toolkit";

const sessionId = uuidv4(); // One per conversation

// First message
await logTrace(
  {
    input: "Hello!",
    output: "Hi there! How can I help?",
    model: "gpt-4o",
    latency: 230,
    sessionId,
    timestamp: new Date(),
  },
  { project: "my-chatbot" }
);

// Second message (same session)
await logTrace(
  {
    input: "What's the weather?",
    output: "I don't have access to real-time weather data.",
    model: "gpt-4o",
    latency: 180,
    sessionId,
    timestamp: new Date(),
  },
  { project: "my-chatbot" }
);
```

### TraceData 引用

| 外地 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `input` | `string` | 对 | 发送给 LLM 的即时/输入 |
| `output` | `string` | 没有 | LLM 反应 |
| `model` | `string` | 对 | 型号名称(例如, `"gpt-4o"`, (中文(简体) ), `"claude-sonnet-4-20250514"`(中文(简体) ) |
| `timestamp` | `Date` | 对 | 打电话的时候 |
| `latency` | `number` | 没有 | 反应时间( 毫秒) |
| `tokens` | `object` | 没有 | Token 计数 : `{ prompt, completion, total }` |
| `cost` | `number` | 没有 | 估计费用(美元) |
| `traceId` | `string` | 没有 | 唯一微量ID( 如果省略则自动生成) |
| `sessionId` | `string` | 没有 | 分组跟踪的会话/对话ID |
| `toolCalls` | `array` | 没有 | 执行期间发出的工具/功能呼叫 |

### 日志跟踪选项

| 外地 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `project` | `string` | `undefined` | 港口仪表板显示的项目名称 |
| `enabled` | `boolean` | `true` | 设定为 `false` 禁用记录 |
| `backend` | `ObservabilityBackend` | 自动检测 | 自定义后端( CortexDB 或控制台) |
| `collector` | `ObservabilityCollector` | 自动创建 | 重用现有的收藏器实例 |

### 倒行逆施

如果追踪无法发送到 CortexDB( 网络错误, 配置错误) , `logTrace` 自动返回控制台日志 这样你就不会丢失跟踪数据.

## 提供者支助

与任何LangChain供应商合作:

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { ChatAnthropic } from "@langchain/anthropic";
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
import { dooorChatGuard } from "@dooor-ai/toolkit";

// OpenAI
const openai = dooorChatGuard(new ChatOpenAI({...}), toolkitConfig);

// Anthropic
const claude = dooorChatGuard(new ChatAnthropic({...}), toolkitConfig);

// Google
const gemini = dooorChatGuard(new ChatGoogleGenerativeAI({...}), toolkitConfig);
```

## LangGraph 整合

```typescript
import { StateGraph } from "@langchain/langgraph";
import { dooorChatGuard } from "@dooor-ai/toolkit";

const llm = dooorChatGuard(baseProvider, toolkitConfig);

const workflow = new StateGraph(...)
  .addNode("agent", async (state) => {
    const response = await llm.invoke(state.messages);
    return { messages: [response] };
  });

// Guards + Evals work automatically via callbacks
```

## 配置

### 工具包配置

```typescript
interface ToolkitConfig {
  // CortexDB connection string (optional, for AI proxy and observability)
  apiKey?: string;
  
  // AI Provider name from CortexDB Studio (optional, for AI-based guards)
  providerName?: string;
  
  // Guards to apply (run before LLM)
  guards?: Guard[];
  
  // Evals to apply (run after LLM)
  evals?: Eval[];
  
  // Output guards (validate LLM output)
  outputGuards?: Guard[];
  
  // Enable observability (default: true)
  observability?: boolean;
  
  // Eval execution mode: "async" | "sync" | "sample"
  evalMode?: string;
  
  // Sample rate for evals (0-1, default: 1.0)
  evalSampleRate?: number;
  
  // Guard failure mode: "throw" | "return_error" | "log_only"
  guardFailureMode?: string;
  
  // Project name for tracing
  project?: string;
}
```

### 守护配置

```typescript
new PromptInjectionGuard({
  threshold: 0.8,
  blockOnDetection: true,
  enabled: true,
})

new ToxicityGuard({
  threshold: 0.7,
  providerName: "gemini", // Optional: override global providerName
  categories: ["hate", "violence", "sexual", "harassment"],
})

new PIIGuard({
  detectTypes: ["email", "phone", "cpf", "credit_card", "ssn"],
  action: "mask", // "mask" | "block" | "warn"
})
```

### Eval 配置

```typescript
new LatencyEval({
  threshold: 3000, // Alert if > 3s
})

new CostEval({
  budgetLimitUsd: 0.10, // Alert if > $0.10
  alertOnExceed: true,
})
```

## CortexDB 整合

为了获得最佳经验,请使用 CortexDB:

**福利:**

-   AI 提供者代理( 您的守护码中没有 API 密钥)
-   AI 提供者管理
-   在 Postgres 中自动跟踪存储
-   用于可观察性的 Dashboard UI
-   自办和开源

**连接字符串格式 :**

```
cortexdb://api_key@host[:port]/database
```

如果省略端口,SDK默认为非本地主机的HTTPS.

**示例**

```typescript
const llm = dooorChatGuard(baseProvider, {
  apiKey: "cortexdb://cortexdb_adm123@35.223.201.25:8000/my_app",
  providerName: "gemini", // Configured in CortexDB Studio
  guards: [new ToxicityGuard()], // Uses Gemini via CortexDB proxy
});
```

## RAG( 回收- 增强的一代)

该工具包通过CortexDB提供ephemeral RAG能力,用于临时文档检索而无需创建永久的集合.

### 快速启动

```typescript
import { RAGContext, RAGStrategy, buildRAGPrompt } from "@dooor-ai/toolkit/rag";
import { dooorChatGuard } from "@dooor-ai/toolkit";

// Create RAG context with documents
const ragContext = new RAGContext({
  documents: [
    {
      content: "NestJS authentication guide: Use @nestjs/passport with JWT...",
      metadata: { source: "docs" }
    },
    {
      content: "Database setup: Install @prisma/client and configure...",
      metadata: { source: "tutorial" }
    }
  ],
  embeddingProvider: "prod-gemini", // From CortexDB Studio
  strategy: RAGStrategy.SIMPLE,
  topK: 3,
  chunkSize: 500,
  chunkOverlap: 100,
});

// Build prompt with RAG context
const userQuery = "How to authenticate users in NestJS?";
const promptWithContext = await buildRAGPrompt(userQuery, ragContext);

// Use with your LLM
const llm = dooorChatGuard(baseProvider, {...});
const response = await llm.invoke(promptWithContext);
```

### RAG 战略

#### 1\. 联合国. **标 题** (默认 - 最快)

使用同位素相似性进行直接语义搜索.

-   ⚡ **速度 :** 最快(1个嵌入)
-   💰 **费用:** 最低
-   🎯 **最佳服务:** 直接问题、技术文件、财务问题

```typescript
strategy: RAGStrategy.SIMPLE
```

#### 2\. 联合国. **希地语NAME** (热门文档嵌入)

首先生成一个假设的答案,然后搜索类似的块.

-   ⚡ **速度 :** 中 (1 LLM call + 2 嵌入)
-   💰 **费用:** 中型
-   🎯 **最佳服务:** 复杂查询、概念问题

**如何运作:**

1.  LLM 生成对您的查询的假设答案
2.  嵌入假设的答案( 不是查询 !)
3.  搜索类似于答案的块

```typescript
strategy: RAGStrategy.HYDE
```

**示例**

```
Query: "How to authenticate users?"
↓
LLM: "To authenticate users, use JWT tokens with passport..."
↓
Embed this answer → Search similar chunks
```

#### 3个. **卢旺达** (LLM重排)

取出更多的入选者,然后使用LLM根据相关性重新排序.

-   ⚡ **速度 :** 较慢(1个嵌入+1 LLM 重新排序)
-   💰 **费用:** 中型
-   🎯 **最佳服务:** 尽可能精确、模糊的询问

**如何运作:**

1.  语义搜索返回到上 k × 3 名候选人
2.  LLM按相关性分析所有和排名
3.  返回最相关的上 k

```typescript
strategy: RAGStrategy.RERANK
```

#### 4.四. **未来** (SIMPLE + HYDE 组合)

并行运行 SIMPLE 和 HYDE,结合结果使用对等的 Rank Fusion.

-   ⚡ **速度 :** 中 (并行执行)
-   💰 **费用:** 最高(兼收并蓄)
-   🎯 **最佳服务:** 关键查询,最高质量

**如何运作:**

1.  同时运行 SIMPLE 和 HYDE
2.  使用 RRF 的组合 : `score = 1/(rank_simple + 60) + 1/(rank_hyde + 60)`
3.  返回核聚变分数最高的顶( k)

```typescript
strategy: RAGStrategy.FUSION
```

### 战略比较

| 战略 | 速度 | 费用 | 精确度 | 最佳服务 |
| --- | --- | --- | --- | --- |
| **标 题** | ⚡⚡⚡ | 💰 | ⭐⭐⭐ | 直接问题 |
| **希地语NAME** | ⚡⚡ | 💰💰 | ⭐⭐⭐⭐ | 复杂查询 |
| **卢旺达** | ⚡ | 💰💰 | ⭐⭐⭐⭐⭐ | 最大精确度 |
| **未来** | ⚡⚡ | 💰💰💰 | ⭐⭐⭐⭐⭐ | 关键查询 |

### 带有文件的RAG

```typescript
const ragContext = new RAGContext({
  files: [
    {
      name: "manual.pdf",
      data: base64EncodedPDF,
      type: "application/pdf"
    }
  ],
  embeddingProvider: "prod-gemini",
  strategy: RAGStrategy.HYDE,
  topK: 5,
});
```

**支持的文件类型 :** PDF、DOCX、MD、TXT

### RAG 可观察性

所有RAG的电话都自动登录到 CortexDB :

-   使用的嵌入符
-   已检索到的块对总数
-   使用的战略
-   时间分解( Parse, 嵌入, 搜索)
-   类似分数

在 CortexDB Studio 中查看 ~可观察性 ~ RAG 标签

## 现实世界实例

### NestJS 整合

配有警卫、保镖和RAG的AI动力API:

```typescript
import { Injectable, Logger } from '@nestjs/common';
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
import { createReactAgent } from '@langchain/langgraph/prebuilt';
import {
  dooorChatGuard,
  PromptInjectionGuard,
  ToxicityGuard,
  LatencyEval,
  AnswerRelevancyEval,
  RAGContext,
  RAGStrategy,
  buildRAGPrompt,
} from "@dooor-ai/toolkit";

@Injectable()
export class AIService {
  private readonly logger = new Logger(AIService.name);

  /**
   * Simple LLM with Guards + Evals
   */
  async askQuestion(question: string) {
    const baseProvider = new ChatGoogleGenerativeAI({
      model: "gemini-2.0-flash-exp",
      apiKey: process.env.GEMINI_API_KEY,
      temperature: 0,
    });

    const llm = dooorChatGuard(baseProvider, {
      apiKey: "cortexdb://your_key@host:8000/my_db",
      providerName: "gemini",
      project: "my-api",
      guards: [
        new PromptInjectionGuard({ threshold: 0.8 }),
        new ToxicityGuard({ threshold: 0.7 }),
      ],
      evals: [
        new LatencyEval({ threshold: 3000 }),
        new AnswerRelevancyEval({ threshold: 0.7 }),
      ],
      observability: true,
    });

    const result = await llm.invoke([
      { role: "user", content: question }
    ]);

    return result;
  }

  /**
   * LangGraph Agent with Tools
   */
  async runAgent(userMessage: string) {
    const baseProvider = new ChatGoogleGenerativeAI({
      model: "gemini-2.0-flash-exp",
      apiKey: process.env.GEMINI_API_KEY,
      temperature: 0,
    });

    const llm = dooorChatGuard(baseProvider, {
      apiKey: "cortexdb://your_key@host:8000/my_db",
      providerName: "gemini",
      project: "agent-api",
      guards: [new PromptInjectionGuard()],
      evals: [new LatencyEval({ threshold: 5000 })],
      observability: true,
    });

    const agent = createReactAgent({
      llm: llm,
      tools: [], // Your tools here
      prompt: `You are a helpful assistant.`,
    });

    const result = await agent.invoke({
      messages: [{ role: "user", content: userMessage }]
    });

    return result;
  }

  /**
   * RAG with Documents (No files needed)
   */
  async ragWithDocuments(query: string) {
    const baseProvider = new ChatGoogleGenerativeAI({
      model: "gemini-2.0-flash-exp",
      apiKey: process.env.GEMINI_API_KEY,
      temperature: 0,
    });

    const llm = dooorChatGuard(baseProvider, {
      apiKey: "cortexdb://your_key@host:8000/my_db",
      providerName: "gemini",
      project: "rag-api",
      guards: [new PromptInjectionGuard()],
      evals: [new LatencyEval({ threshold: 5000 })],
      observability: true,
    });

    // Create RAG context with plain text documents
    const ragContext = new RAGContext({
      documents: [
        {
          content: `
            NestJS Authentication Guide:

            To authenticate users in NestJS:
            1. Install @nestjs/passport and passport-jwt
            2. Create an AuthModule with JwtStrategy
            3. Use @UseGuards(JwtAuthGuard) on protected routes
            4. Store JWT token in Authorization header as "Bearer <token>"

            Example:
            @Post('login')
            async login(@Body() loginDto: LoginDto) {
              const user = await this.authService.validateUser(loginDto);
              return this.authService.generateJwt(user);
            }
          `,
          metadata: { source: 'nestjs-auth-docs' }
        },
        {
          content: `
            Database Configuration in NestJS:

            Use Prisma for type-safe database access:
            1. Install @prisma/client
            2. Define schema in prisma/schema.prisma
            3. Run npx prisma migrate dev
            4. Inject PrismaService in your services
          `,
          metadata: { source: 'nestjs-database-docs' }
        },
      ],
      embeddingProvider: "prod-gemini",
      strategy: RAGStrategy.SIMPLE,
      topK: 3,
      chunkSize: 500,
      chunkOverlap: 100,
    });

    // Build prompt with RAG context
    const promptWithContext = await buildRAGPrompt(query, ragContext);

    this.logger.log(`🔍 RAG Query: ${query}`);
    this.logger.log(`📄 Processing ${ragContext.documents.length} documents`);

    const result = await llm.invoke([
      { role: "user", content: promptWithContext }
    ]);

    this.logger.log('✅ RAG Response received!');

    return result;
  }

  /**
   * RAG with PDF File
   */
  async ragWithPdf(query: string, pdfPath: string) {
    const baseProvider = new ChatGoogleGenerativeAI({
      model: "gemini-2.0-flash-exp",
      apiKey: process.env.GEMINI_API_KEY,
      temperature: 0,
    });

    const llm = dooorChatGuard(baseProvider, {
      apiKey: "cortexdb://your_key@host:8000/my_db",
      providerName: "gemini",
      project: "rag-pdf-api",
      guards: [],
      evals: [new LatencyEval({ threshold: 10000 })],
      observability: true,
    });

    // Read PDF file
    const fs = require('fs').promises;
    const pdfBuffer = await fs.readFile(pdfPath);

    this.logger.log(`📄 PDF loaded: ${pdfPath} (${pdfBuffer.length} bytes)`);

    // Create RAG context with PDF
    const ragContext = new RAGContext({
      files: [
        {
          name: "manual.pdf",
          data: pdfBuffer,
          type: "application/pdf"
        }
      ],
      embeddingProvider: "prod-gemini",
      strategy: RAGStrategy.HYDE, // HyDE for complex queries
      topK: 5,
      chunkSize: 1000,
      chunkOverlap: 200,
    });

    const promptWithContext = await buildRAGPrompt(query, ragContext);

    this.logger.log(`🔍 RAG Query: ${query}`);
    this.logger.log('📊 Strategy: HyDE');

    const result = await llm.invoke([
      { role: "user", content: promptWithContext }
    ]);

    this.logger.log('✅ RAG with PDF completed!');

    return result;
  }

  /**
   * RAG with FUSION Strategy (Best Quality)
   */
  async ragFusion(query: string) {
    const baseProvider = new ChatGoogleGenerativeAI({
      model: "gemini-2.0-flash-exp",
      apiKey: process.env.GEMINI_API_KEY,
      temperature: 0,
    });

    const llm = dooorChatGuard(baseProvider, {
      apiKey: "cortexdb://your_key@host:8000/my_db",
      providerName: "gemini",
      project: "rag-fusion-api",
      guards: [],
      evals: [new LatencyEval({ threshold: 15000 })],
      observability: true,
    });

    const ragContext = new RAGContext({
      documents: [
        {
          content: "Microservices architecture divides applications into small, independent services.",
          metadata: { source: "microservices-101" }
        },
        {
          content: "Monolithic architecture keeps all application logic in a single codebase.",
          metadata: { source: "monolith-101" }
        },
        {
          content: "Service mesh provides observability and traffic management for microservices.",
          metadata: { source: "service-mesh-guide" }
        }
      ],
      embeddingProvider: "prod-gemini",
      strategy: RAGStrategy.FUSION, // FUSION = SIMPLE + HYDE combined
      topK: 5,
    });

    const promptWithContext = await buildRAGPrompt(query, ragContext);

    this.logger.log(`🔍 RAG Query: ${query}`);
    this.logger.log('📊 Strategy: FUSION (SIMPLE + HYDE combined)');

    const result = await llm.invoke([
      { role: "user", content: promptWithContext }
    ]);

    this.logger.log('✅ RAG with FUSION strategy completed!');

    return result;
  }
}
```

### Express.js API (英语)

```typescript
import express from 'express';
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
import { dooorChatGuard, PromptInjectionGuard, LatencyEval } from "@dooor-ai/toolkit";

const app = express();
app.use(express.json());

app.post('/api/chat', async (req, res) => {
  const { message } = req.body;

  const baseProvider = new ChatGoogleGenerativeAI({
    model: "gemini-2.0-flash-exp",
    apiKey: process.env.GEMINI_API_KEY,
  });

  const llm = dooorChatGuard(baseProvider, {
    apiKey: "cortexdb://your_key@host:8000/my_db",
    providerName: "gemini",
    guards: [new PromptInjectionGuard()],
    evals: [new LatencyEval({ threshold: 3000 })],
    observability: true,
  });

  try {
    const result = await llm.invoke([{ role: "user", content: message }]);
    res.json({ response: result.content });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

### 独立脚本

```typescript
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
import { dooorChatGuard, PromptInjectionGuard, LatencyEval } from "@dooor-ai/toolkit";

async function main() {
  const baseProvider = new ChatGoogleGenerativeAI({
    model: "gemini-2.0-flash-exp",
    apiKey: process.env.GEMINI_API_KEY,
  });

  const llm = dooorChatGuard(baseProvider, {
    apiKey: "cortexdb://your_key@host:8000/my_db",
    providerName: "gemini",
    guards: [new PromptInjectionGuard()],
    evals: [new LatencyEval({ threshold: 3000 })],
    observability: true,
  });

  const result = await llm.invoke([
    { role: "user", content: "What is the capital of France?" }
  ]);

  console.log(result.content);
}

main();
```

## 其他实例

见 `examples/` 存储器中的目录 :

-   `basic-usage.ts` - 所有特征的完整实例
-   `multi-provider.ts` - 使用不同的LangChain供应商
-   `simple-usage.ts` - 最小设置

## 发展状况

**当前 :** MVP(第1阶段) - 完成

**已完成的特性 :**

-   有生命周期钩子的核心召回处理器
-   供应商-不可知工厂职能
-   快速注射保护、毒性保护、PII保护
-   科斯特瓦尔州莱滕特埃瓦尔
-   CortexDB 整合
-   控制台和 CortexDB 监视后端

**路线图(第二阶段):**

-   相关性(基于LLM的质量评分)
-   幻觉Eval( 发现虚假信息)
-   CortexDB 工作室的 Dashboard UI
-   Python SDK 键盘
-   增派警卫和保镖

## 许可证

麻省理工学院

## 链接

-   国家预防机制:https://www.npmjs.com/package/@dooor-ai/toolkit
-   GitHub : (中文(简体) ) [https://github.com/dooor-ai/toolkit (英语)](https://github.com/dooor-ai/toolkit)
-   联合国 [https://github.com/dooor-ai/toolkit/docs. 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/dooor-ai/toolkit/docs)
-   问题: [https://github.com/dooor-ai/toolkit/issues (中文(简体) )](https://github.com/dooor-ai/toolkit/issues)

## 常见问题

### @dooor-ai/toolkit 是什么？

Guards, Evals & Observative for AI 应用程序的可观察性——与LangChain/LangGraph无缝合作

### 如何安装 @dooor-ai/toolkit？

在项目目录运行 npm install @dooor-ai/toolkit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@langchain/core（^0\.3\.0 \|\| ^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dooor-ai/toolkit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dooor-ai/toolkit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dooor-ai/toolkit 可以商用吗？

@dooor-ai/toolkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dooor-ai/toolkit 的下载量有多少？

根据 npm 官方下载统计，@dooor-ai/toolkit 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,101 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dooor-ai/toolkit 还在维护吗？

最新版本 0\.1\.62 发布于 2026/04/20（6 个月前）；至今共发布 63 个版本，其中过去 12 个月发布了 20 个；首次发布于 2025/11/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。