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` 결과를 받았을 때 반드시
|
||||
해당 이미지 파일을 직접 읽어 내용을 파악하라.
|
||||
Reference in New Issue
Block a user