블로그 자동 포스팅 에이전트 사용 가이드

이 문서는 블로그 자동 포스팅 에이전트 기능을 실제로 동작시키기 위해 사용자가 해야 할 작업을 정리한 안내서입니다.

1) 준비 사항

  • GitHub 리포지토리에 Actions가 활성화되어 있어야 합니다.
  • 기본 브랜치가 hydejack-pro인지 확인합니다.
  • 아래 디렉터리가 리포에 존재해야 합니다.
    • _agent_source/ (원본 마크다운 입력)
    • _agent_archive/ (처리된 원본 보관)
    • .blog-agent/state.json (사용 이력 기록)

2) 소스 마크다운 준비

  1. _agent_source/ 폴더에 .md 파일을 추가합니다.
  2. 가능한 한 사실 기반으로 작성하고, 비밀/민감정보는 포함하지 않습니다.
  3. 제목이 필요하다면 # 제목 형태의 최상위 헤더를 사용합니다.

참고: 이미 사용된 파일은 .blog-agent/state.json과 _agent_archive/에 의해 재사용이 방지됩니다.

3) GitHub Secrets 설정

리포지토리의 Settings → Secrets and variables → Actions 에서 다음 값을 추가합니다.

필수:

  • LLM_API_KEY

선택:

  • LLM_API_BASE (OpenAI 호환 API 베이스 URL)
  • LLM_MODEL (예: gpt-4o-mini)
  • LLM_FALLBACK_MODEL (기본 모델 실패/약한 출력 시 사용할 폴백 모델)
  • DISCORD_WEBHOOK_URL (Discord 외부 알림용 웹훅 URL)
  • BLOG_BASE_URL (블로그 기본 주소, Variables 권장)
  • DISCORD_SEND_EXCERPT (Discord 알림 요약 전송 여부, Variables 권장)
  • VALIDATION_ALLOWED_EMAIL_DOMAINS (쉼표 구분 이메일 도메인 allowlist)
  • VALIDATION_ALLOWED_HOSTS (쉼표 구분 내부 호스트 allowlist)
  • FAIL_ON_LLM_ERROR (Variables 권장, true면 LLM 오류 시 워크플로 실패)
  • FAIL_ON_VALIDATION_ERROR (Variables 권장, true면 검증 오류 시 워크플로 실패)
  • MAX_CANDIDATE_ATTEMPTS (Variables 권장, 실행당 시도할 후보 소스 최대 개수)

기본 동작(FAIL_ON_VALIDATION_ERROR=false):

  • 검증 실패 시 실행은 실패하지 않고 종료됩니다.
  • 단, VALIDATION_BODY_TOO_SHORT는 소스를 즉시 reject하지 않고 소스별 최대 3회 재시도 후 _agent_reject/로 이동합니다.
  • 그 외 검증 실패는 해당 소스를 _agent_reject/로 이동합니다.
  • 발행 실패 시 가능한 경우 같은 실행에서 다음 후보 소스를 이어서 시도합니다(기본 최대 3개).

Discord 알림 설정 상세는 tools/blog_agent/NOTIFICATIONS.md 참고

4) 실행 방법

A. 예약 실행(기본)

  • 매일 09:10 KST에 자동 실행됩니다.

B. 수동 실행

  1. GitHub → Actions → Blog Auto Publish 워크플로 선택
  2. Run workflow 클릭
  3. mode 입력
    • pr (기본): PR 생성
    • direct: 직접 push

5) 실행 결과 확인

  • 워크플로 Summary에 다음 정보가 기록됩니다.
    • 선택된 원본 파일명
    • 생성된 포스트 파일명
    • 검증 결과

6) PR 모드 vs Direct 모드

  • PR 모드(기본): 새 브랜치를 만들고 PR을 생성합니다.
  • Direct 모드: 결과를 현재 브랜치에 커밋/푸시합니다.
    • Actions에서 mode=direct로 실행하거나 환경변수 MODE=direct를 설정합니다.

7) 로컬 실행(선택)

export LLM_API_KEY=...
# 선택: LLM_API_BASE, LLM_MODEL, MODE=direct
python tools/blog_agent/main.py

8) 문제 발생 시 체크리스트

  • LLM_API_KEY가 등록되어 있는지 확인
  • OpenAI/API 제공자 결제/쿼터가 충분한지 확인 (insufficient_quota면 충전 후 재실행)
  • _agent_source/에 처리 가능한 .md 파일이 존재하는지 확인
  • .blog-agent/state.json에 이미 사용된 파일이 등록되어 있는지 확인
  • 워크플로 Summary에 표시된 오류 메시지 확인

9) 글 길이/품질 튜닝

  • tools/blog_agent/config.yml의 quality 섹션으로 생성 품질을 조정할 수 있습니다.
    • target_body_chars_min, target_body_chars_max, target_body_chars_ratio
    • min_source_retention_ratio (최소 보존율 하드 게이트)
    • min_narrative_chars (코드/표 제외 설명 본문 최소 길이)
    • max_code_ratio (코드 비중 상한)
    • min_narrative_paragraphs_per_h2 (H2별 설명 문단 하한)
    • narrative_paragraph_exempt_h2_keywords (문단 하한 예외 H2 키워드)
    • min_h2_sections
    • require_code_block_if_source_has_code
  • min_body_length는 하드 하한이며, 기본값은 2400자입니다.
  • llm.max_generation_passes: 3이면 초안 생성 후 품질 미달 시 최대 2회 보강 생성합니다.
  • max_candidate_attempts: 5이면 한 실행에서 최대 5개 소스까지 재선정해 발행을 시도합니다.
  • 기본 권장값(발행률과 품질 균형):
    • llm.max_tokens: 6200
    • llm.max_generation_passes: 3
    • quality.target_body_chars_min: 4200
    • quality.target_body_chars_max: 9800
    • quality.target_body_chars_ratio: 1.15
    • quality.min_source_retention_ratio: 0.2
    • quality.min_narrative_chars: 2600
    • quality.max_code_ratio: 0.45
    • quality.min_narrative_paragraphs_per_h2: 2 (요약은 예외)
    • quality.min_h2_sections: 3
    • max_candidate_attempts: 5

© 2024. Chiptune93 All rights reserved.