@restnfeel/agentc-starter-kit/README.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# @restnfeel/agentc-starter-kit

AI 기반 지능형 채팅봇과 RAG(Retrieval-Augmented Generation) 시스템을 위한 종합 스타터 키트입니다.

## 🚀 핵심 기능

### 📱 클라이언트 컴포넌트

- **ChatbotWidget**: 웹사이트에 쉽게 통합 가능한 플로팅 채팅 위젯
- **반응형 디자인**: 데스크탑과 모바일 모두 최적화
- **UI 컴포넌트**: Button, Card, Input 등 재사용 가능한 컴포넌트

### 🔧 서버 사이드 도구 (Admin)

- **DocumentUploader**: 드래그 앤 드롭 파일 업로드
- **KnowledgeManagement**: 업로드된 문서의 체계적 관리
- **RAGManager**: RAG 엔진 설정 및 관리
- **RSSManager**: RSS 피드 자동 수집 및 처리

### 🧠 RAG 엔진

- **문서 기반 AI 응답**: 업로드된 문서를 기반으로 정확한 답변 생성
- **벡터 검색**: 의미론적 검색을 통한 정확한 문서 검색
- **멀티 소스 지원**: PDF, 텍스트, RSS 피드 등 다양한 소스 지원

## 📦 설치

```bash
npm install @restnfeel/agentc-starter-kit
```

### 필수 의존성

```bash
npm install clsx tailwind-merge lucide-react
```

## 🎯 사용 방법

### 1. 기본 채팅봇 위젯

```tsx
import { ChatbotWidget } from "@restnfeel/agentc-starter-kit";

export default function App() {
  return (
    <div>
      <h1>내 웹사이트</h1>
      <ChatbotWidget />
    </div>
  );
}
```

### 2. UI 컴포넌트 사용

```tsx
import { Button, Card, Input } from "@restnfeel/agentc-starter-kit";

export default function MyComponent() {
  return (
    <Card className="p-6">
      <h2 className="text-xl font-bold mb-4">로그인</h2>
      <div className="space-y-4">
        <Input placeholder="이메일을 입력하세요" type="email" />
        <Input placeholder="비밀번호를 입력하세요" type="password" />
        <Button className="w-full">로그인</Button>
      </div>
    </Card>
  );
}
```

### 3. 관리자 컴포넌트 (서버 컴포넌트에서 사용)

```tsx
// app/admin/page.tsx (서버 컴포넌트)
import {
  DocumentUploader,
  KnowledgeManagement,
  RAGManager,
} from "@restnfeel/agentc-starter-kit/admin";

export default function AdminPage() {
  return (
    <div className="container mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">관리자 대시보드</h1>

      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
        <div>
          <h2 className="text-xl font-semibold mb-4">문서 업로드</h2>
          <DocumentUploader />
        </div>

        <div>
          <h2 className="text-xl font-semibold mb-4">지식 관리</h2>
          <KnowledgeManagement />
        </div>

        <div className="lg:col-span-2">
          <h2 className="text-xl font-semibold mb-4">RAG 엔진 관리</h2>
          <RAGManager ragEngine={ragEngine} />
        </div>
      </div>
    </div>
  );
}
```

### 4. RAG 엔진 사용 (서버 사이드)

```tsx
// app/api/chat/route.ts
import { RAGEngine } from "@restnfeel/agentc-starter-kit/rag";

export async function POST(request: Request) {
  const { message } = await request.json();

  const ragEngine = new RAGEngine({
    // RAG 설정
  });

  await ragEngine.initialize();
  const response = await ragEngine.query(message);

  return Response.json({ response });
}
```

## 🧪 로컬 개발 및 테스트

### 자동 테스트 환경

```bash
# 패키지 빌드 + 테스트 환경 자동 생성
npm run test:local
```

이 명령어는 다음을 수행합니다:

- 패키지 빌드 및 .tgz 파일 생성
- 새로운 Next.js 테스트 프로젝트 생성
- 로컬 패키지 설치 및 테스트 파일 생성
- 타입 체크 및 빌드 테스트 실행

### 수동 테스트

```bash
# 1. 패키지 빌드
npm run build:package

# 2. 패키지 파일 생성
npm pack

# 3. 테스트 프로젝트에서 설치
cd ../your-test-project
npm install ../agentc-starter-kit/restnfeel-agentc-starter-kit-*.tgz
```

## 🎨 스타일링

이 패키지는 **Tailwind CSS**를 사용합니다. 프로젝트에서 Tailwind CSS 설정 시 다음을 포함하세요:

```js
// tailwind.config.js
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@restnfeel/agentc-starter-kit/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

## 📖 컴포넌트 API

### ChatbotWidget

```tsx
interface ChatbotWidgetProps {
  apiEndpoint?: string;
  placeholder?: string;
  buttonColor?: string;
  position?: "bottom-right" | "bottom-left";
  title?: string;
  className?: string;
}
```

### Button

```tsx
interface ButtonProps {
  variant?:
    | "default"
    | "destructive"
    | "outline"
    | "secondary"
    | "ghost"
    | "link";
  size?: "default" | "sm" | "lg" | "icon";
  children: React.ReactNode;
  className?: string;
  onClick?: () => void;
  disabled?: boolean;
}
```

### Card

```tsx
interface CardProps {
  children: React.ReactNode;
  className?: string;
}
```

### Input

```tsx
interface InputProps {
  type?: string;
  placeholder?: string;
  value?: string;
  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
  className?: string;
  disabled?: boolean;
}
```

## 🔧 환경 설정

### 환경 변수

```env
# .env.local
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
```

### Next.js 설정

```js
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ["@restnfeel/agentc-starter-kit"],
  },
};

module.exports = nextConfig;
```

## 📋 요구사항

- **Node.js**: 18.0.0 이상
- **React**: 18.0.0 이상
- **Next.js**: 14.0.0 이상 (App Router)
- **Tailwind CSS**: 3.0.0 이상

## 🏗️ 프로젝트 구조

```
your-project/
├── app/
│   ├── api/
│   │   └── chat/route.ts          # RAG API 엔드포인트
│   ├── admin/
│   │   └── page.tsx               # 관리자 페이지 (서버 컴포넌트)
│   └── page.tsx                   # 메인 페이지 (채팅봇 포함)
├── components/                    # 커스텀 컴포넌트
└── lib/                          # 유틸리티
```

## 🔄 패키지 구조

```
@restnfeel/agentc-starter-kit/
├── /                             # 메인 export (ChatbotWidget, UI 컴포넌트)
├── /admin                        # 관리자 컴포넌트 (서버 전용)
├── /rag                          # RAG 엔진 (서버 전용)
└── /templates                    # 템플릿 컴포넌트
```

## 🚨 중요 사항

### 클라이언트 vs 서버 컴포넌트

- **클라이언트 컴포넌트**: `ChatbotWidget`, UI 컴포넌트들
- **서버 컴포넌트**: Admin 컴포넌트들, RAG 엔진

```tsx
// ✅ 올바른 사용법
// 클라이언트 컴포넌트에서
import { ChatbotWidget, Button } from "@restnfeel/agentc-starter-kit";

// 서버 컴포넌트에서
import { RAGManager } from "@restnfeel/agentc-starter-kit/admin";
import { RAGEngine } from "@restnfeel/agentc-starter-kit/rag";

// ❌ 잘못된 사용법
// 클라이언트 컴포넌트에서 서버 전용 컴포넌트 import
import { RAGManager } from "@restnfeel/agentc-starter-kit/admin"; // 빌드 에러
```

## 🐛 문제 해결

### 빌드 에러

1. **fs 모듈 에러**: 클라이언트에서 서버 전용 컴포넌트를 import했을 때

   - 해결: 서버 컴포넌트에서만 admin 컴포넌트 사용

2. **타입 에러**: TypeScript 설정 문제

   - 해결: `tsconfig.json`에서 `skipLibCheck: true` 설정

3. **스타일 적용 안됨**: Tailwind CSS 설정 문제
   - 해결: `tailwind.config.js`에 패키지 경로 추가

## 📝 변경 로그

### v1.3.6

- ✅ 클라이언트/서버 컴포넌트 완전 분리
- ✅ 빌드 에러 수정
- ✅ 자동 테스트 환경 구축
- ✅ Next.js 15 호환성 확보

### v1.3.5

- 🔧 Export 구조 개선
- 🔧 타입 정의 수정

## 🤝 기여하기

1. 이 레포지토리를 포크하세요
2. 새로운 기능 브랜치를 생성하세요 (`git checkout -b feature/new-feature`)
3. 변경사항을 커밋하세요 (`git commit -am 'Add new feature'`)
4. 브랜치에 푸시하세요 (`git push origin feature/new-feature`)
5. Pull Request를 생성하세요

## 📞 지원

- **GitHub Issues**: [문제 신고](https://github.com/restnfeel/agentc-starter-kit/issues)
- **이메일**: support@restnfeel.com

## 📄 라이선스

MIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

---

**AgentC Starter Kit**으로 당신만의 AI 채팅봇을 구축해보세요! 🚀