# https://github.com/genkit-ai/genkit 项目说明书

生成时间：2026-06-23 13:51:22 UTC

## 目录

- [Genkit Framework Overview & Cross-Language Architecture](#page-1)
- [Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions](#page-2)
- [Plugin Ecosystem & Model Provider Integrations](#page-3)
- [Developer Tools, CLI, Tracing, Deployment & Observability](#page-4)

<a id='page-1'></a>

## Genkit Framework Overview & Cross-Language Architecture

### 相关页面

相关主题：[Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions](#page-2), [Developer Tools, CLI, Tracing, Deployment & Observability](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/genkit-ai/genkit/blob/main/README.md)
- [js/genkit/README.md](https://github.com/genkit-ai/genkit/blob/main/js/genkit/README.md)
- [py/README.md](https://github.com/genkit-ai/genkit/blob/main/py/README.md)
- [py/packages/genkit/README.md](https://github.com/genkit-ai/genkit/blob/main/py/packages/genkit/README.md)
- [js/plugins/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/README.md)
- [js/plugins/evaluators/package.json](https://github.com/genkit-ai/genkit/blob/main/js/plugins/evaluators/package.json)
- [js/testapps/basic-gemini/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/basic-gemini/README.md)
- [genkit-tools/cli/README.md](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/README.md)
- [genkit-tools/cli/src/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/src/mcp/README.md)
- [js/plugins/mcp/package.json](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/package.json)
</details>

# Genkit Framework Overview & Cross-Language Architecture

## 框架定位与目标

Genkit 是由 Google 的 Firebase 团队维护的开源框架,用于构建全栈 AI 驱动的应用程序。其核心价值在于通过统一的 API 抽象不同模型提供商之间的差异,使开发者能够使用一致的编程模型完成文本生成、结构化输出、工具调用、聊天会话以及检索增强生成(RAG)等任务。资料来源：[README.md:14-19]()

框架在多语言生态中采用分阶段成熟度策略:JavaScript/TypeScript 与 Go 处于生产就绪状态,提供完整功能;Python 处于 Beta 阶段,具备大部分能力;Dart 处于 Preview 阶段,提供核心功能。这种策略既保证核心 SDK 的稳定性,也允许新语言实现快速迭代。资料来源：[README.md:25-32]()

## 跨语言架构总览

Genkit 在所有语言实现中保持一致的组件模型。下图展示了应用层、SDK 入口、注册表与各类能力模块之间的关系:

```mermaid
graph TB
    A[应用代码] --> B[Genkit SDK 入口]
    B --> C[Registry 注册表]
    B --> D[Flows 流程]
    B --> E[Tools 工具]
    B --> F[Prompts 提示词]
    B --> G[Embedders 嵌入器]
    B --> H[Retrievers 检索器]
    B --> I[Plugins 插件]
    I --> J[Google AI / Vertex AI]
    I --> K[OpenAI / Anthropic]
    I --> L[Ollama 等本地模型]
    I --> M[MCP 模型上下文协议]
```

各语言实现均围绕相同的核心抽象:Flows 封装可执行的 AI 工作流,Tools 让模型可以调用函数,Prompts 提供可复用的提示模板,Embedders 处理向量化,Retrievers 处理 RAG 场景下的数据检索,Registry 统一管理所有组件。资料来源：[py/README.md:9-25]()

## 核心能力与典型用法

JavaScript 入口可通过 `genkit` 工厂函数快速初始化,并以统一的 `ai.generate()` 接口发起调用。资料来源：[js/genkit/README.md:17-26]()

```ts
import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({ plugins: [googleAI()] });

const { text } = await ai.generate({
  model: googleAI.model('gemini-flash-latest'),
  prompt: 'Why is Genkit awesome?',
});
```

Python 实现使用 Pydantic 模型作为输出 schema,与 TypeScript 版本的 Zod 在类型安全体验上保持对等。资料来源：[py/packages/genkit/README.md:20-29]()

Google GenAI 插件示例还演示了多模态输入、思维链、结构化输出、工具调用、搜索接地、URL 上下文等高级能力,展示了插件如何在不同模型特性之上提供统一抽象。资料来源：[js/testapps/basic-gemini/README.md:3-25]()

## 插件生态与工具链

Genkit 通过插件机制扩展模型提供商与外部服务。`@genkit-ai/google-genai`、`@genkit-ai/anthropic`、`@genkit-ai/ollama` 等官方或社区插件为不同模型提供统一接入。资料来源：[README.md:14-16]()

`@genkit-ai/mcp` 插件支持模型上下文协议(MCP),允许 Genkit 应用作为客户端消费 MCP 工具、提示词与资源,也可作为服务端将 Genkit 能力暴露给外部 MCP 客户端。资料来源：[js/plugins/mcp/README.md:1-10]() 该插件以 `@modelcontextprotocol/sdk` 作为对等依赖,实现了与 MCP 生态的互操作。资料来源：[js/plugins/mcp/package.json:24-31]()

`@genkit-ai/evaluator` 插件提供 RAG 与生成质量的评估能力,支持正则匹配、LLM 评分等多种评估器,可与 `genkit eval:run` CLI 命令结合使用。资料来源：[js/plugins/evaluators/package.json:1-15]()

`genkit-cli` 工具覆盖项目初始化、流程执行、批量评估、跟踪检索等典型开发场景,例如 `flow:run`、`flow:batchRun`、`eval:extractData` 等子命令。资料来源：[genkit-tools/cli/README.md:14-30]()

实验性的 Genkit MCP Server 进一步允许 IDE 与 LLM 代理通过 MCP 发现、调用本地 Genkit 流程,并支持检索文档与运行追踪。资料来源：[genkit-tools/cli/src/mcp/README.md:7-25]()

## 社区关注的实现细节

以下问题反映了用户在使用跨语言 Genkit 时遇到的常见痛点,值得在架构选型时留意:

- **Zod 版本兼容性与结构化输出**:`#3470` 反映了核心 schema 校验对 Zod 3 的依赖,`#2758` 则指出 `nullable()`、`describe()` 等 Zod 特性在 Gemini API 中被拒绝,提示插件层需对 schema 做规范化映射。
- **提供商专属参数**:`#1901` 显示 Gemini 的 `googleSearchRetrieval` 等选项需通过 `config` 字段手动透传,框架尚未提供一等公民配置。
- **会话状态语义**:`#1437` 指出 `session.updateState()` 在 JavaScript 中表现为整体替换而非补丁更新,跨语言实现需明确语义以避免行为漂移。
- **Dotprompt 角色渲染**:`#3711` 表明 Go SDK 在渲染多消息 Dotprompt 时统一使用 `user` 角色,忽略了模板中定义的角色,属于 Go 提示词渲染的回归问题。

## See Also

- Genkit JS 核心(`js/genkit`)
- Genkit Python 包(`py/packages/genkit`)
- MCP 插件(`js/plugins/mcp`)
- 评估器插件(`js/plugins/evaluators`)
- Genkit CLI(`genkit-tools/cli`)
- Google GenAI 插件示例(`js/testapps/basic-gemini`)

---

<a id='page-2'></a>

## Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions

### 相关页面

相关主题：[Genkit Framework Overview & Cross-Language Architecture](#page-1), [Plugin Ecosystem & Model Provider Integrations](#page-3), [Developer Tools, CLI, Tracing, Deployment & Observability](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/genkit-ai/genkit/blob/main/README.md)
- [py/README.md](https://github.com/genkit-ai/genkit/blob/main/py/README.md)
- [js/testapps/prompt-file/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/prompt-file/README.md)
- [js/testapps/rag/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/rag/README.md)
- [js/testapps/format-tester/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/format-tester/README.md)
- [js/testapps/basic-gemini/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/basic-gemini/README.md)
- [js/plugins/middleware/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/middleware/README.md)
- [js/plugins/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/README.md)
- [genkit-tools/cli/src/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/src/mcp/README.md)
- [genkit-tools/cli/src/mcp/runtime.ts](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/src/mcp/runtime.ts)
- [py/samples/README.md](https://github.com/genkit-ai/genkit/blob/main/py/samples/README.md)
- [samples/js-menu/README.md](https://github.com/genkit-ai/genkit/blob/main/samples/js-menu/README.md)
- [go/samples/mcp-git-pr-explainer/README.md](https://github.com/genkit-ai/genkit/blob/main/go/samples/mcp-git-pr-explainer/README.md)
</details>

# Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions

Genkit 是一个面向全栈 AI 应用的开源框架，提供跨语言 SDK（JavaScript/TypeScript、Go、Python Beta、Dart Preview）。本页面介绍其核心 SDK 概念：**生成（Generation）、流程（Flows）、提示（Prompts）、工具（Tools）与会话（Sessions）**，帮助开发者理解如何组合这些原语构建可投入生产的 AI 功能。资料来源：[README.md](README.md)

## 1. 核心抽象与 SDK 架构

Genkit 通过统一的 `Genkit` 实例作为注册中心，将模型、流程、工具、提示、嵌入器、检索器等能力进行集中管理。初始化时通过插件（如 `googleAI()`、`vertexAI()`）注入模型提供商，再以装饰器或方法形式声明各种能力。资料来源：[py/README.md](py/README.md)

```mermaid
flowchart LR
    App[应用代码] --> Genkit[Genkit 实例 / Registry]
    Genkit --> Flows[流程 Flows]
    Genkit --> Tools[工具 Tools]
    Genkit --> Prompts[提示 Prompts]
    Genkit --> Models[模型 Models]
    Genkit --> Embedders[嵌入器]
    Genkit --> Retrievers[检索器]
    Models -->|调用| Providers[Google / OpenAI / Anthropic / Ollama ...]
```

下表列出主要原语及其作用：

| 原语 | 作用 | 典型用例 |
| --- | --- | --- |
| Generation | 单次模型调用，支持流式、结构化输出 | 文案生成、文本分类 |
| Flow | 带输入/输出 Schema 的可追踪函数 | 业务工作流、API 端点 |
| Prompt | 模板化提示（代码或 `.prompt` 文件） | 提示版本管理、变体 |
| Tool | 模型可调用的外部函数 | 天气查询、文件操作 |
| Session | 跨调用的状态与历史 | 多轮对话、状态管理 |

## 2. 生成（Generation）

`generate` 是最基础的调用入口，接受 `model`、`prompt`、`config`、`tools` 等参数，并可返回 `text`、`output`（结构化）、`stream` 等形式。Genkit 抽象了不同提供商的差异，使同一份代码可在 Google Gemini、OpenAI、Anthropic、Ollama 等模型间切换。资料来源：[README.md](README.md)

结构化输出支持 `text`、`json`、`array`、`jsonl`、`enum` 等格式，由 `format-tester` 示例对多种模型组合进行自动化验证。资料来源：[js/testapps/format-tester/README.md](js/testapps/format-tester/README.md)

> **社区关注点**：Zod 集成存在诸多陷阱，例如 `nullable()`、`describe()` 等在 Gemini API 中可能被拒绝；社区已提出 #2758 与 #3470 跟踪 Zod 4 的兼容性问题。

## 3. 流程（Flows）

流程（`defineFlow`）将模型调用与业务逻辑封装为强类型函数，具备明确的输入/输出 Schema。Genkit 的 Dev UI 与 CLI 可在运行时发现并测试这些流程。资料来源：[genkit-tools/cli/src/mcp/README.md](genkit-tools/cli/src/mcp/README.md)

典型流程示例包括：
- 基础聊天：`basic-hi`、带重试的 `basic-hi-with-retry`、带回退链的 `basic-hi-with-fallback`。资料来源：[js/testapps/basic-gemini/README.md](js/testapps/basic-gemini/README.md)
- RAG 问答：`askQuestionsAboutCats`、`askQuestionsAboutDogs`，分别基于 Pinecone 与 ChromaDB 检索器。资料来源：[js/testapps/rag/README.md](js/testapps/rag/README.md)
- 多步菜单理解：使用 Vertex AI 与 Llama 3.1 进行 5 个迭代，从纯提示到多模态。资料来源：[samples/js-menu/README.md](samples/js-menu/README.md)

流程可通过 `middleware` 包插入中间件，例如文件系统访问或自定义工具集。资料来源：[js/plugins/middleware/README.md](js/plugins/middleware/README.md)

## 4. 提示（Prompts）

提示是 Genkit 中可版本化、可测试的关键资产。除了内联字符串外，还支持 Dotprompt 格式（`.prompt` 文件 + YAML frontmatter），用于声明模型配置、Schema、变体与部分模板。资料来源：[js/testapps/prompt-file/README.md](js/testapps/prompt-file/README.md)

Dotprompt 关键能力：
- **结构化输出**：如 `recipe.prompt` 使用 `Recipe` Schema 生成结构化菜谱；
- **变体**：如 `recipe.robot.prompt` 提供机器人风格版本；
- **流式 + 部分模板**：如 `story.prompt` 引用 `_style.prompt` 作为部分；
- **自定义助手**：例如 `{{list items}}` 数组渲染助手。

> **社区关注点**：Go SDK 在渲染 Dotprompt 时会忽略 dotprompt 中定义的角色（#3711），始终使用 `"user"`，影响多消息提示场景。

## 5. 工具（Tools）

工具（`defineTool`）使模型能够在生成过程中调用外部函数。Genkit 内置对工具调用、流式工具、结构化工具调用、工具中断（interrupt/resume）的支持。资料来源：[py/samples/README.md](py/samples/README.md)

工具接入途径：
- **直接定义**：`ai.tool` 装饰器声明同步/异步函数；
- **MCP 集成**：通过 `createMcpHost` / `createMcpClient` 消费 Model Context Protocol 服务器暴露的工具与资源。资料来源：[js/plugins/mcp/README.md](js/plugins/mcp/README.md)
- **文件系统中间件**：`filesystem` 中间件自动注入 `list_files`、`read_file` 等标准工具，可限定根目录并通过 `allowWriteAccess` 控制写权限。资料来源：[js/plugins/middleware/README.md](js/plugins/middleware/README.md)

> **社区关注点**：社区请求显式暴露 Gemini 的 `google_search` 选项（#1901），以便在工具之外直接控制搜索检索行为。

## 6. 会话（Sessions）

会话用于在多次调用间维护对话历史与自定义状态。Genkit 提供 `updateState` 等 API，但当前实现存在替换而非合并的行为，社区已就此提出改进请求（#1437）。开发者需注意在更新单个属性时传入完整状态对象，或在调用方做对象合并。资料来源：[README.md](README.md)

## 7. 运行时与 Dev UI

CLI 中的 MCP 服务器与运行时管理组件允许外部 IDE / Agent 通过工具发现、运行流程并查看追踪。`runtime.ts` 中的 `start_runtime` 工具会调用 `options.manager.getManagerWithDevProcess` 启动用户应用进程，供 `genkit start` 与 Dev UI 接入。资料来源：[genkit-tools/cli/src/mcp/runtime.ts](genkit-tools/cli/src/mcp/runtime.ts)

## 8. 常见问题与失败模式

- **Zod Schema 兼容性**：使用 Zod 时避免依赖 `nullable()` / `describe()` 等在 Gemini 结构化输出中可能不被支持的语法。
- **Dotprompt 角色**：Go SDK 当前忽略自定义角色，需在调用前手动调整消息。
- **会话状态更新**：`updateState` 表现为整体替换，调用方需自行合并。
- **MCP 工具路径**：使用 `createMcpHost` 时需确保 `command` 可执行，例如 `GITHUB_MCP_CMD` 指向已构建的二进制。资料来源：[go/samples/mcp-git-pr-explainer/README.md](go/samples/mcp-git-pr-explainer/README.md)

## See Also

- [Model Context Protocol 集成](js/plugins/mcp/README.md)
- [Middleware 集合](js/plugins/middleware/README.md)
- [RAG 示例](js/testapps/rag/README.md)
- [Dotprompt 示例](js/testapps/prompt-file/README.md)
- [Python SDK 概览](py/README.md)
- [CLI MCP 工具](genkit-tools/cli/src/mcp/README.md)

---

<a id='page-3'></a>

## Plugin Ecosystem & Model Provider Integrations

### 相关页面

相关主题：[Genkit Framework Overview & Cross-Language Architecture](#page-1), [Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions](#page-2), [Developer Tools, CLI, Tracing, Deployment & Observability](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/genkit-ai/genkit/blob/main/README.md)
- [js/genkit/README.md](https://github.com/genkit-ai/genkit/blob/main/js/genkit/README.md)
- [py/README.md](https://github.com/genkit-ai/genkit/blob/main/py/README.md)
- [js/plugins/anthropic/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/anthropic/README.md)
- [js/testapps/anthropic/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/anthropic/README.md)
- [js/testapps/basic-gemini/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/basic-gemini/README.md)
- [js/plugins/vertexai/src/modelgarden/v2/mistral.ts](https://github.com/genkit-ai/genkit/blob/main/js/plugins/vertexai/src/modelgarden/v2/mistral.ts)
- [js/plugins/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/README.md)
- [js/plugins/mcp/package.json](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/package.json)
- [js/plugins/middleware/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/middleware/README.md)
- [genkit-tools/cli/src/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/src/mcp/README.md)
- [go/samples/mcp-git-pr-explainer/README.md](https://github.com/genkit-ai/genkit/blob/main/go/samples/mcp-git-pr-explainer/README.md)
- [py/samples/middleware-coding-agent/README.md](https://github.com/genkit-ai/genkit/blob/main/py/samples/middleware-coding-agent/README.md)
- [py/samples/evaluators/README.md](https://github.com/genkit-ai/genkit/blob/main/py/samples/evaluators/README.md)
</details>

# 插件生态与模型提供商集成

## 概述

Genkit 的插件生态是整个框架的核心扩展机制。通过统一的插件接口，开发者可以为 Genkit 添加模型提供商、向量数据库、可观测性后端以及工具协议适配器等能力，而无需改动核心代码。Genkit 在 JavaScript/TypeScript、Go、Python（Beta）和 Dart（Preview）等多语言 SDK 中均提供了一致的插件抽象，使不同语言下的集成体验保持一致 资料来源：[README.md:1-50]()。

在 JavaScript SDK 中，官方将插件按职责划分为多个类别：模型（`@genkit-ai/google-genai`、`@genkit-ai/vertexai`、`@genkit-ai/compat-oai`、`genkitx-anthropic`、`genkitx-ollama`）、部署（`@genkit-ai/express`、`@genkit-ai/fetch`、`@genkit-ai/firebase`、`@genkit-ai/cloud-run`）和监控（`@genkit-ai/google-cloud`）等 资料来源：[js/genkit/README.md:1-30]()。

## 核心模型提供商插件

### Google GenAI 与 Vertex AI

Google GenAI 插件是最常用的模型集成，覆盖 Google AI Studio 与 Vertex AI 两个后端。基础示例 `basic-gemini` 演示了从简单文本生成、思考模式（thinking modes）、工具调用、结构化输出、多模态、图像生成、TTS，到搜索接地（search grounding）和 URL 上下文等几乎全部能力 资料来源：[js/testapps/basic-gemini/README.md:1-30]()。

Vertex AI 插件还支持 Model Garden，可以接入 Mistral 等第三方托管模型。例如 `js/plugins/vertexai/src/modelgarden/v2/mistral.ts` 通过 `modelRef` 构造了 `vertex-model-garden/mistral-*` 模型引用，并基于 `GenerationCommonConfigSchema` 扩展出 `location`、`topP` 等 Mistral 专属配置项 资料来源：[js/plugins/vertexai/src/modelgarden/v2/mistral.ts:1-50]()。

### Anthropic 插件

`@genkit-ai/anthropic` 是官方维护的 Anthropic Claude 集成，最初来源于 Bloom Labs Inc. 在 `genkit-plugins` 仓库中的 Apache 2.0 实现，现由 Google 持续维护 资料来源：[js/plugins/anthropic/README.md:1-15]()。示例应用 `js/testapps/anthropic` 同时演示了 stable 与 beta 两套 API，覆盖基础对话、流式输出、纯文本错误处理、WEBP 图像、PDF 文档以及视觉分析等场景 资料来源：[js/testapps/anthropic/README.md:1-30]()。

## 插件架构与解析机制

Python SDK 中所有插件均继承自抽象基类 `genkit._core.plugin.Plugin`，并实现 `name`（命名空间，如 `'googleai'`、`'anthropic'`、`'ollama'`）、`async init() → list[Action]`（一次性初始化，返回待注册动作）以及 `async resolve(kind, name) → Action?`（按需解析单个动作）。`init` 是在首次动作解析时被懒加载调用，而非注册时立即触发 资料来源：[py/README.md:1-80]()。

```mermaid
flowchart LR
    A[用户定义 Genkit 实例] --> B[注册 Plugin 列表]
    B --> C{首次动作请求?}
    C -- 否 --> D[直接 resolve]
    C -- 是 --> E[调用 plugin.init]
    E --> F[缓存 Action 列表]
    F --> D
    D --> G[返回 Action 实例]
```

该统一契约使不同提供商可以在不修改 SDK 主干的前提下自由扩展。社区也有第三方插件托管在 npm 上，可通过关键词 `genkit-plugin` 检索 资料来源：[js/genkit/README.md:1-30]()。

## 专用插件与协议集成

### Model Context Protocol（MCP）

`@genkit-ai/mcp` 提供 Genkit 与 MCP 的双向集成：客户端侧可通过 `createMcpHost` 或 `createMcpClient` 将 MCP 服务器中的工具、提示与资源暴露给 Genkit；服务器侧则可通过 `createMcpServer` 将 Genkit 工具与提示发布为 MCP 服务 资料来源：[js/plugins/mcp/README.md:1-30]()。该包当前版本为 `1.37.0`，并以 `@modelcontextprotocol/sdk ^1.29.0` 作为对等依赖 资料来源：[js/plugins/mcp/package.json:1-30]()。

Go 端同样提供了对应示例 `mcp-git-pr-explainer`：通过 GitHub MCP 服务器拉取 PR 详情，再交由 Gemini 模型生成 TL;DR 摘要 资料来源：[go/samples/mcp-git-pr-explainer/README.md:1-20]()。此外，`genkit-tools/cli/src/mcp` 提供了一个面向 IDE 与 LLM 代理的 MCP 服务器，允许外部环境列出、运行 Genkit flow，并查询文档与执行轨迹 资料来源：[genkit-tools/cli/src/mcp/README.md:1-30]()。

### Middleware 插件

`@genkit-ai/middleware` 提供若干增强模型与工具调用能力的中介件：`filesystem`（在指定根目录内暴露 `list_files`、`read_file`、`write_file`、`search_and_replace`）、`skills`（扫描 `SKILL.md` 并自动注入系统提示及 `use_skill` 工具）和 `ToolApproval`（对写操作进行人工审批）。Python 示例 `middleware-coding-agent` 将这三者组合到同一个 REPL 中，演示了"系统提示列出技能 + 工具按需拉取 + 敏感操作暂停等待 `y/N` 确认"的完整模式 资料来源：[js/plugins/middleware/README.md:1-30]()，资料来源：[py/samples/middleware-coding-agent/README.md:1-30]()。

### Evaluators 评估器插件

评估器同样以插件形式存在，既包含无需 LLM 的 `genkitEval/regex`（基于正则匹配），也包含基于 LLM 打分的 `byo/maliciousness`（安全性）与 `byo/answer_accuracy`（答案准确性，0/2/4 三档评分） 资料来源：[py/samples/evaluators/README.md:1-30]()。

## 常见问题与社区反馈

社区中与插件生态相关的高频议题包括：

- **Zod 兼容性**：在 JS SDK 中使用 Zod 4 schema 时仍存在兼容性问题，`nullable()`、`describe()` 等生成的 JSON Schema 片段会被 Gemini API 拒绝（#2758、#3470）。
- **Google 搜索选项暴露**：开发者希望在 `config` 中显式透传 `googleSearchRetrieval` 等 Gemini 特有参数（#1901）。
- **Session updateState 语义**：在更新会话状态时到底是 patch 还是 replace，社区存在分歧，需要结合具体 SDK 版本确认（#1437）。
- **Go 端 Dotprompt 角色**：当 `.prompt` 文件中自定义了多消息角色时，Go 渲染器会忽略并始终使用 `user`，这是一个已知的渲染 bug（#3711）。

## 参见

- 快速上手与 CLI：[js/genkit/README.md](https://github.com/genkit-ai/genkit/blob/main/js/genkit/README.md)
- Python 插件抽象：[py/README.md](https://github.com/genkit-ai/genkit/blob/main/py/README.md)
- MCP 集成：[js/plugins/mcp/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/mcp/README.md)
- Middleware 中介件：[js/plugins/middleware/README.md](https://github.com/genkit-ai/genkit/blob/main/js/plugins/middleware/README.md)

---

<a id='page-4'></a>

## Developer Tools, CLI, Tracing, Deployment & Observability

### 相关页面

相关主题：[Genkit Framework Overview & Cross-Language Architecture](#page-1), [Core SDK Concepts: Generation, Flows, Prompts, Tools & Sessions](#page-2), [Plugin Ecosystem & Model Provider Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [genkit-tools/cli/src/cli.ts](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/cli/src/cli.ts)
- [genkit-tools/common/src/api/reflection.ts](https://github.com/genkit-ai/genkit/blob/main/genkit-tools/common/src/api/reflection.ts)
- [README.md](https://github.com/genkit-ai/genkit/blob/main/README.md)
- [js/genkit/README.md](https://github.com/genkit-ai/genkit/blob/main/js/genkit/README.md)
- [py/README.md](https://github.com/genkit-ai/genkit/blob/main/py/README.md)
- [py/samples/README.md](https://github.com/genkit-ai/genkit/blob/main/py/samples/README.md)
- [py/samples/evaluators/README.md](https://github.com/genkit-ai/genkit/blob/main/py/samples/evaluators/README.md)
- [js/testapps/basic-gemini/README.md](https://github.com/genkit-ai/genkit/blob/main/js/testapps/basic-gemini/README.md)
- [go/samples/mcp-git-pr-explainer/README.md](https://github.com/genkit-ai/genkit/blob/main/go/samples/mcp-git-pr-explainer/README.md)
</details>

# Developer Tools, CLI, Tracing, Deployment & Observability

## 概述

Genkit 提供了一整套面向开发者的工作流工具，覆盖命令行界面（CLI）、交互式开发者 UI、追踪与可观测性、以及多种部署目标。这些工具贯穿 `genkit-tools/` 仓库下的 CLI、反射 API 与各语言 SDK（JavaScript/TypeScript、Go、Python、Dart），帮助开发者在本地迭代、调试、评估并将 AI 功能投入生产。资料来源：[README.md:1-100]()

## CLI 命令面

CLI 的入口在 `startCLI()`，它定义了所有可用子命令和通用选项。资料来源：[genkit-tools/cli/src/cli.ts:1-50]()

### 已注册的命令

CLI 注册的命令涵盖运行、评估、追踪查询、文档检索以及 MCP 集成，主要包括：

| 命令 | 用途 |
|---|---|
| `start` / `startFlutter` | 启动开发者 UI 并加载目标应用 |
| `flow:run` / `eval:run` / `eval:flow` | 执行流与评估 |
| `trace:get` / `trace:list` | 检索追踪数据 |
| `docs:list` / `docs:search` / `docs:read` | 读取内置文档 |
| `config` | 配置本地 Genkit 环境 |
| `mcp` | 启动模型上下文协议（MCP）服务器 |
| `init:ai-tools` | 初始化 AI 工具集成 |
| `dev:test-model` | 模型调试与回放 |

资料来源：[genkit-tools/cli/src/cli.ts:1-40]()

### 全局选项

CLI 支持 `--no-update-notification` 关闭更新提示，并通过 `--non-interactive` 让所有交互默认采用默认选项，便于脚本化调用。`preAction` 钩子会在每次执行前记录命令名与运行时类型（编译产物或 Node），并跳过非交互模式下的首次运行分析上报。资料来源：[genkit-tools/cli/src/cli.ts:18-49]()

## 开发者 UI 与反射 API

`genkit start` 命令会加载用户的应用入口文件（例如 `npx tsx src/index.ts`）并启动开发者 UI，用于可视化测试流、检查追踪和试验提示。资料来源：[js/genkit/README.md:1-50]()

### 反射 API

反射 API（Reflection API）暴露在 `genkit-tools/common/src/api/reflection.ts`，它允许客户端检视应用代码、查看所有注册动作、运行它们并查看结果。该文件同时提供 OpenAPI 规范生成逻辑，将控制平面接口写入 YAML，便于客户端 SDK 自动生成。资料来源：[genkit-tools/common/src/api/reflection.ts:1-30]()

```mermaid
flowchart LR
    User[开发者] -->|npx genkit start| CLI[Genkit CLI]
    CLI -->|spawn| App[用户应用<br/>tsx / go run]
    CLI --> DevUI[开发者 UI<br/>localhost:端口]
    App -->|注册动作| Reflection[反射 API<br/>/api/actions]
    DevUI -->|调用| Reflection
    Reflection -->|执行| App
    App -->|上报 span| Tracer[追踪器]
    Tracer -->|trace:get / trace:list| DevUI
```

## 追踪与可观测性

Genkit 的可观测性体现在三个层面：

1. **本地追踪**：`py/samples/tracing` 示例展示了 span 在开发者 UI 中实时出现的行为。资料来源：[py/samples/README.md:1-20]()
2. **中间件钩子**：`py/samples/middleware` 与 `js/testapps/basic-gemini` 中的 `basic-hi-with-retry`、`basic-hi-with-fallback` 示例演示如何通过 `use=[...]` 拦截或修改模型请求，常用于重试、回退与请求/响应埋点。资料来源：[js/testapps/basic-gemini/README.md:1-30]()
3. **云端监控**：JS 生态提供 `@genkit-ai/google-cloud` 插件以对接 Google Cloud 的可观测性栈。资料来源：[js/genkit/README.md:1-50]()

通过 `trace:list` 与 `trace:get` 命令，CLI 可以直接从本地追踪存储中检索 span，配合 MCP 子命令把追踪数据暴露给外部 MCP 客户端（例如在 `go/samples/mcp-git-pr-explainer` 中与 GitHub MCP 服务器并列使用）。资料来源：[go/samples/mcp-git-pr-explainer/README.md:1-30]()

## 评估工具链

评估由 CLI 与 SDK 共同完成。`py/samples/evaluators` 展示了可配置的评估器：

- `genkitEval/regex`：基于正则的轻量评估，无需 LLM。
- `byo/maliciousness` / `byo/answer_accuracy`：使用 LLM 按评分细则打分。

执行入口通过 CLI：

```bash
genkit eval:run datasets/genkit_eval_dataset.json --evaluators=genkitEval/regex
```

资料来源：[py/samples/evaluators/README.md:1-30]()

## 部署目标

Genkit 流程可在任何支持所选语言运行时的地方部署。JS 生态提供了一组官方部署插件：

| 目标 | 插件 |
|---|---|
| Express / 任意 Node | `@genkit-ai/express`、`@genkit-ai/fetch` |
| Firebase | `@genkit-ai/firebase` |
| Cloud Run | `@genkit-ai/cloud-run` |

资料来源：[js/genkit/README.md:1-50]() [README.md:1-100]()

Go 与 Python SDK 同样支持任意兼容容器或函数运行时部署；README 中明确提到 Cloud Functions for Firebase、Cloud Run 等场景。资料来源：[README.md:1-100]()

## 已知问题与社区反馈

与本主题相关的社区讨论集中在工具链与 SDK 行为的一致性上：

- **Zod 兼容性**：`#3470` 申请 Zod 4 支持，`#2758` 报告 Zod 模式生成的 `nullable()`、`describe()` 等结构在 Gemini API 上被拒绝。这会影响 JS CLI 的 `eval:flow` 与本地结构化输出验证。资料来源：[README.md:1-100]()
- **Dotprompt 角色映射**：`#3711` 指出 Go SDK 在渲染 `.prompt` 文件时忽略自定义角色，始终使用 `"user"`。该问题与开发者 UI 中提示预览、追踪捕获的角色字段直接相关。资料来源：[README.md:1-100]()
- **会话状态写入语义**：`#1437` 请求 `updateState()` 改为增量合并而非整体替换，影响追踪中显示的会话状态变更。资料来源：[README.md:1-100]()

## See Also

- [Model Plugins & Structured Output](./models-and-structured-output.md)
- [RAG, Vector Stores & Retrievers](./rag-and-retrievers.md)
- [Dotprompt Templating](./dotprompt-templating.md)
- [MCP Integrations](./mcp-integrations.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：genkit-ai/genkit

摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Go] Add advanced features to Ollama plugin。

## 1. 安全/权限坑 · 来源证据：[Go] Add advanced features to Ollama plugin

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Go] Add advanced features to Ollama plugin
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/genkit-ai/genkit/issues/2380 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：feat(*): Testing Modules

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(*): Testing Modules
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/genkit-ai/genkit/issues/5597 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 配置坑 · 来源证据：feat: Python P0 model parity june 2026

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Python P0 model parity june 2026
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/genkit-ai/genkit/issues/5542 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/genkit-ai/genkit | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/genkit-ai/genkit | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/genkit-ai/genkit | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/genkit-ai/genkit | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：Support Prompt Caching for Anthropic

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Prompt Caching for Anthropic
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/genkit-ai/genkit/issues/817 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 安全/权限坑 · 来源证据：feat(go/plugins/anthropic): support prompt caching (cache_control)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(go/plugins/anthropic): support prompt caching (cache_control)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/genkit-ai/genkit/issues/5598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/genkit-ai/genkit | issue_or_pr_quality=unknown

## 11. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/genkit-ai/genkit | release_recency=unknown

<!-- canonical_name: genkit-ai/genkit; human_manual_source: deepwiki_human_wiki -->