# @flutchai/flutch-sdk 中文文档

规范地址：https://npmcn.com/package/%40flutchai/flutch-sdk/

版本：0\.7\.16
npm 元数据更新时间：2026-11-04T11:22:41.505Z
中文译文更新时间：2026-11-15T02:25:55.670Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.4 MB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：18 个
- peer 依赖：ioredis ^5\.3\.0，mongoose ^8\.0\.0，prom-client ^14\.0\.0 \|\| ^15\.0\.0，@nestjs/core ^10\.0\.0 \|\| ^11\.0\.0，@nestjs/axios ^4\.0\.0，@nestjs/common ^10\.0\.0 \|\| ^11\.0\.0，@nestjs/config ^3\.0\.0 \|\| ^4\.0\.0，@nestjs/swagger ^7\.0\.0 \|\| ^11\.0\.0，@nestjs/mongoose ^10\.0\.0 \|\| ^11\.0\.0，@nestjs/terminus ^10\.0\.0 \|\| ^11\.0\.0，reflect-metadata ^0\.2\.0，@nestjs/platform-express ^10\.0\.0 \|\| ^11\.0\.0，@willsoto/nestjs-prometheus ^5\.0\.0 \|\| ^6\.0\.0
- 首次发布：2025-10-30T23:50:19.183Z
- 最新版本发布：2026-11-04T11:22:41.118Z
- 近 30 天下载量：4614（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 68 个）

## 中文简介

用于构建图表微服务的基础基础设施包 -- -- 核心接口、类型、公用事业和执行引擎

## 安装

```sh
npm install @flutchai/flutch-sdk
```

也可以使用：`pnpm add @flutchai/flutch-sdk`、`yarn add @flutchai/flutch-sdk`、`bun add @flutchai/flutch-sdk`

## README

# @flutchai/flutch-sdk (英语)

与LangGraph和NestJS共同建设图形微服务的基础基础设施包.

## 概览

`@flutchai/flutch-sdk` 是一个自成一体的一揽子基础 **将您的图形逻辑转换为生产准备的微服务**。写出您的图形构建器,SDK处理其他一切:REST API,流线,健康检查,度量衡,回调,和版本.

SDK的设计是 **框架不可知性** - 虽然它目前为有NestJS的LangGraph.js提供一等支持,但该架构允许在未来支持其他图表框架(LlamaIndex,自定义执行等).

## 包含什么

### 核心组成部分

-   **通用图形模块** - 用于拖曳图服务的NestJS模块
-   **抽象图形构建器** - 用于实施图表构建器的基础类
-   **图形控制器** - 有标准终点的REST API控制器
-   **回调控制器** - 交互式流动回调系统

### 接口类型( T)

-   **IGraph 服务** - 所有图表服务的标准接口
-   **IGraph 请求支付负荷** 编号 : **IGraph 反应负载** - 请求/答复合同
-   **IGraphRunnable 图形** - 图表执行配置
-   **回调记录** 编号 : **召回结果** - 回调系统类型
-   **图表类型登记册** - 类型安全图定义

### 引擎组件

-   **兰格芬** - LangGraph.js的整合
-   **事件处理器** - 利用收集的衡量尺度对事件进行流处理
-   **ApiCall追踪器** - API呼叫追踪和消毒设施

### 校验 & Schemas

-   **图表管理方案** - JSON Schema的图表清单
-   **图表管理参数** - 明确验证公用事业

### 公用事业

-   **图形TypeUtils** - 版本分析和正常化
    -   解析 : `global.simple::1.2.0` → `{ companyId, name, version }`
    -   构建 : `build("global", "simple", "1.2.0")` → `global.simple::1.2.0`
    -   规范化: 处理遗留格式

### 回调系统

交互式用户流动的完整回调基础设施:

-   基于托肯的回调注册
-   ACL和安全检查
-   同上:
-   平台专用处理器(Web,Telegram)
-   审计记录

## 安装

```bash
npm install @flutchai/flutch-sdk
```

或者说

```bash
yarn add @flutchai/flutch-sdk
```

## 快速启动

SDK提供所有你需要的 快速启动生产准备图服务。 使用最小的设置,您可以得到一个功能完备的 NestJS 应用程序,与 REST API, 健康检查, 度量衡等等.

### 1\. 创建您的图形构建器

```typescript
import { Injectable } from "@nestjs/common";
import { AbstractGraphBuilder } from "@flutchai/flutch-sdk";
import { StateGraph, START, END } from "@langchain/langgraph";

@Injectable()
export class MyGraphBuilder extends AbstractGraphBuilder<"myGraph"> {
  async buildGraph(config?: any): Promise<CompiledGraphFor<"myGraph">> {
    // Define your graph logic
    const graph = new StateGraph(MyState)
      .addNode("process", async state => {
        // Your processing logic
        return { result: "processed" };
      })
      .addEdge(START, "process")
      .addEdge("process", END)
      .compile();

    return graph;
  }
}
```

### 2\. 登记模块

```typescript
import { Module } from "@nestjs/common";
import { UniversalGraphModule } from "@flutchai/flutch-sdk";

@Module({
  imports: [
    UniversalGraphModule.register({
      graphType: "myGraph",
      builder: MyGraphBuilder,
    }),
  ],
})
export class AppModule {}
```

### 3\. 启动您的申请

```typescript
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();
```

就这样! 您的图形服务正在运行, 并有一个完整的 REST API .

## 你从盒子里得到什么

一旦你的服务运行,你就自动得到:

### REST API 终点

SDK为即用控制器提供标准终点:

#### 图表执行( E)`GraphController`(中文(简体) )

-   `GET /health` - 服务健康检查
-   `GET /graph-types` - 列表支持的图表类型
-   `POST /generate` - 非分流发电
-   `POST /stream` - 服务器事件流
-   `POST /cancel/:requestId` - 取消运行中的生成
-   `GET /registry` - 查看已注册的图表
-   `GET /registry/stats` - 书记官处统计

#### 回调( N)`CallbackController`(中文(简体) )

-   `POST /callback` - 以象征性安全方式处理用户回调

#### UI 调度`UIDispatchController`(中文(简体) )

-   `POST /api/graph/ui/dispatch` - 向自定义 UI 端点发送请求
-   `GET /api/graph/:graphType/manifest` - 用 UI 配置来显示图表
-   `GET /api/graph/:graphType/endpoints` - 列出可用的 UI 端点
-   `GET /api/graph/catalog` - 获取所有图表的目录

### 监测和可观察性

-   普罗米修斯度量衡 `/metrics`
-   健康检查 `@nestjs/terminus`
-   请求/答复记录
-   API 呼叫跟踪与消毒

### 生产特点

-   头盔安全头
-   压缩中间软件
-   重新支持的回调系统
-   OpenAPI/ Swagger 文档
-   处理和验证出错

## API 使用示例

### 非结构化一代

```bash
curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req-123",
    "graphType": "myGraph",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'
```

### 流出生成( SSE)

```bash
curl -X POST http://localhost:3000/stream \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req-456",
    "graphType": "myGraph",
    "messages": [
      { "role": "user", "content": "Tell me a story" }
    ]
  }'
```

流返回 Server- Sent 事件 :

```
event: stream_event
data: {"type":"chunk","content":"Once upon"}

event: stream_event
data: {"type":"chunk","content":" a time"}

event: final
data: {"text":"Once upon a time...","attachments":[],"metadata":{}}
```

### 检查健康

```bash
curl http://localhost:3000/health
# Response: {"status":"healthy","timestamp":"2025-11-03T12:00:00.000Z"}
```

### 查看已注册的图表

```bash
curl http://localhost:3000/registry
# Response: {"total":1,"graphs":[{"graphType":"myGraph","builderName":"MyGraphBuilder"}]}
```

## 高级使用

### 使用多种工具查找代理工具

每一个绑定工具的图案 都被发送到每个回合。 有几十种工具是最快的,模型选择错误的工具往往超过30-50个。 打开工具搜索, 模型看到一些工具加 `search_tools`当任务需要时,找到其余的:

```typescript
import { isToolSearchCall } from "@flutchai/flutch-sdk";

const modelConfig = {
  modelId,
  toolsConfig,
  toolSearch: { enabled: true, alwaysLoaded: ["list_sites", "list_products"] },
};
const model = await modelInitializer.initializeChatModel(modelConfig);

// In the tools node: search runs in the SDK, against the same catalog.
if (isToolSearchCall(toolCall.name)) {
  const { content } = await modelInitializer.searchTools(
    modelConfig,
    toolCall.args,
    config
  );
  messages.push(
    new ToolMessage({ content, tool_call_id: toolCall.id, name: toolCall.name })
  );
}
```

将相同的配置传递给 `searchTools` 这个模型是用来命名目录的。 所找到的工具是从对话历史中读取的,所以图表没有额外状态. Claude通过Anthropic Messages API加载找到工具作为延后定义(`defer_loading` + 键 `tool_reference`),并保持即时缓存;其他提供方将核心工具加所找到的工具各转. `alwaysLoaded` 又取逗号分隔的字符串; `maxResults` (违约5)和 `minTools` (默认15)调取.

### 使用图形TypeUtils

```typescript
import { GraphTypeUtils } from "@flutchai/flutch-sdk";

// Parse versioned graph types
const parsed = GraphTypeUtils.parse("global.simple::1.2.0");
// → { companyId: "global", name: "simple", version: "1.2.0" }

// Build graph type string
const fullType = GraphTypeUtils.build("company-123", "customRag", "2.0.0");
// → "company-123.customRag::2.0.0"

// Normalize legacy formats
const normalized = GraphTypeUtils.normalize("simple");
// → "global.simple"

// Extract version
const version = GraphTypeUtils.getVersion("global.rag::1.5.0");
// → "1.5.0"
```

### 验证图示

```typescript
import { GraphManifestValidator } from "@flutchai/flutch-sdk";

const manifest = {
  graphType: "myGraph",
  title: "My Custom Graph",
  description: "Does cool things",
  // ... other fields
};

// Validate and get result
const result = GraphManifestValidator.validate(manifest);
if (!result.isValid) {
  console.error(result.errors);
}

// Or throw on invalid
GraphManifestValidator.validateOrThrow(manifest);
```

### 处理串流事件

```typescript
import { EventProcessor, StreamAccumulator } from "@flutchai/flutch-sdk";

@Injectable()
export class MyService {
  constructor(private eventProcessor: EventProcessor) {}

  async processStream(stream: any): Promise<IGraphResponsePayload> {
    const accumulator = this.eventProcessor.createAccumulator();

    for await (const event of stream) {
      this.eventProcessor.processEvent(
        accumulator,
        event,
        chunk => console.log(chunk) // Partial callback
      );
    }

    return this.eventProcessor.getResult(accumulator);
  }
}
```

## 建筑

### 软件包结构

```
src/
├── api/              # REST controllers and guards
├── bootstrap.ts      # Service bootstrap utilities
├── callbacks/        # Callback system implementation
├── core/             # Core modules and builders
├── decorators/       # Custom decorators
├── endpoint-registry # Endpoint registration
├── engine/           # Graph execution engines
├── interfaces/       # TypeScript interfaces
├── schemas/          # JSON schemas
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
└── versioning/       # Version management
```

### 依赖关系

软件包没有内部依赖性,只依赖完善的外部库:

-   `@nestjs/*` - 建立可扩展服务器侧应用程序的NestJS框架
-   `@langchain/*` - LLM集成和图解的LangChain生态系统
-   `ioredis` - Redis客户端用于回调系统和缓存
-   `axios` - 用于外部API呼叫的HTTP客户端
-   `zod` - TypeScript- first schema 验证
-   `helmet`, (中文(简体) ), `compression` - HTTP安全和性能中间软件

### 设计原则

1.  **自成一体** - 没有内部依赖,你需要的都是一个包
2.  **类型安全** - 所有组件的综合类型脚本定义
3.  **模块** - 只使用您需要的, 导入特定模块
4.  **生产准备** - 内部监测、健康检查和错误处理
5.  **框架整合** - 与LangGraph合并的无缝巢穴JS

## 快速启动

```typescript
import {
  UniversalGraphModule,
  AbstractGraphBuilder,
} from "@flutchai/flutch-sdk";
import { Module } from "@nestjs/common";

@Injectable()
export class MyGraphBuilder extends AbstractGraphBuilder<"myGraph"> {
  async buildGraph(config?: any) {
    // Your LangGraph implementation
    return compiledGraph;
  }
}

@Module({
  imports: [
    UniversalGraphModule.register({
      graphType: "myGraph",
      builder: MyGraphBuilder,
    }),
  ],
})
export class MyGraphModule {}
```

您的图表服务已经准备好 内置的REST API,健康检查,以及监控!

## API 密码

### 主要出口

```typescript
// Core
export { UniversalGraphModule, AbstractGraphBuilder };

// Interfaces
export {
  IGraphService,
  IGraphRequestPayload,
  IGraphResponsePayload,
  CallbackRecord,
  CallbackResult,
};

// Engine
export { LangGraphEngine, EventProcessor, ApiCallTracer };

// Utilities
export { GraphTypeUtils, GraphManifestValidator };

// Types
export { IGraphTypeRegistry, CompiledGraphFor, BaseGraphState };
```

见 `src/index.ts` 用于完整导出列表.

## 发展

### 大楼

```bash
npm run build
```

### 测试

```bash
npm test
```

### 线性

```bash
npm run lint
```

## 特征

-   **准备使用 NestJS 模块** 图表服务
-   **类型安全图定义** 有类型脚本
-   **内建的REST API** 带有 OpenAPI 文档
-   **回调系统** 用于交互式用户流量
-   **流程处理** 有实时活动
-   **健康检查** 和普罗米修斯度量衡
-   **重新调整整合** 召回和缓存
-   **多LLM支持** (OpenAI, Anthropic, Azure, Google, Mistral, Cohere) (英语)
-   **图形版本** 水电费
-   **表面验证** 用于图形配置

## 小蝶平台集成

SDK的设计旨在与 **小蝶平台**,将企业级能力从框出:

### 一行平台连接

```typescript
UniversalGraphModule.register({
  graphType: "myGraph",
  builder: MyGraphBuilder,
  flutch: {
    apiKey: process.env.FLUTCH_API_KEY,
    endpoint: "https://api.flutch.ai",
  },
});
```

### 用蝶式平台获取什么

**追踪和分析( A)**

-   在所有图表中分布追踪
-   业绩计量和瓶颈检测
-   每个请求和模型的成本分析
-   调用跟踪

**多频道用户界面**

-   Web、Telegram、Slack、WhatsApp 支持
-   跨频道的统一UI组件
-   频道特定适应
-   自定义品牌

**治理和控制**

-   限制税率和配额管理
-   用户和公司一级的限制
-   预算控制和警报
-   用法分析

**测试和质量**

-   A/B 图文测试
-   接受测试自动化
-   AI动力测试生成
-   回归测试

**独立运行或与平台运行**

SDK完全独立地进行自我托管的部署,或连接到Fluch平台的高级功能. 你选择.

## 主要惠益

### 即时服务部署

从图表逻辑到几分钟内部署微服务 不需要建立REST API,执行流线,或设置监控 - 都包括在内.

### 图形版本

内建支持版本您的图表 。 同时运行多个版本,测试新版本,安全地滚回.

### 框架的灵活性

目前支持LangGraph.js. (英语). 该架构旨在支持LlamaIndex等其它图表框架,确保您的投资是绝后的.

### 开发者经验

-   带有类型脚本的类型安全图定义
-   开发过程中的热重载
-   OpenAPI/ Swagger 文档自动生成
-   全面处理错误

### 互动能力

-   **回电**: 在图形中添加交互式按钮和用户交互
-   **UI 端点**: 为动态接口创建自定义的 UI 端点
-   **流线**: 与服务器事件实时响应

### 生产准备

-   用于监测的Prometheus计量标准
-   组织健康检查
-   重新支持的国家管理
-   安全头和压缩

## 使用大小写

-   **AI 代理微服务**:部署自主代理作为可扩展服务
-   **对话AI**: 构建聊天机和虚拟助手
-   **RAG 系统**: 执行检索增强的生成工作流程
-   **多步骤工作流程**: 管弦管式复合AI管线
-   **互动助理**: 创建带有回调和动态 UIs的代理

## 出版

软件包自动发布到 [npmjs.org (韩语)](https://www.npmjs.com/package/@flutchai/flutch-sdk) 每次合并时 `main` 通过 GitHub 动作 .

### 如何运作

1.  合并到 `main`,则 [发布工作流程](https://npmcn.com/package/%40flutchai/flutch-sdk/.github/workflows/release.yml) 运行
2.  它读的版本来自 `package.json`
3.  如果一个标记 `v{version}` 尚不存在——它创建了标记并发布到 npm
4.  如果标签已经存在——所有发布步骤都会被跳过( 独有)

出版用途 [npm OIDC 信任出版](https://docs.npmjs.com/generating-provenance-statements) ——不需要npm标志性秘密. GitHub 动作跑道通过 OpenID Connect 直接以 npmjs.org 认证 .

### 规则

-   **合并前跳出版本** 如果 `package.json` 版本匹配已有的 git 标签, 将不发布
-   **使用语义版本** —— 说 `MAJOR.MINOR.PATCH` (例如:. `0.2.14`(中文(简体) )
    -   `PATCH` ——错误修正,小改进
    -   `MINOR` ——新的后向兼容特征
    -   `MAJOR` ——打破更改
-   **每个 PR 一个版本的凸起** ——尽可能将版本修改与功能/固定修改相隔离

### 发布新版本

```bash
# 1. Create a branch
git checkout -b chore/bump-version-X.Y.Z

# 2. Update version in package.json
# "version": "X.Y.Z"

# 3. Push and open a PR
git push origin chore/bump-version-X.Y.Z

# 4. Merge the PR — publishing happens automatically
```

## 链接

-   [GitHub 仓库](https://github.com/flutchai/node-sdk)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@flutchai/flutch-sdk)
-   [问题](https://github.com/flutchai/node-sdk/issues)

## 许可证

麻省理工学院

## 常见问题

### @flutchai/flutch-sdk 是什么？

用于构建图表微服务的基础基础设施包 -- -- 核心接口、类型、公用事业和执行引擎

### 如何安装 @flutchai/flutch-sdk？

在项目目录运行 npm install @flutchai/flutch-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@nestjs/core（^10\.0\.0 \|\| ^11\.0\.0）、@nestjs/common（^10\.0\.0 \|\| ^11\.0\.0）、@nestjs/config（^3\.0\.0 \|\| ^4\.0\.0）、reflect-metadata（^0\.2\.0）、@nestjs/platform-express（^10\.0\.0 \|\| ^11\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flutchai/flutch-sdk 支持 TypeScript 吗？

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

### @flutchai/flutch-sdk 支持 ESM 还是 CommonJS？

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

### @flutchai/flutch-sdk 可以商用吗？

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

### @flutchai/flutch-sdk 的下载量有多少？

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

### @flutchai/flutch-sdk 还在维护吗？

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