Word 템플릿의 플레이스홀더를 AI가 자동으로 채워주는 Next.js 기반 문서 생성 도구입니다.
- 스마트 플레이스홀더:
{{keyword}}또는{{keyword:작성지침}}형식 지원 - AI 자동 채우기: OpenAI GPT-5 또는 xAI Grok-4-Fast로 내용 자동 생성
- OpenAI 파일 검색 기반 처리: 긴 입력은
file_search로 관련 근거를 검색해 채움 - 다중 파일 업로드: 여러 참고 문서를 한 번에 업로드 (Drag & Drop 지원)
- Word 파일 지원: .docx 파일에서 텍스트 자동 추출
- 실시간 편집: AI가 생성한 내용을 바로 수정 가능
Hermes 같은 AI 에이전트는 브라우저나 Next 서버 없이, apps/cli(Next/React 등 웹 의존성이 전혀 없는 독립 패키지, 의존성 7개)만 전역 CLI로 설치해서 바로 쓸 수 있다.
git clone https://github.com/superwhyun/filldoc.git
cd filldoc/apps/cli
npm install # 의존성 설치 + esbuild로 dist/ 빌드 (prepare 스크립트)
npm install -g . # 빌드된 dist/를 전역 filldoc-* 커맨드로 연결(npm/pnpm은 git URL에서 서브디렉터리만 콕 집어 설치하는 기능을 제공하지 않으므로, 저장소 전체를 clone한 뒤 apps/cli에서 설치한다. 두 명령 다 실행해야 한다 — npm install -g .만 단독으로 실행하면 apps/cli/node_modules가 없는 상태라 prepare 빌드 스크립트가 esbuild를 못 찾아 실패한다.)
filldoc-extract-doc, filldoc-render-doc, filldoc-fill-doc, filldoc-extract-text, filldoc-templatize-doc, filldoc-build-template, filldoc-analyze-doc 커맨드가 어느 작업 디렉토리에서든 바로 실행된다.
전체 커맨드 목록, 파라미터, 데이터 형식, 에러 처리 방식은 .skills/filldoc/SKILL.md에 정리되어 있다. 에이전트는 이 저장소 링크만 받았다면 README보다 그 파일을 먼저 읽고 그대로 따라 하면 된다.
# 저장소 클론
git clone https://github.com/superwhyun/filldoc.git
cd filldoc
# 의존성 설치 (pnpm 권장 — packages/apps 워크스페이스 구조, pnpm-lock.yaml 기준)
pnpm install
# 또는
npm install
# 개발 서버 실행
pnpm dev
# 또는
npm run dev브라우저에서 http://localhost:3000 접속
- 우측 상단 ⚙️ Settings 버튼 클릭
- API 키 입력:
- OpenAI:
sk-로 시작하는 키 (https://platform.openai.com/api-keys) - Grok:
xai-로 시작하는 키 (https://console.x.ai)
- OpenAI:
- 기본 AI 제공자 선택
- 저장 클릭
Word 문서에 플레이스홀더를 작성합니다:
기본 형식:
{{company}}
{{date}}
작성 지침 포함:
{{title:문서 제목을 20자 이내로 작성}}
{{abstract:문서 개요를 300자 이내로 요약}}
{{summary:핵심 내용을 500자 이내로 요약}}
- Choose File 클릭 또는 파일을 드래그하여 .docx 템플릿 업로드
- 자동으로 플레이스홀더 추출
- 추출된 플레이스홀더 목록 확인
- 작성 지침이 있는 경우 함께 표시됨
- Continue to Data Upload 클릭
- 데이터 파일을 업로드 (여러 파일 선택 가능)
- 텍스트 파일: .txt, .md
- Word 문서: .docx
- PDF 문서: .pdf
- 파일을 드래그 앤 드롭으로 추가
- 업로드된 파일 목록 확인
- AI로 자동 채우기 클릭
💡 Tip: Word 및 PDF 파일을 업로드하면 자동으로 텍스트를 추출하여 AI에 전달합니다.
OpenAI 선택 시, 긴 텍스트를 프롬프트에 그대로 넣지 않고 아래 순서로 처리합니다.
- 추출된 텍스트를 임시 파일로 업로드
- 벡터 스토어 생성 및 인덱싱
file_search로 관련 근거 검색- GPT-5가 검색 결과를 바탕으로 플레이스홀더 채움
- 처리 후 업로드 파일/벡터 스토어 즉시 정리(cleanup)
추가 동작:
- OpenAI 경로는 JSON Schema 기반 구조화 출력으로 파싱 안정성을 높입니다.
file_search실패 시 기존 inline 프롬프트 방식으로 1회 fallback 합니다.- cleanup은 재시도(backoff) 로직으로 안정성을 높였습니다.
/api/fill-placeholders 응답에는 다음 필드가 포함될 수 있습니다.
filledPlaceholders: 최종 채워진 값evidence:file_search가 찾은 근거 텍스트 목록processing:usedFallback,fallbackReason,cleanup상태 등 실행 메타데이터
- AI가 자동으로 생성한 내용 확인
- 분석 메타 정보(file_search 사용 여부, fallback 여부) 확인
- 필요하면 근거 보기에서 검색된 텍스트 샘플 확인
- 필요시 각 항목을 직접 수정
- Generate Document 클릭
- 생성된 Word 문서 다운로드
- Start Over로 새 문서 작성
AI가 더 정확한 내용을 생성하도록 구체적인 지침을 제공하세요:
❌ {{summary}}
✅ {{summary:문서의 핵심 내용을 3-5개 문단으로 요약하되, 기술적 용어는 쉽게 풀어서 설명}}
❌ {{date}}
✅ {{date:오늘 날짜를 YYYY-MM-DD 형식으로 기재}}
❌ {{author}}
✅ {{author:제1저자의 이름, 소속, 이메일을 한 줄로 작성}}
문서 메타정보:
{{version:문서 버전, 없으면 1.0}}
{{date:작성 날짜, YYYY-MM-DD 형식}}
{{author:작성자 이름}}
문서 내용:
{{title:문서 제목, 20자 이내}}
{{abstract:개요, 300자 이내}}
{{introduction:도입부, 배경과 목적을 설명}}
{{methodology:방법론, 연구/개발 방법 설명}}
{{results:결과 요약}}
{{conclusion:결론 및 향후 계획}}
프로젝트 정보:
{{project_name:프로젝트명}}
{{objective:프로젝트 목표를 3-5개 항목으로}}
{{timeline:주요 마일스톤과 일정}}
{{budget:예산 개요}}
이제 복잡한 {{#루프}}...{{/루프}} 태그를 직접 적을 필요가 없습니다. 점(.)을 활용한 직관적인 문법을 사용하세요.
Word에서 표를 만들고 각 칸에 {{표이름.항목이름}} 형식으로 적기만 하세요:
| 순번 | 과업 내용 | 담당자 |
|---|---|---|
{{tasks.no}} |
{{tasks.name}} |
{{tasks.owner}} |
시스템이 알아서 처리하는 마법:
tasks.으로 시작하는 태그들이 한 행에 있으면, 이 행 전체가 데이터 개수량만큼 자동으로 반복됩니다.- 사용자는
#이나/를 적지 않아도 됩니다. - AI가 데이터를 채워주면, 화면에서 엑셀처럼 표 형식으로 바로 수정할 수 있습니다.
표 전체에 대한 지침을 주고 싶다면 첫 번째 칸에 적어주세요:
{{tasks.no:업무 일정 5개를 추출해줘}}
| {{#tasks}}{{no}}{{/tasks}} | {{name}} | {{owner}} |
예전 방식은 Word에서 칸 너비를 많이 차지하고 복잡하지만, 기존 템플릿과의 호환성을 위해 여전히 작동은 합니다. 하지만 점(.) 문법이 훨씬 깔끔하고 강력합니다.
- Frontend: Next.js 16, React 19, TypeScript
- Styling: Tailwind CSS v4, shadcn/ui
- AI: OpenAI SDK (GPT-5), xAI SDK (Grok-4)
- 문서 처리: docxtemplater, pizzip, pdf-parse, docx
- CLI 번들링: esbuild (
apps/cli) - 모노레포: pnpm workspace (
packages/*,apps/*) - 테스트: vitest(단위), playwright(e2e)
- 개발 도구: nodemon, ESLint
filldoc/
├── app/ # 웹 UI (Next.js)
│ ├── api/
│ │ ├── extract-placeholders/ # 플레이스홀더 추출
│ │ ├── extract-text/ # Word/PDF 텍스트 추출
│ │ ├── fill-placeholders/ # AI 자동 채우기
│ │ ├── generate-document/ # 문서 생성
│ │ ├── generate-template/ # 예시 문서 → 템플릿 생성
│ │ └── templates/ # 서버 템플릿 목록/다운로드
│ ├── layout.tsx
│ └── page.tsx
├── components/ # 웹 UI 컴포넌트
│ ├── template-upload.tsx # 템플릿 업로드
│ ├── placeholder-list.tsx # 플레이스홀더 목록
│ ├── data-upload.tsx # 데이터 파일 업로드
│ ├── content-editor.tsx # 내용 편집
│ └── settings-dialog.tsx # API 키 설정
├── lib/server/ # 웹 어댑터 (packages/core를 얇게 감싸는 API 라우트용 함수)
├── packages/core/ # 문서 처리 핵심 로직 (환경 독립, 웹/CLI 공용 — @filldoc/core)
├── apps/cli/ # filldoc-* CLI (웹 의존성 없는 독립 배포 패키지)
├── .skills/filldoc/ # AI 에이전트용 스킬 문서 (SKILL.md)
├── template/ # 서버 템플릿 저장소 (.skills/filldoc/templates와 동일 폴더, 심볼릭 링크)
├── tests/ # vitest 단위 테스트 + playwright e2e
└── AGENTS.md # 에이전트 가이드라인
- 발급: https://platform.openai.com/api-keys
- 형식:
sk-로 시작 - 모델:
gpt-5.2(Responses API 사용)
- 발급: https://console.x.ai
- 형식:
xai-로 시작 - 모델:
grok-4-fast-non-reasoning(빠른 non-reasoning 모델)
⚠️ 보안: API 키는 브라우저의 localStorage에 저장되며, 서버로 전송되지 않습니다.
Incorrect API key provided
- Settings에서 API 키가 올바른 형식인지 확인 (sk- 또는 xai- 시작)
- 키를 다시 복사해서 붙여넣기
Failed to extract text from Word document
- .docx 형식인지 확인 (.doc 형식은 지원하지 않음)
- 파일이 암호화되지 않았는지 확인
Duplicate open tag, expected one open tag
- Word 문서에서
{{또는}}가 중복되지 않았는지 확인 - 플레이스홀더를 한 번에 입력 (복사-붙여넣기 권장)
# nodemon으로 개발 서버 실행 (자동 재시작)
npm run dev
# 일반 Next.js 개발 서버
npm run dev:next
# 빌드
npm run build
# 프로덕션 실행
npm run start
# 단위 테스트 (vitest)
npm run test
# E2E 테스트 (playwright)
npm run test:e2e"use client"지시어 사용 (클라이언트 컴포넌트)@/경로 별칭 사용typeoverinterface- 에러 로그는
[v0]접두사 사용
자세한 내용은 AGENTS.md 참조
MIT License
이슈와 PR은 언제나 환영합니다!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request