developing-genkit-tooling

开发 Genkit 工具

命名约定

命名保持一致，有助于用户和 Agent 浏览工具。

CLI 命令

子命令使用带冒号分隔符的 kebab-case。

• 格式：noun:verb 或 category:action
• 示例：flow:run、eval:run、init
• 参数：代码中使用 camelCase（flowName），帮助文本中使用标准格式（<flowName>）。

MCP 工具

工具名称使用 snake_case，以符合 MCP 标准。

• 格式：verb_noun
• 示例：list_flows、run_flow、list_genkit_docs、read_genkit_docs

CLI 命令架构

命令使用 commander 实现在 cli/src/commands/ 中。

运行时交互

大多数命令都需要与用户项目的运行时交互。使用 runWithManager 工具处理运行时进程的生命周期。

import { runWithManager } from '../utils/manager-utils';

// ... command definition ...
.action(async (arg, options) => {
  await runWithManager(await findProjectRoot(), async (manager) => {
    // Interact with manager here
    const result = await manager.runAction({ key: arg });
  });
});

输出格式

• 日志记录：使用来自 @genkit-ai/tools-common/utils 的 logger。
• 机器可读：命令生成数据时，提供 JSON 输出或写入文件的选项。
• 流式传输：如果操作支持流式传输（例如 flow:run），则提供 --stream 标志，并将输出传递到标准输出。

MCP 工具架构

cli/src/mcp/ 中的 MCP 工具遵循两种不同的模式：静态和运行时。

静态工具（例如文档）

这些工具不需要正在运行的 Genkit 项目上下文。

• 注册：defineDocsTool(server: McpServer)
• 依赖项：仅需 server 实例。
• 使用场景：文档、使用指南、全局配置。

运行时工具（例如 Flows、运行时控制）

这些工具与特定 Genkit 项目的运行时交互。

• 注册：defineRuntimeTools(server: McpServer, options: McpToolOptions)
• 依赖项：需要包含 manager（进程管理器）和 projectRoot 的 options。
• Schema：必须使用 getCommonSchema(options.explicitProjectRoot, ...)，以确保工具在需要时能够接受 projectRoot 参数（例如，在多项目环境中）。

// Runtime tool definition pattern
server.registerTool(
  'my_runtime_tool',
  {
    inputSchema: getCommonSchema(options.explicitProjectRoot, {
      myArg: z.string(),
    }),
  },
  async (opts) => {
    // Resolve project root before action
    const rootOrError = resolveProjectRoot(
      options.explicitProjectRoot,
      opts,
      options.projectRoot
    );
    if (typeof rootOrError !== 'string') return rootOrError;

    // access manager via options.manager
  }
);

错误处理

MCP 工具通常应捕获错误，并将其作为带有 isError: true 的内容块返回，而不是抛出异常，以确保客户端收到结构化的错误响应。

try {
  // operation
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  return {
    isError: true,
    content: [{ type: 'text', text: `Error: ${message}` }],
  };
}