fix-layout

/fix-layout — 启动完整 VTO 排版优化

作用: 对当前 LaTeX 项目执行完整的视觉排版优化（VTO）闭环

防呆约束:

• 用户只需要表达目标，不需要手动执行内部命令
• 直接执行 paperfit runtime ... / paperfit run ... / paperfit render ...
• 不要为了“启动闭环”先去调用任何内部任务管理工具
• 不要调用 TaskCreate、TodoWrite、Plan、Agent 之类的任务编排工具来代替实际执行
• 不要在 /fix-layout 过程中再自动触发其他斜杠命令
• 如果任务工具 schema 缺失或出现 InputValidationError，应立即回退到直接 shell 命令，不要重试任务工具

用户入口说明

• /fix-layout 是专家快捷入口，不是要求用户理解内部 CLI 的入口。
• 与之对应的普通自然语言，例如“修复这篇论文的排版问题”“尽量不改语义地压到 9 页”，也应能触发同类任务。
• CLI、runtime、scripts 是你的执行层，不是用户的产品接口。

工具调用约定

可执行脚本在 paperfit-cli 包内；在论文项目根目录执行，勿假设仓库里自带可运行的 scripts/：页图用 paperfit render <pdf> --output data/pages，其它用 paperfit run scripts/<文件> [参数…]；无全局命令时用 npx paperfit-cli … 或 python3 "$(paperfit root)/scripts/…"。

用法

/fix-layout

也可以由普通自然语言触发，例如：

用 PaperFit 修复当前论文的排版问题
把这篇论文排到投稿状态，优先修视觉问题
把正文压到 9 页，尽量不要改正文含义

直接执行入口

首选直接运行：

paperfit runtime --state data/state.json run-round main.tex --template <TEMPLATE> --target-pages <N>

若还未初始化，再先执行：

paperfit runtime --state data/state.json init-task main.tex --template <TEMPLATE> --target-pages <N>

column_void Schema 提示

• data/reports/column_void_rN.json 是 detect_column_void.py 的原始报告
• 原始报告顶层字段使用 pages[]
• by_page[] 不在原始报告里
• by_page[] 只存在于 data/state.json -> cv_signals_summary.by_page

如果要直接分析原始报告，应读取：

{
  "page_count": 60,
  "pages": [
    {
      "page_image": "data/pages/xxx.png",
      "columns": {
        "left": {"max_void_ratio": 0.0},
        "right": {"max_void_ratio": 0.0}
      },
      "a5_candidates": []
    }
  ]
}

不要写：

data["by_page"]

除非你读的是 data/state.json 的 cv_signals_summary。

执行流程

1. 画像（推荐）：若用户尚未建立 data/paperfit-portrait.yaml，可在内部先执行画像构建或刷新；不要把这一步强制变成用户必须再次输入 /paperfit 的动作。若已存在画像，每轮门禁结束或本轮 tex/pdf 更新后执行 paperfit run scripts/paperfit_portrait.py refresh 刷新扫描项与 state.task.portrait_*。
2. 识别主 .tex 文件（data/benchmarks/case/*.tex）
3. 初始化或加载 state.json（优先使用 paperfit runtime --state data/state.json init-task main.tex ...；双栏论文补 --column-type double；若已由 /paperfit 写入栏型，以 state.json / 画像为准）
4. 每轮优先执行 paperfit runtime --state data/state.json run-round main.tex --template <TEMPLATE> --target-pages <N>，统一完成轮次推进、日志解析、crossrefs 提取、页图检查、缺陷摘要推导与 gatekeeper 回写；若需拆步排障，再退回 start-round / mark-compile / mark-render / gatekeeper
5. 若是双栏任务且本轮已生成页图，再执行 detect_column_void + paperfit runtime --state data/state.json ingest-column-void data/reports/column_void_rN.json 写入机检摘要
6. 规则引擎检测编译日志错误
7. 排版侦探基于 VTO 分类体系检测视觉缺陷（合并 machine_signals 与 VLM）
8. 代码外科医生执行修复
9. 重新编译 → 质量门禁验收（诊断报告用 config/diagnostic_report.template.md）
10. 迭代至 DONE 或达到最大轮次