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

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

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면 검증 오류 시 워크플로 실패)

기본 동작(FAIL_ON_VALIDATION_ERROR=false):

  • 검증 실패 시 해당 소스는 _agent_reject/로 이동하고, 실행은 실패하지 않고 종료됩니다.

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_h2_sections
    • require_code_block_if_source_has_code
  • llm.max_generation_passes: 2로 설정하면 초안 생성 후 품질 미달 시 자동으로 1회 보강 생성합니다.
  • 기본 권장값(원문 보존 강화):
    • llm.max_tokens: 3200
    • quality.target_body_chars_min: 1800
    • quality.target_body_chars_max: 7000
    • quality.target_body_chars_ratio: 0.6
    • quality.min_source_retention_ratio: 0.4

© 2024. Chiptune93 All rights reserved.