Academic Style Toolkit (paper-rewriter)
이중 언어 (중국어/영어) 스타일 자연화 도구: 학술 및 의학 작문에서 경직되거나 템플릿화된 기계적 패턴을 발견하고, 기계적 잔여물을 정리하며, 명확성과 자연스러운 어조를 위해 교정합니다. 모든 단계에 무결성 가드레일이 적용됩니다. 읽기 지도 (30초 라우팅; references/INDEX.md와 동일): 처음 사용자 → 빠른 시작 · 문제 해결 → 함정 + 오류 · CI/에이전트 → 자동화 · 한계 → 정직한_경계 · 시나리오 → 모범_사례 · 심화 교정 → deep_rewrite_guide · PDF 신뢰도 → pdf_confidence · 권한 → permissions · 프로그래매틱 → api. 한 줄에 두 계층: 기계적 정리 (transform/pipeline, 결정적) vs 품질 교정 (스타일 가이드 기반 에이전트) — 파이프라인을 먼저 실행하고, 보고서를 읽은 후 심화 교정할 부분을 결정하세요.
한 줄 라우팅: 문법/유창성/저널 형식 다듬기 → (paper-polisher-pro)를 사용하세요; 비템플릿화, 모델 잔여물 정리, AI 어감 스타일 자가 점검 및 재작성 → 이 도구를 사용하세요. 둘 다 필요하다면? 먼저 다듬기를 하고, 그 다음 이 파이프라인을 실행하세요.
기능 상태 (v5.6.0)
⚠️ 행 = 실험적 기능 (유효한 파일을 거부할 수 있음; 출력을 검토하세요). 생성별 전체 기능 목록은 references/feature_status.md로 이동했습니다; 항목별 세부 사항은 references/errors.md 및 주제 문서에 있습니다. 안정적인 주요 기능 (v1.0–5.6 모두 안정): 핵심 다섯 가지 · 섹션 인식 · 교정 계획 · 학습된 가드 · 기계 종료 코드 · 청크 저하 · 배치 재개/동시성 격리 · 파일 간 용어 표류 · 통계적 일관성 가드 · 용어 변형 그룹 · 인코딩 자동 감지 · 제출 자가 점검 번들 (--bundle) · 파이프라인 --handoff · 처방 출력 검증 · docx 쓰기 · 용어 통합 시트 · EN 2026 신호 (헤지/3의 법칙/em-대시 밀도/단락 시작 표현) · 섹션별 집중 (--section) · CN 밀도 미러 (대시 과용/공식적 단락 시작 표현) · 매우 큰 파일에 대한 청크 스캔 비교 · 신호별 근거 (플래깅 이유) · 일반 프로필 가중치 하향 행렬 (8개 구조 그룹 전체) · 배치 워크시트 + 통계 카드 · 적중 줄 번호 (모든 샘플에 L{줄번호}) · 건강 보고서 대시보드 (번들 2.0) · CN 기능 라이브러리 v2 · 인계 줄 앵커 · 문서 수 조정 · 대시보드 작업 체크리스트 · 번들 교정 시트 (09) · 배치 교정 기록 · 쓰기 매니페스트 자체 증명 (00_写入清单.json) · 비교 줄 앵커 + 근거 · 인쇄 친화적 보고서 · 가드 라이브러리 내보내기/가져오기.
| 기능 | 상태 | 도입 시점 |
|---|---|---|
⚠️ PDF 직접 읽기 + 신뢰도 자체 보고 (내장 글꼴/ToUnicode 시도, "중"으로 제한; 보정은 references/pdf_confidence.md; 기본 게이트 = v3.8.0부터 "중" — 왜곡된 전형적 추출은 기본적으로 거부, --pdf-min-confidence 저는 주석 전용 복원) | ⚠️ 실험적 | v1.6–3.8 |
무결성 가드레일 — 먼저 읽기
- 허용: 자신의 초안 다듬기; 학교나 저널이 허용하거나 AI 사용 공개를 요구하는 경우 AI 지원 텍스트를 자신의 어조에 맞추기; 합법적으로 공개된 초안에서 모델 잔여물 (불량
oaicite/[cite:]토큰) 정리; 공식 산문의 명확성, 리듬 및 구체성 개선. - 허용되지 않음: 이 도구 키트를 사용하여 저자 신분을 허위로 표시하거나, 공개가 필요한 경우 AI 사용을 은폐하거나, 학술 무결성 검토를 회피하는 행위. 요청이 "검토자가 알 수 없도록 다시 작성해 달라"는 방식으로 구성된 경우, 해당 요청을 거부하고, 공개 의무를 설명하며, 대신 합법적인 품질 편집 경로를 제공하십시오. 이 스킬을 실행하는 에이전트는 이 기준을 적용해야 합니다.
- 이 도구는 데이터를 절대 변경하지 않습니다: 숫자, p-값, 신뢰 구간, DOI, PMID, 연도 및 용어는
verify.py에 의해 보호됩니다 (아래 참조). 개선된 산문은 사실을 희생해서는 안 됩니다. - 준수: 중국의 AIGC 라벨링 규칙 (2025-09-01 발효), 저널 공개 정책 및 arXiv 정책은
references/compliance.md에 요약되어 있습니다 — 공개 의무는 저자에게 있으며 도구에 있는 것이 아닙니다.
기능 × 경계 (업무 분담 + 한계 + 위치)
| 기능 | 수행 | 수행하지 않음 (경계) | 위치 |
|---|---|---|---|
| 스타일 자가 점검 | 휴리스틱 보고서: 상투적 표현 밀도, 리듬 균일성, 공식적 어조; 섹션 인식 | AI 감지기가 아님 — 유창한 모델 텍스트에서 거의 트리거되지 않음 (낮은 점수 ≠ AI 없음) | detect.py; honest_boundaries 참조 |
| 기계적 정리 | 모델 잔여물 (oaicite/[cite:]), 채팅 군더더기, 구두점 정규화, 전각 숫자 | 문장 재작성 없음 — 정보 손실이 없는 레이어만 | transform.py (--deep는 문장 수준) |
| 품질 심화 교정 | 비템플릿화 / 리듬 / 구체성 / 입장 (일곱 단계) | 데이터 절대 생성하지 않음; 생성된 숫자는 플래깅됨 (W_NUM_ADDED, 사람이 제거) | 사용자 (에이전트) 가 스타일 가이드 따라; plan --handoff를 통한 인계 |
| 무결성 가드 | 숫자/DOI/PMID/연도/용어는 반드시 유지되어야 함; 위반 시 종료 코드 1 (FAIL 출력이 앵커와 함께 수정 사항을 제시) | 진실 판단 없음 — 원본 데이터가 권위 | verify.py |
| 전/후 비교 | 점수 델타 + 무결성 판결 + 프로필 차이 | 사람이 읽는 것을 대체하지 않음 | compare.py / stylecheck --compare |
| 용어 일관성 | 8개 도메인 27개 그룹 (HF/心力衰竭/心衰 한 행); --unify는 변형별 대체 횟수와 함께 통합된 초안을 생성 (채택 전 검토 필요) | 사용 정확성 평가 없음 — 동의어 통합만 | check_terms.py --pack / --unify |
| 숫자 일관성 | 백분율 목록 합계 (파티션 기준) / 파일 간 group-n / p-대-P 스타일 | 통계 검토 아님 — 원본 데이터가 권위 | check_stats.py (--batch) |
빠른 시작
일상적인 표현으로 요청하는 방법 (SKILL_ZH.md의 전체 구문 표를 영어로 요약): "이 논문에서 AI 어감 제거" / "너무 템플릿처럼 읽힌다" / "oaicite와 [cite:] 잔여물 정리" / "먼저 수정할 문장을 알려줘" / "내 수정이 숫자를 망가뜨리지 않았는지 확인" / "스타일 프로필을 보여줘" / "이 합법적인 용어에 플래그를 중지" — 각각 파이프라인, plan.py, transform.py, verify.py+compare.py, stylecheck.py, learn_guards.py에 매핑됩니다.
에이전트는 필요하지 않습니다 — 아래의 모든 기능은 터미널에서 직접 실행됩니다.
모든 스크립트에는 내장 --help (전체 플래그 참조) 및 --version이 있습니다;
빠른 플래그 의미:
| 플래그 | 의미 |
|---|---|
--profile general | 비학술 텍스트: 공식적/상투적 신호 가중치 하향 |
--deep | 결정적 문장 수준 변환 (상투적 시작 표현, 단순 병합 아님) |
--exit-verdict | CI/에이전트 게이팅을 위한 기계 종료 코드 (아래 참조) |
--structure | 섹션 인식 점수 (IMRaD) |
--step-timeout SEC | 단계별 최대 시간 (기본 120초) |
--terms FILE | 무결성 가드를 위한 용어 목록 (extract_terms.py로 구축) |
--unify SHEET | check_terms: 용어 통합 초안 생성 (v4.4.0; 권고 사항 — 대체 목록 검토) |
--section abstract | detect: 단일 섹션 격리 진단 (v4.5.0; 초록은 리뷰어가 가장 먼저 읽는 부분) |
-o revised.docx | -o가 pipeline/transform/compare에서 경로가 .docx로 끝나면 Word 파일 작성 (v4.4.0, 일반 단락; 복잡한 레이아웃은 수동으로 병합) |
한 번의 명령 (자가 점검 → 정리 → 교정 요약 → 무결성 가드):
python scripts/pipeline.py draft.txt -o out.txt --terms terms.txt
- 시각화 / 배치:
--html report.html을 detect/pipeline/compare에 추가하면 자체 포함 보고서 생성 (compare는 문장 수준 차이 추가);--batch dir은 전체 디렉토리 스캔 (pipeline은 CSV 작성; 배치-o요약은 CSV로 유지 — 테이블에 대한 docx 쓰기 없음); pipeline/transform/compare에서-o가.docx로 끝나면 Word로 작성 (v4.4.0, 일반 단락 —.docx직접 읽기와 루프 종료; 표/이미지/스타일은 재구축되지 않음, 복잡한 레이아웃은 수동으로 병합). - 섹션 인식:
detect --structure는 초록/서론/방법/결과를 개별 점수화; 방법/결과 표현은 장르 관습 — 집계에서만 정규화되며, 원시 섹션별 점수는 항상 표시됨. - 교정 계획:
plan.py draft -o plan.md는 문장 순위 (P0 대기열 + 예산 예측);--handoff를 추가하면 문장별 작업 시트 생성. - 입력:
.txt/.md직접 (UTF-8/UTF-16〔BOM 포함〕/GBK 자동 변환, v4.0),.docx직접, PDF 실험적 (기본 안전 게이트 = v3.8부터 중;저는 주석 전용 복원; references/pdf_confidence.md). - 용어 목록:
python scripts/extract_terms.py draft.txt -o terms.txt(수동 확인); 모든 실행은--suggestions path.md로 교정 워크시트를 받을 수 있음. - 비학술 텍스트:
--profile general을 추가하여 공식적인 상투적 표현의 가중치를 낮춤.
또는 개별 단계 실행 (스킬 자체 디렉토리에서 또는 절대 경로 사용):
python scripts/detect.py draft.txt # 스타일 패턴 자가 점검 (-j JSON, -s 점수만)
python scripts/transform.py draft.txt -o step1.txt
# ... 스타일 가이드에 따라 step1.txt의 에이전트 품질 교정 ...
python scripts/verify.py draft.txt step2.txt --terms terms.txt
python scripts/compare.py draft.txt step2.txt
시나리오별 모범 사례 (저널 투고, 학위 논문, 수정 답변, 배치, CI 게이트, 오탐 처리, 중국어 구두점): references/best_practices.md.
전체 예제: references/examples.md. 통합 종료 코드, 위반 범주 및 해결 방법: references/errors.md. 중앙 집중식 일반 실수 목록 (27개 항목): references/pitfalls.md — 첫 실제 실행 전에 읽으십시오. Python API 참조: references/api.md. FAQ: references/faq.md.
- 수정 추적:
--track base는 모든 기계 레이어 변경 사항을base.md+base.json에 기록 (감사 가능: 규칙, 횟수, 삭제된 문장, 플래깅). - PDF (실험적): v3.0.0부터 내장 글꼴/ToUnicode를 포함한 텍스트 PDF — 추출 시도, 신뢰도는 "중"으로 제한되며 스팟 체크 노트 제공; CJK CID 파일은 여전히 가비지 프로브에 의해 내보내기 지침과 함께 거부됨. 규모: 800K자 청크 (2K 중복) · 50MB 한도 · 전체 문서 무결성 가드.
에이전트 호출 프로토콜
호출 시, 먼저 경로를 결정한 다음 실행하십시오:
- 트리거 단어: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 / 学术改写 / 段落改写 / 表达优化 / style self-check / style naturalization / naturalize academic writing / de-templating / academic rewriting / passage rewrite / expression polish / translationese cleanup (= 유럽화된 구문: 중첩된 수동태, 명사화 체인, 긴 관형어 — style_guide_en 1/3단계 참조) / make my writing sound less machine-written / reduce the templated tone / clean up model residue or stray citation tokens / fix stiff formal prose / polish my draft for submission without changing the data / check that numbers and citation IDs survived editing → 위 파이프라인을 실행하십시오. (중국어 변형 트리거 단어는 SKILL_ZH.md에 있음——중국어 어감 단어는 영어 파일에 들어가지 않음; 숫자 일관성/용어 혼용 요청은 check_stats.py / check_terms.py로 라우팅, 아래 참조) (매개변수 치트 시트는 빠른 시작에, 종료 코드 테이블은 references/errors.md에 있습니다 — 둘 다 섹션 간 검색을 피하기 위해 여기에서 연결됨.)
- 명확화 (이 도구 vs 다듬기 도구): 「论文改写润色」는 여기서 스타일 자연화 / 비템플릿화 (학술 산문에서 기계적 어감 제거)를 의미합니다. 결정 규칙 — 언어 정확성/유창성에 관한 요청 (「帮我改下语法」「按期刊风格改写摘要」)은 다듬기 도구(paper-polisher-pro)로 라우팅; 템플릿화된 어조나 모델 잔여물에 관한 요청 (「这篇读起来像 AI 写的」「文里有 [cite: 1] 这种残留」)은 이 도구 키트로 라우팅; 둘 다에 해당하면 먼저 다듬기를 한 후 이 파이프라인을 실행하십시오 — 둘 중 하나가 다른 하나를 대체하지 않습니다.
- 용어 불일치 (약어와 전체 형태, 혼합된 동의어) →
check_terms.py file --pack <domain>; 통합 초안을 직접 생성하려면--unify output.txt추가 (각 그룹을 지배적 변형으로 통합, 변형별 대체 횟수 표시 — 권고 사항 출력, 채택 전 검토 후 verify 실행; v4.4.0);--list-packs는 8개 도메인 팩 모두 표시 (v3.0.0). - 일치하지 않는 숫자 (백분율 목록 합계 100% 불일치, 동일 그룹에 서로 다른 n, p/P 스타일 혼합) →
check_stats.py file(v3.2.0; 종료 코드는 check_terms와 일치: 0 일관 / 1 문제 발견). 장으로 나뉜 원고:check_stats.py --batch 디렉토리는 파일 간 group-n 집계 (초록-방법 불일치, v3.3.0). 또는 한 번에 모두 실행:pipeline.py draft --check-stats. - 사용자가 무엇을 먼저 수정할지 알고 싶어 함 →
plan.py draft.txt -o plan.md(P0 문장 대기열 + 예산 예측);--handoff를 추가하여 문장별 지침 시트 생성 (가드 + 수락 명령, v3.0.0). - 사용자가 수정의 정량적 수락을 원함 →
stylecheck.py 원본 수정본 --compare(v2.6.0 스타일 프로필 델타; 트리거: 风格画像 / 量化验收 / 深改验收 / style profile / acceptance check). - 배치 실행이 중단됨 (Ctrl-C / 정전 / 시간 초과) →
--batch 디렉토리 --resume로 다시 실행 (완료된 파일 건너뜀; 변경되었거나 이전에 실패한 파일은 자동으로 다시 실행; 진행 상황은 배치 디렉토리의 .pr_batch_state.json에 저장). - 시나리오 단축키 (v3.8.0 통합): CI/배치 게이팅 →
--exit-verdict(--ci별칭; 0 깨끗함 / 3 심화 교정 / 4 잔여물 / 1 무결성 실패, pipeline 전용); 오탐 수정 →learn_guards.py from-text 용어 샘플.txt; 심화 교정 시작 위치 →pipeline 원본 -o 수정본 --handoff 인계블록.md(한 명령, 별도 plan 실행 불필요). - 다중 장 용어 통일 →
check_terms.py --batch 디렉토리(파일 간 변형 표류: 각 파일은 내부적으로 일관되지만, 세트는 일관되지 않음). - 스캔이 합법적인 용어에 플래그를 지정함 (오탐) → 패턴 파일을 편집하지 말고, 대신 가드를 유지하십시오:
learn_guards.py from-text 용어 샘플.txt(또는add) — 가드는 저장
…
[번역을 위해 잘림]