voocel/ainovel-cli

ainovel-cli – 자동화된 장편 소설 창작 엔진

무엇인가요 – ainovel-cli는 인간의 개입 없이 완전한 소설을 생성하기 위한 명령줄(옵션으로 TUI) 애플리케이션입니다. 결정론적인 "엔진"이 무엇을 해야 하는지를 결정하고, 실제로 텍스트를 생성하는 3개의 자율 에이전트(Architect, Writer, Editor)를 조율하며, 가끔 의미적 판단을 내리는 가벼운 Arbiter를 포함합니다.

핵심 아이디어

결정론적 제어 흐름 – 엔진은 JSON 스타일의 저장소를 읽고, 정적 라우팅 테이블을 따르며 워커를 디스패치합니다. 제어 로직에는 LLM 호출이 전혀 사용되지 않아 프로세스가 완전히 재현 가능하고 테스트 가능합니다.
세 가지 창의적 에이전트
- Architect – 책의 제목, 줄거리, 개요, 캐릭터 시트, 세계 규칙을 구축합니다.
- Writer – 각 장마다 고정된 파이프라인을 실행: 컨텍스트 로드 → 이전 장 읽기 → 장 계획 → 초안 작성 → 일관성 검사 → 커밋.
- Editor – 완성된 장을 일관성, 리듬, 예고, 흥미 유발, 미적 품질 등 7가지 품질 차원에서 검토하고, 재작성 또는 보완을 트리거할 수 있습니다.
Arbiter – 단일 LLM 호출로 어떤 플래너를 사용할지, 사용자 입력 편집을 어떻게 처리할지, 또는 막다른 길에서 벗어날지 결정하는 함수입니다. 그 결정은 로그에 기록되며 재실행할 수 있습니다.
롤링 윈도우 계획 – 처음 두 개의 "볼륨"과 첫 번째 "아크"만 미리 계획합니다. 이야기가 진행되면서 Architect는 요약과 캐릭터 스냅샷을 사용해 다음 아크/볼륨을 확장하여, 매우 긴 작품에서 "한 번에 모든 것을 계획"하는 문제를 피합니다.
500장 이상의 컨텍스트 관리 – 장 → 아크 → 볼륨의 계층적 요약에 더해, 예고, 캐릭터 등장, 상태 변화, 관계성 기반으로 관련된 이전 장을 스마트하게 추천하는 시스템입니다.
체크포인트 및 복구 – 각 도구가 완료된 후 체크포인트가 기록됩니다. 충돌 시 정확한 단계(계획/초안/검토/커밋)에서 복구 가능하며, 진행 상황을 잃지 않습니다.
인터랙티브 및 헤드리스 모드 – curses 기반 TUI로 실시간으로 진행 상황을 모니터링하고 편집을 삽입할 수 있습니다. --headless 플래그로 서버, CI 파이프라인, NAS 장치에서 무인 실행이 가능합니다.
다중 모델 지원 – OpenRouter, Anthropic, Gemini, OpenAI, Ollama, Bedrock 등과 호환됩니다. 설정 파일의 roles 섹션을 통해 각 에이전트에 다른 프로바이더/모델을 할당할 수 있습니다.

작동 방식 (고수준 흐름)

사용자 프롬프트 → Arbiter가 Architect 선택 → Architect가 뼈대 및 첫 번째 아크 생성 →
Writer가 반복적으로 장 작성 → Editor가 각 아크 검토 →
필요 시 Writer가 재작성 / Editor가 보완 →
아크 종료 시 Architect가 다음 아크 확장 → 책 완성 시까지 반복

모든 상태(단계, 흐름, 초안, 요약, 체크포인트)는 output/novel/ 아래의 단순 파일 시스템 저장소에 저장됩니다.

설치

# macOS / Linux용 원라인 (Go 필요 없음)
curl -fsSL https://raw.githubusercontent.com/voocel/ainovel-cli/main/scripts/install.sh | sh

# 또는 Go를 통한 설치
go install github.com/voocel/ainovel-cli/cmd/ainovel-cli@latest

설치 프로그램은 바이너리 추출 전에 SHA-256 매니페스트를 검증합니다. Windows 사용자는 사전 빌드된 릴리스를 다운로드할 수 있습니다.

일반적인 사용법

인터랙티브 – ainovel-cli를 실행하고 화면 안내를 따라 프로바이더를 선택하고 API 키를 입력하며, 한 문장의 이야기 아이디어를 입력합니다.
헤드리스 – 장시간 실행에 적합:
```
ainovel-cli --headless --prompt "변방의 소도시에서 시작하는 동방 판타지 장편 소설을 쓰세요"
```
로그는 logs/headless.log에, 생성된 소설은 output/novel/에 저장됩니다.
Docker – ghcr.io/voocel/ainovel-cli:latest를 다운로드하고 설정 파일 및 작업 디렉터리를 마운트합니다. TUI를 사용하려면 -it을 사용하거나, 직접 헤드리스로 실행합니다.

설정 JSONC 파일(~/.ainovel/config.json 또는 ./.ainovel/config.json)에 다음을 저장합니다:

프로바이더 선택 및 API 자격 증명.
모델 목록과 선택적 모델별 컨텍스트 창 크기.
기본 추론 노력 수준(off/low/medium/high/xhigh/max).
역할별 오버라이드(roles.writer, roles.architect 등)로 세그멘테이션에는 저렴한 모델, 창작에는 비싼 모델을 할당할 수 있습니다.
스타일 프리셋(default, suspense, fantasy, romance).
커스텀 룰 파일(rules/*.md)로 "AI 톤"을 억제하거나 코드를 건드리지 않고 저자 고유의 선호를 강제할 수 있습니다.

임포트 / 익스포트

임포트 (/import <file>) – 기존 소설을 읽어들여 LLM으로 세그멘테이션하고 사실을 추출하며 새로운 기반을 구축한 후 작성 계속.
익스포트 (/export) – 완성된 장을 일반 텍스트 .txt 또는 .epub 파일로 내보내며 내부 메타데이터를 제거합니다.

진단 /diag는 워크플로 건강 상태, 품질 점수, 계획 상태, 컨텍스트 일관성 등을 포함하는 마크다운 리포트를 생성합니다. 이 리포트는 익명화되어 meta/diag-export.md에 저장되어 버그 보고를 쉽게 합니다.

누가 사용할 수 있나요

대규모 초안을 생성하고 장기적인 플롯 일관성을 유지하는 "공동 작가"를 원하는 작가.
방대한 세계관이나 퀘스트 내러티브가 필요한 게임 디자이너.
다중 에이전트 LLM 오케스트레이션과 결정론적 파이프라인을 탐구하는 연구자.

제한 사항

시스템은 외부 LLM API에 의존하며, 비용과 레이트 제한은 선택한 프로바이더에 따라 달라집니다.
품질은 여전히 프롬프트와 기반 모델에 달려 있습니다. 내장 에디터는 문제를 감지할 수 있지만, 문학적 가치를 보장하지는 않습니다.
현재 중국어 생성에 집중하고 있습니다(토큰 추정 로직에서 CJK 언급). 그러나 아키텍처 자체는 언어에 독립적입니다.

TL;DR – ainovel-cli는 Go 기반 CLI/TUI로, 결정론적 엔진을 사용해 세 개의 LLM 에이전트(Architect, Writer, Editor)와 Arbiter를 조율하여 장편 소설(500장 이상)을 자동으로 초안, 검토, 보완합니다. 체크포인트 복구, 계층적 컨텍스트 요약, 다중 모델 지원, Docker 이미지, 풍부한 설정을 제공하며 코드를 작성하지 않고도 사용 가능합니다.

voocel/ainovel-cli

ainovel-cli – 자동화된 장편 소설 창작 엔진

관련