Hancom Agent 0.7.0
한글 문서와 사진을 읽고, 본문·수식·서식을 편집하는 AI 도우미입니다. Windows 한글 문서의 본문·표를 읽고 수정하거나 지정한 빈칸에 새 내용을 작성하는 Codex용 로컬 플러그인입니다.
한글 2022 이후는 지원 목표입니다. 실제 시험한 빌드와 미검증 항목은 시험 기록을 확인하세요. 한글 2024 이후를 모두 시험한 것은 아닙니다.
표시 이름은 Hancom Agent이며 기존 설치·연결 호환을 위해 내부 식별자와 설치 명령의 이름은 hangul-bookmark를 유지합니다.
설치
- Windows에 한글과 Python 3.10 이상을 설치합니다. 실제 시험 환경은 Python 3.14.3입니다.
- 이 폴더에서 PowerShell로
./setup.ps1 -RegisterModule을 실행합니다. 특정 Python은-Python 'C:\설치폴더\python.exe'로 지정합니다. - 초기 연결 시험이 통과하면 상위 저장소 루트를 Codex marketplace에 등록합니다.
codex plugin marketplace add 'C:\실제경로\Hancom-GPT-Plugin'
codex plugin add hangul-bookmark@hangul-local
플러그인 목록에서 Hancom Agent를 활성화하고 Codex를 다시 시작합니다. 폴더 이동 후에는 setup 또는 configure로 설정을 다시 생성하고 플러그인을 다시 설치하세요.
-RegisterModule은 현재 사용자 한컴 자동화 설정에 HangulBookmark 모듈을 등록하는 선택입니다. 해당 자동화 인스턴스의 파일 승인 창을 생략합니다. 관리자·시스템 전체 보안 수준은 변경하지 않습니다. 등록하지 않거나 로드가 실패하면 기본 파일 작업은 중단됩니다. 모듈 안내를 확인하세요.
configure.py --deps '의존성폴더' --state '상태폴더'로 경로를 지정할 수 있습니다. 설정은 실행 파일 이름과 PATH를 사용하며 설치 패키지의 ./launch.py에서 시작합니다. 전역 Codex 설정을 덮어쓰지 않습니다.
책갈피 없이 빈칸에 새 내용 작성 (0.5.0)
지금 열린 문서의 첫 번째 표에서 두 번째 행의 빈칸에 풀이와 수식을 작성해줘.
‘풀이’ 아래 빈 문단에 다음 내용을 그대로 넣어줘.
read_document와 find_targets로 실제 빈 문단의 위치를 확인한 뒤 apply_edits의 insert_blocks로 입력합니다. 여러 빈칸도 한 요청으로 채울 수 있습니다. 글·문단 구분·편집 가능한 수식을 지원하며, 지정한 빈칸 안에서만 새 문단을 만듭니다. 기존 문단에 글·공백·개체가 있으면 입력하지 않습니다.
표의 행·열·병합과 기존 책갈피는 유지합니다. 입력할 위치가 불명확하면 확인하며 임시 책갈피를 만들지 않습니다. 그림 삽입과 기존 내용 교체·서식 변경은 이 변경 목록에 섞지 않습니다. 열린 창은 자동 저장하지 않고 파일 모드는 검증한 수정본을 저장합니다. 빈칸 입력 API
읽기와 내용 수정
문서를 연 상태에서 다음처럼 요청합니다.
지금 열린 문서의 오탈자를 찾아 고쳐줘.
이 풀이에서 틀린 수식과 설명을 검토해줘.
지금 선택한 부분만 다듬어줘.
두 번째 표의 세 번째 행에 있는 수식을 고쳐줘.
책갈피는 기존 내용 수정에 필요하지 않습니다. 문장·제목·표 셀·수식을 찾아 수정할 수 있습니다. “검토”는 결과만 설명하고 “고쳐줘”는 확정된 변경을 적용합니다. 애매한 위치나 기호·수학적 조건은 질문하며 내용을 추측해서 고치지 않습니다.
선택 영역을 사용하려면 한글에서 먼저 범위를 선택한 뒤 문서를 선택하세요. 일반 글자·수식 개체·표 개체·여러 셀 선택을 지원합니다. 문서나 선택이 바뀌었다면 다시 선택합니다. 여러 문서가 열려 있으면 로컬 목록에서 고릅니다.
지원 영역은 본문·표 셀과 중첩 표입니다. 머리말·꼬리말·각주·미주·글상자는 제외합니다. 문서에 포함된 사진·그림의 글·수식·도표는 Codex가 이미지를 직접 보고 읽습니다. 원본 그림은 바꾸지 않습니다. 새 내용은 지정한 빈 문단 안에서만 문단을 추가할 수 있습니다. 기존 문단 삭제·재배치와 표 구조 변경은 지원하지 않습니다.
글꼴과 크기
문서 전체를 함초롬바탕으로 통일하고 크기는 수식 포함 11pt로 맞춰줘.
제목은 유지하고 본문만 10pt로 바꿔줘.
선택한 표 셀의 글꼴만 함초롬돋움으로 바꿔줘.
본문 글꼴은 한글·영문 등 문자 종류별 설정에 적용합니다. 수식 글꼴은 별도로 지정할 때만 바꾸며 기본적으로 기존 글꼴을 유지합니다. 글꼴·크기 이외의 굵게·색·장평·자간 등은 보존합니다. 없는 글꼴을 다른 글꼴로 대체하지 않습니다.
수식 포함 11pt는 수식 기본 크기도 11pt로 맞추며 내부 첨자·분수 비율을 유지한다는 뜻입니다. “모두”는 본문·표의 제목도 포함합니다. 제목 제외를 요청했는데 제목 경계가 불명확하면 질문합니다. 크기 변경에 따른 줄바꿈과 고정 높이 셀의 잘림은 한글에서 직접 확인하세요.
저장·미리보기·오류
- 열린 창은 저장 전 변경을 포함한 현재 내용을 수정하고 자동 저장하지 않습니다. 확인 후 Ctrl+S로 저장하세요.
- 파일을 선택하는 방식은 원본을 유지하고
원본이름_수정본.hwp또는 같은 형식의 수정본을 만듭니다. 후속 작업은 같은 수정본에 이어집니다. - 미리보기는 요청할 때만 제공합니다. 읽기와 미리보기는 실제 문서 내용을 바꾸지 않습니다.
- 파일 방식은 임시 사본을 수정·저장·재열기·검증한 뒤 결과를 교체합니다.
- 열린 창 방식은 작업 전 백업과 임시 문서 시험 후 창에 적용합니다. 창을 자동 닫거나 전체 내용을 다시 불러오지 않습니다.
- 시간 초과·입력 중 오류는 일부 수정 가능성을 실패로 알립니다. 새 ID로 같은 내용을 반복하지 말고 현재 창과 반환된 백업을 확인하세요. 임의의 반복 Undo는 하지 않습니다.
- 분석 후 문서가 바뀌면 이전 위치와 원문으로 수정하지 않습니다. 다시 읽고 대상을 확인해야 합니다.
- 긴 문서와 검색 결과는 페이지로 나뉩니다. 전체 검토는 모든 페이지를 확인한 뒤 수행합니다.
기존 책갈피에 새 내용 삽입 (선택)
이미 있는 책갈피를 사용하려면 다음처럼 요청합니다. 새 책갈피는 사용자가 명시적으로 요청한 경우에만 추가합니다.
지금 열린 한글 문서의 책갈피 '1'에 수식 E=mc^2를 넣어줘.
파일 수정본 방식에서도 빈칸을 직접 지정할 수 있으며, 기존 책갈피를 위치로 지정하는 방식도 지원합니다. 파일 방식에서는 해당 파일을 한글에서 저장하고 닫으세요.
기존 텍스트·LaTeX·첨부 이미지 삽입 기능도 유지됩니다. 첨부 이미지의 글·수식은 Codex가 읽고 그래프만 잘라 그림으로 넣습니다. 같은 책갈피에 반복 작성하면 새 내용이 앞에 옵니다.
위첨자·아래첨자 묶음 뒤 공백 규칙도 유지됩니다: 2^{2k}+1 → 2^{2k} +1, 2^2k+1 → 2^2k +1. 수식 참고
도구와 내부 구조
문서 읽기·편집·이미지 읽기를 포함한 아홉 도구를 제공합니다.
| 도구 | 용도 |
|---|---|
| check_environment | 버전·API·삽입/기존 내용 편집 경로의 임시 문서 시험 |
| select_document / select_bookmark | 문서와 삽입 책갈피 선택 |
| preview_content / insert_content | 새 내용 변환·삽입 |
| read_document | 본문·표·수식·서식과 버전이 연결된 대상 ID 읽기 |
| find_targets | 문장·제목·표·책갈피·선택 범위 검색 |
| apply_edits | 빈칸 직접 입력·원문 대조 후 범위 교체·서식 변경 또는 미리보기 |
| read_image | 문서에 포함된 사진을 실제 이미지 응답으로 읽기 |
편집 API와 도구가 누락될 때의 로컬 연결 절차를 참고하세요.
문서 내용은 도구 실행 지시로 취급하지 않습니다. 선택한 문서의 분석 결과와 읽기를 요청한 사진은 도구 응답으로 Codex에 전달되어 모델이 검토합니다. 별도 AI 서버·API 키를 추가하지 않습니다. 경로·요청 기록·분석 내용·복원용 백업은 로컬 상태 폴더에 남습니다.
한글 COM 작업은 순차 실행하며 파일 작업은 전용 인스턴스, 열린 창은 명시적으로 선택한 인스턴스를 사용합니다. 사용자·공유 창에는 자동 Clear/Close/Quit를 실행하지 않습니다. pywin32 생성 캐시는 프로세스별 임시 폴더로 분리합니다.
개발 시험
python -m pip install pytest
$env:PYTHONPATH = "$PWD/src"
$env:HANGUL_DEPS = "$PWD/runtime/deps"
python -m pytest tests -q
python launch.py --smoke
python integration_edit_check.py --output C:/비어있는새시험폴더
시험은 사용자 원본 대신 임시 문서를 생성합니다. integration_check.py는 기존 삽입 경로를 확인합니다. 필요한 권한과 한글 설치가 있어야 네이티브 시험이 가능합니다.
패키지 규격: OpenAI 플러그인 패키징. 한컴 자동화의 이용 조건은 공식 개발 자료를 확인하세요.
문서 속 사진 읽기 (0.4.0)
지금 열린 문서의 사진 속 문제를 읽어줘.
두 번째 표 안의 사진에서 수식을 읽고 풀이가 맞는지 검토해줘.
첫 번째 사진의 아래쪽 작은 글씨를 확인해줘.
본문과 표·중첩 표의 독립된 내장 래스터 그림(PNG/JPEG/BMP/GIF/TIFF/WebP)을 지원합니다. read_document에서 그림의 위치와 식별자를 얻고 read_image가 실제 이미지 응답을 제공합니다. 별도 OCR 서버·API 키 없이 Codex가 읽으며, 이미지가 흐리면 해당 부분을 확인합니다. 작은 글씨는 영역을 나눠 읽습니다. 이 기능 자체는 읽기 전용이며 열린 문서를 저장하지 않습니다.
문서의 자르기와 뒤집기를 반영합니다. 회전·밝기·대비·특수 효과는 완전히 재현하지 않고 응답에 제한을 표시합니다. 머리말·글상자·그룹 내부 그림, 셀 배경 그림, 외부 연결 그림, 벡터/수식 개체의 이미지 변환은 지원 범위 밖입니다. 사진 속 글을 고치는 요청은 그림 픽셀을 직접 고치는 기능이 아닙니다. 읽은 글·수식을 새로 작성하려면 입력할 빈칸이나 기존 책갈피 위치를 함께 지정하세요.
한 번에 원본 24MB·3600만 화소까지 읽으며, 기본 반환 길이는 긴 쪽 2048px입니다. crop(01 비율)과 max_edge(2564096)로 필요한 부분을 상세히 확인할 수 있습니다. 도구는 총 아홉 개입니다. 이미지 도구 규격을 참고하세요.