# @genkit-ai/middleware 中文文档

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

版本：0\.12\.0
npm 元数据更新时间：2026-11-03T20:51:54.061Z
中文译文更新时间：2026-11-16T03:45:11.199Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.7 MB，108 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：genkit ^1\.44\.0
- 首次发布：2026-04-14T02:57:38.687Z
- 最新版本发布：2026-11-03T20:51:53.896Z
- 近 30 天下载量：27314（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Genkit 的中间软件

## 安装

```sh
npm install @genkit-ai/middleware
```

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

## README

# Genkit 中间软件

这个软件包为Genkit JS SDK提供了一批有用的中间软件,以加强模型执行,工具使用和代理工作流程.

> **用编码代理? 先安装基因组JS技能.**
> 
> ```bash
> npx skills add genkit-ai/skills --skill developing-genkit-js
> ```
> 
> 它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: [技能/技能](https://github.com/genkit-ai/skills)。 。 。 .

## 安装

```bash
npm install @genkit-ai/middleware
# or
pnpm add @genkit-ai/middleware
```

## 可用的中间软件

### 1\. 中间器件`agents`(中文(简体) )

启用子代理授权 。 对于每个已配置的代理,中间软件会注入一个专门的授权工具(例如:. `delegate_to_researcher`和附件 a `<sub-agents>` 块到系统时,立即列出可用的代理及其描述。 当模型调用授权工具时,中间软件从注册处解决目标代理,并通过其运行 `run()` 方法,并返回子剂的反应作为工具结果.

**关键行为 :**

-   喷出 **每个代理人一个代表团工具**名称 `<toolPrefix>_<agentName>` (默认前缀 : `delegate_to`) (中文(简体) ).
-   代理描述是从注册处自动发现的(或可以被推翻的每个代理),并被浮出系统即时.
-   副代理中断和故障被作为工具响应还原(没有抛出),使管弦乐手能够自我修正. (交互,状态回转和被中断的子剂是未来的特点. 结束的回合没有答案(`length`, (中文(简体) ), `blocked`, (中文(简体) ), `aborted`)被报告为错误,命名原因和代理的最后一个消息,成功时没有最终文本表示,并命名其文物计数.
-   副代理文物合并为母会话和(或)回回内线,由 `artifactStrategy`。 。 。 .
-   与 `async: true`,各代表团可以按背景进行,以后再收集(见下文).
-   向副代理人派出代表团 `store` 离开a `taskId` 后面,还有 `continue_task` (见下文).
-   代表团可携带可选文件 `name` 标签、结果、背景任务报告和续作.

**选项 :**

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `agents` | `(string | { name, description? })[]` | ——(需要) | 授权代理 字符串是代理名称;对象表允许您覆盖描述. |
| `toolPrefix` | `string` | `'delegate_to'` | 生成的代表团工具名的前缀 。 设定为 `''` 以使用裸体代理名称。 非空前缀也会给共享工具命名空格(`continue_task` 和背景任务工具),因此一个生成调用的两个实例需要不同的前缀. |
| `maxDelegations` | `number` | 无限制 | 允许每个生成调用的最大副代理代表团。 防止出轨 授权循环. |
| `historyLength` | `number` | `0` | 转发给子代理作为上下文的最近谈话消息(仅使用/模式)的数量 . |
| `artifactStrategy` | `'inline' | 'session'` | `'inline'` | `inline`: 将文物内容列入工具结果 **财务报告和审定财务报表** 合并为主会话. `session`:文物只被合并到母会话(工具结果只列出名称). 对 `session` 与 `artifacts` 中间软件. |
| `async` | `boolean` | `false` | 启用背景代表团: 代表团工具接受 a `background` 立即返回任务标识的旗帜,以及 `check_background_tasks`, (中文(简体) ), `wait_for_background_tasks`,以及 `abort_background_tasks` 增加了工具。 需要用一个 `store`。 。 。 . |
| `maxWaitSeconds` | `number` | 无约束 | 上面绑着一个 `wait_for_background_tasks` 打电话,随便 `timeoutSeconds` ; 在绑定时, 等待返回当前状态 `timedOut` 设置. |

```typescript
import { genkit } from 'genkit';
import { agents } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// Define sub-agents
const researcher = ai.defineAgent({
  name: 'researcher',
  model: 'gemini-flash-latest',
  description: 'Searches the web and summarizes findings.',
  system: 'You are a research assistant.',
  tools: [webSearchTool],
});

const coder = ai.defineAgent({
  name: 'coder',
  model: 'gemini-flash-latest',
  system: 'You are an expert programmer.',
});

// Main orchestrator agent delegates to sub-agents.
// This injects `delegate_to_researcher` and `delegate_to_coder` tools.
const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: 'gemini-flash-latest',
  system: 'Delegate research to the researcher and coding to the coder.',
  use: [
    agents({ agents: ['researcher', 'coder'] })
  ]
});
```

您可以自定义工具名前缀并覆盖描述 :

```typescript
use: [
  agents({
    // Tools become `ask_researcher` and `ask_coder`.
    toolPrefix: 'ask',
    agents: [
      'researcher', // description auto-discovered from the registry
      { name: 'coder', description: 'Writes TypeScript code' }, // explicit override
    ],
    maxDelegations: 5,
    historyLength: 4,
  }),
];
```

设定 `async: true` 让管弦乐手在副代理运行时继续工作 每个代表团工具都得到一个 `background` 返回任务ID而不是等待的旗帜, 三个共享工具给管弦乐手一个控制器, 每一件它可以做的启动的任务: `check_background_tasks` 无需等待即可读取状态, `wait_for_background_tasks` 在他们定居之前 `abort_background_tasks` 阻止那些不再需要结果的人。 这个 _子剂_ 这里需要的是会话存储器:背景工作通过快照跟踪,所以一个子代理没有 `store` 只能同步授权.

```typescript
import { InMemorySessionStore } from 'genkit/beta';

// The sub-agent needs its own store to be delegated to in the background.
const researcher = ai.defineAgent({
  name: 'researcher',
  model: googleAI.model('gemini-flash-latest'),
  description: 'Researches a topic and summarizes well-sourced findings.',
  system: 'You are a thorough research assistant.',
  store: new InMemorySessionStore(),
});

const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: googleAI.model('gemini-flash-latest'),
  system:
    'Delegate research in the background and post an update while it runs.',
  use: [agents({ agents: ['researcher'], async: true })],
});
```

指挥员随即发射 `{ "task": "...", "background": true }`,在子代理运行时发布更新,然后收集结果。 任务标识( N)`<agent>:<snapshotId>`) 代表团工具中的骑行结果,因此它们被记录在谈话中,一个重新证实的管弦乐手可以独自从它的历史中收集. 背景任务工具和 `continue_task` 仅接受本次对话的代表团所携带的任务ID,并继续结果,所以到达模型的文本不能将它们指向另一个对话的任务. `wait_for_background_tasks` 选择 `timeoutSeconds`,因此缓慢的任务变成了临时的答案而不是被阻断的转弯; `maxWaitSeconds` 盖上它,所以一个从未完成的子代理无法将请求打开 . `waitFor: "first"` 将加盟转换成比赛:工具一旦列出的任务完成就立即返回,而其余的任务则继续运行。 流产可以安全地调用任何任务:一个已经完成的任务被单独留下并报告其结果,因此管弦乐团永远不会因为放弃而失去一个答案. 任务实况报告 `aborting` 风吹而下 `aborted` 与它所节省的进展; `wait_for_background_tasks` 跟着它.

解决问题的代表团留下一个可继续的手柄。 A. 具有下列特性的子代理人的代表团结果或背景任务报告 `store` 携带一个 `taskId`,共享 `continue_task` 工具会花掉它。 失败或中止的任务从上次保存的进度继续:没有 `instructions` 执着的转弯将按原样重新尝试 `instructions` 重试被引导。 完成的任务接受子代理自身会话内的后续指令,因此按下永远不重复完成的工作. 与 `async: true`, (中文(简体) ), `continue_task` 还要 `background: true` 并返回同一会话中的新任务ID。 空背景续作是重试的一个例外:一个没有消息的解去会跑不转,所以副代理获得一个简短的"继续从所停止的地方完成任务"的消息取而代之,而其笔录记录下来. 无代理代理代理 `store` 内部和解,没有 `taskId`,并再次授权重排;当没有配置的子代理有商店时,模型不显示 `continue_task`. 中断的任务无法继续。 一个过期的任务(工人已死亡)被用流产来围住,并且从父母的快照中继续,这是在拆卸前最后一次犯下的;一个在做任何事情之前就已经死亡的背景发射没有救赎,工具说要再次授权.

### 2\. 中相器件(`artifacts`(中文(简体) )

提供与会话文物互动的模型工具并注入 `<artifacts>` 输入系统时, 提示每个回合 。 有用的独立(例如作为文物制作文件的工作空间-建设者代理人)或与 `agents` 使用中间软件 `artifactStrategy: 'session'`,因此管弦乐团可以读取由子剂出品的文物.

**提供的工具:**

-   `read_artifact` ——从会话中读出被命名的文物并返回其文本内容.
-   `write_artifact` ——创建或更新被命名的文物(按名称复制). 何时开放 `readonly: true`。 。 。 .

**选项 :**

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `readonly` | `boolean` | `false` | 当真,只有 `read_artifact` 提供了工具. |

```typescript
import { genkit } from 'genkit';
import { agents, artifacts } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// Standalone: an agent that creates and reads artifacts.
const builder = ai.defineAgent({
  name: 'builder',
  model: 'gemini-flash-latest',
  system: 'You are a code generator. Use write_artifact to create files.',
  use: [artifacts()],
});

// Combined with the agents middleware (session strategy).
const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: 'gemini-flash-latest',
  system: 'You coordinate sub-agents and review their work.',
  use: [
    agents({ agents: ['researcher', 'coder'], artifactStrategy: 'session' }),
    artifacts({ readonly: true }), // can read sub-agent artifacts
  ],
});
```

### 3\. FileSystem Middle 软件(`filesystem`(中文(简体) )

通过注入标准文件操作工具,给予模型访问本地文件系统的机会(`list_files`, (中文(简体) ), `read_file`, (中文(简体) ), `write_file`, (中文(简体) ), `search_and_replace`) (中文(简体) ). 所有操作都被安全限制在一个指定的根目录. 注意写入操作需要设置 `allowWriteAccess: true` 在中间软件配置中.

```typescript
import { genkit } from 'genkit';
import { filesystem } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: 'gemini-flash-latest',
  prompt: 'Create a hello world node app in the workspace',
  use: [
    filesystem({ rootDirectory: './workspace', allowWriteAccess: true })
  ]
});
```

### 4\. 技能中间软件`skills`(中文(简体) )

自动扫描目录 `SKILL.md` 文件(和它们的YAML前题)并注入系统即时。 它还规定: `use_skill` 该模型可以用来根据需要检索更具体的技能.

```typescript
import { genkit } from 'genkit';
import { skills } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  prompt: 'How do I run tests in this repo?',
  use: [
    skills({ skillPaths: ['./skills'] })
  ]
});
```

### 5\. 工具核准中间软件`toolApproval`(中文(简体) )

将工具的执行限于核定清单。 如果模型试图调用一个未经批准的工具,它就会扔出一个 `ToolInterruptError` 允许您在恢复前提示用户手动确认 .

```typescript
import { genkit, restartTool } from 'genkit';
import { toolApproval } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// 1. Initial attempt
const response = await ai.generate({
  prompt: 'write a file',
  tools: [writeFileTool],
  use: [
    toolApproval({ approved: [] }) // Empty list means call triggers interrupt
  ]
});

if (response.finishReason === 'interrupted') {
  const interrupt = response.interrupts[0];

  // 2. Ask user for approval, then recreate the tool request with approval
  const approvedPart = restartTool(interrupt, { toolApproved: true });

  // 3. Resume execution
  const resumedResponse = await ai.generate({
    messages: response.messages,
    resume: { restart: [approvedPart] },
    use: [
      toolApproval({ approved: [] })
    ]
  });
}
```

### 6\. 重试中件( E)`retry`(中文(简体) )

在瞬态错误代码上自动重试失败的模型代号( 如 `RESOURCE_EXHAUSTED`, (中文(简体) ), `UNAVAILABLE`)使用与焦躁相伴的指数后退.

```typescript
import { genkit } from 'genkit';
import { retry } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-pro-latest'),
  prompt: 'Heavy reasoning task...',
  use: [
    retry({
      maxRetries: 3,
      initialDelayMs: 1000,
      backoffFactor: 2
    })
  ]
});
```

### 7\. 后退中软件(`fallback`(中文(简体) )

如果主模型在一组特定的出错代码上失败,则自动切换到不同的模型. 当一个大型模型超过配额限制时,它有助于回到一个较小/较快的模型.

```typescript
import { genkit } from 'genkit';
import { fallback } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-pro-latest'),
  prompt: 'Try the pro model first...',
  use: [
    fallback({
      models: [googleAI.model('gemini-flash-latest')], // try flash if pro fails
      statuses: ['RESOURCE_EXHAUSTED']
    })
  ]
});
```

### 8\. 背景压缩中间软件(`contextCompression`(中文(简体) )

当对话增长过大时会压缩对话上下文,减少代理工作流程和工具循环中的象征性使用和成本. 当估计的令牌或先前的转弯用法超过时会触发压缩 `maxInputTokens`。 。 。 .

**实施的战略:**

1.  **安全盖**: 硬调出任何单一的超大小工具响应(`maxToolResponseChars`,默认值:40万个字符) `[TRUNCATED: ...]` 标记.
2.  **复制**: 以短通知取代重复工具回复(`deduplicateToolResponses`) (中文(简体) ).
3.  **工具响应截取**: 超过字符限制的截断工具响应( T)`toolResponses`,保留最新的工具响应信息,并附上 `[Truncated N characters]` 标记.
4.  **信件计数封顶**: 超过时丢弃旧的非系统消息 `maxMessages`,保存系统信息并确保对话历史从用户回合开始.
5.  **总结**: 使用 LLM(`summarize`),可选阈值跳过(`skipSummarizationThreshold`)和动态超射调整.
6.  **汇算预算回落**: 如果调试和工具响应调试不能将上下文带入 `maxInputTokens`,没有摘要可以取代旧消息,旧的非系统消息会降为 `preserveRecent`。 。 。 .
7.  **无损会话历史**: 默认`preserveOriginalMessages: true`),压缩状态保存在消息元数据中(`message.metadata.contextCompression`)而不是修改原信息。 模型调用在会话和UI日志保留完整原始消息的同时接收压缩视图. 使用 `resolveCompressedHistory(messages)` 以提取活动信件.

> **顺序符 :** 组合时 `contextCompression` 与上下文输入的中间软件(例如 `filesystem()`, (中文(简体) ), `skills()`,或 `artifacts()`),地点 `contextCompression` **之后** 那些中间的软件 `use: [...]` 因此,它们的被注入指令和工具输出在压缩时被核算.

```typescript
import { genkit } from 'genkit';
import { contextCompression, resolveCompressedHistory } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-flash-latest'),
  prompt: 'Research and summarize...',
  tools: [searchTool],
  use: [
    contextCompression({
      maxInputTokens: 80000,
      deduplicateToolResponses: { matchBy: 'name-and-input' },
      toolResponses: { maxChars: 2000, preserveRecent: 2 },
      summarize: {
        model: googleAI.model('gemini-flash-lite-latest'),
        preserveRecent: 6,
      },
      skipSummarizationThreshold: 0.25, // Skip LLM summary if cheap strategies save >= 25%
      preserveOriginalMessages: true, // Non-destructive (default)
      maxMessages: 20,
    }),
  ],
});

// Original uncompressed history is preserved in response.messages:
console.log(response.messages.length);

// Resolve the active compressed messages sent to the model:
const activeMessages = resolveCompressedHistory(response.messages);
```

#### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `maxInputTokens` | `number` | `Infinity` | 当令牌计数超过此阈值时触发压缩 . |
| `preserveRecent` | `number` | `4` | 丢弃旧信件时需要保存的最新非系统消息数量(以及用于 `summarize.preserveRecent`) (中文(简体) ). |
| `preserveSystem` | `boolean` | `true` | 始终保持系统指令完整. |
| `maxToolResponseChars` | `number` | `400000` | 字符中任何单个工具响应大小的硬盖( 覆盖) `output` 财务报告和审定财务报表 `content` ) (中文(简体) ). 设定 `<= 0` 或者说 `Infinity` 以禁用. |
| `deduplicateToolResponses` | `object` | —— 说 | 重复工具呼叫的复制设置 . |
| `deduplicateToolResponses.matchBy` | `'name-and-input' | 'name-only'` | `'name-and-input'` | 如何匹配重复的工具呼叫 . `'name-and-input'` 匹配相同的工具名称和参数. `'name-only'` 组全部单独调用一个工具,并丢弃先前的响应,即使调用不同的输入(仅用于返回最新状态的工具,而不论参数如何). |
| `deduplicateToolResponses.keepRecent` | `number` | `1` | 保留每个重复组的最新答复数目(最少 `1`) (中文(简体) ). |
| `deduplicateToolResponses.notice` | `string` | 标准文本 | 自定义工具回复的替换文本 . |
| `toolResponses` | `object` | —— 说 | 旧工具响应的截断设置 . |
| `toolResponses.maxChars` | `number` | —— 说 | 每个旧工具响应的最大字符( 覆盖) `output` 财务报告和审定财务报表 `content` 一起折叠文本 `content` 输入 `output` 当他被截断的时候. |
| `toolResponses.preserveRecent` | `number` | `2` | 保存未显示的最新工具响应消息数量 . |
| `summarize` | `object` | —— 说 | LLM 汇总设置( R)`model`, (中文(简体) ), `preserveRecent`, (中文(简体) ), `prompt`) (中文(简体) ). |
| `summarize.model` | `ModelArgument` | _(必须)_ | 用于归纳的模型(模型参考、模型名称字符串,或 `ModelAction`) (中文(简体) ). |
| `summarize.preserveRecent` | `number` | `6` | 保留未归纳(默认为顶级)的最新非系统消息数量 `preserveRecent` 如果设定,则返回 `preserveRecent` (c) 缩短预算外历史. |
| `summarize.prompt` | `string` | 标准提示 | 自定义汇总提示 。 使用 `{conversation}` 作为发送信件摘要的占位符. |
| `skipSummarizationThreshold` | `number` | —— 说 | 如果廉价策略至少保存这个分数, 则跳过总和( S)`0..1`上下文并带来估计值 `maxInputTokens`。 。 。 . |
| `maxMessages` | `number` | —— 说 | 最大消息计数目标 。 丢弃旧的非系统消息,确保历史从用户回合开始。 当系统消息和截取通知填补了封顶时,可能会被超越,因为最新的转弯总是保持. |
| `insertTruncationNotice` | `boolean` | `true` | 在删除信件时插入咨询通知. |
| `truncationNotice` | `string` | 标准文本 | 自定义删除信件时使用的通知文本 . |
| `preserveOriginalMessages` | `boolean` | `true` | 保存原始未压缩信件 `request.messages` 财务报告和审定财务报表 `response.messages` 将压缩状态存储于 `message.metadata.contextCompression`设置为 `false` 覆盖 `request.messages` 已经就位. |

## 常见问题

### @genkit-ai/middleware 是什么？

Genkit 的中间软件

### 如何安装 @genkit-ai/middleware？

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

### @genkit-ai/middleware 支持 TypeScript 吗？

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

### @genkit-ai/middleware 支持 ESM 还是 CommonJS？

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

### @genkit-ai/middleware 可以商用吗？

@genkit-ai/middleware 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @genkit-ai/middleware 的下载量有多少？

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

### @genkit-ai/middleware 还在维护吗？

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

