프로젝트가 해결하는 문제
Gongwen GB/T 9704-2012 Skill은 중국어 공식 문서를 위한 오픈 소스 도구입니다. 제목에 흑체를 적용하고 본문에 방송체를 적용하는 데 그치지 않고, GB/T 9704-2012의 실행 가능한 요구사항에 따라 A4 용지, 판심, 제목, 본문, 계층, 첫 페이지, 기관명, 문서 번호, 서명, 날짜 및 페이지 번호 등의 서식 요소를 처리하고 계속 편집할 수 있는 DOCX 파일을 출력합니다.
이 프로젝트는 일반 보고서, 계획안, 업무 보고에 적합하며, 공식 문서 발행, 붉은 머리글과 붉은 선이 인쇄된 용지에 인쇄하는 문서, 완전한 전자식 붉은 머리글, 서신, 명령 및 회의록도 지원합니다. 생성된 문서는 Word 또는 WPS에서 계속 표, 첨부 파일, 인장 이미지를 추가하거나 실제 날인을 진행할 수 있습니다.
GB/T 9704-2012는 당정 기관이 공식 문서를 작성하고 발행하는 데 적용되며, 기타 기관과 단위는 이를 참고하여 시행할 수 있습니다. README에 따르면 이 표준은 2025년 5월 30일 재검토 후에도 계속 유효합니다.
핵심 기능과 사용 범위
- 일반 자료: 기본값으로
ordinary를 사용하며, 기관명을 제공하더라도 붉은 머리글을 자동으로 생성하지 않습니다. - 공식 문서 발행: 반드시
formal을 명시적으로 선택해야 합니다. 인쇄된 붉은 머리글 용지 모드는 용지에 이미 있는 붉은 머리글과 붉은 선을 위한 공간만 확보하며, DOCX에서 이를 다시 그리지 않습니다. - 전자식 붉은 머리글:
formal --letterhead digital을 설정한 경우에만 생성기가 붉은 머리글의 전체 요소를 그립니다. - 기관명과 문서 번호:
--org및--doc-no로 제공합니다. 공식 서식은 연도, 육각 괄호, 일련번호 및 “号” 문자 규칙에 명백히 맞지 않는 문서 번호를 거부합니다. - 제목과 목차: 4단계 제목은 Word/WPS의 “제목 1”부터 “제목 4” 스타일과 해당 개요 수준으로 기록되므로 이를 사용해 자동 목차를 삽입할 수 있습니다.
- 페이지 번호: 가운데 정렬, 홀수·짝수 페이지, 미표시의 세 가지 모드를 지원하며, 구체적인 매개변수는 프로젝트의
SKILL.md를 기준으로 해야 합니다. - 첨부 파일과 판기: 첨부 파일은 별도 페이지에 생성할 수 있으며 공식 문서의 페이지 번호를 연속으로 유지합니다. 참조 발송 또는 인쇄 발행 정보는 마지막 페이지 판심 하단에 고정할 수 있습니다.
- 수동 처리: 인장, 서명 도장, 첨부 파일 내용 및 실제 날인 위치는 용도에 따라 DOCX에서 추가하거나 검토해야 합니다.
프로젝트와 실행 환경 준비
먼저 GitHub 프로젝트 주소에서 저장소를 가져온 뒤 프로젝트 루트 디렉터리로 이동합니다. 생성기와 검증기는 node로 실행되므로 로컬에 사용 가능한 Node.js 환경이 필요합니다. README에는 구체적인 버전이 지정되어 있지 않으므로 현재 저장소의 스크립트와 테스트 결과를 기준으로 해야 합니다.
DOCX만 바로 생성하려면 저장소에서 스크립트를 실행하면 됩니다. AI 프로그래밍 도구가 이 Skill을 자동으로 읽도록 하려면 크로스 플랫폼 설치 프로그램을 사용할 수 있습니다.
macOS 및 Linux
scripts/install.sh --allWindows
.\scripts\install.ps1 -All설치 프로그램은 동일한 소스 디렉터리를 각 플랫폼의 사용자 수준 기술 디렉터리에 연결합니다. Windows는 기호 링크 권한 문제를 피하기 위해 기본적으로 복사 방식을 사용합니다. 지원 플랫폼에는 Codex, Claude Code, OpenCode, Trae Code, Trae CLI, Kimi Code CLI, Kimi Code, WorkBuddy 및 ZCode가 포함됩니다. TraeWork는 저장소의 dist/traework-gongwen-skill.zip 가져오기 패키지를 사용합니다.
첫 번째 일반 자료 생성
프로젝트에는 테스트 입력 파일 tests/fixture.md가 제공됩니다. 다음 명령은 이를 일반 자료 서식으로 변환하여 임시 디렉터리에 저장합니다.
node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/gongwen.docx --format ordinary --title "공문 서식 회귀 테스트"주요 매개변수의 의미는 다음과 같습니다.
--input: 입력 콘텐츠 파일입니다.--output: 생성된 DOCX 경로입니다.--format ordinary: 일반 보고서, 계획안 또는 업무 보고 서식을 사용합니다.--title: 문서 제목을 설정합니다.
생성이 완료되면 검증기를 사용하여 도구가 보장하는 DOCX 구조와 서식 요소를 확인합니다.
node scripts/verify_gongwen_docx.mjs --input /tmp/gongwen.docx --profile ordinary검증을 통과했다고 해서 최종 검토를 생략할 수 있는 것은 아닙니다. 공식 제출 전에 대상 컴퓨터의 Word 또는 WPS에서 파일을 열고 실제 인쇄 조건에 따라 줄바꿈, 페이지 나눔, 글꼴, 첨부 파일 및 날인 위치를 확인해야 합니다.
인쇄된 붉은 머리글 용지용 문서 생성
붉은색 기관 표식과 붉은 선이 이미 인쇄된 용지에 자료를 인쇄해야 한다면 공식 서식과 인쇄된 붉은 머리글 용지 모드를 명확히 선택해야 합니다.
node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/formal.docx --format formal --letterhead preprinted --letterhead-reserve-mm 72 --org "예시 기관 문서" --doc-no "예시 발〔2026〕1号" --title "공문 서식 회귀 테스트"--letterhead-reserve-mm 72는 첫 페이지에서 용지에 이미 있는 붉은 머리글 영역을 위해 72밀리미터를 확보한다는 뜻입니다. 72밀리미터는 기본값이며, 실제 사용 시에는 해당 기관의 붉은 머리글 용지를 측정하고 프로젝트가 지원하는 37~130밀리미터 범위에서 조정해야 합니다. 이 모드는 DOCX에서 붉은색 기관 표식과 붉은 선을 다시 그리지 않습니다.
그 다음 해당 공식 서식 설정으로 검증합니다.
node scripts/verify_gongwen_docx.mjs --input /tmp/formal.docx --profile formal --letterhead preprinted완전한 전자식 붉은 머리글 생성
DOCX에서 붉은 머리글의 전체 요소를 직접 그려야 할 때만 --letterhead digital을 사용합니다.
node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/formal-digital.docx --format formal --letterhead digital --org "예시 기관 문서" --doc-no "예시 발〔2026〕1号" --title "공문 서식 회귀 테스트"전자식 붉은 머리글은 글꼴 환경에 더 민감합니다. 붉은 머리글과 제목에는 대상 컴퓨터에 실제로 설치된 소표송체를 사용해야 하며, 본문 등에는 표준 방송체가 필요합니다. 생성기가 이러한 글꼴을 찾지 못하면 터미널에 경고를 표시하고 사용한 대체 글꼴을 기록합니다.
글꼴 대체 금지
글꼴 대체를 허용할 수 없는 제출 환경에서는 생성기와 검증기에 모두 --require-standard-fonts를 추가합니다. 현재 컴퓨터에 소표송체 또는 표준 방송체가 없으면 명령이 중지되고 누락된 글꼴이 표시되며, 대체 버전을 계속 출력하지 않습니다.
node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/strict.docx --format formal --letterhead digital --org "예시 기관 문서" --doc-no "예시 발〔2026〕1号" --title "공문 서식 회귀 테스트" --require-standard-fonts
node scripts/verify_gongwen_docx.mjs --input /tmp/strict.docx --profile formal --letterhead digital --require-standard-fonts목차, 첨부 파일 및 전용 서식
Word 또는 WPS에서 목차 생성
생성기는 4단계 제목을 표준 제목 스타일과 개요 수준으로 기록합니다. 문서를 연 후 Word/WPS에서 “참조 → 목차”를 선택하여 자동 목차를 생성하거나 업데이트할 수 있습니다. 4단계 제목을 표시할지는 목차 설정에서 선택해야 합니다.
첨부 파일 추가
--attachment-file을 반복 사용하면 여러 첨부 파일을 별도 페이지로 문서에 추가할 수 있습니다. 생성기는 “첨부” 레이블, 세 번째 줄 제목 및 본문을 배치하고 공식 문서의 페이지 번호를 연속으로 유지합니다. 구체적인 입력 구조는 저장소의 SKILL.md를 참조해야 합니다.
전용 생성 분기 선택
- 서신
letter: 지정된 크기의 위아래 붉은색 이중선을 생성하고, 아래 선은 바닥글에 배치하며 페이지 번호를 끕니다. - 명령
command: 기관 표식 아래 두 줄 여백, 명령 번호 아래 두 줄 여백 등의 서식 요구사항을 적용합니다. - 회의록
minutes: “출석”, “휴가”, “열석” 레이블을 흑체로 설정하고 참석자 명단은 방송체로 설정합니다.
이 유형들은 일반 서식의 단순한 문자 교체가 아니라 각각 해당 생성 분기로 진입합니다. 선택하기 전에 문서 종류를 먼저 확인해야 합니다.
고급 사용 권장 사항
- 기관명을 근거로 붉은 머리글 유형을 추측하지 마세요. 일반 자료는 항상
ordinary를 명확히 사용하고, 공식 문서 발행은formal을 명시적으로 사용합니다. - 먼저 용지를 확인한 후 인쇄 여백을 설정하세요. 인쇄된 붉은 머리글 용지의 실제 크기는 기관 템플릿에 따라 다를 수 있으므로 기본값 72밀리미터를 기계적으로 사용해서는 안 됩니다.
- 최종 편집 환경에 글꼴을 설치하고 검증하세요. 동일한 글꼴도 시스템, Word 및 WPS에 따라 이름이 다를 수 있으며, 대체 글꼴은 글자 크기, 줄 간격 및 줄바꿈을 변경할 수 있습니다.
- 긴 문서 관리에 제목 스타일을 활용하세요. 목차 계층을 수동으로 모방하지 말고 생성기가 기록한 제목 1부터 제목 4까지의 스타일을 사용해야 합니다.
- 자동 검증과 수동 검토를 함께 수행하세요. 저장소의
references/gbt9704-audit-matrix.md및references/formal-checklist.md를 참고하여 자동 확인이 가능한 항목과 반드시 수동 검토해야 하는 항목을 구분할 수 있습니다. - 특수 서식 로직에 주의하세요. 공식 전자식 붉은 머리글은 명시적인 28포인트 판심 빈 줄을 사용하여 붉은 선 아래 제목과 기관 표식에서 문서 번호까지의 거리를 제어합니다. 상행 문서의 문서 번호와 발행자는 같은 줄에 배치됩니다.
프로젝트 테스트 실행
macOS 또는 Linux 환경에서는 저장소에서 제공하는 회귀 테스트를 실행할 수 있습니다.
tests/run_tests.sh테스트는 가운데 정렬 및 홀수·짝수 페이지 번호 생성, DOCX 패키지 구조 및 PDF 변환 검증을 다룹니다. 이를 통해 생성기, 검증기 및 인쇄 가능한 파일 경로가 작동하는지 확인할 수 있습니다. 크로스 플랫폼 설치는 tests/test-install.sh를 사용하여 격리된 환경에서 로컬 기술 디렉터리와 TraeWork 가져오기 패키지도 검증할 수 있습니다.
맺음말
Gongwen Skill은 프롬프트, Word 템플릿 및 임시 스크립트에 분산되기 쉬운 공문서 규칙을 하나의 유지 관리 가능한 워크플로로 통합합니다. 가장 안정적인 사용 방법은 먼저 올바른 일반 또는 공식 서식을 선택한 다음 DOCX를 생성하고 검증기를 실행한 후, 대상 Word/WPS 환경, 글꼴 환경 및 인쇄 조건에서 수동 검토를 완료하는 것입니다. 프로젝트는 MIT 라이선스를 따르지만 표준 문서와 기관 템플릿은 여전히 각각의 권리 및 관리 규정을 준수해야 합니다.