원문의 주장과 근거는 지키고, 한국어 산문은 더 선명하게.
v1.0.1 ·
MIT License · Python 3.9 이상
korean-prose-editor는 한국어 산문의 뜻과 근거를 유지하면서 맞춤법, 번역 흔적, 상투 표현, 문장
밀도, 종결문체, 용어 표기와 문단 흐름을 점검하는 로컬 편집 파이프라인이자 에이전트 스킬이다.
현재 공개 버전은 v1.0.1이다.
A local-first Korean prose editor for Grok Build. It keeps claims, numbers, quotes, and document structure in place, then lets an agent revise one sentence at a time. The plugin does not host documents or call a remote writing API.
웹에 문서를 올리고 결과를 받는 SaaS로 제공하지 않는다. Python CLI가 입력을 문장과 구조로 나누고, 편집 상태를 파일로 기록하며, 결과를 다시 조립한 뒤 원문 보존 검사를 실행한다. 고정 표기처럼 판단 범위가 좁은 항목은 결정적 규칙으로 처리한다. 문맥을 읽어야 하는 윤문은 에이전트가 수정안 JSON으로 제안하고, CLI가 그 수정안이 계약을 벗어나지 않았는지 검사한다.
이 프로젝트의 핵심은 문장을 많이 바꾸는 데 있지 않다. 어디까지 바꿀 수 있는지 먼저 정하고, 바꾸지 말아야 할 정보가 움직이면 완료를 거부하는 것에 있다.
| 사용 사례 | 점검하는 내용 |
|---|---|
| 보고서·해설문 | 주장–근거 연결, 종결문체, 용어 표기, 문장 밀도 |
| 칼럼·에디토리얼 | 문장 리듬, 번역 흔적, 상투 표현, 문단 흐름 |
| 이메일·업무 안내 | 높임 표현, 요청의 명확성, 간결한 전달 순서 |
| 논문 초안·연구 메모 | 확신 수준, 수치·인용·전문용어 보존 |
| 뉴스레터·다이제스트 | 반복 표현, 카드 사이 문체, 요약 범위 |
맞춤법만 빠르게 고칠 수도 있지만, 강점은 긴 문서를 문장별로 검토하면서 원문·수정안·적용 규칙과 실패 이유를 함께 남기는 작업에 있다.
입력 문서
→ 구조 보호와 문장 분절
→ 목적·문체·편집 범위 계약
→ 고정 규칙 적용 + 에이전트 수정안 반영
→ 원래 구조로 재조립
→ 수치·URL·인용·코드·문장 수·문체·용어·완전성 검사
→ final.md + summary.md + changes.json + integrity.json
- 구조를 먼저 보호한다. Markdown 제목, 목록, 표, 인용, 코드 블록은 일반 산문과 분리한다.
- 편집 계약을 기록한다. 글의 목적, 종결문체, 맞춤법·표현·형식 레이어와 어투를
contract.json에 저장한다. - 미검토 문장을 드러낸다.
remaining.json에 판단이 필요한 문장만 남긴다. 빈 칸을 성공으로 처리하지 않는다. - 수정안을 통제된 형식으로 받는다. 에이전트는 문장 번호, 수정문, 규칙 식별자를 JSON으로 제출한다. 워크시트를 직접 덮어쓰지 않는다.
- 결과를 원문과 다시 대조한다. 수치, 날짜, URL, 직접 인용, 인라인 코드·수식, 문장 수와 구조가 달라지면 종료 코드와 실패 상태를 남기고 완료를 중단한다.
| 제공하는 것 | 제공하지 않는 것 |
|---|---|
| 문장별 원문·수정안·규칙 기록 | 문장의 사실성을 자동으로 판정하는 기능 |
| 수치·URL·인용·코드·구조 보존 검사 | 법률·의학·학술 내용의 전문 검증 |
| 목적별 문체와 확장 가능한 규칙 팩 | 특정 작가나 매체의 문체 복제 |
| 실패를 숨기지 않는 상태·종료 코드 | 모든 문맥에서 오탐과 누락이 없는 맞춤법 사전 |
| 로컬 파일 중심 실행과 재현 가능한 테스트 | 문서를 외부 모델에 자동 전송하는 호스팅 서비스 |
보존 검사는 중요한 오류를 줄이기 위한 안전장치이며 의미 보존의 수학적 증명을 뜻하지 않는다. 중요한
문서는 summary.md만 보지 말고 원문과 final.md를 직접 대조해야 한다.
이 프로젝트는 Turtle-Hwan/im-ai-copyeditor의 문장 단위 한국어 교정 워크플로에서 설계상의 영감만 받았다. 실행 코드, 규칙, 예문, 테스트는 원본 저장소의 해당 자료를 복사하거나 고쳐 쓰지 않고 이 프로젝트에서 독립적으로 설계·구현·작성했다. 따라서 파일 단위로 남겨 둔 MIT 유래 구현 부분은 없다. 프로젝트가 채택한 표준 MIT 라이선스 본문과 짧고 일반적인 언어 관용구는 다른 MIT 프로젝트와 같을 수 있다. 이 설명은 개발 기록이며 법률 의견이나 보증이 아니다.
English: Turtle-Hwan/im-ai-copyeditor was consulted for design inspiration only. This project's implementation code, rules, examples, and tests were independently designed, implemented, and authored; none were copied or adapted from that repository. No implementation file is retained as an MIT-derived component. The standard MIT license text and short, commonplace language idioms may naturally match other projects. 자세한 표기는 NOTICE, 이용 조건은 LICENSE를 확인한다.
Grok에서 /copyedit나 “한국어 윤문”으로 쓰는 설치 경로다.
grok plugin install rp0927/korean-prose-editor --trust공식 카탈로그에 올라간 뒤에는 아래도 같다.
grok plugin install korean-prose-editor@xai-official --trust설치 후 새 세션에서 korean-prose-editor 스킬과 /copyedit 명령을 사용한다. 플러그인은 파일을
복사할 뿐이며, 실행에는 이미 있는 python3(3.9 이상)가 필요하다.
None. The plugin does not send documents or telemetry to a remote service.
None. No API keys, OAuth, or account sign-in.
- Runtime: Python 3.9+ standard library. No
pip install. - Local files: the helper scripts read the input document and write a run directory.
- Hooks / MCP / LSP: none.
- Remote code download: none.
배포 압축을 로컬에서 풀거나 공개 저장소를 clone한 뒤 korean-prose-editor 디렉터리에서 실행한다.
별도 패키지 설치는 필요하지 않다.
검증된 압축과 SHA-256은 GitHub Releases에서 받을 수 있다.
git clone https://github.com/rp0927/korean-prose-editor.git
cd korean-prose-editor
python3 --version
python3 scripts/run_copyedit.py --help에이전트 스킬로 쓸 때는 이 디렉터리를 사용하는 프로젝트의
.agents/skills/korean-prose-editor에 복사하거나 심볼릭 링크로 연결한다. SKILL.md가 실행 지침의
진입점이다.
아래 명령은 저장소 안의 샘플을 고정 규칙만으로 처리한다. 실행 파일은 local-runs/에 남는다.
python3 scripts/run_copyedit.py tests/sample_in.txt \
--new-run \
--mode deterministic \
--purpose column \
--runs-root ./local-runs명령이 출력한 run_dir에서 final.md, summary.md, changes.json을 확인한다.
에이전트가 판단할 문장까지 다루려면 다음 상태 순서로 실행한다.
python3 scripts/run_copyedit.py draft.txt \
--new-run --mode prepare --purpose auto --runs-root ./local-runs
python3 scripts/run_copyedit.py --outdir <run_dir> --mode remaining --emit-prompt
python3 scripts/run_copyedit.py --outdir <run_dir> --mode import --edits edits.json
python3 scripts/run_copyedit.py --outdir <run_dir> --mode stamp-clean
python3 scripts/run_copyedit.py --outdir <run_dir> --mode finishedits.json은 문장 번호와 수정 결과를 담는다. yun·rule에는 줄바꿈, NUL, 양방향 제어 문자처럼
기록 구조를 흐릴 수 있는 제어 문자를 넣지 않는다.
[
{"idx": 3, "yun": "회의 결론은 금요일에 공유합니다.", "rule": "G-2"},
{"idx": 4, "rule": "변경없음"}
]| 상태 | 역할 | 주요 파일 |
|---|---|---|
prepare |
입력 복사, 분절, 규칙 힌트 생성 | segments.json, worksheet.md, remaining.json |
remaining |
미검토 목록과 작성 안내 재생성 | remaining.json, remaining-prompt.md |
import |
JSON 수정안을 워크시트에 반영 | worksheet.md |
stamp-clean |
검토했지만 수정하지 않은 문장을 명시 | worksheet.md |
finish |
재조립과 보존·완전성 검사를 수행 | final.md, summary.md, changes.json, integrity.json |
status |
현재 단계·종료 코드·오류·파일·미검토 수, 이전 finish와 실패 산출물 위치를 보고 | 표준 출력 |
전체 모드는 PROCESS.md에 정리되어 있다.
| 코드 | 뜻 |
|---|---|
| 0 | 요청한 단계 완료 |
| 1 | 문체·용어, 원문 보존, 또는 신규 플레이스홀더 검사 실패 |
| 2 | 입력, 식별자, 문장 수 또는 수정안 형식 오류 |
| 3 | 허용 범위를 넘는 변경량 |
| 4 | 검토 표시가 없는 문장 |
| 5 | 원문에 없던 제한 문자 |
- 보존 모드는 문장 수와 순서를 유지한다. 문장 재배열이 필요하면 구조 제안으로 분리한다.
- 수치, 날짜, URL, 일부 영문 식별자, 직접 인용, 인라인 코드·수식의 내용은 원문 대비 검사로 변경을 차단한다. 주변 산문은 편집할 수 있다.
- Markdown 헤딩·목록 항목·블록 인용·표·구분선·펜스 및 들여쓴 코드 블록은 구조 레코드로 분리해 바이트 단위로 유지한다.
- 이 검사는 고유명사 전체나 주장 의미를 증명하지 못한다. 최종 결과는 원문과 직접 대조한다.
- 정규식 결과는 편집 후보 신호다. 문맥에 따라 오탐과 누락이 생길 수 있다.
- 이 도구는 맞춤법 사전, 인용 출처, 법률·의학적 정확성을 검증하는 서비스가 아니다.
--allow-script는import와finish의 원문 대비 이질 문자 검사를 우회한다. 입력 언어와 의도한 변경을 확인한 경우에만 사용한다.
기본 실행 경로는 로컬 파일 시스템이다. 도구 자체는 편집 문서를 외부 서비스로 보내지 않는다.
각 run에는 입력 원문 사본과 중간 결과가 들어갈 수 있으므로 민감한 문서는 접근 권한이 제한된
디렉터리에서 처리한다. 재실행 전 결과와 실패 감사 보고는 .previous-finish/attempt-*에도 남을 수
있다. _workspace/, local-runs/, .previous-finish/, 잠금 파일, 로컬 릴리스 산출물은 Git 추적
대상에서 제외한다. 보관·잠금 해제 절차는 PROCESS.md를 따른다.
python3 -m compileall -q scripts tests
python3 scripts/validate_release.py --json
python3 -m unittest discover -s tests -p 'test*.py' -q
python3 - <<'PY'
import json
from pathlib import Path
for path in Path("references").rglob("*.json"):
json.loads(path.read_text(encoding="utf-8"))
print("JSON OK")
PYCI는 이 저장소 루트의 .github/workflows/ci.yml이 Python 3.9–3.13에서 같은 단위 테스트를
실행한다. 선택형 스킬 검증기가 제공된 환경에서는 SKILL_VALIDATOR에 해당 스크립트 경로를
지정해 추가 검사를 실행할 수 있다.
검증된 압축 파일은 다음 명령으로 만든다.
bash scripts/archive_learning_data.sh --output ./release-artifacts포함 항목은 release-files.txt가 관리한다. 스크립트는 압축을 다시 풀어 공개 검사와 전체 테스트를
통과한 경우에만 성공한다.
- 전체 테스트와 샘플 실행을 깨끗한 체크아웃에서 다시 수행한다.
python3 scripts/validate_release.py --json의findings가 비어 있는지 확인한다.- 공개 저장소 루트에서 실제 CI가 모든 지원 Python 버전을 통과했는지 확인한다.
- 비밀값, 개인 경로, 실데이터, 생성된 run이 추적되지 않았는지 확인한다.
- README, NOTICE, LICENSE, SECURITY, CONTRIBUTING의 링크와 책임 범위를 검토한다.
- 릴리스 태그와 배포 압축이 같은 검증 완료 커밋에서 만들어졌는지 확인한다.
- 다른 검토자가 교차 검토 브리프로 재현한다.
기여 절차는 CONTRIBUTING.md, 취약점 신고 방법은 SECURITY.md를 따른다. 공개 이슈에는 실제 편집 원문이나 비밀값을 올리지 않는다.