面向中文学术论文的 DOCX 结构安全修订工具——研究 AIGC 检测误判机制，保护原创文本的格式完整性与事实准确性。
This is a mixed-license research repository. See License for details.
免责声明
本项目仅供研究 AIGC 检测机制与误判修正，目标是帮助人类原创文本通过误判检测，而非掩盖 AI 代写行为。不鼓励、不支持将本工具用于规避学术诚信审查。使用者应自行遵守所在机构的学术诚信规范与相关法律要求。
国内主流 AIGC 检测工具（知网学术不端检测、维普等）对中文学术文本存在系统性误判。在实际使用中，不少人类撰写的论文初稿也会被标记为高 AI 率——尤其是绪论、相关工作、结论等壳章节，以及方法描述中的标准化表述。
误判的根本原因不是文本"太像 AI"，而是：学术写作本身的模板化结构和通用学术表达，恰好落入了检测器的训练分布。检测器被训练来识别"GPT 风格"，而标准学术写作风格与 GPT 风格高度重叠，两者很难被统计模型区分。
现有的"降 AI 率"方案大多依赖口语化替换或同义词改写，代价是破坏学术规范性。本工具的思路不同：在保持甚至提升学术严谨性的前提下，通过段落级冻结保护、结构纵深化和多模型协同改写，对误判高风险段落进行有针对性的修订。
具体来说，工具以 AIGC 检测报告为输入，自动识别误判高风险段落并进行有针对性的修订，其余低风险段落和所有结构性元素（标题、表格、图注、参考文献）保持原样不动。实现细节见下方核心设计决策。
Pipeline 分为两个阶段：初始化和处理。
初始化阶段（--init）解析原稿和 AIGC 报告，建立节点级 IR（Intermediate Representation）和冻结策略表，这一步只需执行一次。处理阶段按章节调用 LLM，完成改写→审计→修补→装配→校验的完整循环，最终输出改写后的 DOCX 文件。
graph TD
A["DOCX 原稿 + AIGC 报告 PDF"] --> B["document_parser\nreport-first 分段 + 风险标注"]
B --> C["manuscript_ir\n构建节点 IR"]
C --> D["freeze_range_resolver\n解析冻结策略\nLOCKED_EXACT / EDITABLE_BODY 等"]
D --> E["prompt_compiler\n裁剪 skill/ 规则文件\n节省约 49% prefix token"]
E --> F["LLM 改写\nGPT 系列 / GPT 系列（轻量）"]
F --> G["meta_output_checker\n正文通道防污染\nCRITICAL = 硬失败"]
G --> H["normalized_auditor\n多维度审计"]
H --> I["factual_restore_patcher\n事实数值回补"]
I --> J["arbiter\nGPT 系列（旗舰）via Responses API\n边界情况仲裁"]
J --> K["typed_patch_compiler\n生成结构化补丁"]
K --> L["structure_assembler\n装配节点 IR"]
L --> M["assembly_validator\n结构完整性校验"]
M --> N["document_renderer\n输出 DOCX / TXT"]
传统方案以文档标题作为分段主锚点，依赖字符串匹配来对齐 AIGC 报告与原稿。这个方法在标题格式不规范时容易失效，导致大量 risk=unknown 的段落无法处理。
本工具改为以 AIGC 报告的分段检测表作为主锚点，通过 Heading 1 样式段落做章节对齐，而不依赖标题字符串匹配。风险等级（high / medium / low）直接来自报告数值（≥70% 为 high，≥40% 为 medium），不经过二次推断。这消除了 risk=unknown 的根本原因，也让分段结果更贴近检测工具的实际判断边界。
冻结策略定义了管线在装配阶段对每个文档节点的处理权限，共四档：
| 策略 | 含义 |
|---|---|
LOCKED_EXACT |
完全冻结，LLM 输出不得替换此节点的文本 |
LOCKED_STRUCTURE |
结构冻结，允许轻微表述变化但不允许内容替换 |
NON_TARGET_DEFAULT_FREEZE |
非目标段落默认冻结 |
EDITABLE_BODY |
可编辑正文，发送给 LLM 改写 |
所有 structural node（heading、pseudo_heading）强制应用 LOCKED_EXACT，不进入 LLM 改写流程。pseudo_heading 的判定规则在 structure_rules.py 中以正则实现：编号式标题（^\d+(\.\d+)*\s+\S）、中文章节标题（^第[一二三四五六七八九十百]+[章节部分篇]\s*\S）、关键字型标题（讨论 / 小结 / 结论 / 前言等）均被识别。
freeze_ranges.yaml 支持 segment 级配置，用户可以针对特定段落编号范围指定策略，优先级高于自动检测结果。配置文件还记录文档指纹（SHA-256，基于首 20 个节点）和锚点文本，支持锚点漂移检测——当文档内容修改后重新运行时，系统会报告哪些冻结配置的锚点已与文档内容不匹配。
管线使用两套 LLM Provider，职责分离：
- OpenAI GPT 系列：改写器（GPT 系列 / GPT 系列（轻量））、审计器、事实修补器、仲裁器（GPT 系列（旗舰））
- 阿里百炼 DashScope Qwen 系列：风格修补器
仲裁器（arbiter）强制通过 Responses API 调用，不走 chat.completions，代码层有明确的运行时检查，如果 SDK 版本不支持 Responses API 会直接报错而不是静默降级。
两套 Provider 的隔离是有意为之：如果所有步骤都使用同一个模型，输出会带有该模型一致的风格指纹，这反而可能提高检测命中率。不同厂商模型的风格差异有助于打破输出的均质性。
具体模型版本见 .env.example 中的变量名和 CLAUDE.md 中的模型策略配置。
LLM 有时会在改写输出中混入面向用户的助手语言（"如果你愿意，我还可以……""改写如下："等），这类内容若写入论文正文将造成严重问题。
本工具在所有正文写入点前插入了 meta_output_checker，基于纯 Python 正则规则检测 7 类污染模式（助手话术、Markdown 标记、引导语等）。CRITICAL 级别的检测结果会硬阻断写入，被拒绝的输出记录到 meta_contamination_log.json，正文文件保持原有内容（或使用原文兜底）。污染检测也是 system prompt 末尾的强制规则契约（_BODY_OUTPUT_CONTRACT）的补充，两层防护相互独立。
改写规则、审计维度、领域知识以 Markdown 文档形式存放在 skill/ 目录，与代码完全分离。PromptCompiler 在初始化时一次性读取、裁剪并缓存编译结果：
- 从
humanizer-zh-core.md中移除第三、六、七部分（不影响改写行为的章节） humanizer-zh-core-control-layer-guide.md完全不进入运行时 system prompt（仅供人类阅读）- 从 domain pack 中移除适用范围、装配说明、版本兼容等非功能节
- 裁剪后节省约 49% prefix token
所有角色目前共享同一份编译后的 system prompt（v1 保守策略）。领域知识包（domain pack）以独立文件形式插件化管理，PromptCompiler 通过 glob 自动发现 humanizer-zh-*-domain-pack.md。
git clone https://github.com/AmyIvan/humanizer-zh.git
cd humanizer-zh
pip install -r requirements.txt依赖：openai>=1.50.0、python-dotenv、python-docx、PyMuPDF、tiktoken
cp .env.example .env编辑 .env，填入：
OPENAI_API_KEY=sk-...
DASHSCOPE_API_KEY=... # 风格修补器（可选，不配置则跳过风格修补步骤）
skill/ 目录提供了两个领域包：humanizer-zh-med-domain-pack.md（医学）和 humanizer-zh-cs-domain-pack.md（计算机科学）。运行时只能激活一个领域包——将不需要的那个移出 skill/ 目录或重命名（去掉 -domain-pack.md 后缀）。
PromptCompiler 在运行时通过 glob 自动发现 skill/ 下的 domain pack 文件，当前版本尚未支持运行时指定领域包。因此需要手动将不使用的领域包重命名或移出目录：
# 示例：使用计算机科学领域包，暂时禁用医学包
mv skill/humanizer-zh-med-domain-pack.md skill/humanizer-zh-med-domain-pack.md.disabledcp config/freeze_ranges.example.yaml config/freeze_ranges.yaml按照示例文件中的格式，根据你的论文段落编号修改冻结策略。也可以先不配置，--init 会自动生成建议配置供参考。
将以下文件放在项目根目录（当前工作目录）：
- 论文原稿：
.docx格式 - AIGC 检测报告：
.pdf格式（来自知网、维普等工具）
工具会自动发现目录下的 .docx 和 .pdf 文件（以 humanizer 开头的 PDF 会被忽略）。
# 第一步：解析文档，建立数据层（只需执行一次）
python run.py --init
# 第二步：查看各章节风险概览
python run.py --list
# 第三步a：处理特定章节（支持章节编号或 ID）
python run.py --chapter 3
python run.py --chapter ch03
# 第三步b：一次处理所有高风险章节
python run.py --high-risk
# 第三步c：处理全部章节并编译 typed patch
python run.py --process-all
# 查看某章节的改写结果
python run.py --show 3
# 查看 API 调用成本估算
python run.py --cost改写结果保存在 result/{chapter_id}/08_final_text.txt，完整运行流程也可以使用：
python run.py --full-run # init → process-all → assemble 一步完成humanizer-zh/
├── pipeline/ # 核心处理流程代码（Apache-2.0）
│ ├── humanizer_pipeline.py # 主管线，LLM 调用路由与章节处理调度
│ ├── document_parser.py # DOCX + AIGC PDF 解析，report-first 分段
│ ├── manuscript_ir.py # 构建节点级 IR（Intermediate Representation）
│ ├── freeze_range_resolver.py # 冻结策略解析，锚点漂移检测
│ ├── freeze_range_suggester.py# 自动生成冻结范围建议
│ ├── prompt_compiler.py # 运行时裁剪 skill/ 文件，编译 system prompt
│ ├── normalized_auditor.py # 多维度改写质量审计
│ ├── factual_restore_patcher.py# 事实数值保护与回补
│ ├── typed_patch_compiler.py # 将改写输出编译为结构化补丁
│ ├── structure_assembler.py # 将补丁装配回节点 IR
│ ├── assembly_validator.py # 装配结果完整性校验
│ ├── document_renderer.py # 输出 DOCX / TXT / TEX
│ ├── meta_output_checker.py # 正文通道防污染检测
│ ├── rewrite_patch_cleaner.py # 补丁预处理与清洗
│ ├── structure_rules.py # 共享文档结构规则（正则 + 分类逻辑）
│ ├── text_normalizer.py # 文本规范化
│ ├── freeze_object_extractor.py# 冻结对象提取
│ ├── post_assembly_validator.py# 装配后校验
│ ├── post_assembly_sonnet_review.py # 装配后复审
│ └── __init__.py
├── skill/ # 改写规则与领域知识包（CC BY-NC-SA 4.0）
│ ├── humanizer-zh-core.md # 核心改写规则（9 个部分）
│ ├── humanizer-zh-core-control-layer-guide.md # 控制层指南（仅供人工阅读）
│ ├── humanizer-zh-med-domain-pack.md # 医学领域包
│ ├── humanizer-zh-cs-domain-pack.md # 计算机科学领域包
│ └── LICENSE # CC BY-NC-SA 4.0 指引
├── config/
│ └── freeze_ranges.example.yaml # 冻结范围配置模板
├── docs/
│ └── README.md # 架构文档（待补充）
├── run.py # CLI 入口，所有用户命令从这里触发
├── CLAUDE.md # Claude Code 操作规范（CC BY-NC-SA 4.0）
├── .env.example # API Key 配置模板
├── requirements.txt # Python 依赖
├── NOTICE # 双许可证说明
├── CONTRIBUTING.md # 贡献指南
└── CITATION.cff # 引用信息
当前提供两个领域包：医学（humanizer-zh-med-domain-pack.md）和计算机科学（humanizer-zh-cs-domain-pack.md）。
由于 PromptCompiler 在运行时通过 glob 自动发现 domain pack 文件，每次运行只能激活一个领域包。后续计划支持运行时指定，目前需要用户手动管理。
Pipeline 核心流程已完成并在实际论文修订中使用，持续优化中。审计器（normalized_auditor）的评分维度和 arbiter 的仲裁规则随规则文件的更新而演进。
扩展新学科领域包只需在 skill/ 目录新增一个符合 PromptCompiler 接口规范的 Markdown 文件（包含 zone_detection_rules、template_skeleton、freeze_object、style_risk、rewrite_preference、examples 六类必需节）。
本仓库采用双许可证结构：
| 范围 | 许可证 |
|---|---|
pipeline/、run.py、requirements.txt、.gitignore、.env.example、config/*.example.yaml、README.md、NOTICE、CONTRIBUTING.md、CITATION.cff、docs/README.md、skill/LICENSE |
Apache License 2.0 |
skill/*.md、CLAUDE.md |
CC BY-NC-SA 4.0 |
完整说明见 NOTICE。
如果本项目对你的研究有帮助，欢迎引用：
@software{ai_yuming_2026_humanizer_zh,
author = {Ai, Yuming},
title = {humanizer-zh},
year = {2026},
version = {1.0.0},
url = {https://github.com/AmyIvan/humanizer-zh},
abstract = {A DOCX structure-safe revision tool for Chinese academic papers ---
researching AIGC detection false-positive mechanisms and protecting
the formatting integrity of human-authored texts.}
}