@p.e.c/boaz-skills 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p.e.c/boaz-skills",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI 코딩 도구용 스킬 모음 (Claude Code, Codex, Gemini)",
   "type": "module",
   "bin": {

package/skills/modify-hwpx/SKILL.md

@@ -5,38 +5,31 @@ description: 'HWPX(한글) 파일 수정 스킬. MCP 서버를 통해 HWPX 문
 
 # HWPX (한글) 파일 수정
 
-> MCP 서버 기반으로 HWPX 문서를 프로그래밍 방식으로 편집하는 스킬
+> HWPX 문서를 프로그래밍 방식으로 편집하는 스킬. 두 가지 방식을 지원한다.
 
 ## 핵심 요약
 
-**MCP 서버**: `@p.e.c/hwpx-mcp` — HWPX 문서의 텍스트/표/이미지를 수정하는 77개 도구 제공
+**방식 A (MCP)**: Claude Code + `@p.e.c/hwpx-mcp` MCP 서버 — 77개 도구로 편집
+**방식 B (Fallback)**: Python lxml로 직접 XML 수정 — MCP 없는 환경(Codex, Gemini 등)에서 사용
 
 ```
-HWPX 파일 → MCP 서버로 열기 → 도구로 편집 → 저장
+방식 A: HWPX 파일 → MCP 서버로 열기 → 도구로 편집 → 저장
+방식 B: HWPX(ZIP) → unzip → lxml로 section XML 수정 → zip CLI로 교체 → 저장
 ```
 
 ---
 
-## 사전 준비 (Setup)
+## 방식 A: MCP 서버 (Claude Code 전용)
 
-### 1. MCP 서버 설치
+### 사전 준비
 
 ```bash
 # Claude Code에 MCP 서버 등록
 claude mcp add --transport stdio --scope user hwpx-mcp -- npx -y @p.e.c/hwpx-mcp
+# Claude Code 재시작 후 /mcp 로 확인
 ```
 
-### 2. Claude Code 재시작
-
-MCP 서버가 로드되려면 Claude Code를 재시작해야 합니다.
-
-### 3. 설치 확인
-
-Claude Code 내에서 `/mcp` 명령으로 `hwpx-mcp` 서버 상태를 확인합니다.
-
----
-
-## 작업 워크플로우
+### 작업 워크플로우
 
 ### Step 1: 문서 열기
 
@@ -169,3 +162,184 @@ claude mcp add --transport stdio --scope user hwpx-mcp -- npx -y @p.e.c/hwpx-mcp
 1. `save_document`로 저장한다 (원본 보존을 위해 다른 경로로 저장 권장)
 2. `verify_integrity: true` 옵션으로 무결성 검증을 수행한다
 3. 사용자에게 한글에서 열어 확인하도록 안내한다
+
+---
+
+## 방식 B: Python lxml Fallback (MCP 없는 환경)
+
+MCP를 지원하지 않는 도구(Codex CLI, Gemini CLI 등)에서는 Python으로 직접 HWPX XML을 수정한다.
+
+### 사전 준비
+
+```bash
+pip3 install lxml --break-system-packages
+```
+
+### HWPX 구조 이해
+
+HWPX는 ZIP 파일이다. 내부 구조:
+```
+mimetype                    ← 시그니처 ("application/hwp+zip")
+Contents/header.xml         ← 문서 스타일/폰트 정의
+Contents/section0.xml       ← 본문 첫번째 섹션
+Contents/section1.xml       ← 두번째 섹션 ...
+Contents/content.hpf        ← 섹션 목록 (spine)
+BinData/                    ← 이미지, OLE 객체
+META-INF/                   ← 매니페스트
+Preview/PrvText.txt         ← 텍스트 미리보기
+```
+
+### 파이프라인: 읽기 → 수정 → 저장
+
+```python
+from lxml import etree
+import zipfile, shutil, subprocess, os
+
+SRC = "원본.hwpx"
+DST = "수정본.hwpx"
+SECTION = "Contents/section0.xml"
+
+# 1. 원본에서 XML 읽기
+with zipfile.ZipFile(SRC, 'r') as z:
+    data = z.read(SECTION)
+
+root = etree.fromstring(data)
+ns_p = 'http://www.hancom.co.kr/hwpml/2011/paragraph'
+
+# 2. 수정 (예시: 텍스트 치환)
+for t_elem in root.iter(f'{{{ns_p}}}t'):
+    if t_elem.text and '치환대상' in t_elem.text:
+        t_elem.text = t_elem.text.replace('치환대상', '새텍스트')
+
+# 3. XML 직렬화 (원본 선언부 보존)
+xml_out = etree.tostring(root, xml_declaration=False, encoding='unicode')
+final = '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>' + xml_out
+final_bytes = final.encode('utf-8')
+
+# 4. 임시 파일에 저장
+import tempfile
+tmpdir = tempfile.mkdtemp()
+os.makedirs(os.path.join(tmpdir, 'Contents'), exist_ok=True)
+with open(os.path.join(tmpdir, SECTION), 'wb') as f:
+    f.write(final_bytes)
+
+# 5. 원본 복사 후 zip CLI로 해당 파일만 교체
+shutil.copy2(SRC, DST)
+subprocess.run(['zip', DST, SECTION], cwd=tmpdir)
+```
+
+**중요**: Python `zipfile`로 전체 재패키징하면 파일이 손상될 수 있다. 반드시 **원본을 복사**하고 **`zip` CLI로 수정된 XML만 교체**한다.
+
+### 표(테이블) 행 삭제 시 필수 처리
+
+병합 셀(rowSpan > 1)이 있는 표에서 행을 삭제할 때 **3가지를 반드시 함께 처리**해야 한다. 누락하면 한글이 크래시한다.
+
+```python
+ns_p = 'http://www.hancom.co.kr/hwpml/2011/paragraph'
+
+def get_all_text(elem):
+    return ''.join(elem.itertext())
+
+def delete_table_rows(root, table_index, rows_to_remove):
+    """
+    표에서 행을 삭제한다. rowSpan/rowAddr/rowCnt를 자동 조정한다.
+
+    Args:
+        root: section XML의 lxml root element
+        table_index: 삭제 대상 테이블 인덱스 (0-based)
+        rows_to_remove: 삭제할 행 인덱스 set (예: {9, 10, 11})
+    """
+    tables = list(root.iter(f'{{{ns_p}}}tbl'))
+    if table_index >= len(tables):
+        return False
+
+    tbl = tables[table_index]
+    all_rows = tbl.findall(f'{{{ns_p}}}tr')
+
+    # 1. rowSpan 조정: 삭제되지 않는 행의 셀이 삭제 행에 걸쳐있으면 rowSpan 줄이기
+    for i, tr in enumerate(all_rows):
+        if i in rows_to_remove:
+            continue
+        for tc in tr.findall(f'{{{ns_p}}}tc'):
+            addr = tc.find(f'{{{ns_p}}}cellAddr')
+            span = tc.find(f'{{{ns_p}}}cellSpan')
+            if addr is None or span is None:
+                continue
+
+            row_addr = int(addr.get('rowAddr'))
+            row_span = int(span.get('rowSpan'))
+            if row_span <= 1:
+                continue
+
+            # 이 셀의 span 범위 내에 삭제 대상 행이 몇 개 있는지 계산
+            span_range = set(range(row_addr, row_addr + row_span))
+            overlap = span_range & rows_to_remove
+            if overlap:
+                span.set('rowSpan', str(row_span - len(overlap)))
+
+    # 2. 행 삭제 (역순)
+    for i in sorted(rows_to_remove, reverse=True):
+        if i < len(all_rows):
+            tbl.remove(all_rows[i])
+
+    # 3. rowAddr 재번호
+    remaining_rows = tbl.findall(f'{{{ns_p}}}tr')
+    for new_idx, tr in enumerate(remaining_rows):
+        for tc in tr.findall(f'{{{ns_p}}}tc'):
+            addr = tc.find(f'{{{ns_p}}}cellAddr')
+            if addr is not None:
+                addr.set('rowAddr', str(new_idx))
+
+    # 4. rowCnt 업데이트
+    tbl.set('rowCnt', str(len(remaining_rows)))
+    return True
+```
+
+사용 예시:
+
+```python
+# 표 0번에서 행 9, 10, 11 삭제
+delete_table_rows(root, table_index=0, rows_to_remove={9, 10, 11})
+```
+
+### 텍스트 검색/치환
+
+```python
+# 문서 전체에서 텍스트 검색
+for t_elem in root.iter(f'{{{ns_p}}}t'):
+    if t_elem.text and '검색어' in t_elem.text:
+        print(f"Found: {t_elem.text}")
+
+# 치환
+for t_elem in root.iter(f'{{{ns_p}}}t'):
+    if t_elem.text and '이전값' in t_elem.text:
+        t_elem.text = t_elem.text.replace('이전값', '새값')
+```
+
+### 표 구조 확인
+
+```python
+for i, tbl in enumerate(root.iter(f'{{{ns_p}}}tbl')):
+    print(f"Table {i}: rowCnt={tbl.get('rowCnt')}, colCnt={tbl.get('colCnt')}")
+    for j, tr in enumerate(tbl.findall(f'{{{ns_p}}}tr')):
+        for tc in tr.findall(f'{{{ns_p}}}tc'):
+            addr = tc.find(f'{{{ns_p}}}cellAddr')
+            span = tc.find(f'{{{ns_p}}}cellSpan')
+            text = get_all_text(tc).strip()[:30]
+            ra = addr.get('rowAddr') if addr is not None else '?'
+            rs = span.get('rowSpan') if span is not None else '1'
+            if text:
+                print(f"  Row {j} Cell: rowAddr={ra} rowSpan={rs} '{text}'")
+```
+
+### Fallback 작업 프로토콜
+
+MCP가 없는 환경에서 HWPX 수정 요청 시:
+
+1. **lxml 확인**: `python3 -c "from lxml import etree"` 실행. 없으면 설치
+2. **구조 파악**: `unzip -l 파일.hwpx`로 내부 구조 확인
+3. **텍스트 미리보기**: `Preview/PrvText.txt` 추출하여 내용 파악
+4. **XML 읽기**: 대상 section XML을 zipfile로 읽기
+5. **lxml로 수정**: 텍스트 치환, 행 삭제 등 실행 (위 함수 사용)
+6. **원본 복사 + zip CLI 교체**: Python zipfile로 재패키징하지 않는다
+7. **검증**: 한글에서 열어 확인하도록 안내