latex-layout-issue-bundler

LaTeX Layout Issue Bundler 用于创建可复现的版面问题 bundle，而不是依赖一次性的手动截图。

用途

当出现以下情况时使用该技能：

用户有一个渲染后的 PDF 页面存在版面问题
通常需要向 agent 发送截图
问题与页面或对象相关：浮动体留白、不自然的分页、算法／表格／图片位置、overfull／underfull 行、短行或局部间距
agent 需要足够的产物上下文来调试版面，而无需查看完整对话

该技能为其他技能生成证据，本身不直接修复论文。

输出结构

bundle 位于论文仓库下：

.agent/layout-issues/<issue-id>/
├── prompt.md
├── manifest.json
├── page-<NN>.png                  # 当有 PDF 渲染器可用时
├── crop.png                       # 当有渲染和裁剪工具可用时
├── page-<NN>.txt                  # 当有 pdftotext 可用时
├── source-snippet.tex             # 当提供源码文件和行范围时
└── compile-log-excerpt.txt        # 当提供或检测到日志路径时

这些默认是 agent 私有产物。除非用户明确希望发布经过清理的调试产物，否则不要将它们提交到作者可见、匿名投稿、arXiv、camera-ready 或出版商可见的论文源码中。

快速命令

解析已安装的技能目录，然后运行：

python3 <latex-layout-issue-bundler-skill-dir>/scripts/create_layout_issue_bundle.py \
  --paper-dir "$PAPER_DIR" \
  --pdf "$PAPER_DIR/main.pdf" \
  --page 7 \
  --title "Algorithm 2 bottom gap" \
  --problem "Large blank space after Algorithm 2 before the following paragraph." \
  --object "Algorithm 2 and lines 247-255" \
  --source "$PAPER_DIR/sections/method.tex:247-255" \
  --crop bottom

脚本会打印 bundle 路径。

输入参数

--paper-dir：论文仓库根目录或论文工作树根目录。
--pdf：渲染后的 PDF 路径。
--page：从 1 开始的 PDF 页码。
--title：简短问题标题，当省略 --issue-id 时用于生成 issue id。
--problem：视觉上看起来不对的地方。
--object：受影响的对象或段落，例如 Algorithm 2、Table 1 或 lines 247-255。
--source：可选的 path:start-end 源码指针。
--crop：可选的裁剪预设或矩形：
- top、bottom、left、right、center
- x,y,w,h（像素）
--log：可选的编译日志路径。若省略，脚本会尝试 <pdf-stem>.log。

工作流程

从 PDF 查看器、Overleaf 预览、Skim 或 SyncTeX 中确定页面和局部对象。
使用页面、问题、对象、可选源码行范围和可选裁剪运行 bundler。
检查 .agent/layout-issues/<issue-id>/prompt.md。
将该 bundle 路径交给 submit-paper、paper-writing-assistant 或新的 reviewer／sidecar 会话。
修复 agent 应做一处小的局部修改，通过配置的后端编译，并再次比较同一页面。

工具行为

脚本仅在工具可用时使用它们：

pdftoppm 将 PDF 页面渲染为 PNG。
pdftotext 提取页面文本。
ImageMagick 的 magick 或 convert 裁剪渲染后的 PNG。

缺失的工具会记录在 manifest.json 中；如果 bundle 仍有有用的上下文，则不视为致命错误。

不要在论文仓库中记录本地绝对工具路径或机器特定的 TeX 安装信息。工具可用性是运行时状态。

给消费者的修复策略

消费 bundle 时，遵循 submit-paper 的版面调试策略：

先定位页面和对象
优先使用文字和局部浮动体／分页修复，而非全局版面设置
一次只改一个对象
避免大范围使用 \sloppy、\emergencystretch、全局段落或全局浮动体间距更改，除非整篇论文有已记录的样式问题
每次修改后在视觉上验证同一页面