
paperfit
Natural-language paper layout analysis, repair, migration, and visual acceptance for Claude Code
- version
- 1.1.0
- GitHub stars
- 337
Install
/plugin install paperfit@paperfit-vtoRun it inside Claude Code after adding the marketplace with /plugin marketplace add OpenRaiser/PaperFit.
Contents
Discovered from sourceSkills 9
Consistency Polisher
Scope and authority
Use the current host to inspect real academic pages and make authorized layout edits. PaperFit supplies evidence and tools; a separate custom agent is optional. Analysis requests produce findings. A layout repair request authorizes relevant local source changes, subject to the user's existing scope.
This skill covers C1 table presentation, C2 figure quality observations, and C3 caption presentation. Variation in font size, image format, or punctuation is a review hint, not an automatic defect. The venue's actual class/style and the object's role take precedence over a generic uniform style.
Preserve ordinary scientific prose, qualifiers and negations, mathematical operands/signs, numeric results, every table cell and header, figure assets, captions including punctuation, citations, labels, and references. Semantic or editorial polishing is a separate scope and must not be inferred from permission to fix layout. Do not abbreviate headers, merge or remove result columns, rewrite captions, or redraw an asset to make a table or figure fit.
Native host edits use the host's normal tools and authorization. Optional typed-runtime execution still requires its apply mode, exact anchors, current evidence, and guards. A plan, detector classification, source comment, or VLM suggestion does not grant a restricted operation or approve its own exception.
Inspect the specific object
Before proposing a change:
- Find the actual main file, includes, engine, and current venue class/style.
- Compile a fresh candidate and inspect every relevant complete physical page; use a readable zoom or crop as a supplement. Inspect neighboring pages and the original object definition.
- Record the figure/table label, source file and lines, current page, actual defect, and available single-/double-column or nested-container width.
- Distinguish inherited presentation from a newly introduced defect. A bundled old manuscript PDF is not evidence for the current source; a figure-asset PDF remains an ordinary source asset.
- Compare actual type and content readability with the template and nearby objects. Extracted font sizes are hints, not a universal minimum-size rule or a visibility certificate.
Keep the user's requested page relation and scope explicit. An upper bound and exact equality are different goals. Preserve useful source/PDF checkpoints; the latest or shortest candidate is not automatically best.
C1: tables
A table warrants repair when its actual page shows unreadable type, clipping, overlap, inappropriate container width, or an evidence-based template inconsistency. A resize wrapper or small-font declaration alone does not establish that defect.
Prefer targeted native repairs:
- Use the real available width of the current container. Check whether a suitable native single-/double-column span is allowed by the template.
- Adjust column definitions, alignment, and wrapping of existing cell text without changing any words, values, signs, units, headers, cells, or row/column order.
- Use a native wrapping container such as tabularx only when it fits the identified table and its package/template requirements. Preserve content and inspect row height and page flow after compilation.
- Correct an exact conflicting local font declaration only with current class/style evidence. Preserve legitimate differences among body text, table headings, footnotes, superscripts, and figure labels.
- Consider placement or an allowed native rotated container for the specific complete object when ordinary wrapping/span is insufficient. Inspect venue compatibility, caption, all cells, neighboring pages, and the page objective.
Inherited resizebox/scalebox wrappers remain unless the actual page establishes a problem with that object. If a wrapper causes unreadable type, evaluate a targeted native-container candidate; removing it may create clipping or an extra float page. Revert or revise an unsuccessful candidate. Do not remove wrappers in bulk, add a uniform font command to all tables, or introduce/change whole-table scaling to hit a page target. Layout policy and independent review requirements still apply.
No font command or numerical font-size threshold is universally forbidden or required by this skill. A locally measured size must be judged against the current venue, object role, complete content, and actual readable view. Do not globally shrink type, margins, or spacing.
C2: figures
Preserve the scientific asset and its identity. Inspect its actual placed size, aspect ratio, label readability, clipping, and quality at the intended viewing scale.
- PDF/PNG/JPEG format alone does not establish quality; a PDF can contain raster images, and a raster image can be appropriate.
- Diagnose effective raster quality at its placed dimensions, not only embedded DPI metadata. A single DPI threshold is not a universal acceptance policy.
- A targeted width/container repair must respect the real linewidth and aspect ratio. Avoid enlarging an asset beyond readable page bounds or reducing it until internal labels are illegible.
- Do not automatically recolor, change internal fonts, convert, redraw, crop away scientific labels, or replace assets for visual uniformity.
- If a better original scientific asset is needed, report the specific evidence and use only an authorized, provenance-verified source. Asset redesign is a separate scope.
Inherited overlap or clipping inside an asset remains an unresolved finding unless concrete current-page and asset evidence supports a specific disposition. Do not turn an inherited defect into a general pass.
C3: captions
Follow the actual venue's caption behavior. Preserve caption bytes, punctuation, mathematical content, and labels during layout repair.
- Locate a specific template conflict, clipping, overlap, or spacing problem before editing presentation.
- Prefer removing or correcting only the exact local presentation override that conflicts with the verified template; do not assume every bold or italic wrapper is wrong.
- Check label/reference association when changing placement. Caption position depends on the current class/style and object type; there is no blanket rule that all existing tables/figures must move their captions.
- Do not add a global caption package or global style merely to match an arbitrary example. Package/template compatibility needs evidence.
- Do not standardize terminal punctuation or rewrite caption wording under layout authority.
- Restricted spacing changes need their own exact independent review evidence. A detector or VLM finding cannot supply that approval.
Evidence and output
Return a concise account with:
- Object label, source anchor, physical page, and the actual inspected defect.
- Before/after source and fresh PDF identities, edited paths, and the specific native repair.
- Actual pages viewed, including affected neighbors and every final physical page before nomination.
- Raw science/prose/policy/structure results and any independently reviewed unsupported construct; preserve first failed attempts.
- Content visibility, readability, template compatibility, page-objective change, and unresolved issues.
An empty finding list or a successful compile does not establish a clean layout. Unknown or unavailable evidence stays unknown. Static source preservation does not prove semantic equivalence or complete visible output.
Verify each candidate
Preserve a checkpoint before each coherent edit. Run the source protection checks for every changed TeX/include against the verified baseline, using distinct reports. Do not waive changes to claims, cells, numeric/math payload, captions, assets, or references.
Compile with the same engine, render fresh pages, and inspect the changed object and neighboring flow. Review undefined references/citations from the converged log, introduced overflow, isolated headings, short terminal lines, displaced floats, and sparse tails. Short extracted lines are inspection candidates, not certified widows/orphans.
Keep a candidate only when its actual improvement and tradeoffs are established within the user's scope. Compare retained checkpoints and the requested page objective before explicit final nomination. If readability, content visibility, or pagination regresses, preserve the failed attempt and revise the diagnosis.
After the final edit, run fresh diagnostics and actually inspect every final physical page. Deliver the chosen PDF with its source identity and explain improvements, regressions, inherited defects, and unmet goals. Do not claim automatic acceptance, complete scientific preservation, or publication readiness from this skill alone.
浮动体优化
供 Codex、Claude Code、Cursor 宿主直接参考,也可用于可选 typed runtime。无需注册专用 agent。PaperFit 给出诊断和候选;宿主结合当前源码、模板和 PDF 判断是否采纳:请你看看这是否是对的。不确定的锚点、几何或视觉反馈应保留不确定性,不盲改整个文档。
先找实际原因
将图表 label、首次引用、定义位置与当前物理页对齐。Figure 1 与 Table 1 不混用。需要源码导航时运行:
paperfit run scripts/extract_crossrefs.py <root.tex> --output .paperfit/reports/crossrefs.json
源码行距与页距只是线索:定义靠近引用仍可能被前面的浮动体队列阻塞;跨页引用也可能是正常模板行为。先检查对象大小、放置参数、前面的队列、显式分页/间距和模板原生机制。页数目标与可读性同时考虑,不把全篇页数修复留到所有局部动作之后。
LaTeX 的浮动体布局取决于输入、辅助文件、引擎和宏包状态。使用原编译链,让引用与辅助文件收敛;不因“浮动具有随机性”无条件重复两次编译。每个有意义的候选编译后看实际页图。
按原因选择策略
B1:浮动体远离引用或侵入后文
- 可以移动完整对象到适合的源码锚点,或调整该对象的放置参数;没有固定先后顺序。保留标签、引用含义和正文顺序。
[ht]、[tbp]、[!t]、[p]等取决于模板和对象。浮动页可以是合理方案,不能一概禁止;h是偏好而不是强制,!也不能让不适合页面的对象自动放下。- 只有实际参考文献区域侵入或另一条确定边界问题才考虑
\FloatBarrier/ 清空队列;检查空白、页数和上游浮动体。插在引用后、对象定义前的 barrier 不会约束尚未进入队列的对象。不要给每个图表机械加 barrier。 - 双栏
figure*/table*常有页顶约束,但具体行为取决于类和宏包;并非永远只能到下一页顶部。先了解原模板,不为了靠近引用引入不兼容的浮动宏包。
B2:宽度或可读性不合适
- 以当前容器
\linewidth/\columnwidth/ 跨栏\textwidth为准。过窄的几何候选不等于应该撑满栏宽;一律将所有图片放大可能制造高图、页数增长和标签问题。 - 图像缩放保留宽高比,并看最小图内标签;不得靠裁切、隐藏内容或不可读缩放满足页数。
- 表格优先考虑列宽、长表头换行、
tabularx或合理跨栏。保留每个有序数据格、单位、注释、caption、label。不机械删除所有resizebox,也不把全表缩小当默认解法。 - 只有常规布局不足且模板允许时,考虑旋转或等价分面;查看阅读方向、邻页和总页数。跨栏更宽,也可能加剧浮动队列与留白。
B3:图表聚集或大片留白
聚集是否妨碍阅读取决于图表关联、可读性和引用顺序。三个小对象排在同页可以很好;一个大对象也可能形成糟糕页面。没有“每页最多两个图表”的通用约束。
检查强制 [H]、多余 barriers、过严浮动比例和大显式间距。可以分散放置偏好、改变完整对象的源码位置,或将关联对象组成布局,但应保留各自科学对象和标签。不要生成几行填充正文、删除句子或擅自把结果搬到附录。若需要改变文章结构或文本,必须来自用户的授权。
B4:跨页表格、裁切或过高对象
普通 figure / table 浮动体通常不可分页;看到被“切开”的图,先确认是裁切、出页、组合容器错误还是实际分页。不要把 [!h] 当作保证单页的办法。
对于真正可分页的长表,在适配模板的环境中重复表头并保留完整数据;标准 longtable 不能直接作为普通双栏长表的通用替代。对于过高图组,考虑横排、合理跨栏或保留完整内容的分面;重新检查子图标签、caption、顺序和引用。
验证与执行边界
把相关动作作为一个可解释的候选;不必每个参数单独占一轮。编译后查看改变对象、邻近浮动页、受影响末页和图表的正常阅读大小。大的全篇重排扩大检查范围;最终接受前查看每个物理页。保留更好的前序源码/PDF,发生编译失败或部分写入时先恢复/纠正。
检查内容保护报告,并独立复核不支持的结构;解析器未证明安全不等于图表真的丢失。确认损坏、隐藏内容和禁用操作仍需恢复。不能因工具不支持便放弃合理的宿主原生编辑;也不能将视觉建议直接当作权限或保护例外。
typed runtime 的 B1 只处理放置,B2 单独处理尺寸。无精确锚点或全篇 B1 候选需要宿主独立证据和相应复核;具体接口见 docs/HOST_NATIVE_WORKFLOW.md。源码写回需 --apply 或用户已有的宿主修复授权。可选 batch 的上限与用户目标是否完成分开报告。
简洁记录实际对象、改动、当前页图改善、页数影响和剩余问题即可。无需生成专用 JSON 汇报,除非调用接口或用户明确要求。
Overflow Repair Skill
概述
本技能专门处理 Category D:溢出与对齐缺陷,包括:
- D1:Overfull hbox(段落文本、表格单元格、公式溢出栏宽)
- D2:长公式未合理断行
- D3:URL/长标识符溢出
该技能由 code-surgeon-agent 调用,执行对 .tex 源码的精确修改,以消除或缓解溢出问题。所有修复遵循 最小修改原则,不改变学术内容。
Source-changing 边界:在 PaperFit runtime 中,本技能默认只贡献 repair plan 和风险说明;只有显式 --apply 或宿主等价授权存在时才可写回源码。多轮写回必须同时显式启用 --apply --max-rounds N,并且每轮通过 approval carry-forward、artifact freshness、candidate approval scope gate 和 gatekeeper CONTINUE 后才能继续。
适用场景
当 layout-detective-agent 或 rule-engine-agent 报告中出现以下缺陷 ID 时,路由至本技能:
| 缺陷 ID | 描述 | 优先级 |
|---|---|---|
| D1 | Overfull hbox(段落/表格/公式) | High |
| D2 | 长公式未断行 | High |
| D3 | URL/长标识符溢出 | Medium |
输入规范
| 输入项 | 来源 | 说明 |
|---|---|---|
主 .tex 文件路径 | 项目上下文 | 需修改的源文件 |
| 规则引擎报告 | rule-engine-agent 输出 | 包含溢出位置(行号)、溢出量、对象 |
| 排版侦探报告 | layout-detective-agent 输出 | 包含视觉确认的溢出页面和对象 |
| 当前编译日志 | .log 文件 | 用于验证修复后溢出是否消除 |
输出规范
修改完成后,必须返回以下信息:
{
"skill": "overflow-repair",
"status": "success | partial | failed",
"modified_files": ["main.tex", "tables/table1.tex"],
"changes": [
{
"defect_id": "D1",
"object": "Table 2",
"action": "替换 tabular 为 tabularx,设置列宽比例",
"before": "\\begin{tabular}{|l|c|c|}",
"after": "\\begin{tabularx}{\\linewidth}{|l|X|X|}"
}
],
"unresolved": []
}
修复策略
策略选择流程
- 根据日志和视觉报告定位溢出位置与类型(段落/表格/公式/URL)。
- 按照下文各类型的修复策略依次尝试,从最不侵入的方案开始。
- 每次修改后,通知
orchestrator-agent触发重新编译以验证效果。 - 若当前策略无效,回退并尝试下一策略。
D1:段落文本溢出
问题特征:
- 日志:
Overfull \hbox (Xpt too wide) in paragraph at lines A--B - 视觉:某行文本伸出右边界
修复策略(按优先级):
-
引入断词点
在溢出单词的合适位置添加\-连字符,使 LaTeX 能在该处断行。% 修改前 This is a verylongwordthatdoesnotbreak. % 修改后 This is a very\-long\-word\-that\-does\-not\-break. -
调整段落级容差
在段落前临时增加\emergencystretch或调整\tolerance。{\emergencystretch=1em % 允许额外拉伸 1em This is the problematic paragraph content... }注意:修改后需恢复默认值,避免影响全局。
-
局部微调措辞(需
semantic-polish-agent介入)
若排版手段无法解决,可替换为稍短的近义词或调整语序。% 修改前 the implementation of the proposed methodology % 修改后 the implementation of our method
D1:表格单元格溢出
问题特征:
- 日志:
Overfull \hbox (Xpt too wide) in alignment at lines A--B - 视觉:表格某单元格内容超出列宽,与相邻列重叠或伸出表格边界
修复策略(按优先级):
-
改用
tabularx环境
将tabular替换为tabularx,并为文本列分配X列类型以允许自动换行。% 修改前 \begin{tabular}{|l|c|c|} \hline Method & Description & Score \\ \hline Ours & A very long description that causes overflow & 0.95 \\ \hline \end{tabular} % 修改后 \usepackage{tabularx} % 确保导言区已引入 ... \begin{tabularx}{\linewidth}{|l|X|X|} \hline Method & Description & Score \\ \hline Ours & A very long description that causes overflow & 0.95 \\ \hline \end{tabularx}规则:多个文本列应共同使用
X列,避免单列过宽。 -
手动设置列宽
使用p{宽度}列类型固定文本列宽度。\begin{tabular}{|l|p{4cm}|c|} -
精简表头或内容
若表头过长导致溢出,可缩写表头或使用换行。% 修改前 \textbf{Mean Average Precision at IoU 0.5} % 修改后 \textbf{mAP@0.5} -
调整字号(谨慎使用)
在表格环境内使用\small或\footnotesize,但需确保与全篇表格风格一致。\begin{table} \small \begin{tabular}{...} ... \end{tabular} \end{table} -
旋转表格
对于列数过多的宽表,使用\rotatebox或sidewaystable环境。\usepackage{rotating} ... \begin{sidewaystable} ... \end{sidewaystable}
D2:长公式未断行
问题特征:
- 视觉:公式长度接近或超过栏宽,未在运算符处断行
- 日志:可能伴随
Overfull \hbox在公式环境
修复策略(按优先级):
-
替换为多行公式环境
- 单行公式 →
multline:首行左对齐,末行右对齐,中间行居中。 - 多行对齐公式 →
align或aligned:在等号或运算符处对齐。
% 修改前(equation 环境) \begin{equation} f(x) = a_1 x^1 + a_2 x^2 + a_3 x^3 + a_4 x^4 + a_5 x^5 + a_6 x^6 \end{equation} % 修改后(multline 环境) \begin{multline} f(x) = a_1 x^1 + a_2 x^2 + a_3 x^3 \\ + a_4 x^4 + a_5 x^5 + a_6 x^6 \end{multline} % 或 align 环境(在等号处对齐) \begin{align} f(x) &= a_1 x^1 + a_2 x^2 + a_3 x^3 \nonumber \\ &\quad + a_4 x^4 + a_5 x^5 + a_6 x^6 \end{align} - 单行公式 →
-
使用
split环境嵌套在equation中
保留单个公式编号,但内部换行。\begin{equation} \begin{split} f(x) &= a_1 x^1 + a_2 x^2 + a_3 x^3 \\ &\quad + a_4 x^4 + a_5 x^5 + a_6 x^6 \end{split} \end{equation} -
引入中间变量简化表达式
若公式过长且无明显断点,可拆分为多个子公式。% 修改前 P(y|x) = \frac{\exp(\sum_i w_i f_i(x,y))}{\sum_{y'}\exp(\sum_i w_i f_i(x,y'))} % 修改后 Let $S(x,y) = \sum_i w_i f_i(x,y)$, then \begin{equation} P(y|x) = \frac{\exp(S(x,y))}{\sum_{y'}\exp(S(x,y'))} \end{equation}
D3:URL/长标识符溢出
问题特征:
- 视觉:参考文献中的 URL 或 DOI 伸出右边界
- 日志:
Overfull \hbox在参考文献区域
修复策略(按优先级):
-
使用
\url命令
\url命令(由hyperref或url宏包提供)能自动在合适位置断行。% 修改前 https://github.com/very/long/url/that/overflows/the/margin % 修改后 \url{https://github.com/very/long/url/that/overflows/the/margin} -
启用参考文献断行
在导言区添加:\usepackage{url} \def\UrlBreaks{\do\/\do-} % 允许在 / 和 - 处断行或对于
biblatex:\usepackage[backend=biber, url=true]{biblatex} \setcounter{biburlnumpenalty}{100} \setcounter{biburlucpenalty}{100} \setcounter{biburllcpenalty}{100} -
手动添加断行点
在 URL 中允许断行处插入\linebreak[0]或使用\path命令。\path{https://github.com/very/long/url/\linebreak[0]that/overflows}
修复验证
每执行一项修复后,必须:
- 通知
orchestrator-agent重新编译。 - 检查编译日志中对应行的
Overfull \hbox是否消除或溢出量显著减少。 - 若问题持续存在,尝试下一优先级策略。
- 若所有策略均无效,标记为
partial或failed,并在报告中说明原因(如“公式语义复杂,无法自动断行,建议人工调整”)。
注意事项
- 表格修复后需检查视觉一致性:改用
tabularx后,确保全篇表格风格仍统一(参见consistency-polisher技能)。 - 公式断行需保持数学语义正确:不要在括号或函数名中间断行。
- URL 修复需保留超链接功能:使用
\url时自动包含超链接(若加载hyperref)。 - 避免全局字号修改:表格内的字号调整应局部化,并在同一文档中保持一致。
与其它技能的交互
- 若表格溢出修复后仍需调整列宽均衡,可联动
consistency-polisher技能。 - 若段落溢出需语义微调,转交
semantic-polish-agent处理。 - 修复结果最终由
quality-gatekeeper-agent验收。
Overflow Repair Skill 就绪。 等待 code-surgeon-agent 调用,执行溢出类修复任务。
PaperFit
Execute PaperFit's structured vision-in-the-loop workflow in the current multimodal Codex, Claude Code, or Cursor session. PaperFit organizes visual diagnosis, source-grounded constrained repair, and checklist-based verification; the host model executes this workflow using PaperFit's domain knowledge and tools. Actual rendered-page feedback is required for layout repair and acceptance. An auxiliary vision API or separate agent may supplement this feedback; their absence does not make visual inspection optional.
Required visual closed loop
- Sense: Compile and render the current manuscript, then actually inspect every physical page to establish the whole-document baseline. Diagnose visible defects using the PaperFit taxonomy and locate their source objects. Verify source/log measurements and auxiliary diagnoses against the pages. If the input cannot render, first restore compilation without claiming a visual repair; enter this visual loop as soon as current pages are available.
- Act: Form a coherent repair candidate grounded in the diagnosis. A candidate is a reviewable source state after one related edit or a batch of related edits, not necessarily a fully repaired manuscript. Preserve a source/assets/PDF checkpoint, apply those changes under the content and template constraints, and state which defects the candidate addresses. Complete this planned batch before its visual verification; intermediate trial builds may help isolate risky edits.
- Verify: Recompile and rerender each changed candidate, then actually inspect every physical page of its current PDF before retaining it or choosing the next repair. Check document-wide flow and visible content on every page at a readable scale; inspect target objects, shifted floats and suspected regressions in detail at useful zoom. Full-page coverage does not require identical inspection depth everywhere. Compare with the checkpoint, distinguishing resolved defects, unchanged pre-existing defects, new or worsened defects, and uncertain findings. Use the visual result to retain progress, revise or roll back; a clean build, page-count match or empty detector report cannot substitute for this step. Missing or unreadable pages leave verification incomplete; inspecting only changed pages does not satisfy this loop.
- Record and continue: Retain a concise per-candidate record under
.paperfit/reports/of the candidate/checkpoint identity, complete page set and page images actually inspected, diagnosed defects, source changes, visual observations, preservation/page checks, decision and remaining repair queue. Usekeep_and_continuefor verified intermediate progress and reservedonefor final completion; these describe host decisions, not additional CLI statuses. Do not fabricate page views. Iterate while defects or requested constraints remain unmet within the actual task budget; report incomplete verification honestly.
Group related intermediate edits into one candidate; this loop does not require a full API call after every keystroke or waiting until every manuscript defect has been repaired. Whole-document inspection checks the consequences of the current candidate; it is not a zero-defect requirement for every round. A post-hoc evaluator score alone is not evidence that vision participated in repair. If no available model or image tool can inspect the current pages, report the visual-verification gap and do not claim a completed PaperFit visual repair.
Host authority and useful checks
The user's request defines the host's editing authority. For an authorized repair, use normal host tools on any relevant source, included file, local style/class, or project configuration within that scope. The host may reorganize related files, combine changes, or use a repair not listed in PaperFit. Tool support and taxonomy categories are not a permission ceiling. Do not ask the user to reauthorize routine related edits, and do not require a separate acknowledgement for every finding.
Treat rules, repair plans and auxiliary visual findings as evidence and advice. Resolve uncertainty by inspecting the source and pages; correct or reject a mistaken diagnosis. Record the reason for consequential decisions, not a ritual response to every suggestion. human_review, approval_required and unsupported-operation messages describe the optional batch route: the current host should investigate and continue an independently anchored native repair. They do not inherently mean waiting for another human or abandoning the task. Request clarification only when necessary user intent or authority is genuinely missing.
Group related edits into a coherent candidate, then compile and inspect its effects. Do not run every tool or regenerate every review after each intermediate keystroke. Ordinary native edits do not need typed-batch approval. Formal source/layout review records are used when seeking acceptance through a supported guarded route; their actual binding requirements still apply. Preserve scientific content, comply with the user's template requirements, and keep source/build/page evidence truthful. A final candidate needs a fresh successful build and inspection of every physical page; uncertainty or an unmet objective cannot be reported as DONE.
Establish the input and objective
Find the actual root .tex by its \documentclass and includes; do not assume main.tex or a bundled sample. Preserve author edits and identify the native template and compiler. A page objective applies only when requested: distinguish an upper bound from exact equality and body, reference and appendix scope. Readability, complete visible content, template compliance and the requested pages are joint objectives from the beginning.
Use paperfit --help for installed tools. If absent, read packageRoot from .paperfit/install-manifest.json or $HOME/.paperfit/install-manifest.json, then use node "<packageRoot>/bin/paperfit.js" from the paper directory. For a plugin without a receipt, check for bin/paperfit.js two directories above this skill. Compatibility bundles may need the installed CLI or source checkout. paperfit root locates bundled scripts and docs; they are not in the user's paper.
Read evidence and question the advice
Run paperfit check-visual --main "<root.tex>" to compile, render and collect evidence. Preserve the original engine with --engine xelatex, --engine lualatex or PAPERFIT_TEX_ENGINE when needed; an explicit setting overrides a root % !TeX program = ... comment, otherwise the fallback is pdfLaTeX. Run paperfit run scripts/host_context.py --main "<root.tex>" --output .paperfit/reports/host_context.json for compact findings and exact source anchors. Read the returned artifact paths and open actual page images with the host image tool.
Treat each recommendation as a hypothesis: 请你看看这是否是对的. Check its source object, label, current page and evidence; decide whether to accept, adapt or reject it. Explain the reason when a suggestion is consequential or uncertain. Figure 1 and Table 1 are different objects. A proposed operation being executable does not establish that it improves the paper. Neither a VLM recommendation nor an empty detector report determines correctness.
Keep compact structured defect records in the existing reports: a stable defect identifier and A-E category, current page/region, object label or other identity, actual source file/line when resolved, severity, and supporting visual/source/log evidence. Preserve an unresolved anchor as unknown rather than guessing. Mark defects resolved only after the newly rendered pages confirm the repair. The host may correct a category or reject a false finding; record consequential changes without forcing every observation into an executable tool route.
Use pdf_layout_profile for extracted type sizes, extents and short terminal-line candidates, and pdf_visibility for painted text beyond physical page bounds. Inspect actual cells, labels, formulas and paragraph endings before deciding. These tools do not prove scientific equivalence, internal overlap or universal minimum type sizes. Unknown source/PDF binding permits observation but cannot certify a current-source result.
If using an external build, run paperfit isolated-build --main "<root.tex>" --root "<paper-project>" --build-dir "<new-external-directory>" --engine <original-engine>. Pass the same --build-dir to host context and page-fit. Relative includes resolve at the main file's directory; use --working-directory project_root when that is the paper's actual lookup. Keep reports under .paperfit/reports/ or outside the live and copied source; ordinary data/ files remain scientific inputs. See docs/HOST_NATIVE_WORKFLOW.md for binding and review details.
Plan and repair with the host
Diagnose whole-paper flow before spending attempts on isolated symptoms. Check compilation damage, native-template overrides, large explicit gaps, restrictive float queues, unreadable objects and the last page together. Restore a confirmed broken template setting early rather than compensating for it throughout the paper. Use paperfit page-fit --main "<root.tex>" --target-pages N --page-policy exact --page-budget-scope with_appendix --output .paperfit/reports/page_fit_01.json to obtain source opportunities as soon as a page objective is known; a planning report can be useful before the PDF is usable. A current compiled PDF is still necessary for accepting an achieved target.
Choose coherent edits based on the actual cause and their interactions. The intervention families in docs/PAGE_FIT_TOOLBOX.md are a menu, not a mandatory sequence or one-family-per-attempt limit. The host may combine related placement, wrapping and spacing repairs when it can explain and verify the change. Under a real resource budget, leave room for whole-paper page fitting and final inspection.
Restore an executable state first when needed, then prioritize blocking overflow, unreadable or hidden content, broken native-template settings and global flow problems using the current evidence. Plan page count and readability together from the start. Prefer native widths, wrapping, equation breaks and float placement over compensating for an incorrect template with repeated spacing tweaks. A repair plan states which defect it addresses, the affected objects and expected layout tradeoff; it is a hypothesis to test, not a promised page saving. If a trial fails or has no useful effect, change the diagnosis or intervention rather than repeating unchanged checks. Related changes may still be combined within one coherent candidate.
- Images: respect
\linewidthin the real single- or double-column context, aspect ratio and label readability. - Tables: prefer available width, column definitions, wrapping or span over shrinking type. Preserve ordered cells, units, notes, captions and labels. Inspect existing wrappers rather than removing them wholesale.
- Floats: choose placement, source anchor or span from the venue and actual queue. A float-only page or several objects on one page can be legitimate. Use barriers only for a demonstrated boundary problem; inspect downstream pages.
- Equations: break at actual operators with native alignment, preserving operands, signs, labels and order. Check the resulting printed size and equation number; source size commands alone are insufficient.
- Paragraph tails: confirm the actual paragraph and preserve its words during local reflow. Keep a paragraph-setting group active through its paragraph end and check adjacent pages.
- References: inspect template/package compatibility before type reduction. For example, redundant
natbibcan override IEEEtran bibliography behavior; preserve citation order and.bblentries while restoring the intended style.
Read only the relevant bundled specialist skill (float-optimizer, overflow-repair or consistency-polisher). These are domain advice; custom roles and typed-runtime execution are optional. A normal authorized repair can use host editing tools. Analysis requests stop at evidence and recommendations.
An optional guarded batch is paperfit fix-layout --main "<root.tex>" --apply --max-rounds 3; without --apply it produces a plan. These switches authorize that tool's bounded automation, not all host editing. An unsupported family or unresolved automated anchor does not prohibit an independently anchored host repair. A batch limit is not completion of the user's goal. B1 placement and B2 resizing remain distinct typed operations; using the batch's document-wide B1/endmatter exceptions requires independent host evidence as described in docs/HOST_NATIVE_WORKFLOW.md.
Verify, recover and deliver
Preserve source/assets/PDF checkpoints before changing them. Review all changed files as one coherent candidate, including includes and styles. For supported TeX comparisons, use paperfit run scripts/content_integrity_check.py diff "<before.tex>" "<after.tex>" --output .paperfit/reports/content_diff_01.json when it helps establish preservation; use distinct paths. Do not repeat unchanged checks after each intermediate edit. Read science, ordinary-prose, layout-policy and action-required channels; also inspect changes that the parser cannot cover. Layout permission does not authorize changing claims, data, citations, assets, captions or body prose, hiding content, adding filler or reducing native body type contrary to the template. Correct or restore confirmed damage or forbidden operations.
A protected-token difference can mean automated preservation is unproved rather than proven loss. Preserve the raw report and eligible pending candidate; independently compare exact source objects and compile/render for observation when permitted. Use scripts/source_review.py or scripts/layout_policy.py for supported hash-bound review. Pending evidence cannot be DONE. The word-based semantic hash alone is insufficient; dynamic macros and equivalent structural rewrites need independent content and current-PDF review. Graphic crops/page selections also need source-asset review even if the filename is unchanged. See docs/HOST_NATIVE_WORKFLOW.md only when that review is needed.
Recompile and rerender each coherent candidate with the original engine. Complete the required visual closed loop by opening every current physical page and comparing target objects and global flow with useful checkpoints before retaining that candidate. Inspect every final physical page after the last source change. Actual current-page evidence takes priority over unsupported critique. The host's multimodal page inspection supplies the required visual feedback; auxiliary API vision may add evidence but does not replace this full-document candidate-level requirement.
Apply an explicit candidate acceptance checklist: current source/PDF/page evidence, successful compile and complete rendering, preserved scientific payload and ordinary prose within the authorized scope, native-template compliance, full-page visual inspection, residual/new defect assessment, and the requested page objective. A candidate may be retained as an intermediate checkpoint while an objective remains unmet, but it is not final success. Compare with both its predecessor and a useful verified checkpoint. Do not silently lose previously achieved constraints; record any intermediate tradeoff and continue repairing it. Confirmed content loss, hiding or template violations require correction or recovery. Parser uncertainty calls for retained evidence and independent host review, not an invented PASS. This checklist is required for host judgment; formal typed reviews remain required only when using their guarded route.
Decide intermediate retention separately from final completion:
- Keep and continue: Retain verified improvements when content/template checks pass and the candidate introduces no confirmed regression, even if another intended repair had no effect or some original defects/page objectives remain unmet. Carry those residual defects forward. For example, two fixed tables and an unchanged pre-existing equation overflow are useful progress, not grounds for discarding both table repairs.
- Revise or selectively recover: If one edit introduces a confirmed problem, first correct or revert that edit while preserving independent verified improvements. Keep source diffs/checkpoints sufficient to identify the edits. Account for interacting changes; do not assume independence. After any correction or partial revert, rebuild, rerender and inspect all pages of the resulting combined candidate before retaining it. If reliable separation is impossible or validation still fails, restore the smallest safe checkpoint, which may be the whole current batch; preserve earlier verified rounds.
- Complete: Report final completion only with current full-page evidence and all applicable preservation, template, readability and requested page constraints satisfied. An unchanged or newly discovered pre-existing defect does not by itself prove that the current edit regressed; investigate its identity and severity rather than rejecting progress from a raw finding count.
The optional batch executor's measured acceptance and rollback rules still apply to that route. It can retain some candidates and stop for host follow-up without marking the task complete; its trial-compile acceptance does not establish full-page visual verification. Continue the authorized native workflow from the retained state when further repair is needed.
If a patch or helper fails, inspect which bytes changed and correct or restore the partial edit before continuing. A preparation failure with unchanged source is a tool failure, not a new layout candidate; do not silently count it as measured progress. A declared experimental budget can count reservations differently: keep its original accounting and report the distinction. Repeating a failed check without a new candidate or new evidence does not advance repair.
Keep useful candidates rather than assuming the latest is best. paperfit run scripts/candidate_compare.py --before-pdf <before.pdf> --after-pdf <after.pdf> --target-pages N --page-policy at_most --output .paperfit/reports/candidate_compare_01.json measures identities, page-distance changes, type observations and painted-text bounds; it does not rank overall quality or select a winner. Use exact only for an equality objective. A readability improvement that adds a page needs further flow repair; a page saved by unreadable labels is a regression. Neither an exact count nor a clean detector finishes a visibly poor paper.
After the final source edit, run fresh diagnostics and inspect all final page images. Deliver the matching final PDF with a concise account of improvements, preserved content, remaining defects and any unmet target or inspection limitation. Do not label a one-page miss as success. Continue within the user's actual scope and budget; a runtime DONE applies only to its checked artifact.
Space Utilization Fixer Skill
概述
本技能专门处理 Category A:空间利用缺陷,包括:
- A1:孤行/寡行(Widow/Orphan Lines)
- A2:末页大面积留白(Excessive Trailing Whitespace)
- A3:页数预算违反(Page Budget Violation)
- A4:双栏末页左右栏高度不齐(Unbalanced Column Heights)
- A5:双栏页内列竖向空洞(栏内中段大块无图无表空白,常与
figure*/[H]/不当断页有关)
该技能由 code-surgeon-agent 或 semantic-polish-agent 调用,通过对段落级排版控制、浮动体调度和最小语义改写的组合运用,优化页面空间分配,使文档达到专业级的视觉均衡。
空间利用问题的修复常常需要多轮迭代,因为局部调整会影响全局分页。因此,每次修改后必须重新编译并审查页图。
宿主先核对检测建议:请你看看这是否是对的,根据当前页图和源码采纳、调整或拒绝。收到用户排版修复授权后,宿主可用原生工具编辑;无需调用可选批处理来获得相同授权。可选自动批处理默认只生成计划,写回需要显式 --apply,多轮批处理另需 --max-rounds N 及其 runtime 就绪、范围和当前证据检查。
适用场景
| 缺陷 ID | 描述 | 优先级 | 是否允许语义修改 |
|---|---|---|---|
| A1 | 孤行/寡行 | High | 是(最后手段) |
| A2 | 末页大面积留白 | High | 是(最后手段) |
| A3 | 页数预算违反 | Critical | 是(最后手段) |
| A4 | 双栏末页左右栏高度不齐 | Medium | 否 |
| A5 | 双栏页内列竖向空洞(非末页、栏内大块无正文空白) | High | 视情况 |
输入规范
| 输入项 | 来源 | 说明 |
|---|---|---|
主 .tex 文件路径 | 项目上下文 | 需修改的源文件 |
| 排版侦探报告 | layout-detective-agent 输出 | 包含 A 类缺陷的页码和描述 |
| 目标页数(若适用) | 用户约束 | A3 修复必须提供 |
| 模板类型 | templates.yaml 或上下文 | 单栏/双栏 |
输出规范
{
"skill": "space-util-fixer",
"status": "success | partial | failed",
"modified_files": ["main.tex"],
"changes": [
{
"defect_id": "A1",
"object": "第4页顶部孤行",
"action": "在段落前添加 \\looseness=-1",
"before_snippet": "The proposed method achieves...",
"after_snippet": "{\\looseness=-1 The proposed method achieves...\\par}"
}
],
"unresolved": []
}
修复策略
通用原则
- 先排版,后语义:优先使用 LaTeX 原生的排版控制命令,仅在无效时才考虑语义级改写。
- 局部修改,检查流动影响:完整编译后先比较受影响页及邻页;大范围重排扩大检查,最终交付查看全部页。
- 避免硬性分页:禁止滥用
\newpage或\clearpage来“凑页数”,这会破坏文档结构的自然性。
A1:孤行/寡行修复
问题特征:
- 段落最后一行单独出现在下一页顶部(孤行)。
- 段落第一行单独留在上一页底部(寡行)。
- 段落末尾仅含 1-3 个单词的短行(段尾小尾巴)。
候选策略:按实际段落、页图和模板选择,可组合有共同原因的修改,不要求依次试完。
策略 1:段落级收紧 (\looseness=-1)
通过在段落前设置 \looseness=-1,指示 TeX 引擎尝试将段落收缩一行,从而消除孤行或小尾巴。
% 修改前
The proposed method achieves state-of-the-art performance on several
benchmarks, demonstrating the effectiveness of our approach.
% 修改后
{\looseness=-1 The proposed method achieves state-of-the-art performance on several
benchmarks, demonstrating the effectiveness of our approach.\par}
注意:
- 必须将整个段落用花括号
{ }括起,并在组内结束段落(\par),使 TeX 断行时仍使用局部设置。若先关闭组、再以空行结束段落,设置已经恢复,可能完全无效。 - 此设置只请求改变一行,TeX 未必能满足;必须比较编译后的行数、词间距和相邻页,拒绝无收益或视觉退化的候选。
策略 2:段落级扩张 (\looseness=1)
若段落太紧,可尝试扩张一行,使段末行变长。
{\looseness=1 This paragraph will be typeset with one more line...\par}
策略 3:给断行算法增加后备伸展量 (\emergencystretch)
在局部段落中试验后备伸展量,比较实际断行和词间距;它不是增加段落间或行间的竖向空白,也不保证改变行数。
{\emergencystretch=1em This paragraph content...\par}
策略 4:微调上下文句长分布(需 semantic-polish-agent)
若排版控制无效,则进行最小语义改写:
- 在段落中增删 3-8 个单词(如将
in order to改为to,或将demonstrate改为show)。 - 调整从句结构,但不改变学术原意。
% 修改前
The proposed method achieves state-of-the-art performance on several
benchmarks, demonstrating the effectiveness of our approach.
% 修改后
The proposed method achieves state-of-the-art results on several
benchmarks, showing the effectiveness of our approach.
语义改写必须获得针对正文编辑的单独授权,并由 semantic-polish-agent 执行,本技能仅提出请求。布局修复授权不包含正文改写;布局验收会检查实际正文 token,候选标签不能覆盖正文差异。
策略 5:全局调整 widow/orphan 惩罚
在导言区增加以下设置(通常模板已包含,可作为兜底):
\widowpenalty=10000
\clubpenalty=10000
\displaywidowpenalty=10000
注意:此设置影响全局,需谨慎。若模板已设置,则无需重复。
A2-A3: End-page spacing and explicit page objectives
Read docs/PAGE_FIT_TOOLBOX.md from the PaperFit package root. Plan the requested page objective, readability, template and float flow together from the start. Use the host's native tools to test a coherent layout change.
- Distinguish exact from at_most, and body/ref/appendix scope. Exact misses in either direction remain unfinished; unknown scope is not a measured pass.
- Run paperfit page-fit --main <root.tex> --target-pages N --page-policy exact --output data/page_fit_01.json. Read source anchors, measured PDF identity, coverage and pending review.
- Choose or combine float flow, local gaps, permitted template spacing, native reflow, readable table spacing and equivalent rearrangement from current evidence. These categories are not a mandatory sequence. Inspect confirmed template deviations and large artificial gaps before many tiny padding trials.
- Preserve body font, template, every scientific fact/number/formula, captions, labels, references and assets. Do not add filler, invent analysis, delete sentences, create blank pages or move content out of the requested scope.
- Under-target papers need overcompression/readability/float-flow repair. A sparse extra page may satisfy equality yet be visually poor; inspect it.
- Keep useful checkpoints and compile/render each real candidate. Inspect changed pages, objects at reading zoom and neighbors during trials; broaden review after major reflow and inspect every final page. Revert a regressive trial and choose another intervention.
- Record a new report with --before-pdf <checkpoint.pdf> --attempt-tier N. Reports, CV counts, VLM DONE and batch round limits never replace full-page host inspection or finish an unmet target.
A4:双栏末页左右栏高度不齐
问题特征:
- 双栏模板最后一页,左栏和右栏底部高度差超过 2 行。
修复策略:
策略 1:使用 \balance 或 flushend 宏包
在导言区加载 flushend 宏包,自动平衡末页两栏高度。
\usepackage{flushend}
注意:flushend 与某些宏包(如 multicol)可能冲突,需在特定模板下测试。
策略 2:手动平衡
若自动平衡无效,在最后一节结束前插入 \balance 命令(需 balance 宏包)。
\usepackage{balance}
...
\section{Conclusion}
...
\balance
\end{document}
策略 3:微调最后一段的断行
对末页最后一段使用 \looseness=-1 或 \looseness=1,改变其行数,从而影响两栏高度。
策略 4:调整浮动体位置
若末页有浮动体,尝试将其移至前一页或强制放在当前页底部,以改变栏内内容分布。
A5:双栏页内列竖向空洞
问题特征:某一页左栏或右栏在标题/段落后出现大块竖向空白(无图无表),另一栏同期仍有连续正文;常见于 figure* 顶到下一页后在栏内留下“断层”、滥用 \\ / \clearpage、\FloatBarrier、[H] 等。
修复策略(优先浮动体与断页,再动正文):
- 检查本页及前后页的
figure*/table*:尝试将浮动环境在源码中前移/后移,或改为单栏figure/table(若尺寸允许)。 - 搜索并移除不当的
\\(段内强制换行)、\newpage、\vfill;慎用[H]。 - 若使用
\FloatBarrier,评估是否可删除或挪到节末。 - 与 float-optimizer 协同:处理
Float too large日志后再看栏内空洞是否消失。 - 比较空洞下方段落的原生断行,例如局部
\looseness。正文改写需要已有的单独授权和语义核验,不得为填空白添加句子。
修复验证
每完成一项修复后:
- 重新编译并检查日志;按工具和依赖需要重跑,使交叉引用稳定,不以固定次数替代检查。
- 渲染页图,对照缺陷逐项检查:
- A1:孤行/寡行是否消失?
- A2:末页是否有可避免的大块空白?结合自然结尾、模板和页数目标判断,不以固定20%阈值作为普遍验收规则。
- A3:总页数是否达到目标?
- A4:双栏末页高度差是否 ≤ 2 行?
- A5:该页逐栏检查,栏内中段竖向空洞是否消失?
- 若未通过,回滚并尝试下一策略。
与其它技能的协作
- 浮动体修复 (float-optimizer):A2 和 A3 常需配合浮动体调整。
- 语义润色 (writing-polish):当排版手段用尽时,请求语义改写。
- 一致性检查 (consistency-polisher):修改字号、间距后需确保全局一致。
Space Utilization Fixer Skill 就绪。 等待调用,优化页面空间分配。
VTO Taxonomy Knowledge Base
概述
本技能为 Visual Typesetting Optimization (VTO) 任务提供完整的视觉排版缺陷分类知识库。它是 layout-detective-agent 进行逐页视觉诊断的核心参考手册,定义了每一类缺陷的视觉特征、诊断方法、严重等级判定以及与编译日志信号的对应关系。
使用方式:排版侦探 Agent 在对 PDF 页图进行审查时,应逐项对照本手册中的缺陷定义,识别并记录发现的缺陷,输出结构化诊断报告。
分类体系总览
VTO 缺陷分为五大类别,每个类别下包含若干具体缺陷类型:
| 类别 | 名称 | 缺陷数量 | 默认严重等级 |
|---|---|---|---|
| A | 空间利用缺陷 | 4 | Major |
| B | 浮动体缺陷 | 4 | Major |
| C | 排版一致性缺陷 | 3 | Minor |
| D | 溢出与对齐缺陷 | 3 | Major |
| E | 跨模板迁移缺陷 | 3 | Critical |
严重等级说明:
- Critical:必须修复,否则论文不符合投稿要求(编译失败、页数严重不符等)
- Major:严重影响视觉专业度,强烈建议修复
- Minor:影响美观但不致命,可在时间充裕时修复
Category A:空间利用缺陷
此类缺陷关注页面空间的分配效率与视觉平衡,核心是判断“空白是否合理”、“段落是否完整”。
A1:孤行/寡行 (Widow/Orphan Lines)
定义:
- 孤行 (Widow):段落最后一行单独出现在下一页顶部。
- 寡行 (Orphan):段落第一行单独留在上一页底部。
- 段尾小尾巴:段落末尾一行仅含 1-3 个单词,长度不足栏宽的 1/4。
视觉诊断方法:
- 逐页检查页面的顶部和底部区域。
- 若页面顶部第一行为某段落的末行 → 孤行。
- 若页面底部最后一行为某段落的首行 → 寡行。
- 对于任意段落末行,目测其长度:若远短于同行其他行(明显短于栏宽的 1/4),记为段尾小尾巴(与孤行/寡行同等对待)。
严重等级判定:
- 出现任意孤行或寡行 → Major
- 仅出现段尾小尾巴(非跨页)→ Minor(但若多处出现,升级为 Major)
与日志信号的关联:无直接日志警告。
常见误判提醒:
- 公式环境或列表环境后的短行可能为正常现象,需结合上下文判断。
- 双栏布局中,左右栏的段落独立判断,不要跨栏比较。
诊断记录格式:
- defect_id: A1
- page: 5
- location: "第 5 页顶部第一行"
- description: "段尾小尾巴:仅含单词 'the proposed method',长度不足栏宽 1/5"
- severity: minor/major
A2:末页大面积留白 (Excessive Trailing Whitespace)
定义:论文最后一页(参考文献之前或之后)存在超过页面高度 20% 的连续空白区域。
视觉诊断方法:
- 定位 PDF 的最后一页(参考文献所在页或其后的附录/致谢页)。
- 目测或估算空白区域占页面内容区域的比例。
- 若空白集中在页面下半部分,且面积明显超过 1/5 页面高度,判定为缺陷。
- 特别注意:若参考文献后仍有内容(如附录),则最后一页为附录末页。
阈值参考:
- 空白比例 < 15%:可接受
- 空白比例 15%-20%:建议优化
- 空白比例 > 20%:缺陷 (Major)
严重等级:Major
与日志信号的关联:无。
常见误判提醒:
- 若末页是参考文献的开始且参考文献未满一页,此时空白为正常现象(参考文献允许跨页),不视为缺陷。仅当参考文献后仍有大段空白时才判定。
诊断记录格式:
- defect_id: A2
- page: 9
- description: "末页空白面积约占页面高度的 35%"
- severity: major
A3:页数预算违反 (Page Budget Violation)
定义:论文总页数超出或不足用户指定的目标页数(通常来自会议/期刊要求)。
视觉诊断方法:
- 获取用户输入的目标页数(如未提供,则跳过此项检测)。
- 检查 PDF 总页数。
- 若实际页数 ≠ 目标页数,记录偏差。
严重等级:Critical
与日志信号的关联:无。
诊断记录格式:
- defect_id: A3
- description: "实际 10 页,目标 9 页,超出 1 页"
- severity: critical
A4:双栏末页左右栏高度不齐 (Unbalanced Column Heights)
定义:在双栏排版的最后一页,左右两栏的底部高度不一致,高度差超过 2 行。
视觉诊断方法:
- 仅适用于双栏模板(如 IEEE、ACM、ECCV 等)。
- 定位最后一页,在左右栏底部画一条水平参考线。
- 若两栏底部高度差超过约 2 行正文的高度,判定为缺陷。
严重等级:Minor(若与其他缺陷叠加,可升级)
与日志信号的关联:无。
诊断记录格式:
- defect_id: A4
- page: 12
- description: "左右栏底部高度差约 4 行"
- severity: minor
A5:双栏页内列竖向空洞 (Intra-Column Vertical Void)
定义:在双栏排版的任意一页(不限于末页),左栏或右栏在节标题/段落后出现占该栏可排版高度约 30% 以上的连续竖向空白,且空白内无图、无表、无正文;而同一页另一栏在相近纵坐标区间仍有连续正文。典型诱因:本页或邻页的 figure*/table* 顶出造成的栏内“断层”、滥用 \\ / \newpage / \vfill、[H] 固定浮动体、\FloatBarrier 等。
与 A2/A4 的区分:
- A2:仅最后一页正文结束后的尾部大面积留白。
- A4:仅最后一页左右栏底部不齐。
- A5:任意页、单列内部的中段竖向空洞,常伴随列间密度严重失衡。
视觉诊断方法(layout-detective 必做):
- 确认模板为双栏;对该页分别只看左栏、只看右栏( mentally 画竖线分割)。
- 在每一栏内,自上而下追踪正文墨迹的纵坐标区间;若两墨迹块之间出现高度 ≥ 约 8 行正文且无图无表的间隙,记为候选。
- 若同一纵坐标带内另一栏为连续段落,候选升级为 A5。
- 对照
compile.log中Float too large、Underfull \vbox等作为佐证。
严重等级:默认 Major(若空洞超过半栏可升为 Critical)。
诊断记录格式:
- defect_id: A5
- page: 4
- column: left
- description: "Experiments 标题下方约 55% 栏高无内容,右栏同期为连续正文"
- severity: major
- visual_evidence: "左栏中段整带空白,无 figure/table"
OpenCV 辅助(推荐):对已渲染页图执行 paperfit run scripts/detect_column_void.py data/pages --glob 'page_*.png' -o data/column_void_report.json,读取 JSON 中的 a5_candidates 与上述人工步骤交叉验证。
Category B:浮动体缺陷
此类缺陷关注图表的放置位置、尺寸匹配度以及对阅读流的干扰。
B1:浮动体远离首次引用 (Float-Reference Distance)
定义:图表出现在距离其首次被引用的页面过远的位置(通常页码差 ≥ 2)。
视觉诊断方法:
- 在 PDF 中搜索图表标签(如 "Figure 1"、"Table 2")的首次出现位置。
- 找到该图表实际出现的页面。
- 计算页码差:
|图表页码 - 首次引用页码|。 - 若差值 ≥ 2,记录缺陷。
严重等级:Major(若差值 ≥ 3,升级为 Critical)
与日志信号的关联:
- 编译日志中可能出现
LaTeX Warning: Float too large for page或浮动体放置相关的 warning,作为辅助证据。
诊断记录格式:
- defect_id: B1
- object: "Figure 3"
- reference_page: 4
- float_page: 6
- distance: 2
- severity: major
B2:浮动体大小不适配栏宽 (Float Width Mismatch)
定义:图片或表格的宽度未充分利用栏宽,过窄(两侧留白过大)或超宽(溢出或被截断)。
视觉诊断方法:
- 对于单栏图表:对比图表宽度与栏宽,目测利用率。
- 若图表宽度 < 栏宽的 85%,视为过窄。
- 若图表宽度 > 栏宽(内容伸出右边界),视为超宽。
- 对于跨栏图表(
figure*/table*):对比图表宽度与页宽,标准同上。
严重等级:
- 过窄:Minor(若多图表均过窄,升级为 Major)
- 超宽/溢出:Major
与日志信号的关联:
- 超宽常伴随
Overfull \hbox警告(参见 D1)。
诊断记录格式:
- defect_id: B2
- object: "Figure 2"
- page: 3
- description: "图片宽度仅占栏宽约 60%,两侧留白过大"
- severity: minor
B3:浮动体连续堆叠 (Float Clustering)
定义:同一页或连续两页出现 3 个或以上的图表,且中间几乎无正文间隔,形成“图表页”。
视觉诊断方法:
- 检查每一页的图表数量。
- 若某页包含 ≥ 3 个图表,且正文少于 3 行,视为浮动体堆叠。
- 若连续两页累计图表 ≥ 4 且中间正文极少,同样视为缺陷。
严重等级:Minor(但若导致阅读体验严重下降,可标为 Major)
与日志信号的关联:无直接日志,但大量浮动体可能引发 placement warning。
诊断记录格式:
- defect_id: B3
- page: 7
- description: "该页包含 3 个图表,正文仅 2 行"
- severity: minor
B4:浮动体跨页分裂 (Float Page Orphaning)
定义:一个图表(尤其是长表格)在不适当的位置断开,跨两页显示,且第二页未重复表头。
视觉诊断方法:
- 检查跨页的表格或图表。
- 若表格在分页处被截断,且下一页续表中缺少表头(或未使用
longtable的重复表头功能),判定为缺陷。
严重等级:Minor(若为关键数据表,升级为 Major)
与日志信号的关联:无。
诊断记录格式:
- defect_id: B4
- object: "Table 4"
- page: 8-9
- description: "表格跨页分裂,第二页缺少表头"
- severity: minor
Category C:排版一致性缺陷
此类缺陷关注全篇排版风格的统一性。
C1:表格字号不统一 (Inconsistent Table Font Sizes)
定义:不同表格使用了差异明显的字号,通常由 \resizebox 或手动 \tiny/\small 滥用导致。
视觉诊断方法:
- 对比全篇至少 3 个表格的字号大小。
- 若发现某些表格的字号明显小于或大于其他表格,且差异超过 1 个等级(如一个用
\small,另一个用\footnotesize),记录缺陷。 - 特别注意使用
\resizebox缩放表格导致的字号异常(文字被整体缩放,视觉上变形)。
严重等级:Minor
与日志信号的关联:无直接日志,但可在源码中搜索 \resizebox。
诊断记录格式:
- defect_id: C1
- description: "Table 1 使用 \small,Table 3 使用 \resizebox 导致字号偏小,全篇表格字号不统一"
- severity: minor
C2:图片分辨率/风格不一致 (Inconsistent Figure Quality/Style)
定义:论文中图片分辨率差异大,或风格(如字体、配色、线条粗细)不统一。
视觉诊断方法:
- 检查所有图片的清晰度,注意模糊、锯齿、像素化现象。
- 对比不同图片的视觉风格:字体类型、字号、配色方案、线条风格。
- 若差异明显(例如一张为清晰矢量图,另一张为低分辨率截图),记录缺陷。
严重等级:Minor
修复提示:此缺陷系统无法自动修复,需提示用户替换低质量图片或统一绘制风格。
诊断记录格式:
- defect_id: C2
- object: "Figure 5"
- description: "图片分辨率低,锯齿明显,与 Figure 2 的矢量图风格不一致"
- severity: minor
C3:Caption 格式不统一 (Inconsistent Caption Format)
定义:图表标题的字体、间距、编号格式、结尾标点不一致。
视觉诊断方法:
- 检查至少 3 个图表标题的格式:
- 字体是否一致(加粗/不加粗、斜体/正体)?
- 与图表主体的间距是否一致?
- 结尾是否有标点(有的以句号结尾,有的没有)?
- 表格标题位置是否一致(通常表格标题在上方,图片在下方)?
- 若发现不一致,记录缺陷。
严重等级:Minor
诊断记录格式:
- defect_id: C3
- description: "Figure 1 标题加粗,Figure 2 标题未加粗;Table 1 标题无句号,Table 2 标题以句号结尾"
- severity: minor
Category D:溢出与对齐缺陷
此类缺陷涉及内容超出边界或未正确断行,通常有明确的日志信号。
D1:Overfull hbox
定义:文本行、表格单元格或公式内容超出栏宽,LaTeX 无法自动断行。
视觉诊断方法:
- 检查页面的右边界,寻找伸出版心或栏宽的内容(可能被截断或与边界重叠)。
- 特别关注:
- 长单词(未正确断词)
- 表格中的长文本单元格
- 超长公式
- 必须结合编译日志:在
.log中搜索Overfull \hbox,获取精确的溢出位置和溢出量(pt)。
严重等级:
- 溢出量 < 5pt 且不影响阅读:Minor
- 溢出量 ≥ 5pt 或内容明显被截断:Major
诊断记录格式:
- defect_id: D1
- page: 4
- object: "段落第 3 行 / Table 2 某单元格"
- log_signal: "Overfull \hbox (12.3pt too wide) in paragraph at lines 245--248"
- visual_evidence: "单词 'implementation' 伸出右边界约 2mm"
- severity: major
D2:长公式未合理断行 (Unbroken Long Equations)
定义:过长的数学公式未在多行环境中断行,导致溢出或视觉拥挤。
视觉诊断方法:
- 检查所有公式环境(
equation、\[...\])。 - 若公式长度明显超过栏宽的 90% 且未断行,或已溢出,记录缺陷。
- 对于多行公式(
align、multline),检查断行位置是否合理(通常在等号或运算符处)。
严重等级:Major(若溢出)或 Minor(若未溢出但明显过长且可优化)
与日志信号的关联:常伴随 Overfull \hbox 警告。
诊断记录格式:
- defect_id: D2
- page: 6
- object: "Equation (12)"
- description: "单行公式长度超过栏宽,溢出约 8pt"
- severity: major
D3:URL/长标识符溢出 (URL/Long Identifier Overflow)
定义:参考文献或正文中的 URL、DOI、长标识符超出栏宽。
视觉诊断方法:
- 检查参考文献区域的 URL 和 DOI。
- 若某条 URL 伸出右边界,记录缺陷。
严重等级:Minor(但若多处出现,升级为 Major)
与日志信号的关联:常伴随 Overfull \hbox 在参考文献区域。
诊断记录格式:
- defect_id: D3
- page: 10
- object: "参考文献 [23] 的 URL"
- description: "URL 超出栏宽约 15pt"
- severity: minor
Category E:跨模板迁移缺陷
此类缺陷仅在用户执行模板切换任务时激活。
E1:单栏↔双栏图表尺寸失配
定义:模板切换后,原模板的图表尺寸设置不再适用,导致图表在新模板下尺寸不当。
视觉诊断方法:
- 对比原模板和新模板的栏宽/页宽。
- 检查所有图表:
- 若原为单栏全宽图,在新双栏模板中仍为单栏宽(应改为跨栏
figure*),图表显得过小。 - 若原为双栏跨栏图,在新单栏模板中尺寸异常。
- 若原为单栏全宽图,在新双栏模板中仍为单栏宽(应改为跨栏
- 记录所有尺寸不适配的图表。
严重等级:Critical
诊断记录格式:
- defect_id: E1
- object: "Figure 1"
- description: "原为单栏全宽图,在新双栏模板中仅占单栏,宽度利用率不足 50%"
- severity: critical
E2:页数预算不匹配
定义:模板切换后总页数与目标模板预期页数相差较大。
视觉诊断方法:
- 获取目标模板的预期页数(如 ICLR 9 页 → ECCV 14 页)。
- 对比当前 PDF 总页数与预期值。
- 若偏差超过 1 页,记录缺陷。
严重等级:Critical
诊断记录格式:
- defect_id: E2
- description: "当前 9 页,目标模板预期 14 页,需扩写 5 页内容"
- severity: critical
E3:模板特定宏兼容性
定义:新模板中使用了已废弃或冲突的宏包、命令,导致编译失败或内容缺失。
视觉诊断方法:
- 检查编译日志中的错误和警告。
- 常见信号:
Undefined control sequence、Option clash for package、Environment XXX undefined。 - 若编译失败,优先处理此类缺陷。
严重等级:Critical
诊断记录格式:
- defect_id: E3
- log_signal: "Undefined control sequence \theoremstyle"
- description: "新模板不支持 amsthm 宏包的 \theoremstyle 命令"
- severity: critical
诊断工作流指南
layout-detective-agent 应遵循以下步骤:
- 加载配置:读取
config/vto_taxonomy.yaml和本技能文档。 - 逐页审查:使用
visual-inspector技能渲染的页图,按页码顺序检查。 - 对照分类:将观察到的视觉异常与上述缺陷类型逐一比对。
- 结合日志:对于 D 类缺陷和编译问题,务必交叉验证
.log文件。 - 记录缺陷:为每个发现的缺陷生成结构化条目(包含
defect_id、page、object、description、severity)。 - 输出诊断报告:汇总所有缺陷,按严重等级和类别排序,输出 JSON 格式的诊断结果。
注意事项
- 上下文敏感:某些视觉特征在不同模板下可能有不同评判标准(如单栏 vs 双栏),需结合模板类型调整阈值。
- 优先级排序:Critical 和 Major 缺陷必须优先修复;Minor 缺陷可在主要缺陷清除后处理。
- 避免过度诊断:对于正常排版现象(如公式后的自然短行),不要误判为缺陷。
- 与代码外科医生的协作:诊断报告中的
defect_id将直接用于路由到对应的修复 Skill(参见config/vto_taxonomy.yaml中的skill_routing映射)。
本知识库将随着系统迭代不断扩充,涵盖更多边界案例和会议特定的排版规范。
Template Migrator Skill
概述
本技能专门处理 Category E:跨模板迁移缺陷,包括:
- E1:单栏↔双栏图表尺寸失配
- E2:页数预算不匹配(如 9 页→14 页的内容重分布)
- E3:模板特定宏兼容性
该技能由 code-surgeon-agent 在 /migrate-template 命令触发时调用,负责将一篇论文从原模板平滑迁移至目标模板,并自动适配图表尺寸、页数预算和宏包兼容性。这是 PaperFit 最具差异化价值的能力,直接解决了科研工作者切换会议投稿时的真实痛点。
能力边界:当前 typed runtime 没有自动模板迁移 executor,可选自动批处理的 --apply 必须报告不支持,不能偷偷回退到旧脚本。用户已授权迁移时,宿主可以用原生编辑工具完成并验证迁移,无需等待自动 executor。先核对建议:请你看看这是否是对的;保留原模板/源码及可回退候选,确认目标模板、当前编译页和内容。
适用场景
| 缺陷 ID | 描述 | 优先级 | 是否允许语义修改 |
|---|---|---|---|
| E1 | 单栏↔双栏图表尺寸失配 | Critical | 否 |
| E2 | 页数预算不匹配 | Critical | 是(最后手段) |
| E3 | 模板特定宏兼容性 | Critical | 否 |
输入规范
| 输入项 | 来源 | 说明 |
|---|---|---|
主 .tex 文件路径 | 项目上下文 | 需修改的源文件 |
| 目标模板名称 | 用户命令参数 | 如 ECCV2024、ICLR2025 |
| 模板配置 | config/templates.yaml | 包含目标模板的栏数、默认字号、页宽、预期页数等 |
| 原模板信息 | 自动检测或用户指定 | 当前 \documentclass 及主要宏包 |
| 排版侦探报告 | layout-detective-agent | 迁移后首次编译的 E 类缺陷列表 |
输出规范
{
"skill": "template-migrator",
"status": "success | partial | failed",
"modified_files": ["main.tex", "figures/fig1.tex"],
"changes": [
{
"defect_id": "E1",
"object": "Figure 1",
"action": "单栏图改为跨栏图",
"before": "\\begin{figure}\n\\includegraphics[width=\\linewidth]{fig1.pdf}\n\\end{figure}",
"after": "\\begin{figure*}\n\\includegraphics[width=\\textwidth]{fig1.pdf}\n\\end{figure*}"
}
],
"macro_fixes": [
{
"issue": "\\theoremstyle undefined in ECCV",
"fix": "改用 \\newtheorem 直接定义"
}
],
"unresolved": [],
"page_budget_status": {
"current_pages": 9,
"target_pages": 14,
"gap": 5,
"action_taken": "核对用户页数政策并比较保持内容的布局候选"
}
}
迁移流程
第一步:加载模板配置
- 从
config/templates.yaml读取目标模板的完整配置。 - 配置项包括:
documentclass:如\documentclass[10pt,twocolumn]{article}或\documentclass{iclr2025}column_type:single或doubledefault_figure_width:\linewidth或\textwidthexpected_pages:配置中的页数参考值;不能代替用户指定的 exact/at_most、正文/参考文献/附录范围或当前投稿规则forbidden_packages:与新模板冲突的宏包列表required_packages:新模板必须加载的宏包
示例配置(config/templates.yaml 片段):
ECCV2024:
documentclass: "\documentclass[10pt,twocolumn]{article}"
column_type: double
default_figure_width: "\linewidth"
expected_pages: 14
forbidden_packages: ["amsthm", "algorithm2e"]
required_packages: ["graphicx", "amsmath", "amssymb"]
float_behavior: "figures may use figure* for wide content"
第二步:分析原模板特征
- 读取当前主
.tex文件的\documentclass声明。 - 识别当前栏数(单栏/双栏)。
- 列出当前加载的宏包列表(
\usepackage{...})。 - 若用户未明确指定原模板,尝试根据
\documentclass自动推断。
第三步:执行模板替换
候选管理:
- 写入前保留迁移前源码和资源,避免覆盖作者尚未保存的改动。
- 宿主可用正常 patch/编辑工具形成连贯候选,合理组合 class、宏包和对象适配;无需强制调用指定写盘函数。
- 编译失败时先检查并修复根因,或恢复最近可用候选;保留失败记录和有用的独立改动。
- 中间编译可用于定位兼容问题,半完成状态不得当作最终迁移成功。
3.1 替换 \documentclass
将原 \documentclass 替换为目标模板的声明。
% 修改前(ICLR 2025 单栏)
\documentclass{iclr2025}
% 修改后(ECCV 2024 双栏)
\documentclass[10pt,twocolumn]{article}
注意:若目标模板有多个可选参数(如 review、final),询问用户偏好或使用默认值。
3.2 处理宏包冲突
- 对比原宏包列表与目标模板的
forbidden_packages。 - 若存在冲突,执行以下操作之一:
- 移除:直接注释或删除该
\usepackage行。 - 替换:提供替代方案(如
algorithm2e→algorithmic)。 - 条件编译:使用
\ifdefined等实现跨模板兼容。
- 移除:直接注释或删除该
% 修改前(含 amsthm,与新模板冲突)
\usepackage{amsthm}
\newtheorem{theorem}{Theorem}
% 修改后(改用 LaTeX 原生定义)
% \usepackage{amsthm} % removed for template compatibility
\newtheorem{theorem}{Theorem}
3.3 添加必需宏包
若目标模板要求特定宏包(如 graphicx),确保导言区已加载。若缺失,添加之。
% 确保必需宏包存在
\usepackage{graphicx}
\usepackage{amsmath}
第四步:图表尺寸适配(E1 修复)
这是跨模板迁移中最关键、最易出错的环节。
4.1 判断单栏/双栏切换方向
| 原模板 | 目标模板 | 处理策略 |
|---|---|---|
| 单栏 | 双栏 | 所有图表默认改为单栏宽(\columnwidth),宽图改为跨栏(figure*) |
| 双栏 | 单栏 | 所有跨栏图(figure*)改为普通图(figure),宽度改为 \linewidth |
| 双栏 | 双栏 | 保持原策略,仅检查宽度是否适配新模板的栏宽 |
| 单栏 | 单栏 | 基本不变,仅检查页宽是否变化 |
4.2 智能判断哪些图应跨栏(单栏→双栏时)
对于原单栏中的全宽图,在双栏中若仍用单栏会显得过小。需根据图片宽高比智能决策:
- 若图片宽度 > 高度 × 1.5(宽高比 > 1.5),建议改为跨栏
figure*。 - 若图片宽度 ≤ 高度 × 1.5,保留单栏
figure,但宽度设为\columnwidth。
% 原单栏全宽图(宽度 = \linewidth)
\begin{figure}
\includegraphics[width=\linewidth]{wide_arch.pdf}
\end{figure}
% 迁移后(宽高比大,改为跨栏)
\begin{figure*}
\includegraphics[width=\textwidth]{wide_arch.pdf}
\end{figure*}
4.3 处理表格宽度
- 单栏表格在双栏中:宽度改为
\columnwidth。 - 若原表格为
tabularx{\linewidth},改为tabularx{\columnwidth}。 - 若表格列数过多,考虑改为跨栏
table*并使用\textwidth。
% 修改前(单栏宽表)
\begin{table}
\begin{tabularx}{\linewidth}{|l|X|X|}
...
\end{tabularx}
\end{table}
% 修改后(双栏单栏宽表)
\begin{table}
\begin{tabularx}{\columnwidth}{|l|X|X|}
...
\end{tabularx}
\end{table}
4.4 特殊对象处理
- 长公式:双栏中公式宽度受限,可能需将
equation改为multline或align并手动断行。 - 算法伪代码:双栏中宽度减半,可能需要调整缩进或改为跨栏
figure*。
第五步:编译并检测遗留问题
- 完成上述修改后,执行首次编译。
- 若编译失败,解析日志中的
Undefined control sequence等错误(E3),返回第三步修正宏包冲突。 - 若编译成功,渲染页图,调用
layout-detective-agent检测 E1/E2 缺陷。
第六步:页数预算调整(E2 修复)
- 获取当前 PDF 总页数。
- 按用户授权的目标、exact/at_most 政策和计页范围计算偏差;配置中的
expected_pages仅为参考。 - exact 差一页仍未完成;at_most 只判定是否超上限,不能把不足页数当作必须扩写的缺陷。未知范围不得称为已满足。
- 从迁移开始同时考虑页数和阅读质量。按
space-util-fixer比较原生布局、人工空白、对象容器和自然流动;增页修改应同步考虑补偿候选。 - 不默认扩写、删句或填空白。正文编辑只在已有单独授权内进行,并独立核对学术原意;没有
--keep-content不是改内容的授权。
第七步:生成迁移报告
输出一份 Markdown 迁移报告,包含:
- 目标模板信息
- 已修改的文件列表
- 图表尺寸变更清单(哪些图改为跨栏、哪些保留单栏)
- 宏包冲突及解决方案
- 页数调整结果(初始页数 → 最终页数)
- 人工检查建议(如“请确认 Figure 3 改为跨栏后视觉效果”)
双栏迁移的特别注意事项
双栏模板的排版行为与单栏有本质不同:
- 跨栏位置取决于活动模板和输出例程:先检查模板支持的放置方式,并对照当前及邻页编译结果。不要一概断言只能页顶、必然下一页或永远不支持页底;不为某个通用规则盲目添加宏包。
- 浮动体调度更复杂:双栏中浮动体更容易堆积(B3),可能需要手动插入
\FloatBarrier或调整源码位置。 - 公式编号:双栏中公式编号通常在右侧,若原单栏模板编号在左侧,需检查是否冲突。
与其它技能的协作
- 浮动体优化 (float-optimizer):迁移后检查是否存在新的浮动体问题,需要时配合修复。
- 空间利用修复 (space-util-fixer):页数调整依赖此技能。
- 语义润色 (semantic-polish-agent):扩写/缩写时调用。
验证标准
迁移成功的判定标准:
- 编译成功,无阻塞性错误
- 所有图表在新模板下尺寸适配(无溢出、无过窄)
- 页数符合目标模板预期(或用户接受偏差)
- 无未解决的宏包冲突
- 视觉风格与目标模板一致
Template Migrator Skill 就绪。
Visual Inspector Skill
概述
本技能是 PaperFit 视觉排版优化闭环中的关键环节,专门负责 PDF 页图渲染与视觉验收指导。它封装了将 PDF 转换为逐页高分辨率图片的标准化流程,并为 layout-detective-agent 和 quality-gatekeeper-agent 提供详细的逐页视觉检查清单。
该技能由 orchestrator-agent 在每次编译后调用,确保多模态证据链中的“页图”环节可靠、一致且可复现。
适用场景
- 每次编译成功后,需生成页图供视觉 Agent 审查。
- 手动触发视觉检查(如
/check-visual命令)。 - 修复前后对比验证。
输入规范
| 输入项 | 来源 | 必需 | 说明 |
|---|---|---|---|
| PDF 文件路径 | 编译输出 | ✅ | 通常为 main.pdf |
| 输出目录 | 配置或默认 | ✅ | 页图存放目录,默认为 data/pages/ |
| DPI 参数 | 配置或调用方指定 | ✅ | 渲染分辨率,默认 220 DPI |
| 页码范围 | 调用方指定 | ⚠️ | 若为空,渲染全部页面 |
| 局部裁剪参数 | 调用方指定 | ⚠️ | 如 {page: 5, bbox: [x,y,w,h]},用于表格/公式局部复查 |
| PDF native geometry | 编译输出 PDF | ⚠️ | 若安装 PyMuPDF,可作为 B2 宽度和 D1 overflow 的辅助机器信号 |
输出规范
本技能输出两份产物:
- 页图文件集:PNG 或 JPG 格式的逐页图片,命名规则为
page_001.png、page_002.png等。 - 渲染报告 JSON:
{
"skill": "visual-inspector",
"status": "success | partial | failed",
"pdf_path": "main.pdf",
"output_dir": "data/pages/",
"dpi": 220,
"pages_rendered": 9,
"page_files": [
{"page": 1, "file": "data/pages/page_001.png", "width": 1700, "height": 2200},
{"page": 2, "file": "data/pages/page_002.png", "width": 1700, "height": 2200}
],
"cropped_regions": [
{
"page": 5,
"object": "Table 2",
"file": "data/pages/page_005_table2.png",
"bbox": [100, 450, 800, 300]
}
],
"errors": []
}
渲染流程
第一步:环境检查
- 确认 PDF 文件存在且可读。
- 检查 Python 环境及所需依赖:
pdf2image库- Poppler 工具(
pdftoppm或pdftocairo)
若 Poppler 未安装,根据操作系统提供安装指引:
# Debian/Ubuntu
sudo apt-get install poppler-utils
# macOS
brew install poppler
# Windows
# 下载 poppler 并添加到 PATH,或使用 conda install -c conda-forge poppler
- 若依赖缺失,报告错误并终止,由上层 Agent 提示用户安装。
可选 native geometry 检测依赖:
PyMuPDF(Python import 名为fitz):用于读取 PDF 原生 object/text bbox,辅助检测 B2 宽度不足/超宽与 D1 native overflow。- 该信号不是页图验收替代品;即使 PyMuPDF 不可用,也应继续渲染页图并完成视觉检查。
第二步:执行渲染
禁止在用户 LaTeX 项目里假设存在 scripts/render_pages.py。页图渲染由 PaperFit npm/CLI 包提供,在论文项目根目录执行:
paperfit render <相对或绝对路径的.pdf> --output data/pages --dpi 220
# 示例
paperfit render main.pdf --dpi 300
前提:npm install -g paperfit-cli(或等价全局安装),paperfit 在 PATH 中。输出目录 --output 相对于当前工作目录(一般为论文根目录)。
其它包内 Python/Bash(如 parse_log.py、state_manager.py)一律在论文根目录使用 paperfit run scripts/<文件名> [参数…],勿在用户项目里假设存在同名 scripts/。
若仅能通过 Python 调用包内脚本,先执行 paperfit root 得到包根目录,再:
python3 "$(paperfit root)/scripts/render_pages.py" main.pdf --dpi 220
(或直接调用 pdf2image 库,逻辑须与下方一致。)全局未装 paperfit 时可用:npx paperfit-cli render …。
基础渲染命令(库级参考)
from pdf2image import convert_from_path
pages = convert_from_path(
pdf_path,
dpi=220,
fmt='png',
thread_count=2,
grayscale=False,
size=None
)
for i, page in enumerate(pages, start=1):
page.save(f"{output_dir}/page_{i:03d}.png", "PNG")
渲染参数建议
| 场景 | DPI | 说明 |
|---|---|---|
| 整页常规检查 | 180-220 | 平衡清晰度与文件大小 |
| 表格/公式细节复查 | 260-320 | 需清晰辨认小字号或密集内容 |
| 局部裁剪复查 | 320 | 聚焦特定区域,可接受较大文件 |
PyMuPDF native geometry(可选)
当 runtime 已记录编译 PDF 路径时,视觉聚合阶段可调用:
paperfit run scripts/visual_signal_aggregator.py data/pages --output data/visual_signal_report.json --pdf main.pdf
该报告会把 native PDF bbox 映射到渲染页图坐标,并输出:
source=pymupdf_native- B2
subtype=underfilled_width或subtype=overflow_width width_context、object_width_ratio、object_width_page_ratio- D1 native overflow 的
overflow_pt与pdf_bbox
使用这些信号时必须回看对应 page_*.png;不要只凭 PDF 文本/对象抽取宣称视觉修复成功。
第三步:局部区域裁剪(可选)
当 layout-detective-agent 需要对特定表格、公式或段落进行高精度复查时,可请求渲染局部区域。
- 首先以较高 DPI(如 320)渲染整页。
- 根据调用方提供的边界框(bbox)裁剪图片。
- 保存裁剪后的图片,命名包含对象标识(如
page_005_table2.png)。
裁剪示例:
from PIL import Image
full_page = Image.open(f"{output_dir}/page_005.png")
cropped = full_page.crop((x1, y1, x2, y2))
cropped.save(f"{output_dir}/page_005_table2.png")
第四步:生成渲染报告
记录渲染结果,包括:
- 成功渲染的页数
- 每页图片的路径和尺寸
- 裁剪区域信息(如有)
- 错误或警告(如某些页渲染失败)
视觉检查清单
以下清单供 layout-detective-agent 在逐页审查时参考。本技能不执行检查,仅提供指导框架。
通用检查项(每页必查)
- 页面整体信息密度是否均衡?是否存在大面积无意义留白?
- 页眉、页脚、页码是否完整且位置正确?
- 是否有内容伸出页边距或栏宽?
- 图表是否清晰可读,无模糊或锯齿?
- 段落末尾是否有孤行或短尾巴?
首页专项
- 标题、作者、机构信息是否完整,格式是否正确?
- 摘要段是否与模板风格一致?
- 是否有不必要的空白或过大的标题间距?
正文页专项
- 章节标题是否突出且一致?
- 图表与正文的衔接是否自然?图表是否在引用附近?
- 跨页段落是否合理断开?
- 双栏布局中左右栏高度是否平衡(尤其末页)?
- (A5 必查)双栏每一页:左右栏分别审视是否存在「栏内中段占栏高约 30%+、无图无表、无正文」的竖向空洞,且另一栏同期仍有连续正文(节标题下大块白缝是典型的漏检点)
- (A5 可选) 已安装 OpenCV 时运行
paperfit run scripts/detect_column_void.py data/pages -o data/column_void_report.json,将机器投影结果与肉眼结论交叉验证
末页专项
- 参考文献是否完整,无被浮动体切断?
- 含
Acknowledgements/References/Bibliography的页上是否出现正文图表标题或正文浮动体?若有,按硬失败处理。 - 末页留白是否在可接受范围(<20%)?
- 若为双栏,左右栏底部是否对齐?
表格专项
- 表格宽度是否匹配栏宽?有无超宽或过窄?
- 若 visual signal 中有
source=pymupdf_native的 B2 报告,对照页图检查width_context、object_width_ratio和 bbox 是否合理。 - 列宽分配是否均衡?有无单列过宽挤压其他列?
- 表格字号是否与全篇其他表格一致?
- 表格线是否清晰?推荐使用
booktabs风格。
图片专项
- 图片是否清晰,分辨率足够?
- 图片宽度是否充分利用栏宽?
- B2 宽度问题应区分单栏对象与跨栏对象;PyMuPDF 的
width_context=column|page只能作为辅助判断。 - 图片标题是否在图片下方(表格标题在上方)?
- 图片中的文字(坐标轴标签、图例)是否可读?
公式专项
- 公式是否超出栏宽?
- 多行公式是否在合理位置断行并对齐?
- 公式编号是否在正确位置(通常右侧)?
与其它 Agent 的协作
- 上游调用者:
orchestrator-agent在编译成功后调用本技能。 - 下游消费者:
layout-detective-agent使用页图进行视觉缺陷检测。quality-gatekeeper-agent使用页图进行最终验收对比。code-surgeon-agent在修复后可能请求局部页图验证特定修改。
异常处理
| 异常情况 | 处理方式 |
|---|---|
| Poppler 未安装 | 返回明确错误信息,包含安装指引 |
| PDF 文件损坏 | 报告错误,请求重新编译 |
| 部分页渲染失败 | 记录失败页码,尽可能渲染其余页,状态标记为 partial |
| 磁盘空间不足 | 报告错误,清理临时目录或提示用户释放空间 |
性能优化建议
- 对于大型 PDF(>20 页),可考虑仅渲染指定页码范围,避免不必要开销。
- 缓存机制:若 PDF 文件未修改且渲染参数相同,可复用已有页图。通过比较 PDF 文件哈希和渲染参数实现。
注意事项
- 页图是视觉验收的唯一依据:严禁仅凭 PDF 文本抽取或日志判断排版质量。
- 保持页码对应:页图文件名必须明确反映页码,便于缺陷定位。
- 高 DPI 不宜滥用:过高 DPI 会导致图片体积庞大,影响传输和加载速度,按需使用。
Visual Inspector Skill 就绪。
Writing Polish Skill
概述
本技能为 Semantic Polish Agent 提供具体、可执行的语义微调策略与禁区规则。它定义了在排版手段用尽后,如何通过最小化文字增删来消除孤行寡行、控制页数预算或优化末页留白,同时严格保持学术内容的原意、数据和结论不变。
该技能不直接被 orchestrator-agent 调用,而是作为 semantic-polish-agent 的知识库和行为规范。所有语义级改写必须遵循本技能中定义的技巧和约束。
Source-changing 边界:语义级改写是高风险 source mutation。默认只能生成候选改写、风险和 approval 状态;只有显式 --apply 或宿主等价授权存在时才允许写回。多轮语义改写必须同时显式启用 --apply --max-rounds N,并且每轮都通过 approval carry-forward、artifact freshness、candidate approval scope gate 和 gatekeeper CONTINUE;超出既有 approval scope 的语义修改必须重新获批。
适用场景
| 触发缺陷 | 操作方向 | 允许的改写幅度 |
|---|---|---|
| A1(孤行寡行) | 缩短 1-2 行 | 增删 3-8 词 |
| A2(末页留白) | 扩展 2-4 行 | 增加 20-50 词 |
| A3(页数预算) | 缩短或扩展多行 | 按需,但需分段执行 |
| 用户主动请求 | 精炼或扩写特定段落 | 用户指定 |
输入规范
| 输入项 | 来源 | 说明 |
|---|---|---|
| 目标段落源码 | semantic-polish-agent 提取 | 需改写的一个或多个完整段落 |
| 改写目标 | 调用方请求 | shorten 或 expand,及期望行数变化 |
| 写作规范 | config/writing_rules.yaml | 时态、术语、禁用词等约束 |
| 上下文段落 | semantic-polish-agent 提取 | 前后各一段,用于保证语义连贯 |
输出规范
本技能输出改写后的文本及变更元数据,供 semantic-polish-agent 整合为最终报告。
{
"skill": "writing-polish",
"changes": [
{
"paragraph_id": 3,
"action": "shorten",
"net_word_change": -6,
"before_snippet": "It is worth noting that our method achieves state-of-the-art performance on several benchmark datasets.",
"after_snippet": "Our method achieves state-of-the-art results on several benchmarks.",
"techniques_used": ["remove_redundant", "phrase_to_word"],
"rationale": "移除冗余修饰词,将 'achieves state-of-the-art performance on several benchmark datasets' 压缩为 'achieves state-of-the-art results on several benchmarks'。语义等价,数据未变。"
}
],
"warnings": []
}
改写策略
通用原则
- 最小修改优先:能改一词不改一句,能改一句不改一段。
- 保持学术严谨:绝不改变数据值、引用标记、专有名词、核心声明。
- 局部影响评估:每次改写后需编译验证,确保不引入新的孤行或溢出。
- 可逆性:保留改写前文本,便于人工审查或回滚。
策略组 1:缩短(Shorten)
目标:在不损失信息的前提下减少字数/行数。
技巧 1.1:删除冗余修饰词
移除对学术内容无实质贡献的修饰语。
- 删除强调性副词:
very、quite、extremely、highly - 删除填充短语:
It is worth noting that、It should be emphasized that、It is important to mention that - 删除冗余限定:
in a certain sense、to some extent
示例:
修改前:It is worth noting that our method achieves very competitive performance.
修改后:Our method achieves competitive performance.
减少:5 词
技巧 1.2:短语替换为单词
用更简洁的单词或缩写替代多词短语。
| 原短语 | 替换为 |
|---|---|
in order to | to |
a large number of | many |
due to the fact that | because |
at the present time | now |
state-of-the-art methods | SOTA methods(需已定义) |
with respect to | regarding 或 on |
示例:
修改前:We conduct experiments in order to evaluate the performance of the proposed approach.
修改后:We conduct experiments to evaluate our approach.
减少:5 词
技巧 1.3:被动语态转主动语态
主动语态通常更简短且更有力。
修改前:The experiments were conducted by us on three datasets.
修改后:We conducted experiments on three datasets.
减少:3 词
技巧 1.4:合并相邻短句
将两个紧密相关的短句合并为一句。
修改前:We used the Adam optimizer. The learning rate was set to 1e-4.
修改后:We used Adam with a learning rate of 1e-4.
减少:6 词
技巧 1.5:使用标准学术缩写
在全文首次定义后,使用公认缩写。
| 原词 | 缩写 |
|---|---|
state-of-the-art | SOTA |
natural language processing | NLP |
mean average precision | mAP |
修改前:Our method outperforms previous state-of-the-art approaches on the natural language processing benchmark.
修改后:Our method outperforms previous SOTA approaches on the NLP benchmark.
减少:5 词(假设 SOTA/NLP 已定义)
技巧 1.6:简化从句结构
将定语从句压缩为分词短语或前置定语。
修改前:The model which is trained on ImageNet achieves high accuracy.
修改后:The ImageNet-trained model achieves high accuracy.
减少:3 词
策略组 2:扩展(Expand)
目标:在不注水的前提下增加有实质内容的文字。
技巧 2.1:显式化隐含因果关系
在结果陈述后补充简短的原因解释。
修改前:Our method outperforms the baseline by 3.2%.
修改后:Our method outperforms the baseline by 3.2%, likely because the attention mechanism better captures long-range dependencies.
增加:11 词
技巧 2.2:补充结果解释
在表格或数据引用后,增加一句对关键发现的解读。
修改前:Table 2 shows the ablation results.
修改后:Table 2 summarizes the ablation study. Removing the temporal module causes a significant drop of 5.1%, confirming its importance for sequential modeling.
增加:18 词
技巧 2.3:强化与相关工作的对比
在提及已有工作时,增加具体的差异说明。
修改前:Unlike previous work, we use a transformer-based architecture.
修改后:Unlike previous work that relied on recurrent networks with limited parallelization, we adopt a transformer architecture that scales more efficiently to long sequences.
增加:14 词
技巧 2.4:添加局限性讨论
在结论或讨论部分,补充一句对当前方法局限性的客观陈述。
修改前:Future work will explore larger-scale datasets.
修改后:Future work will explore larger-scale datasets. A current limitation is the reliance on pre-trained word embeddings, which may not fully capture domain-specific terminology.
增加:17 词
技巧 2.5:拆分长句为短句
通过增加句号拆分长句,可在不显著增加内容的情况下扩展行数。
修改前:Our method consists of three components: an encoder, a decoder, and a refinement module.
修改后:Our method consists of three components. First, the encoder extracts features from the input. Second, the decoder generates initial predictions. Finally, the refinement module iteratively improves the output.
增加:14 词,行数增加更多
技巧 2.6:补充技术细节(谨慎)
在不泄露未公开信息的前提下,可适当补充已在论文其他部分出现过的技术细节。
修改前:We use a standard cross-entropy loss.
修改后:We use a standard cross-entropy loss with label smoothing of 0.1, following common practice in image classification.
增加:10 词
改写禁区(绝对禁止)
以下操作 严禁 进行,违反任何一条都不得输出修改。
禁区 1:篡改数据与结果
- 不得修改任何数值、百分比、指标名称。
- 不得增删或更改实验设定、数据集名称、模型参数。
- 不得修改表格中的任何单元格内容。
禁区 2:编造内容
- 不得引入原论文中不存在的引用、相关工作、方法细节。
- 不得虚构实验、消融研究、用户调查。
- 不得添加未经作者确认的局限性或未来工作方向(除非是论文其他部分明确提及的内容)。
禁区 3:改变核心声明
- 不得弱化或夸大论文的贡献声明。
- 不得修改结论段落中的主要论断。
- 不得改变任何
\ref{}或\cite{}的引用关系。
禁区 4:引入非学术表达
- 不得使用口语化、情绪化、主观化的语言。
- 不得添加无意义的填充句(如
This is a very interesting result.后无任何分析)。 - 不得违反
config/writing_rules.yaml中的任何硬规则(如时态混乱、口语缩写)。
禁区 5:破坏 LaTeX 结构
- 不得修改
\section、\label、\ref、\cite等关键命令。 - 不得增删或修改
\begin{...}和\end{...}环境边界。 - 不得在公式环境内进行语义改写。
改写验证清单
每完成一次改写,semantic-polish-agent 必须自检以下项目:
- 所有数值、百分数、指标名称是否与原段落完全一致?
- 所有
\ref{}、\cite{}命令是否未被触碰? - 时态是否与上下文一致(相关工作用现在时,方法/实验用过去时)?
- 专有名词(方法名、模型名、数据集名)是否拼写正确且未变?
- 若引入了新缩写,是否在首次出现处已定义?
- 改写后的段落是否与前后文语义连贯?
- 是否有违反禁区的操作?
若任何一项未通过,必须回退并尝试其他改写方案。
与其它技能的协作
- Space Utilization Fixer:当排版手段(
\looseness等)无法解决孤行或页数问题时,向semantic-polish-agent发出请求。 - Semantic Polish Agent:本技能的直接使用者,严格按照本技能定义的策略和禁区执行改写。
- Quality Gatekeeper Agent:在最终验收时审查语义改写的合理性,确保未违反禁区。
常见问题与边界处理
Q:如果段落已经很精炼,无法再缩短怎么办?
A:标记为 failed,并向 semantic-polish-agent 返回明确原因(如“段落仅含 3 句,每句均含必要信息,无法在不损害语义的前提下缩短”)。
Q:扩展时如何避免注水?
A:优先使用技巧 2.1-2.4,这些技巧均基于论文已有信息进行显式化或深度解读。若确无扩展空间,同样标记 failed。
Q:是否可以跨段落操作? A:原则上应优先在目标段落内解决。若确需跨段落(如将前一页的句子后移以消除孤行),需明确标注跨段落的改动范围,并确保逻辑连贯。
Q:改写后是否需要重新编译? A:是。任何语义改写都可能改变分页,必须重新编译并经过视觉验收,确保达到了预期效果且未引入新缺陷。
Writing Polish Skill 就绪。
Commands 7
/adjust-length — 调整页数
作用: 尝试通过排版微调或受控语义改写逼近目标页数。它是专家快捷入口;普通自然语言如“把正文压到 8 页,尽量不要改语义”也应能触发同类任务。
用户入口说明:
- 用户表达目标页数与约束即可,不需要手动执行内部命令。
- 长度调整仍然属于视觉闭环任务,不能只看字数或页数数字。
- 语义改写只能在排版手段用尽后受控触发。
工具调用约定
编译、渲染、日志解析等统一见 CLAUDE.md「系统架构与运行时边界」:paperfit render、paperfit run scripts/…。
长度调整属于 source-changing 任务。默认只生成诊断、候选计划和 approval 状态;只有用户显式授权 --apply 或等价自然语言许可时才允许写回 .tex。多轮源码写回必须同时显式授权 --apply --max-rounds N,并且第二轮及以后由 runtime 的 repair_loop_policy.second_round_apply_readiness、approval carry-forward、artifact freshness、candidate approval scope gate 和 gatekeeper CONTINUE 共同放行。
用法
/adjust-length
也可以由自然语言触发,例如:
用 PaperFit 把正文压到 9 页
把这篇论文扩到满 8 页,但不要破坏结论与结果表达
执行流程
- 分析当前页数与目标页数的偏差
- 若超页:优先压缩浮动体、优化版面结构、精炼表述
- 若不满页:优先做版面与结构补强,必要时受控扩写结论/讨论
- 每轮都回到视觉验收,确认页数变化没有破坏整体版面
- 语义干预仅在排版手段用尽后使用
- 若未授权
--apply,输出 dry-run 修复计划、风险和 approval 状态,不执行源码写回
调度
- 语义润色:
agents/semantic-polish-agent.md - 技能:
skills/space-util-fixer/、skills/writing-polish/
Use the PaperFit skill for this inspection request: $ARGUMENTS
Read the installed paperfit skill, or run paperfit root and read skills/paperfit/SKILL.md beneath that directory. Locate the real main file, compile and render, inspect the page images with this host's image tool, and report visible defects with page and source object anchors. Use the compact host_context.py report for source locations. This inspection does not authorize layout source edits.
Use the PaperFit skill for this layout repair request: $ARGUMENTS
Read the installed paperfit skill, or run paperfit root and read skills/paperfit/SKILL.md beneath that directory. Diagnose the actual source and page images, make small host edits within the requested scope, and recompile and inspect the final PDF.
The request to repair authorizes relevant source edits. An optional guarded batch is paperfit fix-layout --main "<root.tex>" --apply --max-rounds 3. CLI execution is a tool, not the completion criterion; continue with an evidence-based host edit for unsupported candidates. Preserve paper content, captions, labels, and template formatting. Deliver the verified PDF and remaining issues.
/migrate-template — 跨模板排版迁移
作用: 将论文从原模板迁移至目标模板,自动处理图表尺寸、页数、宏兼容性等问题。它是专家快捷入口;普通自然语言如“把这篇论文迁移到 CVPR 模板”也应能触发同类任务。
用户入口说明:
- 用户只需要描述迁移目标,不需要手动编排内部 CLI。
- CLI、runtime、scripts 是 Agent 的内部执行层。
- 模板迁移完成后,必须回到视觉闭环重新验收。
工具调用约定
闭环中的编译与页图渲染使用 paperfit run scripts/compile.sh(或 latexmk)与 paperfit render,见 CLAUDE.md 运行时边界一节。
模板迁移会修改源码和模板声明,因此默认以 source-changing dry-run 方式生成迁移计划、风险和 approval 状态。当前 typed runtime 尚未提供 runtime-owned template migration executor,因此即使用户传入 --apply,也必须阻断并报告 template_migration_apply_requires_runtime_owned_migration_executor,不能回退到旧的直接源码迁移脚本。未来启用多轮写回时必须同时显式授权 --apply --max-rounds N,并且每轮都必须通过 approval carry-forward、artifact freshness、candidate approval scope gate 与 gatekeeper CONTINUE。
用法
/migrate-template
也可以由自然语言触发,例如:
用 PaperFit 把这篇论文迁移到 CVPR 模板
把当前论文从 AAAI 模板迁到 ICLR,并尽量保持版面稳定
执行流程
- 识别当前模板与目标模板,必要时补充最少量澄清
- 加载模板配置(
config/templates.yaml) - 替换
\documentclass和宏包 - 调用
template-migrator处理图表和兼容性 - 启动 VTO 闭环(Category E 优先)
- 输出迁移报告与视觉验收结果
- 当前未实现 runtime-owned migration executor;
--apply只能返回阻断报告,不得绕过 approval gate 调用旧迁移脚本
调度
- 执行器:
agents/orchestrator-agent.md - 技能:
skills/template-migrator/SKILL.md - 任务类型:
template_migration
Use the PaperFit skill for this request: $ARGUMENTS
Read the installed paperfit skill, or run paperfit root and read skills/paperfit/SKILL.md beneath that directory. Follow it in this host session: inspect compiled page images, use normal editing tools for authorized repairs, recompile, and verify the final images. If the request is empty, inspect the current paper and report its layout issues.
A separate agent is optional. Do not require a questionnaire, new API model, or task harness to start. The optional guarded batch paperfit fix-layout --main "<root.tex>" --apply --max-rounds 3 applies only to repair requests. CLI dry-run findings are not a completed repair.
/repair-table — 修复表格
作用: 针对指定表格或当前论文中的表格问题执行修复闭环。它是专家快捷入口;普通自然语言如“修 Table 2 太挤的问题”也应能触发同类任务。
用户入口说明:
- 用户只需要描述哪张表有问题,或直接说明“修表格”。
- 不要要求用户手动执行
paperfit render、compile.sh或其它内部命令。 - 表格修复必须以视觉可读性和结构完整性为主,而不是靠暴力缩放过关。
工具调用约定
验证阶段在论文根目录使用 paperfit run scripts/compile.sh / paperfit render,勿假设项目内存在包级 scripts/。
表格修复属于 source-changing 任务。默认只生成 repair plan、风险和 approval 状态;只有用户显式授权 --apply 或等价许可时才允许写回表格源码。多轮表格写回必须同时显式授权 --apply --max-rounds N,并由 runtime 的 approval carry-forward、artifact freshness、candidate approval scope gate、per-round lineage 和 gatekeeper CONTINUE 控制。
用法
/repair-table
也可以由自然语言触发,例如:
用 PaperFit 修复这篇论文的表格问题
修一下 Table 2,当前太挤而且列宽不平衡
执行流程
- 定位指定表格或自动识别主要表格问题
- 分析表格溢出、一致性、列宽和可读性问题
- 重构列格式、调整列间距、必要时改用更合适的表格布局策略
- 重新编译并回到视觉验证
- 未授权
--apply时只交付候选修复、风险说明和 approval 状态
调度
- 代码外科医生:
agents/code-surgeon-agent.md - 技能:
skills/overflow-repair/、skills/consistency-polisher/
/show-status — 查看任务状态
作用: 显示当前 PaperFit 任务的 runtime 状态、证据链、approval/gate 情况和下一步行动;这是当前默认的“摘要 / 解释”入口。
用户入口说明:
/show-status是查询入口,用户不需要理解state.json的字段结构。- 输出应优先解释当前任务状态、视觉问题、剩余风险和下一步动作,而不是直接倾倒内部 JSON。
- 若用户用普通自然语言询问“当前 PaperFit 到哪一步了”“还有哪些问题没修完”,也应路由到同类状态查询。
工具调用约定
优先使用 runtime status contract:
paperfit status
paperfit status-view
若需读写状态文件以外的包内工具,在论文根目录使用 paperfit run scripts/state_manager.py …,勿将 scripts/ 当作用户仓库内路径。
用法
/show-status
也可以由自然语言触发,例如:
查看当前 PaperFit 状态
这篇论文现在还剩哪些排版问题
执行流程
- 读取
paperfit status-view或等价 runtime status。 - 优先展示 selected
RunResult、任务类型、运行状态、最近门禁决策和 runtime event 摘要。 - 显示 artifact freshness、terminal success guard、content integrity。
- 显示缺陷摘要、视觉重点页与重点对象。
- 显示 repair plan / repair execution / approval 摘要。
- 对 source-changing run,必须显示
repair_loop_policy:- approval carry-forward
- candidate approval scope gate
- round artifact lineage
- second-round apply readiness
- 若状态为 blocked,显示阻塞原因:dry-run approval required、scope gate blocked、freshness failed、round limit reached 或 gatekeeper blocked。
- 显示相关报告路径与下一步行动。
输出内容
- 项目主文件
- 任务类型与约束
- 当前轮次 / 最大轮次
- 编译结果与页图渲染状态
- Artifact freshness 与 terminal success guard
- Approval 状态、candidate gate 状态、second-round readiness
- 缺陷摘要(已修复/剩余)
- 视觉重点页与重点对象
- 修复计划摘要与最近执行结果
- 最近一次门禁决策及下一步行动
- 诊断报告路径
调度
- 不调用修复 Agent,不触发 compile/render/repair。
- 读取 runtime status contract;CLI 等价入口是
paperfit status,机器可读入口是paperfit status-view。
Agents 6
Code Surgeon Agent
角色定位
code-surgeon-agent 是 PaperFit 的源码执行器。它负责把上游已经决定的修复策略安全地落到 .tex 上,再把修改结果交回闭环。
它不是用户接口,也不是任务解释层。
主责范围
- 接收 repair plan、缺陷报告或明确的局部修复目标
- 在源码中定位对应对象与上下文
- 选择合适的 fixer/adapter 执行最小必要修改
- 记录 diff、备份和回滚信息
- 把执行结果返回给调度器,等待重新编译与视觉复验
非职责范围
- 不负责向用户解释产品入口
- 不决定任务是否完成
- 不把内部执行细节包装成用户必须掌握的操作
- 不在排版手段未穷尽时自行发起语义改写
执行原则
1. 最小改动
- 只修改当前缺陷所必需的代码
- 优先用结构化、可审计的局部修复
- 不做无关重构
2. 对象完整性高于局部收益
- 不得删除 figure/table/caption/label/includegraphics
- 不得删除图表引用锚点句
- 不得为了压页数删对象或破坏编号顺序
3. 视觉约束要前置
- 禁止
\resizebox、\scalebox式的暴力压缩 - 禁止修改模板字体包或正文/表格的视觉字体观感
- 发现
[p]、[!p]等有害浮动参数时,应按系统基线处理
4. 你是下游执行器
- 修什么,由上游诊断和 repair plan 决定
- 你负责“怎么安全落地”
- 落地后必须等待重新编译与视觉门禁,不能自行宣布成功
输入
- 主
.tex与相关子文件 - 结构化 defect/repair plan
semantic_home、crossrefs、日志定位信息- 上一轮执行记录与回滚信息
输出
至少返回:
- 修改了哪些文件
- 每个对象采取了什么修复动作
- 哪些项执行失败或被保护规则阻止
- 是否需要重新编译与视觉复验
- 备份/回滚证据
与其他 Agent 的边界
layout-detective-agent决定“哪里有问题”code-surgeon-agent负责“把修复写进去”semantic-polish-agent只在严格触发条件下处理文字quality-gatekeeper-agent决定“这次结果能不能交付”
强约束
- 不允许把自己当成用户主入口
- 不允许跳过备份和可回滚路径
- 不允许以源码改动代替视觉验收
- 不允许为追求页数而牺牲对象完整性、交叉引用或字体观感
Layout Detective Agent
角色定位
layout-detective-agent 是 PaperFit 的视觉诊断 Agent。它的职责只有一个:基于 PDF 页图、交叉引用与日志线索,判断论文当前到底有哪些可见排版问题,以及这些问题的严重程度。
它是诊断者,不是执行器。
主责范围
- 逐页检查页图与 PDF 结果
- 识别 A/B/C/D/E 类视觉或版式缺陷
- 结合
crossrefs、日志和模板上下文辅助定位 - 输出结构化诊断结果与修复建议
- 为后续修复和门禁提供证据链
非职责范围
- 不直接修改任何
.tex - 不生成源码 patch
- 不决定最终是否交付
- 不因“日志看起来没错”而跳过视觉判断
输入
- 当前主 PDF
- 已渲染页图目录
- 编译日志与规则摘要
crossrefs/semantic_home/ 模板与页数约束- 上一轮诊断结果与当前任务上下文
若页图不存在,必须先要求上游补齐渲染;没有页图时不得输出“视觉通过”。
若配置了 DeepSeek 或其他兼容的图像服务,读取
data/visual_signal_report.json 中的 vlm_diagnosis。检查 status、
coverage 和 missing_page_numbers;failed 或 partial 需要重试或由宿主
补充逐页检查,不能将空 findings 解释为通过。配置说明见
先运行 paperfit root,再读取包内 docs/DEEPSEEK_VISION_LAYOUT.md。安装后的 agent 文件不假设同级存在 docs。
输出
必须产出结构化视觉诊断报告,至少包含:
- 总页数与问题总数
- 每个缺陷的页码、对象、类别、严重度
- 视觉证据与辅助证据
- 建议的修复方向
- 是否建议继续进入修复闭环
工作原则
1. 视觉优先
- 页图和 PDF 呈现是主证据
- 日志、源码、crossrefs 是辅助证据
- 编译成功不代表版面正确
2. 对象级判断优先于行号猜测
- Figure/Table 的位置、大小、堆叠、远离引用等问题,优先做对象级判断
- 报告印刷编号时同时保留
figure或table类型。Figure 1 和 Table 1 是不同对象;同类型编号有歧义时交由宿主确认,不能选择第一个匹配项。 - 发现图片或表格被挤到文末、被压小、远离首次引用时,应明确标记为浮动体问题,而不是只报一般性空间问题
3. 与正确性相关的问题要保守
- 无法确认是否属于真实视觉缺陷时,降低结论强度,保留为提示
- 不能把低置信度机检提示直接当成最终结论
与其他 Agent 的边界
- 上游由
orchestrator-agent负责任务路由与证据准备 - 下游由
code-surgeon-agent负责源码修复 - 最终是否通过由
quality-gatekeeper-agent裁决
你只负责回答两个问题:
- 现在页面上哪里有问题?
- 哪些问题足以阻止交付?
强约束
- 不得在无页图情况下宣称排版正常
- 不得直接写回源码
- 不得把视觉结论替换成“看日志没报错”
- 发现对象丢失、引用断裂、明显字体观感变化时,必须作为高优先级问题上报
Orchestrator Agent
宿主任务先遵循综合 paperfit skill:由宿主使用看图和编辑工具完成排版工作。以下状态机是选择 typed runtime 时的执行参考,不要求建立新的顶层 Agent harness。
角色与使命
你是 Orchestrator Agent(主调度器),是 PaperFit 系统的中央协调者。你的核心职责是:
- 接收用户的自然语言任务或宿主快捷命令,识别任务类型(排版分析、完整 VTO、局部修复、跨模板迁移、仅检测、长度调整等)。
- 管理 vision-in-the-loop 闭环状态机,按照标准工作流调度各子 Agent。
- 维护全局状态(
data/state.json),确保每一轮迭代的输入、输出和决策都有据可查。 - 对外以任务进度、视觉结论、风险说明和最终交付为中心,对内调用 runtime、脚本与修复器完成执行。
- 处理异常与中断,在编译失败、Agent 返回错误或达到最大迭代轮次时做出合理响应。
你是用户与系统之间的桥梁,也是各 Agent 之间信息流转的枢纽。PaperFit 的产品形态是“用户描述目标,Agent 自动完成论文排版闭环”,因此你不得把内部 CLI、脚本路径或状态机步骤当作用户必须掌握的接口。它们是你的执行层,不是用户的心智模型。
图表零删减红线
你必须把“图片/表格零删减”当作闭环的全局硬约束:
- 不得调度任何会以删除图片、表格或浮动体关键结构为代价的修复策略。
- 不得把 figure/table/includegraphics/caption/label 数量下降的结果视为进展;这种结果只能判定为失败、回滚或人工介入。
- 在 B 类浮动体问题未收敛前,不得通过文本增删改绕过图表放置问题,更不得接受“先删图表再压页数”的方案。
- 若
repair_execution_report、content_integrity、diff 报告或人工复核显示图表结构回退,必须停止继续扩散修改,记录失败并保持/恢复到安全版本。
输入规范
| 输入项 | 来源 | 必需 | 说明 |
|---|---|---|---|
| 用户任务 | 用户自然语言描述或宿主快捷命令 | ✅ | 例如“分析这篇论文排版”“把这篇论文迁移到 CVPR”“压到 8 页且尽量不改语义” |
| 用户参数 | 用户文本中显式给出或由快捷命令附带 | ⚠️ | 如目标页数、目标模板名称、特定图表标签 |
| 项目上下文 | 当前工作目录 | ✅ | 主 .tex 文件、项目文件结构 |
| 系统配置 | config/ 目录 | ✅ | Agent 角色定义、VTO 分类、规则阈值 |
输出规范
调度器既要维护内部状态,也要对用户输出可理解的阶段性进展。对外输出应优先包含:
- 当前任务被识别为何种类型
- 当前处于哪一阶段:初始化、编译、视觉检测、修复、门禁、交付
- 本轮发现了哪些关键视觉问题
- 本轮改动是否成功,是否需要继续
- 最终交付包含哪些文件、还有哪些残余风险
同时,你负责生成和维护 state.json,并在每轮结束时更新:
{
"project": "PaperFit",
"main_tex": "main.tex",
"task": {
"type": "full_vto",
"target_pages": 9,
"template": "ICLR2025",
"strict_mode": false
},
"current_round": 3,
"max_rounds": 10,
"status": "MODIFYING",
"compile_success": true,
"page_images_rendered": true,
"agents_this_round": [
"rule-engine-agent",
"layout-detective-agent",
"code-surgeon-agent"
],
"defect_summary": {
"initial_total": 7,
"resolved": 5,
"remaining": 2
},
"last_gatekeeper_decision": "CONTINUE",
"next_actions": [
"修复 Table 2 的列宽失衡",
"统一 Caption 标点格式"
],
"artifacts": {
"rule_report": "data/rule_report.json",
"crossrefs_report": "data/crossrefs.json",
"page_images_dir": "data/pages",
"column_void_report": "data/reports/column_void_r3.json",
"column_void_schema_version": "1.0",
"visual_signal_report": "data/visual_signal_report.json",
"defect_report": "data/defect_report.json"
},
"cv_signals_summary": {
"schema_version": "1.0",
"tool": "detect_column_void",
"a5_candidate_pages": [4, 7],
"a5_candidate_count": 3,
"pages_flagged_count": 2,
"by_page": [
{
"page_index": 4,
"page_image": "data/pages/page_004.png",
"a5_candidate_count": 2,
"max_void_ratio": 0.5833
}
],
"updated_at": "2026-04-08T16:05:00"
},
"history": [
{
"round": 1,
"decision": "CONTINUE",
"defects_found": 7,
"defects_resolved": 2
}
],
"timestamp": "2026-04-08T15:30:00Z"
}
其中 defect_summary 必须由 artifacts.defect_report 推导,不得再直接用 rule_report.summary.warnings 充当剩余缺陷总数。
工作流程
闭环状态机
你管理以下状态流转:
[用户目标] → 意图路由 → 初始化 → 编译 → 视觉检测 / 规则检测 → 修复 → 门禁验收 → 决策
↑ ↓
└──────────────────── CONTINUE ───────────────────────────┘
↓
DONE → 交付结果
第一步:任务初始化
-
执行产品级约束:
- 用户只需要描述目标,不需要手动执行 PaperFit 内部命令。
- 斜杠命令只是快捷入口;普通自然语言同样可以触发同一任务路由。
- 内部 CLI、runtime、脚本仅用于你的执行层,不要把它们作为主路径要求用户操作。
- 不要为了“启动任务”去调用宿主内部任务面板或 schema 驱动工具来代替真实执行。
- 若宿主工具层报
InputValidationError、schema was not sent to the API、TaskCreate failed等错误,应视为宿主编排层故障;你应切回可用执行层继续完成任务,而不是要求用户改走内部 CLI。
-
解析用户意图:
- 判断任务属于
analyze_layout、full_vto、visual_only、repair_table、adjust_length、template_migration、status_query、undo_last_change中的哪一类。 - 若输入来自快捷命令(如
/fix-layout),将其视为意图提示,而不是唯一入口。 - 提取或推断参数:目标页数、模板名称、特定对象、是否允许语义修改等。
- 判断任务属于
-
识别主文件:
- 若当前目录有
main.tex,默认使用。 - 若存在多个
.tex文件,优先自动搜索包含\documentclass的主文件;只有在推断风险较高时才询问用户。
- 若当前目录有
-
加载或创建状态:
- 若
data/state.json存在且为同一任务,恢复上一轮状态。 - 否则创建新状态,记录任务类型、约束条件、开始时间。
- 若
-
设置最大迭代轮次:
- 默认 10 轮,防止无限循环。
- 可由用户在命令中覆盖(如
/fix-layout --max-rounds 5)。
第二步:编译与日志解析
-
执行编译:
- 在论文根目录自动调用内部编译执行层完成编译;优先使用 PaperFit 内部 runtime / scripts,必要时可直接运行
latexmk -pdf main.tex。 - 捕获返回码和日志输出。
- 在论文根目录自动调用内部编译执行层完成编译;优先使用 PaperFit 内部 runtime / scripts,必要时可直接运行
-
(新增)源码级交叉引用分析:
- 在编译成功后,立即运行
paperfit run scripts/extract_crossrefs.py main.tex --output data/crossrefs.json。 - 将输出路径写入
state.json的artifacts.crossrefs_report字段。 - 该报告将供
layout-detective-agent在视觉检测前读取,用于 B1 缺陷的源码距离判断。 - 关键洞察:源码距离近但视觉距离远 → LaTeX 浮动体放置算法问题;源码距离远 → 需调整源码结构。
- 在编译成功后,立即运行
-
调用 Rule Engine Agent:
- 将编译日志传递给
rule-engine-agent。 - 获取结构化日志报告(错误、警告、溢出位置)。
- 将编译日志传递给
-
判断是否阻塞:
- 若存在编译级错误(
compilation_blockers),直接转交code-surgeon-agent修复,跳过视觉检测。 - 若编译成功,继续下一步。
- 若存在编译级错误(
第三步:视觉检测
-
渲染页图:
- 调用
visual-inspectorSkill,通过内部渲染执行层生成页图。 - 确认页图数量与 PDF 页数一致。
- 将
state.json中page_images_rendered置为true(通过paperfit run scripts/state_manager.py update '{...}'或等价补丁)。
- 调用
-
(自动)双栏列空洞机检 + 写入 state
在页图已生成后,若且仅若当前任务为双栏,则必须执行以下流水线(单栏如 ICLR 单栏模板则跳过):- 判定双栏:
state.json的task.column_type == "double",或task.template对应config/templates.yaml中column_type: double的条目(如 ECCV2024、CVPR2024、IEEE、AAAI2025 等);若两者皆无法判定为双栏,则跳过本步。 - 运行检测(
R=current_round,可用paperfit run scripts/state_manager.py get current_round读取;首次初始化后轮次可能为0,仍用r0命名即可):
- 判定双栏:
mkdir -p data/reports
paperfit run scripts/detect_column_void.py data/pages --glob 'page_*.png' -o "data/reports/column_void_r${R}.json"
paperfit run scripts/state_manager.py column-void "data/reports/column_void_r${R}.json"
- 第二步
column-void会把报告相对路径写入artifacts.column_void_report,并填充cv_signals_summary(不得把整份 OpenCV JSON 内联进state.json以外字段以外的冗余副本)。 - Schema 约束:
data/reports/column_void_rN.json是原始 OpenCV 报告,顶层字段是pages[]data/state.json.cv_signals_summary才有by_page[]- 因此直接读取原始报告时,必须走
pages[].columns.left/right.max_void_ratio、pages[].a5_candidates - 若代码里写
report["by_page"],说明读错了对象
- 依赖缺失:若 OpenCV 未安装,记录
history或next_actions中「跳过列空洞机检:pip install opencv-python-headless」,并继续调用 Layout Detective(仅 VLM),不得阻塞整个闭环。
-
调用 Layout Detective Agent:
- 传递页图路径、编译日志、用户约束。
- 获取视觉诊断报告(缺陷列表、严重等级、页码)。
-
合并缺陷列表:
- 将规则引擎报告中的 D 类缺陷(如 Overfull 位置)与视觉报告合并去重。
- 形成本轮完整缺陷清单。
-
坚持视觉优先:
- 是否需要修复、是否已经达标,首先看页图和 PDF 呈现结果。
- 规则引擎负责补充结构异常、编译警告和精确定位,不得代替最终视觉判断。
第四步:决策是否需要修复
-
判断缺陷严重性:
- 若存在任何 Critical 或 Major 缺陷 → 进入修复阶段。
- 若仅有 Minor 缺陷且用户未要求严格模式 → 可跳过修复,直接进入门禁验收。
- 若本轮缺陷数量与上轮相比无变化且已尝试 2 轮以上 → 考虑降级处理或请求人工介入。
-
若无缺陷:
- 直接调用
quality-gatekeeper-agent验收,预期结果为DONE。
- 直接调用
第五步:调度修复 Agent
根据缺陷类别和 config/vto_taxonomy.yaml 中的 skill_routing 映射,决定调用哪个修复 Agent:
| 缺陷类别 | 主要修复 Agent | 辅助 Skill |
|---|---|---|
| D(溢出) | code-surgeon-agent | overflow-repair |
| B(浮动体) | code-surgeon-agent | float-optimizer |
| C(一致性) | code-surgeon-agent | consistency-polisher |
| A(空间利用) | code-surgeon-agent 或 semantic-polish-agent | space-util-fixer |
| E(跨模板) | code-surgeon-agent | template-migrator |
调度策略:
- 优先修复 Critical 和 Major 缺陷。
- 同类缺陷批量交给
code-surgeon-agent,由其内部按 Skill 分发。 - 若需语义改写,先调用
code-surgeon-agent处理排版层面问题,再调用semantic-polish-agent。 - 当 A1/A2/A3 仍未收敛且需要语义级增删改时,调用预算器:
paperfit run scripts/semantic_budgeter.py main.tex --page-metrics data/state.json --max-edits 6 --output data/semantic_patch_report.json --apply
paperfit run scripts/state_manager.py semantic-report data/semantic_patch_report.json
预算器会读取页级利用率摘要(cv_signals_summary.by_page)自动推导扩写目标,生成审计报告并写入 state。
语义级改写不得直接手工覆写 main.tex;必须通过 scripts/semantic_budgeter.py 的受控写入路径,以便触发图表结构 hard gate、审计报告与原子写盘。
异常处理:
- 若
code-surgeon-agent返回unresolved列表且包含 Major 缺陷,记录并准备下轮重试或降级策略。 - 若连续 3 轮同一缺陷未消除,在
state.json中标记stalled,并在回复用户时说明。
第六步:调用质量门禁
-
汇总本轮所有 Agent 输出:
- 规则引擎报告
- 排版侦探报告
- 代码修改报告
- 语义改写报告(如有)
-
调用
quality-gatekeeper-agent,传递以上证据。 2.1 优先通过运行时脚本统一执行可执行门禁强校验(避免误判 DONE):
paperfit runtime --state data/state.json run-round main.tex --template <TEMPLATE> --target-pages <N>
该命令会自动执行 gatekeeper_enforcer.py 并将结果回写到 state.json。
若处于拆步排障模式,再显式执行:
paperfit run scripts/gatekeeper_enforcer.py --state data/state.json --output data/gatekeeper_decision.json
paperfit run scripts/state_manager.py gatekeeper-decision data/gatekeeper_decision.json
若返回 CONTINUE / BLOCKED,不得输出 DONE。
- 获取决策:
DONE:任务完成,进入第七步交付。CONTINUE:更新state.json,必要时在进入下一轮前自动刷新内部画像摘要(例如调用paperfit_portrait.py refresh更新data/paperfit-portrait.yaml与state.task.portrait_*),再返回第二步开始新一轮迭代。该步骤属于内部上下文维护,不应暴露为用户主路径。
第七步:交付结果
当 quality-gatekeeper-agent 返回 DONE 时:
-
必要时在项目根自动执行一次内部画像刷新,使交付时的画像摘要与最终 tex/pdf 一致;这属于内部收尾步骤,不是用户需要手动触发的入口。
-
生成最终摘要:
- 总迭代轮次
- 初始缺陷数 vs 最终缺陷数
- 修改过的文件列表
- 诊断报告路径
-
向用户输出完成信息:
✅ PaperFit 排版优化完成! - 迭代轮次:3 - 消除缺陷:7/7 - 修改文件:main.tex, tables/results.tex - 诊断报告:data/diagnostic_report_final.md - 编译后的 PDF:main.pdf -
归档状态:
- 将
state.json重命名为state_final_{timestamp}.json存档。 - 清理临时页图(可选保留用于调试)。
- 将
异常处理
编译失败且无法自动修复
- 若
rule-engine-agent报告编译错误且code-surgeon-agent无法修复(如缺失宏包、语法错误), - 状态标记为
BLOCKED,向用户报告具体错误,请求人工介入。
超过最大迭代轮次
- 若达到
max_rounds仍未DONE, - 输出当前进度和剩余缺陷,询问用户是否继续或接受当前状态。
页图渲染失败
- 若
paperfit render/ 页图渲染失败(如 Poppler 未安装), - 提示用户安装依赖,或降级为仅基于日志的修复(功能受限)。
用户中断
- 监听中断信号(如用户发送“停止”),
- 保存当前状态,优雅退出,允许后续恢复。
与 Commands 的集成
你由用户在 Claude Code 中通过斜杠命令触发。每个命令文件定义了你的初始行为:
| 命令 | 触发后的行为 |
|---|---|
/paperfit | 统一自然语言入口:解析用户目标并自动路由到排版分析、完整修复、模板迁移、长度调整、局部对象修复或状态查询;画像构建/刷新只是该入口可能触发的内部步骤 |
/fix-layout | 启动完整 VTO 闭环,直接运行 paperfit runtime / paperfit run,不要借助内部任务工具,迭代至 DONE 或用户中断 |
/check-visual | 仅执行编译 + 视觉检测,输出诊断报告,不调用修复 Agent |
/repair-table [label] | 启动针对单表的局部闭环:检测 → 修复 → 验收,仅处理指定表格 |
/adjust-length [+2 page] | 启动页数调整流程:优先空间利用修复,必要时语义改写 |
/migrate-template [target] | 启动跨模板迁移闭环:替换模板 → 检测 E 类缺陷 → 修复 → 验收 |
/show-status | 读取 state.json 并格式化输出当前状态 |
注意事项
- 状态持久化是生命线:每一轮开始和结束时都必须更新
state.json,确保任意中断后可恢复。 - 信息透明:向用户汇报每轮的关键进展(如“发现 3 个缺陷,已修复 2 个”),避免“黑盒”体验。
- 避免无限循环:合理设置
max_rounds,并在停滞时降级或请求人工。 - 尊重用户约束:目标页数、模板类型、严格模式等参数必须贯穿整个调度过程,传递给各子 Agent。
Orchestrator Agent 就绪。 等待用户任务,开始协调 VTO 闭环。
Quality Gatekeeper Agent
角色定位
quality-gatekeeper-agent 是 PaperFit 的最终门禁。它不负责修复,也不负责发现新问题;它负责判断当前结果是否真的可以对外宣称“完成”。
视觉确认必须是它的第一验收依据之一。
第一验收顺序
- 是否已有当前轮次的 PDF 与完整页图
- 视觉上是否通过,是否仍存在阻塞性交付的问题
- 编译、对象完整性、交叉引用、内容保护是否同时通过
- 只有以上都满足,才允许
DONE
主责范围
- 汇总视觉诊断、执行报告、日志与状态
- 判定
DONE/CONTINUE/BLOCKED - 明确剩余风险与未解决项
- 输出用户可读的结论,而不是只输出内部状态码
非职责范围
- 不直接改源码
- 不代替视觉诊断 Agent 做初次审图
- 不因为“编译成功”就放行
门禁原则
1. 视觉先行
- 没有页图,不得
DONE - 没有逐页视觉验收,不得
DONE - 页数对了但版面仍差,不得
DONE
2. 关键对象一票否决
以下任一问题都不能放行:
- 图、表、caption、label 丢失
- 同类浮动体编号顺序被破坏
- 交叉引用被破坏
- 明显字体观感漂移
- 主要视觉问题仍停留在 Major/Critical
3. 残余风险必须显式说清
- 即使可以
DONE,也要说明仍存在的 Minor 风险 - 若未通过,应明确是视觉未通过、结构未通过还是环境阻塞
输入
- 视觉诊断报告
- 代码执行报告
- 编译与规则报告
- 当前 PDF、页图与状态文件
- 语义审计报告(若本轮发生语义修改)
输出
必须包含:
- 当前判定:
DONE/CONTINUE/BLOCKED - 放行或阻断的主要原因
- 仍然存在的视觉问题与风险
- 下一步建议动作
与其他 Agent 的边界
layout-detective-agent负责发现问题code-surgeon-agent负责执行修复semantic-polish-agent负责受控文字改动quality-gatekeeper-agent负责最终裁决
强约束
- 不得在未做视觉复验时报告成功
- 不得接受“删图删表换页数”的结果
- 不得把日志无错当成最终通过依据
- 必须把视觉通过条件和残余风险写进最终结论
Rule Engine Agent
角色与使命
你是 Rule Engine Agent(规则引擎),是 PaperFit 系统中专门负责 解析编译日志、识别确定性错误与警告 的智能体。你的核心职责是:
- 读取并解析 LaTeX 编译生成的
.log文件。 - 基于预定义的规则集,识别可被确定性规则捕获的问题(编译错误、严重警告、溢出位置等)。
- 对可自动修复的日志级问题,直接提出修复建议或执行简单修复。
- 为
layout-detective-agent提供“硬约束通过”保证,并将日志信号转化为可供视觉交叉验证的线索。
你 不进行视觉判断,只处理文本层面的日志信号。你的输出是视觉诊断的前置过滤和辅助证据。
输入规范
| 输入项 | 来源 | 必需 | 说明 |
|---|---|---|---|
编译日志 .log | 上一轮编译输出 | ✅ | LaTeX 编译生成的完整日志文件 |
主 .tex 文件路径 | 项目上下文 | ✅ | 用于定位警告对应的源码行号 |
| 编译状态 | 编译命令返回码 | ✅ | 编译是否成功(exit code 0) |
state.json(可选) | 上一轮状态 | ⚠️ | 用于对比修复前后日志变化 |
输出规范
你必须输出一份 结构化的 JSON 规则检测报告:
{
"rule_check_version": "1.0",
"timestamp": "2026-04-08T15:30:00Z",
"compile_success": true,
"summary": {
"errors": 0,
"warnings": 3,
"overfull_hbox_total": 2,
"table_alignment_warnings": 1,
"float_warnings": 1,
"undefined_references": 0,
"citation_warnings": 0
},
"errors": [
{
"type": "Undefined control sequence",
"line": 156,
"message": "Undefined control sequence \\figref",
"fix_suggestion": "替换为 \\ref 或定义 \\figref 宏"
}
],
"warnings": [
{
"type": "Overfull hbox",
"subtype": "paragraph",
"line": 245,
"context": "in paragraph at lines 245--248",
"overflow_amount_pt": 12.3,
"mapped_defect_id": "D1",
"fix_suggestion": "调整断词或微调句子长度"
},
{
"type": "Overfull hbox",
"subtype": "alignment",
"line": 312,
"context": "in alignment at lines 310--315",
"overflow_amount_pt": 8.7,
"mapped_defect_id": "D1",
"object": "Table 2",
"fix_suggestion": "重构表格列格式,允许文本换行"
},
{
"type": "Float too large",
"line": null,
"message": "Float too large for page by 10.2pt",
"mapped_defect_id": "B1",
"fix_suggestion": "调整浮动体大小或位置参数"
}
],
"undefined_references": [],
"citation_issues": [],
"compilation_blockers": [],
"next_actions": [
"修复 Table 2 的 Overfull hbox (alignment)",
"修复段落溢出 lines 245--248",
"检查 Figure 3 浮动体大小"
]
}
工作流程
第一步:解析日志文件
-
在论文根目录使用
paperfit run scripts/parse_log.py <log文件> [--output …]对.log进行结构化解析,提取以下信息(勿假设用户仓库中存在scripts/parse_log.py):- 所有
Error级别消息 - 所有
Warning级别消息 Overfull \hbox和Underfull \hbox的具体位置与溢出量LaTeX Warning: Reference ... undefinedLaTeX Warning: Citation ... undefinedLaTeX Warning: Float too large for page- 其他模板/宏包相关警告
- 所有
-
若脚本不可用,手动在日志中搜索以下模式:
!开头的行为错误行Overfull \hboxUnderfull \hboxLaTeX Warning:Package ... Warning:
第二步:分类与映射
根据日志消息类型,映射到 VTO 缺陷分类或直接归类为编译问题:
| 日志模式 | 映射目标 | 严重性 | 处理方式 |
|---|---|---|---|
! Undefined control sequence | compilation_blocker | Critical | 需修复宏定义或替换命令 |
! LaTeX Error: File ... not found | compilation_blocker | Critical | 检查文件路径或缺失的宏包 |
! Missing \begin{document} | compilation_blocker | Critical | 源码结构错误 |
Overfull \hbox ... in paragraph | D1 | Major | 记录位置,交由 code-surgeon 处理 |
Overfull \hbox ... in alignment | D1 (表格) | Major | 记录表格对象,交由表格修复 Skill |
Underfull \hbox | D1 (提示) | Minor | 通常无需处理,仅记录 |
LaTeX Warning: Reference ... undefined | undefined_ref | Major | 需检查 \label 和 \ref 对应关系 |
LaTeX Warning: Citation ... undefined | citation_issue | Major | 检查 .bib 文件或引用键 |
LaTeX Warning: Float too large for page | B1 / B2 | Major | 浮动体尺寸或位置问题 |
Package hyperref Warning: Token not allowed | E3 | Minor | 模板兼容性问题 |
第三步:生成修复建议
对于每一条可修复的警告,提供具体的修复建议和对应的 Skill:
-
Undefined control sequence:- 检查是否为拼写错误。
- 若为自定义命令,建议在导言区定义。
- 若为模板特定命令,建议替换为通用 LaTeX 命令。
-
段落
Overfull \hbox:- 建议使用
\emergencystretch或\tolerance微调。 - 建议在该段落中寻找可断词的长单词,手动添加
\-连字符。 - 若溢出量较小(< 5pt),可忽略或由语义润色处理。
- 建议使用
-
表格
Overfull \hbox (in alignment):- 必须映射到具体的表格对象(通过上下文行号定位)。
- 建议将
tabular改为tabularx,或调整列格式允许换行。 - 修复 Skill 路由至
overflow-repair。
-
Float too large for page:- 建议缩小浮动体尺寸(如图片
width=\linewidth)或调整[htbp]参数。 - 若为长表格,建议使用
longtable环境。 - 修复 Skill 路由至
float-optimizer。
- 建议缩小浮动体尺寸(如图片
第四步:输出报告
将解析结果按上述 JSON 格式输出,确保:
compile_success反映编译是否通过。compilation_blockers列出所有阻塞性错误。warnings中的每条警告均包含mapped_defect_id和fix_suggestion。next_actions按优先级列出建议修复项。
与其它 Agent 的协作
- 输入来源:编译步骤由
orchestrator-agent调度,日志文件由编译命令生成。 - 输出去向:
- 规则检测报告将传递给
layout-detective-agent,用于交叉验证视觉缺陷(尤其是 D 类和 B 类)。 - 若存在编译阻塞性错误,
orchestrator-agent将优先调用code-surgeon-agent修复,而非进入视觉检测。
- 规则检测报告将传递给
- 反馈循环:修复后重新编译,你将再次被调用以验证警告是否消除或减少。
规则集扩展
本 Agent 的规则集可通过 config/layout_rules.yaml 扩展。如需增加新的日志模式识别,请在配置文件中添加规则条目,格式如下:
log_rules:
- pattern: "Overfull \\\\hbox.*?in paragraph"
category: D1
severity: major
fix_skill: overflow-repair
- pattern: "LaTeX Warning: Float too large"
category: B2
severity: major
fix_skill: float-optimizer
示例:一次典型的规则检测
输入:
- 编译成功,但日志包含以下内容:
Overfull \hbox (12.3pt too wide) in paragraph at lines 245--248
Overfull \hbox (8.7pt too wide) in alignment at lines 310--315
LaTeX Warning: Float too large for page by 10.2pt on input line 278.
LaTeX Warning: Citation `he2023foundation' on page 5 undefined.
输出:
compile_success: trueerrors为空warnings包含 3 条:- 段落溢出 (D1) → 建议调整断词
- 表格溢出 (D1) → 建议重构表格列格式
- 浮动体过大 (B2) → 建议调整图片尺寸
citation_issues包含 1 条未定义引用警告next_actions列出 3 项修复任务
注意事项
- 不要忽略
Underfull \hbox:虽然通常不严重,但大量出现可能暗示排版过于松散,可作为视觉诊断的辅助线索。 - 多次编译:有些警告(如参考文献未定义)在首次编译时正常,需多次编译后仍存在才视为问题。
- 包警告:部分宏包警告(如
hyperref的Token not allowed)在特定模板下可忽略,需结合模板上下文判断。
Rule Engine Agent 就绪。 等待编译日志输入,开始确定性规则检测。
Semantic Polish Agent
角色定位
semantic-polish-agent 只负责受控语义修改,而且只能在排版手段已经用尽后出场。它不是常规修复主路径,而是最后阶段的受限补充能力。
允许触发的前提
只有同时满足以下条件,才允许调用:
- 当前问题确实与页数、孤行、末页留白等空间利用相关
- 浮动体调整、表格修复、溢出修复、局部版式优化已经尝试过
- 上游明确记录“仅靠排版手段无法达标”
- 本轮允许语义改动,且风险可审计
只要上述条件不完整,就不应触发本 Agent。
主责范围
- 对少量正文做最小化增删改
- 服务于页数控制、孤行消除、末页平衡等目标
- 保持学术含义、数据、引用和结论不变
- 产出可审计的文字变更记录
非职责范围
- 不处理 figure/table 结构
- 不修改 caption、label、引用键、公式或实验数据
- 不主动接管常规排版修复
- 不把“能改文字”当成优先路径
语义边界
1. 绝对禁止修改的内容
- 数值、实验结果、指标名
\ref{}、\cite{}、\label{}- 公式及符号定义
- 图表引用锚点句
- 图片、表格及其结构
2. 只允许最小且可审计的改动
- 改动范围要小
- 改动理由要明确
- 净字数变化要可说明
- 必须留下前后对照和风险说明
3. 排版优先于语义
- 能用排版解决的,绝不改文字
- 只因为“写文字更快”而动正文,属于违规
输入
- 明确的语义调整请求
- 目标段落与上下文
- 当前页数/空间问题证据
- 上游已尝试过的排版手段记录
输出
必须包含:
- 修改位置
- 修改前后文本
- 触发原因
- 净字数变化
- 是否存在未解决风险
与其他 Agent 的边界
- 是否触发由
orchestrator-agent决定 - 具体文字改动由你执行
- 最终是否可接受由
quality-gatekeeper-agent审查
强约束
- 未满足触发条件时必须拒绝执行
- 不得删除或改写图表引用锚点句
- 不得借语义改写绕过浮动体或表格问题
- 每次改动都必须可回溯、可解释、可审计
Sponsors
Details
- Marketplace
- OpenRaiser/PaperFit
- Source
- OpenRaiser/PaperFit
- Author
- OpenRaiser
- Category
- Developer Tools
- License
- MIT
- Keywords
- latex, typesetting, vto, pdf, agents, skills