mirror of https://github.com/epoko77-ai/im-not-ai.git synced 2026-06-21 13:18:09 +00:00

epoko77-ai 7853b6977e feat: Humanize KR 하네스 초기 구성

AI가 쓴 한글 글을 "사람이 쓴 글처럼" 윤문하는 Claude Code 하네스.

- 10대 카테고리 × 40+ AI 티 패턴 분류 체계 (S1/S2/S3 심각도)
- 6인 에이전트 파이프라인:
  * korean-ai-tell-taxonomist (분류 체계 SSOT 관리)
  * ai-tell-detector (스팬 단위 탐지 리포트)
  * korean-style-rewriter (근거 기반 수술적 윤문)
  * content-fidelity-auditor (13항 의미 동등성 감사)
  * naturalness-reviewer (잔존·과윤문 판정, 품질 등급)
  * humanize-web-architect (Next.js 웹 확장 설계)
- 하이브리드 실행 모드: 순차 파이프라인 + 병렬 검증 팀
- 4대 철칙: 의미 불변 / 근거 기반 / 장르 유지 / 과윤문 금지

2026-04-24 22:13:58 +09:00

7.8 KiB

Raw Permalink Blame History

Humanize KR 웹 서비스 스펙 (Phase 5에서만 로드)

Humanize Korean 파이프라인을 일반 사용자용 웹앱으로 확장할 때 아키텍트가 따르는 참조. 기본 윤문 파이프라인이 안정화된 뒤에만 읽는다.

1. 서비스 콘셉트

한 줄 설명: AI가 쓴 한글을 붙여 넣으면 "사람이 쓴 것처럼" 윤문해주는 서비스.

핵심 가치:

근거 제시: 어디가 왜 AI 티인지 카테고리별 하이라이트.
내용 불변 보증: 사실·수치·인용이 바뀌지 않았음을 diff로 시각화.
한국어 특화: 번역투·영어 용어 과다 등 한글 고유 패턴에 특화.

경쟁 차별점:

기존 영어 중심 humanizer(QuillBot·Hix·Undetectable AI)가 한국어에 약함.
단순 재작성이 아닌 "탐지 → 근거 → 수술적 윤문" 3단계.

2. 기술 스택

프레임워크: Next.js 15 App Router + React Server Components.
런타임: Vercel Fluid Compute (기본 Node.js 24 LTS).
AI: Vercel AI Gateway — Claude(탐지·윤문) + GPT(교차 검증 옵션).
스타일: Tailwind CSS v4 + shadcn/ui + Pretendard 자동 로딩.
상태: useActionState + SSE 스트리밍.
캐시: Runtime Cache API (입력 해시 기반 결과 재활용).
DB (옵션): Neon Postgres (히스토리 저장 시만).
인증 (옵션): Clerk Marketplace.
이메일 (옵션): Resend (가입 확인·요금제 알림).

3. 아키텍처 토폴로지

[Browser]
    ↓ POST /api/humanize (stream: true)
[Routing Middleware]
    ├─ BotID 검증
    ├─ 쿼터 확인 (Runtime Cache)
    └─ 언어 감지 (한글 아니면 400)
    ↓
[Next.js App Router · Fluid Compute]
    ↓
[Vercel Workflow — durable orchestration]
    ├─ step: detect()         ← AI Gateway → Claude Haiku
    ├─ step: rewrite()        ← AI Gateway → Claude Opus
    ├─ step: fidelity_audit() ← AI Gateway → Claude Sonnet
    └─ step: review()         ← AI Gateway → GPT-5 (옵션)
    ↓ stream SSE
[Browser EventSource]

Workflow는 각 step 실패 시 재시도·부분 응답을 허용한다. detect 단계 완료 즉시 하이라이트가 먼저 스트리밍되어 체감 지연을 줄인다.

4. API 스펙

`POST /api/humanize`

입력:

{
  "text": "…",
  "genre": "auto | column | report | blog | formal",
  "min_severity": "S1 | S2 | S3",
  "options": {
    "preserve_formatting": false,
    "cross_validate_with_gpt": false,
    "stream": true
  }
}

응답 (SSE):

event: detection_meta
data: {"detected_count":37,"score":71.5,"estimated_genre":"column"}

event: detection_finding
data: {"id":"f001","category":"A-2","severity":"S1","start":142,"end":153,"text_span":"데이터 분석을 통해","reason":"..."}
...

event: rewrite_chunk
data: {"delta":"데이터를 분석해 인사이트를 얻는다."}
...

event: audit_verdict
data: {"verdict":"full_pass"}

event: review_verdict
data: {"verdict":"accept","quality_level":"A","score_after":18.2}

event: final
data: {"rewrite_text":"…","summary":{...}}

에러 코드:

400: 입력 검증 실패 (비한국어·길이 초과·빈 문자열).
401: 인증 필요 (유료 플랜 API).
429: 쿼터 초과.
502: AI Gateway upstream 실패.
504: Workflow 타임아웃.

개별 라우트

POST /api/detect — 탐지만 (리포트 JSON 반환).
POST /api/rewrite — 탐지 결과를 같이 주면 윤문만.
POST /api/review — 윤문본을 주면 재평가만.
GET /api/runs/:id — 저장된 히스토리 (인증 사용자).
DELETE /api/runs/:id — 히스토리 삭제.

5. UX 플로우

화면 1 — 랜딩·입력

좌측: 붙여넣기 textarea (최대 10,000자, 현재 글자 수 표시).
우측: 사이드 패널
- 장르 라디오 (자동·칼럼·리포트·블로그·공적).
- 엄격도 슬라이더 (S1만 / S2+ / 전체).
- 옵션 토글: "영어 인용 유지", "이모지 유지" (기본 꺼짐).
하단: "윤문하기" 1 버튼. 익명 사용자는 남은 횟수 표시.

화면 2 — 처리 진행 (스트리밍)

탐지 하이라이트가 실시간으로 문서에 그려짐.
우측 사이드: 카테고리별 카운트 막대 그래프.
윤문 시작되면 하단 영역에 토큰 스트림.

화면 3 — 좌우 diff 뷰

좌: 원문 + 카테고리 하이라이트.
우: 윤문본 + 변경 영역 강조.
상단 배지: 변경률 18% · S1 0 잔존 · 점수 71.5 → 18.2 · 등급 A.
우측 패널: 주요 변경 3~5건 (before/after 카드).

화면 4 — 완료·액션

"윤문본 복사" / ".md 다운로드" / "2차 윤문" / "피드백 보내기" 버튼.
하단 보증 문구: "내용은 수정되지 않았습니다. 사실·수치·인용은 원문과 동일합니다."

화면 5 — 히스토리 (인증 사용자)

최근 50건의 run 목록.
각 run 카드에 입력 시각·길이·점수 개선·등급.
개별 클릭 시 화면 3(diff 뷰) 재현.

6. 데이터 모델 (Neon Postgres 옵션)

테이블

users (Clerk 연동)

id (Clerk user_id 매핑)
plan (anonymous / free / pro)
quota_daily (integer)
created_at

humanize_runs

id (uuid)
user_id (nullable, 익명 허용)
input_hash (sha256, 중복 탐지용)
input_length
estimated_genre
score_before, score_after
change_rate
quality_level (A/B/C/D)
created_at
retain_content (bool — 사용자가 본문 저장 동의했는지)

run_contents (retain_content = true 일 때만)

run_id
input_text, rewrite_text
detection_json, diff_json
expires_at (30일 후 자동 삭제)

feedback

run_id, user_id, type (over_polish / under_polish / wrong_category / other), comment, created_at

7. 요금·쿼터·인증

플랜	가격	일 쿼터	글자 한도	API
Anonymous	무료	5회	3,000자	✕
Free (로그인)	무료	30회	5,000자	✕
Pro	$9/월	300회	10,000자	✓ (API 키 발급)
Team	$29/월	1,500회	20,000자	✓ + 웹훅

BotID 검증을 통해 익명 쿼터 남용을 차단. 쿼터는 Runtime Cache(IP + user hash)로 관리.

8. 배포·운영

환경: vercel.ts로 설정 (vercel.json 사용 안 함).
환경변수:
- AI_GATEWAY_API_KEY
- DATABASE_URL (Neon)
- CLERK_SECRET_KEY (옵션)
- RESEND_API_KEY (옵션)
Cron (옵션): 일 1회 오래된 히스토리 정리 (/api/cron/cleanup).
모니터링: Vercel Analytics + AI Gateway observability 대시보드.
Rolling Releases로 신규 프롬프트 버전 점진 롤아웃.

9. 확장 로드맵

단계	내용
v0 MVP	익명·단일 호출·결과 저장 안 함. Phase 3까지만 (탐지+윤문+단일 검증)
v1	Clerk 로그인·히스토리·장르 프리셋·교차 검증 옵션
v2	Pro/Team 플랜·API 키·웹훅·팀 계정
v3	Chrome Extension — 선택 영역 즉석 윤문·Google Docs 플러그인
v4	한국어 외 일본어·중국어로 확장 (언어별 taxonomy 분리)

10. 리스크 & 완화

악용(AI Detector 우회): 학계·저널리즘 맥락에서 논란. 서비스 설명에 "진실성 보증 도구 아님" 명시, 학술 제출용 사용을 약관에서 제한.
오탐·과윤문: 등급 C/D일 때 "사람 검토 권고" 안내, 결과를 자동 게시하지 않음.
프롬프트 주입: 입력을 역할·시스템 프롬프트로 해석하지 않도록 격리. Claude·GPT 모두 user 메시지 슬롯에서만 처리.

7.8 KiB Raw Permalink Blame History