Gpt_Codex_HWP

Codex와 Claude Code에서 한글 HWP를 읽고, 검증 가능한 HWPX를 만드는 로컬 문서 플러그인

한국어 · English · 결과 보기 · 빠른 설치 · Claude Code · 지원 범위 · 보안

개요

Gpt_Codex_HWP는 Codex와 Claude Code에서 한국어 HWP/HWPX 문서를 읽고, 만들고, 수정하고, 검증하고, 미리 보는 로컬 플러그인입니다. HWPX를 정식 쓰기 형식으로 사용하고 기존 HWPX의 원시 ZIP/XML 구조를 가능한 한 보존합니다. 바이너리 HWP는 형식 감지·읽기·미리보기 전용이며, 읽은 내용은 새 HWPX로 저장합니다.

v0.3.5 원본 실패 보존·릴리스 검증

플러그인 identity는 0.3.5+codex.20261021184753, Claude Code 캐시는 0.3.5-codex.20261021184753입니다. identity 자체는 게시 증거가 아닙니다. 설치 전에 v0.3.5 릴리즈의 정확한 불변 태그 SHA, 자체 전체 태그 게이트·동일 실행 attestation 성공과 원본 ZIP·SPDX·provenance·SHA256SUMS 4개 공개 자산을 실제로 확인하십시오.

v0.3.4 원본 전체 태그 게이트는 초기 10 MiB smoke를 통과한 뒤 node-tests의 replacement-ref 숨겨진 비공개 트리 보안 사례에서 WINDOWS_REPOSITORY_TEST_CASE case=pc17 status=failed로 실패했습니다. 릴리스 산출물·attestation·Release는 생성되지 않았습니다. 후속 계측 전체 파일 Windows 진단은 모든 replacement 단계를 통과하고 historyFailures가 없었지만, 원본 게이트 복구나 원인 증명은 아닙니다. 원본의 정확한 원인은 여전히 미확정이며 과거 태그와 실행은 보존합니다.

v0.3.5는 설정 코드 순서에 따른 뒤쪽 오류 대신 실제 TAP 순서의 첫 allowlisted 오류를 보존합니다. 실제 자식 회귀 검사는 수정 전 실패·수정 후 통과했고, 실패한 자식·파일 상태는 계속 실패입니다. history scanner의 기존 엄격한 프로세스 실패 observer를 bounded batch로 전달하며, pc17의 보안 발견 두 assertion과 원본 예외 cause를 유지한 채 제한된 pc17-replace-scan 단계 또는 기존 안전한 프로세스 코드를 보고합니다. 실제 Git cat-file 명령 실패 smoke는 전후 모두 exit 1을 유지하면서 거친 pc17 대신 pc17-replace-scan을 보존했습니다. 이는 증거 유실 수정이지 원본 native/pc17 원인 수정이 아닙니다. 네이티브 수집기·권한·identity/RSS·작업량·실행/캡처/정리 제한과 실패 상태는 그대로이며 native/RSS/정리 증거를 합성하지 않습니다.

v0.3.3의 Linux reparenting 수정도 유지합니다. 정상 부모 변경은 identity 변경이 아니며 같은 PID·프로세스 그룹·시작 시각의 실제 RSS를 유지합니다. 그룹·시작 identity 변경과 RSS 누락은 계속 거부하고 측정 횟수·간격·타임아웃·독립적인 그룹 정리 증명은 유지합니다. 실제 Linux reparenting의 수정 전 거부·수정 후 실제 RSS 일치는 과거 개별 CI 실패의 원인을 증명하지 않습니다. 중복 MCP 도구 이름 literal과 단순 not-throw wrapper 대신 실제 초기화 서버의 canonical 전체 schema catalog·버전·stderr 검사를 유지합니다.

릴리스 생성기·검증기·플랫폼 영수증은 파일별 Git subprocess 대신 기존 bounded blob batch 규약을 공유합니다. 원본 테스트 제한 초과 때 이미 수집한 TAP 진행과 exit/close 상태를 보존하지만, TAP 통과나 정리 도구의 반환값만으로 제한 초과·정리 실패를 성공 처리하지 않습니다. 제한과 비공개 내용 비노출 조건은 유지합니다.

v0.3.1 보안 업데이트

v0.3.1은 소스와 생성 런타임의 markdown-it을 14.3.1에서 14.3.3으로 갱신해 GHSA-gfr2-rv44-r23c, GHSA-r7fv-28h4-cvq7, GHSA-vfgh-jcmw-g37q에 대응합니다. 기존 14.x API와 파서 옵션을 유지하며 새 기능, PDF 지원이나 MCP 도구를 추가하지 않습니다. 플러그인 identity는 0.3.1+codex.20261021043114, Claude Code 캐시 디렉터리는 0.3.1-codex.20261021043114입니다. 게시에는 불변 태그의 전체 릴리즈 게이트와 attestation 성공이 필요하며, 실제 검증·게시 상태는 GitHub 릴리즈와 연결된 워크플로에서 확인하십시오.

v0.3.0 릴리즈

v0.3.0은 같은 플러그인을 Codex와 Claude Code에서 함께 쓰도록 지원을 넓혔습니다. CI 검증 문서 크기를 10 MiB로 낮추고, 공문서 초안을 점검하는 선택 플러그인 korean-official-doc을 추가했으며, 단어 안 밑줄이 사라지던 HWPX 생성 문제와 경로·쓰기 실패 처리를 고쳤습니다. UNC 경로 거부, Python 3.10 요구, 미리보기 오류 코드처럼 0.2.x에서 바뀐 동작은 릴리즈 노트에 정리했습니다. HWP 읽기 전용·HWPX 쓰기 정책, 명시적 런타임 설치와 one-shot 도구 9개는 유지합니다. 개발과 실제 문서 검증은 Windows x64에서 수행했습니다. 호스팅 CI(Windows x64·macOS arm64·Linux lifecycle)는 v0.3.0 릴리스 PR 커밋 기준 기록이며, 그 이후 HEAD의 macOS 결과는 해당 커밋의 영수증으로 따로 확인해야 합니다. 실제 Mac 기기의 Codex Desktop·Claude Code·한컴오피스 한글은 아직 검증하지 않았습니다.

이전 릴리즈

v0.3.5 이전 공개 릴리스는 최신 순으로 v0.3.1, v0.3.0, v0.2.7, v0.2.5입니다. v0.2.7은 의존성 감사 이슈 #18의 패키지를 갱신했습니다. v0.3.4, v0.3.3, v0.3.2, v0.2.3, v0.2.4, v0.2.6은 불변 미게시 태그이며 GitHub Release와 공개 Release 자산이 없습니다. v0.3.3 원본 main native 실행은 windows-helper-sampling, 태그 full node 실행은 mcp-smoke에서 실패했습니다. 정확한 원인은 알 수 없고 후속 native·변경 없는 MCP 성공은 원본 실패를 복구하지 않습니다. 실패 태그와 원본 실행은 변경하지 않습니다. v0.2.2는 HWP 읽기 전용·HWPX 쓰기, 기본 one-shot 실행과 100 MiB CI 검증 범위를 도입했습니다. 자세한 이력은 CHANGELOG와 한국어 릴리즈 노트에서 확인할 수 있습니다.

기능

• Markdown에서 보고서, 계획서, 공문서, 회의록 등의 HWPX 생성
• 기존 HWPX의 구조 보존 텍스트 패치와 라벨 기반 양식 채우기
• 안전한 SVG/PNG 자산 생성과 HWPX 이미지 삽입
• HWP/HWPX 형식 감지, Markdown 읽기, 구조/글꼴 참조 검증, SVG 미리보기
• 보호 문서 거부, 출력 덮어쓰기 방지, 경로/ZIP 순회 방어
• 대용량 문서를 한 번만 파싱해 UTF-8 Markdown으로 저장한 뒤 안전하게 분할 읽기

실제 HWPX 결과

아래 이미지는 README 공개용 합성 Markdown을 hwp_generate_hwpx의 report 프리셋으로 HWPX에 작성하고, 구조 검증을 통과한 문서를 SVG로 미리 본 뒤 PNG로 렌더링한 결과입니다. 개인정보, 사용자 문서, 외부 문서 내용은 사용하지 않았습니다.

_{실제 생성 결과 · 1쪽 · 표 1개 · 검증 문제 0개 · 미리보기 경고 0개}

형식 지원

형식	지원 범위
HWPX	읽기, 생성, 구조 보존 패치, 양식 채우기, 이미지 삽입, 검증, 미리보기
HWP 5.x	형식 감지, 읽기, 미리보기만 지원. 읽은 내용은 새 HWPX로 저장
HWP 3.x	실제 fixture 검증이 없어 지원을 보장하지 않음
PDF, DOCX, XLSX 등	지원하지 않음. hwp_read는 Kordoc 파싱 전에 거부

HWPX는 이 프로젝트의 정식 작성 형식입니다. 바이너리 HWP를 수정하려면 먼저 hwp_read로 읽고, 필요한 내용을 Markdown으로 정리한 다음 hwp_generate_hwpx로 새로운 HWPX 경로에 저장하십시오.

요구 사항

• Node.js 22 이상
• Windows x64 또는 macOS Apple Silicon
• after-paragraph 이미지 삽입에는 표준 위치에 설치된 Python 3.10 이상. PATH는 탐색하지 않습니다. Windows는 %SystemRoot%\py.exe 또는 사용자 설치 %LOCALAPPDATA%\Programs\Python\Launcher\py.exe, macOS는 /opt/homebrew/bin/python3, /usr/local/bin/python3, Command Line Tools의 python3 순, Linux는 /usr/bin/python3, /usr/local/bin/python3을 사용합니다.
• macOS에서는 문서 처리 자식 프로세스의 감독에도 Python을 씁니다. 그림 삽입(두 모드 모두)과 64 MiB를 넘는 문서에는 python3가 필요합니다. 이 용도에는 Xcode Command Line Tools(xcode-select --install)의 python3로 충분하지만, after-paragraph 삽입에는 3.10 이상(예: Homebrew python3)이 필요합니다. 이미지 helper는 신뢰 경로 중 3.10 이상인 첫 인터프리터를 쓰며 doctor도 같은 기준으로 판정합니다. 없으면 /usr/bin/python3가 설치 안내 창을 띄우고 해당 작업이 실패할 수 있습니다.
• Codex 또는 Claude Code 플러그인 마켓플레이스 명령을 사용할 수 있는 환경

Python이 없으면 Python 기반 이미지 삽입 모드만 PYTHON_NOT_FOUND로 실패하며 다른 도구는 계속 사용할 수 있습니다.

v0.1.4 배포 전 주요 보완 사항

Gpt_Codex_HWP는 Kordoc, rhwp, hwpx-editing-skill과 여러 공개 오픈소스를 통합·적용하는 과정에서 확인한 문서 처리 경계 문제를 첫 배포 전에 보완했습니다. 이는 해당 원본 프로젝트들에 동일한 버그나 취약점이 존재한다는 뜻이 아닙니다. 기반 작업을 공개한 모든 유지관리자와 기여자께 감사드립니다.

• HWPX를 메모리에 적재하기 전에 ZIP 중앙 디렉터리의 실제 항목 수와 크기 예산을 검사합니다.
• 대소문자만 다른 보호 매니페스트 중복을 거부하고 UTF-8·UTF-16 보호 설정을 일관되게 탐지합니다.
• 문서·이미지 처리와 실제 최종 MCP 응답에 크기 제한을 적용합니다.
• 수정 결과를 의미 단위로 재검증하고 Python 앵커 탐색은 전체 일치 목록을 만들지 않고 순차 처리합니다.
• 공개 배포 메타데이터에서 개인 식별 흔적을 제거했습니다.
• Kordoc 3.18.1 공식 아카이브를 고정 SHA-512로 인증하고 필요한 Core만 포함해 소스맵과 선택 의존성을 제거했습니다.
• 공개 배포물을 패킹하기 전에 개인정보 경로, 개인키, 실제 자격증명, .env, 테스트·사용자 문서가 없는지 검사합니다.

세부 참고 범위, 고정 버전, 저작권과 라이선스는 THIRD_PARTY_NOTICES.md를 확인하십시오.

개발 및 플랫폼 검증 상태

이 프로젝트는 주로 Windows x64에서 개발하고 실제 검증했습니다. v0.3.1의 검토 commit 4180a8d35e01aa95205a39c60ae9686486f6f9cb에서 Windows x64·macOS arm64·Linux CI가 통과한 기록은 그 SHA에 한정됩니다. 이후 패치는 각각의 실제 CI·태그·릴리즈 증거로 판단하십시오. 호스팅 macOS는 실제 Mac의 Codex Desktop·Claude Code·한컴오피스 한글 사용 검증이 아니며, macOS 완전 지원을 주장하지 않습니다.

릴리스별 테스트·감사 결과는 각 GitHub 릴리즈의 노트에 기록합니다.

v0.3.5 GitHub 설치

아래 명령은 게시 확인 후 사용할 v0.3.5 고정 명령이며 게시 증거가 아닙니다. 먼저 해당 GitHub 릴리즈의 정확한 불변 태그 SHA, 자체 전체 태그 게이트·동일 실행 attestation 성공과 원본 ZIP·SPDX·provenance·SHA256SUMS 4개 공개 자산을 실제로 확인하십시오. 소스 변경·identity 문자열이나 이전 버전의 CI 통과만으로 게시를 추정하지 마십시오. 릴리즈 노트를 확인한 뒤 새 플러그인·캐시 identity로 재설치하고, 캐시 검증·런타임 명시적 설치·doctor·호스트 재시작·문서 작업을 검증하십시오. 성공하기 전에는 이전 지속 런타임을 수동으로 삭제하지 마십시오.

기존 설치의 태그 변경

실행 중인 Codex 호스트를 먼저 닫으십시오. 기존 마켓플레이스가 v0.3.1처럼 다른 ref에 고정돼 있으면 marketplace add --ref v0.3.5만으로는 변경되지 않고 already added from a different source 오류가 납니다. marketplace upgrade도 등록된 ref를 새로 읽을 뿐 태그를 바꾸지 않습니다. 소스 등록을 제거한 뒤 새 태그로 다시 등록합니다.

codex plugin marketplace remove gpt-codex-hwp-local --json
codex plugin marketplace add Burntgogi/Gpt_Codex_HWP --ref v0.3.5 --json
$installed = codex plugin add gpt-codex-hwp@gpt-codex-hwp-local --json | ConvertFrom-Json

marketplace remove는 소스 등록 제거이며 plugin remove가 아닙니다. Codex CLI 0.162.1의 격리 Linux 프로필에서 소스 제거·재등록 후에는 이전 캐시가 남았지만, 새 plugin add는 이전 플러그인 캐시를 정리했습니다. 이전 지속 런타임의 lock·설치 영수증은 바뀌지 않았습니다. 이전 캐시가 항상 남는다고 가정하지 마십시오. 반환된 새 JSON을 아래 4–6단계 기준으로 검증하고, 성공 전에는 이전 지속 런타임을 수동으로 삭제하지 마십시오.

새 버전 검증에 실패하면 호스트를 닫고 위 세 명령의 태그를 직전 공개 v0.3.1로 바꿔 캐시를 다시 만들 수 있습니다. 이때 JSON version은 0.3.1+codex.20261021043114여야 하며, 해당 identity의 installedPath를 검증한 뒤 doctor와 문서 작업을 확인하십시오. 이전의 격리 v0.3.0 → v0.3.1 검증에서는 같은 소스 재등록 경로로 이전 캐시와 DOCTOR_OK를 런타임 재설치 없이 복구했습니다. v0.3.1은 markdown-it 보안 패치를 포함하지만 v0.3.3의 Linux reparenting 수정은 없으므로 임시 복구용으로만 판단하십시오.

사용자는 Codex 에이전트에게 다음과 같이 요청할 수 있습니다.

Burntgogi/Gpt_Codex_HWP의 v0.3.5 자체 전체 게이트·동일 실행 attestation·원본 4개 공개 자산과 게시가 확인되면 태그를 고정해 설치해 주세요. 이 절의 순서를 따르고 installedPath를 검증한 뒤 명시적 런타임 설치기와 doctor를 실행하세요. 실행 중인 모든 Codex CLI와 Desktop 호스트를 한 번 닫았다가 다시 열고 /mcp에 기본 gpt-codex-hwp가 등록되지 않는지와 문서 작업 후 one-shot 프로세스가 종료되는지 확인해 주세요. 검증이 성공할 때까지 이전 지속 런타임을 유지하세요.

1. Git, Codex CLI, Node.js 22 이상과 npm을 확인합니다. after-paragraph 이미지 삽입에만 Python 3.10 이상이 추가로 필요합니다.
2. 움직이는 main 대신 릴리스 태그를 고정해 마켓플레이스를 등록합니다.

codex plugin marketplace add Burntgogi/Gpt_Codex_HWP --ref v0.3.5 --json

반환된 JSON의 marketplaceName이 gpt-codex-hwp-local인지 확인합니다.

3. 설치 결과를 JSON으로 받습니다.

$installed = codex plugin add gpt-codex-hwp@gpt-codex-hwp-local --json | ConvertFrom-Json
$installedPath = [System.IO.Path]::GetFullPath([string]$installed.installedPath)

4. 설치 JSON의 pluginId가 gpt-codex-hwp@gpt-codex-hwp-local이고 version이 0.3.5+codex.20261021184753인지 확인합니다. installedPath가 절대 경로이고 실제 디렉터리이며, 경로 끝이 plugins/cache/gpt-codex-hwp-local/gpt-codex-hwp/<version> 구조인지 확인합니다. 런타임에는 .codex-plugin/plugin.json, runtime-manifest.json, package.json, package-lock.json, dist/install-runtime.js, dist/runtime-bootstrap.js, dist/doctor.js, dist/oneshot.js, dist/mcp.js, examples/oneshot-tool-schemas.json, examples/mcp-manual.json이 모두 있어야 하고, .codex-plugin/plugin.json의 skills는 ./skills/이며 mcpServers 속성은 없어야 합니다. JSON 문자열을 명령으로 평가하거나 예상 밖의 경로에서 npm을 실행하지 않습니다.
5. 검증한 정확한 경로에서 플랫폼 런타임을 설치하고 진단합니다. Windows x64에서 설치된 운영 의존성은 64 MiB 이하인지 확인합니다.

Push-Location -LiteralPath $installedPath
try {
  $runtime = node dist/install-runtime.js --json | ConvertFrom-Json
  if ($LASTEXITCODE -ne 0 -or $runtime.code -ne "RUNTIME_INSTALL_OK") { throw "runtime installation failed" }
  node dist/doctor.js --json
  if ($LASTEXITCODE -ne 0) { throw "doctor found a required failure" }
} finally {
  Pop-Location
}

6. doctor는 진단 전용이며 설치나 복구를 수행하지 않고 MCP 도구가 아닙니다. JSON에는 안전한 상태 코드, 불리언, 버전과 개수만 포함되며 Python·rhwp·고정 테스트 fixture 같은 선택 기능의 부재는 필수 실패와 분리됩니다.
7. 실행 중인 모든 Codex CLI와 Desktop 호스트를 한 번 닫았다가 다시 여십시오. 새 작업만으로는 충분하지 않습니다. 플러그인과 스킬이 보이고 /mcp에 gpt-codex-hwp가 기본 등록되지 않는지 확인합니다. RUNTIME_NOT_INSTALLED가 나오면 문서 작업을 반복하지 말고 검증한 경로에서 설치기를 다시 실행합니다. HWP/HWPX 작업 하나가 성공했는지 확인하고 생성 결과를 검증한 뒤 one-shot 프로세스와 하위 프로세스 종료를 확인합니다. worker-only·child-only·mixed 종료 영수증과 감독된 나머지 프로세스 트리 0개가 검증 대상입니다. 호스팅과 실제 기기의 검증 범위는 위 플랫폼 검증 상태 절을 따릅니다. 실패하면 이전 지속 런타임을 수동으로 삭제하지 말고 오류와 installedPath만 보고합니다. 토큰, 환경 변수, 사용자 문서 내용은 보고하지 않습니다.

설치 및 마이그레이션

v0.3.5 자체 전체 게이트·동일 실행 attestation·원본 4개 공개 자산과 게시를 확인한 뒤 다음 업그레이드 순서를 지키십시오. 새 identity는 이전 런타임을 재사용하지 않으므로 이전 디렉터리의 의존성만 갱신하는 것은 업그레이드가 아닙니다. 기존 설치는 먼저 위 소스 제거·재등록 절차를 따르십시오.

1. 태그를 고정한 마켓플레이스를 등록합니다.

codex plugin marketplace add Burntgogi/Gpt_Codex_HWP --ref v0.3.5

2. 새 플러그인을 설치합니다.

codex plugin add gpt-codex-hwp@gpt-codex-hwp-local

이 명령만으로 운영 의존성이 준비되지는 않습니다. version이 0.3.5+codex.20261021184753인지 확인하고 검증된 installedPath에서 node dist/install-runtime.js --json을 실행해 RUNTIME_INSTALL_OK를 확인한 뒤 node dist/doctor.js --json을 실행해 DOCTOR_OK를 확인하십시오.

3. 실행 중인 모든 Codex CLI와 Desktop 호스트를 한 번 닫았다가 다시 여십시오. 새 작업만으로는 충분하지 않습니다. gpt-codex-hwp@gpt-codex-hwp-local 플러그인과 스킬은 보여야 하지만 /mcp에 gpt-codex-hwp가 기본 등록되면 안 됩니다. 스킬로 문서 작업 하나를 실행해 1회 실행 프로세스가 종료되는지 확인합니다.

4. 새 설치 검증에 성공한 뒤에만 기존 플러그인을 제거합니다.

codex plugin remove hwp-korean-docs@hwp-local

5. 새 설치 검증에 실패하면 이전 지속 런타임을 유지하고 위 태그 변경 절의 복구 경로를 따르십시오. 오류와 검증한 installedPath를 보고하고, 캐시를 강제로 재사용하려고 버전 메타데이터나 이전 런타임 의존성을 수정하지 마십시오.

Claude Code 설치

같은 플러그인 폴더를 Claude Code에서도 씁니다. 저장소 루트의 .claude-plugin/marketplace.json이 plugins/gpt-codex-hwp를 가리키며, 마켓플레이스 이름은 Codex와 같은 gpt-codex-hwp-local입니다. Claude Code 지원은 v0.3.0부터 포함됩니다. v0.3.5 자체 전체 게이트·동일 실행 attestation·원본 4개 공개 자산과 게시를 확인한 뒤 움직이는 main 대신 #v0.3.5 태그를 고정하십시오. 새 캐시·명시적 런타임 설치·doctor와 문서 작업 하나가 성공할 때까지 이전 지속 런타임을 유지하십시오. 이번 버전의 실제 Claude Code GUI 설치·사용은 검증하지 않았습니다.

Claude Code 세션 안에서:

/plugin marketplace add Burntgogi/Gpt_Codex_HWP#v0.3.5
/plugin install gpt-codex-hwp@gpt-codex-hwp-local

터미널에서는 claude plugin marketplace add Burntgogi/Gpt_Codex_HWP#v0.3.5와 claude plugin install gpt-codex-hwp@gpt-codex-hwp-local을 사용합니다.

1. 설치된 플러그인 경로는 ~/.claude/plugins/cache/gpt-codex-hwp-local/gpt-codex-hwp/<버전>입니다. CLAUDE_CONFIG_DIR을 쓰면 ~/.claude 대신 그 경로가 기준입니다. 플러그인 버전이 0.3.5+codex.20261021184753인지 확인하십시오. Claude Code는 버전의 +를 -로 바꿔 디렉터리를 만들므로 이번 버전의 이름은 0.3.5-codex.20261021184753이며, 런타임은 이 배치를 Claude Code 설치로 인식합니다.
2. 그 경로에서 Codex와 같은 명시적 런타임 설치기와 doctor를 실행합니다.

cd "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/gpt-codex-hwp-local/gpt-codex-hwp/0.3.5-codex.20261021184753"
node dist/install-runtime.js --json   # code가 RUNTIME_INSTALL_OK인지 확인
node dist/doctor.js --json            # code가 DOCTOR_OK인지 확인

PowerShell에서는 다음과 같습니다. CLAUDE_CONFIG_DIR을 쓰면 $env:USERPROFILE\.claude 대신 그 경로를 넣으십시오.

Push-Location -LiteralPath "$env:USERPROFILE\.claude\plugins\cache\gpt-codex-hwp-local\gpt-codex-hwp\0.3.5-codex.20261021184753"
try {
  $runtime = node dist/install-runtime.js --json | ConvertFrom-Json
  if ($LASTEXITCODE -ne 0 -or $runtime.code -ne "RUNTIME_INSTALL_OK") { throw "runtime installation failed" }
  node dist/doctor.js --json
} finally { Pop-Location }

3. 운영 의존성은 ~/.claude/plugin-runtime-data/gpt-codex-hwp/<전체-플러그인-버전>/<platform>-<arch>-node<주버전>에 저장됩니다. Codex 런타임과 공유하지 않습니다.
4. Claude Code 세션을 다시 시작한 뒤 /gpt-codex-hwp:gpt-codex-hwp 스킬이 보이는지 확인합니다. 기본 MCP 서버는 등록하지 않으며, 스킬이 작업마다 dist/oneshot.js를 한 번 실행합니다.

과거 Claude Code 경로는 Windows x64의 격리된 CLAUDE_CONFIG_DIR에서 런타임 설치, doctor, HWPX 생성·검증·읽기·미리보기를 확인했습니다. 이는 v0.3.5의 설치·게시·기본 사용자 프로필·실제 Claude Code GUI 검증을 뜻하지 않습니다. macOS의 Claude Code 사용은 아직 검증하지 않았습니다.

함께 쓰면 좋은 스킬 (선택)

다음 스킬은 필수 의존성이 아닙니다. 설치하지 않아도 Gpt_Codex_HWP의 모든 도구가 동작합니다. 설치를 맡은 에이전트는 런타임 설치가 끝난 뒤 사용자에게 한 번만 권하고, 사용자가 동의한 경우에만 각 저장소의 설치 안내를 따릅니다. 거절하면 다시 묻지 않습니다.

스킬	쓰임새	Codex	Claude Code
AI Slop 탈곡기	HWPX로 만들기 전 한국어 초안의 AI 말투와 과잉 설명을 다듬습니다.	codex plugin marketplace add Burntgogi/ai-slop-thresher 후 codex plugin add ai-slop-thresher@ai-slop-thresher	/plugin marketplace add Burntgogi/ai-slop-thresher 후 /plugin install ai-slop-thresher@ai-slop-thresher
kar-plain	주제를 글, 다이어그램, 웹 페이지, 영상으로 설명합니다. 문서의 설명 단락과 도식 초안에 씁니다.	저장소의 수동 설치(~/.agents/skills) 안내	/plugin marketplace add Burntgogi/kar-plain 후 /plugin install kar-plain@kar-plain
공문서 작성 규칙 (korean-official-doc)	공문서 Markdown 초안의 날짜·시각·금액 표기, 항목 기호 순서, 붙임, 「끝」 표시를 법령 근거와 함께 오프라인으로 점검합니다. 공공기관 문서를 쓰는 사용자에게 권합니다.	같은 마켓플레이스에서 codex plugin add korean-official-doc@gpt-codex-hwp-local (v0.3.0 이상 태그)	같은 마켓플레이스에서 /plugin install korean-official-doc@gpt-codex-hwp-local

각 저장소의 최신 릴리스 태그와 설치 안내를 먼저 확인하십시오. 위 명령은 2026-10-08 기준입니다.

지속 런타임 저장과 제거

v0.3.5는 v0.3.0의 캐시 밖 저장 구조를 유지합니다. 운영 의존성은 호스트 관리 캐시가 아니라 Codex에서는 $CODEX_HOME/plugin-runtime-data/gpt-codex-hwp/<전체-플러그인-버전>/<platform>-<arch>-node<Node-주버전>, Claude Code에서는 <CLAUDE_CONFIG_DIR 또는 ~/.claude>/plugin-runtime-data/gpt-codex-hwp/...의 같은 구조에 저장됩니다. 두 지속 런타임 경로의 전체 버전은 0.3.5+codex.20261021184753이며, Claude Code 플러그인 캐시에서만 +를 -로 바꿉니다. 예를 들어 Windows x64의 Node.js 22 런타임 키는 win32-x64-node22입니다. 같은 Codex 프로필에서도 Node 주버전별 런타임은 서로 교체하지 않고 공존합니다.

설치 크기는 플랫폼과 npm에 따라 달라지며 이번 릴리스로 크기가 줄어든다고 보장하지 않습니다. 플러그인 제거가 이 캐시 밖의 데이터를 자동으로 지운다고 가정하지 마십시오. 정리할 때는 모든 Codex CLI와 Desktop 호스트, 또는 Claude Code 세션을 완전히 종료하고, 더 이상 사용하지 않는 정확한 <전체-플러그인-버전> 디렉터리만 확인해 수동으로 제거하십시오. 모든 Gpt_Codex_HWP 버전을 제거한 경우에만 상위 gpt-codex-hwp 런타임 데이터 디렉터리 전체를 제거할 수 있습니다. 나중에 다시 설치하면 검증된 installedPath에서 node dist/install-runtime.js --json을 실행해 런타임을 재생성합니다.

기본 1회 실행과 수동 MCP 호환

기본 설치는 스킬이 각 작업마다 dist/oneshot.js를 한 번 호출합니다. 사용하지 않을 때는 Gpt_Codex_HWP 상주 Node 프로세스가 없고, 호출은 기존 9개 도구 계약 중 하나만 실행한 뒤 종료됩니다. 요청·응답 JSON은 문서 내용을 명령줄에 싣지 않으며 새 응답 파일만 배타적으로 만듭니다.

dist/mcp.js와 npm start는 기존 stdio MCP 호환을 위해 남아 있지만 자동 등록되지 않습니다. 영구 MCP가 필요한 사용자만 examples/mcp-manual.json을 명시적으로 복사·등록하십시오. 이 모드는 Codex 작업이나 호스트마다 별도의 Node 서버가 상주할 수 있습니다.

도구

도구	용도
hwp_detect_format	파일의 실제 문서 형식과 컨테이너를 감지합니다.
hwp_read	HWP/HWPX를 Markdown과 메타데이터로 읽습니다.
hwp_generate_hwpx	Markdown에서 새 HWPX를 생성합니다.
hwp_validate	HWPX 구조와 글꼴 참조 무결성을 검사합니다.
hwp_render_preview	HWP/HWPX를 SVG 미리보기로 렌더링합니다.
hwp_patch_document	기존 HWPX 구조를 보존하며 텍스트를 수정합니다. 바이너리 HWP는 HWP_READ_ONLY입니다.
hwp_fill_form	라벨 기반 양식 값을 안전하게 채웁니다.
hwp_create_svg_asset	안전한 SVG와 PNG 시각 자산을 생성합니다.
hwp_insert_image	앵커를 기준으로 이미지를 HWPX에 삽입합니다.

워크플로

새 문서는 hwp_generate_hwpx로 만든 뒤 hwp_detect_format, hwp_validate, hwp_read, hwp_render_preview 순서로 형식, 구조, 내용, 배치를 확인합니다.

기존 HWPX는 먼저 hwp_read로 읽고 블록 순서와 표 구조를 유지한 Markdown으로 hwp_patch_document를 호출합니다. 바이너리 HWP는 hwp_read로 읽은 뒤 hwp_generate_hwpx를 사용해 새 HWPX로 저장합니다. 양식은 hwp_fill_form, 그림은 hwp_create_svg_asset과 hwp_insert_image를 사용합니다. 일반 그림은 after-paragraph, 서명·도장은 seal-anchor 모드가 적합하며 앵커가 없거나 여러 개면 임의로 선택하지 않습니다.

대용량 문서 읽기

대부분의 한글 문서는 1 MiB 안팎이고 10 MiB를 넘는 경우는 드뭅니다. 그래서 10 MiB 이하를 기본 지원 범위로 정하고 PR CI, 주간 Compatibility, 릴리스 게이트에서 이 크기만 검증합니다. 10 MiB 초과 512 MiB 이하는 이론상 처리 가능한 범위입니다. 같은 코드 경로를 쓰지만 크기별로 일일이 검증하지 않으며 호환성을 보장하지 않습니다(best-effort). 512 MiB 초과 파일은 거부합니다. 크기와 무관하게 비정상·손상 아카이브, 압축 해제 및 자원 정책, 선택적 허용 루트 정책에 따라 거부될 수 있습니다. Kordoc 3.18.1은 현재 HWP/HWPX 전체 압축 해제량을 100 MiB, HWPX 항목 수를 500개로 제한하므로 더 엄격한 엔진 한도가 먼저 적용될 수 있습니다.

일반 hwp_read는 JavaScript 문자열 길이 기준 Markdown 64,000자까지 인라인으로 반환합니다. 더 큰 결과에는 기존 파일이 아닌 새 .md 경로를 markdown_output_path로 지정하십시오. 플러그인은 원본을 한 번만 파싱하고 전체 UTF-8 Markdown을 최대 256 MiB까지 저장하며, 응답에는 처음 64,000자와 전체 크기·원본 지문·권장 분할 크기를 반환합니다. 이후 Codex는 파생 Markdown을 약 64,000자 단위로 읽으므로 원본 문서를 반복 파싱하지 않습니다.

최종 직렬화 MCP 결과의 하드 상한 8 MiB는 별도로 유지됩니다. 원본 파일이 8 MiB를 넘으면 첫 읽기부터 markdown_output_path를 제공하고, 더 작은 원본도 RESPONSE_TOO_LARGE가 반환되면 새 .md 경로를 지정해 다시 읽으십시오.

안전

취약점은 공개 이슈에 비밀·개인 문서·개인정보를 첨부하지 말고 SECURITY.md의 GitHub 비공개 신고 절차를 이용하십시오. 문서 내용과 격리 수준을 포함한 정확한 신뢰 모델은 보안 경계에 설명되어 있습니다.

선택적 문서 루트 제한

GPT_CODEX_HWP_ALLOWED_ROOTS를 설정하면 9개 MCP 도구가 사용하는 모든 사용자 입력·출력 경로를 지정한 로컬 디렉터리 안으로 제한할 수 있습니다. 설정하지 않으면 이전 버전과 같이 현재 OS 사용자가 접근할 수 있는 로컬 경로를 사용합니다. 단 Windows 네트워크(UNC) 경로는 이 기본값에서도 거부합니다. 값은 비어 있지 않은 JSON 배열이어야 하며, 각 항목은 이미 존재하는 고유한 절대 디렉터리여야 합니다. 심볼릭 링크나 Windows junction/reparse 별칭 자체는 루트로 사용할 수 없습니다. 아래 값은 정확한 JSON 문자열 예시입니다.

$env:GPT_CODEX_HWP_ALLOWED_ROOTS = '["C:\\Documents\\HWP","D:\\TeamDocs"]'

export GPT_CODEX_HWP_ALLOWED_ROOTS='["/Volumes/TeamDocs"]'

빈 배열, 잘못된 JSON, 상대 경로, 중복 루트, 존재하지 않는 루트, 파일 또는 링크 루트가 있으면 one-shot 호출은 도구를 실행하기 전에, 수동 MCP 서버는 시작 단계에서 닫힌 상태로 실패합니다. 값은 UTF-8 기준 16,384바이트, 루트 32개, 항목당 4,096자로 제한됩니다. 설정된 경우 원본 HWP/HWPX, Markdown·이미지 입력, 생성·패치·양식·이미지 삽입 HWPX, Markdown·SVG·PNG·미리보기·추출 이미지와 출력 디렉터리 모두 실경로 확인 뒤 같은 정책을 적용합니다. 거부 결과는 PATH_OUTSIDE_ALLOWED_ROOTS만 반환하며 설정값이나 거부된 절대 경로를 노출하지 않습니다.

대용량 처리용 내부 스풀은 사용자 루트 설정을 받지 않는 별도의 예측 불가능한 OS 임시 디렉터리에 소유자 전용 권한으로 만들고, 자식 프로세스에는 상속된 핸들만 전달하며 finally에서 제거합니다. 따라서 스풀은 사용자 허용 루트의 예외가 아니라 독립된 내부 신뢰 영역입니다. allowed_roots는 에이전트의 실수나 경로 이탈을 줄이는 방어선이며, 같은 OS 사용자 권한으로 실행되는 악성 프로세스를 완전히 격리하지는 못합니다. Node.js는 모든 파일시스템에서 Linux openat2나 Windows 핸들 상대 경로와 같은 원자적 보장을 이식성 있게 제공하지 않으므로, 높은 위험의 문서는 별도 저권한 계정·VM·컨테이너 같은 OS 격리에서 처리하십시오.

• 입력 경로와 출력 경로는 달라야 하며 기존 출력 파일을 덮어쓰지 않습니다.
• 서명, 암호화, DRM, 배포용 보호가 감지된 문서는 보호를 우회하지 않고 거부합니다.
• 경로 별칭, 하드링크, 심볼릭 링크, Windows junction, ZIP 경로 순회를 방어합니다.
• Windows 네트워크 경로(UNC, \\서버\공유)는 기본적으로 거부합니다. 네트워크 공유를 써야 하면 GPT_CODEX_HWP_ALLOWED_ROOTS에 그 UNC 루트를 명시하십시오. 그 아래 경로만 허용됩니다. GPT_CODEX_HWP_ALLOWED_ROOTS를 설정하지 않았다면 매핑된 네트워크 드라이브(예: Z:\)에 있는 문서는 읽을 수 있지만, 그 UNC 루트를 지정하지 않는 한 그 공유로 결과물을 쓰지는 않습니다.
• HWPX 검증에 실패하면 생성 또는 편집 결과물을 쓰지 않습니다.
• hwp_patch_document의 의미 검증은 필수이며 검증을 끄거나 검증 통계 없이 결과물을 게시할 수 없습니다.
• 보호 매니페스트는 UTF-8/UTF-16 인코딩을 구분해 검사하고, ZIP 엔트리 수는 JSZip 로드 전에 최대 10,000개로 제한합니다.
• 양식 값은 기본적으로 MCP 결과에서 마스킹하며 명시적 요청이 있을 때만 공개합니다.
• 바이너리 HWP 직접 패치는 HWP_READ_ONLY로 거부합니다.

글꼴 무결성

HWPX는 HANGUL, LATIN, HANJA, JAPANESE, OTHER, SYMBOL, USER 언어권마다 별도의 글꼴표를 사용합니다. 생성 과정은 존재하지 않는 참조만 유효한 ID로 정규화하며 Kordoc의 장평, 자간, 상대 크기, 글자 위치와 글꼴 이름은 바꾸지 않습니다. hwp_validate는 글꼴표의 중복/누락, 카운트, ID, 빈 이름과 잘못된 fontRef를 검사합니다.

이 플러그인은 글꼴 파일을 번들하거나 HWPX에 내장하지 않으며 시스템 글꼴을 자동 설치하지 않습니다. 실제 글꼴 표시와 줄바꿈은 문서를 여는 플랫폼에 설치된 글꼴에 따라 달라질 수 있습니다.

알려진 제한

• 바이너리 HWP는 읽기 전용이며 생성·수정·변환 출력은 모두 HWPX로 작성합니다.
• 유효한 원본 문서는 10 MiB 이하가 CI 검증 기본 범위이며, 10 MiB 초과 512 MiB 이하는 이론상 처리 가능하지만 검증하지 않는 best-effort, 512 MiB 초과는 거부됩니다. 비정상 아카이브, 압축 해제·자원·허용 루트 정책과 Kordoc 3.18.1의 100 MiB 압축 해제량 및 HWPX 500개 항목 제한은 별도로 적용됩니다.
• 인라인 Markdown은 64,000자, 파생 Markdown 파일은 256 MiB, 최종 직렬화 MCP 결과는 8 MiB로 제한합니다.
• Kordoc 또는 rhwp 미리보기는 한컴 GUI와 픽셀 단위로 동일하지 않을 수 있습니다.
• rhwp 미리보기 폴백은 첫 페이지만 렌더링하고 Node 환경의 근사 글꼴 폭을 사용할 수 있습니다.
• 보호 문서의 암호나 DRM을 해제하거나 우회하지 않습니다.
• HWP 3.x는 실제 fixture가 없어 검증된 지원으로 표시하지 않습니다.
• 미리보기 SVG는 128 MiB로 제한합니다.
• 미리보기 하이라이트는 최대 256개 및 합계 16,384자, 한 번의 양식 채우기 값은 합계 10,000개로 제한합니다.

런타임 설치

플랫폼별 네이티브 의존성은 검증한 플러그인 installedPath에서 명시적 설치기로 준비합니다. Windows에서 설치한 런타임을 macOS로 복사하지 마십시오.

node dist/install-runtime.js --json
node dist/doctor.js --json

첫 명령의 JSON code는 RUNTIME_INSTALL_OK여야 합니다. 설치기는 잠금 파일과 매니페스트를 검증하고 lifecycle script를 끈 채 Sharp를 포함한 운영 의존성을 현재 OS와 CPU에 맞게 Codex 관리 캐시 밖에 원자적으로 게시합니다. 두 번째 명령은 설치나 복구 없이 환경을 진단합니다. 문서 작업 중에는 설치하지 않으며, RUNTIME_NOT_INSTALLED가 반환되면 이 절의 설치기를 명시적으로 실행하십시오. 글꼴 파일은 설치하지 않습니다. Kordoc Core는 HWP/HWPX 작업에 필요한 고정 런타임만 제공하며 PDF, OCR, ONNX, 수식 엔진 선택 의존성을 설치하지 않습니다. 검증된 Windows x64 런타임 의존성 예산은 64 MiB 이하입니다.

오픈 소스 감사

이 프로젝트의 hwpx-editing-skill 사용은 일반 런타임 의존성과 다릅니다. 원시 항목과 압축 메타데이터를 보존하는 HWPX 재패키징 흐름, 일부 안전 원칙과 검증 흐름을 해당 프로젝트의 고정 커밋에서 수정·적용했습니다. 유지관리자와 기여자께 감사드립니다.

Kordoc에서는 문서 감지, 읽기, HWPX 생성/검증/미리보기 런타임을 사용했고, rhwp에서는 읽기 전용 문서 흐름을 위한 선택적 HWP/HWPX 파싱과 미리보기 폴백을 사용했습니다. Model Context Protocol TypeScript SDK는 MCP 서버와 stdio 전송을, xmldom은 XML DOM 처리를, SheetJS CFB는 바이너리 HWP의 OLE 복합 파일 처리를, JSZip은 HWPX ZIP 처리를, Sharp는 안전한 이미지 변환을, Zod는 도구 입력 스키마 검증을 제공합니다. 각 프로젝트의 유지관리자와 기여자께 감사드립니다.

Pixelify Sans는 최종 배너의 래스터화된 제목을 제작할 때만 사용했으며 글꼴 파일은 플러그인에 포함되지 않습니다. Pixelify Sans Project Authors와 Google Fonts 유지관리자께 감사드립니다. 정확한 버전, 저작권, 라이선스, 사용 범위는 THIRD_PARTY_NOTICES.md를 참조하십시오.

라이선스

Gpt_Codex_HWP 프로젝트는 Apache-2.0으로 배포됩니다. 제3자 구성 요소와 제작 입력물은 THIRD_PARTY_NOTICES.md에 기재된 각각의 라이선스를 따릅니다.

기여 및 저장소 운영

공개 이슈와 풀 리퀘스트에서의 논의는 환영합니다. 공식 브랜치, 태그, 릴리스, 벤더 런타임, 생성 런타임의 변경은 저장소 소유자가 검토하고 직접 작성하며, 의존성 자동화는 이슈를 통한 권고만 수행합니다. 먼저 기여 지침을 읽고 아키텍처의 원본과 생성 런타임 경계 및 변경 기록을 확인하십시오. 자격증명, 개인 문서, 환경 파일, 개인 경로, 미공개 감사 자료는 공개 보고에 포함하지 않습니다. 보안 문제는 SECURITY.md의 비공개 절차로 신고합니다.