docsor1212/paper-polisher

Paper Polisher Pro

AI写作检测（面向作者的AI率自查）·学术润色指导 · 术语标准化 · 翻译腔检测 · 质量报告 · AIGC合规标签检查 · 段落级归因 · 期刊预检。 100%本地运行，零上传，零凭据，纯标准库（可选 onnxruntime 增强层）。

⛔ 铁律

1. 仅报告可复现的指标。 所有指标均来自 eval/run_eval.py 中保留的测试集评估结果；诸如“100%检测率 / F1 98.3%”等未经支持的声明已从旧文档中移除。
2. 不对短文本做出判定。 短于100字符的文本返回 risk=unknown（社区经验：短文本假阳性不可控）。
3. 指纹仅用于归属，从不评分。 （2026-08-15测量：向检测器注入指纹会使人工假阳性翻倍。）
4. 校准/评估分离。 频谱、权重和阈值仅基于校准半集构建；测试半集保留用于最终评估（样本内AUROC 0.9972在拆分后实际降至0.9187）。

概要

• 功能：100%本地AI率自查 + 中文/英文学术文本润色工具包（可选监督模型以获得最佳准确率）；英文文本仅给出咨询性规则评分。
• 30秒快速上手：python3 scripts/pp.py quickstart（零模型、零文件演示）· python3 scripts/pp.py detect draft.txt --format json · 句子级改写建议：python3 scripts/pp.py fix draft.txt · 完整自查报告：python3 scripts/pp.py workflow draft.txt · 环境检查：python3 scripts/pp.py doctor（单一入口路由所有子命令）
• 实测数据（保留测试集，指纹md5 2631df3d388b）：2026年前AUROC 0.9998 / 当前世代0.9400；人工FPR@medium 2.3%。
• 了解限制：文本<100字符返回 risk=unknown · 降级模式下医学文本评分偏高 · 混合人机文档：文档级评分不可靠（段落归因是可行信号）· 仅限作者自查——切勿用于规避机构AI检测。
• 下一步：场景实践指南见 references/best-practices.md · 下方能力边界矩阵 · 端到端示例见 § 快速开始 · FAQ分五组排列（判定→模式与安装→输出与解读→安全与验证→工具与工作流），跳转至所需组 · 完整历史见 CHANGELOG.md。

30秒任务路由

您想…	运行	详细文档
检查草稿AI率	pp.py detect draft.txt --format json	§ 实测性能 + 下方边界矩阵
查看哪些句子像AI写的	pp.py fix draft.txt	pp_fix_suggest.py --help
比较改写前后	pp.py rewrite-check orig.txt rev.txt	FAQ：改写建议
保持布局翻译PDF	pp.py bundle 不可用——请用doc-holmes	相关工具
检查写作惯例	pp.py norm draft.txt	FAQ：风格规范
批量处理整个论文文件夹	ai_detector.py --batch DIR --csv s.csv --report r.html	FAQ：批量CSV
验证零上传声明	pp.py verify + pp.py test	安全声明
期刊预检（学科上下文）	ai_detector.py draft.txt --profile journal	§ 期刊预检
环境故障排除	pp.py doctor / pp.py freshness --status	FAQ：模式
所有结果一站式可视化仪表板	pp.py html-report draft.workflow.json -o report.html	脚本速查表：pp_report_html.py
追踪多轮改写中的草稿	pp.py trend 轮次目录/ -o trend.html	脚本速查表：pp_trend.py
不确定哪个命令适合？	pp.py recommend "把这段的AI率降一降"	pp.py recommend --help

最重要的三个限制（完整细节见下方矩阵）

1. 降级模式下医学文本评分偏高——仅规则模式下人工FPR@medium ≈59%医学文本 vs ≈2%通用文本；医学文本仅信任@high判定，或安装监督模型。
2. 混合人机文档——文档级AUROC 0.52-0.54（固有平均限制）；使用段落归因作为人工审查排序依据，切勿用作自动判定。
3. 数据覆盖范围——术语库包含2,344个医学/学术术语（非医学文本标准化率偏低属设计特性）；风格层校准基于学术散文（口语化/叙述性输入仅提供咨询性建议）。每个子工具的范围：见下方子工具矩阵。

学术诚信

本工具旨在帮助作者自我审阅并提升自身写作质量——更清晰的句子、一致的术语、自然的风格。它不应用于规避机构AI检测系统，且不得用于将AI生成的作品伪饰为人类撰写。请遵循您所在机构的AI使用和披露政策；捆绑的 aigc_label_check.py 旨在帮助您合规地满足披露和标签要求（例如中国2025年9月的标签规定）——正确声明AI辅助，而非隐藏。每份AI风险报告（ai_detector.py / deai_gate.py）均附带显式的 integrity_notice。

实测性能（C-ReD + DetectRL-ZH，保留测试半集，n=5,251）

语料范围说明（v4.8.0）：下方v3.0时代的表格基于完整保留测试半集（n=5,251）测量。捆绑的示例语料为其子集——其测试半集为n=1,304；可复现的每个语料指标：仅规则模式（PP_NO_SUP）0.8985（旧代）/ 0.7149（当前代），融合模式0.9998 / 0.9400（eval/results/v480_rules_*.json、v35ctl_*.json；缓存键同时绑定模型指纹和引擎模式）。

指标	v2.0基线	v3.0规则+频谱	v3.1 +监督	v3.4 监督（版本时代记录，现行为下方重测行）
AUROC（测试半集）	0.7046	0.9187	0.9997	1.0
TPR@FPR5%	30.4%	49.0%	99.95%	100%
TPR@FPR1%	16.7%	24.9%	99.88%	100%
人工FPR@校准p99	未测量	未测量	3.56% (30/844)	0.71% (6/844)
释义/混合攻击AUROC	0.64	0.89	1.0（语料内）	1.0
“AI辅助”攻击召回率	—	—	71.1%	86.6%
域外朴素叙述/电影召回率	—	—	1/6	5/6仅监督 · 6/6本地融合

v4.4.0指纹绑定重新测量 已部署监督模型（md5 2631df3d388b）：AUROC 0.9998（测试半集，n_base=927），TPR@FPR1% 99.4%，人工FPR@medium 2.3%——eval/results/v35ctl_oldgen.json。上方各列保留为版本时代记录（早期模型谱系；v4.4.0之前二机制未进行指纹绑定）。

哪列适用于您？（精度导航：唯一可引用的当前基线是 eval/results/CURRENT.md 中的 v35ctl_* 文件；左侧列是版本时代记录。）基础包运行v3.0规则+频谱引擎（AUROC 0.9187列，基于完整保留语料测量；v4.4.0之前的存档基线先于指纹绑定——自v4.4.0起，每个评估结果均携带部署模型的md5作为 model_fp，当前绑定数据见 eval/results/v35ctl_*.json）。右侧两列需要可选的本地监督模型（见下文）。引擎会诚实地告知您当前所处模式：当监督层缺失或跳过时，每份报告均携带 degraded_mode / degraded_notice。

能力边界矩阵（信任任何检测器前务必阅读）

场景	行为
中文学术散文，全栈	最佳情况（AUROC 0.9998保留测试集，人工FPR@medium 2.3%——v4.4.0指纹绑定）
无模型的基础包	规则+频谱（0.9187）；医学文本评分偏高（仅规则模式下人工FPR@medium：~59%医学 vs ~2%通用）→ 医学文本仅信任@high判定
英文文本	语言门控默认跳过针对中文训练的监督层；仅规则英文框架，仅供咨询性参考
混合人机文档	文档级AUROC 0.52-0.54（固有平均限制）；段落级AUROC 0.69，校准最佳工作点 P=0.60 覆盖63%（references/para_thresholds.json）——低于自动判定门槛；仅使用 pp_workflow.py/paragraph_report.py 的排序结果供人工审查
编辑程度回归头	ρ=0.540——仅作为元数据报告，从不用于判定
当前世代模型（2026-09采样）	AUROC 0.9400（v4.4.0指纹绑定重新测量，443文档当前代评估集：9个模型族，包括K3/K2.7/Qwen3.7-3.8/DS-V4/V4.1/GLM-5.3/M3）vs 2026年前保留测试集0.9998——存在适度但经验证的差距。此前0.6542 vs 0.9022的数据为测量伪影（过期得分缓存重放+未验证模型谱系）；自v4.4.0起两类错误均被结构性避免（每个结果JSON中均包含model_fp）
口语化/口述文本	风格层校准基于学术散文；该领域之外风格评分仅提供咨询性建议

子工具范围矩阵（每个子工具的校准领域）

子工具	校准领域	领域外行为
ai_detector / deai_gate	中文学术散文（保留测试集校准）	降级模式下医学文本评分偏高；英文仅咨询性规则；叙述性/口语化输入附注注册令
paragraph_report / pp_rewrite_check	与上述引擎标准相同，按段落处理	相同限制；rewrite_check在相同标准下比较两个草稿
pp_fix_suggest	中文AI写作模式库（学术范畴）	英文文本仅执行基本连接词/节奏检查；发现结果为风格观察，非检测
term_check	中文医学/学术术语（2,344词条库）	非医学文本：标准化率读数偏低——此为词库范围，非错误；--auto-fix 遵循上下文
translation_smell_check	中文学术散文（翻译模式）	英文风格源文本：输出列出其盲点术语，而非假装覆盖
style_distance	学术散文文体测量	学术范畴之外风格评分仅提供咨询性建议（输出中已声明）
style_norm	机械惯例——范畴独立	设计上无评分；统计检查（数字/缩写）在短样本上较弱，并会在输出中声明
aigc_label_check	文件元数据 / C2PA / 显式标签声明	非内容检测器；验证标签合规性，而非作者身份
quality_report	手稿的可读性/质量维度	非AI率测量；评分启发式算法为通用型，未针对期刊调优
docx_text	.docx文本提取（保留段落）	非PDF转换器——PDF文件将被拒绝并附带转换建议（无法保证零依赖的中文PDF提取）
批处理模式（--batch）	.txt/.md/.docx 每文件<5 MB	大于5 MB默认跳过；加密/纯图片docx返回显式错误，而非静默空输出

安全与行为声明

• 100%本地运行：所有功能均在设备上执行。代码库不进行任何出站网络调用——无网络客户端库，无网络工具。唯一具备监听能力的组件是可选的MCP HTTP形式（--transport http），其绑定127.0.0.1回环地址（由AST验证器的允许列表规则强制要求）；AST扫描将任何未绑定回环的监听器视为违规。结构性验证方法：python3 scripts/pp_verify.py（AST级扫描；退出码0 = 零网络调用，所有脚本编译通过）。传统文本grep grep -rEin "urllib|requests|socket|import http" scripts/ 可能在报告页脚显示少量URL字符串——这些是字符串常量中的数据，而非网络代码；AST验证器可区分两者。
• 无上传、无凭据：不读取或传输任何凭据、密钥或个人数据；仅有的两个环境变量是 PP_NO_SUP（跳过监督层）和 PP_LANG（en 将 pp.py 入口界面切换为英文）——均为本地行为开关。
• 无持久化：不创建任何计划任务、自启动项或系统配置更改；临时文件（层间JSON、探测文本）使用后删除。
• 无远程代码：不加载任何远程模型或脚本；可选的监督模型由用户放置在本地路径。
• 数据边界：仅读取/写入用户指定的文件、系统临时目录及其自身包数据目录（校准/新性度工件）；报告仅输出到用户指定的位置。
• 学术诚信：参见上方章节——用于作者自我审阅和质量改进，并合规披露；不用于规避检测。

退出码契约（自v5.8.0起稳定）

退出码	含义	典型情况
0	成功	报告生成 · verify零网络通过 · test套件全绿
1	已运行但未通过	引擎运行时失败（消息中附恢复建议）· test失败 · verify漂移 · freshness基线漂移
2	用法或输入错误	未知子命令 · 文件缺失 · 文本不足100字符 · 输入文件无法解析
3	环境未就绪	pp_setup.py 模型安装/验证失败——先运行 pp.py doctor

编程镜像：pp_api 对无效输入抛出 ValueError（↔ 退出码2），对运行时失败抛出 RuntimeError（↔ 退出码1），两者均在消息中携带恢复建议。这些代码是稳定性承诺——未来版本不会重新赋予其他用途。

反模式（每种附正确做法）

本节仅列出判断型规则（不该做什么）；操作性问题请参见 references/faq.md（可通过 pp.py faq <关键字> 搜索）——两者相互引用而非重复。

• 不要输入<100字符并期待判定——risk=unknown 是设计特性（短文本假阳性不可控）。✅ 正确做法：提交至少300字符，或使用风格规范检查（pp.py norm），该检查无判定且适用于短样本。
• 不要信任降级模式下医学文本的评分