Output Dev Types File

作者 growthxaia4f6bd40ab0e无许可证440 个星标收录于 2026年10月8日更新于 2026年10月8日仓库今天更新

Create types.ts files with Zod schemas for Output SDK workflows. Use when defining input/output schemas, creating type definitions, or fixing schema-related errors.

仅含说明Software Development AI & Agents

AI 生成的概览

说明如何为 Output SDK 工作流编写包含 Zod 模式的 types.ts 文件。

功能: 该技能提供为 Output SDK 工作流创建 types.ts 文件的说明和代码模式。内容涵盖从 @outputai/core 导入 z、定义工作流输入/输出模式与步骤模式、导出对应的 TypeScript 类型，以及应用 LLM 输出模式约束（例如在提供方会拒绝时避免数值和数组边界）。它还包含验证清单和常见模式示例。
适用场景: 在定义工作流的输入/输出模式、为步骤添加模式、重构现有类型定义，或修复模式校验与导入错误时使用。
运行要求: 仅为说明，不含脚本。假定已有使用 @outputai/core 包和 TypeScript 的 Output SDK 项目，并引用工作流、步骤、评估器、目录结构和代码风格等相关技能。

Creating types.ts Files with Zod Schemas

Overview

This skill documents how to create types.ts files for Output SDK workflows. These files contain Zod schemas for input/output validation and their corresponding TypeScript types.

When to Use This Skill

Creating a new workflow's type definitions
Adding new schemas for steps
Fixing schema validation errors
Refactoring existing type definitions

Critical Import Rule

ALWAYS import z from @outputai/core, NEVER from zod directly:

typescript

// CORRECTimport { z } from '@outputai/core';
// WRONG - will cause runtime errorsimport { z } from 'zod';

// CORRECTimport { z } from '@outputai/core';
// WRONG - will cause runtime errorsimport { z } from 'zod';

Related Skill: output-error-zod-import for troubleshooting import issues

Basic Structure

typescript

import { z } from '@outputai/core';
// 1. Workflow Input Schemaexport const WorkflowInputSchema = z.object( {  // Define input fields} );
// 2. Workflow Output Typeexport type WorkflowInput = z.infer<typeof WorkflowInputSchema>;export type WorkflowOutput = /* output type */;
// 3. Step Schemas (for each step)export const StepNameInputSchema = z.object( {  // Step input fields} );
export const StepNameOutputSchema = z.object( {  // Step output fields} );
// 4. Type Exportsexport type StepNameInput = z.infer<typeof StepNameInputSchema>;export type StepNameOutput = z.infer<typeof StepNameOutputSchema>;

import { z } from '@outputai/core';
// 1. Workflow Input Schemaexport const WorkflowInputSchema = z.object( {  // Define input fields} );
// 2. Workflow Output Typeexport type WorkflowInput = z.infer<typeof WorkflowInputSchema>;export type WorkflowOutput = /* output type */;
// 3. Step Schemas (for each step)export const StepNameInputSchema = z.object( {  // Step input fields} );
export const StepNameOutputSchema = z.object( {  // Step output fields} );
// 4. Type Exportsexport type StepNameInput = z.infer<typeof StepNameInputSchema>;export type StepNameOutput = z.infer<typeof StepNameOutputSchema>;

CRITICAL: Schema Constraints for LLM Output

Schemas passed to aiSdk.Output.object() are sent to LLM providers as tool definitions. Anthropic rejects several JSON Schema constraints that Zod methods produce. Getting this wrong causes runtime errors.

What Is NOT Allowed in LLM Output Schemas

Numbers: .min(), .max() on z.number() produce minimum/maximum -- rejected by Anthropic.
Arrays: .min(), .max(), .length() on z.array() produce minItems/maxItems -- Anthropic only supports minItems of 0 or 1. Values like .length( 3 ) or .min( 2 ) will be rejected.

Use `.describe()` Instead

.describe() is the primary mechanism for guiding LLM output quality. LLM providers use field names and descriptions from the schema to understand what each field should contain. Write clear, specific descriptions that communicate your intent.

Important: .describe() replaces both unsupported constraints AND prompt-based format instructions. Do not also describe the schema in the prompt -- the schema is sent to the provider automatically, and duplicating it reduces performance and creates drift risk. See output-dev-prompt-file for details.

typescript

// LLM output schema (sent to provider via aiSdk.Output.object()) -- .describe() ONLYconst llmOutputSchema = z.object( {  score: z.number().describe( 'Quality score 0-100' ),  confidence: z.number().describe( 'Confidence 0-1' ),  predictions: z.array( predictionSchema ).describe( 'Exactly 3 predictions' )} );
// Workflow/step validation schema (Zod-only, NOT sent to LLM) -- .min()/.max()/.length() OKconst workflowOutputSchema = z.object( {  score: z.number().min( 0 ).max( 100 ).describe( 'Quality score 0-100' ),  confidence: z.number().min( 0 ).max( 1 ).describe( 'Confidence 0-1' ),  predictions: z.array( predictionSchema ).length( 3 ).describe( 'Exactly 3 predictions' )} );

// LLM output schema (sent to provider via aiSdk.Output.object()) -- .describe() ONLYconst llmOutputSchema = z.object( {  score: z.number().describe( 'Quality score 0-100' ),  confidence: z.number().describe( 'Confidence 0-1' ),  predictions: z.array( predictionSchema ).describe( 'Exactly 3 predictions' )} );
// Workflow/step validation schema (Zod-only, NOT sent to LLM) -- .min()/.max()/.length() OKconst workflowOutputSchema = z.object( {  score: z.number().min( 0 ).max( 100 ).describe( 'Quality score 0-100' ),  confidence: z.number().min( 0 ).max( 1 ).describe( 'Confidence 0-1' ),  predictions: z.array( predictionSchema ).length( 3 ).describe( 'Exactly 3 predictions' )} );

When to Use Which

Context	`.min()/.max()/.length()`	`.describe()`
Schema passed to `aiSdk.Output.object()`	No (numbers or arrays)	Yes
`inputSchema` / `outputSchema` on steps	OK	Optional
`inputSchema` / `outputSchema` on workflows	OK	Optional
`outputSchema` on evaluators	OK	Optional

LLM Schemas Must Live in types.ts

Define all schemas used in aiSdk.Output.object() in types.ts and import them in step functions. Never define them inline -- this causes duplication and makes it harder to verify they follow the constraints above.

Common Schema Patterns

Basic Types

typescript

import { z } from '@outputai/core';
// Stringsconst stringField = z.string();const optionalString = z.string().optional();const stringWithDefault = z.string().default( 'default value' );const describedString = z.string().describe( 'Field description' );
// Numbersconst numberField = z.number();const integerField = z.number().int();const rangedNumber = z.number().min( 1 ).max( 100 ); // runtime only — NOT safe for aiSdk.Output.object() schemas
// Booleansconst booleanField = z.boolean();const defaultBoolean = z.boolean().default( false );
// Enumsconst enumField = z.enum( [ 'option1', 'option2', 'option3' ] );const enumWithDefault = z.enum( [ 'small', 'medium', 'large' ] ).default( 'medium' );

import { z } from '@outputai/core';
// Stringsconst stringField = z.string();const optionalString = z.string().optional();const stringWithDefault = z.string().default( 'default value' );const describedString = z.string().describe( 'Field description' );
// Numbersconst numberField = z.number();const integerField = z.number().int();const rangedNumber = z.number().min( 1 ).max( 100 ); // runtime only — NOT safe for aiSdk.Output.object() schemas
// Booleansconst booleanField = z.boolean();const defaultBoolean = z.boolean().default( false );
// Enumsconst enumField = z.enum( [ 'option1', 'option2', 'option3' ] );const enumWithDefault = z.enum( [ 'small', 'medium', 'large' ] ).default( 'medium' );

Complex Types

typescript

import { z } from '@outputai/core';
// Arraysconst stringArray = z.array( z.string() );const objectArray = z.array( z.object( { id: z.string(), name: z.string() } ) );
// Objectsconst nestedObject = z.object( {  user: z.object( {    id: z.string(),    email: z.string().email()  } ),  settings: z.object( {    notifications: z.boolean()  } )} );
// Union Typesconst flexibleInput = z.union( [  z.string(),  z.array( z.string() )] );
// Recordsconst keyValueMap = z.record( z.string(), z.number() );

import { z } from '@outputai/core';
// Arraysconst stringArray = z.array( z.string() );const objectArray = z.array( z.object( { id: z.string(), name: z.string() } ) );
// Objectsconst nestedObject = z.object( {  user: z.object( {    id: z.string(),    email: z.string().email()  } ),  settings: z.object( {    notifications: z.boolean()  } )} );
// Union Typesconst flexibleInput = z.union( [  z.string(),  z.array( z.string() )] );
// Recordsconst keyValueMap = z.record( z.string(), z.number() );

Validation Patterns

typescript

import { z } from '@outputai/core';
// String Validationsconst emailField = z.string().email();const urlField = z.string().url();const uuidField = z.string().uuid();const minLengthString = z.string().min( 1 );const maxLengthString = z.string().max( 1000 );
// Number Validationsconst positiveNumber = z.number().positive();const nonNegativeNumber = z.number().nonnegative();const percentageNumber = z.number().min( 0 ).max( 100 );
// Array Validations (runtime only — NOT safe for aiSdk.Output.object() schemas)const nonEmptyArray = z.array( z.string() ).min( 1 );const limitedArray = z.array( z.string() ).max( 10 );const fixedLengthArray = z.array( z.string() ).length( 3 );

import { z } from '@outputai/core';
// String Validationsconst emailField = z.string().email();const urlField = z.string().url();const uuidField = z.string().uuid();const minLengthString = z.string().min( 1 );const maxLengthString = z.string().max( 1000 );
// Number Validationsconst positiveNumber = z.number().positive();const nonNegativeNumber = z.number().nonnegative();const percentageNumber = z.number().min( 0 ).max( 100 );
// Array Validations (runtime only — NOT safe for aiSdk.Output.object() schemas)const nonEmptyArray = z.array( z.string() ).min( 1 );const limitedArray = z.array( z.string() ).max( 10 );const fixedLengthArray = z.array( z.string() ).length( 3 );

Complete Example

Based on a real workflow (image_infographic_nano):

typescript

import { z } from '@outputai/core';
// ============================================// Workflow Schemas// ============================================
export const WorkflowInputSchema = z.object( {  content: z.string().describe( 'Text content to generate image ideas from' ),  mode: z.enum( [ 'infographic' ] ).default( 'infographic' ).describe( 'Type of image to generate' ),  colorPalette: z.string().optional().describe( 'Color palette preference for the images' ),  artDirection: z.string().optional().describe( 'Art direction or style preference' ),  numberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of image concepts to generate' ),  referenceImageUrls: z.union( [    z.string(),    z.array( z.string() )  ] ).optional().describe( 'Reference image URLs for style guidance (max 14)' ),  aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ).default( '1:1' ).describe( 'Aspect ratio for generated images' ),  resolution: z.enum( [ '1K', '2K', '4K' ] ).default( '1K' ).describe( 'Resolution for generated images' ),  numberOfGenerations: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of images to generate per concept' ),  storageNamespace: z.string().optional().describe( 'S3 folder path for storing images' )} );
export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;export type WorkflowOutput = string[];
// ============================================// Step Schemas// ============================================
export const ValidateReferenceImagesInputSchema = z.object( {  referenceImageUrls: z.array( z.string() ).optional()} );
export const GenerateImageIdeasInputSchema = z.object( {  content: z.string(),  numberOfIdeas: z.number(),  colorPalette: z.string().optional(),  artDirection: z.string().optional()} );
export const GenerateImagesInputSchema = z.object( {  input: z.object( {    referenceImageUrls: z.union( [ z.string(), z.array( z.string() ) ] ).optional(),    aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ),    resolution: z.enum( [ '1K', '2K', '4K' ] ),    numberOfGenerations: z.number(),    storageNamespace: z.string().optional()  } ),  prompt: z.string()} );
// Schema for LLM response validationexport const ImageIdeasSchema = z.object( {  ideas: z.array( z.string() ).describe( 'Array of detailed image prompts for Gemini' )} );
// ============================================// Type Exports// ============================================
export type ValidateReferenceImagesInput = z.infer<typeof ValidateReferenceImagesInputSchema>;export type GenerateImageIdeasInput = z.infer<typeof GenerateImageIdeasInputSchema>;export type GenerateImagesInput = z.infer<typeof GenerateImagesInputSchema>;export type ImageIdeas = z.infer<typeof ImageIdeasSchema>;

import { z } from '@outputai/core';
// ============================================// Workflow Schemas// ============================================
export const WorkflowInputSchema = z.object( {  content: z.string().describe( 'Text content to generate image ideas from' ),  mode: z.enum( [ 'infographic' ] ).default( 'infographic' ).describe( 'Type of image to generate' ),  colorPalette: z.string().optional().describe( 'Color palette preference for the images' ),  artDirection: z.string().optional().describe( 'Art direction or style preference' ),  numberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of image concepts to generate' ),  referenceImageUrls: z.union( [    z.string(),    z.array( z.string() )  ] ).optional().describe( 'Reference image URLs for style guidance (max 14)' ),  aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ).default( '1:1' ).describe( 'Aspect ratio for generated images' ),  resolution: z.enum( [ '1K', '2K', '4K' ] ).default( '1K' ).describe( 'Resolution for generated images' ),  numberOfGenerations: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of images to generate per concept' ),  storageNamespace: z.string().optional().describe( 'S3 folder path for storing images' )} );
export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;export type WorkflowOutput = string[];
// ============================================// Step Schemas// ============================================
export const ValidateReferenceImagesInputSchema = z.object( {  referenceImageUrls: z.array( z.string() ).optional()} );
export const GenerateImageIdeasInputSchema = z.object( {  content: z.string(),  numberOfIdeas: z.number(),  colorPalette: z.string().optional(),  artDirection: z.string().optional()} );
export const GenerateImagesInputSchema = z.object( {  input: z.object( {    referenceImageUrls: z.union( [ z.string(), z.array( z.string() ) ] ).optional(),    aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ),    resolution: z.enum( [ '1K', '2K', '4K' ] ),    numberOfGenerations: z.number(),    storageNamespace: z.string().optional()  } ),  prompt: z.string()} );
// Schema for LLM response validationexport const ImageIdeasSchema = z.object( {  ideas: z.array( z.string() ).describe( 'Array of detailed image prompts for Gemini' )} );
// ============================================// Type Exports// ============================================
export type ValidateReferenceImagesInput = z.infer<typeof ValidateReferenceImagesInputSchema>;export type GenerateImageIdeasInput = z.infer<typeof GenerateImageIdeasInputSchema>;export type GenerateImagesInput = z.infer<typeof GenerateImagesInputSchema>;export type ImageIdeas = z.infer<typeof ImageIdeasSchema>;

Best Practices

1. Use Descriptive Field Descriptions

typescript

// Good - helps with documentation and error messagesz.string().describe( 'User email address for notifications' )
// Avoid - no context for errorsz.string()

// Good - helps with documentation and error messagesz.string().describe( 'User email address for notifications' )
// Avoid - no context for errorsz.string()

2. Provide Sensible Defaults

typescript

// Good - workflow works without optional fieldsnumberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 )
// Avoid - forces users to provide every fieldnumberOfIdeas: z.number().min( 1 ).max( 10 )

// Good - workflow works without optional fieldsnumberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 )
// Avoid - forces users to provide every fieldnumberOfIdeas: z.number().min( 1 ).max( 10 )

3. Separate Workflow and Step Schemas

typescript

// Workflow input schema (what the user provides)export const WorkflowInputSchema = z.object( { ... } );
// Step schemas (internal data shapes)export const StepNameInputSchema = z.object( { ... } );

// Workflow input schema (what the user provides)export const WorkflowInputSchema = z.object( { ... } );
// Step schemas (internal data shapes)export const StepNameInputSchema = z.object( { ... } );

4. Export Both Schemas and Types

typescript

// Export schema for runtime validationexport const UserSchema = z.object( { ... } );
// Export type for TypeScript type checkingexport type User = z.infer<typeof UserSchema>;

// Export schema for runtime validationexport const UserSchema = z.object( { ... } );
// Export type for TypeScript type checkingexport type User = z.infer<typeof UserSchema>;

Verification Checklist

z is imported from @outputai/core
WorkflowInputSchema is defined and exported
WorkflowInput type is exported
WorkflowOutput type is defined
Each step has corresponding input/output schemas
All schemas have .describe() for important fields
Optional fields use .optional() or .default()
Numeric fields have appropriate constraints (.min()/.max() for runtime schemas, .describe() for aiSdk.Output.object() schemas)
Code follows style conventions (see output-dev-code-style)

Related Skills

output-dev-workflow-function - Using schemas in workflow definitions
output-dev-step-function - Using schemas in step definitions
output-dev-evaluator-function - Using schemas in evaluator definitions
output-dev-folder-structure - Where types.ts belongs in the project
output-error-zod-import - Troubleshooting schema import issues
output-dev-code-style - Code style conventions

来源与署名

来源：growthxai/output位于coding_assistants/claude/plugins/outputai/skills/output-dev-types-file提交a4f6bd4

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Output Dev Types File

Creating types.ts Files with Zod Schemas

Overview

When to Use This Skill

Critical Import Rule

Basic Structure

CRITICAL: Schema Constraints for LLM Output

What Is NOT Allowed in LLM Output Schemas

Use `.describe()` Instead

When to Use Which

LLM Schemas Must Live in types.ts

Common Schema Patterns

Basic Types

Complex Types

Validation Patterns

Complete Example

Best Practices

1. Use Descriptive Field Descriptions

2. Provide Sensible Defaults

3. Separate Workflow and Step Schemas

4. Export Both Schemas and Types

Verification Checklist

Related Skills

来源与署名

更多来自 growthxai/output 的技能

Output Workflow Trace File

Output Plan Workflow

Output Meta Post Flight

Output Dev Step Function

Output Dev Scenario File

Output Dev Llm Streaming

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api

Output Dev Types File

Creating types.ts Files with Zod Schemas

Overview

When to Use This Skill

Critical Import Rule

Basic Structure

CRITICAL: Schema Constraints for LLM Output

What Is NOT Allowed in LLM Output Schemas

Use .describe() Instead

When to Use Which

LLM Schemas Must Live in types.ts

Common Schema Patterns

Basic Types

Complex Types

Validation Patterns

Complete Example

Best Practices

1. Use Descriptive Field Descriptions

2. Provide Sensible Defaults

3. Separate Workflow and Step Schemas

4. Export Both Schemas and Types

Verification Checklist

Related Skills

来源与署名

更多来自 growthxai/output 的技能

Output Workflow Trace File

Output Plan Workflow

Output Meta Post Flight

Output Dev Step Function

Output Dev Scenario File

Output Dev Llm Streaming

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api

Use `.describe()` Instead