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