docsor1212/humanize-ai-text

Academic Style Toolkit (humanize-ai-text)

학술 및 의학 작문을 위한 이중 언어(중국어/영어) 스타일 자연화: 딱딱하고, 템플릿화되었거나 기계적인 어조 패턴을 찾아내고, 기계적 잔여물을 정리하며, 명확성과 자연스러운 표현을 위해 개정합니다 — 모든 단계에 무결성 보호 장치가 적용됩니다.

읽기 지도 (30초 라우팅; references/INDEX.md와 동일): 처음 방문 시 → 빠른 시작 · 문제 해결 → 함정 + 오류 · ci/에이전트 → 자동화 · 한계 → honest_boundaries · 시나리오 → best_practices · 심층 재작성 → deep_rewrite_guide · PDF 신뢰도 → pdf_confidence · 권한 → permissions · 프로그래밍 방식 → api. 한 줄에 두 가지 레이어: 기계적 정리(변환/파이프라인, 결정론적) vs 품질 개정(스타일 가이드별 에이전트) — 파이프라인을 먼저 실행하고, 보고서를 읽은 후, 무엇을 심층 개정할지 결정하세요.

한 줄 라우팅: 문법/유창성/저널 형식 다듬기 → 폴리셔(polisher) 사용 (paper-polisher-pro); 탬플릿 제거, 모델 잔여물 정리, AI-어조 스타일 자가 점검 및 재작성 → 이 도구 사용. 둘 다 필요? 먼저 폴리싱한 후 이 파이프라인을 실행하세요.

기능 상태 (v5.6.0)

⚠️ 행 = 실험적 (유효한 파일을 거부할 수 있음; 출력 검토 필요). 세대별 전체 기능 목록은 references/feature_status.md 로 이동했습니다. 항목별 세부 정보는 references/errors.md 및 주제 문서에 있습니다. 안정적인 주요 기능 (모두 안정, v1.0–5.6): 핵심 다섯 가지 · 섹션 인식 · 재작성 계획 · 학습된 보호 장치 · 기계 종료 코드 · 청크 저하 · 배치 재개/동시성 격리 · 파일 간 용어 변동 · 통계적 일관성 보호 · 용어 변형 그룹 · 인코딩 자동 감지 · 제출 자체 점검 번들 (--bundle) · 파이프라인 --handoff · 검증 처방 출력 · docx 쓰기 저장 · 용어 통합 시트 · EN 2026 신호 (회피 / 규칙-of-three / em-대시 밀도 / 단락 시작 표현) · 섹션별 집중 (--section) · CN 밀도 미러 (대시 과용 / 공식화된 단락 시작 표현) · 매우 큰 파일의 청크 스캔 비교 · 신호별 근거 (왜 플래그가 지정되었는지) · 일반 프로필 가중치 하향 매트릭스 (8개 구조 그룹 전체) · 배치 워크시트 + 통계 카드 · 적중 라인 번호 (모든 샘플에 L{line}) · 건강 보고서 대시보드 (번들 2.0) · CN 기능 라이브러리 v2 · handoff 라인 앵커 · 문서 개수 조정 · 대시보드 작업 체크리스트 · 번들 재작성 시트 (09) · 배치 개정 기록 · 쓰기 매니페스트 자체 증명 (00_写入清单.json) · 라인 앵커 + 근거 비교 · 인쇄 친화적 보고서 · 보호 라이브러리 내보내기/가져오기.

기능	상태	이후 버전
⚠️ PDF 직접 읽기 + 신뢰도 자체 보고 (내장 글꼴/ToUnicode 시도, "중"으로 제한됨; references/pdf_confidence.md에서 보정; v3.8.0부터 기본 게이트 = 중 — 깨진 전형적 추출은 기본적으로 거부되며, --pdf-min-confidence 低는 주석 전용 모드 복원)	⚠️ 실험적	v1.6–3.8

무결성 보호 장치 — 먼저 읽으십시오

• 허용됨: 자신의 초안 다듬기; 학교/저널에서 허용하거나 공개를 요구하는 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/연도/용어는 반드시 유지되어야 함; 변조 = exit 1 (FAIL 출력, 앵커로 수정 제시)	진실 판단 없음 — 원본 데이터가 권위입니다	verify.py
전후 비교	점수 델타 + 무결성 평결 + 프로필 차이	인간 독서를 대체할 수 없음	compare.py / stylecheck --compare
용어 일관성	8개 도메인 27개 그룹 (HF/心力衰竭/心衰를 한 행으로); --unify는 변형별 대체 횟수와 함께 통합된 초안을 생성함 (채택 전 검토)	사용 정확성 없음 — 동의어 통합만 해당	check_terms.py --pack / --unify
수치 일관성	백분율 목록 합계 (파티션 기반) / 파일 간 그룹-n / p-vs-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	pipeline/transform/compare의 -o는 경로가 .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 파일은 쓰레기 프로브에 의해 여전히 거부되며 내보내기 지침 제공. 규모: 800,000자 청크 (2,000자 오버랩) · 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 참조 —— CH 분수 단어는 영어 파일에 포함되지 않음; 숫자 일관성/용어 혼용 관련 요청은 check_stats.py / check_terms.py로 라우팅, 아래 참조) （매개변수 치트 시트는 빠른 시작에 있음; 종료 코드 테이블은 references/errors.md에 있음 — 둘 다 여기에서 연결되어 섹션을 검색하지 않도록 함)
• 명확화 (이 도구 vs 폴리셔): 「论文改写润色」 여기서는 스타일 자연화 / 탬플릿 제거 (학술 산문에서 기계적 어조 제거)를 의미합니다. 결정 규칙: 요청이 언어 정확성/유창성에만 관한 경우 폴리셔(paper-polisher-pro)로 라우팅: 「帮我改下语法」 「按期刊风格改写摘要」; 템플릿 어조 또는 모델 잔여물에 관한 경우 이 툴킷으로 라우팅: 「这篇读起来像 AI 写的」「文里有 [cite: 1] 这种残留」; 둘 다 해당하는 경우 먼저 폴리싱한 다음 이 파이프라인을 실행하십시오 — 둘 중 어느 것도 다른 것을 대체하지 않습니다.
• 용어 불일치 (약어 vs 전체 형태, 혼합 동의어) → 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 문제 발견). 장(chapter)별 원고: check_stats.py --batch 目录는 파일 간 그룹-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 무결성 실패, 파이프라인 전용); 거짓 양성 수정 → learn_guards.py from-text 术语 样本.txt; 심층 개정을 시작할 위치 → pipeline 原稿 -o 改稿 --handoff 交接块.md (단일 명령, 별도의 plan 실행 없음).
• 다중 장 용어 통일 → check_terms.py --batch 目录 (파일 간 변형 변동: 각 파일은 내부적으로 일관되지만 집합은 일관되지 않음).
• 스캔이 적법한 용어에 플래그 지정 (거짓 양성) → 패턴 파일을 편집하지 말고 대신 보호 장치를 유지: learn_guards.py from-text 术语 样本.txt (또는 add)

...