@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/docs/pipeline-sdk/PIPELINE_SDK_DESIGN.md

@@ -0,0 +1,1372 @@
+# moldClaw Pipeline SDK 설계 문서
+
+> **Version**: 1.0.0-draft  
+> **Date**: 2026-03-20  
+> **Status**: 설계 단계
+
+---
+
+## 1. 개요
+
+### 1.1 배경
+
+moldClaw의 비즈니스 모델에서 **파이프라인 마켓플레이스**가 핵심 수익원이다. 사용자들이 도메인별 파이프라인을 쉽게 개발하고 배포할 수 있는 SDK가 필요하다.
+
+### 1.2 목표
+
+- **개발자 친화적 API**: 직관적인 `definePipeline()` API
+- **플러그인 SDK와의 통합**: 기존 `definePluginEntry()` 패턴 위에 구축
+- **유연한 스텝 정의**: DSL 기반의 선언적 파이프라인 정의
+- **풍부한 훅 시스템**: 라이프사이클 전체에 걸친 이벤트 핸들링
+- **쉬운 배포**: CLI를 통한 테스트/퍼블리시 워크플로우
+
+### 1.3 기존 플러그인 SDK와의 관계
+
+```
+┌─────────────────────────────────────────┐
+│           Pipeline SDK (고수준)           │
+│  - definePipeline()                     │
+│  - 스텝 DSL                              │
+│  - UI 바인딩                             │
+└─────────────────┬───────────────────────┘
+                  │ 확장
+┌─────────────────▼───────────────────────┐
+│         Plugin SDK (저수준, 기존)          │
+│  - definePluginEntry()                  │
+│  - registerTool()                       │
+│  - registerHook()                       │
+│  - registerCommand()                    │
+└─────────────────────────────────────────┘
+```
+
+**Pipeline SDK는 Plugin SDK의 상위 추상화 레이어**이다. 내부적으로 플러그인 API를 활용하되, 파이프라인 특화 기능을 제공한다.
+
+---
+
+## 2. SDK 인터페이스 설계
+
+### 2.1 핵심 API: `definePipeline()`
+
+```typescript
+import { definePipeline, step, parallel, conditional } from "@moldclaw/pipeline-sdk";
+
+export default definePipeline({
+  // 메타데이터
+  id: "video-auto-editor",
+  name: "Video Auto Editor",
+  version: "1.0.0",
+  description: "자동 비디오 편집 파이프라인",
+  author: "moldClaw Team",
+  license: "MIT",
+
+  // 카테고리 및 태그
+  category: "media-production",
+  tags: ["video", "editing", "automation"],
+
+  // 가격 정책 (마켓플레이스용)
+  pricing: {
+    type: "one-time", // 'one-time' | 'subscription' | 'free'
+    price: 29.99,
+    currency: "USD",
+  },
+
+  // 의존성
+  dependencies: {
+    apis: ["meshy-ai", "tavily"], // 필요한 외부 API
+    tools: ["ffmpeg", "imagemagick"], // 필요한 시스템 도구
+    pipelines: [], // 다른 파이프라인 의존성
+  },
+
+  // 설정 스키마
+  configSchema: {
+    outputFormat: {
+      type: "select",
+      options: ["mp4", "webm", "mov"],
+      default: "mp4",
+      label: "출력 포맷",
+    },
+    quality: {
+      type: "slider",
+      min: 1,
+      max: 100,
+      default: 80,
+      label: "품질",
+    },
+    apiKeys: {
+      type: "secrets",
+      required: ["MESHY_API_KEY"],
+      optional: ["TAVILY_API_KEY"],
+    },
+  },
+
+  // 파이프라인 정의
+  pipeline: ({ input, config, context }) => [
+    step("analyze", {
+      name: "영상 분석",
+      description: "입력 영상의 씬 분석",
+      handler: async (ctx) => {
+        const scenes = await ctx.tools.ffprobe.analyze(input.videoPath);
+        return { scenes };
+      },
+    }),
+
+    parallel("process-scenes", {
+      name: "씬 병렬 처리",
+      items: (prev) => prev.scenes,
+      handler: async (ctx, scene) => {
+        // 각 씬에 대한 처리
+        return await processScene(scene, config);
+      },
+      maxConcurrency: 4,
+    }),
+
+    conditional("add-subtitles", {
+      condition: (ctx) => config.addSubtitles,
+      then: step("generate-subtitles", {
+        handler: async (ctx) => {
+          // 자막 생성 로직
+        },
+      }),
+    }),
+
+    step("render", {
+      name: "최종 렌더링",
+      handler: async (ctx) => {
+        return await ctx.tools.ffmpeg.render({
+          scenes: ctx.previous,
+          format: config.outputFormat,
+          quality: config.quality,
+        });
+      },
+      ui: {
+        snapshot: true, // UI 스냅샷 활성화
+        interactive: true, // 사용자 개입 허용
+      },
+    }),
+  ],
+
+  // 훅 정의
+  hooks: {
+    onStart: async (ctx) => {
+      ctx.logger.info("파이프라인 시작");
+    },
+    onStepComplete: async (ctx, stepId, result) => {
+      ctx.emit("progress", { step: stepId, status: "complete" });
+    },
+    onError: async (ctx, error, stepId) => {
+      ctx.logger.error(`스텝 ${stepId} 실패:`, error);
+      // 복구 로직
+    },
+    onComplete: async (ctx, result) => {
+      ctx.logger.info("파이프라인 완료");
+    },
+  },
+
+  // UI 정의 (하드 파이프라인용)
+  ui: {
+    type: "canvas", // 'canvas' | 'overlay' | 'none'
+    component: "./ui/EditorCanvas.tsx",
+    snapshotInterval: 1000, // ms
+  },
+});
+```
+
+### 2.2 타입 정의
+
+```typescript
+// packages/pipeline-sdk/src/types.ts
+
+/**
+ * 파이프라인 정의 옵션
+ */
+export interface PipelineDefinition<
+  TInput = unknown,
+  TOutput = unknown,
+  TConfig extends Record<string, unknown> = Record<string, unknown>,
+> {
+  // === 메타데이터 ===
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  license?: string;
+  repository?: string;
+  homepage?: string;
+
+  // === 분류 ===
+  category: PipelineCategory;
+  tags?: string[];
+
+  // === 가격 정책 ===
+  pricing?: PipelinePricing;
+
+  // === 의존성 ===
+  dependencies?: PipelineDependencies;
+
+  // === 설정 ===
+  configSchema?: PipelineConfigSchema<TConfig>;
+
+  // === 파이프라인 로직 ===
+  pipeline: PipelineBuilder<TInput, TOutput, TConfig>;
+
+  // === 훅 ===
+  hooks?: PipelineHooks<TInput, TOutput, TConfig>;
+
+  // === UI ===
+  ui?: PipelineUI;
+
+  // === 보안 ===
+  permissions?: PipelinePermissions;
+}
+
+/**
+ * 스텝 정의
+ */
+export interface StepDefinition<TIn = unknown, TOut = unknown> {
+  name: string;
+  description?: string;
+  handler: StepHandler<TIn, TOut>;
+
+  // 재시도 정책
+  retry?: {
+    maxAttempts: number;
+    delayMs: number;
+    backoffMultiplier?: number;
+  };
+
+  // 타임아웃
+  timeoutMs?: number;
+
+  // UI 설정
+  ui?: StepUIConfig;
+
+  // 조건부 스킵
+  skip?: (ctx: StepContext<TIn>) => boolean | Promise<boolean>;
+}
+
+/**
+ * 스텝 핸들러
+ */
+export type StepHandler<TIn, TOut> = (ctx: StepContext<TIn>) => Promise<TOut> | TOut;
+
+/**
+ * 스텝 실행 컨텍스트
+ */
+export interface StepContext<TIn = unknown> {
+  // 이전 스텝 결과
+  input: TIn;
+  previous: unknown;
+
+  // 설정
+  config: Record<string, unknown>;
+
+  // 도구들
+  tools: PipelineTools;
+
+  // 로거
+  logger: PipelineLogger;
+
+  // 이벤트 발행
+  emit: (event: string, data: unknown) => void;
+
+  // 상태 저장소
+  state: StateStore;
+
+  // UI 상호작용 (하드 파이프라인)
+  ui: PipelineUIBridge;
+
+  // 시그널
+  signal: AbortSignal;
+}
+
+/**
+ * 병렬 실행 스텝
+ */
+export interface ParallelStepDefinition<TItem, TOut> {
+  name: string;
+  items: (previousResult: unknown) => TItem[] | Promise<TItem[]>;
+  handler: (ctx: StepContext, item: TItem, index: number) => Promise<TOut>;
+  maxConcurrency?: number;
+  failFast?: boolean;
+}
+
+/**
+ * 조건부 스텝
+ */
+export interface ConditionalStepDefinition<TIn, TOut> {
+  condition: (ctx: StepContext<TIn>) => boolean | Promise<boolean>;
+  then: StepDefinition<TIn, TOut> | StepDefinition[];
+  else?: StepDefinition<TIn, TOut> | StepDefinition[];
+}
+
+/**
+ * 파이프라인 훅
+ */
+export interface PipelineHooks<TInput, TOutput, TConfig> {
+  onStart?: (ctx: PipelineContext<TInput, TConfig>) => void | Promise<void>;
+  onStepStart?: (ctx: PipelineContext<TInput, TConfig>, stepId: string) => void | Promise<void>;
+  onStepComplete?: (
+    ctx: PipelineContext<TInput, TConfig>,
+    stepId: string,
+    result: unknown,
+  ) => void | Promise<void>;
+  onStepError?: (
+    ctx: PipelineContext<TInput, TConfig>,
+    stepId: string,
+    error: Error,
+  ) => void | Promise<void>;
+  onProgress?: (
+    ctx: PipelineContext<TInput, TConfig>,
+    progress: PipelineProgress,
+  ) => void | Promise<void>;
+  onPause?: (ctx: PipelineContext<TInput, TConfig>) => void | Promise<void>;
+  onResume?: (ctx: PipelineContext<TInput, TConfig>) => void | Promise<void>;
+  onCancel?: (ctx: PipelineContext<TInput, TConfig>) => void | Promise<void>;
+  onError?: (
+    ctx: PipelineContext<TInput, TConfig>,
+    error: Error,
+    stepId?: string,
+  ) => void | Promise<void>;
+  onComplete?: (ctx: PipelineContext<TInput, TConfig>, result: TOutput) => void | Promise<void>;
+}
+
+/**
+ * UI 브릿지 (하드 파이프라인용)
+ */
+export interface PipelineUIBridge {
+  // 스냅샷 캡처
+  snapshot(): Promise<UISnapshot>;
+
+  // 사용자 입력 대기
+  waitForInput<T>(schema: InputSchema): Promise<T>;
+
+  // UI 상태 업데이트
+  updateState(state: Record<string, unknown>): void;
+
+  // 알림 표시
+  notify(message: string, type: "info" | "warning" | "error"): void;
+
+  // 확인 다이얼로그
+  confirm(message: string): Promise<boolean>;
+}
+
+/**
+ * 파이프라인 카테고리
+ */
+export type PipelineCategory =
+  | "productivity"
+  | "media-production"
+  | "development"
+  | "data-analysis"
+  | "marketing"
+  | "customer-support"
+  | "research"
+  | "education"
+  | "finance"
+  | "healthcare"
+  | "gaming"
+  | "creative"
+  | "automation"
+  | "other";
+
+/**
+ * 가격 정책
+ */
+export interface PipelinePricing {
+  type: "free" | "one-time" | "subscription";
+  price?: number;
+  currency?: string;
+  subscriptionPeriod?: "monthly" | "yearly";
+  trialDays?: number;
+}
+
+/**
+ * 의존성 정의
+ */
+export interface PipelineDependencies {
+  // 필요한 외부 API (API 키 등)
+  apis?: string[];
+
+  // 필요한 시스템 도구 (ffmpeg, imagemagick 등)
+  tools?: string[];
+
+  // 다른 파이프라인 의존성
+  pipelines?: Array<{
+    id: string;
+    version?: string;
+  }>;
+
+  // MCP 서버 의존성
+  mcpServers?: string[];
+
+  // npm 패키지 의존성
+  npm?: Record<string, string>;
+}
+
+/**
+ * 설정 스키마 필드
+ */
+export type ConfigField =
+  | { type: "string"; default?: string; label?: string; placeholder?: string; validation?: RegExp }
+  | { type: "number"; default?: number; min?: number; max?: number; label?: string }
+  | { type: "boolean"; default?: boolean; label?: string }
+  | { type: "select"; options: string[]; default?: string; label?: string }
+  | { type: "slider"; min: number; max: number; default?: number; step?: number; label?: string }
+  | { type: "file"; accept?: string[]; label?: string }
+  | { type: "directory"; label?: string }
+  | { type: "secrets"; required?: string[]; optional?: string[] }
+  | { type: "json"; schema?: Record<string, unknown>; label?: string };
+
+export type PipelineConfigSchema<T = Record<string, unknown>> = {
+  [K in keyof T]: ConfigField;
+};
+```
+
+### 2.3 스텝 DSL 헬퍼
+
+```typescript
+// packages/pipeline-sdk/src/dsl.ts
+
+/**
+ * 단일 스텝 정의
+ */
+export function step<TIn = unknown, TOut = unknown>(
+  id: string,
+  definition: StepDefinition<TIn, TOut>,
+): Step<TIn, TOut> {
+  return {
+    type: "step",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 병렬 처리 스텝
+ */
+export function parallel<TItem, TOut>(
+  id: string,
+  definition: ParallelStepDefinition<TItem, TOut>,
+): ParallelStep<TItem, TOut> {
+  return {
+    type: "parallel",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 조건부 분기
+ */
+export function conditional<TIn, TOut>(
+  id: string,
+  definition: ConditionalStepDefinition<TIn, TOut>,
+): ConditionalStep<TIn, TOut> {
+  return {
+    type: "conditional",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 반복 스텝
+ */
+export function loop<TIn, TOut>(
+  id: string,
+  definition: {
+    name: string;
+    until: (ctx: StepContext, iteration: number) => boolean | Promise<boolean>;
+    handler: StepHandler<TIn, TOut>;
+    maxIterations?: number;
+  },
+): LoopStep<TIn, TOut> {
+  return {
+    type: "loop",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 서브파이프라인 호출
+ */
+export function subpipeline(
+  id: string,
+  definition: {
+    pipelineId: string;
+    input: (ctx: StepContext) => unknown;
+    config?: Record<string, unknown>;
+  },
+): SubpipelineStep {
+  return {
+    type: "subpipeline",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 사용자 상호작용 대기
+ */
+export function waitForUser<T>(
+  id: string,
+  definition: {
+    name: string;
+    prompt: string;
+    schema: InputSchema;
+    timeoutMs?: number;
+  },
+): UserInteractionStep<T> {
+  return {
+    type: "user-interaction",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 지연 스텝
+ */
+export function delay(
+  id: string,
+  definition: {
+    name: string;
+    durationMs: number | ((ctx: StepContext) => number);
+  },
+): DelayStep {
+  return {
+    type: "delay",
+    id,
+    ...definition,
+  };
+}
+
+/**
+ * 외부 API 호출 스텝
+ */
+export function apiCall<TOut>(
+  id: string,
+  definition: {
+    name: string;
+    api: string;
+    method: string;
+    params: (ctx: StepContext) => Record<string, unknown>;
+    transform?: (response: unknown) => TOut;
+  },
+): APICallStep<TOut> {
+  return {
+    type: "api-call",
+    id,
+    ...definition,
+  };
+}
+```
+
+### 2.4 도구 및 API 통합
+
+```typescript
+// packages/pipeline-sdk/src/tools.ts
+
+/**
+ * 파이프라인에서 사용 가능한 도구들
+ */
+export interface PipelineTools {
+  // moldClaw 내장 도구
+  moldclaw: {
+    exec: (command: string, opts?: ExecOptions) => Promise<ExecResult>;
+    read: (path: string) => Promise<string>;
+    write: (path: string, content: string) => Promise<void>;
+    browser: BrowserTool;
+    canvas: CanvasTool;
+  };
+
+  // 등록된 외부 API
+  api: {
+    call: <T>(apiId: string, method: string, params: Record<string, unknown>) => Promise<T>;
+    isConfigured: (apiId: string) => boolean;
+  };
+
+  // MCP 서버 도구
+  mcp: {
+    invoke: <T>(serverId: string, method: string, params: Record<string, unknown>) => Promise<T>;
+    list: () => string[];
+  };
+
+  // LLM 호출
+  llm: {
+    complete: (params: LLMCompleteParams) => Promise<string>;
+    stream: (params: LLMCompleteParams) => AsyncIterator<string>;
+  };
+
+  // 파일 시스템 헬퍼
+  fs: {
+    exists: (path: string) => Promise<boolean>;
+    mkdir: (path: string, opts?: { recursive?: boolean }) => Promise<void>;
+    readJson: <T>(path: string) => Promise<T>;
+    writeJson: (path: string, data: unknown) => Promise<void>;
+    glob: (pattern: string) => Promise<string[]>;
+    tempDir: () => Promise<string>;
+  };
+
+  // HTTP 클라이언트
+  http: {
+    get: <T>(url: string, opts?: HttpOptions) => Promise<T>;
+    post: <T>(url: string, body: unknown, opts?: HttpOptions) => Promise<T>;
+    put: <T>(url: string, body: unknown, opts?: HttpOptions) => Promise<T>;
+    delete: <T>(url: string, opts?: HttpOptions) => Promise<T>;
+  };
+}
+
+/**
+ * API 등록 (서드파티 파이프라인 개발자용)
+ */
+export function registerAPI(definition: APIDefinition): void;
+
+export interface APIDefinition {
+  id: string;
+  name: string;
+  baseUrl: string;
+  auth: {
+    type: "api-key" | "bearer" | "oauth2";
+    envVar?: string;
+    headerName?: string;
+  };
+  methods: Record<string, APIMethod>;
+}
+
+export interface APIMethod {
+  path: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  params?: Record<string, { type: string; required?: boolean }>;
+  transform?: (response: unknown) => unknown;
+}
+```
+
+---
+
+## 3. CLI 명령어 스펙
+
+### 3.1 명령어 구조
+
+```
+moldclaw pipeline <command> [options]
+
+Commands:
+  init [template]     새 파이프라인 프로젝트 생성
+  dev                 개발 모드로 파이프라인 실행
+  test [--watch]      파이프라인 테스트 실행
+  build               프로덕션 빌드
+  publish             마켓플레이스에 퍼블리시
+  list                설치된 파이프라인 목록
+  install <id>        마켓플레이스에서 파이프라인 설치
+  uninstall <id>      파이프라인 제거
+  update [id]         파이프라인 업데이트
+  info <id>           파이프라인 상세 정보
+  run <id> [input]    파이프라인 실행
+
+Options:
+  -h, --help          도움말 표시
+  -v, --version       버전 표시
+  --verbose           상세 출력
+```
+
+### 3.2 `moldclaw pipeline init`
+
+```bash
+# 기본 템플릿
+moldclaw pipeline init
+
+# 특정 템플릿 사용
+moldclaw pipeline init --template video-editor
+moldclaw pipeline init --template data-processor
+moldclaw pipeline init --template chatbot
+
+# 옵션
+moldclaw pipeline init [name] \
+  --template <template>     # 템플릿 선택
+  --directory <dir>         # 생성 디렉토리
+  --typescript              # TypeScript 사용 (기본값)
+  --javascript              # JavaScript 사용
+  --package-manager <pm>    # npm | yarn | pnpm
+  --git                     # git 초기화
+  --no-git                  # git 초기화 안 함
+```
+
+**대화형 모드:**
+
+```
+? 파이프라인 이름: my-awesome-pipeline
+? 설명: An awesome pipeline for doing awesome things
+? 카테고리: (Use arrow keys)
+  ❯ productivity
+    media-production
+    development
+    data-analysis
+    ...
+? 템플릿 선택: (Use arrow keys)
+  ❯ blank - 빈 템플릿
+    simple - 단순 선형 파이프라인
+    parallel - 병렬 처리 예제
+    interactive - UI 상호작용 예제
+    api-integration - 외부 API 연동 예제
+? TypeScript 사용? (Y/n)
+? Git 초기화? (Y/n)
+
+✔ 파이프라인 프로젝트 생성 완료!
+
+다음 단계:
+  cd my-awesome-pipeline
+  npm install
+  moldclaw pipeline dev
+```
+
+### 3.3 `moldclaw pipeline dev`
+
+```bash
+# 개발 모드 실행
+moldclaw pipeline dev
+
+# 옵션
+moldclaw pipeline dev \
+  --port <port>           # 개발 서버 포트 (기본: 4321)
+  --no-hot-reload         # 핫 리로드 비활성화
+  --mock-apis             # API를 목업으로 대체
+  --input <file>          # 입력 파일/JSON
+  --config <file>         # 설정 파일
+  --debug                 # 디버그 모드
+```
+
+### 3.4 `moldclaw pipeline test`
+
+```bash
+# 테스트 실행
+moldclaw pipeline test
+
+# 옵션
+moldclaw pipeline test \
+  --watch                 # 파일 변경 감지
+  --coverage              # 커버리지 리포트
+  --filter <pattern>      # 테스트 필터
+  --timeout <ms>          # 타임아웃
+  --parallel              # 병렬 실행
+  --snapshot              # 스냅샷 테스트
+  --update-snapshots      # 스냅샷 업데이트
+```
+
+### 3.5 `moldclaw pipeline build`
+
+```bash
+# 프로덕션 빌드
+moldclaw pipeline build
+
+# 옵션
+moldclaw pipeline build \
+  --output <dir>          # 출력 디렉토리
+  --minify                # 코드 압축
+  --sourcemap             # 소스맵 생성
+  --analyze               # 번들 분석
+  --target <target>       # 타겟 환경 (node | browser | universal)
+```
+
+### 3.6 `moldclaw pipeline publish`
+
+```bash
+# 마켓플레이스에 퍼블리시
+moldclaw pipeline publish
+
+# 옵션
+moldclaw pipeline publish \
+  --tag <tag>             # 버전 태그 (latest, beta, alpha)
+  --dry-run               # 실제 퍼블리시 없이 검증만
+  --access <access>       # public | private | unlisted
+  --pricing <type>        # free | paid
+  --price <amount>        # 가격 (paid인 경우)
+  --changelog <file>      # 변경 로그 파일
+```
+
+**퍼블리시 프로세스:**
+
+```
+$ moldclaw pipeline publish
+
+📦 Building pipeline...
+✔ Build successful
+
+🔍 Validating...
+  ✔ Package structure valid
+  ✔ Dependencies resolved
+  ✔ Security scan passed
+  ✔ Metadata complete
+
+📋 Pipeline Details:
+  Name: video-auto-editor
+  Version: 1.0.0
+  Category: media-production
+  Pricing: one-time ($29.99 USD)
+
+? Confirm publish? (Y/n) Y
+
+🚀 Publishing to moldClaw Marketplace...
+  ⠋ Uploading package...
+  ✔ Package uploaded
+  ⠋ Processing...
+  ✔ Processing complete
+  ⠋ Indexing...
+  ✔ Indexed
+
+✅ Published successfully!
+   https://marketplace.moldclaw.com/pipelines/video-auto-editor
+```
+
+### 3.7 `moldclaw pipeline run`
+
+```bash
+# 파이프라인 실행
+moldclaw pipeline run video-auto-editor --input ./my-video.mp4
+
+# 옵션
+moldclaw pipeline run <pipeline-id> \
+  --input <file|json>     # 입력 데이터
+  --config <file>         # 설정 오버라이드
+  --output <dir>          # 출력 디렉토리
+  --dry-run               # 실제 실행 없이 시뮬레이션
+  --resume <checkpoint>   # 체크포인트에서 재개
+  --async                 # 비동기 실행 (백그라운드)
+  --notify                # 완료 시 알림
+```
+
+---
+
+## 4. 템플릿 구조
+
+### 4.1 기본 프로젝트 구조
+
+```
+my-pipeline/
+├── package.json
+├── tsconfig.json
+├── moldclaw.pipeline.json     # 파이프라인 메타데이터
+├── src/
+│   ├── index.ts               # 메인 엔트리
+│   ├── steps/                 # 스텝 정의
+│   │   ├── analyze.ts
+│   │   ├── process.ts
+│   │   └── render.ts
+│   ├── hooks/                 # 커스텀 훅
+│   │   └── logging.ts
+│   ├── utils/                 # 유틸리티
+│   │   └── helpers.ts
+│   └── types.ts               # 타입 정의
+├── ui/                        # UI 컴포넌트 (하드 파이프라인)
+│   ├── EditorCanvas.tsx
+│   └── styles.css
+├── tests/                     # 테스트
+│   ├── pipeline.test.ts
+│   └── fixtures/
+├── docs/                      # 문서
+│   ├── README.md
+│   └── USAGE.md
+└── .moldclaw/                 # 로컬 설정
+    └── secrets.json
+```
+
+### 4.2 `package.json` 예시
+
+```json
+{
+  "name": "video-auto-editor",
+  "version": "1.0.0",
+  "description": "자동 비디오 편집 파이프라인",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "moldclaw pipeline dev",
+    "build": "tsc && moldclaw pipeline build",
+    "test": "moldclaw pipeline test",
+    "publish": "moldclaw pipeline publish"
+  },
+  "moldclaw": {
+    "type": "pipeline",
+    "entrypoint": "./dist/index.js"
+  },
+  "keywords": ["moldclaw-pipeline", "video", "editing", "automation"],
+  "dependencies": {
+    "@moldclaw/pipeline-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@moldclaw/pipeline-sdk-types": "^1.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "moldclaw": ">=0.1.0"
+  }
+}
+```
+
+### 4.3 `moldclaw.pipeline.json`
+
+```json
+{
+  "$schema": "https://moldclaw.com/schemas/pipeline.json",
+  "id": "video-auto-editor",
+  "name": "Video Auto Editor",
+  "version": "1.0.0",
+  "description": "자동 비디오 편집 파이프라인",
+  "author": {
+    "name": "moldClaw Team",
+    "email": "team@moldclaw.com",
+    "url": "https://moldclaw.com"
+  },
+  "repository": "https://github.com/moldclaw/video-auto-editor",
+  "license": "MIT",
+  "category": "media-production",
+  "tags": ["video", "editing", "automation", "ffmpeg"],
+  "icon": "./assets/icon.png",
+  "screenshots": ["./assets/screenshot-1.png", "./assets/screenshot-2.png"],
+  "pricing": {
+    "type": "one-time",
+    "price": 29.99,
+    "currency": "USD"
+  },
+  "runtime": {
+    "minVersion": "0.1.0",
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "apis": ["meshy-ai"],
+    "tools": ["ffmpeg", "ffprobe"],
+    "npm": {
+      "sharp": "^0.33.0"
+    }
+  },
+  "permissions": {
+    "filesystem": ["read", "write"],
+    "network": ["outbound"],
+    "shell": ["restricted"]
+  },
+  "ui": {
+    "type": "canvas",
+    "component": "./ui/EditorCanvas.tsx"
+  }
+}
+```
+
+### 4.4 도메인별 템플릿
+
+#### 4.4.1 `blank` - 빈 템플릿
+
+```typescript
+// src/index.ts
+import { definePipeline, step } from "@moldclaw/pipeline-sdk";
+
+export default definePipeline({
+  id: "my-pipeline",
+  name: "My Pipeline",
+  version: "0.1.0",
+  description: "A new moldClaw pipeline",
+  category: "other",
+
+  pipeline: ({ input }) => [
+    step("main", {
+      name: "Main Step",
+      handler: async (ctx) => {
+        // Your logic here
+        return { result: "Hello, World!" };
+      },
+    }),
+  ],
+});
+```
+
+#### 4.4.2 `data-processor` - 데이터 처리 템플릿
+
+```typescript
+import { definePipeline, step, parallel } from "@moldclaw/pipeline-sdk";
+
+export default definePipeline({
+  id: "data-processor",
+  name: "Data Processor",
+  version: "0.1.0",
+  description: "Batch data processing pipeline",
+  category: "data-analysis",
+
+  configSchema: {
+    inputPath: { type: "directory", label: "Input Directory" },
+    outputPath: { type: "directory", label: "Output Directory" },
+    format: { type: "select", options: ["json", "csv", "parquet"], default: "json" },
+    batchSize: { type: "number", default: 100, min: 1, max: 10000 },
+  },
+
+  pipeline: ({ input, config }) => [
+    step("scan", {
+      name: "Scan Input Files",
+      handler: async (ctx) => {
+        const files = await ctx.tools.fs.glob(`${config.inputPath}/**/*`);
+        return { files };
+      },
+    }),
+
+    parallel("process", {
+      name: "Process Files",
+      items: (prev) => chunk(prev.files, config.batchSize),
+      handler: async (ctx, batch) => {
+        return await Promise.all(batch.map(processFile));
+      },
+      maxConcurrency: 4,
+    }),
+
+    step("aggregate", {
+      name: "Aggregate Results",
+      handler: async (ctx) => {
+        const results = ctx.previous.flat();
+        await ctx.tools.fs.writeJson(`${config.outputPath}/results.${config.format}`, results);
+        return { count: results.length };
+      },
+    }),
+  ],
+});
+```
+
+#### 4.4.3 `chatbot` - 대화형 AI 템플릿
+
+```typescript
+import { definePipeline, step, loop, waitForUser } from "@moldclaw/pipeline-sdk";
+
+export default definePipeline({
+  id: "custom-chatbot",
+  name: "Custom Chatbot",
+  version: "0.1.0",
+  description: "Interactive chatbot pipeline",
+  category: "customer-support",
+
+  configSchema: {
+    systemPrompt: { type: "string", label: "System Prompt" },
+    model: { type: "select", options: ["claude-4", "gpt-4o", "gemini-2"], default: "claude-4" },
+    temperature: { type: "slider", min: 0, max: 2, default: 0.7, step: 0.1 },
+  },
+
+  pipeline: ({ config }) => [
+    step("init", {
+      name: "Initialize Chat",
+      handler: async (ctx) => {
+        ctx.state.set("history", []);
+        return { ready: true };
+      },
+    }),
+
+    loop("chat", {
+      name: "Chat Loop",
+      until: (ctx) => ctx.state.get("exit") === true,
+      handler: async (ctx) => {
+        // Wait for user input
+        const userMessage = await ctx.ui.waitForInput({ type: "text", prompt: "You:" });
+
+        if (userMessage.toLowerCase() === "/exit") {
+          ctx.state.set("exit", true);
+          return { message: "Goodbye!" };
+        }
+
+        // Get AI response
+        const history = ctx.state.get("history");
+        const response = await ctx.tools.llm.complete({
+          model: config.model,
+          messages: [
+            { role: "system", content: config.systemPrompt },
+            ...history,
+            { role: "user", content: userMessage },
+          ],
+          temperature: config.temperature,
+        });
+
+        // Update history
+        history.push(
+          { role: "user", content: userMessage },
+          { role: "assistant", content: response },
+        );
+        ctx.state.set("history", history);
+
+        return { response };
+      },
+      maxIterations: 100,
+    }),
+  ],
+});
+```
+
+#### 4.4.4 `video-editor` - 비디오 편집 템플릿 (하드 파이프라인)
+
+```typescript
+import { definePipeline, step, parallel, waitForUser } from "@moldclaw/pipeline-sdk";
+
+export default definePipeline({
+  id: "video-editor",
+  name: "Video Editor",
+  version: "0.1.0",
+  description: "Interactive video editing pipeline",
+  category: "media-production",
+
+  dependencies: {
+    tools: ["ffmpeg", "ffprobe"],
+    apis: ["openai-whisper"],
+  },
+
+  ui: {
+    type: "canvas",
+    component: "./ui/VideoEditorCanvas.tsx",
+    snapshotInterval: 500,
+  },
+
+  pipeline: ({ input, config }) => [
+    step("load", {
+      name: "Load Video",
+      handler: async (ctx) => {
+        const metadata = await ctx.tools.moldclaw.exec(
+          `ffprobe -v quiet -print_format json -show_format -show_streams "${input.videoPath}"`,
+        );
+        ctx.ui.updateState({ video: JSON.parse(metadata.stdout) });
+        return { metadata: JSON.parse(metadata.stdout) };
+      },
+    }),
+
+    step("transcribe", {
+      name: "Transcribe Audio",
+      handler: async (ctx) => {
+        const transcript = await ctx.tools.api.call("openai-whisper", "transcribe", {
+          file: input.videoPath,
+          language: config.language,
+        });
+        ctx.ui.updateState({ transcript });
+        return { transcript };
+      },
+      ui: { snapshot: true },
+    }),
+
+    waitForUser("edit", {
+      name: "Manual Editing",
+      prompt: '편집이 완료되면 "완료" 버튼을 클릭하세요.',
+      schema: {
+        type: "object",
+        properties: {
+          cuts: { type: "array", items: { type: "object" } },
+          effects: { type: "array", items: { type: "object" } },
+          subtitles: { type: "array", items: { type: "object" } },
+        },
+      },
+    }),
+
+    step("render", {
+      name: "Render Final Video",
+      handler: async (ctx) => {
+        const edits = ctx.previous;
+        // FFmpeg 렌더링 로직
+        const outputPath = await renderVideo(ctx, edits);
+        return { outputPath };
+      },
+    }),
+  ],
+
+  hooks: {
+    onProgress: async (ctx, progress) => {
+      ctx.ui.updateState({ progress });
+    },
+  },
+});
+```
+
+---
+
+## 5. 문서화 아웃라인
+
+### 5.1 API Reference
+
+```
+/docs/api/
+├── index.md                    # API 개요
+├── define-pipeline.md          # definePipeline() 상세
+├── step-dsl.md                 # 스텝 DSL (step, parallel, conditional 등)
+├── types/
+│   ├── pipeline-definition.md
+│   ├── step-context.md
+│   ├── pipeline-hooks.md
+│   └── config-schema.md
+├── tools/
+│   ├── moldclaw.md             # moldclaw 내장 도구
+│   ├── api.md                  # 외부 API 통합
+│   ├── llm.md                  # LLM 도구
+│   ├── fs.md                   # 파일 시스템
+│   └── http.md                 # HTTP 클라이언트
+└── ui/
+    ├── canvas.md               # Canvas UI
+    ├── bridge.md               # UI Bridge API
+    └── components.md           # 기본 컴포넌트
+```
+
+### 5.2 튜토리얼
+
+```
+/docs/tutorials/
+├── getting-started.md          # 시작하기
+├── first-pipeline.md           # 첫 번째 파이프라인 만들기
+├── working-with-steps.md       # 스텝 활용하기
+├── parallel-processing.md      # 병렬 처리
+├── conditional-logic.md        # 조건부 로직
+├── external-apis.md            # 외부 API 연동
+├── ui-integration.md           # UI 통합 (하드 파이프라인)
+├── testing.md                  # 테스트 작성
+├── publishing.md               # 마켓플레이스 퍼블리시
+└── best-practices.md           # 베스트 프랙티스
+```
+
+### 5.3 예제 코드
+
+```
+/docs/examples/
+├── simple-transformer.md       # 단순 데이터 변환
+├── batch-processor.md          # 배치 처리
+├── api-aggregator.md           # 여러 API 집계
+├── document-analyzer.md        # 문서 분석
+├── image-pipeline.md           # 이미지 처리
+├── video-editor.md             # 비디오 편집
+├── chatbot.md                  # 대화형 AI
+└── workflow-automation.md      # 워크플로우 자동화
+```
+
+### 5.4 가이드
+
+```
+/docs/guides/
+├── architecture.md             # 아키텍처 개요
+├── plugin-vs-pipeline.md       # 플러그인 vs 파이프라인
+├── security.md                 # 보안 가이드
+├── performance.md              # 성능 최적화
+├── debugging.md                # 디버깅
+├── migration.md                # 마이그레이션 가이드
+└── faq.md                      # FAQ
+```
+
+---
+
+## 6. 구현 로드맵
+
+### Phase 1: Core SDK (Week 1-2)
+
+- [ ] `definePipeline()` API 구현
+- [ ] 기본 스텝 DSL (`step`, `parallel`, `conditional`)
+- [ ] 스텝 컨텍스트 및 도구 통합
+- [ ] 기본 훅 시스템
+
+### Phase 2: CLI Tools (Week 3-4)
+
+- [ ] `pipeline init` 명령어
+- [ ] `pipeline dev` 개발 서버
+- [ ] `pipeline test` 테스트 러너
+- [ ] `pipeline build` 빌더
+
+### Phase 3: Templates & Examples (Week 5)
+
+- [ ] 기본 템플릿 세트
+- [ ] 도메인별 스타터
+- [ ] 예제 파이프라인 5개 이상
+
+### Phase 4: Marketplace Integration (Week 6-7)
+
+- [ ] `pipeline publish` 퍼블리시 플로우
+- [ ] 마켓플레이스 API 연동
+- [ ] 버전 관리 및 업데이트
+
+### Phase 5: Documentation (Week 8)
+
+- [ ] API Reference 완성
+- [ ] 튜토리얼 5개 이상
+- [ ] 인터랙티브 예제
+
+---
+
+## 7. 기술적 고려사항
+
+### 7.1 기존 플러그인 SDK와의 관계
+
+```typescript
+// Pipeline SDK는 내부적으로 Plugin SDK를 활용
+export function definePipeline(definition: PipelineDefinition): DefinedPipelineEntry {
+  // 플러그인 엔트리로 변환
+  return definePluginEntry({
+    id: `pipeline:${definition.id}`,
+    name: definition.name,
+    description: definition.description,
+    kind: "pipeline",
+
+    register(api: moldClawPluginApi) {
+      // 파이프라인 전용 커맨드 등록
+      api.registerCommand({
+        name: `run-${definition.id}`,
+        description: `Run ${definition.name} pipeline`,
+        handler: (ctx) => runPipeline(definition, ctx),
+      });
+
+      // 훅 등록
+      registerPipelineHooks(api, definition);
+
+      // UI 등록 (하드 파이프라인)
+      if (definition.ui) {
+        registerPipelineUI(api, definition);
+      }
+    },
+  });
+}
+```
+
+### 7.2 보안 고려사항
+
+- **API 키 보안**: 환경변수 또는 암호화된 시크릿 저장소 사용
+- **샌드박싱**: 파이프라인 실행 시 제한된 권한 환경
+- **입력 검증**: 모든 사용자 입력 검증
+- **권한 선언**: `permissions` 필드를 통한 명시적 권한 요청
+
+### 7.3 학습 곡선 최소화
+
+1. **점진적 복잡성**: 단순 → 복잡 예제
+2. **TypeScript 지원**: 자동 완성 및 타입 힌트
+3. **인터랙티브 CLI**: 대화형 초기화
+4. **풍부한 예제**: 도메인별 스타터 템플릿
+
+### 7.4 타 플랫폼 SDK 벤치마킹
+
+| 플랫폼     | 장점                   | moldClaw 적용                  |
+| ---------- | ---------------------- | ------------------------------ |
+| Vercel SDK | 간결한 API, 훌륭한 DX  | `definePipeline()` 단일 진입점 |
+| Temporal   | 강력한 워크플로우 정의 | 스텝 DSL, 재시도 정책          |
+| Langchain  | 체이닝 패턴            | `step()` → `step()` 연결       |
+| n8n        | 시각적 워크플로우      | UI 통합 (Canvas)               |
+| Retool     | 로우코드 접근          | 설정 스키마 자동 UI            |
+
+---
+
+## 8. 결론
+
+이 설계는 moldClaw의 파이프라인 마켓플레이스 비전을 실현하기 위한 SDK 인터페이스를 정의한다.
+
+**핵심 차별점:**
+
+1. **통합 API**: `definePipeline()`으로 메타데이터, 로직, 훅, UI를 한 곳에서 정의
+2. **유연한 스텝 DSL**: 선형, 병렬, 조건부, 반복 등 다양한 실행 패턴
+3. **하드/소프트 파이프라인 지원**: UI 통합을 통한 대화형 워크플로우
+4. **마켓플레이스 네이티브**: 가격 정책, 퍼블리시 워크플로우 내장
+5. **기존 생태계 활용**: 플러그인 SDK 위에 구축하여 기존 도구/훅 재사용
+
+---
+
+_이 문서는 구현 전 설계 단계의 문서입니다. 실제 구현 시 세부사항이 변경될 수 있습니다._