Hangul Bookmark Writer

Windows에 설치된 한글의 전용 자동화 창을 사용해 사용자가 지정한 책갈피에 원문과 편집 가능한 수식, 그림을 작성한다. 최초에는 _수정본 파일을 만들고 이후 같은 수정본에 계속 저장한다. 원본은 덮어쓰지 않는다.

현재 열린 문서에 직접 작성하는 방식도 지원한다. 기존 창의 저장 전 변경을 유지하며 책갈피에 입력한다. 이 방식은 자동 저장하지 않으며, 사용자가 한글에서 직접 저장한다.

2022 이후는 지원 목표다. 실제 시험한 빌드 및 미검증 항목은 시험 기록을 확인한다. 새 버전은 기능 시험이 통과해야 사용한다. 현재 시험 PC의 12.0.0.535에서는 보안 모듈 재등록 후 승인 창 없이 HWP/HWPX 작성·저장·재열기를 확인했다. 다른 PC에서도 설치 후 실제 연결 시험이 통과해야 한다.

설치

Windows에 한글 2022 이상과 Python 3.10 이상을 설치한다. 실제 개발 시험은 Python 3.14에서 수행했다.
압축을 풀어 폴더를 유지한다. 폴더 경로에는 일반 Windows 경로를 사용한다.
이 폴더에서 PowerShell을 열어 ./setup.ps1을 실행한다. 파일 접근 승인 창을 생략하는 한컴 보안 모듈을 사용하려면 내용을 확인하고 ./setup.ps1 -RegisterModule을 실행한다. 이 선택은 현재 사용자 레지스트리에 HangulBookmark 값만 등록한다. 관리자 설정은 변경하지 않는다. 모듈이 로드되지 않으면 파일 작업을 시작하지 않고 오류로 반환한다.
초기 연결 시험이 성공하면 Codex에 로컬 marketplace를 등록한다. 이 패키지의 상위 폴더에는 .agents/plugins/marketplace.json이 포함되어 있다.

codex plugin marketplace add "C:\실제\압축을푼\패키지폴더"
codex plugin add hangul-bookmark@hangul-local

Codex 앱의 플러그인 목록에서 활성화하고 새 대화에서 사용한다. 플러그인 추가 명령이나 로컬 marketplace 화면은 설치된 앱 버전에 따라 달라질 수 있다. 명령의 안내를 확인한다. 등록 전 setup.ps1이 실제 Python과 플러그인 위치를 .mcp.json/mcp.json에 기록한다. 폴더 이동 후에는 setup.ps1을 다시 실행한다. 앱의 보안 승인은 앱 설정을 따른다.

별도 MCP 연결을 원하는 경우 setup.ps1이 만든 .mcp.json의 command/args/env를 로컬 stdio MCP 설정으로 사용한다. 이 파일은 사용자의 Codex 설정을 자동 덮어쓰지 않는다.

사용

새 대화에서 도구가 없다고 나오는 경우: 0.2.1은 Codex가 거부하던 절대 실행 파일 경로를 수정했다. 플러그인을 업데이트하고 Codex를 다시 연 뒤 새 대화에서 요청한다. 전용 도구가 여전히 제공되지 않으면 스킬에 포함된 로컬 MCP 브리지로 같은 연결을 검사할 수 있다. 연결 시험 결과를 확인하기 전에는 작성 완료로 표시하지 않는다.

한글에서 원본 문서의 본문 또는 표 셀에 책갈피를 미리 넣고 저장한 뒤 문서를 닫는다. 누름틀과 책갈피는 다르다.

위 단계는 파일 수정본 방식이다. 열린 창에 직접 작성하려면 문서를 닫지 않고 “현재 열린 한글 문서의 책갈피 풀이 1에 이 내용을 작성해줘”라고 요청한다. 여러 문서가 열렸으면 로컬 목록에서 대상을 고른다. 아직 파일로 저장하지 않은 새 문서도 책갈피가 있으면 선택할 수 있다. 작성 후 Ctrl+S로 직접 저장한다. 작업 중에는 선택한 문서에서 동시에 편집하지 않는다.

대화에서 “한글 파일 선택해줘”라고 요청하면 PC의 파일 선택 창이 열린다. 책갈피 목록 창에서 입력 위치를 선택하거나 “책갈피 이름은 문제1”처럼 직접 지정한다. 파일·책갈피·출력 경로가 표시된다.

“다음 내용을 그대로 작성해줘”와 함께 글·LaTeX·이미지를 전달한다. 글과 수식은 모델이 원문대로 블록을 만들고 그래프만 그림으로 삽입한다. 이미지 판독은 Codex가 수행하며 서버에 OCR 모델은 포함하지 않는다. 읽을 수 없는 기호는 질문하고 저장하지 않는다. 미리보기는 요청할 때만 제공한다.

작업 완료 후 수정본 경로와 본문 조각·문단 구분·수식·그림 수를 알려준다. 같은 대화·문서 식별자로 다시 작성하면 수정본의 같은 책갈피 시작에 삽입되어 새 내용이 앞에 온다. 파일을 다시 선택하면 새 수정본을 만든다.

저장·복구와 제한

열린 창 방식은 현재 메모리 내용을 네이티브 HWP 사본으로 보관하고 임시 창에서 작성·저장·재열기를 먼저 시험한 뒤 기존 창에 입력한다. 사용자 창은 파일로 다시 열거나 전체 교체하지 않는다. 복원용 사본은 상태 폴더의 live-backups에 남으며 기존 파일과 동일하게 민감한 내용을 포함할 수 있다.
열린 창에서 입력 중 오류가 발생하면 부분 입력 가능성을 오류로 알리고 재시도를 막는다. 창을 자동 닫거나 사용자의 이전 입력까지 Undo하지 않는다. 복원용 사본으로 이전 내용을 확인할 수 있다. 시간 초과 후에는 이후 입력을 중단하도록 요청하며 이미 진행 중인 COM 호출은 즉시 취소할 수 없다.
열린 창의 본문·수식은 메모리에서 작성한다. 그림의 파일 가져오기는 해당 창의 보안 모듈 로드가 확인되어야 시작한다. 읽기 전용·양식·배포용 문서는 직접 작성하지 않는다.
작업은 수정본과 같은 디스크의 임시 사본에서 수행한다. 저장 후 다시 열어 책갈피 위치·글/수식/그림 순서·표 구조를 비교한 뒤 교체한다.
외부 파일 변경이나 파일 잠금은 거부한다. 한글에서 수정본을 편집할 때는 먼저 저장·닫고 플러그인에서 다시 선택한다.
SQLite 요청 기록이 재전송·프로그램 재시작 후 중복 작성을 방지한다. 동일 요청에는 동일 ID를 유지한다. 저장 직후 중단은 출력 해시와 기록으로 복구한다. 불명확한 중단은 성공으로 처리하지 않는다.
Windows 교체 단계에는 파일 쓰기 잠금을 짧게 해제해야 하므로, 검사 직후 외부 프로그램이 교체하는 극히 짧은 경쟁 구간은 완전히 제거할 수 없다. 작성 중 다른 프로그램에서 같은 파일을 편집하지 않는다.
상태 기록은 %LOCALAPPDATA%/HangulBookmark에 저장한다. 문서 경로·해시·요청 결과를 포함한다. stdout은 MCP 전용이다. 네트워크 전송이나 임의 코드 실행 도구는 없다.
기본 임시 폴더에서 저장이 실패하는 실행 환경은 python configure.py --deps 실제의존성폴더 --state 쓰기가능한작업폴더로 MCP 상태·임시 폴더를 지정할 수 있다. 변경 후 플러그인 연결을 다시 시작하고 해당 폴더에서 smoke 시험을 실행한다.
글상자·머리말·꼬리말·각주·미주 책갈피, PDF 입력, 기존 내용 교체, 그래프 도형 재구성은 제외한다.
지원하지 않는 LaTeX 명령은 실패한다. 수식 참고를 확인한다. 문법 구조와 개체 스크립트 검사만으로 모든 수식의 표시 정확성을 보증할 수 없다.
표의 고정 높이 잘림과 복잡한 페이지 레이아웃은 시각 확인이 필요하다. 경고를 결과에 반환한다. 글꼴 대체도 설치된 폰트에 따른다.
한글 자동화의 상용 배포는 한컴 자동화 안내의 이용 조건을 확인한다.

개발 시험

python -m pip install pytest
$env:PYTHONPATH = "$PWD/src"
$env:HANGUL_DEPS = "$PWD/runtime/deps"
python -m pytest tests -q
python launch.py --smoke

직접 승인하며 진단하려는 경우에만 $env:HANGUL_ALLOW_MANUAL_APPROVAL='1' 후 python launch.py --smoke 또는 python integration_check.py --output C:/비어있는/시험폴더를 실행한다. 이 모드에서는 승인 창이 나타날 수 있다. 기본 MCP 설정은 이 옵션을 켜지 않는다.

코드 구조는 content/latex(입력 검사), service(파일·요청 트랜잭션), backend(전용 COM STA 프로세스), live/live_worker(명시적으로 선택한 열린 문서의 지속 STA 연결), server(다섯 MCP 도구)로 나뉜다. 요청은 직렬화한다. 파일 방식은 DispatchEx로 새 COM 객체를 만들고, 열린 창 방식은 선택한 ROT·프로세스 생성 시각·문서 ID·파일 연결을 확인한다. 공유 프로세스나 사용자 창에는 자동 Clear/Close/Quit를 실행하지 않는다.

패키지 규격 출처: OpenAI 플러그인 패키징. 설치 단계의 네트워크는 Python 라이브러리 다운로드에만 필요하다. 모델 이용은 사용자의 Codex 연결을 따른다.