viruagent 1.2.0 → 1.3.0

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,9 +1,12 @@
-<img width="525" height="113" alt="image" src="https://github.com/user-attachments/assets/8bbd21d3-5f14-4d11-933d-17bdf6969ebf" />
-
+<img width="520" height="109" alt="SCR-20260212-opqh" src="https://github.com/user-attachments/assets/b6c79a28-5619-49b9-b87c-4a3f725a193a" />
 
 # ViruAgent
 
-> 터미널에서 티스토리 블로그 글을 만들고, 다듬고, 발행하는 CLI 도구
+> 터미널에서 티스토리 블로그 글을 발행까지 한 번에!
+> (CLI 기반 AI Agent 도구)
+>
+> 태균맨(tae\*virus)의 별명
+> **Viru** + **Agent** = **ViruAgent** (바이루에이전트)
 
 티스토리 API를 역분석해서 OpenAI와 엮었습니다.
 글감 잡기 → 초안 생성 → 수정 → 발행까지 터미널 안에서 끝납니다.
@@ -53,8 +56,6 @@ Unsplash API Key는 `/set api` 명령어로 나중에 설정할 수 있습니다
 
 ---
 
-
-
 | 명령어          | 설명                                         |
 | --------------- | -------------------------------------------- |
 | `/write <주제>` | AI가 블로그 글 초안 생성                     |
@@ -64,7 +65,7 @@ Unsplash API Key는 `/set api` 명령어로 나중에 설정할 수 있습니다
 | `/set`          | 카테고리, 공개 설정, 모델, 말투 변경         |
 | `/list`         | 최근 발행 글 목록                            |
 | `/login`        | 티스토리 세션 갱신                           |
-| `/logout`        | 티스토리 세션 삭제                           |
+| `/logout`       | 티스토리 세션 삭제                           |
 
 ---
 
@@ -74,25 +75,20 @@ Unsplash API Key는 `/set api` 명령어로 나중에 설정할 수 있습니다
 
 ```
 viruagent> AI 에이전트 주제로 글 써서 발행해줘
+```
+![clideo_editor_32d1094183c7474a9985dbfd56abda67](https://github.com/user-attachments/assets/b638db4e-0ca9-4b1f-8a5b-2e1b76854202)
 
-  ⠹
-✓ 글 생성 완료: "AI 에이전트 완벽 가이드: 챗봇과의 7가지 차이"
-  ⠧
-✓ 발행 완료! https://tkman.tistory.com/60
 
-AI
-블로그 글이 성공적으로 발행되었습니다!
-```
 
 ### 자연어 요청 예시
 
-| 입력 | AI가 하는 일 |
-|------|-------------|
-| "AI 트렌드로 글 써줘" | `generate_post` 호출 → 초안 생성 |
-| "서론을 더 흥미롭게 수정해줘" | `edit_post` 호출 → 초안 수정 |
-| "발행해줘" | `publish_post` 호출 → 즉시 발행 |
-| "비공개로 발행해줘" | 공개설정 변경 후 발행 |
-| "글 써서 바로 발행해줘" | 생성 → 발행 연속 실행 |
+| 입력                          | AI가 하는 일                     |
+| ----------------------------- | -------------------------------- |
+| "AI 트렌드로 글 써줘"         | `generate_post` 호출 → 초안 생성 |
+| "서론을 더 흥미롭게 수정해줘" | `edit_post` 호출 → 초안 수정     |
+| "발행해줘"                    | `publish_post` 호출 → 즉시 발행  |
+| "비공개로 발행해줘"           | 공개설정 변경 후 발행            |
+| "글 써서 바로 발행해줘"       | 생성 → 발행 연속 실행            |
 
 ### 동작 원리
 
@@ -116,11 +112,8 @@ AI
 
 <img width="1054" height="896" alt="image" src="https://github.com/user-attachments/assets/9e30e0ed-32f9-41a4-b39f-e4e6863d5d2d" />
 
-
-
 카테고리, 공개 여부, 발행 방식을 물어본 뒤 AI가 글을 생성해서 티스토리에 발행합니다.
 
-
 ### 직접 CLI로 실행
 
 ```bash
@@ -164,13 +157,13 @@ config/
 
 ### 글 유형 (AI가 주제에 맞게 자율 선택)
 
-| 유형 | 구조 |
-|------|------|
-| 튜토리얼 | 준비물 → 단계 → 결과 확인 → 트러블슈팅 |
-| 비교/리뷰 | 비교 테이블 + 장단점 → 추천 |
-| 리스트 | 번호 소제목 + 항목별 팁 |
-| 정보 가이드 | 문제 → 원인 → 해결 → FAQ |
-| 인사이트 | 화두 → 근거 → 시사점 → 액션 |
+| 유형        | 구조                                   |
+| ----------- | -------------------------------------- |
+| 튜토리얼    | 준비물 → 단계 → 결과 확인 → 트러블슈팅 |
+| 비교/리뷰   | 비교 테이블 + 장단점 → 추천            |
+| 리스트      | 번호 소제목 + 항목별 팁                |
+| 정보 가이드 | 문제 → 원인 → 해결 → FAQ               |
+| 인사이트    | 화두 → 근거 → 시사점 → 액션            |
 
 ### prompt-config.json 설정
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viruagent",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI 기반 티스토리 블로그 자동 발행 CLI 도구",
   "main": "src/agent.js",
   "bin": {

package/docs/agent-pattern-guide.md

@@ -1,574 +0,0 @@
-# AI 에이전트 패턴 & Function Calling 학습 가이드
-
-## 목차
-
-1. [에이전트란 무엇인가](#1-에이전트란-무엇인가)
-2. [기존 방식 vs 에이전트 방식](#2-기존-방식-vs-에이전트-방식)
-3. [Function Calling 핵심 원리](#3-function-calling-핵심-원리)
-4. [에이전트 루프 구조](#4-에이전트-루프-구조)
-5. [Tool 정의 작성법](#5-tool-정의-작성법)
-6. [Tool Executor 패턴](#6-tool-executor-패턴)
-7. [실전 흐름 추적](#7-실전-흐름-추적)
-8. [시스템 프롬프트의 역할](#8-시스템-프롬프트의-역할)
-9. [토큰 비용 구조](#9-토큰-비용-구조)
-10. [안전장치 설계](#10-안전장치-설계)
-11. [확장 패턴](#11-확장-패턴)
-
----
-
-## 1. 에이전트란 무엇인가
-
-### 일반 챗봇
-
-```
-사용자 → 질문 → AI → 텍스트 답변
-```
-
-AI는 **말만** 할 수 있다. 실제 행동(파일 저장, API 호출, DB 쿼리)은 불가능.
-
-### 에이전트
-
-```
-사용자 → 요청 → AI → "이 도구를 이렇게 써야겠다" → 코드가 실행 → 결과를 AI에게 → AI가 다음 판단
-```
-
-AI가 **행동을 선택**하고, 코드가 **실행**하고, 결과를 보고 AI가 **다음 행동을 판단**한다.
-
-### 핵심 차이
-
-|           | 챗봇          | 에이전트             |
-| --------- | ------------- | -------------------- |
-| AI의 역할 | 텍스트 생성   | **판단 + 도구 선택** |
-| 실행 주체 | 없음          | 코드(Tool Executor)  |
-| 루프      | 1회 요청-응답 | **반복 루프**        |
-| 자율성    | 없음          | AI가 다음 행동 결정  |
-
----
-
-## 2. 기존 방식 vs 에이전트 방식
-
-### 기존: 사용자가 라우터
-
-```
-사용자가 "/write AI 트렌드" 입력
-  → 코드가 "write" 명령어 파싱
-  → generatePost("AI 트렌드") 직접 호출
-  → 결과 출력
-
-사용자가 "/edit 서론 수정" 입력
-  → 코드가 "edit" 명령어 파싱
-  → revisePost(content, "서론 수정") 직접 호출
-  → 결과 출력
-```
-
-**사용자**가 어떤 함수를 쓸지 결정한다. 코드는 `if/switch`로 매핑만 한다.
-
-### 에이전트: AI가 라우터
-
-```
-사용자가 "AI 트렌드로 글 써서 발행해줘" 입력
-  → AI가 판단: "generate_post를 먼저 호출해야겠다"
-  → 코드가 generatePost() 실행 → 결과를 AI에게 전달
-  → AI가 판단: "글이 완성됐으니 발행 확인을 물어봐야겠다"
-  → "발행할까요?" 텍스트 응답
-  → 사용자: "응"
-  → AI가 판단: "publish_post 호출"
-  → 코드가 publishPost() 실행
-```
-
-**AI**가 어떤 함수를 쓸지 결정한다. 코드는 AI의 결정을 실행만 한다.
-
----
-
-## 3. Function Calling 핵심 원리
-
-OpenAI의 Function Calling은 AI에게 **"너는 이런 도구를 쓸 수 있어"**라고 알려주는 메커니즘이다.
-
-### API 요청 구조
-
-```js
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o-mini',
-  messages: [
-    { role: 'system', content: '당신은 블로그 에이전트입니다.' },
-    { role: 'user', content: 'AI 트렌드로 글 써줘' },
-  ],
-  tools: [
-    // ← 여기서 도구를 알려줌
-    {
-      type: 'function',
-      function: {
-        name: 'generate_post',
-        description: '블로그 글 초안을 생성합니다.',
-        parameters: {
-          type: 'object',
-          properties: {
-            topic: { type: 'string', description: '글 주제' },
-          },
-          required: ['topic'],
-        },
-      },
-    },
-  ],
-});
-```
-
-### API 응답 — 두 가지 경우
-
-**경우 1: 도구를 호출하겠다고 판단**
-
-```json
-{
-  "choices": [
-    {
-      "message": {
-        "role": "assistant",
-        "content": null,
-        "tool_calls": [
-          {
-            "id": "call_abc123",
-            "type": "function",
-            "function": {
-              "name": "generate_post",
-              "arguments": "{\"topic\": \"AI 트렌드\"}"
-            }
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-AI가 직접 함수를 실행하는 게 **아니다**. "이 함수를 이 인자로 호출해줘"라고 **요청**하는 것이다.
-
-**경우 2: 도구 없이 텍스트로 답변**
-
-```json
-{
-  "choices": [
-    {
-      "message": {
-        "role": "assistant",
-        "content": "글이 생성되었습니다! 제목은 'AI 트렌드 2026'입니다."
-      }
-    }
-  ]
-}
-```
-
-`tool_calls`가 없으면 일반 텍스트 응답. 이게 루프의 종료 조건이 된다.
-
----
-
-## 4. 에이전트 루프 구조
-
-에이전트의 핵심은 **while 루프**다.
-
-### 의사코드
-
-```
-messages = [시스템 프롬프트, 사용자 메시지]
-
-반복 (최대 10회):
-    응답 = OpenAI API 호출(messages, tools)
-
-    if 응답에 tool_calls가 있으면:
-        각 tool_call에 대해:
-            함수 실행
-            결과를 messages에 추가
-        → 루프 계속 (다시 API 호출)
-
-    else:
-        텍스트 응답을 사용자에게 표시
-        → 루프 종료
-```
-
-### 실제 코드 (viruagent의 runAgent)
-
-```js
-for (let loop = 0; loop < MAX_LOOPS; loop++) {
-  // 1. API 호출
-  const res = await openai.chat.completions.create({
-    model,
-    messages,
-    tools: agentTools,
-  });
-
-  const msg = res.choices[0].message;
-  messages.push(msg); // AI 응답을 히스토리에 추가
-
-  // 2. 분기: tool_calls 유무
-  if (!msg.tool_calls || msg.tool_calls.length === 0) {
-    // 텍스트 응답 → 루프 종료
-    return msg.content;
-  }
-
-  // 3. 도구 실행 → 결과를 messages에 추가
-  for (const toolCall of msg.tool_calls) {
-    const result = await executeAgentTool(toolCall.function.name, args);
-    messages.push({
-      role: 'tool', // ← 특수 role
-      tool_call_id: toolCall.id, // ← 어떤 호출의 결과인지 매핑
-      content: JSON.stringify(result),
-    });
-  }
-  // → 루프 처음으로 돌아가서 다시 API 호출
-}
-```
-
-### messages 배열의 흐름
-
-```
-[1] { role: "system",    content: "에이전트 프롬프트" }
-[2] { role: "user",      content: "AI 트렌드로 글 써줘" }
-    ↓ API 호출
-[3] { role: "assistant", tool_calls: [generate_post] }     ← AI 판단
-[4] { role: "tool",      content: '{"title":"AI 트렌드"}' } ← 실행 결과
-    ↓ API 재호출 ([1]~[4] 전체 전송)
-[5] { role: "assistant", content: "글이 완성되었습니다!" }  ← 최종 응답
-```
-
-**매 루프마다 전체 messages를 다시 보낸다.** AI는 이전 맥락을 모두 보고 다음 판단을 한다.
-
----
-
-## 5. Tool 정의 작성법
-
-### 기본 구조
-
-```js
-{
-  type: "function",
-  function: {
-    name: "함수이름",              // AI가 호출할 때 사용하는 이름
-    description: "이 도구가 뭘 하는지", // AI가 판단 근거로 사용
-    parameters: {                  // JSON Schema 형식
-      type: "object",
-      properties: {
-        param1: {
-          type: "string",
-          description: "파라미터 설명"  // AI가 값을 채울 때 참고
-        }
-      },
-      required: ["param1"]
-    }
-  }
-}
-```
-
-### 좋은 description 작성법
-
-```
-❌ "글을 만든다"                     → 너무 모호
-✅ "블로그 글 초안을 생성합니다."      → 명확한 행동
-✅ "현재 초안을 블로그에 발행합니다.    → 행동 + 대상
-    반드시 사용자 확인 후 호출하세요."  → 조건까지 명시
-```
-
-description은 AI의 **판단 근거**가 된다. 잘 쓰면 AI가 적절한 타이밍에 적절한 도구를 선택한다.
-
-### 파라미터 없는 도구
-
-```js
-{
-  name: "preview_post",
-  description: "현재 초안을 미리봅니다.",
-  parameters: { type: "object", properties: {} }  // 빈 객체
-}
-```
-
-### 선택적 파라미터
-
-```js
-{
-  name: "generate_post",
-  parameters: {
-    type: "object",
-    properties: {
-      topic: { type: "string", description: "글 주제" },
-      tone:  { type: "string", description: "글 톤 (선택)" }
-    },
-    required: ["topic"]  // tone은 required에 없음 → 선택
-  }
-}
-```
-
----
-
-## 6. Tool Executor 패턴
-
-AI가 "generate_post를 호출해줘"라고 하면, 실제로 실행하는 코드가 필요하다.
-
-### switch 패턴 (viruagent 방식)
-
-```js
-const executeAgentTool = async (name, args, context) => {
-  switch (name) {
-    case 'generate_post': {
-      const result = await generatePost(args.topic, { tone: args.tone });
-      context.state.draft = result;  // 상태 업데이트
-      return { success: true, title: result.title };
-    }
-
-    case 'edit_post': {
-      if (!context.state.draft) {
-        return { error: '초안이 없습니다.' };  // 에러도 JSON으로 반환
-      }
-      const result = await revisePost(context.state.draft.content, args.instruction);
-      context.state.draft = result;
-      return { success: true, title: result.title };
-    }
-
-    case 'publish_post': {
-      const result = await context.publishPost({ ... });
-      return { success: true, url: result.entryUrl };
-    }
-
-    default:
-      return { error: `알 수 없는 도구: ${name}` };
-  }
-};
-```
-
-### 핵심 원칙
-
-1. **결과는 항상 JSON 문자열로 반환** — AI가 읽을 수 있어야 함
-2. **에러도 throw하지 않고 `{ error: "..." }`로 반환** — AI가 에러를 보고 대안을 판단할 수 있음
-3. **상태 변경은 여기서** — `state.draft = result` 같은 부수효과 처리
-
-### Map 패턴 (대안)
-
-도구가 많아지면 switch 대신 Map으로 관리할 수도 있다:
-
-```js
-const toolHandlers = {
-  generate_post: async (args, ctx) => { ... },
-  edit_post: async (args, ctx) => { ... },
-  publish_post: async (args, ctx) => { ... },
-};
-
-const executeAgentTool = async (name, args, ctx) => {
-  const handler = toolHandlers[name];
-  if (!handler) return { error: `알 수 없는 도구: ${name}` };
-  return handler(args, ctx);
-};
-```
-
----
-
-## 7. 실전 흐름 추적
-
-### 시나리오: "AI 트렌드로 글 써서 서론 수정하고 발행해줘"
-
-```
-[사용자 입력]
-"AI 트렌드로 글 써서 서론 수정하고 발행해줘"
-
-[루프 1] API 호출
-  → AI 판단: 먼저 글을 생성해야 한다
-  → tool_calls: [{ name: "generate_post", args: { topic: "AI 트렌드" } }]
-  → 코드 실행: generatePost("AI 트렌드")
-  → 결과: { success: true, title: "2026 AI 트렌드 총정리" }
-
-[루프 2] API 재호출 (이전 맥락 + tool 결과 포함)
-  → AI 판단: 이제 서론을 수정해야 한다
-  → tool_calls: [{ name: "edit_post", args: { instruction: "서론을 더 흥미롭게" } }]
-  → 코드 실행: revisePost(content, "서론을 더 흥미롭게")
-  → 결과: { success: true, title: "2026 AI 트렌드 총정리" }
-
-[루프 3] API 재호출
-  → AI 판단: 발행 전에 사용자 확인이 필요하다 (프롬프트 규칙)
-  → tool_calls 없음
-  → 텍스트: "글이 준비되었습니다! 발행할까요?"
-  → 루프 종료
-
-[사용자 입력]
-"응 발행해"
-
-[루프 1] API 호출
-  → AI 판단: 사용자가 승인했으니 발행
-  → tool_calls: [{ name: "publish_post", args: {} }]
-  → 코드 실행: publishPost(...)
-  → 결과: { success: true, url: "https://blog.example.com/123" }
-
-[루프 2] API 재호출
-  → tool_calls 없음
-  → 텍스트: "발행 완료! https://blog.example.com/123"
-  → 루프 종료
-```
-
----
-
-## 8. 시스템 프롬프트의 역할
-
-에이전트의 **행동 규칙**을 정하는 것이 시스템 프롬프트다.
-
-### tool description vs 시스템 프롬프트
-
-|      | tool description         | 시스템 프롬프트                         |
-| ---- | ------------------------ | --------------------------------------- |
-| 위치 | tools 배열 안            | messages[0]                             |
-| 역할 | "이 도구는 뭘 한다"      | "너는 누구고, 어떻게 행동해라"          |
-| 예시 | "블로그 글을 생성합니다" | "발행 전에 반드시 사용자 확인을 구하라" |
-
-### viruagent의 에이전트 프롬프트 구조
-
-```markdown
-# 역할 정의
-
-당신은 티스토리 블로그 글쓰기를 돕는 자율형 AI 에이전트입니다.
-
-# 도구 사용 원칙 (판단 기준)
-
-1. 글 작성 요청 → generate_post
-2. 수정 요청 → edit_post
-3. 발행 요청 → 반드시 확인 먼저!
-
-# 행동 제약
-
-- 초안 없이 수정/발행 요청 → 안내
-- 불필요한 도구 호출 금지
-```
-
-시스템 프롬프트가 없으면 AI는 **아무 도구나 마구 호출**할 수 있다. 프롬프트로 행동 경계를 잡아주는 것이 중요하다.
-
----
-
-## 9. 토큰 비용 구조
-
-### 매 루프마다 전송되는 토큰
-
-```
-시스템 프롬프트         ~300 토큰  (매번 고정)
-tools 정의 (7개)       ~800 토큰  (매번 고정)
-대화 히스토리           누적 증가
-tool 결과              누적 증가
-──────────────────────────────
-루프 1 입력: ~1,200 토큰
-루프 2 입력: ~1,500 토큰 (이전 맥락 추가)
-루프 3 입력: ~1,800 토큰
-```
-
-### 비용 최적화 전략
-
-| 전략                            | 효과                 |
-| ------------------------------- | -------------------- |
-| 히스토리 길이 제한 (최근 N개만) | 누적 비용 억제       |
-| tool 결과를 요약해서 반환       | 컨텍스트 절약        |
-| 불필요한 tool 제거              | tools 정의 토큰 감소 |
-| 작은 모델 사용 (gpt-4o-mini)    | 단가 자체를 낮춤     |
-
-### 모델별 비용 비교 (루프 3회 기준, ~5,000 입력 토큰)
-
-| 모델        | 입력 단가 | 예상 비용      |
-| ----------- | --------- | -------------- |
-| gpt-4o-mini | $0.15/1M  | ~$0.001 (1원)  |
-| gpt-4o      | $2.5/1M   | ~$0.013 (17원) |
-| gpt-4.1     | $2.0/1M   | ~$0.010 (13원) |
-
----
-
-## 10. 안전장치 설계
-
-### 무한 루프 방지
-
-```js
-const MAX_LOOPS = 10;
-for (let loop = 0; loop < MAX_LOOPS; loop++) {
-  // ... 루프 초과 시 강제 종료
-}
-```
-
-AI가 도구를 호출하고 → 결과를 보고 → 또 호출하고... 무한히 반복할 수 있으므로 **반드시 상한**을 둔다.
-
-### 위험한 동작 보호
-
-```markdown
-# 시스템 프롬프트에서
-
-발행 요청 시에는 반드시 사용자에게 먼저 확인을 구하세요.
-```
-
-```js
-// tool description에서
-{
-  name: "publish_post",
-  description: "현재 초안을 블로그에 발행합니다. 반드시 사용자 확인 후 호출하세요."
-}
-```
-
-**이중 안전장치**: 시스템 프롬프트 + tool description 양쪽에서 제약.
-
-### 에러 격리
-
-```js
-let result;
-try {
-  result = await executeAgentTool(name, args, context);
-} catch (e) {
-  result = { error: e.message }; // throw하지 않고 에러를 AI에게 전달
-}
-```
-
-도구 실행 실패 시 루프가 죽지 않고, AI가 에러를 보고 대안을 판단할 수 있다.
-
----
-
-## 11. 확장 패턴
-
-### 병렬 도구 호출 (Parallel Tool Calls)
-
-AI가 한 번에 여러 도구를 호출할 수 있다:
-
-```json
-{
-  "tool_calls": [{ "name": "get_blog_status" }, { "name": "generate_post", "args": { "topic": "AI" } }]
-}
-```
-
-viruagent는 이미 `for...of`로 순차 처리하지만, `Promise.all`로 병렬 실행도 가능:
-
-```js
-const results = await Promise.all(msg.tool_calls.map((tc) => executeAgentTool(tc.function.name, args)));
-```
-
-### Structured Outputs (응답 형식 강제)
-
-```js
-response_format: {
-  type: 'json_object';
-} // JSON 응답 강제
-```
-
-도구 결과뿐 아니라 AI의 최종 응답도 구조화할 수 있다.
-
-### Multi-Agent (다중 에이전트)
-
-```
-[매니저 에이전트]
-  ├── [글쓰기 에이전트] → generate_post, edit_post
-  ├── [SEO 에이전트] → analyze_seo, suggest_keywords
-  └── [발행 에이전트] → publish_post, schedule_post
-```
-
-각 에이전트가 자기 전문 도구만 갖고, 매니저가 작업을 분배하는 패턴.
-
-### 메모리 (장기 기억)
-
-```js
-tools: [
-  { name: 'save_memory', description: '중요 정보를 저장합니다' },
-  { name: 'search_memory', description: '이전에 저장한 정보를 검색합니다' },
-];
-```
-
-에이전트에게 기억 저장/검색 도구를 주면 대화 세션을 넘어서 정보를 유지할 수 있다.
-
----
-
-## 참고 자료
-
-- [OpenAI Function Calling 공식 문서](https://platform.openai.com/docs/guides/function-calling)
-- [OpenAI API Reference - Chat Completions](https://platform.openai.com/docs/api-reference/chat/create)
-- [Building AI Agents (OpenAI Cookbook)](https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models)

package/docs/hybrid-db-agent-guide.md

@@ -1,484 +0,0 @@
-# 하이브리드 DB 에이전트 설계 가이드
-
-자연어로 데이터베이스를 조회하는 AI 에이전트의 스키마 관리 전략.
-
-**캐싱(부팅 시 스키마 로드)** + **도구(상세 조회)**를 조합하여 정확도와 성능을 모두 확보한다.
-
----
-
-## 1. 전체 아키텍처
-
-```
-[서버 부팅]
-  └── DB에서 스키마 캐싱 (테이블, 컬럼, FK 관계)
-        ↓
-[사용자 요청] "이번 달 매출 상위 고객 보여줘"
-        ↓
-[시스템 프롬프트]
-  ├── 캐싱된 스키마 요약 (항상 포함)
-  └── "상세 정보가 필요하면 get_schema 도구를 사용하라"
-        ↓
-[에이전트 루프]
-  ├── AI가 캐싱된 스키마로 충분하면 → 바로 query_database 호출
-  └── 컬럼 타입, 제약조건 등 상세 필요하면 → get_schema 먼저 호출
-        ↓
-[결과 반환] "매출 상위 고객은 ..."
-```
-
----
-
-## 2. 스키마 캐싱 (서버 부팅 시)
-
-서버가 시작될 때 한 번 DB에서 스키마 정보를 읽어 메모리에 저장한다.
-
-### 2-1. 캐싱 쿼리
-
-```js
-const loadSchema = async (client) => {
-  // 테이블 + 컬럼 정보
-  const columns = await client.query(`
-    SELECT table_name, column_name, data_type, is_nullable,
-           column_default
-    FROM information_schema.columns
-    WHERE table_schema = 'public'
-    ORDER BY table_name, ordinal_position
-  `);
-
-  // FK 관계
-  const fks = await client.query(`
-    SELECT
-      tc.table_name  AS from_table,
-      kcu.column_name AS from_column,
-      ccu.table_name  AS to_table,
-      ccu.column_name AS to_column
-    FROM information_schema.table_constraints tc
-    JOIN information_schema.key_column_usage kcu
-      ON tc.constraint_name = kcu.constraint_name
-    JOIN information_schema.constraint_column_usage ccu
-      ON tc.constraint_name = ccu.constraint_name
-    WHERE tc.constraint_type = 'FOREIGN KEY'
-      AND tc.table_schema = 'public'
-  `);
-
-  // 테이블별 그룹핑
-  const grouped = {};
-  for (const row of columns.rows) {
-    if (!grouped[row.table_name]) grouped[row.table_name] = [];
-    grouped[row.table_name].push(`${row.column_name} (${row.data_type})`);
-  }
-
-  // 텍스트로 변환
-  let schema = '## 테이블 스키마\n';
-  schema += Object.entries(grouped)
-    .map(([table, cols]) => `- ${table}: ${cols.join(', ')}`)
-    .join('\n');
-
-  if (fks.rows.length > 0) {
-    schema += '\n\n## 관계 (FK)\n';
-    schema += fks.rows
-      .map(r => `- ${r.from_table}.${r.from_column} → ${r.to_table}.${r.to_column}`)
-      .join('\n');
-  }
-
-  return schema;
-};
-```
-
-### 2-2. 캐싱 결과 예시
-
-```
-## 테이블 스키마
-- users: id (integer), email (varchar), name (varchar), role (varchar), created_at (timestamp)
-- orders: id (integer), user_id (integer), total (numeric), status (varchar), created_at (timestamp)
-- products: id (integer), name (varchar), price (numeric), category (varchar), stock (integer)
-- order_items: id (integer), order_id (integer), product_id (integer), quantity (integer), price (numeric)
-
-## 관계 (FK)
-- orders.user_id → users.id
-- order_items.order_id → orders.id
-- order_items.product_id → products.id
-```
-
-AI는 이것만 보고도 대부분의 JOIN 쿼리를 정확하게 생성할 수 있다.
-
-### 2-3. 캐시 갱신
-
-```js
-// 서버 시작 시
-let schemaCache = await loadSchema(client);
-
-// 주기적 갱신 (선택)
-setInterval(async () => {
-  schemaCache = await loadSchema(client);
-}, 1000 * 60 * 30); // 30분마다
-
-// 수동 갱신 API (어드민용)
-app.post('/api/admin/refresh-schema', async (req, res) => {
-  schemaCache = await loadSchema(client);
-  res.json({ success: true });
-});
-```
-
----
-
-## 3. 도구 정의
-
-### 3-1. tools 배열
-
-```js
-const tools = [
-  {
-    type: 'function',
-    function: {
-      name: 'query_database',
-      description: 'PostgreSQL에 SELECT 쿼리를 실행합니다. READ ONLY. 결과는 최대 100행.',
-      parameters: {
-        type: 'object',
-        properties: {
-          sql: { type: 'string', description: 'SELECT 쿼리문' },
-        },
-        required: ['sql'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_schema',
-      description: '특정 테이블의 상세 스키마를 조회합니다. 컬럼 타입, 기본값, NOT NULL, 인덱스, 코멘트 등 캐싱된 요약보다 상세한 정보가 필요할 때 사용하세요.',
-      parameters: {
-        type: 'object',
-        properties: {
-          table_name: { type: 'string', description: '조회할 테이블명' },
-        },
-        required: ['table_name'],
-      },
-    },
-  },
-];
-```
-
-### 3-2. AI의 판단 기준
-
-| 상황 | AI 행동 |
-|------|---------|
-| "주문 많은 고객 보여줘" | 캐시에 users, orders, FK 있음 → 바로 `query_database` |
-| "users 테이블에 soft delete 있어?" | 캐시만으론 모름 → `get_schema("users")` 먼저 |
-| "인덱스 걸린 컬럼이 뭐야?" | 캐시에 없음 → `get_schema` 호출 |
-
----
-
-## 4. Tool Executor
-
-### 4-1. query_database
-
-```js
-const executeQuery = async (sql, client) => {
-  // 1차: SQL 파싱 검증
-  const normalized = sql.trim().toUpperCase();
-  if (!normalized.startsWith('SELECT') && !normalized.startsWith('WITH')) {
-    return { error: 'SELECT / WITH 쿼리만 허용됩니다.' };
-  }
-
-  const blocked = ['INSERT', 'UPDATE', 'DELETE', 'DROP', 'ALTER', 'TRUNCATE', 'CREATE', 'GRANT', 'REVOKE'];
-  for (const kw of blocked) {
-    // SELECT 뒤에 나오는 서브쿼리 내 키워드도 체크
-    if (normalized.includes(kw + ' ')) {
-      return { error: `${kw} 키워드가 포함된 쿼리는 실행할 수 없습니다.` };
-    }
-  }
-
-  // 2차: read-only 트랜잭션
-  try {
-    await client.query('BEGIN READ ONLY');
-    const result = await client.query(sql);
-    await client.query('COMMIT');
-
-    return {
-      columns: result.fields.map(f => f.name),
-      rows: result.rows.slice(0, 100),
-      totalRows: result.rowCount,
-      truncated: result.rowCount > 100,
-    };
-  } catch (e) {
-    await client.query('ROLLBACK');
-    return { error: `쿼리 실행 오류: ${e.message}` };
-  }
-};
-```
-
-### 4-2. get_schema (상세 조회)
-
-```js
-const getDetailedSchema = async (tableName, client) => {
-  // 컬럼 상세
-  const columns = await client.query(`
-    SELECT
-      c.column_name,
-      c.data_type,
-      c.character_maximum_length,
-      c.is_nullable,
-      c.column_default,
-      pgd.description AS comment
-    FROM information_schema.columns c
-    LEFT JOIN pg_catalog.pg_description pgd
-      ON pgd.objsubid = c.ordinal_position
-      AND pgd.objoid = (SELECT oid FROM pg_class WHERE relname = $1)
-    WHERE c.table_name = $1 AND c.table_schema = 'public'
-    ORDER BY c.ordinal_position
-  `, [tableName]);
-
-  // 인덱스
-  const indexes = await client.query(`
-    SELECT indexname, indexdef
-    FROM pg_indexes
-    WHERE tablename = $1 AND schemaname = 'public'
-  `, [tableName]);
-
-  // FK (이 테이블에서 나가는)
-  const fksOut = await client.query(`
-    SELECT kcu.column_name, ccu.table_name AS ref_table, ccu.column_name AS ref_column
-    FROM information_schema.table_constraints tc
-    JOIN information_schema.key_column_usage kcu
-      ON tc.constraint_name = kcu.constraint_name
-    JOIN information_schema.constraint_column_usage ccu
-      ON tc.constraint_name = ccu.constraint_name
-    WHERE tc.constraint_type = 'FOREIGN KEY'
-      AND tc.table_name = $1
-  `, [tableName]);
-
-  // FK (이 테이블로 들어오는)
-  const fksIn = await client.query(`
-    SELECT tc.table_name AS from_table, kcu.column_name AS from_column
-    FROM information_schema.table_constraints tc
-    JOIN information_schema.key_column_usage kcu
-      ON tc.constraint_name = kcu.constraint_name
-    JOIN information_schema.constraint_column_usage ccu
-      ON tc.constraint_name = ccu.constraint_name
-    WHERE tc.constraint_type = 'FOREIGN KEY'
-      AND ccu.table_name = $1
-  `, [tableName]);
-
-  return {
-    table: tableName,
-    columns: columns.rows,
-    indexes: indexes.rows,
-    foreignKeysOut: fksOut.rows,
-    foreignKeysIn: fksIn.rows,
-  };
-};
-```
-
----
-
-## 5. 시스템 프롬프트
-
-```js
-const buildSystemPrompt = (schemaCache) => `
-당신은 데이터베이스 조회 어시스턴트입니다.
-사용자의 자연어 질문을 SQL SELECT 쿼리로 변환하여 실행합니다.
-
-## 규칙
-- SELECT 쿼리만 생성하세요. 데이터 변경은 불가합니다.
-- 결과가 많을 수 있으니 LIMIT을 적절히 사용하세요.
-- 날짜 필터가 모호하면 사용자에게 확인하세요.
-- 쿼리 결과를 사용자가 이해하기 쉽게 요약해서 설명하세요.
-- 상세 스키마 정보(인덱스, 코멘트 등)가 필요하면 get_schema 도구를 사용하세요.
-
-${schemaCache}
-`;
-```
-
----
-
-## 6. 에이전트 루프
-
-ViruAgent의 `runAgent`와 동일한 구조:
-
-```js
-const runDbAgent = async (userMessage, { schemaCache, client, chatHistory }) => {
-  chatHistory.push({ role: 'user', content: userMessage });
-
-  const messages = [
-    { role: 'system', content: buildSystemPrompt(schemaCache) },
-    ...chatHistory,
-  ];
-
-  const MAX_LOOPS = 10;
-
-  for (let i = 0; i < MAX_LOOPS; i++) {
-    const res = await openai.chat.completions.create({
-      model: 'gpt-4o-mini',
-      messages,
-      tools,
-      temperature: 0,  // SQL 생성은 정확도 우선
-    });
-
-    const msg = res.choices[0].message;
-    messages.push(msg);
-
-    if (!msg.tool_calls?.length) {
-      chatHistory.push({ role: 'assistant', content: msg.content });
-      return msg.content;
-    }
-
-    for (const tc of msg.tool_calls) {
-      const args = JSON.parse(tc.function.arguments);
-      let result;
-
-      switch (tc.function.name) {
-        case 'query_database':
-          result = await executeQuery(args.sql, client);
-          break;
-        case 'get_schema':
-          result = await getDetailedSchema(args.table_name, client);
-          break;
-        default:
-          result = { error: `알 수 없는 도구: ${tc.function.name}` };
-      }
-
-      messages.push({
-        role: 'tool',
-        tool_call_id: tc.id,
-        content: JSON.stringify(result),
-      });
-    }
-  }
-
-  return '쿼리가 너무 복잡합니다. 질문을 나눠서 요청해주세요.';
-};
-```
-
----
-
-## 7. 실전 흐름 추적
-
-### 시나리오 1: 단순 조회 (캐시만으로 해결)
-
-```
-사용자: "이번 달 주문 건수 알려줘"
-
-[루프 1]
-  시스템 프롬프트에 캐시된 스키마 포함
-  → AI: orders 테이블에 created_at 있네 → 바로 SQL 생성
-  → tool_calls: query_database
-    sql: "SELECT COUNT(*) as cnt FROM orders WHERE created_at >= '2026-02-01'"
-  → 결과: [{ cnt: 1847 }]
-
-[루프 2]
-  → AI: "이번 달 주문은 총 1,847건입니다."
-  → 루프 종료
-
-총 루프: 2회, get_schema 호출: 0회
-```
-
-### 시나리오 2: 복잡한 조회 (상세 스키마 필요)
-
-```
-사용자: "soft delete된 사용자 중에 주문 있는 사람 보여줘"
-
-[루프 1]
-  → AI: 캐시에 users 테이블은 있지만 soft delete 컬럼이 뭔지 모르겠다
-  → tool_calls: get_schema("users")
-  → 결과: { columns: [..., { column_name: "deleted_at", data_type: "timestamp", is_nullable: "YES" }] }
-
-[루프 2]
-  → AI: deleted_at이 NOT NULL이면 soft delete구나
-  → tool_calls: query_database
-    sql: "SELECT u.name, u.email, COUNT(o.id) as order_count
-          FROM users u
-          JOIN orders o ON o.user_id = u.id
-          WHERE u.deleted_at IS NOT NULL
-          GROUP BY u.id, u.name, u.email"
-  → 결과: [{ name: "김철수", email: "...", order_count: 5 }, ...]
-
-[루프 3]
-  → AI: "soft delete된 사용자 중 주문이 있는 분은 3명입니다: ..."
-  → 루프 종료
-
-총 루프: 3회, get_schema 호출: 1회
-```
-
----
-
-## 8. 안전장치 요약
-
-```
-┌─────────────────────────────────────────────┐
-│ Layer 1: 시스템 프롬프트                      │
-│  → "SELECT만 생성하라"                        │
-├─────────────────────────────────────────────┤
-│ Layer 2: Tool Executor (SQL 파싱)             │
-│  → SELECT/WITH 외 차단                        │
-│  → INSERT/UPDATE/DELETE/DROP 키워드 감지       │
-├─────────────────────────────────────────────┤
-│ Layer 3: DB 연결                              │
-│  → BEGIN READ ONLY 트랜잭션                   │
-│  → 또는 read replica 연결                     │
-├─────────────────────────────────────────────┤
-│ Layer 4: 결과 제한                            │
-│  → 최대 100행 반환                            │
-│  → 타임아웃 설정 (statement_timeout)           │
-└─────────────────────────────────────────────┘
-```
-
-### DB 레벨 추가 보호 (권장)
-
-```sql
--- 전용 read-only 유저 생성
-CREATE USER db_agent_readonly WITH PASSWORD '...';
-GRANT CONNECT ON DATABASE mydb TO db_agent_readonly;
-GRANT USAGE ON SCHEMA public TO db_agent_readonly;
-GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_agent_readonly;
-ALTER DEFAULT PRIVILEGES IN SCHEMA public
-  GRANT SELECT ON TABLES TO db_agent_readonly;
-
--- 쿼리 타임아웃 (느린 쿼리 방지)
-ALTER USER db_agent_readonly SET statement_timeout = '10s';
-```
-
----
-
-## 9. 토큰 비용
-
-| 항목 | 토큰 수 |
-|------|---------|
-| 시스템 프롬프트 (규칙) | ~200 |
-| 캐싱된 스키마 (10개 테이블) | ~400 |
-| 캐싱된 스키마 (50개 테이블) | ~2,000 |
-| tools 정의 (2개) | ~300 |
-| get_schema 결과 (1회) | ~500 |
-| query_database 결과 (50행) | ~1,000 |
-
-### 테이블이 많을 때 최적화
-
-```js
-// 50개 이상이면 테이블명만 캐싱, 컬럼은 get_schema로
-const loadLightSchema = async (client) => {
-  const tables = await client.query(`
-    SELECT table_name,
-           obj_description(('"' || table_name || '"')::regclass) AS comment
-    FROM information_schema.tables
-    WHERE table_schema = 'public'
-  `);
-
-  return '## 테이블 목록\n' +
-    tables.rows.map(t =>
-      `- ${t.table_name}${t.comment ? ` (${t.comment})` : ''}`
-    ).join('\n') +
-    '\n\n컬럼 정보가 필요하면 get_schema 도구를 사용하세요.';
-};
-```
-
----
-
-## 10. 하이브리드 방식을 선택한 이유
-
-| 방식 | 장점 | 단점 |
-|------|------|------|
-| 하드코딩 | 빠름, 정확 | 스키마 변경 시 코드 수정 |
-| 도구만 (MCP 방식) | 항상 최신 | 매번 1~2루프 낭비 |
-| 캐싱만 | 빠름, 자동 | 상세 정보 부족 |
-| **하이브리드** | **빠름 + 자동 + 상세** | 구현 약간 복잡 |
-
-하이브리드는 **90%의 쿼리는 캐시로 즉시 처리**하고, **10%의 복잡한 케이스만 도구로 상세 조회**한다. 토큰 절약과 정확도를 동시에 달성하는 최적의 전략이다.