genkit 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

genkit 项目

一个用于构建 AI 驱动应用的开源框架，支持 JavaScript、Go 和 Python，由 Google 构建并在生产环境中使用。

Genkit Framework Overview & Cross-Language Architecture

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

章节 相关页面

继续阅读本节完整说明和来源证据。

框架定位与目标

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

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

跨语言架构总览

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

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

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 提示词渲染的回归问题。

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

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

1. 核心抽象与 SDK 架构

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

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

结构化输出支持 text、json、array、jsonl、enum 等格式，由 format-tester 示例对多种模型组合进行自动化验证。资料来源：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

典型流程示例包括：

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

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

4. 提示（Prompts）

提示是 Genkit 中可版本化、可测试的关键资产。除了内联字符串外，还支持 Dotprompt 格式（.prompt 文件 + YAML frontmatter），用于声明模型配置、Schema、变体与部分模板。资料来源：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

工具接入途径：

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

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

6. 会话（Sessions）

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

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

Plugin Ecosystem & Model Provider Integrations

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Google GenAI 与 Vertex AI

继续阅读本节完整说明和来源证据。

章节 Anthropic 插件

继续阅读本节完整说明和来源证据。

章节 Model Context Protocol（MCP）

继续阅读本节完整说明和来源证据。

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

概述

在 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。

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
Python 插件抽象：py/README.md
MCP 集成：js/plugins/mcp/README.md
Middleware 中介件：js/plugins/middleware/README.md

来源：https://github.com/genkit-ai/genkit / 项目说明书

Developer Tools, CLI, Tracing, Deployment & Observability

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 已注册的命令

继续阅读本节完整说明和来源证据。

章节 全局选项

继续阅读本节完整说明和来源证据。

章节 反射 API

继续阅读本节完整说明和来源证据。

概述

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

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 的可观测性体现在三个层面：

本地追踪：py/samples/tracing 示例展示了 span 在开发者 UI 中实时出现的行为。资料来源：py/samples/README.md:1-20
中间件钩子：py/samples/middleware 与 js/testapps/basic-gemini 中的 basic-hi-with-retry、basic-hi-with-fallback 示例演示如何通过 use=[...] 拦截或修改模型请求，常用于重试、回退与请求/响应埋点。资料来源：js/testapps/basic-gemini/README.md:1-30
云端监控：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：

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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：[Go] Add advanced features to Ollama plugin

可能影响升级、迁移或版本选择。

medium 来源证据：feat(*): Testing Modules

可能增加新用户试用和生产接入成本。

medium 来源证据：feat: Python P0 model parity june 2026

可能增加新用户试用和生产接入成本。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

genkit 项目

Genkit Framework Overview & Cross-Language Architecture

框架定位与目标

跨语言架构总览

核心能力与典型用法

插件生态与工具链

社区关注的实现细节

See Also

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

1. 核心抽象与 SDK 架构

2. 生成（Generation）

3. 流程（Flows）

4. 提示（Prompts）

5. 工具（Tools）

6. 会话（Sessions）

7. 运行时与 Dev UI

8. 常见问题与失败模式

See Also

Plugin Ecosystem & Model Provider Integrations

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

概述

核心模型提供商插件

Google GenAI 与 Vertex AI

Anthropic 插件

插件架构与解析机制

专用插件与协议集成

Model Context Protocol（MCP）

Middleware 插件

Evaluators 评估器插件

常见问题与社区反馈

参见

Developer Tools, CLI, Tracing, Deployment & Observability

概述

CLI 命令面

已注册的命令

全局选项

开发者 UI 与反射 API

反射 API

追踪与可观测性

评估工具链

部署目标

已知问题与社区反馈

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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

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

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

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

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