docsor1212/paper-rewriter

学术风格工具集 (paper-rewriter)

面向学术与医学写作的双语（中/英）风格自然化工具：发现生硬、模板化或机器味表达，清理机械残留，提升清晰度和自然语感——每一步都带有完整性防护。 阅读路标（30秒定位；等同于 references/INDEX.md）：首次使用 → 快速开始 · 故障排查 → 陷阱与错误 · CI/智能体 → 自动化 · 限制 → 诚实边界 · 场景 → 最佳实践 · 深度改写 → deep_rewrite_guide · PDF 置信度 → pdf_confidence · 权限 → permissions · 程序化调用 → api。 一行中的两层：机械清理（transform/pipeline，确定性）与质量修订（按风格指南的智能体）——先运行pipeline，阅读报告，再决定哪些需要深度修订。

一行路由：语法/流畅度/期刊格式润色 → 使用润色工具（paper-polisher-pro）；去模板化、模型残留清理、AI风格自查和改写 → 使用本工具。两者都需要？先润色，再运行本pipeline。

特性状态 (v5.6.0)

⚠️ 行 = 实验性（可能拒绝有效文件；需复查输出）。完整每代能力列表已迁移至 references/feature_status.md；逐项细节见 references/errors.md 和主题文档。稳定版亮点（全部稳定，v1.0–5.6）：核心五项 · 章节感知 · 改写计划 · 学习型防护 · 机器退出码 · 分块降级 · 批量恢复/并发隔离 · 跨文件术语漂移 · 统计一致性防护 · 术语变体组 · 编码自动检测 · 投稿自查包（--bundle） · 管道 --handoff · 验证处方输出 · docx 回写 · 术语统一表 · EN 2026 信号（模糊语 / 三分法 / 破折号密度 / 段落开头） · 按节聚焦（--section） · CN 密度镜像（破折号过度使用 / 公式化段落开头） · 大文件分块扫描对比 · 每信号理由（为何标记） · 通用文档降权矩阵（全部8个结构组） · 批处理工作表 + 统计卡 · 命中行号（每个样本上的 L{行}） · 健康报告仪表板（bundle 2.0） · CN 特征库 v2 · 交接行锚点 · 文档计数对账 · 仪表板行动清单 · bundle 改写表（09） · 批量修订记录 · 写入清单自证（00_写入清单.json） · 对比行锚点 + 理由 · 友好打印报告 · 防护库导出/导入。

能力	状态	起始版本
⚠️ PDF 直接读取 + 置信度自报告（尝试内嵌字体/ToUnicode，置信度上限为"中"；校准见 references/pdf_confidence.md；自 v3.8.0 起默认阈值为"中" ——典型乱码提取被默认拒绝，--pdf-min-confidence 低 可恢复到仅注释模式）	⚠️ 实验性	v1.6–3.8

完整性防护 — 请先阅读

• 允许的行为：润色自己的草稿；在您的学校或期刊允许或要求披露AI辅助的前提下，将AI辅助文本与您的风格对齐；清理合法披露草稿中的模型残留（零散的 oaicite/[cite:] 标记）；提升正式学术写作的清晰度、节奏和具体性。
• 不允许的行为：使用此工具集来歪曲作者身份、在要求披露AI使用的场合隐瞒AI使用，或试图规避学术诚信审查。如果请求被这样表述（"改写一下，让审核看不出来"），请拒绝该表述，解释披露义务，并提供合法的质量编辑路径。执行此技能的AI代理应强制执行此界限。
• 本工具绝不变更数据：数字、p值、置信区间、DOI、PMID、年份和术语由 verify.py 保护（见下文）。改进的行文绝不能以事实为代价。
• 合规性：中国AIGC标注规则（2025年9月1日生效）、期刊披露政策和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值 vs P值样式	不是统计学审查——原始数据是权威依据	check_stats.py（--batch）

快速开始

如何用简单语言请求（SKILL_ZH.md中完整短语表的中文摘要）：“帮我去掉这篇论文的AI味” / “这篇读起来太模板化了” / “清理 oaicite 和 [cite:] 残留” / “告诉我先改哪些句子” / “检查改写有没有破坏数字” / “给我一个风格画像” / “别再标记这个合法术语”——分别映射到 pipeline、plan.py、transform.py、verify.py+compare.py、stylecheck.py 和 learn_guards.py。无需AI代理——以下所有能力均可直接在终端运行。每个脚本都内置了 --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

• 可视化 / 批量处理：在 detect/pipeline/compare 上使用 --html report.html 可生成独立报告（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。常见问题解答：references/faq.md。

• 修订追踪：--track base 将每个机械层的更改记录到 base.md 和 base.json（可审计：规则、计数、删除的句子、标记）。
• PDF（实验性）：自 v3.0.0 起支持文本PDF，包括内嵌字体/ToUnicode——尝试提取，置信度上限为"中"并附带抽查说明；CJK CID 文件仍被垃圾探测拒绝，并提供导出指导。规模：800K字符分块（2K重叠）·50MB上限·全文档完整性防护。

智能体调用协议

被调用时，先决定路径，再执行：

• 触发词：写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 / 学术改写 / 段落改写 / 表达优化 / style self-check / style naturalization / naturalize academic writing / de-templating / academic rewriting / passage rewrite / expression polish / translationese cleanup (= Europeanized syntax: stacked passives, nominalization chains, long attributives — see style_guide_en steps 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 → 运行上面的 pipeline。（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件；数字自洽/术语混用类请求路由到 check_stats.py / check_terms.py，见下）（参数速查表在快速开始；退出码表在 references/errors.md——两者均从此处链接，避免跨节查找。）
• 歧义消除（本工具 vs 润色工具）：「论文改写润色」在此指风格自然化/去模板化（从学术散文中去除机器味）。决策规则——当要求仅涉及语言正确性/流畅度时路由到润色工具（paper-polisher-pro）：「帮我改下语法」「按期刊风格改写摘要」；当涉及模板化语气或模型残留时路由到本工具：「这篇读起来像 AI 写的」「文里有 [cite: 1] 这种残留」；两者都适用时，先润色，再运行本 pipeline——两者不可相互替代。
• 术语不一致（缩写 vs 全称、混用同义词）→ check_terms.py file --pack <domain>；要直接输出统一草稿，添加 --unify output.txt（每组统一为优势变体，显示每种变体的替换计数——咨询性输出，采用前请复查，然后运行 verify；v4.4.0）；--list-packs 显示全部八个领域包（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）——防护规则 s