docs: Initial project scaffold with AI agent guide
- AGENT_GUIDE.md: AI 에이전트 사용 스펙 (CLI, JSON 출력, 페이지 타입 정의) - CLAUDE.md: 프로젝트 개요 및 개발 원칙 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
minsung
201
AGENT_GUIDE.md
Normal file
201
AGENT_GUIDE.md
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
# doc2md — AI Agent Usage Guide
|
||||||
|
|
||||||
|
AI 에이전트가 이 도구를 사용하는 방법을 정의한다.
|
||||||
|
인간용 UI는 없음. 모든 인터페이스는 에이전트 친화적으로 설계됨.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 목적
|
||||||
|
|
||||||
|
`raw/` 폴더의 바이너리 문서(PDF, HWP, HWPX, HML, HTML)를 Markdown으로 변환한다.
|
||||||
|
변환된 `.md` 파일은 에이전트가 직접 읽어 위키 컴파일 등 후속 작업에 사용한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. CLI 인터페이스
|
||||||
|
|
||||||
|
### 기본 사용법
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 단일 파일 변환
|
||||||
|
python convert.py <input_file> -o <output_dir>
|
||||||
|
|
||||||
|
# 결과를 JSON으로 받기 (에이전트 권장)
|
||||||
|
python convert.py <input_file> -o <output_dir> --json
|
||||||
|
|
||||||
|
# 폴더 일괄 변환
|
||||||
|
python convert.py --scan <input_dir> -o <output_dir> --json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 환경변수
|
||||||
|
|
||||||
|
```bash
|
||||||
|
VENV_PYTHON=D:\MYCLAUDE_PROJECT\doc2md\.venv\Scripts\python.exe
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. JSON 출력 스펙 (에이전트가 파싱하는 형식)
|
||||||
|
|
||||||
|
### 성공 (단일 파일)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"input": "raw/report.pdf",
|
||||||
|
"output": "raw/report.md",
|
||||||
|
"format": "pdf",
|
||||||
|
"pages": [
|
||||||
|
{ "n": 1, "type": "text" },
|
||||||
|
{ "n": 2, "type": "diagram", "image": "raw/report_images/page_2.png" },
|
||||||
|
{ "n": 3, "type": "text-with-photo", "images": ["raw/report_images/fig_3_1.png"] }
|
||||||
|
],
|
||||||
|
"has_diagrams": true,
|
||||||
|
"diagram_pages": [2],
|
||||||
|
"images": ["raw/report_images/page_2.png", "raw/report_images/fig_3_1.png"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 성공 (폴더 스캔)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"total": 5,
|
||||||
|
"converted": 4,
|
||||||
|
"skipped": 1,
|
||||||
|
"failed": 0,
|
||||||
|
"results": [
|
||||||
|
{ "input": "raw/doc1.hwp", "output": "raw/doc1.md", "status": "ok" },
|
||||||
|
{ "input": "raw/doc2.pdf", "output": "raw/doc2.md", "status": "ok", "has_diagrams": true, "diagram_pages": [3, 7] },
|
||||||
|
{ "input": "raw/doc3.md", "output": null, "status": "skipped", "reason": "already_md" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 실패
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "error",
|
||||||
|
"input": "raw/broken.hwp",
|
||||||
|
"error": "COM timeout — pyhwp fallback also failed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Exit Codes
|
||||||
|
|
||||||
|
| 코드 | 의미 |
|
||||||
|
|------|------|
|
||||||
|
| `0` | 완전 성공 |
|
||||||
|
| `1` | 부분 성공 (일부 파일 실패, 나머지 성공) |
|
||||||
|
| `2` | 완전 실패 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 페이지 타입 정의 (PDF 전용)
|
||||||
|
|
||||||
|
| 타입 | 설명 | 에이전트 처리 방법 |
|
||||||
|
|------|------|--------------------|
|
||||||
|
| `text` | 텍스트 위주 페이지 | MD 텍스트 직접 읽기 |
|
||||||
|
| `text-with-photo` | 텍스트 + 사진 | MD 텍스트 읽기 + 이미지 참조 |
|
||||||
|
| `diagram` | 다이어그램/도면 (벡터 or 특수 래스터) | **이미지 파일을 Claude Vision으로 처리** |
|
||||||
|
| `image-heavy` | 텍스트 거의 없고 이미지가 대부분 | **이미지 파일을 Claude Vision으로 처리** |
|
||||||
|
|
||||||
|
> **에이전트 필수 동작**: `has_diagrams: true` 이면 `diagram_pages` 의 이미지를
|
||||||
|
> Claude Vision (Read 도구로 이미지 파일 직접 읽기)으로 추가 처리할 것.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 파일 형식별 변환 전략
|
||||||
|
|
||||||
|
### PDF
|
||||||
|
|
||||||
|
1. 각 페이지를 분류 (`text` / `text-with-photo` / `diagram` / `image-heavy`)
|
||||||
|
2. 텍스트 페이지 → marker-pdf로 텍스트 추출
|
||||||
|
3. 다이어그램 페이지 → 페이지 전체를 PNG 렌더링, MD에 이미지 링크 삽입
|
||||||
|
4. 모든 결과를 하나의 `.md` 파일로 합산
|
||||||
|
|
||||||
|
### HWP
|
||||||
|
|
||||||
|
1. 한컴오피스 COM 자동화 시도 (Windows + 한컴오피스 설치 필요)
|
||||||
|
2. 실패 시 pyhwp 폴백 (크로스플랫폼)
|
||||||
|
|
||||||
|
### HWPX
|
||||||
|
|
||||||
|
- ZIP 압축 해제 → XML 직접 파싱
|
||||||
|
- 이미지 추출 포함
|
||||||
|
|
||||||
|
### HML
|
||||||
|
|
||||||
|
- XML 직접 파싱
|
||||||
|
- 병합 셀 테이블은 HTML `<table>` 형식으로 보존 (colspan/rowspan 유지)
|
||||||
|
|
||||||
|
### HTML / HTM
|
||||||
|
|
||||||
|
- html2text (`body_width=0` — 줄바꿈 없음)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 에이전트 권장 사용 패턴
|
||||||
|
|
||||||
|
### ParaWiki ingest-raw 통합 예시
|
||||||
|
|
||||||
|
```python
|
||||||
|
import subprocess, json
|
||||||
|
|
||||||
|
result = subprocess.run(
|
||||||
|
[VENV_PYTHON, 'convert.py', str(src), '-o', str(src.parent), '--json'],
|
||||||
|
cwd=CONVERTER_PATH, capture_output=True, text=True
|
||||||
|
)
|
||||||
|
data = json.loads(result.stdout)
|
||||||
|
|
||||||
|
if data['status'] == 'ok' and data.get('has_diagrams'):
|
||||||
|
# diagram_pages의 이미지를 Claude Vision으로 추가 처리
|
||||||
|
for img_path in data['images']:
|
||||||
|
if 'page_' in img_path: # diagram 페이지 이미지
|
||||||
|
vision_description = claude_read_image(img_path)
|
||||||
|
append_to_md(data['output'], vision_description)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 환경 설정
|
||||||
|
|
||||||
|
### 요구사항
|
||||||
|
|
||||||
|
```
|
||||||
|
Python 3.11+
|
||||||
|
marker-pdf # PDF 텍스트 추출
|
||||||
|
PyMuPDF (fitz) # PDF 페이지 분석 + 렌더링
|
||||||
|
Pillow # 이미지 처리 (다이어그램 감지)
|
||||||
|
beautifulsoup4 # HTML 파싱
|
||||||
|
lxml # XML 파싱 (HML, HWPX)
|
||||||
|
html2text # HTML → MD
|
||||||
|
pyhwp # HWP 폴백 변환
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows 전용 (선택)
|
||||||
|
|
||||||
|
```
|
||||||
|
pywin32 # HWP COM 자동화 (한컴오피스 설치 시)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 스킵 조건
|
||||||
|
|
||||||
|
에이전트가 `--scan` 모드로 실행 시, 다음 파일은 자동으로 건너뜀:
|
||||||
|
- 이미 `.md` 파일이 같은 경로에 존재
|
||||||
|
- 파일 크기 0바이트
|
||||||
|
- `README.md`, `CLAUDE.md`, `AGENT_GUIDE.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 에이전트에게 보내는 메시지
|
||||||
|
|
||||||
|
이 도구는 **변환만** 한다. 변환된 MD의 의미 해석, 위키 구조화, 다이어그램 Vision 처리는
|
||||||
|
에이전트(Claude)의 역할이다. `has_diagrams: true` 결과를 받았을 때 반드시
|
||||||
|
해당 이미지 파일을 직접 읽어 내용을 파악하라.
|
||||||
36
CLAUDE.md
Normal file
36
CLAUDE.md
Normal file
@@ -0,0 +1,36 @@
|
|||||||
|
# doc2md
|
||||||
|
|
||||||
|
바이너리 문서(PDF/HWP/HWPX/HML/HTML)를 Markdown으로 변환하는 도구.
|
||||||
|
AI 에이전트(Claude Code)가 ParaWiki ingest-raw에서 호출한다.
|
||||||
|
|
||||||
|
## 필수 읽기
|
||||||
|
|
||||||
|
**사용법은 [AGENT_GUIDE.md](AGENT_GUIDE.md) 를 먼저 읽어라.**
|
||||||
|
|
||||||
|
## 프로젝트 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
doc2md/
|
||||||
|
├── convert.py # 통합 CLI 진입점 (에이전트가 직접 호출)
|
||||||
|
├── converters/
|
||||||
|
│ ├── pdf.py # PDF → MD (페이지별 분류 + 라우팅)
|
||||||
|
│ ├── hwp.py # HWP → MD (COM + pyhwp fallback)
|
||||||
|
│ ├── hwpx.py # HWPX → MD (ZIP+XML 파싱)
|
||||||
|
│ ├── hml.py # HML → MD (XML 파싱)
|
||||||
|
│ └── html.py # HTML → MD (html2text)
|
||||||
|
├── AGENT_GUIDE.md # AI 에이전트 사용 가이드 (핵심 문서)
|
||||||
|
└── requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## 핵심 원칙
|
||||||
|
|
||||||
|
1. **비대화형**: 절대 사용자 입력 대기하지 않음
|
||||||
|
2. **JSON 출력**: `--json` 플래그 시 파싱 가능한 JSON만 stdout 출력
|
||||||
|
3. **멱등성**: 이미 변환된 파일은 건너뜀 (기본 동작)
|
||||||
|
4. **다이어그램 플래그**: PDF에 다이어그램 페이지 존재 시 `has_diagrams: true` 반환
|
||||||
|
|
||||||
|
## 개발 시 주의사항
|
||||||
|
|
||||||
|
- `convert.py` CLI 인터페이스는 AGENT_GUIDE.md 스펙과 항상 일치해야 함
|
||||||
|
- JSON 출력 구조 변경 시 AGENT_GUIDE.md 동시 업데이트 필수
|
||||||
|
- `converters/` 각 파일은 단독 임포트 가능해야 함 (순환 의존 금지)
|
||||||
Reference in New Issue
Block a user