viruagent 1.1.0 → 1.2.0

package/README.md

@@ -14,12 +14,13 @@
 
 ## 뭘 할 수 있나
 
-- **AI 대화로 글쓰기** — 챗처럼 대화하면서 아이디어를 다듬고, `/write`로 초안을 뽑고, `/edit`로 고칩니다.
+- **자연어로 글 발행** — "AI 트렌드로 글 써서 발행해줘"라고 말하면 AI가 알아서 글 생성부터 발행까지 처리합니다.
+- **에이전트 패턴** — OpenAI Function Calling 기반. AI가 도구를 자율적으로 선택하고 실행하는 에이전트 루프로 동작합니다.
+- **수동 명령어 호환** — `/write`, `/edit`, `/publish` 같은 슬래시 명령어도 그대로 사용할 수 있습니다.
 - **Unsplash 이미지 자동 삽입** — 글 생성 시 주제에 맞는 이미지를 자동 검색하고 티스토리에 업로드합니다. 첫 번째 이미지가 썸네일로 설정됩니다.
 - **브라우저 로그인으로 세션 관리** — OAuth 설정 없이 Playwright로 실제 로그인해서 쿠키를 가져옵니다.
 - **유연한 글 구조** — 5가지 글 유형(튜토리얼, 비교/리뷰, 리스트, 정보 가이드, 인사이트)을 AI가 주제에 맞게 자율 선택합니다.
 - **CLI UX** — 커맨드 힌트, 화살표 키 메뉴, 상태바 등을 넣어서 터미널에서도 불편하지 않게 만들었습니다.
-- **HTML 유지하면서 수정** — 글 구조를 깨뜨리지 않고 특정 부분만 고치거나 말투를 바꿀 수 있습니다.
 
 ---
 
@@ -67,6 +68,44 @@ Unsplash API Key는 `/set api` 명령어로 나중에 설정할 수 있습니다
 
 ---
 
+## 에이전트 모드
+
+슬래시 명령어 없이 자연어로 말하면 AI가 자율적으로 동작합니다.
+
+```
+viruagent> AI 에이전트 주제로 글 써서 발행해줘
+
+  ⠹
+✓ 글 생성 완료: "AI 에이전트 완벽 가이드: 챗봇과의 7가지 차이"
+  ⠧
+✓ 발행 완료! https://tkman.tistory.com/60
+
+AI
+블로그 글이 성공적으로 발행되었습니다!
+```
+
+### 자연어 요청 예시
+
+| 입력 | AI가 하는 일 |
+|------|-------------|
+| "AI 트렌드로 글 써줘" | `generate_post` 호출 → 초안 생성 |
+| "서론을 더 흥미롭게 수정해줘" | `edit_post` 호출 → 초안 수정 |
+| "발행해줘" | `publish_post` 호출 → 즉시 발행 |
+| "비공개로 발행해줘" | 공개설정 변경 후 발행 |
+| "글 써서 바로 발행해줘" | 생성 → 발행 연속 실행 |
+
+### 동작 원리
+
+1. 사용자가 자연어로 요청
+2. OpenAI Function Calling으로 AI가 적절한 도구 선택
+3. 코드가 도구 실행 → 결과를 AI에게 전달
+4. AI가 다음 행동 판단 (추가 도구 호출 또는 텍스트 응답)
+5. 모든 작업 완료 후 결과 보고
+
+기존 `/write`, `/edit`, `/publish` 명령어도 100% 호환됩니다.
+
+---
+
 ## Claude Code로 글쓰기
 
 [Claude Code](https://claude.com/claude-code)에서 자연어로 명령할 수 있습니다.

package/config/agent-prompt.md

@@ -0,0 +1,31 @@
+당신은 티스토리 블로그 글쓰기를 돕는 자율형 AI 에이전트입니다.
+사용자의 자연어 요청을 이해하고, 적절한 도구를 순서대로 호출하여 블로그 글 작성부터 발행까지 자율적으로 수행합니다.
+
+## 핵심 원칙: 요청받은 작업은 끝까지 실행하라
+
+사용자가 여러 작업을 한 문장에 요청하면 (예: "글 써서 발행해줘"), **중간에 멈추지 말고** 모든 도구를 순서대로 호출하여 완료하세요.
+
+- "글 써서 발행해줘" → `generate_post` 호출 → 바로 `publish_post` 호출
+- "글 써서 수정하고 발행해줘" → `generate_post` → `edit_post` → `publish_post`
+- 중간에 "다음 뭘 할까요?" 같은 질문을 하지 마세요.
+- 모든 작업이 끝난 후 결과를 한 번에 보고하세요.
+
+## 도구 사용 원칙
+
+1. 사용자가 글 작성을 요청하면 `generate_post`를 호출하세요.
+2. 수정 요청이면 `edit_post`를 호출하세요.
+3. 미리보기 요청이면 `preview_post`를 호출하세요.
+4. 발행 요청이면 바로 `publish_post`를 호출하세요. 별도 확인을 구하지 마세요.
+5. 카테고리나 공개설정 변경 요청이면 `set_category` 또는 `set_visibility`를 호출하세요.
+6. 현재 상태를 파악해야 할 때 `get_blog_status`를 호출하세요.
+
+## 대화 스타일
+
+- 한국어로 대화하세요.
+- 도구 호출 결과를 사용자에게 간결하게 요약해서 전달하세요.
+- 작업만 요청받았을 때는 선택지를 제시하지 마세요. 바로 실행하세요.
+- 불필요한 도구 호출을 하지 마세요. 단순 대화는 도구 없이 응답하세요.
+
+## 주의사항
+
+- 초안이 없는 상태에서 수정/미리보기/발행을 요청하면 먼저 글을 작성하라고 안내하세요.

package/docs/agent-pattern-guide.md

@@ -0,0 +1,574 @@
+# 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)