InkOS — 다중 에이전트 기반 자율 소설 집필 CLI/Studio

한 줄 요약
InkOS는 소설 생성에 특화된 오픈소스 AI 에이전트 시스템으로, plan → compose → write → audit → revise 체인을 중심으로 통제 문서(control surface), 정본 상태(JSON + Markdown projection), 자동 검수/롤백, 로컬 Studio UI를 결합한 비교적 성숙한 멀티에이전트 아키텍처를 제공한다.

Quick Links

GitHub Repository: https://github.com/Narcooo/inkos
README (English): https://github.com/Narcooo/inkos/blob/main/README.en.md
NPM Package: https://www.npmjs.com/package/@actalk/inkos
OpenClaw Skill: https://clawhub.ai/narcooo/inkos
CLI Entry Point: https://github.com/Narcooo/inkos/blob/main/packages/cli/src/index.ts
Pipeline Runner: https://github.com/Narcooo/inkos/blob/main/packages/core/src/pipeline/runner.ts
State Manager: https://github.com/Narcooo/inkos/blob/main/packages/core/src/state/manager.ts
Studio Server: https://github.com/Narcooo/inkos/blob/main/packages/studio/src/api/server.ts
Studio App: https://github.com/Narcooo/inkos/blob/main/packages/studio/src/App.tsx
관련 논문: 공개 링크 확인되지 않음
공개 데모 사이트: 별도 SaaS 데모는 확인되지 않음. 대신 inkos studio 로컬 웹 워크벤치 제공
Wiki / Discussions: 공개 Wiki/Discussions 문서는 확인되지 않음

Documentation & Community Signals

1) 문서화 성격

이 저장소는 README 중심 프로젝트다. 공식 사용법, 파이프라인, 핵심 명령어, 로드맵, 기능 설명 대부분이 README에 밀집되어 있다. 별도 Wiki나 public Discussion에 의존하는 구조가 아니라, 코드와 README가 사실상 1차 문서다.

2) 커뮤니티/유지보수 시그널

이슈/PR 흐름을 보면 다음 주제가 현재 유지보수의 핵심 축으로 보인다.

state validation / runtime state delta 안정화
모델/provider 호환성 (OpenAI compatible endpoint, Google provider, GLM/MiniMax 등)
CLI/Studio 사용성 개선
Windows / 환경 차이 대응
JSON sanitation 및 graceful degradation 강화

즉, 단순 데모성 생성기가 아니라, 실제로 운영 중 발생하는 상태 불일치와 공급자 편차를 처리하는 방향으로 진화 중인 프로젝트로 읽힌다.

3) 구현 관점에서 읽어야 할 포인트

이 프로젝트를 참고할 때 README의 “무엇을 한다”보다 더 중요한 것은, 코드가 보여주는 다음 네 가지다.

중간 산출물을 파일로 남긴다 (intent.md, context.json, rule-stack.yaml, trace.json)
정본 상태를 LLM이 통째로 쓰지 못하게 한다 (JSON delta + validation + reducer)
실패 시 회복 경로가 있다 (snapshot, rollback, repair-state, lock)
각 에이전트에 다른 모델을 라우팅할 수 있다 (cost/quality 최적화)

Key Features

1) 멀티에이전트 소설 집필 파이프라인

InkOS의 중심은 한 번에 프롬프트 한 덩어리로 쓰는 방식이 아니라, 에이전트 역할을 분리한 순차 파이프라인이다.

Radar: 트렌드/시장 신호 스캔
Planner: 다음 장의 의도(intent) 계약 생성
Composer: 필요한 진실 파일과 규칙을 선택/조합
Architect: 장 구조 및 scene beat 설계
Writer: 실제 장문 생성
Observer / Reflector: 장 텍스트에서 상태 변화 추출
Normalizer: 길이 보정
Continuity Auditor: 연속성/논리 검수
Reviser: 문제 수정 후 재검수

이 구조 덕분에 “창작”, “상태 정리”, “품질 보증”이 분리되어 있다.

2) 33차원 감사(audit) + De-AI-ification

README 기준으로 Auditor는 33개 차원에서 draft를 검사한다. 캐릭터 기억, 자원 연속성, hook payoff, pacing, emotion arc, AI 말투 흔적 등을 검사하고, 실패하면 자동 revision loop에 들어간다. 단순 spell check가 아니라 서사 상태 검증기에 가깝다.

3) 입력 거버넌스(Control Surface)

이 프로젝트의 가장 강한 설계 포인트 중 하나다. 모든 요청을 프롬프트 한 번으로 밀어넣지 않고, 아래 통제 문서를 분리한다.

story/author_intent.md: 장기적인 창작 의도
story/current_focus.md: 향후 1–3화의 초점
story/runtime/chapter-XXXX.intent.md: 이번 장의 human-readable 계약
story/runtime/chapter-XXXX.context.json: 실제 투입된 문맥
story/runtime/chapter-XXXX.rule-stack.yaml: 우선순위 규칙층
story/runtime/chapter-XXXX.trace.json: 조합 과정 추적

즉, 의도(Intent) 와 실행 컨텍스트(Context) 가 분리되어 있고, 중간 산출물이 inspectable 하다.

4) 정본 상태 관리: JSON + Markdown Projection

README와 코드 모두에서 드러나는 핵심 패턴은 다음이다.

사람이 읽는 Markdown truth files 유지
실제 authoritative state는 story/state/*.json
LLM은 full markdown을 재작성하지 않고 JSON delta를 출력
코드 레이어가 validateRuntimeState/immutable update를 수행
실패한 상태는 전파하지 않고 reject

이는 LLM이 상태 저장소를 직접 파괴하지 못하게 만드는 매우 실용적인 안전장치다.

5) Snapshot / Rollback / Repair

각 장 단위로 state snapshot을 남기고, review reject나 rewrite 시 이전 시점으로 롤백할 수 있다. StateManager는 snapshot, chapter index, runtime artifacts, memory DB를 함께 관리하며, rejected chapter 이후 하위 결과물까지 정리한다. 운영계 워크플로우에 가까운 설계다.

6) SQLite 기반 Temporal Memory (Node 22+)

Node 22 이상이면 story/memory.db를 생성해 facts, hooks, chapter summaries를 SQLite로 인덱싱한다. 불가능한 런타임에서는 markdown fallback으로 동작한다. 대규모 컨텍스트를 통째로 프롬프트에 넣는 대신 검색 기반 memory retrieval을 적용한 점이 좋다.

7) Per-Agent Model Routing

전역 모델 1개로 모든 단계를 처리하지 않아도 된다.

Writer는 창의적 모델
Auditor는 더 저렴하고 빠른 모델
Radar는 로컬/커스텀 모델

이런 식으로 agent별 provider/model override가 가능하다. 비용 최적화와 품질 분리를 동시에 달성하는 패턴이다.

8) Studio: 로컬 웹 워크벤치

inkos studio 명령으로 Vite + React + Hono 기반 로컬 웹 UI를 띄울 수 있다. Dashboard, Book detail, Truth files, Analytics, Radar, Config, Import, Style, Doctor, Log viewer, Daemon control 등이 구현되어 있다. 단순 CLI wrapper가 아니라 실질적인 운영 콘솔에 가깝다.

9) Fanfic / Continuation / Style Cloning

프로젝트는 “새 소설 생성”만이 아니라 아래 시나리오를 염두에 둔다.

기존 장문 텍스트 import 후 continuation
원작 기반 fanfic initialization
style fingerprint 추출 및 style import
AI detection / anti-detect revision

즉, “창작 도우미”보다 장기 연재 운영 도구에 더 가깝다.

10) Background Daemon + Notifications

inkos up/down 으로 background loop를 돌릴 수 있고, cron 기반 write/radar 스케줄링, concurrency 제한, daily cap, failure gate, cooldown 등을 설정할 수 있다. Config schema를 보면 Telegram 외에 WeChat Work, Feishu, Webhook 알림도 고려되어 있다.

Tech Stack

Core Stack

영역	사용 기술
모노레포	`pnpm-workspace` 기반 `packages/*` 구성
런타임	Node >= 20, 실무적으로는 Node 22 권장 (`.node-version`이 22, SQLite memory 활성화 조건도 22+)
언어	TypeScript 5.8.x
패키지 매니저	pnpm >= 9
테스트	Vitest 3.x

AI / Core Libraries

영역	라이브러리 / 버전
LLM SDK	`openai ^4.80.0`, `@anthropic-ai/sdk ^0.78.0`
검증	`zod ^3.24.0`
환경변수	`dotenv ^16.4.0`
YAML	`js-yaml ^4.1.1`
CLI	`commander ^13.0.0`
Export	`epub-gen-memory ^1.0.10`, `marked ^15.0.0`

Studio Stack

레이어	사용 기술 / 버전
프런트엔드	`react ^19.0.0`, `react-dom ^19.0.0`, `vite ^6.0.0`
서버	`hono ^4.7.0`, `@hono/node-server ^1.13.0`
UI 유틸	`@base-ui/react ^1.3.0`, `lucide-react ^0.577.0`, `class-variance-authority ^0.7.1`, `clsx ^2.1.1`, `tailwind-merge ^3.5.0`
스타일	`tailwindcss ^4.0.0`, `@tailwindcss/vite ^4.0.0`, `autoprefixer ^10.4.0`, `tw-animate-css ^1.4.0`, `@fontsource-variable/geist ^5.2.8`

코드에서 추가로 드러나는 구현 옵션

Provider: openai / anthropic / custom
API format: chat | responses
커스텀 HTTP headers 지원
agent별 model/provider/base-url/api-key-env override 지원
AI detection provider: gptzero / originality / custom
notification channel: telegram / wechat-work / feishu / webhook

Architecture

High-Level View

CLI / Studio
   │
   ▼
PipelineRunner
   │
   ├─ Radar (optional)
   ├─ Planner
   ├─ Composer
   ├─ Architect
   ├─ Writer
   ├─ Observer
   ├─ Reflector (JSON delta)
   ├─ State Validator / Reducer
   ├─ Length Normalizer
   ├─ Continuity Auditor
   └─ Reviser  ──┐
                 └── re-audit loop until critical issues are resolved
   │
   ▼
StateManager
   ├─ story/state/*.json   (authoritative)
   ├─ truth-file markdown  (human-readable projections)
   ├─ snapshots/
   ├─ runtime artifacts/
   └─ story/memory.db (Node 22+)

Repository Structure

inkos/
├─ assets/                  # README figures
├─ packages/
│  ├─ cli/                  # commander 기반 CLI
│  ├─ core/                 # agents, pipeline, state, models
│  └─ studio/               # React + Hono 로컬 웹 워크벤치
├─ skills/                  # OpenClaw skill metadata / docs
├─ scripts/
└─ test-project/

Important Entry Points

파일	역할	왜 중요하나
`packages/cli/src/index.ts`	CLI command registry	전체 사용자 인터페이스의 시작점
`packages/core/src/pipeline/runner.ts`	파이프라인 오케스트레이터	대부분의 엔드투엔드 동작이 여기서 합쳐짐
`packages/core/src/state/manager.ts`	snapshot/rollback/state projection	상태 일관성의 핵심
`packages/core/src/state/memory-db.ts`	SQLite memory index	장기 컨텍스트 retrieval 힌트
`packages/core/src/agents/*.ts`	agent별 역할 구현	멀티에이전트 설계 파악에 필수
`packages/core/src/models/project.ts`	config schema	provider/model routing, daemon, notifications 확인 가능
`packages/studio/src/api/server.ts`	Studio backend API	Hono, SSE, pipeline bridge
`packages/studio/src/App.tsx`	Studio frontend routing	어떤 운영 화면이 실제 구현됐는지 확인 가능

Agent Layer Analysis

1) Planner

planner.ts는 다음 입력을 조합한다.

author_intent.md
current_focus.md
story_bible.md
volume_outline.md
chapter_summaries.md
book_rules.md
current_state.md
memory retrieval 결과

출력은 “이번 장에서 반드시 유지해야 할 것 / 피해야 할 것 / 어떤 갈등을 우선해야 하는가”에 대한 intent contract다.
이 단계가 있다는 뜻은, Writer에게 바로 창작을 시키지 않고 통제된 목표를 먼저 생성한다는 것이다.

2) Composer

composer.ts는 context package와 rule stack을 생성한다. 특히 우선순위 계층을 분리한 점이 좋다.

hard_facts
author_intent
planning
current_task

그리고 “어떤 레이어가 어떤 레이어를 override할 수 있는가”를 명시한다.
이 설계는 의료 AI나 업무 에이전트에서 정책/가이드라인/로컬 요청 충돌 해결기로 바로 응용 가능하다.

3) Pipeline Runner

runner.ts는 전체 오케스트레이션 허브다.

agent별 model override 처리
draft / audit / revise / full write orchestration
state recovery / truth validation
notification
book init / fanfic init / radar scan / draft write
SQLite availability fallback

실전 구현에서 참고할 만한 점은, 기능이 많지만 결국 오케스트레이터 하나로 수렴된다는 것이다. CLI와 Studio는 이 레이어 위에 thin interface처럼 올라가 있다.

State Model

Canonical Truth Files

InkOS가 관리하는 핵심 진실 파일은 7개다.

current_state.md
particle_ledger.md
pending_hooks.md
chapter_summaries.md
subplot_board.md
emotional_arcs.md
character_matrix.md

중요한 건 파일 개수보다 운영 철학이다.

인간은 Markdown projection을 본다.
시스템은 JSON authoritative state를 본다.
LLM은 full replace가 아니라 delta를 제안한다.
reducer/validator가 구조적 무결성을 강제한다.

이 패턴은 장문 생성뿐 아니라 장기 상태가 쌓이는 모든 에이전트 시스템에 유효하다.

Runtime Artifacts

각 장에 대해 아래 artifacts가 남는다.

chapter-XXXX.intent.md
chapter-XXXX.context.json
chapter-XXXX.rule-stack.yaml
chapter-XXXX.trace.json

즉, “무슨 프롬프트를 넣었는지”보다 한 단계 더 나아가, 왜 그 문맥이 선택되었는가까지 추적할 수 있다.

Review, Rollback, and Safety

StateManager와 review flow에서 읽히는 안전장치는 다음과 같다.

write lock (.write.lock) 으로 동시성 제어
chapter snapshot 자동 저장
reject 시 downstream artifact 및 memory index 정리
structured state bootstrap / migration
validation failure 시 recovery path
human review gate (review approve/reject)

LLM을 쓰는 자동화 시스템에서 가장 어려운 부분은 “잘 만들기”보다 “망가졌을 때 복구하기”다.
InkOS는 이 부분을 꽤 진지하게 다룬다.

Studio Architecture

Studio는 단순 정적 프런트엔드가 아니다.

Backend: Hono + Node server
Frontend: React + Vite
Streaming: SSE 기반 진행 로그/LLM 스트리밍 브로드캐스트
Pages: Dashboard, BookCreate, BookDetail, ChapterReader, Analytics, TruthFiles, Config, Radar, Doctor, GenreManager, StyleManager, ImportManager, DaemonControl, LogViewer

즉, CLI용 백엔드를 재사용하는 로컬 운영 콘솔이다. 나중에 SaaS 제품으로 확장하려면 이 레이어를 그대로 웹 서비스 골격으로 발전시킬 수 있다.

Usage & Setup

권장 환경

Node 22 권장
이유:
- .node-version이 22
- SQLite temporal memory가 Node 22+에서 활성화됨
pnpm 9+
OpenAI / Anthropic / OpenAI-compatible endpoint 중 하나 준비

전역 설치

npm i -g @actalk/inkos
inkos init my-novel
cd my-novel

핵심 환경 변수

프로젝트 .env 또는 글로벌 설정에 다음을 둔다.

INKOS_LLM_PROVIDER=openai          # openai / anthropic / custom
INKOS_LLM_BASE_URL=https://api.openai.com/v1
INKOS_LLM_API_KEY=YOUR_KEY
INKOS_LLM_MODEL=gpt-4o
# Optional
# INKOS_DEFAULT_LANGUAGE=en
# INKOS_LLM_TEMPERATURE=0.7
# INKOS_LLM_MAX_TOKENS=8192
# INKOS_LLM_THINKING_BUDGET=0

권장 시작 순서

# 1) 새 책 생성
inkos book create --title "The Last Delver" --genre litrpg

# 2) 다음 장 intent 생성
inkos plan chapter my-book --context "멘토 갈등을 먼저 부각"

# 3) context/rule-stack 생성
inkos compose chapter my-book

# 4) 전체 파이프라인으로 다음 장 작성
inkos write next my-book

# 5) 상태 확인 및 리뷰
inkos status
inkos review list my-book
inkos review approve-all my-book

# 6) 내보내기
inkos export my-book --format epub

Atomic Command 방식

외부 에이전트나 스크립트와 결합하려면 atomic mode가 더 좋다.

inkos plan chapter my-book --json
inkos compose chapter my-book --json
inkos draft my-book --json
inkos audit my-book 31 --json
inkos revise my-book 31 --json

이 패턴의 장점은 단계별로 검토/보정/재시도가 가능하다는 점이다.

Natural Language Agent Mode

inkos agent "Write a LitRPG novel where the MC is a healer class"
inkos agent "Write the next chapter and focus on the boss fight"

이 모드는 내부적으로 18개 도구를 조합하는 tool-use 기반 인터페이스다.
실무에서는 이 모드보다 atomic commands + 외부 오케스트레이터 조합이 더 예측 가능할 가능성이 높다.

Background Automation

inkos up
inkos down

daemon 모드는 cron 기반으로 radar/write를 스케줄링하고, quality gate와 concurrency cap를 둔다. 장기 연재 실험이나 unattended batch workflow에 적합하다.

로컬 Studio 실행

inkos studio
# 기본 포트 4567

소스에서 개발 실행

git clone https://github.com/Narcooo/inkos.git
cd inkos
pnpm install
pnpm dev
pnpm test
pnpm typecheck

구현 시 체크할 함정

Node 버전 차이: SQLite memory는 22+에서만 확실히 기대
provider 편차: custom OpenAI-compatible endpoint는 output format 차이를 고려해야 함
상태 파일 손상: JSON delta validation 경로를 우회하지 말 것
장문 컨텍스트 비대화: full file injection보다 retrieval selection 유지가 중요
사람 승인 절차: 완전 무인화보다 review gate를 남기는 편이 더 안정적

Personal Insights

1) 의료 AI에 주는 영감

의료 AI 워크플로우로 바꿔 보면 이 프로젝트의 핵심 패턴이 선명해진다.

author_intent.md = 진료 목표 / 관리 계획
current_focus.md = 이번 encounter의 초점
truth files = longitudinal patient state
audit loop = guideline / safety / contradiction checker
snapshot = clinical rollback / provenance point

특히 중요한 점은 생성 모델이 정본 상태를 직접 수정하지 못하게 하고, 구조화된 delta만 제안하게 만든다는 것이다.
의료 분야에서는 이 패턴이 다음 문제에 특히 유리하다.

증상/검사/약물/진단 간 논리 충돌 탐지
visit-to-visit longitudinal consistency 관리
human-in-the-loop 승인 체계
근거 없는 상태 overwrite 방지

실제 의료 AI로 가져가려면 SNOMED/LOINC/RxNorm 같은 ontology grounding, PHI 보호, 접근 제어, deterministic validator, 규제 로그가 추가되어야 한다. 하지만 상태-중심 안전 설계 자체는 매우 좋은 참고점이다.

2) Bioinformatics에 주는 영감

Bioinformatics 파이프라인은 흔히 “원본 데이터 → 중간 산출물 → 품질 관리 → 해석 → 리포트” 구조를 가진다. InkOS의 설계는 여기에 surprisingly well fit한다.

plan = 분석 목적/가설/샘플 우선순위 명시
compose = 필요한 메타데이터/참조 genome/실험 조건 선택
runtime artifacts = parameter provenance
JSON authoritative state = sample/run metadata source of truth
markdown projections = 사람이 읽는 lab note / summary report
audit/revise = QC/재해석 루프

즉, 이 프로젝트는 “소설 쓰기 도구”이지만 사실상 LLM이 개입하는 장기 상태형 파이프라인을 어떻게 통제할 것인가에 대한 reference implementation처럼 읽을 수 있다.
생물정보학 도메인으로 옮기면 sample lineage, variant interpretation note, hypothesis trace, QC exception handling 같은 부분에 바로 응용 가능하다.

3) Autonomous Agent 개발에 주는 영감

Autonomous Agent 관점에서 InkOS의 가장 가치 있는 포인트는 “에이전트를 많이 나눴다”가 아니다. 더 중요한 건 아래 세 가지다.

A. 중간 산출물의 가시성

많은 에이전트 시스템이 내부 reasoning을 숨긴 채 최종 output만 내놓는다. InkOS는 반대로:

intent
context
rule stack
trace
chapter snapshots
audit result

를 남긴다. 디버깅과 운영이 쉬워진다.

B. 모델 역할 분리

모든 agent가 같은 모델일 필요가 없다는 점을 코드 구조로 보여 준다.
생성형 작업, 구조화 추출, 검수, 라우팅, 로컬 검색은 각각 다른 모델/비용 구조가 적합하다.

C. 상태 갱신을 코드 레이어로 회수

Reflector가 state를 “작성”하는 것이 아니라 “delta 제안”만 하고, 실제 write는 코드가 담당한다.
이 패턴은 툴 사용형 agent, browser agent, ops agent, scientific agent 모두에 재사용할 가치가 높다.

4) 내가 이 프로젝트에서 재사용하고 싶은 설계 6가지

control surface 분리: 장기 목표와 단기 초점 분리
inspectable runtime artifacts: context/rule/trace 파일 남기기
authoritative structured state + human projection
validation-first delta application
snapshot + rollback + repair path
per-agent model routing + daemon governance

5) 한계와 주의점

이 프로젝트는 강력하지만, 그대로 다른 고위험 도메인에 옮기면 안 된다.

truth file 내용 자체가 LLM 추출물이라 semantic error 가능성 존재
quality gate가 도메인 전문가 지식 대신할 수는 없음
많은 동작이 파일 시스템 중심이라 멀티유저/분산 환경에는 재설계 필요
보안/권한/감사 요구가 강한 환경에서는 DB + event log 중심 구조로 확장 필요

그럼에도 불구하고, “상태를 가진 자율 에이전트를 운영 가능한 형태로 만드는 법” 이라는 관점에서 InkOS는 참고 가치가 높다.
특히 의료 AI/Bioinformatics/Autonomous Agent 분야에서 생성 모델을 직접 믿지 않고, 통제 문서와 검증 레이어로 감싼다는 설계 철학은 매우 유용하다.

Practical Takeaway

이 저장소를 구현 참고용으로 한 문장으로 요약하면 다음과 같다.

InkOS는 “창작용 LLM 앱”이라기보다, 장기 상태를 가진 멀티에이전트 시스템을 파일/JSON/검증/스냅샷으로 운영하는 참조 아키텍처다.

소설이라는 도메인만 걷어내고 보면, 아래 패턴이 남는다.

human intent surface
retrieval-driven composition
role-specialized agents
delta-based state update
structured validation
reversible execution
mixed CLI + local web console

이 조합은 다른 도메인으로 이식하기에 충분히 강하다.

'AI 생성 글 정리 > tech_github' 카테고리의 다른 글

Hindsight — 장기 학습형 AI 에이전트를 위한 구조화 메모리 시스템 (1)	2026.04.09
Superpowers — 코딩 에이전트에 설계·계획·구현·검증 습관을 주입하는 skill-driven 개발 프레임워크 (1)	2026.04.09
OpenScreen — 오픈소스 Screen Studio 대안, Electron 기반 데스크톱 데모 레코더/에디터 (0)	2026.04.09
PageIndex — 벡터 DB 없이 문서 구조와 LLM 추론으로 검색하는 reasoning-based RAG (0)	2026.04.09
agency-agents — 전문 역할형 AI 에이전트 명세집 + 멀티툴 변환/설치 툴킷 (0)	2026.04.09