Genkit Go SDK 开发规范详解注册表架构、DefineX 构造器与 Schema 生成管线【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkitGenkit Go SDK 的仓库内开发规范go/GEMINI.md定义了 Go 端实现的核心工程纪律注册表优先Registry-First的组件发现机制、强制的context.Context传递、严格的 JSON Schema 生成约定以及从 TypeScript Zod 模式到 Go 代码的单向 Schema 管线。本文基于该规范文档结合 go/genkit/genkit.go、go/internal/registry/registry.go、go/core/logger/logger.go 等源码逐一验证其技术原理帮助你在阅读或扩展 Genkit Go SDK 时既掌握规范的每一条落地写法也能理解规范背后约束的实际实现。五大核心工程纪律go/GEMINI.md开篇列出五条必须遵守的操作协议它们构成了 Genkit Go 代码库的宪法。1. 注册表优先Registry-First ThinkingGenkit 围绕一个中央注册表构建。任何需要被反射 APIReflection API或 Dev UI 发现的组件Flow、Tool 等一律使用genkit.DefineX系列构造器如DefineFlow、DefineTool。从源码看这个注册动作并不神秘。以DefineFlow为例go/genkit/genkit.go#L485-L489 的实现只有三行先调用core.NewFlow创建组件再调用f.Register(g.reg)把组件写入 Genkit 实例持有的注册表然后返回组件本身。注册表的底层实现在 go/internal/registry/registry.goRegistry结构体持有actions、plugins、schemas、values四张以名称为键的 map并用读写锁保护并发访问。值得注意的是RegisterAction对重复注册会直接 panic——同一类型的同名 action 只能注册一次这从机制上保证了注册表中组件名的唯一性。注册表还支持父子层级NewChild创建继承父注册表的子注册表查找时未命中子表会回落到父表。这为插件沙箱和嵌套作用域提供了基础。2. Context 是强制的每个 Genkit 函数和工具执行都需要context.Context必须忠实地逐层传递除非是入口点否则实现内部不得凭空使用context.Background()。这一点在规范中列在第二条因为它同时影响可观测性与生命周期管理trace span、logger、取消信号都挂载在 context 上。后文的日志一节会展示这一约束如何在core/logger中落地。3. Schema 严格性为 Flow 或 Tool 定义输入/输出类型时必须使用带清晰 JSON tag 的 Go struct——模型正是依据这些 tag 和类型来理解接口的。Go SDK 在内部把 struct 反射为 JSON Schema注册表通过github.com/invopop/jsonschema完成 schema 解析见 go/internal/registry/registry.go 的 import 列表因此 struct 字段的json:...tag 就是模型看到的字段名。4. 先搜索再实现许多常用工具已存在于internal/base或ai/包中编写新的 JSON 解析或字符串操作逻辑之前应先检查。以 JSON 处理为例go/internal/base/extract.go 提供了ExtractJSON等宽松解析函数能处理模型输出中包裹在散文里的 JSON以及部分完成的 JSON 结构——这类容错解析正是模型输出解析的高频痛点internal/base中还有验证validation.go、类型转换json_type_converter.go等配套工具。5. 惯用并发优先使用 Go 原生并发goroutine/channel但要留意长生命周期后台任务中 context 的生命周期管理。包结构与组件构造器包布局规范中给出的包结构在当前仓库中完全对应genkit应用开发者的主入口提供定义 flow、prompt、tool 的高层函数go/genkit/genkit.goai核心 AI 类型与接口Model、Prompt、Tool、Embedder、Retriever 等core底层框架原语Actions、Flows、Tracing、Registry主要面向内部使用或插件开发plugins具体提供商的实现Google AI、Vertex AI、Ollama 等如 go/plugins/googlegenai/、go/plugins/ollama/internal私有实现、共享工具与开发工具其中baseJSON 抽取、规范化、验证与 context 处理的底层工具cmd代码生成jsonschemagen、文件同步copy、文档weave的内部命令行工具三个目录均可在 go/internal/cmd/ 下看到registryGenkit action 与 schema 注册表的实现metricsOpenTelemetry 指标埋点fakeembedder模拟 embedding 提供商的测试工具。DefineX 与 NewX 的分工这是本规范最重要的 API 设计决策DefineX如DefineFlow、DefineTool创建并注册组件到注册表。只有经过注册组件才能被反射 API 发现从而出现在 Dev UI 中。NewX如ai.NewTool创建组件但不注册。用于内部组件、动态创建或测试场景。从 go/genkit/genkit.go#L796-L800 可以看到DefineTool正是NewToolRegister的组合func DefineToolIn, Out any *ai.ToolAction[In, Out] { t : ai.NewTool(name, description, fn, opts...) t.Register(g.reg) return t }同样的模式贯穿DefineFlow、DefineModelAction、DefineBackgroundModelAction等所有构造器。DefineTool的 GoDoc 还列出了两个选项ai.WithInputSchema提供自定义 JSON schema 取代从类型参数推断的 schema与ai.WithInputSchemaName按名称引用已注册的 schema。函数式选项模式Options Pattern可选配置一律使用函数式选项如ai.WithModel、genkit.WithPlugins在构造器与方法调用中传递。这种方式让 API 保持稳定且可增量扩展。实际效果可参考 go/README.md 的快速上手示例g : genkit.Init(ctx, genkit.WithPlugins(googlegenai.GoogleAI{}))多值选项如ai.WithTools可重复追加单值选项如ai.WithSystem后者覆盖前者——选项本身就是可组合的请求组装单元。标准编码模式Flow、Tool 与类型化生成定义一个 Flow编排任务使用genkit.DefineFlow输入输出使用带 JSON tag 的类型化 struct 以保证 schema 生成流程内部的子步骤用genkit.Run创建独立的 trace spantype OrderInput struct { ID int json:id } type OrderOutput struct { Status string json:status } // 定义 flow var GetOrderStatusFlow genkit.DefineFlow(g, getOrderStatus, func(ctx context.Context, input *OrderInput) (*OrderOutput, error) { // 用 genkit.Run 为特定步骤创建 trace span status, err : genkit.Run(ctx, lookup-db, func() (string, error) { return Shipped, nil }) if err ! nil { return nil, err } return OrderOutput{Status: status}, nil }, )genkit.Run的源码注释go/genkit/genkit.go#L553-L618补充了一个规范文档没有明说的细节Run的步骤上下文不会传给fn因此步骤内部自己会追踪trace的调用HTTP 客户端、数据库调用会挂在外部 flow 下而不是该步骤下。若希望这些调用嵌套在该步骤的 span 之内应改用RunWithContext——它把步骤自己的 context 传给fn。定义一个 ToolTool 供模型调用描述description至关重要——模型靠它决定何时调用工具type WeatherInput struct { Location string json:location } var WeatherTool genkit.DefineTool(g, getWeather, fetches current weather for a location, func(ctx *ai.ToolContext, input *WeatherInput) (string, error) { // 实现逻辑 return Sunny, nil }, )DefineTool的 GoDoc 中给出了更完整的用法示例工具通过ai.WithTools(weatherTool)附加到生成请求中输入输出类型参数直接决定工具定义中的inputSchema与outputSchema引导模型正确构造入参、解释出参。类型化数据生成genkit.GenerateData[T]让模型的结构化输出直接落到 Go structtype Recipe struct { Name string json:name Ingredients []string json:ingredients } recipe, _, err : genkit.GenerateDataRecipe, ai.WithPrompt(Suggest a pancake recipe), )这就是Schema 严格性纪律的消费端struct 上的 JSON tag 既用于生成请求中的 schema 声明也用于响应的类型安全反序列化。代码质量与 Lint 规则规范对 Go 代码质量提出了明确且可执行的清单运行 Lint所有 Go 代码改动后在go/目录下执行go vet ./...格式化运行bin/fmt执行go fmt。该脚本位于仓库根目录 bin/fmt通过全部测试go test ./...生产级目标产出必须是生产级代码采用shift left策略——尽早捕获错误严格类型Go 是静态类型语言除非绝对必要且有文档说明不要使用interface{}或any不压制警告除非有充分且已记录的理由不要忽略 linter 警告导入分组标准库在前、第三方库居中、内部包在后由goimports自动处理。生成文件与数据模型跨语言 Canonical 一致性这是整份规范中最具架构价值的部分Genkit Go 的核心数据模型必须与 JavaScriptcanonical实现中定义的 JSON schema 完全一致且 Go 侧的许多类型文件是生成的、不可手改。不可手改的生成文件不编辑任何工具生成的文件protobuf、严格类型生成器等产物不直接编辑go/ai/gen.go——它是自动生成文件查看 go/ai/gen.go 可确认其带有标准的 Apache 2.0 生成文件头对核心类型的任何必要变换都必须作用于生成器脚本或schema 清洗器sanitizer不直接编辑genkit-tools/genkit-schema.json——它同样是生成物会被export:schemas脚本覆盖。再生成 gen.go 的三步管线当go/ai/gen.go中的类型需要更新时规范给出了完整的再生成流程修改genkit-tools/common/src/types/中的 Zod schema例如model.ts中的ToolDefinition见 genkit-tools/common/src/types/model.ts#L178 的ToolDefinitionSchema定义重新导出 JSON schemacd genkit-tools pnpm run export:schemas该脚本对应 genkit-tools/package.json#L10 中的npx tsx scripts/schema-exporter.ts .由 genkit-tools/scripts/schema-exporter.ts 实现重新生成 Go 代码cd go/core go run ../internal/cmd/jsonschemagen -outdir .. -config schemas.config ../../genkit-tools/genkit-schema.json ai生成器入口是 go/internal/cmd/jsonschemagen/配置文件是 go/core/schemas.config——一个 2100 余行的文件集中存放所有类型与字段的 GoDoc 文档如Role、Message、各 Part 类型的字段说明这些注释最终会写进生成的 Go 类型上。新增 Part 类型的注意事项规范特别提示新增 Part 类型时必须同步更新schemas.config把新 Part 类型追加到所有现有 Part 的联合oneOf定义中并按需为其添加 omit 配置。从 go/core/schemas.config 的文档段结构可以确认该文件正是各 Part 类型TextPart等的文档与清洗配置来源。类型、风格与文档规范目标环境Go 版本规范表述为Go 1.24 或更新版本当前 go/go.mod 声明为go 1.25.0模块路径为github.com/firebase/genkit/go依赖管理使用go mod。类型与风格标准gofmt格式错误处理使用if err ! nil惯用法短作用域使用短变量名索引i、上下文ctx接口定义在使用方consumer-side而非实现方producer-side——这是 Google 风格的 Go 惯例让接口贴近真实消费点并发使用 channel 与 goroutine尽量避免共享可变状态注释要求使用正确的标点函数注释以函数名开头stub 使用// TODO(issue-id): Fix this later.格式go vet必须无错通过。文档GoDoc为导出的包、类型、函数编写完整的 GoDoc 风格注释内容要求向不熟悉代码的读者解释术语与概念复杂流程尽量配图必备章节Overview包/函数做什么与Examples复杂 API 提供示例最佳实践是在_test.go文件中写Example函数——go/目录下大量example_test.go文件即为佐证;处理外部包时使用go doc命令理解类型与函数定义API 与概念的真理来源是官方文档站点与 GitHub 文档仓库的描述不确定时参考 JavaScript 的同名实现注释与文档中的示例保持简单在相关位置补充文档链接更新代码时同步更新包注释与函数注释并扫描所编辑包的全部文档保持最新。实现准则总是添加单元测试提升覆盖率优先使用 Genkit 原语和辅助函数而非 mock 类型追求与 JS canonical 实现的 API 和行为 1:1 一致每个新 API/功能都应有配套 sample为 flow 和 action 使用默认输入值以降低使用门槛sample 的包注释中要解释为什么、怎么做、是什么以及如何测试该 sample核心框架与插件代码中避免提及 sample 专属内容每个 sample 检查go.mod是否缺少依赖用到就补上模型提供商等插件变更时同步更新相关文档与 sample注释说明为什么而非是什么不留死代码与未使用导入代码变更时同步更新对应 README如果存在。格式化细节工具go fmt经由bin/fmt或编辑器行宽Go 无强制行宽但建议保持在合理范围约 80–100 字符长行与长字符串应适当换行。测试规范框架使用标准testing包新的核心代码不要引入 testify 等外部断言库现有插件可能已用 testify但一致性优先标准库断言遵循want/got模式的普通 if 块if got : func(); got ! want { t.Errorf(func() %v, want %v, got, want) }复杂对象struct、slice、map比较使用github.com/google/go-cmp/cmp必要时加cmpoptsif diff : cmp.Diff(want, got); diff ! { t.Errorf(mismatch (-want got):\n%s, diff) }范围编写遵循 fail-fast 原则的全面单元测试执行go test ./...移植测试移植测试时保持 1:1 逻辑一致性不臆造行为修复策略修复底层代码问题而不是在测试里特判绕过现代化修复底层问题时考虑使用modernize把代码更新为现代 Go 惯用法如slices、mapsGenkit 专属测试实践直接测 Action用flow.Run(ctx, input)或tool.Run(ctx, input)测试 Genkit 组件的逻辑验证 Schema确保DefineX返回的Action具有期望的输入/输出 schemaMock 模型测试调用模型的 Flow 时使用 mock 模型实现保证测试确定性internal/fakeembedder等内部测试工具即为此类Trace 检查对复杂 flow用测试验证genkit.Run的步骤按预期执行。日志规范规范对日志的三条约束与 go/core/logger/logger.go 的实现高度吻合库只要存在context.Context就使用core/logger的包级函数logger.Debug(ctx, ...)、logger.Info、logger.Warn、logger.Error。该包是一个 context 作用域的slog.Logger封装——包注释即声明 Package logger provides a context-scoped slog.Loggercontext 中的 logger 使日志记录能与活跃的 trace span 关联Dev UI、Cloud Logging仅在无 context 的场合包初始化、加载期代码才退回log/slog。格式使用结构化日志的键值对。消息用小写、稳定的短语、不带尾随标点可变数据放进属性绝不用fmt.Sprintf拼进消息错误使用键名error而非err。级别Debug每请求粒度的细节span、模型轮次、工具运行、middleware 钩子Info克制使用仅限一次性生命周期事件初始化完成、服务器开始监听;Warn配置错误、fallback、跳过的工作Error仅当错误没有同时返回给调用方时使用后台 goroutine、写 500 的服务处理器。绝不对同一个错误既打日志又返回。logger包还暴露了SetLevel、AddHandler、SetDefaultHandler等能力Genkit 在 dev 模式下通过AddHandler把日志流式送进 Dev UI应用若自行安装了默认 handlerSetLevel会保留应用 handler 并给出警告而不是擅自接管。许可头、Commit 规范与收尾要求Apache 2.0 许可头每个文件头部都包含 Apache 2.0 许可声明年份按需更新// Copyright [year] Google LLC // // Licensed under the Apache License, Version 2.0 (the License); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an AS IS BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // SPDX-License-Identifier: Apache-2.0仓库中所有源文件如 go/genkit/genkit.go均遵循此格式末尾附SPDX-License-Identifier: Apache-2.0行。Commit 消息规范完成改动后撰写纯文本 commit message不要在 commit message 中以链接形式包含绝对文件路径以#开头的行会被视为注释标题使用更简单的格式在列出变更明细之前先写一段说明为什么改和改了什么的理由段落使用 Conventional Commits 格式scope 参照 release-please 配置如果存在;保持简短。小结go/GEMINI.md用 250 余行覆盖了 Genkit Go SDK 从架构约定到收尾细节的完整开发纪律其背后都有扎实的源码支撑DefineX/NewX的注册语义对应 go/internal/registry/registry.go 中带 panic 保护的注册表schema 严格性对应从 genkit-tools/common/src/types/ 的 Zod 定义、经export:schemas与 go/internal/cmd/jsonschemagen/ 到 go/ai/gen.go 的单向生成管线日志纪律对应 go/core/logger/logger.go 的 context 作用域 slog 封装。遵循这套规范产出的代码才能与 Genkit 的 JS canonical 实现保持数据模型一致并持续通过go vet、go test ./...与 Dev UI 反射链路的验证。【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Genkit Go SDK 开发规范详解：注册表架构、DefineX 构造器与 Schema 生成管线
Genkit Go SDK 开发规范详解注册表架构、DefineX 构造器与 Schema 生成管线【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkitGenkit Go SDK 的仓库内开发规范go/GEMINI.md定义了 Go 端实现的核心工程纪律注册表优先Registry-First的组件发现机制、强制的context.Context传递、严格的 JSON Schema 生成约定以及从 TypeScript Zod 模式到 Go 代码的单向 Schema 管线。本文基于该规范文档结合 go/genkit/genkit.go、go/internal/registry/registry.go、go/core/logger/logger.go 等源码逐一验证其技术原理帮助你在阅读或扩展 Genkit Go SDK 时既掌握规范的每一条落地写法也能理解规范背后约束的实际实现。五大核心工程纪律go/GEMINI.md开篇列出五条必须遵守的操作协议它们构成了 Genkit Go 代码库的宪法。1. 注册表优先Registry-First ThinkingGenkit 围绕一个中央注册表构建。任何需要被反射 APIReflection API或 Dev UI 发现的组件Flow、Tool 等一律使用genkit.DefineX系列构造器如DefineFlow、DefineTool。从源码看这个注册动作并不神秘。以DefineFlow为例go/genkit/genkit.go#L485-L489 的实现只有三行先调用core.NewFlow创建组件再调用f.Register(g.reg)把组件写入 Genkit 实例持有的注册表然后返回组件本身。注册表的底层实现在 go/internal/registry/registry.goRegistry结构体持有actions、plugins、schemas、values四张以名称为键的 map并用读写锁保护并发访问。值得注意的是RegisterAction对重复注册会直接 panic——同一类型的同名 action 只能注册一次这从机制上保证了注册表中组件名的唯一性。注册表还支持父子层级NewChild创建继承父注册表的子注册表查找时未命中子表会回落到父表。这为插件沙箱和嵌套作用域提供了基础。2. Context 是强制的每个 Genkit 函数和工具执行都需要context.Context必须忠实地逐层传递除非是入口点否则实现内部不得凭空使用context.Background()。这一点在规范中列在第二条因为它同时影响可观测性与生命周期管理trace span、logger、取消信号都挂载在 context 上。后文的日志一节会展示这一约束如何在core/logger中落地。3. Schema 严格性为 Flow 或 Tool 定义输入/输出类型时必须使用带清晰 JSON tag 的 Go struct——模型正是依据这些 tag 和类型来理解接口的。Go SDK 在内部把 struct 反射为 JSON Schema注册表通过github.com/invopop/jsonschema完成 schema 解析见 go/internal/registry/registry.go 的 import 列表因此 struct 字段的json:...tag 就是模型看到的字段名。4. 先搜索再实现许多常用工具已存在于internal/base或ai/包中编写新的 JSON 解析或字符串操作逻辑之前应先检查。以 JSON 处理为例go/internal/base/extract.go 提供了ExtractJSON等宽松解析函数能处理模型输出中包裹在散文里的 JSON以及部分完成的 JSON 结构——这类容错解析正是模型输出解析的高频痛点internal/base中还有验证validation.go、类型转换json_type_converter.go等配套工具。5. 惯用并发优先使用 Go 原生并发goroutine/channel但要留意长生命周期后台任务中 context 的生命周期管理。包结构与组件构造器包布局规范中给出的包结构在当前仓库中完全对应genkit应用开发者的主入口提供定义 flow、prompt、tool 的高层函数go/genkit/genkit.goai核心 AI 类型与接口Model、Prompt、Tool、Embedder、Retriever 等core底层框架原语Actions、Flows、Tracing、Registry主要面向内部使用或插件开发plugins具体提供商的实现Google AI、Vertex AI、Ollama 等如 go/plugins/googlegenai/、go/plugins/ollama/internal私有实现、共享工具与开发工具其中baseJSON 抽取、规范化、验证与 context 处理的底层工具cmd代码生成jsonschemagen、文件同步copy、文档weave的内部命令行工具三个目录均可在 go/internal/cmd/ 下看到registryGenkit action 与 schema 注册表的实现metricsOpenTelemetry 指标埋点fakeembedder模拟 embedding 提供商的测试工具。DefineX 与 NewX 的分工这是本规范最重要的 API 设计决策DefineX如DefineFlow、DefineTool创建并注册组件到注册表。只有经过注册组件才能被反射 API 发现从而出现在 Dev UI 中。NewX如ai.NewTool创建组件但不注册。用于内部组件、动态创建或测试场景。从 go/genkit/genkit.go#L796-L800 可以看到DefineTool正是NewToolRegister的组合func DefineToolIn, Out any *ai.ToolAction[In, Out] { t : ai.NewTool(name, description, fn, opts...) t.Register(g.reg) return t }同样的模式贯穿DefineFlow、DefineModelAction、DefineBackgroundModelAction等所有构造器。DefineTool的 GoDoc 还列出了两个选项ai.WithInputSchema提供自定义 JSON schema 取代从类型参数推断的 schema与ai.WithInputSchemaName按名称引用已注册的 schema。函数式选项模式Options Pattern可选配置一律使用函数式选项如ai.WithModel、genkit.WithPlugins在构造器与方法调用中传递。这种方式让 API 保持稳定且可增量扩展。实际效果可参考 go/README.md 的快速上手示例g : genkit.Init(ctx, genkit.WithPlugins(googlegenai.GoogleAI{}))多值选项如ai.WithTools可重复追加单值选项如ai.WithSystem后者覆盖前者——选项本身就是可组合的请求组装单元。标准编码模式Flow、Tool 与类型化生成定义一个 Flow编排任务使用genkit.DefineFlow输入输出使用带 JSON tag 的类型化 struct 以保证 schema 生成流程内部的子步骤用genkit.Run创建独立的 trace spantype OrderInput struct { ID int json:id } type OrderOutput struct { Status string json:status } // 定义 flow var GetOrderStatusFlow genkit.DefineFlow(g, getOrderStatus, func(ctx context.Context, input *OrderInput) (*OrderOutput, error) { // 用 genkit.Run 为特定步骤创建 trace span status, err : genkit.Run(ctx, lookup-db, func() (string, error) { return Shipped, nil }) if err ! nil { return nil, err } return OrderOutput{Status: status}, nil }, )genkit.Run的源码注释go/genkit/genkit.go#L553-L618补充了一个规范文档没有明说的细节Run的步骤上下文不会传给fn因此步骤内部自己会追踪trace的调用HTTP 客户端、数据库调用会挂在外部 flow 下而不是该步骤下。若希望这些调用嵌套在该步骤的 span 之内应改用RunWithContext——它把步骤自己的 context 传给fn。定义一个 ToolTool 供模型调用描述description至关重要——模型靠它决定何时调用工具type WeatherInput struct { Location string json:location } var WeatherTool genkit.DefineTool(g, getWeather, fetches current weather for a location, func(ctx *ai.ToolContext, input *WeatherInput) (string, error) { // 实现逻辑 return Sunny, nil }, )DefineTool的 GoDoc 中给出了更完整的用法示例工具通过ai.WithTools(weatherTool)附加到生成请求中输入输出类型参数直接决定工具定义中的inputSchema与outputSchema引导模型正确构造入参、解释出参。类型化数据生成genkit.GenerateData[T]让模型的结构化输出直接落到 Go structtype Recipe struct { Name string json:name Ingredients []string json:ingredients } recipe, _, err : genkit.GenerateDataRecipe, ai.WithPrompt(Suggest a pancake recipe), )这就是Schema 严格性纪律的消费端struct 上的 JSON tag 既用于生成请求中的 schema 声明也用于响应的类型安全反序列化。代码质量与 Lint 规则规范对 Go 代码质量提出了明确且可执行的清单运行 Lint所有 Go 代码改动后在go/目录下执行go vet ./...格式化运行bin/fmt执行go fmt。该脚本位于仓库根目录 bin/fmt通过全部测试go test ./...生产级目标产出必须是生产级代码采用shift left策略——尽早捕获错误严格类型Go 是静态类型语言除非绝对必要且有文档说明不要使用interface{}或any不压制警告除非有充分且已记录的理由不要忽略 linter 警告导入分组标准库在前、第三方库居中、内部包在后由goimports自动处理。生成文件与数据模型跨语言 Canonical 一致性这是整份规范中最具架构价值的部分Genkit Go 的核心数据模型必须与 JavaScriptcanonical实现中定义的 JSON schema 完全一致且 Go 侧的许多类型文件是生成的、不可手改。不可手改的生成文件不编辑任何工具生成的文件protobuf、严格类型生成器等产物不直接编辑go/ai/gen.go——它是自动生成文件查看 go/ai/gen.go 可确认其带有标准的 Apache 2.0 生成文件头对核心类型的任何必要变换都必须作用于生成器脚本或schema 清洗器sanitizer不直接编辑genkit-tools/genkit-schema.json——它同样是生成物会被export:schemas脚本覆盖。再生成 gen.go 的三步管线当go/ai/gen.go中的类型需要更新时规范给出了完整的再生成流程修改genkit-tools/common/src/types/中的 Zod schema例如model.ts中的ToolDefinition见 genkit-tools/common/src/types/model.ts#L178 的ToolDefinitionSchema定义重新导出 JSON schemacd genkit-tools pnpm run export:schemas该脚本对应 genkit-tools/package.json#L10 中的npx tsx scripts/schema-exporter.ts .由 genkit-tools/scripts/schema-exporter.ts 实现重新生成 Go 代码cd go/core go run ../internal/cmd/jsonschemagen -outdir .. -config schemas.config ../../genkit-tools/genkit-schema.json ai生成器入口是 go/internal/cmd/jsonschemagen/配置文件是 go/core/schemas.config——一个 2100 余行的文件集中存放所有类型与字段的 GoDoc 文档如Role、Message、各 Part 类型的字段说明这些注释最终会写进生成的 Go 类型上。新增 Part 类型的注意事项规范特别提示新增 Part 类型时必须同步更新schemas.config把新 Part 类型追加到所有现有 Part 的联合oneOf定义中并按需为其添加 omit 配置。从 go/core/schemas.config 的文档段结构可以确认该文件正是各 Part 类型TextPart等的文档与清洗配置来源。类型、风格与文档规范目标环境Go 版本规范表述为Go 1.24 或更新版本当前 go/go.mod 声明为go 1.25.0模块路径为github.com/firebase/genkit/go依赖管理使用go mod。类型与风格标准gofmt格式错误处理使用if err ! nil惯用法短作用域使用短变量名索引i、上下文ctx接口定义在使用方consumer-side而非实现方producer-side——这是 Google 风格的 Go 惯例让接口贴近真实消费点并发使用 channel 与 goroutine尽量避免共享可变状态注释要求使用正确的标点函数注释以函数名开头stub 使用// TODO(issue-id): Fix this later.格式go vet必须无错通过。文档GoDoc为导出的包、类型、函数编写完整的 GoDoc 风格注释内容要求向不熟悉代码的读者解释术语与概念复杂流程尽量配图必备章节Overview包/函数做什么与Examples复杂 API 提供示例最佳实践是在_test.go文件中写Example函数——go/目录下大量example_test.go文件即为佐证;处理外部包时使用go doc命令理解类型与函数定义API 与概念的真理来源是官方文档站点与 GitHub 文档仓库的描述不确定时参考 JavaScript 的同名实现注释与文档中的示例保持简单在相关位置补充文档链接更新代码时同步更新包注释与函数注释并扫描所编辑包的全部文档保持最新。实现准则总是添加单元测试提升覆盖率优先使用 Genkit 原语和辅助函数而非 mock 类型追求与 JS canonical 实现的 API 和行为 1:1 一致每个新 API/功能都应有配套 sample为 flow 和 action 使用默认输入值以降低使用门槛sample 的包注释中要解释为什么、怎么做、是什么以及如何测试该 sample核心框架与插件代码中避免提及 sample 专属内容每个 sample 检查go.mod是否缺少依赖用到就补上模型提供商等插件变更时同步更新相关文档与 sample注释说明为什么而非是什么不留死代码与未使用导入代码变更时同步更新对应 README如果存在。格式化细节工具go fmt经由bin/fmt或编辑器行宽Go 无强制行宽但建议保持在合理范围约 80–100 字符长行与长字符串应适当换行。测试规范框架使用标准testing包新的核心代码不要引入 testify 等外部断言库现有插件可能已用 testify但一致性优先标准库断言遵循want/got模式的普通 if 块if got : func(); got ! want { t.Errorf(func() %v, want %v, got, want) }复杂对象struct、slice、map比较使用github.com/google/go-cmp/cmp必要时加cmpoptsif diff : cmp.Diff(want, got); diff ! { t.Errorf(mismatch (-want got):\n%s, diff) }范围编写遵循 fail-fast 原则的全面单元测试执行go test ./...移植测试移植测试时保持 1:1 逻辑一致性不臆造行为修复策略修复底层代码问题而不是在测试里特判绕过现代化修复底层问题时考虑使用modernize把代码更新为现代 Go 惯用法如slices、mapsGenkit 专属测试实践直接测 Action用flow.Run(ctx, input)或tool.Run(ctx, input)测试 Genkit 组件的逻辑验证 Schema确保DefineX返回的Action具有期望的输入/输出 schemaMock 模型测试调用模型的 Flow 时使用 mock 模型实现保证测试确定性internal/fakeembedder等内部测试工具即为此类Trace 检查对复杂 flow用测试验证genkit.Run的步骤按预期执行。日志规范规范对日志的三条约束与 go/core/logger/logger.go 的实现高度吻合库只要存在context.Context就使用core/logger的包级函数logger.Debug(ctx, ...)、logger.Info、logger.Warn、logger.Error。该包是一个 context 作用域的slog.Logger封装——包注释即声明 Package logger provides a context-scoped slog.Loggercontext 中的 logger 使日志记录能与活跃的 trace span 关联Dev UI、Cloud Logging仅在无 context 的场合包初始化、加载期代码才退回log/slog。格式使用结构化日志的键值对。消息用小写、稳定的短语、不带尾随标点可变数据放进属性绝不用fmt.Sprintf拼进消息错误使用键名error而非err。级别Debug每请求粒度的细节span、模型轮次、工具运行、middleware 钩子Info克制使用仅限一次性生命周期事件初始化完成、服务器开始监听;Warn配置错误、fallback、跳过的工作Error仅当错误没有同时返回给调用方时使用后台 goroutine、写 500 的服务处理器。绝不对同一个错误既打日志又返回。logger包还暴露了SetLevel、AddHandler、SetDefaultHandler等能力Genkit 在 dev 模式下通过AddHandler把日志流式送进 Dev UI应用若自行安装了默认 handlerSetLevel会保留应用 handler 并给出警告而不是擅自接管。许可头、Commit 规范与收尾要求Apache 2.0 许可头每个文件头部都包含 Apache 2.0 许可声明年份按需更新// Copyright [year] Google LLC // // Licensed under the Apache License, Version 2.0 (the License); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an AS IS BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // SPDX-License-Identifier: Apache-2.0仓库中所有源文件如 go/genkit/genkit.go均遵循此格式末尾附SPDX-License-Identifier: Apache-2.0行。Commit 消息规范完成改动后撰写纯文本 commit message不要在 commit message 中以链接形式包含绝对文件路径以#开头的行会被视为注释标题使用更简单的格式在列出变更明细之前先写一段说明为什么改和改了什么的理由段落使用 Conventional Commits 格式scope 参照 release-please 配置如果存在;保持简短。小结go/GEMINI.md用 250 余行覆盖了 Genkit Go SDK 从架构约定到收尾细节的完整开发纪律其背后都有扎实的源码支撑DefineX/NewX的注册语义对应 go/internal/registry/registry.go 中带 panic 保护的注册表schema 严格性对应从 genkit-tools/common/src/types/ 的 Zod 定义、经export:schemas与 go/internal/cmd/jsonschemagen/ 到 go/ai/gen.go 的单向生成管线日志纪律对应 go/core/logger/logger.go 的 context 作用域 slog 封装。遵循这套规范产出的代码才能与 Genkit 的 JS canonical 实现保持数据模型一致并持续通过go vet、go test ./...与 Dev UI 反射链路的验证。【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
