# @cascadeflow/core 中文文档

规范地址：https://npmcn.com/package/%40cascadeflow/core/

版本：1\.1\.0
npm 元数据更新时间：2026-03-08T16:53:49.205Z
中文译文更新时间：2026-11-09T08:48:13.750Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.5 MB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- peer 依赖：@anthropic-ai/sdk ^0\.30\.0，@huggingface/inference ^2\.8\.0，@huggingface/transformers ^3\.0\.0，groq-sdk ^0\.5\.0，openai ^4\.0\.0
- 首次发布：2025-11-06T08:57:50.542Z
- 最新版本发布：2026-03-08T16:53:49.062Z
- 近 30 天下载量：3310（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 8 个）

## 中文简介

级联流 TypeScript 库 - 用于成本优化的智能AI模型串联

## 安装

```sh
npm install @cascadeflow/core
```

也可以使用：`pnpm add @cascadeflow/core`、`yarn add @cascadeflow/core`、`bun add @cascadeflow/core`

## README

![cascadeflow Logo](https://npmcn.com/package/.github/assets/CF_logo_dark.svg)

# @ cascadeflow/ core (中文(简体) )

[![npm version](https://img.shields.io/npm/v/@cascadeflow/core?color=red&label=npm)](https://www.npmjs.com/package/@cascadeflow/core) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://npmcn.com/package/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![Tests](https://github.com/lemony-ai/cascadeflow/actions/workflows/test.yml/badge.svg)](https://github.com/lemony-ai/cascadeflow/actions/workflows/test.yml)

 **![TypeScript](https://npmcn.com/package/.github/assets/CF_ts_color.svg) 用于级联流的Script/JavaScript 库**

* * *

**智能AI模式串联成本优化.**

在LLM上节省了40-85%的成本,并配有智能模型路由. 可用于Node.js,浏览器,和边缘环境.

## 安装

```bash
npm install @cascadeflow/core
# or
pnpm add @cascadeflow/core
# or
yarn add @cascadeflow/core
```

## 机能快速启动( V2.1)

```typescript
import { cascadeflow } from '@cascadeflow/core';

// 1) Turn on in-process harness decisions + SDK auto-instrumentation
cascadeflow.init({ mode: 'enforce', budget: 0.5 });

// 2) Scope one run (global defaults are inherited)
const result = await cascadeflow.run({ maxToolCalls: 8 }, async (run) => {
  // Any OpenAI / Anthropic SDK calls made here are evaluated by the harness.
  return { runId: run.runId };
});

console.log(result);
```

## 快速启动

### 建议设置( Claude Haiku + GPT-5)

```typescript
import { CascadeAgent } from '@cascadeflow/core';

const agent = new CascadeAgent({
  models: [
    {
      name: 'claude-haiku-4-5',
      provider: 'anthropic',
      cost: 0.001  // Fast, high-quality drafter
    },
    {
      name: 'gpt-5',
      provider: 'openai',
      cost: 0.00125  // Superior reasoning verifier (50% cheaper than GPT-4o!)
    }
  ]
});

const result = await agent.run('What is artificial intelligence?');

console.log(result.content);
console.log(`Cost: $${result.totalCost}`);
console.log(`Savings: ${result.savingsPercentage}%`);
```

### 质量配置

当级联使用具有质量阈值的起草者与核查者时控制:

```typescript
// Recommended: Complexity-aware thresholds
const agent = new CascadeAgent({
  models: [
    { name: 'claude-haiku-4-5', provider: 'anthropic', cost: 0.001 },
    { name: 'gpt-5', provider: 'openai', cost: 0.00125 }
  ],
  quality: {
    confidenceThresholds: {
      simple: 0.6,      // "What is Python?" - Accept 60%+ confidence
      moderate: 0.7,    // "Compare Python vs Java" - Accept 70%+
      hard: 0.8,     // "Analyze quantum computing" - Accept 80%+
      expert: 0.85      // "Implement distributed cache" - Accept 85%+
    }
  }
});
```

**快速配置选项 :**

```typescript
// Option 1: Use CASCADE_QUALITY_CONFIG (optimized for 50-60% acceptance)
import { CascadeAgent, CASCADE_QUALITY_CONFIG } from '@cascadeflow/core';
const agent = new CascadeAgent({
  models: [...],
  quality: CASCADE_QUALITY_CONFIG  // Lower threshold (0.40) = more cost savings
});

// Option 2: Simple flat threshold
const agent = new CascadeAgent({
  models: [...],
  quality: {
    threshold: 0.7,              // 70% confidence required (default)
    requireMinimumTokens: 10     // Minimum response length
  }
});

// Option 3: Use defaults (no quality config needed)
const agent = new CascadeAgent({
  models: [...]
  // Automatically uses threshold: 0.7
});
```

**何时调整 :**

-   **下限(0.4-0.6)**:接受更多的草案 ——节省费用,质量略低
-   **更高的阈值(0.8-0.9)**:接受的草稿较少 ——节省较少,质量最高
-   **复杂意识**: 最佳平衡 = 根据查询难度自动调整

> **GPT-5要求组织核查**
> 
> 要使用 GPT-5, 您的 OpenAI 组织必须经过验证 :
> 
> 1.  转到 [https://platform.openai.com/ settings/organization/general (中文(简体) )](https://platform.openai.com/settings/organization/general)
> 2.  点击“ 验证组织”
> 3.  等待 ~ 15 分钟, 访问传播
> 
> **立即动工:** 上面的级联马上起作用! Claude Haiku处理75%的询问,GPT-5只在需要时打电话.

> **型号命名**
> 
> 两项命名公约都与CascadeFlow合作:
> 
> -   `claude-haiku-4-5` (用于预设,建议)
> -   `claude-3-5-haiku-20241022` (Anthropic API格式) (中文(简体) )
> 
> 库既接受格式,又正确引导.

### 仅限 OpenAI

```typescript
const agent = new CascadeAgent({
  models: [
    { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015 },
    { name: 'gpt-5', provider: 'openai', cost: 0.00125 }  // Requires org verification
  ]
});
```

### 甚至轻松: 使用预设

**不需要配置** - 只需导入一个预设 然后去:

```typescript
import { CascadeAgent, PRESET_ULTRA_FAST, PRESET_BEST_OVERALL } from '@cascadeflow/core';

// Ultra-fast with Groq (5-10x faster than OpenAI)
const agent = new CascadeAgent(PRESET_ULTRA_FAST);

// Or best overall (Claude Haiku + GPT-4o-mini)
const agent = new CascadeAgent(PRESET_BEST_OVERALL);

const result = await agent.run('Your query here');
```

**可用的预设 :**

| 预设 | 最佳服务 | 速度 | 费用/查询 | API 密钥 |
| --- | --- | --- | --- | --- |
| `PRESET_BEST_OVERALL` | 多数使用案例 | 快 (~2-3s) (英语) | ~ 0.0008美元(美元) | 人类 + OpenAI |
| `PRESET_ULTRA_FAST` | 实时应用程序 | 超快(~1-2s) | ~ 0.0002美元(美元) | 格罗克 |
| `PRESET_ULTRA_CHEAP` | 高容量 | 非常快(~1-3s) | ~0.008美元(美元) | 格罗克+ OpenAI |
| `PRESET_OPENAI_ONLY` | 单一提供者 | 快 (~2-4s) (英语) | ~ 0.04美元(美元) | 开放AI |
| `PRESET_ANTHROPIC_ONLY` | 克劳德球迷 | 快 (~2-3s) (英语) | ~0.002美元(美元) | 安东尼 |
| `PRESET_FREE_LOCAL` | 隐私/离线 | 中度( ~ 3-5s) | 0美元(免费) | 无( 奥巴马) |

**自定义预设 :**

```typescript
import { CascadeAgent, createPreset } from '@cascadeflow/core';

const agent = new CascadeAgent(
  createPreset({
    quality: 'strict',      // 'cost-optimized' | 'balanced' | 'strict'
    performance: 'fast',    // 'fast' | 'balanced' | 'reliable'
    includePremium: true    // Add premium tier (gpt-4o)
  })
);
```

## 高级特性

### QQ 质量简介

控制质量验证, 并优化预定义配置文件, 用于不同的使用情形 :

```typescript
import { CascadeAgent, QualityValidator } from '@cascadeflow/core';

// Strict Mode: Maximum quality with semantic validation
const strictAgent = new CascadeAgent({
  models: [...],
  cascade: {
    enabled: true,
    qualityConfig: {
      useProductionConfidence: true,
      strictMode: true,
      useSemanticValidation: true,
      minConfidence: 0.85,
      provider: 'openai',
    },
  },
});

// Or use factory methods
const strictValidator = QualityValidator.strict();
const prodValidator = QualityValidator.forProduction();    // Multi-signal confidence
const devValidator = QualityValidator.forDevelopment();     // Lenient for testing
const cascadeValidator = QualityValidator.forCascade();     // Optimized for 50-60% acceptance
const permissiveValidator = QualityValidator.permissive();  // Maximum throughput
```

**可用的配置文件 :**

-   **严格**: 85% 置信度+语义验证(最大质量)
-   **生产**: 70%的置信度与多信号估计(平衡)
-   **发展**: 50% 置信度, 最小字数( 快速重排)
-   **连锁店**: 40%的置信度,优化以节省费用(50-60%的接受草案)
-   **允许性**:30%的信心,最大吞吐量(最高储蓄)

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/quality-profiles.ts)

### 遥测和召回

以事件驱动调用监视级联操作 :

```typescript
import { CascadeAgent, CallbackManager, CallbackEvent } from '@cascadeflow/core';

const callbackManager = new CallbackManager(true); // verbose=true

// Track query lifecycle
callbackManager.register(CallbackEvent.QUERY_START, (data) => {
  console.log(`Query started: "${data.query}"`);
});

callbackManager.register(CallbackEvent.COMPLEXITY_DETECTED, (data) => {
  console.log(`Complexity: ${data.data.complexity} (confidence: ${data.data.confidence})`);
});

callbackManager.register(CallbackEvent.DRAFT_ACCEPTED, (data) => {
  console.log(`Draft accepted! Savings: $${data.data.savings}`);
});

const agent = new CascadeAgent({
  models: [...],
  callbacks: callbackManager,
  cascade: { enabled: true },
});
```

**可用事件 :**

-   `QUERY_START` 编号 : `QUERY_COMPLETE` - 查询生命周期
-   `COMPLEXITY_DETECTED` - 查询复杂性分析
-   `CASCADE_DECISION` - 例行决定
-   `QUALITY_VALIDATION` - 质量检查
-   `DRAFT_ACCEPTED` 编号 : `DRAFT_REJECTED` - 结果草案
-   `VERIFIER_CALLED` - 验证者援引

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/telemetry-callbacks.ts)

### 批处理

处理多个查询,包括进度跟踪和分析:

```typescript
const queries = [
  'What is TypeScript?',
  'Explain async/await.',
  'What are design patterns?',
];

const batchResult = await agent.runBatch(queries, {
  strategy: BatchStrategy.SEQUENTIAL,
  continueOnError: true,
  onProgress: (completed, total, currentQuery) => {
    console.log(`[${(completed/total*100).toFixed(0)}%] ${completed}/${total}`);
  },
});

// Analyze results
console.log(`Success rate: ${(batchResult.successCount / queries.length * 100).toFixed(1)}%`);
console.log(`Total cost: $${batchResult.results.reduce((sum, r) => sum + (r.result?.totalCost || 0), 0)}`);
console.log(`Draft acceptance: ${batchResult.results.filter(r => r.result?.draftAccepted).length}`);
```

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/batch-processing.ts)

### QQ 路由器集成

具有复杂性分析和能力过滤功能的智能路由:

```typescript
// PreRouter: Automatically routes based on query complexity
const simpleResult = await agent.run('What is 2 + 2?');
// → Uses draft model (simple query)

const complexResult = await agent.run(
  'Explain quantum computing theory with recent research references.'
);
// → Routes directly to best model (complex query)

// ToolRouter: Filters to tool-capable models
// Use a strict parser helper (see examples/nodejs/safe-math.ts).
const calculatorTool = createTool({
  name: 'calculator',
  description: 'Perform calculations',
  function: async ({ expression }) => safeCalculateExpression(expression),
});

const toolResult = await agent.run('Calculate 125 * 47', {
  tools: [calculatorTool],
});
// → Automatically excludes models without tool support

// Get router statistics
const stats = agent.getRouterStats();
console.log(stats.preRouter);  // Complexity-based routing stats
console.log(stats.toolRouter);  // Tool filtering stats
```

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/router-integration.ts)

### QQ 用户配置和工作流程

管理用户级别、预算和优化偏好:

```typescript
import { createUserProfile, createWorkflowProfile, TIER_PRESETS, WORKFLOW_PRESETS } from '@cascadeflow/core';

// Tier-based profiles
const freeProfile = createUserProfile({
  tier: TIER_PRESETS.free,  // Max budget: $0.01, Quality: 0.60
});

const premiumProfile = createUserProfile({
  tier: TIER_PRESETS.premium,  // Max budget: $0.10, Quality: 0.80
});

// Custom profile with optimization weights
const customProfile = createUserProfile({
  tier: { name: 'custom', maxBudget: 0.05, qualityThreshold: 0.75 },
  optimizationWeights: {
    cost: 0.5,    // 50% weight on cost
    speed: 0.3,   // 30% weight on speed
    quality: 0.2, // 20% weight on quality
  },
});

// Latency-aware profiles
const lowLatencyProfile = createUserProfile({
  tier: TIER_PRESETS.premium,
  latencyProfile: {
    maxTotalMs: 2000,      // 2 second total limit
    maxPerModelMs: 1000,   // 1 second per model
    preferParallel: true,  // Prefer parallel execution
    skipCascadeThreshold: 1500,
  },
});

// Use with agent
const agent = new CascadeAgent({
  models: [...],
  profile: premiumProfile,
  cascade: { enabled: true },
});
```

**工作流程预设 :**

-   `WORKFLOW_PRESETS.production` - 高质量、合理的长期性
-   `WORKFLOW_PRESETS.realtime` - 超低纬度,单一型号
-   `WORKFLOW_PRESETS.batch` - 最大吞吐量,放松约束

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/user-profiles-workflows.ts)

### 工厂方法

以自动配置方式简化代理创建 :

```typescript
import { CascadeAgent } from '@cascadeflow/core';

// Auto-detect providers from environment variables
const envAgent = CascadeAgent.fromEnv({
  quality: 'production',  // 'strict' | 'production' | 'development'
});
// Checks for: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, etc.

// Create from user profile
const profileAgent = CascadeAgent.fromProfile({
  profile: premiumProfile,
  preferredModels: ['gpt-4o-mini', 'gpt-4o', 'claude-3-5-haiku-20241022'],
});

// Traditional manual configuration (full control)
const manualAgent = new CascadeAgent({
  models: [
    { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015 },
    { name: 'gpt-4o', provider: 'openai', cost: 0.00625 },
  ],
  cascade: { enabled: true },
});
```

**福利:**

-   `fromEnv()`: 可用的自动检测提供者, 合理的默认
-   `fromProfile()`: 多租户应用程序,每个用户配置
-   手动配置:全面控制生产需求

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/factory-methods.ts)

### \* 强化流式

事件驱动、实时进展的流出:

```typescript
const stream = agent.streamEvents('What is TypeScript?', {
  forceDirect: true,
});

for await (const event of stream) {
  switch (event.type) {
    case StreamEventType.START:
      console.log(`Streaming from: ${event.data.model}`);
      break;
    case StreamEventType.CHUNK:
      process.stdout.write(event.data.content);
      break;
    case StreamEventType.COMPLETE:
      console.log(`\nCost: $${event.data.totalCost?.toFixed(6)}`);
      console.log(`Time: ${event.data.timing?.total}ms`);
      break;
    case StreamEventType.ERROR:
      console.error(`Error: ${event.data.error}`);
      break;
  }
}

// Or collect the full result
import { collectResult } from '@cascadeflow/core';
const result = await collectResult(stream);
console.log(`Content: ${result.content}`);
console.log(`Model: ${result.modelUsed}`);
```

**使用大小写 :**

-   交互式聊天应用程序
-   实时内容生成
-   渐进内容显示
-   长式内容(文章、散文)

[\* 完整实例](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/enhanced-streaming.ts)

## 特征

-   🎯 **智能分层**: 先自动尝试较小的模型
-   💰 **成本优化**: LLM 成本节省40-85%
-   ⚡ **快点**: 2- 10x 用小型模型更快的响应
-   🔀 **多服务**: OpenAI、Anthropic、Groq 和更多
-   ✅ **质量验证**: 有语义分析的多信号置信度
-   📊 **遥测**: 事件驱动的监测与回调
-   📦 **批处理**: 有分析的顺序处理
-   🔀 **智能运行**: 复杂和能力意识
-   👤 **用户配置文件**:基于等级的出入控制和预算
-   🌊 **强化流化**: 事件驱动的流出和进展
-   🏭 **工厂方法**: 以自动配置简化设置
-   📈 **费用追踪**: 详细的计量和节约分析

## 实例

所有实例均载于 [`examples/nodejs`](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs) 目录 :

-   [**质量简介.ts**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/quality-profiles.ts) - 质量鉴定概况(限制、生产、开发、级联、允许)
-   [**遥测回调**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/telemetry-callbacks.ts) - 事件驱动的监测和召回
-   [**批处理.ts**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/batch-processing.ts) - 附有进度跟踪的批处理
-   [**路由器-集成.ts**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/router-integration.ts) - 鲁特前与工具鲁特结合
-   [**用户配置-工作流程**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/user-profiles-workflows.ts) - 用户简介、层级和工作流程
-   [**工厂方法**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/factory-methods.ts) - 工厂方法(来自Env,来自Profile)
-   [**增强流化.ts**](https://npmcn.com/package/%40cascadeflow/core/examples/nodejs/enhanced-streaming.ts) - 随着活动而加强流动

以 :

```bash
npx tsx examples/nodejs/<example-name>.ts
```

## 文档

见 [主要级联流文件](https://github.com/lemony-ai/cascadeflow) 为完整的指南和实例.

## 许可证

麻省理工学院莱莫尼公司.

## 常见问题

### @cascadeflow/core 是什么？

级联流 TypeScript 库 - 用于成本优化的智能AI模型串联

### 如何安装 @cascadeflow/core？

在项目目录运行 npm install @cascadeflow/core，或使用 pnpm add / yarn add / bun add。

### @cascadeflow/core 支持 TypeScript 吗？

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

### @cascadeflow/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cascadeflow/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cascadeflow/core 可以商用吗？

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

### @cascadeflow/core 的下载量有多少？

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

### @cascadeflow/core 还在维护吗？

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