genkit

Genkit

当核心问题是**“这个 Firebase AI 功能应该直接集成客户端 SDK，还是构建可复用、由服务端负责的 Genkit 工作流？”**时，使用此技能。

本技能不用于提供冗长的 Genkit 教程、CLI 目录或 Firebase 产品介绍。 先梳理当前请求，选择一个所有权边界和运行模式，然后将 Firebase 平台操作和广泛的框架比较引导至相邻技能。

处理混合或含糊不清的请求前，请阅读 references/intake-packets-and-fallbacks.md。 选择主要模式前，请阅读 references/modes-and-routing.md。 运行时选择是真正悬而未决的问题时，请阅读 references/deployment-and-runtime-boundaries.md。 工作流已存在且信心是瓶颈时，请阅读 references/evals-and-observability.md。

何时使用此技能

• 移动或 Web 应用需要直接集成 Firebase AI Logic 客户端 SDK，包括模型设置、结构化输出、流式传输、App Check 或安全的客户端/服务端边界
• 后端或全栈功能需要可复用的 Genkit flow，而不是在各个路由处理程序中分散调用提供商
• 工作需要类型化契约、工具调用、检索、提示词文件、评估、追踪，或在服务端所有权边界内进行部署
• 请求明确涉及 Firebase AI Logic、Genkit，或要在客户端所有权与服务端所有权的实现方式之间做出选择
• 现有 Firebase AI 功能需要调试、评估、可观测性或发布就绪情况审查

何时不使用此技能

• 主要工作是 Firebase 引导配置、模拟器使用、Hosting/Functions 部署、身份验证/登录或 Admin CLI 操作 → firebase-cli
• 请求是通用前端流式传输/渲染，不涉及 Firebase AI SDK 或 Genkit 边界 → 相关的前端/Web 技能
• 真正的问题是广泛的框架选择（Genkit 与 Vercel AI SDK 或其他框架的比较） → survey
• 普通的提供商 SDK 或简单路由处理程序已经足够，且 Firebase/Genkit 并非必需 → 说明回退方案，并保持回答简洁

说明

步骤 1：梳理当前请求

在推荐 Genkit 前，记录最精简且有用的需求信息。

记录：

• 应用形态：Web | 移动端 | 后端 | 全栈 | 混合 | 未知
• 所有权：客户端功能 | 后端能力 | 混合 | 未知
• 请求材料：路由处理程序 | 功能概要 | 架构说明 | 已部署的 flow | 评估/追踪问题 | 部署计划 | 无
• 工作流需求：简单生成 | 结构化输出 | 工具 | 检索 | 提示词文件 | 评估 | 可观测性 | 部署 | 未知
• 交付压力：单个端点 | 多端复用 | 发布就绪 | 迁移 | 可靠性问题 | 未知

快速梳理：

App shape: fullstack
Ownership: backend capability
Packet: existing API route + support feature brief
Workflow need: retrieval + one ticket tool + evals later
Delivery pressure: reuse across web app and internal ops panel

步骤 2：先选择请求材料

请使用 references/intake-packets-and-fallbacks.md。

选择用户当前实际拥有的材料：

• 新后端能力需求
• 现有路由/处理程序材料
• 已部署工作流的质量问题
• 部署/运行时材料
• 比较/回退方案材料
• 尚无可用材料

此步骤的输出格式：

## Intake Packet
- Current packet:
- Why it is enough (or not enough):
- Missing context to collect next:

规则：不要仅仅因为应用已经使用 Firebase，就强行采用由服务端负责的 Genkit flow。

第 3 步：选择所有权层

在选择模式之前，明确做出客户端还是服务端的决策。

当主要需求是以下内容时，选择 client-ai-logic：

• 直接使用移动端／Web Firebase AI Logic SDK
• 客户端流式传输或结构化输出，且功能边界由小型应用负责
• App Check、客户端可见的模型配置，或客户端／服务端数据暴露规则

当主要需求是以下内容时，选择由服务端负责的 Genkit 模式：

• 可复用的后端 AI 契约或类型化流程边界
• 由一个位置负责管理工具、检索、提示词、评估或追踪
• 多个客户端、作业或受保护的服务端资源共用的能力

如果使用普通提供商 SDK、常规路由处理程序或更广泛的框架调研更合适，就不要强行选择上述任一层。

用一行说明此决策：

## Layer Decision
- Ownership: client-ai-logic | server-genkit | plain-sdk-fallback | survey-first
- Why:

第 4 步：选择一种主要运行模式

从 references/modes-and-routing.md 中选择一种主要模式。

主要模式：

• client-ai-logic
• flow-foundation
• tool-and-agent
• retrieval-and-prompt
• evaluation-and-observability
• deployment-runtime
• comparison-or-fallback

规则：一种主要模式，可选一种次要模式。 不要把客户端 SDK 接线、后端流程设计、部署运维和架构比较混成一团。

第 5 步：确定最小功能边界

对于 client-ai-logic，定义：

• 一个应用功能和模型交互
• 输入／输出或流式传输契约
• 客户端可见与仅限服务端的数据和配置
• App Check／身份验证／错误处理及防滥用边界

对于由服务端负责的 Genkit 模式，定义：

• 一个命名的后端能力和类型化流程契约
• 哪些内容必须保留在服务端
• 工具／检索／提示词（如有）
• 哪些客户端或作业会调用它

避免构建庞大的流程、向客户端暴露服务端密钥，或在基本路径正常运行之前添加工具／检索。

第 6 步：如实说明回退方案或转交方向

使用 references/intake-packets-and-fallbacks.md。

常见转交方向：

• Firebase CLI／模拟器／部署／管理员工作 → firebase-cli
• 不涉及 Firebase AI SDK 边界的通用前端渲染 → 相关前端／Web 技能
• 广泛的框架比较或架构不确定性 → survey
• 简单的非 Firebase 模型调用 → 普通提供商 SDK／路由处理程序回退方案
• 耐久性、重试或后台编排是主要问题 → 队列／作业／工作流底层方案

第 7 步：选择最小的下一步切片

不要直接跳到庞大的系统图。只返回一个切片：

• 接通一条客户端 SDK 生成／流式传输路径，并加入验证和防滥用边界
• 定义或封装一个服务端流程契约
• 添加一个工具或检索边界
• 添加一组有代表性的评估
• 选择一种运行时／部署形态

第 8 步：当信心成为瓶颈时，使用评估和追踪

使用 references/evals-and-observability.md。

如果工作流已经存在，优先执行：

1. 有代表性的输入
2. 本地追踪审查／Developer UI 检查
3. 小型评估集
4. 契约／提示词／工具清理
5. 只有在证据反馈循环足够完善后才推出

第 9 步：返回 Firebase AI 实施简报

# Firebase AI Implementation Brief

## Scope
- App shape:
- Ownership: client-ai-logic | server-genkit | fallback
- Intake packet:
- Primary mode:
- Confidence:

## Layer Decision
- Why this ownership fits:

## Feature Boundary
- Capability:
- Input / output or streaming contract:
- Client-visible / server-only responsibilities:
- Tools / retrieval / prompt-file needs:
- Auth, App Check, errors, and abuse boundaries:

## Smallest Next Slice
1. ...
2. ...
3. ...

## Route-outs / Fallbacks
- ...

示例

示例 1：可复用的后端支持工作流

输入：“为我们的支持应用构建一个 Genkit 后端流程：检索帮助文章、调用一个工单工具，并公开一个 Web 应用可复用的服务端端点。”

预期形态：tool-and-agent 或 retrieval-and-prompt，明确由服务端负责的流程边界，以及一项工具／检索计划。

示例 2：直接在 Firebase 应用中添加功能

输入：“使用 Firebase SDK，在我们的 Firebase Web 应用中直接添加由 Gemini 驱动的摘要功能。”

预期形态：client-ai-logic，包含由应用负责的 SDK 边界、结构化输出或流式传输契约、App Check／身份验证，并且不添加不必要的服务端流程。

示例 3：现有流程需要在发布前确认可靠性

输入：“我们的 Genkit 流程在本地运行正常，但在部署到 Cloud Run 之前，我们需要一套实用的评估与可观测性方案。”

预期形式：evaluation-and-observability、精简的证据闭环，并将运行时细节与 Firebase CLI 操作分开。

示例 4：尚未确定框架选择

输入：“对于这个 Firebase 应用，我们应该使用 Genkit、Firebase AI Logic、Vercel AI SDK，还是直接调用 SDK？”

预期形式：comparison-or-fallback，将广泛的框架选择引导至 survey，然后回到这里，选择 client-ai-logic 或由服务器负责的 Genkit 模式。

最佳实践

1. 在指定工具或模型之前，先确定客户端或服务器的职责边界。
2. 优先采用清晰、精简的功能／流程边界，而非笼统庞大的 AI 功能分类。
3. 将密钥和受保护的资源保留在服务器端；对于客户端直接调用，明确 App Check／身份验证和滥用防护边界。
4. 在足够满足需求时，说明使用普通路由处理程序／服务提供方 SDK 的回退方案。
5. 将运行时选择视为架构决策，而非 Genkit 必不可少的证明。
6. 在扩大推广范围之前，使用追踪和评估。
7. 每当入口边界发生变化时，同步更新精简的发现入口。

参考资料

• Firebase Genkit 文档：https://firebase.google.com/docs/genkit
• Genkit 文档：https://genkit.dev/docs/
• Genkit 流程文档：https://genkit.dev/docs/js/flows/
• Genkit 客户端访问文档：https://genkit.dev/docs/client/
• Firebase AI Logic 文档：https://firebase.google.com/docs/ai-logic
• Firebase AI Logic Web SDK 文档：https://firebase.google.com/docs/ai-logic/get-started?api=web
• ../firebase-cli/SKILL.md
• ../survey/SKILL.md
• ../survey/SKILL.md