draft-polisher

初稿润色器（审计式编辑）

触发条件与路由

• 触发词：润色初稿、去模板化、连贯性检查、去除套话、润色、去套话、去重复、统一术语。
• 使用时机：已有一版初稿，但读起来像脚手架（重复、省略、模板化措辞），或需要在全局审阅／LaTeX 之前检查连贯性。

目标：将初稿润色成易读的综述正文，同时不破坏证据契约。

这是一个局部润色流程：去模板化 + 增强连贯性 + 统一术语 + 精简冗余。

注意：如果主要问题是各章节累积造成的结构性冗余，应将修改前移至 sections/，并在合并前使用 paragraph-curator。draft-polisher 不应成为决定保留哪些段落的主要环节。

角色卡（明确使用）

风格协调编辑（编辑）

使命：去除生成器腔调，让正文读起来像出自同一位作者之手。

应做：

• 删除叙述性开场和幻灯片式导航语句，改为承接论点的过渡句。
• 调整节奏，消除重复的模板句式。
• 将重复的免责声明合并为一段前置方法说明。

避免：

• 添加或删除引用键。
• 在不同小节之间移动引用。

证据契约守护者（质疑者）

使命：防止润色夸大证据所支持的结论。

应做：

• 界定定量陈述的适用范围（任务／指标／约束），否则应弱化表述。
• 将证据缺失视为失败信号；应将问题上报处理，而不是绕开缺口改写。

避免：

• 证据仅来自摘要时使用过于自信的措辞。

角色提示词：风格协调编辑（编辑专家）

You are the style and coherence editor for a technical survey.

Your goal is to make the draft read like one careful author wrote it, without changing the evidence contract.

Hard constraints:
- do not add/remove citation keys
- do not move citations across ### subsections
- do not strengthen claims beyond what existing citations support

High-leverage edits:
- delete generator voice (This subsection..., Next we move..., We now turn...)
- replace navigation with argument bridges (content-bearing handoffs)
- collapse repeated disclaimers into one methodology paragraph in front matter
- keep quantitative statements well-scoped (task/metric/constraint in the same sentence)

Working style:
- rewrite sentences so they carry content, not process
- vary rhythm, but avoid “template stems” repeating across H3s

输入

• output/DRAFT.md
• 可选上下文（只读；有助于避免“润色偏移”）：
  • outline/outline.yml
  • outline/subsection_briefs.jsonl
  • outline/evidence_drafts.jsonl
  • citations/ref.bib

输出

• output/DRAFT.md（就地优化）
• output/citation_anchors.prepolish.jsonl（基线，由脚本在首次运行时生成）

不可妥协的规则（硬性要求）

1. 引用键不可更改

• 不要添加新的 [@BibKey] 键。
• 不要删除引用标记。
• 如果存在 citations/ref.bib，不要引入其中未定义的键。

2. 引用锚点不可更改

• 不要将引用移到不同的 ### 子章节。
• 如果必须跨子章节重组内容，请停止并将更改提交到上游（大纲／简报／证据），然后重新生成。

3. 不得夸大证据

• 如果某句话的表述强于证据所能支持的程度（仅有摘要），请改写为带有限定的表述。
• 如有疑问，请查看 outline/evidence_drafts.jsonl 中对应子章节的证据包，并确保论断与摘录一致。

4. 规范引用格式

• 合并同一句中相邻的引用块（避免 [@a] [@b]）。
• 删除同一引用块中的重复键（避免 [@a; @a]）。
• 避免只在句末堆放引用：在论断句中（句中）保留部分引用，而不只是放在段落末尾。

5. 规范定量论断

• 如果保留数字，请确保句子同时说明任务类型、指标定义及相关限制（预算／成本／工具访问权限），不得猜测；并将引用嵌入该句。
• 避免使用含糊的模型名称（例如“GPT-5”），除非引用的论文使用了该确切名称；否则请使用论文中的名称或中性描述。

6. 避免流水线式表述

• 删除以下脚手架式短语：
  • “我们采用以下工作论断……”
  • “我们追踪的主要维度是……”
  • “摘要被视为核验目标……”
  • “方法说明（证据政策）：……”（避免标签，改写为普通的综述方法描述）
  • “本次运行是……”（改写为综述方法描述：“本综述……”）
  • “范围与定义／设计空间／评估实践……”
  • “接下来，我们将从……转向……”
  • “现在我们转向……”
  • “从到，……”（标题式叙述；改写为论证过渡）
  • “下一节／下一小节……”
  • “因此／由此，综述综合或比较应当……”（改写为面向文献的观察）
• 同时删除类似生成器的论文式开场白，这类表述读起来像大纲叙述：
  • “本小节综述……”
  • “本小节论证……”

建议分三轮处理

第 1 轮 — 小节润色（结构 + 去模板化）

两版择优微调（推荐）：

• 对于你修改的任何句子或段落，先拟写 2 个改写版本，再保留较好的一个。
• 用简单的标准进行选择：表意清晰、不带模板化开头、引用保持对应，且引用形式便于读者阅读（不出现相邻引用块／重复键）。
• 不要同时保留两个版本。选定一个后继续（目标是收敛，而不是无休止地改写）。

角色分工：

• 编辑：改写句子，使其更清晰流畅。
• 审稿人：删除任何泛泛的／模板化句子。

目标：

• 每个 H3 都体现：张力 → 对比 → 证据 → 局限。
• 删除重复的“免责声明段落”；证据政策只保留在一处（最好在引言或相关工作中用一段文字说明综述方法，而不是记录流程或执行日志）。
• 如果存在，使用 outline/outline.yml，避免编辑时标题偏移。
• 如果存在，使用 outline/subsection_briefs.jsonl，在改善行文流畅度的同时，确保每个 H3 的范围／研究问题保持一致。
• 快速检查“模式”（语义检查，而非机械查找）：
  • 删除大纲旁白：This subsection ...、In this subsection ...
  • 删除幻灯片式导航：Next, we move from ...、We now turn to ...、In the next section ...
  • 删除标题旁白：From <X> to <Y>, ...
  • 替换为：内容主张 + 论证衔接 + 结构说明句（不引入新事实／引用）
• 如果使用了 citation-injector，应润色预算注入句，使其读起来像论文：
  • 保持引用键不变。
  • 避免使用列举式注入开头（例如，“A few representative references include …”“Notable lines of work include …”“Concrete examples ... include ...”）。
  • 优先将新增引用融入现有论证句，或改写为简短的括号插入语 e.g., ...，并与小节视角关联（不引入新事实）。
  • 变换措辞；避免在多个 H3 中重复使用相同的开头句式。
• 语气：保持平实、学术；删除夸张用语和重复的开头标签（例如多个 H3 中反复出现字面形式的 Key takeaway:）。
• 减少重复的综合性句式（例如，许多段落都以 Taken together, ... 开头）；变换表达方式，并确保每个综合句都包含具体内容。
  • 如果 Taken together, 出现超过两次（或集中出现在同一章），应改写以变换表达，同时保留每句综合内容的具体性。反复使用 Taken together, 会显得像生成器的惯用表达。
  • 变换综合性句子的开头，例如：“In summary,”“Across these studies,”“The pattern that emerges,”“A key insight,”“Collectively,”“The evidence suggests,”或直接陈述结论，不加综合标记。
  • 每个综合性开头都应紧扣具体内容，而非模板标签。

小节开头的改写方法（保持论文风格，不引入新事实）：

• 删除：This subsection surveys/argues...／In this subsection, we...
• 改写为简洁的开头，涵盖以下 2–3 项（不加标签；各小节之间变换表达）：
  • 内容主张：点明该小节的具体张力／权衡（可嵌入 1–2 条引用）
  • 重要性：将主张与评估／工程约束（基准测试／协议／成本／工具访问）联系起来
  • 预告：说明接下来要比较的内容及视角（A 与 B；然后是评估依据；最后是局限）
• 示例句式（请改写，不要照搬）：
  • 以张力为先：A central tension is ...; ...; we contrast ...
  • 以决策为先：For builders, the crux is ...; ...
  • 以视角为先：Seen through the lens of ..., ...

第 2 轮 — 术语规范化

角色分工：

• 术语分类员：确定规范术语及同义词使用规则。
• 整合员：在全文中统一应用替换。

目标：

• 一个概念只使用一个名称，全文保持一致。
• 标题、表格和正文使用相同的规范术语。

第 3 轮 — 冗余删减（全局重复）

角色分工：

• 压缩者：精简重复的套话。
• 叙述保留者：确保删去重复内容不会破坏论证链条。

目标：

• 删除跨章节重复的引言和结语。
• 小节中只保留该小节特有的内容。

脚本

快速开始

• uv run python .codex/skills/draft-polisher/scripts/run.py --help
• uv run python .codex/skills/draft-polisher/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>：工作区根目录
• --unit-id <U###>：单元 ID（可选；用于日志）
• --inputs <semicolon-separated>：覆盖输入项（少见；建议使用默认值）
• --outputs <semicolon-separated>：覆盖输出项（少见；建议使用默认值）
• --checkpoint <C#>：检查点 ID（可选；用于日志）

示例

• 第一轮润色（创建锚定基线 output/citation_anchors.prepolish.jsonl）：

  • uv run python .codex/skills/draft-polisher/scripts/run.py --workspace <workspace>

• 重置锚定基线（仅当你有意接受引文漂移时）：

  • 删除 output/citation_anchors.prepolish.jsonl，然后重新运行润色器。

验收清单

• 不含 TODO/TBD/FIXME/(placeholder)。
• 不含 … 或 ... 截断。
• 不在多个小节中重复出现套话句子。
• 引文锚定检查通过（无跨小节漂移）。
• 每个 H3 至少包含一段跨论文综合分析（>=2 条引文）。

故障排除

问题：润色导致小节间的引文漂移

解决方法：

• 将引文保留在同一个 ### 小节内；如果有意调整结构，请删除 output/citation_anchors.prepolish.jsonl 并重新生成基线。

问题：写作审批前有人请求润色草稿

解决方法：

• 在 DECISIONS.md 中记录相关审批（通常为 Approve C2），然后再进行文字层面的修改。